Re: [patch] ipcs (in git) produces too much output

[Benno Schulenberg <bensberg@justemail.net>]

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


Hi Sami,

On Sun, Jan 27, 2013, at 21:27, Sami Kerola wrote:
> Both patches look pretty good. I just wonder would .SS make sense for
> second level option headers?

Yes, that looks nicer.  Attached an updated patch for the man page.
It also makes a third subsection for --bytes and --human.

Regards,

Benno

-- 
http://www.fastmail.fm - Send your email first class


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-docs-improve-wording-formatting-and-accuracy-of-ipcs.patch --]
[-- Type: text/x-patch; name="0002-docs-improve-wording-formatting-and-accuracy-of-ipcs.patch", Size: 4229 bytes --]

From ed77954d18187fc8e4155c12c155d133c0a6a944 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@justemail.net>
Date: Sun, 27 Jan 2013 14:40:19 +0100
Subject: [PATCH 2/2] docs: improve wording, formatting and accuracy of ipcs man page

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/ipcs.1 |   73 ++++++++++++++++++++++++++++-------------------------
 1 files changed, 39 insertions(+), 34 deletions(-)

diff --git a/sys-utils/ipcs.1 b/sys-utils/ipcs.1
index 5fc3a81..c070d1a 100644
--- a/sys-utils/ipcs.1
+++ b/sys-utils/ipcs.1
@@ -1,76 +1,79 @@
 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
 .\" May be distributed under the GNU General Public License
-.TH IPCS "1" "September 2011" "util-linux" "User Commands"
+.TH IPCS "1" "January 2013" "util-linux" "User Commands"
 .SH NAME
-ipcs \- provide information on ipc facilities
+ipcs \- provide information on IPC facilities
 .SH SYNOPSIS
 .B ipcs
-[resource] [...] [output\-format]
+.RB [ resource\-option "] [" output\-format ]
 .br
 .B ipcs
-[resource]
-.I \-i id
+.RB [ resource\-option ]
+.BI \-i " id"
 .SH DESCRIPTION
 .B ipcs
-provides information on the ipc facilities for which the calling process
-has read access.
+provides information on the inter-process communication facilities
+for which the calling process has read access.
 .SH OPTIONS
 .TP
 \fB\-i\fR, \fB\-\-id\fR \fIid\fR
-Print details only on resource identified by
+Print details only on the resource identified by
 .IR id .
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Display this help and exit.
+Display a help text and exit.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
-Output version information and exit.
-.SH "RESOURCE OPTIONS"
-.TP
-\fB\-m\fR, \fB\-\-shmems\fR
-Write information about active shared memory segments.
+Display version information and exit.
+.SS "Resource options"
 .TP
 \fB\-q\fR, \fB\-\-queues\fR
 Write information about active message queues.
 .TP
+\fB\-m\fR, \fB\-\-shmems\fR
+Write information about active shared memory segments.
+.TP
 \fB\-s\fR, \fB\-\-semaphores\fR
 Write information about active semaphore sets.
 .TP
 \fB\-a\fR, \fB\-\-all\fR
-Write information about all resources (default).
-.SH "OUTPUT FORMATS"
+Write information about all three resources (default).
+.SS "Output formats"
+Of these options only one takes effect: the last one specified.
+.TP
+\fB\-c\fR, \fB\-\-creator\fR
+Show creator and owner.
+.TP
+\fB\-l\fR, \fB\-\-limits\fR
+Show resource limits.
+.TP
+\fB\-p\fR, \fB\-\-pid\fR
+Show PIDs of creator and last operator.
 .TP
 \fB\-t\fR, \fB\-\-time\fR
-Write time information. Time of the last control operation that changed the
-access permissions for all facilities, time of the last
+Write time information.  The time of the last control operation that changed
+the access permissions for all facilities, the time of the last
 .I msgsnd()
 and
 .I msgrcv()
-operations on message queues, time of the last
+operations on message queues, the time of the last
 .I shmat()
 and
 .I shmdt()
-operations on shared memory, and time of the last
+operations on shared memory, and the time of the last
 .I semop()
 operation on semaphores.
 .TP
-\fB\-p\fR, \fB\-\-pid\fR
-Show creator and last operations PIDs.
-.TP
-\fB\-c\fR, \fB\-\-creator\fR
-Show creator and owner.
-.TP
-\fB\-l\fR, \fB\-\-limits\fR
-Show resource limits.
-.TP
 \fB\-u\fR, \fB\-\-summary\fR
 Show status summary.
-.TP
-.B \-\-human
-Print sizes in human readable format.
+.SS "Representation"
+These affect only the \fB\-l\fR (\fB\-\-limits\fR) option.
 .TP
 \fB\-b\fR, \fB\-\-bytes\fR
 Print sizes in bytes.
+.TP
+.B \-\-human
+Print sizes in human-readable format.
 .SH SEE ALSO
 .BR ipcrm (1),
 .BR ipcmk (1),
@@ -83,7 +86,8 @@ Print sizes in bytes.
 .BR shmget (2)
 .SH CONFORMING TO
 The Linux ipcs utility is not fully compatible to the POSIX ipcs utility.
-The Linux version does not support the
+The Linux version does not support the POSIX
+.BR \-a ,
 .B \-b
 and
 .B \-o
@@ -91,7 +95,8 @@ options, but does support the
 .B \-l
 and
 .B \-u
-options not defined by POSIX. The portable application shall not use the
+options not defined by POSIX.  A portable application shall not use the
+.BR \-a ,
 .BR \-b ,
 .BR \-o ,
 .BR \-l ,
-- 
1.7.0.4