Re: [Lazarus] authoring user manuals
On 08/03/2015 04:08 PM, Gour wrote: 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. 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 -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
On 2015-08-03 15:08, 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 - -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
On 2015-08-03 18:27, 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 - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
On 2015-08-03 21:09, 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 - -- fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal http://fpgui.sourceforge.net/ -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
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. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
Mark Morgan Lloyd markmll.laza...@telemetry.co.uk writes: 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.. 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. 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 -- There is no possibility of one's becoming a yogī, O Arjuna, if one eats too much or eats too little, sleeps too much or does not sleep enough. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
Gordon Cooper hughgord...@gmail.com writes: 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 -- Never was there a time when I did not exist, nor you, nor all these kings; nor in the future shall any of us cease to be. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
Marco van de Voort mar...@stack.nl writes: 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 -- The working senses are superior to dull matter; mind is higher than the senses; intelligence is still higher than the mind; and he [the soul] is even higher than the intelligence. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
Graeme Geldenhuys mailingli...@geldenhuys.co.uk writes: See this message from July, and the attached example application. Ahh…I apologize for not spotting this recent thread. :-( 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. 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. 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/INF means I have to forger about Emacs which I use a lot… Sincerely, Gour -- A person who has given up all desires for sense gratification, who lives free from desires, who has given up all sense of proprietorship and is devoid of false ego — he alone can attain real peace. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
On Mon, Aug 03, 2015 at 04:08:46PM +0200, 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. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
[Lazarus] authoring user manuals
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 -- A self-realized man has no purpose to fulfill in the discharge of his prescribed duties, nor has he any reason not to perform such work. Nor has he any need to depend on any other living being. -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
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. -- Mark Morgan Lloyd markMLl .AT. telemetry.co .DOT. uk [Opinions above are the author's, not those of his employers or colleagues] -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
Re: [Lazarus] authoring user manuals
2015-08-03 20:47 GMT+02:00 Gour g...@atmarama.net: Marco van de Voort mar...@stack.nl writes: 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. If you want to use fpdoc without writing XML, you can try Txt2FPDoc ( http://yann.merignac.free.fr/txt2fpdoc.html). -- ___ Lazarus mailing list Lazarus@lists.lazarus.freepascal.org http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
