Mostly complete implementation of the 'c' (character available)

[mandoc.git] / roff.7

diff --git a/roff.7 b/roff.7
index e329f161cc00435d09b415f3a439df187d9308b5..5bf3ed25869da921129cb59a9db47a4126523eaa 100644 (file)
--- a/roff.7
+++ b/roff.7
@@ -1,7 +1,7 @@
-.\"    $Id: roff.7,v 1.87 2017/06/10 16:32:27 schwarze Exp $
+.\"    $Id: roff.7,v 1.101 2018/08/19 17:46:14 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: June 10 2017 $
+.Dd $Mdocdate: August 19 2018 $

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


@@ -86,13 +86,9 @@ character, and, in certain circumstances, the tab character.
 The backslash character
 .Sq \e
 indicates the start of an escape sequence, used for example for
 The backslash character
 .Sq \e
 indicates the start of an escape sequence, used for example for

-.Sx Comments ,
-.Sx Special Characters ,
-.Sx Predefined Strings ,
+.Sx Comments

 and
 and

-user-defined strings defined using the
-.Sx ds
-request.
+.Sx Special Characters .

 For a listing of escape sequences, consult the
 .Sx ESCAPE SEQUENCE REFERENCE
 below.
 For a listing of escape sequences, consult the
 .Sx ESCAPE SEQUENCE REFERENCE
 below.


@@ -169,34 +165,6 @@ Text decoration is
 recommended for
 .Xr mdoc 7 ,
 which encourages semantic annotation.
 recommended for
 .Xr mdoc 7 ,
 which encourages semantic annotation.

