| 1 | .\" $Id: man.7,v 1.46 2009/11/02 17:07:30 kristaps Exp $ |
| 2 | .\" |
| 3 | .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> |
| 4 | .\" |
| 5 | .\" Permission to use, copy, modify, and distribute this software for any |
| 6 | .\" purpose with or without fee is hereby granted, provided that the above |
| 7 | .\" copyright notice and this permission notice appear in all copies. |
| 8 | .\" |
| 9 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
| 10 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
| 11 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
| 12 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 13 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
| 14 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
| 15 | .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 16 | .\" |
| 17 | .Dd November 6, 2009 |
| 18 | .Dt MAN 7 |
| 19 | .Os |
| 20 | . |
| 21 | . |
| 22 | .Sh NAME |
| 23 | .Nm man |
| 24 | .Nd man language reference |
| 25 | . |
| 26 | . |
| 27 | .Sh DESCRIPTION |
| 28 | The |
| 29 | .Nm man |
| 30 | language was historically used to format |
| 31 | .Ux |
| 32 | manuals. This reference document describes its syntax, structure, and |
| 33 | usage. |
| 34 | . |
| 35 | .Pp |
| 36 | .Bf -emphasis |
| 37 | Do not use |
| 38 | .Nm |
| 39 | to write your manuals. |
| 40 | .Ef |
| 41 | Use the |
| 42 | .Xr mdoc 7 |
| 43 | language, instead. |
| 44 | . |
| 45 | .Pp |
| 46 | An |
| 47 | .Nm |
| 48 | document follows simple rules: lines beginning with the control |
| 49 | character |
| 50 | .Sq \&. |
| 51 | are parsed for macros. Other lines are interpreted within the scope of |
| 52 | prior macros: |
| 53 | .Bd -literal -offset indent |
| 54 | \&.SH Macro lines change control state. |
| 55 | Other lines are interpreted within the current state. |
| 56 | .Ed |
| 57 | . |
| 58 | . |
| 59 | .Sh INPUT ENCODING |
| 60 | .Nm |
| 61 | documents may contain only graphable 7-bit ASCII characters, the |
| 62 | space character, and the tabs character. All manuals must have |
| 63 | .Ux |
| 64 | line termination. |
| 65 | . |
| 66 | .Pp |
| 67 | Blank lines are acceptable; where found, the output will assert a |
| 68 | vertical space. |
| 69 | . |
| 70 | .Pp |
| 71 | The |
| 72 | .Sq \ec |
| 73 | escape is common in historical |
| 74 | .Nm |
| 75 | documents; if encountered at the end of a word, it ensures that the |
| 76 | subsequent word isn't off-set by whitespace. |
| 77 | . |
| 78 | . |
| 79 | .Ss Comments |
| 80 | Text following a |
| 81 | .Sq \e\*" , |
| 82 | whether in a macro or free-form text line, is ignored to the end of |
| 83 | line. A macro line with only a control character and comment escape, |
| 84 | .Sq \&.\e" , |
| 85 | is also ignored. Macro lines with only a control character and |
| 86 | optionally whitespace are stripped from input. |
| 87 | . |
| 88 | . |
| 89 | .Ss Special Characters |
| 90 | Special characters may occur in both macro and free-form lines. |
| 91 | Sequences begin with the escape character |
| 92 | .Sq \e |
| 93 | followed by either an open-parenthesis |
| 94 | .Sq \&( |
| 95 | for two-character sequences; an open-bracket |
| 96 | .Sq \&[ |
| 97 | for n-character sequences (terminated at a close-bracket |
| 98 | .Sq \&] ) ; |
| 99 | or a single one-character sequence. See |
| 100 | .Xr mandoc_char 7 |
| 101 | for a complete list. Examples include |
| 102 | .Sq \e(em |
| 103 | .Pq em-dash |
| 104 | and |
| 105 | .Sq \ee |
| 106 | .Pq back-slash . |
| 107 | . |
| 108 | . |
| 109 | .Ss Text Decoration |
| 110 | Terms may be text-decorated using the |
| 111 | .Sq \ef |
| 112 | escape followed by an indicator: B (bold), I, (italic), or P and R |
| 113 | (Roman, or reset). |
| 114 | . |
| 115 | . |
| 116 | .Ss Whitespace |
| 117 | Unless specifically escaped, consecutive blocks of whitespace are pruned |
| 118 | from input. These are later re-added, if applicable, by a front-end |
| 119 | utility such as |
| 120 | .Xr mandoc 1 . |
| 121 | . |
| 122 | . |
| 123 | .Ss Dates |
| 124 | The |
| 125 | .Sx \&TH |
| 126 | macro is the only |
| 127 | .Nm |
| 128 | macro that requires a date. The form for this date is the ISO-8601 |
| 129 | standard |
| 130 | .Cm YYYY-MM-DD . |
| 131 | . |
| 132 | . |
| 133 | .Ss Scaling Widths |
| 134 | Many macros support scaled widths for their arguments, such as |
| 135 | stipulating a two-inch paragraph indentation with the following: |
| 136 | .Bd -literal -offset indent |
| 137 | \&.HP 2i |
| 138 | .Ed |
| 139 | . |
| 140 | .Pp |
| 141 | The syntax for scaled widths is |
| 142 | .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? , |
| 143 | where a decimal must be preceded or proceeded by at least one digit. |
| 144 | Negative numbers, while accepted, are truncated to zero. The following |
| 145 | scaling units are accepted: |
| 146 | . |
| 147 | .Pp |
| 148 | .Bl -tag -width Ds -offset indent -compact |
| 149 | .It c |
| 150 | centimetre |
| 151 | .It i |
| 152 | inch |
| 153 | .It P |
| 154 | pica (~1/6 inch) |
| 155 | .It p |
| 156 | point (~1/72 inch) |
| 157 | .It f |
| 158 | synonym for |
| 159 | .Sq u |
| 160 | .It v |
| 161 | default vertical span |
| 162 | .It m |
| 163 | width of rendered |
| 164 | .Sq m |
| 165 | .Pq em |
| 166 | character |
| 167 | .It n |
| 168 | width of rendered |
| 169 | .Sq n |
| 170 | .Pq en |
| 171 | character |
| 172 | .It u |
| 173 | default horizontal span |
| 174 | .It M |
| 175 | mini-em (~1/100 em) |
| 176 | .El |
| 177 | .Pp |
| 178 | Using anything other than |
| 179 | .Sq m , |
| 180 | .Sq n , |
| 181 | .Sq u , |
| 182 | or |
| 183 | .Sq v |
| 184 | is necessarily non-portable across output media. |
| 185 | . |
| 186 | .Pp |
| 187 | If a scaling unit is not provided, the numerical value is interpreted |
| 188 | under the default rules of |
| 189 | .Sq v |
| 190 | for vertical spaces and |
| 191 | .Sq u |
| 192 | for horizontal ones. |
| 193 | .Em Note : |
| 194 | this differs from |
| 195 | .Xr mdoc 7 , |
| 196 | which, if a unit is not provided, will instead interpret the string as |
| 197 | literal text. |
| 198 | . |
| 199 | . |
| 200 | .Sh MANUAL STRUCTURE |
| 201 | Each |
| 202 | .Nm |
| 203 | document must contain contains at least the |
| 204 | .Sx \&TH |
| 205 | macro describing the document's section and title. It may occur |
| 206 | anywhere in the document, although conventionally, it appears as the |
| 207 | first macro. |
| 208 | . |
| 209 | .Pp |
| 210 | Beyond |
| 211 | .Sx \&TH , |
| 212 | at least one macro or text node must appear in the document. Documents |
| 213 | are generally structured as follows: |
| 214 | .Bd -literal -offset indent |
| 215 | \&.TH FOO 1 2009-10-10 |
| 216 | \&. |
| 217 | \&.SH NAME |
| 218 | \efBfoo\efR \e(en a description goes here |
| 219 | \&.\e\*q The next is for sections 2 & 3 only. |
| 220 | \&.\e\*q .SH LIBRARY |
| 221 | \&. |
| 222 | \&.SH SYNOPSIS |
| 223 | \efBfoo\efR [\efB\e-options\efR] arguments... |
| 224 | \&. |
| 225 | \&.SH DESCRIPTION |
| 226 | The \efBfoo\efR utility processes files... |
| 227 | \&. |
| 228 | \&.\e\*q .SH IMPLEMENTATION NOTES |
| 229 | \&.\e\*q The next is for sections 1 & 8 only. |
| 230 | \&.\e\*q .SH EXIT STATUS |
| 231 | \&.\e\*q The next is for sections 2, 3, & 9 only. |
| 232 | \&.\e\*q .SH RETURN VALUES |
| 233 | \&.\e\*q The next is for sections 1, 6, 7, & 8 only. |
| 234 | \&.\e\*q .SH ENVIRONMENT |
| 235 | \&.\e\*q .SH FILES |
| 236 | \&.\e\*q .SH EXAMPLES |
| 237 | \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. |
| 238 | \&.\e\*q .SH DIAGNOSTICS |
| 239 | \&.\e\*q The next is for sections 2, 3, & 9 only. |
| 240 | \&.\e\*q .SH ERRORS |
| 241 | \&.\e\*q .SH SEE ALSO |
| 242 | \&.\e\*q .BR foo ( 1 ) |
| 243 | \&.\e\*q .SH STANDARDS |
| 244 | \&.\e\*q .SH HISTORY |
| 245 | \&.\e\*q .SH AUTHORS |
| 246 | \&.\e\*q .SH CAVEATS |
| 247 | \&.\e\*q .SH BUGS |
| 248 | \&.\e\*q .SH SECURITY CONSIDERATIONS |
| 249 | .Ed |
| 250 | .Pp |
| 251 | The sections in a |
| 252 | .Nm |
| 253 | document are conventionally ordered as they appear above. Sections |
| 254 | should be composed as follows: |
| 255 | .Bl -ohang -offset indent |
| 256 | .It Em NAME |
| 257 | The name(s) and a short description of the documented material. The |
| 258 | syntax for this is generally as follows: |
| 259 | .Pp |
| 260 | .D1 \efBname\efR \e(en description |
| 261 | .It Em LIBRARY |
| 262 | The name of the library containing the documented material, which is |
| 263 | assumed to be a function in a section 2 or 3 manual. For functions in |
| 264 | the C library, this may be as follows: |
| 265 | .Pp |
| 266 | .D1 Standard C Library (libc, -lc) |
| 267 | .It Em SYNOPSIS |
| 268 | Documents the utility invocation syntax, function call syntax, or device |
| 269 | configuration. |
| 270 | .Pp |
| 271 | For the first, utilities (sections 1, 6, and 8), this is |
| 272 | generally structured as follows: |
| 273 | .Pp |
| 274 | .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... |
| 275 | .Pp |
| 276 | For the second, function calls (sections 2, 3, 9): |
| 277 | .Pp |
| 278 | .D1 \&.B char *name(char *\efIarg\efR); |
| 279 | .Pp |
| 280 | And for the third, configurations (section 4): |
| 281 | .Pp |
| 282 | .D1 \&.B name* at cardbus ? function ? |
| 283 | .Pp |
| 284 | Manuals not in these sections generally don't need a |
| 285 | .Em SYNOPSIS . |
| 286 | .It Em DESCRIPTION |
| 287 | This expands upon the brief, one-line description in |
| 288 | .Em NAME . |
| 289 | It usually contains a break-down of the options (if documenting a |
| 290 | command). |
| 291 | .It Em IMPLEMENTATION NOTES |
| 292 | Implementation-specific notes should be kept here. This is useful when |
| 293 | implementing standard functions that may have side effects or notable |
| 294 | algorithmic implications. |
| 295 | .It Em EXIT STATUS |
| 296 | Command exit status for section 1, 6, and 8 manuals. This section is |
| 297 | the dual of |
| 298 | .Em RETURN VALUES , |
| 299 | which is used for functions. Historically, this information was |
| 300 | described in |
| 301 | .Em DIAGNOSTICS , |
| 302 | a practise that is now discouraged. |
| 303 | . |
| 304 | .It Em RETURN VALUES |
| 305 | This section is the dual of |
| 306 | .Em EXIT STATUS , |
| 307 | which is used for commands. It documents the return values of functions |
| 308 | in sections 2, 3, and 9. |
| 309 | . |
| 310 | .It Em ENVIRONMENT |
| 311 | Documents any usages of environment variables, e.g., |
| 312 | .Xr environ 7 . |
| 313 | . |
| 314 | .It Em FILES |
| 315 | Documents files used. It's helpful to document both the file and a |
| 316 | short description of how the file is used (created, modified, etc.). |
| 317 | . |
| 318 | .It Em EXAMPLES |
| 319 | Example usages. This often contains snippets of well-formed, |
| 320 | well-tested invocations. Make doubly sure that your examples work |
| 321 | properly! |
| 322 | . |
| 323 | .It Em DIAGNOSTICS |
| 324 | Documents error conditions. This is most useful in section 4 manuals. |
| 325 | Historically, this section was used in place of |
| 326 | .Em EXIT STATUS |
| 327 | for manuals in sections 1, 6, and 8; however, this practise is |
| 328 | discouraged. |
| 329 | . |
| 330 | .It Em ERRORS |
| 331 | Documents error handling in sections 2, 3, and 9. |
| 332 | . |
| 333 | .It Em SEE ALSO |
| 334 | References other manuals with related topics. This section should exist |
| 335 | for most manuals. |
| 336 | .Pp |
| 337 | .D1 \&.BR bar \&( 1 \&), |
| 338 | .Pp |
| 339 | Cross-references should conventionally be ordered |
| 340 | first by section, then alphabetically. |
| 341 | . |
| 342 | .It Em STANDARDS |
| 343 | References any standards implemented or used, such as |
| 344 | .Pp |
| 345 | .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq) |
| 346 | .Pp |
| 347 | If not adhering to any standards, the |
| 348 | .Em HISTORY |
| 349 | section should be used. |
| 350 | . |
| 351 | .It Em HISTORY |
| 352 | The history of any manual without a |
| 353 | .Em STANDARDS |
| 354 | section should be described in this section. |
| 355 | . |
| 356 | .It Em AUTHORS |
| 357 | Credits to authors, if applicable, should appear in this section. |
| 358 | Authors should generally be noted by both name and an e-mail address. |
| 359 | . |
| 360 | .It Em CAVEATS |
| 361 | Explanations of common misuses and misunderstandings should be explained |
| 362 | in this section. |
| 363 | . |
| 364 | .It Em BUGS |
| 365 | Extant bugs should be described in this section. |
| 366 | . |
| 367 | .It Em SECURITY CONSIDERATIONS |
| 368 | Documents any security precautions that operators should consider. |
| 369 | . |
| 370 | .El |
| 371 | . |
| 372 | . |
| 373 | .Sh MACRO SYNTAX |
| 374 | Macros are one to three three characters in length and begin with a |
| 375 | control character , |
| 376 | .Sq \&. , |
| 377 | at the beginning of the line. An arbitrary amount of whitespace may |
| 378 | sit between the control character and the macro name. Thus, the |
| 379 | following are equivalent: |
| 380 | .Bd -literal -offset indent |
| 381 | \&.PP |
| 382 | \&.\ \ \ PP |
| 383 | .Ed |
| 384 | . |
| 385 | .Pp |
| 386 | The |
| 387 | .Nm |
| 388 | macros are classified by scope: line scope or block scope. Line |
| 389 | macros are only scoped to the current line (and, in some situations, |
| 390 | the subsequent line). Block macros are scoped to the current line and |
| 391 | subsequent lines until closed by another block macro. |
| 392 | . |
| 393 | . |
| 394 | .Ss Line Macros |
| 395 | Line macros are generally scoped to the current line, with the body |
| 396 | consisting of zero or more arguments. If a macro is scoped to the next |
| 397 | line and the line arguments are empty, the next line is used instead, |
| 398 | else the general syntax is used. Thus: |
| 399 | .Bd -literal -offset indent |
| 400 | \&.I |
| 401 | foo |
| 402 | .Ed |
| 403 | . |
| 404 | .Pp |
| 405 | is equivalent to |
| 406 | .Sq \&.I foo . |
| 407 | If next-line macros are invoked consecutively, only the last is used; in |
| 408 | other words, if a next-line macro is preceded by a block macro, it is |
| 409 | ignored. |
| 410 | .Bd -literal -offset indent |
| 411 | \&.YO \(lBbody...\(rB |
| 412 | \(lBbody...\(rB |
| 413 | .Ed |
| 414 | . |
| 415 | .Pp |
| 416 | .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" |
| 417 | .It Em Macro Ta Em Arguments Ta Em Scope |
| 418 | .It Sx \&B Ta n Ta next-line |
| 419 | .It Sx \&BI Ta n Ta current |
| 420 | .It Sx \&BR Ta n Ta current |
| 421 | .It Sx \&DT Ta 0 Ta current |
| 422 | .It Sx \&I Ta n Ta next-line |
| 423 | .It Sx \&IB Ta n Ta current |
| 424 | .It Sx \&IR Ta n Ta current |
| 425 | .It Sx \&PD Ta n Ta current |
| 426 | .It Sx \&R Ta n Ta next-line |
| 427 | .It Sx \&RB Ta n Ta current |
| 428 | .It Sx \&RI Ta n Ta current |
| 429 | .It Sx \&SB Ta n Ta next-line |
| 430 | .It Sx \&SM Ta n Ta next-line |
| 431 | .It Sx \&TH Ta >1, <6 Ta current |
| 432 | .It Sx \&UC Ta n Ta current |
| 433 | .It Sx \&br Ta 0 Ta current |
| 434 | .It Sx \&fi Ta 0 Ta current |
| 435 | .It Sx \&i Ta n Ta current |
| 436 | .It Sx \&na Ta 0 Ta current |
| 437 | .It Sx \&nf Ta 0 Ta current |
| 438 | .It Sx \&r Ta 0 Ta current |
| 439 | .It Sx \&sp Ta 1 Ta current |
| 440 | .El |
| 441 | . |
| 442 | .Pp |
| 443 | The |
| 444 | .Sx \&PD , |
| 445 | .Sx \&RS , |
| 446 | .Sx \&RE , |
| 447 | .Sx \&UC , |
| 448 | .Sx \&br , |
| 449 | .Sx \&fi , |
| 450 | .Sx \&i , |
| 451 | .Sx \&na , |
| 452 | .Sx \&nf , |
| 453 | .Sx \&r , |
| 454 | and |
| 455 | .Sx \&sp |
| 456 | macros should not be used. They're included for compatibility. |
| 457 | . |
| 458 | . |
| 459 | .Ss Block Macros |
| 460 | Block macros are comprised of a head and body. Like for in-line macros, |
| 461 | the head is scoped to the current line and, in one circumstance, the |
| 462 | next line; the body is scoped to subsequent lines and is closed out by a |
| 463 | subsequent block macro invocation. |
| 464 | .Bd -literal -offset indent |
| 465 | \&.YO \(lBhead...\(rB |
| 466 | \(lBhead...\(rB |
| 467 | \(lBbody...\(rB |
| 468 | .Ed |
| 469 | . |
| 470 | .Pp |
| 471 | The closure of body scope may be to the section, where a macro is closed |
| 472 | by |
| 473 | .Sx \&SH ; |
| 474 | sub-section, closed by a section or |
| 475 | .Sx \&SS ; |
| 476 | part, closed by a section, sub-section, or |
| 477 | .Sx \&RE ; |
| 478 | or paragraph, closed by a section, sub-section, part, |
| 479 | .Sx \&HP , |
| 480 | .Sx \&IP , |
| 481 | .Sx \&LP , |
| 482 | .Sx \&P , |
| 483 | .Sx \&PP , |
| 484 | or |
| 485 | .Sx \&TP . |
| 486 | No closure refers to an explicit block closing macro. |
| 487 | . |
| 488 | .Pp |
| 489 | .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent |
| 490 | .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope |
| 491 | .It Sx \&HP Ta <2 Ta current Ta paragraph |
| 492 | .It Sx \&IP Ta <3 Ta current Ta paragraph |
| 493 | .It Sx \&LP Ta 0 Ta current Ta paragraph |
| 494 | .It Sx \&P Ta 0 Ta current Ta paragraph |
| 495 | .It Sx \&PP Ta 0 Ta current Ta paragraph |
| 496 | .It Sx \&RE Ta 0 Ta current Ta none |
| 497 | .It Sx \&RS Ta 1 Ta current Ta part |
| 498 | .It Sx \&SH Ta >0 Ta next-line Ta section |
| 499 | .It Sx \&SS Ta >0 Ta next-line Ta sub-section |
| 500 | .It Sx \&TP Ta n Ta next-line Ta paragraph |
| 501 | .El |
| 502 | . |
| 503 | .Pp |
| 504 | If a block macro is next-line scoped, it may only be followed by in-line |
| 505 | macros (excluding |
| 506 | .Sx \&DT , |
| 507 | .Sx \&PD , |
| 508 | .Sx \&TH , |
| 509 | .Sx \&UC , |
| 510 | .Sx \&br , |
| 511 | .Sx \&na , |
| 512 | .Sx \&sp , |
| 513 | .Sx \&nf , |
| 514 | and |
| 515 | .Sx \&fi ) . |
| 516 | . |
| 517 | . |
| 518 | .Sh REFERENCE |
| 519 | This section is a canonical reference to all macros, arranged |
| 520 | alphabetically. For the scoping of individual macros, see |
| 521 | .Sx MACRO SYNTAX . |
| 522 | . |
| 523 | . |
| 524 | .Ss \&B |
| 525 | Text is rendered in bold face. |
| 526 | .Pp |
| 527 | See also |
| 528 | .Sx \&I , |
| 529 | .Sx \&R , |
| 530 | .Sx \&b , |
| 531 | .Sx \&i , |
| 532 | and |
| 533 | .Sx \&r . |
| 534 | . |
| 535 | . |
| 536 | .Ss \&BI |
| 537 | Text is rendered alternately in bold face and italic. Thus, |
| 538 | .Sq .BI this word and that |
| 539 | causes |
| 540 | .Sq this |
| 541 | and |
| 542 | .Sq and |
| 543 | to render in bold face, while |
| 544 | .Sq word |
| 545 | and |
| 546 | .Sq that |
| 547 | render in italics. Whitespace between arguments is omitted in output. |
| 548 | .Pp |
| 549 | Examples: |
| 550 | .Pp |
| 551 | .D1 \&.BI bold italic bold italic |
| 552 | .Pp |
| 553 | The output of this example will be emboldened |
| 554 | .Dq bold |
| 555 | and italicised |
| 556 | .Dq italic , |
| 557 | with spaces stripped between arguments. |
| 558 | .Pp |
| 559 | See also |
| 560 | .Sx \&IB , |
| 561 | .Sx \&BR , |
| 562 | .Sx \&RB , |
| 563 | .Sx \&RI , |
| 564 | and |
| 565 | .Sx \&IR . |
| 566 | . |
| 567 | . |
| 568 | .Ss \&BR |
| 569 | Text is rendered alternately in bold face and roman (the default font). |
| 570 | Whitespace between arguments is omitted in output. |
| 571 | .Pp |
| 572 | See |
| 573 | .Sx \&BI |
| 574 | for an equivalent example. |
| 575 | .Pp |
| 576 | See also |
| 577 | .Sx \&BI , |
| 578 | .Sx \&IB , |
| 579 | .Sx \&RB , |
| 580 | .Sx \&RI , |
| 581 | and |
| 582 | .Sx \&IR . |
| 583 | . |
| 584 | . |
| 585 | .Ss \&DT |
| 586 | Has no effect. Included for compatibility. |
| 587 | . |
| 588 | . |
| 589 | .Ss \&HP |
| 590 | Begin a paragraph whose initial output line is left-justified, but |
| 591 | subsequent output lines are indented, with the following syntax: |
| 592 | .Bd -filled -offset indent |
| 593 | .Pf \. Sx \&HP |
| 594 | .Op Cm width |
| 595 | .Ed |
| 596 | .Pp |
| 597 | The |
| 598 | .Cm width |
| 599 | argument must conform to |
| 600 | .Sx Scaling Widths . |
| 601 | If specified, it's saved for later paragraph left-margins; if unspecified, the |
| 602 | saved or default width is used. |
| 603 | .Pp |
| 604 | See also |
| 605 | .Sx \&IP , |
| 606 | .Sx \&LP , |
| 607 | .Sx \&P , |
| 608 | .Sx \&PP , |
| 609 | and |
| 610 | .Sx \&TP . |
| 611 | . |
| 612 | . |
| 613 | .Ss \&I |
| 614 | Text is rendered in italics. |
| 615 | .Pp |
| 616 | See also |
| 617 | .Sx \&B , |
| 618 | .Sx \&R , |
| 619 | .Sx \&b , |
| 620 | .Sx \&i , |
| 621 | and |
| 622 | .Sx \&r . |
| 623 | . |
| 624 | . |
| 625 | .Ss \&IB |
| 626 | Text is rendered alternately in italics and bold face. Whitespace |
| 627 | between arguments is omitted in output. |
| 628 | .Pp |
| 629 | See |
| 630 | .Sx \&BI |
| 631 | for an equivalent example. |
| 632 | .Pp |
| 633 | See also |
| 634 | .Sx \&BI , |
| 635 | .Sx \&BR , |
| 636 | .Sx \&RB , |
| 637 | .Sx \&RI , |
| 638 | and |
| 639 | .Sx \&IR . |
| 640 | . |
| 641 | . |
| 642 | .Ss \&IP |
| 643 | Begin an indented paragraph with the following syntax: |
| 644 | .Bd -filled -offset indent |
| 645 | .Pf \. Sx \&IP |
| 646 | .Op Cm head Op Cm width |
| 647 | .Ed |
| 648 | .Pp |
| 649 | The |
| 650 | .Cm width |
| 651 | argument defines the width of the left margin and is defined by |
| 652 | .Sx Scaling Widths , |
| 653 | It's saved for later paragraph left-margins; if unspecified, the saved or |
| 654 | default width is used. |
| 655 | .Pp |
| 656 | The |
| 657 | .Cm head |
| 658 | argument is used as a leading term, flushed to the left margin. This is |
| 659 | useful for bulleted paragraphs and so on. |
| 660 | .Pp |
| 661 | See also |
| 662 | .Sx \&HP , |
| 663 | .Sx \&LP , |
| 664 | .Sx \&P , |
| 665 | .Sx \&PP , |
| 666 | and |
| 667 | .Sx \&TP . |
| 668 | . |
| 669 | . |
| 670 | .Ss \&IR |
| 671 | Text is rendered alternately in italics and roman (the default font). |
| 672 | Whitespace between arguments is omitted in output. |
| 673 | .Pp |
| 674 | See |
| 675 | .Sx \&BI |
| 676 | for an equivalent example. |
| 677 | .Pp |
| 678 | See also |
| 679 | .Sx \&BI , |
| 680 | .Sx \&IB , |
| 681 | .Sx \&BR , |
| 682 | .Sx \&RB , |
| 683 | and |
| 684 | .Sx \&RI . |
| 685 | . |
| 686 | . |
| 687 | .Ss \&LP |
| 688 | Begin an undecorated paragraph. The scope of a paragraph is closed by a |
| 689 | subsequent paragraph, sub-section, section, or end of file. The saved |
| 690 | paragraph left-margin width is re-set to the default. |
| 691 | .Pp |
| 692 | See also |
| 693 | .Sx \&HP , |
| 694 | .Sx \&IP , |
| 695 | .Sx \&P , |
| 696 | .Sx \&PP , |
| 697 | and |
| 698 | .Sx \&TP . |
| 699 | . |
| 700 | . |
| 701 | .Ss \&P |
| 702 | Synonym for |
| 703 | .Sx \&LP . |
| 704 | .Pp |
| 705 | See also |
| 706 | .Sx \&HP , |
| 707 | .Sx \&IP , |
| 708 | .Sx \&LP , |
| 709 | .Sx \&PP , |
| 710 | and |
| 711 | .Sx \&TP . |
| 712 | . |
| 713 | . |
| 714 | .Ss \&PP |
| 715 | Synonym for |
| 716 | .Sx \&LP . |
| 717 | .Pp |
| 718 | See also |
| 719 | .Sx \&HP , |
| 720 | .Sx \&IP , |
| 721 | .Sx \&LP , |
| 722 | .Sx \&P , |
| 723 | and |
| 724 | .Sx \&TP . |
| 725 | . |
| 726 | . |
| 727 | .Ss \&R |
| 728 | Text is rendered in roman (the default font). |
| 729 | .Pp |
| 730 | See also |
| 731 | .Sx \&I , |
| 732 | .Sx \&B , |
| 733 | .Sx \&b , |
| 734 | .Sx \&i , |
| 735 | and |
| 736 | .Sx \&r . |
| 737 | . |
| 738 | . |
| 739 | .Ss \&RB |
| 740 | Text is rendered alternately in roman (the default font) and bold face. |
| 741 | Whitespace between arguments is omitted in output. |
| 742 | .Pp |
| 743 | See |
| 744 | .Sx \&BI |
| 745 | for an equivalent example. |
| 746 | .Pp |
| 747 | See also |
| 748 | .Sx \&BI , |
| 749 | .Sx \&IB , |
| 750 | .Sx \&BR , |
| 751 | .Sx \&RI , |
| 752 | and |
| 753 | .Sx \&IR . |
| 754 | . |
| 755 | . |
| 756 | .Ss \&RE |
| 757 | Explicitly close out the scope of a prior |
| 758 | .Sx \&RS . |
| 759 | . |
| 760 | . |
| 761 | .Ss \&RI |
| 762 | Text is rendered alternately in roman (the default font) and italics. |
| 763 | Whitespace between arguments is omitted in output. |
| 764 | .Pp |
| 765 | See |
| 766 | .Sx \&BI |
| 767 | for an equivalent example. |
| 768 | .Pp |
| 769 | See also |
| 770 | .Sx \&BI , |
| 771 | .Sx \&IB , |
| 772 | .Sx \&BR , |
| 773 | .Sx \&RB , |
| 774 | and |
| 775 | .Sx \&IR . |
| 776 | . |
| 777 | . |
| 778 | .Ss \&RS |
| 779 | Begin a part setting the left margin. The left margin controls the |
| 780 | offset, following an initial indentation, to un-indented text such as |
| 781 | that of |
| 782 | .Sx \&PP . |
| 783 | This has the following syntax: |
| 784 | .Bd -filled -offset indent |
| 785 | .Pf \. Sx \&Rs |
| 786 | .Op Cm width |
| 787 | .Ed |
| 788 | .Pp |
| 789 | The |
| 790 | .Cm width |
| 791 | argument must conform to |
| 792 | .Sx Scaling Widths . |
| 793 | If not specified, the saved or default width is used. |
| 794 | . |
| 795 | . |
| 796 | .Ss \&SB |
| 797 | Text is rendered in small size (one point smaller than the default font) |
| 798 | bold face. |
| 799 | . |
| 800 | . |
| 801 | .Ss \&SH |
| 802 | Begin a section. The scope of a section is only closed by another |
| 803 | section or the end of file. The paragraph left-margin width is re-set |
| 804 | to the default. |
| 805 | . |
| 806 | . |
| 807 | .Ss \&SM |
| 808 | Text is rendered in small size (one point smaller than the default |
| 809 | font). |
| 810 | . |
| 811 | . |
| 812 | .Ss \&SS |
| 813 | Begin a sub-section. The scope of a sub-section is closed by a |
| 814 | subsequent sub-section, section, or end of file. The paragraph |
| 815 | left-margin width is re-set to the default. |
| 816 | . |
| 817 | . |
| 818 | .Ss \&TH |
| 819 | Sets the title of the manual page with the following syntax: |
| 820 | .Bd -filled -offset indent |
| 821 | .Pf \. Sx \&TH |
| 822 | .Cm title section |
| 823 | .Op Cm date Op Cm source Op Cm volume |
| 824 | .Ed |
| 825 | .Pp |
| 826 | At least the upper-case document title |
| 827 | .Cm title |
| 828 | and numeric manual section |
| 829 | .Cm section |
| 830 | arguments must be provided. The |
| 831 | .Cm date |
| 832 | argument should be formatted as described in |
| 833 | .Sx Dates : |
| 834 | if it does not conform, the current date is used instead. The |
| 835 | .Cm source |
| 836 | string specifies the organisation providing the utility. The |
| 837 | .Cm volume |
| 838 | string replaces the default rendered volume, which is dictated by the |
| 839 | manual section. |
| 840 | .Pp |
| 841 | Examples: |
| 842 | .Pp |
| 843 | .D1 \&.TH CVS 5 "1992-02-12" GNU |
| 844 | . |
| 845 | . |
| 846 | .Ss \&TP |
| 847 | Begin a paragraph where the head, if exceeding the indentation width, is |
| 848 | followed by a newline; if not, the body follows on the same line after a |
| 849 | buffer to the indentation width. Subsequent output lines are indented. |
| 850 | The syntax is as follows: |
| 851 | .Bd -filled -offset indent |
| 852 | .Pf \. Sx \&TP |
| 853 | .Op Cm width |
| 854 | .Ed |
| 855 | .Pp |
| 856 | The |
| 857 | .Cm width |
| 858 | argument must conform to |
| 859 | .Sx Scaling Widths . |
| 860 | If specified, it's saved for later paragraph left-margins; if |
| 861 | unspecified, the saved or default width is used. |
| 862 | .Pp |
| 863 | See also |
| 864 | .Sx \&HP , |
| 865 | .Sx \&IP , |
| 866 | .Sx \&LP , |
| 867 | .Sx \&P , |
| 868 | and |
| 869 | .Sx \&PP . |
| 870 | . |
| 871 | . |
| 872 | .Ss \&PD |
| 873 | Has no effect. Included for compatibility. |
| 874 | . |
| 875 | . |
| 876 | .Ss \&UC |
| 877 | Has no effect. Included for compatibility. |
| 878 | . |
| 879 | . |
| 880 | .Ss \&br |
| 881 | Breaks the current line. Consecutive invocations have no further effect. |
| 882 | .Pp |
| 883 | See also |
| 884 | .Sx \&sp . |
| 885 | . |
| 886 | . |
| 887 | .Ss \&fi |
| 888 | End literal mode begun by |
| 889 | .Sx \&nf . |
| 890 | . |
| 891 | . |
| 892 | .Ss \&i |
| 893 | Italicise arguments. If no arguments are specified, all subsequent text |
| 894 | is italicised. |
| 895 | .Pp |
| 896 | See also |
| 897 | .Sx \&B , |
| 898 | .Sx \&I , |
| 899 | .Sx \&R . |
| 900 | .Sx \&b , |
| 901 | and |
| 902 | .Sx \&r . |
| 903 | . |
| 904 | . |
| 905 | .Ss \&na |
| 906 | Don't align to the right margin. |
| 907 | . |
| 908 | . |
| 909 | .Ss \&nf |
| 910 | Begin literal mode: all subsequent free-form lines have their end of |
| 911 | line boundaries preserved. May be ended by |
| 912 | .Sx \&fi . |
| 913 | . |
| 914 | . |
| 915 | .Ss \&r |
| 916 | Fonts and styles (bold face, italics) reset to roman (default font). |
| 917 | .Pp |
| 918 | See also |
| 919 | .Sx \&B , |
| 920 | .Sx \&I , |
| 921 | .Sx \&R , |
| 922 | .Sx \&b , |
| 923 | and |
| 924 | .Sx \&i . |
| 925 | . |
| 926 | . |
| 927 | .Ss \&sp |
| 928 | Insert vertical spaces into output with the following syntax: |
| 929 | .Bd -filled -offset indent |
| 930 | .Pf \. Sx \&sp |
| 931 | .Op Cm height |
| 932 | .Ed |
| 933 | .Pp |
| 934 | Insert |
| 935 | .Cm height |
| 936 | spaces, which must conform to |
| 937 | .Sx Scaling Widths . |
| 938 | If 0, this is equivalent to the |
| 939 | .Sx \&br |
| 940 | macro. Defaults to 1, if unspecified. |
| 941 | .Pp |
| 942 | See also |
| 943 | .Sx \&br . |
| 944 | . |
| 945 | . |
| 946 | .Sh COMPATIBILITY |
| 947 | This section documents compatibility with other roff implementations, at |
| 948 | this time limited to |
| 949 | .Xr groff 1 . |
| 950 | .Bl -hyphen |
| 951 | .It |
| 952 | In quoted literals, groff allowed pair-wise double-quotes to produce a |
| 953 | standalone double-quote in formatted output. This idiosyncratic |
| 954 | behaviour is no longer applicable. |
| 955 | .It |
| 956 | The |
| 957 | .Sq sp |
| 958 | macro does not accept negative numbers. |
| 959 | .It |
| 960 | Blocks of whitespace are stripped from both macro and free-form text |
| 961 | lines (except when in literal mode), while groff would retain whitespace |
| 962 | in free-form text lines. |
| 963 | .El |
| 964 | . |
| 965 | . |
| 966 | .Sh SEE ALSO |
| 967 | .Xr mandoc 1 , |
| 968 | .Xr mandoc_char 7 |
| 969 | . |
| 970 | . |
| 971 | .Sh AUTHORS |
| 972 | The |
| 973 | .Nm |
| 974 | reference was written by |
| 975 | .An Kristaps Dzonsons Aq kristaps@kth.se . |
| 976 | . |
| 977 | . |
| 978 | .Sh CAVEATS |
| 979 | Do not use this language. Use |
| 980 | .Xr mdoc 7 , |
| 981 | instead. |
| 982 | . |