[PATCH 1/3] docs: improve the formatting and wording of two man pages

[PATCH 1/3] docs: improve the formatting and wording of two man pages

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 login-utils/sulogin.8  |   39 ++++++++++++++++++++-------------------
 login-utils/utmpdump.1 |   16 ++++++++--------
 2 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/login-utils/sulogin.8 b/login-utils/sulogin.8
index 57a7118..17b07da 100644
--- a/login-utils/sulogin.8
+++ b/login-utils/sulogin.8
@@ -1,4 +1,3 @@
-'\" -*- coding: UTF-8 -*-
 .\" Copyright (C) 1998-2006 Miquel van Smoorenburg.
 .\" Copyright (C) 2012 Karel Zak <kzak@redhat.com>
 .\"
@@ -16,18 +15,17 @@
 .\" along with this program; if not, write to the Free Software
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 .\"
-.TH SULOGIN "8" "Jul 2012" "util-linux" "System Administration"
+.TH SULOGIN "8" "July 2014" "util-linux" "System Administration"
 .SH NAME
-sulogin \- Single-user login
+sulogin \- single-user login
 .SH SYNOPSIS
-.B sulogin
-.RB [ options ]
-.RB [ tty ]
+.BR sulogin " [options]"
+.RI [ tty ]
 .SH DESCRIPTION
-.I sulogin
+.B sulogin
 is invoked by
 .B init
-when the system goes into single user mode.
+when the system goes into single-user mode.
 .PP
 The user is prompted:
 .IP "" .5i
@@ -35,40 +33,43 @@ Give root password for system maintenance
 .br
 (or type Control\-D for normal startup):
 .PP
-.I sulogin
-will be connected to the current terminal, or to the optional tty device that
+.B sulogin
+will be connected to the current terminal, or to the optional \fItty\fR device that
 can be specified on the command line (typically
 .BR /dev/console ).
 .PP
-After the user exits the single-user shell or presses control\-D at the
+When the user exits from the single-user shell, or presses control\-D at the
 prompt, the system will continue to boot.
 .SH OPTIONS
 .IP "\fB\-e\fR, \fB\-\-force\fP"
-If the default method of obtaining the root password via
+If the default method of obtaining the root password from the system via
 .BR getpwnam (3)
-from the system fails, manually examine
+fails, then examine
 .I /etc/passwd
 and
 .I /etc/shadow
-to get the password.  If they are damaged or nonexistent, sulogin will start
-a root shell without asking for a password.
+to get the password.  If these files are damaged or nonexistent,
+.B sulogin
+will start a root shell without asking for a password.
 .IP
 Only use the
 .B \-e
 option if you are sure the console is physically protected against
 unauthorized access.
 .IP "\fB\-p\fR, \fB\-\-login\-shell\fP"
-Specifying this option causes sulogin to start the shell process as a login
-shell.
+Specifying this option causes
+.B sulogin
+to start the shell process as a login shell.
 .IP "\fB\-t\fR, \fB\-\-timeout \fIseconds\fP"
 Specify the maximum amount of time to wait for user input.  By default,
-sulogin will wait forever.
+.B sulogin
+will wait forever.
 .IP "\fB\-h\fR, \fB\-\-help\fP"
 Display help text and exit.
 .IP "\fB\-V\fR, \fB\-\-version\fP"
 Display version information and exit.
 .SH ENVIRONMENT VARIABLES
-.I sulogin
+.B sulogin
 looks for the environment variable
 .B SUSHELL
 or
diff --git a/login-utils/utmpdump.1 b/login-utils/utmpdump.1
index 7a7442a..933a3c9 100644
--- a/login-utils/utmpdump.1
+++ b/login-utils/utmpdump.1
@@ -1,4 +1,3 @@
-'\" -*- coding: UTF-8 -*-
 .\" Copyright (C) 2010 Michael Krapp
 .\"
 .\" This program is free software; you can redistribute it and/or modify
