3.4. Building a document

To build a document:

Confirm the YEAR and HOLDER entities have been configured in the Doc_Name.ent file, as described in Section 3.1.6, “Doc_Name.ent”.
Change into the root directory of the document. For example, if the document was named Test_Book and was 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, --formats=html,html-single,pdf. Replace langs with a comma-separated list of the languages that you want to build, for example, --langs=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 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.
pdf: Publican outputs the document as a PDF file.
txt: Publican outputs the document as a single text file.
epub: Publican outputs the document as an e-book in EPUB format.

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

3.4.1. Building a document created with Publican 0

Documents produced with early versions of Publican (versions up to and including 0.45) did not have a publican.cfg file; a similar set of parameters was defined in a Makefile. Before you build such a document in a current version of Publican (version 0.99 onwards), you must convert the Makefile into a publican.cfg file. Publican can do this conversion automatically:

Change into the document directory, the one that holds the Makefile.
Run publican old2new. Publican parses the Makefile and creates a publican.cfg file with equivalent parameters wherever available.

When you run publican old2new, Publican does not alter or delete the original Makefile. A Makefile and a publican.cfg file can coexist in the same document.