Publican 0.44

Users Guide

Publishing books, articles, papers and multi-volume sets with DocBook XML

Edition 1.2

Don Domingo

Red Hat Engineering Content Services

ddomingo@redhat.com

Brian Forté

Red Hat Engineering Content Services

bforte@redhat.com

Murray McAllister

Red Hat Engineering Content Services

mmcallis@redhat.com

Joshua Oakes

Red Hat Engineering Content Services

joakes@redhat.com

Joshua Wulf

Red Hat Engineering Content Services

jwulf@redhat.com

Edited by

Brian Forté

Red Hat Engineering Content Services

bforte@redhat.com

Jeff Fearn

Extensive review, rough drafts, persistent annoyances.

jfearn@redhat.com

Legal Notice

Copyright © 2008 Red Hat, Inc This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt).

Abstract

This book will help you install publican. It also provides instructions for using publican to create and publish DocBook XML-based books, articles and book-sets. This guide assumes you are already familiar with DocBook XML.

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

Press Enter to execute the command.
Press Ctrl-Alt-F1 to switch to the first virtual terminal. Press Ctrl-Alt-F7 to return to your X-Windows session.

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

Choose System > Preferences > Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications > Accessories > Character Map from the main menu bar. Next, choose Search > Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit > Paste from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.

Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.

1.2. Pull-quote Conventions

Two, commonly multi-line, data types are set off visually from the surrounding text.

Output sent to a terminal is set in Mono-spaced Roman and presented thus:

books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs

Source-code listings are also set in Mono-spaced Roman but are presented and highlighted as follows:

package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
   
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

A Note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.

Warning

A Warning should not be ignored. Ignoring warnings will most likely cause data loss.

2. We Need Feedback!

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&version=rawhide&component=publican against the product fedora. When submitting a bug report, be sure to mention the manual's identifier: publican

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

Chapter 1. Introduction

Publican is a tool for publishing material authored in DocBook XML. This guide explains how to to create and build books and articles using publican. It is not a DocBook XML tutorial and concentrates solely on using the publican tools. See docbook.org for information about DocBook XML.

Publican began life as an internal tool used by Red Hat's Documentation Group (now known as Engineering Content Services). On occasion, this legacy is visible.

Design

Publican is a publication system, not just a DocBook processing tool. As well as ensuring your DocBook XML is valid, publican works to ensure your XML is up to publishable standard.

The Branding functionality allows you to create your own presentation rules and look, over-riding many parts of the default style to meet your publishing needs. Choices executed in code, however, are not changeable.

Entities, for example, can be validly defined in any XML file. However, to ensure the DTD declaration is present, valid and standardized, Publican rewrites the declaration in every XML file before it builds a book or article. Consequently, all entities declared in all XML files are lost. Publican, therefore, requires you define Entities in the Book_Name.ent file (see Section 3.3.7, “Book_Name.ent”).

As publishing workflows grow, unrestrained Entity definition leads to Entity duplication and other practices that cause maintenance difficulties. Consolidating Entity definitions in a single, predictable place alleviates these maintenance issues and helps the automation of the build process stay robust.

Entities also present an essentially insurmountable obstacle to quality translation (see Section 3.3.7, “Book_Name.ent”). Consequently, while we are not reducing the Book_Name.ent file's functionality, we are no longer considering requests to add functionality or features associated with Entity use.

Chapter 2. Branding

Publican uses brands to apply a consistent look and style to html and pdf output. Brands are collections of files installed to /usr/share/publican/Common_Content/brand/. Publican ships with one brand, common/.

Brands for JBoss, GIMP, Red Hat Enterprise Linux, Fedora and oVirt can be installed using yum install publican-brand.

Each currently available brand is distributed under a brand-specific license as follows:

Brand	License	Package	Comment
common	GFDL Version 1.2	publican	GPL compatible license. No options.
RedHat	OPL 1.0	publican-redhat	No Options.
Fedora	OPL 1.0	publican-fedora	No Options.
JBoss	OPL 1.0	publican-jboss	No Options.
oVirt	OPL 1.0	publican-ovirt	No Options.
GIMP	GFDL Version 1.2	publican-gimp	GPL compatible license. No options.

Table 2.1. Current Brands and their packages

To make a custom brand, use the brand with the license you wish to use as base for your new brand. If you want to use a different open source license, and none of the shipped brands are compatible with your license, submit a bug using Red Hat Bugzilla against the product fedora, component publican, and ask for a new brand to be shipped under that license.

Chapter 3. Using the publican package

3.1. Installing publican

3.2. Creating a Book

3.3. Files in the Book directory

3.3.1. The Makefile
3.3.2. Book_Info.xml
3.3.3. RPMs, Editions, Impressions and Versions
3.3.4. Author_Group.xml
3.3.5. Chapter.xml
3.3.6. Book_Name.xml
3.3.7. Book_Name.ent
3.3.8. Revision_History.xml

3.4. Adding Images

3.4.1. Big Test

3.5. Building a Book

3.6. Conditional Tagging

3.7. Pre-release software and draft documentation

3.7.1. Denoting pre-release software
3.7.2. Denoting draft documentation
3.7.3. Denoting draft documentation of pre-release software