@@ -19,7 +18,8 @@
 .SH NAME
 utmpdump \- dump UTMP and WTMP files in raw format
 .SH SYNOPSIS
-utmpdump [\-frohV] [ filename ]
+.BR utmpdump " [options]"
+.RI [ filename ]
 .SH DESCRIPTION
 .B utmpdump
 is a simple program to dump UTMP and WTMP files in raw format, so they
@@ -31,10 +31,10 @@ is passed.
 .SH OPTIONS
 .IP "\fB\-f\fR, \fB\-\-follow\fP"
 Output appended data as the file grows.
-.IP "\fB\-r\fR, \fB\-\-reverse\fP
-Undump, write back edited login information into the utmp or wtmp files.
 .IP "\fB\-o\fR, \fB\-\-output\fP \fIfile\fR
 Write command output to \fIfile\fR instead of standard output.
+.IP "\fB\-r\fR, \fB\-\-reverse\fP
+Undump, write back edited login information into the utmp or wtmp files.
 .IP "\fB\-h\fR, \fB\-\-help\fP"
 Display help text and exit.
 .IP "\fB\-V\fR, \fB\-\-version\fP"
@@ -42,14 +42,14 @@ Display version information and exit.
 .SH NOTES
 .B utmpdump
 can be useful in cases of corrupted utmp or wtmp entries.  It can dump
-out utmp/wtmp to an ASCII file, whic can then be edited to remove
-bogus entries and reintegrated, using
+out utmp/wtmp to an ASCII file, which can then be edited to remove
+bogus entries, and reintegrated using:
 .PP
 .RS
-utmpdump -r < ascii_file > wtmp
+.B utmpdump -r < ascii_file > wtmp
 .RE
 .PP
-but be warned, as
+But be warned,
 .B utmpdump
 was written for debugging purposes only.
 .SH BUGS
-- 
1.7.0.4

[PATCH 2/3] docs: improve the wording and conventions in the man-page howto

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 Documentation/howto-man-page.txt |   97 +++++++++++++++++++++-----------------
 1 files changed, 53 insertions(+), 44 deletions(-)

diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt
index 01b458f..ee3cb4e 100644
--- a/Documentation/howto-man-page.txt
+++ b/Documentation/howto-man-page.txt
@@ -1,12 +1,12 @@
-.\" This is an util-linux manual page example in troff format.
+.\" This is a util-linux manual page example in troff format.
 .\"
-.\" .TH macro is expecting following arguments:
+.\" The .TH macro expects the following arguments:
 .\"	title section date footer header
-.\" The title is usually command name.
-.\" The section must match with file name extension.
-.\" The date tells month and year when last update happen.
+.\" The title is usually the command name.
+.\" The section must match the filename extension.
+.\" The date is the month and year when the last update happened.
 .\" The footer is fixed to "util-linux".
-.\" The header is textual string of section
+.\" The header is a textual description of the section:
 .\"	1 "User Commands"
 .\"	2 "System calls"
 .\"	3 "Programmer's Manual"
@@ -16,35 +16,36 @@
 .\"	7 "Miscellanea"
 .\"	8 "System Administration"
 .\"
-.\" Please read `man 7 groff_man' howto use various macros.
+.\" Please read `man 7 groff_man' to see how to use the various macros.
 .\"
-.TH EXAMPLE "1" "August 2011" "util-linux" "User Commands"
+.TH EXAMPLE "1" "July 2014" "util-linux" "User Commands"
 .SH NAME
-example \- an util-linux man page howto
+example \- a util-linux man-page howto
 .SH SYNOPSIS
 .B example
 [options]
 .I argument
 .SH DESCRIPTION
-All manual pages need some sort of description.  Write such here.
+Each manual page needs some sort of description of the command.
+Write such here.
 .SH OPTIONS
 .TP
 \fB\-n\fR, \fB\-\-no\-argument\fR
