Re: docs: improve the cal --help [was: standardizing...]

[Benno Schulenberg <bensberg@justemail.net>]

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


On Wed, Oct 9, 2013, at 11:47, Karel Zak wrote:
>  So I guess we're ready for -rc2, right? (probably tomorrow/Friday)

Oh.  Maybe still apply Pádraig's patch to improve cal's help text.
I have somehow lost his original message, but I had downloaded
his patch, and have attached a slightly improved version: adding
a tiny doc string and a period, and using "arguments" instead of
"options".  Okay with you, Pádraig?

Benno

-- 
http://www.fastmail.fm - Or how I learned to stop worrying and
                          love email again


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-docs-improve-the-cal-help-text-and-man-page.patch --]
[-- Type: text/x-patch; name="0001-docs-improve-the-cal-help-text-and-man-page.patch", Size: 2793 bytes --]

From 4d1675bc2e513dce30290c6787cf75ceaf9b820d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <P@draigBrady.com>
Date: Wed, 9 Oct 2013 20:44:12 +0200
Subject: [PATCH] docs: improve the 'cal' help text and man page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* misc-utils/cal.c: Add a little doc string, and mention that the
  current month is implicit if not specified.  Also remove mention
  of "current" from two option descriptions as a specific date may
  have been specified.
* misc-utils/cal.1: Likewise.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
Signed-off-by: Pádraig Brady <P@draigBrady.com>
---
 misc-utils/cal.1 |    4 ++--
 misc-utils/cal.c |    9 ++++++---
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/misc-utils/cal.1 b/misc-utils/cal.1
index 4e7570d..0e686dd 100644
--- a/misc-utils/cal.1
+++ b/misc-utils/cal.1
@@ -51,7 +51,7 @@ Display single month output.
 (This is the default.)
 .TP
 \fB\-3\fR, \fB\-\-three\fR
-Display prev/current/next month output.
+Display three months spanning the date.
 .TP
 \fB\-s\fR, \fB\-\-sunday\fR
 Display Sunday as the first day of the week.
@@ -63,7 +63,7 @@ Display Monday as the first day of the week.
 Display Julian dates (days one-based, numbered from January 1).
 .TP
 \fB\-y\fR, \fB\-\-year\fR
-Display a calendar for the current year.
+Display a calendar for the whole year.
 .TP
 \fB\-\-color\fR [\fIwhen\fR]
 Colorize output.  The
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index 76d6252..27f94d1 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -805,13 +805,16 @@ static void __attribute__ ((__noreturn__)) usage(FILE * out)
 	fputs(USAGE_HEADER, out);
 	fprintf(out, _(" %s [options] [[[day] month] year]\n"), program_invocation_short_name);
 
+	fprintf(out, _("\nDisplay a calendar, or some part of it.\n"));
+	fprintf(out, _("Without any arguments, display the current month.\n"));
+
 	fputs(USAGE_OPTIONS, out);
-	fputs(_(" -1, --one             show only current month (default)\n"), out);
-	fputs(_(" -3, --three           show previous, current and next month\n"), out);
+	fputs(_(" -1, --one             show only a single month (default)\n"), out);
+	fputs(_(" -3, --three           show three months spanning the date\n"), out);
 	fputs(_(" -s, --sunday          Sunday as first day of week\n"), out);
 	fputs(_(" -m, --monday          Monday as first day of week\n"), out);
 	fputs(_(" -j, --julian          output Julian dates\n"), out);
-	fputs(_(" -y, --year            show whole current year\n"), out);
+	fputs(_(" -y, --year            show the whole year\n"), out);
 	fputs(_("     --color[=<when>]  colorize messages (auto, always or never)\n"), out);
 
 	fputs(USAGE_SEPARATOR, out);
-- 
1.7.0.4