Date: Thu, 8 Sep 2016 14:40:04 +0000 (UTC) From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r49372 - head/en_US.ISO8859-1/books/fdp-primer/xml-primer Message-ID: <201609081440.u88Ee4kO076004@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201609081440.u88Ee4kO076004>