Algorithms-HOWTO draft in broken Docbook

[Andrew P Moise <moise+@andrew.cmu.edu>]

  The summary: Docbook has me stumped, so I have no idea how badly I've
botched the sgml in the current draft, but I've posted the current
Algorithms-HOWTO at
http://www.contrib.andrew.cmu.edu/~moise/algorithms-howto.sgml, and I'm
looking for feedback.  If you fix the sgml into something that you can
render, send me the version that renders for you, and I'll use that as a
template until I get motivated enough to figure out how to do whatever
you did.  Also send me the HTML you render so I can post it and start
asking for feedback from outside ldp-discuss (which, I assume, contains
mostly people who already know this stuff).  UUencoded tarballs are
preferred; my mailer is a very old CMU homebrew job, and does not handle
attachments/MIME at all that I know of.
  The long version:
  Okay, so maybe I'm just not that bright or patient, but I've been
wrestling with jade (both the 1.2.1 Redhat RPM and the Openjade source
install) for over a day now, and I have yet to successfully render any
SGML.  My latest round of error messages is something akin to:

[chops@chops ldp]$ jade -t sgml -i html -d \
/usr/lib/sgml/stylesheets/ldp.dsl\#html algorithms-howto.sgml > /dev/null
jade:algorithms-howto.sgml:1:25:W: cannot generate system identifier for
document type "LINUXDOC"
jade:algorithms-howto.sgml:1:25:E: reference to entity "LINUXDOC" for
which no system identifier could be generated
jade:algorithms-howto.sgml:1:0: entity was defined here
jade:algorithms-howto.sgml:1:25:E: DTD did not contain element
declaration for document type name
jade:algorithms-howto.sgml:9:8:E: element "ARTICLE" undefined
jade:algorithms-howto.sgml:11:6:E: element "TITLE" undefined
jade:algorithms-howto.sgml:12:7:E: element "AUTHOR" undefined

Changing the doctype to <!doctype article PUBLIC "-//OASIS//DTD DocBook
V3.1//EN"> causes jade to lead off with:

[chops@chops ldp]$ jade -t sgml -i html -d \
/usr/lib/sgml/stylesheets/ldp.dsl\#html algorithms-howto.sgml > /dev/null
jade:/usr/lib/sgml/dbcent.mod:54:0:E: cannot open
"/usr/lib/sgml/iso-amsa.gml" (No such file or directory)    
jade:/usr/lib/sgml/dbcent.mod:61:0:E: cannot open
"/usr/lib/sgml/iso-amsb.gml" (No such file or directory)
jade:/usr/lib/sgml/dbcent.mod:68:0:E: cannot open
"/usr/lib/sgml/iso-amsc.gml" (No such file or directory)
... and many more ...

and then start bitching about my sgml, to wit:

jade:algorithms-howto.sgml:12:8:E: character data is not allowed here
jade:algorithms-howto.sgml:12:26:E: document type does not allow element
"EMAIL" here
jade:algorithms-howto.sgml:13:8:E: document type does not allow element
"PUBDATE" here
... and so on, for many lines.

  I'm trying to work from big-howto-template-ld.sgml and the Author's
Guide as much as possible, but no single reference tells me how to do
everything (environment variables, directory structure, doctype
configuration, sgml structure, jade arguments, etc.), and they all seem
to be inconsistent in the areas over which they overlap.  I've pretty
much been reduced to trying random combinations of recommendations from
different sources and making shit up.  Here's my catalog environment at
present:

[chops@chops ldp]$ echo $SGML_CATALOG_FILES
/usr/lib/sgml/docbook.cat:/usr/lib/sgml/dsssl.cat:/usr/lib/sgml/nwalsh-modular.
cat:/usr/lib/sgml/sgml-common.cat:/usr/lib/sgml/stylesheets.cat

  At present I'm using an RPM installation (docbook-3.1-5.noarch.rpm,
sgml-common-0.1-8.noarch.rpm, stylesheets-1.54.13rh-1.noarch.rpm, and
jade-1.2.1-10.i386.rpm, with ldp.dsl placed in /usr/lib/sgml/stylesheets
and modified as per
http://www.linuxdoc.org/LDP/LDP-Author-Guide/usingldpdsssl.html).  The
source I've been trying is available at
http://www.contrib.andrew.cmu.edu/~moise/algorithms-howto.sgml; I know
there are many, many things wrong with its sgml (and content), but they
don't seem serious enough to me to stop the renderer in its tracks.  If
you're willing to fix up the sgml into any format that renders and looks
decent on your machine, I would be ecstatic to scrap all this nonsense
and use your sgml as a template (be it Docbook or whatever) while I get
back to working on the goddamned content, and accept that I cannot
render any kind of sgml on my machine.  If you'd like to try to help me
with my Docbook setup, email me, but be warned that my patience with
RingTFM is pretty much at an end; I want to put files from specific
sources in specific directories, run specific commands and modify
specific files in specific ways, and give specific arguments to jade,
and I want it to work.  I'm running Mandrake 7.0, which uses the Redhat
directory structure.
  In the meantime, I'd appreciate any and all comments on the current
Algorithms-HOWTO draft, even if its sgml is still broken enough that
you'll have to read the source in emacs.  I recently noticed how much
farther I'd gone with it than I intended to before getting feedback, so
I stopped modifiying it at that very character to avoid worrying it any
farther into its current local maximum of quality.  I'd like to hold off
on modifying any of the content until someone can get it HTML-ized so
that I can start serving it as HTML and get a broad range of feedback
(the local maximum thing again), but if you see something obviously
horrible in it (such as that I've propagated a lie my teachers told me
about what algorithms certain common tools use), I'd like to know, and
any other feedback that comes to mind would probably start me thinking
in good directions. 


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org