Re: [Lazarus] Duplicate items in xml doc files
Okay, Back to the original topic. The duplicates in graphics.xml are almost certainly because they are overloaded methods. Whether that is correct in the context of the tool used to update the file, I do not know, I am submitting a patch for other files with duplicate topics.This does not include graphics.xml; I was hoping the new content could be resolved by the author, -- Don -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
> makeskel does support update, the Makefile of fpc docs has even a target for > it ? > It only does additions, though. > I suppose that deletions should also be easily added. > > Michael. My initial efforts to use it were in the Lazarus 1.8.x time frame. and it would not run without exception then. So I sought an alternate mechanism. I'd be glad to give it another try to see how it works out. == Don -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
Am 19.12.2019 um 20:48 schrieb Don Siders via lazarus: 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. Just to make sure: It was never my intention to say that you did. I edit manually too. It's neither difficult nor error prone. I get exactly the FP Doc markup that I feel is appropriate. Now we have a problem. FPDocEditor and LazDocEditor ARE distributed with Lazarus, and nobody is prevented from using them. So, when I modify one of your recent xml files using FPCDocEditor, there's a chance that FPDocEditor will destroy your markup and add numerous svn diffs again. 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. A long tool-chain. Only enthusiast like you will do that. I really think that in particular FPDocEditor, maybe also LazDocEditor, is an important tool for the occasional user. But it should be re-worked to produce consistent and svn-friendly xml files. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
On Thu, 19 Dec 2019, Don Siders via lazarus wrote: 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. makeskel does support update, the Makefile of fpc docs has even a target for it ? It only does additions, though. I suppose that deletions should also be easily added. Michael. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
On Wed, Dec 18, 2019 at 10:24 AM wrote: > From: Werner Pamler > Subject: Re: [Lazarus] Duplicate items in xml doc files > Message-ID: > 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 by their > short forms (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 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
Re: [Lazarus] Duplicate items in xml doc files
Am 18.12.2019 um 13:11 schrieb Marco van de Voort via lazarus: A lemma in the help that is just "polybezier", and not TCanvas.polybezier. I assume it is a global procedure The lemma has Source position: winapih.inc line 211 I looked at TCanvas.PolyBezier (the help text is in graphics.xml). The help text for the lemma that you mention is in interfacebase.xml and is structured correctly (in my opinion) because is does not contain duplicate xml nodes, and the non-canvas PolyBezier does display the description in the mouse-over hint. (But your note reminds me to adapt the docs change that I made in graphics.xml for issue https://bugs.freepascal.org/view.php?id=36452 also in interfacebase.xml.) -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
On Wed, 18 Dec 2019 16:21:33 +0100 Werner Pamler via lazarus wrote: >[...] > Another issue with the FPDocEditor is that it frequently writes back > to the xml file although nothing has been changed. Sound like a regression. It contains code to check if something has changed. Mattias -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
Am 18.12.2019 um 16:36 schrieb Werner Pamler via lazarus: Am 18.12.2019 um 16:29 schrieb Michael Van Canneyt via lazarus: That's why the docs of fpc have the checkxml tool, which is used to quickly check the XML structure after editing, before committing or building. Thanks - I did not know that. Where is this tool? I did a search through all fpc folders and did not find it. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
Am 18.12.2019 um 16:29 schrieb Michael Van Canneyt via lazarus: That's why the docs of fpc have the checkxml tool, which is used to quickly check the XML structure after editing, before committing or building. Thanks - I did not know that. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
On Wed, 18 Dec 2019, Werner Pamler via lazarus wrote: 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. That's why the docs of fpc have the checkxml tool, which is used to quickly check the XML structure after editing, before committing or building. Michael. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
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 by their short forms (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.) -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
Op 2019-12-18 om 12:55 schreef Werner Pamler via lazarus: You are sure you really have TCanvas.polybezier in the editor, and not the polybezier global? (at least I see a polybezier global in the last CHM snapshot) No, I am not sure. I even don't know what "polybezier global" is... A lemma in the help that is just "polybezier", and not TCanvas.polybezier. I assume it is a global procedure The lemma has Source position: winapih.inc line 211 -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
Am 18.12.2019 um 11:05 schrieb Marco van de Voort via lazarus: Op 2019-12-17 om 22:52 schreef Werner Pamler via lazarus: Fixing a docs-related issue today (https://bugs.freepascal.org/view.php?id=36452), I noticed that the entry for TCanvas.PolyBezier almost does not have any elements when the item is displayed in the *FPDoc editor* of Lazarus, i.e. I do "View" > "FPDoc Editor" and place the cursor in the normal source code window on the PolyBezier identifier - then the FPDoc editor displays only the "short" text, all other tabs are empty. On the other hand, the full chm file contains a lot more information (https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.polybezier.html), among it the description node which is the topic of that bug report. How is this possible? You are sure you really have TCanvas.polybezier in the editor, and not the polybezier global? (at least I see a polybezier global in the last CHM snapshot) No, I am not sure. I even don't know what "polybezier global" is... -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] Duplicate items in xml doc files
On Tue, 17 Dec 2019, Werner Pamler via lazarus wrote: Fixing a docs-related issue today (https://bugs.freepascal.org/view.php?id=36452), I noticed that the entry for TCanvas.PolyBezier almost does not have any elements when the item is displayed in the *FPDoc editor* of Lazarus, i.e. I do "View" > "FPDoc Editor" and place the cursor in the normal source code window on the PolyBezier identifier - then the FPDoc editor displays only the "short" text, all other tabs are empty. On the other hand, the full chm file contains a lot more information (https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.polybezier.html), among it the description node which is the topic of that bug report. How is this possible? It's XML, not a database with a unique index on element name. There is nothing to stop you from adding an entry twice, but such a feature could easily be added to the editors... On the other hand, opening the file graphics.xml in the *LazDocEditor *and finding the TCanvas node shows two PolyBezier nodes. The first one contains the text from the chm file, the second one has subnodes for the parameters of the function - there is no text assigned to them, but some of them are listed twice. There are other help items which show the same phenomenon: Chord, Polygon, PolyLine, RadialPie, where Polygon even has three entries! Is this correct? If yes it is at least very confusing and makes the LazDocEditor possibly a dangerous tool because the xml file might be damaged when text is added to the wrong node. Why would that damage the XML ? 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 ? And why are there so many empty lines? If they were added by either FPDocEditor or LazDocEditor (and not by the author manually) then these tools do not look very mature. The empty lines are irrelevant. Probably related: the source code mouse-over hint of PolyBezier shows only the "short" text, not the full "description". That will depend on the XML node that is chosen to display the help. Michael. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
[Lazarus] Duplicate items in xml doc files
Fixing a docs-related issue today (https://bugs.freepascal.org/view.php?id=36452), I noticed that the entry for TCanvas.PolyBezier almost does not have any elements when the item is displayed in the *FPDoc editor* of Lazarus, i.e. I do "View" > "FPDoc Editor" and place the cursor in the normal source code window on the PolyBezier identifier - then the FPDoc editor displays only the "short" text, all other tabs are empty. On the other hand, the full chm file contains a lot more information (https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.polybezier.html), among it the description node which is the topic of that bug report. How is this possible? On the other hand, opening the file graphics.xml in the *LazDocEditor *and finding the TCanvas node shows two PolyBezier nodes. The first one contains the text from the chm file, the second one has subnodes for the parameters of the function - there is no text assigned to them, but some of them are listed twice. There are other help items which show the same phenomenon: Chord, Polygon, PolyLine, RadialPie, where Polygon even has three entries! Is this correct? If yes it is at least very confusing and makes the LazDocEditor possibly a dangerous tool because the xml file might be damaged when text is added to the wrong node. 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)? And why are there so many empty lines? If they were added by either FPDocEditor or LazDocEditor (and not by the author manually) then these tools do not look very mature. Probably related: the source code mouse-over hint of PolyBezier shows only the "short" text, not the full "description". Werner -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
