Abstract
publican.cfg parametersMono-spaced Bold
To see the contents of the filemy_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
Press Enter to execute the command.Press Ctrl+Alt+F2 to switch to a virtual terminal.
mono-spaced bold. For example:
File-related classes includefilesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Choose → → from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).To insert a special character into a gedit file, choose → → from the main menu bar. Next, choose → from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose → from the gedit menu bar.
Mono-spaced Bold Italic or Proportional Bold Italic
To connect to a remote machine using ssh, typessh username@domain.nameat a shell prompt. If the remote machine isexample.comand your username on that machine is john, typessh john@example.com.Themount -o remount file-systemcommand remounts the named file system. For example, to remount the/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use therpm -q packagecommand. It will return a result as follows:package-version-release.
Publican is a DocBook publishing system.
mono-spaced roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}Note
Important
Warning
Doc_Name.ent file (refer to Section 4.1.6, “Doc_Name.ent”).
Doc_Name.ent file's functionality, we are no longer considering requests to add functionality or features associated with entity use.
Important — Availability in repositories
su -
$yum install publican publican-doc
$yum install publican-brand
redhat, fedora, jboss, ovirt, or gimp. Refer to Chapter 5, Branding for more information on branding.
Important — Unsupported software
Important — Dependencies available only internally to Red Hat
su -
$yum install publican publican-doc
$yum install publican-brand
redhat, fedora, jboss, ovirt, or gimp. Refer to Chapter 5, Branding for more information on branding.
$sudo apt-get install publican
su -
$apt-get install publican
$publican -vversion=2.8
Important — Installing more recent packages using Apt-Pinning
su -
/etc/apt/sources.list file in a text editor. For example, to edit the file in gedit run:
$gedit /etc/apt/sources.list
#### testing ######### deb http://ftp.us.debian.org/debian testing main contrib non-free
/etc/apt/preferences file in a text editor. For example, to edit the file in gedit run:
$gedit /etc/apt/preferences
Package: * Pin: release a=stable Pin-Priority: 900 Package: * Pin: release a=testing Pin-Priority: 400 Package: * Pin: release o=Debian Pin-Priority: -10
$apt-get update
$apt-get -t testing install publican
Which indicates that you might need to upgrade libxml2 and libxslt to the testing repository version too. This can be done by searching to find the likely library:$publicanWarning: program compiled against libxml 209 using older 208Warning: XML::LibXML compiled against libxml2 20901, but runtime libxml2 is older 20800Warning: program compiled against libxml 209 using older 208Warning: XML::LibXSLT compiled against libxslt 10128, but runtime libxslt is older 10126Can't open publican: No such file or directory at /usr/bin/publican line 430.
(and the same again for libxml2)$apt-get search libxsltgambas3-gb-xml-xslt - Gambas XSLT componentlibidzebra-2.0-mod-alvis - IDZebra filter alvis (XSLT filter for XML)libidzebra-2.0-mod-dom - IDZebra filter 'dom' (XML DOM internal document model with XSLT)libical-parser-html-perl - generates HTML calendars from iCalendarslibxsltc-java - XSL Transformations (XSLT) compiler from Xalan-Javalibxml-filter-xslt-perl - Perl module for XSLT as a SAX Filterlibxml-libxslt-perl - Perl interface to the GNOME libxslt librarylibxslt1-dbg - XSLT 1.0 processing library - debugging symbolslibxslt1-dev - XSLT 1.0 processing library - development kitlibxslt1.1 - XSLT 1.0 processing library - runtime librarypython-libxslt1 - Python bindings for libxslt1python-libxslt1-dbg - Python bindings for libxslt1 (debug extension)python-lxml - pythonic binding for the libxml2 and libxslt librariespython-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)python-lxml-doc - pythonic binding for the libxml2 and libxslt libraries (documentation)python3-lxml - pythonic binding for the libxml2 and libxslt librariespython3-lxml-dbg - pythonic binding for the libxml2 and libxslt libraries (debug extension)php5-xsl - XSL module for php5libsp-gxmlcpp-dev - S+P C++ wrapper for Gnome libxml2/libxsltlibsp-gxmlcpp1 - S+P C++ wrapper for Gnome libxml2/libxsltswfmill - xml2swf and swf2xml processorlibxslthl-java - XSLT syntax highlighting
$apt-get -t testing upgrade libxml2 libxslt1.1
$sudo zypper install perl-Config-Simple perl-DateTime \ perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \ perl-File-Find-Rule perl-File-Which perl-HTML-Format \ perl-Locale-MakeText-Gettext perl-Template-Toolkit \ perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \ perl-YAML liberation-fonts
Note
Liberation-fonts is most likely already installed, but it is required. Zypper will not reinstall it if it is already present.
$sudo sh cpan File::pushd File::Copy::Recursive Locale::PO pp \ Syntax::Highlight::Engine::Kate XML::TreeBuilder exit
$cd ~ mkdir -p SourceCode/publican cd SourceCode/publican svn checkout http://svn.fedorahosted.org/svn/publican/branches/publican-2x ./
$perl Build.PL
WARNING: the following files are missing in your kit:META.ymlPlease inform the author.Created MYMETA.yml and MYMETA.jsonCreating new 'Build' script for 'Publican' version '2.9'
File/pushd.pm is reported as missing, you would use this to install it:
$sudo sh cpan File::pushd exit
Build.PL script will have created a new script named Build which we will use to create, test and install Publican 2.9.
$./Build
DEBUG: Publican::Builder: end of build$./Build test
Test Summary Report-------------------t/910.publican.Users_Guide.t (Wstat: 256 Tests: 5 Failed: 1)Failed test: 5Non-zero exit status: 1t/pod-coverage.t (Wstat: 256 Tests: 9 Failed: 1)Failed test: 7Non-zero exit status: 1Files=10, Tests=68, 420 wallclock secs ( 0.31 usr 0.17 sys + 246.87 cusr 18.73 csys = 266.08 CPU)Result: FAILFailed 2/10 test programs. 2/68 subtests failed.
ghostscript-fonts-std as opposed to ghostscript-fonts) wkhtmltopdf will not run even if force installed with no dependency checks.
Note
$JFEARN=http://jfearn.fedorapeople.org/wkhtmltopdf/f15 MYSYSTEM=i686 ## For 64bit system use MYSYSTEM=x86_64 instead. wget $JFEARN/$MYSYSTEM/wkhtmltopdf-qt-4.7.1-1.git20110804.fc15.i686.rpm wget $JFEARN/$MYSYSTEM/wkhtmltopdf-0.10.0_rc2-1.fc15.i686.rpm
Note
MYSYSTEM appropriately.
$sudo sh rpm -ivh wkhtmltopdf-qt* rpm -ivh --nodeps wkhtmltopdf-0* exit
ghostscript-fonts problem described above.
$sudo sh ./Build test exit
$publican create --type=book --product=testing --version=1.2.3 --name=TestPublicanProcessing file en-US/Author_Group.xml -> en-US/Author_Group.xml Processing file en-US/Book_Info.xml -> en-US/Book_Info.xml Processing file en-US/Chapter.xml -> en-US/Chapter.xml Processing file en-US/Preface.xml -> en-US/Preface.xml Processing file en-US/Revision_History.xml -> en-US/Revision_History.xml Processing file en-US/TestPublican.xml -> en-US/TestPublican.xml$cd TestPublican/ publican build --lang=all --formats=html,html-single,html-desktop,txt,pdf,epub
Note
runtime error: file /usr/share/publican/xsl/epub.xsl element chooseVariable 'epub.embedded.fonts' has not been declared.at /usr/lib/perl5/site_perl/5.14.2/Publican/Builder.pm line 915
SourceCode/TestPublican/tmp/en-US/ and view the various output formats that you find there.
Note
This will take some time, as it downloads a fedora based container, and then the dependencies needed for publican$docker pull svendowideit/publican
$echo 'alias publican="docker run -t -i -v $(pwd):/mnt svendowideit/publican"' >> ~/.bashrc
$publican --versionversion=3.2.1
Publican-Installer-version.exe.
Publican-Installer-version.exe file.
Main in the installer window), a number of brands (including RedHat, JBoss, and fedora), and two DocBook components (the DocBook Data Type Definition (DTD) and DocBook Extensible Stylesheet Language (XSL) stylesheets). The three brands are grouped under the collapsible heading Brands and the DocBook components are grouped under the collapsible heading DocBook in the installer window. Refer to Chapter 5, Branding for an explanation of brands in Publican. Publican uses the DTD and the XSL stylesheets to render XML documents in other presentation formats (such as HTML and PDF). If you do not install these components, Publican must download this data from the Internet every time it processes a document, which creates lengthy delays.
Publican within the %ProgramFiles% folder of your computer — typically C:\Program Files\Publican. You can manually edit the path displayed in the Destination Folder box to select a different folder.
Completed.
Note
/opt/local, away from your normal OS files.
$sudo port installdocbook-xml docbook-xsl docbook-sgml-4.2 perl5 bash-completion p5-file-pushd p5-config-simple p5-file-find-rule p5-file-slurp p5-class-trigger p5-time-hires p5-list-moreutils p5-ipc-run3 p5-class-accessor p5-test-perl-critic p5-xml-libxslt p5-locale-gettext p5-image-size p5-file-copy-recursive p5-datetime p5-archive-zip p5-timedate p5-html-format p5-dbd-sqlite p5-xml-simple p5-devel-cover p5-test-pod p5-test-pod-coverage p5-template-toolkit
$sudo cpanLocale::Maketext::Gettext Locale::PO DateTime::Format::DateParse Syntax::Highlight::Engine::Kate XML::TreeBuilder File::Inplace String::Similarity HTML::FormatText::WithLinks::AndTables
$sudo port installfop
$echo"FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc
/Users/yourusername
$git clonegit://git.fedorahosted.org/publican.git
$cdpublican/publican
Build.pl. Verify that you are in the correct directory, then run the following command. Ignore all the messages you get.
$perl ./Build.PL
$./Build
/opt/local:
$sudo ./Build install
Procedure 1.1. Create and build a book
$publican create--name=testbook
$cd testbook
$publican build--formats=html --langs=en-US
tmp/en-US/html/index.html file in a browser to prove that it built correctly.
Procedure 1.2. Install a brand
$find /opt/local/share/publican-type f|xargs sudo chmod 644
$cd publican/publican-jboss
$publican build--formats=xml --langs=all --publish
$sudo publican install_brand--path=/opt/local/share/publican/Common_Content
publican.cfg file or specifying the --brand option when creating your book.
~/.publican.cfg. Currently, Publican supports the following values:
Note
publican.cfg that is used to build a book. It does not accept the same parameters.
Example 2.1. Setting formats and lang
$echo 'formats: "html,html-single,pdf,txt"' >> ~/.publican.cfg$echo 'langs: "en-US"' >> ~/.publican.cfg$publican buildSetting up en-US[...]Finished txt
~/.publican.cfg.
Example 2.2. Setting user details
$echo 'firstname: "Dude"' >> ~/.publican.cfg$echo 'surname: "McPants"' >> ~/.publican.cfg$echo 'email: "dude.mcpants@awesome.com"' >> ~/.publican.cfg$publican add_revision --member "Updated examples in chapter 2." \--member "Removed obsolete example in sect 4.1"
cmd command from the to open a command prompt.
$ publican command_option$ publican command itself.
$ publican action action_options$ publican command_option action action_optionspublican command are:
--help--man--help option supplies, in addition to information about licensing and dependencies.
--help_actions-v--config filepublican.cfg.
--nocolours--quietRevision_History.xml.
tmp/ subdirectory. The tmp/ subdirectory is created after running the $ publican build command to build a document, such as publican build --formats=html --langs=en-US.
First Section in a book named Test_Book will have the following ID after you run $ publican clean_ids: <section id="Test_Book-First_Section">
Warning — $ publican clean_ids
$ publican 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.
$ publican clean_ids, the XML and PO files will no longer be in synchrony with each other. In this case, all links in the PO files must be manually updated.
Important — ID conflicts can occur
$ publican clean_ids command is intended to facilitate building a DocBook structure around documents ported from other formats such as HTML. However, publican clean_ids is file-based and and only has access to information in the XML file that it is currently processing and to the document name. Therefore, nodes of the same type that have the same title receive the same IDs. These duplicate IDs will prevent the document from building.
$ publican clean_ids command to assist you in laying out your document, but expect that some manual adjustment to IDs might be necessary. We recommend that you do not run publican clean_ids on an already well established document.
publican.cfg. Refer to Section 4.1.1, “The publican.cfg file” for more detail.
msgids; the number of fuzzy strings (counts the strings contained in msgids whose content changed since the last POT generation) and the number of translated strings, coinciding after translation, with the the number of strings contained in the msgid.
<xi:include> tag in a book, article, or set.
<xi:include> tag in a book, article, or set.
<imagedata> tag in a book, article, or set.
$ publican create command to create a new document, including all the necessary files for the document.
$ publican create command accepts several options, detailed in this chapter. When an option can accept a value, separate the option from the value with a space or an equals sign; for example, publican create --name New_Book or publican create --name=New_Book.
--help$ publican create command options.
--name Doc_Name$ create_book --name Test_Book creates a book named Test_Book with all the necessary files to build the book, and sets the BOOKID in the Test_Book.ent file.
--lang Language_Codeen-US (American English). The --lang option sets the xml_lang in the publican.cfg file and creates a directory with this name in the document directory. When initially created, this directory contains some boilerplate XML files. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters and Appendix G, Language codes for more detail on language codes.
--version version5.1. The default version is 0.1. The --version option sets the <productnumber> tag in the Book_Info.xml or Article_Info.xml file. For more information refer to Section 4.1.2, “Book_Info.xml”.
--edition edition1.0. The default value is 0. The --edition option sets the <edition> tag in the Book_Info.xml or Article_Info.xml file. For more information refer to Section 4.1.2, “Book_Info.xml”.
--product Product_NameFedora for core Fedora documentation, and the name of the product for other products, for example, Fedora_Directory_Server. The default value is Documentation. The --product option sets the <product name> tag in the Book_Info.xml file or Article_Info.xml file and the PRODUCT entity in the Doc_Name.ent file.
--type Article --name Article_Name--type option sets the type in the publican.cfg file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters.
--type Set --name Set_Name--type option sets the type in the publican.cfg file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters and to Chapter 6, Using sets for details on using sets.
--brand brandRedHat, fedora, JBoss, oVirt, or GIMP. The default value is common, a default brand shipped with Publican. The --brand option sets the brand parameter in the publican.cfg file. Refer to Section 4.1.1, “The publican.cfg file” for more information on publican.cfg parameters. This option requires the appropriate Publican brand package to be installed. For example, to build Red Hat branded books, you must install the publican-redhat package. Refer to Section 5.1, “Installing a brand” for instructions on installing brand packages for Publican. If you do not specify a brand, Publican uses its built-in, default brand. Refer to Chapter 5, Branding for more information.
$ publican create 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/$publican create --name Test_Book
$ls
Test_Book/Test_Book/ directory on a computer with a Linux operating system, run the following:
$cd Test_Book/$ls
en-US/ publican.cfg$ publican create --name Test_Book --lang en-US, Publican creates a directory structure and required files, similar to the following:
publican.cfg
en-US (directory)
Test_Book.xml
Test_Book.ent
Revision_History.xml
Preface.xml
Chapter.xml
Book_Info.xml
Author_Group.xml
images (directory)
icon.svg
Note — Customizing output
--config to specify a configuration file other than the publican.cfg file and therefore a different set of parameters to use in a particular build. For example:
$publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
publican.cfg file configures build options, and is located in the root of the book directory. The following is an example publican.cfg file, with a description of publican.cfg parameters following afterwards:
# Config::Simple 4.59 # Wed Jul 18 13:00:40 2012 xml_lang: "en-US" type: Book brand: common
Default parameters
xml_langen-US, as set by the --lang option for $ publican create.
type<article>, DocBook <book>, or DocBook <set>, as set by the --type option for $ publican create.
brandRedHat, fedora, JBoss, oVirt or GIMP , as set by the --brand option for $ publican create. If you do not specify a brand, Publican uses its default brand. Refer to Chapter 5, Branding for more information.
Advanced parameters
archarch: x86_64 in the publican.cfg file, Publican will only include XML elements tagged with the equivalent attribute, such as <para arch="x86_64">.
Use with caution
arch can cause great difficulties when translating documents. Refer to Section 4.9.1, “Conditional tagging and translation” for an explanation of the issues.
arch set for root nodes
arch attribute, your document will not build, because empty files are not valid XML. For example, if Installation_and_configuration-PPC.xml contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_PowerPC" arch="PowerPC"> <title>Installation and configuration on PowerPC</title> [text of chapter] </chapter>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: x86 set in the publican.cfg file.
arch attribute to the <xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration-PPC.xml.
xrefs and the arch attribute
<xref> points to content not included in the build due to the arch attribute, the build will fail. For example, with arch: x86 set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="Itanium_installation"> pointing to <section id="Itanium_installation" arch="IA64">.
booksbrew_distdocs-5E. Refer to Section 4.8.2, “The $ publican package command” and Section 5.4, “Packaging a brand” for more information on building RPM packages.
bridgehead_in_toc<bridgehead> elements (free-floating titles) should be included among other titles (such as section titles and chapter titles) in tables of contents. To enable this feature, set bridgehead_in_toc: 1. Otherwise, the parameter defaults to 0, and <bridgehead>s are not included in tables of contents.
chunk_firstchunk_first: 1. Otherwise, the parameter defaults to 0, and the first section appears on the same page of its chapter.
chunk_section_depth4.
Example 4.1. Controlling the section depth with chunk_section_depth
classpath/usr/share/java/ant/ant-trax-1.7.0.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik-all.jar:/usr/share/java/xml-commons-apis.jar:/usr/share/java/xml-commons-apis-ext.jar
common_config/usr/share/publican. On a computer with a Windows operating system, the default location is %SystemDrive%/%ProgramFiles%/publican — most usually C:/Program Files/publican.
common_content/usr/share/publican/Common_Content. On a computer with a Windows operating system, the default location is %SystemDrive%/%ProgramFiles%/publican/Common_Content — most usually C:/Program Files/publican/Common_Content.
conditionRoot nodes and conditional tagging
Installation_and_configuration_on_Fedora.xml contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora"> <title>Installation and configuration on Fedora</title> [text of chapter] </chapter>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration_on_Fedora.xml.
xrefs and conditional tagging
<xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.
confidential1, Publican adds the text specified by the confidential_text parameter (by default, CONFIDENTIAL) to the foot of each HTML page and the head of every page in a PDF document. The default value is 0 (no header or footer).
confidential_textconfidential parameter is set to 1. The default text is CONFIDENTIAL.
debug0, Publican does not display debugging messages. Change this value to 1 to view these messages.
def_langdoc_urlimage_right.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican
docname<title> tag in the Book_Info.xml file when you package a document. This value must contain only upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
dt_obsoletesdt_requiresdtdverA different DTD might slow your build
dtd_typeNote
dtd_uriNote
ec_idplugin directory.
ec_nameec_providereditionNote
<edition> tag was required by versions of Publican prior to 2.0, which used it to generate the version of a documentation package. This tag is now completely optional and does not affect packaging in any way.
extras_dirextras)
footergenerate_section_toc_level0, Publican will generate tables of contents at the start of the document and in parts, chapters, and appendixes, but not in sections. If (for example) the value is set to 1, tables of contents also appear in each "level 1" section, such as sections 1.1, 1.2, 2.1, and 2.2. If set to 2, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.
Example 4.2. Setting the section depth at which tables of contents appear
ignored_translationses-ES,it-IT. If you build or package a book for a language filtered by this parameter, Publican ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to Section 4.6, “Translating a document”, and to Appendix G, Language codes.
img_dirimages)
info_filelicensemax_image_widthImportant — 444 pixels is the maximum safe width
max_image_width parameter if your images contain important information. Images wider than 444 pixels presented at their full size might lead to poorly presented HTML and to PDF output that it is unusable because the images have run off the page and are incomplete.
mainfile<article>, <book>, or <set>, and the name of the corresponding .ent file that contains the document's entities. For example, if you set mainfile: master, Publican looks for the root XML node in master.xml and the document entities in master.ent.
mainfile is not set, Publican looks for the root XML node in a file that matches the <title> of the document set in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file, and looks for the document entities in a file with a corresponding name.
menu_category.menu file) in which a document should appear when installed from a desktop RPM package. Refer to Section 4.8.1.3, “Desktop menu entries for documents”.
os_ver.fc15 for Fedora 15. The default value is .el5, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to Section 4.8, “Packaging a document” and Section 5.4, “Packaging a brand”.
prod_urlimage_left.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican.
product<productname> tag in the Book_Info.xml file when you package a document. This value must include only contain upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
release<pubsnumber> in the Book_Info.xml file when you package a document. This value must include only digits (‘0’–‘9’).
reporev_dirasc or ascending.
rev_fileRevision_History.xml.
scmSVN as its default setting. Refer to Section 6.2, “Distributed sets”.
show_remarks<remark>s in transformed output. By default, this value is set to 0, which causes Publican to hide remarks. Set this value to 1 to display remarks. In Publican's common brand, displayed remarks are highlighted in magenta.
sort_ordersrc_urlSource: field in the header of an RPM spec file. Refer to Section 4.8, “Packaging a document”.
tmp_dirtmp, which creates a directory named tmp inside the directory that holds your article or book.
tmpl_path/usr/share/publican/templates.
toc_jstoc.tmpl is in. The template name must be must be of the form toc_type+.tmpl
toc_typetoc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.
toc_section_depth2. With the default setting, sections 1.1 and 1.1.1 will appear in the main table of contents, but section 1.1.1.1 will not. (Note that the first digit in these examples represents a chapter, not a section).
Example 4.3. Controlling the depth of sections in the main table of contents
version<productnumber> tag in the Book_Info.xml file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
web_brew_distdocs-5E, representing documentation packages for Red Hat Enterprise Linux 5. Refer to Section 4.8, “Packaging a document”.
web_formats$ publican package command”.
web_homeImportant — web_home is deprecated
web_home is replaced by web_type: home. Support for web_home will be removed in a future version of Publican.
web_name_labelweb_obsoletesweb_product_labelweb_style1 and 2. Style 1 features a navigation pane at the left side of the screen that provides access to all of the documents on the site. Style 2 offers a breadcrumb-like navigation system.
web_typeweb_type: home), product description pages (web_type: product), and version description pages (web_type: version). Refer to Chapter 7, Building a website with Publican.
web_version_labelUNUSED for general documentation that does not apply to any particular version of a product. Refer to Chapter 7, Building a website with Publican.
wkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
Help from the command line
$ publican help_config command in the root directory of a book for a summary of these parameters.
Article_Info.xml and Set_Info.xml
Book_Info.xml file applies to Article_Info.xml and Set_Info.xml files too. However, for the sake of simplicity, the file is referred to as Book_Info.xml throughout this section.
Packages other than RPM packages
$ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
Book_Info.xml file contains the key metadata concerning a book: the book's ID; title; subtitle; author and edition number. It also contains the name and version of the product that is documented, and an abstract.
Book_Info.xml must have appropriate data within them, and that data must conform to the requirements of the RPM format. You can override the data in these tags by using equivalent fields in the publican.cfg file, as discussed in this section.
publican.cfg file, 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 package is constructed as follows:
productname-title-productnumber-language-edition-pubsnumber.src.rpm
Book_Info.xml — you specify language when you build the book. As well, the <subtitle> and <abstract> are used in the RPM spec file, to provide the Summary: field in the header and the %description field, respectively.
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 conformance="121" id="book-Publican-Users_Guide-Users_Guide" lang="en-US"> <title>Users' Guide</title> <subtitle>Publishing books, articles, papers and multi-volume sets with DocBook XML</subtitle> <productname>&PRODUCT;</productname> <productnumber>&PRODUCTNUM;</productnumber> <abstract> <para> This book will help you install <application>&PRODUCT;</application>. It also provides instructions for using Publican to create and publish DocBook XML-based books, articles and book sets. This guide assumes that you are already familiar with DocBook XML. </para> </abstract> <keywordset> <keyword>publican</keyword> <keyword>docbook</keyword> <keyword>publishing</keyword> </keywordset> <subjectset scheme="libraryofcongress"> <subject> <subjectterm>Electronic Publishing</subjectterm> </subject> <subject> <subjectterm>XML (Computer program language)</subjectterm> </subject> </subjectset> <corpauthor> <inlinemediaobject> <imageobject> <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> </imageobject> <textobject> <phrase>Team &PRODUCT;</phrase> </textobject> </inlinemediaobject> </corpauthor> <mediaobject role="cover"> <imageobject remap="lrg" role="front-large"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="s" role="front"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="xs" role="front-small"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> <imageobject remap="cs" role="thumbnail"> <imagedata fileref="images/cover_thumbnail.png" format="PNG" /> </imageobject> </mediaobject> <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">, <articleinfo id="article_id">, <setinfo id="set_id">$ publican clean_ids command, any manually entered ID, including this one, changes to a Doc_Name-Title format, where Title is the title of the associated book, article, section, or chapter.
<productname>productname</productname>Red Hat Enterprise Linux or JBoss Enterprise Application Platform. When building a book as an RPM package, data in the <productname> tag is used as part of the file name of the package.
product variable in the publican.cfg file if the name of your product contains non-Latin characters, accented Latin characters, or punctuation marks other than the underscore.
Permitted characters
publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain upper- and lower-case un-accented letters, digits, and the hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
<title>title</title><title>Server Configuration Guide</title>). The title appears under the product name in both HTML and PDF editions. A title is required to build an RPM package. When building a book as an RPM package the title is used as the part of the file name of the package.
docname parameter in the publican.cfg file to set a name for the document in ASCII characters. When you build the document, the title appears as you set it with the <title> tag, but when you package the document, the value that you used in the docname parameter is used in the file name of the RPM package.
Permitted characters
publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain upper- and lower-case un-accented letters, digits, and the hyphen-minus, period, underscore, and plus characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘-’, ‘.’, ‘_’, and ‘+’) if you plan to build packages with Publican.
<title> tag to find the file that contains the root XML node: <article>, <book>, or <set>. For example, if you set the title to <title>Server Configuration Guide</title>, Publican expects the root XML node to be in a file named Server_Configuration_Guide.xml and the document entities to be in a file named Server_Configuration_Guide.ent. To use a different name for these files, set the mainfile parameter in the document configuration file (by default, publican.cfg). Refer to Section 4.1.1, “The publican.cfg file”.
<subtitle>subtitle</subtitle>Summary in the RPM spec file. The rpm -qi command returns the contents of several spec file fields, including the Summary field.
<productnumber>productnumber</productnumber>$ publican create --name Doc_Name --version version command correctly configures the product number.
version variable in the publican.cfg file if the product version is anything other than a number.
Permitted characters
publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain numbers and the period (‘0–9’ and ‘.’) if you plan to build packages with Publican.
<edition>edition</edition>$ publican package command.
1.2 and building the book using the $ publican package --binary --lang=en-US command creates an RPM file named productname-title-productnumber-en-US-1.2-0.src.rpm.
$ publican create --name Doc_Name --edition x.y command correctly configures the edition.
edition variable in the publican.cfg file if the edition of your document is identified by anything other than a number.
Permitted characters
publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain numbers and the period (‘0–9’ and ‘.’) if you plan to build packages with Publican.
<pubsnumber>pubsnumber</pubsnumber>$ publican package command. For example, setting the pubsnumber to 1 and building the book using the publican package --binary --lang=en-US command creates an RPM file named productname-title-productnumber-en-US-edition-1.src.rpm.
release variable in the publican.cfg file if the release number of your document contains anything other than whole numbers.
Permitted characters
publican.cfg file. If you do not override this tag in the publican.cfg file, this tag must only contain numbers (‘0–9’) if you plan to build packages with Publican.
<abstract><para>abstract</para></abstract>Description field of the RPM's spec file. This makes the abstract for a package available via the rpm -qi command.
Book_Info.xml file of a document, to support specific features in various output formats:
<keywordset>, <keyword><keyword> and placed within a <keywordset> are added to a <meta name="keywords"> entry in the head of HTML files and to the Keywords field of the properties of a PDF document.
<subjectset>, <subject><subject> and placed within a <subjectset> are added to the Subject field of the properties of a PDF document and in the metadata of an ebook in EPUB format.
scheme attibute in the <subjectset> tag, for example, <subjectset scheme="libraryofcongress">. You can search for LCSH subject headings through the Library of Congress Authorities & Vocabularies page: http://id.loc.gov/authorities/search/.
<mediaobject role="cover" id="epub_cover"><mediaobject> tag with the role="cover" and id="epub_cover" attributes to set cover art for an ebook in EPUB format. For example:
<mediaobject role="cover" id="epub_cover"> <imageobject role="front-large" remap="lrg"> <imagedata width="600px" format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="front" remap="s"> <imagedata format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="front-small" remap="xs"> <imagedata format="PNG" fileref="images/front_cover.png"/> </imageobject> <imageobject role="thumbnail" remap="cs"> <imagedata format="PNG" fileref="images/front_cover_thumbnail.png"/> </imageobject> </mediaobject>
images subdirectory.
Book_Info.xml used by Publican includes an <edition> tag.
Book_Info.xml also includes the <pubsnumber> tag. Any data placed within this tag changes the release number of RPM-packaged books.
<productnumber> tag also found in Book_Info.xml: <productnumber> denotes the version number of the product being documented or otherwise written about.
<pubsnumber> tag, not the <edition> tag. It functions as a near-equivalent to the impression or printing number of traditional publishing.
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.
Articles and chapters
--type=article option with $ publican create, Publican does not create a Chapter.xml file. Use sections to organize content within articles.
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 by the $ publican create 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>
Section 1 Test and Section 2 Test. Refer to http://docbook.org/tdg/en/html/chapter.html for further information about chapters.
Note
Installation.xml, whereas a chapter on setting up a piece of software would be better called Setup.xml or Configuration.xml.
Doc_Name.xml file contains xi:include directives to include the other necessary XML files for the document, including chapters or sections contained in other XML files. For example, a book's Doc_Name.xml file brings together chapters that are contained in separate XML files.
Doc_Name.xml file that describes a DocBook book — note the DOCTYPE is set to book.
Example 4.4. A DocBook 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>
Book_Info.xml, Preface.xml, Chapter.xml, and Appendix.xml XML files.
Important
Book_Info.xml will precede Preface.xml which will precede Chapter.xml, and so on.
Doc_Name.xml file is not limited to using xi:include directives. You can create documents with 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>
Doc_Name.ent file is used to define local entities. The YEAR and HOLDER entities are used for copyright information. By default, Publican sets YEAR to the current year, and inserts a message into HOLDER to remind you to specify the copyright holder for the document. If the YEAR and HOLDER entities are missing altogether, the document will not build.
BOOKID to specify how readers should refer to a document when they submit feedback about it.
<!ENTITY PRODUCT "MYPRODUCT"> <!ENTITY BOOKID "MYBOOK"> <!ENTITY YEAR "2008"> <!ENTITY HOLDER "YOUR NAME GOES HERE">
Use entities with extreme caution
&FDS; instead of Fedora Directory Server saves the writer time but transformed entities do not appear in the portable object (PO) files that translators use. Complete translations of documents containing entities are, as a consequence, impossible.
<!ENTITY LIFT "Liberty Installation and Formatting Tome"> — you can enter &LIFT; in your XML and it will appear as Liberty Installation and Formatting Tome every time the book is built as HTML, PDF or text.
Liberty Installation and Formatting Tome. Instead they see &LIFT;, which they cannot translate.
As noted in the Liberty Installation and Formatting Tome, Chapter 3…
Wie in dem Wälzer für die Installation und Formatierung von Liberty, Kapitel 3, erwähnt…
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr ""
#. Tag: para #, no-c-format msgid "As noted in the <citetitle>&LIFT;</citetitle>, Chapter 3…" msgstr "Wie in <citetitle>&LIFT;</citetitle>, Kapitel 3, erwähnt…"
Wie in Liberty Installation and Formatting Tome, Kapitel 3, erwähnt…
However, a careful reading of the Liberty Installation and Formatting Tome afterword shows that…
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für den Wälzer für die Installation und Formatierung von Liberty, dass…
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr ""
#. Tag: para #, no-c-format msgid "However, a careful reading of the <citetitle>&LIFT;</citetitle> afterword shows that…" msgstr "Jedoch ergibt ein sorgfältiges Lesen des Nachworts für <citetitle>&LIFT;</citetitle>, dass…"
Jedoch ergibt ein sorgfältiges Lesen des Nachworts für Liberty Installation and Formatting Tome, dass…
&PRODUCT;. The advantage of this approach is that by simply changing this value in the Doc_Name.ent file, you could easily adjust the book to document (for example) Red Hat Enterprise Linux, Fedora, or CentOS. However, while the proper noun Fedora never varies in English, it has multiple forms in other languages. For example, in Czech the name Fedora has six different forms, depending on one of seven ways in which you can use it in a sentence:
Table 4.1. 'Fedora' in Czech
| Case | Usage | Form |
|---|---|---|
| Nominative | the subject of a sentence | Fedora |
| Genitive | indicates possession | Fedory |
| Accusative | the direct object of a sentence | Fedoru |
| Dative | the indirect object of a sentence | Fedoře |
| Vocative | the subject of direct address | Fedoro |
| Locative | relates to a location | Fedoře |
| Instrumental | relates to a method | Fedorou |
me and she is not correct. Me is the accusative form of the pronoun, but because it is the subject of the sentence, the pronoun should take the nominative form, I. Similarly, she is nominative case, but as the direct object of the sentence the pronoun should take its accusative form, her.
Doc_Name.ent file, entities might prove useful for version numbers of products. Beyond that, the use of entities is tantamount to a conscious effort to inhibit and reduce the quality of translations. Furthermore, readers of your document in a language that inflects nouns (whether for case, definiteness, or other reasons) will not know that the bad grammar is the result of XML entities that you set — they will probably assume that the translator is incompetent.
$ publican package command searches for the first XML file in the document's XML directory containing a <revhistory> tag. Publican then uses that file to build the RPM revision history.
images subdirectory in the directory that holds your XML files. 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>
<textobject> so that your content remains accessible to people with visual impairments. In certain jurisdictions, you might have a legal responsibility to provide this accessibility — for example, if you or your organization must comply with Section 508 of the United States Rehabilitation Act of 1973.
[1]
images subdirectories for each language directory. Make sure that the image file in the translated language has the same name as the image file in the original language. When you build the book in the translated language, Publican uses the file from the images/ subdirectory of the translated language instead of the file from the images/ subdirectory of the original language.
<imagedata> tag. For example, to set an image width to 670 pixels:
<imagedata fileref=".images/image.png" width="670px">
Image file locations
images subdirectory of your XML directory and corresponding images in the images subdirectories of your translated languages. Images stored in other directories directories do not work.
PNG files in PDF documents
Add alpha channel, the option might be labeled Add transparency instead.
extras/ in your source language directory and use an <xi:include> to pull the code file into the XML structure of your document. Publican does not parse any files that it finds in the extras/ directory as XML.
& and <. If you insert code samples directly into the XML of your document, you must escape these characters, either by marking them as CDATA or by replacing them with entities (& and < respectively).
[2] If you place these files in the extras/ directory, you do not need to escape these characters. This approach saves time, reduces the chances of introducing errors into either the document XML or the code itself, and makes future maintenance of the document and the code easier.
extras/ directory in your document, follow this procedure:
$mkdiren-US/extras
$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>
en-US/extras/foo.c in your favorite editor without having to be concerned about how it will affect the XML.
<programlistingco> <areaspec> <area id="orbit-for-parameter" coords='4 75'/> <area id="orbit-for-magnitude" coords='12 75'/> </areaspec> <programlisting language="Fortran"><xi:include parse="text" href="extras/orbit.for" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> <calloutlist> <callout id="callout-for-parameter" arearefs="orbit-for-parameter"> <para> The <firstterm>standard gravitational parameter</firstterm> (μ) is a derived value, the product of Newton's gravitational constant (G) and the mass of the primary body. </para> </callout> <callout id="callout-for-magnitude" arearefs="orbit-for-magnitude"> <para> Since the mass of the orbiting body is many orders of magnitude smaller than the mass of the primary body, the mass of the orbiting body is ignored in this calculation. </para> </callout> </calloutlist> </programlistingco>
<area> elements that define the position of the callouts that will appear on the code sample. The coords attributes specify a line number and a column number separated by a space. In this example, callouts are applied to lines 4 and 12 of the code, lined up with each other in column 75. Although this approach means that you might have to adjust coords attributes if you ever modify the code to which they apply, it avoids mixing XML <coords> tags into the code itself.
files in the language directory for the original language (e.g. en-US) of the book (e.g. My_Book).
My_Book:
$mkdir en-US/files
files:
$cp arbitrary_files en-US/files
$ publican rename command makes it easy for you to rename a document to give it a new title, or to change the name or version of the product to which the document applies. The command accepts up to three options:
--name new_title$publican rename --name "Server Deployment Guide"
<title> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file, and sets a value for the mainfile parameter in the publican.cfg file so that Publican can still find the root XML node and the entities for the document.
$ publican rename command does not change any file names. Therefore, the root XML node and the document entities are still located in files named after the original title of the document — Server_Configuration_Guide in the previous example.
--product new_product$publican rename --product PendantFarm
<productname> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file.
--version new_version$publican rename --version 2.0
<productnumber> tag in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file.
$publican rename --name "Server Deployment Guide" --product PendantFarm --version 2.0
$publican trans_drop
trans_drop/. The trans_drop/ subdirectory contains a snapshot of the source files of the document. When the trans_drop/ directory is present in a documentation project, Publican uses its content as the basis for the commands documented later in this procedure.
$publican update_pot
pot. The pot subdirectory holds a POT file for each XML file in the document. If Publican has created POT files for this document previously, Publican updates the existing POT files to reflect any changes in the XML since the POT files were last updated.
Remove unused XML files
$ publican print_unused command to generate a list of XML files that are not used in your document.
$publican update_po --langs=language_code
$publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
--langs= option. This subdirectory holds a PO file for each POT file in pot subdirectory, plus a Revision_History.xml file that tracks the history of this particular translation. When created for the first time, the Revision_History.xml file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's Revision_History.xml file) on which this translation is therefore based.
Revision_History.xml file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. You can update existing PO files in every subdirectory with the --langs=all option:
$publican update_po --langs=all
Remove unused POT files
pot directory, whether the POT file is based on a corresponding XML file that is used in the document or not, or whether a corresponding XML file even exists. If you transform POT files for unused or deleted XML files into PO files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
publican add_revision command to describe your changes or corrections. Publican updates the Revision_History.xml file for you.
publican trans_drop, publican update_pot, and publican update_po commands as described earlier in this procedure instead.
$publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
$publican package --lang=is-IS
--langs=all option, but note that you must package each language individually. Refer to Section 4.7, “Building a document” for more information on building a document, and Section 4.8, “Packaging a document” on packaging a document.
$translation/Author_Group.xml and add a valid DocBook authorgroup. The translator can add their details to this file and Publican will append it to $source_lang/Author_Group.xml when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.
<glossentry> elements into a book's glossary; and <primary>, <secondary>, and <tertiary> <indexterm> elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.
sortas attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify:
#. Tag: indexterm #, no-c-format msgid "<primary>encryption</primary>" msgstr "<primary sortas="あんごうか">暗号化</primary>"
#. Tag: glossentry #, no-c-format msgid "<glossterm>encryption</glossterm>" msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"
Note — Customizing output
publican.cfg) allow you to control many aspects of the way in which a document is presented — refer to Section 4.1.1, “The publican.cfg file”.
--config to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
$publican build --formats html,pdf --langs en-US,de-DE,hu-HU --config community.cfg
YEAR and HOLDER entities have been configured in the Doc_Name.ent file, as described in Section 4.1.6, “Doc_Name.ent”.
Test_Book and is located in the ~/books/ directory, run the following command:
$cd ~/books/Test_Book
$publican build --formats=test --langs=en-US
$publican build --formats=formats --langs=languages
html,html-single,pdf. Replace langs with a comma-separated list of the languages that you want to build; for example, en-US,sv-SE,uk-UA,ko-KR.
Formats for the build action
htmlchunk_first and chunk_section depth parameters in the publican.cfg file to control how Publican chunks sections in this format.
html-singlehtml-desktopmanpdftesttxtepubeclipseid, name, and provider-name parameters with Publican's ec_id, ec_name, and ec_provider parameters.
$ publican build commands:
$ publican build --help$ publican build options for building a book.
$ publican build --formats=test --langs=languages--formats=test before running any other $ publican build command, and before checking a book back into a version-controlled repository from which other contributors might download it.
$ publican build --formats=html --langs=languagesDoc_Name/tmp/language/html/ directory. Each chapter and major section is placed in a separate HTML file. You can control the depth at which Publican places subsections into separate HTML files with the chunk-section-depth parameter in the publican.cfg — refer to Section 4.1.1, “The publican.cfg file”.
$ publican build --formats=html-single --langs=languagesDoc_Name/tmp/language/html-single/ directory.
$ publican build --formats=pdf --langs=languagesDoc_Name/tmp/language/pdf/ directory.
$ publican build --formats=html,html-single,pdf --langs=languages<xref>s) to sections of the document that do not yet exist. To skip validation, run $ publican build with the --novalid option. Cross-references to non-existent content appear in the built document as three question marks: ???.
--novalid option is highly suspect. Do not publish documentation that you have built with the --novalid option.
Packages other than RPM packages
$ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
Note — Customizing output
publican.cfg) allow you to control many aspects of the way in which a document is presented and packaged — refer to Section 4.1.1, “The publican.cfg file”.
--config to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
$publican package --lang hi-IN --config community.cfg
/usr/share/doc/, the location specified by the Filesystem Hierarchy Standard (FHS) for ‘Miscellaneous documentation’.
[3] The desktop RPM package also contains a desktop file, to be placed in /usr/share/applications/. This file enables desktop environments to add the installed document to their menus for ease of reference by users. By default, the menu item appears under → on the GNOME desktop. To customize the placement of the menu item, create a documentation menu package to supply .directory and .menu files and set the dt_requires and menu_category parameters in the publican.cfg file to require this package and supply the appropriate menu category. Refer to Section 4.8.1.3, “Desktop menu entries for documents”
web_formats parameter. The value of this parameter overrides the default formats that Publican packages. For example, to publish the document only as single-page HTML, PDF, and text, set web_formats: "html-single,pdf,txt"
/var/www/html/, a common document root for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.
.directory) file that provides metadata about the new submenu.
.menu) file that defines the position of the new submenu within the menu.
.directory file for Publican-generated documentation is as follows:
[Desktop Entry]
Name parameter, set to the name of the submenu that you want to place under the menu.
Name parameter, in the format Name[language_code] where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.
Comment parameter, set to a description of the new submenu.
Comment parameter, in the format Comment[language_code] where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.
Type parameter, set to Directory.
Encoding parameter, set to UTF-8.
Example 4.5. Example .directory file
menu-example.directory illustrates the structure of a desktop entry file.
[Desktop Entry] Name=Example Name[fr]=Exemple Name[it]=Esempio Comment=Example Documentation menu Comment[fr]=Exemple d'une menu de documentation Comment[it]=Esempio di un menù di documentazione Type=Directory Encoding=UTF-8
/usr/share/desktop-directories/
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>, that contains:
<Name> element with the content Documentation
<Menu> element that in turn contains:
<Name> element with the content Documentation (just like the root element)
<Directory> element with its content the name of the desktop entry file you created, for example:
<Directory>menu-example.directory</Directory>
<Includes> element with the content X-category_name, where category_name is an identifier for the documents that will be grouped together under this menu entry. For example:
<Includes>X-Example-Docs</Includes>
Example 4.6. Example .menu file
menu-example.menu illustrates the structure of a desktop menu file.
<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"> <Menu> <Name>Documentation</Name> <Menu> <Name>Documentation</Name> <Menu> <Name>Example</Name> <Directory>menu-example.directory</Directory> <Include> <Category>X-Example-Docs</Category> </Include> </Menu> </Menu> </Menu>
/etc/xdg/menus/settings-merged/
menu_category parameter in its publican.cfg file to match the content of the <Includes> element in the corresponding desktop menu file. For example, consider a desktop menu file that contains the element:
<Includes>X-Example-Docs</Includes>
publican.cfg file should contain:
menu_category: X-Example-Docs
Important
__LANG__ with the current language. This allows menus to be customized on a per language basis.
menu_category: X-Example-Docs-__LANG__
defaults.cfg file or overrides.cfg file of a brand so that all documents built with that brand are grouped into this submenu automatically without you having to set the menu_category parameter in each document.
dt_requires parameter in the document's publican.cfg file. For example, if you ship a desktop menu package named foodocs-menu, set:
dt_requires: foodocs-menu
defaults.cfg file or overrides.cfg file of a brand so that all documents built with that brand require the same desktop menu package.
$ publican package command$ publican package --lang=Language_Code command to package documents for distribution in the language that you specify with the --lang option. Refer to Appendix G, Language codes for more information about language codes.
$ publican package with no options other than the mandatory --lang option, Publican produces a web SRPM package. The full range of options for publican package is as follows:
--lang languageIncomplete translations
ignored_translations parameter in the document's publican.cfg file. The package will be named appropriately for the language, but will contain documentation in the original language of the XML rather than a partial translation. When translation is complete, remove the ignored_translations parameter, increase the release number in the Project-Id-Version field in the Book_Info.po file for that language, and generate the package again. When you distribute the revised package, it becomes available to replace the original untranslated package.
--config filenamepublican.cfg file.
--desktop--brew--scratch--brew and --desktop options, specifies that an SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that an SRPM package is structured correctly, without updating the package database to use the resulting package.
--short_sightedversion in the publican.cfg file) in the package name.
Omitting the software version number
--binary$ publican package command, Publican outputs completed SRPM packages to the document's tmp/rpm directory, and completed binary RPM packages to the document's tmp/rpm/noarch directory.
productname-title-productnumber-[web]-language-edition-pubsnumber. [.[build_target].noarch].file_extension.
publican.cfg) to supply the various parameters in the file name, and then information in the Book_Info.xml file for any parameters missing from the configuration file. Refer to Section 4.1, “Files in the book directory” for details of the parameters used in these files. Additionally, note that:
-web- between the product version and the language code.
.src.rpm but binary RPM packages have the file extension .rpm
build_target.noarch before the file extension, where build_target represents the operating system and version that the package is built for as set by the os_ver parameter in the publican.cfg file. The noarch element specifies that the package can be installed on any system, regardless of the system architecture.
--short_sighted option removes the -productnumber- from the package name.
Project-Id-Version parameter in the Article_Info.po or Book_Info.po file. This release number is specific to a particular language and bears no relationship to the release numbers of the same document in the original language or any other language.
$ publican package command — Example usage$ publican package --lang=cs-CZ$ publican package --desktop --lang=cs-CZ$ publican package --binary --lang=cs-CZ$ publican package --desktop --binary --lang=cs-CZ$ publican package --desktop --short_sighted --lang=cs-CZ$ condition. For example, let's say the book How To Use Product Foo has an "upstream", "enterprise", and "beta" version:
<para condition="upstream"> <application>Foo</application> starts automatically when you boot the system. </para> <para condition="enterprise"> <application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>. </para> <para condition="beta"> <application>Foo</application> does not start automatically when you boot the system. </para> <para condition="beta,enterprise"> To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file. </para>
$ condition: version parameter to the publican.cfg file and run the $ publican build command as normal. For example, if you add condition: upstream to the publican.cfg file of How To Use Product Foo and run:
$publican build --formats=pdf --langs=en-US
condition="upstream" and builds How To Use Product Foo in as a PDF file in American English.
Root nodes and conditional tagging
Installation_and_configuration_on_Fedora.xml contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora"> <title>Installation and configuration on Fedora</title> [text of chapter] </chapter>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration_on_Fedora.xml.
xrefs and conditional tagging
<xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.
Use conditional tagging with great caution
#. Tag: para #, no-c-format msgid "<application>Foo</application> starts automatically when you boot the system." msgstr "" #. Tag: para #, no-c-format msgid "<application>Foo</application> only starts automatically when you boot the system when installed together with <application>Bar</application>." msgstr "" #. Tag: para #, no-c-format msgid "<application>Foo</application> does not start automatically when you boot the system." msgstr "" #. Tag: para #, no-c-format msgid "To make <application>Foo</application> start automatically at boot time, edit the <filename>/etc/init.d/foo</filename> file." msgstr ""
publican.cfg file and are aware of the valid conditions for your book, they cannot proofread their work. Without that knowledge, when translators proofread a document, they will wonder why they cannot find text that they know they translated and can find easily in the PO file. If you must use conditionals in your book, you must be prepared to provide a greater degree of support to your translators than you would otherwise provide.
upstream.cfg file might contain the condition condition: upstream and the enterprise.cfg file might contain the condition condition: enterprise. You could then specify the version of the document to build or package with the --config; for example, $ publican package --lang en-US --config upstream.cfg. Using two separate config files saves you from having to edit the one config file each time you build or package a document.
<subtitle> tag 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>
show_remarks to the publican.cfg file and set it to '1':
show_remarks: 1
<remark> tag and the show_remarks setting in place, the pre-release nature of the software is displayed clearly and unmistakably. PDF builds display the remark on their cover and title pages. HTML builds (both single-page HTML and multiple-page HTML) display the remark near the beginning of index.html.
Book_Info.xml used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
Important
<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.
status="draft" attribute to the <article>, <book> or <set> tag in your document's root node. For example:
<book status="draft">
<book> tag in your Doc_Name.xml file.
<article> or <set> tag in Doc_Name.xml.
status="draft" attribute causes each page of the document to show the draft watermark. This is by design.
common/. Documentation projects can produce and distribute brands to their contributors, either as a package (for example, an RPM package) or as an archive (for example, a tarball or ZIP file).
yum install publican-brand or with a graphical package manager such as PackageKit.
Common_Content directory. By default, this directory is located at /usr/share/publican/Common_Content on Linux operating systems and at %SystemDrive%/%ProgramFiles%/Publican/Common_Content on Windows operating systems — typically, C:/Program Files/Publican/Common_Content
$cd publican-brand
$publican build --formats xml --langs all --publish
$sudo publican install_brand --path path
$sudo publican install_brand --path /usr/share/publican/Common_Content
$publican install_brand --path "C:/Program Files/Publican/Common_Content"
Table 5.1. Current Brands and their packages
| Brand | License of Common Content files | Default license for documents | Package | Comment |
|---|---|---|---|---|
| common | CC0 1.0 | GFDL Version 1.2 | publican | GPL compatible license. No options. |
| RedHat | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-redhat | |
| Fedora | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-fedora | |
| JBoss | CC-BY-SA 3.0 | CC-BY-SA 3.0 | publican-jboss | No Options. |
| oVirt | OPL 1.0 | OPL 1.0 | publican-ovirt | No Options. |
| GIMP | GFDL Version 1.2 | GFDL Version 1.2 | publican-gimp | Matches the license for existing GIMP documentation. |
| Genome | OPL 1.0 | OPL 1.0 | publican-genome | No Options. |
$ create_brand action to create a new brand. When you create a new brand, you must give it a name and specify the original language for the brand's XML files. The --name option provides the name, and the --lang option specifies the language. The complete command is therefore:
$publican create_brand --name=brand --lang=language_code
publican-brand, where brand is the brand that you specified with the --name option.
Acme, which will have its Common Content XML files written originally in American English, run:
$publican create_brand --name=Acme --lang=en-US
publican-Acme.
SETUP in the default files that Publican creates and edit the files to provide the missing details. On Linux operating systems, you can search for the word SETUP in these files with the command:
$grep -r 'SETUP' *
$ publican create_brand --name=brand --lang=language_code command creates a directory structure and the required files. The brand directory initially contains:
COPYING
defaults.cfg
overrides.cfg
publican.cfg
publican-brand.spec, where brand is the name of the brand.
README
en-US). These files are:
Feedback.xml
Legal_Notice.xml
css subdirectory, which contains:
overrides.css
images subdirectory, which contains 43 images in both raster (PNG) and vector (SVG) formats.
publican.cfg file in a brand serves a similar purpose to the publican.cfg file in a document — it configures a number of basic options that define your brand.
version$ publican create_brand, the version number is set to 0.1. Update the version number here in the brand publican.cfg file and in the publican-brand.spec file when you prepare a new version of the brand.
12 in its publican.cfg file, but might be built with version 1.0 of the publican-fedora brand.
xml_langen-US, as set by the --lang option for $ publican create_brand.
release$ publican create_brand, the release number is set to 0. Update the version number here in the brand publican.cfg file and in the publican-brand.spec file when you prepare a new release of an existing version of the brand.
typetype: brand, this parameter identifies the contents of this directory as a brand, rather than a book, article, or set.
brand--name option for $ publican create_brand.
web_cfgweb_dirpublican-brand.spec.
web_reqpublican.cfg file in its root directory, which configures build options for the document. Refer to Section 4.1.1, “The publican.cfg file” for a full description of these options. The defaults.cfg file and overrides.cfg file in a brand supply default values for any of the parameters that you can otherwise set with a document's publican.cfg file.
defaults.cfg file before it applies the values in the document's publican.cfg file. Values in the document's publican.cfg file therefore override those in the brand's defaults.cfg file.
overrides.cfg file, which therefore override any values in the brand's defaults.cfg file and the document's publican.cfg file.
defaults.cfg file to set values that you routinely apply to your brand but want to allow writers to change in particular books; use the overrides.cfg file for values that you do not want to allow writers to change.
defaults.cfg or overrides.cfg. These will be listed by the Publican action print_banned.
README file contains a brief description of the brand package.
COPYING file contains details of the copyright license for the package and perhaps the text of the license itself.
--lang option when you created the brand. This subdirectory contains XML and image files that override the default Common Content provided with Publican. Customizing these files provides your brand with its distinctive appearance, including its color scheme and logos.
Feedback.xmlFeedback.xml file is included by default in the preface of every book produced in Publican. It invites readers to leave feedback about the document. Customize this file with the contact details of your project. If your project uses a bug tracking system such as Bugzilla, JIRA, or Trac, you could include this information here.
Legal_Notice.xmlLegal_Notice.xml file contains the legal notice that appears at the beginning of every document produced by Publican. Insert the details of your chosen copyright license into this file. Typically, this might include the name of the license, a short summary of the license, and a link to the full details of the license.
css subdirectorycss subdirectory contains a single file: overrides.css.
overrides.css file sets the visual style for your brand. Values in this file override those in Publican's Common_Content/common/xml_lang/css/common.css file.
images subdirectoryimages subdirectory contains 43 images in both portable network graphics (PNG) and scalable vector graphics (SVG) format. These images are placeholders for various navigation icons, admonition graphics, and brand logos. They include:
image_leftprod_url in the publican.cfg file for the document. Consider setting prod_url in the brand's defaults.cfg or overrides.cfg file.
image_rightdoc_url in the publican.cfg file for the document. If all the documentation for this brand is produced by the same team, consider setting doc_url in the brand's defaults.cfg or overrides.cfg file.
title_logonote, important, warning<note>, <important>, and <warning>.
dot, dot2<listitem>s in <itemizedlist>s.
stock-go-back, stock-go-forward, stock-go-up, stock-homeh1-bgwatermark_draftxsl in your brand: it sits at the same level as the various language files for your brand. Publican uses any XSL that it finds in that directory to override the XSL templates that we ship in the common brand (which in turn override the XSL templates that the DocBook project ships).
Important
Packages other than RPM packages
$ publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.
$ publican package command in the brand directory. When used without any further options, Publican produces an SRPM package. The options for packaging a brand are as follows:
--binary--brew--scratch--brew option, specifies that a SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that a SRPM package is structured correctly, without updating the package database to use the resulting package.
--lang, --desktop and --short_sighted options that apply when you package books (described in Section 4.8, “Packaging a document”) are meaningless when you package brands. In particular, note that although the --lang option is mandatory when you package a book, you do not need to use it when you package a brand.
publican-brand-version-release.build_target.noarch.file_extension.
publican.cfg file to supply the various parameters in the file name. Refer to Section 5.3.1, “The publican.cfg file” for details of configuring this file. Additionally:
.src.rpm but binary RPM packages have the file extension .rpm
build_target.noarch before the file extension, where [build_target] represents the operating system and version that the package is built for as set by the os_ver parameter in the publican.cfg file. The noarch element specifies that the package can be installed on any system, regardless of the system architecture.
$ create_book command creates a template for a set by setting the type parameter to Set.
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 6.1. Creating a stand-alone set
books/ directory to create a set named My_Set branded in the Red Hat style and in which the XML will be written in American English.
publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
$ cd into the My_Set/en-US directory and create two directories (not books) called Book_A and Book_B.
$cdMy_Set/en-US$mkdirBook_ABook_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>
books/My_Set/en-US/Book_B directory, as per the step above.
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>
My_Set.xml, comment out the following lines:
<remark>NOTE: the href does not contain a language! This is CORRECT!</remark> <remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark> <setindex></setindex>
Preface.xml and Book_Info.xml for each book you are using, add ../../ to the front of every Common_Content string you see. For example:
<xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
publican build --formats=test --langs=en-US command.
-- My_Set
|-- en-US
| |-- Author_Group.xml
| |-- Book_A.ent
| |-- Book_A.xml
| |-- Book_B.ent
| |-- Book_B.xml
| |-- Book_Info_A.xml
| |-- Book_Info_B.xml
| |-- chapter_A.xml
| |-- chapter_B.xml
| |-- images
| | |-- icon.svg
| | `-- image1.png
| |-- My_Set.ent
| |-- My_Set.xml
| |-- Preface.xml
| |-- Revision_History.xml
| `-- Set_Info.xml
`-- publican.cfg
-- My_Set
|-- en-US
| |-- Author_Group.xml
| |-- Book_A
| | |-- Book_A.ent
| | |-- Book_A.xml
| | |-- Book_Info.xml
| | `-- chapter.xml
| |-- Book_B
| | |-- Book_B.ent
| | |-- Book_B.xml
| | |-- Book_Info.xml
| | `-- chapter.xml
| |-- images
| | |-- icon.svg
| | `-- image1.png
| |-- My_Set.ent
| |-- My_Set.xml
| |-- Preface.xml
| |-- Revision_History.xml
| `-- Set_Info.xml
`-- publican.cfg
publican.cfg file, 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
Procedure 6.2. Creating a set
My_Set branded in the Red Hat style and in which the XML will be written in American English.
$ publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US
publican.cfg file:
books: Book_A Book_B repo: http://PATH-TO-YOUR-SVN-REPOSITORY scm: SVN
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>
My_Set.xml
<remark>NOTE: the href does not contain a language! This is CORRECT!</remark> <remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark> <setindex></setindex>
publican build --formats=test --langs=en-US command.
Important
publican clean_ids command will be run over each book because of the constraint that IDs 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.
index.html — an index page that redirects to localized versions of a home page for the site.
interactive.css — a CSS stylesheet that contains styles for the navigation menu.
opds.xml — an Open Publication Distribution System (OPDS) catalog to allow compliant eBook readers to find EPUB documents on your site easily.
Sitemap — A Sitemap is a list of the URLs from your website and metadata about them, like update history, change frequency, and importance relative to other URLs in the site. A Sitemap can be supplied to many major search engines, where it is used to help their crawlers index your site more intelligently. A Sitemap does not guarantee that your site will be ranked higher in search results. However, it does help search engines to return the most relevant results from your website in response to user queries. For more information on Sitemaps, visit sitemaps.org.
site_overrides.css — a CSS stylesheet that overrides the styles contained in interactive.css to provide site-specific styles. This file is not created by the site creation process, but must be added manually later, or supplied by the site home page.
default.js — a JavaScript script that directs visitors to localized content based on the locale set in their browser and which controls the presentation of the navigation menu.
opds.xml and toc.html. Later it also contains opds-product.xml:
opds.xml — an OPDS catalog of EPUB documents in this language.
opds-product.xml — an OPDS catalog of EPUB documents for each product for which you publish documentation in this language. Within each product catalog, documentation is divided into <category>s for different versions of the same product.
toc.html — the table of contents for that language, initially without links to any documents.
$mkdir ~/docsite$cd ~/docsite
publican create_site, specifying the following parameters:
--site_config — the name of the configuration file for your site, with the filename extension .cfg
--db_file — the name of the SQLite database file for your site, with the filename extension .db
--toc_path — the path to the directory in which you will place your documents
--tmpl_path — the path to the templates/ directory of your Publican installation. On computers with Windows operating systems, this is typically %SystemDrive%\%ProgramFiles%\Publican\templates.
$publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
foomaster.cfg and foomaster.db. You can set --toc_path to whatever you choose.
title parameter, for example:
title: "Foomaster Documentation"
host parameter as a full URL, including the protocol (for example, http://). For example:
host: http://docs.example.com
host to construct the URLs in the XML Sitemap that it creates for search engine crawlers, and to limit searches submitted through the search box in the navigation menu to results on your site only.
<form> with the search parameter. If you do not specify a custom web search, Publican creates a Google search limited to the host that you specified in the host parameter.
docs.example.com, set:
search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'
value="###Search###" in the code for a submit button, Publican uses the word Search on the button, localized into any language that Publican supports.
Important — the search parameter is not validated
search parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
def_lang with a language code. For example:
def_lang: fr-FR
def_lang set to fr-FR, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
$ publican update_site command is run. Configure the dump, dump_file, and zip_dump parameters as follows:
dumpdump: 1 to enable the dump file function. This parameter defaults to 0 (off).
dump_filedump_file: name to specify the name of the dump file and the directory in which Publican stores it. This parameter defaults to /var/www/html/DUMP.xml.
zip_dumpzip_dump: 1 to specify that Publican should create a zipped version of the XML file together with the XML version. This parameter defaults to 0 (off).
web_style.
Important
web_style: 2 for your website, you need to have web_style: 2 set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg or overrides.cfg files of the brands that you intend to use with this site.
manual_toc_update parameter, for example:
manual_toc_update: 1
$ publican update_site command.
toc_js parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
toc_path/toc.js with the $ publican update_site command. This path should be relative to the toc_path parameter.
site_overrides.css in the directory that you specified with doc_path (the directory that contains interactive.css and the various language directories). If you want to use site-specific styles to override those provided by interactive.css, you can add a site_overrides.css to the document that provides the site home page — refer to Section 7.1.2, “Creating, installing, and updating the home page”. If you do not want to use site-specific styles, the empty file you add here will prevent 404 errors on your server. On a Linux system, change into the directory that you specified with doc_path and run:
$touch site_overrides.css
common brand.
$cdbrandsrc_dir
$publican build --formats=xml --langs=all --publish
$publican install_brand --web --path=path_to_site_root_dir
$publican update_site
$publican update_site --site_config path_to_site_configuration_file.cfg
<article> with an extra web_type: home parameter in its publican.cfg file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican. To create the home page:
$ publican create command:
$publican create --type Article --name page_name
$publican create --type Article --name Home_Page
common brand) present the name of the document in large, coloured letters close to the top of the page, underneath the banner that contains the product name (the --name option sets the <title> tag). Therefore, by default, the value that you set with the --name option is presented prominently to visitors to your site; in the above example, visitors are greeted with the words Home Page underneath the product banner.
$cd page_name
$cd Home_Page
Article_Info.xml file from your root XML file.
Article_Info.xml file is likely to be useful for the home page of your website. Therefore, edit the root XML file of your home page to remove the <xi:include> tag that links to Article_Info.xml. Publican still uses the information in Article_Info.xml for packaging, but does not include it on the page itself.
publican.cfg file.
web_type parameter and set it to home:
web_type: home
web_type: home parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg file. Other optional changes to the publican.cfg file that are frequently useful for Publican-generated websites include:
brandbrand: name_of_brand
docname, product<title> or the <product> that you set in the Article_Info file included anything other than basic, unaccented Latin characters, set the docname and product as necessary.
page_name.xml file (for example, Home_Page.xml) as you would any other DocBook document.
<xi:include> that links to Article_Info.xml, specify a title for your page in the following format:
<title role="producttitle">FooMaster Documentation</title>
$ publican update_pot and publican update_po commands.
web_logo.png. Place this image in the images/ directory in the document's XML directory, for example en-US/images/.
interactive.css file, add styles to a file named site_overrides.css and place it in the root of your document source (the same directory that contains publican.cfg and the language directories).
--embedtoc option and install it in your website structure. For example:
$publican build --publish --formats html-single --embedtoc --langs all$publican install_book --site_config ~/docsite/foomaster.cfg --lang Language_Code
$ publican install_book command.
<article>s with an extra web_type: product or web_type: version parameter in their publican.cfg files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican. To create a product page or version page:
$ publican create command:
$publican create --type Article --name page_name
$publican create --type Article --name FooMaster
$publican create --type Article --name FooMaster_3
$cd page_name
$cd FooMaster
Article_Info.xml file from your root XML file.
Article_Info.xml file is likely to be useful for product pages or version pages. Therefore, edit the root XML file of your page to remove the <xi:include> tag that links to Article_Info.xml. Publican still uses the information in Article_Info.xml for packaging, but does not include it on the page itself.
publican.cfg file.
web_type parameter and set it to product or version:
web_type: product
web_type: version
web_type parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg file. Other optional changes to the publican.cfg file that are frequently useful for product pages or version pages include:
brandbrand: name_of_brand
docname, product<title> or the <product> that you set in the Article_Info file included anything other than basic, unaccented Latin characters, set the docname and product as necessary.
page_name.xml file (for example, FooMaster.xml) as you would any other DocBook document.
<xi:include> that links to Article_Info.xml, specify a title for your page in the following format:
<title role="producttitle">FooMaster Documentation</title>
$ publican update_pot and publican update_po commands.
--embedtoc option and install it in your website structure. For example:
$publican build --publish --formats html-single --embedtoc --langs all$publican install_book --site_config ~/docsite/foomaster.cfg --lang Language_Code
$ publican install_book command.
$publican build --embedtoc --formats=list_of_formats --langs=language_codes --publish$publican install_book --site_config path_to_site_configuration_file.cfg --lang language_code
$ publican build command for all languages that you want to publish, but must run a separate publican install_book for each language. You must include html as one of the formats in the publican build command; optionally, include any or all of the following formats in a comma-separated list: html-single, pdf, and epub.
$publican remove_book --site_config path_to_site_configuration_file.cfg --lang language_code
Warning — This procedure replaces files
/var/www/html/docs directory. Existing files in this directory might be overwritten by this procedure.
$sudo yum install publican publican-common-web
/etc/publican-website.cfg file to specify the name of the site, the web host, and optionally, search parameters, default language, dump file settings, and web style for the site:
title parameter, for example:
title: "Foomaster Documentation"
host parameter as a full URL, including the protocol (for example, http://). For example:
host: http://docs.example.com
host to construct the URLs in the XML Sitemap that it creates for search engine crawlers, and to limit searches submitted through the search box in the navigation menu to results on your site only.
<form> with the search parameter. If you do not specify a custom web search, Publican creates a Google search limited to the host that you specified in the host parameter.
docs.example.com, set:
search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'
value="###Search###" in the code for a submit button, Publican uses the word Search on the button, localized into any language that Publican supports.
Important — the search parameter is not validated
search parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
def_lang with a language code. For example:
def_lang: fr-FR
def_lang set to fr-FR, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
$ publican update_site command is run. Configure the dump, dump_file, and zip_dump parameters as follows:
dumpdump: 1 to enable the dump file function. This parameter defaults to 0 (off).
dump_filedump_file: name to specify the name of the dump file and the directory in which Publican stores it. This parameter defaults to /var/www/html/DUMP.xml.
zip_dumpzip_dump: 1 to specify that Publican should create a zipped version of the XML file together with the XML version. This parameter defaults to 0 (off).
web_style.
Important
web_style: 2 for your website, you need to have web_style: 2 set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg or overrides.cfg files of the brands that you intend to use with this site.
manual_toc_update parameter, for example:
manual_toc_update: 1
$ publican update_site command.
toc_js parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
toc_path/toc.js with the $ publican update_site command. This path should be relative to the toc_path parameter.
site_overrides.css. If you want to use site-specific styles to override those provided by interactive.css, you can add a site_overrides.css to the document that provides the site home page — refer to Section 7.1.2, “Creating, installing, and updating the home page”. If you do not want to use site-specific styles, the empty file you add here will prevent 404 errors on your server. On a Linux system, run:
#touch /var/www/html/docs/site_overrides.css
$publican update_site
<article> with an extra web_type: home parameter in its publican.cfg file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican and is packaged the same way.
$publican package --binary
/tmp/rpms/noarch/ directory of the home page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver parameter in the home page's publican.cfg file.
rpm -i or yum localinstall command, or place the package in a repository and configure the webserver to install from that repository when you run yum install.
<edition> number or <pubsnumber> in the Article_Info.xml. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.
<article>s with an extra web_type: product or web_type: version parameter in their publican.cfg files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican and are packaged the same way.
$publican package --binary
/tmp/rpms/noarch/ directory of the product page or version page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver parameter in the publican.cfg file of the product page or version page.
rpm -i or yum localinstall command, or place the package in a repository and configure the webserver to install from that repository when you run yum install.
<edition> number or <pubsnumber> in the Article_Info.xml. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.
$publican package --binary --lang language_code
/tmp/rpms/noarch/ directory of the document. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the os_ver parameter in the document's publican.cfg file.
rpm -i or yum localinstall command, or place the packages in a repository and configure the webserver to install from that repository when you run yum install.
<edition> number or <pubsnumber> in the Book_Info.xml or Article_Info.xml. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.
rpm -e or yum erase command.
manual_toc_update parameter in the site's configuration file. With this parameter set, you must run the $ publican update_site command after installing, updating, or removing documents. Refer to Section 7.1.1, “Creating the website structure” for more information.
Procedure 7.1. To Submit Your Sitemap to Google:
Procedure 7.2. To Submit Your Sitemap to Bing:
BingSiteAuth.xml file that Bing provides to the document root of your website.
BingSiteAuth.xml file has been uploaded to the required location by accessing it in a web browser, click the button.
$ publican build command to create the CSV file for Drupal import. Before running the command, use the cd command to change into the directory where your book is located. For example, if you have a book call "User_Guide" in your home directory, then run the following command.
$cd User_Guide/$publican build --langs en-US --formats=drupal-book
tmp/en-US/drupal-book/ directory.
/tmp/en-US/drupal-book/ directory. This directory contains the following files:
$product-$version-$docname-$lang-$edition.csv
Important — Use version control system
$ publican build --langs en-US --formats=drupal-book command, you will notice that the xml files in the en-US directory had been changed. This is because Publican added a 'Conformance' attribute for every xml tag that has id. This attribute contains a number which is unique across xml files in the book. If you are using a version control system like git for your xml files, then you need to commit the changes so that the number won't get reset when other users run it. These unique numbers are very important, because they are use as the url path in drupal. Besides, Publican also created a database file name max_unique_id.db in the en-US directory. This database file is use to track the current maximum unique number in the book, so that Publican can know where you are up to and add a new unique number for your newly created Chapter or Section. Therefore, it is very important to add the database file to the version control and commit it if there is any change. If you add a new section in the xml, don't set the 'Comformance' attribute yourself as that will make the database outdated. Just leave it for publican to set it.
drupal_authorpublican.cfg file to override it.
Important — Setting Author
drupal_menu_titledrupal_menu_block"user-guide".
Important — Setting menu block
drupal_image_path"sites/default/files/".
/var/www/html/drupal/ directory, then you should copy the module to /var/www/html/drupal/sites/all/modules/ directory. To enable the installed module, login to the Drupal site and go to Administer -> Site building -> Modules . In the Development section, tick the and click button to activate the Node Import Module.
Important — Enable Drupal Core Modules
Permission to install Module
drupal_menu_block parameter in publican.cfg.
sites/default/files/imports/ .
import directory.
import directory will be assigned ownership to this user.
Important — File Ownership
Book Page content type is checked.
Procedure 8.1. To import book into Drupal:
import Directory in the Drupal Server
en-US directory to the "sites/default/files/" directory in the Drupal server. This value can be overriden in the publican.cfg. For more details, please read Section 8.2, “The publican.cfg file”
Warning — Section Chunking
$ publican update_po --langs=language, where language is the code for the new language that you want to add. You can add more than one language at a time, with the language codes separated by commas. For example, publican update_po --langs=ja-JP creates the Japanese language directory and Japanese PO files, and publican update_po --langs=ja-JP,ko-KR creates directories and PO files for both Japanese and Korean.
$ publican update_po --langs=es,de,fr?
zh-CN (Simplified Chinese as used in the People's Republic of China) and zh-TW (Traditional Chinese as used in the Republic of China, on Taiwan). Even when only one variety is currently defined, it is always safest to include the country code so that, for example, a future update of Publican does not suddenly cause your German (de-DE) documents to switch to Schweizerdeutsch (Swiss German, de-CH) Common Content and headings.
$ publican update_po --langs=all command.
$ publican build --help command.
$ publican help_config command in a directory that holds any Publican document.
/usr/share/publican/ on Linux operating systems and in %SystemDrive%/%ProgramFiles%/publican/Common_Content on Windows operating systems — typically, C:/Program Files/publican/Common_Content.
files in your source language directory it will be included in any tarballs or SRPM packages that Publican creates.
Important
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.
java.lang.NullPointerException and no PDF file is produced. What is wrong?
$ publican create command. If the problem is not just with one particular document, you probably have a mismatch between the Java Runtime Environment (JRE) and the Java Development Kit (JDK) in use on your system. If you have a JDK installed, FOP requires that the JDK is of the same version as the JRE. Furthermore, FOP cannot use the GNU Compiler for Java (GCJ).
alternatives --config java and alternatives --config javac to determine which JRE and JDK are in use, then select versions that match and which do not have gcj in their name. For example, the following Java configuration shows a matching JRE and JDK that allow PDFs to build:
$alternatives --config javaThere are 3 programs which provide 'java'. Selection Command ----------------------------------------------- 1 /usr/lib/jvm/jre-1.5.0-gcj/bin/java * 2 /usr/lib/jvm/jre-1.6.0-openjdk/bin/java + 3 /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java Enter to keep the current selection[+], or type selection number:
$alternatives --config javacThere are 3 programs which provide 'javac'. Selection Command ----------------------------------------------- *+ 1 /usr/lib/jvm/java-1.6.0-openjdk.x86_64/bin/javac 2 /usr/lib/jvm/java-1.6.0-openjdk/bin/javac 3 /usr/lib/jvm/java-1.5.0-gcj/bin/javac Enter to keep the current selection[+], or type selection number:
alternatives environment correctly. No fix has been determined for this situation.
java.lang.NullPointerException errors and using the alternatives command to ensure that the JRE and JDK match.
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
$ publican build run echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.
<para> tags while it transformed XML because empty <para> tags broke earlier translation toolchains used within Red Hat and the Fedora Project. Empty <para> tags are valid DocBook XML, and Publican no longer removes them.
#!/bin/sh # Jeff Fearn 2010 ASPELL_EXCLUDES=programlisting,userinput,screen,filename,command,computeroutput,abbrev,accel,orgname,surname,foreignphrase,acronym,hardware for file in `find en-US -wholename '*/extras/*' -prune -o -name \*.xml -print`; do echo "Processing $file"; aspell --list --lang=en-US --mode=sgml --add-sgml-skip={$ASPELL_EXCLUDES} < $file | sort -u; echo; done
<segmentedlist>s. When <segmentedlist>s are formatted as tables, the DocBook XSL limits the number of columns to two, and Publican formats <segmentedlist>s as tables.
<programlisting> tag that Syntax::Highlight::Engine::Kate does not recognize, you receive an error when you build your book. The first lines of the error message are similar to:
undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pmline 615.cannot create plugin for language 'JAVA'
<programlisting language="Java"> works, but <programlisting language="java"> and <programlisting language="JAVA"> do not. The error message that you receive identifies the problematic language attribute.
sudo yum install bash-completion.
~/.bashrc file:
# Use bash-completion, if available if [ -f /etc/bash_completion ]; then . /etc/bash_completion fi
source ~/.bashrc.
ulimit -n 8192 to change the limit for the current shell.
/etc/security/limits.conf and add these two lines:
* soft nofile 8192 * hard nofile 8192
Supported, unsupported, and disallowed
$ publican print_known to print a list of tags that Publican supports, and the command publican print_banned to print a list of tags that are banned in Publican.
<caution>, <tip><tip>, <note>, <important>, <caution>, and <warning>. Taken together, these represent a very fine-grained set of distinctions. It is unlikely that these fine distinctions can be applied consistently within a document, especially when more than one person writes or maintains the document. Moreover, this level of granularity is meaningless to readers. By design, Publican disallows the <tip> and <caution> elements, these elements being the two most redundant in the set.
<note> instead of <tip>, and use either <important> or <warning> instead of <caution>. Some criteria by which you might select a suitable level of severity are presented in the ‘Document Conventions’ section of the preface of books produced with Publican's default brand.
<entrytbl><glossdiv>, <glosslist><glossdiv>s that looks like this in English:
Apple — an apple is…
Grapes — grapes are…
Orange — an orange is…
Peach — a peach is…
Manzana — la manzana es…
Uva — la uva es…
Naranja — la naranja es…
Melocotonero — el melocotonero es…
<inlinegraphic><inlinegraphic> is not valid in DocBook version 5.
<link><link> tag provides a general-purpose hyperlink and therefore offers nothing that the <xref> and <ulink> tags do not, for internal and external hyperlinks respectively. The <link> tag is disallowed due to its redundancy.
<olink><olink> tag provides cross-references between XML documents. For <olink>s to work outside of documents that are all hosted within the same library of XML files, you must provide a URL for the document to which you are linking. In environments that use <olink>s, these URLs can be supplied either as an XML entity or with a server-side script. Publican produces documents intended for wide dissemination in which URLs are always necessary for cross-references. Therefore, the <olink> tag offers no advantage over the <ulink> tag, and is disallowed due to its redundancy.
<[element] xreflabel="[any_string_here]"><xreflabel> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.
<chapter id="ch03" xreflabel="Chapter Three"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
<xref> tag becomes an HTML anchor tag as follows:
…see <a href="#ch03">Chapter Three</a> for details.
<xreflabel> attribute. In this case, it means that readers of printed copies have less information available to them.
<xreflabel> attribute the same as the text within the <title></title> element tags. However, this duplication increases the risk of typo-level errors and otherwise offers no underlying improvement. And it still reduces the amount of information presented to readers of printed copies.
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see >xref linkend="ch03"> for details.
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
<xreflabel> attribute. The following:
<chapter id="ch03"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
<xref> element as follows when built to HTML:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
<xreflabel> tags cause. Attribute values are not seen by translators. Consequently, they are not translated. Consider the second example above again:
<chapter id="ch03" xreflabel="The Secret to Eternal Life"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
<xref> is still transformed into an anchor tag as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
<xreflabel> attribute is not used, the title and chapter indicator, both properly translated, appear to the reader. That is, the following:
<chapter id="ch03"> <title>The Secret to Eternal Life</title> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] …see <xref linkend="ch03"> for details.
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
xreflabel attribute is therefore disallowed.
<[element] endterm="[any_string_here]">endterm attribute allows you to present hyperlinked text other than the name of the section or chapter to which the hyperlink points. As such, it decreases the usability of printed versions of documents, and causes difficulty for translators.
<xref>) that contains the endterm attribute is taken from a <titleabbrev> tag in the target chapter or section. Although the content of the <titleabbrev> tag is available to translators in the document's PO files, it is removed from the context of the <xref>. The absence of this context makes reliable translation impossible in languages that mark prepositions or articles for grammatical number and grammatical gender.
<chapter id="The_Secret"> <title>The Secret to Eternal Life</title> <titleabbrev id="final">the final chapter</titleabbrev> <para>The secret to eternal life is…</para> </chapter> [more deathless prose here] The solution is in <xref linkend="The_Secret" endterm="final"/>.
<xref> presents in the English version of the document as:
The solution is inthe final chapter.
<titleabbrev> in a PO file as:
#. Tag: titleabbrev #, no-c-format msgid "the final chapter" msgstr ""
<xref> elsewhere in the PO file (or, more likely, in a completely different PO file) as:
#. Tag: para #, no-c-format msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>." msgstr ""
<xref linkend="The_Secret" endterm="final"/> when the document builds, so a translation in Italian might read:
#. Tag: para #, no-c-format msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>." msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
in.
the final chapter in Italian as l'ultimo capitolo, the result when the document builds will read:
La soluzione è inl'ultimo capitolo.
La soluzione è nell'ultimo capitolo.
in to stand by itself, or which of seven different possible combinations with the definite article to use: nel, nei, nello, nell', negli, nella, or nelle.
<xref>, or in the <titleabbrev>. Whichever of these two solutions the translator selects will cause problems when the endterm appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.
endterm presents for translation, Publican disallows this attribute.
Command options
$ publican --help$ publican --man$ publican --help_actions$ publican --v--config filepublican.cfg.
--nocolours--quietActions
$ publican add_revisionRevision_History.xml. Options:
$ publican build$ publican clean$ publican clean_ids$ publican clean_set$ publican create$ publican create_brandtoc.html file (mandatory).
/usr/share/publican/templates).
$ publican help_configpublican.cfg file.
$ publican install_brand/usr/share/publican/Common_Content on Linux operating systems and at %SystemDrive%/%ProgramFiles%/Publican/Common_Content on Windows operating systems — typically, C:/Program Files/Publican/Common_Content
$ publican copy_web_brand$ publican lang_stats$ publican migrate_site$ publican package--brew to specify a scratch build (meaningless outside Red Hat).
$ publican print_tree<xi:include> tag in a book, article, or set.
<imagedata> tag in a book, article, or set.
$ publican rename$ publican update_pot$ publican update_popdf,html-single
publican update_db --add --lang en-US --formats html,pdf --name Foo \ --name_label "foo is good" --version 0.1 --version_label UNUSED \ --product Bar --product_label "To the bar" \ --subtitle "A guide to Bar Foo" \ --abstract "There once was a Foo from Bar ..." \ --site_config /usr/share/bar/foo.cfg
publican update_db --del --lang en-US --name Foo --version 0.1 --product Bar \ --site_config /usr/share/bar/foo.cfg
publican.cfg file in its root directory. Parameters that can be set in the publican.cfg file are:
docname--name option.
version--version option.
xml_lang--lang option.
edition--edition option.
type<article>, DocBook <book>, or DocBook <set>, set by the --type option.
brand--brand option.
product--product option.
archbooksbrew_distdocs-5E)
bridgehead_in_tocbridgeheads should be included in tables of contents. (Default: 0 — bridgeheads are not included in tables of contents).
chunk_first0 — the first section starts a new HTML page).
chunk_section_depth4)
classpath/usr/share/java/ant/ant-trax-1.7.0.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik-all.jar:/usr/share/java/xml-commons-apis.jar:/usr/share/java/xml-commons-apis-ext.jar)
common_config/usr/share/publican, default for Windows operating systems: %SystemDrive%/%ProgramFiles%/publican — most usually C:/Program Files/publican)
common_content/usr/share/publican/Common_Content, default for Windows operating systems: %SystemDrive%/%ProgramFiles%/publican/Common_Content — most usually C:/Program Files/publican/Common_Content)
conditionconfidential0 — not confidential).
confidential_textCONFIDENTIAL).
debug0 — suppress messages)
def_langen-US — American English)
doc_urlhttps://fedorahosted.org/publican)
dt_obsoletesdt_requiresdtdver4.5)
dtd_typeNote
dtd_uriNote
ec_idec_nameec_providerextras_dirextras)
generate_section_toc_level0 — no tables of contents in sections)
ignored_translationsimg_dirimages)
info_filelicensemainfile<article>, <book>, or <set>, and the name of the corresponding .ent file that contains the document's entities. For example, if you set mainfile: master, Publican looks for the root XML node in master.xml and the document entities in master.ent.
mainfile is not set, Publican looks for the root XML node in a file that matches the <title> of the document set in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file, and looks for the document entities in a file with a corresponding name.
max_image_width<imagedata> tag for a specific image. (Default: 444 — 444 pixels wide)
Important — 444 pixels is the maximum safe width
max_image_width parameter if your images contain important information. Images wider than 444 pixels presented at their full size might lead to poorly presented HTML and to PDF output that it is unusable because the images have run off the page and are incomplete.
menu_category.menu file) in which a document should appear when installed from a desktop RPM package. Refer to Section 4.8.1.3, “Desktop menu entries for documents”.
os_verprod_urlhttps://fedorahosted.org/publican)
releasexml_lang, fetched from the title tag in xml_lang/TYPE_Info.xml or Project-Id-Version in lang/TYPE_Info.po.
reporev_dirasc or ascending.
rev_filescmSVN)
show_remarks0 — hide remarks)
sort_ordersrc_urltmp_dirtmp)
toc.html file (mandatory).
toc_section_depth2)
/usr/share/publican/templates).
web_brew_distdocs-5E)
web_formats$ publican package command”.
web_homeImportant — web_home is deprecated
web_home is replaced by web_type: home. Support for web_home will be removed in a future version of Publican.
web_name_labelweb_obsoletesweb_product_labelweb_typeweb_type: home), product description pages (web_type: product), and version description pages (web_type: version). Refer to Chapter 7, Building a website with Publican.
web_version_labelwkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
publican.cfg parameterspublican.cfg parameters
archarch: x86_64 in the publican.cfg file, Publican will only include XML elements tagged with the equivalent attribute, such as <para arch="x86_64">.
Use with caution
arch can cause great difficulties when translating documents. Refer to Section 4.9.1, “Conditional tagging and translation” for an explanation of the issues.
arch set for root nodes
arch attribute, your document will not build, because empty files are not valid XML. For example, if Installation_and_configuration-PPC.xml contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_PowerPC" arch="PowerPC"> <title>Installation and configuration on PowerPC</title> [text of chapter] </chapter>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: x86 set in the publican.cfg file.
arch attribute to the <xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration-PPC.xml.
xrefs and the arch attribute
<xref> points to content not included in the build due to the arch attribute, the build will fail. For example, with arch: x86 set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="Itanium_installation"> pointing to <section id="Itanium_installation" arch="IA64">.
booksbrandRedHat, fedora, JBoss, oVirt or GIMP , as set by the --brand option for $ publican create. If you do not specify a brand, Publican uses its default brand. Refer to Chapter 5, Branding for more information.
brew_distdocs-5E. Refer to Section 4.8.2, “The $ publican package command” and Section 5.4, “Packaging a brand” for more information on building RPM packages.
bridgehead_in_toc<bridgehead> elements (free-floating titles) should be included among other titles (such as section titles and chapter titles) in tables of contents. To enable this feature, set bridgehead_in_toc: 1. Otherwise, the parameter defaults to 0, and <bridgehead>s are not included in tables of contents.
chunk_firstchunk_first: 1. Otherwise, the parameter defaults to 0, and the first section appears on the same page of its chapter.
chunk_section_depth4.
Example D.1. Controlling the section depth with chunk_section_depth
classpath/usr/share/java/ant/ant-trax-1.7.0.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik-all.jar:/usr/share/java/xml-commons-apis.jar:/usr/share/java/xml-commons-apis-ext.jar
common_config/usr/share/publican. On a computer with a Windows operating system, the default location is %SystemDrive%/%ProgramFiles%/publican — most usually C:/Program Files/publican.
common_content/usr/share/publican/Common_Content. On a computer with a Windows operating system, the default location is %SystemDrive%/%ProgramFiles%/publican/Common_Content — most usually C:/Program Files/publican/Common_Content.
conditionRoot nodes and conditional tagging
Installation_and_configuration_on_Fedora.xml contains a single chapter:
<?xml version='1.0' encoding='utf-8' ?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="chap-Installation_and_configuration_on_Fedora" condition="Fedora"> <title>Installation and configuration on Fedora</title> [text of chapter] </chapter>
User_Guide.xml with an <xi:include> tag, the document will not build with $ condition: Ubuntu set in the publican.cfg file.
<xi:include> tag in User_Guide.xml, not to the <chapter> tag in Installation_and_configuration_on_Fedora.xml.
xrefs and conditional tagging
<xref> points to content not included in the build due to conditional tagging, the build will fail. For example, with $ condition: upstream set in the publican.cfg file, $ publican build --formats=pdf --langs=en-US will fail if the book has the tag <xref linkend="betasection"> pointing to <section id="betasection" condition="beta">.
confidential1, Publican adds the text specified by the confidential_text parameter (by default, CONFIDENTIAL) to the foot of each HTML page and the head of every page in a PDF document. The default value is 0 (no header or footer).
confidential_textconfidential parameter is set to 1. The default text is CONFIDENTIAL.
debug0, Publican does not display debugging messages. Change this value to 1 to view these messages.
def_langdoc_urlimage_right.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican
docname<title> tag in the Book_Info.xml file when you package a document. This value must contain only upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
dt_obsoletesdt_requiresdtdverA different DTD might slow your build
dtd_typeNote
dtd_uriNote
ec_idplugin directory.
ec_nameec_provideredition<edition> tag in the Book_Info.xml file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
extras_dirextras)
footergenerate_section_toc_level0, Publican will generate tables of contents at the start of the document and in parts, chapters, and appendixes, but not in sections. If (for example) the value is set to 1, tables of contents also appear in each "level 1" section, such as sections 1.1, 1.2, 2.1, and 2.2. If set to 2, tables of contents also appear in "level 2" sections, such as sections 1.1.1, 1.1.2, and 1.2.1.
Example D.2. Setting the section depth at which tables of contents appear
ignored_translationses-ES,it-IT. If you build or package a book for a language filtered by this parameter, Publican ignores any translations that exist for this language, and builds or packages the book in the language of the original XML instead. Refer to Section 4.6, “Translating a document”, and to Appendix G, Language codes.
img_dirimages)
info_filelicensemax_image_widthImportant — 444 pixels is the maximum safe width
max_image_width parameter if your images contain important information. Images wider than 444 pixels presented at their full size might lead to poorly presented HTML and to PDF output that it is unusable because the images have run off the page and are incomplete.
mainfile<article>, <book>, or <set>, and the name of the corresponding .ent file that contains the document's entities. For example, if you set mainfile: master, Publican looks for the root XML node in master.xml and the document entities in master.ent.
mainfile is not set, Publican looks for the root XML node in a file that matches the <title> of the document set in the Article_Info.xml, Book_Info.xml, or Set_Info.xml file, and looks for the document entities in a file with a corresponding name.
menu_category.menu file) in which a document should appear when installed from a desktop RPM package. Refer to Section 4.8.1.3, “Desktop menu entries for documents”.
os_ver.fc15 for Fedora 15. The default value is .el5, which signifies Red Hat Enterprise Linux 5 and operating systems derived from it. Refer to Section 4.8, “Packaging a document” and Section 5.4, “Packaging a brand”.
prod_urlimage_left.png image in the Common_Content/images directory for the brand. This parameter defaults to https://fedorahosted.org/publican.
product<productname> tag in the Book_Info.xml file when you package a document. This value must include only contain upper- and lower-case un-accented letters, digits, and the underscore and space characters (‘a–z’, ‘A–Z’, ‘0’–‘9’, and ‘_’ and ‘ ’).
release<pubsnumber> in the Book_Info.xml file when you package a document. This value must include only digits (‘0’–‘9’).
reporev_dirasc or ascending.
rev_fileRevision_History.xml.
scmSVN as its default setting. Refer to Section 6.2, “Distributed sets”.
show_remarks<remark>s in transformed output. By default, this value is set to 0, which causes Publican to hide remarks. Set this value to 1 to display remarks. In Publican's common brand, displayed remarks are highlighted in magenta.
sort_ordersrc_urlSource: field in the header of an RPM spec file. Refer to Section 4.8, “Packaging a document”.
tmp_dirtmp, which creates a directory named tmp inside the directory that holds your article or book.
tmpl_path/usr/share/publican/templates.
toc_jstoc.tmpl is in. The template name must be must be of the form toc_type+.tmpl
toc_typetoc-$toc_type.tmpl in /usr/share/publican/templates. You can override this by setting an alternative path with tmpl_path.
toc_section_depth2. With the default setting, sections 1.1 and 1.1.1 will appear in the main table of contents, but section 1.1.1.1 will not. (Note that the first digit in these examples represents a chapter, not a section).
Example D.3. Controlling the depth of sections in the main table of contents
type<article>, DocBook <book>, or DocBook <set>, as set by the --type option for $ publican create.
version<productnumber> tag in the Book_Info.xml file when you package a document. This value must include only digits and the period (‘0’–‘9’ and ‘.’).
web_brew_distdocs-5E, representing documentation packages for Red Hat Enterprise Linux 5. Refer to Section 4.8, “Packaging a document”.
web_formats$ publican package command”.
web_homeImportant — web_home is deprecated
web_home is replaced by web_type: home. Support for web_home will be removed in a future version of Publican.
web_name_labelweb_obsoletesweb_product_labelweb_style1 and 2. Style 1 features a navigation pane at the left side of the screen that provides access to all of the documents on the site. Style 2 offers a breadcrumb-like navigation system.
web_typeweb_type: home), product description pages (web_type: product), and version description pages (web_type: version). Refer to Chapter 7, Building a website with Publican.
web_version_labelUNUSED for general documentation that does not apply to any particular version of a product. Refer to Chapter 7, Building a website with Publican.
wkhtmltopdf_optswkhtmltopdf_opts: "-O landscape -s A3"
xml_langen-US, as set by the --lang option for $ publican create.
<host>host parameter in the site configuration file.
<def_lang>def_lang parameter in the site configuration file.
<name><title> tag in the Book_Info.xml, Article_Info.xml, or Set_Info.xml file unless overridden by the docname parameter in the publican.cfg file. Any spaces in the title are replaced by underscores.
<ID><abstract><abstract> tag in the Book_Info.xml, Article_Info.xml, or Set_Info.xml file. Publican uses this same content to generate the %description section of the spec file when it packages a document. If the <abstract> is translated, this field contains the translated text.
<format>html for multi-page html, html-single for single-page html, pdf for PDF, and epub for EPUB.
<language><name_label>web_name_label parameter in the document's publican.cfg file. Otherwise, the field is empty for a document in its original language, or uses the translated title of the document in a translated language. Any spaces in the name label are replaced by underscores.
<product><productname> tag in the Book_Info.xml, Article_Info.xml, or Set_Info.xml file unless overridden by the product parameter in the publican.cfg file. Any spaces in the product name are replaced by underscores.
<product_label>web_product_label parameter in the document's publican.cfg file. Otherwise, the field is empty for a document in its original language, or uses the translated title of the document in a translated language. Any spaces in the name label are replaced by underscores.
UNUSED, no heading for this product appears in the website tables of contents.
<subtitle><subtitle> tag in the Book_Info.xml, Article_Info.xml, or Set_Info.xml file. Publican uses this same content to generate the Summary section of the spec file when it packages a document. If the <subtitle> is translated, this field contains the translated text.
<update_date><version><productnumber> tag in the Book_Info.xml, Article_Info.xml, or Set_Info.xml file unless overridden by the version parameter in the publican.cfg file.
<version_label>web_version_label parameter in the document's publican.cfg file.
UNUSED, no heading for this version of the product appears in the website tables of contents.
Example E.1. Sample records from a DUMP.xml file
DUMP.xml file show the same book, the Red Hat Enterprise Linux 5 Installation Guide, in two different formats and two different languages — an English PDF version and a French multi-page HTML version.
<record> <name>Installation_Guide</name> <ID>22</ID> <abstract>This manual explains how to boot the Red Hat Enterprise Linux 5 installation program (anaconda) and to install Red Hat Enterprise Linux 5 on 32-bit and 64-bit x86 systems, 64-bit POWER systems, and IBM System z. It also covers advanced installation methods such as kickstart installations, PXE installations, and installations over VNC. Finally, it describes common post-installation tasks and explains how to troubleshoot installation problems.</abstract> <format>pdf</format> <language>en-US</language> <name_label>Installation_Guide</name_label> <product>Red_Hat_Enterprise_Linux</product> <product_label>Red_Hat_Enterprise_Linux</product_label> <subtitle>Installing Red Hat Enterprise Linux 5 for all architectures</subtitle> <update_date>2010-10-07</update_date> <version>5</version> <version_label></version_label> </record> <record> <name>Installation_Guide</name> <ID>149</ID> <abstract>Ce manuel explique comment lancer le programme d'installation Red Hat Enterprise Linux 5 et comment installer Red Hat Enterprise Linux 5 sur les systèmes x86 32-bit et 64-bit, sur les systèmes POWER 64-bit, et sur les systèmes IBM System z. Il couvre aussi des méthodes d'installation avancées telles que les installations kickstart, PXE, et les installations au moyen de VNC. Finalement, ce manuel décrit les tâches communes post-installation et explique comment résoudre les problèmes liés à une installation.</abstract> <format>html</format> <language>fr-FR</language> <name_label>Guide_d'installation</name_label> <product>Red_Hat_Enterprise_Linux</product> <product_label>Red_Hat_Enterprise_Linux</product_label> <subtitle>Installation de Red Hat Enterprise Linux 5 pour toutes les architectures</subtitle> <update_date>2010-10-19</update_date> <version>5</version> <version_label></version_label> </record>
<host>
<name>
<format>
<language>
<product>
<version>
<host>/<language>/<product>/<version>/<format>/<name>/index.html
http://docs.fedoraproject.org/en-US/Fedora/14/html/Accessibility_Guide/index.html
<host>/<language>/<product>/<version>/<format>/<name>/index.html
http://docs.fedoraproject.org/en-US/Fedora/14/html-single/Accessibility_Guide/index.html
<host>/<language>/<product>/<version>/<format>/<name>/<product>-<version>-<name>-<language>.pdf
http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.pdf
<host>/<language>/<product>/<version>/<format>/<name>/<product>-<version>-<name>-<language>.epub
http://docs.fedoraproject.org/en-US/Fedora/14/pdf/Accessibility_Guide/Fedora-14-Accessibility_Guide-en-US.epub
<product_label>, <version_label>, and <name_label> fields have no significance for URLs, even when these fields are suppressed in tables of contents by the UNUSED setting.
.directory) file and a desktop menu (.menu) file in an RPM package for shipping. Refer to Section 4.8.1.3, “Desktop menu entries for documents” for the structure of these files.
menu-example.directory, a desktop menu file named menu-example.menu, and a readme file named README are located in a directory named menu-example-0 that is archived as menu-example-0.tgz.
Name: menu-example
Version: 0
Release: 8%{?dist}.t1
Summary: Example of how to do a documentation menu package
Group: Development/Tools
License: GPLv2+
URL: http://engineering.redhat.com
Source0: %{name}-%{version}.tgz
BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
BuildArch: noarch
%description
Example of how to do a documentation menu package
%prep
%setup -q
%build
%install
rm -rf %{buildroot}
mkdir -p $RPM_BUILD_ROOT%{_datadir}/desktop-directories
mkdir -p $RPM_BUILD_ROOT/etc/xdg/menus/settings-merged
install -m644 menu-example.directory $RPM_BUILD_ROOT%{_datadir}/desktop-directories/menu-example.directory
install -m644 menu-example.menu $RPM_BUILD_ROOT%{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu
%{_fixperms} $RPM_BUILD_ROOT/*
%clean
rm -rf %{buildroot}
%files
%defattr(-,root,root,-)
%doc README
%{_datadir}/desktop-directories/menu-example.directory
%config(noreplace) %{_sysconfdir}/xdg/menus/settings-merged/menu-example.menu
%changelog
* Tue Nov 23 2010 Jeff Fearn <jfearn@redhat.com> 0-8
- Creation
Region subtags
Other language codes
@ symbol to separate elements — for example, en_GB or sr_RS@latin) do not comply with the XML standard and therefore do not work with Publican.
language-script-region-variant
x- and do not need to be registered. Private-use subtags aside, a subtag is valid if it appears in the registry of subtags maintained by the IETF through the Internet Assigned Numbers Authority (IANA).
[7] Although Publican will accept any language tag that is valid under the rules presented in BCP 47, it is designed around the assumption that language tags for documents will most usually take the form language-region. A brief description of subtags follows:
zh (Chinese), hi (Hindi), es (Spanish), and en (English). Where no two-letter code exists in ISO 639-1, the language subtag is usually a three-letter code identical with the codes specified in ISO 639-2,
[9] for example, bal (Balochi), apk (Kiowa Apache), and tpi (Tok Pisin). Finally, a small number of language subtags appear in the IANA registry that have no ISO 639-1 or ISO 639-2 equivalent, such as subtags for the constructed languages qya (Quenya) and tlh (Klingon), and for the occult language i-enochian (Enochian). This last example also illustrates a small number of language subtags grandfathered into the registry that do not match the two-letter or three-letter pattern of codes derived from the ISO 639 standards.
Extended language subtags
yue represents Cantonese, but this subtag must always be used with the language subtag associated with it (Chinese), thus: zh-yue. The IETF does not yet recognize RFC 5646 as "Best Common Practice", nor are these subtags part of the XML standard yet.
sr-Latn represents Serbian written with the Latin alphabet and sr-Cyrl represents Serbian written with the Cyrillic alphabet; az-Arab represents Azerbaijani written in Arabic script and az-Cyrl represents Azerbaijani written with the Cyrillic alphabet. Conversely, French should not be represented as fr-Latn, because French is not commonly written in any script other than the Latin alphabet anywhere in the world.
AT (Austria), TZ (Tanzania), and VE (Venezuela). The three-digit region subtags are based on those in UN M.49,
[13] for example, 015 (Northern Africa), 061 (Polynesia), and 419 (Latin America and the Caribbean).
nedis denotes Nadiza (also known as Natisone), a dialect of Slovenian. This tag must be used in conjunction with the language subtag for Slovenian, thus: sl-nedis. In September 2009, the IETF issued a Request for Comments (RFC) that (amongst other things) proposes that dialects be represented by language extension subtags attached to language subtags.
[14]
fr-1606nicot (French as documented by Jean Nicot in 1606), de-1901 (German spelling codified by the 2nd Orthographic Conference in 1901) and be-1959acad (Belarusian as codified by the Orthography Commission in 1959).
zh-Latn-wadegile is Chinese written in the Latin alphabet, according to the transliteration system developed by Thomas Wade and Herbert Giles; ja-Latn-hepburn is Japanese written in the Latin alphabet using the transliteration system of James Curtis Hepburn.
| Revision History | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Revision 4.0-5 | Thu Mar 27 2014 | ||||||||||
| |||||||||||
| Revision 4.0-4 | Mon Nov 25 2013 | ||||||||||
| |||||||||||
| Revision 4.0-3 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
| Revision 4.0-2 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
| Revision 4.0-1 | Thu Nov 14 2013 | ||||||||||
| |||||||||||
| Revision 3.2-1 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
| Revision 3.2-0 | Thu Jul 11 2013 | ||||||||||
| |||||||||||
| Revision 3.1-0 | Tue Jan 8 2013 | ||||||||||
| |||||||||||
| Revision 3.0-0 | Mon Feb 20 2012 | ||||||||||
| |||||||||||
| Revision 2.7-1 | Tue Sep 6 2011 | ||||||||||
| |||||||||||
| Revision 2.6-1 | Mon Jul 18 2011 | ||||||||||
| |||||||||||
| Revision 2.4-1 | Wed Dec 1 2010 | ||||||||||
| |||||||||||
| Revision 2.3-0 | Mon Oct 25 2010 | ||||||||||
| |||||||||||
| Revision 2.3-0 | Tue Oct 5 2010 | ||||||||||
| |||||||||||
| Revision 2.2-0 | Thu Aug 19 2010 | ||||||||||
| |||||||||||
| Revision 2.1-1 | Fri Jul 16 2010 | ||||||||||
| |||||||||||
| Revision 1.6-1 | Mon May 24 2010 | ||||||||||
| |||||||||||
| Revision 1.6-0 | Fri May 7 2010 | ||||||||||
| |||||||||||
| Revision 1.5-0 | Fri Feb 26 2010 | ||||||||||
| |||||||||||
| Revision 1.4-0 | Wed Feb 17 2010 | ||||||||||
| |||||||||||
| Revision 1.3-0 | Mon Dec 7 2009 | ||||||||||
| |||||||||||
| Revision 1.2-0 | Fri Nov 27 2009 | ||||||||||
| |||||||||||
| Revision 1.1-1 | Thu Nov 26 2009 | ||||||||||
| |||||||||||
| Revision 1.1-0 | Thu Oct 22 2009 | ||||||||||
| |||||||||||
| Revision 1.0-0 | Tue Oct 13 2009 | ||||||||||
| |||||||||||
| Revision 0.5-0 | Thu Dec 18 2008 | ||||||||||
| |||||||||||
| Revision 0.4-0 | Tue Nov 25 2008 | ||||||||||
| |||||||||||
| Revision 0.3-0 | Fri Oct 10 2008 | ||||||||||
| |||||||||||
| Revision 0.2-0 | Fri Sep 05 2008 | ||||||||||
| |||||||||||
| Revision 0.1-1 | Fri Jun 06 2008 | ||||||||||
| |||||||||||
| Revision 0.1-0 | Fri May 16 2008 | ||||||||||
| |||||||||||
| Revision 0.0-0 | Thu Dec 13 2007 | ||||||||||
| |||||||||||