[PATCH 17/21] login-utils/chfn.1: Improve the typesetting of the manual

[PATCH 17/21] login-utils/chfn.1: Improve the typesetting of the manual

[Bjarni Ingi Gislason]

  Change comma (,) to a period (.) as it is the control character

  Use macro RB instead of the reverse one (BR)

  Add missing [ in front of  an (optional) option

  Protect a full stop (.), that begins or ends a string, with \&

  Change '-' to '\-', if it indicates an option

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
 login-utils/chfn.1 |   8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/login-utils/chfn.1 b/login-utils/chfn.1
index 2c35acd..3b44fb3 100644
--- a/login-utils/chfn.1
+++ b/login-utils/chfn.1
@@ -19,11 +19,11 @@ chfn \- change your finger information
 .IR full-name ]
 .RB [ \-o
 .IR office ]
-,RB [ \-p
+.RB [ \-p
 .IR office-phone ]
 .RB [ \-h
 .IR home-phone ]
-.BR \-u ]
+.RB [ \-u ]
 .RB [ \-v ]
 .RI [ username ]
 .SH DESCRIPTION
@@ -40,7 +40,7 @@ command will display four pieces of information that can be changed by
 your real name, your work room and phone, and your home phone.
 
 .B chfn
-supports non-local entries (kerberos, LDAP, etc.) if linked with libuser,
+supports non-local entries (kerberos, LDAP, etc.\&) if linked with libuser,
 otherwise use ypchsh, lchsh or any other implementation for non-local
 entries.
 .SS COMMAND LINE
@@ -71,7 +71,7 @@ Specify your home phone number.
 .B "\-u, \-\-help"
 Display help text and exit.
 .TP
-.B "-v, \-\-version"
+.B "\-v, \-\-version"
 Display version information and exit.
 .SH "EXIT STATUS"
 Returns 0 if operation was successful, 1 if operation failed or command syntax was not valid.
-- 
1.9.0

[PATCH 18/21] login-utils/chsh.1: Improve the typesetting of the manual

[Bjarni Ingi Gislason]

  Protect a full stop (.), that begins or ends a string, with \&

  Change '-' to '\-', if it indicates an option

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
 login-utils/chsh.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/login-utils/chsh.1 b/login-utils/chsh.1
index 5ee0f09..229f5e1 100644
--- a/login-utils/chsh.1
+++ b/login-utils/chsh.1
@@ -29,7 +29,7 @@ If a shell is not given on the command line,
 prompts for one.
 
 .B chsh
-supports non-local entries (kerberos, LDAP, etc.) if linked with libuser,
+supports non-local entries (kerberos, LDAP, etc.\&) if linked with libuser,
 otherwise use ypchsh, lchsh or any other implementation for non-local
 entries.
 .SH OPTIONS
@@ -45,7 +45,7 @@ and exit.
 .B "\-u, \-\-help"
 Display help text and exit.
 .TP
-.B "-v, \-\-version"
+.B "\-v, \-\-version"
 Display version information and exit.
 .SH "VALID SHELLS"
 .B chsh
-- 
1.9.0

Re: [PATCH 18/21] login-utils/chsh.1: Improve the typesetting of the manual

[Karel Zak]

On Sat, May 03, 2014 at 02:32:36AM +0000, Bjarni Ingi Gislason wrote:
>  login-utils/chsh.1 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

 Applied, thanks.


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

[PATCH 19/21] login-utils/last-deprecated.1: Improve the typesetting of the manual

