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.
Move the <?dbhtml filename="glossary"?> to its correct location after the
opening <glossary> tag; otherwise the index.html file gets named
glossary.html (oops!).
fop.extensions are no longer supported, deprecated
fop1.extensions are required when handling some of our documents
which contain all sorts of features; citations for choices are in the XSL
shade.verbatim is just to make FOP output look more like other LDP PDFs
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.)
adjust to generate a script which can be inspected before being run;
try to locate all HTML, single HTML, PDF and text files and report
on the 'not found' outputs
This is just to help during migration to the new content structure.
The LDP output tree has an inconsistent structure for handling documents of
different types. With the new processing tools, we will be able to produce
a single output directory for each source document. This script allows
the creation of links in the historical LDP output directory to the new
automatically created (and updated) directory.
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
Generating PDF outputs (today), requires using <mediaobject> and supplying a
file that can be converted into a print-consumable by the TeX engine.
I added .eps files (thank you, ImageMagick) to allow regeneration and also
added a file called 'image-missing' for the peculiar absence of a file
called OREILLY.BIND.DIAGRAM.
Below comment is reproduced in the doc-index.sgml, which
was generated using collateindex.pl and then hand-tuned into
valid DocBook SGML (version 3.1).
The stock collateindex.pl (md5=2e36626ed6709e5ba0e6af0999bc3102, in
dsssl-stylesheets-1.79) program makes a few mistakes in generating
the complex index below.
It creates a nesting problem for <secondaryie/> elements which contain
both a <ulink/> and have a subsequent <seeie/>. In that case, it
orphans the <ulink/> elements beneath the <seeie/> AFTER closing the
<secondaryie/>. I can't figure out a patch to collateindex.pl, so
hand-fixed the 5 entries and am committing this as is for TLDP.
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).
The qandaset had a defaultlabel="none" attribute. This is DocBook legal, but
the XSLT layer was producing FO output that included an empty
fo:list-item-label, with the following error message:
"fo:list-item-label" is missing child elements. Required content model:
marker* (%block;)+
By omitting the defaultlabel="none", the entire problem disappears.
Also, adjusted paths for reference to the ./Annimals/ which are now in
./resources/Annimals/.
The images were supplied here as a tarball, which meant that the DocBook
processor could not read them directly out of the version control system;
adding directories for the ./images/ and the ./resources/ (which contains
Annimals subdirectory and one chap4sec26 file.
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.
first, xsltproc (and friends) did not like the duplication of id="A" in both
the gloss.xml and index-gloss.xml; so renaming the IDs solved that problem
second, fop complained that empty gloss entries existed; no problem after
commenting them out