7. Building a document

Note — Customizing output

The parameters set in the document configuration file (by default, publican.cfg) allow you to control many aspects of the way in which a document is presented — refer to Section 1.1, “The publican.cfg file”.

If you maintain multiple versions of a document, you can create a configuration file for each version. When building the document, you can use the --config to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:

$ publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg

To build a document:

Confirm the YEAR and HOLDER entities have been configured in the Doc_Name.ent file, as described in Section 1.6, “Doc_Name.ent”.
Change into the root directory of the document. For example, if the document is named Test_Book and is located in the ~/books/ directory, run the following command:
```
$ cd ~/books/Test_Book
```
Run a test for any errors that would stop the book from building in your chosen language, for example:
```
$ publican build --formats=test --langs=en-US
```
Run the following command to build the book:
```
$ publican build --formats=formats --langs=languages
```
Replace formats with a comma-separated list of the formats that you want to build; for example, html,html-single,pdf. Replace langs with a comma-separated list of the languages that you want to build; for example, en-US,sv-SE,uk-UA,ko-KR.

Formats for the build action

html

Publican outputs the document as in multiple HTML pages, with each chapter and major section on a separate page. Publican places an index at the start of the document, and places navigational elements on each page.

Use the chunk_first and chunk_section depth parameters in the publican.cfg file to control how Publican chunks sections in this format.

html-single

Publican outputs the document as a single HTML page with the table of contents near the top of the page.

html-desktop

Publican outputs the document as a single HTML page with the table of contents located in a separate pane on the left side of the document.

man

Publican outputs the document as a manual page ("man page") for use with Linux, UNIX, and similar operating systems.

pdf

Publican outputs the document as a PDF file.

test

Publican validates the XML structure of the book, but does not transform the XML into another format.

txt

Publican outputs the document as a single text file.

epub

Publican outputs the document as an e-book in EPUB format.

eclipse

Publican outputs the document as an Eclipse help plugin. Refer to Section 1.1, “The publican.cfg file” for details of specifying Eclipse's id, name, and provider-name parameters with Publican's ec_id, ec_name, and ec_provider parameters.

The following examples demonstrate commonly used $ publican build commands:

$ publican build --help: List available $ publican build options for building a book.
$ publican build --formats=test --langs=languages: Check that the book can be built correctly. Build --formats=test before running any other $ publican build command, and before checking a book back into a version-controlled repository from which other contributors might download it.
$ publican build --formats=html --langs=languages: Build the book in multi-page HTML format. The HTML output will be located in the Doc_Name/tmp/language/html/ directory. Each chapter and major section is placed in a separate HTML file. You can control the depth at which Publican places subsections into separate HTML files with the chunk-section-depth parameter in the publican.cfg — refer to Section 1.1, “The publican.cfg file”.
$ publican build --formats=html-single --langs=languages: Build the book in single-page HTML format. The output will be a single HTML file located in the Doc_Name/tmp/language/html-single/ directory.
$ publican build --formats=pdf --langs=languages: Build the book as a PDF file. Publican relies on an external application, FOP to render PDF. Therefore, building PDF might not be available on all systems, depending on the availability of FOP. The output will be a single PDF file located in the Doc_Name/tmp/language/pdf/ directory.
$ publican build --formats=html,html-single,pdf --langs=languages: Build the book in multi-page HTML, single-page HTML, and PDF formats.

7.1. Building a document without validation

Publican validates your XML against the DocBook document type definition (DTD) before it builds the content. However, while a document is under development, you might sometimes want to skip validation while building, especially if the document contains cross-references (<xref>s) to sections of the document that do not yet exist. To skip validation, run $ publican build with the --novalid option. Cross-references to non-existent content appear in the built document as three question marks: ???.

Because the document has not been validated against the DTD, the quality of the output produced when you build with the --novalid option is highly suspect. Do not publish documentation that you have built with the --novalid option.