Fix several language, style and mdoc improvements (such as correct

usage of .Xr and removal of hard sentence breaks).

PR:		18880
Submitted by:	Christian Weisgerber <naddy@unix-ag.uni-kl.de>
Obtained from:	OpenBSD (in parts)

1 files changed, 60 insertions, 57 deletions

diff --git a/bin/date/date.1 b/bin/date/date.1
index d53f0bd..8cb5aad 100644
--- a/bin/date/date.1
+++ b/bin/date/date.1
@@ -61,23 +61,26 @@
 .Oc
 .Op Cm + Ns Ar format
 .Sh DESCRIPTION
-.Nm Date
-displays the current date and time when invoked without arguments.
-Providing arguments will format the date and time in a user-defined
-way or set the date.
+When invoked without arguments, the
+.Nm
+utility displays the current date and time.
+Otherwise, depending on the options specified,
+.Nm
+will set the date and time or print it in a user-defined way.
+.Pp
 Only the superuser may set the date.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
-.It Fl d
-Set the kernel's value for daylight savings time.
+.It Fl d Ar dst
+Set the system's value for daylight saving time.
 If
 .Ar dst
 is non-zero, future calls
 to
 .Xr gettimeofday 2
-will return a non-zero
-.Ql tz_dsttime  .
+will return a non-zero value for
+.Fa tz_dsttime .
 .It Fl f
 Use
 .Ar fmt
@@ -89,30 +92,29 @@ the default
 .Oc "\&yy" Oc "\&mm" Oc "\&dd" Oc "\&HH" Ns
 .Oc
 .No "\&MM" Ns Op "\&.ss" Xc
-format.  Parsing is done using
+format.
+Parsing is done using
 .Xr strptime 3 .
 .It Fl j
-Do not try to set the date.  This allows you to use the
+Do not try to set the date.
+This allows you to use the
 .Fl f
 flag in addition to the
 .Cm +
 option to convert one date format to another.
 .It Fl n
-The utility
+By default,
+if the
 .Xr timed 8
-is used to synchronize the clocks on groups of machines.
-By default, if
-.Xr timed
-is running,
+daemon is running,
 .Nm
-will set the time on all of the machines in the local group.
+sets the time on all of the machines in the local group.
 The
 .Fl n
-option stops
-.Nm
-from setting the time for other than the current machine.
-.It Fl r
-Print out the date and time that is
+option suppresses this behavior and causes the time to be set only on the
+current machine.
+.It Fl r Ar seconds
+Print out (in specified format) the date and time represented by
 .Ar seconds
 from the Epoch
 .Po
@@ -120,19 +122,18 @@ from the Epoch
 see
 .Xr time 3
 .Pc .
-.It Fl t
-Set the kernel's value for minutes west of
+.It Fl t Ar minutes_west
+Set the system's value for minutes west of
 .Tn GMT .
-.Ar Minutes_west
+.Ar minutes_west
 specifies the number of minutes returned in
-.Ql tz_minuteswest  
+.Fa tz_minuteswest
 by future calls to
 .Xr gettimeofday 2 .
 .It Fl u
 Display or set the date in
 .Tn UTC
-.Pq universal
-time.
+(Coordinated Universal) time.
 .It Fl v
 Adjust the second, minute, hour, month day, week day, month or year according to
 .Ar val .  
@@ -140,8 +141,9 @@ If
 .Ar val
 is preceded with a plus or minus sign, the date is adjusted forwards
 or backwards according to the remaining string, otherwise the relevant
-part of the date is set.  The date can be adjusted as many times as
-required using these flags.  Flags are processed in the order given.
+part of the date is set.
+The date can be adjusted as many times as required using these flags.
+Flags are processed in the order given.
 .Pp
 When setting values
 .Pq rather than adjusting them ,
@@ -167,18 +169,20 @@ or
 must be used to specify which part of the date is to be adjusted.
 .Pp
 The week day or month may be specified using a name rather than a
-number.  If a name is used with the plus
+number.
+If a name is used with the plus
 .Pq or minus
 sign, the date will be put forwards
 .Pq or backwards
 to the next
 .Pq previous
