Hi again Michael, Pavel, Eric and mailing list
(Cc: to Eric, Pavel and Linux Netdev List on behalf of Michael asking for
comment)
Here's the revised veth(4) man page (the inline replies to Michael's
critique are following the man page):
********************************************************************
.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@xxxxxxxxxxxxx),
.\" Fri, 03 Nov 2012 22:35:33 +0100
.\"
.\" 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., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\"
.TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
.SH NAME
veth \- Virtual Ethernet Device
.SH DESCRIPTION
The
.B veth
devices are virtual Ethernet devices.
They can act as tunnels between network namespaces to create
a bridge to a physical network device in another namespace, but
can also be used as standalone network devices.
Because of their original purpose for tunneling
.B veth
devices are always created in pairs, that are
interconnected with each other.
When one
.B veth
end receives a packet it appears on its pair and vice versa.
.B Veth
devices can be manipulated with the
.BR ip (8)
tool.
See
.I "ip link help"
for more information.
.SH NOTES
This page is based on Pavel Emelianov's veth driver submission to
the LKML and on the
.BR clone (8)
manpage.
.SH "SEE ALSO"
.BR clone (2),
.BR ip (8)
********************************************************************
On Sat, 3 Nov 2012, Michael Kerrisk (man-pages) wrote:
On Fri, Nov 2, 2012 at 2:25 PM, Tomas Pospisek <tpo@xxxxxxxxxxxxx> wrote:
[...]
You can find the manpage below
See comments. After revising, could you resubmit, and and Eric
Biederman and Pavel Emelianov to CC, asking them for comment. Maybe
also CC linux-kernel.
Also, do you have a pointer to "Pavel Emelianov's veth driver
submission to the LKML"? I couldn't find it. It would be at least
handy to have a URL for archived mail in the changelog for this man
page.
Apparently that was to the Linux Netdev List. So I've Cc'ed it instead of
LKML.
http://lwn.net/Articles/237688/
http://lwn.net/Articles/241883/
.TH veth 4 2012-11-02 "Linux" "Linux Programmer's Manual"
.SH NAME
veth \- Virtual Ethernet Device
.SH DESCRIPTION
The \fBveth*\fP devices are virtual ethernet devices.
Ethernet
They can act as tunnels between network namespaces to create
a bridge to a physical network device in another namespace, but
can also be used as standalone network devices.
Because of their original purpose for tunneling \fBveth\fP devices
I somewhat prefer the use of the line formatting directives, thus
.B veth
are allways created in pairs, that are interconnected with
always
each other. When one \fBveth\fP end receives a packet it
I prefer new sentences to start on new source lines (See man-pages(7).)
appears on its pair and vice versa.
\fBVeth\fP devices can be manipulated with the
.BR ip (8)
tool. See \fB ip link help\fP for more information.
See
.I "ip link help"
for more information.
.SH "SEE ALSO"
.BR ip (8) ,
.BR clone (2)
Reverse the order of those two lines.
.SH COLOPHON
The COLOPHON is autogenerated by scripts. No need to add it, [...]
The above manpage should have incorporated all your critique to this
point.
[...] and we
don't really need the next sentence in the man-page itself, thought it
will be useful for the changelog.
This page is based on Pavel Emelianov's veth driver submission to
the LKML and on the .BR clone (8)
manpage.
The reason I've included this - and I've moved it to the "NOTES" section
above - is that I feel extremely uncomfortable evoking the impression the
man page would be my work. I don't want to deny responsability for what
I've submitted to the mailing list - the faults are of course mine. But
99% of the sentences from the veth(4) manpage are copy/paste from Pavel's
email or the clone man page.
Certainly I won't insist on the NOTES section and rip it out or move it
to the comments on your request.
Thanks a lot for your consideration of the manpage submission,
*t
