Publican 0.99

Users Guide

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

Ausgabe 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

Herausgegeben von

Brian Forté

Red Hat Engineering Content Services

bforte@redhat.com

Jeff Fearn

Extensive review, rough drafts, persistent annoyances.

jfearn@redhat.com

Rechtlicher Hinweis

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

Zusammenfassung

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

1.1. Typografische Konventionen
1.2. Pull-Quote-Konventionen
1.3. Anmerkungen und Warnungen

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

4. Using Sets

4.1. Stand-alone Sets
4.2. Distributed Sets

5. Frequently Asked Questions

A. Makefile Parameters

B. Revision History

Preface

1. Dokumentkonventionen

Dieses Handbuch verwendet mehrere Konventionen, um bestimmte Wörter und Phrasen hervorzuheben und Aufmerksamkeit auf spezifische Teile von Informationen zu lenken.

In PDF- und Papierausgaben verwendet dieses Handbuch Schriftbilder des Liberation-Fonts-Sets. Das Liberation-Fonts-Set wird auch für HTML-Ausgaben verwendet, falls es auf Ihrem System installiert ist. Falls nicht, werden alternative, aber äquivalente Schriftbilder angezeigt. Beachten Sie: Red Hat Enterprise Linux 5 und die nachfolgende Versionen beinhalten das Liberation-Fonts-Set standardmäßig.

1.1. Typografische Konventionen

Es werden vier typografische Konventionen verwendet, um die Aufmerksamkeit auf spezifische Wörter und Phrasen zu lenken. Diese Konventionen und ihre Umstände, unter denen sie auftreten, sind folgende:

Mono-spaced Bold

Dies wird verwendet, um Systemeingaben hervorzuheben, einschließlich Shell-Befehle, Dateinamen und Pfade. Es wird ebenfalls zum Hervorheben von Tasten und Tastenkombinationen verwendet. Zum Beispiel:

Um den Inhalt der Dateimy_next_bestselling_novel in Ihrem aktuellen Arbeitsverzeichnis zu sehen, geben Sie den Befehl cat my_next_bestselling_novel in den Shell-Prompt ein und drücken Sie Enter, um den Befehl auszuführen.

Das oben aufgeführte Beispiel beinhaltet einen Dateinamen, einen Shell-Befehl und eine Taste. Alle werden in Mono-spaced Bold dargestellt und alle können, dank des Kontextes, leicht unterschieden werden.

Die Tastenkombination kann von einer Taste, durch den Bindestrich, der alle Teile der Tastenkombination miteinander verbindet, unterschieden werden. Zum Beispiel:

Drücken Sie Enter, um den Befehl auszuführen.
Drücken Sie Strg+Alt+F1, um zum ersten visuellen Terminal zu wechseln. Drücken Sie Strg+Alt+F7, um zu Ihrer X-Windows-Sitzung zurückzukehren.

Der erste Satz hebt die jeweilige Taste hervor, die gedrückt werden soll. Der zweite Satz hebt die beiden Sets von drei Tasten hervor, wobei jedes Set gleichzeitig gedrückt wird.

Falls Quellcode diskutiert wird, werden Klassennamen, Methoden, Funktionen, variable Namen und Wiedergabewerte, die in einen Abschnitt erwähnt werden, in Mono-spaced Bold dargestellt. Zum Beispiel:

Dateiverwandte Klassen einschließlich filesystem für Dateisysteme, file für Dateien und dir für Verzeichnisse. Jede Klasse hat ihr eigenes Set an Berechtigungen.

Proportional Bold

Dies kennzeichnet Wörter oder Phrasen, die auf einem System gefunden werden, einschließlich Applikationsnamen, Dialogtext-Boxen, beschriftete Tasten, Check-Box- und Radio-Button-Labels, Menütitel und Untermenütitel. Zum Beispiel:

