From nobody@FreeBSD.org  Fri Sep  9 21:59:13 2005
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 2585B16A41F
	for <freebsd-gnats-submit@FreeBSD.org>; Fri,  9 Sep 2005 21:59:13 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id EABD843D53
	for <freebsd-gnats-submit@FreeBSD.org>; Fri,  9 Sep 2005 21:59:12 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id j89LxCMV032297
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 9 Sep 2005 21:59:12 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id j89LxCaD032296;
	Fri, 9 Sep 2005 21:59:12 GMT
	(envelope-from nobody)
Message-Id: <200509092159.j89LxCaD032296@www.freebsd.org>
Date: Fri, 9 Sep 2005 21:59:12 GMT
From: Pierre Riteau <kineox@gmail.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] typo in ftp-primer (en_US.ISO8859-1)
X-Send-Pr-Version: www-2.3

>Number:         85928
>Category:       docs
>Synopsis:       [patch] typo in fdp-primer (en_US.ISO8859-1)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    yar
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Sep 09 22:00:32 GMT 2005
>Closed-Date:    Mon Sep 12 16:12:43 GMT 2005
>Last-Modified:  Mon Sep 12 16:12:43 GMT 2005
>Originator:     Pierre Riteau
>Release:        none (error seen on the online doc)
>Organization:
>Environment:
>Description:
In the fdp-primer document, in the chapter sgml-markup, &lt; and &gt; entites are used but they are in a CDATA section, so the tag is not displayed correctly. I may add that there are a huge number of the same mistakes in the french (fr_FR.ISO8859-1) translation of fdp-primer. I have not made a patch for this one.
>How-To-Repeat:
Read http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup.html#AEN1203
>Fix:
--- chapter.sgml.orig   2005-09-09 23:30:54.000000000 +0200
+++ chapter.sgml        2005-09-09 23:44:47.000000000 +0200
@@ -302,7 +302,7 @@

   <dt>Term 3</dt>

-  <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
+  <dd>Paragraph 1 of definition 3.  Note that the <p>
     element is not required in the single paragraph case.</dd>
 </dl>]]></programlisting>
        </example>
>Release-Note:
>Audit-Trail:

From: Yar Tikhiy <yar@comp.chem.msu.su>
To: Pierre Riteau <kineox@gmail.com>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/85928: [patch] typo in ftp-primer (en_US.ISO8859-1)
Date: Mon, 12 Sep 2005 13:19:31 +0400

 On Fri, Sep 09, 2005 at 09:59:12PM +0000, Pierre Riteau wrote:
 > >Description:
 > In the fdp-primer document, in the chapter sgml-markup, &lt; and
 > &gt; entites are used but they are in a CDATA section, so the tag
 > is not displayed correctly. I may add that there are a huge number
 > of the same mistakes in the french (fr_FR.ISO8859-1) translation
 > of fdp-primer. I have not made a patch for this one.
 
 > >How-To-Repeat:
 > Read http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup.html#AEN1203
 > >Fix:
 > --- chapter.sgml.orig   2005-09-09 23:30:54.000000000 +0200
 > +++ chapter.sgml        2005-09-09 23:44:47.000000000 +0200
 > @@ -302,7 +302,7 @@
 > 
 >    <dt>Term 3</dt>
 > 
 > -  <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
 > +  <dd>Paragraph 1 of definition 3.  Note that the <p>
 >      element is not required in the single paragraph case.</dd>
 >  </dl>]]></programlisting>
 >         </example>
 
 I'm afraid you're not quite right here.  The subsection talks about HTML
 and gives examples of raw HTML code, where you need to write "&lt;p&gt;"
 to get "<p>" in the rendering.  If you write just "<p>", it will be
 swallowed by the HTML engine, and you will get a new paragraph, which
 is not what you want.  Therefore the example is correct WRT to this.
 
 However, I'd argue the statement the example makes.  According to my
 experience with HTML documents using CSS, you will get different renderings
 of a text block depending on whether you use "<p>" in front of it because
 there can be style elements implicitly associated with the <p> tag.  Since
 today nearly everybody uses CSS, it is an important point.
 
 -- 
 Yar

