/[docs]/example-tutorial/en_US/example-tutorial2.xml
ViewVC logotype

Contents of /example-tutorial/en_US/example-tutorial2.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.9 - (show annotations) (download) (as text)
Fri Jun 22 12:08:11 2007 UTC (2 years, 5 months ago) by pfrields
Branch: MAIN
CVS Tags: LIVE, HEAD
Changes since 1.8: +1 -1 lines
File MIME type: text/xml
typofix
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Id: -->
3
4 <!-- ================================================= -->
5 <!-- EXAMPLE TUTORIAL FOR FEDORA DOCUMENTATION PROJECT -->
6 <!-- ================================================= -->
7
8 <!-- This file is a self-documenting tutorial for creating DocBook XML -->
9 <!-- documents for the Fedora Documentation Project. -->
10
11 <!-- If you are not interested in learning usage guidelines for DocBook -->
12 <!-- XML, you do not need to use this file. You can instead simply copy -->
13 <!-- one of the template XML files in this directory to start either a -->
14 <!-- very long document (a "book"), or a shorter tutorial (an -->
15 <!-- "article"). For most uses, the "article" template is the proper -->
16 <!-- starting point. -->
17
18 <!-- Wherever you see a block of text that has beginning and end markers -->
19 <!-- that look like this: -->
20
21 <!-- -->
22
23 <!-- ...you are looking at a COMMENT. If you have HTML experience, you -->
24 <!-- have likely seen these markings, or TAGS, before. All of these -->
25 <!-- comment blocks (other than Line 2, as noted below) are NOT meant to -->
26 <!-- be copied into your file. They are only here for your reference. -->
27 <!-- If you use this file as a template for your own work, delete these -->
28 <!-- comment blocks. -->
29
30 <!-- XML is the eXtensible Markup Language, and is simply a way of -->
31 <!-- indicating the meaning of content so it can be understood both -->
32 <!-- manually by human readers and automatically by computer programs. -->
33 <!-- If you look at the following text, you probably understand that it -->
34 <!-- is a quote from Shakespeare: -->
35
36 <!-- "Alas, poor Yorick! I knew him, Horatio. -->
37 <!-- He hath borne me on his back a thousand times..." -->
38 <!-- W. Shakespeare, _Hamlet_, II:3 -->
39
40 <!-- For a computer, however, there is no easy way to derive the sense -->
41 <!-- of any part of this quotation. How does the computer understand -->
42 <!-- what pieces of text are part of the quotation, the author's name, -->
43 <!-- and so forth? XML provides both the computer and the human a way -->
44 <!-- of understanding the role of any input text. Look at the following -->
45 <!-- reorganization of this text into XML: -->
46
47 <!--
48 <quotation>
49 <line>Alas, poor Yorick! I knew him, Horatio.</line>
50 <line>He hath borne me on his back a thousand times...</line>
51 <citation type="play">
52 <author>
53 <lastName>Shakespeare</lastName>
54 <firstName>W.</firstName>
55 </author>
56 <title>Hamlet<title>
57 <act>2</act>
58 <scene>3</scene>
59 </citation>
60 </quotation>
61 -->
62
63 <!-- There are probably many other ways we could express this content in -->
64 <!-- XML using a SCHEMA, or set of organizational rules. The Fedora -->
65 <!-- Documentation Project uses DocBook XML to express documentation -->
66 <!-- content. That schema has particular rules for organizing document, -->
67 <!-- such as articles, chapters, sections, paragraphs, and so forth. -->
68 <!-- (Note that the XML snippet above is *not* DocBook XML.) -->
69
70 <!-- Any type of content can be organized with TAGS, which surround the -->
71 <!-- content and show what type of role that content fills. For -->
72 <!-- instance, in the above XML, each line of the quotation starts with -->
73 <!-- the opening tag <line> and ends with the closing tag </line>. -->
74
75 <!-- These tags mark the beginning and end of ELEMENTS in the XML -->
76 <!-- document. An element also may have ATTRIBUTES which further -->
77 <!-- describe the way an element is to be interpreted. For example, the -->
78 <!-- quotation above includes a "citation" element which has a "role" -->
79 <!-- attribute defined as "play". An attribute can give both the -->
80 <!-- computer and the human reader an idea of how the content of a -->
81 <!-- specific element is properly understood. -->
82
83 <!-- Any element tag may be split over two lines. This is not a problem -->
84 <!-- for XML documents. Declarations or tags can have any amount of -->
85 <!-- whitespace between their internal attributes. The following two -->
86 <!-- XML snippets are completely identical as far as the computer is -->
87 <!-- concerned: -->
88
89 <!-- EXAMPLE 1: -->
90 <!-- <comment role="FIXME">This isn't finished.</comment> -->
91
92 <!-- EXAMPLE 2: -->
93 <!-- <comment
94 role="FIXME">This isn't finished.</comment> -->
95
96 <!-- This is practically all you need to know to get started with -->
97 <!-- DocBook XML. You can even copy lines from this document to make -->
98 <!-- your own template for creating new DocBook XML documents. Read -->
99 <!-- further for an explanation of the important lines worth copying. -->
100
101 <!-- Lines 1 and 2 of this file are special. To view them, scroll back -->
102 <!-- to the beginning of this page. Their serve the following purposes: -->
103
104 <!-- LINE 1: This line is a declaration line, which indicates this file -->
105 <!-- is an XML file of some sort. It is only later that the file is -->
106 <!-- declared to be a certain type of XML called DocBook XML. Always -->
107 <!-- make this the very first line in your DocBook XML file. -->
108
109 <!-- LINE 2: This comment line is a special line used for revision -->
110 <!-- control. If you use a revision control system, like CVS or -->
111 <!-- Subversion, that system can substitute special text inside the -->
112 <!-- comment line. Always make this the second line in your DocBook XML -->
113 <!-- file. -->
114
115 <!-- Following this comment block is an element which points to a -->
116 <!-- Document Type Declaration, or DTD, which will inform any capable -->
117 <!-- editor program how to treat the XML content. -->
118
119 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
120 "http://www.docbook.org/xml/4.4/docbookx.dtd" [
121
122 <!-- Here is the meaning of each attribute in the DTD pointer: -->
123 <!-- DOCTYPE : This is a DOCTYPE element that points to a DTD. -->
124 <!-- article : The root, or top, element in this document is <article>. -->
125 <!-- PUBLIC : The DTD for this document is publicly available. -->
126 <!-- "-//OASIS//DTD DocBook XML V4.4//EN" : The "formal public
127 identifier" (FPI) for the DTD for this document. *Every
128 DocBook XML version 4.4 document uses this exact FPI.* -->
129 <!-- "http://www.docbook.org/xml/4.4/docbookx.dtd" : A URL that points
130 to the DTD with the FPI above. There are other URLs that
131 also point to this DTD, but it is always safe to use this
132 one. (It's important to have a good URL here if your XML
133 editor is DTD-aware, since it will allow your editor to
134 help you write your document.) -->
135
136 <!-- The DOCTYPE element states that the document's root, or first, -->
137 <!-- element must be an "article" element. That is the next thing that -->
138 <!-- should appear in the document. Note this article has an ID -->
139 <!-- attribute. Almost *any* DocBook element can have an ID attribute, -->
140 <!-- but they are most useful for bigger organizational elements, like -->
141 <!-- an article, chapter, or section; or for marking specific elements -->
142 <!-- which you want to cross-reference from other parts of the document. -->
143
144 <!-- Between the [ and ] markers are a set of declarations known as the -->
145 <!-- document's INTERNAL SUBSET. The author can declare additional -->
146 <!-- directives for processing here. The FDP uses the following -->
147 <!-- standard lines for all internal subsets. Authors may add to them -->
148 <!-- if needed, but it is not recommended for reasons of translation and -->
149 <!-- localization. -->
150
151 <!-- XML files often use ENTITIES to simplify and reduce errors in -->
152 <!-- usage. Those entities typically allow the author to use shorthand -->
153 <!-- that expands to other text, such as using &FDP; to represent the -->
154 <!-- text "Fedora Documentation Project". The declarations below -->
155 <!-- are themselves entities, as you can see from the fact that they -->
156 <!-- start with the "!ENTITY" identifier. These entries are a special -->
157 <!-- kind of entity that load additional files containing the actual -->
158 <!-- general entities. -->
159
160 <!ENTITY % FDP-ENTITIES SYSTEM "fdp-entities.ent">
161 %FDP-ENTITIES;
162
163 <!ENTITY % DOC-ENTITIES SYSTEM "doc-entities.ent">
164 %DOC-ENTITIES;
165
166 ]>
167
168 <article id="example-tutorial">
169 <!-- As mentioned before, DocBook XML is a particular schema used to -->
170 <!-- organize content for technical documentation. The schema is -->
171 <!-- described by a DTD, which lays out the rules for organizing -->
172 <!-- elements and content. If you want to know what elements can be -->
173 <!-- used in what order, you could read the DTD to find out. That's a -->
174 <!-- really difficult thing to do, though, even for people who are -->
175 <!-- well-versed in DTDs. Instead, you can read (and download) -->
176 <!-- "DocBook: The Definitive Guide" at the following URL: -->
177
178 <!-- http://www.docbook.org/ -->
179
180 <!-- Once you've established the root element, if you're not writing -->
181 <!-- strictly for the Fedora Documentation Project, you are free to -->
182 <!-- write and organize content in any way you want, as long as your -->
183 <!-- organization is VALID, meaning it follows the DTD. The content -->
184 <!-- that follows is merely a typical example. -->
185
186 <!-- However, if you are writing for the FDP (and the rest of this -->
187 <!-- tutorial assumes you are, since you downloaded it!), there are some -->
188 <!-- additional rules to follow. Otherwise your document may not work -->
189 <!-- with the FDP tools for publication and dissemination. -->
190
191 <!-- The next element is a way to include metadata, or descriptive -->
192 <!-- information, about this document. It is peculiar to the FDP. -->
193
194 <xi:include href="fdp-info.xml"
195 xmlns:xi="http://www.w3.org/2001/XInclude">
196 <xi:fallback>CHECK "rpm-info.xml"!</xi:fallback>
197 </xi:include>
198
199 <!-- FDP articles require an additional XML file called "rpm-info.xml" -->
200 <!-- which includes information about the title, author, copyright, and -->
201 <!-- revision history for this document. That file is transformed into -->
202 <!-- a new file called "fdp-info.xml" which is then included as part of -->
203 <!-- this document. (XML provides all sorts of fascinating -->
204 <!-- opportunities for reusing information in this way.) If for some -->
205 <!-- reason your "rpm-info.xml" is missing or wrong, only the text -->
206 <!-- snippet 'CHECK "rpm-info-xml"!' appears in your document, alerting -->
207 <!-- you that something is wrong. Technically, no xi:fallback element -->
208 <!-- is required, since an fdp-info.xml failure will simply cause the -->
209 <!-- document validation or building to fail with noisy errors. -->
210
211 <!-- Typically, the next element is a "section" element. You can nest -->
212 <!-- "section" elements inside each other to organize content. Many -->
213 <!-- writers like to lay out their "section" elements like an outline, -->
214 <!-- which allows them to visualize the flow of their documents before -->
215 <!-- they start writing in earnest. -->
216
217 <!-- NOTE: Some documents use "sect1," "sect2," and "sect3" elements to -->
218 <!-- denote organizational depth. A "sect1" is a first-level section, a -->
219 <!-- "sect2" is second-level, and so forth. Unfortunately these -->
220 <!-- elements make sections less portable and harder to rearrange if you -->
221 <!-- change your mind about organization, so FDP recommends against -->
222 <!-- their use. -->
223
224 <!-- The following snippet is a very simple use of a "section" -->
225 <!-- element. -->
226
227 <section id="sn-small-section">
228 <!-- You should give every section in your document a title. -->
229 <title>A Small Section</title>
230 <!-- If you want to mark content in your document for indexing,
231 simply place an "indexterm" element prior to the content to be
232 indexed. To include multiple index entries pointing to the
233 following content, use more than one "indexterm" element. -->
234 <indexterm>
235 <primary>sect1, sect2, and sect3</primary>
236 </indexterm>
237 <para>
238 This is an example section. You should not use
239 <sgmltag
240 class="element">sect1</sgmltag>
241 ,
242 <sgmltag
243 class="element">sect2</sgmltag>
244 , and
245 <sgmltag
246 class="element">sect3</sgmltag>
247 , since those tags will make sections less modular and harder to
248 relocate without changing a lot of other markup.
249 </para>
250 </section>
251
252 <!-- The next section demonstrates the use of some standard DocBook -->
253 <!-- elements which appear frequently in our documentation. -->
254
255 <section id="sn-about-ShmooMaker">
256 <!-- A program with a graphical interface, or an application suite,
257 uses the <application> element. -->
258 <title>About <application>ShmooMaker</application></title>
259 <!-- The first time a term of art or jargon appears, use the
260 <firstterm> element. It is useful to define the term immediately
261 following or during its first use. -->
262 <para>
263 <application>ShmooMaker</application> is a utility for making
264 <firstterm>shmoos</firstterm>. A shmoo is a lovable, globular
265 beastie with a penchant for turning himself into other objects.
266 Everyone loves shmoos due to their warm and cuddly nature.
267 </para>
268 <!-- You can nest sections as appropriate to organize your
269 document. -->
270 <section id="sn-installing-ShmooMaker">
271 <title>Installing <application>ShmooMaker</application></title>
272 <!-- Use the <package> element for RPMs. When referring to a FILE
273 that is an RPM, use <filename> instead. For programs that are not
274 graphical, use the <command> element. -->
275 <para>
276 To install <application>ShmooMaker</application>, use
277 <command>yum</command> to install the
278 <package>ShmooMaker</package>
279 RPM package:
280 </para>
281 <!-- To demonstrate a command outside a sentence, or to show a
282 series of input or output lines, use the <screen> element.
283 IMPORTANT: All the text in a <screen> element is duplicated
284 verbatim when rendered to other formats, including line breaks and
285 initial white space. -->
286 <screen><command>yum install ShmooMaker</command></screen>
287 </section>
288 <section id="sn-configuring-ShmooMaker">
289 <title>Configuring <application>ShmooMaker</application></title>
290 <para>
291 <application>ShmooMaker</application> creates a basic system
292 configuration template for shmoos in the
293 <filename
294 class="directory">/etc/</filename> folder. The
295 configuration file is called <filename>/etc/shmoos</filename>.
296 You can add your own user-specific shmoo information by creating
297 a file in your home directory called
298 <filename>~/.shmoos</filename>. The
299 <filename>/etc/shmoos</filename> file resembles the following:
300 </para>
301 <!-- Note again how the text in a <screen> element is rendered
302 exactly as it is included here. The second and following lines are
303 flush-left so that extra space does not appear in the document
304 output. If you use auto-indenting commands in your editor, be
305 careful that they do not improperly reformat the <screen> sections.
306 You can use other elements inside a <screen>. It is common to
307 denote what the user types with <userinput>, and the output with
308 <computeroutput>. Avoid including shell prompts, since users may
309 not be using the same shell environment. -->
310 <screen><userinput>cat /etc/shmoos</userinput>
311 <computeroutput>[shmoo]
312 size = medium
313 lovable = True
314
315 [add-ons]
316 intelligibility = 0</computeroutput></screen>
317 <!-- Use the <systemitem> element to mark user and group names,
318 services, daemons, and other items related to a running operating
319 system. -->
320 <para>
321 To edit the system configuration template, use the
322 <systemitem class="username">root</systemitem> account.
323 </para>
324 </section>
325 <section id="sn-using-ShmooMaker">
326 <title>Using <application>ShmooMaker</application></title>
327 <!-- To denote GUI menu selections, use the <menuchoice> element
328 and the sub-elements <guimenu>, <guisubmenu>, and <guimenuitem>.
329 The <guimenu> element is the top-level menu label, followed
330 optionally by one or more <guisubmenu> elements as needed. The
331 terminal choice by the user is marked with <guimenuitem>. If the
332 selection is a button, use <guibutton>. If the selection is an
333 icon, use <guiicon>. For any other GUI elements, use the generic
334 <guilabel>. -->
335
336 <para>
337 To run <application>ShmooMaker</application>, select it from the
338 GUI menu under <menuchoice> <guimenu>Applications</guimenu>
339 <guisubmenu>Entertainment</guisubmenu>
340 <guimenuitem>ShmooMaker</guimenuitem> </menuchoice>.
341 </para>
342
343 <!-- Denote options for a command using the <option> element. -->
344
345 <para>
346 If you want to run <application>ShmooMaker</application> as a
347 daemon process, use the command <command>shmoo-maker
348 <option>-d</option></command>.
349 </para>
350 </section>
351
352 <section id="sn-creating-shmoos">
353 <title>Creating Shmoos</title>
354
355 <para>
356 To create a shmoo, do the following:
357 </para>
358
359 <!-- Any incremental series of steps should use the <procedure>
360 element as below. -->
361
362 <procedure>
363 <step>
364 <para>
365 Click the <guibutton>New</guibutton> button.
366 </para>
367 </step>
368 <step>
369 <para>
370 Select the desired shmoo from the list in the dialog.
371 </para>
372 </step>
373 <step>
374 <para>
375 When the shmoo appears, feed it and give it a hug.
376 </para>
377 </step>
378 </procedure>
379 <!-- To indicate keystrokes, use the <keycap> element. If your
380 keystroke includes more than one key, use the <keycombo> element
381 as shown below. The proper symbols for joining the <keycap>
382 contents are automatically added by the DocBook stylesheets when
383 rendered. -->
384 <para>
385 To put away your shmoo for safe-keeping, hit
386 <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap>
387 </keycombo>
388 .
389 </para>
390 <!-- You can, and should, mark important terms for indexing. The
391 FDP toolchain will allow you to automatically generate an index
392 for your document at render time. Use the <primary> and
393 <secondary> elements consistently to organize your index
394 topically. The <secondary> element is not required. -->
395 <!-- The <itemizedlist> element is useful for lists where order is
396 not important. Although there is an <orderedlist> element, make
397 sure you don't use it instead of <procedure> if a <procedure> is
398 more appropriate. -->
399 <para>
400 Shmoos love the following kinds of food:
401 </para>
402 <indexterm>
403 <primary>shmoo</primary>
404 <secondary>feeding</secondary>
405 </indexterm>
406 <itemizedlist>
407 <listitem>
408 <para>
409 Candied yams
410 </para>
411 </listitem>
412 <listitem>
413 <para>
414 Marshmallows
415 </para>
416 </listitem>
417 <listitem>
418 <para>
419 Gummi bears
420 </para>
421 </listitem>
422 </itemizedlist>
423 </section>
424 </section>
425
426 <!-- And now the closing tag for the whole article, which ends the -->
427 <!-- actual document. -->
428
429 <index />
430 </article>
431
432 <!-- The final comment block below is a special section used for the GNU -->
433 <!-- Emacs editor, which is an ideal way to edit XML and DocBook. -->
434
435 <!--
436 Local variables:
437 mode: xml
438 fill-column: 72
439 End:
440 -->

admin@fedoraproject.org
ViewVC Help
Powered by ViewVC 1.1.2