svn commit: r49372 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer
Gabor Kovesdan <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
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 <[email protected]>
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>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"