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.