- Prev
- Users' Guide
- Next

# Chapter 5. Branding

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 that supply XSL files need to change the relative path 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.

- PrevChapter 4. Creating a document
- Up
- Home
- NextChapter 6. Using sets