Hello,

by looking at
http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application page it seems there are several options to provide help (aka user manual) for one?s app - CHM, HTML & INF.

Now I wonder which one is recommended and if there are some helpers assisting manual authors to use some higher-level markup like markdown/AsciiDoc/rst?

Sincerely,
Gour

Gour wrote

Now I wonder which one is recommended and if there are some helpers assisting manual authors

See this message from July, and the attached example application.

http://free-pascal-lazarus.989080.n3.nabble.com/Lazarus-Help-for-your-applications-tp4043078p4043079.html

I use the INF format because it is very simple to author and extremely compact (10+ times smaller than CHM of the same content). The markup language is much shorter that HTML, less complicated than LaTeX, and not very verbose. The IPF tags are mnemonic, making it easy to associate them with their functions.

In my eyes DocView is also a superior help viewer compared to any CHM or HLP help viewer I have seen, with built in support for Contents, Index (auto-generated in none exists), full-text search with advanced filtering, search highlighting, in-line annotation support, custom font configuration and is lightning fast etc.

Regards,
- Graeme -

Graeme Geldenhuys wrote

See this message from July, and the attached example application.

Ahh?I apologize for not spotting this recent thread. :-(

Hmm?sound good and I have to check it out - I just wonder if it?s rich enough and/or how its markup compares with e.g. rst/Asciidoc.

I like what I?ve seen in DocView?now have to find out if using FPC/INF means I have to forger about Emacs which I use a lot?

Sincerely,
Gour

Gour wrote

by looking at http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application page it seems there are several options to provide help (aka user manual) for one???s app - CHM, HTML & INF.

For unit documentation a tool called fpdoc is used that is basically generate with XML + source scanning as input. there are various outputs.

The preferences vary. The IPF proponents are very vocal as I'm sure you noticed. I prefer CHM, if only because you can open it on e.g. Windows without telling people how to install a viewer.

And frankly I don't care about size, at least not till it gets too weird.

Now I wonder which one is recommended and if there are some helpers assisting manual authors to use some higher-level markup like markdown/AsciiDoc/rst?

No, it was more meant to be edited from the GUI using editors. The original gui tool was part of fpgui's precursor fpgtk.

Marco van de Voort wrote

For unit documentation a tool called fpdoc is used that is basically generate with XML + source scanning as input. there are various outputs.

Yeah, that?s for code, that I did see.

The preferences vary. The IPF proponents are very vocal as I'm sure you noticed. I prefer CHM, if only because you can open it on e.g. Windows without telling people how to install a viewer.

I like that it?s nicely supported and not vendor lock-in.

So far, I do not see about conversion capabilities for IPF, iow. whether there are tools convert to/from it.

Sincerely,
Gour

Gour wrote

> In my eyes DocView is also a superior help viewer compared to any CHM or> HLP help viewer I have seen, with built in support for Contents, Index> (auto-generated in none exists), full-text search with advanced> filtering, search highlighting, in-line annotation support, custom font> configuration and is lightning fast etc. I like what I?ve seen in DocView?now have to find out if using FPC/INFmeans I have to forger about Emacs which I use a lot?

Focussing on help files, in the past I've experimentally generated text for these as an appendix in a PDF file using Lyx etc., then post-processed it into a .chm. This has the obvious advantage that printed and online documentation remains in step, however I'm not sure how practical this would be if a substantial amount of internationalisation were required.

Speaking as somebody who is neither a core developer nor a list manager, this is the Lazarus mailing list and the principal format used by Lazarus is .chm. It's all very well for an advocate of an alternative documentation format and an alternative UI toolkit to be enthusiastic about them, but I'm not sure that they're something which should be promoted too vocally to somebody who hasn't been active in the field for an extended period.

2015-08-03 20:47 GMT+02:00 Gour :

If you want to use fpdoc without writing XML, you can try Txt2FPDoc ( http://yann.merignac.free.fr/txt2fpdoc.html).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20150803/47d50c58/attachment.html>

Gour wrote

FPC/INF means I have to forger about Emacs which I use a lot?

You can write software and help using Emacs, no problem. There is no requirement to drop your editor of choice. Some prefer using Lazarus IDE for everything, but equally I know of many that use Geany or Eclipse (or some other text editor) to write Object Pascal software (compiled using FPC).

Regards,
- Graeme -

Mark Morgan Lloyd wrote

Lazarus mailing list and the principal format used by Lazarus is .chm.

No, the "official" help format for lazarus is.... there is none! Some parts are HTML (and then repackaged as CHM), the wiki, the mailing list etc.

There is also NO rule that says if you use LCL for your application that you must use CHM for your application help. That is absolute nonsense. Many use raw HTML in a directory as application help. Equally so, I showed that they could also use DocView+INF for LCL based application help.

Regards,
- Graeme -

Just a comment - with the requirement to produce a User Manual in HTML and PDF for a new Linux OS, we settled on Lyx as the primary editor.

Gordon
Tauranga N.Z.

Mark Morgan Lloyd wrote

Focussing on help files, in the past I've experimentally generated text for these as an appendix in a PDF file using Lyx etc., then post-processed it into a .chm.

Heh, I was using Lyx for authoring real books in the past..

Hmm, I?m very new here, but in my original message I posted a link from *Lazarus* wiki
(http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application) which mentions CHM, HTML and INF as possible help formats and that was the reason to ask ?which one?? ;)

Sincerely,
Gour

Gordon Cooper wrote

Just a comment - with the requirement to produce a User Manual in HTML and PDF for a new Linux OS, we settled on Lyx as the primary editor.

Thanks. I was using LyX and I like it?although in a recent time I?m considering some markup (rst/AsciiDoc) so I can use ?single? markup for web content writing (static-site generator), study-notes etc.

Sincerely,
Gour

As there is a wiki containing many pages that are interesting for users you might add "wiki format" here.

Most of the source of the "F1-help" is done using a propriety "FP" help file format and Editor, but AFAIK you can use other file formats as well. For "F1-help" (not aka user manual) AFAIK, there is no way to do that using Wiki format.

-Michael