Respecting DOCDIR in share/xml/urls.ent vs. documenting constraints on it in the FDP primer

[Pau Amma]

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.