Groff manual

• Introduction
  • What is Groff
  • Using Groff
• Writing Groff Documents
  • Basics
  • Page Layout
  • Headers and Footer
  • Line Layout
  • Fonts
  • Drawing
  • Tables
  • Lists
  • Page Motions
  • Using Symbols
  • Including Pictures
  • Sourcing Files
  • Multiple Columns
  • Defining Strings
  • Writing Macros
  • Traps
  • Others

Groff is a program which enables you to produce very neat documents from UNIX. Documents can be formated exactly as you wish, including boxes, tables and even pictures.
Groff takes a little time to learn, but this is well worthwhile as the printed document is much smarter than the default Premvet documents.

Groff documents can be produced in your favourite text editor, and consist of the text to be printed along with the groff commands which do the formating. This is very similar in principle to an HTML document, or even a simple .def file.

Groff can be quite difficult to use by itself, but it provides macro facilities which make it much easier. Many macros are collected together into macro packages such as man (which formats the UNIX man pages) and mm. This manual assumes that you are using the mm macro package.

Pre-processors are used to convert certain types of input, such as tables, post-processors are used to convert the document to a form understood by your printer. These are both taken care of automatically by Premvet.

How do I use Groff

Premvet will automatically print groff documents using the correct programs so long as the first line of the document is

.ty nroff

.pr X

.dp X

If you are writing your own printer script and have an HP Laserjet printer, then the command line would be something like:

/usr/local/bin/groff -t -mm -Tlj4 $1 | lp

.sp

.sp 3

.sp -2

Arguments are separated from the command and from each other by spaces.

The other type of groff command is an escape sequence. These start with \ and can be placed part way through a line, or even inside a word.

In groff, measurements can be in several different units and it is generally wise to specify these, then you can be sure what you will get. The most useful units are: i (inches), c (cm) and v (vertical space - the current line spacing, this is the default for .sp).

If you want a new line (a line break) the command to use is:

.br

When groff reads a file, it will fill the text - collect as many words together on one line as possible. Once it has filled a line, it will adjust it - widen the spaces between words so that the text reaches the right margin.

.nf will turn off filling (i.e. not join lines), while .fi will turn it on again.
.na will turn off adjusting, while .ad will turn it on again.

.ad will accept arguments:

l    will cause left justified text with a ragged right margin
r    will cause right justified text with a ragged left margin
c    will cause centre filled text
b    and
n    will justify to both margins. This is the default.

Comments can be inserted into groff documents by preceeding them with \". This can be used to place comments on a line by themselves, or at the end of another line.

If \" is used to start a line, a one line space will be printed. To avoid this use .\" instead.

Page Layout

The .pl command does not affect the top and bottom margins, these are controlled by the .VM command. This accepts two arguments, the top and bottom margin sizes.

.VM 0 0

.bp will break the page, printing continues on the next page.

Sometimes you may want to force a certain amount of space before a page break occurs, this will avoid having odd lines at the bottom of the page. The .ne request will ensure that there is a certain distance before the next page is triggered. .ne accepts an argument - for instance .ne 2v will ensure that the next page break doesn't occur for at least two lines.

To help in adjusting lines, groff will sometimes hyphenate a word and split it over two lines. It is possible to control how groff does this using the .hy command. .hy accepts arguments as follows:

1    hyphenate without restriction (the default).
2    do not hyphenate the last word on a page or column.
4    do not hyphenate the last two characters of a word.
8    do not hyphenate the first two characters of a word.

These arguments are additive so, for instance, if you don't want to hyphenate the first two or the last two characters, use the argument 12.

If you want to avoid hyphenation altogether, use the .nh command.

Headers and Footers

.tl '*********'%'*********'

The chances are that you will usually not want a title at all at the top of your pages. It is possible to abolish titles altogether and there are several ways of doing this.
The .PGNH command will abolish the header on the next page. This doesn't always seem to work on the first page though, and it can be inconvenient to pepper your document with .PGNH's. There is a way of abolishing headers and footers on every page - you need to put the following macros at the top of your document (macros are explained later).

.de TP
..
.de EOP
..
.nr pg*header-size 0
.nr pg*footer-size 0
.pg@move-trap

.ll 7.5

The left margin is set with the page offset (.po) command.

.po 0.5i

The .in command sets the distance from the left margin where text will start printing.

Both .po and .in can be called without an argument. This will reset the value to whatever it was before it was last reset.
The right margin is whatever is left on the page after .po, .in and .ll are added together. This is illustrated by the following diagram:

     |-----------------ll-------------|


|-po-|-in-|-----------text------------|-right margin-|


|--------------------Paper width---------------------|

The .ce command will centre lines. This command takes one argument - the number of lines to be centred. If the argument is ommited, one line will be centred. A common way to use this command is to centre many lines and then to turn centreing off as follows:

.ce 100
several lines of text
.ce 0

.R    Times Roman
.I      Italic
.B    Bold
.BI   Bold italic

but it is also possible to change the font using an escape sequence.

This is \fBVERY\fR important

This is VERY important

.S 12 14

.ps 12
.vs 12

.ps +2

.ps -2