-This option does not use argument.
+This option does not use an argument.
 .TP
 \fB\-o\fR, \fB\-\-optional\fR[\fI=argument\fR]
-Tell in description an
+Tell in this description that the
 .I argument
-is optional, and what happens when is or is not given.  Notice that
+is optional, and what happens when it is or is not given.  Notice that the word
 .I argument
-is not abbreviated, like in usage function.  Assuming usage function would
-define argument to be
+is not abbreviated as is customary in the usage text.  For example, when the
+usage text uses the argument
 .IR num ,
 the manual page should say
 .IR number .
 .TP
 \fB\-r\fR, \fB\-\-required\fR \fIargument\fR
-Tell in description option
+Tell in this description that the
 .I argument
 is required.
 .TP
@@ -52,27 +53,33 @@ is required.
 Display version information and exit.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
-Display help and exit.
+Display help text and exit.
 .SH NOTES
-Tell details what users might need to know.  For example kernel feature or
+Tell details that users might need to know.  For example, kernel feature or
 version requirements.
 .PP
-The man page groff input lines should not exceed 80 characters length.
+The man-page source lines should not exceed 80 characters in length.
 .PP
-Do not leave empty lines to groff input.  If you need break or paragraph use
-appropriate groff macros.  See
+Do not leave empty lines in the groff input.  If you need a break or a new
+paragraph, use the appropriate groff macros.  See
 .BR groff_man (7)
 how to use man page macros.
 .PP
-Use of
+The use cases of
 .I italic
-which is underlined in terminal, and
+(which is underlined on a terminal) and
 .B bold
-are not strictly defined.  As some sort of convention
-.I arguments
-use italic, and the
-.B other highlights
-are bold.
+are not strictly defined.  The main convention is that
+.I symbolic arguments
+use italic, and
+.B commands
+and
+.B literal arguments
+use bold, and
+.I other highlights
+use
+.B either
+one.
 .\"
 .\" The manual page comments are undervalued way of adding clarifications
 .\" quite not belong to the manual, questions, TODO items etc.  Feel free
@@ -80,37 +87,39 @@ are bold.
 .\"
 .PP
 When in the source a new sentence begins somewhere midline, it should use a
-double space before its initial letter.  This is done because groff uses double
-spaces last sentence ends to end of line, and next begins from new line.
-Unless double spaces are used in middle of of line the spacing style is
-inconsistent.
+double space before its initial letter.  This is done because \fBgroff\fR
+uses a double space after a sentence when this sentence ends at the end of
+an input line and the next sentence begins on the next line.
+Unless a double space is used before other sentence starts as well, the
+spacing style will be inconsistent.
 .SH ENVIRONMENT
-Tell which environment variables affect, and how, to execution of the command.
+Tell which environment variables affect, and how, the execution of the command.
 .TP
 .B EXAMPLE_PATH
-Configuration file path.  Notice that a well-known environment variables such as
-.B HOME
-does not need explanation.
+Configuration file path.  Notice that well-known environment variables, such as
+.BR HOME ,
+do not need explanation.
 .SH FILES
-Tell which file(s) command uses.
+Tell which file(s) the command uses.
 .TP
 .B $EXAMPLE_PATH
 .TQ
 .B $HOME/.example.conf
 .TQ
 .B /etc/example.conf
-What are these files, which order and will the evaluation end or continue if a
-file is found.  In case the explanation is not simple write separated Special
-Files manual page that tells about syntax, meaning of key-value settings etc.
-The file manual page needs to be referred in
+What are these files, in which order are they read, and will the evaluation
+end or continue if one of them is found.
+In case the explanation is not simple, write a separate "Special Files"
+manual page that tells about syntax, meaning of key-value settings, etc.
+This "Special Files" manual page then needs to be referred in the
 .B SEE ALSO
 section.
 .TP
 .B /var/log/example.log
 Another file.
 .SH EXAMPLES
