Product SiteDocumentation Site

⁠Chapter 5. Branding

5.1. Installing a brand
5.2. Creating a brand
5.3. Files in the brand directory
5.3.1. The publican.cfg file
5.3.2. The defaults.cfg file and overrides.cfg file
5.3.3. publican-brand.spec file
5.3.4. README
5.3.5. COPYING
5.3.6. Common Content for the brand
5.3.7. The css subdirectory
5.3.8. The images subdirectory
5.3.9. The brand_dir option
5.4. Packaging a brand
Brands are collections of files that Publican uses to apply a consistent look and style to HTML and PDF output. They provide boilerplate text that appears at the beginning of documents, images such as logos, and stylistic elements such as color schemes. Publican ships with one brand, 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).

⁠5.1. Installing a brand

Publican brands for Fedora, Genome, and oVirt documents are available as RPM packages in Fedora. Similarly, Red Hat internally distributes RPM packages containing Publican brands for GIMP, JBoss, and Red Hat documents. Providing that you have access to the relevant repositories, you can install these brands on a computer that runs Red Hat Enterprise Linux or Fedora — or an operating system derived from either — with the command yum install publican-brand or with a graphical package manager such as PackageKit.
If you use Publican on an operating system that does not use RPM packages, your documentation project might provide its brand in another format. Whatever the format in which the brand is supplied, you must place the brand files in a subdirectory of the Publican 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
Each currently available brand is distributed under a brand-specific license as follows:
To install the brand:
  1. If the brand was supplied to you in an archive of some kind, for example, a tarball or ZIP file, unpack the brand into a new directory on your system.
  2. Change into the directory in which you created or unpacked the brand: 
    $ cd publican-brand
    where brand is the name of the brand.
  3. Build the brand: 
    $ publican build --formats xml --langs all --publish
  4. Install the brand: 
    $ sudo publican install_brand --path path
    where path is the path to the Publican Common Content files. For example, on a Linux system, run: 
    $ sudo publican install_brand --path /usr/share/publican/Common_Content
    or on a Windows system, run 
    $ 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.
Note the difference in licensing between the common content files provided in the common brand (CC0) and the default license set for books generated with the common brand (GFDL). The CC0 license allows you to redistribute and relicense the files that make up the common brand (including the CSS and image files) to suit your project. Publican suggests the GFDL for documentation by default because Publican is developed primarily to build documentation for software. The GFDL is compatible with the GPL, which is the most commonly used license for open-source software.

⁠5.2. Creating a brand

Use the $ 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 creates a new subdirectory named publican-brand, where brand is the brand that you specified with the --name option.
For example, to create a brand called Acme, which will have its Common Content XML files written originally in American English, run: 
$ publican create_brand --name=Acme --lang=en-US
Publican creates the brand in a subdirectory named publican-Acme.
To configure your new brand, search for the word 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' *

⁠5.3. Files in the brand directory

Running the $ 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
  • a subdirectory for the brand's XML files, CSS stylesheets, and default images. The subdirectory is named with the language code of the original language of the brand (for example, en-US). These files are:
    • Feedback.xml
    • Legal_Notice.xml
    • the css subdirectory, which contains:
      • overrides.css
    • the images subdirectory, which contains 43 images in both raster (PNG) and vector (SVG) formats.

⁠5.3.1. The publican.cfg file

The 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
specifies the version number for the brand. When you create the brand with $ 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.
Note that this parameter is unrelated to the version number of documents built with this brand. For example, the Fedora 12 Installation Guide has its version set as 12 in its publican.cfg file, but might be built with version 1.0 of the publican-fedora brand.
xml_lang
specifies the language of the source XML files for the brand's Common Content, for example, en-US, as set by the --lang option for $ publican create_brand.
release
specifies the release number for the brand. When you create the brand with $ 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.
type
when set to type: brand, this parameter identifies the contents of this directory as a brand, rather than a book, article, or set.
brand
specifies the name of the brand, as set by the --name option for $ publican create_brand.
web_cfg
the full path for the Publican site configuration file for non standard RPM websites.
web_dir
the full path to where files will be installed. You must also set wwwdir in publican-brand.spec.
web_req
the name of the RPM package that will supply the Publican site config file.

⁠5.3.2. The defaults.cfg file and overrides.cfg file