This chapter describes—the process of installing the publican package, creating books, the main configuration files, example book files, and how to build a book.

3.1. Installing publican

To install publican:

Change to the root user: $ su -
Run the following command to install the publican package: # yum install publican publican-doc

There are several brand packages available for use with publican. Run the following command as the root user to install packages for building branded books:

# yum install publican-brand

Replace brand with redhat, fedora, jboss, ovirt, or gimp.

3.2. Creating a Book

Use the create_book command to create a new book. The create_book command creates all the necessary files to create a book.

The following is a list of valid options for the create_book command. Append these options to the end of the create_book command. For example, create_book --help, create_book --name New_Book, and so on:

--help: print a list of all create_book command options.
--man: view the publican manual page. The manual page contains the same information returned by the create_book --help command.
--name Book_Name: replace Book_Name with the name of the book or article. This variable must not contain any spaces. For example, running the create_book --name Test_Book command creates a book named Test_Book, and all the necessary files to build the book. This updates the Makefile with the correct DOCNAME, and the Book_Name.ent file with the correct BOOKID.
--version version: replace version with the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use 5.1. The default version is 0.1. Using --version version updates the <issuenum></issuenum> tags in the Book_Info.xml file. For more information see Section 3.3.2, “Book_Info.xml”.
--edition edition: replace edition with the edition number of the book. This number indicates to users when a new edition of the book is released. The initial GA release of the book should be edition 1.0. The default value is 0. Using --edition edition updates the <edition></edition> tags in the Book_Info.xml file. For more information see Section 3.3.2, “Book_Info.xml”.
--product Product_Name: replace Product_Name with the product name. This variable must not contain any spaces. Set this to Fedora for core Fedora documentation, and the name of the product for other products, for example, Fedora_Directory_Server. The --product Product_Name option updates the Makefile and the Book_Name.ent file with the correct product name.
--type Article --name Article_Name: create an article instead of a book. Replace Article_Name with the article name. This variable must not contain any spaces.
--brand brand: replace brand with RedHat, fedora, JBoss, oVirt, or GIMP. This requires the appropriate publican package to be installed. For example, to build Red Hat branded books, you must install the publican-redhat package. See Section 3.1, “Installing publican” for instructions on installing the branded publican packages. If no brand is specified, the default brand is used.

Before running the create_book command, use the cd command to change into the directory where you want the book to be created. For example, to create a book named Test_Book in the /my/books/ directory, run the following commands:

cd /my/books/

create_book --name Test_Book

To see the results of this command, run the following:

ls

The output should be similar to the following:

en-US  Makefile

3.3. Files in the Book directory

Running the create_book --name Book_Name command will create a directory structure and the required files, similar to the following:

Figure 3.1. directory structure

3.3.1. The Makefile

The Makefile is used to configure build options, and is located in the root of the book directory. The following is an example Makefile, with instructions following afterwards:

#Makefile for MYBOOK

XML_LANG	= en-US
BRAND		= common

#OTHER_LANGS	= as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW

# Extra Parameters start here

# Extra Parameters stop here
COMMON_CONFIG  = /usr/share/publican
include $(COMMON_CONFIG)/make/Makefile.common

XML_LANG: set this to the language of the source xml files, for example, en-US.
BRAND: set the brand of the book. Accepted values are RedHat, fedora, JBoss, oVirt and GIMP. If no brand is specified, the default brand is used.
Running the create_book --name Book_Name --brand brand command correctly configures the BRAND.
OTHER_LANGS: space-separated list of other language locales. Used to specify other language locales to build the book in.

The following is an example Makefile that includes translations:

XML_LANG       = en-US
BRAND	       = RedHat

OTHER_LANGS    = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW
	
COMMON_CONFIG  = /usr/share/publican
include $(COMMON_CONFIG)/make/Makefile.common

Note

OTHER_LANGS is no longer commented out.

Note

Run the make help_params command in the root directory of a book for a full list of parameters that can be set in the Makefile.

3.3.2. Book_Info.xml

The Book_Info.xml file contains the key meta-data concerning a book: the book's ID; title; subtitle; author and edition number. It also contains the name and version of the product the book is about and an abstract.

Aside from, as you'd expect, constituting much of a book's front matter, this meta-data is also used when building books as RPMs. Consequently, if you wish to distribute a book as a .rpm file, several of the tags included by default in Book_Info.xml must have appropriate data within them, and that data must conform to the requirements of the RPM format.

Data from seven of the default tags in Book_Info.xml is required to build books as RPMs. Most immediately, the file name of a book built as an RPM is constructed as follows: productname-title-productnumber-language-edition-pubsnumber.src.rpm. Everything but language above is pulled from Book_Info.xml. (Language is supplied by the user at make time.) As well, the subtitle and abstract are used in the rpm spec file.

An example Book_Info.xml file, for the Test_Book book, is presented below. Details regarding this file, and what the RPM format requirements are for each tag, follow.

