[Lazarus] Adding Notes in FPDoc

[Michael Van Canneyt]

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

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

I'm sure you'll have wonderful discussions with the Lazarus team.

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

If by "document" you mean package or module, I think you understood it wrong then.

It is implemented on a topic level. i.e you can associate notes with each <element>.

This means that for HTML, notes are emitted on the level of a single HTML page.

For linear, it is at the end of the current identifier section.
[[sub]sub]section, in LaTeX.

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

[snip]

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

By the looks of it, you are going to have a field day with this.

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

Everybody is eagerly awaiting your patches for the documentation editors...

Michael.