svn commit: r49372 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer

[Gabor Kovesdan]

Author: gabor
Date: Thu Sep  8 14:40:03 2016
New Revision: 49372
URL: https://svnweb.freebsd.org/changeset/doc/49372

Log:
  - Update and simplify section on comments according to the XML standard
    (this section still reflected some old SGML constructs).
  
  PR:		204885
  Submitted by:	Andreas Perstinger <andipersti at gmail.com>

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml

Modified: head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml	Thu Sep  8 14:31:17 2016	(r49371)
+++ head/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml	Thu Sep  8 14:40:03 2016	(r49372)
@@ -717,56 +717,40 @@ example.xml:5: element head: validity er
   <sect1 xml:id="xml-primer-comments">
     <title>Comments</title>
 
-    <para>Comments are an <acronym>XML</acronym> construct, and are
-      normally only valid inside a <acronym>DTD</acronym>.  However,
-      as <xref linkend="xml-primer-xml-escape"/> shows, it is possible
-      to use <acronym>XML</acronym> syntax within the document.</para>
-
-    <para>The delimiter for XML comments is the string
-      <quote><literal>--</literal></quote>.  The first occurrence of
-      this string opens a comment, and the second closes it.</para>
+    <para>An <acronym>XML</acronym> document may contain comments.
+      They may appear anywhere as long as they are not inside tags.
+      They are even allowed in some locations inside the
+      <acronym>DTD</acronym> (e.g., between <link
+	linkend="xml-primer-entities">entity
+	declarations</link>).</para>
+
+    <para><acronym>XML</acronym> comments start with the string
+      <quote><literal><!--</literal></quote> and end with the
+      string <quote><literal>--></literal></quote>.</para>
+
+    <para>Here are some examples of valid <acronym>XML</acronym>
+      comments:</para>
 
     <example>
-      <title><acronym>XML</acronym> Generic Comment</title>
+      <title><acronym>XML</acronym> Generic Comments</title>
 
       <programlisting><!-- This is inside the comment -->
 
-<!-- This is another comment    -->
+<!--This is another comment-->
 
-<!-- This is one way
-     of doing multiline comments -->
+<!-- This is how you
+     write multiline comments -->
 
-<!-- This is another way of   --
-  -- doing multiline comments --></programlisting>
+<p>A simple <!-- Comment inside an element's content --> paragraph.</p></programlisting>
     </example>
 
-    <para><acronym>XHTML</acronym> users may be familiar with different
-      rules for comments.  In particular, it is often believed that
-      the string <literal><!--</literal> opens a comment, and it is
-      only closed by <literal>--></literal>.</para>
-
-    <para>This is <emphasis>not</emphasis> correct.  Many web browsers
-      have broken <acronym>XHTML</acronym> parsers, and will accept
-      incorrect input as valid.  However, the <acronym>XML</acronym>
-      parsers used by the Documentation Project are more strict, and
-      will reject documents with that error.</para>
+    <para><acronym>XML</acronym> comments may contain any strings
+      except <quote><literal>--</literal></quote>:</para>
 
     <example>
-      <title>Erroneous <acronym>XML</acronym> Comments</title>
-
-      <programlisting><!-- This is in the comment --
-
-     THIS IS OUTSIDE THE COMMENT!
-
-  -- back inside the comment --></programlisting>
-
-      <para>The <acronym>XML</acronym> parser will treat this as
-	though it were actually:</para>
-
-      <programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting>
+      <title>Erroneous <acronym>XML</acronym> Comment</title>
 
-      <para>That is not valid <acronym>XML</acronym>, and may give
-	confusing error messages.</para>
+      <programlisting><!-- This comment--is wrong --></programlisting>
     </example>
 
     <sect2>