From: Pierre Riteau <kineox@gmail.com>
To: Yar Tikhiy <yar@comp.chem.msu.su>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/85928: [patch] typo in ftp-primer (en_US.ISO8859-1)
Date: Mon, 12 Sep 2005 12:31:40 +0200

 2005/9/12, Yar Tikhiy <yar@comp.chem.msu.su>:
 > On Fri, Sep 09, 2005 at 09:59:12PM +0000, Pierre Riteau wrote:
 > > >Description:
 > > In the fdp-primer document, in the chapter sgml-markup, &lt; and
 > > &gt; entites are used but they are in a CDATA section, so the tag
 > > is not displayed correctly. I may add that there are a huge number
 > > of the same mistakes in the french (fr_FR.ISO8859-1) translation
 > > of fdp-primer. I have not made a patch for this one.
 >=20
 > > >How-To-Repeat:
 > > Read http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-m=
 arkup.html#AEN1203
 > > >Fix:
 > > --- chapter.sgml.orig   2005-09-09 23:30:54.000000000 +0200
 > > +++ chapter.sgml        2005-09-09 23:44:47.000000000 +0200
 > > @@ -302,7 +302,7 @@
 > >
 > >    <dt>Term 3</dt>
 > >
 > > -  <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
 > > +  <dd>Paragraph 1 of definition 3.  Note that the <p>
 > >      element is not required in the single paragraph case.</dd>
 > >  </dl>]]></programlisting>
 > >         </example>
 >=20
 > I'm afraid you're not quite right here.  The subsection talks about HTML
 > and gives examples of raw HTML code, where you need to write "&lt;p&gt;"
 > to get "<p>" in the rendering.  If you write just "<p>", it will be
 > swallowed by the HTML engine, and you will get a new paragraph, which
 > is not what you want.  Therefore the example is correct WRT to this.
 >=20
 > However, I'd argue the statement the example makes.  According to my
 > experience with HTML documents using CSS, you will get different renderin=
 gs
 > of a text block depending on whether you use "<p>" in front of it because
 > there can be style elements implicitly associated with the <p> tag.  Sinc=
 e
 > today nearly everybody uses CSS, it is an important point.
 
 Well, did you watch the document I linked ? I am sure it was not
 intended to be displayed like this. In the SGML source [1] you can see
 that there are <dl> and <dd> tags around the &lt;p&gt; we are talking
 about. They are displayed as is in the HTML document, they are not
 caught as definition tags by the SGML -> HTML conversion engine,
 because a CDATA section is on (it ends after the </dl> with the "]]").
 Why would a <p> not be displayed as is in the same way ?
 
 And if you watch the source [1] a few lines above (ln 395, 297 and
 301), you will see that there are <p> tags, and they are displayed as
 is in the HTML document. So I think I am quite right here ;)
 
 Anyway thanks for working on the problem. And sorry for my crappy english..=
 .
 
 Pierre
 
 [1] http://www.freebsd.org/cgi/cvsweb.cgi/~checkout~/doc/en_US.ISO8859-1/bo=
 oks/fdp-primer/sgml-markup/chapter.sgml?rev=3D1.69

