💾 Archived View for thrig.me › tech › troff-quickstart.gmi captured on 2023-12-28 at 16:43:56. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-04-19)
-=-=-=-=-=-=-
These days troff (or something like it) mostly renders man pages, though typesetting PDF documents is another option. Troff is usually very fast compared to texlive. There are several implementations; groff is probably the most common and portable version these days.
https://www.gnu.org/software/groff/
https://github.com/n-t-roff/heirloom-doctools
https://man.openbsd.org/mandoc.1
Other documentation systems can likely emit troff; these are not considered here. A UnixTextProcessing.pdf can probably be found on the Internet. This text covers the vi editor, major troff macro systems, and how to write your own macros. mandoc is a variant particular to man pages though can be used to emit PDF; it may lack the typesetting possibilities of a more generic troff implementation.
$ doas pkg_add groff
Note that the OpenBSD port has modified groff to suit man pages under the port system, see the package readme for details. An input file might look like:
And the command to produce a PDF from it:
$ groff -Kutf8 -Tpdf < sample-groff.roff > out.pdf
Hey, it's a quickstart, not a book. And to render a man page:
$ groff -P-c -mtty-char -Tascii -mandoc -c < /usr/share/man/man1/ls.1
These sorts of commands may be hidden in the depths of various man implementations; the previous was extracted from the sysutils/man port in MacPorts on the old 2009 macbook.
$ doas pkg_add heirloom-doctools
$ PATH=/usr/local/heirloom-doctools/bin:$PATH
$ troff -ms sample-troff.roff | dpost | ps2pdf - out.pdf
The /usr/local/share/heirloom-doctools/tmac directory may be worth a study; there will be an equivalent directory for groff somewhere.