-.Ss Predefined Strings
-Predefined strings, like
-.Sx Special Characters ,
-mark special output glyphs.
-Predefined strings are escaped with the slash-asterisk,
-.Sq \e* :
-single-character
-.Sq \e*X ,
-two-character
-.Sq \e*(XX ,
-and N-character
-.Sq \e*[N] .
-.Pp
-Examples:
-.Bl -tag -width Ds -offset indent -compact
-.It Li \e*(Am
-Two-letter ampersand predefined string.
-.It Li \e*q
-One-letter double-quote predefined string.
-.El
-.Pp
-Predefined strings are not recommended for use,
-as they differ across implementations.
-Those supported by
-.Xr mandoc 1
-are listed in
-.Xr mandoc_char 7 .
-Manuals using these predefined strings are almost certainly not portable.

 .Ss Whitespace
 Whitespace consists of the space character.
 In text lines, whitespace is preserved within a line.
 .Ss Whitespace
 Whitespace consists of the space character.
 In text lines, whitespace is preserved within a line.


@@ -206,7 +174,7 @@ Unescaped trailing spaces are stripped from text line input unless in a
 literal context.
 In general, trailing whitespace on any input line is discouraged for
 reasons of portability.
 literal context.
 In general, trailing whitespace on any input line is discouraged for
 reasons of portability.

-In the rare case that a blank character is needed at the end of an
+In the rare case that a space character is needed at the end of an

 input line, it may be forced by
 .Sq \e\ \e& .
 .Pp
 input line, it may be forced by
 .Sq \e\ \e& .
 .Pp


@@ -412,7 +380,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


@@ -666,7 +633,7 @@ produces
 .Pp
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 Each occurrence of \e\e$* is replaced with all the arguments,
 .Pp
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 Each occurrence of \e\e$* is replaced with all the arguments,

-joined together with single blank characters.
+joined together with single space characters.

 .Pp
 Since macros and user-defined strings share a common string table,
 defining a macro
 .Pp
 Since macros and user-defined strings share a common string table,
 defining a macro


@@ -923,15 +890,15 @@ The following
 .Ar font
 arguments are supported:
 .Bl -tag -width 4n -offset indent
 .Ar font
 arguments are supported:
 .Bl -tag -width 4n -offset indent

-.It Cm B , BI , 3 , 4
+.It Cm B , BI , CB , 3 , 4

 switches to
 .Sy bold
 font
 switches to
 .Sy bold
 font

-.It Cm I , 2
+.It Cm I , CI , 2

 switches to
 .Em underlined
 font
 switches to
 .Em underlined
 font

-.It Cm R , CW , 1
+.It Cm R , CR , CW , 1

 switches to normal font
 .It Cm P No "or no argument"
 switches back to the previous font
 switches to normal font
 .It Cm P No "or no argument"
 switches back to the previous font


@@ -1038,15 +1005,13 @@ is
 or
 .Sq o
 .Pq odd page ,
 or
 .Sq o
 .Pq odd page ,

-it evaluates to true.
+it evaluates to true, and the
+.Ar body
+starts with the next character.

 .It
 If the first character of
 .Ar condition
 is
 .It
 If the first character of
 .Ar condition
 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,7 +1019,29 @@ is
 or
 .Sq v
 .Pq vroff mode ,
 or
 .Sq v
 .Pq vroff mode ,

-it evaluates to false.
+it evaluates to false, and the
+.Ar body
+starts with the next character.
+.It
+If the first character of
+.Ar condition
+is
+.Sq c
+.Pq character available ,
+it evaluates to true if the following character is an ASCII character
+or a valid character escape sequence, or to false otherwise.
+The
+.Ar body
+starts with the character following that next character.
+.It
+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
 .It
 If the first character of
 .Ar condition


@@ -1340,9 +1327,12 @@ Currently unsupported.
 Temporarily turn off line numbering.
 Currently unsupported.
 .It Ic \&nop Ar body
 Temporarily turn off line numbering.
 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
+Execute the rest of the input line as a request, macro, or text line,
+skipping the
+.Ic \&nop
+request and any space characters immediately following it.
+This is mostly used to indent text lines inside macro definitions.
+.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.


@@ -1354,6 +1344,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:


@@ -1435,8 +1433,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.


@@ -1458,7 +1463,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


@@ -1477,7 +1482,9 @@ 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
 .It Ic \&rm Ar macroname
 Remove a request, macro or string.
 .It Ic \&rn Ar oldname newname


@@ -1825,6 +1832,12 @@ is an unpaddable space-sized non-breaking space character; see
 .Ss \e\(dq
 The rest of the input line is treated as
 .Sx Comments .
 .Ss \e\(dq
 The rest of the input line is treated as
 .Sx Comments .

+.Ss \e#
+Line continuation with comment.
+Discard the rest of the physical input line and continue the logical
+input line on the next physical input line, joining the text on
+both lines together as if it were on a single input line.
+This is a groff extension.

 .Ss \e%
 Hyphenation allowed at this point of the word; ignored by
 .Xr mandoc 1 .
 .Ss \e%
 Hyphenation allowed at this point of the word; ignored by
 .Xr mandoc 1 .


@@ -1839,17 +1852,32 @@ 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
 Interpolate the string with the

-.Ar name ;
-see
-.Sx Predefined Strings
-and
-.Sx ds .
+.Ar name .

 For short names, there are variants
 .No \e* Ns Ar c
 and
 .No \e*( Ns Ar cc .
 For short names, there are variants
 .No \e* Ns Ar c
 and
 .No \e*( Ns Ar cc .

+.Pp
+One string is predefined on the
+.Nm
+language level: \e*(.T expands to the name of the output device,
+for example ascii, utf8, ps, pdf, html, or markdown.
+.Pp
+Macro sets traditionally predefine additional strings which are not
+portable and differ across implementations.
+Those supported by
+.Xr mandoc 1
+are listed in
+.Xr mandoc_char 7 .
+.Pp
+Strings can be defined, changed, and deleted with the
+.Ic \&ds ,
+.Ic \&as ,
+and
+.Ic \&rm
+requests.

 .Ss \e,
 Left italic correction (groff extension); ignored by
 .Xr mandoc 1 .
 .Ss \e,
 Left italic correction (groff extension); ignored by
 .Xr mandoc 1 .


@@ -1859,7 +1887,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 .


@@ -1915,14 +1943,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


@@ -1931,7 +1959,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


@@ -1941,11 +1969,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 width Ns \(aq
-Horizontal motion relative to the current position.
+.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 .
 The default scaling unit is
 .Cm m .

-.Ss \ek[ Ns Ar name ]
+.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


@@ -1960,14 +1991,14 @@ Draw a horizontal line of
 .Ar width
 using the glyph
 .Ar c .
 .Ar width
 using the glyph
 .Ar c .

-.Ss \eM[ Ns Ar name ]
+.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


@@ -1978,19 +2009,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 .


@@ -2003,9 +2042,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


@@ -2013,7 +2052,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


@@ -2040,7 +2079,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