* 0.3.1:

  - Add new publishing chapter
  - Include new chapter in book

3 files changed, 235 insertions, 1 deletions

diff --git a/en_US/documentation-guide.xml b/en_US/documentation-guide.xml
index 3699e93..e2472aa 100644
--- a/en_US/documentation-guide.xml
+++ b/en_US/documentation-guide.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!-- $Id: documentation-guide.xml,v 1.8 2007/07/28 22:02:46 pfrields Exp $ -->
+<!-- $Id: documentation-guide.xml,v 1.9 2007/08/03 16:38:15 pfrields Exp $ -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
@@ -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" />
diff --git a/en_US/publishing.xml b/en_US/publishing.xml
new file mode 100644
index 0000000..3afb566
--- /dev/null
+++ b/en_US/publishing.xml
@@ -0,0 +1,226 @@
+<?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>
diff --git a/en_US/rpm-info.xml b/en_US/rpm-info.xml
index 4d0e931..52b16f6 100644
--- a/en_US/rpm-info.xml
+++ b/en_US/rpm-info.xml
@@ -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>