example-tutorial/en_US example-tutorial2.xml,1.6,1.7
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Fri Jun 1 17:04:10 UTC 2007
Author: pfrields
Update of /cvs/docs/example-tutorial/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv21408/en_US
Modified Files:
example-tutorial2.xml
Log Message:
De-uglify
Index: example-tutorial2.xml
===================================================================
RCS file: /cvs/docs/example-tutorial/en_US/example-tutorial2.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- example-tutorial2.xml 1 Jun 2007 16:57:43 -0000 1.6
+++ example-tutorial2.xml 1 Jun 2007 17:04:07 -0000 1.7
@@ -1,71 +1,46 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: -->
-
<!-- EXAMPLE TUTORIAL FOR FEDORA DOCUMENTATION PROJECT -->
-
<!-- ================================================= -->
<!-- This file is a self-documenting tutorial for creating DocBook XML -->
-
<!-- documents for the Fedora Documentation Project. -->
<!-- If you are not interested in learning usage guidelines for DocBook -->
-
<!-- XML, you do not need to use this file. Youcan instead simply copy -->
-
<!-- one of the template XML files in this directory to start either a -->
-
<!-- very long document (a "book"), or a shorter tutorial (an -->
-
<!-- "article"). For most uses, the "article" template is the proper -->
-
<!-- starting point. -->
<!-- Wherever you see a block of text that has beginning and end markers -->
-
<!-- that look like this: -->
<!-- -->
<!-- ...you are looking at a COMMENT. If you have HTML experience, you -->
-
<!-- have likely seen these markings, or TAGS, before. All of these -->
-
<!-- comment blocks (other than Line 2, as noted below) are NOT meant to -->
-
<!-- be copied into your file. They are only here for your reference. -->
-
<!-- If you use this file as a template for your own work, delete these -->
-
<!-- comment blocks. -->
<!-- XML is the eXtensible Markup Language, and is simply a way of -->
-
<!-- indicating the meaning of content so it can be understood both -->
-
<!-- manually by human readers and automatically by computer programs. -->
-
<!-- If you look at the following text, you probably understand that it -->
-
<!-- is a quote from Shakespeare: -->
<!-- "Alas, poor Yorick! I knew him, Horatio. -->
-
<!-- He hath borne me on his back a thousand times..." -->
-
<!-- W. Shakespeare, _Hamlet_, II:3 -->
<!-- For a computer, however, there is no easy way to derive the sense -->
-
<!-- of any part of this quotation. How does the computer understand -->
-
<!-- what pieces of text are part of the quotation, the author's name, -->
-
<!-- and so forth? XML provides both the computer and the human a way -->
-
<!-- of understanding the role of any input text. Look at the following -->
-
<!-- reorganization of this text into XML: -->
<!--
@@ -85,90 +60,58 @@
-->
<!-- There are probably many other ways we could express this content in -->
-
<!-- XML using a SCHEMA, or set of organizational rules. The Fedora -->
-
<!-- Documentation Project uses DocBook XML to express documentation -->
-
<!-- content. That schema has particular rules for organizing document, -->
-
<!-- such as articles, chapters, sections, paragraphs, and so forth. -->
-
<!-- (Note that the XML snippet above is *not* DocBook XML.) -->
<!-- Any type of content can be organized with TAGS, which surround the -->
-
<!-- content and show what type of role that content fills. For -->
-
<!-- instance, in the above XML, each line of the quotation starts with -->
-
<!-- the opening tag <line> and ends with the closing tag </line>. -->
<!-- These tags mark the beginning and end of ELEMENTS in the XML -->
-
<!-- document. An element also may have ATTRIBUTES which further -->
-
<!-- describe the way an element is to be interpreted. For example, the -->
-
<!-- quotation above includes a "citation" element which has a "role" -->
-
<!-- attribute defined as "play". An attribute can give both the -->
-
<!-- computer and the human reader an idea of how the content of a -->
-
<!-- specific element is properly understood. -->
<!-- Any element tag may be split over two lines. This is not a problem -->
-
<!-- for XML documents. Declarations or tags can have any amount of -->
-
<!-- whitespace between their internal attributes. The following two -->
-
<!-- XML snippets are completely identical as far as the computer is -->
-
<!-- concerned: -->
<!-- EXAMPLE 1: -->
-
<!-- <comment role="FIXME">This isn't finished.</comment> -->
<!-- EXAMPLE 2: -->
-
<!-- <comment
role="FIXME">This isn't finished.</comment> -->
<!-- This is practically all you need to know to get started with -->
-
<!-- DocBook XML. You can even copy lines from this document to make -->
-
<!-- your own template for creating new DocBook XML documents. Read -->
-
<!-- further for an explanation of the important lines worth copying. -->
<!-- Lines 1 and 2 of this file are special, and serve these purposes: -->
<!-- LINE 1: This line is a declaration line, which indicates this file -->
-
<!-- is an XML file of some sort. It is only later that the file is -->
-
<!-- declared to be a certain type of XML called DocBook XML. Always -->
-
<!-- make this the very first line in your DocBook XML file. -->
<!-- LINE 2: This comment line is a special line used for revision -->
-
<!-- control. If you use a revision control system, like CVS or -->
-
<!-- Subversion, that system can substitute special text inside the -->
-
<!-- comment line. Always make this the second line in your DocBook XML -->
-
<!-- file. -->
<!-- Following this comment block is an element which points to a -->
-
<!-- Document Type Declaration, or DTD, which will inform any capable -->
-
<!-- editor program how to treat the XML content. -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
@@ -222,43 +165,28 @@
<article id="example-tutorial">
<!-- As mentioned before, DocBook XML is a particular schema used to -->
-
<!-- organize content for technical documentation. The schema is -->
-
<!-- described by a DTD, which lays out the rules for organizing -->
-
<!-- elements and content. If you want to know what elements can be -->
-
<!-- used in what order, you could read the DTD to find out. That's a -->
-
<!-- really difficult thing to do, though, even for people who are -->
-
<!-- well-versed in DTDs. Instead, you can read (and download) -->
-
<!-- "DocBook: The Definitive Guide" at the following URL: -->
<!-- http://www.docbook.org/ -->
<!-- Once you've established the root element, if you're not writing -->
-
<!-- strictly for the Fedora Documentation Project, you are free to -->
-
<!-- write and organize content in any way you want, as long as your -->
-
<!-- organization is VALID, meaning it follows the DTD. The content -->
-
<!-- that follows is merely a typical example. -->
<!-- However, if you are writing for the FDP (and the rest of this -->
-
<!-- tutorial assumes you are, since you downloaded it!), there are some -->
-
<!-- additional rules to follow. Otherwise your document may not work -->
-
<!-- with the FDP tools for publication and dissemination. -->
<!-- The next element is a way to include metadata, or descriptive -->
-
<!-- information, about this document. It is peculiar to the FDP. -->
<xi:include href="fdp-info.xml"
@@ -267,51 +195,31 @@
</xi:include>
<!-- FDP articles require an additional XML file called "rpm-info.xml" -->
-
<!-- which includes information about the title, author, copyright, and -->
-
<!-- revision history for this document. That file is transformed into -->
-
<!-- a new file called "fdp-info.xml" which is then included as part of -->
-
<!-- this document. (XML provides all sorts of fascinating -->
-
<!-- opportunities for reusing information in this way.) If for some -->
-
<!-- reason your "rpm-info.xml" is missing or wrong, only the text -->
-
<!-- snippet 'CHECK "rpm-info-xml"!' appears in your document, alerting -->
-
<!-- you that something is wrong. Technically, no xi:fallback element -->
-
<!-- is required, since an fdp-info.xml failure will simply cause the -->
-
<!-- document validation or building to fail with noisy errors. -->
<!-- Typically, the next element is a "section" element. You can nest -->
-
<!-- "section" elements inside each other to organize content. Many -->
-
<!-- writers like to lay out their "section" elements like an outline, -->
-
<!-- which allows them to visualize the flow of their documents before -->
-
<!-- they start writing in earnest. -->
<!-- NOTE: Some documents use "sect1," "sect2," and "sect3" elements to -->
-
<!-- denote organizational depth. A "sect1" is a first-level section, a -->
-
<!-- "sect2" is second-level, and so forth. Unfortunately these -->
-
<!-- elements make sections less portable and harder to rearrange if you -->
-
<!-- change your mind about organization, so FDP recommends against -->
-
<!-- their use. -->
<!-- The following snippet is a very simple use of a "section" -->
-
<!-- element. -->
<section id="sn-small-section">
@@ -340,7 +248,6 @@
</section>
<!-- The next section demonstrates the use of some standard DocBook -->
-
<!-- elements which appear frequently in our documentation. -->
<section id="sn-about-ShmooMaker">
@@ -376,10 +283,8 @@
initial white space. -->
<screen><command>yum install ShmooMaker</command></screen>
</section>
-
<section id="sn-configuring-ShmooMaker">
<title>Configuring <application>ShmooMaker</application></title>
-
<para>
<application>ShmooMaker</application> creates a basic system
configuration template for shmoos in the
@@ -415,7 +320,6 @@
<systemitem class="username">root</systemitem> account.
</para>
</section>
-
<section id="sn-using-ShmooMaker">
<title>Using <application>ShmooMaker</application></title>
<!-- To denote GUI menu selections, use the <menuchoice> element
@@ -426,13 +330,16 @@
selection is a button, use <guibutton>. If the selection is an
icon, use <guiicon>. For any other GUI elements, use the generic
<guilabel>. -->
+
<para>
To run <application>ShmooMaker</application>, select it from the
GUI menu under <menuchoice> <guimenu>Applications</guimenu>
<guisubmenu>Entertainment</guisubmenu>
<guimenuitem>ShmooMaker</guimenuitem> </menuchoice>.
</para>
+
<!-- Denote options for a command using the <option> element. -->
+
<para>
If you want to run <application>ShmooMaker</application> as a
daemon process, use the command <command>shmoo-maker
@@ -446,8 +353,10 @@
<para>
To create a shmoo, do the following:
</para>
+
<!-- Any incremental series of steps should use the <procedure>
element as below. -->
+
<procedure>
<step>
<para>
@@ -513,14 +422,12 @@
</section>
<!-- And now the closing tag for the whole article, which ends the -->
-
<!-- actual document. -->
<index />
</article>
<!-- The final comment block below is a special section used for the GNU -->
-
<!-- Emacs editor, which is an ideal way to edit XML and DocBook. -->
<!--
More information about the Fedora-docs-commits
mailing list