[Lazarus] Lazarus IDE help and Application help formats

Mattias Gärtner nc-gaertnma at netcologne.de
Mon Aug 17 12:22:00 CEST 2009


Zitat von Graeme Geldenhuys <graemeg at opensoft.homeip.net>:

> Chris Kirkpatrick wrote:
>>>
>> I have used the 'topic' tag in FPDoc to produce some general 'How-To'
>> sections (see the documentation for StdCtrls, DBCtrls for examples)
>
> This is exactly what I was thinking of doing as well.
>
> Thinking about this a bit more and what could apply to my own  
> applications context sensitive help. He is the requirements I have  
> for application (not source code / class) documentation.
>
>  * Must be in a text format so it can be tracked by
>    SCM systems.
>  * Must be able to apply for easy amendments via
>    patches from the community.
>  * Must be flexible enough to various output formats
>    can be generated.
>  * Must be usable for online and offline viewing.
>  * Must not have a huge tool-chain requirement to view,
>    edit and generate documentation.
>  * Possible archive format (single file) deployment.

Almost any text format fits these requirements. You should be more specific.
For example the documentation needs
* a toc
* possibility to combine docs to modules
* links to docs in the same module
* links to docs in other modules
* external links
* keywords to refer from outside
* viewers for all platforms:
** a good search engine
** allow to load/view several modules at the same time
** remote control in both directions


> So this immediately drops DocBook and LaTeX formats (sorry Michael)  
> because they require large tool-chains to be installed before you  
> can generate documentation output.
>
> fpdoc format might not be ideal, because it is design specifically  
> to document source code - classes and units etc.. Not application  
> screens.
>
> Wiki's are only online. You cannot edit documentation offline and  
> submit a patch. Wiki pages are stored in a database (90% of the time).
>
> Possible solution
> -----------------
> AsciiDoc or Markdown syntax. I first time I saw this used, was in  
> the Git project. All documentation is written in AsciiDoc syntax.
>
> AsciiDoc or Markdown on it's own is very much like a standard  
> readme.txt document. Everything is in ascii art format with very  
> little formatting tags. Just reading the raw AsciiDoc or Markdown  
> text is possible, without even generating a specific output format.
>
> Because it is text, it works very well in SCM systems.
>
> There are tools (similar to DocBook and LaTeX) to generate various  
> other output formats (man pages, pdf's, HTML, LaTeX etc.) from the  
> raw syntax, but again it has a relatively large tool-chain  
> requirement and doesn't come standard with most OSes. Good news is  
> that AsciiDoc or Markdown syntax is very easy to parse, so it  
> shouldn't take a lot of work to write our own document generator for  
> markdown syntax. Similar as what fpdoc does for it's format. We can  
> even include a AsciiDoc syntax highlighter in Lazarus, so you can  
> use Lazarus IDE to write the documentation. No extra "document  
> editors" required.
>
> Here is an example of AsciiDoc used to document the git-annotate  
> command. This is the actual git-annotate (raw syntax) documentation.
>
> As you can see, the AsciiDoc syntax hardly has any formatting tags,  
> so you can read it as-is without problems.
>
> It would even be possible to write a "on-the-fly" generator, so when  
> the user clicks the help button, the .txt help file is loaded and  
> generates say an HTML format in memory and viewed with an HTML  
> component in a window. No external web browsers or viewers required.
>
> ------------------[ git-annotate.txt ]------------------------
> git-annotate(1)
> ===============
>
> NAME
> ----
> git-annotate - Annotate file lines with commit information
>
> SYNOPSIS
> --------
> 'git annotate' [options] file [revision]
>
> DESCRIPTION
> -----------
> Annotates each line in the given file with information from the commit
> which introduced the line. Optionally annotates from a given revision.
>
> The only difference between this command and linkgit:git-blame[1] is that
> they use slightly different output formats, and this command exists only
> for backward compatibility to support existing scripts, and provide a more
> familiar command name for people coming from other SCM systems.
>
> OPTIONS
> -------
> include::blame-options.txt[]
>
> SEE ALSO
> --------
> linkgit:git-blame[1]
>
> AUTHOR
> ------
> Written by Ryan Anderson <ryan at michonline.com>.
>
> GIT
> ---
> Part of the linkgit:git[1] suite
> --------------------[ end ]------------------------

This looks like an info page.


> This format should be just as easily applicable for any Lazarus  
> based application that you write. So the same help format and  
> "viewer" can be used in LCL based applications.  We could even  
> package the .txt help into a ZIP archive using TZipper or TZipFile  
> so a single archive can be distributed with your application. And  
> the help can be read directly from the help archive.
>
> Your thoughts in this?

Documentation need a good viewer.

Mattias






More information about the Lazarus mailing list