From: Yar Tikhiy <yar@comp.chem.msu.su>
To: Pierre Riteau <kineox@gmail.com>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/85928: [patch] typo in ftp-primer (en_US.ISO8859-1)
Date: Mon, 12 Sep 2005 15:30:55 +0400

 On Mon, Sep 12, 2005 at 12:31:40PM +0200, Pierre Riteau wrote:
 > 2005/9/12, Yar Tikhiy <yar@comp.chem.msu.su>:
 > > On Fri, Sep 09, 2005 at 09:59:12PM +0000, Pierre Riteau wrote:
 > > > >Description:
 > > > In the fdp-primer document, in the chapter sgml-markup, &lt; and
 > > > &gt; entites are used but they are in a CDATA section, so the tag
 > > > is not displayed correctly. I may add that there are a huge number
 > > > of the same mistakes in the french (fr_FR.ISO8859-1) translation
 > > > of fdp-primer. I have not made a patch for this one.
 > > 
 > > > >How-To-Repeat:
 > > > Read http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup.html#AEN1203
 > > > >Fix:
 > > > --- chapter.sgml.orig   2005-09-09 23:30:54.000000000 +0200
 > > > +++ chapter.sgml        2005-09-09 23:44:47.000000000 +0200
 > > > @@ -302,7 +302,7 @@
 > > >
 > > >    <dt>Term 3</dt>
 > > >
 > > > -  <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
 > > > +  <dd>Paragraph 1 of definition 3.  Note that the <p>
 > > >      element is not required in the single paragraph case.</dd>
 > > >  </dl>]]></programlisting>
 > > >         </example>
 > > 
 > > I'm afraid you're not quite right here.  The subsection talks about HTML
 > > and gives examples of raw HTML code, where you need to write "&lt;p&gt;"
 > > to get "<p>" in the rendering.  If you write just "<p>", it will be
 > > swallowed by the HTML engine, and you will get a new paragraph, which
 > > is not what you want.  Therefore the example is correct WRT to this.
 > > 
 > > However, I'd argue the statement the example makes.  According to my
 > > experience with HTML documents using CSS, you will get different renderings
 > > of a text block depending on whether you use "<p>" in front of it because
 > > there can be style elements implicitly associated with the <p> tag.  Since
 > > today nearly everybody uses CSS, it is an important point.
 > 
 > Well, did you watch the document I linked ?
 
 Sure I did.
 
 > I am sure it was not
 > intended to be displayed like this.
 
 And I believe it was.
 
 > In the SGML source [1] you can see
 > that there are <dl> and <dd> tags around the &lt;p&gt; we are talking
 > about. They are displayed as is in the HTML document, they are not
 > caught as definition tags by the SGML -> HTML conversion engine,
 > because a CDATA section is on (it ends after the </dl> with the "]]").
 > Why would a <p> not be displayed as is in the same way ?
 
 You seem to be missing the whole point.  It is an _example_ of raw
 HTML source to show to the reader of fdp-primer.  Can people new
 to the FreeBSD DocProject read SGML or HTML source better than
 morning newspapers?  As a rule, no.  Instead, they go to www.freebsd.org
 and read what their browser shows to them.  OK, some of such people
 want to study basic HTML and so they read the relevant section of
 fdp-primer.  While reading, they meet some easy examples of HTML
 code to start with.  Do they need to click "View HTML source" for
 that?  No, they see the sample HTML code along with the body text.
 Can they cut'n'paste the sample HTML code in a new .html file and
 load it into another browser window?  For sure, so they get an idea
 of how HTML works.  And now, the crucial question: what should they
 see then?
 
 Imagine that you are such a self-studying person.  Now think of how
 the sample code should render if you open
 
 http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup.html#AEN1203
 
 in your browser, cut'n'paste the example into a .html file and load
 the .html file into your browser:
 
 	Term 3
 		Paragraph 1 of definition 3.  Note that the <p> element
 		is not required in the single paragraph case.
 
 Could you finally get the _literal_ "<p>" if there were "<p>", not
 "&lt;p&gt;", in the example you saw on your screen?  No, you could
 not.  You would get something like this instead:
 
 	Term 3
 		Paragraph 1 of definition 3.  Note that the
 
 		element is not required in the single paragraph case.
 
 The example shows you how to make HTML render into what looks like
 HTML.  So you can write a book on HTML in HTML.
 
 > And if you watch the source [1] a few lines above (ln 395, 297 and
 > 301), you will see that there are <p> tags, and they are displayed as
 > is in the HTML document. So I think I am quite right here ;)
 
 In those lines, <p> tags are intended to become *real* HTML tags if you
 cut'n'paste the examples into your own HTML code.
 
 P.S. I'd rather kill the sentence saying, "Note that the <p> element
 is not required in the single paragraph case."  First, it is a bogus
 statement in the presence of CSS.  Second, we'll have nothing to argue
 over then ;-)
 
 -- 
 Yar

