ms: The ms macros: a reference for knitroff documents
In knitroff: Dynamic Reports in 'troff' with 'knitr'
ms R Documentation
The ms macros: a reference for knitroff documents
Description
A knitroff document is troff with the ms macros, a package for papers, reports and memoranda. This page lists the macros, registers and strings of ms as GNU groff implements it, following groff_ms(7) for groff 1.24.1. Marked entries are extensions: (Berkeley) from 4.2BSD, (Tenth Ed.) from Research Unix, (GNU) from groff. Requests and escapes, such as .sp and \fB, are in troff.
Using the ms macros with knitroff
render_roff()runs groff -ms -k -e -t -p: the ms macros, UTF-8 input, and the eqn, tbl and pic preprocessors. refer is not run, so .[ ... .] citations are left as they are.
.SS, .SE, .SRare knitroff's, not ms's: knitroff replaces them before groff sees the document. ms has no macros with these names, so there is no clash.
- listings
each R chunk becomes a .DS L ... .DE display in the constant-width font CR, so it is kept together on one page.
- figures
a plot becomes .PDFPIC -C (PDF) or .PSPIC -C (PostScript), centred, with its caption.
- a skeleton
a document needs at least one paragraph or heading macro; begin the text with .LP or .PP. After a heading, call a paragraph macro to end the heading text.
- settings
set registers and strings such as .nr LL 6i or .ds CH before the first ms macro other than .RP.
Document description
Call these in the order shown. .TL is required if any of .RP, .AU, .AI, .AB is used; .AE is required after .AB.
.RP [no-repeat-info] [no-renumber]report format: put the title, authors and abstract on a separate cover page. no is the AT&T form of no-repeat-info; the other options are (GNU).
.TLthe title: the following input lines, until .AU, .AB, or a heading or paragraph macro.
.AUan author's name, on the following lines. Call it again for each author.
.AIthe preceding author's institution, on the following lines.
.DA [x ...]the current date, or x, in the centre footer (and on the cover page with .RP).
.ND [x ...]no date in the footer; the date, or x, only on the cover page with .RP. This is groff's default.
.AB [no]begin the abstract, headed by an italic "ABSTRACT"; no leaves out the heading.
.AEend the abstract.
Paragraphs
Each paragraph macro breaks the line and adds the space in \n[PD].
.LPa paragraph with no indentation.
.PPa paragraph whose first line is indented by \n[PI].
.IP [mark [width]]an indented paragraph, with mark hanging in the margin: the way to make lists (.IP \(bu, .IP 1.). width (in ens) replaces \n[PI] and stays until the next heading or other paragraph macro.
.QPa paragraph indented from both margins by \n[QI], for quotations.
.QS, .QEbegin and end a region in which every paragraph is indented from both margins.
.XPan "exdented" paragraph: a hanging indent, every line but the first indented. (Berkeley)
Headings
.NH [depth]a numbered heading, 1., 1.1., 1.1.1. ..., at depth (default 1); the following lines are its text, ended by a paragraph macro. Skipping a depth draws a warning.
.NH S n ...set the heading numbers explicitly; numbering continues from them. (Berkeley)
.SH [depth]an unnumbered heading. depth (GNU) matches its size to .NH at that depth.
\*[SN], \*[SN-DOT], \*[SN-NO-DOT]the number of the last .NH, for captions and cross-references; with and without the final period. (GNU, SN Berkeley)
.als SN-STYLE SN-NO-DOTnumber headings without the final period. (GNU)
Registers PSINCR and GROWPS (GNU) make headings above a depth larger; HORPHANS (GNU) keeps a heading with lines of the next paragraph.
Typeface
In these macros, text is set in the face, then post in the previous face with no space, and pre before it: .B word , gives a bold word followed by a roman comma. Without arguments, the face holds until the next paragraph, heading or typeface macro. pre is (GNU).
.B [text [post [pre]]]bold.
.I [text [post [pre]]]italic.
.R [text [post [pre]]]roman (upright). Its arguments are (GNU).
.BI [text [post [pre]]]bold italic. (Tenth Ed.)
.CW [text [post [pre]]]constant width, for code in a sentence. (Tenth Ed.)
.BX [text]text in a box (reverse video on a terminal). Use unbreakable spaces, such as \~, inside it.
.UL [text [post]]underlined text (between underscores on a terminal).
.LG, .SM, .NLtype 2 points larger, 2 points smaller, or back to the normal size \n[PS].
\*{ ... \*}superscript. (GNU)
\*< ... \*>subscript. (GNU)
Indented regions
.RSbegin a region where headings, paragraphs and displays are indented further by \n[PI]. Regions nest. Use this, not .in, which ms resets.
.REend the innermost region.
Keeps, boxes and displays
A keep holds text on one page; a display also turns filling off, so lines break as in the source.
.KS, .KEbegin and end a keep: if it does not fit, the page breaks before it.
.KF, .KEa floating keep: if it does not fit, the text after it fills the page and the keep goes to the top of the next.
.B1, .B2a keep with a box drawn round it. Put it inside .KF ... .KE to let it float.
.DS L, or .LDa left-aligned display (.DS: kept; .LD: may break across pages). knitroff's listings are these.
.DS [I [indent]], or .ID [indent]an indented display, by indent or \n[DI].
.DS B, or .BDa block display: left-aligned, with its longest line centred.
.DS C, or .CDa centred display: each line centred.
.DS R, or .RDa right-aligned display. (GNU)
.DEend any display.
Displays and preprocessor regions get \n[DD] of space before and after (Berkeley); \n[DI] (GNU) is the default indentation.
Tables, pictures, equations and citations
Preprocessors find these tokens only at the start of a line, with nothing between the dot and the name.
.TS [H] ... .TEa table for tbl (see tbl). With H, the rows before .TH repeat at the top of each page.
.PS h v ... .PE or .PFa pic diagram; .PF ends it and returns to the top of the picture.
.EQ [align [label]] ... .ENan equation for eqn (see eqn), centred unless align is L or I, with label at the right margin.
.[ ... .]a citation for refer, which render_roff() does not run.
Footnotes
\**an automatically numbered footnote mark in the text. (Berkeley)
.FS [mark], .FEbegin and end the footnote text, set at the foot of the page. Without mark, the next automatic number is used.
\n[FF] sets the style: 0, the mark as a superscript (default); 1, as text with a period; 2, as 1 without indentation; 3, as 1 with the mark hanging. FI, FPS, FVS, FPD (the last three GNU) are the footnote indentation, type size, vertical spacing and paragraph distance. FS-MARK is a hook macro called by .FS. (GNU)
Headers and footers
.ds LH, CH, RHthe left, centre and right header; CH is -\n[%]-, the page number between dashes, by default.
.ds LF, CF, RFthe left, centre and right footer, empty by default.
.OH 'left'centre'right', .EH, .OF, .EFheaders and footers for odd and even pages. Any character can replace the apostrophes. (Berkeley)
%in header or footer text, the page number. ms prints no header on page 1.
.P1print the header on page 1 too. (Berkeley)
PT, BT, HDthe macros that print the header and footer, which you may redefine; HD is called after the header. (HD Berkeley)
Columns, tabs and contents
.1C, .2Cone column (default) or two columns.
.MC [width [gutter]]as many columns of width as fit, at least gutter apart; without arguments, two columns. \n[MINGW] (GNU) is the minimum gutter.
.TAreset tab stops to every 5 ens. Set others with .ta.
.XS [page], .XA [page [indent]], .XEbegin, add to, and end a table of contents entry; the lines between are its text. (Berkeley)
.PX [no], .TC [no]print the table of contents at the end of the document; .TC also restarts page numbers in roman numerals. (Berkeley)
.XN text, .XH depth textset a heading and make its contents entry at once, after .NH or .SH. (GNU)
Registers and strings
Set with .nr name value or .ds name text before the first ms macro. Defaults are for typesetters; terminals use the value in parentheses.
\n[PO] page offset (left margin) 1i (0)
\n[LL] line length 6.5i (65n)
\n[LT] title line length 6.5i (65n)
\n[HM], \n[FM] top and bottom margins 1i
\n[PS] type size 10p
\n[VS] vertical spacing (leading) 12p
\n[HY] hyphenation mode; 0 turns it off (Tenth Ed.) 6
\*[FAM] font family: T Times, H Helvetica, C Courier, ... (GNU) T
\n[PI] paragraph indentation 5n
\n[PD] space between paragraphs 0.3v (1v)
\n[QI] quotation indentation 5n
\n[PORPHANS] first lines of a paragraph kept together (GNU) 1
\n[PSINCR] heading size increment (GNU) 1p
\n[GROWPS] depth above which headings grow (GNU) 0
\n[HORPHANS] lines kept with a heading (GNU) 1
\n[FI] footnote indentation 2n
\n[FF] footnote format, 0 to 3 0
\n[FPS], \n[FVS] footnote type size and spacing (GNU) PS-2p, FPS+2p
\n[FPD] footnote paragraph distance (GNU) PD/2
\*[FR] footnote line length, as a ratio 11/12
\n[DD] space around displays (Berkeley) 0.5v (1v)
\n[DI] display indentation (GNU) 0.5i
\n[MINGW] minimum gutter between columns (GNU) 2n
\n[GS] 1 under groff ms, for a document to test 1
Strings for symbols: \*- an em dash; \*Q and \*U left and right quotation marks. Strings to translate: \*[ABSTRACT], \*[TOC], \*[REFERENCES], and \*[MONTH1] to \*[MONTH12].
Seventh Edition compatibility
groff ms is a reimplementation of AT&T ms, the package Mike Lesk wrote at Bell Laboratories and shipped with the Seventh Edition (1979). Marked entries are extensions: (Berkeley) from 4.2BSD, (Tenth Ed.) from Research Unix, (GNU) from groff. Leave them out and the document is one 1979 ms could have formatted. Some Seventh Edition macros were specific to Bell Laboratories and are not in groff: the document types EG IM MF MR TM TR, AT CS CT OK SG, the Bell Labs addresses HO IH MH PY WH, and UX. The old accent strings, such as \*' (acute) and \*: (umlaut), and .AM still work, but UTF-8 input or \[...] characters (see troff) are better.
See Also
troff, eqn, tbl, render_roff. In a terminal: man groff_ms; and M. E. Lesk, Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff, Bell Laboratories, 1978.
Examples
doc <- c(".TL", "A short report", ".AU", "A. Student", ".AB",
"One paragraph of abstract.", ".AE", ".NH", "Method", ".PP",
"The mean is `r mean(1:10)`.", ".IP \\(bu", "a list item")
writeLines(doc, file.path(tempdir(), "report.Rms"))
knitroff documentation built on Oct. 16, 2026, 5:09 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ms | R Documentation |
The ms macros: a reference for knitroff documents
Description
A knitroff document is troff with the ms macros, a package for papers, reports and memoranda. This page lists the macros, registers and strings of ms as GNU groff implements it, following groff_ms(7) for groff 1.24.1. Marked entries are extensions: (Berkeley) from 4.2BSD, (Tenth Ed.) from Research Unix, (GNU) from groff. Requests and escapes, such as .sp and \fB, are in troff.
Using the ms macros with knitroff
render_roff()runs
groff -ms -k -e -t -p: the ms macros, UTF-8 input, and the eqn, tbl and pic preprocessors.referis not run, so.[....]citations are left as they are..SS,.SE,.SRare knitroff's, not ms's: knitroff replaces them before groff sees the document. ms has no macros with these names, so there is no clash.
- listings
each R chunk becomes a
.DS L....DEdisplay in the constant-width fontCR, so it is kept together on one page.- figures
a plot becomes
.PDFPIC -C(PDF) or.PSPIC -C(PostScript), centred, with its caption.- a skeleton
a document needs at least one paragraph or heading macro; begin the text with
.LPor.PP. After a heading, call a paragraph macro to end the heading text.- settings
set registers and strings such as
.nr LL 6ior.ds CHbefore the first ms macro other than.RP.
Document description
Call these in the order shown. .TL is required if any of .RP, .AU, .AI, .AB is used; .AE is required after .AB.
.RP [no-repeat-info] [no-renumber]report format: put the title, authors and abstract on a separate cover page.
nois the AT&T form ofno-repeat-info; the other options are (GNU)..TLthe title: the following input lines, until
.AU,.AB, or a heading or paragraph macro..AUan author's name, on the following lines. Call it again for each author.
.AIthe preceding author's institution, on the following lines.
.DA [x ...]the current date, or x, in the centre footer (and on the cover page with
.RP)..ND [x ...]no date in the footer; the date, or x, only on the cover page with
.RP. This is groff's default..AB [no]begin the abstract, headed by an italic "ABSTRACT";
noleaves out the heading..AEend the abstract.
Paragraphs
Each paragraph macro breaks the line and adds the space in \n[PD].
.LPa paragraph with no indentation.
.PPa paragraph whose first line is indented by
\n[PI]..IP [mark [width]]an indented paragraph, with mark hanging in the margin: the way to make lists (
.IP \(bu,.IP 1.). width (in ens) replaces\n[PI]and stays until the next heading or other paragraph macro..QPa paragraph indented from both margins by
\n[QI], for quotations..QS,.QEbegin and end a region in which every paragraph is indented from both margins.
.XPan "exdented" paragraph: a hanging indent, every line but the first indented. (Berkeley)
Headings
.NH [depth]a numbered heading, 1., 1.1., 1.1.1. ..., at depth (default 1); the following lines are its text, ended by a paragraph macro. Skipping a depth draws a warning.
.NH S n ...set the heading numbers explicitly; numbering continues from them. (Berkeley)
.SH [depth]an unnumbered heading. depth (GNU) matches its size to
.NHat that depth.\*[SN],\*[SN-DOT],\*[SN-NO-DOT]the number of the last
.NH, for captions and cross-references; with and without the final period. (GNU,SNBerkeley).als SN-STYLE SN-NO-DOTnumber headings without the final period. (GNU)
Registers PSINCR and GROWPS (GNU) make headings above a depth larger; HORPHANS (GNU) keeps a heading with lines of the next paragraph.
Typeface
In these macros, text is set in the face, then post in the previous face with no space, and pre before it: .B word , gives a bold word followed by a roman comma. Without arguments, the face holds until the next paragraph, heading or typeface macro. pre is (GNU).
.B [text [post [pre]]]bold.
.I [text [post [pre]]]italic.
.R [text [post [pre]]]roman (upright). Its arguments are (GNU).
.BI [text [post [pre]]]bold italic. (Tenth Ed.)
.CW [text [post [pre]]]constant width, for code in a sentence. (Tenth Ed.)
.BX [text]text in a box (reverse video on a terminal). Use unbreakable spaces, such as
\~, inside it..UL [text [post]]underlined text (between underscores on a terminal).
.LG,.SM,.NLtype 2 points larger, 2 points smaller, or back to the normal size
\n[PS].\*{...\*}superscript. (GNU)
\*<...\*>subscript. (GNU)
Indented regions
.RSbegin a region where headings, paragraphs and displays are indented further by
\n[PI]. Regions nest. Use this, not.in, which ms resets..REend the innermost region.
Keeps, boxes and displays
A keep holds text on one page; a display also turns filling off, so lines break as in the source.
.KS,.KEbegin and end a keep: if it does not fit, the page breaks before it.
.KF,.KEa floating keep: if it does not fit, the text after it fills the page and the keep goes to the top of the next.
.B1,.B2a keep with a box drawn round it. Put it inside
.KF....KEto let it float..DS L, or.LDa left-aligned display (
.DS: kept;.LD: may break across pages). knitroff's listings are these..DS [I [indent]], or.ID [indent]an indented display, by indent or
\n[DI]..DS B, or.BDa block display: left-aligned, with its longest line centred.
.DS C, or.CDa centred display: each line centred.
.DS R, or.RDa right-aligned display. (GNU)
.DEend any display.
Displays and preprocessor regions get \n[DD] of space before and after (Berkeley); \n[DI] (GNU) is the default indentation.
Tables, pictures, equations and citations
Preprocessors find these tokens only at the start of a line, with nothing between the dot and the name.
.TS [H]....TEa table for tbl (see
tbl). WithH, the rows before.THrepeat at the top of each page..PS h v....PEor.PFa pic diagram;
.PFends it and returns to the top of the picture..EQ [align [label]]....ENan equation for eqn (see
eqn), centred unless align isLorI, with label at the right margin..[....]a citation for refer, which
render_roff()does not run.
Footnotes
\**an automatically numbered footnote mark in the text. (Berkeley)
.FS [mark],.FEbegin and end the footnote text, set at the foot of the page. Without mark, the next automatic number is used.
\n[FF] sets the style: 0, the mark as a superscript (default); 1, as text with a period; 2, as 1 without indentation; 3, as 1 with the mark hanging. FI, FPS, FVS, FPD (the last three GNU) are the footnote indentation, type size, vertical spacing and paragraph distance. FS-MARK is a hook macro called by .FS. (GNU)
Headers and footers
.ds LH,CH,RHthe left, centre and right header;
CHis-\n[%]-, the page number between dashes, by default..ds LF,CF,RFthe left, centre and right footer, empty by default.
.OH 'left'centre'right',.EH,.OF,.EFheaders and footers for odd and even pages. Any character can replace the apostrophes. (Berkeley)
%in header or footer text, the page number. ms prints no header on page 1.
.P1print the header on page 1 too. (Berkeley)
PT,BT,HDthe macros that print the header and footer, which you may redefine;
HDis called after the header. (HDBerkeley)
Columns, tabs and contents
.1C,.2Cone column (default) or two columns.
.MC [width [gutter]]as many columns of width as fit, at least gutter apart; without arguments, two columns.
\n[MINGW](GNU) is the minimum gutter..TAreset tab stops to every 5 ens. Set others with
.ta..XS [page],.XA [page [indent]],.XEbegin, add to, and end a table of contents entry; the lines between are its text. (Berkeley)
.PX [no],.TC [no]print the table of contents at the end of the document;
.TCalso restarts page numbers in roman numerals. (Berkeley).XN text,.XH depth textset a heading and make its contents entry at once, after
.NHor.SH. (GNU)
Registers and strings
Set with .nr name value or .ds name text before the first ms macro. Defaults are for typesetters; terminals use the value in parentheses.
\n[PO] | page offset (left margin) | 1i (0) |
\n[LL] | line length | 6.5i (65n) |
\n[LT] | title line length | 6.5i (65n) |
\n[HM], \n[FM] | top and bottom margins | 1i |
\n[PS] | type size | 10p |
\n[VS] | vertical spacing (leading) | 12p |
\n[HY] | hyphenation mode; 0 turns it off (Tenth Ed.) | 6 |
\*[FAM] | font family: T Times, H Helvetica, C Courier, ... (GNU) | T |
\n[PI] | paragraph indentation | 5n |
\n[PD] | space between paragraphs | 0.3v (1v) |
\n[QI] | quotation indentation | 5n |
\n[PORPHANS] | first lines of a paragraph kept together (GNU) | 1 |
\n[PSINCR] | heading size increment (GNU) | 1p |
\n[GROWPS] | depth above which headings grow (GNU) | 0 |
\n[HORPHANS] | lines kept with a heading (GNU) | 1 |
\n[FI] | footnote indentation | 2n |
\n[FF] | footnote format, 0 to 3 | 0 |
\n[FPS], \n[FVS] | footnote type size and spacing (GNU) | PS-2p, FPS+2p |
\n[FPD] | footnote paragraph distance (GNU) | PD/2 |
\*[FR] | footnote line length, as a ratio | 11/12 |
\n[DD] | space around displays (Berkeley) | 0.5v (1v) |
\n[DI] | display indentation (GNU) | 0.5i |
\n[MINGW] | minimum gutter between columns (GNU) | 2n |
\n[GS] | 1 under groff ms, for a document to test | 1 |
Strings for symbols: \*- an em dash; \*Q and \*U left and right quotation marks. Strings to translate: \*[ABSTRACT], \*[TOC], \*[REFERENCES], and \*[MONTH1] to \*[MONTH12].
Seventh Edition compatibility
groff ms is a reimplementation of AT&T ms, the package Mike Lesk wrote at Bell Laboratories and shipped with the Seventh Edition (1979). Marked entries are extensions: (Berkeley) from 4.2BSD, (Tenth Ed.) from Research Unix, (GNU) from groff. Leave them out and the document is one 1979 ms could have formatted. Some Seventh Edition macros were specific to Bell Laboratories and are not in groff: the document types EG IM MF MR TM TR, AT CS CT OK SG, the Bell Labs addresses HO IH MH PY WH, and UX. The old accent strings, such as \*' (acute) and \*: (umlaut), and .AM still work, but UTF-8 input or \[...] characters (see troff) are better.
See Also
troff, eqn, tbl, render_roff. In a terminal: man groff_ms; and M. E. Lesk, Typing Documents on the UNIX System: Using the -ms Macros with Troff and Nroff, Bell Laboratories, 1978.
Examples
doc <- c(".TL", "A short report", ".AU", "A. Student", ".AB",
"One paragraph of abstract.", ".AE", ".NH", "Method", ".PP",
"The mean is `r mean(1:10)`.", ".IP \\(bu", "a list item")
writeLines(doc, file.path(tempdir(), "report.Rms"))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.