Date: Wed, 23 May 2001 20:49:14 -0700 (PDT) From: dd@freebsd.org To: FreeBSD-gnats-submit@freebsd.org Subject: docs/27605: Cross-document references (<olink>) Message-ID: <200105240349.f4O3nED02768@spike.unixfreak.org>
next in thread | raw e-mail | index | archive | help
>Number: 27605
>Category: docs
>Synopsis: Cross-document references (<olink>)
>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 <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 & 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 @@
+<!-- $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>
--- /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 @@
+<!ENTITY doc.faq SYSTEM "../../books/faq/faq.sgml" CDATA SGML>
+<!ENTITY doc.handbook SYSTEM "../../books/handbook/book.sgml" CDATA SGML>
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))))))
+
+ <!-- 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))
(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 @@
<!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
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200105240349.f4O3nED02768>