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).
yum install publican-brand
or with a graphical package manager such as PackageKit.
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
$
cd publican-brand
$
publican build --formats xml --langs all --publish
$
sudo publican install_brand --path path
$
sudo publican install_brand --path /usr/share/publican/Common_Content
$
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. |
$
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-brand
, where brand is the brand that you specified with the --name
option.
Acme
, which will have its Common Content XML files written originally in American English, run:
$
publican create_brand --name=Acme --lang=en-US
publican-Acme
.
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' *
$
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
en-US
). These files are:
Feedback.xml
Legal_Notice.xml
css
subdirectory, which contains:
overrides.css
images
subdirectory, which contains 43 images in both raster (PNG) and vector (SVG) formats.
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
$
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.
12
in its publican.cfg
file, but might be built with version 1.0 of the publican-fedora brand.
xml_lang
en-US
, as set by the --lang
option for $
publican create_brand
.
release
$
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
type: brand
, this parameter identifies the contents of this directory as a brand, rather than a book, article, or set.
brand
--name
option for $
publican create_brand
.
web_cfg
web_dir
publican-brand.spec
.
web_req
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.
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.
overrides.cfg
file, which therefore override any values in the brand's defaults.cfg
file and the document's publican.cfg
file.
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.
defaults.cfg
or overrides.cfg
. These will be listed by the Publican action print_banned.
README
file contains a brief description of the brand package.
COPYING
file contains details of the copyright license for the package and perhaps the text of the license itself.
--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
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
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
subdirectorycss
subdirectory contains a single file: overrides.css
.
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
subdirectoryimages
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
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
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
note
, important
, warning
<note>
, <important>
, and <warning>
.
dot
, dot2
<listitem>
s in <itemizedlist>
s.
stock-go-back
, stock-go-forward
, stock-go-up
, stock-home
h1-bg
watermark_draft
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
Packages other than RPM packages
$
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.
$
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
--brew
--scratch
--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.
--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.
publican-brand-version-release.build_target.noarch.file_extension
.
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:
.src.rpm
but binary RPM packages have the file extension .rpm
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.