[Bjarni Ingi Gislason]

  Change \(em to \- in the NAME section

  Add a space character in front of an ellipsis

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
 login-utils/last-deprecated.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/login-utils/last-deprecated.1 b/login-utils/last-deprecated.1
index beb6917..3176885 100644
--- a/login-utils/last-deprecated.1
+++ b/login-utils/last-deprecated.1
@@ -1,6 +1,6 @@
 .TH LAST 1 "March 1992" "util-linux" "User Commands"
 .SH NAME
-last \(em indicate last logins by user or terminal
+last \- indicate last logins by user or terminal
 .SH SYNOPSIS
 .ad l
 .B last
@@ -15,7 +15,7 @@ last \(em indicate last logins by user or terminal
 .IR address ]
 .RB [ \-l ]
 .RB [ \-y ]
-.RI [ name ...]
+.RI [ name " ...]
 .ad b
 .SH DESCRIPTION
 \fBLast\fP looks back in the \fBwtmp\fP file which records all logins
-- 
1.9.0

[PATCH 20/21] login-utils/last.1: Improve the typesetting of the manual

[Bjarni Ingi Gislason]

  Warning from "groff -b -e -mandoc -t -z -ww < ...":

<standard input>:159: warning: can't find font `t'

  Input file is last.1

###

  Add a space character in front of an ellipsis

  Change '-' to '\-', if it indicates an option

  Change '\-' (minus) to '-' (code "hyphen-minus", rendered with the
glyph hyphen in troff), if it is a part of a compound name.
  A minus is not used in words.  People using UTF-8 and copy-and-paste
can(?) (may?) use "info", "man --ascii" or the command "man" should
have an option to display the '-' ("hyphen-minus") in names of options
with the code (character name) "hyphen-minus" (u002D) instead of
"u2010" (code (character) name "hyphen").

  Change word preferrable
to            preferable

  Change 'left' (causes the warning) to 'l' as a command in a table

  Change '-' to '\-', if it means a minus

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
 login-utils/last.1 | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/login-utils/last.1 b/login-utils/last.1
index d0b9744..1398fd1 100644
--- a/login-utils/last.1
+++ b/login-utils/last.1
@@ -20,13 +20,13 @@ last, lastb \- show listing of last logged in users
 .SH SYNOPSIS
 .B last
 .RI [ options ]
-.RI [ username ...]
-.RI [ tty ...]
+.RI [ username " ...]
+.RI [ tty " ...]
 .br
 .B lastb
 .RI [ options ]
-.RI [ username ...]
-.RI [ tty ...]
+.RI [ username " ...]
+.RI [ tty " ...]
 .SH DESCRIPTION
 .B last
 searches back through the file
@@ -97,7 +97,7 @@ but displays the host's IP number instead of name.
 .TP
 .BI \- number
 .TQ
-.BR \-n , " -\-limit " \fInumber\fR
+.BR \-n , " \-\-limit " \fInumber\fR
 This is a count telling
 .B last
 how many lines to show.
@@ -122,7 +122,7 @@ particular time.  The option is often combined with
 Display the state of logins until the specified
 .IR time .
 .TP
-.BI \-\-time\-format " format"
+.BI \-\-time-format " format"
 Define the output timestamp
 .I format
 to be one of
@@ -142,7 +142,7 @@ is the same as the
 option.  The
 .I iso
 variant will display the timestamp in ISO-8601 format.  The ISO format
-contains timezone information, making it preferrable when printouts are
+contains timezone information, making it preferable when printouts are
 investigated outside of the system.
 .TP
 .BR \-w , " \-\-fullnames"
@@ -155,7 +155,7 @@ The options that take the
 .I time
 argument understand the following formats:
 .TS
-left l2 l.
+l l2 l.
 YYYYMMDDhhmmss
 YYYY-MM-DD hh:mm:ss
 YYYY-MM-DD hh:mm	(seconds will be set to 00)
@@ -167,7 +167,7 @@ yesterday	(time is set to 00:00:00)
 today	(time is set to 00:00:00)
 tomorrow	(time is set to 00:00:00)
 +5min
--5days
+\-5days
 .TE
 .SH NOTES
 The files
-- 
1.9.0

Re: [PATCH 20/21] login-utils/last.1: Improve the typesetting of the manual

[Benno Schulenberg]

Hello Bjarni,

On Sat, May 3, 2014, at 4:32, Bjarni Ingi Gislason wrote:
>   Add a space character in front of an ellipsis

Hmm.  I find it clearer when the ellipsis is glued to the thing
that it applies to.  But, as a space before it seems to be the
accepted convention, okay.

However, it would be nice if you could make thematic patches:
one patch for each type of change.  For example, one big patch
for *all* man pages (in util-linux) that makes this space-before-
ellipsis change, then one big patch for no-minus-within-options,
and so on.

(A strange effect of this ellipsis is that between the following pair
of "] [" brackets there will be a double space instead of a single one.
Do you see this too?  An if so, would this be a bug or intentional?)

>   A minus is not used in words.  People using UTF-8 and copy-and-paste
> can(?) (may?) use "info", "man --ascii"

No, you cannot require/suggest that people (if they want to copy and
paste from the man-page output) use 'info' instead of 'man', or use an
extra option.  Commands in the output of plain 'man' should be copy-
and-pastable.  People who want to actually print a manual page may
be required to use extra options to get the typesetting right.

But for me, on a terminal in a UTF-8 locale, it makes no difference
whether a man page contains \-\-long-option or --long-option, all
those dashes render to  0x2d.  So copy-and-paste will work fine.

By the way, what do you use to look at a typeset version of a man
page?  For the first time in my life I've looked at a virtual printout
with 'man -Tps login-utils/last.1 >last.ps; evince last.ps', and I must
say that I find the rendering of --long-option more readable than of
\-\-long-option.  But as I won't ever use this, either way is fine with me.

> -.RI [ username ...]
> -.RI [ tty ...]
> +.RI [ username " ...]
> +.RI [ tty " ...]

Hm.  An unpaired quotation mark I find ugly.
Better do "username " or " ...]" instead.


Benno

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

Re: [PATCH 20/21] login-utils/last.1: Improve the typesetting of the manual

[Karel Zak]

On Sat, May 03, 2014 at 02:44:59PM +0200, Benno Schulenberg wrote:
> 
> Hello Bjarni,
> 
> On Sat, May 3, 2014, at 4:32, Bjarni Ingi Gislason wrote:
> >   Add a space character in front of an ellipsis
> 
> Hmm.  I find it clearer when the ellipsis is glued to the thing
> that it applies to.  But, as a space before it seems to be the
> accepted convention, okay.

 But it would be nice to be consistent. Few minutes ago I merged your
 patch with

     - <device> [...]
     + <device>...\

 I don't have any strong opinion about it, but I'd like to avoid 
 situation when we every week change it.

> However, it would be nice if you could make thematic patches:
> one patch for each type of change.  For example, one big patch
> for *all* man pages (in util-linux) that makes this space-before-
> ellipsis change, then one big patch for no-minus-within-options,
> and so on.

 Yep, it would be really nice.

> (A strange effect of this ellipsis is that between the following pair
> of "] [" brackets there will be a double space instead of a single one.
> Do you see this too?  An if so, would this be a bug or intentional?)
> 
> >   A minus is not used in words.  People using UTF-8 and copy-and-paste
> > can(?) (may?) use "info", "man --ascii"

Bjarni, this is really ugly recommendation -- especially when UTF8 and
copy & past from man pages is pretty common.

> No, you cannot require/suggest that people (if they want to copy and
> paste from the man-page output) use 'info' instead of 'man', or use an
> extra option.  Commands in the output of plain 'man' should be copy-
> and-pastable.  People who want to actually print a manual page may
> be required to use extra options to get the typesetting right.

Exactly.

> But for me, on a terminal in a UTF-8 locale, it makes no difference
> whether a man page contains \-\-long-option or --long-option, all
> those dashes render to  0x2d.  So copy-and-paste will work fine.

 Yep, me too :-)

> > -.RI [ username ...]
> > -.RI [ tty ...]
> > +.RI [ username " ...]
> > +.RI [ tty " ...]
> 
> Hm.  An unpaired quotation mark I find ugly.
> Better do "username " or " ...]" instead.

 Yep, we're SW developers. All strings have to be terminated :-)

    Karel


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

Re: [PATCH 20/21] login-utils/last.1: Improve the typesetting of the manual

[Benno Schulenberg]

On Tue, May 6, 2014, at 12:18, Karel Zak wrote:
> On Sat, May 03, 2014 at 02:44:59PM +0200, Benno Schulenberg wrote:
> > On Sat, May 3, 2014, at 4:32, Bjarni Ingi Gislason wrote:
> > >   Add a space character in front of an ellipsis
> > 
> > Hmm.  I find it clearer when the ellipsis is glued to the thing
> > that it applies to.  But, as a space before it seems to be the
> > accepted convention, okay.
> 
>  But it would be nice to be consistent. Few minutes ago I merged your
>  patch with
> 
>      - <device> [...]
>      + <device>...\
> 
>  I don't have any strong opinion about it, but I'd like to avoid 
>  situation when we every week change it.

:)

Of course.  We'll wait and see what Bjarni has to say.  If he has a
strong opinion about this, we'll go with his.  If not, we'll negotiate
and agree on something.

Benno

-- 
http://www.fastmail.fm - The way an email service should be

[PATCH 21/21] login-utils/login.1: Improve the typesetting of the manual

[Bjarni Ingi Gislason]

  Change macros [BI]R to [BI] when they have only one argument

  Change word approprate
to            appropriate

  Change word adminitrator
to            administrator

  Use a real apostrophe \(aq instead of ' (prints as a single right
quote) or \' (prints as an acute accent)

  Protect a full stop (.), that begins or ends a string, with \&

  Change "and if does not exist then"
to       "and, if it does not exist, then"

  Enlarge tilde (diacritic, accent) as it prints small in "troff"

  Change a macro I to IR and add a full stop (.) to end the sentence

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
 login-utils/login.1 | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/login-utils/login.1 b/login-utils/login.1
index 3e9434f..5b105c5 100644
--- a/login-utils/login.1
+++ b/login-utils/login.1
@@ -6,17 +6,17 @@ login \- begin session on the system
 .SH SYNOPSIS
 .B login
 [
-.BR \-p
+.B \-p
 ] [
-.BR \-h
-.IR host
+.B \-h
+.I host
 ] [
-.BR \-H
+.B \-H
 ] [
-.BR \-f
-.IR username
+.B \-f
+.I username
 |
-.IR username
+.I username
 ]
 .SH DESCRIPTION
 .B login
@@ -24,7 +24,7 @@ is used when signing onto a system.  If no argument is given,
 .B login
 prompts for the username.
 .PP
-The user is then prompted for a password, where approprate.  Echoing
+The user is then prompted for a password, where appropriate.  Echoing
 is disabled to prevent revealing the password.  Only a small number
 of password failures are permitted before
 .B login
@@ -41,7 +41,7 @@ The user and group ID will be set according to their values in the
 .I /etc/passwd
 file.  There is one exception if the user ID is zero: in this case,
 only the primary group ID of the account is set.  This should allow
-the system adminitrator to login even in case of network problems.
+the system administrator to login even in case of network problems.
 The value for
 .BR $HOME ,
 .BR $USER ,
@@ -65,7 +65,7 @@ preserved if the
 .B \-p
 option is given) or be initialize to the terminal type on your tty.
 .PP
-Then the user's shell is started.  If no shell is specified for the
+Then the user\(aqs shell is started.  If no shell is specified for the
 user in
 .BR /etc\:/passwd ,
 then
@@ -119,7 +119,7 @@ with the
 .B \-h
 option the name is
 .IR remote .
-It is necessary to create a proper PAM config files (e.g.
+It is necessary to create a proper PAM config files (e.g.\&
 .I /etc\:/pam.d\:/login
 and
 .IR /etc\:/pam.d\:/remote ).
@@ -138,7 +138,7 @@ Display version information and exit.
 reads the
 .IR /etc\:/login.defs (5)
 configuration file.  Note that the configuration file could be
-distributed with another package (e.g. shadow-utils).  The following
+distributed with another package (e.g.\& shadow-utils).  The following
 configuration items are relevant for
 .BR login (1):
 .PP
@@ -184,9 +184,9 @@ login failure.  The default value is
 (string)
 .RS 4
 The terminal permissions.  The default value is
-.IR 0600
+.I 0600
 or
-.IR 0620
+.I 0620
 if tty group is used.
 .RE
 .PP
@@ -200,7 +200,7 @@ The default value is
 If the
 .B TTYGROUP
 does not exist then the ownership of the terminal is set to the
-user\'s primary group.
+user\(aqs primary group.
 .PP
 The
 .B TTYGROUP
@@ -211,19 +211,19 @@ can be either the name of a group or a numeric group identifier.
 (string)
 .RS 4
 If defined, this file can inhibit all the usual chatter during the
-login sequence.  If a full pathname (e.g.
+login sequence.  If a full pathname (e.g.\&
 .IR /etc\:/hushlogins )
-is specified, then hushed mode will be enabled if the user\'s name or
+is specified, then hushed mode will be enabled if the user\(aqs name or
 shell are found in the file.  If this global hush login file is empty
 then the hushed mode will be enabled for all users.
 .PP
 If not a full pathname is specified, then hushed mode will be enabled
-if the file exists in the user\'s home directory.
+if the file exists in the user\(aqs home directory.
 .PP
 The default is to check
 .I /etc\:/hushlogins
-and if does not exist then
-.I ~/.hushlogin
+and, if it does not exist, then
+.IR \s+3~\s0/.hushlogin .
 .PP
 If the
 .B HUSHLOGIN_FILE
@@ -307,7 +307,7 @@ does a vhangup() system call to remove any possible listening
 processes on the tty.  This is to avoid password sniffing.  If one
 uses the command
 .BR login ,
-then the surrounding shell gets killed by vhangup() because it's no
+then the surrounding shell gets killed by vhangup() because it\(aqs no
 longer the true owner of the tty.  This can be avoided by using
 .B exec login
 in a top-level shell or xterm.
-- 
1.9.0

Re: [PATCH 21/21] login-utils/login.1: Improve the typesetting of the manual

[Benno Schulenberg]

On Sat, May 3, 2014, at 4:32, Bjarni Ingi Gislason wrote:
>   Use a real apostrophe \(aq instead of ' (prints as a single right
> quote) or \' (prints as an acute accent)

Indeed, \' prints as an acute accent, which is not right, but for
me, on a terminal, ' is shown as ', as a plain apostrophe, 0x27
-- there is no need for \(aq there.  And for people who actually
want to print a man page, I would have thought they would prefer
to see the curly U+2019 ("this is the preferred character to use
for apostrophe") instead of the straight U+0027.

https://en.wikipedia.org/wiki/Apostrophe#Typographic_form

What makes you prefer the straight form in typeset documents?

Benno

-- 
http://www.fastmail.fm - mmm... Fastmail...

Re: [PATCH 17/21] login-utils/chfn.1: Improve the typesetting of the manual

[Karel Zak]

On Sat, May 03, 2014 at 02:32:35AM +0000, Bjarni Ingi Gislason wrote:
>  login-utils/chfn.1 |   8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)

 Applied, thanks.

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