Table of Contents
This appendix describes the installation of the tools needed to produce a formatted version of the NetBSD guide. Besides that it contains instructions that describe how to build the guide. This appendix assumes knowledge of pkgsrc, see see Chapter 30, The package collection for details.
XML (eXtensible Markup Language) is a language which is used to define other languages based on markups, i.e. with XML you can define the grammar (i.e. the valid constructs) of markup languages. HTML, for example, can be defined using XML. If you are a programmer, think of XML like the BNF (Backus-Naur Form): a tool used to define grammars.
DocBook is a markup template defined using XML; DocBook lists the valid tags that can be used in a DocBook document and how they can be combined together. If you are a programmer, think of DocBook as the grammar of a language specified with the BNF. For example, it says that the tags:
<para> ... </para>
define a paragraph, and that a <para> can be inside a <sect1> but that a <sect1> cannot be inside a <para>.
Therefore, when you write a document, you write a document in DocBook and not in XML: in this respect DocBook is the counterpart of HTML (although the markup is richer and a few concepts are different).
The DocBook specification (i.e. the list of tags and rules) is called a DTD (Document Type Definition.)
In short, a DTD defines how your source documents look like but it gives no indication about the format of your final (compiled) documents. A further step is required: the DocBook sources must be converted to some other representation like, for example, HTML or PDF. This step is performed by a tool like Jade, which applies the DSSSL transforms to the source document. DSSSL (Document Style Semantics and Specification Language) is a format used to define the stylesheets necessary to perform the conversion from DocBook to other formats. The build structure for the guide also supports the XSL (Extensible Stylesheet Language) stylesheet language. The xsltproc program is used for transforming XML with XSL stylesheets.
All the tools that are needed to generate the guide in various formats can be installed through the netbsd-www, netbsd-doc, and netbsd-doc-print meta-packages. Together the netbsd-doc and netbsd-www packages install everything that is needed to generate the HTML version of the guide. To be able to generate printable formats, such as Postscript and PDF, install the netbsd-doc-print meta-package.
Supposing that a current pkgsrc tree is installed at
/usr/pkgsrc, you can install all these
meta-packages with:
$cd /usr/pkgsrc/meta-pkgs/netbsd-www$make install$cd /usr/pkgsrc/meta-pkgs/netbsd-doc$make install$cd /usr/pkgsrc/meta-pkgs/netbsd-doc-print$make install
This section provides an overview of how the guide can be compiled from XML to any of the following target formats: html, html-split, ascii, ps, and pdf. Creating all formats is the default. To produce any of the above output formats, run make with the format(s) as argument.
Let's look at a few examples.
Before looking at the output generated in any of the above-mentioned formats, integrity of the XML structure has to be ensured. This can be done by running make lint:
$cd htdocs/guide/en$make lint
Fix any errors you may get. When working on the contents of the guide, you may want to produce the HTML version to have a look at it for proofreading:
$cd htdocs/guide/en$make html-split
After this, please update the Postscript and PDF versions of the guide too. The command for this is:
$cd htdocs/guide/en$make pdf
Before you go and commit the generated files, please make sure that you commit the XML files first, then re-generated all formats, i.e. the procedure would be something like:
$cd htdocs/guide/en$cvs commit *.xml$$make lint$make$make install-doc$$cd ..$cvs commit en download
When running make with no argument, all formats will be re-generated. This is the default way to build the guide for the NetBSD.org website.
The NetBSD guide is currently available in three languages: English, French and Italian. Of these, only English and French are automatically hyphenated by TeX. To turn on hyphenation for the Italian language, some simple steps are required:
Edit
/usr/pkg/share/texmf/tex/generic/config/language.dat
and remove the comment (%) from the line
of the Italian hyphenation. I.e.
%italian ithyph.tex
becomes
italian ithyph.tex
As more translations of the guide become available, you will probably need to enable other hyphenation patterns as well.
Now the latex and pdflatex formats must be recreated:
#cd /usr/pkg/share/texmf/web2c#fmtutil --byfmt latex#fmtutil --byfmt pdflatex
If you check, for example, latex.log
you will find something like:
Babel <v3.6Z> and hyphenation patterns for american, french, german, ngerman, italian, nohyphenation, loaded.
Please note that there are many ways to perform these operations, depending on your level of expertise with the TeX system (mine is very low). For example, you could use the "texconfig" interactive program, or you could recreate the formats by hand using the tex program.
If you know a better way of doing the operations described in this appendix, please let me know.
The official DocBook home page is where you can find the definitive documentation on DocBook. You can also read online or download a copy of the book DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner.
For DSSSL start looking at http://nwalsh.com.
XSL is described at http://www.w3.org/Style/XSL/.
Jade/OpenJade sources and info can be found on the OpenJade Home Page.
If you want to produce Postscript and PDF documents from your DocBook source, look at the home page of JadeTex.
The home page of Markus Hoenicka explains everything you need to know if you want to work with SGML/DocBook on the Windows NT platform.