networks.5 man page

networks.5 man page

[Michael Kerrisk]

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 <joey-1lCxjdRlhQ9g9hUCZPvPmw@public.gmane.org>
.\"
.\" 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: networks.5 man page

[Martin Schulze]

Michael Kerrisk wrote:
> 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?

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: networks.5 man page

[Michael Kerrisk]

On Tue, Sep 2, 2008 at 4:56 AM, Martin Schulze <joey-1lCxjdRlhQ9g9hUCZPvPmw@public.gmane.org> wrote:
> Michael Kerrisk wrote:
>> 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?
>
> Great!  I'd appreciate this!

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: networks.5 man page

[Michael Kerrisk]

On Tue, Sep 2, 2008 at 2:04 PM, Michael Kerrisk
<mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org> wrote:
> On Tue, Sep 2, 2008 at 4:56 AM, Martin Schulze <joey-1lCxjdRlhQ9g9hUCZPvPmw@public.gmane.org> wrote:
>> Michael Kerrisk wrote:
>>> 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?
>>
>> Great!  I'd appreciate this!
>
> 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?
> ]]

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

--- networks.5.orig     2008-09-04 15:52:03.000000000 +0200
+++ networks.5  2008-09-04 15:51:13.000000000 +0200
@@ -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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: networks.5 man page

[Martin Schulze]

Michael Kerrisk wrote:
> On Tue, Sep 2, 2008 at 2:04 PM, Michael Kerrisk
> <mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org> wrote:
> > On Tue, Sep 2, 2008 at 4:56 AM, Martin Schulze <joey-1lCxjdRlhQ9g9hUCZPvPmw@public.gmane.org> wrote:
> >> Michael Kerrisk wrote:
> >>> 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?
> >>
> >> Great!  I'd appreciate this!
> >
> > 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?
> > ]]

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

> 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.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html