Publican

Users Guide

Red Hat Documentation Group

Joshua Oakes

Red Hat
 Engineering Content Services

Murray McAllister

Red Hat
 Engineering Content Services

Joshua Wulf

Red Hat
 Engineering Content Services

Edited by

Brian Forté

Red Hat
 Engineering Content Services

Jeff Fearn

Extensive review and rough drafts.  
Engineering Operations Logo
Red Hat
 Engineering Operations

Copyright © 2007 Red Hat, Inc.

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
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. Using Sets
4.1. Stand-alone Sets
4.2. Distributed Sets
5. Frequently Asked Questions
A. Revision History
B. Man Page: TEST
ls — list contents of a directory

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.

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.

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.

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.6, “ 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.

If there is sufficient demand to add conditions or over-ride this and other choices designed to improve and maintain the published standard of material, we will consider requests to add such functionality.

Publican allows users to brand books by changing colours and logos. Publican ships with a default brand, common, and five other Brands. Each brand is distributed under a brand-specific 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.
oVirt OPL 1.0 + Restrictions publican-ovirt No substantively modified versions, No commercial purposes.
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 Red_Hat_Enterprise_Linux , component publican, and ask for a new brand to be shipped under that license.

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.

To install publican:

  1. Change to the root user: 

    $ su -
Password:

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

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.

--revision revision

replace revision with the revision number of the book. This number indicates to users when a new revision of the book is released. The initial GA release of the book should be revision 1.0. 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, 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

Directory Structure

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

directory structure
Figure 3.1. directory structure

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
DOCNAME		= MYBOOK
#PRODUCT	= FIX_ME!
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.

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.

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.

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

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.

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="MYBOOK-Product_Name_and_Version">
	<title>Product Name and Version</title>
	<subtitle>MYBOOKNAME</subtitle>
	<issuenum>0.0</issuenum>
	<productnumber>0</productnumber>
	<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. 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>

The name of the product or product stream, for example: "Red Hat Enterprise Linux" or "JBoss Enterprise Application Platform". Replace title with the title of the book. Remove the <title> tags to remove the title.

<subtitle> subtitle </subtitle>

The title of the actual book, for example: "Server Configuration Guide". The subtitle appears under the title when the book is built. 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>

The version number of the product to which the book applies, for example "5.1" for Red Hat Enterprise Linux 5.1, 4.3 for JBoss EAP 4.3. If your book does not apply to a product then you can put whatever you like. 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-en-US 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>

This is the edition number of the book. The first edition of the book should be 1.0 (you may like to use 0.x for alpha and beta releases). Subsequent revisions should increment the 1.x to indicate to readers that the book is a revised edition. 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-en-US 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>

A brief description of the subject of a book that appears before the main body of text in html and pdf output. This paragraph indicates to the reader in a general sense what the book covers, and allows them to evaluate whether or not they need or want to read it, without having to scan the entire book. It is also used in the rpm description, which allows people installing packages to do the same thing before installing a documentation package. 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.

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'?>

<authorgroup id="foo">
	<corpauthor id="fubar" lang="en">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>

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

Delete the following line from Book_Info.xml to prevent author information being included in the built versions of a book: 

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

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.

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="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>

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

Note

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.

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 PRODUCT "MYPRODUCT">
<!ENTITY BOOKID "MYBOOK">

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.

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 will only use images in the en- US /images subdirectory. Other directories will not work.

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 following command to check for any errors that would stop the book from building: 

    make test-en-US

  4. 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 tar- format -en-US 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">

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.

As well, running make clean_ids removes all comments from the xml source.

4.1. Stand-alone Sets
4.2. Distributed Sets

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.

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

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

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

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

  4. Use the same process for Book_B, located in the books/My_Set/en-US/Book_B directory, as per the step above.

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

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

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

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

  2. 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-REPOSITORY
                           SET_REPO_TYPE	= SVN
...
pre:: get_books set_books
clean:: clean_set_books

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

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

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

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: Why does Jeff call Isaac Ivan?

How do I add a language to my book?

Edit your books 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 the /usr/share/publican directory.

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

  1. Create the extras directory 

                                           mkdir en-US/extras

  2. Copy the code file to the extras directory 

                                           cp ~/samples/foo.c en-US/extras/.

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

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

Warning

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.

Why does Jeff call Isaac Ivan?

Because Jeff's memory is pants!

Revision History
Revision 1.1.1 Friday June 06 2008 Murray McAllister
Updated Branding to note addition of oVirt and GIMP brands
Revision 1.1 Tuesday May 16 2008 Jeff Fearn
Updated FAQ
Revision 1.0 Thursday December 13 2007 Murray McAllister
Initial content release

Name

ls — list contents of a directory

Synopsis

/usr/bin/ls [ aAbcCdfFgilLmnopqrRstux1 ] [ file ...]

Description

For each file that is a directory, ls lists the contents of the directory; for each file that is an ordinary file, ls repeats its name and any other information requested.

…