A simple Docbook 5.0 example

A simple docbook 5.0 example

I used docbook to write documents for about a month or two, but I have been paying attention to docbook for a long time. I have also read many Chinese and English docbook documents online. The main reason why docbook 4.2 has never been used is that the compilation environment configuration of docbook looks complicated. I tried to configure it once, but I finally gave up a lot of catalog configurations, SGML configurations, and openjade configurations.

Until one day, I saw the playing written by BENR.
With docbook 5.0, the first time you actually write a docbook document. Docbook 5.0 no longer uses the old sgml dtd, instead uses XML, and the compilation environment configuration is much simpler.

Next I will first introduce how to build the docbook 5.0 compiling environment in windows, and then take a simple docbook 5.0 document as an example to explain how to convert the docbook document to other formats.

[Setting up the docbook compiling environment in Windows]

1. Download the Docbook XSL style sheet

   First download Docbook
   XSL conversion style sheet. Download docbook-xsl-ns. The latest version is 1.74.3. After the download, decompress it to a directory, I suppose to decompress it to the C: \ docbook directory, that is, the directory where the Docbook XSL is located is: C: \ docbook \ docbook-xsl-ns-1.74.3 \.

   In the document about Docbook, I mentioned that Docbook is "separated content and format". When we write a Docbook document, we only focus on the content of the document. How to convert Docbook to another document type is determined by Docbook
   XSL conversion style sheet to define. The most common method is to convert to HTML style sheets and to FO style sheets.

2. Download the ttproc Conversion Program

   Next, you need to download the XML language conversion tool. My favorite Conversion Tool is xsltproc, an XML Conversion Tool written in C language. It features fast conversion and supports both Windows and Linux. In addition to this conversion tool, there are many conversion tools written in Java, such as Saxon and Xalan.

   Here we download the Windows version of javastproc. We need to download the following packages:

   • Iconv-1.9.2.win32.zip-encoding conversion tools
   • Zlib-1.2.3.win32.zip-compression tools
   • Libxslt-1.1.24.win32.zip-XSL and EXSL conversion tools, where the xsltproc Program
   • Libxml2-2.7.3.win32.zip-XML parsing and processing tools with verification toolsXmllint and xmlcatalog

   In fact, it is quite easy to configure docbook in windows, and the above four tools are indispensable.

   After downloading the package, decompress the package to the same directory. For example, extract the package to the C: \ docbook \ javastproc directory. After unzipping, you can see the package in C: \ docbook \ javastproc \ has three more directories: bin, include, and lib. Now you need to add C: \ docbook \ ttproc \ bin to the environment variable PATH, and then open a DOS window. You can directly enter the xsltproc command without entering the full PATH.

3. Install FOP

   After the above two tools are installed, you can convert Docbook documents into HTML format. If you need to convert Docbook documents to PDF, you also need to install a conversion tool to convert XSL-FO format to PDF format, Apache
   FOP is a good choice. However, I do not have this requirement and I have not installed it yet. It is said that it is complicated to configure Apache FOP to support Chinese characters. I tried to write it again the next day. (2009/04/11. For more information about Apache FOP configuration, see the article "use Apache ".
   FOP converts Docbook documents to PDF (1)

Now, the compilation environment of docbook is ready. Compared with docbook 4.2, it is much easier to build the compiling environment. You don't have to configure catalog any more, because docbook 5.0 no longer requires Document Type Definitions.

Next, we will write a simple docbook document.

[Compile docbook documents]

You can download the files used in this example here, including docbook. XML, docbook_easwy.xsl, and easwy makefile.

Below is a simple docbook 5.0 document. Save this section, for example, save it as a file docbook. xml.

<? XML version = '1. 0' encoding = "UTF-8"?> <Article xmlns = "http://docbook.org/ns/docbook" version = "5.0" XML: lang = "ZH-CN" xmlns: xlink = 'HTTP: // www.w3.org/5o/xlink'> <articleinfo> <title> my first docbook 5.0 document </title> <author> <firstname> easwy </firstname> <surname> Yang </surname> </author> </articleinfo> <section> <title> document introduction </title> <para> This is my first docbook 5.0 document, welcome to <link xlink: href = 'HTTP: // easwy.com/blog/'> easwy blog </link>. </Para> </section> </Article>

[Convert a document to HTML format]

Set the output encoding to a UTF-8 before conversion. The default output encoding for docbook-XSL-ns is ISO-8859-1, but for Chinese characters, we should set the output encoding to UTF-8, otherwise the output file will be garbled.

It's easy to change the output encoding, you can directly modify your c: \ docbook \ docbook-xsl-ns-1.74.3 \ HTML \ docbook. XSL file, find in the file

   <xsl:output method="html"            encoding="ISO-8859-1"            indent="no"/>     

Change it

   <xsl:output method="html"            encoding="UTF-8"            indent="no"/>     

I usually write another XSL file that contains the standard docbook-XSL and redefines my code as a UTF-8. Save the following file as docbook_easwy.xsl:

<?xml version='1.0'?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"                version='1.0'><xsl:include href="C:/docbook/docbook-xsl-ns-1.74.3/html/docbook.xsl"/><xsl:output method="html"            encoding="UTF-8"            indent="no"/></xsl:stylesheet> 

Next, we will convert the Docbook document to HTML format and use the following command:

xsltproc -o docbook.html docbook_easwy.xsl docbook.xml 

If you see a message similar to the following, your xsl is not docbook-xsl-ns, but docbook-xsl. If you do not want to download docbook-xsl-ns, ignore the alarms. These alarms do not affect usage.

1: Note: namesp. cut: stripped namespace before processing my first Docbook 5.0 document

2: WARNING: cannot add @ xml: base to node set root element. Relative paths may not work.

3: Note: namesp. cut: processing stripped document my first Docbook 5.0 document

If it is too troublesome to input a conversion command, you can save the preceding command as a batch processing file. I installed Cygwin in Windows (refer to this article to install cygwin). Therefore, Makefile is generally used to convert the Docbook source file. The content of my Makefile is as follows:

# Docbook Makefile# Easwy YangXSLFILE=docbook_easwy.xslXML_FILE=$(wildcard *.xml)HTML_FILE=$(XML_FILE:.xml=.html).PHONY: html cleanhtml : $(HTML_FILE)%.html : %.xmlxsltproc -o $(@F) $(XSLFILE) $<clean:rm *.html 

Now, in vim, I can directly use the: make command to convert my Docbook source document.