Bug 26293

Summary:	Just add detail on the tutorial
Product:	Documentation	Reporter:	jrcharron <jrcharron>
Component:	Books & Articles	Assignee:	dd <dd>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description jrcharron 2001-04-02 15:50:01 UTC

On this web page http://www.freebsd.org/handbook/pppoe.html. 

I try to configure the pppoe on my computer..And after 1 hours, I discover 
my problem. When you create the file /etc/ppp/ppp.conf you need to put
at least 1 space after the name of the provider in the configuration 
parameter for this provider to have a working script.

Example: ( Default and set are not in the same column. This is the good way)
    default: # or name_of_service_provider
      set device PPPoE:xl1 # replace xl1 with your ethernet device
      set mru 1492
      set mtu 1492
      set authname YOURLOGINNAME



Please put this information on the handbook.

Other think, on my Freebsd4.2, by default in the /etc/default/rc.conf 
nat is activated, ppp_nat="YES" so you don't need to add  
nat enable yes # if you want to enable nat for your local net
on your /etc/ppp/ppp.conf


Thanks
Jean-Richard Charron

Comment 1 dima 2001-04-03 02:43:07 UTC

[ cc'd to brain, the ppp maintainer ]

jrcharron@gen-int.com writes:
> 
> >Number:         26293
> >Category:       docs
> >Synopsis:       Just add detail on the tutorial
>
> I try to configure the pppoe on my computer..And after 1 hours, I discover 
> my problem. When you create the file /etc/ppp/ppp.conf you need to put
> at least 1 space after the name of the provider in the configuration 
> parameter for this provider to have a working script.
> 
> Example: ( Default and set are not in the same column. This is the good way)
>     default: # or name_of_service_provider
>       set device PPPoE:xl1 # replace xl1 with your ethernet device
>       set mru 1492
>       set mtu 1492
>       set authname YOURLOGINNAME

Brain, can you confirm that this is indeed the intended behavior, and
not a bug?  If that's the case, I'll update the docs to mention this
(unless you want to do it).

Thanks,

					Dima Dorfman
					dima@unixfreak.org

Comment 2 Brian Somers 2001-04-03 03:10:15 UTC

> [ cc'd to brain, the ppp maintainer ]
> 
> jrcharron@gen-int.com writes:
> > 
> > >Number:         26293
> > >Category:       docs
> > >Synopsis:       Just add detail on the tutorial
> >
> > I try to configure the pppoe on my computer..And after 1 hours, I discover 
> > my problem. When you create the file /etc/ppp/ppp.conf you need to put
> > at least 1 space after the name of the provider in the configuration 
> > parameter for this provider to have a working script.
> > 
> > Example: ( Default and set are not in the same column. This is the good way)
> >     default: # or name_of_service_provider
> >       set device PPPoE:xl1 # replace xl1 with your ethernet device
> >       set mru 1492
> >       set mtu 1492
> >       set authname YOURLOGINNAME
> 
> Brain, can you confirm that this is indeed the intended behavior, and
> not a bug?  If that's the case, I'll update the docs to mention this
> (unless you want to do it).

Yes, all lines that are not labels should be indented by at least one 
space or tab.  This is documented, but now that I look through the 
docs, it seems it's not very clear (it's surprising what you can take 
for granted!!!).

Fire away if you want to clarify things.

> Thanks,
> 
> 					Dima Dorfman
> 					dima@unixfreak.org

Cheers.
-- 
Brian <brian@Awfulhak.org>                        <brian@[uk.]FreeBSD.org>
      <http://www.Awfulhak.org>                   <brian@[uk.]OpenBSD.org>
Don't _EVER_ lose your sense of humour !

Comment 3 dima 2001-04-04 02:02:19 UTC

Brian Somers <brian@Awfulhak.org> writes:
> > jrcharron@gen-int.com writes:
> > > [ commands must be indented in ppp.conf ]
> > 
> > Brain, can you confirm that this is indeed the intended behavior, and
> > not a bug?  If that's the case, I'll update the docs to mention this
> > (unless you want to do it).
> 
> Yes, all lines that are not labels should be indented by at least one 
> space or tab.  This is documented, but now that I look through the 
> docs, it seems it's not very clear (it's surprising what you can take 
> for granted!!!).

