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

4.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 1.0. Update the version number here in the brand publican.cfg file and in the brand publican.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 brand publican.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.

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

4.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 4.4, “Packaging a brand” to learn how to configure the spec file and use it to produce an RPM package.

4.3.4. README

The README file in an SRPM package includes a brief description of the package.

4.3.5. COPYING

The COPYING file in an SRPM package contains details of the copyright license for the package.

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

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

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

4.3.7. The `css` subdirectory

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

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

4.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 3.7.2, “Denoting draft documentation”.