-date that matches the given week day or month.  This will not adjust the date
+date that matches the given week day or month.
+This will not adjust the date
 if the given week day or month is the same as the current one.
 .Pp
 When a date is adjusted to a specific value or in units greater than hours,
-daylight savings time considerations are ignored.
-Adjustments in units of hours or less honour daylight savings time.
+daylight saving time considerations are ignored.
+Adjustments in units of hours or less honor daylight saving time.
 So, assuming the current date is March 26, 0:30 and that the DST adjustment
 means that the clock goes forward at 01:00 to 02:00, using
 .Fl v No +1H
@@ -200,14 +204,17 @@ the two times.
 Refer to the examples below for further details.
 .El
 .Pp
-An operand with a leading plus
-.Pq Dq \&+
-sign signals a user-defined format string which specifies the format in
-which to display the date and time.  The format string may contain any of
-the conversion specifications described in the 
+An operand with a leading plus sign
+.Pq Sq +
+signals a user-defined format
+string which specifies the format in which to display the date and time.
+The format string may contain any of the conversion specifications described
+in the
 .Xr strftime 3
 manual page, as well as any arbitrary text.
-A <newline> character is always output after the characters specified by
+A newline
+.Pq Ql \en
+character is always output after the characters specified by
 the format string.
 The format string for the default display is
 .Dq +%+ .
@@ -225,23 +232,22 @@ prepended to the abbreviated year.
 Year in abbreviated form
 .Pq e.g. 89 for 1989, 06 for 2006 .
 .It Ar mm
-Numeric month.
-A number from 1 to 12.
+Numeric month, a number from 1 to 12.
 .It Ar dd
 Day, a number from 1 to 31.
 .It Ar HH
 Hour, a number from 0 to 23.
 .It Ar MM
 Minutes, a number from 0 to 59.
-.It Ar .ss
+.It Ar ss
 Seconds, a number from 0 to 61
 .Pq 59 plus a maximum of two leap seconds .
 .El
 .Pp
 Everything but the minutes is optional.
 .Pp
-Time changes for Daylight Saving and Standard time and leap seconds
-and years are handled automatically.
+Time changes for Daylight Saving Time, standard time, leap seconds,
+and leap years are handled automatically.
 .Sh EXAMPLES
 The command:
 .Bd -literal -offset indent
@@ -305,9 +311,8 @@ sets the time to
 .Li "2:32 PM" ,
 without modifying the date.
 .Sh ENVIRONMENT
-The execution of
-.Nm
-is affected by the following environment variables:
+The following environment variables affect the execution of
+.Nm date :
 .Bl -tag -width Ds
 .It Ev TZ
 The timezone to use when displaying dates.
@@ -323,9 +328,9 @@ for more information.
 .Sh FILES
 .Bl -tag -width /var/log/messages -compact
 .It Pa /var/log/wtmp
-a record of date resets and time changes
+record of date resets and time changes
 .It Pa /var/log/messages
-a record of the user setting the time
+record of the user setting the time
 .El
 .Sh SEE ALSO
 .Xr gettimeofday 2 ,
@@ -339,31 +344,29 @@ a record of the user setting the time
 .%A S. Zatti
 .Re
 .Sh DIAGNOSTICS
-The
-.Nm
-utility exits 0 on success, 1 if unable to set the date, and 2
+Exit status is 0 on success, 1 if unable to set the date, and 2
 if able to set the local date, but unable to set it globally.
 .Pp
 Occasionally, when
-.Xr timed
+.Xr timed 8
 synchronizes the time on many hosts, the setting of a new time value may
 require more than a few seconds.
 On these occasions,
 .Nm
 prints:
-.Ql Network time being set .
+.Dq Network time being set .
 The message
-.Ql Communication error with timed
+.Dq Communication error with timed
 occurs when the communication
 between
 .Nm
 and
-.Xr timed
+.Xr timed 8
 fails.
 .Sh STANDARDS
 The
 .Nm
-command is expected to be compatible with
+utility is expected to be compatible with
 .St -p1003.2 .
 .Sh HISTORY
 A