Users Guide

Publican

Red Hat Documentation Group

Murray McAllister

Red Hat
 Engineering Content Services

Copyright © 2007 Red Hat, Inc.

Copyright © 2007 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, use, create, and publish Docbook XML books using the publican package.

Preface
1. Document Conventions
2. We Need Feedback!
1. Introduction
2. Branding
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. Author_Group.xml
3.3.4. Chapter.xml
3.3.5. Book_Name.xml
3.3.6. Book_Name.ent
3.4. Adding Images
3.5. Building a Book
4. FAQ
A. Revision History

Preface

1. Document Conventions

Certain words in this manual are represented in different fonts, styles, and weights. This highlighting indicates that the word is part of a specific category. The categories include the following:

Courier font

Courier font represents commands, file names and paths, and prompts .

When shown as below, it indicates computer output: 

Desktop       about.html       logs      paulwesterberg.png
Mail          backupfiles      mail      reports

bold Courier font

Bold Courier font represents text that you are to type, such as: service jonas start

If you have to run a command as root, the root prompt (#) precedes the command: 

# gconftool-2
italic Courier font

Italic Courier font represents a variable, such as an installation directory: install_dir/bin/

bold font

Bold font represents application programs and text found on a graphical interface.

When shown like this: OK , it indicates a button on a graphical application interface.

Additionally, the manual uses different strategies to draw your attention to pieces of information. In order of how critical the information is to you, these items are marked as follows:

Note

A note is typically information that you need to understand the behavior of the system.

Tip

A tip is typically an alternative way of performing a task.

Important

Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.

Caution

A caution indicates an act that would violate your support agreement, such as recompiling the kernel.

Warning

A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.

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: http://bugzilla.redhat.com/bugzilla/ against the product Red_Hat_Enterprise_Linux. 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

The publican package helps you build books in DocBook XML. This guide describes how to use publican to create and build books. This is not a DocBook XML tutorial, and concentrates only on using the publican tools.

Please visit http://docbook.org/tdg/en/html/docbook.html for more information about DocBook XML.

Chapter 2. Branding

Publican allows users to brand books by changing colours and logos. Publican ships with a default brand, common, and three other Brands. Each brand is distributed under a different license:

Brand License Package Comment
common GFDL Version 1.2 publican GPL compatible license. No options.
RedHat OPL 1.0 + Restrictions publican-redhat No substantively modified versions, No commercial purposes.
fedora OPL 1.0 publican-fedora No Options.
JBoss CC A-N-SA 3.0 publican-jboss Attribution, Noncommercial, Share Alike.
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 bugzilla against the product Red_Hat_Enterprise_Linux, 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. Author_Group.xml
3.3.4. Chapter.xml
3.3.5. Book_Name.xml
3.3.6. Book_Name.ent
3.4. Adding Images
3.5. Building a Book

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:

  1. Change to the root user: 

    $ su -
Password:

  2. Run the following command to install the publican package: 

    # yum install publican

As well, there are three branded publican packages available: redhat, fedora and jboss. Run the following command as the root user to build branded books: 

# yum install publican-brand

Replace brand with redhat, fedora, or jboss.

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 book. The default version is 0.1. Using --version version updates the <issuenum></issuenum> tags in the Book_Info.xml file.

--revision revision

replace revision with the revision number of the book. The default value is 0. Using --revision revision updates the <productnumber></productnumber> tags in the Book_Info.xml file.

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

--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, or JBoss. 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.

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

3.3. Files in the Book directory

Directory Structure

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

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: 

XML_LANG        = en-US
DOCNAME         = Test_Name
PRODUCT        = Test_Product
	
#OTHER_LANGS    = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN
TRANSLATIONS   = $(XML_LANG) $(OTHER_LANGS)
	
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.

DOCNAME

this must be set to the same name as the main book file, Book_Name.xml, otherwise the book will not build. This variable must not contain any spaces.

Running the create_book --name Book_Name command correctly configures the DOCNAME.

PRODUCT

the product the book is associated with. This variable must not contain any spaces. Set this to Fedora for core Fedora documentation. For other documentation, this will be the product, for example, Fedora_Directory_Server.

Running the create_book --name Book_Name --product Product_Name command correctly configures the PRODUCT.

TRANSLATIONS

list of language locales to build the book in. Specify additional languages using OTHER_LANGS, then add $(OTHER_LANGS) to TRANSLATIONS.

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
DOCNAME        = Test_Name
PRODUCT        = Test Product

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
TRANSLATIONS   = $(XML_LANG) $(OTHER_LANGS)
	
COMMON_CONFIG  = /usr/share/publican
include $(COMMON_CONFIG)/make/Makefile.common

Note that OTHER_LANGS is no longer commented out, and $(OTHER_LANGS) has been added to TRANSLATIONS.

make help_params

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 is used to set the book ID, title, subtitle, issue and product numbers, and an abstract which appears at the start of the book. The following is an example Book_Info.xml file for the Test_Book book, with instructions following afterwards: 

<?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="Test_Book-Product_Name_and_Version">
	<title>Product Name and Version</title>
	<subtitle>Test Book</subtitle>
	<issuenum>0.0</issuenum>
	<productnumber>0</productnumber>
	<abstract><para>This book is about... (Be brief; this para is used for the RPM spec
	file)</para>
	</abstract>
	<corpauthor>
		<inlinemediaobject>
			<imageobject>
				<imagedata fileref="Common_Content/images/title_logo.png" />
			</imageobject>
		</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">

replace book_id with an ID for the book; however, if you run the make clean_ids command, this ID along with all other IDs will be changed to a Book_Name-Title format, where "Title" is the title of the article, book, section, or chapter.

<title>title</title>

replace title with the title of the book. Remove the <title> tags to remove the title.

<subtitle>subtitle</subtitle>

replace subtitle with the subtitle of the book. The subtitle will appear under the title when the book is built. Remove the <subtitle> tags to remove the subtitle. A subtitle is required to build an RPM. When building a book as an RPM the subtitle is used as the Summary in the RPM spec file.

<issuenum>issue-number</issuenum>

replace issue-number with the issue number. The issue number changes the version number (the first two digits) when building a book with the tar or srpm options. For example, setting the issue number to 1.2 and building the book using the make srpm command, would create an RPM file named PRODUCT-DOCNAME-1.2-0.src.rpm. PRODUCT and DOCNAME are configured in the Makefile.

Running the create_book --name Book_Name --version version command correctly configures the issue number.

<productnumber>product-number</productnumber>

replace product-number with the product number. The product number changes the release number (the last digit) when building a book with the tar or srpm options. For example, setting the product number to 1 and building the book using the make srpm command, would create an RPM file named PRODUCT-DOCNAME-0.0-1.src.rpm. PRODUCT and DOCNAME are configured in the Makefile.

Running the create_book --name Book_Name --revision revision command correctly configures the product number.

<abstract><para>abstract</para></abstract>

replace abstract with the abstract for the book. The abstract appears before the table of contents when using HTML, and on the second page when using PDF. When building a book as an RPM the abstract is used as the description in the RPM spec file.

<year>&YEAR;</year>

The &YEAR; entity is defined in Book_Name.ent. Use this to set the copyright year of the book. Refer to Section 3.3.6, “Book_Name.ent” for configuration details.

<holder>&HOLDER;</holder>

The &HOLDER; entity is defined in Book_Name.ent. Use this to set the copyright holder of the book. Refer to Section 3.3.6, “Book_Name.ent” for configuration details. The copyright section is not required.

3.3.3. Author_Group.xml

Use the Author_Group.xml file to configure author details. This file is not required. 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>
		     Red Hat Documentation Group
 	</corpauthor>
	<author>
		<firstname>Murray</firstname>
	 	<surname>McAllister</surname>
		<affiliation>
		     <orgname>Red Hat</orgname>
		     <orgdiv>Engineering Content Services</orgdiv>
		</affiliation>
		<email>mmcallis@redhat.com</email>
	</author>
</authorgroup>

The Author_Group.xml file does not have to contain all of the above information: include as much or as little as required. The above Author_Group.xml file will create the following HTML output on the first page of the book:

Delete the following line from the Book_Info.xml file to remove the author information: 

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

3.3.4. 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="Test_Book-Test">>
	<title>Test</title>
	<para>
		A test paragraph.
	</para>
	<section id="Test_Book-Test-Section_1_Test">
		<title>Section 1 Test</title>
		<para>
			A paragraph in section 1.
		</para>
	</section>
	
	<section id="Test_Book-Test-Section_2_Test">
		<title>Section 2 Test</title>
		<para>
			A paragraph in section 2.
		</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 something significant to the subject of the chapter. For example, a file on installing a product might be named Installation.xml, whereas a file on how to setup a piece of software might be renamed to Setup.xml or Configuration.xml.

3.3.5. 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="Chapter1.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chatper2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="Chapter3.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	
</book>

This example loads the Book_Info.xml file, and the Chapter1.xml, Chapter2.xml, and Chapter3.xml files. Replace the ChapterX.xml files with the name of your chapter files.

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.6. Book_Name.ent

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

<!ENTITY YEAR "2008">
<!ENTITY HOLDER "Red Hat, Inc">

The YEAR and HOLDER entities are used for copyright information. Use entities to make writing commonly used terms quicker: 

<!ENTITY FDP "Fedora Documentation Project">
<!ENTITY FDS "Fedora Directory Server">

Two entities are defined: FDP and FDS. Instead of typing Fedora Documentation Project you can use &FDP;. The build system adds the required entities to the XML files at build time. In the example above, &FDP; would be replaced with Fedora Documentation Project.

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>
</mediaobject>

Image File Locations

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

3.5. Building a Book

To build a book:

  1. Confirm the YEAR and HOLDER entities have been configured in the Book_Name.ent file, as per Section 3.3.6, “Book_Name.ent”.

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

  3. Run the ls command in the root of a book directory. The output will be similar to the following: 

    en-US  Makefile

  4. Run the following command to check for any errors that would stop the book from building: 

    make test

  5. Run the following command to build the book: 

    make format

    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 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 Build the book in HTML format. The HTML output will be located in the Book_Name/tmp/en-US/html/ directory.
make html-single 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 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 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 tar-format Create a tar archive for the specified format. For example, running the make tar-html command creates a tar archive of the book in HTML format. The tar archive is located in the publish/en-US/Product_Name/book-version/tar/ directory.
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">

Table 3.1. Common make Commands

make clean_ids

Be careful running the make clean_ids command. To make translation easier, make clean_ids prepends the first four characters of the tag to the ID. Therefore you must ensure you have checked out the latest versions of the source and the translations before running make clean_ids. Failing to have the po files checked out when you run make clean_ids will result in the XML and po files becoming out of sync. This will require all links in the po files to be manually updated. As well, running make clean_ids will remove all comments!

Chapter 4. FAQ

The following is a list of frequently asked questions regarding the publican toolchain:

Q:

How do I add another language to my book?

A:

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 language directory and language specific po files.

Q:

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

A:

Run the make update-po-en command.

Q:

How do I update all po files?

A:

Run the make update-po-all command.

Q:

Where can I get a complete list of make targets?

A:

Run the make help command.

Q:

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

A:

Run the make help_params command.

Q:

Where are the publican common files located?

A:

By default they are in the /usr/share/publican directory.

Q:

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

A:

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

Appendix A. Revision History

Revision History
Revision 1.0 Thursday December 13 2007 Murray
 McAllister
Initial content release