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