## 7.2. Building a website using RPM packages

### 7.2.1. Creating the website structure

Warning — This procedure replaces files

When you create the website structure, Publican places files in the `/var/www/html/docs` directory. Existing files in this directory might be overwritten by this procedure.
Perform the following steps on your webserver. You must have an account with root privileges.

1. Log into the webserver.
2. Become root:

       $ su -

3. Install Publican. For example, on a webserver with a Fedora operating system, run:

       # yum install publican-web publican-$brand-web

4. Edit the `/etc/publican-website.cfg` file to specify the name of the site, the web host, and optionally, search parameters, default language, and dump file settings for the site:
   1. 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.
   2. 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.
   3. 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.

      Important — the search parameter is not validated

      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.
   4. 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.
   5. 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 E, Contents of the website dump file for a description of the contents of the dump file.
5. Create an empty file named `site_overrides.css`. 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 7.2.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, run:

       # touch /var/www/html/docs/site_overrides.css

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

    $ publican update_site

### 7.2.2. Creating, installing, and updating 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_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 and is packaged the same way.

1. On a workstation, create a home page using the procedure described in Section 7.1.2, “Creating, installing, and updating the home page”.
2. In the directory in which you created the home page, run:

       $ publican package --binary

   Publican builds an RPM package and places it in the `/tmp/rpms/noarch/` directory of the home page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the `os_ver` parameter in the home page's `publican.cfg` file.
3. Either upload the home page package to the webserver and install it with the `rpm -i` or `yum localinstall` command, or place the package in a repository and configure the webserver to install from that repository when you run `yum install`.

To update the home page, build a new package with a higher `<edition>` number or `<pubsnumber>` in the `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.

### 7.2.3. Creating, installing, and updating product pages and version pages

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 and are packaged the same way.

1. On a workstation, create a product or version page using the procedure described in Section 7.1.3, “Creating, installing, and updating product pages and version pages”.
2. In the directory in which you created the product page or version page, run:

       $ publican package --binary

   Publican builds an RPM package and places it in the `/tmp/rpms/noarch/` directory of the product page or version page. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the `os_ver` parameter in the `publican.cfg` file of the product page or version page.
3. Either upload the package to the webserver and install it with the `rpm -i` or `yum localinstall` command, or place the package in a repository and configure the webserver to install from that repository when you run `yum install`.

To update the product page or version page, build a new package with a higher `<edition>` number or `<pubsnumber>` in the `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.

### 7.2.4. Installing, updating and removing documents

On your workstation, 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. By default, Publican builds the RPM package for the operating system within which you are running Publican. To build an RPM package to install on a server that runs a different operating system, set the `os_ver` parameter in the document's `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.
On large or busy sites, we recommend that you set the `manual_toc_update` parameter in the site's configuration file. With this parameter set, you must run the `$` `publican update_site` command after installing, updating, or removing documents. Refer to Section 7.1.1, “Creating the website structure” for more information.