Forum > Documentation (Maintaining -)

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

<< < (2/2)

dsiders:

--- Quote from: marcov on December 23, 2023, 02:35:06 pm ---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 \)

--- End quote ---

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:

--- Quote from: dsiders on December 25, 2023, 02:51:47 am ---* 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..

--- End quote ---

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:

--- Quote from: marcov on December 30, 2023, 01:39:26 pm ---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
--- End quote ---

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


--- Quote from: marcov on December 30, 2023, 01:39:26 pm ---
* 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.
--- End quote ---

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

Thanks for the follow-up.

--
Don

Navigation

[0] Message Index

[*] Previous page

Go to full version