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