[Lazarus] Lazarus IDE help and Application help formats

[Mattias Gärtner]

Zitat von Graeme Geldenhuys <graemeg at opensoft.homeip.net>:

> 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