[Lazarus] Duplicate items in xml doc files

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

[Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list

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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list


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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list

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)


--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list

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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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.)


--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus

FPDocEditor_lclintf.png (72K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list


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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
On Wed, 18 Dec 2019 16:21:33 +0100
Werner Pamler via lazarus <[hidden email]> 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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
On Wed, Dec 18, 2019 at 10:24 AM <[hidden email]> wrote:

> From: Werner Pamler <[hidden email]>
> Subject: Re: [Lazarus] Duplicate items in xml doc files
> Message-ID: <[hidden email]>

> 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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list


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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
> 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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] Duplicate items in xml doc files

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus