From ue@nathan.ruhr.de  Thu Jul 20 05:24:49 2000
Return-Path: <ue@nathan.ruhr.de>
Received: from mail.ruhr.de (in-ruhr2.ruhr.de [141.39.224.60])
	by hub.freebsd.org (Postfix) with SMTP id DDE2437BA99
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Jul 2000 05:24:47 -0700 (PDT)
	(envelope-from ue@nathan.ruhr.de)
Received: (qmail 19109 invoked by alias); 20 Jul 2000 12:26:19 -0000
Received: (from ue@localhost)
	by nathan.ruhr.de (8.9.3/8.9.3) id OAA66040;
	Thu, 20 Jul 2000 14:22:41 +0200 (CEST)
	(envelope-from ue)
Message-Id: <200007201222.OAA66040@nathan.ruhr.de>
Date: Thu, 20 Jul 2000 14:22:41 +0200 (CEST)
From: Udo Erdelhoff <ue@nathan.ruhr.de>
Reply-To: ue@nathan.ruhr.de
To: FreeBSD-gnats-submit@freebsd.org
Subject: Bad SGML in the "@ sign" entry of the FAQ
X-Send-Pr-Version: 3.2

>Number:         20056
>Category:       docs
>Synopsis:       Bad SGML in the "@ sign" entry of the FAQ
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 20 05:30:00 PDT 2000
>Closed-Date:    Thu Jul 20 16:55:06 BST 2000
>Last-Modified:  Fri Jul 21 09:30:01 PDT 2000
>Originator:     Udo Erdelhoff
>Release:        FreeBSD 5.0-CURRENT i386
>Organization:
>Environment:

$FreeBSD: doc/en_US.ISO_8859-1/books/faq/book.sgml,v 1.72

>Description:

The FAQ entry about the use of @ for the pn capability uses the string
<@> to denote the @-character. The use of <> is reserved for SGML tags,
<@> is not a valid tag.

Found during devlopment of suppe.

>How-To-Repeat:

n/a

>Fix:

Two diffs. The first replaces <@> with &lt;@&gt;. While I'm here, replace
<emphasis remap=tt></emphasis> with <literal></literal>, replace the
links to man.cgi for the filenames with the proper <filename></filename>,
use <programlisting> instead of <literallayout> and remove the <para></para>
around <programlisting> to remove one of the many warnings issued by tidy.

The second diff fixes the indentation and the word wrapping. Whitespace
changes only, may be ignored by the translations teams. Reformatting done
by suppe 1.6, about 850 KBytes (19763 lines) of diffs left :->

First diff:
--- book.sgml	Thu Jul 20 13:20:55 2000
+++ book.sgml.orig	Thu Jul 20 13:36:15 2000
@@ -8209,14 +8209,17 @@
 </answer></qandaentry>
 
 <qandaentry><question>
-<para>The <literal>&lt;@&gt;</literal> sign for the pn capability doesn't work!</para></question><answer>
+<para>The <emphasis remap=tt><@></emphasis> sign for the pn capability doesn't work!</para></question><answer>
 
-<para>The <literal>&lt;@&gt;</literal> sign in the phone number capability tells tip to look in
-<filename>/etc/phones</filename> for a phone number.  But the <literal>&lt;@&gt;</literal> sign is
+<para>The <emphasis remap=tt><@></emphasis> sign in the phone number capability tells tip to look in
+<ulink URL="http://www.FreeBSD.org/cgi/man.cgi?phones(5)">/etc/phones</ulink> for a phone number.  But the <emphasis remap=tt><@></emphasis> sign is
 also a special character in capability files like
-<filename>/etc/remote</filename>.  Escape it with a backslash:</para>
+<ulink URL="http://www.FreeBSD.org/cgi/man.cgi?remote">/etc/remote</ulink>.  Escape it with a backslash:</para>
 
-<programlisting>        pn=\@</programlisting>
+<para>
+<literallayout>        pn=\@
+      </literallayout>
+</para>
 
 </answer></qandaentry>
 
Second diff:

--- book.sgml.orig	Thu Jul 20 13:41:05 2000
+++ book.sgml	Thu Jul 20 13:41:39 2000
@@ -8208,17 +8208,24 @@
 
 </answer></qandaentry>
 
-<qandaentry><question>
-<para>The <literal>&lt;@&gt;</literal> sign for the pn capability doesn't work!</para></question><answer>
+      <qandaentry>
+        <question>
+          <para>The <literal>&lt;@&gt;</literal> sign for the pn capability
+            doesn't work!</para>
+        </question>
 
-<para>The <literal>&lt;@&gt;</literal> sign in the phone number capability tells tip to look in
-<filename>/etc/phones</filename> for a phone number.  But the <literal>&lt;@&gt;</literal> sign is
-also a special character in capability files like
-<filename>/etc/remote</filename>.  Escape it with a backslash:</para>
+        <answer>
+          <para>The <literal>&lt;@&gt;</literal> sign in the phone number
+            capability tells tip to look in
+            <filename>/etc/phones</filename> for a phone number.  But the
+            <literal>&lt;@&gt;</literal> sign is also a special character
+            in capability files like <filename>/etc/remote</filename>.
+            Escape it with a backslash:</para>
 
 <programlisting>        pn=\@</programlisting>
 
-</answer></qandaentry>
+        </answer>
+      </qandaentry>
 
 <qandaentry><question>
 <para>How can I dial a phone number on the command line?</para></question><answer>

>Release-Note:
>Audit-Trail:

From: Ben Smithurst <ben@FreeBSD.org>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Thu, 20 Jul 2000 14:37:56 +0100

 Udo Erdelhoff wrote:
 
 > Two diffs. The first replaces <@> with &lt;@&gt;. While I'm here, replace
 > <emphasis remap=tt></emphasis> with <literal></literal>, replace the
 > links to man.cgi for the filenames with the proper <filename></filename>,
 > use <programlisting> instead of <literallayout> and remove the <para></para>
 > around <programlisting> to remove one of the many warnings issued by tidy.
 
 Looks good to me, with one minor exception: the white space before the
 "pn=\@" line in <programlisting> is unnecessary.
 
 > The second diff fixes the indentation and the word wrapping. Whitespace
 > changes only, may be ignored by the translations teams. Reformatting done
 > by suppe 1.6, about 850 KBytes (19763 lines) of diffs left :->
 
 I think I'll leave this bit, if you don't mind too much, it can be
 committed in one batch at some point.
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 

From: Udo Erdelhoff <ue@nathan.ruhr.de>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Thu, 20 Jul 2000 16:36:05 +0200

 Hi,
 > Looks good to me, with one minor exception: the white space before the
 > "pn=\@" line in <programlisting> is unnecessary.
 
 whitespace and linebreaks within a <programlisting> element are significant.
 With the whitespace in front of the pn=\@, the output will be intended by
 approximately one tab. Without it, it will start in column 0.
 
 Or did you mean that I should not intend the the output? In that case, 
 replace the whole line with <para><literal>pn=\@</literal></para>. You
 could even change the end of the previous paragraph to read
 
 ...with a backslash, i.e. use <literal>pn=\@</literal>.</para>
 
 and remove the <programlisting> element completly.
 
 > I think I'll leave this bit, if you don't mind too much, it can be
 > committed in one batch at some point.
 
 I don't mind.
 
 /s/Udo
 -- 
 Ich bin root, ich darf das.
 
State-Changed-From-To: open->closed 
State-Changed-By: ben 
State-Changed-When: Thu Jul 20 16:55:06 BST 2000 
State-Changed-Why:  
Functional part committed.  White space change not committed, that will 
probably all get cleaned up in a mega-commit at some point. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20056 