Wählen Sie System > Präferenzen > Maus in der Hauptmenüleiste aus, um Maus-Präferenzen zu starten. Im Tab Schaltflächen Tab, klicken Sie auf die Check-Box Maus für Linkshänder und anschließend auf Schließen, um auf die primären Maus-Schaltflächen von der linken auf die rechte Seite zu wechseln (d.h., um die Maus auf Linkshänder anzupassen).
Um ein spezielles Zeichen in eine gedit Datei einzufügen, wählen Sie Applikationen > Zubehör > Zeichentabelle in der Hauptmenüleiste aus. Wählen Sie als nächstes Suchen > Finden… aus der Zeichentabelle-Menüleiste aus, geben den Namen des Zeichens in das Suchen-Feld ein und klicken auf Weiter. Das gesuchte Zeichen wird in der Zeichentabelle hervorgehoben. Doppelklicken Sie auf das hervorgehobene Zeichen, um Ihn in das Feld Zu kopierender Text einzufügen und klicken Sie auf die Schaltfläche Kopieren. Wechseln Sie nun zurück in Ihr Dokument und wählen Sie Bearbeiten > Einfügen aus der gedit-Menüleiste aus.

Der oben aufgeführte Text umfaßt Applikationsnamen, systemweite Menünamen und Elemente, sowie applikationsspezifische Menünamen und Schaltflächen und Textsuche innerhalb einer GUI-Schaltfläche. Alle werden in Proportional Bold dargestellt und vom Kontext hervorgehoben.

Beachten Sie, dass das Kürzel > verwendet wird, um den Verlauf in einem Menü, bzw. Untermenü zu verdeutlichen. Auf diese Weise wird der schwer nachvollziehbare Ansatz 'Wähle Maus aus dem Untermenü Präferenzen im System-Menü der Hauptmenüleiste umgangen.

Mono-spaced Bold Italic oder Proportional Bold Italic

Ob Mono-spaced Bold oder Proportional Bold, ein Kursivdruck weist auf einen ersetzbaren oder variablen Text hin. Kursivdruck weist weiterhin auf Text hin, der nicht wörtlich eingeben wird oder der sich je nach Umstand ändert. Zum Beispiel:

Um sich mit einer Remote-Maschine via SSH zu verbinden, tippen Sie ssh username@domain.name in den Shell-Prompt. Falls die Remote-Maschine example.com ist und Ihr Benutzername auf dieser Maschine John ist, tippen Sie ssh john@example.com.
Der Befehl mount -o remount file-system hängt das angegebene Dateisystem wieder ein . Um beispielsweise das /home-Dateisystem wieder einzuhängen, verwenden Sie den Befehl mount -o remount /home.
Um die Version des derezeit installierten Paketes zu sehen, verwenden Sie den Befehl rpm -q package. Die Ausgabe sieht wie folgt aus: package-version-release.

Achten Sie auf die oben aufgeführten Wörter, die fett und kursiv gedruckt sind — username, domain.name, file-system, package, version und release. Jedes Wort ist ein Platzhalter, entweder für einen Text, den Sie eingeben, wenn Sie einen Befehl ausführen oder für Text, der durch das System angezeigt wird.

Neben der Standardbenutzung für die Darstellung des Arbeitstitels, zeigt der Kursivdruck die erste Nutzung eines neuen und wichtigen Ausdrucks an. Zum Beispiel:

Wenn der Apache HTTP-Server Anfragen akzeptiert, sendet er Child-Prozesse oder Threads, um mit ihnen umzugehen. Diese Gruppe von Child-Prozessen oder Threads ist als server-pool bekannt. Unter Apache HTTP Server 2.0, wurde die Verantwortung für die Erstellung und Wartung dieser Server-Pools auf eine Gruppe von Modulen namens Multi-Processing Modules (MPMs) übertragen. Anders als andere Module, kann nur ein Modul der MPM-Gruppe vom Apache HTTP Server geladen werden.

1.2. Pull-Quote-Konventionen

Zwei, im Allgemeinen mehrzeilige, Daten-Typen werden visuell vom umliegenden Text hervorgehoben.

Eine Ausgabe, die an das Terminal gesendet wird, wird durch Mono-spaced Roman definiert und daher wie folgt präsentiert:

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

