Publishing a document with Publican

As of version 2.0, Publican includes features to automate publishing documents to websites.

Prerequisites
To follow this procedure, you must:
 * be a member of the docs-publishers group
 * have a local copy of the book checked out from the book's git or SVN repo

Preparation
Create a local copy of the git repository of the docs.fedoraproject.org website: git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git Where USERNAME is your FAS username.  Change into the directory into which you downloaded the web.git repo, and make a copy of homepage.tmp named homepage.cfg: cp homepage.tmp homepage.cfg  Edit the homepage.cfg file to provide the absolute paths to the fedoradocs.db file and the public_html directory. For example, if you downloaded the web.git repo to the fedoradocs subdirectory of your home directory, your homepage.cfg file might look like:
 * 1) Config::Simple 4.59
 * 2) Tue May 11 13:53:03 2010

db_file: /home/jsmith/fedoradocs/web/fedoradocs.db toc_path: /home/jsmith/fedoradocs/web/public_html host: http://docs.fedoraproject.org title: "Fedora Documentation" search: ' '  Make sure you have the latest version of Publican and the Fedora brand package. As root, run: yum update publican publican-fedora 

Publishing a document
Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: git pull 

Change to the directory where you keep a checked-out copy of the document that you want to publish, then run: publican build --embedtoc --publish --formats epub,html,html-single,pdf --langs LANGUAGE_CODES where LANGUAGE_CODES is a comma-separated list of the languages in which you want to publish this document. 

Browse to the publish subdirectory and to the documents themselves inside it to ensure that the documents have built as you expected. In particular, verify:
 * the product name is Fedora (note capitalization)
 * the version number is correct
 * the document title is properly capitalized and spaced: for example, Foo Guide, not foo-guide</li>

Install the book to the Fedora website: publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE where PATH_TO_SITE_CONFIG_FILE is the path to the homepage.cfg file in your local copy of the docs.fedoraproject.org website, and LANGUAGE_CODE is the language in which you are publishing the document. Note that you can only run publican install_book for one language at a time.</li>

Change to the directory in which you keep your local copy of the site and run: git add. git commit -m "DESCRIPTION_OF_YOUR_CHANGES" git push </li></ol>

Removing a document
To remove a document for a particular version of Fedora in a particular language:

Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: git pull </li>

Change to the directory where you keep a checked-out copy of the document that you want to remove, then run: publican remove_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE

where PATH_TO_SITE_CONFIG_FILE is the path to the homepage.cfg file in your local copy of the docs.fedoraproject.org website, and LANGUAGE_CODE is the language in which you are removing the document. Note that you can only run publican remove_book for one language at a time.</li>

Change to the directory in which you keep your local copy of the site and run: git add. git commit -m "DESCRIPTION_OF_YOUR_CHANGES" git push </li>

Publican can only remove the local files and directories on your system, not their record in Git. To remove the deleted files from your local Git repo, run: for f in $(git ls-files --deleted); do git rm $f; done Then push these changes to the remote repo: git commit -m"rm unused files" git push </li></ol>

Updating a document
To update a document previously published in a particular language for a particular version of Fedora, change into the directory in which you keep a checked-out copy of the document, then run publican install_book, as if you were installing it for the first time. Publican automatically replaces the old version with the new one.

Working with a translated document
The Fedora Docs Project uses Transifex.net as the docs translation management system. Refer to Setting up a document with Transifex for instructions on how to prepare, update and publish a translated document using Publican and Transifex.net.