diff options
Diffstat (limited to 'contrib/mdocml/roff.7')
| -rw-r--r-- | contrib/mdocml/roff.7 | 305 |
1 files changed, 235 insertions, 70 deletions
diff --git a/contrib/mdocml/roff.7 b/contrib/mdocml/roff.7 index 48e16dd..bc2f24e 100644 --- a/contrib/mdocml/roff.7 +++ b/contrib/mdocml/roff.7 @@ -1,7 +1,7 @@ -.\" $Id: roff.7,v 1.46 2013/12/26 02:43:18 schwarze Exp $ +.\" $Id: roff.7,v 1.55 2014/07/07 11:35:06 schwarze Exp $ .\" .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2010, 2011, 2013, 2014 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 @@ -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. .\" -.Dd $Mdocdate: December 26 2013 $ +.Dd $Mdocdate: July 7 2014 $ .Dt ROFF 7 .Os .Sh NAME @@ -409,24 +409,27 @@ and the number of arguments is not checked. Append to a macro definition. The syntax of this request is the same as that of .Sx \&de . -It is currently ignored by -.Xr mandoc 1 , -as are its children. .Ss \&ami Append to a macro definition, specifying the macro name indirectly. The syntax of this request is the same as that of .Sx \&dei . -It is currently ignored by -.Xr mandoc 1 , -as are its children. .Ss \&am1 Append to a macro definition, switching roff compatibility mode off during macro execution. The syntax of this request is the same as that of .Sx \&de1 . -It is currently ignored by -.Xr mandoc 1 , -as are its children. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&am . +.Ss \&as +Append to a user-defined string. +The syntax of this request is the same as that of +.Sx \&ds . +If a user-defined string with the specified name does not yet exist, +it is set to the empty string before appending. .Ss \&cc Changes the control character. Its syntax is as follows: @@ -439,6 +442,12 @@ If is not specified, the control character is reset to .Sq \&. . Trailing characters are ignored. +.Ss \&ce +Center some lines. +This line-scoped request is intended to take one integer argument, +specifying how many lines to center. +Currently, it is ignored including its arguments, and the number +of arguments is not checked. .Ss \&de Define a .Nm @@ -542,9 +551,13 @@ Define a macro, specifying the macro name indirectly. The syntax of this request is the same as that of .Sx \&de . -It is currently ignored by -.Xr mandoc 1 , -as are its children. +The request +.Pp +.D1 Pf . Cm \&dei Ar name Op Ar end +.Pp +has the same effect as: +.Pp +.D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end .Ss \&de1 Define a .Nm @@ -647,6 +660,34 @@ This line-scoped request is intended to have one argument specifying the font family to be selected. It is a groff extension, and currently, it is ignored including its arguments, and the number of arguments is not checked. +.Ss \&ft +Change the font. +Its syntax is as follows: +.Pp +.D1 Pf . Cm \&ft Op Ar font +.Pp +The following +.Ar font +arguments are supported: +.Bl -tag -width 4n -offset indent +.It Cm B , BI , 3 , 4 +switches to +.Sy bold +font +.It Cm I , 2 +switches to +.Em underlined +font +.It Cm R , CW , 1 +switches to normal font +.It Cm P No "or no argument" +switches back to the previous font +.El +.Pp +This request takes effect only locally, may be overridden by macros +and escape sequences, and is only supported in +.Xr man 7 +for now. .Ss \&hw Specify hyphenation points in words. This line-scoped request is currently ignored. @@ -665,10 +706,67 @@ Its syntax is equivalent to .Sx \&if . .Ss \&if Begins a conditional. -Right now, the conditional evaluates to true -if and only if it starts with the letter -.Sy n , -indicating processing in nroff style as opposed to troff style. +This request has the following syntax: +.Bd -literal -offset indent +\&.if COND BODY +.Ed +.Bd -literal -offset indent +\&.if COND \e{BODY +BODY...\e} +.Ed +.Bd -literal -offset indent +\&.if COND \e{\e +BODY... +\&.\e} +.Ed +.Pp +COND is a conditional statement. +Currently, +.Xr mandoc 1 +supports the following subset of roff conditionals: +.Bl -bullet +.It +If +.Sq \&! +is prefixed to COND, the condition is logically inverted. +.It +If the first character of COND is +.Sq n +.Pq nroff mode +or +.Sq o +.Pq odd page , +COND evaluates to true. +.It +If the first character of COND is +.Sq c +.Pq character available , +.Sq d +.Pq string defined , +.Sq e +.Pq even page , +.Sq r +.Pq register accessed , +or +.Sq t +.Pq troff mode , +COND evaluates to false. +.It +If COND starts with a parenthesis or with an optionally signed +integer number, it is evaluated according to the rules of +.Sx Numerical expressions +explained below. +It evaluates to true if the the result is positive, +or to false if the result is zero or negative. +.It +Otherwise, the first character of COND is regarded as a delimiter +and COND evaluates to true if the string extending from its first +to its second occurrence is equal to the string extending from its +second to its third occurrence. +.It +If COND cannot be parsed, it evaluates to false. +.El +.Pp If a conditional is false, its children are not processed, but are syntactically interpreted to preserve the integrity of the input document. @@ -686,44 +784,12 @@ will continue to syntactically interpret to the block close of the final conditional. Sub-conditionals, in this case, obviously inherit the truth value of the parent. -This request has the following syntax: -.Bd -literal -offset indent -\&.if COND \e{\e -BODY... -\&.\e} -.Ed -.Bd -literal -offset indent -\&.if COND \e{ BODY -BODY... \e} -.Ed -.Bd -literal -offset indent -\&.if COND \e{ BODY -BODY... -\&.\e} -.Ed -.Bd -literal -offset indent -\&.if COND \e -BODY -.Ed -.Pp -COND is a conditional statement. -roff allows for complicated conditionals; mandoc is much simpler. -At this time, mandoc supports only -.Sq n , -evaluating to true; -and -.Sq t , -.Sq e , -and -.Sq o , -evaluating to false. -All other invocations are read up to the next end of line or space and -evaluate as false. .Pp If the BODY section is begun by an escaped brace .Sq \e{ , -scope continues until a closing-brace escape sequence -.Sq \.\e} . +scope continues until the end of the input line containing the +matching closing-brace escape sequence +.Sq \e} . If the BODY is not enclosed in braces, scope continues until the end of the line. If the COND is followed by a BODY on the same line, whether after a @@ -803,6 +869,23 @@ Otherwise, it only terminates the and arguments following it or the .Sq \&.. request are discarded. +.Ss \&ll +Change the output line length. +Its syntax is as follows: +.Pp +.D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width +.Pp +If the +.Ar width +argument is omitted, the line length is reset to its previous value. +The default setting for terminal output is 78n. +If a sign is given, the line length is added to or subtracted from; +otherwise, it is set to the provided value. +Using this request in new manuals is discouraged for several reasons, +among others because it overrides the +.Xr mandoc 1 +.Fl O Cm width +command line option. .Ss \&ne Declare the need for the specified minimum vertical space before the next trap or the bottom of the page. @@ -810,23 +893,19 @@ This line-scoped request is currently ignored. .Ss \&nh Turn off automatic hyphenation mode. This line-scoped request is currently ignored. -.Ss \&rm -Remove a request, macro or string. -This request is intended to have one argument, -the name of the request, macro or string to be undefined. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. .Ss \&nr Define or change a register. A register is an arbitrary string value that defines some sort of state, which influences parsing and/or formatting. Its syntax is as follows: .Pp -.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value +.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression .Pp -The -.Ar value -may, at the moment, only be an integer. +For the syntax of +.Ar expression , +see +.Sx Numerical expressions +below. If it is prefixed by a sign, the register will be incremented or decremented instead of assigned to. .Pp @@ -861,6 +940,16 @@ Change point size. This line-scoped request is intended to take one numerical argument. Currently, it is ignored including its arguments, and the number of arguments is not checked. +.Ss \&rm +Remove a request, macro or string. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&rm Ar name +.Ss \&rr +Remove a register. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&rr Ar name .Ss \&so Include a source file. Its syntax is as follows: @@ -929,6 +1018,73 @@ Begin a table, which formats input in aligned rows and columns. See .Xr tbl 7 for a description of the tbl language. +.Ss Numerical expressions +The +.Sx \&nr , +.Sx \&if , +and +.Sx \&ie +requests accept integer numerical expressions as arguments. +These are always evaluated using the C +.Vt int +type; integer overflow works the same way as in the C language. +Numbers consist of an arbitrary number of digits +.Sq 0 +to +.Sq 9 +prefixed by an optional sign +.Sq + +or +.Sq - . +.Pp +The following binary operators are implemented. +Unless otherwise stated, they behave as in the C language: +.Pp +.Bl -tag -width 2n -compact +.It Ic + +addition +.It Ic - +subtraction +.It Ic * +multiplication +.It Ic / +division +.It Ic % +remainder of division +.It Ic < +less than +.It Ic > +greater than +.It Ic == +equal to +.It Ic = +equal to, same effect as +.Ic == +(this differs from C) +.It Ic <= +less than or equal to +.It Ic >= +greater than or equal to +.It Ic <> +not equal to (corresponds to C +.Ic != ; +this one is of limited portability, it is supported by Heirloom roff, +but not by groff) +.It Ic & +logical and (corresponds to C +.Ic && ) +.It Ic \&: +logical or (corresponds to C +.Ic \&|| ) +.It Ic <? +minimum (not available in C) +.It Ic >? +maximum (not available in C) +.El +.Pp +There is no concept of precendence; evaluation proceeds from left to right, +except when subexpressions are enclosed in parantheses. +Inside parentheses, whitespace is ignored. .Sh ESCAPE SEQUENCE REFERENCE The .Xr mandoc 1 @@ -1017,10 +1173,15 @@ Digit width space character. Anchor definition; ignored by .Xr mandoc 1 . .Ss \eB\(aq Ns Ar string Ns \(aq -Test whether +Interpolate +.Sq 1 +if .Ar string -is a numerical expession; ignored by -.Xr mandoc 1 . +conforms to the syntax of +.Sx Numerical expressions +explained above and +.Sq 0 +otherwise. .Ss \eb\(aq Ns Ar string Ns \(aq Bracket building function; ignored by .Xr mandoc 1 . @@ -1144,9 +1305,13 @@ Vertical motion; ignored by .Xr mandoc 1 . .Ss \ew\(aq Ns Ar string Ns \(aq Interpolate the width of the -.Ar string ; -ignored by -.Xr mandoc 1 . +.Ar string . +The +.Xr mandoc 1 +implementation assumes that after expansion of user-defined strings, the +.Ar string +only contains normal characters, no escape sequences, and that each +character has a width of 24 basic units. .Ss \eX\(aq Ns Ar string Ns \(aq Output .Ar string |
