Re: [iproute PATCH] ss: add detail explains of -m, -o, -e and -i options in ss man page

[Phil Sutter <phil@nwl.cc>]

Hi Yupeng,

On Wed, Oct 25, 2017 at 02:20:25PM -0700, peng yu wrote:
> Thanks for your suggestion, below is a new patch. What I did:
> 1. change all 'package' to 'packet'
> 2. put my additional text as second paragraphs of the original options.
> 3. checked the man page by aspell
> If anything else need to fix, please let me know.

Thanks for quickly addressing all mentioned issues! Though here come a
few more (sorry):

Your MUA mangled the patch so it doesn't apply cleanly. Please in
future, use 'git format-patch' and 'git send-email' to avoid this. You
can still add comments to it (like those lines above) by inserting them
below the '---' marker (and above the diff-stat) format-patch usually
inserts. This way these comments won't be included in the commit
message.

More inline:

> commit 9803d27de31028733de789495d78ff7a39385009
> Author: yupeng <yupeng0921@gmail.com>
> Date:   Wed Oct 25 21:12:21 2017 +0000
> 
>     add additional explain in ss man page
> 
>     Add detail explains of -m, -o, -e and -i options, which are not
>     documented anywhere
> 
>     Signed-off-by: Peng Yu <yupeng0921@gmail.com>

You have something set up inconsistently regarding your name here: In
'Author' above it's "yupeng" while in SoB and From address it's "Peng
Yu". This is just a minor nit, but if you set it up consistently, the
submitted patches will appear more clean.

> diff --git a/man/man8/ss.8 b/man/man8/ss.8
> index 3bec97f..401ae3e 100644
> --- a/man/man8/ss.8
> +++ b/man/man8/ss.8
> @@ -37,19 +37,152 @@ Display both listening and non-listening (for TCP
> this means established connect

This is an example of where your MUA mangled the patch, the line above
shouldn't be broken.

>  Display only listening sockets (these are omitted by default).
>  .TP
>  .B \-o, \-\-options
> -Show timer information.
> +Show timer information. For tcp protocol, the output format is:
> +.br

I suggest replacing that explicit line break with:
.RS
.P

> +timer:(<timer_name>,<expire_time>,<retrans>)
> +.br

And this one with:
.P
.TP

> +.B <timer_name>
> +the name of the timer, there are five kind of timer names:
> +.RS
> +.RS

Then drop one of the .RS here.

> +.BR on ": means one of these timers: tcp retrans timer, tcp early
> retrans timer and tail loss probe timer"
> +.br
> +.BR keepalive ": tcp keep alive timer"
> +.br
> +.BR timewait ": timewait stage timer"
> +.br
> +.BR persist ": zero window probe timer"
> +.br
> +.BR unknown ": none of the above timers"
> +.RE

Insert .TP here.

> +.B <expire_time>
> +how long time the timer will expire
> +.br

Replace .br here with .TP and change the other additions equivalently. I
think the result is more readable, what do you think?

Thanks, Phil