-Write typical and/or clever use examples here.  The bellow examples are stupid,
-and you should never write them to real man page.
+Write typical and/or clever use examples here.  The below examples are stupid,
+and you should never write them in a real man page.
 .TP
 .B example -h
 Output help screen.
@@ -118,7 +127,7 @@ Output help screen.
 .B example -V
 Output version information.
 .SH "EXIT STATUS"
-This section can be removed if command has only two return values,
+This section can be left out if the command has only two return values,
 .B 0
 for success and
 .B 1
-- 
1.7.0.4

[PATCH 3/3] build-sys: harmonize some indentation

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 configure.ac |   18 +++++++++---------
 1 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/configure.ac b/configure.ac
index 1083752..0cf448c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1329,7 +1329,7 @@ AM_CONDITIONAL([BUILD_LINE], [test "x$build_line" = xyes])
 
 
 AC_ARG_ENABLE([mesg],
-	      AS_HELP_STRING([--disable-mesg], [do not build mesg]),
+  AS_HELP_STRING([--disable-mesg], [do not build mesg]),
   [], [UL_DEFAULT_ENABLE([mesg], [yes])]
 )
 UL_BUILD_INIT([mesg])
@@ -1337,7 +1337,7 @@ AM_CONDITIONAL([BUILD_MESG], [test "x$build_mesg" = xyes])
 
 
 AC_ARG_ENABLE([raw],
-	      AS_HELP_STRING([--disable-raw], [do not build raw]),
+  AS_HELP_STRING([--disable-raw], [do not build raw]),
   [], [UL_DEFAULT_ENABLE([raw], [check])]
 )
 UL_BUILD_INIT([raw])
@@ -1417,8 +1417,8 @@ AM_CONDITIONAL([BUILD_CHFN_CHSH], [test "x$build_chfn_chsh" = xyes])
 AM_CONDITIONAL([CHFN_CHSH_PASSWORD], [test "x$enable_chfn_chsh_password" = xyes])
 
 AC_ARG_ENABLE([chsh-only-listed],
-AS_HELP_STRING([--disable-chsh-only-listed], [chsh: allow shells not in /etc/shells]),
-[], enable_chsh_only_listed=yes
+  AS_HELP_STRING([--disable-chsh-only-listed], [chsh: allow shells not in /etc/shells]),
+  [], enable_chsh_only_listed=yes
 )
 
 AS_IF([test "x$enable_chsh_only_listed" = xyes], [
@@ -1814,14 +1814,14 @@ AC_MSG_RESULT([
 	prefix:            ${prefix}
 	exec prefix:       ${exec_prefix}
 
-        localstatedir:     ${localstatedir}
-	bindir:	           ${bindir}
+	localstatedir:     ${localstatedir}
+	bindir:            ${bindir}
 	sbindir:           ${sbindir}
 	libdir:            ${libdir}
 	includedir:        ${includedir}
-        usrbin_execdir:    ${usrbin_execdir}
-        usrsbin_execdir:   ${usrsbin_execdir}
-        usrlib_execdir:    ${usrlib_execdir}
+	usrbin_execdir:    ${usrbin_execdir}
+	usrsbin_execdir:   ${usrsbin_execdir}
+	usrlib_execdir:    ${usrlib_execdir}
 
 	compiler:          ${CC}
 	cflags:            ${CFLAGS}
-- 
1.7.0.4

Re: [PATCH 1/3] docs: improve the formatting and wording of two man pages

[Karel Zak]

On Wed, Jul 16, 2014 at 01:09:51PM +0200, Benno Schulenberg wrote:
>  login-utils/sulogin.8  |   39 ++++++++++++++++++++-------------------
>  login-utils/utmpdump.1 |   16 ++++++++--------
>  2 files changed, 28 insertions(+), 27 deletions(-)

 Applied all 3 patches, thanks.

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