%FEDORA-ENTITIES-EN; ]> This chapter shows how to publish official &FDP; work to the docs.fedoraproject.org website. To publish official documentation, you must be approved to write to the web repository in CVS. Access for publishing is limited to contributors who have demonstrated capacity for working with CVS and other project tools. Once you have acquired and are comfortable with these skills, contributions as a publisher are welcome.

The docs.fedoraproject.org website is a set of PHP files and scripts. Publishers maintain these files in a CVS repository, and the website host retrieves them hourly to refresh the site. The host does not automatically use the newest content for the website. Instead, it pulls files with the CVS tag LIVE to populate the website. Each publisher sets up a local testing website on an available &DISTRO; system. This site, sometimes called a sandbox, allows the publisher to test and view changes to documents, and ensure stability on the public site.

To test document publishing, first set up a web sandbox on a local &DISTRO; system. Install the "Web Server" package group: su -c 'yum groupinstall "Web Server"' Create a folder for the web server to access the site files. su -c 'mkdir /var/www/fedora' Change the permissions on this directory to make it easier to access for your normal user account. su -c 'chown username /var/www/fedora' Link to the new directory from your home directory. ln -s /var/www/fedora ~/fedora Retrieve the web module from CVS. cd ~/fedora cvs -d :ext:username@cvs.fedoraproject.org:/cvs/fedora co web You must have access to the cvsweb module through the Fedora Account System to check in changes. If you do not have access, you can use in place of above. Visit the Fedora Account System at for more information. Edit the /etc/hosts file and add the following line after all other lines: 127.0.0.1 docs.localhost.localdomain Create a file /etc/httpd/conf.d/fpo.conf with the following content: ServerName docs.localhost.localdomain DocumentRoot /var/www/fedora/web/html/docs Alias /images /var/www/fedora/web/html/images Alias /css /var/www/fedora/web/html/css Alias /include /var/www/fedora/web/include Options Indexes FollowSymLinks ]]> Create a file /etc/php.d/fpo.ini with the following content: include_path = ".:/var/www/fedora/web/include" Start the web server using the following command: su -c '/sbin/service httpd start' To have the web server start at every boot, use the following command: su -c '/sbin/chkconfig httpd on' To test the new sandbox site, open a Web browser and point it at the URL http://docs.localhost.localdomain.

Follow these guidelines to ensure maintainability and ease of use for all publishers. Use a short, descriptive name for the document directory. The module name from its Docs CVS location is usually appropriate. Good examples include install-guide/ or example-tutorial/. Under the document directory, include a branch directory if the document references specific features of a particular &DISTRO; release. Under the branch directory (or document directory if no branches are necessary), make at least a en_US/ directory. Make an additional directory for each locale that has been fully translated.

To add content, follow the procedure below. The following commands show an example of adding content for a new document called the Foobar Tutorial. This document includes a translation for the "zz_XX" locale and follows specifics of each &DISTRO; release. Make the required directory structure. cd ~/fedora/web/html/docs/ mkdir foobar-tutorial mkdir foobar-tutorial/f7 mkdir foobar-tutorial/f7/{en_US,zz_XX} Build the HTML version of each translation of the document from Docs CVS. cd ~/my-docs/foobar-tutorial/F-7/ make html-en_US html-zz_XX Copy the HTML content to the web sandbox. cd ~/fedora/web/html/docs/foobar-tutorial/f7/ cp -r ~/my-docs/foobar-tutorial/F-7/foobar-tutorial-en_US/ en_US/ cp -r ~/my-docs/foobar-tutorial/F-7/foobar-tutorial-zz_XX/ zz_XX/ Convert the HTML in each directory to PHP using the provided docbookhtml2php.py script. Create any necessary index.php files for the overall directories. Each document and branch directory must have an index.php file directing users to appropriate content. In this example, the necessary files are foobar-tutorial/index.php and foobar-tutorial/f7/index.php. You do not need to write these files from scratch. Copy an existing file from another document, and change it as needed to suit the new document. Depending on content, publication may include changing a higher-level index.php file. To test the changes in your sandbox, open a web browser and point it at http://docs.localhost.localdomain/. Do not proceed further until you test all changes. Check that all links and index pages work.

To push your new content to the web site, follow this procedure: Add all the new file content to CVS. cd ~/fedora/web/html/docs/ cvs add foobar-tutorial cd foobar-tutorial cvs add f7 cd f7 cvs add en_US/ zz_XX/ cvs add en_US/*php en_US/stylesheet-images/ cvs add zz_XX/*php zz_XX/stylesheet-images/ cvs add en_US/stylesheet-images/*png cvs add zz_XX/stylesheet-images/*png cd ../../ cvs add foobar-tutorial/index.php cvs add foobar-tutorial/f7/index.php Commit the changes to CVS. Use a message that describes the document being committed. cvs ci -m 'message about document' foobar-tutorial/ Tag the content LIVE in CVS. cvs tag -F LIVE foobar-tutorial/