From: Ben Smithurst <ben@FreeBSD.org>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Thu, 20 Jul 2000 16:54:56 +0100

 Udo Erdelhoff wrote:
 
 > Hi,
 >> Looks good to me, with one minor exception: the white space before the
 >> "pn=\@" line in <programlisting> is unnecessary.
 > 
 > whitespace and linebreaks within a <programlisting> element are significant.
 > With the whitespace in front of the pn=\@, the output will be intended by
 > approximately one tab. Without it, it will start in column 0.
 
 Not in the HTML output I see.
 
 <pre class="PROGRAMLISTING">
     pn=\@
 </pre>
 
 That results from <programlisting>pn=\@</programlisting>, and I'd assume
 conversions to other formats get this right too.
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 

From: Udo Erdelhoff <ue@nathan.ruhr.de>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Thu, 20 Jul 2000 18:24:35 +0200

 On Thu, Jul 20, 2000 at 04:54:56PM +0100, Ben Smithurst wrote:
 > <pre class="PROGRAMLISTING">
 >     pn=\@
 > </pre>
 The html-tag pre indicates preformatted text and both Netscape 4 and the
 Preview 1 of Netscape 6 (I admit my sin: Yes, I'm using Windows 98, too)
 indent this text.
 
 Note: You must activate style sheets and javascript in a 4.x Netscape to
 see the effect - Netscape 4 handles style sheets by converting them into
 javascript commands. No javascript -> no style sheets -> left aligned.
 
 Even lynx creates the indent. w3m should do that, too.
 
 > That results from <programlisting>pn=\@</programlisting>, and I'd assume
 > conversions to other formats get this right too.
 
 My eyes tell me a rather different story :-)
 
 /s/Udo
 -- 
 Q:  How do you play religious roulette?
 A:  You stand around in a circle and blaspheme and see who gets struck
     by lightning first.
 

From: Ben Smithurst <ben@FreeBSD.org>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Thu, 20 Jul 2000 21:46:41 +0100

 Udo Erdelhoff wrote:
 
 > On Thu, Jul 20, 2000 at 04:54:56PM +0100, Ben Smithurst wrote:
 >> <pre class="PROGRAMLISTING">
 >>     pn=\@
 >> </pre>
 > The html-tag pre indicates preformatted text and both Netscape 4 and the
 > Preview 1 of Netscape 6 (I admit my sin: Yes, I'm using Windows 98, too)
 > indent this text.
 
 Yes.  That's what I see too.
 
 >> That results from <programlisting>pn=\@</programlisting>, and I'd assume
 >> conversions to other formats get this right too.
 > 
 > My eyes tell me a rather different story :-)
 
 About what? <programlisting> without the leading white space produces an
 indent, are you saying the other formats get this wrong?
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 

