<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="123" version="5.0" xml:id="sect-Publican-Users_Guide-Building_a_document" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
	<info>
		<title>Building a document</title>

	</info>
	 <note>
		<info>
			<title>Note — Customizing output</title>

		</info>
		 <para>
			The parameters set in the document configuration file (by default, <filename>publican.cfg</filename>) allow you to control many aspects of the way in which a document is presented — refer to <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" />.
		</para>
		 <para>
			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 <option>--config</option> to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
		</para>
		 
<screen><prompt>$</prompt> <command>publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg</command></screen>

	</note>
	 <para>
		To build a document:
	</para>
	 <procedure>
		<step>
			<para>
				Confirm the <parameter>YEAR</parameter> and <parameter>HOLDER</parameter> entities have been configured in the <filename><replaceable>Doc_Name</replaceable>.ent</filename> file, as described in <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory-Doc_Name.ent" />.
			</para>

		</step>
		 <step>
			<para>
				Change into the root directory of the document. For example, if the document is named <literal>Test_Book</literal> and is located in the <filename>~/books/</filename> directory, run the following command:
			</para>
			 
<screen><prompt>$</prompt> <command>cd ~/books/Test_Book</command></screen>

		</step>
		 <step>
			<para>
				Run a test for any errors that would stop the book from building in your chosen language, for example:
			</para>
			 
<screen><prompt>$</prompt> <command>publican build --formats=test --langs=en-US</command></screen>

		</step>
		 <step>
			<para>
				Run the following command to build the book:
			</para>
			 
<screen><prompt>$</prompt> <command>publican build --formats=<replaceable>formats</replaceable> --langs=<replaceable>languages</replaceable></command></screen>
			 <para>
				Replace <replaceable>formats</replaceable> with a comma-separated list of the formats that you want to build; for example, <literal>html,html-single,pdf</literal>. Replace <replaceable>langs</replaceable> with a comma-separated list of the languages that you want to build; for example, <literal>en-US,sv-SE,uk-UA,ko-KR</literal>.
			</para>

		</step>

	</procedure>
	 <variablelist conformance="124" xml:id="vari-Publican-Users_Guide-Building_a_document-Formats_for_the_build_action">
		<info>
			<title>Formats for the <command>build</command> action</title>

		</info>
		 <varlistentry>
			<term><option>html</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as in multiple HTML pages, with each chapter and major section on a separate page. <application>Publican</application> places an index at the start of the document, and places navigational elements on each page.
				</para>
				 <para>
					Use the <parameter>chunk_first</parameter> and <parameter>chunk_section depth</parameter> parameters in the <filename>publican.cfg</filename> file to control how <application>Publican</application> chunks sections in this format.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>html-single</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as a single HTML page with the table of contents near the top of the page.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>html-desktop</option></term>
			 <listitem>
				<para>
					<application>Publican</application> 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.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>man</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as a manual page ("man page") for use with Linux, UNIX, and similar operating systems.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>pdf</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as a PDF file.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>test</option></term>
			 <listitem>
				<para>
					<application>Publican</application> validates the XML structure of the book, but does not transform the XML into another format.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>txt</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as a single text file.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>epub</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as an e-book in EPUB format.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><option>eclipse</option></term>
			 <listitem>
				<para>
					<application>Publican</application> outputs the document as an <application>Eclipse</application> help plugin. Refer to <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" /> for details of specifying <application>Eclipse</application>'s <parameter>id</parameter>, <parameter>name</parameter>, and <parameter>provider-name</parameter> parameters with <application>Publican</application>'s <parameter>ec_id</parameter>, <parameter>ec_name</parameter>, and <parameter>ec_provider</parameter> parameters.
				</para>

			</listitem>

		</varlistentry>

	</variablelist>
	 <para>
		The following examples demonstrate commonly used <prompt>$</prompt> <command>publican build</command> commands:
	</para>
	 <variablelist>
		<varlistentry>
			<term><prompt>$</prompt> <command>publican build --help</command></term>
			 <listitem>
				<para>
					List available <prompt>$</prompt> <command>publican build</command> options for building a book.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><prompt>$</prompt> <command>publican build --formats=test --langs=<replaceable>languages</replaceable></command></term>
			 <listitem>
				<para>
					Check that the book can be built correctly. Build <command>--formats=test</command> before running any other <prompt>$</prompt> <command>publican build</command> command, and before checking a book back into a version-controlled repository from which other contributors might download it.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><prompt>$</prompt> <command>publican build --formats=html --langs=<replaceable>languages</replaceable></command></term>
			 <listitem>
				<para>
					Build the book in multi-page HTML format. The HTML output will be located in the <filename><replaceable>Doc_Name</replaceable>/tmp/<replaceable>language</replaceable>/html/</filename> directory. Each chapter and major section is placed in a separate HTML file. You can control the depth at which <application>Publican</application> places subsections into separate HTML files with the <literal>chunk-section-depth</literal> parameter in the <filename>publican.cfg</filename> — refer to <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" />.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><prompt>$</prompt> <command>publican build --formats=html-single --langs=<replaceable>languages</replaceable></command></term>
			 <listitem>
				<para>
					Build the book in single-page HTML format. The output will be a single HTML file located in the <filename><replaceable>Doc_Name</replaceable>/tmp/<replaceable>language</replaceable>/html-single/</filename> directory.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><prompt>$</prompt> <command>publican build --formats=pdf --langs=<replaceable>languages</replaceable></command></term>
			 <listitem>
				<para>
					Build the book as a PDF file. <application>Publican</application> relies on an external application, <application>FOP</application> to render PDF. Therefore, building PDF might not be available on all systems, depending on the availability of <application>FOP</application>. The output will be a single PDF file located in the <filename><replaceable>Doc_Name</replaceable>/tmp/<replaceable>language</replaceable>/pdf/</filename> directory.
				</para>

			</listitem>

		</varlistentry>
		 <varlistentry>
			<term><prompt>$</prompt> <command>publican build --formats=html,html-single,pdf --langs=<replaceable>languages</replaceable></command></term>
			 <listitem>
				<para>
					Build the book in multi-page HTML, single-page HTML, and PDF formats.
				</para>

			</listitem>

		</varlistentry>

	</variablelist>
	 <section conformance="125" xml:id="sect-Publican-Users_Guide-Building_a_document-Building_a_document_without_validation">
		<info>
			<title>Building a document without validation</title>

		</info>
		 <para>
			<application>Publican</application> validates your XML against the DocBook <firstterm>document type definition</firstterm> (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 (<tag>&lt;xref&gt;</tag>s) to sections of the document that do not yet exist. To skip validation, run <prompt>$</prompt> <command>publican build</command> with the <option>--novalid</option> option. Cross-references to non-existent content appear in the built document as three question marks: <literal>???</literal>.
		</para>
		 <para>
			Because the document has not been validated against the DTD, the quality of the output produced when you build with the <option>--novalid</option> option is highly suspect. Do not publish documentation that you have built with the <option>--novalid</option> option.
		</para>

	</section>

</section>