[Lazarus] Lazarus IDE help and Application help formats

[Graeme Geldenhuys]

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? If 
you publish your docs online, a search engine will be able to index them.


> 
> 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.

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.


Regards,
   - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://opensoft.homeip.net/fpgui/