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
227
228
229
230
231
232
233
|
<!-- $Id: -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- *************** Bring in Fedora entities *************** -->
<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "fdp-entities.ent">
%FEDORA-ENTITIES-EN;
]>
<chapter id="ch-getting-files">
<title>Prerequisites</title>
<para>
To work on official &FED; documentation you need to install the required
tools. Follow the directions below to configure your system.
</para>
<section id="sn-system-packages">
<title>System Packages</title>
<para>
Install the "Authoring and Publishing" package group, which contains
required DocBook XML files, stylesheets and scripts:
</para>
<screen>
<userinput>su -c 'yum groupinstall "Authoring and Publishing"'</userinput>
</screen>
<para>
Next, install the <filename>cvs</filename> package, which is used to
handle revision control on files in the official repository:
</para>
<screen>
<userinput>su -c 'yum install cvs'</userinput>
</screen>
<para>If you plan to use <application>Emacs</application> to edit
DocBook XML documentation, install <package>psgml</package>, which
adds helpful and time-saving functionality to maximize editing
efficiency:</para>
<screen><userinput>su -c 'yum install psgml'</userinput></screen>
</section>
<section id="ch-getting-files-fdp">
<title>Fedora Documentation Tools</title>
<para>
The &FDP;'s custom scripts and stylesheets are stored in CVS on the
<systemitem class="fqdomainname">cvs.fedoraproject.org</systemitem> CVS
server. When you check out a document module from CVS, the tools
are included in the module inside the <filename
class="directory">docs-common/</filename> directory.
To work on existing documents in CVS, refer to <xref
linkend="ch-cvs"/>.
</para>
<para>The most powerful component in the &FDP; toolbox is
<firstterm>DocBook XML</firstterm>. DocBook XML is a specific
scheme for authoring technical documentation using
<firstterm>Extensible Markup Language</firstterm>, or
<acronym>XML</acronym>. XML allows authors to mark pieces of
content with descriptive tags. The following output is an example
of DocBook XML:</para>
<screen><![CDATA[<article>
<title>A Very Short Article</title>
<para>This very short article is a
demonstration of DocBook XML in
its simplest form. Notice how the
tags <emphasis>describe</emphasis>
the content they surround, and how
that content fits into the meaning
of the text as a written work.</para>
</article>]]></screen>
<para>This example article, entitled <citetitle>A Very Short
Article</citetitle>, consists of only a single paragraph. The
tags, or markup, surround elements of content to define the sense
in which they are used. A paragraph, for example, is marked with
<sgmltag>para</sgmltag> tags. Text that requires emphasis is
marked with <sgmltag>emphasis</sgmltag> tags. The author does not
worry about the visual formatting such as italics or font size.
&FDP; build tools automatically perform all formatting
tasks.</para>
<para>The custom tools built by the &FDP; render DocBook source into
a variety of formats for publication and distribution. They also
allow translators to create localized versions of the XML
documents for &DISTRO; users around the world. The flexibility of
XML allows for a single document to be used many times for many
purposes, like reusable code for a programmer.</para>
<para>DocBook is itself very well documented. For more information
about DocBook, visit <ulink url="http://www.docbook.org/"/>. The
DocBook site also features complete copies of <citetitle>DocBook:
The Definitive Guide</citetitle> to browse and download, the
canonical source for DocBook information.</para>
<note>
<title>DocBook XML Versions</title>
<para>DocBook XML, like a computer program, has version numbers.
The version used by &FDP; right now is &DBVER;. The DocBook web
site may document a slightly newer version, but the majority of
the schema still applies.</para>
</note>
<para>Contributors who use the Microsoft Windows operating system
can still make use of DocBook tools. For more information, refer
to <ulink
url="http://www.codeproject.com/winhelp/docbook_howto.asp"/>.</para>
</section>
<section id="sn-getting-files-names">
<title>Naming Conventions</title>
<para>
The &FDP; provides the tools, scripts, and stylesheets to
transform your <abbrev>XML</abbrev> documents into other output
formats such as <abbrev>HTML</abbrev>. In addition, these tools
can build your document into a <abbrev>RPM</abbrev> package. To
take advantage of these services, follow the conventions in this
section to name your files.
</para>
<para>On the CVS server, directories that contain document files are
called <firstterm>modules</firstterm>. Each module represents a
single document. Each document may consist of several
<firstterm>branches</firstterm> if that document changes with each
release of &DISTRO;. Contributors can check out single branches
of these modules or the entire module. Each document or branch
may contain multiple XML source files.</para>
<para>Use the <command>cvs co -c</command> command to view existing
module names.</para>
<example>
<title>Partial List of CVS Modules</title>
<screen><userinput>cd ~/localrepo/fedora-docs/</userinput>
<computeroutput><![CDATA[about-fedora about-fedora &docs-common
about-fedora-F-7 &about-fedora-F-7-dir &docs-common
about-fedora-F-7-dir -d about-fedora about-fedora/F-7
about-fedora-devel &about-fedora-devel-dir &docs-common
about-fedora-devel-dir -d about-fedora about-fedora/devel
build-docs infrastructure/build-docs &docs-common
cvsroot CVSROOT
desktop-up2date desktop-up2date &docs-common
desktop-user-guide desktop-user-guide &docs-common
desktop-user-guide-FC-6 &desktop-user-guide-FC-6-dir &docs-common
desktop-user-guide-FC-6-dir -d desktop-user-guide desktop-user-guide/FC-6
desktop-user-guide-devel &desktop-user-guide-devel-dir &docs-common
desktop-user-guide-devel-dir -d desktop-user-guide desktop-user-guide/devel
developer-guide developer-guide &docs-common
docs .
docs-common docs-common
documentation-guide documentation-guide &docs-common]]></computeroutput></screen>
</example>
<para>The leftmost entry in each line is the name of a module you
can check out from CVS. The rest of the line ensures that
checkouts include the proper branch of a document and the common
build tools. For more information on CVS, refer to <xref
linkend="ch-cvs"/>.</para>
<para>Note in the listing above that the
<systemitem>about-fedora</systemitem> module has two branches
available. One branch is for &DISTRO; 7 and one is for forward
development to match the current work of developers. On the other
hand, the <systemitem>documentation-guide</systemitem> module is
not branched.</para>
<tip>
<title>Modules Labeled <filename>-dir</filename></title>
<para>Modules ending with the suffix <filename>-dir</filename> are
not usually helpful to checkout directly. These modules do not
include the common build tools and thus do not provide many of
the functions contributors require.</para>
</tip>
<section id="ch-getting-files-naming-modules">
<title>Module Names</title>
<para>Choose a module name that accurately reflects your
document's subject, but avoid any name already taken. The
document title without any use of the word
<wordasword>&FEDLC;</wordasword> is a reasonable choice in most
cases. Use the length descriptors
<wordasword>tutorial</wordasword> or
<wordasword>guide</wordasword> in the module name where
appropriate.</para>
<important>
<title>Avoid Redundancy</title>
<para>
Do not use the word <wordasword>&FEDLC;</wordasword> to name
modules in the &FDP; CVS repository.
</para>
</important>
<segmentedlist id="sl-correct-module-naming">
<title>Correct Module Naming</title>
<segtitle>Document Name</segtitle>
<segtitle>CVS Module Name</segtitle>
<seglistitem>
<seg>Desktop User Guide</seg>
<seg>desktop-user-guide</seg>
</seglistitem>
<seglistitem>
<seg>Software Management with
<application>Yum</application></seg>
<seg>yum-guide</seg>
</seglistitem>
<seglistitem>
<seg>Using <application>Pup</application></seg>
<seg>pup-tutorial</seg>
</seglistitem>
</segmentedlist>
</section>
<section>
<title>File Names</title>
<para>Follow these guidelines for naming files to make
collaboration and document reuse easy:</para>
<itemizedlist>
<listitem>
<para>As with module names, avoid using the word
<wordasword>&FEDLC;</wordasword> in file names since it is
redundant.</para>
</listitem>
<listitem>
<para>If the document is comprised of many XML files, avoid
repeating the name of the document when naming the
constituent files.</para>
</listitem>
<listitem>
<para>Avoid numbering files to show order, since editors and
authors often rearrange documents or reuse their files in
other documents.</para>
</listitem>
</itemizedlist>
</section>
</section>
</chapter>
<!--
Local variables:
mode: xml
fill-column: 72
End:
-->
|
