[PATCH 13/15] prlimit: enhance examples section of the man page

[PATCH 13/15] prlimit: enhance examples section of the man page

[Bernhard Voelker]

[PATCH 13/15] prlimit: enhance examples section of the man page

Add various examples to the man page, e.g. demonstrating setting
limits using short options, showing that the --pid option can be
used in random positions, how to use the "-1" notation for the
"unlimited" value, and that prlimit takes the values from the arguments
last set.

Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
---
  sys-utils/prlimit.1 |   13 ++++++++++---
  1 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/sys-utils/prlimit.1 b/sys-utils/prlimit.1
index fa45aca..ece6c05 100644
--- a/sys-utils/prlimit.1
+++ b/sys-utils/prlimit.1
@@ -88,13 +88,20 @@ Timeout for real-time tasks.
  .SH EXAMPLES
  .IP "\fBprlimit \-\-pid 13134\fP"
  Display limit values for all current resources.
-.IP "\fBprlimit \-\-pid 13134 \--rss --nofile=1024:4095\fP"
+.IP "\fBprlimit \--rss \-\-pid 13134 --nofile=1024:4095\fP"
  Display the limits of the RSS and set the soft and hard limits for the 
amount
  of open files to 1024 and 4095, respectively.
-.IP "\fBprlimit \-\-pid 13134 --nproc=512:\fP"
+.IP "\fBprlimit \-\-pid 13134 -n512:\fP"
  Modify only the soft limit for the amount of processes.
-.IP "\fBprlimit \-\-pid $$ --nproc=unlimited\fP"
+.IP "\fBprlimit \-\-pid=$$ --nproc=unlimited\fP"
  Set the amount of processes for both soft and ceiling values to unlimited.
+.IP "\fBprlimit \-p$$ -n-1:\fP"
+Likewise, but only for the soft limit and using the "-1" notation.
+.IP "\fBprlimit \-p$$ -n:1000 -n\fP"
+Set the hard NPROC limit to 1000 and display its value.
+.IP "\fBprlimit \-p$$ -n100:200 -n300 -n400: -n:500\fP"
+Example to demonstrate that prlimit uses the values of the options last 
set.
+Here it will set the soft NPROC limit to 400 and the hard limit to 500.

  .SH "SEE ALSO"
  .BR prlimit (2),

Re: [PATCH 13/15] prlimit: enhance examples section of the man page

[Davidlohr Bueso]

On Mon, 2011-11-14 at 02:48 +0100, Bernhard Voelker wrote:
> [PATCH 13/15] prlimit: enhance examples section of the man page
> 
> Add various examples to the man page, e.g. demonstrating setting
> limits using short options, showing that the --pid option can be
> used in random positions, how to use the "-1" notation for the
> "unlimited" value, and that prlimit takes the values from the arguments
> last set.

Just a few examples are more than enough to illustrate the point;
manpages have always been this way. I think this is unnecessary and
clogs the document.

> Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
> ---
>   sys-utils/prlimit.1 |   13 ++++++++++---
>   1 files changed, 10 insertions(+), 3 deletions(-)
> 
> diff --git a/sys-utils/prlimit.1 b/sys-utils/prlimit.1
> index fa45aca..ece6c05 100644
> --- a/sys-utils/prlimit.1
> +++ b/sys-utils/prlimit.1
> @@ -88,13 +88,20 @@ Timeout for real-time tasks.
>   .SH EXAMPLES
>   .IP "\fBprlimit \-\-pid 13134\fP"
>   Display limit values for all current resources.
> -.IP "\fBprlimit \-\-pid 13134 \--rss --nofile=1024:4095\fP"
> +.IP "\fBprlimit \--rss \-\-pid 13134 --nofile=1024:4095\fP"
>   Display the limits of the RSS and set the soft and hard limits for the 
> amount
>   of open files to 1024 and 4095, respectively.
> -.IP "\fBprlimit \-\-pid 13134 --nproc=512:\fP"
> +.IP "\fBprlimit \-\-pid 13134 -n512:\fP"
>   Modify only the soft limit for the amount of processes.
> -.IP "\fBprlimit \-\-pid $$ --nproc=unlimited\fP"
> +.IP "\fBprlimit \-\-pid=$$ --nproc=unlimited\fP"
>   Set the amount of processes for both soft and ceiling values to unlimited.
> +.IP "\fBprlimit \-p$$ -n-1:\fP"
> +Likewise, but only for the soft limit and using the "-1" notation.
> +.IP "\fBprlimit \-p$$ -n:1000 -n\fP"
> +Set the hard NPROC limit to 1000 and display its value.
> +.IP "\fBprlimit \-p$$ -n100:200 -n300 -n400: -n:500\fP"
> +Example to demonstrate that prlimit uses the values of the options last 
> set.
> +Here it will set the soft NPROC limit to 400 and the hard limit to 500.
> 
>   .SH "SEE ALSO"
>   .BR prlimit (2),
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

