Date: Thu, 19 Apr 2001 22:56:01 -0700 From: Dima Dorfman <dima@unixfreak.org> To: doc@freebsd.org Subject: Using <olink> to make intra-document references Message-ID: <20010420055601.62D953E09@bazooka.unixfreak.org>
index | next in thread | raw e-mail
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 <olink>
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:
<!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.
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
(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 @@
+<!-- $FreeBSD: doc/share/sgml/default.dsl,v 1.1 2000/09/28 23:29:48 nbm Exp $ -->
+
+<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY olink.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook OLink Summary V1.1//EN" CDATA DSSSL>
+]>
+
+<style-sheet>
+ <style-specification use="olink">
+ <style-specification-body>
+ <![ %output.html; [
+
+ (define %gentext-nav-use-tables%
+ ;; Use tables to build the navigation headers and footers?
+ #t)
+
+ (define %html-ext%
+ ;; Default extension for HTML output files
+ ".html")
+
+ (define %shade-verbatim%
+ ;; Should verbatim environments be shaded?
+ #f)
+
+ (define %use-id-as-filename%
+ ;; Use ID attributes as name for component HTML files?
+ #t)
+
+ (define %root-filename%
+ ;; Name for the root HTML document
+ "index")
+
+ (define html-manifest
+ ;; Write a manifest?
+ #f)
+
+ (define %generate-legalnotice-link%
+ ;; Should legal notices be a link to a separate file?
+ ;;
+ ;; Naturally, this has no effect if you're building one big
+ ;; HTML file.
+ #t)
+ ]]>
+ </style-specification-body>
+ </style-specification>
+
+ <external-specification id="olink" document="olink.dsl">
+</style-sheet>
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))))))
+
+ <!-- Conclusions: I don't know what I'm doing.
+ Assumptions: many.
+ -->
+ (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))
</style-specification-body>
</style-specification>
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 @@
+<!ENTITY doc.faq SYSTEM "../../books/faq/faq.sgml" CDATA SGML>
+<!ENTITY doc.handbook SYSTEM "../../books/handbook/book.sgml" CDATA SGML>
**********************************************************************
* 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 @@
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
+
+<!ENTITY % doc PUBLIC "-//FreeBSD//ENTITIES DocBook Document Entities//EN">
+%doc;
]>
<book>
@@ -768,8 +771,9 @@
<para>The '<filename>/etc/ppp/ppp.conf</filename>' 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
+<olink targetdocent="doc.handbook">FreeBSD Handbook</olink>
+describes the contents and syntax of this file in
detail.</para>
<para>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
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010420055601.62D953E09>