<?xml version='1.0'?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<bookinfo id="MYBOOK-MYPRODUCT">
	<title>MYBOOKNAME</title>
	<subtitle>short descriptor</subtitle>
	<productname>MYPRODUCTNAME</productname>
	<productnumber>0.0</productnumber>
	<edition>0.0</edition>
	<pubsnumber>0</pubsnumber>
	<abstract>
		<para>A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the #description field of the book's RPM spec file.</para>
	</abstract>
	<corpauthor>
		<inlinemediaobject>
			<imageobject>
				<imagedata format='SVG' fileref="Common_Content/images/title_logo.svg" />
			</imageobject>
			<textobject><phrase>Logo</phrase></textobject>
		</inlinemediaobject>
	</corpauthor>
	<copyright>
		<year>&YEAR;</year>
		<holder>&HOLDER;</holder>
	</copyright>
	<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>

<bookinfo id="book_id">: The Book ID is used internally and is not displayed to end users when the book is built. If you run the make clean_ids command, any manually entered ID, including this one, will be changed to a Book_Name-Title format, where Title is the title of the associated book, article, section, or chapter.
<productname>productname</productname>: The name of the product or product stream the book is about (for example: Red Hat Enterprise Linux or JBoss Enterprise Application Platform). When building a book as an RPM, data in the <productname> tag is used as part of the filename of the resultant .rpm file.
Important
Because data in this tag also appears as part of the .rpm filename, this field can only contain upper- and lower-case un-accented letters and the underscore and space characters (ie ‘a–z’, ‘A–Z’ and ‘_’ and ‘ ’).
<title>title</title>: Obviously enough, the book's title (for example, Server Configuration Guide). The title appears under the product name in both HTML and PDF editions. A title is required to build an RPM. When building a book as an RPM the title is used as the part of the file-name of the RPM package.
Important
Because data in this tag also appears as part of the .rpm filename, this field can only contain upper- and lower-case un-accented letters and the underscore and space characters (ie ‘a–z’, ‘A–Z’ and ‘_’ and ‘ ’).
<subtitle>subtitle</subtitle>: Again, plainly enough, the subtitle tag contains a book's subtitle: an alternative, and commonly explanatory title for the book (for example: Server Configuration Guide: Preparing Red Hat Enterprise Linux for Production Use). The subtitle appears under the title in both HTML and PDF editions. A subtitle is also required to make a book available as an RPM. When building a book as an RPM, the subtitle is used as the Summary in the RPM spec file. The rpm -qi returns the contents of several spec file fields, including the Summary field.
<productnumber>productnumber</productnumber>: The version number of the product the book covers, for example ‘5.2’ for Red Hat Enterprise Linux 5.2 and ‘4.3’ for JBoss EAP 4.3.
Running the create_book --name Book_Name --version version command correctly configures the product number.
Important
Because data in this tag is used in the RPM spec file, this tag can only contain numbers and the full stop or period (ie ‘0–9’ and ‘.’).
<edition>edition</edition>: This is the edition number of the book. The first edition of the book should be 1.0 (you may like to use 0.y for pre-release versions of a book). Subsequent editions should increment the 1.y to indicate to readers that the book is a new edition. The edition changes the first two digits of the version number in the .rpm filename when building a book with the tar or srpm options.
For example, setting the edition to 1.2 and building the book using the make srpm-en-US command, would create an RPM file named productname-title-productnumber-en-US-1.2-0.src.rpm.
Running the create_book --name Book_Name --edition x.y command correctly configures the edition.
Important
Because data in this tag sets the Version in the RPM spec file, this tag can only contain numbers and the full stop or period (ie ‘0–9’ and ‘.’).
<pubsnumber>pubsnumber</pubsnumber>: The pubsnumber changes the release number (the last digit) when building a book with the tar or srpm options. For example, setting the pubsnumber to 1 and building the book using the make srpm-en-US command, would create an RPM file named productname-title-productnumber-en-US-edition-1.src.rpm.
Important
Because data in this tag sets the Release in the RPM spec file, this tag can only contain numbers (ie ‘0–9’).
<abstract><para>abstract</para></abstract>: A short overview and summary of the book's subject and purpose, traditionally no more than a paragraph long. The abstract appears before the table of contents in HTML editions and on the second page of PDF editions. When a book is built as an RPM, the abstract sets the Description field of the RPM's spec file. This makes the abstract for a package available via the rpm -qi.

3.3.3. RPMs, Editions, Impressions and Versions

As noted above, the default Book_Info.xml used by Publican includes an <edition> tag.

If you distribute a book as an RPM package, the data placed within this tag sets 'the first two digits of the version number in the .rpm filename'.

So, an edition of '1.0' becomes a version of '1.0'.

Book_Info.xml also includes the <pubsnumber> tag. Any data placed within this tag changes the release number of RPM-packaged books.

A book with an edition of 1.0 and a pubsnumber of 5, would be version 1.0, release 5 (1.0-5).

The edition and pubsnumber are not tied to the <productnumber> tag also found in Book_Info.xml: productnumber denotes the version number of the product being documented or otherwise written about.

It is entirely possible to have a 2nd edition of a book pertaining to a particular version of a product.

In Bibliography, two copies of a book are the same edition if they are printed using substantially the same type-set master plates or pages. ('Substantially' offers some wiggle room for typo corrections and the like.)

