Contents of the Information Box for custom components?

[CM630]

The easiest way to generate a help text is to add a comment BEFORE a property declaration in the published section.

As @JuhaManninen wrote (when the thread was created), there was a bug, so that did not work.

The more complex way is to create xml files for FPDoc. I had exercised that for TAChart and want to repeat this now for the Industrial package: In the package options go to "IDE Integration" and enter a path to the directory for the xml files in the "Search paths" box (the IDE proposes the folder "fpdoc" inside the package directory - that's fine). Then load the unit for which you want to add the xml texts into the IDE and open the FPDoc Editor (from "View" menu).
...

It occurred that the IDE has automatically added the path to the XML for me.
I tried it and it works, but there seems to be a bug related with the underlined text (see the image attached):



I will try to add this info in the Wiki until the end of the next week.

[wp]

but there seems to be a bug related with the underlined text

I see it in Laz/main, too. Would you mind to report this? I don't think that it's a bug in FPDoc since it does insert the < u > tags (but see below), it's also not a bug in the html viewer since I know that the TIpHtmlPanel does handle this correctly. Maybe in the converter from xml to html (fpdoc?).

@dsiders: In your own xml files did you ever notice that underlined text portions were not handled correctly (dropped)?

Anyway, the FPDocEditor is quite buggy. The most annoying feature to me is that it always reformats the files written, even without any changes made. This adds endless changes to version control. It's not a good idea to have it open for a long time.

Or, I saw this just now: Double-click on a word in a paragraph that you want to highlight as bold - but FPDocEditor highlights the entire line. When you now click on the B button (bold) the < b > tag is not applied correctly. This is because of that strange formatting concept which puts the < p > tag in a separate line before the paragraph text and the </ p> tag at the end of the same line. Therefore the xml text is

Code: [Select]

initial text:
<p>
The help text.</p>

after double-click on "help" and "B" click
<p>
<b>The help text.</p></b>    // Note: The terminating </b> should be before the terminating </p>!

after saving
<p>
<b/>The help text.</p>
&lt;/b&gt;
For FPSpreadsheet I wrote the help text using PasDoc, based on the inline comments of the source files. I am not happy with that either because I do not like to have too much documentation in the interface part of a unit. And the PasDoc-generated help files look very crowded to me...

If I'd return to FPDoc for FPSpreadsheet, I think I'd use the makeskel utility (in FPC folder) to create the frame of empty keywords in the xml, and then use an ordinary text editor for adding the text itself. There is a quite nice articel by Michael Van Canneyt about FPDoc: https://www.freepascal.org/~michael/articles/fpdoc/fpdoc.pdf

I will try to add this info in the Wiki until the end of the next week.

There is already a wiki article at https://wiki.freepascal.org/FPDoc_Editor, I don't know whether it needs a brush-up.

BTW, there is also a large editor, LazDE (https://wiki.freepascal.org/Lazarus_Documentation_Editor, source in folder doceditor of Lazarus installation), but I never got into how to use it.

[JuhaManninen]

you can provide help by your self with WebView2
to see: https://github.com/paule32/chmViewer

It is for Windows only.   

[JuhaManninen]

I see it in Laz/main, too. Would you mind to report this? I don't think that it's a bug in FPDoc since it does insert the < u > tags (but see below), it's also not a bug in the html viewer since I know that the TIpHtmlPanel does handle this correctly. Maybe in the converter from xml to html (fpdoc?).

How is it converted? I haven't played with this myself thus a dummy question.

[dsiders]

I see it in Laz/main, too. Would you mind to report this? I don't think that it's a bug in FPDoc since it does insert the < u > tags (but see below), it's also not a bug in the html viewer since I know that the TIpHtmlPanel does handle this correctly. Maybe in the converter from xml to html (fpdoc?).

How is it converted? I haven't played with this myself thus a dummy question.

The InfoBox in the IDE uses the THtml2TextRenderer - which does not handle <u></u> tags (and many other) tags.

[JuhaManninen]

The InfoBox in the IDE uses the THtml2TextRenderer - which does not handle <u></u> tags (and many other) tags.

Yes, both the InfoBox and the edit hint use THtml2TextRenderer when TurboPowerIPro package is not installed. It is useful for having a minimal light IDE, for example when developing and debugging the IDE itself.
AFAIK THtml2TextRenderer shows the HTML text content correctly, it only doesn't underline for obvious reasons.
According to wp TurboPowerIPro also renders correctly and the problem is in XML -> HTML conversion.
I have forgotten how it is converted.

[dsiders]

The InfoBox in the IDE uses the THtml2TextRenderer - which does not handle <u></u> tags (and many other) tags.

Yes, both the InfoBox and the edit hint use THtml2TextRenderer when TurboPowerIPro package is not installed. It is useful for having a minimal light IDE, for example when developing and debugging the IDE itself.
AFAIK THtml2TextRenderer shows the HTML text content correctly, it only doesn't underline for obvious reasons.
According to wp TurboPowerIPro also renders correctly and the problem is in XML -> HTML conversion.
I have forgotten how it is converted.

TCodeHelpManager.GetFPDocNodeAsHTML - and it does not handle u tags.

[wp]

Then just add a "or (Node.NodeName='u') " to the sequence of html tag names queried in a lengthy "if" instruction in "NodeToHTML()". Tested, it works.

Is there anything else from fpdoc missing here? Because it looks that everything between omitted html tags here is omitted from conversion to html.

I'll file a bug report for the underline issue for better documentation.

[EDIT]
Bug report: https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/41739
Fixed in: https://gitlab.com/freepascal.org/lazarus/lazarus/-/commit/aba12f952b522a61a067ad1c7a29ff45f0a6eec5

[CM630]

I added info in the wiki:
https://wiki.freepascal.org/How_To_Write_Lazarus_Component#Adding_contensts_for_the_Information_box

The remark tag also causes undisplayed text, but that is what remark means. This info is also added in the wiki.

Anyway, the FPDocEditor is quite buggy. The most annoying feature to me is that it always reformats the files written, even without any changes made. This adds endless changes to version control. It's not a good idea to have it open for a long time.

I added this info is also in the wiki,  I am not sure that I understood you completely (I think that I understood you, but I do not get what bothers you, so I might not have). Maybe I have misinterpreted it in the wiki.

I used TLazSerial in the screenshots, I hope the author(s) do not get offended.

[JuhaManninen]

TCodeHelpManager.GetFPDocNodeAsHTML - and it does not handle u tags.

Ah yes. No HTML files are created. Somehow I had forgotten how this works.

I added this info is also in the wiki,  I am not sure that I understood you completely (I think that I understood you, but I do not get what bothers you, so I might not have). Maybe I have misinterpreted it in the wiki.

The same things bother me, too. FPDocEditor formats text without any reason. When you commit it to revision control, it shows a massive change while you only fixed a small typo. Not good. What algorithm it uses for formatting? There seems to be no logic. The output is not nice and human readable like a well formatted XML can be.
That is a pity because the idea of an integrated document editor is good and it works well in many other aspects.

[dsiders]

TCodeHelpManager.GetFPDocNodeAsHTML - and it does not handle u tags.

Ah yes. No HTML files are created. Somehow I had forgotten how this works.

I added this info is also in the wiki,  I am not sure that I understood you completely (I think that I understood you, but I do not get what bothers you, so I might not have). Maybe I have misinterpreted it in the wiki.

The same things bother me, too. FPDocEditor formats text without any reason. When you commit it to revision control, it shows a massive change while you only fixed a small typo. Not good. What algorithm it uses for formatting? There seems to be no logic. The output is not nice and human readable like a well formatted XML can be.
That is a pity because the idea of an integrated document editor is good and it works well in many other aspects.

Gee, I wonder where I've heard this conversation before?

[paule32]

@Juha

yes, I compiled it under Windows - because my prefered OS.
But the Engine for display the WebPages is available for Windows. Linux and MacOS

[wp]

The remark tag also causes undisplayed text, but that is what remark means.

Not sure... The doc (https://www.freepascal.org/docs-html/fpdoc/fpdocsu87.html#x108-1070005.3.27) says:

A remark tag can be used to make a paragraph stand out. The remark is equivalent to the p tag, but it’s contents is formatted in a way that makes it stand out from the rest of the text.

Note that any text before or after the remark tag must be enclosed in paragraph (p) tags.

Example:
<p>Normal text.</p> 
<remark> 
This text will stand out. 
</remark> 
<p>Again normal text.</p>

Will be formatted as

Normal text.

Remark This text will stand out.

Again normal text.

@dsiders: Have you encountered this?

[CM630]

Since the list is started, one of the formatting buttons is disabled or simply does nothing.
And maybe a button „clear formatting“ would be useful.

[dsiders]

The remark tag also causes undisplayed text, but that is what remark means.

Not sure... The doc (https://www.freepascal.org/docs-html/fpdoc/fpdocsu87.html#x108-1070005.3.27) says:

A remark tag can be used to make a paragraph stand out. The remark is equivalent to the p tag, but it’s contents is formatted in a way that makes it stand out from the rest of the text.

Note that any text before or after the remark tag must be enclosed in paragraph (p) tags.

Example:
<p>Normal text.</p> 
<remark> 
This text will stand out. 
</remark> 
<p>Again normal text.</p>

Will be formatted as

Normal text.

Remark This text will stand out.

Again normal text.

@dsiders: Have you encountered this?

Not sure what you're asking, but..In FpDoc output formats the remark tag cause a CSS style to be applied to the paragraph anf the tesxt content. The paragraph usually have the orange-ish background with "Remark" in bold-face. That's how the text stands out.

If tyou want the Info Box to emulate that, you'll have include include a paragraph style and a bolf-faced "Remark" text element before the element content.