This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
Slick Talking DocBook Salesman + diary
- To: docbook-apps at lists dot oasis-open dot org, papowell at astart dot com
- Subject: DOCBOOK-APPS: Slick Talking DocBook Salesman + diary
- From: papowell at astart dot com
- Date: Sun, 18 Jun 2000 12:31:51 -0700 (PDT)
- Cc: kevinmd at hsc dot edu, ndw at nwalsh dot com, nik at freebsd dot org
I previously posted to this list some questions. Here is the
reason for them.
In a follow on posting I have some additional questions and
comments.
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 21'st 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, directly a steely
glare into the eyes of the slick talking salesman.
"Yeah, any time, just send me eamil, 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 change 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) Hunted down examples
c) Push as far as I could
d) Beat on the authors/support 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... This 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.
3. Struggles with RTFM - Tue Jun 6
Yesterday I went home, sat in the Comfy Chair, and started reading
DocBook - the Definite Grunge...
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.
PUT SOME INSTRUCTIONS IN THE PRIMER ON HOW TO USE JADETEX!
(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
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.
/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...
6. The Patch and Fix Process - Fri Jun 9
OK, before I edit this 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, Chapters 1-3 again.
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 will note that there are a set of tools that build
trees and forests from the XML and SGML 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) sure does carry this on to another level.
It 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.
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 methodologies are interesting.
This starts looking more and more understandable.
Lets go back to the mystery stuff that I 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.
>
Cool. This is the purpose of the -d flag... Now I know.
> 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
and fixing up the formatting of various entries.
8. Do I Understand This Stuff - Sun Jun 11
Lets if I now understand what is happening. I will walk through
the various parts of the command 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 I just rip 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 now 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 get this define and will include the stuff for generating
HTML. I we were to use -ioutput.print we would get the print
formatting stuff. Makes sense now.
#
# <!-- 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...
# <!-- 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...
#
# <!-- 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. This looks kinda obvious.
#
# <external-specification id="docbook" document="freebsd.dsl">
And now we drag the 'freebsd.dsl' in, from above
# </style-sheet>
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)
# (make sequence
# (if nochunks
# (make empty-element gi: "hr")
# (empty-sosofo))
# (make element gi: "p"
# attributes: (list (list "align" "center"))
# (make element gi: "small"
# ($email-footer$))))))
# ]]>
#
# <!-- Print only ................................................... -->
# <![ %output.print; [
#
# ]]>
#
# <!-- Both sets of stylesheets ..................................... -->
#
# (define %section-autolabel% #t)
# (define %may-format-variablelist-as-table% #f)
# (define %indent-programlisting-lines% " ")
# (define %indent-screen-lines% " ")
# (define (article-titlepage-recto-elements)
# (list (normalize "title")
# (normalize "subtitle")
# (normalize "corpauthor")
# (normalize "authorgroup")
# (normalize "author")
# (normalize "releaseinfo")
# (normalize "copyright")
# (normalize "pubdate")
# (normalize "revhistory")
# (normalize "legalnotice")
# (normalize "abstract")))
# (element sgmltag ($mono-seq$
# (make sequence (literal "<") (process-children) (literal ">"))))
# <!-- John Fieber's 'instant' translation specification had
# '<command>' rendered in a mono-space font, and '<application>'
# rendered in bold.
# Norm's stylesheet doesn't do this (although '<command>' is
# rendered in bold).
# Configure the stylesheet to behave more like John's. -->
# (element command ($mono-seq$))
# (element application ($bold-seq$))
# <!-- Warnings and cautions are put in boxed tables to make them stand
# out. The same effect can be better achieved using CSS or similar,
# so have them treated the same as <important>, <note>, and <tip>
# -->
# (element warning ($admonition$))
# (element (warning title) (empty-sosofo))
# (element (warning para) ($admonpara$))
# (element (warning simpara) ($admonpara$))
# (element caution ($admonition$))
# (element (caution title) (empty-sosofo))
# (element (caution para) ($admonpara$))
# (element (caution simpara) ($admonpara$))
#
# (define en-warning-label-title-sep ": ")
# (define en-caution-label-title-sep ": ")
#
# <!-- Tell the stylesheet about our local customisations -->
#
# (element hostid ($mono-seq$))
# (element username ($mono-seq$))
# (element devicename ($mono-seq$))
# (element maketarget ($mono-seq$))
# (element makevar ($mono-seq$))
# (define (qanda-defaultlabel)
# (normalize "qanda"))
# <![ %output.html [
# (element question
# (let* ((chlist (children (current-node)))
# (firstch (node-list-first chlist))
# (restch (node-list-rest chlist)))
# (make element gi: "DIV"
# attributes: (list (list "CLASS" (gi)))
# (make element gi: "P"
# (make element gi: "BIG"
# (make element gi: "A"
# attributes: (list
# (list "NAME" (element-id)))
# (empty-sosofo))
# (make element gi: "B"
# (literal (question-answer-label
# (current-node)) " ")
# (process-node-list (children firstch)))))
# (process-node-list restch))))
# ]]>
#
# </style-specification-body>
# </style-specification>
#
# <external-specification id="docbook" document="docbook.dsl">
# </style-sheet>
OK. So we could copy this define our own style sheets.
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
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@'. Now you may ask how I know that
this is the right... the answer is that I don't and it appears to
be a bug.
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