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.
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 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?
Regards,
- Graeme -
--
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://opensoft.homeip.net/fpgui/
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
