This is part of the Groff Series:
Groff II: Requests, Escape Sequences, and Macros
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!
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 organizing 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 vertical 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 can format text inline. The `\f` sequence can take `B`, `I`, and `R` arguments to make the text bold, italic, or "roman". The `\s` sequence 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:
image: screenshot of pdf with variable fonts
You can read all about requests and escape sequences in `man 7 groff`.
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".
:wq
Thoughts? Comments? Let me know at dozens@tilde.team
Filed under:
title: Groff II: Requests, Escape Sequences, and Macros author: dozens <dozens@tilde.team> url: gemini://tilde.town/~dozens/gemlog/22.gmi created: 2024-02-17T00:00:00-06:00 updated: 2024-02-24T00:00:00-07:00 tags: groff