On Wed, Dec 18, 2019 at 10:24 AM <lazarus-requ...@lists.lazarus-ide.org> wrote:
> From: Werner Pamler <werner.pam...@freenet.de> > Subject: Re: [Lazarus] Duplicate items in xml doc files > Message-ID: <b3211483-23be-e249-5368-6609de97a...@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 -- _______________________________________________ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
