version 1.5, 2023/10/23 10:56:55 |
version 1.6, 2023/10/23 14:46:22 |
Line 80 that can be used as quoting characters. |
|
Line 80 that can be used as quoting characters. |
|
.El |
.El |
.Pp |
.Pp |
Upon function entry, |
Upon function entry, |
.Fa end |
.Pf * Fa end |
is expected to point to the escape sequence identifier. |
is expected to point to the escape sequence identifier. |
The values passed in as |
The values passed in as |
.Fa start |
.Pf * Fa start |
and |
and |
.Fa sz |
.Pf * Fa sz |
are ignored and overwritten. |
are ignored and overwritten. |
.Pp |
.Pp |
By design, this function cannot handle those |
By design, this function cannot handle those |
Line 102 and numerical expression control |
|
Line 102 and numerical expression control |
|
These are handled by |
These are handled by |
.Fn roff_expand , |
.Fn roff_expand , |
a private preprocessor function called from |
a private preprocessor function called from |
.Fn roff_parseln , |
.Fn roff_parseln |
|
and |
|
.Fn roff_getarg , |
see the file |
see the file |
.Pa roff.c . |
.Pa roff.c . |
.Pp |
.Pp |
|
|
recursively by itself, because some escape sequence arguments can |
recursively by itself, because some escape sequence arguments can |
in turn contain other escape sequences, |
in turn contain other escape sequences, |
.It |
.It |
for error detection internally by the |
for parsing and error detection internally by the |
.Xr roff 7 |
.Xr roff 7 |
parser part of the |
parser part of the |
.Xr mandoc 3 |
.Xr mandoc 3 |
library, see the file |
library, see the file |
.Pa roff.c , |
.Pa roff.c , |
.It |
.It |
|
occasionally by high-level parser and validation modules when they |
|
need to skip escape sequences while scanning the input, see the files |
|
.Pa mdoc.c , |
|
.Pa man.c , |
|
.Pa man_validate.c , |
|
.Pa eqn.c , |
|
and |
|
.Pa tbl_data.c |
|
.It |
above all externally by the |
above all externally by the |
.Xr mandoc 1 |
.Xr mandoc 1 |
formatting modules, in particular |
formatting modules, in particular |
Line 139 to purge escape sequences from text. |
|
Line 150 to purge escape sequences from text. |
|
.El |
.El |
.Sh RETURN VALUES |
.Sh RETURN VALUES |
Upon function return, the pointer |
Upon function return, the pointer |
.Fa end |
.Pf * Fa end |
is set to the character after the end of the escape sequence, |
is set to the character after the end of the escape sequence, |
such that the calling higher-level parser can easily continue. |
such that the calling higher-level parser can easily continue. |
.Pp |
.Pp |
For escape sequences taking an argument, the pointer |
For escape sequences taking an argument, the pointer |
.Fa start |
.Pf * Fa start |
is set to the beginning of the argument and |
is set to the beginning of the argument and |
.Fa sz |
.Pf * Fa sz |
is set to the length of the argument. |
is set to the length of the argument. |
For escape sequences not taking an argument, |
For escape sequences not taking an argument, |
.Fa start |
.Pf * Fa start |
is set to the character after the end of the sequence and |
is set to the character after the end of the sequence and |
.Fa sz |
.Pf * Fa sz |
is set to 0. |
is set to 0. |
Both |
Both |
.Fa start |
.Fa start |
Line 165 For sequences taking an argument, the function |
|
Line 176 For sequences taking an argument, the function |
|
.Fn mandoc_escape |
.Fn mandoc_escape |
returns one of the following values: |
returns one of the following values: |
.Bl -tag -width 2n |
.Bl -tag -width 2n |
|
.It Dv ESCAPE_DEVICE |
|
The escape sequence |
|
.Ic \e*(.T |
|
or |
|
.Ic \e*[.T] . |
.It Dv ESCAPE_FONT |
.It Dv ESCAPE_FONT |
The escape sequence |
The escape sequence |
.Ic \ef |
.Ic \ef |
Line 183 More specific values are returned for the most commonl |
|
Line 199 More specific values are returned for the most commonl |
|
.It Cm P Ta Dv ESCAPE_FONTPREV |
.It Cm P Ta Dv ESCAPE_FONTPREV |
.It Cm BI Ta Dv ESCAPE_FONTBI |
.It Cm BI Ta Dv ESCAPE_FONTBI |
.El |
.El |
|
.It Dv ESCAPE_HLINE |
|
The escape sequence |
|
.Ic \eh |
|
followed by an argument delimited by an arbitrary character. |
|
.It Dv ESCAPE_HORIZ |
|
The escape sequence |
|
.Ic \el |
|
followed by an argument delimited by an arbitrary character. |
|
.It Dv ESCAPE_NUMBERED |
|
The escape sequence |
|
.Ic \eN |
|
followed by a delimited argument. |
|
The delimiter character is arbitrary except that digits cannot be used. |
|
If a digit is encountered instead of the opening delimiter, that |
|
digit is considered to be the argument and the end of the sequence, and |
|
.Dv ESCAPE_IGNORE |
|
is returned. |
|
.Pp |
|
Such ASCII character escape sequences can be rendered using the function |
|
.Fn mchars_num2char |
|
described in the |
|
.Xr mchars_alloc 3 |
|
manual. |
|
.It Dv ESCAPE_OVERSTRIKE |
|
The escape sequence |
|
.Ic \eo |
|
followed by an argument delimited by an arbitrary character. |
.It Dv ESCAPE_SPECIAL |
.It Dv ESCAPE_SPECIAL |
The escape sequence |
The escape sequence |
.Ic \eC |
.Ic \eC |
Line 225 are hexadecimal digits and |
|
Line 268 are hexadecimal digits and |
|
is not zero: |
is not zero: |
.Ic \eC'u , \e[u . |
.Ic \eC'u , \e[u . |
As a special exception, |
As a special exception, |
.Fa start |
.Pf * Fa start |
is set to the character after the |
is set to the character after the |
.Ic u , |
.Ic u , |
and the |
and the |
.Fa sz |
.Pf * Fa sz |
return value does not include the |
return value does not include the |
.Ic u |
.Ic u |
either. |
either. |
Line 239 Such Unicode character escape sequences can be rendere |
|
Line 282 Such Unicode character escape sequences can be rendere |
|
described in the |
described in the |
.Xr mchars_alloc 3 |
.Xr mchars_alloc 3 |
manual. |
manual. |
.It Dv ESCAPE_NUMBERED |
|
The escape sequence |
|
.Ic \eN |
|
followed by a delimited argument. |
|
The delimiter character is arbitrary except that digits cannot be used. |
|
If a digit is encountered instead of the opening delimiter, that |
|
digit is considered to be the argument and the end of the sequence, and |
|
.Dv ESCAPE_IGNORE |
|
is returned. |
|
.Pp |
|
Such ASCII character escape sequences can be rendered using the function |
|
.Fn mchars_num2char |
|
described in the |
|
.Xr mchars_alloc 3 |
|
manual. |
|
.It Dv ESCAPE_OVERSTRIKE |
|
The escape sequence |
|
.Ic \eo |
|
followed by an argument delimited by an arbitrary character. |
|
.It Dv ESCAPE_IGNORE |
.It Dv ESCAPE_IGNORE |
|
Many escape sequences that |
|
.Xr mandoc 1 |
|
intends to ignore, in particular: |
.Bl -bullet -width 2n |
.Bl -bullet -width 2n |
.It |
.It |
The escape sequence |
The escape sequence |
|
|
.It |
.It |
The escape sequences |
The escape sequences |
.Ic \eF , |
.Ic \eF , |
.Ic \eg , |
|
.Ic \ek , |
.Ic \ek , |
.Ic \eM , |
.Ic \eM , |
.Ic \em , |
.Ic \em , |
.Ic \en , |
.Ic \eO , |
.Ic \eV , |
|
and |
and |
.Ic \eY |
.Ic \eY |
followed by an argument in standard form. |
followed by an argument in standard form. |
.It |
.It |
The escape sequences |
The escape sequences |
.Ic \eA , |
|
.Ic \eb , |
.Ic \eb , |
.Ic \eD , |
.Ic \eD , |
.Ic \eR , |
.Ic \eR , |
Line 298 followed by an argument delimited by an arbitrary char |
|
Line 322 followed by an argument delimited by an arbitrary char |
|
.It |
.It |
The escape sequences |
The escape sequences |
.Ic \eH , |
.Ic \eH , |
.Ic \eh , |
|
.Ic \eL , |
.Ic \eL , |
.Ic \el , |
|
.Ic \eS , |
.Ic \eS , |
.Ic \ev , |
.Ic \ev , |
and |
and |
Line 312 is found instead of a delimiter, the sequence is consi |
|
Line 334 is found instead of a delimiter, the sequence is consi |
|
with that character, and |
with that character, and |
.Dv ESCAPE_ERROR |
.Dv ESCAPE_ERROR |
is returned. |
is returned. |
|
.It |
|
The escape sequences |
|
.Ic \eO |
|
with a single-digit argument in the range from 1 to 4 inclusive. |
.El |
.El |
|
.It Dv ESCAPE_UNSUPP |
|
An escape sequence that |
|
.Xr mandoc 1 |
|
can parse, but for which formatting in unsupported, in particular |
|
.Qq \eO0 |
|
and |
|
.Qq \eO5 . |
.It Dv ESCAPE_ERROR |
.It Dv ESCAPE_ERROR |
Escape sequences taking an argument but not matching any of the above patterns. |
Escape sequences taking an argument |
|
where the actual argument contains a syntax error. |
In particular, that happens if the end of the logical input line |
In particular, that happens if the end of the logical input line |
is reached before the end of the argument. |
is reached before the end of the argument. |
.El |
.El |
Line 323 For sequences that do not take an argument, the functi |
|
Line 357 For sequences that do not take an argument, the functi |
|
.Fn mandoc_escape |
.Fn mandoc_escape |
returns one of the following values: |
returns one of the following values: |
.Bl -tag -width 2n |
.Bl -tag -width 2n |
.It Dv ESCAPE_SKIPCHAR |
.It Dv ESCAPE_BREAK |
The escape sequence |
The escape sequence |
.Qq \ez . |
.Qq \ep . |
|
.It Dv ESCAPE_IGNORE |
|
Many escape sequences including |
|
.Qq \e% , |
|
.Qq \e& , |
|
.Qq \e| , |
|
.Qq \ed , |
|
and |
|
.Qq \eu . |
.It Dv ESCAPE_NOSPACE |
.It Dv ESCAPE_NOSPACE |
The escape sequence |
The escape sequence |
.Qq \ec . |
.Qq \ec . |
.It Dv ESCAPE_IGNORE |
.It Dv ESCAPE_SKIPCHAR |
|
The escape sequence |
|
.Qq \ez . |
|
.It Dv ESCAPE_UNSUPP |
The escape sequences |
The escape sequences |
.Qq \ed |
.Qq \e! , |
|
.Qq \e? , |
and |
and |
.Qq \eu . |
.Qq \er . |
|
.It Dv ESCAPE_UNDEF |
|
Many escape sequences that other |
|
.Xr roff 7 |
|
implementations do not define either, for example |
|
.Qq \eG , |
|
.Qq \eI , |
|
.Qq \ei , |
|
.Qq \eJ , |
|
.Qq \ej , |
|
.Qq \eK , |
|
.Qq \eP , |
|
.Qq \eT , |
|
.Qq \eU , |
|
.Qq \eW , |
|
and |
|
.Qq \ey . |
.El |
.El |
.Sh FILES |
.Sh FILES |
This function is implemented in |
This function is implemented in |
Line 347 This function has been available since mandoc 1.11.2. |
|
Line 409 This function has been available since mandoc 1.11.2. |
|
.Sh AUTHORS |
.Sh AUTHORS |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org |
.Sh BUGS |
|
The function doesn't cleanly distinguish between sequences that are |
|
valid and supported, valid and ignored, valid and unsupported, |
|
syntactically invalid, or undefined. |
|
For sequences that are ignored or unsupported, it doesn't tell |
|
whether that deficiency is likely to cause major formatting problems |
|
and/or loss of document content. |
|
The function is already rather complicated and still parses some |
|
sequences incorrectly. |
|
. |
|
.ig |
|
For these sequences, the list given below specifies a starting string |
|
and either the length of the argument or an ending character. |
|
The argument starts after the starting string. |
|
In the former case, the sequence ends with the end of the argument. |
|
In the latter case, the argument ends before the ending character, |
|
and the sequence ends with the ending character. |
|
.. |
|