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. To install Publican-generated RPM packages on a webserver, Publican (version 2.1 or higher) and rpm must be installed on the server. If you build and maintain the website on a workstation and upload it to a webserver for publication, Publican and rpm do not need to be installed on the webserver.
The websites that Publican creates consist of four parts: the website structure, a home page, product and version description pages, and the documents published on the site. 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 that redirects to localized versions of a home page for the site.
interactive.css
— a CSS stylesheet that contains styles for the navigation menu.
opds.xml
— an Open Publication Distribution System (OPDS) catalog to allow compliant eBook readers to find EPUB documents on your site easily.
Sitemap
— A Sitemap is a list of the URLs from your website and metadata about them, like update history, change frequency, and importance relative to other URLs in the site. A Sitemap can be supplied to many major search engines, where it is used to help their crawlers index your site more intelligently. A Sitemap does not guarantee that your site will be ranked higher in search results. However, it does help search engines to return the most relevant results from your website in response to user queries. For more information on Sitemaps, visit sitemaps.org.
site_overrides.css
— a CSS stylesheet that overrides the styles contained in interactive.css
to provide site-specific styles. This file is not created by the site creation process, but must be added manually later, or supplied by the site home page.
default.js
— a JavaScript script that directs visitors to localized content based on the locale set in their browser and which controls the presentation of the navigation menu.
subdirectories for each language in which you publish. Initially, this contains opds.xml
and toc.html
. Later it also contains opds-product.xml
:
opds.xml
— an OPDS catalog of EPUB documents in this language.
opds-product.xml
— an OPDS catalog of EPUB documents for each product for which you publish documentation in this language. Within each product catalog, documentation is divided into <category>
s for different versions of the same product.
toc.html
— the table of contents for that language, initially without links to any documents.
A subdirectory for each product for which you publish documentation in this language.
Optionally, the site structure might also include a dump file — an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The site structure might also contain a zipped version of the dump file. Refer to Section 1.1, “Creating the website structure” and Section 1.1, “Creating the website structure” for details of creating a dump file, and to Appendix D, Contents of the website dump file for a description of the dump file contents.
To build the website structure:
On your workstation, 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:
--tmpl_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
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
. You can set --toc_path
to whatever you choose.
Edit the site configuration file to specify the name of the site, the web host, and optionally, search parameters, default language, dump file settings, and update settings for the site:
Specify the title with the title
parameter, for example:
title: "Foomaster Documentation"
Normally, visitors to your website do not see this title because the site's JavaScript redirects them to a homepage. However, this title is likely to be found and indexed by search engines.
Specify the web host with the host
parameter as a full URL, including the protocol (for example, http://
). For example:
host: http://docs.example.com
Publican uses the value set for host
to construct the URLs in the XML Sitemap
that it creates for search engine crawlers, and to limit searches submitted through the search box in the navigation menu to results on your site only.
Optionally, construct a search engine query to use with the search box in the navigation menu and specify the entire content of a HTML <form>
with the search
parameter. If you do not specify a custom web search, Publican creates a Google search limited to the host that you specified in the host
parameter.
For example, to construct a Yahoo! search limited to docs.example.com
, set:
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###"
in the code for a submit button, Publican uses the word Search
on the button, localized into any language that Publican supports.
Publican does not validate the 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.
Optionally, set the default language of the website. Publican creates a separate, translatable navigation menu for each language in which you publish documentation. However, if a document is not available in a particular language, Publican links visitors to the untranslated 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.
Optionally, configure a dump file for the website. Publican can output an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The file is updated whenever a book is installed or removed from the site, or the $
publican update_site command is run. Configure the dump
, dump_file
, and zip_dump
parameters as follows:
dump
Set dump: 1
to enable the dump file function. This parameter defaults to 0
(off).
dump_file
Set dump_file: name
to specify the name of the dump file and the directory in which Publican stores it. This parameter defaults to /var/www/html/DUMP.xml
.
zip_dump
Set zip_dump: 1
to specify that Publican should create a zipped version of the XML file together with the XML version. This parameter defaults to 0
(off).
Refer to Appendix D, Contents of the website dump file for a description of the contents of the dump file.
Optionally, specify the web style with the web_style
.
The website resembles those produced by Publican 2, with a list of products displayed in a navigation pane at the left of the page. (Default)
The website includes a breadcrumb-like navigation bar across the top of the documentation.
The web style set for your site must match the web style set for your content. For example, if you set web_style: 2
for your website, you need to have web_style: 2
set in each of the books that you want to install on the site. Consider setting this parameter in the defaults.cfg
or overrides.cfg
files of the brands that you intend to use with this site.
Optionally, specify that the site tables of contents will be updated manually with the manual_toc_update
parameter, for example:
manual_toc_update: 1
Normally, Publican updates the site's tables of contents every time a documentation package is added or removed. On a site with a large number of documents on it (more than a few hundred), or where documents are updated very frequently (dozens of updates per week), this process is very demanding on a server. On a large or busy site, we recommend that you set this parameter and then periodically update the tables of contents with the $
publican update_site command.
Optionally, override the default JavaScript for the site with the toc_js
parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
This file will be symlinked as toc_path
/toc.js with the $
publican update_site command. This path should be relative to the toc_path
parameter.
Create an empty file named site_overrides.css
in the directory that you specified with doc_path
(the directory that contains interactive.css
and the various language directories). If you want to use site-specific styles to override those provided by interactive.css
, you can add a site_overrides.css
to the document that provides the site home page — refer to Section 1.2, “Creating, installing, and updating the home page”. If you do not want to use site-specific styles, the empty file you add here will prevent 404 errors on your server. On a Linux system, change into the directory that you specified with doc_path
and run:
$
touch site_overrides.css
Build and install each brand, including the Publican common
brand.
Change into the directory that holds the source for the brand.
$
cd brandsrc_dir
Build the brand.
$
publican build --formats=xml --langs=all --publish
Install the brand on your website.
$
publican install_brand --web --path=path_to_site_root_dir
Perform these steps for all brands.
Update the site.
$
publican update_site
To make Publican refresh the site structure at any time, run:
$
publican update_site --site_config path_to_site_configuration_file.cfg
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_type: home
parameter in its publican.cfg
file. In its structure and its presentation, the home page is the same as any other article that you produce with Publican. 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
Most brands (including the common
brand) present the name of the document in large, coloured letters close to the top of the page, underneath the banner that contains the product name (the --name
option sets the <title>
tag). Therefore, by default, the value that you set with the --name
option is presented prominently to visitors to your site; in the above example, visitors are greeted with the words Home Page
underneath the product banner.
Change into the article directory:
$
cd page_name
For example:
$
cd Home_Page
Unlink the Article_Info.xml
file from your root XML file.
Little of the content of the Article_Info.xml
file is likely to be useful for the home page of your website. Therefore, edit the root XML file of your home page to remove the <xi:include>
tag 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.
At the very least, you must add the web_type
parameter and set it to home
:
web_type: home
The web_type: home
parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg
file. Other optional changes to the publican.cfg
file that are frequently useful for Publican-generated websites include:
brand
To style your home page to match your documents, add:
brand: name_of_brand
docname
, product
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.
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 290 px × 100 px and name it web_logo.png
. Place this image in the images/
directory in the document's XML directory, for example en-US/images/
.
To specify site-specific styles to override the styles set in the website's interactive.css
file, add styles to a file named site_overrides.css
and place it in the root of your document source (the same directory that contains publican.cfg
and the language directories).
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 --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Language_Code
Note that you can build all languages at the same time, but must install the home page for each language with a separate $
publican install_book command.
Publican-generated product pages and version pages are the localizable pages that provide a general overview of a product or version respectively. Visitors access these pages by clicking on a product or version in the navigation menu. The pages are structured as DocBook <article>
s with an extra web_type: product
or web_type: version
parameter in their publican.cfg
files. In their structure and presentation, product pages and version pages are the same as any other article that you produce with Publican. To create a product page or version page:
Change into a convenient directory and run the following $
publican create command:
$
publican create --type Article --name page_name
For example, a product page might be:
$
publican create --type Article --name FooMaster
or a version page might be:
$
publican create --type Article --name FooMaster_3
Change into the article directory:
$
cd page_name
For example:
$
cd FooMaster
Unlink the Article_Info.xml
file from your root XML file.
Little of the content of the Article_Info.xml
file is likely to be useful for product pages or version pages. Therefore, edit the root XML file of your page to remove the <xi:include>
tag 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.
At the very least, you must add the web_type
parameter and set it to product
or version
:
web_type: product
or
web_type: version
The web_type
parameter instructs Publican to process this document differently from product documentation. This is the only mandatory change to the publican.cfg
file. Other optional changes to the publican.cfg
file that are frequently useful for product pages or version pages include:
brand
To style your home page to match your documents, add:
brand: name_of_brand
docname
, product
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.
Edit the content of the page_name.xml
file (for example, FooMaster.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.
Build the product page or version 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 --langs all$
publican install_book --site_config ~/docsite/foomaster.cfg --lang Language_Code
Note that you can build all languages at the same time, but must install the product page or version page for each language with a separate $
publican install_book command.
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 command; 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.