Point size can also be changed part way though a line or word by using \s. This works in the same way as .ps, but there is no space between the command and the argument.

This is \s+2VERY\s-2 important

To double space lines, use .ls 2. .ls 1 will return to single spacing.

.VERBON will print text "verbatim" using courier font. All characters have the same width. This can be useful if you wish to include text from Premvet5 that has been formatted into columns. Premvet output is formatted for courier, so printing this in Roman font would disrupt the columns. .VERBOFF ends verbatim output.

Drawing

\L will draw vertical lines in the same way as \l draws horizontal lines. The default drawing character is | (the pipe character). Positive values for length will draw downwards, negative will draw upwards.

.B1 draws a box around the following text. The text will be indented 1 character and the right margin will be 1 character shorter. .B2 ends the box.

To print the clients name and address with a box around it, you could use:

.B1
&client
&address1
&address2
&address3
.B2

\D'c d'    Draw a circle with a diameter of d with the leftmost point at the current position.
\D'C d'    Draw a solid circle with the same parameters as an outlined circle.
\D'e dx dy'    Draw an ellipse with a horizontal diameter of dx and a vertical diameter of dy with the leftmost point at the current position.
\D'E dx dy'    Draw a solid ellipse with the same parameters as an outlined ellipse.
\D'p dx1 dy1 dx2 dy2 ...'    Draw a polygon from the current location to (dx1,dy1) then to (dx2,dy2) and so on. Then back to starting point.
\D'P dx1 dy1 dx2 dy2 ...'    Draw a solid polygon with the same parameters as an outlined polygon.

These are a bit complex, so I'll give some examples.
The following will draw an elipse 1 inch across and 1/2 inch high:

\D'E 1i 0.5i'

\D'p 0.13i 0 0 -0.13i -0.13i 0 0 0.13i'

.TS
tab(^);
l l.
I ^&client^
of^&address1^
  ^&address2^
  ^&address3^
.TE

You can also specify other options in the same line. These options must be separated from each other with a space.

center     Centres the table. Default is left justified.
expand    Expands the table to the full width of the page (cannot be used with center).
box         Draws a box around the table.
doublebox Draws a double box (with two lines) around the table.
allbox    Draws a box around each item in the table.

The next line - l l. - tells groff to left justify both columns. You could also use:

r to right justify
c to centre the text
n to line up the column on decimal points (a numeric column)
s to allow the entry from the previous column to span across.

You need to specify each column, and this line must end with a full stop.

If you want to justify different lines of your table differently, you can specify this.

l l l.
c c c.

The following format features can also be used in this line:

| Placed between column format letters will print a vertical line between these columns.
_ instead of a format letter will draw a single line in place of the column.
= will do the same as _, but with a double line.
A number after a format letter will set the gap between this column and the next.
B will change to bold font.
I will change to italic font.

The following illustrates another use of tables. This produces a checklist.

.TS
allbox tab(^);
l c c c c c c c c c c c c c.
^MON^^TUE^^WED^^THU^^FRI^^SAT^
^am^ pm ^am^ pm ^am^ pm ^am^ pm ^am^ pm ^am^ pm ^
Clean sink ^^^^^^^^^^^^
Clean cloth ^^^^^^^^^^^^
Clean instruments ^^^^^^^^^^^^
Wipe down surfaces ^^^^^^^^^^^^
.TE

A simple list is laid out as follows:

.BL
.LI
I hereby give permission for the administration of an anaesthetic to the above animal and to the surgical procedure detailed on this form, together with any other procedures which might prove necessary.
.LI
I understand that all anaesthetic techniques and surgical procedures involve some risk to the animal.
.LI
I understand that I am expected to settle the account on collecting the animal from the surgery.
.LE

The list types available are:

.BL a bullet list - each item is preceded by a bullet
.AL an autoincrement list - each item is preceded by a number
.DL a dash list - each item is preceded by a dash
.ML a marked list - each item is preceded by a mark of your choice
.RL a reference list - each item is preceded by an automatically incremented number between square brackets
.VL a variable item list - each mark is specified individually after .LI
.BVL a broken variable list - as .VL, but the item starts on the line after the mark

Each of these accepts optional arguments:

.BL, .DL and .RL accept up to 2 arguments. The first is the text indent. Any second argument will stop a blank line being printed before each item.

So

.BL
.LI
item 1
.LI
item 2
.EL

     item 1

     item 2

While

.BL 1 1

 item 1
 item 2

i.e. an indent of 1 and no blank line before each item.

.AL and .ML also accept another argument in front of the usual two. In .AL this argument sets the numbering type and is optional:

1    Arabic numbers (the default)
A    Upper case letters
a    Lower case letters
I    Upper case Roman
i    Lower case Roman

In .ML this first argument is the mark and is not optional.

.VL and .BVL also accept three arguments. The first is required and sets the indent to the text. The second, optional argument sets the distance from the current indent to the mark. The third argument, also optional, prevents a blank line before each item.

Page Motions

.MOVE will move you to a set position on the page. .MOVE accepts three arguments, the first is required and is the distance from the top of the page.

.MOVE 0

.MOVE 10i

