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

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

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

## 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 to learn how to configure the spec file and use it to produce an RPM package.

## README

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

## COPYING

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

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

### `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.

### `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.

## The `css` subdirectory

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

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

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

## 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).

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