Chapter 6. Building a website with Publican

Publican not only builds documents for publication but can build and manage a documentation website as well. For a suite of documents that you maintain by yourself, you can use Publican to build a site on your local system; you can then upload the site to a webserver. by whatever means you choose. This approach does not scale well, however, so for team-based documentation projects, Publican can generate RPM packages of documentation to install on the webserver.

The websites that Publican creates consist of three parts: the website structure, a home page, and the documents published on the site.

6.1. The website structure

The website structure itself consists of:

a configuration file.
an SQLite database file.
a subdirectory for the published documents, which contains:
- index.html — an index page with no content that redirects to localized versions of a home page for the site.
- interactive.css — a CSS stylesheet that contains styles for the navigation menu, map, and site statistics page.
- Sitemap — an XML Sitemap to assist search engines to crawl the site.
- toc.html — a static map of the documents on the site, to assist visitors to the site who do not have JavaScript enabled on their browsers.
- toc.js — a JavaScript script that directs visitors to localized content based on the locale set in their browser and controls the presentation of the navigation menu.
- subdirectories for each language in which you publish. Initially, this contains: Site_Statistics.html
  - Site_Statistics.html — an overview of the documentation installed on the site.
  - Site_Tech.html — an overview of the technology used to build the site.
  - toc.html — the table of contents for that language, initially empty.

6.1.1. Creating the website structure

To build the website structure:

Create a new directory and change into it. For example, on a Linux system, run:
```
mkdir ~/docsite
cd ~/docsite
```
Run publican create_site, specifying the following parameters:
- --site_config — the name of the configuration file for your site, with the filename extension .cfg
- --db_file — the name of the SQLite database file for your site, with the filename extension .db
- --toc_path — the path to the directory in which you will place your documents
On a computer with an operating system other than Linux, also set:
- --temp_path — the path to the templates/ directory of your Publican installation. On computers with Windows operating systems, this is typically %SystemDrive%\%ProgramFiles%\Publican\templates.
For example:
```
publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
```
Typically, you might give names to the site configuration file and database file that help you to recognize the site to which they belong. For example, for the FooMaster documentation site, you might call these files foomaster.cfg and foomaster.db.
If you plan to install documentation on the webserver with Publican-generated RPM packages, set --toc_path to /var/www/html/docs. If you plan to build the site manually and upload it to the webserver, you can set --toc_path to whatever you choose.
If you plan to install Publican-generated RPM packages of documents on the site, transfer the site structure to the /var/www/ directory of your webserver now by whatever process you usually use, for example scp, rsync, or an FTP client. If you plan to build the site manually, you can wait until you finish building the site and then upload the complete site.

To make Publican refresh the site structure at any time, run:

publican update_site --site_config path_to_site_configuration_file.cfg

6.2. The home page

The Publican-generated home page is the localizable page to which visitors are directed by the site JavaScript and which provides the style for the website structure. The home page is structured as a DocBook <article> with an extra web_home parameter in its publican.cfg file. To create the home page:

Change into a convenient directory and run the following publican create command:

publican create --type Article --name page_name

For example:

publican create --type Article --name Home_Page

