[Lazarus] Duplicate items in xml doc files
Werner Pamler
werner.pamler at freenet.de
Wed Dec 18 16:21:33 CET 2019
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>
More information about the lazarus
mailing list