1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
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">docs.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>
|
