/contrib/groff/tmac/groff_ms.man

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 1556 lines · 1552 code · 4 blank · 0 comment · 0 complexity · 50a86178f34770c3e4e8c7e6d93c3bef MD5 · raw file

  1. '\" t
  2. .ig
  3. Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005
  4. Free Software Foundation, Inc.
  5. Permission is granted to make and distribute verbatim copies of
  6. this manual provided the copyright notice and this permission notice
  7. are preserved on all copies.
  8. Permission is granted to copy and distribute modified versions of this
  9. manual under the conditions for verbatim copying, provided that the
  10. entire resulting derived work is distributed under the terms of a
  11. permission notice identical to this one.
  12. Permission is granted to copy and distribute translations of this
  13. manual into another language, under the above conditions for modified
  14. versions, except that this permission notice may be included in
  15. translations approved by the Free Software Foundation instead of in
  16. the original English.
  17. ..
  18. .
  19. .do nr groff_ms_C \n[.C]
  20. .cp 0
  21. .
  22. .TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  23. .
  24. .
  25. .
  26. .SH NAME
  27. .
  28. groff_ms \- groff ms macros
  29. .
  30. .
  31. .
  32. .SH SYNOPSIS
  33. .
  34. .B groff
  35. .B \-ms
  36. [
  37. .IR options .\|.\|.\&
  38. ]
  39. [
  40. .IR files .\|.\|.\&
  41. ]
  42. .br
  43. .B groff
  44. .B \-m\ ms
  45. [
  46. .IR options .\|.\|.\&
  47. ]
  48. [
  49. .IR files .\|.\|.\&
  50. ]
  51. .
  52. .
  53. .
  54. .SH DESCRIPTION
  55. .
  56. This manual page describes the GNU version of the
  57. .I ms
  58. macros,
  59. part of the
  60. .I groff
  61. typesetting system.
  62. The
  63. .I ms
  64. macros are mostly compatible with the
  65. documented behavior of the 4.3
  66. .SM BSD
  67. Unix
  68. .I ms
  69. macros (see
  70. .I Differences from troff ms
  71. below for details).
  72. The
  73. .I ms
  74. macros are suitable for reports, letters, books, and
  75. technical documentation.
  76. .
  77. .
  78. .
  79. .SH USAGE
  80. .
  81. The
  82. .I ms
  83. macro package expects files to have
  84. a certain amount of structure.
  85. The simplest documents can begin with a paragraph macro
  86. and consist of text separated by paragraph macros
  87. or even blank lines.
  88. Longer documents have a structure as follows:
  89. .
  90. .TP
  91. .B "Document type"
  92. If you use the
  93. .B RP
  94. (report) macro at the beginning of the document,
  95. .I groff
  96. prints the cover page information on its own page;
  97. otherwise it prints the information on the
  98. first page with your document text immediately following.
  99. Other document formats found in AT&T
  100. .I troff
  101. are specific to AT&T
  102. or Berkeley, and are not supported in
  103. .IR "groff ms" .
  104. .
  105. .TP
  106. .B "Format and layout"
  107. By setting number registers,
  108. you can change your document's type (font and size),
  109. margins, spacing, headers and footers, and footnotes.
  110. See
  111. .I "Document control registers"
  112. below for more details.
  113. .
  114. .TP
  115. .B "Cover page"
  116. A cover page consists of a title,
  117. and optionally the author's name and institution,
  118. an abstract, and the date.
  119. See
  120. .I "Cover page macros"
  121. below for more details.
  122. .
  123. .TP
  124. .B "Body"
  125. Following the cover page is your document.
  126. It consists of paragraphs, headings, and lists.
  127. .
  128. .TP
  129. .B "Table of contents"
  130. Longer documents usually include a table of contents,
  131. which you can add by placing the
  132. .B TC
  133. macro at the end of your document.
  134. .
  135. .
  136. .SS "Document control registers"
  137. .
  138. The following table lists the document control
  139. number registers.
  140. For the sake of consistency,
  141. set registers related to margins at the beginning of your document,
  142. or just after the
  143. .B RP
  144. macro.
  145. .
  146. .LP
  147. .ne 12
  148. .B Margin settings
  149. .RS
  150. .na
  151. .TS
  152. cb s cb s s cb s cb s
  153. afCW s l s s l s l s.
  154. Reg. Definition Effective Default
  155. _
  156. PO T{
  157. Page offset (left margin)
  158. T} T{
  159. next page
  160. T} 1i
  161. LL T{
  162. Line length
  163. T} next para. 6i
  164. LT T{
  165. Header/footer length
  166. T} next para. 6i
  167. HM T{
  168. Top (header) margin
  169. T} next page 1i
  170. FM T{
  171. Bottom (footer) margin
  172. T} next page 1i
  173. _
  174. .TE
  175. .RE
  176. .
  177. .LP
  178. .ne 12
  179. .B Text settings
  180. .RS
  181. .TS
  182. cb s cb s s cb s cb s
  183. afCW s l s s l s l s.
  184. Reg. Definition Effective Default
  185. _
  186. PS T{
  187. Point size
  188. T} next para. 10p
  189. VS T{
  190. Line spacing (leading)
  191. T} next para. 12p
  192. PSINCR T{
  193. Point size increment
  194. for section headings of
  195. increasing importance
  196. T} next heading 1p
  197. GROWPS T{
  198. Heading level
  199. beyond which PSINCR
  200. is ignored
  201. T} next heading 0
  202. _
  203. .TE
  204. .RE
  205. .
  206. .LP
  207. .ne 11
  208. .B Paragraph settings
  209. .RS
  210. .TS
  211. cb cb s cb cb
  212. afCW l s l l .
  213. Reg. Definition Effective Default
  214. _
  215. PI T{
  216. Initial indent
  217. T} next para. 5n
  218. PD T{
  219. Space between paragraphs
  220. T} next para. 0.3v
  221. QI T{
  222. Quoted paragraph indent
  223. T} next para. 5n
  224. PORPHANS T{
  225. Number of initial lines
  226. to be kept together
  227. T} next para. 1
  228. HORPHANS T{
  229. Number of initial lines
  230. to be kept with heading
  231. T} next heading 1
  232. _
  233. .TE
  234. .RE
  235. .
  236. .LP
  237. .ne 7
  238. .B Footnote settings
  239. .RS
  240. .TS
  241. cb cb cb cb
  242. afCW l l l .
  243. Reg. Definition Effective Default
  244. _
  245. FL Footnote length next footnote \[rs]n[LL]*5/6
  246. FI Footnote indent next footnote 2n
  247. FF Footnote format next footnote 0
  248. FPS Point size next footnote \[rs]n[PS]-2
  249. FVS Vert. spacing next footnote \[rs]n[FPS]+2
  250. FPD Para. spacing next footnote \[rs]n[PD]/2
  251. _
  252. .TE
  253. .RE
  254. .
  255. .LP
  256. .ne 6
  257. .B Other settings
  258. .RS
  259. .TS
  260. cb s cb s s cb s cb s
  261. afCW s l s s l s l s.
  262. Reg. Definition Effective Default
  263. _
  264. MINGW T{
  265. Minimum width between columns
  266. T} next page 2n
  267. _
  268. .TE
  269. .ad
  270. .RE
  271. .
  272. .
  273. .SS "Cover page macros"
  274. .
  275. Use the following macros to create a cover page for your document
  276. in the order shown.
  277. .
  278. .TP
  279. .B .RP [no]
  280. Specifies the report format for your document.
  281. The report format creates a separate cover page.
  282. With no
  283. .B RP
  284. macro,
  285. .I groff
  286. prints a subset of the
  287. cover page on page\~1 of your document.
  288. .
  289. .IP
  290. If you use the optional
  291. .B no
  292. argument,
  293. .I groff
  294. prints a title page but
  295. does not repeat any of the title page information
  296. (title, author, abstract, etc.\&)
  297. on page\~1 of the document.
  298. .
  299. .TP
  300. .B .P1
  301. (P-one) Prints the header on page\~1.
  302. The default is to suppress the header.
  303. .
  304. .TP
  305. .BI ".DA [" xxx ]
  306. (optional) Print the current date,
  307. or the arguments to the macro if any,
  308. on the title page (if specified)
  309. and in the footers.
  310. This is the default for
  311. .IR nroff .
  312. .
  313. .TP
  314. .BI ".ND [" xxx ]
  315. (optional) Print the current date,
  316. or the arguments to the macro if any,
  317. on the title page (if specified)
  318. but not in the footers.
  319. This is the default for
  320. .IR troff .
  321. .
  322. .TP
  323. .B .TL
  324. Specifies the document title.
  325. .I Groff
  326. collects text following the
  327. .B TL
  328. macro into the title, until reaching the author name or abstract.
  329. .
  330. .TP
  331. .B .AU
  332. Specifies the author's name.
  333. You can specify multiple authors by using an
  334. .B AU
  335. macro for each author.
  336. .
  337. .TP
  338. .B .AI
  339. Specifies the author's institution.
  340. You can specify multiple institutions.
  341. .
  342. .TP
  343. .B .AB [no]
  344. Begins the abstract.
  345. The default is to print the word
  346. .BR ABSTRACT ,
  347. centered and in italics, above the text of the abstract.
  348. The option
  349. .B no
  350. suppresses this heading.
  351. .
  352. .TP
  353. .B .AE
  354. End the abstract.
  355. .
  356. .
  357. .SS Paragraphs
  358. .
  359. Use the
  360. .B PP
  361. macro to create indented paragraphs,
  362. and the
  363. .B LP
  364. macro to create paragraphs with no initial indent.
  365. .
  366. .PP
  367. The
  368. .B QP
  369. macro indents all text at both left and right margins.
  370. The effect is identical to the HTML
  371. .B <BLOCKQUOTE>
  372. element.
  373. The next paragraph or heading
  374. returns margins to normal.
  375. .
  376. .PP
  377. The
  378. .B XP
  379. macro produces an exdented paragraph.
  380. The first line of the paragraph begins at
  381. the left margin,
  382. and subsequent lines are indented
  383. (the opposite of
  384. .BR PP ).
  385. .
  386. .PP
  387. For each of the above paragraph types,
  388. and also for any list entry introduced by the
  389. .B IP
  390. macro
  391. (described later),
  392. the document control register
  393. .BR PORPHANS ,
  394. sets the
  395. .I minimum
  396. number of lines which must be printed,
  397. after the start of the paragraph,
  398. and before any page break occurs.
  399. If there is insufficient space remaining on the current page
  400. to accommodate this number of lines,
  401. then a page break is forced
  402. .I before
  403. the first line of the paragraph is printed.
  404. .
  405. .PP
  406. Similarly,
  407. when a section heading
  408. (see subsection
  409. .I Headings
  410. below)
  411. preceeds any of these paragraph types,
  412. the
  413. .B HORPHANS
  414. document control register specifies the
  415. .I minimum
  416. number of lines of the paragraph
  417. which must be kept on the same page as the heading.
  418. If insufficient space remains on the current page
  419. to accommodate the heading and this number of lines of paragraph text,
  420. then a page break is forced
  421. .I before
  422. the heading is printed.
  423. .
  424. .
  425. .SS Headings
  426. .
  427. Use headings to create a hierarchical structure
  428. for your document.
  429. By default,
  430. the
  431. .I ms
  432. macros print headings in
  433. .B bold
  434. using the same font family and point size as the body text.
  435. For output devices which support scalable fonts,
  436. this behaviour may be modified,
  437. by defining the document control registers,
  438. .B GROWPS
  439. and
  440. .BR PSINCR .
  441. .
  442. .PP
  443. The following heading macros are available:
  444. .
  445. .TP
  446. .BI .NH\ xx
  447. Numbered heading.
  448. The argument
  449. .I xx
  450. is either a numeric argument to indicate the
  451. level of the heading, or
  452. .I S\ xx\ xx\ \c
  453. ".\|.\|."
  454. to set the section number explicitly.
  455. If you specify heading levels out of sequence,
  456. such as invoking
  457. .B ".NH\ 3"
  458. after
  459. .BR ".NH\ 1" ,
  460. .I groff
  461. prints a warning on standard error.
  462. .
  463. .IP
  464. If the
  465. .B GROWPS
  466. register is set to a value
  467. greater than the level of the heading,
  468. then the point size of the heading will be increased by
  469. .B PSINCR
  470. units over the text size specified by the
  471. .B PS
  472. register,
  473. for each level by which the heading level is less than
  474. the value of
  475. .BR GROWPS .
  476. For example,
  477. the sequence:
  478. .
  479. .RS
  480. .ne 12
  481. .nf
  482. .IP
  483. \&.nr PS 10
  484. \&.nr GROWPS 3
  485. \&.nr PSINCR 1.5p
  486. \&.
  487. \&.NH 1
  488. Top Level Heading
  489. \&.
  490. \&.NH 2
  491. Second Level Heading
  492. \&.
  493. \&.NH 3
  494. Third Level Heading
  495. .fi
  496. .RE
  497. .
  498. .IP
  499. will cause
  500. .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
  501. to be printed in 13pt
  502. .B bold
  503. text, followed by
  504. .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
  505. in 11.5pt
  506. .B bold
  507. text, while
  508. .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
  509. and all more deeply nested heading levels,
  510. will remain in the 10pt
  511. .B bold
  512. text which is specified by the
  513. .B PS
  514. register.
  515. .
  516. .IP
  517. Note that the value stored in
  518. .B PSINCR
  519. is interpreted in
  520. .I groff
  521. basic units;
  522. the
  523. .I p
  524. scaling factor should be employed,
  525. when assigning a value specified in points.
  526. .
  527. .IP
  528. After invoking
  529. .BR .NH ,
  530. the assigned heading number is available in the strings
  531. .B SN-DOT
  532. (exactly as it appears in the formatted heading),
  533. and
  534. .B SN-NO-DOT
  535. (with its final period omitted).
  536. The string
  537. .B SN
  538. is also defined,
  539. as an alias for
  540. .BR SN-DOT ;
  541. if preferred,
  542. the user may redefine it as an alias for
  543. .BR SN-NO-DOT ,
  544. 'ne 10
  545. by including the initialisation:
  546. .
  547. .RS
  548. .nf
  549. .IP
  550. \&.ds SN-NO-DOT
  551. \&.als SN SN-NO-DOT
  552. .fi
  553. .RE
  554. .
  555. .IP
  556. .I before
  557. the first use of
  558. .BR .NH ,
  559. or simply:
  560. .
  561. .RS
  562. .nf
  563. .IP
  564. \&.als SN SN-NO-DOT
  565. .fi
  566. .RE
  567. .
  568. .IP
  569. .I after
  570. the first use of
  571. .BR .NH .
  572. .
  573. .TP
  574. .BI .SH\ [ xx ]
  575. Unnumbered subheading.
  576. The use of the optional
  577. .I xx
  578. argument is a GNU extension,
  579. which adjusts the point size of the unnumbered subheading
  580. to match that of a numbered heading,
  581. introduced using
  582. .BI .NH\ xx
  583. with the same value of
  584. .IR xx .
  585. For example,
  586. given the same settings for
  587. .BR PS ,
  588. .B GROWPS
  589. and
  590. .BR PSINCR ,
  591. as used in the preceeding
  592. .B .NH
  593. example,
  594. the sequence:
  595. .
  596. .RS
  597. .ne
  598. .nf
  599. .IP
  600. \&.SH 2
  601. An Unnumbered Subheading
  602. .fi
  603. .RE
  604. .
  605. .IP
  606. will print
  607. .RI \*(lq "An Unnumbered Subheading" \*(rq
  608. in 11.5pt
  609. .B bold
  610. text.
  611. .
  612. .
  613. .SS Highlighting
  614. .
  615. The
  616. .I ms
  617. macros provide a variety of methods to highlight
  618. or emphasize text:
  619. .
  620. .TP
  621. .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
  622. Sets its first argument in
  623. .BR "bold type" .
  624. If you specify a second argument,
  625. .I groff
  626. prints it in the previous font after
  627. the bold text, with no intervening space
  628. (this allows you to set punctuation after
  629. the highlighted text without highlighting
  630. the punctuation).
  631. Similarly, it prints the third argument (if any)
  632. in the previous font
  633. .B before
  634. the first argument.
  635. For example,
  636. .RS
  637. .
  638. .IP
  639. \&.B foo ) (
  640. .RE
  641. .
  642. .IP
  643. prints
  644. .RB ( foo ).
  645. .
  646. .IP
  647. If you give this macro no arguments,
  648. .I groff
  649. prints all text following in bold until
  650. the next highlighting, paragraph, or heading macro.
  651. .
  652. .TP
  653. .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
  654. Sets its first argument in
  655. roman (or regular) type.
  656. It operates similarly to the
  657. .B B
  658. macro otherwise.
  659. .
  660. .TP
  661. .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
  662. Sets its first argument in
  663. .IR "italic type" .
  664. It operates similarly to the
  665. .B B
  666. macro otherwise.
  667. .
  668. .TP
  669. .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
  670. Sets its first argument in a constant width face.
  671. It operates similarly to the
  672. .B B
  673. macro otherwise.
  674. .
  675. .TP
  676. .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
  677. Sets its first argument in bold italic type.
  678. It operates similarly to the
  679. .B B
  680. macro otherwise.
  681. .
  682. .TP
  683. .BI ".BX [" txt ]
  684. Prints its argument and draws a box around it.
  685. If you want to box a string that contains spaces,
  686. use a digit-width space (\[rs]0).
  687. .
  688. .TP
  689. .BI ".UL [" txt " [" post ]]
  690. Prints its first argument with an underline.
  691. If you specify a second argument,
  692. .I groff
  693. prints it in the previous font after
  694. the underlined text, with no intervening space.
  695. .
  696. .TP
  697. .B .LG
  698. Prints all text following in larger type
  699. (2\~points larger than the current point size) until
  700. the next font size, highlighting, paragraph, or heading macro.
  701. You can specify this macro multiple times
  702. to enlarge the point size as needed.
  703. .
  704. .TP
  705. .B .SM
  706. Prints all text following in
  707. smaller type
  708. (2\~points smaller than the current point size) until
  709. the next type size, highlighting, paragraph, or heading macro.
  710. You can specify this macro multiple times
  711. to reduce the point size as needed.
  712. .
  713. .TP
  714. .B .NL
  715. Prints all text following in
  716. the normal point size
  717. (that is, the value of the
  718. .B PS
  719. register).
  720. .
  721. .TP
  722. .BI \[rs]*{ text \[rs]*}
  723. Print the enclosed
  724. .I text
  725. as a superscript.
  726. .
  727. .
  728. .SS Indents
  729. .
  730. You may need to indent sections of text.
  731. A typical use for indents is to create nested lists and sublists.
  732. .
  733. .PP
  734. Use the
  735. .B RS
  736. and
  737. .B RE
  738. macros to start and end a section of indented text, respectively.
  739. The
  740. .B PI
  741. register controls the amount of indent.
  742. .
  743. .PP
  744. You can nest indented sections as deeply as needed by
  745. using multiple, nested pairs of
  746. .B RS
  747. and
  748. .BR RE .
  749. .
  750. .
  751. .SS Lists
  752. .
  753. The
  754. .B IP
  755. macro handles duties for all lists.
  756. Its syntax is as follows:
  757. .
  758. .TP
  759. .BI ".IP [" marker " [" width ]]
  760. .
  761. .IP
  762. The
  763. .I marker
  764. is usually a bullet character
  765. .B \[rs](bu
  766. for unordered lists,
  767. a number (or auto-incrementing number register) for numbered lists,
  768. or a word or phrase for indented (glossary-style) lists.
  769. .
  770. .IP
  771. The
  772. .I width
  773. specifies the indent for the body of each list item.
  774. Once specified, the indent remains the same for all
  775. list items in the document until specified again.
  776. .\" -----
  777. .br
  778. .ne 15
  779. .
  780. .
  781. .SS "Tab stops"
  782. .
  783. Use the
  784. .B ta
  785. request to set tab stops as needed.
  786. Use the
  787. .B TA
  788. macro to reset tabs to the default (every 5n).
  789. You can redefine the
  790. .B TA
  791. macro to create a different set of default tab stops.
  792. .
  793. .
  794. .SS "Displays and keeps"
  795. .
  796. Use displays to show text-based examples or figures
  797. (such as code listings).
  798. Displays turn off filling, so lines of code can be
  799. displayed as-is without inserting
  800. .B br
  801. requests in between each line.
  802. Displays can be
  803. .I kept
  804. on a single page, or allowed to break across pages.
  805. The following table shows the display types available.
  806. .RS
  807. .ne 11
  808. .na
  809. .TS
  810. cb s s s cbt s s
  811. cb s cb s ^ s s
  812. lfCW s lfCW s l s s.
  813. Display macro Type of display
  814. With keep No keep
  815. _
  816. \&.DS L \&.LD Left-justified.
  817. \&.DS I [\fIindent\fP] \&.ID T{
  818. Indented (default indent in the \fBDI\fP register).
  819. T}
  820. \&.DS B \&.BD T{
  821. Block-centered (left-justified, longest line centered).
  822. T}
  823. \&.DS C \&.CD Centered.
  824. \&.DS R \&.RD Right-justified.
  825. _
  826. .TE
  827. .RE
  828. .ad
  829. .
  830. .LP
  831. Use the
  832. .B DE
  833. macro to end any display type.
  834. The macros
  835. .B Ds
  836. and
  837. .B De
  838. were formerly provided as aliases for
  839. .B DS
  840. and
  841. .BR DE ,
  842. respectively, but they have been removed, and should no longer be used.
  843. X11 documents which actually use
  844. .B Ds
  845. and
  846. .B De
  847. always load a specific macro file from the X11 distribution (macros.t)
  848. which provides proper definitions for the two macros.
  849. .PP
  850. To
  851. .I keep
  852. text together on a page,
  853. such as
  854. a paragraph that refers to a table (or list, or other item)
  855. immediately following, use the
  856. .B KS
  857. and
  858. .B KE
  859. macros.
  860. The
  861. .B KS
  862. macro begins a block of text to be kept on a single page,
  863. and the
  864. .B KE
  865. macro ends the block.
  866. .
  867. .PP
  868. You can specify a
  869. .I "floating keep"
  870. using the
  871. .B KF
  872. and
  873. .B KE
  874. macros.
  875. If the keep cannot fit on the current page,
  876. .I groff
  877. holds the contents of the keep and allows text following
  878. the keep (in the source file) to fill in the remainder of
  879. the current page.
  880. When the page breaks,
  881. whether by an explicit
  882. .B bp
  883. request or by reaching the end of the page,
  884. .I groff
  885. prints the floating keep at the top of the new page.
  886. This is useful for printing large graphics or tables
  887. that do not need to appear exactly where specified.
  888. .
  889. .PP
  890. The macros
  891. .B B1
  892. and
  893. .B B2
  894. can be used to enclose a text within a box;
  895. .B .B1
  896. begins the box, and
  897. .B .B2
  898. ends it.
  899. Text in the box is automatically placed in a diversion
  900. (keep).
  901. .
  902. .
  903. .SS "Tables, figures, equations, and references"
  904. .
  905. The
  906. .I -ms
  907. macros support the standard
  908. .I groff
  909. preprocessors:
  910. .IR tbl ,
  911. .IR pic ,
  912. .IR eqn ,
  913. and
  914. .IR refer .
  915. Mark text meant for preprocessors by enclosing it
  916. in pairs of tags as follows:
  917. .
  918. .TP
  919. .BR ".TS [H]" " and " .TE
  920. Denotes a table, to be processed by the
  921. .I tbl
  922. preprocessor.
  923. The optional
  924. .BR H "\~argument"
  925. instructs
  926. .I groff
  927. to create a running header with the information
  928. up to the
  929. .B TH
  930. macro.
  931. .I Groff
  932. prints the header at the beginning of the table;
  933. if the table runs onto another page,
  934. .I groff
  935. prints the header on the next page as well.
  936. .
  937. .TP
  938. .BR .PS " and " .PE
  939. Denotes a graphic, to be processed by the
  940. .I pic
  941. preprocessor.
  942. You can create a
  943. .I pic
  944. file by hand, using the
  945. AT&T
  946. .I pic
  947. manual available on the Web as a reference,
  948. or by using a graphics program such as
  949. .IR xfig .
  950. .
  951. .TP
  952. .BR ".EQ [\fI\,align\/\fP]" " and " .EN
  953. Denotes an equation, to be processed by the
  954. .I eqn
  955. preprocessor.
  956. The optional
  957. .I align
  958. argument can be
  959. .BR C ,
  960. .BR L ,
  961. or\~\c
  962. .B I
  963. to center (the default), left-justify, or indent
  964. the equation.
  965. .
  966. .TP
  967. .BR .[ " and " .]
  968. Denotes a reference, to be processed by the
  969. .I refer
  970. preprocessor.
  971. The GNU
  972. .IR @g@refer (@MAN1EXT@)
  973. manual page provides a comprehensive reference
  974. to the preprocessor and the format of the
  975. bibliographic database.
  976. .
  977. .
  978. .SS Footnotes
  979. .
  980. The
  981. .I ms
  982. macros provide a flexible footnote system.
  983. You can specify a numbered footnote by using the
  984. .B \[rs]**
  985. escape, followed by the text of the footnote
  986. enclosed by
  987. .B FS
  988. and
  989. .B FE
  990. macros.
  991. .
  992. .PP
  993. You can specify symbolic footnotes
  994. by placing the mark character (such as
  995. .B \[rs](dg
  996. for the dagger character) in the body text,
  997. followed by the text of the footnote
  998. enclosed by
  999. .B FS\ \[rs](dg
  1000. and
  1001. .B FE
  1002. macros.
  1003. .
  1004. .PP
  1005. You can control how
  1006. .I groff
  1007. prints footnote numbers by changing the value of the
  1008. .B FF
  1009. register as follows:
  1010. .RS
  1011. .ne 7
  1012. .
  1013. .TP
  1014. 0
  1015. Prints the footnote number as a superscript; indents the footnote (default).
  1016. .
  1017. .TP
  1018. 1
  1019. Prints the number followed by a period (like\~1.\&)
  1020. and indents the footnote.
  1021. .
  1022. .TP
  1023. 2
  1024. Like\~1, without an indent.
  1025. .
  1026. .TP
  1027. 3
  1028. Like\~1, but prints the footnote number as a hanging paragraph.
  1029. .
  1030. .LP
  1031. .RE
  1032. You can use footnotes safely within keeps and displays,
  1033. but avoid using numbered footnotes within floating keeps.
  1034. You can set a second
  1035. .B \[rs]**
  1036. between a
  1037. .B \[rs]**
  1038. and its corresponding
  1039. .BR .FS ;
  1040. as long as each
  1041. .B .FS
  1042. occurs
  1043. .I after
  1044. the corresponding
  1045. .B \[rs]**
  1046. and the occurrences of
  1047. .B .FS
  1048. are in the same order as the corresponding occurrences of
  1049. .BR \[rs]** .
  1050. .
  1051. .
  1052. .SS "Headers and footers"
  1053. .
  1054. There are two ways to define headers and footers:
  1055. .
  1056. .IP \(bu 3n
  1057. Use the strings
  1058. .BR LH ,
  1059. .BR CH ,
  1060. and
  1061. .B RH
  1062. to set the left, center, and right headers; use
  1063. .BR LF ,
  1064. .BR CF ,
  1065. and
  1066. .B RF
  1067. to set the left, center, and right footers.
  1068. This works best for documents that do not distinguish
  1069. between odd and even pages.
  1070. .
  1071. .IP \(bu
  1072. Use the
  1073. .B OH
  1074. and
  1075. .B EH
  1076. macros to define headers for the odd and even pages; and
  1077. .B OF
  1078. and
  1079. .B EF
  1080. macros to define footers for the odd and even pages.
  1081. This is more flexible than defining the individual strings.
  1082. The syntax for these macros is as follows:
  1083. .RS
  1084. .
  1085. .IP
  1086. .B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
  1087. .RE
  1088. .
  1089. .IP
  1090. You can replace the quote (') marks with any character not
  1091. appearing in the header or footer text.
  1092. .
  1093. .
  1094. .SS Margins
  1095. .
  1096. You control margins using a set of number registers.
  1097. The following table lists the register names and defaults:
  1098. .RS
  1099. .ne 8
  1100. .na
  1101. .TS
  1102. cb s cb s s cb s cb s
  1103. afCW s l s s l s l s.
  1104. Reg. Definition Effective Default
  1105. _
  1106. PO T{
  1107. Page offset (left margin)
  1108. T} next page 1i
  1109. LL T{
  1110. Line length
  1111. T} next para. 6i
  1112. LT T{
  1113. Header/footer length
  1114. T} next para. 6i
  1115. HM T{
  1116. Top (header) margin
  1117. T} next page 1i
  1118. FM T{
  1119. Bottom (footer) margin
  1120. T} next page 1i
  1121. _
  1122. .TE
  1123. .RE
  1124. .ad
  1125. .
  1126. .PP
  1127. Note that there is no right margin setting.
  1128. The combination of page offset and line length
  1129. provide the information necessary to
  1130. derive the right margin.
  1131. .
  1132. .
  1133. .SS "Multiple columns"
  1134. .
  1135. The
  1136. .I ms
  1137. macros can set text in as many columns as will reasonably
  1138. fit on the page.
  1139. The following macros are available.
  1140. All of them force a page break if a multi-column mode is already set.
  1141. However, if the current mode is single-column, starting a multi-column
  1142. mode does
  1143. .I not
  1144. force a page break.
  1145. .
  1146. .TP
  1147. .B .1C
  1148. Single-column mode.
  1149. .
  1150. .TP
  1151. .B .2C
  1152. Two-column mode.
  1153. .
  1154. .TP
  1155. .BI ".MC [" width " [" gutter ]]
  1156. Multi-column mode.
  1157. If you specify no arguments, it is equivalent to the
  1158. .B 2C
  1159. macro.
  1160. Otherwise,
  1161. .I width
  1162. is the width of each column and
  1163. .I gutter
  1164. is the space between columns.
  1165. The
  1166. .B MINGW
  1167. number register is the default gutter width.
  1168. .
  1169. .
  1170. .SS "Creating a table of contents"
  1171. .
  1172. Wrap text that you want to appear in the
  1173. table of contents in
  1174. .B XS
  1175. and
  1176. .B XE
  1177. macros.
  1178. Use the
  1179. .B TC
  1180. macro to print the table of contents at the end of the document,
  1181. resetting the page number to\~\c
  1182. .B i
  1183. (Roman numeral\~1).
  1184. .
  1185. .PP
  1186. You can manually create a table of contents
  1187. by specifying a page number as the first argument to
  1188. .BR XS .
  1189. Add subsequent entries using the
  1190. .B XA
  1191. macro.
  1192. For example:
  1193. .RS
  1194. .
  1195. .PP
  1196. .ne 8
  1197. .nf
  1198. \&.XS 1
  1199. Introduction
  1200. \&.XA 2
  1201. A Brief History of the Universe
  1202. \&.XA 729
  1203. Details of Galactic Formation
  1204. \&.\|.\|.
  1205. \&.XE
  1206. .fi
  1207. .RE
  1208. .
  1209. .LP
  1210. Use the
  1211. .B PX
  1212. macro to print a manually-generated table of contents
  1213. without resetting the page number.
  1214. .
  1215. .PP
  1216. If you give the argument
  1217. .B no
  1218. to either
  1219. .B PX
  1220. or
  1221. .BR TC ,
  1222. .I groff
  1223. suppresses printing the title
  1224. specified by the
  1225. .B \[rs]*[TOC]
  1226. string.
  1227. .
  1228. .
  1229. .SS "Fractional point sizes"
  1230. .
  1231. Traditionally, the
  1232. .I ms
  1233. macros only support integer values for the document's font size and
  1234. vertical spacing.
  1235. To overcome this restriction, values larger than or equal to 1000 are taken
  1236. as fractional values, multiplied by 1000.
  1237. For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
  1238. .
  1239. .LP
  1240. The following four registers accept fractional point sizes:
  1241. .BR PS ,
  1242. .BR VS ,
  1243. .BR FPS ,
  1244. and
  1245. .BR FVS .
  1246. .
  1247. .LP
  1248. Due to backwards compatibility, the value of
  1249. .B VS
  1250. must be smaller than 40000 (this is 40.0 points).
  1251. .
  1252. .
  1253. .
  1254. .SH "DIFFERENCES FROM troff ms"
  1255. .
  1256. The
  1257. .I "groff ms"
  1258. macros are a complete re-implementation,
  1259. using no original AT&T code.
  1260. Since they take advantage of the extended features in
  1261. .IR groff ,
  1262. they cannot be used with AT&T
  1263. .IR troff .
  1264. Other differences include:
  1265. .
  1266. .IP \(bu 3n
  1267. The internals of
  1268. .I "groff ms"
  1269. differ from the internals of Unix
  1270. .IR ms .
  1271. Documents that depend upon implementation details of Unix
  1272. .I ms
  1273. may not format properly with
  1274. .IR "groff ms" .
  1275. .
  1276. .IP \(bu
  1277. The error-handling policy of
  1278. .I "groff ms"
  1279. is to detect and report errors,
  1280. rather than silently to ignore them.
  1281. .
  1282. .IP \(bu
  1283. Bell Labs localisms are not implemented.
  1284. .
  1285. .IP \(bu
  1286. Berkeley localisms, in particular the
  1287. .B TM
  1288. and
  1289. .B CT
  1290. macros,
  1291. are not implemented.
  1292. .
  1293. .IP \(bu
  1294. .I "Groff ms"
  1295. does not work in compatibility mode (e.g., with the
  1296. .B \-C
  1297. option).
  1298. .
  1299. .IP \(bu
  1300. There is no support for typewriter-like devices.
  1301. .
  1302. .IP \(bu
  1303. .I "Groff ms"
  1304. does not provide cut marks.
  1305. .
  1306. .IP \(bu
  1307. Multiple line spacing is not supported
  1308. (use a larger vertical spacing instead).
  1309. .
  1310. .IP \(bu
  1311. Some Unix
  1312. .I ms
  1313. documentation says that the
  1314. .B CW
  1315. and
  1316. .B GW
  1317. number registers can be used to control the column width and
  1318. gutter width, respectively.
  1319. These number registers are not used in
  1320. .IR "groff ms" .
  1321. .
  1322. .IP \(bu
  1323. Macros that cause a reset
  1324. (paragraphs, headings, etc.\&)
  1325. may change the indent.
  1326. Macros that change the indent do not increment or decrement
  1327. the indent, but rather set it absolutely.
  1328. This can cause problems for documents that define
  1329. additional macros of their own.
  1330. The solution is to use not the
  1331. .B in
  1332. request but instead the
  1333. .B RS
  1334. and
  1335. .B RE
  1336. macros.
  1337. .
  1338. .IP \(bu
  1339. The number register
  1340. .B GS
  1341. is set to\~1 by the
  1342. .I "groff ms"
  1343. macros,
  1344. but is not used by the Unix
  1345. .I ms
  1346. macros.
  1347. Documents that need to determine whether
  1348. they are being formatted with Unix
  1349. .I ms
  1350. or
  1351. .I "groff ms"
  1352. should use this number register.
  1353. .
  1354. .IP \(bu
  1355. To make
  1356. .I "groff ms"
  1357. use the default page offset (which also specifies the left margin),
  1358. the
  1359. .B PO
  1360. number register must stay undefined until the first
  1361. .B ms
  1362. macro is evaluated.
  1363. This implies that
  1364. .B PO
  1365. should not be used early in the document, unless it is changed also:
  1366. Remember that accessing an undefined register automatically defines it.
  1367. .br
  1368. .ne 23
  1369. .
  1370. .
  1371. .SS Strings
  1372. .
  1373. You can redefine the following strings to adapt the
  1374. .I "groff ms"
  1375. macros to languages other than English:
  1376. .TS
  1377. center;
  1378. cb cb
  1379. afCW l .
  1380. String Default Value
  1381. _
  1382. REFERENCES References
  1383. ABSTRACT ABSTRACT
  1384. TOC Table of Contents
  1385. MONTH1 January
  1386. MONTH2 February
  1387. MONTH3 March
  1388. MONTH4 April
  1389. MONTH5 May
  1390. MONTH6 June
  1391. MONTH7 July
  1392. MONTH8 August
  1393. MONTH9 September
  1394. MONTH10 October
  1395. MONTH11 November
  1396. MONTH12 December
  1397. _
  1398. .TE
  1399. .
  1400. .PP
  1401. The
  1402. .B \[rs]*-
  1403. string produces an em dash \[em] like this.
  1404. .
  1405. .PP
  1406. Use
  1407. .B \[rs]*Q
  1408. and
  1409. .B \[rs]*U
  1410. to get a left and right typographer's quote,
  1411. respectively, in
  1412. .I troff
  1413. (and plain quotes in
  1414. .IR nroff ).
  1415. .
  1416. .
  1417. .SS Text Settings
  1418. .
  1419. The
  1420. .B FAM
  1421. string sets the default font family.
  1422. If this string is undefined at initialization,
  1423. it is set to Times.
  1424. .
  1425. .LP
  1426. The point size, vertical spacing, and inter-paragraph spacing for footnotes
  1427. are controlled by the number registers
  1428. .BR FPS ,
  1429. .BR FVS ,
  1430. and
  1431. .BR FPD ;
  1432. at initialization these are set to
  1433. .BR \[rs]n(PS-2 ,
  1434. .BR \[rs]n[FPS]+2 ,
  1435. and
  1436. .BR \[rs]n(PD/2 ,
  1437. respectively.
  1438. If any of these registers are defined before initialization,
  1439. the initialization macro does not change them.
  1440. .
  1441. .LP
  1442. The hyphenation flags (as set by the
  1443. .B hy
  1444. request) are set from the
  1445. .B HY
  1446. register;
  1447. the default is\~14.
  1448. .
  1449. .PP
  1450. Improved accent marks
  1451. (as originally defined in Berkeley's
  1452. .I ms
  1453. version)
  1454. are available by specifying the
  1455. .B AM
  1456. macro at the beginning of your document.
  1457. You can place an accent over most characters
  1458. by specifying the string defining the accent
  1459. directly after the character.
  1460. For example,
  1461. .B n\[rs]*~
  1462. produces an n with a tilde over it.
  1463. .
  1464. .
  1465. .
  1466. .SH "NAMING CONVENTIONS"
  1467. .
  1468. .
  1469. .LP
  1470. The following conventions are used for names of macros, strings and
  1471. number registers.
  1472. External names available to documents that use the
  1473. .I "groff ms"
  1474. macros contain only uppercase letters and digits.
  1475. .
  1476. .LP
  1477. Internally the macros are divided into modules;
  1478. naming conventions are as follows:
  1479. .
  1480. .IP \(bu 3n
  1481. Names used only within one module are of the form
  1482. .IB \%module * name\fR.
  1483. .
  1484. .IP \(bu
  1485. Names used outside the module in which they are defined are of the form
  1486. .IB \%module @ name\fR.
  1487. .
  1488. .IP \(bu
  1489. Names associated with a particular environment are of the form
  1490. .IB \%environment : name\fR;
  1491. these are used only within the
  1492. .B par
  1493. module.
  1494. .
  1495. .IP \(bu
  1496. .I name
  1497. does not have a module prefix.
  1498. .
  1499. .IP \(bu
  1500. Constructed names used to implement arrays are of the form
  1501. .IB \%array ! index\fR.
  1502. .
  1503. .PP
  1504. Thus the groff ms macros reserve the following names:
  1505. .
  1506. .IP \(bu 3n
  1507. Names containing the characters
  1508. .BR * ,
  1509. .BR @ ,
  1510. and\~\c
  1511. .BR : .
  1512. .
  1513. .IP \(bu
  1514. Names containing only uppercase letters and digits.
  1515. .
  1516. .
  1517. .
  1518. .SH FILES
  1519. .
  1520. .B @MACRODIR@/ms.tmac
  1521. (a wrapper file for
  1522. .BR s.tmac )
  1523. .br
  1524. .B @MACRODIR@/s.tmac
  1525. .
  1526. .
  1527. .
  1528. .SH "SEE ALSO"
  1529. .
  1530. .BR groff (@MAN1EXT@),
  1531. .BR @g@troff (@MAN1EXT@),
  1532. .BR @g@tbl (@MAN1EXT@),
  1533. .BR @g@pic (@MAN1EXT@),
  1534. .BR @g@eqn (@MAN1EXT@),
  1535. .BR @g@refer (@MAN1EXT@),
  1536. .I Groff: The GNU Implementation of troff
  1537. by Trent Fisher and Werner Lemberg.
  1538. .
  1539. .
  1540. .
  1541. .SH AUTHOR
  1542. .
  1543. Original manual page by James Clark
  1544. .IR "et al" ;
  1545. rewritten by Larry Kollar
  1546. (\fIlkollar@despammed.com\fR).
  1547. .
  1548. .cp \n[groff_ms_C]
  1549. .
  1550. .\" Local Variables:
  1551. .\" mode: nroff
  1552. .\" End: