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.
defualt.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.
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.
$
mkdir ~/docsite
$
cd ~/docsite
$
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
--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
.
$
publican create_site --site_config foomaster.cfg --db_file foomaster.db --toc_path html/docs
foomaster.cfg
and foomaster.db
. You can set --toc_path
to whatever you choose.
title
parameter, for example:
title: "Foomaster Documentation"
host
parameter as a full URL, including the protocol (for example, http://
). For example:
host: http://docs.example.com
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.
<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.
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>'
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
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.
def_lang
with a language code. For example:
def_lang: fr-FR
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.
$
publican update_site
command is run. Configure the dump
, dump_file
, and zip_dump
parameters as follows:
dump
dump: 1
to enable the dump file function. This parameter defaults to 0
(off).
dump_file
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
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).
manual_toc_update
parameter, for example:
manual_toc_update: 1
$
publican update_site
command.
toc_js
parameter, for example:
toc_js: "mybrand/scripts/megafoo.js"
toc_path
/toc.js with the $
publican update_site
command. This path should be relative to the toc_path
parameter.
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
common
brand.
$
cd
brandsrc_dir
$
publican build --formats=xml --langs=all --publish
$
publican install_brand --web --path=
path_to_site_root_dir
$
publican update_site
$
publican update_site --site_config path_to_site_configuration_file.cfg
<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:
$
publican create
command:
$
publican create --type Article --name page_name
$
publican create --type Article --name Home_Page
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.
$
cd page_name
$
cd Home_Page
Article_Info.xml
file from your root XML file.
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.
publican.cfg
file.
web_type
parameter and set it to home
:
web_type: home
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
brand: name_of_brand
docname
, product
<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.
page_name.xml
file (for example, Home_Page.xml
) as you would any other DocBook document.
<xi:include>
that links to Article_Info.xml
, specify a title for your page in the following format:
<title role="producttitle">FooMaster Documentation</title>
$
publican update_pot
and publican update_po
commands.
web_logo.png
. Place this image in the images/
directory in the document's XML directory, for example en-US/images/
.
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).
--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
$
publican install_book
command.
<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:
$
publican create
command:
$
publican create --type Article --name page_name
$
publican create --type Article --name FooMaster
$
publican create --type Article --name FooMaster_3
$
cd page_name
$
cd FooMaster
Article_Info.xml
file from your root XML file.
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.
publican.cfg
file.
web_type
parameter and set it to product
or version
:
web_type: product
web_type: version
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
brand: name_of_brand
docname
, product
<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.
page_name.xml
file (for example, FooMaster.xml
) as you would any other DocBook document.
<xi:include>
that links to Article_Info.xml
, specify a title for your page in the following format:
<title role="producttitle">FooMaster Documentation</title>
$
publican update_pot
and publican update_po
commands.
--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
$
publican install_book
command.
$
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
$
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
.
$
publican remove_book --site_config path_to_site_configuration_file.cfg --lang language_code
Warning — This procedure replaces files
/var/www/html/docs
directory. Existing files in this directory might be overwritten by this procedure.
$
su -
#
yum install publican-web publican-$brand-web
/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:
title
parameter, for example:
title: "Foomaster Documentation"
host
parameter as a full URL, including the protocol (for example, http://
). For example:
host: http://docs.example.com
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.
<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.
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>'
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
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.
def_lang
with a language code. For example:
def_lang: fr-FR
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.
$
publican update_site
command is run. Configure the dump
, dump_file
, and zip_dump
parameters as follows:
dump
dump: 1
to enable the dump file function. This parameter defaults to 0
(off).
dump_file
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
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).
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
$
publican update_site
<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.
$
publican package --binary
/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.
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
.
<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.
<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.
$
publican package --binary
/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.
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
.
<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.
$
publican package --binary --lang language_code
/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.
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
.
<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.
rpm -e
or yum erase
command.
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.
Procedure 7.1. To Submit Your Sitemap to Google:
Procedure 7.2. To Submit Your Sitemap to Bing:
BingSiteAuth.xml
file that Bing provides to the document root of your website.
BingSiteAuth.xml
file has been uploaded to the required location by accessing it in a web browser, click the button.