docs and masterdb

[Gaetan Nadon]

-----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
<view-source:file:///home/nadon/xorg/src/lib/libXt/libX11/libX11/libX11.html#Parsing_Command_Line_Options>"

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 - http://enigmail.mozdev.org/

iEYEARECAAYFAk9xJ0AACgkQubv1WfueyfyDFACfa1PScHxNmrW0AVfUjUt6HP6b
k8MAn2pJH9DgeBthNqThwkNAfIUKkc+T
=ejhB
-----END PGP SIGNATURE-----

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg-devel/attachments/20120326/df7fb45e/attachment.html>