Book collectors routinely conflate 'first edition' with 'first print run', while Bibliographers pay attention to the text commonly placed in the front matter of a book, which calls a 2nd print run off the same (or substantially the same) plates a '1st edition, 2nd impression' or '1st edition, 2nd printing'.

We recommend following Bibliographic practice in this regard. When using Publican to re-publish a book from 'substantially the same XML', increment the <pubsnumber> tag, not the <edition> tag. It functions as a near-equivalent to the impression or printing number of traditional publishing.

As for changing the Edition number, we recommend changing this in the same circumstances traditional publishers change the edition of a work: when it is revised and re-written significantly. What constitutes significant, and how much re-writing is needed to increment an Edition number by a whole number and how much is needed to increment it by one-tenth of a whole number, is a matter of editorial discretion.

3.3.4. Author_Group.xml

Author_Group.xml is not required but is the standard place to record author, editor, artist and other credit details. The following is an example Author_Group.xml file:

<?xml version='1.0'?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<authorgroup>
	<corpauthor>FF0000 Headgear Documentation Group</corpauthor>
	<author>
		<firstname>Dude</firstname>
		<surname>McDude</surname>
		<affiliation>
			<orgname>My Org</orgname>
			<orgdiv>Best Div in the place</orgdiv>
		</affiliation>
		<email>dude.mcdude@myorg.org</email>
	</author>
</authorgroup>

Author_Group.xml does not have to contain all of the above information: include as much or as little as required.

If you do not want or need Author_Group.xml included in a book, delete the following line from Book_Info.xml before building:

<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

3.3.5. Chapter.xml

The Chapter.xml file is a template for creating chapter files. Chapter files contain the content that make up a book. The following is a chapter template (Chapter.xml) that is created after running the create_book command. Note the DOCTYPE is set to chapter:

<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="MYBOOK-Test">
	<title>Test</title>
	<para>
		This is a test paragraph
	</para>
	<section id="MYBOOK-Test-Section_1_Test">
		<title>Section 1 Test</title>
		<para>
			Test of a section
		</para>
	</section>
	
	<section id="MYBOOK-Test-Section_2_Test">
		<title>Section 2 Test</title>
		<para>
			Test of a section
		</para>
	</section>

</chapter>

This chapter has two sections, Section 1 Test and Section 2 Test. Please refer to http://docbook.org/tdg/en/html/chapter.html for further information about chapters.

Note

The chapter file should be renamed to reflect the chapter subject. For example, a chapter on product installation could be named Installation.xml, whereas a chapter on setting up a piece of software would be better called Setup.xml or Configuration.xml.

3.3.6. Book_Name.xml

The Book_Name.xml file contains xi:include directives to include the chapters for a book. Chapters are contained in separate XML files, and the Book_Name.xml file brings them together into a single book.

The following is an example Book_Name.xml file. Note the DOCTYPE is set to book.

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<book>
	<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<index />
</book>

This example loads the Book_Info.xml, Preface.xml, Chapter.xml, and Appendix.xml XML files.

Important

The order in which chapters are listed matters. When this example book is built, Book_Info.xml will precede Preface.xml which will precede Chapter.xml, and so on.

The Book_Name.xml file is not limited to using xi:include directives. Books can be created using a single XML file. The following is an example of a book created using a single XML file:

<book>

<chapter>
<title>Chapter 1</title>
	<para>
		A paragraph in Chapter 1.
	</para>
	<section id="section1">
	<title>Chapter 1 Section 1</title>
		<para>
			A paragraph in Section 1.
		</para>
	</section>
	<section id="section2">
	<title>Chapter 1 Section 2</title>
		<para>
			A paragraph in Section 2.
		</para>
	</section>
</chapter>

<chapter>
<title>Chapter 2</title>
	<para>
		A paragraph in Chapter 2.
	</para>
</chapter>

</book>

This book contains two chapters. Chapter one contains two sections. Please refer to http://docbook.org/tdg/en/html/section.html for further information about sections, and http://docbook.org/tdg/en/html/book.html for further information about books.

3.3.7. Book_Name.ent

The Book_Name.ent file is used to define local entities. The YEAR and HOLDER entities are used for copyright information. You must define YEAR and HOLDER entities, otherwise the book will not build:

<!ENTITY PRODUCT "MYPRODUCT">
<!ENTITY BOOKID "MYBOOK">
<!ENTITY YEAR "2008">
<!ENTITY HOLDER "YOUR NAME GOES HERE">

Important

Entities offer convenience but they should be used with extreme caution. Writing (for example) &FDS; instead of Fedora Directory Server saves the writer time but transformed entities do not appear in .po files. Complete translations of documents containing entities are, as a consequence, impossible.

If you define an entity — <!ENTITY LIFT "Liberty Installation and Formatting Tome"> — you can enter &LIFT; in your XML and it will appear as The Secret to Eternal Life every time the book is built to HTML, PDF or Text.

Entities are not transformed when XML is converted to PO, however. Which means translators never see Liberty Installation and Formatting Tome. Instead they see &LIFT;, which they cannot translate.

Consider something as simple as the following English sentence fragment being translated into a related language: German.

As noted in the Liberty Installation and Formatting Tome, Chapter 3…

A translation of this might be as follows:

Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…

