networks.5 man page

Hi Joey,

I see that Debian downstream has a networks(5) page (below) that you wrote some years back (before my time as maintainer). It seems to me that it might make sense to take this page upstream. What do you think?

Cheers,

Michael

PS The FreeBSD networks(5) page has some details not in your page
http://www.freebsd.org/cgi/man.cgi?query=networks&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=html
Perhaps some of those details might also be usefully covered in your page?

.\" Copyright (c) 2001 Martin Schulze <[email protected]> .\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.TH NETWORKS 5 2001-12-22 "GNU/Linux" "Linux System Administration" .SH NAME
networks \- network name information
.SH DESCRIPTION
The file
.I /etc/networks
is a plain ASCII file that describes known DARPA networks and symbolic names for these networks.
Each line represents a network and has the following structure:

.RS
.I name number aliases ...
.RE

where the fields are delimited by spaces or tabs.
Empty lines are ignored.
If a line contains a hash mark (#), the hash mark and the remaining part of the line are ignored.

The field descriptions are:

.TP
.I name
The symbolic name for the network.
.TP
.I number
The official number for this network in dotted-decimal notation. The trailing ".0" may be omitted.
.TP
.I aliases
Optional aliases for the network.
.LP

This file is read by
.B route
or
.B netstat
utilities.
Only Class A, B or C networks are supported, partitioned networks (i.e. network/26 or network/28) are not supported by this facility. .SH FILES
.TP
.I /etc/networks
The networks definition file.
.SH "SEE ALSO"
.BR getnetbyaddr (3),
.BR getnetbyname (3),
.BR getnetent (3),
.BR route (8),
.BR netstat (8)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Great! I'd appreciate this!

Regards,

Joey

Beware of bugs in the above code; I have only proved it correct,
not tried it.  -- Donald E. Knuth

Please always Cc to me when replying to me on the lists.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

And your thoughts on this piece?

[[
PS The FreeBSD networks(5) page has some details not in your page
http://www.freebsd.org/cgi/man.cgi?query=networks&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=html
Perhaps some of those details might also be usefully covered in your page?
]]

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Joey,

After reviewing the FreeBSD page, and doing a little testing, I made a few edits to the Debian downstream networks(5) page and have included it for man-pages-3.09.

Could you please review the diff below? The most notable change is the substitution of "dotted-decimal" by "numbers-and-dots" notation, since getnetent(3) etc. do indeed accept that more general form, according to my tests.

Cheers,

Michael

@@ -19,8 +19,9 @@
 .\" License along with this manual; if not, write to the Free
 .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
 .\" USA.
+.\" 2008-09-04, mtk, taken from Debian downstream, with a few light edits
 .\"
-.TH NETWORKS 5 2001-12-22 "GNU/Linux" "Linux System Administration"
+.TH NETWORKS 5 2008-09-04 "GNU/Linux" "Linux System Administration"
 .SH NAME
 networks \- network name information
 .SH DESCRIPTION

@@ -36,27 +37,32 @@
 
 where the fields are delimited by spaces or tabs.
 Empty lines are ignored.
-If a line contains a hash mark (#), the hash mark and the remaining
-part of the line are ignored.
+The hash character (\fB#\fP) indicates the start of a comment:
+this character, and the remaining characters up to
+the end of the current line,
+are ignored by library functions that process the file.
 
 The field descriptions are:
 
 .TP
 .I name
 The symbolic name for the network.
+Network names can contain any printable characters execept
+white-space characters or the comment character.
 .TP
 .I number
-The official number for this network in dotted-decimal notation.
-The trailing ".0" may be omitted.
+The official number for this network in numbers-and-dots notation (see
+.BR inet (3)).
+The trailing ".0" (for the host component of the network address) may

be omitted.
.TP
.I aliases
Optional aliases for the network.
.LP

-This file is read by
-.B route
-or
-.B netstat
+This file is read by the
+.BR route (8)
+and
+.BR netstat (8)
utilities.
Only Class A, B or C networks are supported, partitioned networks (i.e. network/26 or network/28) are not supported by this facility.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

I'd appreciate if you could merge both contents. I'm happy if manpages contain comprehensive information about the subjects they ought to describe.

Yes, that's fine with me.

I'm sorry that I had postponed the response and only remembered it yesterday night again. Thankfully, it didn't stall the process and you were able to continue work nevertheless.

Regards,

Joey

Beware of bugs in the above code; I have only proved it correct,
not tried it.  -- Donald E. Knuth
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html