The GNU roff program or groff is a typesetting program that takes marked up text files and produces structured output, most usefully in PostScript but also many other formats. It is related to the ancient Unix commands roff (run off), troff (typeset …), and nroff (new …). Because of stupid license issues groff is the only one left standing but it sometimes calls programs named after their inspirations for compatibility with such. Sticking with groff should suffice.

Seems like there is the core groff system and there are macros. This is like there is TeX and LaTeX. The most useful macros seem to be the ms set which stands for "Manuscript" macros. See man groff_ms.

There is another set of important macros, man which is for formatting man pages. Organizing man pages are probably groff’s main modern function. While you can use a modern tool to create man pages, they are classically specified in a roff type of syntax.

To see a language reference use man 7 groff.

Running

It seems the correct extension (according to Vim) for groff formatted files is filename.roff. When working with a file named differently in Vim use :set syntax=groff.

To make an X window display of the thing use -TX75 or -TX100 like:

gunzip -c /usr/share/man/man1/ls.1.gz |groff -TX75 -man -

Might think about including a .warn in the document to cause warnings to be output. This could be handy in the case of mysterious problems.

If you just need some text file put into Postscript as is, you can use something like this:

(echo '.nf'; cat atextfile) | groff -ms  > atextfile.ps

If someone has given you a groff formatted man page and you just need to see it like a man page, this works.

wget -qO- pastebin.com/raw/PT8LbcWA | groff -Tascii -man | less

Core groff Language

Some delightfully ancient (1972) documentation lives here.

.

Starts a command or macro if first character of the line.

'

Same as dot but does not produce a line break. Again, as start of line. Elsewhere it is apostrophe as expected.

Units

You can use cm(c), inch(i), pica(P), point(p), Em(m), 100th of em(M), En(n).

Language

There are operators like +, -, *, /, % and boolean logic, grouping, comparison operators, etc. All normal looking.

There is a conditional if, ie (if-else) and el, and a while command. Some testable conditions are N (true if not zero), !N (true if zero), ` s1’s2 ` (if string s1 == s2), e (even page now), o (odd page), F<font> (Font <font> exists), etc.

.

Dot with otherwise empty line. Does nothing.

.hw <words>

List of words with exceptional hyphenation.

.ig

Ignore text until .. encountered. Found in Copyrights, etc.

.kern

Enable kerning. Use .kern 0 to disable.

.length <reg> <string>

Set register to string length.

.na

No output line adjusting.

.nh

No hyphenation mode.

.nm N [M [S [I]]]

Line number mode. Set number, multiple, spacing, indentation.

.pc [<c>]

Set page number character. Default is %.

.rj <n>

Right justify the next n lines.

.sp [<n]>

Skip one or n lines. Like a line break of sorts. Value of 0 is just inserts a line break. Also values of .5, etc, are ok.

.substring xx n1 n2

Maybe more like a "slice"?

.tl 'left'center'right'

Title definition.

.tr abcd...

Translate a to b and c to d etc.

.ul N

Underline (or italicize in some contexts) N lines.

Macros

There are various macros for use with groff which seem low level, but are a lot better than the real groff stuff. One common one is the macro -man which is useful for interpreting man pages.

Another very useful one is -ms which stands for "manuscript". This has a lot of very useful (essential!) things. If something you’re trying is not working and you think it should, make sure you’re not failing to load the corresponding macro package.

To convert a file with the -ms macro set use:

groff -ms file

Commands

.2C

Two columns starting here.

.1C

Back to one column at this point.

.MC[colwidth[gutterwidth]]

General multicolumn command.

.NH

Numbered Heading.

.SH

Simple/Standard? Heading (not numbered).

.PP

Ordinary paragraph starter.

.IP

Indented paragraph - comes with numbers if label supplied.

.RS

Right shift. Do the indenting yourself.

.RE

Release end. Resets a .RS back left again.

.QP

Next paragraph is indented (like blockquoting).

.QS

Start next several paragraphs indented.

.QE

End the indenting of paragraphs.

.I

Italic. Can also be done by the word with .I word.

.R

Roman. Resets italic back to normal.

.B

Bold. Works like italic and resets with .R the same too.

.CW

Constant Width. Courier. Like <tt>.

.LG

Increase font from previous size until next major feature. Can be used multiple times and can cancel levels of .SM.

.SM

Decrease font from previous size until next major feature.

.NL

Normal font size as specified by the PS register.

.B1

Box. Don’t confuse with bold. .B2 stops boxed section.

.BX

Box a just a word.

.DS

Display (like <pre>) start. Also .DS C for center. Doesn’t rearrange words. Useful for code, tables, etc.

.DE

Display End.

.KS

Keep a block of text together, start.

.KE

Keep a block of text together, end.

.KF

Keep a block of text together, move the block through the text until it fits (all on the same page).

.bp

Begin new page.

.sp n

Insert n spaces.

.na

Non-aligned right margins. (Left justify, not "full" justify.)

.br

Break. Don’t know exactly how it works.

.DA

Force a date to be printed (at the bottom of the page).

.ND

Suppress printing of a date.

.SG

Include signature line (somewhere?). Not too helpful.

.EQ [n]

Equation formatting. Numbered with n.

.EN

End of equation? Or some other kind?

.TS

Start of table.

.TE

End of table.

.TL

Specify title.

.AU

Specify Author.

.AB

Start Abstract.

.AE

End Abstract.

.EX

Example?, fixed-width, like <tt>.

.EE

End Example.

Registers

There are named registers (like variables) that can be modified to achieve various effects. Use the .nr NAME VALUE syntax to change them.

Register

Defines

Takes effect

Defaul

PS

Point Size

Next Paragraph

10

VS

Vertical Spacing

Next Paragraph

12pts

LL

Line Length

Next Paragraph

6"

LT

Length Title

Next Paragraph

6"

PD

Paragraph Padding

Next Paragraph

.3*VS

PI

Paragraph Indent

Next Paragraph

5ens

FL

Footnote Length

Next FS

11/12*LL

CW

Column Width

Next 2C

7/15*LL

GW

Intercolumn GTap

Next 2C

1/15*LL

PO

Page Offset

Next Page

26/27"

HM

Head Margin

Next Page

1"

FM

Foot Margin

Next Page

1"

LH

Left Head String

CH

Center Head String

RH

Right Head String

LF

Left Foot String

CF

Center Foot String

RF

Right Foot String

PN

Page Number

Accents

\*'e resume accented e (acute?)
\*:u umlaut over u