* Re: [PATCH] more: comply with howto-usage-function.txt
2014-02-08 17:15 [PATCH] more: comply with howto-usage-function.txt Phillip Susi
@ 2014-02-09 10:43 ` Benno Schulenberg
2014-02-21 10:58 ` Karel Zak
0 siblings, 1 reply; 3+ messages in thread
From: Benno Schulenberg @ 2014-02-09 10:43 UTC (permalink / raw)
To: Phillip Susi; +Cc: Util-Linux
[-- Attachment #1: Type: text/plain, Size: 1151 bytes --]
On Sat, Feb 8, 2014, at 18:15, Phillip Susi wrote:
> .TP
> -.B \-number
> +.B \-<number>
The angle-bracket convention is valid for the in-program usage texts,
not for man pages. Man pages use italics for non-literal parameters,
as in the explanatory text of the option:
> This option specifies an integer
> .I number
> which is the screen size (in lines).
Attached changes the man page to use italics for every non-literal
parameter.
> - " -NUM specify the number of lines per screenful\n"
> - " +NUM display file beginning from line number NUM\n"
> + " -<NUM> specify NUM number of lines per screenful\n"
> + " +<NUM> display file beginning from line number NUM\n"
> " +/STRING display file beginning from search string match\n"
If <NUM> then also <STRING>, no? Attached patch includes that
change, and uses the full word "number" in all lowercase instead,
as is the convention when using angular brackets, and seizes the
opportunity to slice up the monolithic help text into single options
for ease of translation.
Regards,
Benno
--
http://www.fastmail.fm - The way an email service should be
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-more-improve-formatting-and-wording-of-man-page-and-.patch --]
[-- Type: text/x-patch; name="0001-more-improve-formatting-and-wording-of-man-page-and-.patch", Size: 4985 bytes --]
From 67cff46bbdb36e1f22ec0bc6e2d2c3ab20e0b675 Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@justemail.net>
Date: Sun, 9 Feb 2014 11:26:49 +0100
Subject: [PATCH] more: improve formatting and wording of man page and help text
Also, slice up the usage text for ease of translation.
Reported-by: Phillip Susi <psusi@ubuntu.com>
Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
text-utils/more.1 | 38 ++++++++++++++++++++------------------
text-utils/more.c | 31 +++++++++++++++----------------
2 files changed, 35 insertions(+), 34 deletions(-)
diff --git a/text-utils/more.1 b/text-utils/more.1
index 479f037..0cf3892 100644
--- a/text-utils/more.1
+++ b/text-utils/more.1
@@ -37,12 +37,13 @@
.\" conform with the more 5.19 currently in use by the Linux community.
.\"
.\" .Dd July 29, 1991 (Modified December 25, 1992)
-.TH MORE "1" "September 2011" "util-linux" "User Commands"
+.TH MORE "1" "February 2014" "util-linux" "User Commands"
.SH NAME
more \- file perusal filter for crt viewing
.SH SYNOPSIS
.B more
-[options] file [...]
+[options]
+.IR file ...
.SH DESCRIPTION
.B more
is a filter for paging through text one screenful at a time. This version is
@@ -59,11 +60,6 @@ environment variable
override them.
.It Fl num
.TP
-.B \-number
-This option specifies an integer
-.I number
-which is the screen size (in lines).
-.TP
.B \-d
.B more
will prompt the user with the message "[Press space to continue, 'q' to
@@ -100,15 +96,19 @@ Squeeze multiple blank lines into one.
.B \-u
Suppress underlining.
.TP
-.B +/
-The
-.B +/
-option specifies a string that will be searched for before each file is
-displayed.
+.BI \- number
+The screen size to use, in
+.I number
+of lines.
.TP
-.B +number
-Start at line
+.BI + number
+Start displaying each file at line
.IR number .
+.TP
+.BI +/ string
+The
+.I string
+to be searched in each file before starting to display it.
.SH COMMANDS
Interactive commands for
.B more
@@ -203,7 +203,9 @@ Display current file name and line number.
.B \&.
Repeat previous command.
.SH ENVIRONMENT
-More utilizes the following environment variables, if they exist:
+The
+.B more
+command respects the following environment variables, if they exist:
.TP
.B MORE
This variable may be set with favored options to
@@ -213,16 +215,16 @@ This variable may be set with favored options to
Current shell in use (normally set by the shell at login time).
.TP
.B TERM
-Specifies terminal type, used by more to get the terminal
+The terminal type used by \fBmore\fR to get the terminal
characteristics necessary to manipulate the screen.
.TP
.B VISUAL
-Editor the user is preferring. Used when key command
+The editor the user prefers. Invoked when command key
.I v
is pressed.
.TP
.B EDITOR
-Editor of choise when
+The editor of choice when
.B VISUAL
is not specified.
.SH SEE ALSO
diff --git a/text-utils/more.c b/text-utils/more.c
index 4c39887..b06abbb 100644
--- a/text-utils/more.c
+++ b/text-utils/more.c
@@ -315,22 +315,21 @@ static char *my_tgoto(char *cap, int col, int row)
static void __attribute__((__noreturn__)) usage(FILE *out)
{
- fprintf(out,
- _("Usage: %s [options] file...\n\n"),
- program_invocation_short_name);
- fprintf(out,
- _("Options:\n"
- " -d display help instead of ring bell\n"
- " -f count logical, rather than screen lines\n"
- " -l suppress pause after form feed\n"
- " -p do not scroll, clean screen and display text\n"
- " -c do not scroll, display text and clean line ends\n"
- " -u suppress underlining\n"
- " -s squeeze multiple blank lines into one\n"
- " -NUM specify the number of lines per screenful\n"
- " +NUM display file beginning from line number NUM\n"
- " +/STRING display file beginning from search string match\n"
- " -V output version information and exit\n"));
+ fputs(USAGE_HEADER, out);
+ fprintf(out, _(" %s [options] <file>...\n"), program_invocation_short_name);
+ fputs(USAGE_OPTIONS, out);
+ fputs(_(" -d display help instead of ringing bell\n"), out);
+ fputs(_(" -f count logical rather than screen lines\n"), out);
+ fputs(_(" -l suppress pause after form feed\n"), out);
+ fputs(_(" -c do not scroll, display text and clean line ends\n"), out);
+ fputs(_(" -p do not scroll, clean screen and display text\n"), out);
+ fputs(_(" -s squeeze multiple blank lines into one\n"), out);
+ fputs(_(" -u suppress underlining\n"), out);
+ fputs(_(" -<number> the number of lines per screenful\n"), out);
+ fputs(_(" +<number> display file beginning from line number\n"), out);
+ fputs(_(" +/<string> display file beginning from search string match\n"), out);
+ fputs(_(" -V display version information and exit\n"), out);
+ fprintf(out, USAGE_MAN_TAIL("more(1)"));
exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
}
--
1.7.0.4
^ permalink raw reply related [flat|nested] 3+ messages in thread