Every document built in Publican has a publican.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.
When you build a document with a particular brand, Publican first applies the values in the brand's 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.
Publican next applies the values in the brand's overrides.cfg file, which therefore override any values in the brand's defaults.cfg file and the document's publican.cfg file.
Use the 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.
You can add a list of banned tags or attributes using banned_tags and banned_attrs respectively to either defaults.cfg or overrides.cfg. These will be listed by the Publican action print_banned.

⁠5.3.3. publican-brand.spec file

Some Linux operating systems use the RPM Package Manager to distribute software, in the form of RPM packages. In general terms, an RPM package contains software files compressed into an archive, accompanied by a spec file that tells the RPM Package Manager how and where to install those files.
When you create a brand, Publican generates the outline of an RPM spec file for the brand. The automatically generated spec file provides you with a starting point from which to create an RPM package to distribute your brand. Refer to Section 5.4, “Packaging a brand” to learn how to configure the spec file and use it to produce an RPM package.

⁠5.3.4. README

The README file contains a brief description of the brand package.

⁠5.3.5. COPYING

The COPYING file contains details of the copyright license for the package and perhaps the text of the license itself.

⁠5.3.6. Common Content for the brand

Inside the brand directory is a subdirectory named after the default XML language for brand, as set with the --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.

⁠5.3.6.1. Feedback.xml

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

⁠5.3.6.2. Legal_Notice.xml

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

⁠5.3.7. The css subdirectory

The css subdirectory contains a single file: overrides.css.

⁠5.3.7.1. overrides.css

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

⁠5.3.8. The images subdirectory

The images 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_left
is a logo for the product to which this document applies. It appears at the top left corner of HTML pages, where it contains a hyperlink to a web page for the product, as defined by prod_url in the publican.cfg file for the document. Consider setting prod_url in the brand's defaults.cfg or overrides.cfg file.
image_right
is a logo for the team that produced this documentation. It appears at the top right corner of HTML pages, where it contains a hyperlink to a web page for the documentation team, as defined by doc_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_logo
is a larger version of your product logo, which appears on the title page of PDF documents and at the start of HTML documents.
note, important, warning
are icons that accompany the XML admonitions <note>, <important>, and <warning>.
dot, dot2
are bullets used for <listitem>s in <itemizedlist>s.
stock-go-back, stock-go-forward, stock-go-up, stock-home
are navigation icons for HTML pages.
h1-bg
is a background for the heading that contains the name of your product, as it appears at the very beginning of a HTML document.
watermark_draft
is a watermark that appears on pages of draft documentation. Refer to Section 4.10.2, “Denoting draft documentation”.

⁠5.3.9. The brand_dir option

The Publican build option brand_dir allows you to specify the location of brand files. These files do not have to be part of an installed brand.
You can ship custom XSL in a folder named xsl 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

Brands with custom XSLT need to change the relative path of referencing XSL templates to a URI.

⁠5.4. Packaging a brand

Packages other than RPM packages

This section discusses packaging documents for distribution through the RPM Package Manager. However, when you use the $ 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.
After you create a brand (as described in Section 5.2, “Creating a brand”), Publican can help you to distribute the brand to members of your documentation project as RPM packages. RPM packages are used to distribute software to computers with Linux operating systems that use the RPM Package Manager. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
Publican can produce both source RPM packages (SRPM packages) and binary RPM packages. As part of this process, it also creates the spec file — the file that contains the details of how a package is configured and installed.
SRPM packages contain the source code used to generate software rather than the software itself. To use an SRPM package, a computer must compile the source code into software. SRPM packages of Publican brands contain the configuration files, XML files, and image files that define the brand in its original language, plus the PO files that generate the Common Content files in translated languages. You cannot install documentation directly from SRPM packages with current versions of the RPM Package Manager.
Conversely, binary RPM packages contain software — in this case, a Publican brand — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed, and therefore, the computer does not need to have Publican installed.
To package a brand, use the $ 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
specifies that Publican should build the package as a binary RPM package.
--brew
specifies that Publican should push the completed package to Brew. Brew is the build system used internally by Red Hat; this option is meaningless outside Red Hat.
--scratch
when used together with the --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.
The --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.
By default, Publican brand packages are named:
publican-brand-version-release.build_target.noarch.file_extension.
Publican uses the information in the 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:
  • SRPM packages have the file extension .src.rpm but binary RPM packages have the file extension .rpm
  • binary RPM packages include 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.