Zitat von Graeme Geldenhuys <grae...@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 <r...@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
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus