FPC(fixes)+lazarus(trunk) CHM doc snapshot beta

[marcov]

I did a rehearsal for FPC release building, and uploaded the results to the usual site:

http://www.stack.nl/~marcov/doc-chmbeta.zip

FPC is fixes3.2, lazarus is from trunk (as of today), and the used fpdoc is from fixes, as the trunk fpdoc seems to segfault (which I assume Don already noticed in July, from comments in build_chm.sh)

Also I can't get latex to compile it anymore on Windows, probably due to the docs restructure and maybe newer latex snapshots. Compiling a file with path\filename seems to not work (with either / or \)

[dsiders]

I did a rehearsal for FPC release building, and uploaded the results to the usual site:

http://www.stack.nl/~marcov/doc-chmbeta.zip

Nice. Internal links to identifiers with dotted unit namespaces seem to be working well.

FPC is fixes3.2, lazarus is from trunk (as of today), and the used fpdoc is from fixes, as the trunk fpdoc seems to segfault (which I assume Don already noticed in July, from comments in build_chm.sh)

You are correct. I've tried a couple of FPC trunk builds since then... with no change.

[dsiders]

Nice. Internal links to identifiers with dotted unit namespaces seem to be working well.

I stand corrected. It didn't pull in any of the content. Not for system.uitypes.TColor at least.

[marcov]

I assume that support is in trunk.  Fixes is still mostly 3.2.2 level I guess.

I also saw that the system.uitypes index had two unclickable entries for "string" and "String".

I tried yesterday to reproduce the crashing on windows compiling, but couldn't.  It compiled fine. 

Do those links work in the online version, and what link do you use to test?

[dsiders]

I assume that support is in trunk.  Fixes is still mostly 3.2.2 level I guess.

I need to rebuild my FPC Trunk and try again. I haven't been tracking the 3.2 fixes branch... perhaps it's time to start.

I also saw that the system.uitypes index had two unclickable entries for "string" and "String".

I noticed some of those for ordinal types like Word too.

I tried yesterday to reproduce the crashing on windows compiling, but couldn't.  It compiled fine. 

My problem was a run-time error in the FPDOc output. At some point, it decided to spew binary content on the screen and stopped writing the help output. I'll try again and see what happens now.

Do those links work in the online version, and what link do you use to test?

If you mean existing online versions at https://www.freepascal.org/docs.html... then No. system.uitypes is not icluded there.

I use any  property defined as TColor to test, like TControl.Color.
https://lazarus-ccr.sourceforge.io/docs/lcl/controls/tcontrol.color.html

Clicking on the type in the source declaration or navigating between topics should ultimately take you to system.uitypes. It doesn't work in the link above.
I noticed that your beta did navigate  to the topic, but it does not have the content for the "TColor" topic in the XML file as if it was not found. But that content exists in Trunk. I haven't looked at fixes yet.

I try my luck after rebuilding trunk and making a build for fixes.

[dsiders]

I did a rehearsal for FPC release building, and uploaded the results to the usual site:

http://www.stack.nl/~marcov/doc-chmbeta.zip

FPC is fixes3.2, lazarus is from trunk (as of today), and the used fpdoc is from fixes, as the trunk fpdoc seems to segfault (which I assume Don already noticed in July, from comments in build_chm.sh)

Also I can't get latex to compile it anymore on Windows, probably due to the docs restructure and maybe newer latex snapshots. Compiling a file with path\filename seems to not work (with either / or \)

I've got good news and bad news...

The good news:

* FPDoc 3.3.1 no longer produces a run-time error when generating output.
* Topics with dotted namespaces like system.uitypes.TColor are linkable using the .xct indices from your beta.

The bad news:

* Topics in dotted namespace units have no content. None of them. See system.uitypes.tcolor in RTL.chm. It finds the code and produces a navigation link to an empty topic. system.uitypes.xml has content for various topics but FPDoc 3.3.1 does not pull it in. So I doubt FPDoc from a fixes branch would fare any better.

The FPC documentation repository has only pre-3.X release tags and the main branch... so it's not a matter of cherry-picking updated XML to another branch.

i haven't sorted out using the FPC 3.2 fixes yet. But I'll keep trying.

[marcov]

* Topics in dotted namespace units have no content. None of them. See system.uitypes.tcolor in RTL.chm. It finds the code and produces a navigation link to an empty topic. system.uitypes.xml has content for various topics but FPDoc 3.3.1 does not pull it in. So I doubt FPDoc from a fixes branch would fare any better.

The FPC documentation repository has only pre-3.X release tags and the main branch..

I can vaguely remember this is some fundamental problem.   fpdoc works internally with fully qualified paths (e.g. rtl.unitname.recordtype.fieldname).  If unit name is system.uitypes, it tries to find symbol uitypes in system. The online html also has this problem: https://www.freepascal.org/daily/doc/rtl/system.uitypes/index-5.html. 

Probably we either need to add some disambiguating syntax (like adding some quoting system like  rtl.#system.uitypes#.recordtype.fieldname or change to a different separator all together (but that would be a lot of work to change all XMLs) or maintain lists of packages and unitnames and then always do a longest match. That maybe risks that other corner cases be found or that the list of units is not complete at any point when this system is used

[marcov]

Some follow up:

• system.uitypes XML is disabled in xml\rtl-project.xml because it is not yet complete. (Michael only enables completely documented units). The files are commented in the XML using <!---- styled html/xml comments. But for your own tests you can enable it. Keep in mind there is one line commented for the parsing of the system.uitypes source, and one for the xml with data
• if you enable it, the short description in the package's unit list is missing. That is localized to a routine that also splits up such paths during XML loading, but not solved yet.
• Also in the System.Uitypes overview (if you click the unit name in the RTL package list) sometimes things are not right. I suspect this is a different incarnation of the same issue. To be revisited if that is fixed.
• I suspect if these are fixed, similar issues in XCT loading will pop up.

[dsiders]

Some follow up:

• system.uitypes XML is disabled in xml\rtl-project.xml because it is not yet complete. (Michael only enables completely documented units). The files are commented in the XML using <!---- styled html/xml comments. But for your own tests you can enable it. Keep in mind there is one line commented for the parsing of the system.uitypes source, and one for the xml with data

That particular issue should be resolved by the patch in https://gitlab.com/freepascal.org/fpc/documentation/-/issues/39376.

• if you enable it, the short description in the package's unit list is missing. That is localized to a routine that also splits up such paths during XML loading, but not solved yet.
• Also in the System.Uitypes overview (if you click the unit name in the RTL package list) sometimes things are not right. I suspect this is a different incarnation of the same issue. To be revisited if that is fixed.
• I suspect if these are fixed, similar issues in XCT loading will pop up.

I have never successfully built RTL docs. I'll give it another shot.

Thanks for the follow-up.

--
Don