<html> <head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> </head> <body bgcolor="#FFFFFF" text="#000000"> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 12-03-25 02:32 PM, Julien Cristau wrote: > Hi, > > I'm trying to figure out how to correctly use the external references > stuff when building docs for my packages, and I have a few questions. > (I've read the xorg-sgml-doctools README, which is a big help, so I'm > mostly looking for confirmations.) > > First, the hardcoded pathnames in masterdb.xml won't really work for me. To be exact, masterdb.xml paths are @datarootdir@/doc/libXt/ which get resolved during 'make' time to /usr/share/doc/libXt. All docs must be built under the same $datarootdir for olinks to work. The "libXt" is based on ${PACKAGE_TARNAME} from the libXt package. > > E.g. I'll probably want to install the Xt docs in > /usr/share/doc/libxt-dev/ (as that's what my package is called) rather > than /usr/share/doc/libXt/. Should I be patching all the paths in > masterdb? Would that cause any issues for anyone else building docs on > a Debian system? This would be equivalent to moving the docs out of the libXt package and into a new libxt-dev package. In masterdb.xml, @datarootdir@/doc/libXt/ would need to be changed to @datarootdir@/doc/libxt-dev/ to match ${PACKAGE_TARNAME} of the libxt-dev package. That change alone would not be sufficient. Once installed, the docs are structured in a tree that is rooted at $datarootdir/doc. The <sitemap> xml markup is a mapping of the directory structure of the docs. This sitemap is used to construct references such that an html protocol doc can refer an html libX11 doc, for example. Any change in the docs installation directory structure that is not reflected in the sitemap will break olinks. So <dir name="libXt"> would also need to be changed to <dir name="libxt-dev">. If you are familiar with the change of X from "monolith" to "modular", one could say that for olinks to work, the docs have to be "monolith". The docs are scattered through several modules, but when installed under the same $datarootdir/doc tree, they become monolith. The sitemap navigates through the monolith. One example here from the libXt intrinsics html doc. It has a reference to libX11. The reference is: <a href="../libX11/libX11/libX11.html#Parsing_Command_Line_Options <a class="moz-txt-link-rfc2396E" href="view-source:file:///home/nadon/xorg/src/lib/libXt/libX11/libX11/libX11.html#Parsing_Command_Line_Options"><view-source:file:///home/nadon/xorg/src/lib/libXt/libX11/libX11/libX11.html#Parsing_Command_Line_Options></a>" The sitemap moves one up from to $datarootdir/doc and the down to libX11/libX11/libX11.html. > > > What's the impact of the 'unresolved olink' errors I see while > generating documentation? Do I need to have all the referenced docs > installed at their final locations (including the ones that come from > the same module) when building a module's docs, to avoid them? That > sounds like it would result in fun dependency loops. Dependency loops are unavoidable. In order to resolve all olinks, the build has to be run twice for all modules containing documentation. The README attempts to explain this in the "Local X builds" section. For example, x11proto can refer to libX11 and vice-versa. Build order will not help. There will always be an unresolved olink in one of the two modules upon the first build. During the second 'make clean all', all olinks will be resolved because all *.db.* files will have been generated. > > > I think I'm going to need some time to get this all straight :) I think only the sitemap has to be changed. The module xorg-sgml-doctools and all docs have to be rebuilt (twice). It's worth a try with a pair of modules having circular references. If a user downloads new packages from X.Org and builds them against the distro, the olinks should work. If a user downloads xorg-sgml-doctools and builds/installs it, your changes get overwritten and all links break. It still hurts my brain :-) > > > Cheers, > Julien > -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Mozilla - <a class="moz-txt-link-freetext" href="http://enigmail.mozdev.org/">http://enigmail.mozdev.org/</a> iEYEARECAAYFAk9xJ0AACgkQubv1WfueyfyDFACfa1PScHxNmrW0AVfUjUt6HP6b k8MAn2pJH9DgeBthNqThwkNAfIUKkc+T =ejhB -----END PGP SIGNATURE----- </body> </html>