Quellcode-Auflistungen werden auch durch Mono-spaced Roman definiert. Sie werden wie folgt präsentiert und hervorgehoben:

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. Anmerkungen und Warnungen

Abschließend verwenden wir drei visuelle Stile, um die Aufmerksamkeit auf Informationen zu lenken die anderenfalls vielleicht übersehen werden könnten.

Anmerkung

Eine Anmerkung ist ein Tipp oder ein Shortcut oder ein alternativer Ansatz für die vorliegende Funktion. Das Ignorieren von Anmerkungen sollte keine negativen Auswirkungen haben, aber Sie verpassen so vielleicht einen Trick der Ihnen das Leben vereinfacht.

Wichtig

Die Wichtig-Schaukästen lenken die Aufmerksamkeit auf Dinge die sonst leicht übersehen werden können: Konfigurationsänderungen die nur für die aktuelle Sitzung gelten oder Dienste für die ein Neustart nötig ist, bevor ein Update gültig ist. Das Ignorieren von Wichtig-Schaukästen würde keinen Datenverlust verursachen, aber unter Umständen zu Irritation und Frustration führen.

Warnung

Eine Warnung sollte nicht ignoriert werden. Das Ignorieren von Warnungen führt mit hoher Wahrscheinlichkeit zu Datenverlust.

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.

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

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

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

Kapitel 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 Abschnitt 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 Abschnitt 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 Abschnitt 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:

Abbildung 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:

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' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
]>
<bookinfo id="book-Users_Guide-Users_Guide" lang="de-DE">
	<title>Users Guide</title>
	<subtitle>Publishing books, articles, papers and multi-volume sets with DocBook XML</subtitle>
	<productname>Publican</productname>
	<productnumber>0.99</productnumber>
	<edition>1.2</edition>
	<pubsnumber>0</pubsnumber>
	<abstract>
		<para>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.</para></abstract>
			<keywordset>
				<keyword>publican</keyword>
				<keyword>docbook</keyword>
				<keyword>publishing</keyword>
			</keywordset>
			<corpauthor>
				<inlinemediaobject>
					<imageobject>
						<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
					</imageobject>
					<textobject>
						<phrase>Logo</phrase>
					</textobject>
				</inlinemediaobject>
			</corpauthor>
			<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
			<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
		</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 Abschnitt 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.

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

Wichtig

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

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

Kapitel 5. Frequently Asked Questions

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

Prozedur 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

Versionsgeschichte

Version 0.5

Thu Dec 18 2008

Jeff Fearn

Added appendix on Makefile parameters

Added entry to FAQ about java heap space.

Version 0.4

Tue Nov 25 2008

Brian Forté

Added "Pre-release and draft documentation" section.

Version 0.3

Fri Oct 10 2008

Don Domingo

Adding "Conditional Tagging" section.

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

Version 0.1.1

Fri Jun 06 2008

Murray McAllister

Updated Branding to note addition of oVirt and GIMP brands

Version 0.1

Fri May 16 2008

Jeff Fearn

Updated FAQ

Version 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

Herausgegeben von

Brian Forté

Jeff Fearn

Rechtlicher Hinweis

Zusammenfassung

Preface

1. Dokumentkonventionen

1.1. Typografische Konventionen

1.2. Pull-Quote-Konventionen

1.3. Anmerkungen und Warnungen

Anmerkung

Wichtig

Warnung

2. We Need Feedback!

Kapitel 1. Introduction

Design

Kapitel 2. Branding

Tabelle 2.1. Current Brands and their packages

Kapitel 3. Using the publican package

3.1. Installing publican

3.2. Creating a Book

3.3. Files in the Book directory

Abbildung 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

Kapitel 4. Using Sets

4.1. Stand-alone Sets

Prozedur 4.1. Creating a Stand-alone Set

4.2. Distributed Sets

Wichtig

Prozedur 4.2. Creating a Set

Wichtig

Kapitel 5. Frequently Asked Questions

Prozedur 5.1. Including code samples

Important

Makefile Parameters

Revision History

Warning: `make clean_ids`