Because there is no text missing, the title can be translated into elegant German, avoiding the multi-syllabic mega-word syndrome. Also, note the use of ‘in dem’, the correct pronoun when referring to a Wälzer (tome).

By contrast, if entities are used, the English would be

As noted in the &LIFT;, Chapter 3…

The translation of this would probably run thus:

Wie in &LIFT;, Kapitel 3, erwähnt…

And the presentation would be thus:

Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…

This, of course, leaves the title in English, including words like Tome and Formatting that are unlikely to be understood. Also, the translator is forced to use the pronoun ‘in’, a more general construction that comes close to Denglisch or Angleutsch. Many German speakers consider this approach incorrect and almost all consider it inelegant.

Equivalent problems emerge with a fragment such as this:

However, a careful reading of the Liberty Installation and Formatting Tome afterword, shows that…

With no text hidden behind an entity, a German translation of this might be:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…

If an entity was used to save the writer time, the translator has to deal with this:

However, a careful reading of the &LIFT; afterword, shows that…

And the translation would be subtly but importantly different:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für &LIFT;, dass…

When presented to a reader, this would appear as follows:

Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…

Again, note the missing pronoun, ‘den’. This is inelegant but necessary since the translator can otherwise only guess which pronoun (der, die or das) to use, which would inevitably lead to error.

Now multiply such problems by the 22 languages Publican currently supports. Using entities for anything other than the few non-translated strings currently supported is arguably a conscious effort to inhibit and reduce the quality of translations.

3.3.8. Revision_History.xml

The make searches for the first XML file in the $(XML_LANG) directory containing a revhistory tag. Publican then uses that file to build the RPM revision history.

Important

All dates must be in the correct RPM format, other formats will break the spec file creation.

Mon Aug 4 2008

3.4. Adding Images

Use the images subdirectory in the en-US/ directory to store images. Use ./images/image-name to insert images into a book. The following is an example that inserts the testimage.png image:

<mediaobject>
	<imageobject>
		<imagedata fileref="./images/testimage.png" />
	</imageobject>
	<textobject><phrase>alternate text goes here</phrase></textobject>
</mediaobject>

Image File Locations

The build system only uses images in the en-US/images subdirectory. Other directories do not work.

3.4.1. Big Test

Tester

3.5. Building a Book

To build a book:

Confirm the YEAR and HOLDER entities have been configured in the Book_Name.ent file, as per Section 3.3.7, “Book_Name.ent”.
Change into the root directory of the book. For example, if the book was named Test_Book and was located in the /books/ directory, run the following command:
```
cd /books/Test_Book
```
Run the following command to check for any errors that would stop the book from building:
```
make test-en-US
```
Run the following command to build the book:
```
make format-en-US
```
Replace format with the desired format, for example, html.

The following table lists commonly used make commands:

Command	Result
`make help`	List available `make` commands for building a book.
`make help_params`	List available parameters that can be set in the `Makefile`.
`make test-en-US`	Check that the book can be built correctly. Run the `make test` command before running any other `make` command, and before checking a book back into a repository (i.e. CVS or SVN).
`make html-en-US`	Build the book in HTML format. The HTML output will be located in the `Book_Name/tmp/en-US/html/` directory.
`make html-single-en-US`	Build the book HTML format. The output will be a single HTML file located in the `Book_Name/tmp/en-US/html-single/` directory.
`make htmlhelp-en-US`	Build the book in HTML HELP format. HTML HELP is a limited form of HTML, designed to be viewed regardless of your platform or Web browser. The output is located in the `Book_Name/tmp/en-US/htmlhelp/` directory.
`make pdf-en-US`	Build the book in PDF format. This may not be supported on all systems.
`make clean`	Remove all files and folders in the `tmp/` subdirectory. The `tmp/` subdirectory is created after running a `make` command to build a book, such as `make html`.
`make web-srpm-en-US`	Create a source RPM to generate web based documentation RPMs from.
`make clean_ids`	Change all IDs to a standard format. This format is `Book_Name-title`. For example, a section with a title of `First Section` in a book named `Test_Book` will have the following ID after running `make clean_ids`: `<section id="Test_Book-First_Section">`

Warning: `make clean_ids`

To make translation easier, make clean_ids uses the first four characters of the tag as a prefix for the ID. Consequently, you must check out the latest versions of the xml source and translations before running this command.

Failing to have the po files checked out before running make clean_ids causes the XML and po files to slip out of sync. And this means all links in the po files have to be manually updated.

3.6. Conditional Tagging

In some cases you may need to maintain multiple versions of a book; for example, a HOWTO guide for product FOO can have an upstream version and an enterprise version, with very subtle differences between them.

Publican makes it easy to manage differences between multiple versions of a book by allowing you to simply use one source for all versions. Conditional tagging allows you to make sure that version-specific content only appears in the correct version; i.e. "conditionalizing content".

To conditionalize content in a book, use the tag attribute condition. For example, let's say the book How To Use Product Foo has an "upstream", "enterprise", and "beta" version:

<para condition="upstream">
This paragraph will only appear in the upstream version of How To Use Product Foo.
</para>
	
<para condition="enterprise">
This paragraph will only appear in the enterprise version of How To Use Product Foo.
</para>	
	
