conf/62772: static_routes needs an example in

[Simon L. Nielsen]

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

From: "Simon L. Nielsen" <simon at FreeBSD.org>
To: Jerry McAllister <jerrymc at clunix.cl.msu.edu>
Cc: kris at obsecurity.org, Alain Hoang <hoanga at alum.rpi.edu>,
	freebsd-gnats-submit at FreeBSD.org
Subject: Re: conf/62772: static_routes needs an example in
Date: Sat, 14 Feb 2004 14:36:45 +0100

 --y0ulUmNC+osPPQO6
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On 2004.02.13 10:45:31 -0500, Jerry McAllister wrote:
 > >=20
 > > The following reply was made to PR conf/62772; it has been noted by GNA=
 TS.
 > >=20
 > > From: Kris Kennaway <kris at obsecurity.org>
 > > To: hoanga at alum.rpi.edu
 > > Cc: kris at obsecurity.org, freebsd-gnats-submit at FreeBSD.org
 > > Subject: Re: conf/62772: static_routes needs an example in /etc/default=
 s/rc.conf
 > > Date: Fri, 13 Feb 2004 01:22:28 -0800
 > >=20
 > >  > Thanks for the quick response. I had read the documentation
 > >  > in the manpage as well and misinterpreted 'Set to the list of static
 > >  > routes'
 > >  > as 'please insert your static route here' rather than 'please
 > >  > put a list of identifiers that are space seperated that will be used=
  as
 > >  > a reference to route_ that containts all the options=20
 > >  > you need to feed to the route command to add the route'.
 > > =20
 > >  The second sentence says precisely that, although perhaps it can be
 > >  clarified..I don't think an example is needed here, but I'll leave it
 > >  up to the manpage people to decide.
 >=20
 > I have always been of the opinion that examples are always in order.
 > Language is a funny thing - especially English and can be misunderstood
 > regardless of how clear the writer thinks the text is.   An example
 > or two tends to clear away a lot of potential fog (for both the writer=20
 > and the reader) even in the simplest situation.   At least it can give=20
 > the reader - who is reading it because [s]he doesn't already know
 > the information - some comfort and that has value too.
 
 While I generally agree that examples are a very good thing, I don't
 think it's a good idea to put on in either defaults/rc.conf or the
 rc.conf(5) manual page, since both are already very big files.
 
 I think the best solution would be for someone to write a section about
 this for the Handbook (section '19.2 Gateways and Routes' seems the
 right place).  Any takes ? :-)
 
 --=20
 Simon L. Nielsen
 FreeBSD Documentation Team
 
 --y0ulUmNC+osPPQO6
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.3 (FreeBSD)
 
 iD8DBQFALiRmh9pcDSc1mlERAv6IAKCgZoizqdLRdgmMh4tUq6B1Khd/4wCeNeaA
 cb4PbYkBpvhUf277nyoDqL4=
 =pIQr
 -----END PGP SIGNATURE-----
 
 --y0ulUmNC+osPPQO6--