mirror of https://github.com/tLDP/LDP
updated
This commit is contained in:
gferg
parent
074eb2f29f
commit
6bb0dd5562
|
|
@ -21,6 +21,31 @@
|
|||
</author>
|
||||
|
||||
<revhistory>
|
||||
<revision>
|
||||
<revnumber>v1.6</revnumber>
|
||||
<date>2010-09-14</date>
|
||||
<authorinitials>esr</authorinitials>
|
||||
<revremark>
|
||||
Major update. dblatex actually works for PDF production.
|
||||
Describe asciidoc.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.5</revnumber>
|
||||
<date>2006-10-13</date>
|
||||
<authorinitials>esr</authorinitials>
|
||||
<revremark>
|
||||
Major update. Getox seems to be dead, FOP a bit further along.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.4</revnumber>
|
||||
<date>2004-10-28</date>
|
||||
<authorinitials>esr</authorinitials>
|
||||
<revremark>
|
||||
Minor update and license change.
|
||||
</revremark>
|
||||
</revision>
|
||||
<revision>
|
||||
<revnumber>v1.3</revnumber>
|
||||
<date>2004-02-27</date>
|
||||
|
|
@ -57,6 +82,14 @@
|
|||
</revision>
|
||||
</revhistory>
|
||||
|
||||
<legalnotice>
|
||||
<title>Copyright</title>
|
||||
<para>Permission is granted to copy, distribute and/or modify
|
||||
this document under the terms of the
|
||||
<ulink url='http://creativecommons.org/licenses/by/2.0/'>Creative Commons Attribution License,</ulink>
|
||||
version 2.0.</para>
|
||||
</legalnotice>
|
||||
|
||||
<abstract><para>
|
||||
This HOWTO attempts to clear the fog and mystery surrounding the
|
||||
DocBook markup system and the tools that go with it. It is aimed at
|
||||
|
|
@ -131,11 +164,11 @@ that's why so many projects are adopting it.</para>
|
|||
<para>DocBook has the vices that go with its virtues. Some people
|
||||
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 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
|
||||
tools they like (things like asciidoc or Perl POD or GNU Texinfo) can
|
||||
generate 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.</para>
|
||||
|
||||
</sect1>
|
||||
|
|
@ -303,18 +336,18 @@ bash$ ls *.html
|
|||
foo.html
|
||||
</screen>
|
||||
|
||||
<para>Finally, here is how you make Postscript for printing:</para>
|
||||
<para>Finally, here is how you make PDF for printing:</para>
|
||||
|
||||
<screen>
|
||||
bash$ xmlto ps foo.xml # To make Postscript
|
||||
bash$ ls *.ps
|
||||
foo.ps
|
||||
bash$ dblatex foo.xml # To make PDF
|
||||
bash$ ls *.pdf
|
||||
foo.pdf
|
||||
</screen>
|
||||
|
||||
<para>Some older versions of <command>xmlto</command> may be
|
||||
more verbose, emitting noise like "Coverting to XHTML" and so forth.</para>
|
||||
more verbose, emitting noise like "Converting to XHTML" and so forth.</para>
|
||||
|
||||
<para>To turn your documents into HTML or Postscript, you need an
|
||||
<para>To turn your documents into HTML or PDF, you need an
|
||||
engine that can apply the combination of DocBook DTD and
|
||||
a suitable stylesheet to your document. Here is how the
|
||||
open-source tools for doing this fit together:</para>
|
||||
|
|
@ -328,8 +361,7 @@ open-source tools for doing this fit together:</para>
|
|||
|
||||
<para>Parsing your document and applying the stylesheet transformation
|
||||
will be handled by one of three programs. The most likely one is
|
||||
<application>xsltproc</application><indexterm><primary>xsltproc</primary></indexterm>,
|
||||
the parser that ships with Red Hat 7.3 and later versions. The other
|
||||
<application>xsltproc</application><indexterm><primary>xsltproc</primary></indexterm>. The other
|
||||
possibilities are two Java programs,
|
||||
<application>Saxon</application><indexterm><primary>Saxon</primary></indexterm>
|
||||
and
|
||||
|
|
@ -356,20 +388,22 @@ FO<indexterm><primary>FO</primary></indexterm>
|
|||
can think of it as a sort of XML functional equivalent of troff. It
|
||||
has to be translated to Postscript for packaging in a PDF.</para>
|
||||
|
||||
<para>In the toolchain shipped with Red Hat, this job is handled by a
|
||||
TeX macro package called
|
||||
<application>PassiveTeX</application><indexterm><primary>PassiveTeX</primary></indexterm>. It
|
||||
translates the formatting objects generated by
|
||||
<command>xsltproc</command> into Donald Knuth's TeX language. TeX was
|
||||
one of the earliest open-source projects, an old but powerful
|
||||
presentation-level formatting language much beloved of mathematicians
|
||||
(to whom it provides particulaly elaborate facilities for describing
|
||||
mathematical notation). TeX is also famously good at basic
|
||||
typesetting tasks like kerning, line filling, and hyphenating. TeX's
|
||||
output, in what's called DVI<indexterm><primary>DVI</primary></indexterm>
|
||||
(DeVice Independent) format, is then massaged into PDF.</para>
|
||||
<para>In the toolchain shipped with most present-day Linux
|
||||
distributions, this job is best handled by a program called
|
||||
<application>dblatex</application><indexterm><primary>dblatex</primary></indexterm>
|
||||
(this obsoletes the older passivetex package that previous versions of
|
||||
tis HOWTO described).</para>
|
||||
|
||||
<para>If you think this bucket chain of XML to Tex macros to DVI to
|
||||
<para><command>dblatex</command> translates the formatting objects
|
||||
generated by <command>xsltproc</command> into Donald Knuth's TeX
|
||||
language. TeX was one of the earliest open-source projects, an old
|
||||
but powerful presentation-level formatting language much beloved of
|
||||
mathematicians (to whom it provides particulaly elaborate facilities
|
||||
for describing mathematical notation). TeX is also famously good at
|
||||
basic typesetting tasks like kerning, line filling, and hyphenating.
|
||||
TeX's output is then massaged into PDF.</para>
|
||||
|
||||
<para>If you think this bucket chain of XML to Tex macros to
|
||||
PDF sounds like an awkward kludge, you're right. It clanks, it
|
||||
wheezes, and it has ugly warts. Fonts are a significant problem,
|
||||
since XML and TeX and PDF have very different models of how fonts
|
||||
|
|
@ -377,15 +411,16 @@ work; also, handling internationalization and localization is a
|
|||
nightmare. About the only thing this code path has going for it is
|
||||
that it works.</para>
|
||||
|
||||
<para>The elegant way will be
|
||||
FOP<indexterm><primary>FOP</primary></indexterm>, a direct
|
||||
<para>The elegant way will be <ulink
|
||||
url="http://xmlgraphics.apache.org/fop/">
|
||||
FOP</ulink><indexterm><primary>FOP</primary></indexterm>, a direct
|
||||
FO-to-Postscript translator being developed by the Apache project.
|
||||
With FOP, the internationalization problem is, if not solved, at least
|
||||
well confined; XML tools handle Unicode all the way through to FOP.
|
||||
Glyph to font mapping is also strictly FOP's problem. The only
|
||||
trouble with this approach is that it doesn't work — yet. As of
|
||||
August 2002 FOP is in an unfinished alpha state — usable, but
|
||||
with rough edges and missing features.</para>
|
||||
trouble with this approach is that it entirely doesn't work yet. As
|
||||
of October 2010 FOP is at 1.0 and usable, but with rough edges and
|
||||
missing features. I recommed dblatex for production use.</para>
|
||||
|
||||
<para>Here is what the FOP toolchain looks like:</para>
|
||||
|
||||
|
|
@ -396,12 +431,22 @@ with rough edges and missing features.</para>
|
|||
</caption>
|
||||
</mediaobject>
|
||||
|
||||
<para>FOP has competition. There is another project called
|
||||
<application>xsl-fo-proc</application><indexterm><primary>xsl-fo-proc</primary></indexterm>
|
||||
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 <application>xsl-fo-proc</application> is in an unfinished
|
||||
alpha state, not as far along as FOP.</para>
|
||||
</sect1>
|
||||
<sect1><title>asciidoc</title>
|
||||
|
||||
<para>There is a relatively new tool called <ulink
|
||||
url="http://www.methods.co.nz/asciidoc/">asciidoc</ulink> that tackles
|
||||
several of the problems associated with DocBook rather effectively.</para>
|
||||
|
||||
<para>The <command>asciidoc</command> tool accepts a simple,
|
||||
lightweight syntax resembling wiki markups and turns it into various
|
||||
output formats using DocBook as an intermediate stage. The asciidoc
|
||||
markup is easier to compose in than DocBook itself, and serves
|
||||
as its own best rendering in flat ASCII.</para>
|
||||
|
||||
<para>Printing support in <command>asciidoc</command> is through an
|
||||
experimental LaTeX back end. It is most useful for writing short
|
||||
to medium-length documents for World Wide Web distribution.</para>
|
||||
|
||||
</sect1>
|
||||
<sect1><title>Who are the projects and the players?</title>
|
||||
|
|
@ -422,7 +467,7 @@ GNOME code to run. I hear it's blazingly fast compared to the
|
|||
Java alternatives, not a surprising claim.</para>
|
||||
|
||||
<para><ulink url="http://cyberelk.net/tim/xmlto/">xmlto</ulink> is the
|
||||
user interface of the XML toolchain that Red Hat ships. It's written
|
||||
user interface of the XML toolchain that most Linuxes. It's written
|
||||
and maintained by Tim Waugh.</para>
|
||||
|
||||
<para><ulink url="http://users.iclway.co.uk/mhkay/saxon/">Saxon</ulink>
|
||||
|
|
@ -435,6 +480,10 @@ Linux and BSD; it's designed to work with FOP.</para>
|
|||
XML Formatting Objects to PDF. It is part of the Apache XML project
|
||||
and is designed to work with Xalan.</para>
|
||||
|
||||
<para><ulink url="http://www.methods.co.nz/asciidoc/">asciidoc</ulink>
|
||||
translates its own lightweight markup to DocBook, and thence to various
|
||||
output formats.</para>
|
||||
|
||||
</sect1>
|
||||
<sect1><title>Migration tools</title>
|
||||
|
||||
|
|
@ -528,44 +577,25 @@ for details.</para>
|
|||
</sect1>
|
||||
<sect1><title>Editing tools</title>
|
||||
|
||||
<para>One thing we presently do not have is a good open-source
|
||||
structure editor for SGML/XML documents.</para>
|
||||
<para>Most people still hack DocBook tags by hand using either vi or
|
||||
emacs. There's an Nxml mode that ships with Emacs and is automatically
|
||||
invoked when the editor recognizes an XMl document. It has become
|
||||
pretty good; while it doesn't give GUI presentation, it does use its
|
||||
knowledge of XML to highlight out-of-balance tags. Some alternative
|
||||
are summarized at the <ulink
|
||||
url="http://www.emacswiki.org/emacs/CategoryXML">Emacs CategoryXML
|
||||
page</ulink>.</para>
|
||||
|
||||
<para>The <ulink url='http://conglomerate.org/'>Conglomerate</ulink> project
|
||||
aims specifically at producing a good DocBook editor. As of early
|
||||
2004 it is stilll alpha software.</para>
|
||||
<para>There have been a number of attempts at GUI editors for DocBook,
|
||||
often with the aim of being general editors for any markup with an XML or
|
||||
SGML schema. EuroMath, MLView, Conglomerate, ThotBook are among them.
|
||||
Such projects tent to stall out in alpha stage; designing a decent
|
||||
UI for this task is extemely difficult.</para>
|
||||
|
||||
<para>The <ulink
|
||||
url='http://www.freespiders.org/projects/gmlview/'>MlView</ulink>
|
||||
project is an XML editor, not specifically DocBook targeted. As of
|
||||
early 2004 it lacks documentation and appears to be in alpha.</para>
|
||||
|
||||
<para><ulink url="http://www.lyx.org/">LyX</ulink> 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
|
||||
<ulink url="http://bgu.chez.tiscali.fr/doc/db4lyx/">how-to document</ulink>
|
||||
escribing how to write SGML and XML in the LyX GUI.</para>
|
||||
|
||||
<para><ulink url="http://idx-getox.idealx.org/">GeTox</ulink>, the
|
||||
GNOME XML Editor, aims at nontechnical users. But the software is
|
||||
still (as of August 2001) alpha, more a proof of concept than anything
|
||||
useful, and the project group seems not to be very active; there have
|
||||
been no updates of the website between May 2001 and August 2002 (time of
|
||||
writing).</para>
|
||||
|
||||
<para><ulink
|
||||
url="http://www.math.u-psud.fr/~anh/TeXmacs/TeXmacs.html"> GNU
|
||||
TeXMacs</ulink> is a project aimed at producing an editor that is good
|
||||
for technical and mathematical material, including displayed formulas.
|
||||
1.0 was released in April 2002. The developers plan XML support in
|
||||
the future, but it's not there yet.</para>
|
||||
|
||||
<para><ulink url="http://www.freesoftware.fsf.org/thotbook/">ThotBook</ulink>
|
||||
is a project to put together a GUI editor for DocBook based on
|
||||
the Thot toolkit. It may be moribund; the web page was not updated
|
||||
from November 2001 to August 2002 (time of writing).</para>
|
||||
|
||||
<para>Most people still hack the tags by hand using either vi or emacs.</para>
|
||||
<para>Some attempts that have made it to production stage (if only
|
||||
barely, in many cases) can be found at the <ulink
|
||||
url="http://wiki.docbook.org/topic/DocBookAuthoringTools">DocBook
|
||||
Authoring Tools page</ulink>. I have not tried using any of these.</para>
|
||||
|
||||
</sect1>
|
||||
<sect1><title>Hints and tricks</title>
|
||||
|
|
@ -758,7 +788,7 @@ url="http://www.oreilly.com/catalog/docbook/">in print</ulink> and
|
|||
web</ulink>. This is indeed the definitive reference, but as an
|
||||
introduction or tutorial it's a disaster. Instead, read this:</para>
|
||||
|
||||
<para><ulink url="http://www.bureau-cornavin.com/opensource/crash-course/index.html">Writing
|
||||
<para><ulink url="http://opensource.bureau-cornavin.com/crash-course">Writing
|
||||
Documentation Using DocBook: A Crash Course</ulink>. This is an excellent
|
||||
tutorial.</para>
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 2.5 KiB After Width: | Height: | Size: 6.7 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 2.9 KiB After Width: | Height: | Size: 9.0 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 2.3 KiB After Width: | Height: | Size: 6.0 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 6.7 KiB After Width: | Height: | Size: 16 KiB |
|
|
@ -1104,7 +1104,7 @@ How to become a totally "small time" DNS admin. </Para>
|
|||
DocBook-Demystification-HOWTO</ULink>,
|
||||
<CiteTitle>DocBook Demystification HOWTO</CiteTitle>
|
||||
</Para><Para>
|
||||
<CiteTitle>Updated: Feb 2004</CiteTitle>.
|
||||
<CiteTitle>Updated: Sep 2010</CiteTitle>.
|
||||
Attempts to clear the fog and mystery surrounding the DocBook markup
|
||||
system and the tools that go with it. </Para>
|
||||
</ListItem>
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Topics covered in this section include:
|
|||
DocBook-Demystification-HOWTO</ULink>,
|
||||
<CiteTitle>DocBook Demystification HOWTO</CiteTitle>
|
||||
</Para><Para>
|
||||
<CiteTitle>Updated: Feb 2004</CiteTitle>.
|
||||
<CiteTitle>Updated: Sep 2010</CiteTitle>.
|
||||
Attempts to clear the fog and mystery surrounding the DocBook markup
|
||||
system and the tools that go with it. </Para>
|
||||
</ListItem>
|
||||
|
|
|
|||
Loading…
Reference in New Issue