<para condition="beta">
This paragraph will only appear in the beta version of How To Use Product Foo.
</para>
	
<para condition="beta,enterprise">
This paragraph will only appear in the beta and enterprise versions of How To Use Product Foo.
</para>

To build a specific version (thereby capturing all content conditionalized for that version), use make parameter CONDITION="version" format. Using the same example for the book How To Use Product Foo, you can build the "upstream" version of the book in pdf using:

make CONDITION="upstream" pdf-en-US

This will capture all tags that use condition="upstream" and build How To Use Product Foo in PDF format.

Note

You can conditionalize content as per the BRAND setting. To do so, add the following line to Makefile:

CONDITION=$(BRAND)

In this manner, make CONDITION="brand1" pdf-en-US will build the book in PDF and capture all tags that use the condition="brand1" attribute.

Further, if an <xref> points to content that is not going to be included in the build due to conditional tagging, the build will fail. For example, make CONDITION="upstream" pdf-en-US will fail if the book has the tag <xref linkend="betasection" pointing to <section id="betasection" CONDITION="beta">.

3.7. Pre-release software and draft documentation

Completed documentation for pre-release software is not the same thing as draft documentation.

Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.

In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.

3.7.1. Denoting pre-release software

Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.

To create that mark do the following:

Add the software's pre-release version number, or equivalent state information, to the subtitle in your Book_Info.xml file. Place this additional text in <remark> tags. For example:
```
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
```
add SHOW_REMARKS to the Makefile and set it to '1':
```
SHOW_REMARKS = 1
```

When your book is built with this text and setting, the software's status is displayed in clear and unmistakable fashion. PDF builds display the remark on their cover and title pages. HTML builds (both html and html-single) display the remark near the beginning of index.html

Because this approach makes no changes to the information in Book_Info.xml used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.

Important

It is the writer's responsibility to remove the <remark> tag and its contents and remove or turn off SHOW_REMARKS when documentation is updated for use with the release version of the software.

3.7.2. Denoting draft documentation

Unfinished documentation made available to others for review should be labeled clearly as such.

To add the draft watermark to your documentation add the status="draft" attribute to the <article>, <book> or <set> tag in your document's root node. For example:
```
<book status="draft">
```

By default, your root node is the <book> tag in your [book_name].xml file.

If you are working on an article or set, the root node is the <article> or <set> tag in [book_name].xml.

Adding the status="draft" attribute causes each page of the document to show the draft watermark. This is by design.

Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.

3.7.3. Denoting draft documentation of pre-release software

To denote unfinished documentation of pre-release software properly simply do both previously noted procedures.

A set is a collection of books, published as a single output. The Services Plan for example is a Set comprised of many books such as the Developer Guide, Engineering Content Services Guide and the Engineering Operations Guide to name just a few. The create_book command creates a template for a set by setting the type parameter to Set. There are two types of sets, Stand-alone Sets and Distributed Sets.

4.1. Stand-alone Sets

A stand-alone set contains the xml files for each book, all of which are located inside the directory of the set.

The procedure that follows will guide you through the process of creating a stand-alone set named My Set located in a directory called books/My_Set/. The set will contain Book A and Book B both of which will be manually created inside the books/My_Set/en-US directory.

Procedure 4.1. Creating a Stand-alone Set

Run the following command in a shell in the books/ directory to create a set named My_Set branded in the Red Hat style.
```
create_book --type=Set --name=My_Set --brand=RedHat
```
cd into the My_Set/en-US directory and create two directories called Book_A and Book_B.
```
cd My_Set/en-US
mkdir Book_A Book_B
```
cd into the books/My_Set/en-US/Book_A directory. Create and edit the Book_A.xml, Book_Info.xml, and any other xml files required for your book such as those required for individual chapters. Ensure that Book_A.xml contains the correct xi:include references to all of your xml files in the directory. For example, if Book A contained Book_Info.xml and Chapter_1.xml, the Book_A.xml file would look like this:
```
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
	  
<book>
	  <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
	  <xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</book>
```
Use the same process for Book_B, located in the books/My_Set/en-US/Book_B directory, as per the step above.

Open the books/My_Set/en-US/My_Set.xml file in an editor. For each book in the set, add an xi:include reference to the primary xml file from the book. The primary xml file for Book A will be Book_A.xml and for Book B, Book_B.xml. The My_Set.xml file should now look like this:

<?xml version="1.0"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<set>
	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</set>

Test your set by running the make test-en-US command.

4.2. Distributed Sets

A Distributed Set contains books that are located in SVN. By setting the repository location and titles of the included books in the Makefile, each book can be exported to build the entire set. The procedure that follows will guide you through the process of creating a set named My Set containing Book A and Book B.

Important

The following procedure assumes that Book A and Book B already exist and are available in your SVN repository. Currently publican only supports SVN.

Procedure 4.2. Creating a Set

Run the following command in a shell to create a set named My_Set branded in the Red Hat style.
```
$ create_book --type=Set --name=My_Set --brand=RedHat
```

Uncomment the following lines in the Makefile from:

#BOOKS		= My_Other_Book His_Book Her_Book Their_Book
#SET_REPO	= http://svn.repo.com/repos/project
#SET_REPO_TYPE	= SVN
...
#pre:: get_books set_books
#clean:: clean_set_books