From: Pierre Riteau <kineox@gmail.com>
To: Yar Tikhiy <yar@comp.chem.msu.su>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/85928: [patch] typo in ftp-primer (en_US.ISO8859-1)
Date: Mon, 12 Sep 2005 14:42:40 +0200

 2005/9/12, Yar Tikhiy <yar@comp.chem.msu.su>:
 > You seem to be missing the whole point.  It is an _example_ of raw
 > HTML source to show to the reader of fdp-primer.
 
 Oh, now I get it. I was totally misunderstanding the purpose of this
 example. The fact that it was not easy to read made me think that it
 was a mistake. So the french documents is right too. I'm so sorry...
 
 Thank you for explaining me clearly why I was totally wrong, and I'm
 sorry I wasted your time so much.
 
 > P.S. I'd rather kill the sentence saying, "Note that the <p> element
 > is not required in the single paragraph case."  First, it is a bogus
 > statement in the presence of CSS.  Second, we'll have nothing to argue
 > over then ;-)
 
 I'm far from being an expert in HTML/CSS, I want to be sure I am
 understanding well. What do you mean by "style elements implicitly
 associated with the <p> tag" ?
 
 Pierre

From: Yar Tikhiy <yar@comp.chem.msu.su>
To: Pierre Riteau <kineox@gmail.com>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/85928: [patch] typo in ftp-primer (en_US.ISO8859-1)
Date: Mon, 12 Sep 2005 17:58:51 +0400

 On Mon, Sep 12, 2005 at 02:42:40PM +0200, Pierre Riteau wrote:
 > 2005/9/12, Yar Tikhiy <yar@comp.chem.msu.su>:
 > > You seem to be missing the whole point.  It is an _example_ of raw
 > > HTML source to show to the reader of fdp-primer.
 > 
 > Oh, now I get it. I was totally misunderstanding the purpose of this
 > example. The fact that it was not easy to read made me think that it
 > was a mistake. So the french documents is right too. I'm so sorry...
 > 
 > Thank you for explaining me clearly why I was totally wrong, and I'm
 > sorry I wasted your time so much.
 
 Never mind, recursive examples of markup can be really tough to grok :-)
 
 > > P.S. I'd rather kill the sentence saying, "Note that the <p> element
 > > is not required in the single paragraph case."  First, it is a bogus
 > > statement in the presence of CSS.  Second, we'll have nothing to argue
 > > over then ;-)
 > 
 > I'm far from being an expert in HTML/CSS, I want to be sure I am
 > understanding well. What do you mean by "style elements implicitly
 > associated with the <p> tag" ?
 
 I mean the following.  AFAIK, it is possible with CSS to specify
 that ordinary <body> text will be, say, Times New Roman 12pt single
 spaced while any <p> text will be Helvetica 14pt double spaced.  In
 fact, if you specify any properties for <p> text with CSS, there
 will be a great chance of them different from the default properties
 of ordinary <body> text.
 
 By "implicitly" (perhaps a poorly chosen word) I meant that you
 write "<p>something" just to get a new paragraph, but get a different
 style for the text unexpectedly if you don't control the CSS.  And
 vice versa, you may need to always use <p> if the CSS defines finer
 style for <p> text, but leaves ordinary text at its defaults.
 
 -- 
 Yar
State-Changed-From-To: open->closed 
State-Changed-By: yar 
State-Changed-When: Mon Sep 12 16:10:49 GMT 2005 
State-Changed-Why:  
The bug isn't there. 


Responsible-Changed-From-To: freebsd-doc->yar 
Responsible-Changed-By: yar 
Responsible-Changed-When: Mon Sep 12 16:10:49 GMT 2005 
Responsible-Changed-Why:  
The bug isn't there. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=85928 
>Unformatted:
