Issue a STYLE message when normalizing the date format in .Dd/.TH.

[mandoc.git] / roff.7

diff --git a/roff.7 b/roff.7
index b6876e3565fcb9f57fbb77278ff2ac29303f985b..8cb922c70676dfe5d7619dadd947bfed0490121f 100644 (file)
--- a/roff.7
+++ b/roff.7
@@ -1,7 +1,7 @@
-.\"    $Id: roff.7,v 1.80 2017/05/08 15:34:54 schwarze Exp $
+.\"    $Id: roff.7,v 1.96 2018/04/10 00:52:30 schwarze Exp $

 .\"
 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>

-.\" Copyright (c) 2010,2011,2013-2015,2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010-2018 Ingo Schwarze <schwarze@openbsd.org>

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: May 8 2017 $
+.Dd $Mdocdate: April 10 2018 $

 .Dt ROFF 7
 .Os
 .Sh NAME
 .Dt ROFF 7
 .Os
 .Sh NAME


@@ -180,7 +180,7 @@ single-character
 two-character
 .Sq \e*(XX ,
 and N-character
 two-character
 .Sq \e*(XX ,
 and N-character

-.Sq \e*[N] .
+.Sq \e* Ns Bq N .

 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact
 .Pp
 Examples:
 .Bl -tag -width Ds -offset indent -compact


@@ -412,7 +412,6 @@ Create an alias for a number register.
 Currently unsupported.
 .It Ic \&als Ar newname oldname
 Create an alias for a request, string, macro, or diversion.
 Currently unsupported.
 .It Ic \&als Ar newname oldname
 Create an alias for a request, string, macro, or diversion.

-Currently unsupported.

 .It Ic \&am Ar macroname Op Ar endmacro
 Append to a macro definition.
 The syntax of this request is the same as that of
 .It Ic \&am Ar macroname Op Ar endmacro
 Append to a macro definition.
 The syntax of this request is the same as that of


@@ -527,7 +526,10 @@ Trailing characters are ignored.
 Center the next
 .Ar N
 input lines without filling.
 Center the next
 .Ar N
 input lines without filling.

-Currently ignored.
+.Ar N
+defaults to 1.
+An argument of 0 or less ends centering.
+Currently, high level macros abort centering.

 .It Ic \&cf Ar filename
 Output the contents of a file.
 Ignored because insecure.
 .It Ic \&cf Ar filename
 Output the contents of a file.
 Ignored because insecure.


@@ -808,8 +810,11 @@ This is a Heirloom extension and currently unsupported.
 Set a trap within a diversion.
 Currently unsupported.
 .It Ic \&ec Op Ar char
 Set a trap within a diversion.
 Currently unsupported.
 .It Ic \&ec Op Ar char

-Change the escape character.
-Currently unsupported.
+Enable the escape mechanism and change the escape character.
+The
+.Ar char
+argument defaults to the backslash
+.Pq Sq \e .

 .It Ic \&ecr
 Restore the escape character.
 Currently unsupported.
 .It Ic \&ecr
 Restore the escape character.
 Currently unsupported.


@@ -839,7 +844,6 @@ See
 .Ic \&EQ .
 .It Ic \&eo
 Disable the escape mechanism completely.
 .Ic \&EQ .
 .It Ic \&eo
 Disable the escape mechanism completely.

-Currently unsupported.

 .It Ic \&EP
 End a picture started by
 .Ic \&BP .
 .It Ic \&EP
 End a picture started by
 .Ic \&BP .


@@ -1040,8 +1044,6 @@ If the first character of
 is
 .Sq c
 .Pq character available ,
 is
 .Sq c
 .Pq character available ,

-.Sq d
-.Pq string defined ,

 .Sq e
 .Pq even page ,
 .Sq t
 .Sq e
 .Pq even page ,
 .Sq t


@@ -1054,6 +1056,15 @@ it evaluates to false.
 If the first character of
 .Ar condition
 is
 If the first character of
 .Ar condition
 is

+.Sq d ,
+it evaluates to true if the rest of
+.Ar condition
+is the name of an existing user defined macro or string;
+otherwise, it evaluates to false.
+.It
+If the first character of
+.Ar condition
+is

 .Sq r ,
 it evaluates to true if the rest of
 .Ar condition
 .Sq r ,
 it evaluates to true if the rest of
 .Ar condition


@@ -1294,7 +1305,9 @@ Set title line length.
 Currently ignored.
 .It Ic \&mc Ar glyph Op Ar dist
 Print margin character in the right margin.
 Currently ignored.
 .It Ic \&mc Ar glyph Op Ar dist
 Print margin character in the right margin.

-Currently ignored.
+The
+.Ar dist
+is currently ignored; instead, 1n is used.

 .It Ic \&mediasize Ar media
 Set the device media size.
 This is a Heirloom extension and currently ignored.
 .It Ic \&mediasize Ar media
 Set the device media size.
 This is a Heirloom extension and currently ignored.


@@ -1335,7 +1348,7 @@ Currently unsupported.
 .It Ic \&nop Ar body
 Execute the rest of the input line as a request or macro line.
 Currently unsupported.
 .It Ic \&nop Ar body
 Execute the rest of the input line as a request or macro line.
 Currently unsupported.

-.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
+.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize

 Define or change a register.
 A register is an arbitrary string value that defines some sort of state,
 which influences parsing and/or formatting.
 Define or change a register.
 A register is an arbitrary string value that defines some sort of state,
 which influences parsing and/or formatting.


@@ -1347,6 +1360,14 @@ below.
 If it is prefixed by a sign, the register will be
 incremented or decremented instead of assigned to.
 .Pp
 If it is prefixed by a sign, the register will be
 incremented or decremented instead of assigned to.
 .Pp

+The
+.Ar stepsize
+is used by the
+.Ic \en+
+auto-increment feature.
+It remains unchanged when omitted while changing an existing register,
+and it defaults to 0 when defining a new register.
+.Pp

 The following
 .Ar register
 is handled specially:
 The following
 .Ar register
 is handled specially:


@@ -1428,8 +1449,15 @@ Currently ignored.
 Print all number registers on standard error output.
 Currently ignored.
 .It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset
 Print all number registers on standard error output.
 Currently ignored.
 .It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset

-Set horizontal page offset.
-Currently ignored.
+Set a horizontal page offset.
+If no argument is specified, the page offset is reverted to its
+previous value.
+If a sign is specified, the new page offset is calculated relative
+to the current one; otherwise, it is absolute.
+The argument follows the syntax of
+.Sx Scaling Widths
+and the default scaling unit is
+.Cm m .

 .It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size
 Change point size.
 Currently ignored.
 .It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size
 Change point size.
 Currently ignored.


@@ -1451,7 +1479,7 @@ This is a groff extension and currently ignored.
 .It Ic \&rchar Ar glyph ...
 Remove glyph definitions.
 Currently unsupported.
 .It Ic \&rchar Ar glyph ...
 Remove glyph definitions.
 Currently unsupported.

-.It Ic \&rd Op Ar prompt Op Ar agument ...
+.It Ic \&rd Op Ar prompt Op Ar argument ...

 Read from standard input.
 Currently ignored.
 .It Ic \&recursionlimit Ar maxrec maxtail
 Read from standard input.
 Currently ignored.
 .It Ic \&recursionlimit Ar maxrec maxtail


@@ -1470,12 +1498,23 @@ This is a Heirloom extension and currently ignored.
 Justify the next
 .Ar N
 input lines to the right margin without filling.
 Justify the next
 .Ar N
 input lines to the right margin without filling.

-Currently ignored.
+.Ar N
+defaults to 1.
+An argument of 0 or less ends right adjustment.

 .It Ic \&rm Ar macroname
 Remove a request, macro or string.
 .It Ic \&rn Ar oldname newname
 Rename a request, macro, diversion, or string.
 .It Ic \&rm Ar macroname
 Remove a request, macro or string.
 .It Ic \&rn Ar oldname newname
 Rename a request, macro, diversion, or string.

-Currently unsupported.
+In
+.Xr mandoc 1 ,
+user-defined macros,
+.Xr mdoc 7
+and
+.Xr man 7
+macros, and user-defined strings can be renamed, but renaming of
+predefined strings and of
+.Nm
+requests is not supported, and diversions are not implemented at all.

 .It Ic \&rnn Ar oldname newname
 Rename a number register.
 Currently unsupported.
 .It Ic \&rnn Ar oldname newname
 Rename a number register.
 Currently unsupported.


@@ -1767,7 +1806,7 @@ logical and (corresponds to C
 .Ic && )
 .It Ic \&:
 logical or (corresponds to C
 .Ic && )
 .It Ic \&:
 logical or (corresponds to C

-.Ic \&|| )
+.Ic || )

 .It Ic <?
 minimum (not available in C)
 .It Ic >?
 .It Ic <?
 minimum (not available in C)
 .It Ic >?


@@ -1823,7 +1862,7 @@ instead.
 .Sx Special Characters
 with two-letter names, see
 .Xr mandoc_char 7 .
 .Sx Special Characters
 with two-letter names, see
 .Xr mandoc_char 7 .

-.Ss \e*[ Ns Ar name ]
+.Ss \e* Ns Bq Ar name

 Interpolate the string with the
 .Ar name ;
 see
 Interpolate the string with the
 .Ar name ;
 see


@@ -1843,7 +1882,7 @@ Special character
 .Ss \e/
 Right italic correction (groff extension); ignored by
 .Xr mandoc 1 .
 .Ss \e/
 Right italic correction (groff extension); ignored by
 .Xr mandoc 1 .

-.Ss \e[ Ns Ar name ]
+.Ss \e Ns Bq Ar name

 .Sx Special Characters
 with names of arbitrary length, see
 .Xr mandoc_char 7 .
 .Sx Special Characters
 with names of arbitrary length, see
 .Xr mandoc_char 7 .


@@ -1899,14 +1938,14 @@ Move down by half a line; ignored by
 .Xr mandoc 1 .
 .Ss \ee
 Backslash special character.
 .Xr mandoc 1 .
 .Ss \ee
 Backslash special character.

-.Ss \eF[ Ns Ar name ]
+.Ss \eF Ns Bq Ar name

 Switch font family (groff extension); ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 .No \eF Ns Ar c
 and
 .No \eF( Ns Ar cc .
 Switch font family (groff extension); ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 .No \eF Ns Ar c
 and
 .No \eF( Ns Ar cc .

-.Ss \ef[ Ns Ar name ]
+.Ss \ef Ns Bq Ar name

 Switch to the font
 .Ar name ,
 see
 Switch to the font
 .Ar name ,
 see


@@ -1915,7 +1954,7 @@ For short names, there are variants
 .No \ef Ns Ar c
 and
 .No \ef( Ns Ar cc .
 .No \ef Ns Ar c
 and
 .No \ef( Ns Ar cc .

-.Ss \eg[ Ns Ar name ]
+.Ss \eg Ns Bq Ar name

 Interpolate the format of a number register; ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 Interpolate the format of a number register; ignored by
 .Xr mandoc 1 .
 For short names, there are variants


@@ -1925,10 +1964,14 @@ and
 .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
 Set the height of the current font; ignored by
 .Xr mandoc 1 .
 .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
 Set the height of the current font; ignored by
 .Xr mandoc 1 .

-.Ss \eh\(aq Ns Ar number Ns \(aq
-Horizontal motion; ignored by
-.Xr mandoc 1 .
-.Ss \ek[ Ns Ar name ]
+.Ss \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns \(aq
+Horizontal motion.
+If the vertical bar is given, the motion is relative to the current
+indentation.
+Otherwise, it is relative to the current position.
+The default scaling unit is
+.Cm m .
+.Ss \ek Ns Bq Ar name

 Mark horizontal input place in register; ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 Mark horizontal input place in register; ignored by
 .Xr mandoc 1 .
 For short names, there are variants


@@ -1938,17 +1981,19 @@ and
 .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
 Vertical line drawing function; ignored by
 .Xr mandoc 1 .
 .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
 Vertical line drawing function; ignored by
 .Xr mandoc 1 .

-.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
-Horizontal line drawing function; ignored by
-.Xr mandoc 1 .
-.Ss \eM[ Ns Ar name ]
+.Ss \el\(aq Ns Ar width Ns Oo Ar c Oc Ns \(aq
+Draw a horizontal line of
+.Ar width
+using the glyph
+.Ar c .
+.Ss \eM Ns Bq Ar name

 Set fill (background) color (groff extension); ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 .No \eM Ns Ar c
 and
 .No \eM( Ns Ar cc .
 Set fill (background) color (groff extension); ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 .No \eM Ns Ar c
 and
 .No \eM( Ns Ar cc .

-.Ss \em[ Ns Ar name ]
+.Ss \em Ns Bq Ar name

 Set glyph drawing color (groff extension); ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 Set glyph drawing color (groff extension); ignored by
 .Xr mandoc 1 .
 For short names, there are variants


@@ -1959,19 +2004,27 @@ and
 Character
 .Ar number
 on the current font.
 Character
 .Ar number
 on the current font.

-.Ss \en[ Ns Ar name ]
+.Ss \en Ns Oo +|- Oc Ns Bq Ar name

 Interpolate the number register
 .Ar name .
 For short names, there are variants
 .No \en Ns Ar c
 and
 .No \en( Ns Ar cc .
 Interpolate the number register
 .Ar name .
 For short names, there are variants
 .No \en Ns Ar c
 and
 .No \en( Ns Ar cc .

+If the optional sign is specified,
+the register is first incremented or decremented by the
+.Ar stepsize
+that was specified in the relevant
+.Ic \&nr
+request, and the changed value is interpolated.

 .Ss \eo\(aq Ns Ar string Ns \(aq
 Overstrike, writing all the characters contained in the
 .Ar string
 to the same output position.
 In terminal and HTML output modes,
 only the last one of the characters is visible.
 .Ss \eo\(aq Ns Ar string Ns \(aq
 Overstrike, writing all the characters contained in the
 .Ar string
 to the same output position.
 In terminal and HTML output modes,
 only the last one of the characters is visible.

+.Ss \ep
+Break the output line at the end of the current word.

 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
 Set number register; ignored by
 .Xr mandoc 1 .
 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
 Set number register; ignored by
 .Xr mandoc 1 .


@@ -1984,9 +2037,9 @@ Change point size; ignored by
 Alternative forms
 .No \es Ns Oo +|- Oc Ns Ar n ,
 .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
 Alternative forms
 .No \es Ns Oo +|- Oc Ns Ar n ,
 .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,

-.No \es Ns [ Oo +|- Oc Ns Ar number ] ,
+.No \es Ns Bq Oo +|- Oc Ns Ar number ,

 and
 and

-.No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
+.No \es Ns Oo +|- Oc Ns Bq Ar number

 are also parsed and ignored.
 .Ss \et
 Horizontal tab; ignored by
 are also parsed and ignored.
 .Ss \et
 Horizontal tab; ignored by


@@ -1994,7 +2047,7 @@ Horizontal tab; ignored by
 .Ss \eu
 Move up by half a line; ignored by
 .Xr mandoc 1 .
 .Ss \eu
 Move up by half a line; ignored by
 .Xr mandoc 1 .

-.Ss \eV[ Ns Ar name ]
+.Ss \eV Ns Bq Ar name

 Interpolate an environment variable; ignored by
 .Xr mandoc 1 .
 For short names, there are variants
 Interpolate an environment variable; ignored by
 .Xr mandoc 1 .
 For short names, there are variants


@@ -2021,7 +2074,7 @@ as device control function; ignored in nroff mode and by
 .Ss \ex\(aq Ns Ar number Ns \(aq
 Extra line space function; ignored by
 .Xr mandoc 1 .
 .Ss \ex\(aq Ns Ar number Ns \(aq
 Extra line space function; ignored by
 .Xr mandoc 1 .

-.Ss \eY[ Ns Ar name ]
+.Ss \eY Ns Bq Ar name

 Output a string as a device control function; ignored in nroff mode and by
 .Xr mandoc 1 .
 For short names, there are variants
 Output a string as a device control function; ignored in nroff mode and by
 .Xr mandoc 1 .
 For short names, there are variants