Debian Bug report logs - #304242
manpages: hosts(5) wrong or confusing

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Ross Boylan <RossBoylan@stanfordalumni.org>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Cc: RossBoylan@stanfordalumni.org

Subject: manpages: hosts(5) wrong or confusing

Date: Mon, 11 Apr 2005 14:25:26 -0700

Package: manpages
Version: 1.70-1
Severity: normal

X-Debbugs-cc: srivasta@debian.org

The description of /etc/hosts says "The format of the host table is
described in RFC 952."  But that format is not at all close to the
format given in this man page.

3 possibilities occur to me:
1) My interpretation that RFC 952 was supposed to give the format of
this file is wrong.  If so, could the man page be clearer on that
point.
2) That RFC is not directly relevant.  The reference should be removed
or replaced.
3) The format of /etc/hosts is supposed to be that of RFC 952.  Then
the man page is quite off.

Also, the basic syntax description is incomplete.  Judging from the
examples, the aliases field is optional.  So it should be
IP_address canonical_hostname [aliases]

I also can't tell whether aliases should be separated by commas,
whitespace, etc.

I stumbled on this because I have an /etc/hosts with a single entry,
my non-fully qualified host name.  I'm trying to figure out whether
that's OK.  It seems not to be, under any interpretation....


-- System Information:
Debian Release: 3.1
  APT prefers testing
  APT policy: (990, 'testing'), (50, 'unstable')
Architecture: i386 (i686)
Kernel: Linux 2.4.27advncdfs
Locale: LANG=en_US, LC_CTYPE=en_US (charmap=ISO-8859-1)

-- no debconf information

Message #10 received at 304242@bugs.debian.org (full text, mbox, reply):

From: Martin Schulze <joey@infodrom.org>

To: Ross Boylan <RossBoylan@stanfordalumni.org>

Cc: Debian Bug Tracking System <304242@bugs.debian.org>, Michael Kerrisk <mtk-manpages@gmx.net>, Manoj Srivastava <srivasta@debian.org>

Subject: Re: Bug#304242: manpages: hosts(5) wrong or confusing

Date: Thu, 21 Apr 2005 20:42:29 +0200

[Message part 1 (text/plain, inline)]

Hi Michael,

I guess Ross is correct and this manpage should be adjusted.

Ross Boylan wrote:
> The description of /etc/hosts says "The format of the host table is
> described in RFC 952."  But that format is not at all close to the
> format given in this man page.
> 
> 3 possibilities occur to me:
> 1) My interpretation that RFC 952 was supposed to give the format of
> this file is wrong.  If so, could the man page be clearer on that
> point.
> 2) That RFC is not directly relevant.  The reference should be removed
> or replaced.
> 3) The format of /etc/hosts is supposed to be that of RFC 952.  Then
> the man page is quite off.

Agreed.  I'd move the note to the RFC to the history section.

> Also, the basic syntax description is incomplete.  Judging from the
> examples, the aliases field is optional.  So it should be
> IP_address canonical_hostname [aliases]

Ack.

> I also can't tell whether aliases should be separated by commas,
> whitespace, etc.

Agreed, it should probably look like

IP_address canonical_hostname [alias [alias [..]]]

See the attached patch.

In addition to that some of the sample addresses have changed, not
sure if you want to correct them in the manpage at all, but in case
you do, it's:

- 216.234.231.5   master.debian.org      master
- 205.230.163.103 www.opensource.org
+ 146.82.138.7    master.debian.org      master
+ 209.237.226.90  www.opensource.org

Regards,

	Joey

-- 
Testing? What's that? If it compiles, it is good, if it boots up, it is perfect.

Please always Cc to me when replying to me on the lists.

[x (text/plain, attachment)]

Message #15 received at 304242-close@bugs.debian.org (full text, mbox, reply):

From: Martin Schulze <joey@infodrom.org>

To: 304242-close@bugs.debian.org

Subject: Bug#304242: fixed in manpages 2.02-1

Date: Thu, 21 Apr 2005 15:49:02 -0400

Source: manpages
Source-Version: 2.02-1

We believe that the bug you reported is fixed in the latest version of
manpages, which is due to be installed in the Debian FTP archive:

