[Lazarus] Duplicate items in xml doc files

[Werner Pamler]

Disregarding LazFPDoc for the moment:

I do like the FPDoc Editor because once I understood its principle I 
could simply edit existing and create new help items. And moving the 
mouse over the corresponding keywords in the text gave an immediate 
feedback. But now I am quite confused because it does not necessarily 
consider all nodes in a file. As we see here, there are two 
TCanvas.PolyBezier nodes in the same file. The FPDocEditor uses only the 
first node and ignores the second one; and the mouse-over hint is 
constructed also from the first node only -- the (larger) work somebody 
else has put into the second one is forgotten. I wonder how it was 
possible that a second node could be added at all. Carelessness of the 
user manually editing the file?

I suppose that it is possible to merge the two nodes and remove the 
duplicates manually. Correct?

Another issue with the FPDocEditor is that it frequently writes back to 
the xml file although nothing has been changed. Unfortunately it formats 
the xml text in its own way which causes a lot of text changes and 
pollutes the svn history. The attached TortoiseMerge screenshot shows 
the diffs induced by opening lclintf.inc in Lazarus with FPDocEditor and 
clicking on some LCLIntf-related keywords in the source files of 
winapi.inc and winapih.inc: a huge number of lines is changed due to 
replacement of empty expanded xml tags such as <short></short> by their 
short forms <short/> (see the left gutter for an overview of all 
changes). This is an extreme case, normally I have seen only changes at 
a few places. I cannot tell what exactly causes the different behavior.


>> Can both tools, FPDoc Editor and LazDocEditor, be used to edit help 
>> information? Or is it recommended to do this manually (which is 
>> extremely error-prone)?
>
> For FPC, I only edit manually. I don't see why this would be error 
> prone ?

Typos! Once I tried to build the html help files myself and it failed 
because somebody had forgotten the slash in the end tag of some element. 
I can imagine dozens of such errors. And there is no feedback, only when 
someone at some time in the future builds the help files again and is 
annoyed by the crash due to somebody else's mistakes. Therefore, an 
easy-to use editing tool is essential if we want the (poor) help files 
of Lazarus to be improved.

BTW: User Don Siders is doing an excellent job in continuously 
submitting patches for the xml files. The help files have improved 
considerably since then (I wonder how he is editing the xml files.)

-------------- next part --------------
A non-text attachment was scrubbed...
Name: FPDocEditor_lclintf.png
Type: image/png
Size: 54230 bytes
Desc: not available
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20191218/b641a78b/attachment-0001.png>