Groff II
Requests, Escape Sequences, and Macros
2024-02-17
This is part of the Groff Series:
- Groff I: Whence and Wherefore
- Groff II: Requests, Escape Sequences, and Macros
Contents
Introduction
I took a lot of time between writing Groff I and Groff II because I took the time to read the entirety of UNIX Text Processing by Dale Dougherty and Tim O’Reily. It is a great book! And it is available for free as party of O’Reilly’s Open Books project.
https://www.oreilly.com/openbook/utp/
It was written in 1987 and is all about text processing with groff and nroff, and as a special bonus it also includes deep dives into vi and ex, sed, awk, coreutils like join and paste, and more. It is a wholistic text processing book. It has been a constant reference during the weeks since I read it. I liked it so much I ordered a use copy of the physical book! I highly recommend it!
Requests
You would use groff to typeset a document. And nroff to typeset a text file. One of main things they do is linefilling.
For example, I use a lot of linebreaks when typing. I find it useful for oragnizing thoughts and for editing later. Here’s a paragraph from the previous section:
It was written in 1987
and is all about text processing with groff
and nroff,
and as a special bonus
it also includes deep dives into
vi and ex,
sed,
awk,
coreutils like join and paste,
and more.
It is a wholistic text processing book.
It has been a constant reference
during the weeks since I read it.
I liked it so much
I ordered a use copy
of the physical book!That’s how I write!
I inserted a blank line to show you that by default it treats blank lines as the start of a new paragraph. Here’s how it looks piped through nroff:
It was written in 1987 and is all about text processing with
groff and nroff, and as a special bonus it also includes deep
dives into vi and ex, sed, awk, coreutils like join and paste,
and more.
It is a wholistic text processing book. It has been a constant
reference during the weeks since I read it. I liked it so much I
ordered a use copy of the physical book!See? Linefilling! And justified so pretty.
You can control your document with escape sequences and requests.
For example, you set your page margins with a combination of the
.ll line length request and the .po page
offset request. And you can use the .ti temporary indent
request to indent a line. And .ce to center one.
.sp will give you some verticle space.
.p0 1i
.ll 6.5i
.ce
the groff book
.sp 1
It was written in 1987
and is all about text processing with groff
and nroff,
and as a special bonus
it also includes deep dives into
vi and ex,
sed,
awk,
coreutils like join and paste,
and more.
.sp 0
.ti 5n
It is a wholistic text processing book.
It has been a constant reference
during the weeks since I read it.
I liked it so much
I ordered a use copy
of the physical book!When piped through nroff:
the groff book
It was written in 1987 and is all about text processing with
groff and nroff, and as a special bonus it also includes deep
dives into vi and ex, sed, awk, coreutils like join and paste,
and more.
It is a wholistic text processing book. It has been a con‐
stant reference during the weeks since I read it. I liked it so
much I ordered a use copy of the physical book!Escape Sequences
Escape sequences can format text inline. The \f sequence
can take B, I, and R arugments to
make the text bold, italic, or “roman”. The \s esquence can
set point size.
.p0 1i
.ll 6.5i
.ce
\s+2the groff book\s0
.sp 1
It was written in 1987
and is all about \f[I]text processing\f[] with groff
and nroff,
and as a special bonus
it also includes deep dives into
vi and ex,
\f[I]sed\f[],
awk,
coreutils like join and paste,
and more.
.sp 0
.ti 5n
It is a wholistic text processing book.
It has been a constant reference
during the weeks since I read it.
I liked it so much
I ordered a use copy
of the physical book!Now using groff -Tpdf so you can see the point size and
font face changes in the resulting
pdf:
man 7 groff.
Macros
Groff’s requests and escape sequences provide a ton of low level control over typesetting and text layout. But they don’t on their own provide any kind of document layout or semantic markup on their own.
That’s what macros are for.
Use the .de request to define a new macro, and the
.. to end the macro definition. Let’s make a macro for a
page title or section header.
.p0 1i
.ll 6.5i
.de TITLE \" Begin TITLE macro
.ce
## \\$* ##
.sp 1
.. \" End TITLE macro
.TITLE the groff book
It was written in 1987
and is all about text processing with groff
and nroff,
and as a special bonus
it also includes deep dives into
vi and ex,
sed,
awk,
coreutils like join and paste,
and more.
.sp 0
.ti 5n
It is a wholistic text processing book.
It has been a constant reference
during the weeks since I read it.
I liked it so much
I ordered a use copy
of the physical book!Back to nroff:
## the groff book ##
It was written in 1987 and is all about text processing with
groff and nroff, and as a special bonus it also includes deep
dives into vi and ex, sed, awk, coreutils like join and paste,
and more.
It is a wholistic text processing book. It has been a con‐
stant reference during the weeks since I read it. I liked it so
much I ordered a use copy of the physical book!You have to escape the escape characters inside macros.
$* is a special register that holds all of the macro
arguments. And inside the macro, it has to be double escaped like
\\$*.
A lot of groffers write their own macros and reuse them between documents. And also there are a lot of extremely powerful macro packages that come with your groff installation that provide you with a lot of high level document control, and a lot of nice features on top of the basic groff requests and escape sequences. These packages include the ms, me, and mom macro packages. And we will take a look at them in “Groff III: Macro Packages”.