Date: Wed, 14 Jun 2000 18:49:48 -0700 (PDT) From: papowell@astart.com To: freebsd-doc@freebsd.org Subject: Slick Talking DocBook Salesman + Diary Message-ID: <200006150149.SAA15926@h4.private>
next in thread | raw e-mail | index | archive | help
The DocBook Experience
Patrick Powell
1. Overview and Introduction- Wed May 31
I promised that I would keep notes as I did this stuff,
and here is the running diary.
I wrote the LPRng Print Spooler software, which is currently
running on over 80 different UNIX or Posix-like systems. The
two problems that I deal with are testing and documentation.
About a year ago at the 1999 FreeBSD Conference a smooth talking
SGML expert did a sales job on me for DocBook.
"Why stick to that old LinuxDoc stuff, move into the 21st century,
son," he said as he handed me another beer. "DocBook does it all.
Sings, dances, graphics, multiple languages, and it is the way that
all FreeBSD documentation will go."
I was impressed. However, I remembered another sales job like
this and found out that while a similar product sang, it only knew
one song and that was obscene, it could only dance the polka, it
needed an etch-a-sketch for an output device, and the multiple
languages included Uru, Afghani, and Puktu, but did not include
English and French.
"OK, I will take a crack at using DocBook, but you will be expected
to help me out on this, won't you?" I said, directing a steely
glare into the eyes of the slick talking salesman.
"Yeah, any time, just send me email, no problem!" was the reply.
Well, I finally got around to deciding to use the DocBook stuff.
Actually, what happened was that the current method I was using has
become so mangled that I forgot how to use it.
I decided to call the smooth talking salesman. With a name like
Nik, I should have known. Sigh. At least I did not sign my soul
away, just some time.
"Uhhh... Did I promise some time? Help? Ummm... I'm kinda
busy right now... Are you sure we met? Oh... Right. Well,
tell you what, why not give it a try and see what happens."
Sigh. O.K., I was on my own on this. So, remembering my standard
motto of dealing with the problem, "RTFM before you FU," I would
did the following:
a) Gather information
b) Hunt down examples
c) Push as far as I could
d) Beat on the author/support/mail groups
e) Record the steps so that others can benefit.
Right. Back to the stone age. Hunting, gathering, territorial
agression, and drawing on the cave walls. Sigh. The benefits
of modern technology.
2. RTFM and more RTFM - Mon Jun 5
I decided that the best place to start was the FreeBSD Documentation
project web page:
http://www.freebsd.org/docproj
This in turn led me to the DocProj primer.
http://www.freebsd.org/docproj/sgml.html
Now this was more like it. I threw myself at the examples.
Yuch. HTML from Hell. Bad Taste XML. But I'm tough, I can
take it. The first pass was OK - I got the idea. I got the
port:
/usr/ports/textproc/docproj
I read the bit about using TeX, and decided to see just how big
it was.
cd /usr/ports/textproc/docproj
make JADETEX=YES all install
Grind grind... download download... yawn yawn. I gave up and
went off and did something else. Six hours later I came back
just in time to read the comment about testing the distribution
go off the screen.
While I was waiting, I had dropped into San Diego Technical Books,
and dropped my usual $100... That place is almost as hard on my
bank account as Round Records, but I digress. I got
DocBook - The Definitive Guide by Norm Walsh and Leonard
Muellner.
I went home, sat in the Comfy Chair, and started reading
DocBook - the Definite Grunge...
3. Struggles with RTFM - Tue Jun 6
Eight hours later, this morning, I woke up refreshed and still on
the Preface. I drank 3 cups of coffee and sat on a rock in the
back garden, at 4:00 AM. I read the first 5 chapters, which look
REALLY FAMILIAR guys... and start to make a bit more sense.
I reread the DocProj Primer (hard copy). Went to the office, and
sat down at the terminal, drank 2 more cups of coffee, and started
in on the gathering... I mean trying to get the downloaded stuff
to work.
I set up my Environment variables.
I did the exercises in the DocProj Primer. I editted files, read
about the general and parameter entities, and had fun. The simple
examples worked, much to my amazement. Now for the good stuff -
lets produce the actual HTML output.
WHAT! No directions in the Primer? What... Sigh... OK OK This
is one of the reasons I am doing this...
PUT SOME INSTRUCTIONS IN THE PRIMER ON HOW TO PRODUCE
HTML and RTF, Nik
PUT SOME INSTRUCTIONS IN THE PRIMER ON HOW TO USE JADETEX!
Or what the hell JadeTex IS...
(Pant pant pant... There. I feel better now.)
Lets read the Jade documentation. Ummm... no man pages?
h4: {223} : jade -=
usage is "jade [-vCegG2] [-b encoding] [-f error_file] \
[-c catalog_sysid] [-D dir] [-a link_type] [-A arch] \
[-E max_errors] [-i entity] [-w warning_type] [-d dsssl_spec] \
[-V variable] [-t (fot|rtf|tex|sgml|xml)] [-o output_file] sysid..."
OK, lets see what else there is:
find / -type f -name '*jade*' -print
Voila!
/usr/ports/textproc/jade/work/jade-1.2.1/jade.htm
So I read the document. This document contained the following stuff
that was to come to haunt me, as being typical of the SMGL/Jade/DSSSL
universe - written by those who know for those who know:
---- from the jade.htm page ---
# Using Jade
#
# Add the directory containing the jade binary to your path, change
# directory to the dsssl directory, and do
#
# jade demo.sgm
#
# If everything is working, there should be a well-formed XML file
# demo.fot created.
#
# The system identifier of the document to be processed is specified
# as an argument to Jade. If this is omitted, standard input will be
# read.
#
# Jade determines the system identifier for the DSSSL specification
# as follows:
#
# 1.If the -d option is specified, it will use the argument as
# the system identifier.
#
# 2.Otherwise, it will look for processing instructions in the
# prolog of the document. Two kinds of processing instruction
# are recognized:
#
# <?stylesheet href="sysid" type="text/dsssl">
#
# The system data of the processing instruction is parsed
# like an SGML start-tag. It will be parsed using the
# reference concrete syntax whatever the actual concrete
# syntax of the document. The name that starts the processing
# instruction can be either stylesheet, xml-stylesheet or
# xml:stylesheet. The processing instruction will be ignored unless
# the value of the type attribute is one of text/dsssl, text/x-dsssl,
# application/dsssl, or application/x-dsssl. The value of href
# attribute is the system identifier of the DSSSL specification.
#
# <?dsssl sysid>
#
# The system identifier is the portion of the system data
# of the processing instruction following the initial name
# and any whitespace.
#
# Although the processing instruction is only recognized in
# the prolog, it need not occur in the document entity. For
# example, it could occur in a DTD. The system identifier will
# be interpreted relative to where the the processing instruction
# occurs.
#
# 3. Otherwise, it will use the system identifier of the document
# with any extension changed to .dsl.
#
----- end ----
OK, I admit it. After reading this I had severe mental cramps
and had to resort to theraputic treatment. Two beers for lunch
later I was ready for more.
"Where had I read this stuff before? Ahh... The DocBook - The
Definitive Guide." So I reread the first couple chapters. I then
reread this.
It was coming clearer - Now I understand where and what to do.
4. Try A Real Working Example - Wed Jun 7
I suddenly realized that there were some examples to look at: the
CVS tree. So I reread section 7.2 of the DocProj Primer, and
decided to try it:
mkdir /var/tmp/webuild
cd /var/tmp/webuild
CVSROOT=/home/ncvs ; export CVSROOT
cvs -r co www doc
--- ugly messages about no www ---
So I go to the /usr/src/share/examples and discover a
www-supfile.
No explanation of the differences between www and doc directories,
but Hey! I am used to this. Probably somewhere in the non-existent
as-of-yet documenters guide. I guess.
So I add this to the cvs list, download the cvs, and redo:
cvs -r co www doc
cd www
make links
cd en
make all
And there is a flurry of activity... as shell scripts get executed,
and ... jade is called... and HTML forms of the document is produced.
I looked at the output of the Make process and choose a victim...
I mean sample. Why not use the FreeBSD Documentation Project Primer
as the starting point?
/usr/local/bin/jade -ioutput.html -V nochunks
-c /var/tmp/webuild/doc/en_US.ISO_8859-1/books/fdp-primer/../../../share/sgml/catalog
-c /usr/local/share/sgml/docbook/dsssl/modular/catalog
-c /usr/local/share/sgml/docbook/catalog
-c /usr/local/share/sgml/jade/catalog
-d /var/tmp/webuild/doc/en_US.ISO_8859-1/books/fdp-primer/../../share/sgml/freebsd.dsl
-t sgml
/var/tmp/webuild/doc/en_US.ISO_8859-1/books/fdp-primer/book.sgml > book.html
5. The Conversion Process - Thu Jun 8
In email that I got from Nik ("really, its very easy"), he said
(with keyboard in cheek, most likely):
#
# > b) I have stuff in the LinuxBook form - is there an easy way
# > to convert?
#
# Yes and no.
#
# Go to http://www.freebsd.org/cgi/cvsweb.cgi/doc/en/handbook/Attic/
# and look at the README file. This covers the steps I took to convert
# the Handbook from LinuxDoc to DocBook. The raw conversion can be automated,
# but because DocBook is a 'richer' markup than LinuxDoc, you then have to
# go through it adjusting the automatic markup choices with more appropriate
# ones.
#
So I pulled down the document, read it (well, I scanned it once,
then reread up to section 4). This looked pretty straight forward:
a) you run this shell script
b) you get rid of bad stuff
c) you get rid of bad stuff
(iterate until happy)
Being the logical scientific experimenter I am, I carefully
cloned my FreeBSD system and ran this procedure on another machine.
Been there, done this, before. Yeah...
I ran the script. It took about 10 seconds. I was suprised.
I then ran nsgmls on the output. OOOPPPSSS! Lots and lots
of warning, messages, and stuff.
About 60 minutes of futzing with silly stuff that was actually
caused by mistakes in the original (missing this, that and the
other) I got a parseable document.
So now I took a deep breath and rattle the keys:
/usr/local/bin/jade -ioutput.html -V nochunks \
-c /var/tmp/webuild/doc/en_US.ISO_8859-1/books/fdp-primer/../../../share/sgml/catalog \
-c /usr/local/share/sgml/docbook/dsssl/modular/catalog \
-c /usr/local/share/sgml/docbook/catalog \
-c /usr/local/share/sgml/jade/catalog \
-d /var/tmp/webuild/doc/en_US.ISO_8859-1/books/fdp-primer/../../share/sgml/freebsd.dsl \
-t sgml $(DOC).sgml > handbook.html
Error messages from HELL! Weird messages. STRANNNGE message.
Cross references to anchors? Sigh...
Back to the editor... typeity typeity type type type type...
far into the afternoon.
6. The Patch and Fix Process - Fri Jun 9
Bright and early here, sitting at the terminal, and armed with
fresh coffee, I prepare to hit the DocBook Trail again.
OK, before I edit the document again, why not read some documentation?
I reread the http://nwalsh.com/docbook/dsssl/ stuff that Norm
Walsh had published. I reread the freebsd.dsl file - you know, this
is starting to make sense. Then I reread the DocBook - The Extremely
Vague Answer to Life, The Universe, and Formatting, Part 1.
This time stuff was starting to make sense, and I was getting a
better handle on the model used. Just for fun, here is what,
at this point, my understanding is. Now remember, this is based
on only reading the aformentioned (run THAT through your spell checker)
documents.
a) The 'markup' used is very very simple- you have
a set of elements with attributes that you use
to create a parse tree. Any resemblance between
this and LISP is coincidental, and get your mind
out of the gutter. We use '<xx>' and '</xx>' not
'(' and ')' close, and we match the '<xx>' to '</xx>'
and not like LISP. Right. Sure. Tell me another one.
OK OK, if you insist. Like SCHEME. Not LISP.
b) Parsing is simply the matter of building a tree (or
even a DAG I suspect), each node of which corresponds
to an 'element' object, and which can have sub-nodes.
Also, each node can be 'decorated' with 'attributes'
which are assigned to it.
The SMGL parsing rules simply say what and in what
order the subnodes may appear and what attribute
values must be present. Also, how deep the tree can
be and if some 'element' types can be in the subtree.
(This sure looks like something that would appear as
'An Advanced Exercise' in Ableson and Sussman...
I note that there are a set of tools that build
trees and forests from XML and SGML^H^H^H^HDocBook
source, but I digress... Interesting...)
c) Now we get to the really interesting stuff - generating
the actual 'readable output'.
The DSSSL (Document Style Semantics and Specification
Language) carry the walking and decoration onto another level.
The DSSSL lanaguage appears to be a way to define how to
'walk' the tree, decorating each node with information.
The 'decorated nodes' would then be used to generate output.
The DocBook DSSSL Stylesheet is then simply a specification
that is used by a 'tree walker' to do the decoration,
and then the flattening/conversion to an output stream.
I think this is kinda neat. Now, of course, there is NO
relationship between this methodology and the way that some
optimizing compilers work. Right! That is exactly what most
of them do, they build up a tree of syntax nodes, decorate
them with 'code to be emitted' and then 'string the code
together' and produce the output file. Again, the similarities
of the two methodologies are interesting.
This starts looking more and more understandable.
Lets go back to the mystery stuff that I read before:
> Jade determines the system identifier for the DSSSL specification
> as follows:
>
> 1.If the -d option is specified, it will use the argument as
> the system identifier.
>
Cool. This is the purpose of the -d flag... Now I know.
This allows me to specify the Style Sheet, say, docbook.dsl,
or even papowell.dsl
> 3. Otherwise, it will use the system identifier of the document
> with any extension changed to .dsl.
Hey, that means I can put my own DSSSL stylesheet in place,
and have it contain the stuff I want on a per document basis.
Nice idea.
7. The First Stuff Out - Sat Jun 10
OK, lets try out some ideas. Here is the first line of the
LPRng.sgml
<!DOCTYPE book PUBLIC
"-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"
[
<!ENTITY LPRng "LPRng">
]>
Here is the Makefile I am using:
CATALOGS= \
-c /var/tmp/webuild/doc/share/sgml/catalog \
-c /usr/local/share/sgml/docbook/dsssl/modular/catalog \
-c /usr/local/share/sgml/docbook/catalog \
-c /usr/local/share/sgml/jade/catalog
html:
/usr/local/bin/jade -ioutput.html -V nochunks \
-d /var/tmp/webuild/doc/share/sgml/freebsd.dsl \
$(CATALOGS) \
-t sgml LPRng.sgml > LPRng.html
check:
#nsgmls -sv -f handbook.errs handbook.sgml
nsgmls -sv $(CATALOGS) LPRng.sgml
clean:
rm -f LPRng.html LPRng.errs *.htm
I spent the rest of the day editing the LPRng.sgml file,
reading the freebsd.dsl and freebsd.dtd files and their
little friends, and fixing up the formatting in the LPRng.sgml
file.
8. Do I Understand This Stuff - Sun Jun 11
Right. Here it is Sunday, and I am sitting at home, armed with
my network connection and lots of sloth.
Lets if I now understand what is happening. I will walk through
the various parts of files and commands that I am using to generate
the HTML output.
Here is the header of my LPRng.sgml file:
<!DOCTYPE book PUBLIC
"-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"
[
<!ENTITY LPRng "LPRng">
]>
Now lets see if we can find out what catalog the PID for the DTD
is defined in (gAHHH... I am starting to use the jargon). The #
is used to indicate file contents. I have removed whitespace and
some 'filler' comments.
/var/tmp/webuild/doc/share/sgml/catalog
# -- ...................................................................... --
# -- FreeBSD SGML Public Identifiers ...................................... --
# -- Language neutral ..................................................... --
# -- These identifiers are shared across all translations of the FreeBSD
# documentation, even though the listed language is "EN"
# --
# PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" "freebsd.dtd"
# PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" "man-refs.ent"
# -- These identifiers should only be used by English language versions of
# the FreeBSD Documentation.
# All other translations should base their FPIs on these, but change the
# final parameter in the FPI to represent the target language, as
# appropriate. Do not change the rest of the FPI
# --
# PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN"
# "../../en_US.ISO_8859-1/share/sgml/bookinfo.ent"
# PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"
# "../../en_US.ISO_8859-1/books/handbook/authors.ent"
Now if I understand this:
The "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" means
I use the the freebsd.dtd file.
--- OK - this will be DTD stuff, I understand this now.
The "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" means
I use the "man-refs.ent" file.
--- OK - this is proably a set of entities that we can use.
Lets take a little peek:
more /var/tmp/webuild/doc/share/sgml/man-refs.ent
<!ENTITY man.at.1 "<citerefentry/<refentrytitle/at/<manvolnum/1//">
<!ENTITY man.awk.1 "<citerefentry/<refentrytitle/awk/<manvolnum/1//">
....
Bingo! It looks like we are doing better now. And also I like
the sneaky way that the <citerefentry/ stuff is done... :-)
I grep through the FDP.sgml (ok, the 'book.sgml')
file and pull out this:
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
OOOHHH... I understand this! We are going to define
an ENTITY (% -> parameter entity), with the name 'man' and using
Formal Public Identifier (PUBLIC indicates this) "-../EN".
This now allows us to use the entity. We do this with '%man;' which
is the way that we get the entity definition file processed by the
parser.
Ummm... This is really not as bad as I thought.
Now lets move on to see what the freebsd.dtd file contains.
I have removed a bunch of whitespace and 'filler' comments.
/var/tmp/webuild/doc/share/sgml/freebsd.dtd
# <!-- FreeBSD Documentation Project, Extended DocBook DTD
# This DTD builds upon the DocBook 3.1 DTD. It extends it in order to
# add some new elements.
# The comment style and section headings are drawn from the DocBook DTD.
# The FPI for this DTD is "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"
# -->
# <!ENTITY % output.html "IGNORE"> <!-- HTML output is being generated -->
# <!ENTITY % output.print "IGNORE"> <!-- Print output is being generated -->
# <!ENTITY % local.list.class "|FAQList">
# <!ENTITY % local.tech.char.class "|HostID|Username|Devicename|MakeTarget|MakeVar">
OK, we define some parameter entities. The 'output.html' and
'output.print' seem to be familiar... Yes, it appears in the
jade command:
/usr/local/bin/jade -ioutput.html -V nochunks
... [-i entity]
And after a bit of a search, we find that the nsgmls.htm file
in the jade distribution has the following:
-iname
Pretend that
<!ENTITY % name "INCLUDE">
occurs at the start of the document type declaration subset
in the SGML document entity. Since repeated definitions of
an entity are ignored, this definition will take precedence
over any other definitions of this entity in the document
type declaration. Multiple -i options are allowed. If the
SGML declaration replaces the reserved name INCLUDE then
the new reserved name will be the replacement text of the
entity. Typically the document type declaration will contain
<!ENTITY % name "IGNORE">
and will use %name; in the status keyword specification of
a marked section declaration. In this case the effect of
the option will be to cause the marked section not to be
ignored.
So we see how we use -ioutput.html to set the %output.html to
INCLUDE and this will now include the stuff for generating HTML.
I we were to use -ioutput.print we would get the print
formatting stuff. Makes sense now.
Lets see what is in the rest of the file...
#
# <!-- OS Version attributes ...............................................
# Each element has three attributes which specify which version(s) of
# FreeBSD the element's content applies to. It is up to the
# pre-processor to include or exclude elements based on the value of
# these attributes. -->
# <!ENTITY % local.common.attrib
# "OSVersionMin CDATA #IMPLIED
# OSVersionMax CDATA #IMPLIED
# OSVersionIn CDATA #IMPLIED">
#
This looks evil. EVIL! Sigh... The things people will do to get around
missing stuff... So you are going to add some 'general attributes'
that allow you to set some OS versions... OK, I get this... sorta...
# <!-- Altered general entities ............................................
# The HTML 4.0 DTD includes some new ISO entities. Most browsers don't
# support them yet. Change the definition of some of these entities to
# character strings that the browsers will support.
# This does not apply when generating printed output, so these are
# contained within a %output.html; marked section.
# As browser technology improves, these definitions can be removed. -->
#
# <![ %output.html; [
# <!ENTITY ldquo "``">
# <!ENTITY rdquo "''">
# <!ENTITY lsquo "`">
# <!ENTITY rsquo "'">
# <!ENTITY mdash "--">
# <!ENTITY ndash "-">
# <!ENTITY hellip "...">
# <!ENTITY dollar "$">
# ]]>
Snicker.... Ohhh... the joys of moving target standards...
So you wanna use it but it is not there yet.
#
# <!-- Pull in the original DTD -->
# <!ENTITY % orig-docbook PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
# %orig-docbook;
And here is where we pull in the original stuff, and the previous
declarations get overridden.
#
# <!ELEMENT HostID - - ((%cptr.char.mix;)+)>
# <!ATTLIST HostID
# --
# Role: More specific information about this hostname.
# If not specified then the default is 'hostname'.
# --
# Role (Hostname
# |Domainname
# |FQDN
# |IPAddr
# |Netmask
# |MAC) #IMPLIED
# %common.attrib;
# >
Hmmm... this is interesting... so this is how we extend the DTD.
#
# <!ELEMENT Username - - ((%cptr.char.mix;)+)>
# <!ATTLIST Username
# %common.attrib;
# >
#
# <!ELEMENT Devicename - - ((%cptr.char.mix;)+)>
# <!ATTLIST Devicename
# %common.attrib;
# >
#
# <!ELEMENT MakeTarget - - ((%cptr.char.mix;)+)>
# <!ATTLIST MakeTarget
# %common.attrib;
# >
#
# <!ELEMENT MakeVar - - ((%cptr.char.mix;)+)>
# <!ATTLIST MakeVar
# %common.attrib;
# >
# <!ENTITY prompt.root "<prompt>#</prompt>">
# <!ENTITY prompt.user "<prompt>%</prompt>">
Looks simple NOW. OK, so we know what the DTD does.
Lets look at the DSSSL. I decided to start with this one:
/var/tmp/webuild/doc/en_US.ISO_8859-1/share/sgml/freebsd.dsl
# <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
# <!ENTITY freebsd.dsl SYSTEM "../../../share/sgml/freebsd.dsl" CDATA DSSSL>
# <!ENTITY % output.html "IGNORE">
# <!ENTITY % output.print "IGNORE">
# ]>
#
Been here before, and we see the 'output.html' strike again.
I noticed the CDATA DSSSL stuff, but it is not documented anywhere,
so I guess this is part of the DSSSL language specification.
# <style-sheet>
# <style-specification use="docbook">
# <style-specification-body>
#
# <![ %output.html; [
# (define ($email-footer$)
# (make sequence
# (literal "For questions about FreeBSD, e-mail <")
# (make element gi: "a"
# attributes: (list (list "href" "mailto:questions@FreeBSD.org"))
# (literal "questions@FreeBSD.org"))
# (literal ">.")
# (make empty-element gi: "br")
# (literal "For questions about this documentation, e-mail <")
# (make element gi: "a"
# attributes: (list (list "href" "mailto:doc@FreeBSD.org"))
# (literal "doc@FreeBSD.org"))
# (literal ">.")))
# ]]>
# </style-specification-body>
# </style-specification>
OK, we define an 'eamil-footer' decoration thing. The definition
looks kinda obvious. I reread the "DocBook - the Cure for Insomnia"
section on extending style sheets and this makes sense... but I
don't have the faintest idea what it DOES :-).
#
# <external-specification id="docbook" document="freebsd.dsl">
And now we drag the 'freebsd.dsl' in, from above
# </style-sheet>
And we are at the end. OK, lets get the 'freebsd.dsl':
"../../../share/sgml/freebsd.dsl"
/var/tmp/webuild/doc/share/sgml/freebsd.dsl
# <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
# <!ENTITY % output.html "IGNORE">
# <!ENTITY % output.print "IGNORE">
#
# <![ %output.html; [
# <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
# ]]>
# <![ %output.print; [
# <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
#
# ]]>
# ]>
OK. So if it is HTML we use James Clark's HTML style sheet,
otherwise we use the Print style sheet. Makes sense.
#
# <style-sheet>
# <style-specification use="docbook">
# <style-specification-body>
# <!-- HTML only .................................................... -->
# <![ %output.html; [
# <!-- Configure the stylesheet using documented variables -->
# (define %gentext-nav-use-tables%
# ;; Use tables to build the navigation headers and footers?
^^^ SCHEME comments? Right. I should have known...
# #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)
# (element segmentedlist
# (make element gi: "TABLE"
# (process-children)))
# (element seglistitem
# (make element gi: "TR"
# (process-children)))
# (element seg
# (make element gi: "TD"
# attributes: '(("VALIGN" "TOP"))
# (process-children)))
#
# <!-- The next two definitions control the appearance of an
# e-mail footer at the bottom of each page. -->
#
# <!-- This is the text to display at the bottom of each page.
# Defaults to nothing. The individual stylesheets should
# redefine this as necessary. -->
# (define ($email-footer$)
# (empty-sosofo))
Ohh... very clever. You define this in the other style sheet,
like we saw.
#
# <!-- This code handles displaying $email-footer$ at the bottom
# of each page.
#
# If "nuchunks" is turned on then we make sure that an <hr>
# is shown first.
Ummmm... do we mean 'nochunks' ? Sigh...
#
# Then create a centered paragraph ("<p>"), and reduce the font
# size ("<small>"). Then run $email-footer$, which should
# create the text and links as necessary. -->
# (define ($html-body-end$)
# (if (equal? $email-footer$ (normalize ""))
# (empty-sosofo)
..... Boring stuff deleted
#
# </style-specification-body>
# </style-specification>
#
# <external-specification id="docbook" document="docbook.dsl">
And now we do the 'drag in another stylesheet' trick...
# </style-sheet>
OK. So we could copy this and define our own style sheets.
I copied the freebsd.dtd to LPRng-HOWTO.dtd, and the
freebsd.dsl to LPRng-HOWTO.dsl.
Here is the Makefile after we copy this stuff, and our
header from LPRng.sgml:
<!DOCTYPE book
SYSTEM "LPRng-HOWTO.dtd"
-- PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" --
-- PUBLIC "-//OASIS//DTD DocBook V3.1//EN" --
[
<!ENTITY LPRng "LPRng">
]>
# CATALOGS= \
# -c /usr/local/share/sgml/catalog \
# -c /usr/local/share/sgml/docbook/dsssl/modular/catalog
# LPRng-HOWTO.html: LPRng-HOWTO.sgml LPRng-HOWTO.dsl
# jade \
# -i output.html -V nochunks \
# $(CATALOGS) \
# -d LPRng-HOWTO.dsl \
# -t sgml \
# LPRng-HOWTO.sgml >LPRng-HOWTO.html
# check:
# #nsgmls -s -f handbook.errs handbook.sgml
# nsgmls -s $(CATALOGS) LPRng-HOWTO.sgml
#
# clean:
# rm -f LPRng.html LPRng.errs x*.htm c*.htm b*.htm
I ran this and it worked the first time. Produced identical
output as well...
Cool...
I spent the rest of Sunday fixing up various formats, and playing
with tables.
9. On to Special Effects Mon Jun 12
OK, I have the 'one big html file', how do I get the 'lots of
little html files?' I looked in the FDP Makefile and spotted:
FORMATS="html split-html"
Ummmm... it couldn't be that simple, could it? Well, it was.
make FORMATS=split-html
Sorta. You also need to have a 'manifest' file. Here is the
required steps.
# Makefile
CATALOGS= \
-c /usr/local/share/sgml/catalog \
-c /usr/local/share/sgml/docbook/dsssl/modular/catalog
index.html HTML.manifest: LPRng-HOWTO.sgml LPRng-HOWTO.dsl
jade -i output.html -V html-manifest $(CATALOGS) \
-d LPRng-HOWTO.dsl -t sgml LPRng-HOWTO.sgml
-tidy -i -m -f /dev/null ${TIDYFLAGS} `xargs < HTML.manifest`
ARGHHH!!! ARGHH!!! This produces a lot of files, one per section.
I wanted one per chapter. OK, perhaps this was not such a good idea.
Or perhaps there is a hidden mystery flag that will fix this
up, and be compatible with the old LinuxDoc convention.
OK, lets see what we can do with PostScript:
make FORMATS=ps
And we get the equivalent:
LPRng-HOWTO.ps:
jade -Vtex-backend -ioutput.print -t tex -o LPRng-HOWTO.tex \
$(CATALOGS) \
-d LPRng-HOWTO.dsl \
LPRng-HOWTO.sgml
### --- see the comments below ---
perl -spi -e 's/\000\000/5\\p\@/;' LPRng-HOWTO.tex
### ---
echo "==> TeX pass 1/3"
tex "&jadetex" LPRng-HOWTO.tex
echo "==> TeX pass 2/3"
tex "&jadetex" LPRng-HOWTO.tex
echo "==> TeX pass 3/3"
tex "&jadetex" LPRng-HOWTO.tex
dvips -o LPRng-HOWTO.ps LPRng-HOWTO.dvi
Now, what is that &*()(*& Perl Script doing here? The answer is:
BUG FIX! BUG FIX! The freebsd.dsl style sheet has some very odd
steps that cause two NULL (\000\000) characters to be put out into
the TeX file, instead of '5\p@'. I have been here before with
some conversion scripts and KNOW this one only too well.
10. Why Not DocBook 4.0? and the new DSSSL Style Sheets? Tue Jun 13
OK, I was feeling frisky now, I figured out what to do,
things were looking better.
So lets test ourselves: Get the latest DocBook 4.0 and upgrade
to the latest style sheet and see if it is backwards compatible.
If not, then fix stuff up RIGHT NOW to make sure.
http://www.oasis-open.org/docbook/sgml/4.0/
Get the zipped archive - docbk40.zip
mkdir 4.0; cd 4.0; unzip ../docbk40.zip
cp docbook.cat catalog
edit catalog and COMMENT OUT THE PUBLIC IDS that are not
non-4.0 release (I read the warnings in the readme)
cd ..
cp -r 4.0 /usr/local/share/sgml/docbook
cat /usr/local/share/sgml/docbook/catalog
CATALOG "2.4.1/catalog"
CATALOG "3.0/catalog"
CATALOG "3.1/catalog"
echo 'CATALOG "4.0/catalog"' >>/usr/local/share/sgml/docbook/catalog
vi some.test.document
change "-//OASIS//DTD DocBook V3.1//EN" to
"-//OASIS//DTD DocBook V4.0//EN"
nsgmls -s some.test.document
>>> get error message 'DTDDECL not supported'
This tells you it is dragging in the right DTD
vi /usr/local/share/sgml/docbook/4.0/catalog
and comment out the DTDDECL
and you are done... Easy!!! (Once you know how).
OK, now what about the style sheets?
http://nwalsh.com/docbook/dsssl/index.html
Download db154.zip, db154d.zip
unzip db154.zip
unzip db154d.zip
-> docbook/{all the stylesheet stuff}
Now it turns out that this stuff is stored in my distribution
in the /usr/local/share/sgml/docbook/dsssl/modular
directory. So I did the following for testing:
mv docbook docbook-1.54
cp -r docbook-1.54 /usr/local/share/sgml/docbook/dsssl
In my makefile I had a CATALOG entry:
CATALOGS= \
-c /usr/local/share/sgml/catalog \
-c /usr/local/share/sgml/docbook/dsssl/docbook-4.0/catalog
I changed this to
CATALOGS= \
-c /usr/local/share/sgml/catalog \
-c /usr/local/share/sgml/docbook/dsssl/docbook-1.54/catalog
I reran my tests AND they worked. Some of the output was
a bit different, but it LOOKED BETTER. Hmmm...
I had the following in the Makefile:
### --- see the comments below ---
perl -spi -e 's/\000\000/5\\p\@/;' LPRng-HOWTO.tex
### ---
I removed it and ran the tests again. This time tex did not
complain! Soooo... We have a nice new version installed.
Gee, I am getting better at this.
And at this point I am at a stop... or rather finish. The rest
seems to be simply tidying up and fighting with the DSSSL style
sheets, TeX, and other things to get a 'pretty' format.
Patrick ("Slick talking SGML salesmen... gRRRR...") Powell
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200006150149.SAA15926>