to :

BOOKS 		= Book_A Book_B
SET_REPO	= http://PATH-TO-YOUR-SVN-REPOSITORYSET_REPO_TYPE	= SVN
...
pre:: get_books set_books
clean:: clean_set_books

Open the My_Set.xml file in an editor. For each book in the set, add an xi:include reference to the primary xml file from the book. The primary xml file for Book A will be Book_A.xml and for Book B, Book_B.xml. The My_Set.xml file should now look like this:

<?xml version="1.0"?>
<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<set>
	<xi:include href="Set_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_A/Book_A.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Book_B/Book_B.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</set>

Test your set by running the make test-en-US command.
Important
When building a set, the make clean_ids command will be run over each book because of the constraint that ID's must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.

Chapter 5. Frequently Asked Questions

Q: How do I add a language to my book?
Q: How do I add another language to my book?
Q: What if I only use the country code? For example, OTHER_LANGS = en de fr?
Q: How do I update all po files?
Q: Where can I get a complete list of make targets?
Q: Where can I get a complete list of parameters that can be set in the Makefile?
Q: Where are the Publican common files located?
Q: Can I use the OASIS DocBook DTD for XML completion in editors such as Kate?
Q: I have extensive code samples for my book, how can I include them without having to xml escape everything?
Q: Is it possible to include arbitrary files in tar and RPM files?
Q: Why does publican give me warnings about unknown tags?
Q: How do I find out which tags have been tested in publican?
Q: Why does publican give me an error about banned tags?
Q: How do I find out which tags are banned in publican?
Q: Which brands enable STRICT mode?
Q: I get an error saying Batik is not in the classpath but batik is installed! What is wrong?
Q: I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
Q: Why does Jeff call Isaac Ivan?

How do I add a language to my book?

Edit your book's Makefile and uncomment the OTHER_LANGS entry. Add the required language code after the '=' sign.

How do I add another language to my book?

Append the language to OTHER_LANGS in the Makefile. Run the make update-po-language command. For example, make update-po-ja-JP creates the Japanese language directory and the Japanese po files.

What if I only use the country code? For example, OTHER_LANGS = en de fr?

Run the make update-po-en command.

How do I update all po files?

Run the make update-po-all command.

Where can I get a complete list of make targets?

Run the make help command.

Where can I get a complete list of parameters that can be set in the Makefile?

Run the make help_params command.

Where are the Publican common files located?

By default, they are in /usr/share/publican/.

Can I use the OASIS DocBook DTD for XML completion in editors such as Kate?

Yes. The OASIS DocBook DTD is included in the publican package, and is located here: /usr/share/publican/xsl/docbook.dtd.xml

I have extensive code samples for my book, how can I include them without having to xml escape everything?

The best way to do this is to create a directory named extras in your source language directory and use an xi:include to pull in the code file.

Procedure 5.1. Including code samples

Create the extras directory
```
mkdir en-US/extras
```
Copy the code file to the extras directory
```
cp ~/samples/foo.c en-US/extras/.
```

xi:include the sample file in your xml file

<programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>

You can now edit en-US/extras/foo.c in your favorite editor without having to be concerned about how it will affect the XML.

Is it possible to include arbitrary files in tar and RPM files?

Yes. If you make a directory named files in your source language directory it will be included in any tar or SRPM files created by publican.

Important

The files directory will not be available during the validation process so you can not xi:include or otherwise embed any files in this directory in your XML.

Why does publican give me warnings about unknown tags?

This warning informs you that you are using a tag whose output has not been tested for attractiveness, XHTML 1.0 Strict compliance, or Section 508 (Accessibility) compliance.

How do I find out which tags have been tested in publican?

Run xmlClean --known

Why does publican give me an error about banned tags?

This error indicates that the brand you are using has STRICT mode enabled for xmlClean and that the tag in question has been marked as undesirable. The error message should contain a reason why the tag was banned.

How do I find out which tags are banned in publican?

Run xmlClean --banned

Which brands enable STRICT mode?

Currently the Red Hat and JBoss brands enable STRICT mode.

I get an error saying Batik is not in the classpath but batik is installed! What is wrong?

We believe this is due to classpath issues caused by having different JRE and JDK versions installed. Sometimes this can be fixed by upgrading your JDK to the same version of your JRE.

Sometimes this issue can be revealed by running alternatives --config java and alternatives --config javac, if the versions are different then selecting the same version in both can fix this problem.

Some Java installs do not set-up the alternatives environment correctly, no fix has been determined for this situation.

I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?

The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to FOP. Before running make run echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc. This sets the initial heap space to 50MB and allows it to grow to a maximum of 700MB.

Why does Jeff call Isaac Ivan?

Because Jeff's memory is pants!

Makefile Parameters

Every Book, Article or Book Set has a Makefile in its root directory. Parameters that can be set in a Book's Makefile are:

