Create docbook documents

1. knowledge required to create a docbook document:

1) XML-this is the most basic. If you don't understand this, you 'd better first look for an entry-level book;
2) DTD-helps you understand the structure of docbook;
3) XSL-help you customize your own docbook;
4) XSL-FO-it is better to understand a little, help to better customize your own PDF output.

2. The simplest process to create a docbook document includes the following steps:

1) edit the XML file;
2) process XML files and generate HTML or PDF documents.

2.1. Edit the XML file

If you use a plain text editor to complete this task, I bet you won't be able to do it any more in a day. Directly editing XML is a tough task. Using tools such as xmlspy provides the automatic filling function, and can check the validity at any time, which is not prone to errors and can make the work much easier.

Docbook documents are divided into two types: Book and article ). Article is a general article, not including chapter, but only section ). The book is complete and can contain preface, part, chapter, and article. The above descriptions are all elements defined by the docbook DTD, which cannot be described in detail here. For details about the structure of each element, see docbook DTD.

Let's take a look at the typical definition of a book-type document:

List 1. Typical book-type documents
<? XML version = "1.0" encoding = "UTF-8"?>
<! Doctype book public "-// oasis // DTD docbook XML v4.2 // en"
Http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd>
<Book>
<Bookinfo>
<Title> my book </title>
<Author>
<Firstname> my first name </firstname>
<Surname> my last name </surname>
</Author>
<Publisher>
<Publishername> csdn </publishername>
</Publisher>
<ISBN> ISBN # </ISBN>
<Copyright>
<Year> 2005 </year>
</Copyright>
</Bookinfo>
<Part>
<Title> my part </title>
<Chapter>
<Title> my chapter </title>
<Sect1>
<Title> my Section1 </title>
<Para> This is a demo of a book. </para>
</Sect1>
</Chapter>
</Part>
</Book>

This document declares that the DTD used is author (title), author (author), publisher (publisher), Book Number (ISBN), and copyright (copyright ). The content contained in the part element is a part of the book. There is a chapter below, followed by a section (sect1), of course, each with its own title.

The meaning of each element is obvious. Based on the element name, you can know what elements your content should contain.

In the above example, some elements are not required. For example, bookinfo can have either or none of them. Read the docbook DTD.

The following uses articles of the article type as an example to describe how to create a docbook document.

The first is the XML declaration, which describes some basic information about the document:

<? XML version = "1.0" encoding = "UTF-8"?>

The document's DTD Declaration shows that the document's DTD also contains the root element. The DTD declaration of a typical docbook document is as follows:

<! Doctype Article public "-// oasis // DTD docbook XML v4.2 // en"
Http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd>

This statement indicates that the root element of the document is <Article>. An external DTD is used. The DTD is identified by a public identifier "-// oasis // DTD docbook XML v4.2 // en, this DTD is located somewhere in the network. The identifier must be globally unique in the form:

Prefix // owner-identifier // text-class text-description // language // display-version

The first prefix is "+/-", "+" indicates that it is a registered identifier, and "-" indicates that it is the opposite. Compare the meanings of other parts.

Then you can add the content. First, the root element:

<Article>

</Article>

Article must have a title:

<Article>
<Title> my article </title>
</Article>

There must be content after the title, and there cannot be any content in the article:

<Article>
<Title> my article </title>
<Sect1>
</Sect1>
</Article>

Here we add a section. "sect1" is the top-level element of the section. Its orchestration method is similar to "Heading 1" in MS Word.

Same as article, sect1 must also have a title:

<Article>
<Title> my article </title>
<Sect1>
<Title> my section </title>
</Sect1>
</Article>

NO content is allowed in sect1:

<Article>
<Title> my article </title>
<Sect1>
<Title> my section </title>
<Para> This is my first article. </para>
</Sect1>
</Article>

