From owner-freebsd-doc Thu Apr 19 22:56:10 2001 Delivered-To: freebsd-doc@freebsd.org Received: from bazooka.unixfreak.org (bazooka.unixfreak.org [63.198.170.138]) by hub.freebsd.org (Postfix) with ESMTP id D7D8637B423 for ; Thu, 19 Apr 2001 22:56:01 -0700 (PDT) (envelope-from dima@unixfreak.org) Received: from spike.unixfreak.org (spike [63.198.170.139]) by bazooka.unixfreak.org (Postfix) with ESMTP id 62D953E09 for ; Thu, 19 Apr 2001 22:56:01 -0700 (PDT) To: doc@freebsd.org Subject: Using to make intra-document references Date: Thu, 19 Apr 2001 22:56:01 -0700 From: Dima Dorfman Message-Id: <20010420055601.62D953E09@bazooka.unixfreak.org> Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org I had some free time today, and since Nik recently resurrected the sane hierachy on the website I thought I'd take a look at the stuff some people have hinted should be used to make intra-document links. 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: once that's included into the document, one can do something like this: This is a link to the "Limiting users" section of the FreeBSD Handbook. 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. 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 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 (I actually know very little about SGML; the only reason I was able to do any this is because some parts of DSSSL resemble Lisp). - The olink file generated for the Handbook contains entities such as & and ö 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. So, without further ado, here are the patches. 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). Dima Dorfman dima@unixfreak.org P.S. This is more of a "is-this-how-we-want-to-do-it" than a "tell-me-if-there's-anything-wrong-because-I-want-to-commit-it" type thing. --- /dev/null Thu Apr 19 22:42:32 2001 +++ share/sgml/olink.dsl Thu Apr 19 18:16:33 2001 @@ -0,0 +1,47 @@ + + + +]> + + + + + + + + + + Index: share/sgml/freebsd.dsl =================================================================== RCS file: /st/src/FreeBSD/doc/share/sgml/freebsd.dsl,v retrieving revision 1.28 diff -u -r1.28 freebsd.dsl --- share/sgml/freebsd.dsl 2001/04/09 20:35:47 1.28 +++ share/sgml/freebsd.dsl 2001/04/20 05:35:49 @@ -414,6 +414,23 @@ (string-append "Q" (question-answer-label))) (else (string-append "AEN" (number->string (all-element-number nd)))))) + + + (define (olink-href target modespec) + (let* ((linfo (normalize (attribute-string (normalize "localinfo")))) + (sysid (entity-system-id target)) + (basef (trim-string sysid '(".sgml"))) + (based (trim-string basef '("book" "article"))) + (sumdoc (sgml-parse (string-append basef %olink-outline-ext%))) + (root (node-property 'document-element sumdoc)) + (node (if linfo (element-with-id linfo root) root)) + (idfn (attribute-string (normalize "id") node)) + (anchor (if idfn (string-append "#" idfn) "")) + (href (string-append based + (attribute-string (normalize "href") node) anchor))) + href)) Index: share/mk/doc.docbook.mk =================================================================== RCS file: /st/src/FreeBSD/doc/share/mk/doc.docbook.mk,v retrieving revision 1.31 diff -u -r1.31 doc.docbook.mk --- share/mk/doc.docbook.mk 2001/03/27 16:15:07 1.31 +++ share/mk/doc.docbook.mk 2001/04/20 05:35:48 @@ -68,6 +68,7 @@ NSGMLS?= ${PREFIX}/bin/nsgmls .endif +DSLOLINK?= ${DOC_PREFIX}/share/sgml/olink.dsl DSLHTML?= ${DOC_PREFIX}/share/sgml/default.dsl DSLPRINT?= ${DOC_PREFIX}/share/sgml/default.dsl FREEBSDCATALOG= ${DOC_PREFIX}/share/sgml/catalog @@ -193,7 +194,13 @@ .MAIN: all -all: ${_docs} +# XXX FIXME +CLEANFILES+= ${DOC}.olink + +all: ${DOC}.olink ${_docs} + +${DOC}.olink: ${SRCS} + ${JADE} -ioutput.html ${JADEOPTS} -d ${DSLOLINK} -t sgml ${MASTERDOC} > ${.TARGET} || (rm -f ${.TARGET} && false) index.html HTML.manifest: ${SRCS} ${LOCAL_IMAGES_LIB} ${IMAGES_PNG} .if defined(GEN_INDEX) Index: share/sgml/catalog =================================================================== RCS file: /st/src/FreeBSD/doc/share/sgml/catalog,v retrieving revision 1.14 diff -u -r1.14 catalog --- share/sgml/catalog 2001/02/20 19:10:47 1.14 +++ share/sgml/catalog 2001/04/20 05:35:48 @@ -20,6 +20,9 @@ PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" "man-refs.ent" +PUBLIC "-//FreeBSD//ENTITIES DocBook Document Entities//EN" + "doc-refs.ent" + PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//EN" "freebsd.dsl" --- /dev/null Thu Apr 19 22:42:32 2001 +++ share/sgml/doc-refs.ent Thu Apr 19 21:07:43 2001 @@ -0,0 +1,2 @@ + + ********************************************************************** * NEW PATCH FOLLOWS ********************************************************************** Index: en_US.ISO_8859-1/books/ppp-primer/book.sgml =================================================================== RCS file: /st/src/FreeBSD/doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v retrieving revision 1.10 diff -u -r1.10 book.sgml --- en_US.ISO_8859-1/books/ppp-primer/book.sgml 2001/04/17 15:58:38 1.10 +++ en_US.ISO_8859-1/books/ppp-primer/book.sgml 2001/04/20 05:35:43 @@ -1,6 +1,9 @@ %man; + + +%doc; ]> @@ -768,8 +771,9 @@ The '/etc/ppp/ppp.conf' file contains the information and settings required to set up a dial-out PPP connection. More than one -configuration may be contained in this file. The FreeBSD handbook -(XXX URL? XXX) describes the contents and syntax of this file in +configuration may be contained in this file. The +FreeBSD Handbook +describes the contents and syntax of this file in detail. This section will describe only the minimal configuration to get a To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message