I think it's pretty clear where it's mentioned, but it's not mentioned
in share/examples/ppp.conf.sample, or the PPP Primer, which is
probably what most people read.  Below are patches to those two.  I'd
appreciate if you'd check them to make sure they're not spreading
misinformation (I don't use ppp on a daily basis).

Thanks,

					Dima Dorfman
					dima@unixfreak.org


Index: ppp.conf.sample
===================================================================
RCS file: /st/src/FreeBSD/src/share/examples/ppp/ppp.conf.sample,v
retrieving revision 1.22
diff -u -r1.22 ppp.conf.sample
--- ppp.conf.sample	2000/12/01 11:52:22	1.22
+++ ppp.conf.sample	2001/04/04 00:58:15
@@ -11,7 +11,8 @@
 # This file is separated into sections.  Each section is named with
 # a label starting in column 0 and followed directly by a ``:''.  The
 # section continues until the next section.  Blank lines and lines
-# beginning with ``#'' are ignored.
+# beginning with ``#'' are ignored.  All commands inside sections *must*
+# be indented by at least one space or tab or they will not be recognized!
 #
 # Lines beginning with "!include" will ``include'' another file.  You
 # may want to ``!include ~/.ppp.conf'' for backwards compatibility.

Index: book.sgml
===================================================================
RCS file: /st/src/FreeBSD/doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v
retrieving revision 1.6
diff -u -r1.6 book.sgml
--- book.sgml	2001/01/17 07:22:10	1.6
+++ book.sgml	2001/04/04 00:58:29
@@ -772,6 +772,15 @@
   
 <para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a
 dial-out Internet gateway for our example LAN:
+
+<note>
+  <para>The full syntax for <filename>ppp.conf</filename> is described in
+    &man.ppp.8;.  Particuarly, note that any line that isn't a label that
+    ends with a colon (e.g., <literal>default:</literal>,
+    <literal>interactive:</literal>) or a comment <emphasis>must</emphasis>
+    be indented!</para>
+</note>
+
 <programlisting>
 ################################################################
 # PPP Configuration File ('/etc/ppp/ppp.conf')

Comment 4 dima 2001-04-04 02:19:03 UTC

Brian Somers <brian@Awfulhak.org> writes:
> Hi,
> 
> Yes, these changes look good.  The only caveat I'd mention is that 
> the ``!include'' can appear without indents inside a section, but I 
> think that's reasonably clear anyway....

Can it appear *with* indents, though?  I don't want to screw people
over trying to use that.  If it can appear either way, then it's
probably not worth mentioning it (bloat).  If it must appear without
indents, a small notice somewhere may be in order so we people don't
pull their hair out because of that..

Thanks,

					Dima Dorfman
					dima@unixfreak.org


> 
> Cheers.
> 
> > Brian Somers <brian@Awfulhak.org> writes:
> > > > jrcharron@gen-int.com writes:
> > > > > [ commands must be indented in ppp.conf ]
> > > > 
> > > > Brain, can you confirm that this is indeed the intended behavior, and
> > > > not a bug?  If that's the case, I'll update the docs to mention this
> > > > (unless you want to do it).
> > > 
> > > Yes, all lines that are not labels should be indented by at least one 
> > > space or tab.  This is documented, but now that I look through the 
> > > docs, it seems it's not very clear (it's surprising what you can take 
> > > for granted!!!).
> > 
> > I think it's pretty clear where it's mentioned, but it's not mentioned
> > in share/examples/ppp.conf.sample, or the PPP Primer, which is
> > probably what most people read.  Below are patches to those two.  I'd
> > appreciate if you'd check them to make sure they're not spreading
> > misinformation (I don't use ppp on a daily basis).
> > 
> > Thanks,
> > 
> > 					Dima Dorfman
> > 					dima@unixfreak.org
> > 
> > 
> > Index: ppp.conf.sample
> > ===================================================================
> > RCS file: /st/src/FreeBSD/src/share/examples/ppp/ppp.conf.sample,v
> > retrieving revision 1.22
> > diff -u -r1.22 ppp.conf.sample
> > --- ppp.conf.sample	2000/12/01 11:52:22	1.22
> > +++ ppp.conf.sample	2001/04/04 00:58:15
> > @@ -11,7 +11,8 @@
> >  # This file is separated into sections.  Each section is named with
> >  # a label starting in column 0 and followed directly by a ``:''.  The
> >  # section continues until the next section.  Blank lines and lines
> > -# beginning with ``#'' are ignored.
> > +# beginning with ``#'' are ignored.  All commands inside sections *must*
> > +# be indented by at least one space or tab or they will not be recognized!
> >  #
> >  # Lines beginning with "!include" will ``include'' another file.  You
> >  # may want to ``!include ~/.ppp.conf'' for backwards compatibility.
> > 
> > Index: book.sgml
> > ===================================================================
> > RCS file: /st/src/FreeBSD/doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v
> > retrieving revision 1.6
> > diff -u -r1.6 book.sgml
> > --- book.sgml	2001/01/17 07:22:10	1.6
> > +++ book.sgml	2001/04/04 00:58:29
> > @@ -772,6 +772,15 @@
> >    
> >  <para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a
> >  dial-out Internet gateway for our example LAN:
> > +
> > +<note>
> > +  <para>The full syntax for <filename>ppp.conf</filename> is described in
> > +    &man.ppp.8;.  Particuarly, note that any line that isn't a label that
> > +    ends with a colon (e.g., <literal>default:</literal>,
> > +    <literal>interactive:</literal>) or a comment <emphasis>must</emphasis
> >
> > +    be indented!</para>
> > +</note>
> > +
> >  <programlisting>
> >  ################################################################
> >  # PPP Configuration File ('/etc/ppp/ppp.conf')
> > 
> 
> -- 
> Brian <brian@Awfulhak.org>                        <brian@[uk.]FreeBSD.org>
>       <http://www.Awfulhak.org>                   <brian@[uk.]OpenBSD.org>
> Don't _EVER_ lose your sense of humour !
> 
>

Comment 5 Brian Somers 2001-04-04 02:19:20 UTC

Hi,

Yes, these changes look good.  The only caveat I'd mention is that 
the ``!include'' can appear without indents inside a section, but I 
think that's reasonably clear anyway....

Cheers.

> Brian Somers <brian@Awfulhak.org> writes:
> > > jrcharron@gen-int.com writes:
> > > > [ commands must be indented in ppp.conf ]
> > > 
> > > Brain, can you confirm that this is indeed the intended behavior, and
> > > not a bug?  If that's the case, I'll update the docs to mention this
> > > (unless you want to do it).
> > 
> > Yes, all lines that are not labels should be indented by at least one 
> > space or tab.  This is documented, but now that I look through the 
> > docs, it seems it's not very clear (it's surprising what you can take 
> > for granted!!!).
> 
> I think it's pretty clear where it's mentioned, but it's not mentioned
> in share/examples/ppp.conf.sample, or the PPP Primer, which is
> probably what most people read.  Below are patches to those two.  I'd
> appreciate if you'd check them to make sure they're not spreading
> misinformation (I don't use ppp on a daily basis).
> 
> Thanks,
> 
> 					Dima Dorfman
> 					dima@unixfreak.org
> 
> 
> Index: ppp.conf.sample
> ===================================================================
> RCS file: /st/src/FreeBSD/src/share/examples/ppp/ppp.conf.sample,v
> retrieving revision 1.22
> diff -u -r1.22 ppp.conf.sample
> --- ppp.conf.sample	2000/12/01 11:52:22	1.22
> +++ ppp.conf.sample	2001/04/04 00:58:15
> @@ -11,7 +11,8 @@
>  # This file is separated into sections.  Each section is named with
>  # a label starting in column 0 and followed directly by a ``:''.  The
>  # section continues until the next section.  Blank lines and lines
> -# beginning with ``#'' are ignored.
> +# beginning with ``#'' are ignored.  All commands inside sections *must*
> +# be indented by at least one space or tab or they will not be recognized!
>  #
>  # Lines beginning with "!include" will ``include'' another file.  You
>  # may want to ``!include ~/.ppp.conf'' for backwards compatibility.
> 
> Index: book.sgml
> ===================================================================
> RCS file: /st/src/FreeBSD/doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v
> retrieving revision 1.6
> diff -u -r1.6 book.sgml
> --- book.sgml	2001/01/17 07:22:10	1.6
> +++ book.sgml	2001/04/04 00:58:29
> @@ -772,6 +772,15 @@
>    
>  <para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a
>  dial-out Internet gateway for our example LAN:
> +
> +<note>
> +  <para>The full syntax for <filename>ppp.conf</filename> is described in
> +    &man.ppp.8;.  Particuarly, note that any line that isn't a label that
> +    ends with a colon (e.g., <literal>default:</literal>,
> +    <literal>interactive:</literal>) or a comment <emphasis>must</emphasis>
> +    be indented!</para>
> +</note>
> +
>  <programlisting>
>  ################################################################
>  # PPP Configuration File ('/etc/ppp/ppp.conf')
> 

-- 
Brian <brian@Awfulhak.org>                        <brian@[uk.]FreeBSD.org>
      <http://www.Awfulhak.org>                   <brian@[uk.]OpenBSD.org>
Don't _EVER_ lose your sense of humour !

Comment 6 Brian Somers 2001-04-04 02:28:12 UTC

> Brian Somers <brian@Awfulhak.org> writes:
> > Hi,
> > 
> > Yes, these changes look good.  The only caveat I'd mention is that 
> > the ``!include'' can appear without indents inside a section, but I 
> > think that's reasonably clear anyway....
> 
> Can it appear *with* indents, though?  I don't want to screw people
> over trying to use that.  If it can appear either way, then it's
> probably not worth mentioning it (bloat).  If it must appear without
> indents, a small notice somewhere may be in order so we people don't
> pull their hair out because of that..

!include isn't allowed with indents :-/

> Thanks,
> 
> 					Dima Dorfman
> 					dima@unixfreak.org

-- 
Brian <brian@Awfulhak.org>                        <brian@[uk.]FreeBSD.org>
      <http://www.Awfulhak.org>                   <brian@[uk.]OpenBSD.org>
Don't _EVER_ lose your sense of humour !

Comment 7 dima 2001-04-04 02:38:24 UTC

Brian Somers <brian@Awfulhak.org> writes:
> > Can [!include] appear *with* indents, though?  I don't want to screw people
> > over trying to use that.  If it can appear either way, then it's
> > probably not worth mentioning it (bloat).  If it must appear without
> > indents, a small notice somewhere may be in order so we people don't
> > pull their hair out because of that..
> 
> !include isn't allowed with indents :-/

Okay.  Here's an updated patch.  I've tried to make them as
unintrusive as possible, but even if it is a little confusing it'll at
least make the person pay attention to indentation (and give them
something to read/research if they can't figure out why it doesn't
work).

Regards,

					Dima Dorfman
					dima@unixfreak.org


Index: ppp.conf.sample
===================================================================
RCS file: /st/src/FreeBSD/src/share/examples/ppp/ppp.conf.sample,v
retrieving revision 1.22
diff -u -r1.22 ppp.conf.sample
--- ppp.conf.sample	2000/12/01 11:52:22	1.22
+++ ppp.conf.sample	2001/04/04 01:35:18
@@ -11,7 +11,9 @@
 # This file is separated into sections.  Each section is named with
 # a label starting in column 0 and followed directly by a ``:''.  The
 # section continues until the next section.  Blank lines and lines
-# beginning with ``#'' are ignored.
+# beginning with ``#'' are ignored.  All commands inside sections that do
+# not begin with ``!'' (e.g., ``!include'') *must* be indented by at least
+# one space or tab or they will not be recognized!
 #
 # Lines beginning with "!include" will ``include'' another file.  You
 # may want to ``!include ~/.ppp.conf'' for backwards compatibility.

Index: book.sgml
===================================================================
RCS file: /st/src/FreeBSD/doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v
retrieving revision 1.6
diff -u -r1.6 book.sgml
--- book.sgml	2001/01/17 07:22:10	1.6
+++ book.sgml	2001/04/04 01:35:30
@@ -772,6 +772,16 @@
   
 <para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a
 dial-out Internet gateway for our example LAN:
+
+<note>
+  <para>The full syntax for <filename>ppp.conf</filename> is described in
+    &man.ppp.8;.  Particuarly, note that any line that isn't a label that
+    ends with a colon (e.g., <literal>default:</literal>,
+    <literal>interactive:</literal>), a command that begins with
+    <quote>!</quote> (e.g., <literal>!include</literal>), or a comment
+    <emphasis>must</emphasis> be indented!</para>
+</note>
+
 <programlisting>
 ################################################################
 # PPP Configuration File ('/etc/ppp/ppp.conf')

Comment 8 Brian Somers 2001-04-04 08:18:56 UTC

Yep - this looks perfect.

> Brian Somers <brian@Awfulhak.org> writes:
> > > Can [!include] appear *with* indents, though?  I don't want to screw people
> > > over trying to use that.  If it can appear either way, then it's
> > > probably not worth mentioning it (bloat).  If it must appear without
> > > indents, a small notice somewhere may be in order so we people don't
> > > pull their hair out because of that..
> > 
> > !include isn't allowed with indents :-/
> 
> Okay.  Here's an updated patch.  I've tried to make them as
> unintrusive as possible, but even if it is a little confusing it'll at
> least make the person pay attention to indentation (and give them
> something to read/research if they can't figure out why it doesn't
> work).
> 
> Regards,
> 
> 					Dima Dorfman
> 					dima@unixfreak.org
> 
> 
> Index: ppp.conf.sample
> ===================================================================
> RCS file: /st/src/FreeBSD/src/share/examples/ppp/ppp.conf.sample,v
> retrieving revision 1.22
> diff -u -r1.22 ppp.conf.sample
> --- ppp.conf.sample	2000/12/01 11:52:22	1.22
> +++ ppp.conf.sample	2001/04/04 01:35:18
> @@ -11,7 +11,9 @@
>  # This file is separated into sections.  Each section is named with
>  # a label starting in column 0 and followed directly by a ``:''.  The
>  # section continues until the next section.  Blank lines and lines
> -# beginning with ``#'' are ignored.
> +# beginning with ``#'' are ignored.  All commands inside sections that do
> +# not begin with ``!'' (e.g., ``!include'') *must* be indented by at least
> +# one space or tab or they will not be recognized!
>  #
>  # Lines beginning with "!include" will ``include'' another file.  You
>  # may want to ``!include ~/.ppp.conf'' for backwards compatibility.
> 
> Index: book.sgml
> ===================================================================
> RCS file: /st/src/FreeBSD/doc/en_US.ISO_8859-1/books/ppp-primer/book.sgml,v
> retrieving revision 1.6
> diff -u -r1.6 book.sgml
> --- book.sgml	2001/01/17 07:22:10	1.6
> +++ book.sgml	2001/04/04 01:35:30
> @@ -772,6 +772,16 @@
>    
>  <para>Below is the /etc/ppp/ppp.conf file that we'll be using to provide a
>  dial-out Internet gateway for our example LAN:
> +
> +<note>
> +  <para>The full syntax for <filename>ppp.conf</filename> is described in
> +    &man.ppp.8;.  Particuarly, note that any line that isn't a label that
> +    ends with a colon (e.g., <literal>default:</literal>,
> +    <literal>interactive:</literal>), a command that begins with
> +    <quote>!</quote> (e.g., <literal>!include</literal>), or a comment
> +    <emphasis>must</emphasis> be indented!</para>
> +</note>
> +
>  <programlisting>
>  ################################################################
>  # PPP Configuration File ('/etc/ppp/ppp.conf')

Cheers.

-- 
Brian <brian@Awfulhak.org>                        <brian@[uk.]FreeBSD.org>
      <http://www.Awfulhak.org>                   <brian@[uk.]OpenBSD.org>
Don't _EVER_ lose your sense of humour !

Comment 9 dd freebsd_committer

2001-04-05 02:44:37 UTC

State Changed
From-To: open->suspended

Note added to PPP primer and share/examples/ppp/ppp.conf.sample; the 
latter will be MFC'd after the code freeze.

Comment 10 dd freebsd_committer

2001-04-05 02:44:37 UTC

Responsible Changed
From-To: freebsd-doc->dd

My MFC reminder for ppp.conf.sample

Comment 11 dd freebsd_committer

2001-04-26 03:20:27 UTC

State Changed
From-To: suspended->closed

MFC'd.