The content of the body is generally enclosed by <para> elements. Para is the meaning of a paragraph (paragraph.

Now we have a simple docbook document. List 2 is the complete code.

List 2. A simple article
<? XML version = "1.0" encoding = "UTF-8"?>
<! Doctype Article public "-// oasis // DTD docbook XML v4.2 // en"
Http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd>
<Article>
<Title> my article </title>
<Sect1>
<Title> my section </title>
<Para> This is my first article. </para>
</Sect1>
</Article>

After editing, save it as myarticle. xml and generate HTML or PDF.

2.2 generate html

For how to install the configuration tool, see "install and configure docbook ".

I use xsltproc under cygwin to generate HTML, and enter the command in cygwin shell:

Xsltproc -- nonet -- output myarticle.html C:/docbook-xsl-1.67.2/html/docbook. XSL myarticle. xml

-- Nonet indicates that I do not want to obtain a DTD from the network, which can save time.

--Outputspecifies the name of the output file, which is myarticle.html.

Next is the XSL style sheet used to convert XML files. Note that the XSL style sheet in the HTML directory is used.

The docbook document to be processed.

If you are not interested, you can open myarticle.html with a browser to check the effect.

2.3 generate PDF files

The following uses fop to generate a PDF file. For more information about how to install and configure fop, see http://blog.csdn.net/mickeyrat/archive/2005/02/06/2820.1.aspx.

Enter the following command in the console:

Fop-XML myarticle. XML-xsl c:/docbook-xsl-1.67.2/FO/docbook. XSL myarticleworkflow

Linux commands are similar. Pay attention to the docbook. XSL path.

-XML specifies the docbook document to be converted.

-XSL specifies the style sheet used. Note that the style sheet under the fo directory is used here, which is designed for conversion XSL-FO.

Finally, the file name of the output document.

In the FOP processing process, many

Property-"background-position-horizontal" is not implemented yet.

. Ignore this because FOP is still under development and many XSL-FO features are not supported. This problem does not affect the generation of the final document.

Open myarticle.pdf and check the effect. Is it a professional PDF document?

Do you think it is very easy to create a docbook document? This may be wrong. The rest of this article describes the Advanced Skills for creating docbook documents.

3. Customize your own XSL style sheets

After you officially create your own docbook documents, you will find that the generated documents do not fully meet your format requirements, such as chapter numbers, page numbers, fonts, and so on. This section describes how to customize your own XSL style sheets to generate documents meeting specific requirements. The following content involves XSL and XSL-fo.

Some people may want to customize the docbook DTD, but this method is not recommended, because after you modify the docbook DTD, your document is no longer a docbook document.

Because docbook completely separates the content from the style, you can change the output result by modifying the XSL style sheet.

To modify a style sheet, you need to have your own custom layer, that is, develop your own style sheet based on the docbook XSL style sheet. Do not directly modify the docbook XSL style sheet. There are two disadvantages to doing so:

1) not easy to maintain: Your modifications may be scattered among dozens of files. In a few days, you will forget the modified items.

2) not easy to upgrade: If you want to upgrade the style to a new version, you have to merge all the modifications you have made into the new version. The merge process must deal with a large number of conflicts, and prone to errors.

I think you should know the difference between <XSL: Include> and <XSL: Import>: The elements introduced by <XSL: Include> are valid for the first time if repeated definitions exist; the last element introduced by <XSL: Import> is valid. The custom layer is actually dependent on a feature such as XSL. Use <XSL: Import> to introduce the starting file of the docbook XSL style sheet, and then add your own modifications. List 3 provides a framework for customizing layer files.

List 3 customization. XSL
<? XML version = '1. 0'?>
<XSL: stylesheet xmlns: XSL = "http://www.w3.org/1999/XSL/Transform" version = "1.0">
<XSL: Import href = "html/docbook. XSL"/>
...
Modifications
...
</XSL: stylesheet>

The custom layer is an XSL file, so we need to introduce the XSL namespace. In the third line, introduce docbook. XSL, the starting file of the XSL style sheet that converts HTML, if it is the custom layer of the XSL-FO, the starting file is under the fo directory. Then you can add your own modifications.

There are two types of customization: one is to modify the style sheet parameters and the other is to modify the template.

3.1 modify the parameters of a style sheet

Open html/Param. XSL or FO/Param. XSL to find all the style sheet parameters. Let's look at the example below.

<XSL: Param name = "section. autolabel" select = "0"/>

The parameter name is "section. autolabel" and the value is "0 ". This parameter is used to control whether the section is automatically numbered when a document is generated, such as "1" and "1.1. "0" indicates that the automatic number is disabled. You can take a look at the previous document. Is there no chapter number?

To enable the automatic number, you only need to modify it as follows:

<XSL: Param name = "section. autolabel" select = "1"/>

Didn't you change it directly in Param. XSL? If yes, change it back! Remember that all the modifications are written in the previously generated customization. XSL. Now generate HTML again,

Xsltproc -- nonet -- output myarticle.html C:/docbook-xsl-1.67.2/customization. XSL myarticle. xml

Or generate PDF
Fop-XML myarticle. XML-xsl c:/docbook-xsl-1.67.2/customization. XSL myarticleworkflow

Note that this parameter is valid for both HTML and XSL-FO, but you must use <XSL: Import> in customization. XSL to introduce the corresponding start file; otherwise, an error is reported. Is there a chapter number in the new document?

Another one. The bookmark function is disabled in FO/Param. XSL. Add the following in customization. XSL:

<XSL: Param name = "fop. Extensions" select = "1"/>

