cvs commit: ALFS/docs/syntax_doc/preface changelog.xml

jwrober at linuxfromscratch.org jwrober at linuxfromscratch.org
Mon Mar 15 20:12:26 PST 2004


jwrober     04/03/15 21:12:26

  Modified:    docs/syntax_doc index.xml
               docs/syntax_doc/alfs_dtd xml_dtd-syntax.xml
               docs/syntax_doc/preface changelog.xml
  Log:
  added more to the xml dtd intro
  
  Revision  Changes    Path
  1.15      +2 -2      ALFS/docs/syntax_doc/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/docs/syntax_doc/index.xml,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -r1.14 -r1.15
  --- index.xml	15 Mar 2004 03:49:11 -0000	1.14
  +++ index.xml	16 Mar 2004 04:12:26 -0000	1.15
  @@ -3,8 +3,8 @@
   		"/usr/share/xml/docbook/xml-dtd-4.2/docbookx.dtd" [
   
   <!ENTITY alfs-dtd-version "3.1">
  -<!ENTITY version "&alfs-dtd-version;-2004-03-14">
  -<!ENTITY releasedate "February 23, 2004">
  +<!ENTITY version "&alfs-dtd-version;-2004-03-15">
  +<!ENTITY releasedate "March 15, 2004">
   
   <!ENTITY % book      SYSTEM "book/book.ent">
   <!ENTITY % preface   SYSTEM "preface/preface.ent">
  
  
  
  1.4       +116 -53   ALFS/docs/syntax_doc/alfs_dtd/xml_dtd-syntax.xml
  
  Index: xml_dtd-syntax.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/docs/syntax_doc/alfs_dtd/xml_dtd-syntax.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- xml_dtd-syntax.xml	15 Mar 2004 03:51:35 -0000	1.3
  +++ xml_dtd-syntax.xml	16 Mar 2004 04:12:26 -0000	1.4
  @@ -11,10 +11,13 @@
   syntax. The eXtensible Markup Language is very powerful and easy to use and
   understand.</para>
   
  -<note><para>This introduction does not provide any examples.  This book in
  -written in an XML DTD called DocBook XML.  For an example of XML just look
  -at the book's source.  Since this book is documenting an XML DTD, look at
  -the rest of the book's contents for examples DTD syntax</para></note>
  +<note><para>This introduction provides very few examples.  This book is
  +written in an <acronym>XML</acronym> <acronym>DTD</acronym> called DocBook
  +<acronym>XML</acronym>.  For an example of <acronym>XML</acronym> just look
  +at the book's source.  Since this book is documenting an
  +<acronym>XML</acronym> <acronym>DTD</acronym>, look at the rest of the
  +book's contents for examples of <acronym>DTD</acronym>
  +syntax.</para></note>
   
   <para>To begin, here are some basic rules of
   <acronym>XML</acronym> :</para>
  @@ -36,8 +39,8 @@
   <acronym>XML</acronym>.</para></listitem>
   
   <listitem><para>All <acronym>XML</acronym> documents must have a root
  -element. All <acronym>XML</acronym> documents must contain a single tag
  -pair to define a root element.</para></listitem>
  +element. In other words, all <acronym>XML</acronym> documents must contain
  +a single tag pair to define a root element.</para></listitem>
   
   <listitem><para>Attribute values must always be quoted. With
   <acronym>XML</acronym>, it is illegal to omit quotation marks around
  @@ -46,9 +49,10 @@
   <listitem><para>With <acronym>XML</acronym>, white space is
   preserved.</para></listitem>
   
  -<listitem><para>With <acronym>XML</acronym>, <acronym>CR</acronym> /
  -<acronym>LF</acronym> is converted to
  -<acronym>LF</acronym></para></listitem>
  +<listitem><para>With <acronym>XML</acronym>,
  +<filename><acronym>CR</acronym></filename> /
  +<filename><acronym>LF</acronym></filename> is converted to
  +<filename><acronym>LF</acronym></filename></para></listitem>
   
   </itemizedlist>
   
  @@ -57,19 +61,22 @@
   <sect2>
   <title>XML Elements and Attributes</title>
   
  -<para>XML is designed to hold any kind of information.  This information is
  -stored in Elements.  Elements are the basic building blocks of XML.
  -Attributes provide a mechanism to further define or classify an element.
  -Elements have relationships with other elements in a document.  Some are
  -parents and some are children.  Using this symantic description, one can
  -see that children elements need parent elements defined first.  As
  -mentioned in the last section, a XML document must have a root element.
  -Think of this as the ultimate parent element.  It must be defined before
  -all other elements and all elements will reside inside of the root element.
  -An element can have element content, mixed content, simple content, empty
  -content or attributes.</para>
  +<para><acronym>XML</acronym> is designed to hold any kind of information.
  +This information is stored in Elements.  Elements are the basic building
  +blocks of <acronym>XML</acronym> and are represented in an
  +<acronym>XML</acronym> documents as tag pairs.  Attributes provide a
  +mechanism to further define or classify an element.  Elements have
  +relationships with other elements in a document.  Some are parents and some
  +are children.  Using this symantic description, one can see that children
  +elements need parent elements defined and used first.  As mentioned in the
  +last section, an <acronym>XML</acronym> document must have a root element.
  +Think of this as the ultimate parent element.  It must be defined and used
  +before all other elements and all sub-elements (children) will reside
  +inside of the root element.  An element can have element content, mixed
  +content, simple content, empty content or attributes.</para>
   
  -<para>XML elements must follow these naming rules :</para>
  +<para><acronym>XML</acronym> elements must follow these naming
  +rules :</para>
   
   <itemizedlist>
   
  @@ -80,7 +87,7 @@
   character</para></listitem>
   
   <listitem><para>Names must not start with the letters xml (or XML or Xml
  -..)</para></listitem>
  +...)</para></listitem>
   
   <listitem><para>Names cannot contain spaces</para></listitem>
   
  @@ -89,67 +96,123 @@
   </sect2>
   
   <sect2>
  -<title>Quick Introduction to DTD Syntax</title>
  +<title>Quick Introduction to <acronym>DTD</acronym> Syntax</title>
   
  -<para>Once an XML document is written, it is generally a good idea to
  -validate the elements against a known DTD.  The Document Type Definition is
  -the mechanism with which one validates the content of a well-formed XML
  +<para>Once an <acronym>XML</acronym> document is written, it is generally a
  +good idea to validate the elements used in the document against a known
  +<acronym>DTD</acronym>.  The Document Type Definition is the mechanism with
  +which one validates the content of a well-formed <acronym>XML</acronym>
   document.</para>
   
  -<para>XML DTD files contain :</para>
  +<para><acronym>XML</acronym> <acronym>DTD</acronym> files
  +contain :</para>
   
   <itemizedlist>
   
   <listitem><para>Element declarations and definitions : Elements
  -are declared and defined with their relationships in the DTD
  -file.</para></listitem>
  +are declared and defined with their relationships in the
  +<acronym>DTD</acronym> file.</para></listitem>
   
   <listitem><para>Attribute declarations and definitions : Element
  -classes or attributes are declared and defined in the DTD
  -file.</para></listitem>
  +classes or attributes are declared and defined in the
  +<acronym>DTD</acronym> file.</para></listitem>
   
   <listitem><para>Entities : Entities are the same thing as
  -variables inside a DTD file or XML document.</para></listitem>
  +variables inside a <acronym>DTD</acronym> file or <acronym>XML</acronym>
  +document.</para></listitem>
   
  -<listitem><para>PCDATA : PCDATA is Parsed Character DATA. PCDATA
  -is text that will be parsed by a parser. Tags inside the text will be
  -treated as markup and entities will be expanded.</para></listitem>
  +<listitem><para><filename><acronym>PCDATA</acronym></filename> : <filename><acronym>PCDATA</acronym></filename>
  +is Parsed Character DATA. <filename><acronym>PCDATA</acronym></filename> is
  +text that will be parsed by a parser. Tags inside the text will be treated
  +as markup and entities will be expanded.</para></listitem>
   
  -<listitem><para>CDATA : CDATA is Character DATA. CDATA is text
  +<listitem><para><filename><acronym>CDATA</acronym></filename> : <filename><acronym>CDATA</acronym></filename>
  +is Character DATA. <filename><acronym>CDATA</acronym></filename> is text
   that will NOT be parsed by a parser. Tags inside the text will NOT be
   treated as markup and entities will not be expanded.</para></listitem>
   
   </itemizedlist>
   
  -<para>Elements are declared in the DTD file using a simple,
  -but strict syntax.  There are four ways to define an element :</para>
  +</sect2>
  +
  +<sect2>
  +<title><acronym>DTD</acronym> Element Declaration</title>
  +
  +<para>Elements are declared in the <acronym>DTD</acronym> file using a
  +simple, but strict syntax.  There are four ways to define an
  +element :</para>
   
   <itemizedlist>
   
  -<listitem><para>EMPTY : When an element is declared with the
  -EMPTY keyword, it means that the element will not hold any information.
  -This is generally used for special tags like <br>.</para></listitem>
  -
  -<listitem><para>ANY : When an element is declared with the ANY
  -keyword, it means that the element can contain any information that the
  -programmer wants it to. This is generally a special case.</para></listitem>
  +<listitem><para><filename>EMPTY</filename> : When an element is
  +declared with the <filename>EMPTY</filename> keyword, it means that the
  +element will not hold any information.  This is generally used for special
  +tags like <br>.</para></listitem>
  +
  +<listitem><para><filename>ANY</filename> : When an element is
  +declared with the <filename>ANY</filename> keyword, it means that the
  +element can contain any information that the author wants it to. This
  +is generally a special case.</para></listitem>
   
   <listitem><para>Character Data : When an element is declared with
  -either the PCDATA or CDATA keywords, the will hold one of the two types of
  -information described above.</para></listitem>
  +either the <filename>PCDATA</filename> or <filename>CDATA</filename>
  +keywords, it will hold one of the two types of information described
  +above.</para></listitem>
   
   <listitem><para>With Children : When an element is declared with
  -the names of other elements in it, this defines a parent child
  -relationship. Look in the DTD for the child element names to be further
  -defined with the other three ways.</para></listitem>
  +the names of other elements in it, this defines a parent-child
  +relationship. Look in the <acronym>DTD</acronym> for the child element
  +names to be further defined with the other three ways.</para></listitem>
   
  -<listitem><para>Mixed : Some combination of the above
  -four.</para></listitem>
  +<listitem><para>Mixed : Some combination of the above four.
  +Generally this is character data mixed with children.</para></listitem>
   
   </itemizedlist>
   
   <para>When an element is declared with children, it will also define how
  -the children can be called: </para>
  +the children can be used inside an <acronym>XML</acronym> document.  There
  +are four ways that children elements can be defined in a
  +<acronym>DTD</acronym> file : </para>
  +
  +<itemizedlist>
  +
  +<listitem><para>One Occurance Only : Example : 
  +<xref linkend="elem_search_replace"/>. The child elements of
  +<search_replace> &emdash; <file>, <find>, and
  +<replace> can one be used once. Notice that there are no symbols
  +after any of the child element names. This is the
  +identifier.</para></listitem>
  +
  +<listitem><para>Minimum of One Occurance : Example : 
  +<xref linkend="elem_permissions"/>. One of the child elements of
  +<permissions> &emdash; <name>, must be used a minimum
  +of once, but can also be used many times. Notice the plus [ + ]
  +symbol after the name. This is the identifier.</para></listitem>
  +
  +<listitem><para>Zero or More Occurances : Example : 
  +<xref linkend="elem_download"/>. One of the child elements of
  +<download> &emdash; <url>, can be used zero or
  +many times. Notice the asterisk [ * ] symbol after the name.
  +This is the identifier.</para></listitem>
  +
  +<listitem><para>Zero or One Occurance : Example : 
  +<xref linkend="elem_download"/>. One of the child elements of
  +<download> &emdash; <digest>, can be used zero
  +or one time only. Notice the question mark [ ? ] symbol after the name.
  +This is the identifier.</para></listitem>
  +
  +<listitem><para>Either / Or Occurances : Example : 
  +<xref linkend="elem_execute"/>. One of the two child elements of
  +<execute> &emdash; <param>, or <prefix>, can
  +only be used.  Notice the pipe [ | ] symbol in between the two
  +elements. This is the identifier.</para></listitem>
  +
  +</itemizedlist>
  +
  +</sect2>
  +
  +<sect2>
  +<title><acronym>DTD</acronym> Attribute Declaration</title>
   
   </sect2>
   
  
  
  
  1.24      +3 -0      ALFS/docs/syntax_doc/preface/changelog.xml
  
  Index: changelog.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/docs/syntax_doc/preface/changelog.xml,v
  retrieving revision 1.23
  retrieving revision 1.24
  diff -u -r1.23 -r1.24
  --- changelog.xml	15 Mar 2004 03:49:28 -0000	1.23
  +++ changelog.xml	16 Mar 2004 04:12:26 -0000	1.24
  @@ -6,6 +6,9 @@
   
   <itemizedlist>
   
  +<listitem><para>March, 15th, 2004 [jwrober]: Added more to the XML and DTD
  +syntax intro &emdash; Bug 784.</para></listitem>
  +
   <listitem><para>March, 14th, 2004 [jwrober]: Added an initial stab at an
   XML and DTD syntax intro &emdash; Bug 784.</para></listitem>
   
  
  
  



More information about the alfs-log mailing list