View on GitHub

presentations

Presentation notes from JMU Unix Users Group meetings

The Roff Document Formatting System

Mitch Feigenbaum - https://mrf-dot.github.io

Define the Terms

What is Roff?

What you need

1) Valid Groff Installation

- Linux: It's already installed
- Mac: `brew install groff`

2) Text Editor (VIM recommended)

Macro Sets

MAN Macro Set Quick Reference

       Macro   Meaning                         Subsection
       ───────────────────────────────────────────────────────────────────
       .B      Bold                            Font style macros
       .BI     Bold, italic alternating        Font style macros
       .BR     Bold, roman alternating         Font style macros
       .EE     Example end                     Document structure macros
       .EX     Example begin                   Document structure macros
       .I      Italic                          Font style macros
       .IB     Italic, bold alternating        Font style macros
       .IP     Indented paragraph              Paragraph macros
       .IR     Italic, roman alternating       Font style macros
       .LP     (Left) paragraph                Paragraph macros
       .ME     Mail-to end                     Hyperlink and email macros
       .MT     Mail-to start                   Hyperlink and email macros
       .OP     (Command-line) option           Command synopsis macros
       .P      Paragraph                       Paragraph macros
       .PP     Paragraph                       Paragraph macros
       .RB     Roman, bold alternating         Font style macros
       .RE     Relative-indent end             Document structure macros
       .RI     Roman, italic alternating       Font style macros
       .RS     Relative-indent start           Document structure macros
       .SB     Small bold                      Font style macros
       .SH     Section heading                 Document structure macros
       .SM     Small                           Font style macros
       .SS     Subection heading               Document structure macros
       .SY     Synopsis start                  Command synopsis macros
       .TH     Title heading                   Document structure macros
       .TP     Tagged paragraph                Paragraph macros
       .TQ     Tagged paragraph continuation   Paragraph macros
       .UE     URL end                         Hyperlink and email macros
       .UR     URL start                       Hyperlink and email macros
       .YS     Synopsis end                    Command synopsis macros

Using Groff MS

.TL

.TL
title

.IP \(bu

Groff MS Macros

  1. Report Cover
  2. Document Content
  3. Text Styling
  4. Document Preprocessors

Report Cover Macros

Headings

.NH 1
Top Level
.NH 2
Second level
.NH 3
Third level

Paragraphs

Quoted Paragraphs

Lists

Unordered (bulleted) list

.IP \(bu
Apple
.IP \(bu
Banana

Ordered (numbered) list

.nr a 0
.IP \n+a
Apple
.IP \n+a
Banana

Indents

.IP 1
Point 1
.RS
. IP 1.1
Nested point 1.1
. RS
.  IP 1.1.1
Nested point 1.1.1
. RE
.RE

Displays and Keeps

| With keep | No keep | Type of Display | | ——– | ——– | ——– | | .DS L | .LD | Left-justified | | .DS I [indent] | .ID | Indented | | .DS B | .BD | Block-centered | | .DS C | .CD | Centered | | .DS R | .RD | Right-justified | —

Displays and Keeps (cont.)

Footnotes

This text is in need of extra context.\**
.FS
This is the extra context we needed in the form of a footnote
.FE
Now the rest of the paragraph can proceed.

Text Size

Text Style

\f[CBI]This text is monospaced, bold, and italic. \f[R]This text is regular.

.BX "This text is in a box"

Text color

\m[red]this is red text\m[green]this is green text\m[black]this is black text.

Special characters

\(Do   Dollar $
\(Eu   Euro €
\(Po   British pound sterling £
\(aq   Apostrophe quote '
\(bu   Bullet sign •
\(co   Copyright ©
\(cq   Single closing quote (right) ’
\(ct   Cent ¢
\(dd   Double dagger ‡
\(de   Degree °
\(dg   Dagger †
\(dq   Double quote (ASCII 34) "
\(em   Em-dash —
\(en   En-dash –
\(hy   Hyphen ‐
\(lq   Double quote left “
\(oq   Single opening quote (left) ‘
\(rg   Registered sign ®
\(rq   Double quote right ”
\(rs   Printable backslash character \
\(sc   Section sign §
\(tm   Trademark symbol ™
\(ul   Underline character _
\(==   Identical ≡
\(>=   Larger or equal ≥
\(<=   Less or equal ≤
\(!=   Not equal ≠
\(->   Right arrow →
\(<-   Left arrow ←
\(+-   Plus-minus sign ±

Preprocessors

EQN

Let's show off the power of EQN by writing the quadratic formula in groff!
.EQ
x = {-b +- sqrt {b sup 2 - 4ac}} over 2a
.EN

TBL

.TS
allbox expand;
l l.
Email mfeigenbaum23@gmail.com
Github https://github.com/mrf-dot
Website https://mrf-dot.github.io
YouTube https://www.youtube.com/channel/UCdJoCFI6t7DTzms9Cr3U0hQ
.TE

Compilation

eqn file.ms | groff | ps2pdf

groff -e -Tpdf file.ms > file.pdf

grog -Tpdf file.ms --run > file.pdf

Writing Groff with Vim

augroup Roff
 autocmd!
 autocmd BufRead,BufNewFile *.ms,*.me,*.mom,*.man,*.mla set filetype=groff
 autocmd BufWritePost *.ms,*.me,*.mom,*.man,*.mla :execute '!grog -Tpdf % --run > %:t:r.pdf' | redraw
augroup END

Example Groff file

.TL
A file
.AU
<Your name>
.AI
Unix User Group
.PP
Hello, world!

Live Demonstration

Follow along at https://github.com/mrf-dot/proguide

Extra resources