[Lazarus] Adding Notes in FPDoc

[Michael Van Canneyt]

On Mon, 13 Feb 2012, Hans-Peter Diettrich wrote:

> Graeme Geldenhuys schrieb:
>
> A better help system should allow to show or hide details based on more 
> criteria. In Delphi and MS (.NET...) help it would be helpful to show the 
> texts associated with a specific language. In FPC/Lazarus help the platform 
> or widgetset details could be shown or hidden. In all cases the use case 
> could be honored, like:
> - user needing instructions for calling a method in code
> - user having (known?) problems with a method
> - component writer wants to override a method
> - expert wants to fix or extend a method
>
> All that can not be achieved with only a level of verbosity.

But it can easily be achieved by adding attributes to each note, and reacting 
on these attributes. This is already implemented in revision 20335.

Things like

<note platform="win32"></note>
<note type="warning"></note>
<note author="websiteuser=laurence at arabia"></note>
<note author="DoDi"></note>

Whatever. The attributes do not get in the way of the regular working of fpdoc.

You could also do something like
<note anchorpos="123"></note>
and have the note 'anchored' at position 123 in the text. 
(or a linenumber, it is just an example, or maybe an <link anchor=123> could be inserted in the text).
This could serve as a hint for the output engine.

Since I do not know what attributes people would like to see supported, 
the mechanism currently always emits all notes.

People need to agree on:

1) Which attributes to support by default.
2) What values the attributes can take.
3) what to do if an attribute is absent.

As soon as an agreement is reached, I can implement the necessary logic to 
emit notes on a selective basis.

The documentation editors need then to be adapted to allow easy setting of the agreed 
attributes.

Michael.