Change into the article directory. For example:
```
cd Home_Page
```
Edit the Article_Info.xml file to configure the product name and version number. As with other documents created with Publican, the product name and product version number appear in a banner at the top of the page when built as HTML. Unless the entire site documents only a single version of a product, you might want to suppress the version number. If so, make the <productnumber> tag empty, thus:
```
<productnumber></productnumber>
```
You might also want to remove or re-order some of the typical content of a DocBook article as rendered by Publican, such as the <abstract>, <corpauthor>, and the transcluded <authorgroup> and <legalnotice>.
Alternatively, edit the root XML file of your home page to remove the <xi:include> that links to Article_Info.xml. Publican still uses the information in Article_Info.xml for packaging, but does not include it on the page itself.
Edit the publican.cfg file to add the web_home parameter and set it to 1 (enabled):
```
web_home: 1
```
The web_home parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg file. The rest of this step describes other parameters that might be useful but which are not required.
To style your home page to match your documents, add:
```
brand: name_of_brand
```
If you emptied the <productnumber> tag in the Article_Info.xml file, set:
```
version: 0.1
```
If the <title> or the <product> that you set in the Article_Info file included anything other than basic, unaccented Latin characters, set the docname and product as necessary.
Publican creates a separate, translatable navigation menu for each language in which you publish documentation. However, a document is not available in a particular language, Publican links visitors to the translated version of that document. To specify the default, untranslated language for the site, set def_lang with a language code. For example:
```
def_lang: fr-FR
```
With def_lang set to fr-FR, visitors viewing the navigation menu in (for example) Spanish are presented with a link to the original French version of the document if the document has not yet been translated into Spanish.
The navigation menu also includes a search box that submits a query to Google. To constrain the results to only hits on your site, set the web_host parameter. For example, to limit the Google results to only pages on your website at http://docs.example.com, set:
```
web_host: http://docs.example.com
```
Publican also uses the value set for web_host to construct the URLs in the XML Sitemap that it creates for search engine crawlers. Therefore, when you set this parameter, make sure you use the full URL, including the protocol (for example, http://).
If you prefer to use a search engine other than Google, or want to customize the search, use the web_search parameter to specify the entire content of a HTML <form>. For example, to construct a Yahoo! search limited to docs.example.com, set:
```
web_search: '<form target="_top" method="get" action="http://search.yahoo.com/search"> <div class="search"> <input type="text" name="p" value="" /> <input type="hidden" name="vs" value="docs.example.com" /> <input type="submit" value="###Search###" /> </div> </form>'
```
Refer to the documentation of your chosen search engine for details of how to construct custom searches.
If you set value="###Search###" on the code for a submit button, Publican uses the word Search on the button, localized into any language that Publican supports.
Important — Publican does not validate the web_search parameter
Publican does not validate the web_search parameter, but builds the value of this parameter into the navigation menu exactly as you specify it. Be especially careful when you use this feature.
Edit the content of the page_name.xml file (for example, Home_Page.xml) as you would any other DocBook document.
If you remove the <xi:include> that links to Article_Info.xml, specify a title for your page in the following format:
```
<title role="producttitle">FooMaster Documentation</title>
```
If you publish documentation in more than one language, create a set of POT files and a set of PO files for each language with the publican update_pot and publican update_po commands.
To customize the logo at the top of the navigation menu that provides a link back to the home page, create a PNG image 300 px × 100 px and name it web_home.png. Place this image in the images/ directory in the document's XML directory, for example en-US/images/.
If you are building your website manually, build the home page in single-page HTML format with the --embedtoc option and install it in your website structure. For example:
```
publican build --publish --formats html-single --embedtoc 
publican install_book --site_config ~/docsite/foomaster.cfg
```
Alternatively, to build RPM packages to install on your webserver, run the following command for each language in which you publish documentation:
```
publican package --binary --lang language_code
```

6.3. Installing, updating and removing documents

6.3.1. Installing, updating and removing documents manually

To install a document on a website that you are building manually, change into the directory that contains the source for the document and run:

publican build --embedtoc --formats=list_of_formats --langs=language_codes --publish 
publican install_book --site_config path_to_site_configuration_file.cfg --lang language_code

Note that you can run a single publican build command for all languages that you want to publish, but must run a separate publican install_book for each language. You must include html as one of the formats in the publican build; optionally, include any or all of the following formats in a comma-separated list: html-single, pdf, and epub.

To update a document, change into the directory that contains the updated source for the document and run the same commands as if you were installing the document for the first time. Publican replaces the old version with the new version.

To remove a document, change into the directory that contains the source for the document and run:

publican remove_book --site_config path_to_site_configuration_file.cfg --lang language_code

When you have installed the documents, the website is ready to upload to your webserver by whatever process you usually use, for example scp, rsync, or an FTP client.

6.3.2. Installing, updating and removing documents as RPM packages

To use an RPM package to install a document on a website, change into the directory that contains the source for the document and run:

publican package --binary --lang language_code

Publican builds an RPM package and places it in the /tmp/rpms/noarch/ directory of the document. Note that by default, Publican generates an RPM package to install on a Red Hat Enterprise Linux 5 server. To build an RPM package to install on a server that runs a different operating system, set the os_var parameter in the publican.cfg file.

Either upload the document packages to the webserver and install them with the rpm -i or yum localinstall command, or place the packages in a repository and configure the webserver to install from that repository when you run yum install.

To update a document, build a new package with a higher <edition> number or <pubsnumber> in the Book_Info.xml or Article_Info.xml. Publican uses these values to set the version and release numbers for the RPM package. When you install this package on your webserver, yum can replace the old version with the new when you run yum localinstall for a local package, or yum update for a package fetched from a repository.

Remove a document from the webserver with the rpm -e or yum erase command.

6.4. Automating publishing

Because Publican can generate RPM packages, you can use Publican together with an RPM build system like Koji to automate your publishing process. When a document is ready for publication, the writer or translator runs the following command:

publican package --cvs

Publican then carries out the following actions:

generates an SRPM
imports the SRPM into the CVS root for the Koji instance specified in the document's publican.cfg file
runs cvs up
runs make build

If your webserver periodically checks for updated packages in the repository in which Koji places built packages, the webserver can automatically install updated versions of your documents.

You might also implement a system of tags where a writer or translator could run koji tag-pkg to apply a tag that tells the webserver to publish the document only on a staging site for proofreading and review; or a different tag that tells the webserver to publish the document publicly.

To prepare a document for building in a Koji instance, edit the publican.cfg file to specify:

cvs_branch: the name of the branch for the package; typically, a particular software version.
cvs_pkg: the name of the package in CVS. Publican defaults to: product-title-product_version-web-language-edition-pubsnumber
cvs_root: the CVS root into which to import the SRPM. For example, the CVS root for the Fedora Project's Koji instance is :ext:USERNAME@cvs.fedoraproject.org:/cvs/pkgs

For more information about Koji, visit https://fedorahosted.org/koji/wiki.