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 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_cfgthe 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_reqthe name of the RPM package that will supply the Publican site config 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 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.
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, “Packaging a brand” to learn how to configure the spec file and use it to produce an RPM package.
The README file contains a brief description of the brand package.
The COPYING file contains details of the copyright license for the package and perhaps the text of the license itself.
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.
css subdirectory
The css subdirectory contains a single file: 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.
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_logois 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-homeare navigation icons for HTML pages.
h1-bgis a background for the heading that contains the name of your product, as it appears at the very beginning of a HTML document.
watermark_draftis a watermark that appears on pages of draft documentation. Refer to Section 10.2, “Denoting draft documentation”.
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.