documentation-guide/en_US publishing.xml, NONE, 1.1 documentation-guide.xml, 1.8, 1.9 rpm-info.xml, 1.9, 1.10
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Fri Aug 3 16:38:17 UTC 2007
- Previous message (by thread): release-notes/F-7/po es.po,1.5,1.6
- Next message (by thread): documentation-guide/po documentation-guide.pot, 1.2, 1.3 pt.po, 1.16, 1.17 pt_BR.po, 1.13, 1.14 zh_CN.po, 1.2, 1.3
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Author: pfrields
Update of /cvs/docs/documentation-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv25850/en_US
Modified Files:
documentation-guide.xml rpm-info.xml
Added Files:
publishing.xml
Log Message:
* 0.3.1:
- Add new publishing chapter
- Include new chapter in book
--- NEW FILE publishing.xml ---
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd" [
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-publishing">
<title>Publishing Official Documentation</title>
<para>This chapter shows how to publish official &FDP; work to the
<systemitem class="fqdomainname">docs.fedoraproject.org</systemitem>
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.</para>
<section id="sn-how-site-works">
<title>How the Site Works</title>
<para>The <systemitem
class="fqdomainname">dos.fedoraproject.org</systemitem> 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 <systemitem>LIVE</systemitem> to populate the
website.</para>
<para>Each publisher sets up a local testing website on an available
&DISTRO; system. This site, sometimes called a
<firstterm>sandbox</firstterm>, allows the publisher to test and
view changes to documents, and ensure stability on the public
site.</para>
</section>
<section id="sn-sandbox-setup">
<title>Setting Up a Web Sandbox</title>
<para>To test document publishing, first set up a web sandbox on a
local &DISTRO; system.</para>
<procedure>
<step>
<para>Install the "Web Server" package group:</para>
<screen>su -c 'yum groupinstall "Web Server"'</screen>
</step>
<step>
<para>Create a folder for the web server to access the site
files.</para>
<screen>su -c 'mkdir /var/www/fedora'</screen>
</step>
<step>
<para>Change the permissions on this directory to make it
easier to access for your normal user account.</para>
<screen>su -c 'chown <replaceable>username</replaceable> /var/www/fedora'</screen>
</step>
<step>
<para>Link to the new directory from your home directory.</para>
<screen>ln -s /var/www/fedora ~/fedora</screen>
</step>
<step>
<para>Retrieve the web module from CVS.</para>
<screen>cd ~/fedora
cvs -d :ext:<replaceable>username</replaceable>@cvs.fedoraproject.org:/cvs/fedora co web</screen>
</step>
<step>
<para>Edit the <filename>/etc/hosts</filename> file and add the
following line <emphasis>after</emphasis> all other
lines:</para>
<screen>127.0.0.1 docs.localhost.localdomain</screen>
</step>
<step>
<para>Create a file
<filename>/etc/httpd/conf.d/fpo.conf</filename> with the
following content:</para>
<screen><![CDATA[NameVirtualHost *:80
<VirtualHost *:80>
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
</Virtualhost>]]></screen>
</step>
<step>
<para>Create a file <filename>/etc/php.d/fpo.ini</filename> with
the following content:</para>
<screen>include_path = ".:/var/www/fedora/web/include"</screen>
</step>
<step>
<para>Start the web server using the following command:</para>
<screen>su -c '/sbin/service httpd start'</screen>
<para>To have the web server start at every boot, use the
following command:</para>
<screen>su -c '/sbin/chkconfig httpd on'</screen>
</step>
</procedure>
<para>To test the new sandbox site, open a Web browser and point it
at the URL <uri>http://docs.localhost.localdomain</uri>.</para>
</section>
<section id="sn-creating-new-pub">
<title>Creating a New Publication</title>
<section id="sn-creating-new-pub-prepdirs">
<title>General Guidelines</title>
<para>Follow these guidelines to ensure maintainability and ease
of use for all publishers.</para>
<itemizedlist>
<listitem>
<para>Use a short, descriptive name for the document
directory. The module name from its Docs CVS location is
usually appropriate. Good examples include <filename
class="directory">install-guide/</filename> or <filename
class="directory">example-tutorial/</filename>.</para>
</listitem>
<listitem>
<para>Under the document directory, include a branch directory
if the document references specific features of a particular
&DISTRO; release.</para>
</listitem>
<listitem>
<para>Under the branch directory (or document directory if no
branches are necessary), make at least a <filename
class="directory">en_US/</filename> directory. Make an
additional directory for each locale that has been fully
translated.</para>
</listitem>
</itemizedlist>
</section>
<section id="sn-creating-new-pub-content">
<title>Adding Content</title>
<para>To add content, follow the procedure below. The following
commands show an example of adding content for a new document
called the <citetitle>Foobar Tutorial</citetitle>. This document
includes a translation for the "zz_XX" locale and follows
specifics of each &DISTRO; release.</para>
<procedure>
<step>
<para>Make the required directory structure.</para>
<screen>cd ~/fedora/web/html/docs/
mkdir foobar-tutorial
mkdir foobar-tutorial/f7
mkdir foobar-tutorial/f7/{en_US,zz_XX}</screen>
</step>
<step>
<para>Build the HTML version of each translation of the
document from Docs CVS.</para>
<screen>cd <replaceable>~/my-docs/foobar-tutorial/F-7/</replaceable>
make html-en_US html-zz_XX</screen>
</step>
<step>
<para>Copy the HTML content to the web sandbox.</para>
<screen>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/</screen>
</step>
<step>
<para>Convert the HTML in each directory to PHP using the
provided <filename>docbookhtml2php.py</filename>
script.</para>
<screen><![CDATA[cd en_US/
~/fedora/web/scripts/docbookhtml2php.py *html && rm -f *html
cd ../zz_XX/
~/fedora/web/scripts/docbookhtml2php.py *html && rm -f *html]]></screen>
</step>
<step>
<para>Create any necessary <filename>index.php</filename>
files for the overall directories. Each document and branch
directory must have an <filename>index.php</filename> file
directing users to appropriate content. In this example,
the necessary files are
<filename>foobar-tutorial/index.php</filename> and
<filename>foobar-tutorial/f7/index.php</filename>. 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.</para>
<para>Depending on content, publication may include changing
a higher-level <filename>index.php</filename> file.</para>
</step>
<step>
<para>To test the changes in your sandbox, open a web browser
and point it at
<uri>http://docs.localhost.localdomain/</uri>.</para>
<important>
<title>Always Test Changes</title>
<para><emphasis>Do not proceed further until you test all
changes.</emphasis> Check that all links and index
pages work.</para>
</important>
</step>
</procedure>
</section>
<section id="creating-new-pub-push">
<title>Pushing Content to the Web</title>
<para>To push your new content to the web site, follow this
procedure:</para>
<procedure>
<step>
<para>Add all the new file content to CVS.</para>
<screen>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
</screen>
</step>
<step>
<para>Commit the changes to CVS. Use a message that describes
the document being committed.</para>
<screen>cvs ci -m '<replaceable>message about document</replaceable>' foobar-tutorial/</screen>
</step>
<step>
<para>Tag the content <systemitem>LIVE</systemitem> in
CVS.</para>
<screen>cvs tag -F LIVE foobar-tutorial/</screen>
</step>
</procedure>
</section>
</section>
</chapter>
Index: documentation-guide.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/documentation-guide.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- documentation-guide.xml 28 Jul 2007 22:02:46 -0000 1.8
+++ documentation-guide.xml 3 Aug 2007 16:38:15 -0000 1.9
@@ -59,6 +59,10 @@
<xi:include href="tutorial.xml" xpointer="element(ch-tutorial)"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- PUBLISHING -->
+ <xi:include href="publishing.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
<!-- CVS -->
<xi:include href="cvs-en_US.xml" xml:base="&FDPCOMMONDIR;/common"
xpointer="element(ch-cvs)" xmlns:xi="http://www.w3.org/2001/XInclude" />
Index: rpm-info.xml
===================================================================
RCS file: /cvs/docs/documentation-guide/en_US/rpm-info.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- rpm-info.xml 29 Jul 2007 23:55:25 -0000 1.9
+++ rpm-info.xml 3 Aug 2007 16:38:15 -0000 1.10
@@ -33,6 +33,10 @@
<title>Fedora Documentation Guide</title>
<desc>Guidelines and procedures for producing documentation for Fedora</desc>
<changelog order="newest-first">
+ <revision date="2007-08-03" number="0.3.1">
+ <author worker="PaulWFrields"/>
+ <details>Add new chapter on publishing</details>
+ </revision>
<revision date="2007-07-29" number="0.3.0.3">
<author worker="PaulWFrields"/>
<details>Include information on LINGUAS usage</details>
- Previous message (by thread): release-notes/F-7/po es.po,1.5,1.6
- Next message (by thread): documentation-guide/po documentation-guide.pot, 1.2, 1.3 pt.po, 1.16, 1.17 pt_BR.po, 1.13, 1.14 zh_CN.po, 1.2, 1.3
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the Fedora-docs-commits
mailing list