[PATCH] more: comply with howto-usage-function.txt

[PATCH] more: comply with howto-usage-function.txt

[Phillip Susi]

Add angle brackets around the -<num> argument to make it
clear that this is a number, and not the word "NUM"

Signed-off-by: Phillip Susi <psusi@ubuntu.com>
---
 text-utils/more.1 | 4 ++--
 text-utils/more.c | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/text-utils/more.1 b/text-utils/more.1
index 479f037..b6b6585 100644
--- a/text-utils/more.1
+++ b/text-utils/more.1
@@ -59,7 +59,7 @@ environment variable
 override them.
 .It Fl num
 .TP
-.B \-number
+.B \-<number>
 This option specifies an integer
 .I number
 which is the screen size (in lines).
@@ -106,7 +106,7 @@ The
 option specifies a string that will be searched for before each file is
 displayed.
 .TP
-.B +number
+.B +<number>
 Start at line
 .IR number .
 .SH COMMANDS
diff --git a/text-utils/more.c b/text-utils/more.c
index 4c39887..1a93257 100644
--- a/text-utils/more.c
+++ b/text-utils/more.c
@@ -327,8 +327,8 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 		  "  -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"
+		  "  -<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"
 		  "  -V        output version information and exit\n"));
 	exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
-- 
1.8.3.2

Re: [PATCH] more: comply with howto-usage-function.txt

[Benno Schulenberg]

[-- 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

Re: [PATCH] more: comply with howto-usage-function.txt

[Karel Zak]

On Sun, Feb 09, 2014 at 11:43:10AM +0100, Benno Schulenberg wrote:
>  text-utils/more.1 |   38 ++++++++++++++++++++------------------
>  text-utils/more.c |   31 +++++++++++++++----------------
>  2 files changed, 35 insertions(+), 34 deletions(-)

 Applied, thanks.

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