added a bunch of corrections for <itemizedlist/> <listitem/> and <para/>
nesting to match the DocBook content model more strictly; this allows full
validation of the document
the external general entities (files) which were getting pulled in already
contained a <programlisting/> element; this XML element was not necessary, but
the lack of an <areaspec/> inside the <programlistingco/> was giving xmllint
fits.
apparently, DocBook is quite picky about the order of children elements within
the <affiliation/> element; so rearranged; and also only one of <revremark/>
or <revdescription/> is (technically) allowed in a <revision/>, so I chose to
convert the <revremark/> elements to <remark/> and drop them inside of a
<revdescription/>, which allows much richer expression of content
the entire set of directories here had been checked in (in 2005) under
NCURSES-Programming-HOWTO; and has since been moved to a subdirectory,
NCURSES-Programming-HOWTO/resources
this is cruft and does not need to be here (there are even newer files in the
NCURSES-Programming-HOWTO/resources/ncurses_programs directory
Several <xref/> elements used the endterm attribute, which takes the entire
content contained in the element as replacement. Because the endterm was
also, for example, a <section/>, the replaced text was a gigantic (multi-page)
link with the whole section included. Unintended, I'm sure.
added a reference to bufferbloat
upgraded a few untagged text items to be wrapped with <command>, a few others
from <command> to the more appropriate <emphasis> or <constant>
added a FIXME for more description on enqueuing from userspace/network
Since the initial release of this document, there have been quite a few new
queuing disciplines added. Identify the ones for which there is no
documentation here.
It is not necessary to credit SecurePipe, Inc. in every single file,
especially since it was merely my employer and did not actually contribute
materially to the documentation. (As much as I appreciated the experience,
knowledge, role and professional growth.)
This document used an endterm in the wrong place and its presence was
confusing the heck out of the FO processor:
<xref endterm="partitiontable" linkend="partitiontable" />
The endterm="" attribute tells the DocBook processor to copy the content found
at the linkend inline. The problem is that the content at this particular
linkend was an entire table. This meant that the FO processor was receiving
an entire (DocBook) table (as FO, of course) and futilely trying to render it
inline.
Removing the endterm="partitiontable" allows the document to be processed by
FOP into a PDF.
Author contacted, responded quickly, provided the missing old files
and confirmed that it was acceptable to comment out the reference to
../openMosix-2.6-HOWTO/openMosix-2.6-HOWTO-content.sgml
Source available: https://github.com/KrisBuytaert/openmosix-howto
Author contacted, responded quickly, provided the missing old files
and confirmed that it was acceptable to comment out the reference to
../openMosix-2.6-HOWTO/openMosix-2.6-HOWTO-content.sgml
Source available: https://github.com/KrisBuytaert/openmosix-howto
The desired output formats can be tweaked by setting the value of the
parameter entities %output.print.png% (and friends) to "INCLUDE";
The document still needed a few corrections, namely the removal of two
extraneous </listitem> elements and a few <application/> and <acronym/>
elements that were in illegal locations (for example as a child of the
<contrib> element).
Using the HTTP variant of the system identifier; let the local DocBook
installation map that system identifier to the local filesystem for us.
Replacing two literal < with <.
The Template-Big-HOWTO.sgml contained references to images that were not
present in the VCS. I located green.gif and red.gif in the ancient Linux
Gazette materials and added them here, along with a few .eps files for print
outputs.
The markup in this document made plenty of references to elements that
post-date the DocBook 3.0 specification (e.g. <mediaobject/>).
Fortunately, with one or two minor corrections to the nesting of elements, the
newer revision of DocBook can validate the document.
The additional programs and content were stored in a directory called
ncurses_programs and were referred to in the document--the problem is that
only ./images/ were copied to the output tree, so HTML versions of the
document would fail in building AND the files would not be viewable.
Adjusted that be creating a ./resources/ directory along the same line
as the ./images/ directory. This can be changed, if desired, but this
allows for automated publication of the document. (Side benefit: this is
generalizable to all other TLDP documents.)
When generating a book (or article) index, the filename is index.sgml. Not an
issue with DocBook XML, only with the older tools which make several passes
over the input sources to create the index data (output as SGML in a file
called index.sgml) and then incorporate that into the final document.
removing extraneous and empty <author/>, non-validating <toc/>
replacing an <ulink/> with a mailto: with an <email/> element
stuffing an & in the url="" attribute value for a <ulink/>
document now validates
Though it is legal to define parameter entity substitutions in a
DTD's internal subset, you cannot actually use them there. It is only
legal to use a parameter entity substitution in an external subset.
See this:
https://www.w3.org/TR/1998/REC-xml-19980210#wfc-PEinInternalSubset
Therefore, for the XML-RPC-HOWTO, the %GoodStyleSheets; definition is
left uncommented, but the suppression of the alternate definition of
legal.notice is commented out.
Document validates and processes correctly, now, using the legal.notice
definition intended. N.B., there is no actual difference in the license
specified, just the markup used to communicate it.
first line of fdl.xml with XML text declaration was confusing xsltproc;
removed and things were fine, also removed commented out DOCTYPE declaration
used URI for DocBook 4.1.2 in system identifier in rpmupgrade.xml
commented out <xref endterm="xrefdemo" linked="xrefdemo" /> which was causing
a recursion error in the DocBook XSLT layer
document now validates and builds (except for PDF)
jade processor was very unhappy to have closing tags on <imagedata>;
removing them (which felt like violence) allowed the document to be
validated and processed
In his document build system, each script is cooked (wrapped in <![ CDATA []]>
during build process--this is elegant, but we are not calling his build
Makefile, so we need to store the cooked scripts in the source tree.
jade did not like trying to process <graphic/> elements where it could not
find the source images; also, it wanted the filename extension included (did
early DocBook SGML processing tools simply locate an image of the preferred
type?)
Georg Käfer had to become Georg Käfer for SGML, anyway; the
problem was not in the generation of HTML, but rather PDF output
through the tex engine
changing all <link xlink:href=""/> elements to <ulink url=""/>;
this document is DocBook 4.1.2, and the use of xlink:href="" instead of the
more general <ulink/> element was preventing proper processing of the
document (without making the processor aware of this particular namespace)
HOWTO can be processed now by a completely automated (xsltproc) toolchain.
Persnickety about the placement of <title/> elements in both the <appendix/>,
where it must come after the <appendixinfo/> and in the <sect1/>, which
requires a <title/>. Changes made to allow document validation.
OK, this one is just weird--order matters (!?); The <orgname/> child of
<affiliation/> needed to precede the <address/> child. The document
would not validate without this change. Seems very strange.
Wrapping a <caution/> in a <para/>, wrapping a bunch of <procedure/> elements
in <blockquote/> and correcting a bad xreflinkend attribute to xreflabel,
all to allow for validation.
upgrading entire document to DocBook V3.1 (from V3.0):
<!DOCTYPE Article PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
because the authors were using elements (e.g. <legalnotice/> and
<varname/>) that were not available in the earlier DocBook release
lots of <ULink/> nits because &65533; is not SGML friendly (?)
several <Email/> substitutions for <ULink> inline and a very
strange addition of <Affiliation/> just to allow the nesting of
<Address><Email/></Address>
A crapton of corrections; parser seems a bit more cantankerous, is requiring
closing </ListItem> entries; so I added them.
Also, corrected a few misplaced or missing </para> elements.
N.B. The canonical content seems to be hosted at git://repo.or.cz/lartc.git
corrected placement of one </para> which was foiling validation
(and also aligned some text visually)
<sect3/> became <sect2/> because they could not descend directly
from <sect1>
<comment/> becomes <remark/>
The following additional changes were made in DocBook V4.0: artheader was
renamed articleinfo; comment was renamed remark; docinfo was broken into a
set of other info elements; and bookbiblio, interfacedefinition, and
seriesinfo were removed.
http://www.docbook.org/tdg/en/html/ref-elements.html
<listitem/> cannot contain text directly; wrapping in <para/>
switching a few <orderedlist/> elements to <simplelist/> with <member/>
old element <docinfo/> has been renamed <appendixinfo/>
Any <listitem/> elements without <para/> got a new friend.
Replaced two <itemizedlist/> with <simplelist/>
Removed one spuriously hovering and extraneous '>'
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:443:11:E: value of attribute "id" invalid: "7" cannot start a name
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:468:12:E: document type does not allow element "procedure" here; missing one of "caution", "important", "note", "tip", "warning", "blockquote" start-tag
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:471:5:E: character data is not allowed here
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:472:8:E: end tag for "step" which is not finished
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:474:13:E: document type does not allow element "command" here; missing one of "remark", "title", "synopsis", "cmdsynopsis", "literallayout", "programlisting", "screen", "para", "simpara", "bridgehead" start-tag
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:475:8:E: end tag for "step" which is not finished
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:477:5:E: character data is not allowed here
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:477:52:E: document type does not allow element "command" here; missing one of "remark", "title", "synopsis", "cmdsynopsis", "literallayout", "programlisting", "screen", "para", "simpara", "bridgehead" start-tag
jade:LDP/LDP/howto/docbook/Athlon-Powersaving-HOWTO.xml:478:8:E: end tag for "step" which is not finished
Martin A. Brown