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
|
<!-- $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>
</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
avalable. 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>
<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:
-->
|
