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

man.7 (17815B)


  1. .\" $Id: man.7,v 1.148 2021/08/05 14:31:14 schwarze Exp $
  2. .\"
  3. .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
  4. .\" Copyright (c) 2011-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
  5. .\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
  6. .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
  7. .\"
  8. .\" Permission to use, copy, modify, and distribute this software for any
  9. .\" purpose with or without fee is hereby granted, provided that the above
  10. .\" copyright notice and this permission notice appear in all copies.
  11. .\"
  12. .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  13. .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  14. .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  15. .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  16. .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  17. .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  18. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  19. .\"
  20. .Dd $Mdocdate: August 5 2021 $
  21. .Dt MAN 7
  22. .Os
  23. .Sh NAME
  24. .Nm man
  25. .Nd legacy formatting language for manual pages
  26. .Sh DESCRIPTION
  27. The
  28. .Nm man
  29. language was the standard formatting language for
  30. .At
  31. manual pages from 1979 to 1989.
  32. Do not use it to write new manual pages: it is a purely presentational
  33. language and lacks support for semantic markup.
  34. Use the
  35. .Xr mdoc 7
  36. language, instead.
  37. .Pp
  38. In a
  39. .Nm
  40. document, lines beginning with the control character
  41. .Sq \&.
  42. are called
  43. .Dq macro lines .
  44. The first word is the macro name.
  45. It usually consists of two capital letters.
  46. For a list of portable macros, see
  47. .Sx MACRO OVERVIEW .
  48. The words following the macro name are arguments to the macro.
  49. .Pp
  50. Lines not beginning with the control character are called
  51. .Dq text lines .
  52. They provide free-form text to be printed; the formatting of the text
  53. depends on the respective processing context:
  54. .Bd -literal -offset indent
  55. \&.SH Macro lines change control state.
  56. Text lines are interpreted within the current state.
  57. .Ed
  58. .Pp
  59. Many aspects of the basic syntax of the
  60. .Nm
  61. language are based on the
  62. .Xr roff 7
  63. language; see the
  64. .Em LANGUAGE SYNTAX
  65. and
  66. .Em MACRO SYNTAX
  67. sections in the
  68. .Xr roff 7
  69. manual for details, in particular regarding
  70. comments, escape sequences, whitespace, and quoting.
  71. .Pp
  72. Each
  73. .Nm
  74. document starts with the
  75. .Ic TH
  76. macro specifying the document's name and section, followed by the
  77. .Sx NAME
  78. section formatted as follows:
  79. .Bd -literal -offset indent
  80. \&.TH PROGNAME 1 1979-01-10
  81. \&.SH NAME
  82. \efBprogname\efR \e(en one line about what it does
  83. .Ed
  84. .Sh MACRO OVERVIEW
  85. This overview is sorted such that macros of similar purpose are listed
  86. together.
  87. Deprecated and non-portable macros are not included in the overview,
  88. but can be found in the alphabetical reference below.
  89. .Ss Page header and footer meta-data
  90. .Bl -column "RS, RE" description
  91. .It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume
  92. .It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
  93. .It Ic UC Ta display BSD version in the page footer (<= 1 argument)
  94. .El
  95. .Ss Sections and paragraphs
  96. .Bl -column "RS, RE" description
  97. .It Ic SH Ta section header (one line)
  98. .It Ic SS Ta subsection header (one line)
  99. .It Ic PP Ta start an undecorated paragraph (no arguments)
  100. .It Ic RS , RE Ta reset the left margin: Op Ar width
  101. .It Ic IP Ta indented paragraph: Op Ar head Op Ar width
  102. .It Ic TP Ta tagged paragraph: Op Ar width
  103. .It Ic PD Ta set vertical paragraph distance: Op Ar height
  104. .It Ic in Ta additional indent: Op Ar width
  105. .El
  106. .Ss Physical markup
  107. .Bl -column "RS, RE" description
  108. .It Ic B Ta boldface font
  109. .It Ic I Ta italic font
  110. .It Ic SB Ta small boldface font
  111. .It Ic SM Ta small roman font
  112. .It Ic BI Ta alternate between boldface and italic fonts
  113. .It Ic BR Ta alternate between boldface and roman fonts
  114. .It Ic IB Ta alternate between italic and boldface fonts
  115. .It Ic IR Ta alternate between italic and roman fonts
  116. .It Ic RB Ta alternate between roman and boldface fonts
  117. .It Ic RI Ta alternate between roman and italic fonts
  118. .El
  119. .Sh MACRO REFERENCE
  120. This section is a canonical reference to all macros, arranged
  121. alphabetically.
  122. For the scoping of individual macros, see
  123. .Sx MACRO SYNTAX .
  124. .Bl -tag -width 3n
  125. .It Ic AT
  126. Sets the volume for the footer for compatibility with man pages from
  127. .At
  128. releases.
  129. The optional arguments specify which release it is from.
  130. This macro is an extension that first appeared in
  131. .Bx 4.3 .
  132. .It Ic B
  133. Text is rendered in bold face.
  134. .It Ic BI
  135. Text is rendered alternately in bold face and italic.
  136. Thus,
  137. .Sq .BI this word and that
  138. causes
  139. .Sq this
  140. and
  141. .Sq and
  142. to render in bold face, while
  143. .Sq word
  144. and
  145. .Sq that
  146. render in italics.
  147. Whitespace between arguments is omitted in output.
  148. .Pp
  149. Example:
  150. .Pp
  151. .Dl \&.BI bold italic bold italic
  152. .It Ic BR
  153. Text is rendered alternately in bold face and roman (the default font).
  154. Whitespace between arguments is omitted in output.
  155. See also
  156. .Ic BI .
  157. .It Ic DT
  158. Restore the default tabulator positions.
  159. They are at intervals of 0.5 inches.
  160. This has no effect unless the tabulator positions were changed with the
  161. .Xr roff 7
  162. .Ic ta
  163. request.
  164. .It Ic EE
  165. This is a non-standard Version 9
  166. .At
  167. extension later adopted by GNU.
  168. In
  169. .Xr mandoc 1 ,
  170. it does the same as the
  171. .Xr roff 7
  172. .Ic fi
  173. request (switch to fill mode).
  174. .It Ic EX
  175. This is a non-standard Version 9
  176. .At
  177. extension later adopted by GNU.
  178. In
  179. .Xr mandoc 1 ,
  180. it does the same as the
  181. .Xr roff 7
  182. .Ic nf
  183. request (switch to no-fill mode).
  184. .It Ic HP
  185. Begin a paragraph whose initial output line is left-justified, but
  186. subsequent output lines are indented, with the following syntax:
  187. .Pp
  188. .D1 Pf . Ic HP Op Ar width
  189. .Pp
  190. The
  191. .Ar width
  192. argument is a
  193. .Xr roff 7
  194. scaling width.
  195. If specified, it's saved for later paragraph left margins;
  196. if unspecified, the saved or default width is used.
  197. .Pp
  198. This macro is portable, but deprecated
  199. because it has no good representation in HTML output,
  200. usually ending up indistinguishable from
  201. .Ic PP .
  202. .It Ic I
  203. Text is rendered in italics.
  204. .It Ic IB
  205. Text is rendered alternately in italics and bold face.
  206. Whitespace between arguments is omitted in output.
  207. See also
  208. .Ic BI .
  209. .It Ic IP
  210. Begin an indented paragraph with the following syntax:
  211. .Pp
  212. .D1 Pf . Ic IP Op Ar head Op Ar width
  213. .Pp
  214. The
  215. .Ar width
  216. argument is a
  217. .Xr roff 7
  218. scaling width defining the left margin.
  219. It's saved for later paragraph left-margins; if unspecified, the saved or
  220. default width is used.
  221. .Pp
  222. The
  223. .Ar head
  224. argument is used as a leading term, flushed to the left margin.
  225. This is useful for bulleted paragraphs and so on.
  226. .It Ic IR
  227. Text is rendered alternately in italics and roman (the default font).
  228. Whitespace between arguments is omitted in output.
  229. See also
  230. .Ic BI .
  231. .It Ic LP
  232. A synonym for
  233. .Ic PP .
  234. .It Ic ME
  235. End a mailto block started with
  236. .Ic MT .
  237. This is a non-standard GNU extension.
  238. .It Ic MT
  239. Begin a mailto block.
  240. This is a non-standard GNU extension.
  241. It has the following syntax:
  242. .Bd -unfilled -offset indent
  243. .Pf . Ic MT Ar address
  244. link description to be shown
  245. .Pf . Ic ME
  246. .Ed
  247. .It Ic OP
  248. Optional command-line argument.
  249. This is a non-standard DWB extension.
  250. It has the following syntax:
  251. .Pp
  252. .D1 Pf . Ic OP Ar key Op Ar value
  253. .Pp
  254. The
  255. .Ar key
  256. is usually a command-line flag and
  257. .Ar value
  258. its argument.
  259. .It Ic P
  260. This synonym for
  261. .Ic PP
  262. is an
  263. .At III
  264. extension later adopted by
  265. .Bx 4.3 .
  266. .It Ic PD
  267. Specify the vertical space to be inserted before each new paragraph.
  268. .br
  269. The syntax is as follows:
  270. .Pp
  271. .D1 Pf . Ic PD Op Ar height
  272. .Pp
  273. The
  274. .Ar height
  275. argument is a
  276. .Xr roff 7
  277. scaling width.
  278. It defaults to
  279. .Cm 1v .
  280. If the unit is omitted,
  281. .Cm v
  282. is assumed.
  283. .Pp
  284. This macro affects the spacing before any subsequent instances of
  285. .Ic HP ,
  286. .Ic IP ,
  287. .Ic LP ,
  288. .Ic P ,
  289. .Ic PP ,
  290. .Ic SH ,
  291. .Ic SS ,
  292. .Ic SY ,
  293. and
  294. .Ic TP .
  295. .It Ic PP
  296. Begin an undecorated paragraph.
  297. The scope of a paragraph is closed by a subsequent paragraph,
  298. sub-section, section, or end of file.
  299. The saved paragraph left-margin width is reset to the default.
  300. .It Ic RB
  301. Text is rendered alternately in roman (the default font) and bold face.
  302. Whitespace between arguments is omitted in output.
  303. See also
  304. .Ic BI .
  305. .It Ic RE
  306. Explicitly close out the scope of a prior
  307. .Ic RS .
  308. The default left margin is restored to the state before that
  309. .Ic RS
  310. invocation.
  311. .Pp
  312. The syntax is as follows:
  313. .Pp
  314. .D1 Pf . Ic RE Op Ar level
  315. .Pp
  316. Without an argument, the most recent
  317. .Ic RS
  318. block is closed out.
  319. If
  320. .Ar level
  321. is 1, all open
  322. .Ic RS
  323. blocks are closed out.
  324. Otherwise,
  325. .Ar level No \(mi 1
  326. nested
  327. .Ic RS
  328. blocks remain open.
  329. .It Ic RI
  330. Text is rendered alternately in roman (the default font) and italics.
  331. Whitespace between arguments is omitted in output.
  332. See also
  333. .Ic BI .
  334. .It Ic RS
  335. Temporarily reset the default left margin.
  336. This has the following syntax:
  337. .Pp
  338. .D1 Pf . Ic RS Op Ar width
  339. .Pp
  340. The
  341. .Ar width
  342. argument is a
  343. .Xr roff 7
  344. scaling width.
  345. If not specified, the saved or default width is used.
  346. .Pp
  347. See also
  348. .Ic RE .
  349. .It Ic SB
  350. Text is rendered in small size (one point smaller than the default font)
  351. bold face.
  352. This macro is an extension that probably first appeared in SunOS 4.0
  353. and was later adopted by GNU and by
  354. .Bx 4.4 .
  355. .It Ic SH
  356. Begin a section.
  357. The scope of a section is only closed by another section or the end of
  358. file.
  359. The paragraph left-margin width is reset to the default.
  360. .It Ic SM
  361. Text is rendered in small size (one point smaller than the default
  362. font).
  363. .It Ic SS
  364. Begin a sub-section.
  365. The scope of a sub-section is closed by a subsequent sub-section,
  366. section, or end of file.
  367. The paragraph left-margin width is reset to the default.
  368. .It Ic SY
  369. Begin a synopsis block with the following syntax:
  370. .Bd -unfilled -offset indent
  371. .Pf . Ic SY Ar command
  372. .Ar arguments
  373. .Pf . Ic YS
  374. .Ed
  375. .Pp
  376. This is a non-standard GNU extension
  377. and very rarely used even in GNU manual pages.
  378. Formatting is similar to
  379. .Ic IP .
  380. .It Ic TH
  381. Set the name of the manual page for use in the page header
  382. and footer with the following syntax:
  383. .Pp
  384. .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
  385. .Pp
  386. Conventionally, the document
  387. .Ar name
  388. is given in all caps.
  389. The
  390. .Ar section
  391. is usually a single digit, in a few cases followed by a letter.
  392. The recommended
  393. .Ar date
  394. format is
  395. .Sy YYYY-MM-DD
  396. as specified in the ISO-8601 standard;
  397. if the argument does not conform, it is printed verbatim.
  398. If the
  399. .Ar date
  400. is empty or not specified, the current date is used.
  401. The optional
  402. .Ar source
  403. string specifies the organisation providing the utility.
  404. When unspecified,
  405. .Xr mandoc 1
  406. uses its
  407. .Fl Ios
  408. argument.
  409. The
  410. .Ar volume
  411. string replaces the default volume title of the
  412. .Ar section .
  413. .Pp
  414. Examples:
  415. .Pp
  416. .Dl \&.TH CVS 5 "1992-02-12" GNU
  417. .It Ic TP
  418. Begin a paragraph where the head, if exceeding the indentation width, is
  419. followed by a newline; if not, the body follows on the same line after
  420. advancing to the indentation width.
  421. Subsequent output lines are indented.
  422. The syntax is as follows:
  423. .Bd -unfilled -offset indent
  424. .Pf . Ic TP Op Ar width
  425. .Ar head No \e" one line
  426. .Ar body
  427. .Ed
  428. .Pp
  429. The
  430. .Ar width
  431. argument is a
  432. .Xr roff 7
  433. scaling width.
  434. If specified, it's saved for later paragraph left-margins; if
  435. unspecified, the saved or default width is used.
  436. .It Ic TQ
  437. Like
  438. .Ic TP ,
  439. except that no vertical spacing is inserted before the paragraph.
  440. This is a non-standard GNU extension
  441. and very rarely used even in GNU manual pages.
  442. .It Ic UC
  443. Sets the volume for the footer for compatibility with man pages from
  444. .Bx
  445. releases.
  446. The optional first argument specifies which release it is from.
  447. This macro is an extension that first appeared in
  448. .Bx 3 .
  449. .It Ic UE
  450. End a uniform resource identifier block started with
  451. .Ic UR .
  452. This is a non-standard GNU extension.
  453. .It Ic UR
  454. Begin a uniform resource identifier block.
  455. This is a non-standard GNU extension.
  456. It has the following syntax:
  457. .Bd -unfilled -offset indent
  458. .Pf . Ic UR Ar uri
  459. link description to be shown
  460. .Pf . Ic UE
  461. .Ed
  462. .It Ic YS
  463. End a synopsis block started with
  464. .Ic SY .
  465. This is a non-standard GNU extension.
  466. .It Ic in
  467. Indent relative to the current indentation:
  468. .Pp
  469. .D1 Pf . Ic in Op Ar width
  470. .Pp
  471. If
  472. .Ar width
  473. is signed, the new offset is relative.
  474. Otherwise, it is absolute.
  475. This value is reset upon the next paragraph, section, or sub-section.
  476. .El
  477. .Sh MACRO SYNTAX
  478. The
  479. .Nm
  480. macros are classified by scope: line scope or block scope.
  481. Line macros are only scoped to the current line (and, in some
  482. situations, the subsequent line).
  483. Block macros are scoped to the current line and subsequent lines until
  484. closed by another block macro.
  485. .Ss Line Macros
  486. Line macros are generally scoped to the current line, with the body
  487. consisting of zero or more arguments.
  488. If a macro is scoped to the next line and the line arguments are empty,
  489. the next line, which must be text, is used instead.
  490. Thus:
  491. .Bd -literal -offset indent
  492. \&.I
  493. foo
  494. .Ed
  495. .Pp
  496. is equivalent to
  497. .Sq .I foo .
  498. If next-line macros are invoked consecutively, only the last is used.
  499. If a next-line macro is followed by a non-next-line macro, an error is
  500. raised.
  501. .Pp
  502. The syntax is as follows:
  503. .Bd -literal -offset indent
  504. \&.YO \(lBbody...\(rB
  505. \(lBbody...\(rB
  506. .Ed
  507. .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
  508. .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
  509. .It Ic AT Ta <=1 Ta current Ta \&
  510. .It Ic B Ta n Ta next-line Ta \&
  511. .It Ic BI Ta n Ta current Ta \&
  512. .It Ic BR Ta n Ta current Ta \&
  513. .It Ic DT Ta 0 Ta current Ta \&
  514. .It Ic EE Ta 0 Ta current Ta Version 9 At
  515. .It Ic EX Ta 0 Ta current Ta Version 9 At
  516. .It Ic I Ta n Ta next-line Ta \&
  517. .It Ic IB Ta n Ta current Ta \&
  518. .It Ic IR Ta n Ta current Ta \&
  519. .It Ic OP Ta >=1 Ta current Ta DWB
  520. .It Ic PD Ta 1 Ta current Ta \&
  521. .It Ic RB Ta n Ta current Ta \&
  522. .It Ic RI Ta n Ta current Ta \&
  523. .It Ic SB Ta n Ta next-line Ta \&
  524. .It Ic SM Ta n Ta next-line Ta \&
  525. .It Ic TH Ta >1, <6 Ta current Ta \&
  526. .It Ic UC Ta <=1 Ta current Ta \&
  527. .It Ic in Ta 1 Ta current Ta Xr roff 7
  528. .El
  529. .Ss Block Macros
  530. Block macros comprise a head and body.
  531. As with in-line macros, the head is scoped to the current line and, in
  532. one circumstance, the next line (the next-line stipulations as in
  533. .Sx Line Macros
  534. apply here as well).
  535. .Pp
  536. The syntax is as follows:
  537. .Bd -literal -offset indent
  538. \&.YO \(lBhead...\(rB
  539. \(lBhead...\(rB
  540. \(lBbody...\(rB
  541. .Ed
  542. .Pp
  543. The closure of body scope may be to the section, where a macro is closed
  544. by
  545. .Ic SH ;
  546. sub-section, closed by a section or
  547. .Ic SS ;
  548. or paragraph, closed by a section, sub-section,
  549. .Ic HP ,
  550. .Ic IP ,
  551. .Ic LP ,
  552. .Ic P ,
  553. .Ic PP ,
  554. .Ic RE ,
  555. .Ic SY ,
  556. or
  557. .Ic TP .
  558. No closure refers to an explicit block closing macro.
  559. .Pp
  560. As a rule, block macros may not be nested; thus, calling a block macro
  561. while another block macro scope is open, and the open scope is not
  562. implicitly closed, is syntactically incorrect.
  563. .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
  564. .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
  565. .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
  566. .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
  567. .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
  568. .It Ic ME Ta 0 Ta none Ta none Ta GNU
  569. .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
  570. .It Ic P Ta 0 Ta current Ta paragraph Ta \&
  571. .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
  572. .It Ic RE Ta <=1 Ta current Ta none Ta \&
  573. .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
  574. .It Ic SH Ta >0 Ta next-line Ta section Ta \&
  575. .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
  576. .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
  577. .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
  578. .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
  579. .It Ic UE Ta 0 Ta current Ta none Ta GNU
  580. .It Ic UR Ta 1 Ta current Ta part Ta GNU
  581. .It Ic YS Ta 0 Ta none Ta none Ta GNU
  582. .El
  583. .Pp
  584. If a block macro is next-line scoped, it may only be followed by in-line
  585. macros for decorating text.
  586. .Ss Font handling
  587. In
  588. .Nm
  589. documents, both
  590. .Sx Physical markup
  591. macros and
  592. .Xr roff 7
  593. .Ql \ef
  594. font escape sequences can be used to choose fonts.
  595. In text lines, the effect of manual font selection by escape sequences
  596. only lasts until the next macro invocation; in macro lines, it only lasts
  597. until the end of the macro scope.
  598. Note that macros like
  599. .Ic BR
  600. open and close a font scope for each argument.
  601. .Sh SEE ALSO
  602. .Xr man 1 ,
  603. .Xr mandoc 1 ,
  604. .Xr eqn 7 ,
  605. .Xr mandoc_char 7 ,
  606. .Xr mdoc 7 ,
  607. .Xr roff 7 ,
  608. .Xr tbl 7
  609. .Sh HISTORY
  610. The
  611. .Nm
  612. language first appeared as a macro package for the roff typesetting
  613. system in
  614. .At v7 .
  615. .Pp
  616. The stand-alone implementation that is part of the
  617. .Xr mandoc 1
  618. utility first appeared in
  619. .Ox 4.6 .
  620. .Sh AUTHORS
  621. .An -nosplit
  622. .An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu
  623. designed and implemented the original version of these macros,
  624. wrote the original version of this manual page,
  625. and was the first to use them when he edited volume 1 of the
  626. .At v7
  627. manual pages.
  628. .Pp
  629. .An James Clark
  630. later rewrote the macros for groff.
  631. .An Eric S. Raymond Aq Mt esr@thyrsus.com
  632. and
  633. .An Werner Lemberg Aq Mt wl@gnu.org
  634. added the extended
  635. .Nm
  636. macros to groff in 2007.
  637. .Pp
  638. The
  639. .Xr mandoc 1
  640. program and this
  641. .Nm
  642. reference were written by
  643. .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .