docs/85928: [patch] typo in ftp-primer (en_US.ISO8859-1)

Mon Sep 12 11:40:12 UTC 2005

The following reply was made to PR docs/85928; it has been noted by GNATS.

From: Yar Tikhiy <yar at comp.chem.msu.su>
To: Pierre Riteau <kineox at gmail.com>
Cc: freebsd-gnats-submit at 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 at 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, < and
 > > > > 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 <p>
 > > > +  <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 "<p>"
 > > 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 <p> 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 element
 		is not required in the single paragraph case.

Could you finally get the _literal_ "" if there were "", not
 "", 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, 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 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