[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