The second, optional, argument is the page offset and the third argument, also optional, is the line length.

Another useful method of moving around the page is the .mk command. This marks a position on the page which you can later return to, from further down, with .rt.

Using Symbols

The most useful of these are:

\(Po    Pound sign
\(bu    Bullet
\(co    Copyright
\(rg    Registered
\(tm    Trademark
\(de    Degree
\(*A    Capital alpha
\(*a    Lower case alpha
\(*B    Capital beta
\(*b    Lower case beta
\(*G    Capital gamma
\(*g    lower case gamma

But there are many others also.

Including Pictures

.PSPIC /u/vetdata/text/images/frontline.ps

By default, .PSPIC will centre the image on the page, but you can change this by putting -L (for left), -R (for right) or -I n where n is the amount to indent, before the file name.

It is also possible to set the size of the picture.

.PSPIC -I 2i /u/vetdata/text/images/logo.ps 2i 3i

The image files must be in encapsulated postscript (EPS) format and there are several ways of creating them. Images created in Paint Shop Pro (and probably other windows programs) and saved as EPS files will not work, as the postscript is buggy. The following ways are known to work:

Create an image file in any graphics program and save as jpg or gif. Use xv in Unix to convert this to EPS.

Create an image file in any MS Windows graphics program and print it using the Adobe postscript driver (available from the Adobe website) or the Apple Laserwriter driver (included with Windows) to a file on disk. Make sure you select the EPS setting.

Both of these methods work fine, but the second seems to produce better quality images.

The .PSPIC command is one of the macros included with the postscript postprocessor, so you will need to format the groff output for postscript. This can be done automatically by using

.TY PSROF

If you don't have a postscript printer, but are using an HP laserjet, you will need to convert the postscript to a form that laserjets can understand using the Ghostscript program. This can be done with:

.TY PSGS

If you are using your own printer scripts, the following command line is suitable for an HP laserjet 5L or 6L:

groff -t -mm -Tps $1 | gs -q -dNOPAUSE -sDEVICE=ljetplus -sPAPERSIZE=a4 -sOutputFile=\|"lp -s -d$PRINTER" - -c quit

.so /u/vetdata/text/letterhead.def

.mso mstp.tmac

.1C will return to single column output and will cause a page break. If you give .1C an argument of 1, the page break will be disabled.

Defining Strings

.ds sign Mr V Surgeon BVSc MRCVS

\*(sign

Mr V Surgeon BVSc MRCVS

If you want a space at the beginning of the defined string, you should preceed the definition with "

.de sign " Mr V Surgeon BVSc MRCVS

Do not put another " at the end of the string, if you do it will be included in the string.

Writing Macros

The first line of a macro definition is .de X where X is the name of the macro. Following lines are the commands used in the macro, the last line is .. (two dots). Make sure that you don't give your macro the same name as an existing command (unless you want to replace that command). Sometimes it is useful to replace an existing command. An example is the TP macro that we used earlier in this manual to abolish page headers. .TP is used automatically by groff to set up the top of the page. This macro re-defines .TP as nothing:

.de TP
..

It might be that you always want 3 blank lines before each new paragraph, and the first line of the paragraph indented by 5 spaces. If so, you could define a macro to do this:

.de PARA
.sp 3
.ti 5
..

A slightly more complex example can be used to insert a picture and flow text around it:

.de PSPICR
.mk
.PSPIC -R \\$1 \\$2 16i
.rt
.sp
.ll \\$4
.it \\$3 PSPICR-end
..
.de PSPICR-end
.ll
..

This macro first uses the .mk command to mark the position on the page. It then calls the .PSPIC command to insert an image; the -R argument to .PSPIC is used, so the image will be right justified. The image will be no more than $2 wide (and 16 inches high). The image name is the first argument to the macro. The macro then uses .rt to return to the marked position. .sp inserts a blank line and .ll sets the line length to $4 (the fourth argument).

.it is an input line trap (explained later) it calls the specified macro in a set number of lines (in this case $3 lines). The macro definition is ended with .. The command called by .it is defined next, this just returns the line length to it's previous setting.

To use this macro in your document, you could type:

.PSPICR /u/vetdata/text/images/acclaim.ps 2i 5 5i

Macros can be defined in each document, or they can be collected into your own macro file in the tmac directory. You would then use the .mso command to make the macros available in a document.

Traps

One type is an input-line trap. This will call a specified macro after a set number of lines. The format for this is:

.it X macro

.de pof
.it \\$1 pof-end
.po \\$2
..
.de pof-end
.po
..

Page location traps are often used for headers and footers. The format is:

.wh X macro

.\"Page header
.de hd
'sp 0.5i
.tl 'Veterinary Surgery Information'
'sp 0.3i
..
.\"Page footer
.de fo
'sp 1v
.tl "%"
'bp
..
.wh 0 hd
.wh 11i fo

End of input traps are called at the end of the last page. If you wanted a section for a signature at the end of your document, you could use:

.de sig
.sp 2
.in 2i
Signature \l'15' Date \l'6'
..
.em sig

You are unlikely to need any more detail, but details of all the obscure and less useful commands are available in the man pages.