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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20191217/53e5cdd5/attachment.html>

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

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.

Op 2019-12-17 om 22:52 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...

Op 2019-12-18 om 12:55 schreef Werner Pamler 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

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

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>

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.

Michael Van Canneyt wrote

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.

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

Marco van de Voort wrote

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

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.

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.

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

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.

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.

Don Siders wrote

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.

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.

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

No. It won't destroy anything. It may turn it into a unreadable mess for the human being editing the file. But it won't lose or alter anything beyond whitespace and indentation levels.

and add numerous svn diffs again.

Now this is the *real* issue, and it's one that others have brought up as well. Consider for a moment that makeskel writes a skeleton using an empty <short></short> element and the doc editors use the <short/> tag. Built in diffs. And it has nothing to do with me, my selected tool chain, or files that I have touched.

I do add blank lines and indentation. I'm not a machine... I need it.

I wasn't advocating their use. The question was asked and answered. That's all.

Look. I'm not trying to be difficult. I'm not a "rock star" programmer. So, I chose to contribute in whatever way I could. If what I'm doing is a pain point for the project, it is easy to resolve.

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.

I agree.

But I think you'll have to elaborate on the "svn-friendly" bit. For example, I'm updating controls.xml right now. It's a 600K XML file. The diff is at 1MB and growing. There is nothing svn-friendly about of course, you're not interested in the updates
just to keep the svn history clean and tight.

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,