1 .\"
   2 .\" Permission to use, copy, modify, and distribute this software for any
   3 .\" purpose with or without fee is hereby granted, provided that the above
   4 .\" copyright notice and this permission notice appear in all copies.
   5 .\"
   6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  13 .\"
  14 .\"
  15 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  16 .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
  17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
  18 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  19 .\"
  20 .Dd Jul 13, 2014
  21 .Dt MANDOC_ROFF 5
  22 .Os
  23 .Sh NAME
  24 .Nm mandoc_roff
  25 .Nd roff language reference for mandoc
  26 .Sh DESCRIPTION
  27 The
  28 .Nm roff
  29 language is a general purpose text formatting language.
  30 Since traditional implementations of the
  31 .Xr mdoc 5
  32 and
  33 .Xr man 5
  34 manual formatting languages are based on it,
  35 many real-world manuals use small numbers of
  36 .Nm
  37 requests intermixed with their
  38 .Xr mdoc 5
  39 or
  40 .Xr man 5
  41 code.
  42 To properly format such manuals, the
  43 .Xr mandoc 1
  44 utility supports a tiny subset of
  45 .Nm
  46 requests.
  47 Only these requests supported by
  48 .Xr mandoc 1
  49 are documented in the present manual,
  50 together with the basic language syntax shared by
  51 .Nm ,
  52 .Xr mdoc 5 ,
  53 and
  54 .Xr man 5 .
  55 For complete
  56 .Nm
  57 manuals, consult the
  58 .Sx SEE ALSO
  59 section.
  60 .Pp
  61 Input lines beginning with the control character
  62 .Sq \&.
  63 are parsed for requests and macros.
  64 Such lines are called
  65 .Dq request lines
  66 or
  67 .Dq macro lines ,
  68 respectively.
  69 Requests change the processing state and manipulate the formatting;
  70 some macros also define the document structure and produce formatted
  71 output.
  72 The single quote
  73 .Pq Qq \(aq
  74 is accepted as an alternative control character,
  75 treated by
  76 .Xr mandoc 1
  77 just like
  78 .Ql \&.
  79 .Pp
  80 Lines not beginning with control characters are called
  81 .Dq text lines .
  82 They provide free-form text to be printed; the formatting of the text
  83 depends on the respective processing context.
  84 .Sh LANGUAGE SYNTAX
  85 .Nm
  86 documents may contain only graphable 7-bit ASCII characters, the space
  87 character, and, in certain circumstances, the tab character.
  88 The back-space character
  89 .Sq \e
  90 indicates the start of an escape sequence for
  91 .Sx Comments ,
  92 .Sx Special Characters ,
  93 .Sx Predefined Strings ,
  94 and
  95 user-defined strings defined using the
  96 .Sx ds
  97 request.
  98 .Ss Comments
  99 Text following an escaped double-quote
 100 .Sq \e\(dq ,
 101 whether in a request, macro, or text line, is ignored to the end of the line.
 102 A request line beginning with a control character and comment escape
 103 .Sq \&.\e\(dq
 104 is also ignored.
 105 Furthermore, request lines with only a control character and optional
 106 trailing whitespace are stripped from input.
 107 .Pp
 108 Examples:
 109 .Bd -literal -offset indent -compact
 110 \&.\e\(dq This is a comment line.
 111 \&.\e\(dq The next line is ignored:
 112 \&.
 113 \&.Sh EXAMPLES \e\(dq This is a comment, too.
 114 \&example text \e\(dq And so is this.
 115 .Ed
 116 .Ss Special Characters
 117 Special characters are used to encode special glyphs and are rendered
 118 differently across output media.
 119 They may occur in request, macro, and text lines.
 120 Sequences begin with the escape character
 121 .Sq \e
 122 followed by either an open-parenthesis
 123 .Sq \&(
 124 for two-character sequences; an open-bracket
 125 .Sq \&[
 126 for n-character sequences (terminated at a close-bracket
 127 .Sq \&] ) ;
 128 or a single one character sequence.
 129 .Pp
 130 Examples:
 131 .Bl -tag -width Ds -offset indent -compact
 132 .It Li \e(em
 133 Two-letter em dash escape.
 134 .It Li \ee
 135 One-letter backslash escape.
 136 .El
 137 .Pp
 138 See
 139 .Xr mandoc_char 5
 140 for a complete list.
 141 .Ss Text Decoration
 142 Terms may be text-decorated using the
 143 .Sq \ef
 144 escape followed by an indicator: B (bold), I (italic), R (regular), or P
 145 (revert to previous mode).
 146 A numerical representation 3, 2, or 1 (bold, italic, and regular,
 147 respectively) may be used instead.
 148 The indicator or numerical representative may be preceded by C
 149 (constant-width), which is ignored.
 150 .Pp
 151 Examples:
 152 .Bl -tag -width Ds -offset indent -compact
 153 .It Li \efBbold\efR
 154 Write in bold, then switch to regular font mode.
 155 .It Li \efIitalic\efP
 156 Write in italic, then return to previous font mode.
 157 .El
 158 .Pp
 159 Text decoration is
 160 .Em not
 161 recommended for
 162 .Xr mdoc 5 ,
 163 which encourages semantic annotation.
 164 .Ss Predefined Strings
 165 Predefined strings, like
 166 .Sx Special Characters ,
 167 mark special output glyphs.
 168 Predefined strings are escaped with the slash-asterisk,
 169 .Sq \e* :
 170 single-character
 171 .Sq \e*X ,
 172 two-character
 173 .Sq \e*(XX ,
 174 and N-character
 175 .Sq \e*[N] .
 176 .Pp
 177 Examples:
 178 .Bl -tag -width Ds -offset indent -compact
 179 .It Li \e*(Am
 180 Two-letter ampersand predefined string.
 181 .It Li \e*q
 182 One-letter double-quote predefined string.
 183 .El
 184 .Pp
 185 Predefined strings are not recommended for use,
 186 as they differ across implementations.
 187 Those supported by
 188 .Xr mandoc 1
 189 are listed in
 190 .Xr mandoc_char 5 .
 191 Manuals using these predefined strings are almost certainly not portable.
 192 .Ss Whitespace
 193 Whitespace consists of the space character.
 194 In text lines, whitespace is preserved within a line.
 195 In request and macro lines, whitespace delimits arguments and is discarded.
 196 .Pp
 197 Unescaped trailing spaces are stripped from text line input unless in a
 198 literal context.
 199 In general, trailing whitespace on any input line is discouraged for
 200 reasons of portability.
 201 In the rare case that a blank character is needed at the end of an
 202 input line, it may be forced by
 203 .Sq \e\ \e& .
 204 .Pp
 205 Literal space characters can be produced in the output
 206 using escape sequences.
 207 In macro lines, they can also be included in arguments using quotation; see
 208 .Sx MACRO SYNTAX
 209 for details.
 210 .Pp
 211 Blank text lines, which may include whitespace, are only permitted
 212 within literal contexts.
 213 If the first character of a text line is a space, that line is printed
 214 with a leading newline.
 215 .Ss Scaling Widths
 216 Many requests and macros support scaled widths for their arguments.
 217 The syntax for a scaled width is
 218 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
 219 where a decimal must be preceded or followed by at least one digit.
 220 Negative numbers, while accepted, are truncated to zero.
 221 .Pp
 222 The following scaling units are accepted:
 223 .Pp
 224 .Bl -tag -width Ds -offset indent -compact
 225 .It c
 226 centimetre
 227 .It i
 228 inch
 229 .It P
 230 pica (~1/6 inch)
 231 .It p
 232 point (~1/72 inch)
 233 .It f
 234 synonym for
 235 .Sq u
 236 .It v
 237 default vertical span
 238 .It m
 239 width of rendered
 240 .Sq m
 241 .Pq em
 242 character
 243 .It n
 244 width of rendered
 245 .Sq n
 246 .Pq en
 247 character
 248 .It u
 249 default horizontal span
 250 .It M
 251 mini-em (~1/100 em)
 252 .El
 253 .Pp
 254 Using anything other than
 255 .Sq m ,
 256 .Sq n ,
 257 .Sq u ,
 258 or
 259 .Sq v
 260 is necessarily non-portable across output media.
 261 See
 262 .Sx COMPATIBILITY .
 263 .Pp
 264 If a scaling unit is not provided, the numerical value is interpreted
 265 under the default rules of
 266 .Sq v
 267 for vertical spaces and
 268 .Sq u
 269 for horizontal ones.
 270 .Pp
 271 Examples:
 272 .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
 273 .It Li \&.Bl -tag -width 2i
 274 two-inch tagged list indentation in
 275 .Xr mdoc 5
 276 .It Li \&.HP 2i
 277 two-inch tagged list indentation in
 278 .Xr man 5
 279 .It Li \&.sp 2v
 280 two vertical spaces
 281 .El
 282 .Ss Sentence Spacing
 283 Each sentence should terminate at the end of an input line.
 284 By doing this, a formatter will be able to apply the proper amount of
 285 spacing after the end of sentence (unescaped) period, exclamation mark,
 286 or question mark followed by zero or more non-sentence closing
 287 delimiters
 288 .Po
 289 .Sq \&) ,
 290 .Sq \&] ,
 291 .Sq \&' ,
 292 .Sq \&"
 293 .Pc .
 294 .Pp
 295 The proper spacing is also intelligently preserved if a sentence ends at
 296 the boundary of a macro line.
 297 .Pp
 298 Examples:
 299 .Bd -literal -offset indent -compact
 300 Do not end sentences mid-line like this.  Instead,
 301 end a sentence like this.
 302 A macro would end like this:
 303 \&.Xr mandoc 1 \&.
 304 .Ed
 305 .Sh REQUEST SYNTAX
 306 A request or macro line consists of:
 307 .Pp
 308 .Bl -enum -compact
 309 .It
 310 the control character
 311 .Sq \&.
 312 or
 313 .Sq \(aq
 314 at the beginning of the line,
 315 .It
 316 optionally an arbitrary amount of whitespace,
 317 .It
 318 the name of the request or the macro, which is one word of arbitrary
 319 length, terminated by whitespace,
 320 .It
 321 and zero or more arguments delimited by whitespace.
 322 .El
 323 .Pp
 324 Thus, the following request lines are all equivalent:
 325 .Bd -literal -offset indent
 326 \&.ig end
 327 \&.ig    end
 328 \&.   ig end
 329 .Ed
 330 .Sh MACRO SYNTAX
 331 Macros are provided by the
 332 .Xr mdoc 5
 333 and
 334 .Xr man 5
 335 languages and can be defined by the
 336 .Sx \&de
 337 request.
 338 When called, they follow the same syntax as requests, except that
 339 macro arguments may optionally be quoted by enclosing them
 340 in double quote characters
 341 .Pq Sq \(dq .
 342 Quoted text, even if it contains whitespace or would cause
 343 a macro invocation when unquoted, is always considered literal text.
 344 Inside quoted text, pairs of double quote characters
 345 .Pq Sq Qq
 346 resolve to single double quote characters.
 347 .Pp
 348 To be recognised as the beginning of a quoted argument, the opening
 349 quote character must be preceded by a space character.
 350 A quoted argument extends to the next double quote character that is not
 351 part of a pair, or to the end of the input line, whichever comes earlier.
 352 Leaving out the terminating double quote character at the end of the line
 353 is discouraged.
 354 For clarity, if more arguments follow on the same input line,
 355 it is recommended to follow the terminating double quote character
 356 by a space character; in case the next character after the terminating
 357 double quote character is anything else, it is regarded as the beginning
 358 of the next, unquoted argument.
 359 .Pp
 360 Both in quoted and unquoted arguments, pairs of backslashes
 361 .Pq Sq \e\e
 362 resolve to single backslashes.
 363 In unquoted arguments, space characters can alternatively be included
 364 by preceding them with a backslash
 365 .Pq Sq \e\~ ,
 366 but quoting is usually better for clarity.
 367 .Pp
 368 Examples:
 369 .Bl -tag -width Ds -offset indent -compact
 370 .It Li .Fn strlen \(dqconst char *s\(dq
 371 Group arguments
 372 .Qq const char *s
 373 into one function argument.
 374 If unspecified,
 375 .Qq const ,
 376 .Qq char ,
 377 and
 378 .Qq *s
 379 would be considered separate arguments.
 380 .It Li .Op \(dqFl a\(dq
 381 Consider
 382 .Qq \&Fl a
 383 as literal text instead of a flag macro.
 384 .El
 385 .Sh REQUEST REFERENCE
 386 The
 387 .Xr mandoc 1
 388 .Nm
 389 parser recognises the following requests.
 390 Note that the
 391 .Nm
 392 language defines many more requests not implemented in
 393 .Xr mandoc 1 .
 394 .Ss \&ad
 395 Set line adjustment mode.
 396 This line-scoped request is intended to have one argument to select
 397 normal, left, right, or centre adjustment for subsequent text.
 398 Currently, it is ignored including its arguments,
 399 and the number of arguments is not checked.
 400 .Ss \&am
 401 Append to a macro definition.
 402 The syntax of this request is the same as that of
 403 .Sx \&de .
 404 It is currently ignored by
 405 .Xr mandoc 1 ,
 406 as are its children.
 407 .Ss \&ami
 408 Append to a macro definition, specifying the macro name indirectly.
 409 The syntax of this request is the same as that of
 410 .Sx \&dei .
 411 It is currently ignored by
 412 .Xr mandoc 1 ,
 413 as are its children.
 414 .Ss \&am1
 415 Append to a macro definition, switching roff compatibility mode off
 416 during macro execution.
 417 The syntax of this request is the same as that of
 418 .Sx \&de1 .
 419 It is currently ignored by
 420 .Xr mandoc 1 ,
 421 as are its children.
 422 .Ss \&de
 423 Define a
 424 .Nm
 425 macro.
 426 Its syntax can be either
 427 .Bd -literal -offset indent
 428 .Pf . Cm \&de Ar name
 429 .Ar macro definition
 430 \&..
 431 .Ed
 432 .Pp
 433 or
 434 .Bd -literal -offset indent
 435 .Pf . Cm \&de Ar name Ar end
 436 .Ar macro definition
 437 .Pf . Ar end
 438 .Ed
 439 .Pp
 440 Both forms define or redefine the macro
 441 .Ar name
 442 to represent the
 443 .Ar macro definition ,
 444 which may consist of one or more input lines, including the newline
 445 characters terminating each line, optionally containing calls to
 446 .Nm
 447 requests,
 448 .Nm
 449 macros or high-level macros like
 450 .Xr man 5
 451 or
 452 .Xr mdoc 5
 453 macros, whichever applies to the document in question.
 454 .Pp
 455 Specifying a custom
 456 .Ar end
 457 macro works in the same way as for
 458 .Sx \&ig ;
 459 namely, the call to
 460 .Sq Pf . Ar end
 461 first ends the
 462 .Ar macro definition ,
 463 and after that, it is also evaluated as a
 464 .Nm
 465 request or
 466 .Nm
 467 macro, but not as a high-level macro.
 468 .Pp
 469 The macro can be invoked later using the syntax
 470 .Pp
 471 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
 472 .Pp
 473 Regarding argument parsing, see
 474 .Sx MACRO SYNTAX
 475 above.
 476 .Pp
 477 The line invoking the macro will be replaced
 478 in the input stream by the
 479 .Ar macro definition ,
 480 replacing all occurrences of
 481 .No \e\e$ Ns Ar N ,
 482 where
 483 .Ar N
 484 is a digit, by the
 485 .Ar N Ns th Ar argument .
 486 For example,
 487 .Bd -literal -offset indent
 488 \&.de ZN
 489 \efI\e^\e\e$1\e^\efP\e\e$2
 490 \&..
 491 \&.ZN XtFree .
 492 .Ed
 493 .Pp
 494 produces
 495 .Pp
 496 .D1 \efI\e^XtFree\e^\efP.
 497 .Pp
 498 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 499 .Pp
 500 Since macros and user-defined strings share a common string table,
 501 defining a macro
 502 .Ar name
 503 clobbers the user-defined string
 504 .Ar name ,
 505 and the
 506 .Ar macro definition
 507 can also be printed using the
 508 .Sq \e*
 509 string interpolation syntax described below
 510 .Sx ds ,
 511 but this is rarely useful because every macro definition contains at least
 512 one explicit newline character.
 513 .Pp
 514 In order to prevent endless recursion, both groff and
 515 .Xr mandoc 1
 516 limit the stack depth for expanding macros and strings
 517 to a large, but finite number.
 518 Do not rely on the exact value of this limit.
 519 .Ss \&dei
 520 Define a
 521 .Nm
 522 macro, specifying the macro name indirectly.
 523 The syntax of this request is the same as that of
 524 .Sx \&de .
 525 It is currently ignored by
 526 .Xr mandoc 1 ,
 527 as are its children.
 528 .Ss \&de1
 529 Define a
 530 .Nm
 531 macro that will be executed with
 532 .Nm
 533 compatibility mode switched off during macro execution.
 534 This is a GNU extension not available in traditional
 535 .Nm
 536 implementations and not even in older versions of groff.
 537 Since
 538 .Xr mandoc 1
 539 does not implement
 540 .Nm
 541 compatibility mode at all, it handles this request as an alias for
 542 .Sx \&de .
 543 .Ss \&ds
 544 Define a user-defined string.
 545 Its syntax is as follows:
 546 .Pp
 547 .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
 548 .Pp
 549 The
 550 .Ar name
 551 and
 552 .Ar string
 553 arguments are space-separated.
 554 If the
 555 .Ar string
 556 begins with a double-quote character, that character will not be part
 557 of the string.
 558 All remaining characters on the input line form the
 559 .Ar string ,
 560 including whitespace and double-quote characters, even trailing ones.
 561 .Pp
 562 The
 563 .Ar string
 564 can be interpolated into subsequent text by using
 565 .No \e* Ns Bq Ar name
 566 for a
 567 .Ar name
 568 of arbitrary length, or \e*(NN or \e*N if the length of
 569 .Ar name
 570 is two or one characters, respectively.
 571 Interpolation can be prevented by escaping the leading backslash;
 572 that is, an asterisk preceded by an even number of backslashes
 573 does not trigger string interpolation.
 574 .Pp
 575 Since user-defined strings and macros share a common string table,
 576 defining a string
 577 .Ar name
 578 clobbers the macro
 579 .Ar name ,
 580 and the
 581 .Ar name
 582 used for defining a string can also be invoked as a macro,
 583 in which case the following input line will be appended to the
 584 .Ar string ,
 585 forming a new input line passed to the
 586 .Nm
 587 parser.
 588 For example,
 589 .Bd -literal -offset indent
 590 \&.ds badidea .S
 591 \&.badidea
 592 H SYNOPSIS
 593 .Ed
 594 .Pp
 595 invokes the
 596 .Cm SH
 597 macro when used in a
 598 .Xr man 5
 599 document.
 600 Such abuse is of course strongly discouraged.
 601 .Ss \&el
 602 The
 603 .Qq else
 604 half of an if/else conditional.
 605 Pops a result off the stack of conditional evaluations pushed by
 606 .Sx \&ie
 607 and uses it as its conditional.
 608 If no stack entries are present (e.g., due to no prior
 609 .Sx \&ie
 610 calls)
 611 then false is assumed.
 612 The syntax of this request is similar to
 613 .Sx \&if
 614 except that the conditional is missing.
 615 .Ss \&EN
 616 End an equation block.
 617 See
 618 .Sx \&EQ .
 619 .Ss \&EQ
 620 Begin an equation block.
 621 See
 622 .Xr eqn 5
 623 for a description of the equation language.
 624 .Ss \&hy
 625 Set automatic hyphenation mode.
 626 This line-scoped request is currently ignored.
 627 .Ss \&ie
 628 The
 629 .Qq if
 630 half of an if/else conditional.
 631 The result of the conditional is pushed into a stack used by subsequent
 632 invocations of
 633 .Sx \&el ,
 634 which may be separated by any intervening input (or not exist at all).
 635 Its syntax is equivalent to
 636 .Sx \&if .
 637 .Ss \&if
 638 Begins a conditional.
 639 Right now, the conditional evaluates to true
 640 if and only if it starts with the letter
 641 .Sy n ,
 642 indicating processing in nroff style as opposed to troff style.
 643 If a conditional is false, its children are not processed, but are
 644 syntactically interpreted to preserve the integrity of the input
 645 document.
 646 Thus,
 647 .Pp
 648 .D1 \&.if t .ig
 649 .Pp
 650 will discard the
 651 .Sq \&.ig ,
 652 which may lead to interesting results, but
 653 .Pp
 654 .D1 \&.if t .if t \e{\e
 655 .Pp
 656 will continue to syntactically interpret to the block close of the final
 657 conditional.
 658 Sub-conditionals, in this case, obviously inherit the truth value of
 659 the parent.
 660 This request has the following syntax:
 661 .Bd -literal -offset indent
 662 \&.if COND \e{\e
 663 BODY...
 664 \&.\e}
 665 .Ed
 666 .Bd -literal -offset indent
 667 \&.if COND \e{ BODY
 668 BODY... \e}
 669 .Ed
 670 .Bd -literal -offset indent
 671 \&.if COND \e{ BODY
 672 BODY...
 673 \&.\e}
 674 .Ed
 675 .Bd -literal -offset indent
 676 \&.if COND \e
 677 BODY
 678 .Ed
 679 .Pp
 680 COND is a conditional statement.
 681 roff allows for complicated conditionals; mandoc is much simpler.
 682 At this time, mandoc supports only
 683 .Sq n ,
 684 evaluating to true;
 685 and
 686 .Sq t ,
 687 .Sq e ,
 688 and
 689 .Sq o ,
 690 evaluating to false.
 691 All other invocations are read up to the next end of line or space and
 692 evaluate as false.
 693 .Pp
 694 If the BODY section is begun by an escaped brace
 695 .Sq \e{ ,
 696 scope continues until a closing-brace escape sequence
 697 .Sq \.\e} .
 698 If the BODY is not enclosed in braces, scope continues until
 699 the end of the line.
 700 If the COND is followed by a BODY on the same line, whether after a
 701 brace or not, then requests and macros
 702 .Em must
 703 begin with a control character.
 704 It is generally more intuitive, in this case, to write
 705 .Bd -literal -offset indent
 706 \&.if COND \e{\e
 707 \&.foo
 708 bar
 709 \&.\e}
 710 .Ed
 711 .Pp
 712 than having the request or macro follow as
 713 .Pp
 714 .D1 \&.if COND \e{ .foo
 715 .Pp
 716 The scope of a conditional is always parsed, but only executed if the
 717 conditional evaluates to true.
 718 .Pp
 719 Note that the
 720 .Sq \e}
 721 is converted into a zero-width escape sequence if not passed as a
 722 standalone macro
 723 .Sq \&.\e} .
 724 For example,
 725 .Pp
 726 .D1 \&.Fl a \e} b
 727 .Pp
 728 will result in
 729 .Sq \e}
 730 being considered an argument of the
 731 .Sq \&Fl
 732 macro.
 733 .Ss \&ig
 734 Ignore input.
 735 Its syntax can be either
 736 .Bd -literal -offset indent
 737 .Pf . Cm \&ig
 738 .Ar ignored text
 739 \&..
 740 .Ed
 741 .Pp
 742 or
 743 .Bd -literal -offset indent
 744 .Pf . Cm \&ig Ar end
 745 .Ar ignored text
 746 .Pf . Ar end
 747 .Ed
 748 .Pp
 749 In the first case, input is ignored until a
 750 .Sq \&..
 751 request is encountered on its own line.
 752 In the second case, input is ignored until the specified
 753 .Sq Pf . Ar end
 754 macro is encountered.
 755 Do not use the escape character
 756 .Sq \e
 757 anywhere in the definition of
 758 .Ar end ;
 759 it would cause very strange behaviour.
 760 .Pp
 761 When the
 762 .Ar end
 763 macro is a roff request or a roff macro, like in
 764 .Pp
 765 .D1 \&.ig if
 766 .Pp
 767 the subsequent invocation of
 768 .Sx \&if
 769 will first terminate the
 770 .Ar ignored text ,
 771 then be invoked as usual.
 772 Otherwise, it only terminates the
 773 .Ar ignored text ,
 774 and arguments following it or the
 775 .Sq \&..
 776 request are discarded.
 777 .Ss \&ne
 778 Declare the need for the specified minimum vertical space
 779 before the next trap or the bottom of the page.
 780 This line-scoped request is currently ignored.
 781 .Ss \&nh
 782 Turn off automatic hyphenation mode.
 783 This line-scoped request is currently ignored.
 784 .Ss \&rm
 785 Remove a request, macro or string.
 786 This request is intended to have one argument,
 787 the name of the request, macro or string to be undefined.
 788 Currently, it is ignored including its arguments,
 789 and the number of arguments is not checked.
 790 .Ss \&nr
 791 Define a register.
 792 A register is an arbitrary string value that defines some sort of state,
 793 which influences parsing and/or formatting.
 794 Its syntax is as follows:
 795 .Pp
 796 .D1 Pf \. Cm \&nr Ar name Ar value
 797 .Pp
 798 The
 799 .Ar value
 800 may, at the moment, only be an integer.
 801 So far, only the following register
 802 .Ar name
 803 is recognised:
 804 .Bl -tag -width Ds
 805 .It Cm nS
 806 If set to a positive integer value, certain
 807 .Xr mdoc 5
 808 macros will behave in the same way as in the
 809 .Em SYNOPSIS
 810 section.
 811 If set to 0, these macros will behave in the same way as outside the
 812 .Em SYNOPSIS
 813 section, even when called within the
 814 .Em SYNOPSIS
 815 section itself.
 816 Note that starting a new
 817 .Xr mdoc 5
 818 section with the
 819 .Cm \&Sh
 820 macro will reset this register.
 821 .El
 822 .Ss \&ns
 823 Turn on no-space mode.
 824 This line-scoped request is intended to take no arguments.
 825 Currently, it is ignored including its arguments,
 826 and the number of arguments is not checked.
 827 .Ss \&ps
 828 Change point size.
 829 This line-scoped request is intended to take one numerical argument.
 830 Currently, it is ignored including its arguments,
 831 and the number of arguments is not checked.
 832 .Ss \&so
 833 Include a source file.
 834 Its syntax is as follows:
 835 .Pp
 836 .D1 Pf \. Cm \&so Ar file
 837 .Pp
 838 The
 839 .Ar file
 840 will be read and its contents processed as input in place of the
 841 .Sq \&.so
 842 request line.
 843 To avoid inadvertent inclusion of unrelated files,
 844 .Xr mandoc 1
 845 only accepts relative paths not containing the strings
 846 .Qq ../
 847 and
 848 .Qq /.. .
 849 .Pp
 850 This request requires
 851 .Xr man 1
 852 to change to the right directory before calling
 853 .Xr mandoc 1 ,
 854 per convention to the root of the manual tree.
 855 Typical usage looks like:
 856 .Pp
 857 .Dl \&.so man3/Xcursor.3
 858 .Pp
 859 As the whole concept is rather fragile, the use of
 860 .Sx \&so
 861 is discouraged.
 862 Use
 863 .Xr ln 1
 864 instead.
 865 .Ss \&ta
 866 Set tab stops.
 867 This line-scoped request can take an arbitrary number of arguments.
 868 Currently, it is ignored including its arguments.
 869 .Ss \&tr
 870 Output character translation.
 871 Its syntax is as follows:
 872 .Pp
 873 .D1 Pf \. Cm \&tr Ar [ab]+
 874 .Pp
 875 Pairs of
 876 .Ar ab
 877 characters are replaced
 878 .Ar ( a
 879 for
 880 .Ar b ) .
 881 Replacement (or origin) characters may also be character escapes; thus,
 882 .Pp
 883 .Dl tr \e(xx\e(yy
 884 .Pp
 885 replaces all invocations of \e(xx with \e(yy.
 886 .Ss \&T&
 887 Re-start a table layout, retaining the options of the prior table
 888 invocation.
 889 See
 890 .Sx \&TS .
 891 .Ss \&TE
 892 End a table context.
 893 See
 894 .Sx \&TS .
 895 .Ss \&TS
 896 Begin a table, which formats input in aligned rows and columns.
 897 See
 898 .Xr tbl 5
 899 for a description of the tbl language.
 900 .Sh COMPATIBILITY
 901 This section documents compatibility between mandoc and other other
 902 .Nm
 903 implementations, at this time limited to GNU troff
 904 .Pq Qq groff .
 905 The term
 906 .Qq historic groff
 907 refers to groff version 1.15.
 908 .Pp
 909 .Bl -dash -compact
 910 .It
 911 In mandoc, the
 912 .Sx \&EQ ,
 913 .Sx \&TE ,
 914 .Sx \&TS ,
 915 and
 916 .Sx \&T& ,
 917 macros are considered regular macros.
 918 In all other
 919 .Nm
 920 implementations, these are special macros that must be specified without
 921 spacing between the control character (which must be a period) and the
 922 macro name.
 923 .It
 924 The
 925 .Cm nS
 926 register is only compatible with OpenBSD's groff-1.15.
 927 .It
 928 Historic groff did not accept white-space before a custom
 929 .Ar end
 930 macro for the
 931 .Sx \&ig
 932 request.
 933 .It
 934 The
 935 .Sx \&if
 936 and family would print funny white-spaces with historic groff when
 937 using the next-line syntax.
 938 .El
 939 .Sh SEE ALSO
 940 .Xr mandoc 1 ,
 941 .Xr eqn 5 ,
 942 .Xr man 5 ,
 943 .Xr mandoc_char 5 ,
 944 .Xr mdoc 5 ,
 945 .Xr tbl 5
 946 .Rs
 947 .%A Joseph F. Ossanna
 948 .%A Brian W. Kernighan
 949 .%I AT&T Bell Laboratories
 950 .%T Troff User's Manual
 951 .%R Computing Science Technical Report
 952 .%N 54
 953 .%C Murray Hill, New Jersey
 954 .%D 1976 and 1992
 955 .%U http://www.kohala.com/start/troff/cstr54.ps
 956 .Re
 957 .Rs
 958 .%A Joseph F. Ossanna
 959 .%A Brian W. Kernighan
 960 .%A Gunnar Ritter
 961 .%T Heirloom Documentation Tools Nroff/Troff User's Manual
 962 .%D September 17, 2007
 963 .%U http://heirloom.sourceforge.net/doctools/troff.pdf
 964 .Re
 965 .Sh HISTORY
 966 The RUNOFF typesetting system, whose input forms the basis for
 967 .Nm ,
 968 was written in MAD and FAP for the CTSS operating system by Jerome E.
 969 Saltzer in 1964.
 970 Doug McIlroy rewrote it in BCPL in 1969, renaming it
 971 .Nm .
 972 Dennis M. Ritchie rewrote McIlroy's
 973 .Nm
 974 in PDP-11 assembly for
 975 .At v1 ,
 976 Joseph F. Ossanna improved roff and renamed it nroff
 977 for
 978 .At v2 ,
 979 then ported nroff to C as troff, which Brian W. Kernighan released with
 980 .At v7 .
 981 In 1989, James Clarke re-implemented troff in C++, naming it groff.
 982 .Sh AUTHORS
 983 .An -nosplit
 984 This
 985 .Nm
 986 reference was written by
 987 .An Kristaps Dzonsons ,
 988 .Mt kristaps@bsd.lv ;
 989 and
 990 .An Ingo Schwarze ,
 991 .Mt schwarze@openbsd.org .