From owner-freebsd-doc Wed May 23 20:50:16 2001 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 6095C37B424 for ; Wed, 23 May 2001 20:50:01 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.1/8.11.1) id f4O3o1h95402; Wed, 23 May 2001 20:50:01 -0700 (PDT) (envelope-from gnats) Received: from bazooka.unixfreak.org (bazooka.unixfreak.org [63.198.170.138]) by hub.freebsd.org (Postfix) with ESMTP id 237FA37B423 for ; Wed, 23 May 2001 20:49:15 -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 C720E3E84 for ; Wed, 23 May 2001 20:49:14 -0700 (PDT) Received: (from dima@localhost) by spike.unixfreak.org (8.11.3/8.11.1) id f4O3nED02768; Wed, 23 May 2001 20:49:14 -0700 (PDT) (envelope-from dima) Message-Id: <200105240349.f4O3nED02768@spike.unixfreak.org> Date: Wed, 23 May 2001 20:49:14 -0700 (PDT) From: dd@freebsd.org Reply-To: dd@freebsd.org To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.113 Subject: docs/27605: Cross-document references () Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org >Number: 27605 >Category: docs >Synopsis: Cross-document references () >Confidential: no >Severity: serious >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: sw-bug >Submitter-Id: current-users >Arrival-Date: Wed May 23 20:50:01 PDT 2001 >Closed-Date: >Last-Modified: >Originator: Dima Dorfman >Release: FreeBSD 5.0-20010519-CURRENT i386 >Organization: FreeBSD >Environment: System: FreeBSD spike.unixfreak.org 5.0-20010519-CURRENT FreeBSD 5.0-20010519-CURRENT #6: Mon May 21 16:48:38 PDT 2001 dima@spike.unixfreak.org:/c/home/dima/w/f/c/sys/compile/SPIKE i386 >Description: [ 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 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; just doesn't cut it. ] As of 2001/05/20, there is no way other than 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 tag. Unfortunately, the semantics of 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 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: 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 (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 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 & 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. 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). >How-To-Repeat: >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. --- /dev/null Mon May 21 18:50:52 2001 +++ share/sgml/olink.dsl Thu Apr 19 18:16:33 2001 @@ -0,0 +1,47 @@ + + + +]> + + + + + + + + + + --- /dev/null Mon May 21 18:50:52 2001 +++ share/sgml/doc-refs.ent Thu Apr 19 22:44:07 2001 @@ -0,0 +1,2 @@ + + Index: share/sgml/freebsd.dsl =================================================================== RCS file: /st/src/FreeBSD/doc/share/sgml/freebsd.dsl,v retrieving revision 1.29 diff -u -r1.29 freebsd.dsl --- share/sgml/freebsd.dsl 2001/05/20 17:30:44 1.29 +++ share/sgml/freebsd.dsl 2001/05/22 02:58:42 @@ -414,6 +415,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)) (define (xref-biblioentry target) (let* ((abbrev (node-list-first 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/05/22 02:58:42 @@ -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" 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/05/22 02:58:42 @@ -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) ********************************************************************** ********************************************************************** **************************** SECOND PATCH **************************** ********************************************************************** ********************************************************************** Index: 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 --- book.sgml 2001/04/17 15:58:38 1.10 +++ book.sgml 2001/05/22 03:02:09 @@ -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 >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message