From: Udo Erdelhoff <ue@nathan.ruhr.de>
To: Ben Smithurst <ben@FreeBSD.org>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Fri, 21 Jul 2000 17:02:36 +0200

 Hi Ben,
 my apologies for the late answer, but I wanted to have lots of sleep before
 I tried to unravel this mess.
 
 > > The html-tag pre indicates preformatted text and both Netscape 4 and the
 > > Preview 1 of Netscape 6 (I admit my sin: Yes, I'm using Windows 98, too)
 > > indent this text.
 > 
 > Yes.  That's what I see too.
 Duh. I assumed your statement "the whitespace is not neccessary" meant
 "the whitespace is ignored". Repeat after me: "assume makes an ass out of
 u and me" :-(
 
 > About what? <programlisting> without the leading white space produces an
 > indent, are you saying the other formats get this wrong?
 
 I compared the indent created by the old version (literallayout) with
 the new version (programlisting). The default indentation created by
 <programlisting> (or, to be precise, created by the corresponding HTML
 code) is much smaller than the indentation created by <literallayout>.
 I added the additional whitespace to have an almost identical amount
 of indentation in the new version.
 
 BTW: I've found another instance of the original problem: There's a <\@> a
 few entries later. The patch replaces <\@> with &lt;\@&gt;
 While I'm here :-)
 - replace <ulink ...man.cgi>/etc/remote</ulink> with <filename>...
 - replace <emphasis remap=tt>-Elements with <literal>-elements
 - replace <literallayout>-elments with <programlisting>-elements
 - remove the useless <para>-elements around the <programlisting>-elements;
   this change removes two tidy-warnings
 - replace the first instance of <ulink..man.cgi>tip</ulink> with &man.tip.1;
 - replace the second instace of this element with <command>tip</command>
   and add a command-element around the while of "in a while loop".
 
 --- book.sgml.orig	Fri Jul 21 16:17:22 2000
 +++ book.sgml	Fri Jul 21 16:32:40 2000
 @@ -8368,30 +8368,26 @@
  <para>This is often a problem where a university has several modem lines
  and several thousand students trying to use them...</para>
  
 -<para>Make an entry for your university in <ulink URL="http://www.FreeBSD.org/cgi/man.cgi?remote">/etc/remote</ulink>
 -and use <emphasis remap=tt><\@></emphasis> for the <emphasis remap=tt>pn</emphasis> capability:</para>
 +<para>Make an entry for your university in <filename>/etc/remote</filename>
 +and use <literal>&lt;\@&gt;</literal> for the <literal>pn</literal> capability:</para>
  
 -<para>
 -<literallayout>        big-university:\
 +<programlisting>        big-university:\
          :pn=\@:tc=dialout
          dialout:\
          :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:
 -      </literallayout>
 -</para>
 +</programlisting>
  
  <para>Then, list the phone numbers for the university in
 -<ulink URL="http://www.FreeBSD.org/cgi/man.cgi?phones">/etc/phones</ulink>:</para>
 +<filename>/etc/phones</filename>:</para>
  
 -<para>
 -<literallayout>        big-university 5551111
 +<programlisting>        big-university 5551111
          big-university 5551112
          big-university 5551113
          big-university 5551114
 -      </literallayout>
 -</para>
 +</programlisting>
  
 -<para><ulink URL="http://www.FreeBSD.org/cgi/man.cgi?tip">tip</ulink> will try each one in the listed order, then give up.  If
 -you want to keep retrying, run <emphasis remap=tt>tip</emphasis> in a while loop.</para>
 +<para>&man.tip.1; will try each one in the listed order, then give up.  If
 +you want to keep retrying, run <command>tip</command> in a <command>while</command> loop.</para>
  
  </answer></qandaentry>
 
 /s/Udo
 

From: Ben Smithurst <ben@FreeBSD.org>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/20056: Bad SGML in the "@ sign" entry of the FAQ
Date: Fri, 21 Jul 2000 17:09:12 +0100

 Udo Erdelhoff wrote:
 
 > BTW: I've found another instance of the original problem: There's a <\@> a
 > few entries later. The patch replaces <\@> with &lt;\@&gt;
 > While I'm here :-)
 > - replace <ulink ...man.cgi>/etc/remote</ulink> with <filename>...
 
 I'll be axing all man.cgi unless anyone on -doc objects...
 
 > - replace <emphasis remap=tt>-Elements with <literal>-elements
 > - replace <literallayout>-elments with <programlisting>-elements
 > - remove the useless <para>-elements around the <programlisting>-elements;
 >   this change removes two tidy-warnings
 > - replace the first instance of <ulink..man.cgi>tip</ulink> with &man.tip.1;
 > - replace the second instace of this element with <command>tip</command>
 >   and add a command-element around the while of "in a while loop".
 
 A load of that will be fixed in my megapatch too.  Patience. :-)
 
 -- 
 Ben Smithurst                 / ben@FreeBSD.org / PGP: 0x99392F7D
 FreeBSD Documentation Project /
 
>Unformatted:
