added a DocBook 5.0 declaration and, after failing validation with jing,
changed the anchor location to be inside the <firstname/> element.
Validates now!
(and restoring commit 78ec6080e6 which
suppresses the dbhtml PI for document naming)
Assembly-HOWTO.xml was written as a DocBook 5.0 document, however it sported a
declaration of a DocBook XML 4.5 document. This confused me and I changed all
of the <xlink:href/> elements to <ulink/> elements.
reverts commit 13943cb7fb
DocBook 4.x appears to be fairly picky about order in <author/> elements and
the document will not validate without the order being correct. Fixed.
Also, in the <revhistory/>, there were plenty of places where multiple
<revremark/> elements needed to be wrapped in a <revdescription/> along with a
bunch of <remark/> elements instead.
first, this is not XSL and in DocBook 4.x, these extra namespaces confuse the
processing toolchain (may be different in DocBook 5.x); next, xmllint refuses
to validate the document because of the order of elements in, for example the
<author/> elements and the <affiliation/> elements; just flipping these in
most cases did the trick
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
I don't know how this document ever validated before. There were countless
locations where there were extra </itemize> closing tags and tons of missing
<itemize> opening tags.
I tried not to do any violence to the nesting, but it was very difficult to
understand, given the ambiguity. The document now validates and can be built.
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
From: Rick Moen <rick@linuxmafia.com>
To: discuss@en.tldp.org
Subject: Linux User Group HOWTO v. 1.8.5 ready
Date: Thu, 25 Feb 2016 04:30:58
Good folks, I have a major revamp of HOWTO ready for the submission
process.
http://linuxmafia.com/lug/User-Group-HOWTO.sgml
This is Linuxdoc SGML, selected by original author Kendall Grant Clark
back in 1997. I've verified clean parsing of this revision.
HTML output here: http://linuxmafia.com/lug/User-Group-HOWTO.html
Licence has been modified slightly on this release from the prior
CC BY-SA 3.0, to CC BY-SA 4.0 (current revision). CC BY-SA is listed as
an accepted licence on http://wiki.tldp.org/LdpWikiDefaultLicence ,
and I doubt the revamped licence text would create any problme. (If
LDP has a problem with 4.0, I will back-rev that.)
I hope someone will do me the courtesy of picking up the SGML file and
feeding it into GitHub. Please advise. Thank you!
--
Cheers, QA engineer walks into a bar. Orders a beer.
Rick Moen Orders 0 beers. Orders 999999999 beers. Orders
rick@linuxmafia.com a lizard. Orders -1 beers. Orders a sfdeljknesv.
McQ! (4x80) -- @sempf, https://www.sempf.net/post/On-Testing1.aspx
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.
use terse format for table, which had all of the closing tags jammed at the
end of the </tabular>
correct nesting of <item> elements in many <enum> and <itemize> elements
fix a few <url> elements
remove the 50-car pileup of closing tags at the end of the document
all in order to quell validation errors
adding comment terminator --> where required
ordering the preliminary content in the required order, (title, author,
date, abstract, toc) in order to make the linuxdoc processor happier
nsgmls processor was complaining when trying to interpret an email
address as an element; just switched these to < and > and all
is well; also removed an extraneous trailing numeral '2' outside the document
structure
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.