[Lazarus] Duplicate items in xml doc files

[Don Siders]

On Wed, Dec 18, 2019 at 10:24 AM <lazarus-request at lists.lazarus-ide.org> wrote:

> From: Werner Pamler <werner.pamler at freenet.de>
> Subject: Re: [Lazarus] Duplicate items in xml doc files
> Message-ID: <b3211483-23be-e249-5368-6609de97aab3 at freenet.de>

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

That's a possibility. Mistakes happen. But in looking at the file
there are several duplicates. I don't think I would have been that
careless.

Here are the duplicates I've detected:

TCanvas.Arc
TCanvas.Arc.height
TCanvas.Arc.width
TCanvas.Arc.x
TCanvas.Arc.y
TCanvas.Chord
TCanvas.Chord.Height
TCanvas.Chord.Width
TCanvas.Chord.x
TCanvas.Chord.y
TCanvas.Ellipse
TCanvas.FillRect
TCanvas.Frame
TCanvas.FrameRect
TCanvas.PolyBezier
TCanvas.PolyBezier.Continuous
TCanvas.PolyBezier.Filled
TCanvas.PolyBezier.Points
TCanvas.Polygon
TCanvas.Polygon.NumPts
TCanvas.Polygon.Points
TCanvas.Polygon.Winding
TCanvas.Polyline
TCanvas.Polyline.NumPts
TCanvas.Polyline.Points
TCanvas.RadialPie
TCanvas.RadialPie.Height
TCanvas.RadialPie.Width
TCanvas.RadialPie.x
TCanvas.RadialPie.y
TCanvas.Rectangle
TCanvas.RoundRect
TCanvas.RoundRect.RX
TCanvas.RoundRect.RY
TCustomBitmap.CanReadGraphicStreams.AClass
TCustomBitmap.CanReadGraphicStreams.Result
TFont.Assign
TPortableNetworkGraphic

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

Sure. Just a matter of resolving conflicting content (if any).

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

Yes. That's some of the the reasons I stopped using LazFPDocEditor and
FP DocEditor. The other being that those tools don't enforce stylistic
use of FPDoc markup. There no reason to ever see BR sand PRE tags in
an FP Doc XML file. Whether it was generated by FP Doc or manually.

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

I can't see the attachment; it is scrubbed in the email digest. The
<short></short> could be because of my editing process. At a minimum,
a doc topic needs a short tag. I have a habit of putting them in when
I start editing a file.

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

I edit manually too. It's neither difficult nor error prone. I get
exactly the FP Doc markup that I feel is appropriate.

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

Immediate feedback on tagging and structure issues is available using
Tidy. Works for me.

In general, I think the editors are great if you're uncomfortable with
XML markup.I'm all for them when they work properly. When they become
a hindrance, I avoid them. In my case, they were more of a nuisance
than an aid.

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

Thanks for the compliment.

I am using the IDE to navigate source and determine ancestry. I use
Atom to edit the FP Doc XML description files (due to its support for
XML syntax and "XML-completion" facilities). I use Tidy to validate
the XML content. I use ASpell to catch spelling mistakes and
fat-fingered typing.
Since makeskel doesn't support update mode, I resolve additions and
removals using a tool I cobbled together using TPasSrcAnalysis and
TXMLDocument. Apparently a duplicate check needs to be added to it.

--
Don