In this way, fop generates a bookmark during processing. Note that the parameter name "fop. Extensions" indicates that this parameter belongs to the FOP extension and is only valid for fop. If passivetex is used, set "passivetex. Extensions ".

The following is a complex example:

<XSL: Param name = "formal. Title. Placement">
Figure after
Example before
Equation before
Table before
Procedure before
Task before
</XSL: param>

This parameter acts on the title of the graph, table, and other elements in the document, and controls whether the title is located before (Before), after (after), And Param. XSL predefines "before", where the title of figure is placed behind the graph. This parameter is valid for both HTML and XSL-FO. Add the <figure> element to your document and regenerate the document to see the effect.

3.2 modify a template

Docbook XSL provides many parameters to control the output results. But sometimes, modifying parameters alone does not meet all requirements. In this case, you need to modify the template.

Let's look at a very realistic example. The XSL-FO defines a class of attributes starting with "Keep-", such as "Keep-with-next", indicating that the previous content must be on the same page as the subsequent content, it cannot be disconnected from two pages. Except table,
FOP currently does not support such attributes. So when the document is long, in the PDF document generated by fop, you will find that the title of some sections is at the bottom of a page, while the content is on the next page, this can happen for other headers. This is of course unreasonable, but no matter how you add parameters of the "Keep-" class, it will not help.

In this case, the fop faq tells you: "Sorry, we haven't implemented it yet." As for the implementation time, "don't ask, I don't know ".

Therefore, only one work und can be used. As I mentioned earlier, if fop supports this attribute for table, can you consider placing such content in table? Of course we can. fop has a concept of "blind table". The content of such a table is invisible and meets our requirements. The problem now is that docbook XSL style sheets generate generic XSL-FO files that do not put the content of elements like <sect2> into "Blind table. There is only one path left (in fact, there is another one, with commercial products ^ _ ^, renderx's xep supports the "keep-" Class Attribute), modifying the style sheet template. The Code of list 4 puts the content of <sect2> in a "Blind table.
 
List 4. blindtable. XSL
<? XML version = '1. 0'?>
<XSL: stylesheet xmlns: XSL = "http://www.w3.org/1999/XSL/Transform"
Xmlns: fo = "http://www.w3.org/1999/XSL/Format"
Version = "1.0">
<XSL: Import href = "docbook. XSL"/>

<XSL: template match = "sect2">
<XSL: variable name = "ID">
<XSL: Call-Template Name = "object. ID"/>
</XSL: Variable>

<FO: Table-layout = "fixed" width = "100%">
<FO: Table-column-number = "1"/>
<FO: Table-body>
<FO: Table-row keep-with-Next = "always">
<FO: Table-cell id = "{$ id}" XSL: Use-Attribute-sets = "section. level2.properties">
<XSL: Call-Template Name = "sect2.titlepage"/>
</FO: Table-cell>
</FO: Table-row>
<XSL: variable name = "toc. Params">
<XSL: Call-Template Name = "find. Path. Params">
<XSL: With-Param name = "table" select = "normalize-space ($ generate. TOC)"/>
</XSL: Call-template>
<XSL: If test = "contains ($ toc. Params, 'toc ') and $ generate. Section. toc. Level & gt; = 2">
<XSL: Call-Template Name = "section. TOC"/>
<XSL: Call-Template Name = "section. toc. separator"/>
</XSL: If>
</XSL: Variable>
<FO: Table-row>
<FO: Table-cell>
<XSL: Apply-templates select = "* [2]"/>
</FO: Table-cell>
</FO: Table-row>
</FO: Table-body>
</FO: Table>
<XSL: Apply-templates select = "* [position ()> 2]"/>
</XSL: Template>
</XSL: stylesheet>

This section of code will not be explained much. In general, its role is to cover the sections. the template named "sect2" defined in XSL puts the title and content of <sect2> into two lines in a single list when generating the XSL-FO file. Because the fo namespace is used here, the fo namespace should be introduced at the beginning.

Regenerate a PDF file:

Fop-XML yourarticle. XML-xsl c:/docbook-xsl-1.67.2/blindtable. XSL yourarticleworkflow

You will find that all <sect2> content is not separated from the content on two pages.

4. Summary

So far, you have learned the complete process of making a docbook:

1) edit the XML document;
2) generate html/pdf;
3) customize the XSL style sheet.

You cannot directly modify the docbook XSL style sheet for custom XSL styles. You need to create a new XSL file as the custom layer.

There are two types of XSL style sheet customization:

1) modify the XSL parameters;
2) modify the XSL template.

In short, docbook is a very powerful tool that can be used to produce very professional and beautiful technical documents, or even other documents.

References:

Docbook Introduction

Install and configure docbook

Docbook XSL: the complete guide