Bug 27605

Description dd 2001-05-24 04:50:01 UTC

[ I am submitting this as a PR so that it doesn't get lost.  I sent a
very similar e-mail to -doc on April 19, 2001, but it elicited no
response.  Additionally, Nik doesn't seem to have time to take a look
at it and address the issues outlined below, and I don't blame him: it
isn't very fun.  This PR includes the patches I have to date, and the
issues with them that I'm aware of.  It is my hope that someone,
someday, will pick this up, resolve the issues, clean it up, and
commit it (or, if <olink> isn't what we want to use, then I'm fine
with this being closed).  I'd appreciate if this PR were kept open
until some sane way of making links between documents is implemented;
<ulink> just doesn't cut it. ]

As of 2001/05/20, there is no way other than <ulink> to link from one
document (e.g., the Handbook) to another (e.g., the FAQ).  According
to Nik, the most "SGML"-like way of doing something like this would be
to use the <olink> tag.  Unfortunately, the semantics of <olink>
aren't well-defined, and there are, as far as I know, no examples of
its use.  One day some time ago I sat down and tried to add the
requied infrastructure so that it can be used in the FreeBSD
documentation tree.  This is the result of that work.

[ The rest of this assumes that you know what <olink> is, and what
it's supposed to do; if you don't, you may want to find out before
going on.  Nik recommends these web sites which I've found useful:

     http://www.docbook.org/tdg/html/olink.html
     http://www.nwalsh.com/docbook/dsssl/doc/olinksemantics.html
]

The problem can be divided into two parts: generating the
.olink files, and using the .olink files.

Generating the files is relatively easy.  Basically, we create a DSSSL
stylesheet, olink.dsl, and use it instead of freebsd.dsl to generate
the .olink file (freebsd.dsl is still used to generated HTML and other
stuff, of course).  The only problem here is that the options used to
generate the olink summary have to be the same ones used to generate
the HTML.  I.e., if %html-ext% is ".html" in the olink summary it also
better be ".html" in the HTML or things won't work.  In my tests I
just pasted that stuff into olink.dsl (which looks like default.dsl
except s/docbook/olink/g), but I'm sure there's a more elegant way to
do that.

Using the tag itself is also easy.  Essentially, we create a
doc-refs.ent file a la man-refs.ent and fill it with stuff that looks
like:
     
        <!ENTITY doc.faq SYSTEM "../../books/faq.sgml" CDATA SGML>
        <!ENTITY doc.handbook SYSTEM "../../books/handbook/book.sgml" CDATA SGML>

once that's included into the document, one can do something like this:

        <olink targetdocent="doc.handbook" linkend="users-limiting">
        This is a link to the "Limiting users" section of the
        FreeBSD Handbook.</olink>

<modespec> can still be used to automatically generate the caption,  
but is not required.  Actually, all of the above doesn't work with the
stock stylesheets.  More specifically, the link generated will be   
horribly incorrect.  This can be remedied by overriding the olink-href
procedure (see patch).

The remaining caveats (problems?) are as follows:

        - Linking to a specific question in the FAQ doesn't work
        because /usr/local/share/sgml/docbook/dsssl/modular/olink/olink.dsl,
        referenced by the new share/sgml/olink.dsl, doesn't understand
        <qandaset> and friends.
        
        - This depends on being able to construct a relative link from
        one document to another using "../../(book|article)/(document-name)".

        - The options, such as %html-ext%, use-id-as-filename, etc., are 
        duplicated in freebsd.dsl and olink.dsl.  I don't know how to fix it
        
        - The olink file generated for the Handbook contains entities
        such as &amp; and &ouml; which are not supported.  These cause
        warnings when running jade on a document which links to the Handbook.
        They're just warnings, and everything else works fine (I think), but
        it's something we may want to fix.

        - I probably screwed up the stuff in doc.docbook.mk.  It
        works, but it's probably misplaced.

        - Generating olink files isn't instantaneous, so it slows down
        the build a little.  I don't think it's a problem.
        
The patch in the "Fix" section is divided into two parts.  The first
part is the infrastructural stuff, and the second part is an example
of how all of it is used (example of linking from ppp-primer to the
Handbook).

Fix: share/sgml/olink.dsl and share/sgml/doc-refs.ent are new files, and is
diff'd against /dev/null.  As explained above, the first part is the
infrastructural stuff, and the second part is an example of how to use
it.

**********************************************************************
**********************************************************************
**************************** SECOND PATCH ****************************
**********************************************************************
**********************************************************************