# troff, groff, etc. #

troff is a typesetting system and markup language written by Brian Kernighan at Bell Labs in 1979.
GNU implements it as "groff".

Building blocks of troff:

- **Primitive requests**: a standard troff command in the form of a period followed by two letters. The period must appear at the start of a line. Any text following the request is treated as an argument.
- **Macros**: provide shortcuts to typeset more easily than with pure primitives. Macros may be grouped into packages, such as the `ms` and `man` packages. We can freely mix primitives and macro package commands.
- **Preprocessors**: a set of commands devoted to a particular task. The `pic` preprocessor formats line drawings, for example. The `tbl` preprocessor formats tables. We can embed preprocessor commands in a document that also uses macro commands and primitives.
- **Strings**: can be used as variable-like placeholders.
- **Number registers**: storage locations we can use to keep track of values like current font size, current indentation level, current list item, etc. Some registers are read-only, others we can manipulate. Number registers can contain alphabetic as well as numeric values.
- **Escape sequences**: backslash-escaped commands let us enter commands in-line, rather than on lines by themselves.
- **Special characters**: include long dash, degree symbols, and copyright symbols.

`nroff` sends output to a terminal instead of formatting it for printing.
Format a file of troff primitives:

	$ nroff -c myfile | less

troff produces (semi-)device-independent output that must be processed for a particular printer.

	$ troff myfile | hplj | lpr -hP printer

A sample file:

	.ft bi
	text filling and margin adjustments
	.ft p

	by default, troff fills lines to produce fully justified output with consistent right margins.
	however, the `.nf` primitive tells troff to leave a ragged right margin.

	.nf
	this bit of
	text will not be joined
	together
	to fill a line.

	.fi
	`.fi` is a primitive command that restores filling of lines.

	blank lines separate blocks of text.
	the `.br` primitive can be used to
	.br
	insert manual breaks.

	.ad l
	the primitive `.ad` adjusts the margins of filled text.
	the "l" argumnet, like `.ad l`, sets the text to left justified, as opposed to the fully justified default.
	this paragraph should be left justified, and look different from the first paragraph.

	.ad r
	the primitive `.ad r` sets the text to right justified.

	.ad c
	adjust the margin to center the text with `.ad c`.

	.ad b
	the `.ad b` primitive returns the text to default fully-justified block margins.

	.nf
	.ce 5
	if we turn off filling of lines
	with `.nf`, we can
	turn on
	centering with `.ce`, but we must
	specify the number of lines as an argument, like `.ce 5`.

	.ft bi
	vertical spacing
	.ft p

## Mom ##

Mom is macro package that ships with GNU Troff/groff aimed at ease of use and PDF output.
http://www.schaffter.ca/mom/momdoc/toc.html

Generate output like:

	$ groff -mom filename.mom > filename.ps

or, preferably:

	$ pdfmom -K utf-8 filename.mom > filename.pdf

Example:

```
.PRINTSTYLE TYPESET
.PAGELENGTH 8.5i
.PAGEWIDTH 5.5i
.L_MARGIN 33.45p
.R_MARGIN 33.45p
.T_MARGIN 33.87p
.B_MARGIN 33.87p
"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
```

Here's my take on a screenplay format using Mom:

```
\" Use Groff Mom and a few custom macros for approximate screenplay formatting.
\" $ pdfmom -K utf-8 screenplay.mom > screenplay.pdf
.PRINTSTYLE TYPESET
.PAPER LETTER
.L_MARGIN 1.5i
.R_MARGIN 1.0i
.T_MARGIN 1.0i
.B_MARGIN 1.0i
.FOOTER_MARGIN 0
.FOOTERS OFF
.HEADERS OFF
.PAGENUM_FONT C
.PAGENUM_POS TOP RIGHT
.PAGENUM_STYLE DIGIT
.PAGENUM_ON_FIRST_PAGE OFF
.PAGENUM_HYPHENS OFF
.FAMILY C
.PT_SIZE 12

.DOCHEADER_ADVANCE 0

 \" Character name/dialog cue:
 .de C
 .IBX CLEAR
 .IL 2.2i
 \\$*
 .IQ CLEAR
 ..

 \" Parenthetical dialog direction
 .de P
 .IBX CLEAR
 .IL 1.5i
 .IR 2.0i
 \\$*
 .IQ CLEAR
 ..

 \" Dialog
 .de D
 .IBX CLEAR
 .IL 1.0i
 .IR 1.5i
 \\$*
 .IQ CLEAR
 ..

 \" Transition
 .de T
 .rj
 \\$*
 ..

 .START
 .ad l

 INT. OBSERVATORY GANGWAY — DAY

 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

 .C ELIZABETH
 .P (while spitting up mouthfuls of blood)
 .D Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 

 .C JOHN (O.S.)
 .D Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

 .T CUT TO:

 .C FREDDIE
 .D Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 .P (into phone)
 .D Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

 EXT. BATTLEMENT (DENMARK) — NIGHT

 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
 ```

## Links ##

- https://www.gnu.org/software/groff/manual/groff.pdf
- http://cmd.inp.nsk.su/old/cmd2/manuals/unix/UNIX_Unleashed/ch08.htm
- https://www.gnu.org/software/groff/
- https://archive.org/details/Unix_Unleashed_System_Administrators_Edition
- http://www.troff.org/54.pdf
- https://www.linuxjournal.com/node/4375/print
- https://www.gnu.org/software/groff/groff-and-mom.pdf
- /usr/share/doc/groff-base/examples/mom/
- https://opensource.apple.com/source/groff/groff-28/groff/contrib/mom/momdoc/docprocessing.html?txt