RE: [PATCH 13/15] prlimit: enhance examples section of the man page

[Voelker, Bernhard]

Davidlohr Bueso wrote:
> On Mon, 2011-11-14 at 02:48 +0100, Bernhard Voelker wrote:
> > [PATCH 13/15] prlimit: enhance examples section of the man page
> > 
> > Add various examples to the man page, e.g. demonstrating setting
> > limits using short options, showing that the --pid option can be
> > used in random positions, how to use the "-1" notation for the
> > "unlimited" value, and that prlimit takes the values from the arguments
> > last set.

> Just a few examples are more than enough to illustrate the point;
> manpages have always been this way. I think this is unnecessary and
> clogs the document.

admitted.

Somehow I felt that the existing examples where to homogeneous.
Well, prlimit didn't e.g. support passing the PID after other
modifying arguments, so I thought that enhancing the examples
with the new, "wilder" usage would be nice. ;-)

But in these 2 I missed an error: there's a "=" missing between
"--pid" and the PID:

> > -.IP "\fBprlimit \-\-pid 13134 \--rss --nofile=1024:4095\fP"
> > +.IP "\fBprlimit \--rss \-\-pid 13134 --nofile=1024:4095\fP"

> > -.IP "\fBprlimit \-\-pid 13134 --nproc=512:\fP"
> > +.IP "\fBprlimit \-\-pid 13134 -n512:\fP"

I only spotted the missing "=" here, but failed to mention it
in the commit log:

> > -.IP "\fBprlimit \-\-pid $$ --nproc=unlimited\fP"
> > +.IP "\fBprlimit \-\-pid=$$ --nproc=unlimited\fP"

What's your recommendation?

Have a nice day,
Berny

Re: [PATCH 13/15] prlimit: enhance examples section of the man page

[Karel Zak]

On Mon, Nov 14, 2011 at 10:24:14AM +0100, Voelker, Bernhard wrote:
> Davidlohr Bueso wrote:
> > On Mon, 2011-11-14 at 02:48 +0100, Bernhard Voelker wrote:
> > > [PATCH 13/15] prlimit: enhance examples section of the man page
> > > 
> > > Add various examples to the man page, e.g. demonstrating setting
> > > limits using short options, showing that the --pid option can be
> > > used in random positions, how to use the "-1" notation for the
> > > "unlimited" value, and that prlimit takes the values from the arguments
> > > last set.
> 
> > Just a few examples are more than enough to illustrate the point;
> > manpages have always been this way. I think this is unnecessary and
> > clogs the document.
> 
> admitted.
> 
> Somehow I felt that the existing examples where to homogeneous.

 This is feature ;-)

 Really, we prefer nice *readable* examples with long options.

> Well, prlimit didn't e.g. support passing the PID after other
> modifying arguments, so I thought that enhancing the examples
> with the new, "wilder" usage would be nice. ;-)
> 
> But in these 2 I missed an error: there's a "=" missing between
> "--pid" and the PID:
> 
> > > -.IP "\fBprlimit \-\-pid 13134 \--rss --nofile=1024:4095\fP"
> > > +.IP "\fBprlimit \--rss \-\-pid 13134 --nofile=1024:4095\fP"
> 
> > > -.IP "\fBprlimit \-\-pid 13134 --nproc=512:\fP"
> > > +.IP "\fBprlimit \-\-pid 13134 -n512:\fP"
> 
> I only spotted the missing "=" here, but failed to mention it
> in the commit log:
> 
> > > -.IP "\fBprlimit \-\-pid $$ --nproc=unlimited\fP"
> > > +.IP "\fBprlimit \-\-pid=$$ --nproc=unlimited\fP"
> 
> What's your recommendation?

 The '=' is necessary for optional arguments (for example resource
 arguments) only.

 Bernhard, small note: many of your patches are malformed by your
 e-mail client. Please, reconfigure the mail client (to not modify
 long lines) or use git-send-email.

 Thanks, your found many issues!

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 13/15] prlimit: enhance examples section of the man page

[Bernhard Voelker]

On 11/16/2011 02:05 PM, Karel Zak wrote:


>   Bernhard, small note: many of your patches are malformed by your
>   e-mail client. Please, reconfigure the mail client (to not modify
>   long lines) or use git-send-email.

sorry for that. I thought I have already taught my Thunderbird to not
touch the text ...
BTW: would you have preferred attachments?

>   Thanks, your found many issues!

Thanks for taking your time. I'd have made your life easier if
I had asked before whether the solution with the array is what you
like. Sorry.

Bye,
Berny