[RFC] iproute2: split up ip man page?

[RFC] iproute2: split up ip man page?

[Stephen Hemminger]

The current ip man page is both incomplete and so big that
the actual functions get lost easily.

I propose splitting the the pages for the subfunction
into sub pages. The man command appears
to be smart enough to handle:
  man tc htb

and pickup the manpage for /usr/share/man/man1/tc-htb.8.gz
Why not do the same thing for ip command?

The base ip page would just be a place holder that covered the
generic arguments.

Re: [RFC] iproute2: split up ip man page?

[Ben Hutchings]

On Wed, 2011-12-07 at 13:15 -0800, Stephen Hemminger wrote:
> The current ip man page is both incomplete and so big that
> the actual functions get lost easily.
> 
> I propose splitting the the pages for the subfunction
> into sub pages. The man command appears
> to be smart enough to handle:
>   man tc htb

Or, for another familiar example, 'man git diff'.

Oddly enough, man(1) only describes this under the '--no-subpages'
option which turns off the behaviour.

> and pickup the manpage for /usr/share/man/man1/tc-htb.8.gz
> Why not do the same thing for ip command?
> 
> The base ip page would just be a place holder that covered the
> generic arguments.

Sounds like a very sensible change.

Ben.

-- 
Ben Hutchings, Staff Engineer, Solarflare
Not speaking for my employer; that's the marketing department's job.
They asked us to note that Solarflare product names are trademarked.

Re: [RFC] iproute2: split up ip man page?

[Petr Šabata]

[-- Attachment #1: Type: text/plain, Size: 562 bytes --]

On Wed, Dec 07, 2011 at 01:15:14PM -0800, Stephen Hemminger wrote:
> The current ip man page is both incomplete and so big that
> the actual functions get lost easily.

I totally agree.

> I propose splitting the the pages for the subfunction
> into sub pages. The man command appears
> to be smart enough to handle:
>   man tc htb
> 
> and pickup the manpage for /usr/share/man/man1/tc-htb.8.gz
> Why not do the same thing for ip command?
> 
> The base ip page would just be a place holder that covered the
> generic arguments.

+1

-- Petr

[-- Attachment #2: Type: application/pgp-signature, Size: 230 bytes --]

Re: [RFC] iproute2: split up ip man page?

[Stephen Hemminger]

On Wed, 7 Dec 2011 13:15:14 -0800
Stephen Hemminger <shemminger@vyatta.com> wrote:

> The current ip man page is both incomplete and so big that
> the actual functions get lost easily.
> 
> I propose splitting the the pages for the subfunction
> into sub pages. The man command appears
> to be smart enough to handle:
>   man tc htb
> 
> and pickup the manpage for /usr/share/man/man1/tc-htb.8.gz
> Why not do the same thing for ip command?
> 
> The base ip page would just be a place holder that covered the
> generic arguments.
> 
> 
> --
> To unsubscribe from this list: send the line "unsubscribe netdev" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Ok, the ip man page is now broken up. I tried to fix some of the
incorrect grammar and usage as well. The pages still need editing for
readability.

Added a few examples as well.

Please download from the git repository and send me any comments
or changes.

   git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git

Re: [RFC] iproute2: split up ip man page?

[Hagen Paul Pfeifer]

* Stephen Hemminger | 2011-12-22 10:37:23 [-0800]:

>Ok, the ip man page is now broken up. I tried to fix some of the
>incorrect grammar and usage as well. The pages still need editing for
>readability.

Great! Commit 1b1177ed5f3 synched kernel headers. Should I rebase my iproute
netem rate patch (and again update include/linux/pkt_sched.h for net-next) or
keep you aware of this?

Hagen

Re: [RFC] iproute2: split up ip man page?

[Stephen Hemminger]

On Fri, 23 Dec 2011 01:10:03 +0100
Hagen Paul Pfeifer <hagen@jauu.net> wrote:

> * Stephen Hemminger | 2011-12-22 10:37:23 [-0800]:
> 
> >Ok, the ip man page is now broken up. I tried to fix some of the
> >incorrect grammar and usage as well. The pages still need editing for
> >readability.
> 
> Great! Commit 1b1177ed5f3 synched kernel headers. Should I rebase my iproute
> netem rate patch (and again update include/linux/pkt_sched.h for net-next) or
> keep you aware of this?
> 
> Hagen

I am fixing netem loss stuff now. Fixing broken gimodel.
After 3.2 is released, the will merge in support for 3.3 features.

Re: [RFC] iproute2: split up ip man page?

[Hagen Paul Pfeifer]

* Stephen Hemminger | 2011-12-22 16:29:59 [-0800]:

>I am fixing netem loss stuff now. Fixing broken gimodel.

Great news, I have some pending patches for the gimodel too.

Hagen