diff --git a/LDP/howto/docbook/DocBook-Demystification-HOWTO/DocBook-Demystification-HOWTO.xml b/LDP/howto/docbook/DocBook-Demystification-HOWTO/DocBook-Demystification-HOWTO.xml index 6dcbc60e..c8a7153d 100644 --- a/LDP/howto/docbook/DocBook-Demystification-HOWTO/DocBook-Demystification-HOWTO.xml +++ b/LDP/howto/docbook/DocBook-Demystification-HOWTO/DocBook-Demystification-HOWTO.xml @@ -3,6 +3,7 @@ "http://docbook.org/xml/4.1.2/docbookx.dtd" [ + ]>
@@ -20,11 +21,28 @@ + + v1.3 + 2004-02-27 + esr + + Add pointers to two editors. + + + + v1.2 + 2003-02-17 + esr + + Reorder to defer references to SGML until after it has been + introduced. + + v1.1 2002-10-01 esr - + Correct inadvertent misrepresentation of FSF's position. Added pointer to the DocBook FAQ. @@ -57,17 +75,15 @@ including the Linux kernel, GNOME, KDE, Samba, and the Linux Documentation Project. The advocates of XML-based "structural markup" (as opposed to the older style of "presentation markup" exemplified by troff, Tex, and Texinfo) seem to have won the theoretical -battle. +battle. You can generate presentation markup from structural markup, +but going in the other direction is very difficult. Nevertheless, a lot of confusion surrounds DocBook and the programs that support it. Its devotees speak an argot that is dense and forbidding even by computer-science standards, slinging around acronyms that have no obvious relationship to the things you need to do to write markup and make HTML or Postscript from it. XML standards -and technical papers are notoriously obscure. Most DocBook-related -tools are very poorly documented, and their documentation is -especially prone to assume way too much prior knowledge on the -reader's part. +and technical papers are notoriously obscure. This HOWTO will attempt to clear up the major mysteries surrounding DocBook and its application to open-source documentation @@ -98,13 +114,13 @@ system is one rich, searchable, cross-indexed and hyperlinked database (rather than being scattered across several different formats in multiple locations as it is now). -Ideally, whenever you install a software package on your machine +Ideally, whenever you install a software package on your machine it would register its DocBook documentation into your system's -catalog. HTML, properly indexed and cross-linked to the HTML in the +catalog. HTML, properly indexed and cross-linked to the HTML in the rest of your catalog, would be generated. The new package's -documentation would then be available through your browser. All -your documentation would would be searchable through an interface -resembling a good Web search engine. +documentation would then be available through your browser. All your +documentation would be searchable through an interface resembling a +good Web search engine. HTML itself is not quite rich enough a format to get us to that world. To name just one lack, you can't explicitly declare index @@ -116,10 +132,11 @@ that's why so many projects are adopting it. find it unpleasantly heavyweight, and too verbose to be really comfortable as a composition format. That's OK; as long as the markup tools they like (things like Perl POD or GNU Texinfo) can generate -DocBook out their back ends, we can all still get we want. It doesn't -matter whether or not everybody writes in DocBook — as long as -it becomes the common document interchange format that everyone uses, -we'll still get unified searchable documentation databases. +DocBook out their back ends, we can all still get what we want. It +doesn't matter whether or not everybody writes in DocBook — as +long as it becomes the common document interchange format that +everyone uses, we'll still get unified searchable documentation +databases. Structural markup: a primer @@ -174,7 +191,7 @@ instructions to your formatter. final document would be controlled by a stylesheet stylesheet. It is the stylesheet that would tell the formatter "render emphasis as a font -change to boldface". One advantage of presentation-markup languages +change to boldface". One advantage of structural-markup languages is that by changing a stylesheet you can globally change the presentation of the document (to use different fonts, for example) without having to hack all the the individual instances of (say) @@ -185,8 +202,8 @@ without having to hack all the the individual instances of (say) (Note: to keep the explanation simple, most of this section is going to tell some lies, mainly by omitting a lot of -history. Truthfulness will be fully restored in a following -section.) +history. Truthfulness will be fully restored in a +following section.) DocBook is a structural-level markup language. Specifically, it is a dialect of XML. A DocBook document is a hunk of XML that uses @@ -215,7 +232,7 @@ first step is to pass it through a validating parser (the front end of the DocBook formatter). This program checks your document against the DocBook DTD to make sure you aren't breaking any of the DTD's structural rules (otherwise the back end of the formatter, the part -that applies your style sheet, might become quite confused) +that applies your style sheet, might become quite confused). The validating parser will either bomb out, giving you error messages about places where the document structure is broken, or translate @@ -262,12 +279,16 @@ there. The DocBook toolchain +The easiest way to format and render XML-DocBook documents is to +use the xmlto toolchain. This ships with +Red Hat; Debian users can get it with the command apt-get +install xmlto. + Normally, what you'll do to make XHTML from your DocBook sources will look like this: bash$ xmlto xhtml foo.xml -Convert to XHTML bash$ ls *.html ar01s02.html ar01s03.html ar01s04.html index.html @@ -278,7 +299,6 @@ index page and two parts. Making one big page is just as easy: bash$ xmlto xhtml-nochunks foo.xml -Convert to XHTML bash$ ls *.html foo.html @@ -287,14 +307,13 @@ foo.html bash$ xmlto ps foo.xml # To make Postscript -Convert to XSL-FO -Making portrait pages on A4 paper (210mmx297mm) -Post-process XSL-FO to DVI -Post-process DVI to PS bash$ ls *.ps foo.ps +Some older versions of xmlto may be +more verbose, emitting noise like "Coverting to XHTML" and so forth. + To turn your documents into HTML or Postscript, you need an engine that can apply the combination of DocBook DTD and a suitable stylesheet to your document. Here is how the @@ -302,18 +321,21 @@ open-source tools for doing this fit together: + + Present-day XML-DocBook toolchain + Parsing your document and applying the stylesheet transformation will be handled by one of three programs. The most likely one is xsltprocxsltproc, -the parser that ships with Red Hat 7.3. The other possibilities are -two Java programs, +the parser that ships with Red Hat 7.3 and later versions. The other +possibilities are two Java programs, SaxonSaxon and XalanXalan, -It is relatively easy to generate high-quality XHTML from either +It is relatively easy to generate high-quality XHTML from DocBook; the fact that XHTML is simply another XML DTD helps a lot. Translation to HTML is done by applying a rather simple stylesheet, and that's the end of the story. RTF is also simple to generate in @@ -322,9 +344,9 @@ text approximation in a pinch. The awkward case is print. Generating high-quality printed output (which means, in practice, Adobe's -PDFPDF -(Portable Document Format) is difficult. Doing it right requires -algorithmically duplicating the delicate judgments of a human +PDFPDF or Portable Document +Format, a packaged form of PostScript) is difficult. Doing it right +requires algorithmically duplicating the delicate judgments of a human typesetter moving from content to presentation level. So, first, a stylesheet translates Docbook's structural markup @@ -369,14 +391,17 @@ with rough edges and missing features. + +Future XML-DocBook toolchain with FOP. + FOP has competition. There is another project called xsl-fo-procxsl-fo-proc which aims to do the same things as FOP, but in C++ (and therefore both faster than Java and not relying on the Java environment). As of -August 2002 FOP is in an unfinished alpha state, not as far along as -FOP. +August 2002 xsl-fo-proc is in an unfinished +alpha state, not as far along as FOP. Who are the projects and the players? @@ -385,24 +410,9 @@ FOP. Committee, headed by Norman Walsh. Norm is the principal author of the DocBook stylesheets, a man who has focused remarkable energy and talent over many years on the extremely complex problems DocBook -addresses. He is as universally respected in the DocBook/SGML/XML +addresses. He is as universally respected in the DocBook community as Linus Torvalds is in the Linux world. -The -docbook-tools project provides open-source tools for -converting SGML DocBook to HTML, Postscript, and other formats. This -package is shipped with Red Hat and other Linux distributions. It is -maintained by Mark Galassi. - -Jade is an -engine used to apply DSSSL stylesheets to SGML documents. It is -maintained by James Clark. - -OpenJade -is a community project undertaken because the founders thought James -Clark's maintainance of Jade was spotty. The docbook-tools programs -use OpenJade. - libxslt is a C library that interprets XSLT, applying stylesheets to XML documents. It includes a wrapper program, xsltproc, that can be @@ -421,14 +431,6 @@ programs that interpret XSLT. Saxon seems to be designed to work under Windows. Xalan is part of the XML Apache project and native to Linux and BSD; it's designed to work with FOP. -PassiveTeX the -package of LaTeX macros that xmlto uses for -producing DVI from XML-DocBook. JadeTex is the package -of LaTeX macros that OpenJade uses for producing DVI from -SGML-DocBook. - FOP translates XML Formatting Objects to PDF. It is part of the Apache XML project and is designed to work with Xalan. @@ -438,9 +440,9 @@ and is designed to work with Xalan. The second biggest problem with DocBook is the effort needed to convert old-style presentation markup to DocBook markup. Human beings -can usually parse the presentatition of a document into logical +can usually parse the presentation of a document into logical structure automatically, because (for example) they can tell from -context when an italic font means `emphasis' and when it meabs +context when an italic font means `emphasis' and when it means something else such as `this is a foreign phrase'. Somehow, in converting documents to DocBook, those @@ -460,9 +462,10 @@ various other formats: support DocBook as an interchange format. Texinfo has enough structure to make reasonably good automatic conversion possible, and the 4.x versions of makeinfo feature a - switch that generates DocBook. More at the -makeinfo -project page. + switch that generates DocBook. +More at the makeinfo project +page. @@ -472,7 +475,7 @@ project page. There is a POD::DocBook module that translates Plain Old Documentation markup to DocBook. It -claims to support every DocBook tag except the L<> italic tag. +claims to translate every POD tag except the L<> italic tag. The man page also says "Nested =over/=back lists are not supported within DocBook." but notes that the module has been heavily tested. @@ -507,7 +510,7 @@ features for automatic translation to get some traction. I wrote a tool to do this myself, because I couldn't find anything else that did a half-decent job of it (and the problem is interesting). It's called doclifter. It will +url="&home;/doclifter/">doclifter. It will translate to either SGML or XML DocBook from man 7, @@ -528,6 +531,15 @@ for details. One thing we presently do not have is a good open-source structure editor for SGML/XML documents. +The Conglomerate project +aims specifically at producing a good DocBook editor. As of early +2004 it is stilll alpha software. + +The MlView +project is an XML editor, not specifically DocBook targeted. As of +early 2004 it lacks documentation and appears to be in alpha. + LyX is a GUI word processor that uses LaTeX for printing and supports structural editing of LaTeX markup. There is a LaTeX package that generates DocBook, and a @@ -550,11 +562,21 @@ the future, but it's not there yet. ThotBook is a project to put together a GUI editor for DocBook based on -the Thot toolkit. It way be moribund; the web page was not updated +the Thot toolkit. It may be moribund; the web page was not updated from November 2001 to August 2002 (time of writing). -Most people still hack the tags by hand using either vi or Emacs, using -psgml to validate the results. +Most people still hack the tags by hand using either vi or emacs. + + +Hints and tricks + +It is possible to generate an index by including an empty +<index/> tag at the point in your document where you wish +it to appear. Be warned that, as of early 2004, this facility is +still somewhat primitive. It won't merge ranges, and the output +generated for PostScript is not yet production-quality. + +This space is reserved for more hints and tricks. Related standards and practices @@ -570,18 +592,18 @@ cataloguing and metadata. url="http://scrollkeeper.sourceforge.net/">Scrollkeeper project aims directly to meet this need. It provides a simple set of script hooks that can be used by package install and uninstall -productions to register and unregister their documentation. +productions to register and unregister their documentation into and +out of a shared, searchable system-wide database. Scrollkeeper uses the Open Metadata Format. +url="http://www.ibiblio.org/osrt/omf/">Open Metadata Format. This is a standard for indexing open-source documentation analogous to a library card-catalog system. The idea is to support rich search facilities that use the card-catalog metadata as well as the source text of the documentation itself. - -SGML and SGML-Tools +SGML and SGML-Tools In previous sections, I have thrown away a lot of DocBook's history. XML has an older brother, @@ -591,10 +613,11 @@ Markup Language. Until mid-2002, no discussion of DocBook would have been complete without a long excursion into SGML, the differences between SGML and XML, and detailed descriptions of the SGML DocBook toolchain. -Life can be simpler now; a XML DocBook toolchain is available in open -source, works as well as the SGML toolchain ever did, and is easier to -use, If you don't think you'll ever have to deal with old SGML-Docbook -documents, you can skip the remainder of this section. +Life can be simpler now; an XML DocBook toolchain is available in open +source, works as well as the SGML toolchain ever did, and is much +easier to use. If you don't think you'll ever have to deal with old +SGML-Docbook documents, you can skip the remainder of this +section. DocBook SGML @@ -627,17 +650,42 @@ correct version: The DSSSL toolchain is what processed DocBook SGML. Under it, a document goes from DocBook format through one of two closely-related stylesheet engines called Jade and OpenJade. These -turn it into a TeX-macro markup. which is processed by a package called +turn it into a TeX-macro markup, which is processed by a package called JadeTeX, into DVIs, which then get turned into Postscript. - + +SGML tools + +The +docbook-tools project provides open-source tools for +converting SGML DocBook to HTML, Postscript, and other formats. This +package is shipped with Red Hat and other Linux distributions. It is +maintained by Mark Galassi. + +Jade is an +engine used to apply DSSSL stylesheets to SGML documents. It is +maintained by James Clark. + +OpenJade +is a community project undertaken because the founders thought James +Clark's maintainance of Jade was spotty. The docbook-tools programs +use OpenJade. + +PassiveTeX the +package of LaTeX macros that xmlto uses for +producing DVI from XML-DocBook. JadeTex is the package +of LaTeX macros that OpenJade uses for producing DVI from +SGML-DocBook. + + Why SGML DocBook is dead The DSSSL toolchain is, as far as new development goes, -effectively dead. The XSLT toolchain has just reached production -status as I write in August 2002; a working version shipped in Red Hat -7.3. It's where DocBook developers are putting almost all of their -effort. +effectively dead. The XSLT toolchain has reached production status in +mid-2002; a working version shipped in Red Hat 7.3. It's where +DocBook developers are putting almost all of their effort. The reason for the change to XML was threefold. First, SGML turned out to be too complicated to use; then, DSSSL turned out @@ -667,10 +715,10 @@ write and modify. (It was a dialect of Scheme. Your humble editor, a LISP-head from way back, shakes his head in sad bemusement that this should drive people away.) -XML fans like to sum up all these changes with "XML: tastes great, less -filling." - +XML fans like to sum up all these changes with XML: +tastes great, less filling. + SGML-Tools SGML-Tools was the name of a DTD used by the is still maintained. The LDP has been phasing out SGML-Tools in favor of DocBook, but it is still possible you might take over an old HOWTO. These can be -regognized by the identifying header "<!doctype linuxdoc -system>. If this happens to you, convert the thing to XML DocBook +recognized by the identifying header "<!doctype linuxdoc +system>". If this happens to you, convert the thing to XML DocBook and give the old version a quick burial. @@ -694,7 +742,7 @@ and give the old version a quick burial. One of the things that makes learning DocBook difficult is that the sites related to it tend to overwhelm the newbie with long lists -of W3C standards, massive exercises in SGML theology, and dense +of W3C standards, massive exercises in markup theology, and dense thickets of abstract terminology. We're going to try to avoid that here by giving you just a few selected references to look at. @@ -729,8 +777,9 @@ url="http://vig.pearsoned.com/store/product/0,,store-562_banner-0_isbn-013642299 XML Documents (Prentice-Hall, ISBN: 0-13-642299-3). For XML only, XML In A Nutshell -by W. Scott Means and Elliotte "Rusty" Harold is very good. +url="http://www.oreilly.com/catalog/xmlnut2/">XML In A +Nutshell by W. Scott Means and Elliotte Rusty +Harold is very good. The XML Bible looks like a pretty comprehensive reference on XML and diff --git a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure1.png b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure1.png index 26584957..4f2b92ce 100644 Binary files a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure1.png and b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure1.png differ diff --git a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure2.png b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure2.png index 7f0f2e28..b43758d4 100644 Binary files a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure2.png and b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure2.png differ diff --git a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure3.png b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure3.png index 14dbfb6b..af5e8d3e 100644 Binary files a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure3.png and b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure3.png differ diff --git a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure4.png b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure4.png index 1232c5b0..b2f43879 100644 Binary files a/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure4.png and b/LDP/howto/docbook/DocBook-Demystification-HOWTO/figure4.png differ diff --git a/LDP/howto/docbook/HOWTO-INDEX/howtoChap.sgml b/LDP/howto/docbook/HOWTO-INDEX/howtoChap.sgml index 6b740101..5b8cc5c2 100644 --- a/LDP/howto/docbook/HOWTO-INDEX/howtoChap.sgml +++ b/LDP/howto/docbook/HOWTO-INDEX/howtoChap.sgml @@ -1123,7 +1123,7 @@ How to become a totally "small time" DNS admin. DocBook-Demystification-HOWTO, DocBook Demystification HOWTO -Updated: Oct 2002. +Updated: Feb 2004. Attempts to clear the fog and mystery surrounding the DocBook markup system and the tools that go with it. @@ -2058,7 +2058,7 @@ under Linux. K7s5a-HOWTO, The Elite's K7s5a mainboard HOWTO -Updated: Jan 2004. +Updated: Feb 2004. Describes how to use Elite's K7s5a board with Linux. @@ -2309,7 +2309,7 @@ This HOWTO has been removed for review. Linksys-Blue-Box-Router-HOWTO, Linksys Blue Box Router HOWTO -Updated: Jul 2003. +Updated: Feb 2004. Hints and tips for managing Linksys routers from a Linux system, including the firmware upgrade procedure. diff --git a/LDP/howto/docbook/HOWTO-INDEX/hwSect.sgml b/LDP/howto/docbook/HOWTO-INDEX/hwSect.sgml index 4585be0f..f0ae2054 100644 --- a/LDP/howto/docbook/HOWTO-INDEX/hwSect.sgml +++ b/LDP/howto/docbook/HOWTO-INDEX/hwSect.sgml @@ -475,7 +475,7 @@ This HOWTO has been removed for review. K7s5a-HOWTO, The Elite's K7s5a mainboard HOWTO -Updated: Jan 2004. +Updated: Feb 2004. Describes how to use Elite's K7s5a board with Linux. @@ -1148,7 +1148,7 @@ scanner device on a system running Linux. Linksys-Blue-Box-Router-HOWTO, Linksys Blue Box Router HOWTO -Updated: Jul 2003. +Updated: Feb 2004. Hints and tips for managing Linksys routers from a Linux system, including the firmware upgrade procedure. diff --git a/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml b/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml index 0dbdb600..f1825d39 100644 --- a/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml +++ b/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml @@ -22,7 +22,7 @@ Topics covered in this section include: DocBook-Demystification-HOWTO, DocBook Demystification HOWTO -Updated: Oct 2002. +Updated: Feb 2004. Attempts to clear the fog and mystery surrounding the DocBook markup system and the tools that go with it. diff --git a/LDP/howto/docbook/HOWTO-INDEX/networkingSect.sgml b/LDP/howto/docbook/HOWTO-INDEX/networkingSect.sgml index 55e84016..ab547a17 100644 --- a/LDP/howto/docbook/HOWTO-INDEX/networkingSect.sgml +++ b/LDP/howto/docbook/HOWTO-INDEX/networkingSect.sgml @@ -984,7 +984,7 @@ How to enable the Linux IP Masquerade feature on a given Linux host. Linksys-Blue-Box-Router-HOWTO, Linksys Blue Box Router HOWTO -Updated: Jul 2003. +Updated: Feb 2004. Hints and tips for managing Linksys routers from a Linux system, including the firmware upgrade procedure. diff --git a/LDP/howto/docbook/Linksys-Blue-Box-Router-HOWTO.xml b/LDP/howto/docbook/Linksys-Blue-Box-Router-HOWTO.xml index 3d0c7d2e..1054eae9 100644 --- a/LDP/howto/docbook/Linksys-Blue-Box-Router-HOWTO.xml +++ b/LDP/howto/docbook/Linksys-Blue-Box-Router-HOWTO.xml @@ -1,34 +1,3 @@ -From esr@snark.thyrsus.com Thu Feb 26 20:42:49 2004 -Received: by mail01.powweb.com (mbox 1061.gferg) (with Cubic Circle's - cucipop (v1.31 1998/05/13) Fri Feb 27 06:24:22 2004) -X-From_: submit-return-7753-gferg=fergusontechgroup.com@en.tldp.org Thu - Feb 26 17:50:17 2004 -Return-Path: -X-Original-To: gferg@fergusontechgroup.com -Delivered-To: 1061.gferg@mail01.powweb.com -Received: from gabber.metalab.unc.edu (gabber.metalab.unc.edu - [152.2.241.57]) by mail01.powweb.com (Postfix) with SMTP id 9F5D136A38 for - ; Thu, 26 Feb 2004 17:50:16 -0800 (PST) -Received: (qmail 31923 invoked by uid 1008); 27 Feb 2004 01:50:16 -0000 -Mailing-List: contact submit-help@en.tldp.org; run by ezmlm -Precedence: bulk -X-No-Archive: yes -List-Post: -List-Help: -List-Unsubscribe: - -List-Subscribe: -Delivered-To: mailing list submit@en.tldp.org -Received: (qmail 31915 invoked from network); 27 Feb 2004 01:50:15 -0000 -Date: Thu, 26 Feb 2004 20:42:49 -0500 -From: "Eric S. Raymond" -Message-Id: <200402270142.i1R1gnWK029547@snark.thyrsus.com> -To: submit@en.tldp.org -Subject: Linksys Blue Box Router HOWTO update -X-Evolution-Source: pop://1061.gferg@mail.fergusontechgroup.com -Mime-Version: 1.0 -Content-Transfer-Encoding: 8bit -
- - - ---------------------------------------------------------------------- -To unsubscribe, e-mail: submit-unsubscribe@en.tldp.org -For additional commands, e-mail: submit-help@en.tldp.org -