Attachment 163635 Details for Bug 204885 – Rewrite of the XML comments section in FDP

Rewrite of the XML comments section in FDP

new_comments_chapter.txt (text/plain), 3.31 KB, created by Andreas Perstinger on 2015-11-28 18:42:29 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Andreas Perstinger

Created: 2015-11-28 18:42:29 UTC

Size: 3.31 KB

patch

obsolete

>Index: chapter.xml
>===================================================================
>--- chapter.xml	(revision 47806)
>+++ chapter.xml	(working copy)
>@@ -718,56 +718,40 @@
>   <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>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>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><acronym>XML</acronym> comments start with the string
>+      <quote><literal>&lt;!--</literal></quote> and end with the
>+      string <quote><literal>--&gt;</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>&lt;!-- This is inside the comment --&gt;
> 
>-&lt;!-- This is another comment    --&gt;
>+&lt;!--This is another comment--&gt;
> 
>-&lt;!-- This is one way
>-     of doing multiline comments --&gt;
>+&lt;!-- This is how you
>+     write multiline comments --&gt;
> 
>-&lt;!-- This is another way of   --
>-  -- doing multiline comments --&gt;</programlisting>
>+&lt;p&gt;A simple &lt;!-- Comment inside an element's content --&gt; paragraph.&lt;/p&gt;</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>&lt;!--</literal> opens a comment, and it is
>-      only closed by <literal>--&gt;</literal>.</para>
>+    <para><acronym>XML</acronym> comments may contain any strings
>+      except <quote><literal>--</literal></quote>:</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>
>-
>     <example>
>-      <title>Erroneous <acronym>XML</acronym> Comments</title>
>+      <title>Erroneous <acronym>XML</acronym> Comment</title>
> 
>-      <programlisting>&lt;!-- This is in the comment --
>-
>-     THIS IS OUTSIDE THE COMMENT!
>-
>-  -- back inside the comment --&gt;</programlisting>
>-
>-      <para>The <acronym>XML</acronym> parser will treat this as
>-	though it were actually:</para>
>-
>-      <programlisting>&lt;!THIS IS OUTSIDE THE COMMENT&gt;</programlisting>
>-
>-      <para>That is not valid <acronym>XML</acronym>, and may give
>-	confusing error messages.</para>
>+      <programlisting>&lt;!-- This comment--is wrong --&gt;</programlisting>
>     </example>
> 
>     <sect2>

Actions: View

Attachments on bug 204885: 163635