logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mdoc.7 (77101B)


  1. .\" $Id: mdoc.7,v 1.287 2021/07/29 17:32:01 schwarze Exp $
  2. .\"
  3. .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  4. .\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org>
  5. .\"
  6. .\" Permission to use, copy, modify, and distribute this software for any
  7. .\" purpose with or without fee is hereby granted, provided that the above
  8. .\" copyright notice and this permission notice appear in all copies.
  9. .\"
  10. .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11. .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12. .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13. .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14. .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15. .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17. .\"
  18. .Dd $Mdocdate: July 29 2021 $
  19. .Dt MDOC 7
  20. .Os
  21. .Sh NAME
  22. .Nm mdoc
  23. .Nd semantic markup language for formatting manual pages
  24. .Sh DESCRIPTION
  25. The
  26. .Nm mdoc
  27. language supports authoring of manual pages for the
  28. .Xr man 1
  29. utility by allowing semantic annotations of words, phrases,
  30. page sections and complete manual pages.
  31. Such annotations are used by formatting tools to achieve a uniform
  32. presentation across all manuals written in
  33. .Nm ,
  34. and to support hyperlinking if supported by the output medium.
  35. .Pp
  36. This reference document describes the structure of manual pages
  37. and the syntax and usage of the
  38. .Nm
  39. language.
  40. The reference implementation of a parsing and formatting tool is
  41. .Xr mandoc 1 ;
  42. the
  43. .Sx COMPATIBILITY
  44. section describes compatibility with other implementations.
  45. .Pp
  46. In an
  47. .Nm
  48. document, lines beginning with the control character
  49. .Sq \&.
  50. are called
  51. .Dq macro lines .
  52. The first word is the macro name.
  53. It consists of two or three letters.
  54. Most macro names begin with a capital letter.
  55. For a list of available macros, see
  56. .Sx MACRO OVERVIEW .
  57. The words following the macro name are arguments to the macro, optionally
  58. including the names of other, callable macros; see
  59. .Sx MACRO SYNTAX
  60. for details.
  61. .Pp
  62. Lines not beginning with the control character are called
  63. .Dq text lines .
  64. They provide free-form text to be printed; the formatting of the text
  65. depends on the respective processing context:
  66. .Bd -literal -offset indent
  67. \&.Sh Macro lines change control state.
  68. Text lines are interpreted within the current state.
  69. .Ed
  70. .Pp
  71. Many aspects of the basic syntax of the
  72. .Nm
  73. language are based on the
  74. .Xr roff 7
  75. language; see the
  76. .Em LANGUAGE SYNTAX
  77. and
  78. .Em MACRO SYNTAX
  79. sections in the
  80. .Xr roff 7
  81. manual for details, in particular regarding
  82. comments, escape sequences, whitespace, and quoting.
  83. However, using
  84. .Xr roff 7
  85. requests in
  86. .Nm
  87. documents is discouraged;
  88. .Xr mandoc 1
  89. supports some of them merely for backward compatibility.
  90. .Sh MANUAL STRUCTURE
  91. A well-formed
  92. .Nm
  93. document consists of a document prologue followed by one or more
  94. sections.
  95. .Pp
  96. The prologue, which consists of the
  97. .Ic \&Dd ,
  98. .Ic \&Dt ,
  99. and
  100. .Ic \&Os
  101. macros in that order, is required for every document.
  102. .Pp
  103. The first section (sections are denoted by
  104. .Ic \&Sh )
  105. must be the NAME section, consisting of at least one
  106. .Ic \&Nm
  107. followed by
  108. .Ic \&Nd .
  109. .Pp
  110. Following that, convention dictates specifying at least the
  111. .Em SYNOPSIS
  112. and
  113. .Em DESCRIPTION
  114. sections, although this varies between manual sections.
  115. .Pp
  116. The following is a well-formed skeleton
  117. .Nm
  118. file for a utility
  119. .Qq progname :
  120. .Bd -literal -offset indent
  121. \&.Dd $\&Mdocdate$
  122. \&.Dt PROGNAME section
  123. \&.Os
  124. \&.Sh NAME
  125. \&.Nm progname
  126. \&.Nd one line about what it does
  127. \&.\e\(dq .Sh LIBRARY
  128. \&.\e\(dq For sections 2, 3, and 9 only.
  129. \&.\e\(dq Not used in OpenBSD.
  130. \&.Sh SYNOPSIS
  131. \&.Nm progname
  132. \&.Op Fl options
  133. \&.Ar
  134. \&.Sh DESCRIPTION
  135. The
  136. \&.Nm
  137. utility processes files ...
  138. \&.\e\(dq .Sh CONTEXT
  139. \&.\e\(dq For section 9 functions only.
  140. \&.\e\(dq .Sh IMPLEMENTATION NOTES
  141. \&.\e\(dq Not used in OpenBSD.
  142. \&.\e\(dq .Sh RETURN VALUES
  143. \&.\e\(dq For sections 2, 3, and 9 function return values only.
  144. \&.\e\(dq .Sh ENVIRONMENT
  145. \&.\e\(dq For sections 1, 6, 7, and 8 only.
  146. \&.\e\(dq .Sh FILES
  147. \&.\e\(dq .Sh EXIT STATUS
  148. \&.\e\(dq For sections 1, 6, and 8 only.
  149. \&.\e\(dq .Sh EXAMPLES
  150. \&.\e\(dq .Sh DIAGNOSTICS
  151. \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
  152. \&.\e\(dq .Sh ERRORS
  153. \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
  154. \&.\e\(dq .Sh SEE ALSO
  155. \&.\e\(dq .Xr foobar 1
  156. \&.\e\(dq .Sh STANDARDS
  157. \&.\e\(dq .Sh HISTORY
  158. \&.\e\(dq .Sh AUTHORS
  159. \&.\e\(dq .Sh CAVEATS
  160. \&.\e\(dq .Sh BUGS
  161. \&.\e\(dq .Sh SECURITY CONSIDERATIONS
  162. \&.\e\(dq Not used in OpenBSD.
  163. .Ed
  164. .Pp
  165. The sections in an
  166. .Nm
  167. document are conventionally ordered as they appear above.
  168. Sections should be composed as follows:
  169. .Bl -ohang -offset Ds
  170. .It Em NAME
  171. The name(s) and a one line description of the documented material.
  172. The syntax for this as follows:
  173. .Bd -literal -offset indent
  174. \&.Nm name0 ,
  175. \&.Nm name1 ,
  176. \&.Nm name2
  177. \&.Nd a one line description
  178. .Ed
  179. .Pp
  180. Multiple
  181. .Sq \&Nm
  182. names should be separated by commas.
  183. .Pp
  184. The
  185. .Ic \&Nm
  186. macro(s) must precede the
  187. .Ic \&Nd
  188. macro.
  189. .Pp
  190. See
  191. .Ic \&Nm
  192. and
  193. .Ic \&Nd .
  194. .It Em LIBRARY
  195. The name of the library containing the documented material, which is
  196. assumed to be a function in a section 2, 3, or 9 manual.
  197. The syntax for this is as follows:
  198. .Bd -literal -offset indent
  199. \&.Lb libarm
  200. .Ed
  201. .Pp
  202. See
  203. .Ic \&Lb .
  204. .It Em SYNOPSIS
  205. Documents the utility invocation syntax, function call syntax, or device
  206. configuration.
  207. .Pp
  208. For the first, utilities (sections 1, 6, and 8), this is
  209. generally structured as follows:
  210. .Bd -literal -offset indent
  211. \&.Nm bar
  212. \&.Op Fl v
  213. \&.Op Fl o Ar file
  214. \&.Op Ar
  215. \&.Nm foo
  216. \&.Op Fl v
  217. \&.Op Fl o Ar file
  218. \&.Op Ar
  219. .Ed
  220. .Pp
  221. Commands should be ordered alphabetically.
  222. .Pp
  223. For the second, function calls (sections 2, 3, 9):
  224. .Bd -literal -offset indent
  225. \&.In header.h
  226. \&.Vt extern const char *global;
  227. \&.Ft "char *"
  228. \&.Fn foo "const char *src"
  229. \&.Ft "char *"
  230. \&.Fn bar "const char *src"
  231. .Ed
  232. .Pp
  233. Ordering of
  234. .Ic \&In ,
  235. .Ic \&Vt ,
  236. .Ic \&Fn ,
  237. and
  238. .Ic \&Fo
  239. macros should follow C header-file conventions.
  240. .Pp
  241. And for the third, configurations (section 4):
  242. .Bd -literal -offset indent
  243. \&.Cd \(dqit* at isa? port 0x2e\(dq
  244. \&.Cd \(dqit* at isa? port 0x4e\(dq
  245. .Ed
  246. .Pp
  247. Manuals not in these sections generally don't need a
  248. .Em SYNOPSIS .
  249. .Pp
  250. Some macros are displayed differently in the
  251. .Em SYNOPSIS
  252. section, particularly
  253. .Ic \&Nm ,
  254. .Ic \&Cd ,
  255. .Ic \&Fd ,
  256. .Ic \&Fn ,
  257. .Ic \&Fo ,
  258. .Ic \&In ,
  259. .Ic \&Vt ,
  260. and
  261. .Ic \&Ft .
  262. All of these macros are output on their own line.
  263. If two such dissimilar macros are pairwise invoked (except for
  264. .Ic \&Ft
  265. before
  266. .Ic \&Fo
  267. or
  268. .Ic \&Fn ) ,
  269. they are separated by a vertical space, unless in the case of
  270. .Ic \&Fo ,
  271. .Ic \&Fn ,
  272. and
  273. .Ic \&Ft ,
  274. which are always separated by vertical space.
  275. .Pp
  276. When text and macros following an
  277. .Ic \&Nm
  278. macro starting an input line span multiple output lines,
  279. all output lines but the first will be indented to align
  280. with the text immediately following the
  281. .Ic \&Nm
  282. macro, up to the next
  283. .Ic \&Nm ,
  284. .Ic \&Sh ,
  285. or
  286. .Ic \&Ss
  287. macro or the end of an enclosing block, whichever comes first.
  288. .It Em DESCRIPTION
  289. This begins with an expansion of the brief, one line description in
  290. .Em NAME :
  291. .Bd -literal -offset indent
  292. The
  293. \&.Nm
  294. utility does this, that, and the other.
  295. .Ed
  296. .Pp
  297. It usually follows with a breakdown of the options (if documenting a
  298. command), such as:
  299. .Bd -literal -offset indent
  300. The options are as follows:
  301. \&.Bl \-tag \-width Ds
  302. \&.It Fl v
  303. Print verbose information.
  304. \&.El
  305. .Ed
  306. .Pp
  307. List the options in alphabetical order,
  308. uppercase before lowercase for each letter and
  309. with no regard to whether an option takes an argument.
  310. Put digits in ascending order before all letter options.
  311. .Pp
  312. Manuals not documenting a command won't include the above fragment.
  313. .Pp
  314. Since the
  315. .Em DESCRIPTION
  316. section usually contains most of the text of a manual, longer manuals
  317. often use the
  318. .Ic \&Ss
  319. macro to form subsections.
  320. In very long manuals, the
  321. .Em DESCRIPTION
  322. may be split into multiple sections, each started by an
  323. .Ic \&Sh
  324. macro followed by a non-standard section name, and each having
  325. several subsections, like in the present
  326. .Nm
  327. manual.
  328. .It Em CONTEXT
  329. This section lists the contexts in which functions can be called in section 9.
  330. The contexts are autoconf, process, or interrupt.
  331. .It Em IMPLEMENTATION NOTES
  332. Implementation-specific notes should be kept here.
  333. This is useful when implementing standard functions that may have side
  334. effects or notable algorithmic implications.
  335. .It Em RETURN VALUES
  336. This section documents the
  337. return values of functions in sections 2, 3, and 9.
  338. .Pp
  339. See
  340. .Ic \&Rv .
  341. .It Em ENVIRONMENT
  342. Lists the environment variables used by the utility,
  343. and explains the syntax and semantics of their values.
  344. The
  345. .Xr environ 7
  346. manual provides examples of typical content and formatting.
  347. .Pp
  348. See
  349. .Ic \&Ev .
  350. .It Em FILES
  351. Documents files used.
  352. It's helpful to document both the file name and a short description of how
  353. the file is used (created, modified, etc.).
  354. .Pp
  355. See
  356. .Ic \&Pa .
  357. .It Em EXIT STATUS
  358. This section documents the
  359. command exit status for section 1, 6, and 8 utilities.
  360. Historically, this information was described in
  361. .Em DIAGNOSTICS ,
  362. a practise that is now discouraged.
  363. .Pp
  364. See
  365. .Ic \&Ex .
  366. .It Em EXAMPLES
  367. Example usages.
  368. This often contains snippets of well-formed, well-tested invocations.
  369. Make sure that examples work properly!
  370. .It Em DIAGNOSTICS
  371. Documents error messages.
  372. In section 4 and 9 manuals, these are usually messages printed by the
  373. kernel to the console and to the kernel log.
  374. In section 1, 6, 7, and 8, these are usually messages printed by
  375. userland programs to the standard error output.
  376. .Pp
  377. Historically, this section was used in place of
  378. .Em EXIT STATUS
  379. for manuals in sections 1, 6, and 8; however, this practise is
  380. discouraged.
  381. .Pp
  382. See
  383. .Ic \&Bl
  384. .Fl diag .
  385. .It Em ERRORS
  386. Documents
  387. .Xr errno 2
  388. settings in sections 2, 3, 4, and 9.
  389. .Pp
  390. See
  391. .Ic \&Er .
  392. .It Em SEE ALSO
  393. References other manuals with related topics.
  394. This section should exist for most manuals.
  395. Cross-references should conventionally be ordered first by section, then
  396. alphabetically (ignoring case).
  397. .Pp
  398. References to other documentation concerning the topic of the manual page,
  399. for example authoritative books or journal articles, may also be
  400. provided in this section.
  401. .Pp
  402. See
  403. .Ic \&Rs
  404. and
  405. .Ic \&Xr .
  406. .It Em STANDARDS
  407. References any standards implemented or used.
  408. If not adhering to any standards, the
  409. .Em HISTORY
  410. section should be used instead.
  411. .Pp
  412. See
  413. .Ic \&St .
  414. .It Em HISTORY
  415. A brief history of the subject, including where it was first implemented,
  416. and when it was ported to or reimplemented for the operating system at hand.
  417. .It Em AUTHORS
  418. Credits to the person or persons who wrote the code and/or documentation.
  419. Authors should generally be noted by both name and email address.
  420. .Pp
  421. See
  422. .Ic \&An .
  423. .It Em CAVEATS
  424. Common misuses and misunderstandings should be explained
  425. in this section.
  426. .It Em BUGS
  427. Known bugs, limitations, and work-arounds should be described
  428. in this section.
  429. .It Em SECURITY CONSIDERATIONS
  430. Documents any security precautions that operators should consider.
  431. .El
  432. .Sh MACRO OVERVIEW
  433. This overview is sorted such that macros of similar purpose are listed
  434. together, to help find the best macro for any given purpose.
  435. Deprecated macros are not included in the overview, but can be found below
  436. in the alphabetical
  437. .Sx MACRO REFERENCE .
  438. .Ss Document preamble and NAME section macros
  439. .Bl -column "Brq, Bro, Brc" description
  440. .It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
  441. .It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch
  442. .It Ic \&Os Ta operating system version: Op Ar system Op Ar version
  443. .It Ic \&Nm Ta document name (one argument)
  444. .It Ic \&Nd Ta document description (one line)
  445. .El
  446. .Ss Sections and cross references
  447. .Bl -column "Brq, Bro, Brc" description
  448. .It Ic \&Sh Ta section header (one line)
  449. .It Ic \&Ss Ta subsection header (one line)
  450. .It Ic \&Sx Ta internal cross reference to a section or subsection
  451. .It Ic \&Xr Ta cross reference to another manual page: Ar name section
  452. .It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments
  453. .It Ic \&Pp Ta start a text paragraph (no arguments)
  454. .El
  455. .Ss Displays and lists
  456. .Bl -column "Brq, Bro, Brc" description
  457. .It Ic \&Bd , \&Ed Ta display block:
  458. .Fl Ar type
  459. .Op Fl offset Ar width
  460. .Op Fl compact
  461. .It Ic \&D1 Ta indented display (one line)
  462. .It Ic \&Dl Ta indented literal display (one line)
  463. .It Ic \&Ql Ta in-line literal display: Ql text
  464. .It Ic \&Bl , \&El Ta list block:
  465. .Fl Ar type
  466. .Op Fl width Ar val
  467. .Op Fl offset Ar val
  468. .Op Fl compact
  469. .It Ic \&It Ta list item (syntax depends on Fl Ar type )
  470. .It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists
  471. .It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references)
  472. .El
  473. .Ss Spacing control
  474. .Bl -column "Brq, Bro, Brc" description
  475. .It Ic \&Pf Ta prefix, no following horizontal space (one argument)
  476. .It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments)
  477. .It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments)
  478. .It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off
  479. .It Ic \&Bk , \&Ek Ta keep block: Fl words
  480. .El
  481. .Ss Semantic markup for command line utilities
  482. .Bl -column "Brq, Bro, Brc" description
  483. .It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility
  484. .It Ic \&Fl Ta command line options (flags) (>=0 arguments)
  485. .It Ic \&Cm Ta command modifier (>0 arguments)
  486. .It Ic \&Ar Ta command arguments (>=0 arguments)
  487. .It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
  488. .It Ic \&Ic Ta internal or interactive command (>0 arguments)
  489. .It Ic \&Ev Ta environmental variable (>0 arguments)
  490. .It Ic \&Pa Ta file system path (>=0 arguments)
  491. .El
  492. .Ss Semantic markup for function libraries
  493. .Bl -column "Brq, Bro, Brc" description
  494. .It Ic \&Lb Ta function library (one argument)
  495. .It Ic \&In Ta include file (one argument)
  496. .It Ic \&Fd Ta other preprocessor directive (>0 arguments)
  497. .It Ic \&Ft Ta function type (>0 arguments)
  498. .It Ic \&Fo , \&Fc Ta function block: Ar funcname
  499. .It Ic \&Fn Ta function name: Ar funcname Op Ar argument ...
  500. .It Ic \&Fa Ta function argument (>0 arguments)
  501. .It Ic \&Vt Ta variable type (>0 arguments)
  502. .It Ic \&Va Ta variable name (>0 arguments)
  503. .It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments)
  504. .It Ic \&Er Ta error constant (>0 arguments)
  505. .It Ic \&Ev Ta environmental variable (>0 arguments)
  506. .El
  507. .Ss Various semantic markup
  508. .Bl -column "Brq, Bro, Brc" description
  509. .It Ic \&An Ta author name (>0 arguments)
  510. .It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name
  511. .It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain
  512. .It Ic \&Cd Ta kernel configuration declaration (>0 arguments)
  513. .It Ic \&Ad Ta memory address (>0 arguments)
  514. .It Ic \&Ms Ta mathematical symbol (>0 arguments)
  515. .El
  516. .Ss Physical markup
  517. .Bl -column "Brq, Bro, Brc" description
  518. .It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments)
  519. .It Ic \&Sy Ta boldface font (symbolic) (>0 arguments)
  520. .It Ic \&No Ta return to roman font (normal) (>0 arguments)
  521. .It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy
  522. .El
  523. .Ss Physical enclosures
  524. .Bl -column "Brq, Bro, Brc" description
  525. .It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
  526. .It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
  527. .It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
  528. .It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
  529. .It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
  530. .It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
  531. .It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
  532. .It Ic \&Eo , \&Ec Ta generic enclosure
  533. .El
  534. .Ss Text production
  535. .Bl -column "Brq, Bro, Brc" description
  536. .It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ...
  537. .It Ic \&Rv Fl std Ta standard function return values: Op Ar function ...
  538. .It Ic \&St Ta reference to a standards document (one argument)
  539. .It Ic \&At Ta At
  540. .It Ic \&Bx Ta Bx
  541. .It Ic \&Bsx Ta Bsx
  542. .It Ic \&Nx Ta Nx
  543. .It Ic \&Fx Ta Fx
  544. .It Ic \&Ox Ta Ox
  545. .It Ic \&Dx Ta Dx
  546. .El
  547. .Sh MACRO REFERENCE
  548. This section is a canonical reference of all macros, arranged
  549. alphabetically.
  550. For the scoping of individual macros, see
  551. .Sx MACRO SYNTAX .
  552. .Bl -tag -width 3n
  553. .It Ic \&%A Ar first_name ... last_name
  554. Author name of an
  555. .Ic \&Rs
  556. block.
  557. Multiple authors should each be accorded their own
  558. .Ic \%%A
  559. line.
  560. Author names should be ordered with full or abbreviated forename(s)
  561. first, then full surname.
  562. .It Ic \&%B Ar title
  563. Book title of an
  564. .Ic \&Rs
  565. block.
  566. This macro may also be used in a non-bibliographic context when
  567. referring to book titles.
  568. .It Ic \&%C Ar location
  569. Publication city or location of an
  570. .Ic \&Rs
  571. block.
  572. .It Ic \&%D Oo Ar month day , Oc Ar year
  573. Publication date of an
  574. .Ic \&Rs
  575. block.
  576. Provide the full English name of the
  577. .Ar month
  578. and all four digits of the
  579. .Ar year .
  580. .It Ic \&%I Ar name
  581. Publisher or issuer name of an
  582. .Ic \&Rs
  583. block.
  584. .It Ic \&%J Ar name
  585. Journal name of an
  586. .Ic \&Rs
  587. block.
  588. .It Ic \&%N Ar number
  589. Issue number (usually for journals) of an
  590. .Ic \&Rs
  591. block.
  592. .It Ic \&%O Ar line
  593. Optional information of an
  594. .Ic \&Rs
  595. block.
  596. .It Ic \&%P Ar number
  597. Book or journal page number of an
  598. .Ic \&Rs
  599. block.
  600. Conventionally, the argument starts with
  601. .Ql p.\&
  602. for a single page or
  603. .Ql pp.\&
  604. for a range of pages, for example:
  605. .Pp
  606. .Dl .%P pp. 42\e(en47
  607. .It Ic \&%Q Ar name
  608. Institutional author (school, government, etc.) of an
  609. .Ic \&Rs
  610. block.
  611. Multiple institutional authors should each be accorded their own
  612. .Ic \&%Q
  613. line.
  614. .It Ic \&%R Ar name
  615. Technical report name of an
  616. .Ic \&Rs
  617. block.
  618. .It Ic \&%T Ar title
  619. Article title of an
  620. .Ic \&Rs
  621. block.
  622. This macro may also be used in a non-bibliographical context when
  623. referring to article titles.
  624. .It Ic \&%U Ar protocol Ns :// Ns Ar path
  625. URI of reference document.
  626. .It Ic \&%V Ar number
  627. Volume number of an
  628. .Ic \&Rs
  629. block.
  630. .It Ic \&Ac
  631. Close an
  632. .Ic \&Ao
  633. block.
  634. Does not have any tail arguments.
  635. .Tg Ad
  636. .It Ic \&Ad Ar address
  637. Memory address.
  638. Do not use this for postal addresses.
  639. .Pp
  640. Examples:
  641. .Dl \&.Ad [0,$]
  642. .Dl \&.Ad 0x00000000
  643. .Tg An
  644. .It Ic \&An Fl split | nosplit | Ar first_name ... last_name
  645. Author name.
  646. Can be used both for the authors of the program, function, or driver
  647. documented in the manual, or for the authors of the manual itself.
  648. Requires either the name of an author or one of the following arguments:
  649. .Pp
  650. .Bl -tag -width "-nosplitX" -offset indent -compact
  651. .It Fl split
  652. Start a new output line before each subsequent invocation of
  653. .Ic \&An .
  654. .It Fl nosplit
  655. The opposite of
  656. .Fl split .
  657. .El
  658. .Pp
  659. The default is
  660. .Fl nosplit .
  661. The effect of selecting either of the
  662. .Fl split
  663. modes ends at the beginning of the
  664. .Em AUTHORS
  665. section.
  666. In the
  667. .Em AUTHORS
  668. section, the default is
  669. .Fl nosplit
  670. for the first author listing and
  671. .Fl split
  672. for all other author listings.
  673. .Pp
  674. Examples:
  675. .Dl \&.An -nosplit
  676. .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
  677. .It Ic \&Ao Ar block
  678. Begin a block enclosed by angle brackets.
  679. Does not have any head arguments.
  680. This macro is almost never useful.
  681. See
  682. .Ic \&Aq
  683. for more details.
  684. .Tg Ap
  685. .It Ic \&Ap
  686. Inserts an apostrophe without any surrounding whitespace.
  687. This is generally used as a grammatical device when referring to the verb
  688. form of a function.
  689. .Pp
  690. Examples:
  691. .Dl \&.Fn execve \&Ap d
  692. .Tg Aq
  693. .It Ic \&Aq Ar line
  694. Enclose the rest of the input line in angle brackets.
  695. The only important use case is for email addresses.
  696. See
  697. .Ic \&Mt
  698. for an example.
  699. .Pp
  700. Occasionally, it is used for names of characters and keys, for example:
  701. .Bd -literal -offset indent
  702. Press the
  703. \&.Aq escape
  704. key to ...
  705. .Ed
  706. .Pp
  707. For URIs, use
  708. .Ic \&Lk
  709. instead, and
  710. .Ic \&In
  711. for
  712. .Dq #include
  713. directives.
  714. Never wrap
  715. .Ic \&Ar
  716. in
  717. .Ic \&Aq .
  718. .Pp
  719. Since
  720. .Ic \&Aq
  721. usually renders with non-ASCII characters in non-ASCII output modes,
  722. do not use it where the ASCII characters
  723. .Sq <
  724. and
  725. .Sq >
  726. are required as syntax elements.
  727. Instead, use these characters directly in such cases, combining them
  728. with the macros
  729. .Ic \&Pf ,
  730. .Ic \&Ns ,
  731. or
  732. .Ic \&Eo
  733. as needed.
  734. .Pp
  735. See also
  736. .Ic \&Ao .
  737. .Tg Ar
  738. .It Ic \&Ar Op Ar placeholder ...
  739. Command arguments.
  740. If an argument is not provided, the string
  741. .Dq file ...\&
  742. is used as a default.
  743. .Pp
  744. Examples:
  745. .Dl ".Fl o Ar file"
  746. .Dl ".Ar"
  747. .Dl ".Ar arg1 , arg2 ."
  748. .Pp
  749. The arguments to the
  750. .Ic \&Ar
  751. macro are names and placeholders for command arguments;
  752. for fixed strings to be passed verbatim as arguments, use
  753. .Ic \&Fl
  754. or
  755. .Ic \&Cm .
  756. .Tg At
  757. .It Ic \&At Op Ar version
  758. Formats an
  759. .At
  760. version.
  761. Accepts one optional argument:
  762. .Pp
  763. .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
  764. .It Cm v[1-7] | 32v
  765. A version of
  766. .At .
  767. .It Cm III
  768. .At III .
  769. .It Cm V | V.[1-4]
  770. A version of
  771. .At V .
  772. .El
  773. .Pp
  774. Note that these arguments do not begin with a hyphen.
  775. .Pp
  776. Examples:
  777. .Dl \&.At
  778. .Dl \&.At III
  779. .Dl \&.At V.1
  780. .Pp
  781. See also
  782. .Ic \&Bsx ,
  783. .Ic \&Bx ,
  784. .Ic \&Dx ,
  785. .Ic \&Fx ,
  786. .Ic \&Nx ,
  787. and
  788. .Ic \&Ox .
  789. .It Ic \&Bc
  790. Close a
  791. .Ic \&Bo
  792. block.
  793. Does not have any tail arguments.
  794. .Tg Bd
  795. .It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact
  796. Begin a display block.
  797. Display blocks are used to select a different indentation and
  798. justification than the one used by the surrounding text.
  799. They may contain both macro lines and text lines.
  800. By default, a display block is preceded by a vertical space.
  801. .Pp
  802. The
  803. .Ar type
  804. must be one of the following:
  805. .Bl -tag -width 13n -offset indent
  806. .It Fl centered
  807. Produce one output line from each input line, and center-justify each line.
  808. Using this display type is not recommended; many
  809. .Nm
  810. implementations render it poorly.
  811. .It Fl filled
  812. Change the positions of line breaks to fill each line, and left- and
  813. right-justify the resulting block.
  814. .It Fl literal
  815. Produce one output line from each input line,
  816. and do not justify the block at all.
  817. Preserve white space as it appears in the input.
  818. Always use a constant-width font.
  819. Use this for displaying source code.
  820. .It Fl ragged
  821. Change the positions of line breaks to fill each line, and left-justify
  822. the resulting block.
  823. .It Fl unfilled
  824. The same as
  825. .Fl literal ,
  826. but using the same font as for normal text, which is a variable width font
  827. if supported by the output device.
  828. .El
  829. .Pp
  830. The
  831. .Ar type
  832. must be provided first.
  833. Additional arguments may follow:
  834. .Bl -tag -width 13n -offset indent
  835. .It Fl offset Ar width
  836. Indent the display by the
  837. .Ar width ,
  838. which may be one of the following:
  839. .Bl -item
  840. .It
  841. One of the pre-defined strings
  842. .Cm indent ,
  843. the width of a standard indentation (six constant width characters);
  844. .Cm indent-two ,
  845. twice
  846. .Cm indent ;
  847. .Cm left ,
  848. which has no effect;
  849. .Cm right ,
  850. which justifies to the right margin; or
  851. .Cm center ,
  852. which aligns around an imagined center axis.
  853. .It
  854. A macro invocation, which selects a predefined width
  855. associated with that macro.
  856. The most popular is the imaginary macro
  857. .Ar \&Ds ,
  858. which resolves to
  859. .Sy 6n .
  860. .It
  861. A scaling width as described in
  862. .Xr roff 7 .
  863. .It
  864. An arbitrary string, which indents by the length of this string.
  865. .El
  866. .Pp
  867. When the argument is missing,
  868. .Fl offset
  869. is ignored.
  870. .It Fl compact
  871. Do not assert vertical space before the display.
  872. .El
  873. .Pp
  874. Examples:
  875. .Bd -literal -offset indent
  876. \&.Bd \-literal \-offset indent \-compact
  877. Hello world.
  878. \&.Ed
  879. .Ed
  880. .Pp
  881. See also
  882. .Ic \&D1
  883. and
  884. .Ic \&Dl .
  885. .Tg Bf
  886. .It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy
  887. Change the font mode for a scoped block of text.
  888. The
  889. .Fl emphasis
  890. and
  891. .Cm \&Em
  892. argument are equivalent, as are
  893. .Fl symbolic
  894. and
  895. .Cm \&Sy ,
  896. and
  897. .Fl literal
  898. and
  899. .Cm \&Li .
  900. Without an argument, this macro does nothing.
  901. The font mode continues until broken by a new font mode in a nested
  902. scope or
  903. .Ic \&Ef
  904. is encountered.
  905. .Pp
  906. See also
  907. .Ic \&Li ,
  908. .Ic \&Ef ,
  909. .Ic \&Em ,
  910. and
  911. .Ic \&Sy .
  912. .Tg Bk
  913. .It Ic \&Bk Fl words
  914. For each macro, keep its output together on the same output line,
  915. until the end of the macro or the end of the input line is reached,
  916. whichever comes first.
  917. Line breaks in text lines are unaffected.
  918. .Pp
  919. The
  920. .Fl words
  921. argument is required; additional arguments are ignored.
  922. .Pp
  923. The following example will not break within each
  924. .Ic \&Op
  925. macro line:
  926. .Bd -literal -offset indent
  927. \&.Bk \-words
  928. \&.Op Fl f Ar flags
  929. \&.Op Fl o Ar output
  930. \&.Ek
  931. .Ed
  932. .Pp
  933. Be careful in using over-long lines within a keep block!
  934. Doing so will clobber the right margin.
  935. .Tg Bl
  936. .It Xo
  937. .Ic \&Bl
  938. .Fl Ns Ar type
  939. .Op Fl width Ar val
  940. .Op Fl offset Ar val
  941. .Op Fl compact
  942. .Op Ar col ...
  943. .Xc
  944. Begin a list.
  945. Lists consist of items specified using the
  946. .Ic \&It
  947. macro, containing a head or a body or both.
  948. .Pp
  949. The list
  950. .Ar type
  951. is mandatory and must be specified first.
  952. The
  953. .Fl width
  954. and
  955. .Fl offset
  956. arguments accept macro names as described for
  957. .Ic \&Bd
  958. .Fl offset ,
  959. scaling widths as described in
  960. .Xr roff 7 ,
  961. or use the length of the given string.
  962. The
  963. .Fl offset
  964. is a global indentation for the whole list, affecting both item heads
  965. and bodies.
  966. For those list types supporting it, the
  967. .Fl width
  968. argument requests an additional indentation of item bodies,
  969. to be added to the
  970. .Fl offset .
  971. Unless the
  972. .Fl compact
  973. argument is specified, list entries are separated by vertical space.
  974. .Pp
  975. A list must specify one of the following list types:
  976. .Bl -tag -width 12n -offset indent
  977. .It Fl bullet
  978. No item heads can be specified, but a bullet will be printed at the head
  979. of each item.
  980. Item bodies start on the same output line as the bullet
  981. and are indented according to the
  982. .Fl width
  983. argument.
  984. .It Fl column
  985. A columnated list.
  986. The
  987. .Fl width
  988. argument has no effect; instead, the string length of each argument
  989. specifies the width of one column.
  990. If the first line of the body of a
  991. .Fl column
  992. list is not an
  993. .Ic \&It
  994. macro line,
  995. .Ic \&It
  996. contexts spanning one input line each are implied until an
  997. .Ic \&It
  998. macro line is encountered, at which point items start being interpreted as
  999. described in the
  1000. .Ic \&It
  1001. documentation.
  1002. .It Fl dash
  1003. Like
  1004. .Fl bullet ,
  1005. except that dashes are used in place of bullets.
  1006. .It Fl diag
  1007. Like
  1008. .Fl inset ,
  1009. except that item heads are not parsed for macro invocations.
  1010. Most often used in the
  1011. .Em DIAGNOSTICS
  1012. section with error constants in the item heads.
  1013. .It Fl enum
  1014. A numbered list.
  1015. No item heads can be specified.
  1016. Formatted like
  1017. .Fl bullet ,
  1018. except that cardinal numbers are used in place of bullets,
  1019. starting at 1.
  1020. .It Fl hang
  1021. Like
  1022. .Fl tag ,
  1023. except that the first lines of item bodies are not indented, but follow
  1024. the item heads like in
  1025. .Fl inset
  1026. lists.
  1027. .It Fl hyphen
  1028. Synonym for
  1029. .Fl dash .
  1030. .It Fl inset
  1031. Item bodies follow items heads on the same line, using normal inter-word
  1032. spacing.
  1033. Bodies are not indented, and the
  1034. .Fl width
  1035. argument is ignored.
  1036. .It Fl item
  1037. No item heads can be specified, and none are printed.
  1038. Bodies are not indented, and the
  1039. .Fl width
  1040. argument is ignored.
  1041. .It Fl ohang
  1042. Item bodies start on the line following item heads and are not indented.
  1043. The
  1044. .Fl width
  1045. argument is ignored.
  1046. .It Fl tag
  1047. Item bodies are indented according to the
  1048. .Fl width
  1049. argument.
  1050. When an item head fits inside the indentation, the item body follows
  1051. this head on the same output line.
  1052. Otherwise, the body starts on the output line following the head.
  1053. .El
  1054. .Pp
  1055. Lists may be nested within lists and displays.
  1056. Nesting of
  1057. .Fl column
  1058. and
  1059. .Fl enum
  1060. lists may not be portable.
  1061. .Pp
  1062. See also
  1063. .Ic \&El
  1064. and
  1065. .Ic \&It .
  1066. .It Ic \&Bo Ar block
  1067. Begin a block enclosed by square brackets.
  1068. Does not have any head arguments.
  1069. .Pp
  1070. Examples:
  1071. .Bd -literal -offset indent -compact
  1072. \&.Bo 1 ,
  1073. \&.Dv BUFSIZ \&Bc
  1074. .Ed
  1075. .Pp
  1076. See also
  1077. .Ic \&Bq .
  1078. .Tg Bq
  1079. .It Ic \&Bq Ar line
  1080. Encloses its arguments in square brackets.
  1081. .Pp
  1082. Examples:
  1083. .Dl \&.Bq 1 , \&Dv BUFSIZ
  1084. .Pp
  1085. .Em Remarks :
  1086. this macro is sometimes abused to emulate optional arguments for
  1087. commands; the correct macros to use for this purpose are
  1088. .Ic \&Op ,
  1089. .Ic \&Oo ,
  1090. and
  1091. .Ic \&Oc .
  1092. .Pp
  1093. See also
  1094. .Ic \&Bo .
  1095. .It Ic \&Brc
  1096. Close a
  1097. .Ic \&Bro
  1098. block.
  1099. Does not have any tail arguments.
  1100. .It Ic \&Bro Ar block
  1101. Begin a block enclosed by curly braces.
  1102. Does not have any head arguments.
  1103. .Pp
  1104. Examples:
  1105. .Bd -literal -offset indent -compact
  1106. \&.Bro 1 , ... ,
  1107. \&.Va n \&Brc
  1108. .Ed
  1109. .Pp
  1110. See also
  1111. .Ic \&Brq .
  1112. .Tg Brq
  1113. .It Ic \&Brq Ar line
  1114. Encloses its arguments in curly braces.
  1115. .Pp
  1116. Examples:
  1117. .Dl \&.Brq 1 , ... , \&Va n
  1118. .Pp
  1119. See also
  1120. .Ic \&Bro .
  1121. .Tg Bsx
  1122. .It Ic \&Bsx Op Ar version
  1123. Format the
  1124. .Bsx
  1125. version provided as an argument, or a default value if
  1126. no argument is provided.
  1127. .Pp
  1128. Examples:
  1129. .Dl \&.Bsx 1.0
  1130. .Dl \&.Bsx
  1131. .Pp
  1132. See also
  1133. .Ic \&At ,
  1134. .Ic \&Bx ,
  1135. .Ic \&Dx ,
  1136. .Ic \&Fx ,
  1137. .Ic \&Nx ,
  1138. and
  1139. .Ic \&Ox .
  1140. .It Ic \&Bt
  1141. Supported only for compatibility, do not use this in new manuals.
  1142. Prints
  1143. .Dq is currently in beta test.
  1144. .Tg Bx
  1145. .It Ic \&Bx Op Ar version Op Ar variant
  1146. Format the
  1147. .Bx
  1148. version provided as an argument, or a default value if no
  1149. argument is provided.
  1150. .Pp
  1151. Examples:
  1152. .Dl \&.Bx 4.3 Tahoe
  1153. .Dl \&.Bx 4.4
  1154. .Dl \&.Bx
  1155. .Pp
  1156. See also
  1157. .Ic \&At ,
  1158. .Ic \&Bsx ,
  1159. .Ic \&Dx ,
  1160. .Ic \&Fx ,
  1161. .Ic \&Nx ,
  1162. and
  1163. .Ic \&Ox .
  1164. .Tg Cd
  1165. .It Ic \&Cd Ar line
  1166. Kernel configuration declaration.
  1167. This denotes strings accepted by
  1168. .Xr config 8 .
  1169. It is most often used in section 4 manual pages.
  1170. .Pp
  1171. Examples:
  1172. .Dl \&.Cd device le0 at scode?
  1173. .Pp
  1174. .Em Remarks :
  1175. this macro is commonly abused by using quoted literals to retain
  1176. whitespace and align consecutive
  1177. .Ic \&Cd
  1178. declarations.
  1179. This practise is discouraged.
  1180. .Tg Cm
  1181. .It Ic \&Cm Ar keyword ...
  1182. Command modifiers.
  1183. Typically used for fixed strings passed as arguments to interactive
  1184. commands, to commands in interpreted scripts, or to configuration
  1185. file directives, unless
  1186. .Ic \&Fl
  1187. is more appropriate.
  1188. .Pp
  1189. Examples:
  1190. .Dl ".Nm mt Fl f Ar device Cm rewind"
  1191. .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
  1192. .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
  1193. .Dl ".Ic set Fl o Cm vi"
  1194. .Dl ".Ic lookup Cm file bind"
  1195. .Dl ".Ic permit Ar identity Op Cm as Ar target"
  1196. .Tg D1
  1197. .It Ic \&D1 Ar line
  1198. One-line indented display.
  1199. This is formatted by the default rules and is useful for simple indented
  1200. statements.
  1201. It is followed by a newline.
  1202. .Pp
  1203. Examples:
  1204. .Dl \&.D1 \&Fl abcdefgh
  1205. .Pp
  1206. See also
  1207. .Ic \&Bd
  1208. and
  1209. .Ic \&Dl .
  1210. .It Ic \&Db
  1211. This macro is obsolete.
  1212. No replacement is needed.
  1213. It is ignored by
  1214. .Xr mandoc 1
  1215. and groff including its arguments.
  1216. It was formerly used to toggle a debugging mode.
  1217. .It Ic \&Dc
  1218. Close a
  1219. .Ic \&Do
  1220. block.
  1221. Does not have any tail arguments.
  1222. .Tg Dd
  1223. .It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year
  1224. Document date for display in the page footer,
  1225. by convention the date of the last change.
  1226. This is the mandatory first macro of any
  1227. .Nm
  1228. manual.
  1229. .Pp
  1230. The
  1231. .Ar month
  1232. is the full English month name, the
  1233. .Ar day
  1234. is an integer number, and the
  1235. .Ar year
  1236. is the full four-digit year.
  1237. .Pp
  1238. Other arguments are not portable; the
  1239. .Xr mandoc 1
  1240. utility handles them as follows:
  1241. .Bl -dash -offset 3n -compact
  1242. .It
  1243. To have the date automatically filled in by the
  1244. .Ox
  1245. version of
  1246. .Xr cvs 1 ,
  1247. the special string
  1248. .Dq $\&Mdocdate$
  1249. can be given as an argument.
  1250. .It
  1251. The traditional, purely numeric
  1252. .Xr man 7
  1253. format
  1254. .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
  1255. is accepted, too.
  1256. .It
  1257. If a date string cannot be parsed, it is used verbatim.
  1258. .It
  1259. If no date string is given, the current date is used.
  1260. .El
  1261. .Pp
  1262. Examples:
  1263. .Dl \&.Dd $\&Mdocdate$
  1264. .Dl \&.Dd $\&Mdocdate: July 2 2018$
  1265. .Dl \&.Dd July 2, 2018
  1266. .Pp
  1267. See also
  1268. .Ic \&Dt
  1269. and
  1270. .Ic \&Os .
  1271. .Tg Dl
  1272. .It Ic \&Dl Ar line
  1273. One-line indented display.
  1274. This is formatted as literal text and is useful for commands and
  1275. invocations.
  1276. It is followed by a newline.
  1277. .Pp
  1278. Examples:
  1279. .Dl \&.Dl % mandoc mdoc.7 \e(ba less
  1280. .Pp
  1281. See also
  1282. .Ic \&Ql ,
  1283. .Ic \&Bd Fl literal ,
  1284. and
  1285. .Ic \&D1 .
  1286. .It Ic \&Do Ar block
  1287. Begin a block enclosed by double quotes.
  1288. Does not have any head arguments.
  1289. .Pp
  1290. Examples:
  1291. .Bd -literal -offset indent -compact
  1292. \&.Do
  1293. April is the cruellest month
  1294. \&.Dc
  1295. \e(em T.S. Eliot
  1296. .Ed
  1297. .Pp
  1298. See also
  1299. .Ic \&Dq .
  1300. .Tg Dq
  1301. .It Ic \&Dq Ar line
  1302. Encloses its arguments in
  1303. .Dq typographic
  1304. double-quotes.
  1305. .Pp
  1306. Examples:
  1307. .Bd -literal -offset indent -compact
  1308. \&.Dq April is the cruellest month
  1309. \e(em T.S. Eliot
  1310. .Ed
  1311. .Pp
  1312. See also
  1313. .Ic \&Qq ,
  1314. .Ic \&Sq ,
  1315. and
  1316. .Ic \&Do .
  1317. .Tg Dt
  1318. .It Ic \&Dt Ar TITLE section Op Ar arch
  1319. Document title for display in the page header.
  1320. This is the mandatory second macro of any
  1321. .Nm
  1322. file.
  1323. .Pp
  1324. Its arguments are as follows:
  1325. .Bl -tag -width section -offset 2n
  1326. .It Ar TITLE
  1327. The document's title (name), defaulting to
  1328. .Dq UNTITLED
  1329. if unspecified.
  1330. To achieve a uniform appearance of page header lines,
  1331. it should by convention be all caps.
  1332. .It Ar section
  1333. The manual section.
  1334. This may be one of
  1335. .Cm 1
  1336. .Pq General Commands ,
  1337. .Cm 2
  1338. .Pq System Calls ,
  1339. .Cm 3
  1340. .Pq Library Functions ,
  1341. .Cm 3p
  1342. .Pq Perl Library ,
  1343. .Cm 4
  1344. .Pq Device Drivers ,
  1345. .Cm 5
  1346. .Pq File Formats ,
  1347. .Cm 6
  1348. .Pq Games ,
  1349. .Cm 7
  1350. .Pq Miscellaneous Information ,
  1351. .Cm 8
  1352. .Pq System Manager's Manual ,
  1353. or
  1354. .Cm 9
  1355. .Pq Kernel Developer's Manual .
  1356. It should correspond to the manual's filename suffix and defaults to
  1357. the empty string if unspecified.
  1358. .It Ar arch
  1359. This specifies the machine architecture a manual page applies to,
  1360. where relevant, for example
  1361. .Cm alpha ,
  1362. .Cm amd64 ,
  1363. .Cm i386 ,
  1364. or
  1365. .Cm sparc64 .
  1366. The list of valid architectures varies by operating system.
  1367. .El
  1368. .Pp
  1369. Examples:
  1370. .Dl \&.Dt FOO 1
  1371. .Dl \&.Dt FOO 9 i386
  1372. .Pp
  1373. See also
  1374. .Ic \&Dd
  1375. and
  1376. .Ic \&Os .
  1377. .Tg Dv
  1378. .It Ic \&Dv Ar identifier ...
  1379. Defined variables such as preprocessor constants, constant symbols,
  1380. enumeration values, and so on.
  1381. .Pp
  1382. Examples:
  1383. .Dl \&.Dv NULL
  1384. .Dl \&.Dv BUFSIZ
  1385. .Dl \&.Dv STDOUT_FILENO
  1386. .Pp
  1387. See also
  1388. .Ic \&Er
  1389. and
  1390. .Ic \&Ev
  1391. for special-purpose constants,
  1392. .Ic \&Va
  1393. for variable symbols, and
  1394. .Ic \&Fd
  1395. for listing preprocessor variable definitions in the
  1396. .Em SYNOPSIS .
  1397. .Tg Dx
  1398. .It Ic \&Dx Op Ar version
  1399. Format the
  1400. .Dx
  1401. version provided as an argument, or a default
  1402. value if no argument is provided.
  1403. .Pp
  1404. Examples:
  1405. .Dl \&.Dx 2.4.1
  1406. .Dl \&.Dx
  1407. .Pp
  1408. See also
  1409. .Ic \&At ,
  1410. .Ic \&Bsx ,
  1411. .Ic \&Bx ,
  1412. .Ic \&Fx ,
  1413. .Ic \&Nx ,
  1414. and
  1415. .Ic \&Ox .
  1416. .It Ic \&Ec Op Ar closing_delimiter
  1417. Close a scope started by
  1418. .Ic \&Eo .
  1419. .Pp
  1420. The
  1421. .Ar closing_delimiter
  1422. argument is used as the enclosure tail, for example, specifying \e(rq
  1423. will emulate
  1424. .Ic \&Dc .
  1425. .It Ic \&Ed
  1426. End a display context started by
  1427. .Ic \&Bd .
  1428. .It Ic \&Ef
  1429. End a font mode context started by
  1430. .Ic \&Bf .
  1431. .It Ic \&Ek
  1432. End a keep context started by
  1433. .Ic \&Bk .
  1434. .It Ic \&El
  1435. End a list context started by
  1436. .Ic \&Bl .
  1437. See also
  1438. .Ic \&It .
  1439. .Tg Em
  1440. .It Ic \&Em Ar word ...
  1441. Request an italic font.
  1442. If the output device does not provide that, underline.
  1443. .Pp
  1444. This is most often used for stress emphasis (not to be confused with
  1445. importance, see
  1446. .Ic \&Sy ) .
  1447. In the rare cases where none of the semantic markup macros fit,
  1448. it can also be used for technical terms and placeholders, except
  1449. that for syntax elements,
  1450. .Ic \&Sy
  1451. and
  1452. .Ic \&Ar
  1453. are preferred, respectively.
  1454. .Pp
  1455. Examples:
  1456. .Bd -literal -compact -offset indent
  1457. Selected lines are those
  1458. \&.Em not
  1459. matching any of the specified patterns.
  1460. Some of the functions use a
  1461. \&.Em hold space
  1462. to save the pattern space for subsequent retrieval.
  1463. .Ed
  1464. .Pp
  1465. See also
  1466. .Ic \&No ,
  1467. .Ic \&Ql ,
  1468. and
  1469. .Ic \&Sy .
  1470. .It Ic \&En Ar word ...
  1471. This macro is obsolete.
  1472. Use
  1473. .Ic \&Eo
  1474. or any of the other enclosure macros.
  1475. .Pp
  1476. It encloses its argument in the delimiters specified by the last
  1477. .Ic \&Es
  1478. macro.
  1479. .Tg Eo
  1480. .It Ic \&Eo Op Ar opening_delimiter
  1481. An arbitrary enclosure.
  1482. The
  1483. .Ar opening_delimiter
  1484. argument is used as the enclosure head, for example, specifying \e(lq
  1485. will emulate
  1486. .Ic \&Do .
  1487. .Tg Er
  1488. .It Ic \&Er Ar identifier ...
  1489. Error constants for definitions of the
  1490. .Va errno
  1491. libc global variable.
  1492. This is most often used in section 2 and 3 manual pages.
  1493. .Pp
  1494. Examples:
  1495. .Dl \&.Er EPERM
  1496. .Dl \&.Er ENOENT
  1497. .Pp
  1498. See also
  1499. .Ic \&Dv
  1500. for general constants.
  1501. .It Ic \&Es Ar opening_delimiter closing_delimiter
  1502. This macro is obsolete.
  1503. Use
  1504. .Ic \&Eo
  1505. or any of the other enclosure macros.
  1506. .Pp
  1507. It takes two arguments, defining the delimiters to be used by subsequent
  1508. .Ic \&En
  1509. macros.
  1510. .Tg Ev
  1511. .It Ic \&Ev Ar identifier ...
  1512. Environmental variables such as those specified in
  1513. .Xr environ 7 .
  1514. .Pp
  1515. Examples:
  1516. .Dl \&.Ev DISPLAY
  1517. .Dl \&.Ev PATH
  1518. .Pp
  1519. See also
  1520. .Ic \&Dv
  1521. for general constants.
  1522. .Tg Ex
  1523. .It Ic \&Ex Fl std Op Ar utility ...
  1524. Insert a standard sentence regarding command exit values of 0 on success
  1525. and >0 on failure.
  1526. This is most often used in section 1, 6, and 8 manual pages.
  1527. .Pp
  1528. If
  1529. .Ar utility
  1530. is not specified, the document's name set by
  1531. .Ic \&Nm
  1532. is used.
  1533. Multiple
  1534. .Ar utility
  1535. arguments are treated as separate utilities.
  1536. .Pp
  1537. See also
  1538. .Ic \&Rv .
  1539. .Tg Fa
  1540. .It Ic \&Fa Ar argument ...
  1541. Function argument or parameter.
  1542. Each argument may be a name and a type (recommended for the
  1543. .Em SYNOPSIS
  1544. section), a name alone (for function invocations),
  1545. or a type alone (for function prototypes).
  1546. If both a type and a name are given or if the type consists of multiple
  1547. words, all words belonging to the same function argument have to be
  1548. given in a single argument to the
  1549. .Ic \&Fa
  1550. macro.
  1551. .Pp
  1552. This macro is also used to specify the field name of a structure.
  1553. .Pp
  1554. Most often, the
  1555. .Ic \&Fa
  1556. macro is used in the
  1557. .Em SYNOPSIS
  1558. within
  1559. .Ic \&Fo
  1560. blocks when documenting multi-line function prototypes.
  1561. If invoked with multiple arguments, the arguments are separated by a
  1562. comma.
  1563. Furthermore, if the following macro is another
  1564. .Ic \&Fa ,
  1565. the last argument will also have a trailing comma.
  1566. .Pp
  1567. Examples:
  1568. .Dl \&.Fa \(dqconst char *p\(dq
  1569. .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
  1570. .Dl \&.Fa \(dqchar *\(dq size_t
  1571. .Pp
  1572. See also
  1573. .Ic \&Fo .
  1574. .It Ic \&Fc
  1575. End a function context started by
  1576. .Ic \&Fo .
  1577. .Tg Fd
  1578. .It Ic \&Fd Pf # Ar directive Op Ar argument ...
  1579. Preprocessor directive, in particular for listing it in the
  1580. .Em SYNOPSIS .
  1581. Historically, it was also used to document include files.
  1582. The latter usage has been deprecated in favour of
  1583. .Ic \&In .
  1584. .Pp
  1585. Examples:
  1586. .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
  1587. .Dl \&.Fd #define SIO_MAXNFDS
  1588. .Dl \&.Fd #ifdef FS_DEBUG
  1589. .Dl \&.Ft void
  1590. .Dl \&.Fn dbg_open \(dqconst char *\(dq
  1591. .Dl \&.Fd #endif
  1592. .Pp
  1593. See also
  1594. .Sx MANUAL STRUCTURE ,
  1595. .Ic \&In ,
  1596. and
  1597. .Ic \&Dv .
  1598. .Tg Fl
  1599. .It Ic \&Fl Op Ar word ...
  1600. Command-line flag or option.
  1601. Used when listing arguments to command-line utilities.
  1602. For each argument, prints an ASCII hyphen-minus character
  1603. .Sq \- ,
  1604. immediately followed by the argument.
  1605. If no arguments are provided, a hyphen-minus is printed followed by a space.
  1606. If the argument is a macro, a hyphen-minus is prefixed
  1607. to the subsequent macro output.
  1608. .Pp
  1609. Examples:
  1610. .Dl ".Nm du Op Fl H | L | P"
  1611. .Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
  1612. .Dl ".Nm route Cm add Fl inet Ar destination gateway"
  1613. .Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile"
  1614. .Dl ".Nm aucat Fl o Fl"
  1615. .Dl ".Nm kill Fl Ar signal_number"
  1616. .Pp
  1617. For GNU-sytle long options, escaping the additional hyphen-minus is not
  1618. strictly required, but may be safer with future versions of GNU troff; see
  1619. .Xr mandoc_char 7
  1620. for details.
  1621. .Pp
  1622. See also
  1623. .Ic \&Cm .
  1624. .Tg Fn
  1625. .It Ic \&Fn Ar funcname Op Ar argument ...
  1626. A function name.
  1627. .Pp
  1628. Function arguments are surrounded in parenthesis and
  1629. are delimited by commas.
  1630. If no arguments are specified, blank parenthesis are output.
  1631. In the
  1632. .Em SYNOPSIS
  1633. section, this macro starts a new output line,
  1634. and a blank line is automatically inserted between function definitions.
  1635. .Pp
  1636. Examples:
  1637. .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
  1638. .Dl \&.Fn funcname \(dqint arg0\(dq
  1639. .Dl \&.Fn funcname arg0
  1640. .Bd -literal -offset indent
  1641. \&.Ft functype
  1642. \&.Fn funcname
  1643. .Ed
  1644. .Pp
  1645. When referring to a function documented in another manual page, use
  1646. .Ic \&Xr
  1647. instead.
  1648. See also
  1649. .Sx MANUAL STRUCTURE ,
  1650. .Ic \&Fo ,
  1651. and
  1652. .Ic \&Ft .
  1653. .Tg Fo
  1654. .It Ic \&Fo Ar funcname
  1655. Begin a function block.
  1656. This is a multi-line version of
  1657. .Ic \&Fn .
  1658. .Pp
  1659. Invocations usually occur in the following context:
  1660. .Bd -ragged -offset indent
  1661. .Pf \. Ic \&Ft Ar functype
  1662. .br
  1663. .Pf \. Ic \&Fo Ar funcname
  1664. .br
  1665. .Pf \. Ic \&Fa Qq Ar argtype Ar argname
  1666. .br
  1667. \&.\.\.
  1668. .br
  1669. .Pf \. Ic \&Fc
  1670. .Ed
  1671. .Pp
  1672. A
  1673. .Ic \&Fo
  1674. scope is closed by
  1675. .Ic \&Fc .
  1676. .Pp
  1677. See also
  1678. .Sx MANUAL STRUCTURE ,
  1679. .Ic \&Fa ,
  1680. .Ic \&Fc ,
  1681. and
  1682. .Ic \&Ft .
  1683. .It Ic \&Fr Ar number
  1684. This macro is obsolete.
  1685. No replacement markup is needed.
  1686. .Pp
  1687. It was used to show numerical function return values in an italic font.
  1688. .Tg Ft
  1689. .It Ic \&Ft Ar functype
  1690. A function type.
  1691. .Pp
  1692. In the
  1693. .Em SYNOPSIS
  1694. section, a new output line is started after this macro.
  1695. .Pp
  1696. Examples:
  1697. .Dl \&.Ft int
  1698. .Bd -literal -offset indent -compact
  1699. \&.Ft functype
  1700. \&.Fn funcname
  1701. .Ed
  1702. .Pp
  1703. See also
  1704. .Sx MANUAL STRUCTURE ,
  1705. .Ic \&Fn ,
  1706. and
  1707. .Ic \&Fo .
  1708. .Tg Fx
  1709. .It Ic \&Fx Op Ar version
  1710. Format the
  1711. .Fx
  1712. version provided as an argument, or a default value
  1713. if no argument is provided.
  1714. .Pp
  1715. Examples:
  1716. .Dl \&.Fx 7.1
  1717. .Dl \&.Fx
  1718. .Pp
  1719. See also
  1720. .Ic \&At ,
  1721. .Ic \&Bsx ,
  1722. .Ic \&Bx ,
  1723. .Ic \&Dx ,
  1724. .Ic \&Nx ,
  1725. and
  1726. .Ic \&Ox .
  1727. .It Ic \&Hf Ar filename
  1728. This macro is not implemented in
  1729. .Xr mandoc 1 .
  1730. It was used to include the contents of a (header) file literally.
  1731. .Tg Ic
  1732. .It Ic \&Ic Ar keyword ...
  1733. Internal or interactive command, or configuration instruction
  1734. in a configuration file.
  1735. See also
  1736. .Ic \&Cm .
  1737. .Pp
  1738. Examples:
  1739. .Dl \&.Ic :wq
  1740. .Dl \&.Ic hash
  1741. .Dl \&.Ic alias
  1742. .Pp
  1743. Note that using
  1744. .Ic \&Ql ,
  1745. .Ic \&Dl ,
  1746. or
  1747. .Ic \&Bd Fl literal
  1748. is preferred for displaying code samples; the
  1749. .Ic \&Ic
  1750. macro is used when referring to an individual command name.
  1751. .Tg In
  1752. .It Ic \&In Ar filename
  1753. The name of an include file.
  1754. This macro is most often used in section 2, 3, and 9 manual pages.
  1755. .Pp
  1756. When invoked as the first macro on an input line in the
  1757. .Em SYNOPSIS
  1758. section, the argument is displayed in angle brackets
  1759. and preceded by
  1760. .Qq #include ,
  1761. and a blank line is inserted in front if there is a preceding
  1762. function declaration.
  1763. In other sections, it only encloses its argument in angle brackets
  1764. and causes no line break.
  1765. .Pp
  1766. Examples:
  1767. .Dl \&.In sys/types.h
  1768. .Pp
  1769. See also
  1770. .Sx MANUAL STRUCTURE .
  1771. .Tg It
  1772. .It Ic \&It Op Ar head
  1773. A list item.
  1774. The syntax of this macro depends on the list type.
  1775. .Pp
  1776. Lists
  1777. of type
  1778. .Fl hang ,
  1779. .Fl ohang ,
  1780. .Fl inset ,
  1781. and
  1782. .Fl diag
  1783. have the following syntax:
  1784. .Pp
  1785. .D1 Pf \. Ic \&It Ar args
  1786. .Pp
  1787. Lists of type
  1788. .Fl bullet ,
  1789. .Fl dash ,
  1790. .Fl enum ,
  1791. .Fl hyphen
  1792. and
  1793. .Fl item
  1794. have the following syntax:
  1795. .Pp
  1796. .D1 Pf \. Ic \&It
  1797. .Pp
  1798. with subsequent lines interpreted within the scope of the
  1799. .Ic \&It
  1800. until either a closing
  1801. .Ic \&El
  1802. or another
  1803. .Ic \&It .
  1804. .Pp
  1805. The
  1806. .Fl tag
  1807. list has the following syntax:
  1808. .Pp
  1809. .D1 Pf \. Ic \&It Op Cm args
  1810. .Pp
  1811. Subsequent lines are interpreted as with
  1812. .Fl bullet
  1813. and family.
  1814. The line arguments correspond to the list's left-hand side; body
  1815. arguments correspond to the list's contents.
  1816. .Pp
  1817. The
  1818. .Fl column
  1819. list is the most complicated.
  1820. Its syntax is as follows:
  1821. .Pp
  1822. .D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ...
  1823. .D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ...
  1824. .Pp
  1825. The arguments consist of one or more lines of text and macros
  1826. representing a complete table line.
  1827. Cells within the line are delimited by the special
  1828. .Ic \&Ta
  1829. block macro or by literal tab characters.
  1830. .Pp
  1831. Using literal tabs is strongly discouraged because they are very
  1832. hard to use correctly and
  1833. .Nm
  1834. code using them is very hard to read.
  1835. In particular, a blank character is syntactically significant
  1836. before and after the literal tab character.
  1837. If a word precedes or follows the tab without an intervening blank,
  1838. that word is never interpreted as a macro call, but always output
  1839. literally.
  1840. .Pp
  1841. The tab cell delimiter may only be used within the
  1842. .Ic \&It
  1843. line itself; on following lines, only the
  1844. .Ic \&Ta
  1845. macro can be used to delimit cells, and portability requires that
  1846. .Ic \&Ta
  1847. is called by other macros: some parsers do not recognize it when
  1848. it appears as the first macro on a line.
  1849. .Pp
  1850. Note that quoted strings may span tab-delimited cells on an
  1851. .Ic \&It
  1852. line.
  1853. For example,
  1854. .Pp
  1855. .Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
  1856. .Pp
  1857. will preserve the whitespace before both commas,
  1858. but not the whitespace before the semicolon.
  1859. .Pp
  1860. See also
  1861. .Ic \&Bl .
  1862. .Tg Lb
  1863. .It Ic \&Lb Cm lib Ns Ar name
  1864. Specify a library.
  1865. .Pp
  1866. The
  1867. .Ar name
  1868. parameter may be a system library, such as
  1869. .Cm z
  1870. or
  1871. .Cm pam ,
  1872. in which case a small library description is printed next to the linker
  1873. invocation; or a custom library, in which case the library name is
  1874. printed in quotes.
  1875. This is most commonly used in the
  1876. .Em SYNOPSIS
  1877. section as described in
  1878. .Sx MANUAL STRUCTURE .
  1879. .Pp
  1880. Examples:
  1881. .Dl \&.Lb libz
  1882. .Dl \&.Lb libmandoc
  1883. .Tg Li
  1884. .It Ic \&Li Ar word ...
  1885. Request a typewriter (literal) font.
  1886. Deprecated because on terminal output devices, this is usually
  1887. indistinguishable from normal text.
  1888. For literal displays, use
  1889. .Ic \&Ql Pq in-line ,
  1890. .Ic \&Dl Pq single line ,
  1891. or
  1892. .Ic \&Bd Fl literal Pq multi-line
  1893. instead.
  1894. .Tg Lk
  1895. .It Ic \&Lk Ar uri Op Ar display_name
  1896. Format a hyperlink.
  1897. .Pp
  1898. Examples:
  1899. .Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq
  1900. .Dl \&.Lk https://bsd.lv
  1901. .Pp
  1902. See also
  1903. .Ic \&Mt .
  1904. .It Ic \&Lp
  1905. Deprecated synonym for
  1906. .Ic \&Pp .
  1907. .Tg Ms
  1908. .It Ic \&Ms Ar name
  1909. Display a mathematical symbol.
  1910. .Pp
  1911. Examples:
  1912. .Dl \&.Ms sigma
  1913. .Dl \&.Ms aleph
  1914. .Tg Mt
  1915. .It Ic \&Mt Ar localpart Ns @ Ns Ar domain
  1916. Format a
  1917. .Dq mailto:
  1918. hyperlink.
  1919. .Pp
  1920. Examples:
  1921. .Dl \&.Mt discuss@manpages.bsd.lv
  1922. .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
  1923. .Tg Nd
  1924. .It Ic \&Nd Ar line
  1925. A one line description of the manual's content.
  1926. This is the mandatory last macro of the
  1927. .Em NAME
  1928. section and not appropriate for other sections.
  1929. .Pp
  1930. Examples:
  1931. .Dl Pf . Ic \&Nd mdoc language reference
  1932. .Dl Pf . Ic \&Nd format and display UNIX manuals
  1933. .Pp
  1934. The
  1935. .Ic \&Nd
  1936. macro technically accepts child macros and terminates with a subsequent
  1937. .Ic \&Sh
  1938. invocation.
  1939. Do not assume this behaviour: some
  1940. .Xr whatis 1
  1941. database generators are not smart enough to parse more than the line
  1942. arguments and will display macros verbatim.
  1943. .Pp
  1944. See also
  1945. .Ic \&Nm .
  1946. .Tg Nm
  1947. .It Ic \&Nm Op Ar name
  1948. The name of the manual page, or \(em in particular in section 1, 6,
  1949. and 8 pages \(em of an additional command or feature documented in
  1950. the manual page.
  1951. When first invoked, the
  1952. .Ic \&Nm
  1953. macro expects a single argument, the name of the manual page.
  1954. Usually, the first invocation happens in the
  1955. .Em NAME
  1956. section of the page.
  1957. The specified name will be remembered and used whenever the macro is
  1958. called again without arguments later in the page.
  1959. The
  1960. .Ic \&Nm
  1961. macro uses
  1962. .Sx Block full-implicit
  1963. semantics when invoked as the first macro on an input line in the
  1964. .Em SYNOPSIS
  1965. section; otherwise, it uses ordinary
  1966. .Sx In-line
  1967. semantics.
  1968. .Pp
  1969. Examples:
  1970. .Bd -literal -offset indent
  1971. \&.Sh SYNOPSIS
  1972. \&.Nm cat
  1973. \&.Op Fl benstuv
  1974. \&.Op Ar
  1975. .Ed
  1976. .Pp
  1977. In the
  1978. .Em SYNOPSIS
  1979. of section 2, 3 and 9 manual pages, use the
  1980. .Ic \&Fn
  1981. macro rather than
  1982. .Ic \&Nm
  1983. to mark up the name of the manual page.
  1984. .Tg No
  1985. .It Ic \&No Ar word ...
  1986. Normal text.
  1987. Closes the scope of any preceding in-line macro.
  1988. When used after physical formatting macros like
  1989. .Ic \&Em
  1990. or
  1991. .Ic \&Sy ,
  1992. switches back to the standard font face and weight.
  1993. Can also be used to embed plain text strings in macro lines
  1994. using semantic annotation macros.
  1995. .Pp
  1996. Examples:
  1997. .Dl ".Em italic , Sy bold , No and roman"
  1998. .Bd -literal -offset indent
  1999. \&.Sm off
  2000. \&.Cm :C No / Ar pattern No / Ar replacement No /
  2001. \&.Sm on
  2002. .Ed
  2003. .Pp
  2004. See also
  2005. .Ic \&Em ,
  2006. .Ic \&Ql ,
  2007. and
  2008. .Ic \&Sy .
  2009. .Tg Ns
  2010. .It Ic \&Ns
  2011. Suppress a space between the output of the preceding macro
  2012. and the following text or macro.
  2013. Following invocation, input is interpreted as normal text
  2014. just like after an
  2015. .Ic \&No
  2016. macro.
  2017. .Pp
  2018. This has no effect when invoked at the start of a macro line.
  2019. .Pp
  2020. Examples:
  2021. .Dl ".Ar name Ns = Ns Ar value"
  2022. .Dl ".Cm :M Ns Ar pattern"
  2023. .Dl ".Fl o Ns Ar output"
  2024. .Pp
  2025. See also
  2026. .Ic \&No
  2027. and
  2028. .Ic \&Sm .
  2029. .Tg Nx
  2030. .It Ic \&Nx Op Ar version
  2031. Format the
  2032. .Nx
  2033. version provided as an argument, or a default value if
  2034. no argument is provided.
  2035. .Pp
  2036. Examples:
  2037. .Dl \&.Nx 5.01
  2038. .Dl \&.Nx
  2039. .Pp
  2040. See also
  2041. .Ic \&At ,
  2042. .Ic \&Bsx ,
  2043. .Ic \&Bx ,
  2044. .Ic \&Dx ,
  2045. .Ic \&Fx ,
  2046. and
  2047. .Ic \&Ox .
  2048. .It Ic \&Oc
  2049. Close multi-line
  2050. .Ic \&Oo
  2051. context.
  2052. .It Ic \&Oo Ar block
  2053. Multi-line version of
  2054. .Ic \&Op .
  2055. .Pp
  2056. Examples:
  2057. .Bd -literal -offset indent -compact
  2058. \&.Oo
  2059. \&.Op Fl flag Ns Ar value
  2060. \&.Oc
  2061. .Ed
  2062. .Tg Op
  2063. .It Ic \&Op Ar line
  2064. Optional part of a command line.
  2065. Prints the argument(s) in brackets.
  2066. This is most often used in the
  2067. .Em SYNOPSIS
  2068. section of section 1 and 8 manual pages.
  2069. .Pp
  2070. Examples:
  2071. .Dl \&.Op \&Fl a \&Ar b
  2072. .Dl \&.Op \&Ar a | b
  2073. .Pp
  2074. See also
  2075. .Ic \&Oo .
  2076. .Tg Os
  2077. .It Ic \&Os Op Ar system Op Ar version
  2078. Operating system version for display in the page footer.
  2079. This is the mandatory third macro of
  2080. any
  2081. .Nm
  2082. file.
  2083. .Pp
  2084. The optional
  2085. .Ar system
  2086. parameter specifies the relevant operating system or environment.
  2087. It is suggested to leave it unspecified, in which case
  2088. .Xr mandoc 1
  2089. uses its
  2090. .Fl Ios
  2091. argument or, if that isn't specified either,
  2092. .Fa sysname
  2093. and
  2094. .Fa release
  2095. as returned by
  2096. .Xr uname 3 .
  2097. .Pp
  2098. Examples:
  2099. .Dl \&.Os
  2100. .Dl \&.Os KTH/CSC/TCS
  2101. .Dl \&.Os BSD 4.3
  2102. .Pp
  2103. See also
  2104. .Ic \&Dd
  2105. and
  2106. .Ic \&Dt .
  2107. .It Ic \&Ot Ar functype
  2108. This macro is obsolete.
  2109. Use
  2110. .Ic \&Ft
  2111. instead; with
  2112. .Xr mandoc 1 ,
  2113. both have the same effect.
  2114. .Pp
  2115. Historical
  2116. .Nm
  2117. packages described it as
  2118. .Dq "old function type (FORTRAN)" .
  2119. .Tg Ox
  2120. .It Ic \&Ox Op Ar version
  2121. Format the
  2122. .Ox
  2123. version provided as an argument, or a default value
  2124. if no argument is provided.
  2125. .Pp
  2126. Examples:
  2127. .Dl \&.Ox 4.5
  2128. .Dl \&.Ox
  2129. .Pp
  2130. See also
  2131. .Ic \&At ,
  2132. .Ic \&Bsx ,
  2133. .Ic \&Bx ,
  2134. .Ic \&Dx ,
  2135. .Ic \&Fx ,
  2136. and
  2137. .Ic \&Nx .
  2138. .Tg Pa
  2139. .It Ic \&Pa Ar name ...
  2140. An absolute or relative file system path, or a file or directory name.
  2141. If an argument is not provided, the character
  2142. .Sq \(ti
  2143. is used as a default.
  2144. .Pp
  2145. Examples:
  2146. .Dl \&.Pa /usr/bin/mandoc
  2147. .Dl \&.Pa /usr/share/man/man7/mdoc.7
  2148. .Pp
  2149. See also
  2150. .Ic \&Lk .
  2151. .It Ic \&Pc
  2152. Close parenthesised context opened by
  2153. .Ic \&Po .
  2154. .Tg Pf
  2155. .It Ic \&Pf Ar prefix macro Op Ar argument ...
  2156. Removes the space between its argument and the following macro.
  2157. It is equivalent to:
  2158. .Pp
  2159. .D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ...
  2160. .Pp
  2161. The
  2162. .Ar prefix
  2163. argument is not parsed for macro names or delimiters,
  2164. but used verbatim as if it were escaped.
  2165. .Pp
  2166. Examples:
  2167. .Dl ".Pf $ Ar variable_name"
  2168. .Dl ".Pf . Ar macro_name"
  2169. .Dl ".Pf 0x Ar hex_digits"
  2170. .Pp
  2171. See also
  2172. .Ic \&Ns
  2173. and
  2174. .Ic \&Sm .
  2175. .It Ic \&Po Ar block
  2176. Multi-line version of
  2177. .Ic \&Pq .
  2178. .Tg Pp
  2179. .It Ic \&Pp
  2180. Break a paragraph.
  2181. This will assert vertical space between prior and subsequent macros
  2182. and/or text.
  2183. .Pp
  2184. Paragraph breaks are not needed before or after
  2185. .Ic \&Sh
  2186. or
  2187. .Ic \&Ss
  2188. macros or before displays
  2189. .Pq Ic \&Bd Ar line
  2190. or lists
  2191. .Pq Ic \&Bl
  2192. unless the
  2193. .Fl compact
  2194. flag is given.
  2195. .Tg Pq
  2196. .It Ic \&Pq Ar line
  2197. Parenthesised enclosure.
  2198. .Pp
  2199. See also
  2200. .Ic \&Po .
  2201. .It Ic \&Qc
  2202. Close quoted context opened by
  2203. .Ic \&Qo .
  2204. .Tg Ql
  2205. .It Ic \&Ql Ar line
  2206. In-line literal display.
  2207. This can be used for complete command invocations and for multi-word
  2208. code examples when an indented display is not desired.
  2209. .Pp
  2210. See also
  2211. .Ic \&Dl
  2212. and
  2213. .Ic \&Bd
  2214. .Fl literal .
  2215. .It Ic \&Qo Ar block
  2216. Multi-line version of
  2217. .Ic \&Qq .
  2218. .Tg Qq
  2219. .It Ic \&Qq Ar line
  2220. Encloses its arguments in
  2221. .Qq typewriter
  2222. double-quotes.
  2223. Consider using
  2224. .Ic \&Dq .
  2225. .Pp
  2226. See also
  2227. .Ic \&Dq ,
  2228. .Ic \&Sq ,
  2229. and
  2230. .Ic \&Qo .
  2231. .It Ic \&Re
  2232. Close an
  2233. .Ic \&Rs
  2234. block.
  2235. Does not have any tail arguments.
  2236. .Tg Rs
  2237. .It Ic \&Rs
  2238. Begin a bibliographic
  2239. .Pq Dq reference
  2240. block.
  2241. Does not have any head arguments.
  2242. The block macro may only contain
  2243. .Ic \&%A ,
  2244. .Ic \&%B ,
  2245. .Ic \&%C ,
  2246. .Ic \&%D ,
  2247. .Ic \&%I ,
  2248. .Ic \&%J ,
  2249. .Ic \&%N ,
  2250. .Ic \&%O ,
  2251. .Ic \&%P ,
  2252. .Ic \&%Q ,
  2253. .Ic \&%R ,
  2254. .Ic \&%T ,
  2255. .Ic \&%U ,
  2256. and
  2257. .Ic \&%V
  2258. child macros (at least one must be specified).
  2259. .Pp
  2260. Examples:
  2261. .Bd -literal -offset indent -compact
  2262. \&.Rs
  2263. \&.%A J. E. Hopcroft
  2264. \&.%A J. D. Ullman
  2265. \&.%B Introduction to Automata Theory, Languages, and Computation
  2266. \&.%I Addison-Wesley
  2267. \&.%C Reading, Massachusetts
  2268. \&.%D 1979
  2269. \&.Re
  2270. .Ed
  2271. .Pp
  2272. If an
  2273. .Ic \&Rs
  2274. block is used within a SEE ALSO section, a vertical space is asserted
  2275. before the rendered output, else the block continues on the current
  2276. line.
  2277. .Tg Rv
  2278. .It Ic \&Rv Fl std Op Ar function ...
  2279. Insert a standard sentence regarding a function call's return value of 0
  2280. on success and \-1 on error, with the
  2281. .Va errno
  2282. libc global variable set on error.
  2283. .Pp
  2284. If
  2285. .Ar function
  2286. is not specified, the document's name set by
  2287. .Ic \&Nm
  2288. is used.
  2289. Multiple
  2290. .Ar function
  2291. arguments are treated as separate functions.
  2292. .Pp
  2293. See also
  2294. .Ic \&Ex .
  2295. .It Ic \&Sc
  2296. Close single-quoted context opened by
  2297. .Ic \&So .
  2298. .Tg Sh
  2299. .It Ic \&Sh Ar TITLE LINE
  2300. Begin a new section.
  2301. For a list of conventional manual sections, see
  2302. .Sx MANUAL STRUCTURE .
  2303. These sections should be used unless it's absolutely necessary that
  2304. custom sections be used.
  2305. .Pp
  2306. Section names should be unique so that they may be keyed by
  2307. .Ic \&Sx .
  2308. Although this macro is parsed, it should not consist of child node or it
  2309. may not be linked with
  2310. .Ic \&Sx .
  2311. .Pp
  2312. See also
  2313. .Ic \&Pp ,
  2314. .Ic \&Ss ,
  2315. and
  2316. .Ic \&Sx .
  2317. .Tg Sm
  2318. .It Ic \&Sm Op Cm on | off
  2319. Switches the spacing mode for output generated from macros.
  2320. .Pp
  2321. By default, spacing is
  2322. .Cm on .
  2323. When switched
  2324. .Cm off ,
  2325. no white space is inserted between macro arguments and between the
  2326. output generated from adjacent macros, but text lines
  2327. still get normal spacing between words and sentences.
  2328. .Pp
  2329. When called without an argument, the
  2330. .Ic \&Sm
  2331. macro toggles the spacing mode.
  2332. Using this is not recommended because it makes the code harder to read.
  2333. .It Ic \&So Ar block
  2334. Multi-line version of
  2335. .Ic \&Sq .
  2336. .Tg Sq
  2337. .It Ic \&Sq Ar line
  2338. Encloses its arguments in
  2339. .Sq typewriter
  2340. single-quotes.
  2341. .Pp
  2342. See also
  2343. .Ic \&Dq ,
  2344. .Ic \&Qq ,
  2345. and
  2346. .Ic \&So .
  2347. .Tg Ss
  2348. .It Ic \&Ss Ar Title line
  2349. Begin a new subsection.
  2350. Unlike with
  2351. .Ic \&Sh ,
  2352. there is no convention for the naming of subsections.
  2353. Except
  2354. .Em DESCRIPTION ,
  2355. the conventional sections described in
  2356. .Sx MANUAL STRUCTURE
  2357. rarely have subsections.
  2358. .Pp
  2359. Sub-section names should be unique so that they may be keyed by
  2360. .Ic \&Sx .
  2361. Although this macro is parsed, it should not consist of child node or it
  2362. may not be linked with
  2363. .Ic \&Sx .
  2364. .Pp
  2365. See also
  2366. .Ic \&Pp ,
  2367. .Ic \&Sh ,
  2368. and
  2369. .Ic \&Sx .
  2370. .Tg St
  2371. .It Ic \&St Fl Ns Ar abbreviation
  2372. Replace an abbreviation for a standard with the full form.
  2373. The following standards are recognised.
  2374. Where multiple lines are given without a blank line in between,
  2375. they all refer to the same standard, and using the first form
  2376. is recommended.
  2377. .Bl -tag -width 1n
  2378. .It C language standards
  2379. .Pp
  2380. .Bl -tag -width "-p1003.1g-2000" -compact
  2381. .It \-ansiC
  2382. .St -ansiC
  2383. .It \-ansiC-89
  2384. .St -ansiC-89
  2385. .It \-isoC
  2386. .St -isoC
  2387. .It \-isoC-90
  2388. .St -isoC-90
  2389. .br
  2390. The original C standard.
  2391. .Pp
  2392. .It \-isoC-amd1
  2393. .St -isoC-amd1
  2394. .Pp
  2395. .It \-isoC-tcor1
  2396. .St -isoC-tcor1
  2397. .Pp
  2398. .It \-isoC-tcor2
  2399. .St -isoC-tcor2
  2400. .Pp
  2401. .It \-isoC-99
  2402. .St -isoC-99
  2403. .br
  2404. The second major version of the C language standard.
  2405. .Pp
  2406. .It \-isoC-2011
  2407. .St -isoC-2011
  2408. .br
  2409. The third major version of the C language standard.
  2410. .El
  2411. .It POSIX.1 before the Single UNIX Specification
  2412. .Pp
  2413. .Bl -tag -width "-p1003.1g-2000" -compact
  2414. .It \-p1003.1-88
  2415. .St -p1003.1-88
  2416. .It \-p1003.1
  2417. .St -p1003.1
  2418. .br
  2419. The original POSIX standard, based on ANSI C.
  2420. .Pp
  2421. .It \-p1003.1-90
  2422. .St -p1003.1-90
  2423. .It \-iso9945-1-90
  2424. .St -iso9945-1-90
  2425. .br
  2426. The first update of POSIX.1.
  2427. .Pp
  2428. .It \-p1003.1b-93
  2429. .St -p1003.1b-93
  2430. .It \-p1003.1b
  2431. .St -p1003.1b
  2432. .br
  2433. Real-time extensions.
  2434. .Pp
  2435. .It \-p1003.1c-95
  2436. .St -p1003.1c-95
  2437. .br
  2438. POSIX thread interfaces.
  2439. .Pp
  2440. .It \-p1003.1i-95
  2441. .St -p1003.1i-95
  2442. .br
  2443. Technical Corrigendum.
  2444. .Pp
  2445. .It \-p1003.1-96
  2446. .St -p1003.1-96
  2447. .It \-iso9945-1-96
  2448. .St -iso9945-1-96
  2449. .br
  2450. Includes POSIX.1-1990, 1b, 1c, and 1i.
  2451. .El
  2452. .It X/Open Portability Guide version 4 and related standards
  2453. .Pp
  2454. .Bl -tag -width "-p1003.1g-2000" -compact
  2455. .It \-xpg3
  2456. .St -xpg3
  2457. .br
  2458. An XPG4 precursor, published in 1989.
  2459. .Pp
  2460. .It \-p1003.2
  2461. .St -p1003.2
  2462. .It \-p1003.2-92
  2463. .St -p1003.2-92
  2464. .It \-iso9945-2-93
  2465. .St -iso9945-2-93
  2466. .br
  2467. An XCU4 precursor.
  2468. .Pp
  2469. .It \-p1003.2a-92
  2470. .St -p1003.2a-92
  2471. .br
  2472. Updates to POSIX.2.
  2473. .Pp
  2474. .It \-xpg4
  2475. .St -xpg4
  2476. .br
  2477. Based on POSIX.1 and POSIX.2, published in 1992.
  2478. .El
  2479. .It Single UNIX Specification version 1 and related standards
  2480. .Pp
  2481. .Bl -tag -width "-p1003.1g-2000" -compact
  2482. .It \-susv1
  2483. .St -susv1
  2484. .It \-xpg4.2
  2485. .St -xpg4.2
  2486. .br
  2487. This standard was published in 1994.
  2488. It was used as the basis for UNIX 95 certification.
  2489. The following three refer to parts of it.
  2490. .Pp
  2491. .It \-xsh4.2
  2492. .St -xsh4.2
  2493. .Pp
  2494. .It \-xcurses4.2
  2495. .St -xcurses4.2
  2496. .Pp
  2497. .It \-p1003.1g-2000
  2498. .St -p1003.1g-2000
  2499. .br
  2500. Networking APIs, including sockets.
  2501. .Pp
  2502. .It \-svid4
  2503. .St -svid4 ,
  2504. .br
  2505. Published in 1995.
  2506. .El
  2507. .It Single UNIX Specification version 2 and related standards
  2508. .Pp
  2509. .Bl -tag -width "-p1003.1g-2000" -compact
  2510. .It \-susv2
  2511. .St -susv2
  2512. This Standard was published in 1997
  2513. and is also called X/Open Portability Guide version 5.
  2514. It was used as the basis for UNIX 98 certification.
  2515. The following refer to parts of it.
  2516. .Pp
  2517. .It \-xbd5
  2518. .St -xbd5
  2519. .Pp
  2520. .It \-xsh5
  2521. .St -xsh5
  2522. .Pp
  2523. .It \-xcu5
  2524. .St -xcu5
  2525. .Pp
  2526. .It \-xns5
  2527. .St -xns5
  2528. .It \-xns5.2
  2529. .St -xns5.2
  2530. .El
  2531. .It Single UNIX Specification version 3
  2532. .Pp
  2533. .Bl -tag -width "-p1003.1-2001" -compact
  2534. .It \-p1003.1-2001
  2535. .St -p1003.1-2001
  2536. .It \-susv3
  2537. .St -susv3
  2538. .br
  2539. This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
  2540. It is also called X/Open Portability Guide version 6.
  2541. It is used as the basis for UNIX 03 certification.
  2542. .Pp
  2543. .It \-p1003.1-2004
  2544. .St -p1003.1-2004
  2545. .br
  2546. The second and last Technical Corrigendum.
  2547. .El
  2548. .It Single UNIX Specification version 4
  2549. .Pp
  2550. .Bl -tag -width "-p1003.1g-2000" -compact
  2551. .It \-p1003.1-2008
  2552. .St -p1003.1-2008
  2553. .It \-susv4
  2554. .St -susv4
  2555. .br
  2556. This standard is also called
  2557. X/Open Portability Guide version 7.
  2558. .El
  2559. .It Other standards
  2560. .Pp
  2561. .Bl -tag -width "-p1003.1g-2000" -compact
  2562. .It \-ieee754
  2563. .St -ieee754
  2564. .br
  2565. Floating-point arithmetic.
  2566. .Pp
  2567. .It \-iso8601
  2568. .St -iso8601
  2569. .br
  2570. Representation of dates and times, published in 1988.
  2571. .Pp
  2572. .It \-iso8802-3
  2573. .St -iso8802-3
  2574. .br
  2575. Ethernet local area networks.
  2576. .Pp
  2577. .It \-ieee1275-94
  2578. .St -ieee1275-94
  2579. .El
  2580. .El
  2581. .Tg Sx
  2582. .It Ic \&Sx Ar Title line
  2583. Reference a section or subsection in the same manual page.
  2584. The referenced section or subsection name must be identical to the
  2585. enclosed argument, including whitespace.
  2586. .Pp
  2587. Examples:
  2588. .Dl \&.Sx MANUAL STRUCTURE
  2589. .Pp
  2590. See also
  2591. .Ic \&Sh
  2592. and
  2593. .Ic \&Ss .
  2594. .Tg Sy
  2595. .It Ic \&Sy Ar word ...
  2596. Request a boldface font.
  2597. .Pp
  2598. This is most often used to indicate importance or seriousness (not to be
  2599. confused with stress emphasis, see
  2600. .Ic \&Em ) .
  2601. When none of the semantic macros fit, it is also adequate for syntax
  2602. elements that have to be given or that appear verbatim.
  2603. .Pp
  2604. Examples:
  2605. .Bd -literal -compact -offset indent
  2606. \&.Sy Warning :
  2607. If
  2608. \&.Sy s
  2609. appears in the owner permissions, set-user-ID mode is set.
  2610. This utility replaces the former
  2611. \&.Sy dumpdir
  2612. program.
  2613. .Ed
  2614. .Pp
  2615. See also
  2616. .Ic \&Em ,
  2617. .Ic \&No ,
  2618. and
  2619. .Ic \&Ql .
  2620. .Tg Ta
  2621. .It Ic \&Ta
  2622. Table cell separator in
  2623. .Ic \&Bl Fl column
  2624. lists; can only be used below
  2625. .Ic \&It .
  2626. .Tg Tg
  2627. .It Ic \&Tg Op Ar term
  2628. Announce that the next input line starts a definition of the
  2629. .Ar term .
  2630. This macro must appear alone on its own input line.
  2631. The argument defaults to the first argument of the first macro
  2632. on the next line.
  2633. The argument may not contain whitespace characters, not even when it is quoted.
  2634. This macro is a
  2635. .Xr mandoc 1
  2636. extension and is typically ignored by other formatters.
  2637. .Pp
  2638. When viewing terminal output with
  2639. .Xr less 1 ,
  2640. the interactive
  2641. .Ic :t
  2642. command can be used to go to the definition of the
  2643. .Ar term
  2644. as described for the
  2645. .Ev MANPAGER
  2646. variable in
  2647. .Xr man 1 ;
  2648. when producing HTML output, a fragment identifier
  2649. .Pq Ic id No attribute
  2650. is generated, to be used for deep linking to this place of the document.
  2651. .Pp
  2652. In most cases, adding a
  2653. .Ic \&Tg
  2654. macro would be redundant because
  2655. .Xr mandoc 1
  2656. is able to automatically tag most definitions.
  2657. This macro is intended for cases where automatic tagging of a
  2658. .Ar term
  2659. is unsatisfactory, for example if a definition is not tagged
  2660. automatically (false negative) or if places are tagged that do
  2661. not define the
  2662. .Ar term
  2663. (false positives).
  2664. When there is at least one
  2665. .Ic \&Tg
  2666. macro for a
  2667. .Ar term ,
  2668. no other places are automatically marked as definitions of that
  2669. .Ar term .
  2670. .It Ic \&Tn Ar word ...
  2671. Supported only for compatibility, do not use this in new manuals.
  2672. Even though the macro name
  2673. .Pq Dq tradename
  2674. suggests a semantic function, historic usage is inconsistent, mostly
  2675. using it as a presentation-level macro to request a small caps font.
  2676. .It Ic \&Ud
  2677. Supported only for compatibility, do not use this in new manuals.
  2678. Prints out
  2679. .Dq currently under development.
  2680. .It Ic \&Ux
  2681. Supported only for compatibility, do not use this in new manuals.
  2682. Prints out
  2683. .Dq Ux .
  2684. .Tg Va
  2685. .It Ic \&Va Oo Ar type Oc Ar identifier ...
  2686. A variable name.
  2687. .Pp
  2688. Examples:
  2689. .Dl \&.Va foo
  2690. .Dl \&.Va const char *bar ;
  2691. .Pp
  2692. For function arguments and parameters, use
  2693. .Ic \&Fa
  2694. instead.
  2695. For declarations of global variables in the
  2696. .Em SYNOPSIS
  2697. section, use
  2698. .Ic \&Vt .
  2699. .Tg Vt
  2700. .It Ic \&Vt Ar type Op Ar identifier
  2701. A variable type.
  2702. .Pp
  2703. This is also used for indicating global variables in the
  2704. .Em SYNOPSIS
  2705. section, in which case a variable name is also specified.
  2706. Note that it accepts
  2707. .Sx Block partial-implicit
  2708. syntax when invoked as the first macro on an input line in the
  2709. .Em SYNOPSIS
  2710. section, else it accepts ordinary
  2711. .Sx In-line
  2712. syntax.
  2713. In the former case, this macro starts a new output line,
  2714. and a blank line is inserted in front if there is a preceding
  2715. function definition or include directive.
  2716. .Pp
  2717. Examples:
  2718. .Dl \&.Vt unsigned char
  2719. .Dl \&.Vt extern const char * const sys_signame[] \&;
  2720. .Pp
  2721. For parameters in function prototypes, use
  2722. .Ic \&Fa
  2723. instead, for function return types
  2724. .Ic \&Ft ,
  2725. and for variable names outside the
  2726. .Em SYNOPSIS
  2727. section
  2728. .Ic \&Va ,
  2729. even when including a type with the name.
  2730. See also
  2731. .Sx MANUAL STRUCTURE .
  2732. .It Ic \&Xc
  2733. Close a scope opened by
  2734. .Ic \&Xo .
  2735. .It Ic \&Xo Ar block
  2736. Extend the header of an
  2737. .Ic \&It
  2738. macro or the body of a partial-implicit block macro
  2739. beyond the end of the input line.
  2740. This macro originally existed to work around the 9-argument limit
  2741. of historic
  2742. .Xr roff 7 .
  2743. .Tg Xr
  2744. .It Ic \&Xr Ar name section
  2745. Link to another manual
  2746. .Pq Qq cross-reference .
  2747. .Pp
  2748. Cross reference the
  2749. .Ar name
  2750. and
  2751. .Ar section
  2752. number of another man page.
  2753. .Pp
  2754. Examples:
  2755. .Dl \&.Xr mandoc 1
  2756. .Dl \&.Xr mandoc 1 \&;
  2757. .Dl \&.Xr mandoc 1 \&Ns s behaviour
  2758. .El
  2759. .Sh MACRO SYNTAX
  2760. The syntax of a macro depends on its classification.
  2761. In this section,
  2762. .Sq \-arg
  2763. refers to macro arguments, which may be followed by zero or more
  2764. .Sq parm
  2765. parameters;
  2766. .Sq \&Yo
  2767. opens the scope of a macro; and if specified,
  2768. .Sq \&Yc
  2769. closes it out.
  2770. .Pp
  2771. The
  2772. .Em Callable
  2773. column indicates that the macro may also be called by passing its name
  2774. as an argument to another macro.
  2775. For example,
  2776. .Sq \&.Op \&Fl O \&Ar file
  2777. produces
  2778. .Sq Op Fl O Ar file .
  2779. To prevent a macro call and render the macro name literally,
  2780. escape it by prepending a zero-width space,
  2781. .Sq \e& .
  2782. For example,
  2783. .Sq \&Op \e&Fl O
  2784. produces
  2785. .Sq Op \&Fl O .
  2786. If a macro is not callable but its name appears as an argument
  2787. to another macro, it is interpreted as opaque text.
  2788. For example,
  2789. .Sq \&.Fl \&Sh
  2790. produces
  2791. .Sq Fl \&Sh .
  2792. .Pp
  2793. The
  2794. .Em Parsed
  2795. column indicates whether the macro may call other macros by receiving
  2796. their names as arguments.
  2797. If a macro is not parsed but the name of another macro appears
  2798. as an argument, it is interpreted as opaque text.
  2799. .Pp
  2800. The
  2801. .Em Scope
  2802. column, if applicable, describes closure rules.
  2803. .Ss Block full-explicit
  2804. Multi-line scope closed by an explicit closing macro.
  2805. All macros contains bodies; only
  2806. .Ic \&Bf
  2807. and
  2808. .Pq optionally
  2809. .Ic \&Bl
  2810. contain a head.
  2811. .Bd -literal -offset indent
  2812. \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
  2813. \(lBbody...\(rB
  2814. \&.Yc
  2815. .Ed
  2816. .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
  2817. .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
  2818. .It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed
  2819. .It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef
  2820. .It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek
  2821. .It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El
  2822. .It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd
  2823. .It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf
  2824. .It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk
  2825. .It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl
  2826. .El
  2827. .Ss Block full-implicit
  2828. Multi-line scope closed by end-of-file or implicitly by another macro.
  2829. All macros have bodies; some
  2830. .Po
  2831. .Ic \&It Fl bullet ,
  2832. .Fl hyphen ,
  2833. .Fl dash ,
  2834. .Fl enum ,
  2835. .Fl item
  2836. .Pc
  2837. don't have heads; only one
  2838. .Po
  2839. .Ic \&It
  2840. in
  2841. .Ic \&Bl Fl column
  2842. .Pc
  2843. has multiple heads.
  2844. .Bd -literal -offset indent
  2845. \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
  2846. \(lBbody...\(rB
  2847. .Ed
  2848. .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
  2849. .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
  2850. .It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El
  2851. .It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh
  2852. .It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss
  2853. .It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh
  2854. .It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss
  2855. .El
  2856. .Pp
  2857. Note that the
  2858. .Ic \&Nm
  2859. macro is a
  2860. .Sx Block full-implicit
  2861. macro only when invoked as the first macro
  2862. in a
  2863. .Em SYNOPSIS
  2864. section line, else it is
  2865. .Sx In-line .
  2866. .Ss Block partial-explicit
  2867. Like block full-explicit, but also with single-line scope.
  2868. Each has at least a body and, in limited circumstances, a head
  2869. .Po
  2870. .Ic \&Fo ,
  2871. .Ic \&Eo
  2872. .Pc
  2873. and/or tail
  2874. .Pq Ic \&Ec .
  2875. .Bd -literal -offset indent
  2876. \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
  2877. \(lBbody...\(rB
  2878. \&.Yc \(lBtail...\(rB
  2879. \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
  2880. \(lBbody...\(rB \&Yc \(lBtail...\(rB
  2881. .Ed
  2882. .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
  2883. .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
  2884. .It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao
  2885. .It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac
  2886. .It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo
  2887. .It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc
  2888. .It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro
  2889. .It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc
  2890. .It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do
  2891. .It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc
  2892. .It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo
  2893. .It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec
  2894. .It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo
  2895. .It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc
  2896. .It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo
  2897. .It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc
  2898. .It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po
  2899. .It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc
  2900. .It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo
  2901. .It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc
  2902. .It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs
  2903. .It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re
  2904. .It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So
  2905. .It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc
  2906. .It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo
  2907. .It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc
  2908. .El
  2909. .Ss Block partial-implicit
  2910. Like block full-implicit, but with single-line scope closed by the
  2911. end of the line.
  2912. .Bd -literal -offset indent
  2913. \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
  2914. .Ed
  2915. .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
  2916. .It Em Macro Ta Em Callable Ta Em Parsed
  2917. .It Ic \&Aq Ta Yes Ta Yes
  2918. .It Ic \&Bq Ta Yes Ta Yes
  2919. .It Ic \&Brq Ta Yes Ta Yes
  2920. .It Ic \&D1 Ta \&No Ta \&Yes
  2921. .It Ic \&Dl Ta \&No Ta Yes
  2922. .It Ic \&Dq Ta Yes Ta Yes
  2923. .It Ic \&En Ta Yes Ta Yes
  2924. .It Ic \&Op Ta Yes Ta Yes
  2925. .It Ic \&Pq Ta Yes Ta Yes
  2926. .It Ic \&Ql Ta Yes Ta Yes
  2927. .It Ic \&Qq Ta Yes Ta Yes
  2928. .It Ic \&Sq Ta Yes Ta Yes
  2929. .It Ic \&Vt Ta Yes Ta Yes
  2930. .El
  2931. .Pp
  2932. Note that the
  2933. .Ic \&Vt
  2934. macro is a
  2935. .Sx Block partial-implicit
  2936. only when invoked as the first macro
  2937. in a
  2938. .Em SYNOPSIS
  2939. section line, else it is
  2940. .Sx In-line .
  2941. .Ss Special block macro
  2942. The
  2943. .Ic \&Ta
  2944. macro can only be used below
  2945. .Ic \&It
  2946. in
  2947. .Ic \&Bl Fl column
  2948. lists.
  2949. It delimits blocks representing table cells;
  2950. these blocks have bodies, but no heads.
  2951. .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
  2952. .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
  2953. .It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It
  2954. .El
  2955. .Ss In-line
  2956. Closed by the end of the line, fixed argument lengths,
  2957. and/or subsequent macros.
  2958. In-line macros have only text children.
  2959. If a number (or inequality) of arguments is
  2960. .Pq n ,
  2961. then the macro accepts an arbitrary number of arguments.
  2962. .Bd -literal -offset indent
  2963. \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
  2964. \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
  2965. \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
  2966. .Ed
  2967. .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
  2968. .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
  2969. .It Ic \&%A Ta \&No Ta \&No Ta >0
  2970. .It Ic \&%B Ta \&No Ta \&No Ta >0
  2971. .It Ic \&%C Ta \&No Ta \&No Ta >0
  2972. .It Ic \&%D Ta \&No Ta \&No Ta >0
  2973. .It Ic \&%I Ta \&No Ta \&No Ta >0
  2974. .It Ic \&%J Ta \&No Ta \&No Ta >0
  2975. .It Ic \&%N Ta \&No Ta \&No Ta >0
  2976. .It Ic \&%O Ta \&No Ta \&No Ta >0
  2977. .It Ic \&%P Ta \&No Ta \&No Ta >0
  2978. .It Ic \&%Q Ta \&No Ta \&No Ta >0
  2979. .It Ic \&%R Ta \&No Ta \&No Ta >0
  2980. .It Ic \&%T Ta \&No Ta \&No Ta >0
  2981. .It Ic \&%U Ta \&No Ta \&No Ta >0
  2982. .It Ic \&%V Ta \&No Ta \&No Ta >0
  2983. .It Ic \&Ad Ta Yes Ta Yes Ta >0
  2984. .It Ic \&An Ta Yes Ta Yes Ta >0
  2985. .It Ic \&Ap Ta Yes Ta Yes Ta 0
  2986. .It Ic \&Ar Ta Yes Ta Yes Ta n
  2987. .It Ic \&At Ta Yes Ta Yes Ta 1
  2988. .It Ic \&Bsx Ta Yes Ta Yes Ta n
  2989. .It Ic \&Bt Ta \&No Ta \&No Ta 0
  2990. .It Ic \&Bx Ta Yes Ta Yes Ta n
  2991. .It Ic \&Cd Ta Yes Ta Yes Ta >0
  2992. .It Ic \&Cm Ta Yes Ta Yes Ta >0
  2993. .It Ic \&Db Ta \&No Ta \&No Ta 1
  2994. .It Ic \&Dd Ta \&No Ta \&No Ta n
  2995. .It Ic \&Dt Ta \&No Ta \&No Ta n
  2996. .It Ic \&Dv Ta Yes Ta Yes Ta >0
  2997. .It Ic \&Dx Ta Yes Ta Yes Ta n
  2998. .It Ic \&Em Ta Yes Ta Yes Ta >0
  2999. .It Ic \&Er Ta Yes Ta Yes Ta >0
  3000. .It Ic \&Es Ta Yes Ta Yes Ta 2
  3001. .It Ic \&Ev Ta Yes Ta Yes Ta >0
  3002. .It Ic \&Ex Ta \&No Ta \&No Ta n
  3003. .It Ic \&Fa Ta Yes Ta Yes Ta >0
  3004. .It Ic \&Fd Ta \&No Ta \&No Ta >0
  3005. .It Ic \&Fl Ta Yes Ta Yes Ta n
  3006. .It Ic \&Fn Ta Yes Ta Yes Ta >0
  3007. .It Ic \&Fr Ta Yes Ta Yes Ta >0
  3008. .It Ic \&Ft Ta Yes Ta Yes Ta >0
  3009. .It Ic \&Fx Ta Yes Ta Yes Ta n
  3010. .It Ic \&Hf Ta \&No Ta \&No Ta n
  3011. .It Ic \&Ic Ta Yes Ta Yes Ta >0
  3012. .It Ic \&In Ta \&No Ta \&No Ta 1
  3013. .It Ic \&Lb Ta \&No Ta \&No Ta 1
  3014. .It Ic \&Li Ta Yes Ta Yes Ta >0
  3015. .It Ic \&Lk Ta Yes Ta Yes Ta >0
  3016. .It Ic \&Lp Ta \&No Ta \&No Ta 0
  3017. .It Ic \&Ms Ta Yes Ta Yes Ta >0
  3018. .It Ic \&Mt Ta Yes Ta Yes Ta >0
  3019. .It Ic \&Nm Ta Yes Ta Yes Ta n
  3020. .It Ic \&No Ta Yes Ta Yes Ta >0
  3021. .It Ic \&Ns Ta Yes Ta Yes Ta 0
  3022. .It Ic \&Nx Ta Yes Ta Yes Ta n
  3023. .It Ic \&Os Ta \&No Ta \&No Ta n
  3024. .It Ic \&Ot Ta Yes Ta Yes Ta >0
  3025. .It Ic \&Ox Ta Yes Ta Yes Ta n
  3026. .It Ic \&Pa Ta Yes Ta Yes Ta n
  3027. .It Ic \&Pf Ta Yes Ta Yes Ta 1
  3028. .It Ic \&Pp Ta \&No Ta \&No Ta 0
  3029. .It Ic \&Rv Ta \&No Ta \&No Ta n
  3030. .It Ic \&Sm Ta \&No Ta \&No Ta <2
  3031. .It Ic \&St Ta \&No Ta Yes Ta 1
  3032. .It Ic \&Sx Ta Yes Ta Yes Ta >0
  3033. .It Ic \&Sy Ta Yes Ta Yes Ta >0
  3034. .It Ic \&Tg Ta \&No Ta \&No Ta <2
  3035. .It Ic \&Tn Ta Yes Ta Yes Ta >0
  3036. .It Ic \&Ud Ta \&No Ta \&No Ta 0
  3037. .It Ic \&Ux Ta Yes Ta Yes Ta n
  3038. .It Ic \&Va Ta Yes Ta Yes Ta n
  3039. .It Ic \&Vt Ta Yes Ta Yes Ta >0
  3040. .It Ic \&Xr Ta Yes Ta Yes Ta 2
  3041. .El
  3042. .Ss Delimiters
  3043. When a macro argument consists of one single input character
  3044. considered as a delimiter, the argument gets special handling.
  3045. This does not apply when delimiters appear in arguments containing
  3046. more than one character.
  3047. Consequently, to prevent special handling and just handle it
  3048. like any other argument, a delimiter can be escaped by prepending
  3049. a zero-width space
  3050. .Pq Sq \e& .
  3051. In text lines, delimiters never need escaping, but may be used
  3052. as normal punctuation.
  3053. .Pp
  3054. For many macros, when the leading arguments are opening delimiters,
  3055. these delimiters are put before the macro scope,
  3056. and when the trailing arguments are closing delimiters,
  3057. these delimiters are put after the macro scope.
  3058. Spacing is suppressed after opening delimiters
  3059. and before closing delimiters.
  3060. For example,
  3061. .Pp
  3062. .D1 Pf \. \&Aq "( [ word ] ) ."
  3063. .Pp
  3064. renders as:
  3065. .Pp
  3066. .D1 Aq ( [ word ] ) .
  3067. .Pp
  3068. Opening delimiters are:
  3069. .Pp
  3070. .Bl -tag -width Ds -offset indent -compact
  3071. .It \&(
  3072. left parenthesis
  3073. .It \&[
  3074. left bracket
  3075. .El
  3076. .Pp
  3077. Closing delimiters are:
  3078. .Pp
  3079. .Bl -tag -width Ds -offset indent -compact
  3080. .It \&.
  3081. period
  3082. .It \&,
  3083. comma
  3084. .It \&:
  3085. colon
  3086. .It \&;
  3087. semicolon
  3088. .It \&)
  3089. right parenthesis
  3090. .It \&]
  3091. right bracket
  3092. .It \&?
  3093. question mark
  3094. .It \&!
  3095. exclamation mark
  3096. .El
  3097. .Pp
  3098. Note that even a period preceded by a backslash
  3099. .Pq Sq \e.\&
  3100. gets this special handling; use
  3101. .Sq \e&.\&
  3102. to prevent that.
  3103. .Pp
  3104. Many in-line macros interrupt their scope when they encounter
  3105. delimiters, and resume their scope when more arguments follow that
  3106. are not delimiters.
  3107. For example,
  3108. .Pp
  3109. .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
  3110. .Pp
  3111. renders as:
  3112. .Pp
  3113. .D1 Fl a ( b | c \*(Ba d ) e
  3114. .Pp
  3115. This applies to both opening and closing delimiters,
  3116. and also to the middle delimiter, which does not suppress spacing:
  3117. .Pp
  3118. .Bl -tag -width Ds -offset indent -compact
  3119. .It \&|
  3120. vertical bar
  3121. .El
  3122. .Pp
  3123. As a special case, the predefined string \e*(Ba is handled and rendered
  3124. in the same way as a plain
  3125. .Sq \&|
  3126. character.
  3127. Using this predefined string is not recommended in new manuals.
  3128. .Pp
  3129. Appending a zero-width space
  3130. .Pq Sq \e&
  3131. to the end of an input line is also useful to prevent the interpretation
  3132. of a trailing period, exclamation or question mark as the end of a
  3133. sentence, for example when an abbreviation happens to occur
  3134. at the end of a text or macro input line.
  3135. .Ss Font handling
  3136. In
  3137. .Nm
  3138. documents, usage of semantic markup is recommended in order to have
  3139. proper fonts automatically selected; only when no fitting semantic markup
  3140. is available, consider falling back to
  3141. .Sx Physical markup
  3142. macros.
  3143. Whenever any
  3144. .Nm
  3145. macro switches the
  3146. .Xr roff 7
  3147. font mode, it will automatically restore the previous font when exiting
  3148. its scope.
  3149. Manually switching the font using the
  3150. .Xr roff 7
  3151. .Ql \ef
  3152. font escape sequences is never required.
  3153. .Sh COMPATIBILITY
  3154. This section provides an incomplete list of compatibility issues
  3155. between mandoc and GNU troff
  3156. .Pq Qq groff .
  3157. .Pp
  3158. The following problematic behaviour is found in groff:
  3159. .Pp
  3160. .Bl -dash -compact
  3161. .It
  3162. .Ic \&Pa
  3163. does not format its arguments when used in the FILES section under
  3164. certain list types.
  3165. .It
  3166. .Ic \&Ta
  3167. can only be called by other macros, but not at the beginning of a line.
  3168. .It
  3169. .Sq \ef
  3170. .Pq font face
  3171. and
  3172. .Sq \eF
  3173. .Pq font family face
  3174. .Sx Text Decoration
  3175. escapes behave irregularly when specified within line-macro scopes.
  3176. .It
  3177. Negative scaling units return to prior lines.
  3178. Instead, mandoc truncates them to zero.
  3179. .El
  3180. .Pp
  3181. The following features are unimplemented in mandoc:
  3182. .Pp
  3183. .Bl -dash -compact
  3184. .It
  3185. .Ic \&Bd Fl file Ar file
  3186. is unsupported for security reasons.
  3187. .It
  3188. .Ic \&Bd
  3189. .Fl filled
  3190. does not adjust the right margin, but is an alias for
  3191. .Ic \&Bd
  3192. .Fl ragged .
  3193. .It
  3194. .Ic \&Bd
  3195. .Fl literal
  3196. does not use a literal font, but is an alias for
  3197. .Ic \&Bd
  3198. .Fl unfilled .
  3199. .It
  3200. .Ic \&Bd
  3201. .Fl offset Cm center
  3202. and
  3203. .Fl offset Cm right
  3204. don't work.
  3205. Groff does not implement centered and flush-right rendering either,
  3206. but produces large indentations.
  3207. .El
  3208. .Sh SEE ALSO
  3209. .Xr man 1 ,
  3210. .Xr mandoc 1 ,
  3211. .Xr eqn 7 ,
  3212. .Xr man 7 ,
  3213. .Xr mandoc_char 7 ,
  3214. .Xr roff 7 ,
  3215. .Xr tbl 7
  3216. .Pp
  3217. The web page
  3218. .Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
  3219. provides a few tutorial-style pages for beginners, an extensive style
  3220. guide for advanced authors, and an alphabetic index helping to choose
  3221. the best macros for various kinds of content.
  3222. .Pp
  3223. The manual page
  3224. .Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)"
  3225. contained in the
  3226. .Dq groff
  3227. package documents exactly the same language in a somewhat different style.
  3228. .Sh HISTORY
  3229. The
  3230. .Nm
  3231. language first appeared as a troff macro package in
  3232. .Bx 4.4 .
  3233. It was later significantly updated by Werner Lemberg and Ruslan Ermilov
  3234. in groff-1.17.
  3235. The standalone implementation that is part of the
  3236. .Xr mandoc 1
  3237. utility written by Kristaps Dzonsons appeared in
  3238. .Ox 4.6 .
  3239. .Sh AUTHORS
  3240. The
  3241. .Nm
  3242. reference was written by
  3243. .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .