Bug 85928
| Summary: | [patch] typo in fdp-primer (en_US.ISO8859-1) | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Pierre Riteau <kineox> |
| Component: | Books & Articles | Assignee: | Yar Tikhiy <yar> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
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. -- Yar 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, < 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. >=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 <p> > > + <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 "<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. >=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 <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 ? 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 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, < 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 <p> element is not required in the single paragraph case. Could you finally get the _literal_ "<p>" if there were "<p>", not "<p>", 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 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 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 The bug isn't there. Responsible Changed From-To: freebsd-doc->yar The bug isn't there. |
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. Fix: <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>--NIsGuIY1c79KoIToOvr7qARQHM6lINxmOANQKc1jpzxjQtEu Content-Type: text/plain; name="file.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="file.diff" --- 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 @@ How-To-Repeat: Read http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup.html#AEN1203