Zitat von Graeme Geldenhuys <[email protected]>:
Mattias Gärtner wrote:
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
These are all supported by AsciiDoc.
* keywords to refer from outside
This can be created by us - using a documentation generator or
something. Similar to what fpdoc does for CHM help.
* viewers for all platforms:
This is easy. Default help can be HTML format. Lazarus already
includes an HTMl viewer component as used by 'lhelp'. I'm sure there
are many more available.
** a good search engine
** allow to load/view several modules at the same time
** remote control in both directions
I don't understand these? What do they have to do with documentation?
It's not sufficient to only have help files. The important piece is to
find and present the help. Just take a look at the mails. We have
thousands of help pages and still people say we have no usable help.
If you publish your docs online, a search engine will be able to index them.
And if you view them offline?
And: An index is not enough.
When someone needs help at a certain place, then a F1 should open the
help for that - context sensitive help. For example when a user is in
the compiler options dialog, a F1 should tell the help viewer to open
the help for the 'compiler options dialog'.
That's what I mean with support for "keywords" and "remote control".
The online help currently shows the help for the LCL and the FCL.
This looks like an info page.
Well, that is the style Git writes there documentation in. So maybe
that was a bad example. See the AsciiDoc website for many more
examples. We don't have to strictly adhere to AsciiDoc syntax - we
could pick the best bits from AsciiDoc, MarkDown etc.. Though it
might be beneficial to stick to syntax that is already well thought
out, documented and tested.
Maybe I should take one of the Lazarus IDE wiki help pages and
convert it to AsciiDoc so we can see a "real" appropriate example
and how the default asciidoc generated XHTML 1.1 output looks like.
Documentation need a good viewer.
Any HTML viewer component should do.
No.
Where is the search field?
Who produces the html from the doc files?
One extra nice thing is shown below. Icons for notes, tips etc..
http://www.methods.co.nz/asciidoc/userguide.html#X28
Such images can be embedded inside the generated HTML via data URI
tags. No need to reference such images or CSS in external files.
Again, makes for easier deployment. By the way "data URI" normally
uses base64 encoding, which FCL has support for. Again, no external
dependencies needed.
Mattias
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