manpages-dev_2.02-1_all.deb
  to pool/main/m/manpages/manpages-dev_2.02-1_all.deb
manpages_2.02-1.diff.gz
  to pool/main/m/manpages/manpages_2.02-1.diff.gz
manpages_2.02-1.dsc
  to pool/main/m/manpages/manpages_2.02-1.dsc
manpages_2.02-1_all.deb
  to pool/main/m/manpages/manpages_2.02-1_all.deb
manpages_2.02.orig.tar.gz
  to pool/main/m/manpages/manpages_2.02.orig.tar.gz



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 304242@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Martin Schulze <joey@infodrom.org> (supplier of updated manpages package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.7
Date: Thu, 21 Apr 2005 20:43:55 +0200
Source: manpages
Binary: manpages manpages-dev
Architecture: source all
Version: 2.02-1
Distribution: unstable
Urgency: low
Maintainer: Martin Schulze <joey@debian.org>
Changed-By: Martin Schulze <joey@infodrom.org>
Description: 
 manpages   - Manual pages about using a GNU/Linux system
 manpages-dev - Manual pages about using GNU/Linux for development
Closes: 278861 287917 300313 304242
Changes: 
 manpages (2.02-1) unstable; urgency=low
 .
   * New upstream release, incorporating
     - helpful example of URL macro usage to man(7) (closes: Bug#278861)
   * Adjusted the section of zdump(8) in references in tzselect(8) and
     zic(8) since Debian uses the libc-provided version which is in section
     1 and not in section 8 (closes: Bug#300313)
   * Applied patch by Justin Pryzby to fix english grammar in null(4)
     (closes: Bug#287917)
   * Corrected format in hosts(5) and moved the RFC reference to the
     historical note section (closes: Bug#304242)
Files: 
 4f9830438d1bc2daec7b71e9ac4e1818 584 doc - manpages_2.02-1.dsc
 632f596793ff5403539a671c86b528c1 1016987 doc - manpages_2.02.orig.tar.gz
 11fda66260b15247424395e646bc28df 46143 doc - manpages_2.02-1.diff.gz
 ab4b7e0146ffdbfaef5f5b753ade0346 392318 doc important manpages_2.02-1_all.deb
 4f3de745636b380602ba51d4a57b20d8 1084936 doc standard manpages-dev_2.02-1_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (GNU/Linux)

iD8DBQFCZ/WhW5ql+IAeqTIRAvDbAJ4ygQowGy2tCCUpgesq4AHJQo0MZgCgoxg9
XsiJhj24PHWEV2ebW3bP09Y=
=BuSw
-----END PGP SIGNATURE-----

Message #20 received at 304242@bugs.debian.org (full text, mbox, reply):

From: Ross Boylan <RossBoylan@stanfordalumni.org>

To: Martin Schulze <joey@infodrom.org>

Cc: Ross Boylan <RossBoylan@stanfordalumni.org>, Debian Bug Tracking System <304242@bugs.debian.org>, Michael Kerrisk <mtk-manpages@gmx.net>, Manoj Srivastava <srivasta@debian.org>

Subject: Re: Bug#304242: manpages: hosts(5) wrong or confusing

Date: Fri, 22 Apr 2005 00:49:55 -0700

Thanks.

One further change proposed below, and a further query.

On Thu, Apr 21, 2005 at 08:42:29PM +0200, Martin Schulze wrote:
....
> 
> See the attached patch.
> 
> Regards,
> 
> 	Joey
> 

> Index: man5/hosts.5
> ===================================================================
> RCS file: /var/cvs/debian/manpages/man5/hosts.5,v
> retrieving revision 1.6
> diff -u -p -r1.6 hosts.5
> --- man5/hosts.5	16 Oct 2004 13:05:19 -0000	1.6
> +++ man5/hosts.5	21 Apr 2005 18:39:31 -0000
> @@ -37,7 +37,7 @@ with hostnames, one line per IP address.
>  line should be present with the following information:
>  .RS
>  .PP
> -IP_address canonical_hostname aliases
> +IP_address canonical_hostname [alias [alias [..]]]
>  .RE
>  .PP
>  Fields of the entry are separated by any number of blanks and/or
> @@ -48,7 +48,6 @@ alphabetic character and end with an alp
>  Aliases provide for name changes, alternate spellings,
>  shorter hostnames, or generic hostnames (for example,
>  .IR localhost ).
> -The format of the host table is described in RFC 952. 
>  .PP
>  The Berkeley Internet Name Domain (BIND) Server implements the
>  Internet name server for UNIX systems. It augments or replaces the
> @@ -93,6 +92,8 @@ unknown hosts.  The NIC no longer mainta
>  though looking around at the time of writing (circa 2000), there are
>  historical hosts.txt files on the WWW. I just found three, from 92,
>  94, and 95.
> +
> +The format of the host table is originally described in RFC 952. 
How about this instead?
+RFC 952 gave the original format for the host table, though it has
+since changed.

That makes it clearer that RFC 952 does not describe the current
format of this file.

>  .SH FILES
>  .I /etc/hosts
>  .SH "SEE ALSO"

Also, if you could say anything about when changes to the file have an
effect, or what needs to be done to make them have an effect (e.g., on
the resolver, on DNS), that would be helpful.  I realize that
information may be application specific.

Message #25 received at 304242@bugs.debian.org (full text, mbox, reply):

From: Martin Schulze <joey@infodrom.org>

To: Ross Boylan <RossBoylan@stanfordalumni.org>, 304242@bugs.debian.org

Cc: Michael Kerrisk <mtk-manpages@gmx.net>

Subject: Re: Bug#304242: manpages: hosts(5) wrong or confusing

Date: Sun, 24 Apr 2005 18:54:23 +0200

Ross Boylan wrote:
> > +
> > +The format of the host table is originally described in RFC 952. 
> How about this instead?
> +RFC 952 gave the original format for the host table, though it has
> +since changed.
> 
> That makes it clearer that RFC 952 does not describe the current
> format of this file.

I have now:

diff -u -p -r1.7 hosts.5
--- man5/hosts.5	21 Apr 2005 18:43:40 -0000	1.7
+++ man5/hosts.5	24 Apr 2005 16:39:37 -0000
@@ -93,7 +93,8 @@ though looking around at the time of wri
 historical hosts.txt files on the WWW. I just found three, from 92,
 94, and 95.
 
-The format of the host table is originally described in RFC 952. 
+The format of the host table is originally described in RFC 952 and
+has been changed since then.
 .SH FILES
 .I /etc/hosts
 .SH "SEE ALSO"


> >  .SH FILES
> >  .I /etc/hosts
> >  .SH "SEE ALSO"
> 
> Also, if you could say anything about when changes to the file have an
> effect, or what needs to be done to make them have an effect (e.g., on
> the resolver, on DNS), that would be helpful.  I realize that
> information may be application specific.

Michael, what about the following note:

diff -u -p -r1.8 -r1.9
--- man5/hosts.5	24 Apr 2005 16:45:49 -0000	1.8
+++ man5/hosts.5	24 Apr 2005 16:53:04 -0000	1.9
@@ -82,6 +82,9 @@ advantage. 
  146.82.138.7    master.debian.org      master
  209.237.226.90  www.opensource.org
 .fi
+.SH NOTE
+Modifications in this file usually take effect immediately, except
+when a programs cache this file.
 .SH "HISTORICAL NOTE"
 Before the advent of DNS, the host table was the only way of resolving
 hostnames on the fledgling Internet. Indeed, this file could be

Regards,

	Joey

-- 
Everybody talks about it, but nobody does anything about it!  -- Mark Twain

Please always Cc to me when replying to me on the lists.

Message #30 received at 304242@bugs.debian.org (full text, mbox, reply):

From: "Michael Kerrisk" <mtk-manpages@gmx.net>

To: Martin Schulze <joey@infodrom.org>

Cc: RossBoylan@stanfordalumni.org,304242@bugs.debian.org,Manoj Srivastava <srivasta@debian.org>

Subject: Re: Bug#304242: manpages: hosts(5) wrong or confusing

Date: Wed, 11 May 2005 17:09:14 +0200 (MEST)

> Ross Boylan wrote:
> > > +
> > > +The format of the host table is originally described in RFC 952. 
> > How about this instead?
> > +RFC 952 gave the original format for the host table, though it has
> > +since changed.
> > 
> > That makes it clearer that RFC 952 does not describe the current
> > format of this file.
> 
> I have now:
> 
> diff -u -p -r1.7 hosts.5
> --- man5/hosts.5	21 Apr 2005 18:43:40 -0000	1.7
> +++ man5/hosts.5	24 Apr 2005 16:39:37 -0000
> @@ -93,7 +93,8 @@ though looking around at the time of wri
>  historical hosts.txt files on the WWW. I just found three, from 92,
>  94, and 95.
>  
> -The format of the host table is originally described in RFC 952. 
> +The format of the host table is originally described in RFC 952 and
> +has been changed since then.
>  .SH FILES
>  .I /etc/hosts
>  .SH "SEE ALSO"
> 
> 
> > >  .SH FILES
> > >  .I /etc/hosts
> > >  .SH "SEE ALSO"
> > 
> > Also, if you could say anything about when changes to the file have an
> > effect, or what needs to be done to make them have an effect (e.g., on
> > the resolver, on DNS), that would be helpful.  I realize that
> > information may be application specific.
> 
> Michael, what about the following note:
> 
> diff -u -p -r1.8 -r1.9
> --- man5/hosts.5	24 Apr 2005 16:45:49 -0000	1.8
> +++ man5/hosts.5	24 Apr 2005 16:53:04 -0000	1.9
> @@ -82,6 +82,9 @@ advantage. 
>   146.82.138.7    master.debian.org      master
>   209.237.226.90  www.opensource.org
>  .fi
> +.SH NOTE
> +Modifications in this file usually take effect immediately, except
> +when a programs cache this file.
>  .SH "HISTORICAL NOTE"
>  Before the advent of DNS, the host table was the only way of resolving
>  hostnames on the fledgling Internet. Indeed, this file could be
> 
> Regards,
> 
> 	Joey

Hi Joey,

I have committed the the patch below for man-pages-2.03.
I think that covers all the bits you submitted, though I've
changed your wordings slightly.  Please close.

Cheers,

Michael

--- hosts.5     (revision 116)
+++ hosts.5     (working copy)
@@ -37,7 +37,7 @@
 line should be present with the following information:
 .RS
 .PP
-IP_address canonical_hostname aliases
+IP_address canonical_hostname [aliases...]
 .RE
 .PP
 Fields of the entry are separated by any number of blanks and/or
@@ -45,10 +45,9 @@
 a comment, and is ignored.  Host names may contain only alphanumeric
 characters, minus signs ("-"), and periods (".").  They must begin with an
 alphabetic character and end with an alphanumeric character.
-Aliases provide for name changes, alternate spellings,
+Optional aliases provide for name changes, alternate spellings,
 shorter hostnames, or generic hostnames (for example,
 .IR localhost ).
-The format of the host table is described in RFC 952.
 .PP
 The Berkeley Internet Name Domain (BIND) Server implements the
 Internet name server for UNIX systems. It augments or replaces the
@@ -80,10 +79,16 @@
  127.0.0.1       localhost
  192.168.1.10    foo.mydomain.org      foo
  192.168.1.13    bar.mydomain.org      bar
- 216.234.231.5   master.debian.org      master
- 205.230.163.103 www.opensource.org
+ 146.82.138.7    master.debian.org      master
+ 209.237.226.90  www.opensource.org
 .fi
-.SH "HISTORICAL NOTE"
+.SH "NOTE"
+Modifications to this file normally take effect immediately,
+except in cases where the file is cached by applications.
+.SH "HISTORICAL NOTES"
+RFC 952 gave the original format for the host table, though it has
+since changed.
+
 Before the advent of DNS, the host table was the only way of resolving
 hostnames on the fledgling Internet. Indeed, this file could be
 created from the official host data base maintained at the Network


-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 

Want to help with man page maintenance?  Grab the
latest tarball
and grep the source files for 'FIXME'.

Please submit man page suggestions as "diff -u" patches
if possible.

Sign The Open Group "Developer Declaration of Independence"
http://www.opengroup.org/declaration/

+++ Lassen Sie Ihren Gedanken freien Lauf... z.B. per FreeSMS +++
GMX bietet bis zu 100 FreeSMS/Monat: http://www.gmx.net/de/go/mail

Send a report that this bug log contains spam.