BOOKS: This defines the Books a Set contains. It is only useful for Book Sets.
Default value: Undefined.
BRAND: This parameter tells Publican which Brand to apply to a book's html and pdf output. Its default value is: common.
BREW_DIST: BREW_DIST sets the Brew tag for desktop RPMs. Default: dist-5E-qu-candidate.
CHUNK_FIRST: Controls chunking of first sections. 0 or 1. Default: 0.
CHUNK_SECTION_DEPTH: Override the max section depth to chunk to. Default: 4.
COMMON_CONFIG: Sets the path to Publican's configuration and common files, including Brand files. Default: /usr/share/publican.
CONFIDENTIAL: The default value — 0 — is not confidential. To set a book to confidential, change this to 1.
Setting this parameter to 1 places a large Confidential footer on each page.
DEFAULT_LANGS: Languages that should be included in xi:include even if the translation is not complete. Used in update_includes. Default: Undefined.
DESKTOP: Use the desktop CSS (1) or not (0). Default: 0
DOC_TYPE: Sets the sort of publication being produced: Book, Article or Set. Default value is Book. This paremeter has no relationship to the DOCTYPE declaration in a publication's XML files.
DOC_URL: Sets the URL used for the link in the right-hand header of every html page. Also sets the URL entry in a publication's RPM spec file. Default: https://fedorahosted.org/publican
DT_OBSOLETES: A comma seperated list of desk top packages the package should obsolete. Default: undefined.
EMBEDTOC: Embed the web navigation TOC in the html. 0 or 1. Default: 0.
GENERATE_SECTION_TOC_LEVEL: Include a Table of Contents at the given section level. Valid values: 0 – 5. Default: 0.
IGNORED_TRANSLATIONS: When building, replace any languages in this list with the source langauge text. This allows you to work on translations without shipping incomplete translations. Default: Undefined.
OTHER_LANGS: Space seperated list of language locales. Default: Undefined.
PRODUCT: The product this book is associated with. Default: Documentation.
PROD_URL: Sets the URL used for the link in the left-hand header of every html page. Default: https://fedorahosted.org/publican
SHOW_REMARKS: Display contents of remark tags in output? Two possible values: 0 (off) or 1 (on). Off by default.
TOC_SECTION_DEPTH: How many section levels should be included in the main Table of Contents. Default: 2.
WEB_BREW_DIST: WEB_BREW_DIST sets the Brew tag for web RPMs. Default: docs-5E.
WEB_OBSOLETES: A comma seperated list of web site packages the web package should obsolete. Default: Undefined.
XML_LANG: Language of a publication's source xml. Default: en-US (US English).
USE_SAXON: Use saxon for xslt. Two possible values: 0 (off) or 1 (on). On by default.
USE_XALAN: Test xalan for xslt. 0 or 1. Default: 0.

Revision History

Revision History

Revision 0.5

Thu Dec 18 2008

Jeff Fearn

Added appendix on Makefile parameters

Added entry to FAQ about java heap space.

Revision 0.4

Tue Nov 25 2008

Brian Forté

Added "Pre-release and draft documentation" section.

Revision 0.3

Fri Oct 10 2008

Don Domingo

Adding "Conditional Tagging" section.

Revision 0.2

Fri Sep 05 2008

Brian Forté

General edits and updates related to Publican 0.36 release. Also, new section added to Chapter 3.3.

Revision 0.1.1

Fri Jun 06 2008

Murray McAllister

Updated Branding to note addition of oVirt and GIMP brands

Revision 0.1

Tue May 16 2008

Jeff Fearn

Updated FAQ

Revision 0.0

Thu Dec 13 2007

Murray McAllister

Initial content release

Users Guide

Publishing books, articles, papers and multi-volume sets with DocBook XML

Logo

Don Domingo

Brian Forté

Murray McAllister

Joshua Oakes

Joshua Wulf

Edited by

Brian Forté

Jeff Fearn

Legal Notice

Abstract

Preface

1. Document Conventions

1.1. Typographic Conventions

1.2. Pull-quote Conventions

1.3. Notes and Warnings

Note

Important

Warning

2. We Need Feedback!

Chapter 1. Introduction

Design

Chapter 2. Branding

Table 2.1. Current Brands and their packages

Chapter 3. Using the publican package

3.1. Installing publican

3.2. Creating a Book

3.3. Files in the Book directory

Figure 3.1. directory structure

3.3.1. The Makefile

Note

Note

3.3.2. Book_Info.xml

Important

Important

Important

Important

Important

3.3.3. RPMs, Editions, Impressions and Versions

3.3.4. Author_Group.xml

3.3.5. Chapter.xml

Note

3.3.6. Book_Name.xml

Important

3.3.7. Book_Name.ent

Important

3.3.8. Revision_History.xml

Important

3.4. Adding Images

Image File Locations

3.4.1. Big Test

3.5. Building a Book

Warning: make clean_ids

3.6. Conditional Tagging

Note

3.7. Pre-release software and draft documentation

3.7.1. Denoting pre-release software

Important

3.7.2. Denoting draft documentation

3.7.3. Denoting draft documentation of pre-release software

Chapter 4. Using Sets

4.1. Stand-alone Sets

Procedure 4.1. Creating a Stand-alone Set

4.2. Distributed Sets

Important

Procedure 4.2. Creating a Set

Important

Chapter 5. Frequently Asked Questions

Procedure 5.1. Including code samples

Important

Makefile Parameters

Revision History

Warning: `make clean_ids`