💾 Archived View for tilde.town › ~dozens › gemlog › 22.gmi captured on 2024-08-24 at 23:43:26. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅️ Previous capture (2024-08-18)

-=-=-=-=-=-=-

Groff II: Requests, Escape Sequences, and Macros

This is part of the Groff Series:

Groff I: Whence and Wherefore

Groff II: Requests, Escape Sequences, and Macros

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!

image: unix text processing 👍

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 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

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`.

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".

:wq

Thoughts? Comments? Let me know at dozens@tilde.team

Filed under:

groff

All tags

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