# 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 .

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:

1. Confirm the `YEAR` and `HOLDER` entities have been configured in the `Doc_Name.ent` file, as described in .

2. 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

3. 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

4. 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 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 .

$ `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.

## 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.