Date: Mon, 08 Jun 2020 18:20:08 +0200 From: Pau Amma <pauamma@gundo.com> To: doc@freebsd.org Subject: Respecting DOCDIR in share/xml/urls.ent vs. documenting constraints on it in the FDP primer Message-ID: <7fa464fad50a848d0ead44a4172cdd9f@gundo.com>
next in thread | raw e-mail | index | archive | help
Executive summary: The '<!ENTITY url.doc.base "&url.base;/doc">' line in share/xml/urls.ent doesn't respect DOCDIR, but I'm not sure whether and how to best fix it (in the toolchain or in the FDP primer), or even if it needs to be fixed at all (eg I could be missing something). Longer version, lightly paraphrased and expanded from my mumblings in EFnet #bsddocs yesterday: I noticed that when using DOCDIR *and* the source dir isn't /parent/of/DOCDIR/doc, "make all install" generates links with the wrong prefix (in my case, /home/pauamma/doc) for URLs that in the XML source include "&url.doc.handbook;", which breaks a number of between-docs links. When using DOCDIR and the source dir *is* /parent/of/DOCDIR/doc, these links are still wrong but work *by accident* because copies of the .html files happen to be under ~/doc until the next make clean. After staring at XML source for 2 hours wondering why my links no longer worked following a source dir change, I noticed the following 3 lines in share/xml/urls.ent: <!ENTITY url.relprefix "../../../.."> <!ENTITY url.base "@@URL_RELPREFIX@@"> <!ENTITY url.doc.base "&url.base;/doc"> I think these are what causes the problem I'm seeing. Is this problem fixable in the toolchain at all? (I have no idea how, if it is. Makefiles are mostly a mystery to me.) Or should there be a warning in the FDP primer instead to always set DOCDIR to ~/doc or something? If this is a problem to be fixed in the documentation, I think there are 2 things to change: 1- the SVN checkout examples (eg, in 1.1) need to specify something different from ~/doc for the checkout directory, and 2- the DOCDIR examples need to be reworded to specify that DOCDIR *must* be (parent of checkout dir)/doc. Opinions, suggestions, and clues all welcome.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?7fa464fad50a848d0ead44a4172cdd9f>