[Lazarus] Adding Notes in FPDoc

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

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

IMO we have to agree in the first place about the *intended use* for the 
notes.

The first implementation looks like an "Errata" sheet, referring to the 
entire document.

The mentioned verbosity level suggests expandable parts in the docs, 
e.g. represented by "[more]" or "[+]" insertions.

A "footnote" like usage would come close to my needs, but should be 
accompanied by points-of-reference in the text, like "[1]". These may be 
implemented as clickable links, which lead to the note's text, or 
display the note in kind of a an overlaid hint window - depending on the 
viewer. Or the entire referenced word or phrase may be represented as a 
link, without additional insertions into the text - again heavily 
depending on viewer capabilites.

We should keep in mind how the notes can be represented in the final 
docs - linear formats have more restrictions than e.g. HTML pages. This 
is where I'd draw a line between Documentation (linear) and Help (random 
pages).


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

One solution could show the available attributes in a headline or menu 
bar, as currently implemented for "[index] ... (#lcl)", with the 
selected items being expanded when selected. Two such lines can be 
inserted, for common (agreed) attributes (like platform, widgetset), or 
document-specific attributes. The expansion can be implemented as a 
different page for every selected attribute, or by scripting features of 
the server or viewer. Scripting would allow to activate (expand) 
multiple attributes at the same time, without a need to store every 
single version as a new document.

For the editors I'd suggest multiple panes, for the original (smallest) 
content, and another pane for notes. A command "Insert Note" would place 
a link mark into the text, and connect it to whatever is written in the 
Notes pane. This also may be a solution for the HTML display of the 
final docs, where the Notes pane can reside in another window. This 
secondary window then can contain means to select the available and 
currently activated attribute(s). Different solutions may be required 
for small screens (of portables).

DoDi