[Lazarus] Building help files: the nitty-gritty

[Graeme Geldenhuys]

Hi,

On 10 July 2012 23:45, Mattias Gaertner <nc-gaertnma at netcologne.de> wrote:
>>
>> I personally thing that is tackling the problem from the wrong end. I
>> definitely don't want other peoples annotations in my help documents.
>> Such functionality needs to be added at runtime by the docs viewer.
>> Just my 2c.
>
> I agree with the locality. The IDE is not a science project or critical
> apparatus. Annotations of the LCL docs and probably all packages in the
> Lazarus sources should be local.

Yes, annotations are a personal thing. I might annotate a help topic I
struggle with, where somebody else could well have thought it pretty
obvious, and needed no further explanation.


> I don't understand what you mean with "that is tackling the problem
> from the wrong end".

I meant, in is not really the fpdoc XML files that need annotation
support, it is the Help Viewers than need the support. The Help
Viewers must be able to add annotations at runtime, store them
locally, and separate from the original help files.

The other problems I can see that will happen with the Lazarus IDE's
FPDoc Editor supporting annotations, is that if those annotations are
stored in the same fpdoc XML files as the LCL, then somebody might
submit those changes with actual LCL documentation fixes. Then the
burden will fall on the Lazarus core team to make sure they don't
accidentally commit such a contribution (somebody's personal
annotations mixed with legit documentation bug fixes) to the
repository.


> So far my other applications never needed an extensive offline help

Lucky you! :)


-- 
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://fpgui.sourceforge.net