Date: Mon, 03 Nov 2008 08:53:30 +0100 From: Gabor PALI <pgj@FreeBSD.org> To: Eitan Adler <eitanadlerlist@gmail.com> Cc: freebsd-doc@freebsd.org Subject: Re: change to sgml-primer example Message-ID: <490EADFA.3020708@FreeBSD.org> In-Reply-To: <490E2907.5090907@gmail.com> References: <490E2907.5090907@gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Eitan Adler wrote:
> Can anyone comment on the attached patch to be run from
> /usr/doc/en_US.ISO8859-1/books/fdp-primer/sgml-primer
------------------------------------------------------------------------
--- chapter.sgml 2008-10-31 08:23:35.000000000 -0400
+++ newchapter.sgml 2008-11-02 17:21:54.000000000 -0500
@@ -862,6 +862,7 @@
<example>
<title>Erroneous SGML comments</title>
+ <para> The SGML parser will treat </para>
<programlisting><![ CDATA [
<!-- This is in the comment --
@@ -870,22 +871,21 @@
-- back inside the comment -->]]></programlisting>
- <para>The SGML parser will treat this as though it were
actually:</para>
+ <para>as though it were actually:</para>
I would not prefer splitting paragraphs around <programlisting>
elements, as I have already fought against this before [1].
<programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting>
<para>This is not valid SGML, and may give confusing error
messages.</para>
+ <para>Because "--" delimitates the end of a comment do
<emphasis>do not</emphasis> write comments like this: </para>
+
<programlisting><![ CDATA [<!--------------- This is a very bad
idea --------------->]]></programlisting>
- <para>As the example suggests, <emphasis>do not</emphasis> write
- comments like that.</para>
+ <para>This is a (slightly) better approach, but it still potentially
confusing to people new to SGML:</para>
<programlisting><![ CDATA
[<!--===================================================-->]]></programlisting>
- <para>That is a (slightly) better approach, but it still potentially
- confusing to people new to SGML.</para>
</example>
<sect2>
In my very humble opinion, I am good with the original text.
Cheers,
:g
[1]
http://www.freebsd.org/cgi/cvsweb.cgi/doc/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?490EADFA.3020708>