⁠Chapter 7. Building a website with Publican

1. On your workstation, create a new directory and change into it. For example, on a Linux system, run:

   $ mkdir ~/docsite
   $ cd ~/docsite

2. 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.
3. 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:
   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.
   6. 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.
   7. 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.
4. 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 7.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

5. Build and install each brand, including the Publican common brand.
   1. Change into the directory that holds the source for the brand.

      $ cd brandsrc_dir

   2. Build the brand.

      $ publican build --formats=xml --langs=all --publish

   3. Install the brand on your website.

      $ publican install_brand --web --path=path_to_site_root_dir

      Perform these steps for all brands.
6. Update the site.

   $ publican update_site

1. 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.
2. Change into the article directory:

   $ cd page_name

   For example:

   $ cd Home_Page

3. 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.
4. 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.

5. 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>

6. 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.
7. 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/.
8. 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).
9. 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.

1. 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

2. Change into the article directory:

   $ cd page_name

   For example:

   $ cd FooMaster

3. 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.
4. 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.

5. 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>

6. 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.
7. 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.

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

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.

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.

Procedure 7.1. To Submit Your Sitemap to Google:

1. Sign up for a Google account at Google Webmaster Tools. If you already have a Google account, you can use it.
2. Sign in to your Google Webmaster Tools account at this URL: http://www.google.com/webmasters/tools/home.
3. First you must verify you are the owner of your Publican site. Click the Add A Site button.
4. A dialog box is displayed for you to Add a site with. Enter the URL of your Publican site in the text entry field and click Continue.
5. Follow the instructions that display and upload the HTML file that Google provides to the document root of your website.
6. When you have confirmed that the provided HTML file has been uploaded to the required location by accessing it in a web browser, click the Verify button.
7. When you have successfully verified the ownership of your Publican website to Google, return to the Webmaster Tools home page. Your Publican site is listed. Click on it.
8. You are taken to the Webmaster Tools configuration page for your Publican site. On the left side of the page there is a menu. Click on the Site configuration menu entry to expand it. Its expanded contents includes a Sitemaps entry. Click it.
9. You are taken to a Sitemap submission page. Click the Submit a Sitemap button.
10. A text entry field displays, including the base URL of your Publican site, with room to enter the URL of your Sitemap XML file. Enter its location and click the Submit Sitemap button. The details of the Sitemap are displayed in a table.
11. Result

    The Sitemap for your Publican site has been successfully submitted to Google.

Procedure 7.2. To Submit Your Sitemap to Bing:

1. Sign up for a Bing Webmaster Tools account at Bing Webmaster Tools. If you already have a Windows LiveID account, you can use it.
2. Sign in to your Bing Webmaster Tools account at this URL: http://www.bing.com/toolbox/webmaster/.
3. Click the Add Site button.
4. The Add Site dialog box is displayed. Enter the URL of your Publican site in the text entry field and click Submit.
5. The Verify Ownership dialog displays, with three options. Follow the instructions given when the Option 1: Place an XML file on your web server has been expanded. Upload the BingSiteAuth.xml file that Bing provides to the document root of your website.
6. When you have confirmed that the provided BingSiteAuth.xml file has been uploaded to the required location by accessing it in a web browser, click the Verify button.
7. When you have successfully verified your ownership of your Publican website to Bing, return to the Bing Webmaster Tools home page. Your Publican site is listed. Click on it.
8. Select the Crawl tab.
9. Select Sitemaps and then Add Feed.
10. The Add Feed dialog displays. Enter the URL of your Sitemap file and click Submit. The details of the Sitemap are displayed.
11. Result:

    The Sitemap for your Publican site has been successfully submitted to Bing.