Documented in Volume 1 of the UNIX Programmers Manual.
See also % man 5 vgrindefs for a more complete explanation.
Here is how the example pages of the EXAMPLE Manual are produced by vgrind:
First, an executable shell script is placed in a file in the current
directory. Here is a list of it:
% cat -n Make.ex
1 #! /bin/sh
2 PRINTER=8/300
3 export PRINTER
4 cd /usr/local/lib/example/unix
5 /usr/lib/vfontedpr -d /ta/kemp/bin/vgrindefs -lex \
6 $* \
7 | cat /ta/kemp/bin/vgrind.macros /ta/kemp/bin/vgrind.vcat - \
8 | /usr/local/lib/ditroff/troff -Tip \
9 | /usr/local/dimp -t \
10 | /usr/ucb/lpr -Pimager
Once the shell script is in place, and if the text for the example of
vgrind is placed in the file named 'vgrind' in the present directory,
then the command:
% Make.ex vgrind
will produce, on the Imagen 8/300 printer known as 'imager', a hardcopy
version of the example for vgrind that resembles what you are presently
reading (if you are reading from the Example Manual). The following
discussion describes how this is accomplished.
At line:
1: the script is identified as a Bourne shell script.
2: set the environment variable PRINTER to an Imagen model 8/300.
3: set PRINTER in the parent shell, too.
4: cd to the directory containing examples of 4.2 UNIX commands.
5: vfontedpr inputs text from the files named at line 6, selecting
from the file /ta/kemp/bin/vgrindefs a set of language
formatting definitions named 'ex'. Based on those definitions,
troff directives and macro calls are interspersed with the
input text and passed to stdout.
6: the list of shell-expanded filenames to process,
'vgrind' in this case.
7: the set of macros (to satisfy troff macro calls generated by
vfontedpr) and a small set of font and point-size directives
are prepended to the text, and everything is passed to stdout.
8: device-independent troff processes the text, using the file named
/usr/lib/font/devip for fonts (-Tip), passing output to stdout.
9: device-independent imprint (the Imagen print program) processes
the text, prepends Imagen Impress language @document commands,
and passes output to stdout.
10: the print spooler lpr takes the input and spools it to the device
known as 'imager' (by virtue of being found as a printer entry in
/etc/printcap), which is an Imagen 8/300 printer.
The program named /usr/lib/vfontedpr is the key component of vgrind's
processing. It is a C program filter which massages the input by hiding
backslashes and other special characters from troff, as well as embedding
troff macro calls to macros residing in /ta/kemp/bin/vgrind.macros and
/ta/kemp/vgrind.vcat.
Vgrind's format-definition capability lets you specify alternate
fonts whenever text takes certain forms.
For that reason, the EXAMPLE database consists of structured text files
in a form that allows the text to be used two ways:
1) as the online output of the 'example' command
2) as input for generating a nicely formatted manual.
Below is the vgrindef definition residing in /ta/kemp/bin/vgrindefs for
the EXAMPLE manual. It defines exactly when alternate fonts will be used
(Note that the numbers are not part of the entry):
1 ex|example:\
2 :cb=(^ $):\
3 :ce=(\a? $):\
4 :kw=NOTE CAUTION WARNING BEWARE HINT BUGS\
5 See From \
6 CTRL DELETE RETURN ESC stdin stdout stderr newline EOF\
7 ANI ANIs\
8 GCB GPCC Tbox SAC HIGHLIGHTS PMSS\
10 USENET nic NIC Nic sri SRI Sri DDN ddn TAC\
11 SIMTEL20 simtel20 Simtel20\
12 BASS bass COD cod\
13 GUPPY guppy MARLIN marlin \
14 SALMON salmon SHARK shark TETRA tetra TROUT trout\
15 bugs daffy eel elmer frog gator mplvax noscf4 orca\
16 turtle whale roadrunner\
17 :
Note: if you are reading the Example Manual, you can see that keywords
on lines 4 through 16 above appear in a special boldface type.
That is because this page was created by vgrind, and the words are
defined as keywords.
Line 1: names the definition 'ex' or 'example'.
Line 2: specifies when to change fonts to boldface, font f2, for the
representation of actual keyins or actual output from the computer.
The cb parameter (:cb=) contains the start-font-f2 definition.
(^ $):\
means wherever there is a line consisting solely of a tab
then start using the font f2 (boldface). Note that the actual
tab character follows the ^ above.
NOTE:
^ is the beginning of line
( starts a group of alternative choices
$ is end of line
| is a logical 'or' between alternative choices
\d? is any or none of space, tab, newline or start of line
\a? is any string of symbols
) ends the group of alternative choices
: ends the start-font-f2 specification
\ hides the newline for vgrind's sake.
NOTE: the format may be skewed, depending on your choice of fonts
Line 3: specifies when to change fonts back to normal, font f1,
from boldface for the representation of normal narrative text.
The ce parameter (:ce=) contains the end-font-f2 definition.
(\a? $):
means at the next instance of a line terminated by a tab,
resume using font f1 (normal typeface).
Note that the actual tab character follows the ? above.
Lines 4-15: contain a list of keywords which will be highlighted in
alternate font f3 (special boldface) wherever they appear in the text.
If you are reading hardcopy, note that each of the "keywords"
actually does appear in special boldface because you are reading the
finished document.
To customize which fonts and point sizes are to be used, the file named
/ta/kemp/bin/vgrind.vcat contains:
.\" a variant of /usr/local/lib/ditmac/tmac.vcat:
.ps 10p \" point size of the manual text
.vs 12p \" vertical spacing for the above point size
.\" LOAD FONTS 1, 2 AND 3
.fp 1 HR \" Hershey Roman is the normal font for text, page headers
.fp 2 LB \" Listing Bold is for keyins, subheaders
.fp 3 H \" Helvetica is for keywords
The following troff macro file allows even more customization of the header
and footer lines. The contents of the file named /ta/kemp/bin/vgrind.macros:
'\" taken from /usr/local/lib/ditmac/tmac.vgrind
'\" f1 is Hershey Roman, f2 is Listing Bold, f3 is Helvetica
'\" (see vgrind.cat for the font and point-size assignments....)
'ss 18
'ds _ \d\(mi\u
'ds - \(mi
'\" 'ds / \\h'\\w' 'u-\\w'/'u'/ \" don't modify slash (/) characters
'ds /* \\h'\\w' 'u-\\w'/'u'/*
'bd B 3 \" pseudo-bold for Helvetica
'bd S B 3
'nr cm 0
'nf
'\" HEADER...............................
'de vH
'ev 2
'ft 1
'bd 1 3 \" pseudo-bold the header font
'sp .35i
'tl '\s14\f1\\*(=F\fP\s0'\\*(=H'\f1\s14\\*(=F\fP\s0'
'sp .25i
'ft 1
\f1\s12\h'\\n(.lu-\w'\\*(=f'u'\\*(=f\fP\s0\h'|0u'
'sp .05i
'bd 1
'ev
'ds =G \\*(=F
..
'\" FOOTER...............................
'de vF
'ev 2
'sp .35i
'\" 'tl '\f3\\*(=M''Page % of \\*(=G\fP' \" cannot properly datestamp,
'tl '\f3\November 1985''Page % of \\*(=G\fP' \" kludge the date manually
'bp
'ev
'ft 1
'if \\n(cm=1 'ft 2
..
'\" SET PAGE NUMBER........................
'de ()
'pn 1
..
'\" START A 'COMMENT'......................
'de +C
'nr cm 1
'ss 13
'ft 2
'ds +K
'ds -K
..
'\" END A 'COMMENT'........................
'de -C
'nr cm 0
'ss 18
'ft 1
'ds +K \f3
'ds -K \fP
..
'\" UNKNOWN?...............................
'+C
'-C
'am +C
'ne 3
..
'\" START A 'C FUNCTION NAME'..............
'de FN
\f2\s14\h'\\n(.lu-\w'\\$1'u'\\$1\fP\s0\h'|0u'\c
.if \\nx .tm \\$1 \\*(=F \\n%
'ds =f \&...\\$1
..
'\" ?......................................
'de FC
.if \\nx .tm \\$1 \\*(=F \\n%
'ds =f \&...\\$1
..
'\" CLEAN UP MACROS........................
'de -F
'rm =f
..
'\" GET READY, SET FONT TO 1...............
'ft 1
'lg 0
# From eugene miya - NASA Ames Research Center - @ames-vmsb.ARPA
# This definition is hacked from the Pascal definition. Ada and vgrind
# have several problems: should you treat tasks, packages, and generics
# as you treat procedures? Private objects are easily declared twice in
# such as way as to be confusing. Oh well! The keywords came from 1815a.
# Please mail any improvements to me.
ada|a:\
:pb=(^\d?procedure|function|task|package\d\p\d|\(|;|\:)|(=\d?record\d):\
:bb=\dbegin|case|loop|do|select|private\d:\
:be=\dend\d|;:\
:cb=--:ce=$:\
:sb=':se=':oc:\
:kw=abort abs accept access all and array at begin body case constant\
declare delay delta digits do else elsif end entry exception exit\
for function generic goto if in is limited loop mod new not null\
of or others out package pragma private procedure raise range record\
rem renames return reverse select separate subtype task terminate\
then type use when while with xor
WARNING:
1) Tabular data requires formatting with tabs to make output line up
correctly.
2) To get 'what-you-see-is-what-you-get', let column 1 always
contain a blank. Lines which contain a period (.) or a quote (')
in column 1 will be gobbled up and interpreted as troff directives
at vgrind-time.
BUGS:
1) vgrind insists on italicizing the asterisk (*) and the single quote (').
2) On multiple-file invocation, (i.e. vgrind f1 f2 f3), when each file
is more than one page, the date found on page one of f2 is actually
the date of f1, the date found on the first page of f3 is actually the
date of f2, and so on.
NOTE: the kludged line in the footer macro named vF (in
vgrind.macros above) is a brute force fix for this date bug.
3) An extra blank page is always generated as the last page.
This is probably related to the bug above.