summaryrefslogtreecommitdiff
path: root/support/lgrind/source/lgrind.1
blob: 8963aad647ffa9a96a928bdf34e616cf08375cd3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
'\" t
.\" @(#)lgrind.1 3.62 25/05/99 MPi; from UCB 4.3
.\" $Id: lgrind.1,v 1.5 2000/12/27 21:42:42 mike Exp $
.\" This man page was reverse engineered by George V. Reilly from the
.\" preformatted man page written by Tuna Ertemalp for Jerry Leichter's
.\" version of tgrind.  gvr remains wilfully ignorant of troff.
.dS C C\"       \" Fixed-width font
.TH lgrind 1 "25 May 1999" "TeX/LaTeX"
.SH NAME
lgrind \- grind nice program listings using LaTeX
.SH NOTE
This man page is not yet much outdated, but might be soon except somebody
asks me to work on it. Consider the LaTeX docs the real docs.
.SH SYNOPSIS
\fBlgrind\fR [ \fB-e\fP ] [ \fB-i\fP ] [ \fB-\fP ] [ \fB-n\fP ] [ \fB-c\fP ]
[ \fB-t\fP \fI<width>\fP ]
[ \fB-h\fP \fI<header>\fP ] [ \fB-d\fP \fI<description file>\fP ]
[ \fB-l\fP\fI<language>\fP ] [ \fB-s\fP ] \fI<name>\fP ...
.PP
.SH DESCRIPTION
LGrind formats program sources in a nice style using LaTeX(1).
Comments are placed in roman, keywords in bold face, variables in
italics, and strings in typewriter font. Source file line numbers
appear in the right margin (every 10 lines).
.PP
LGrind processes its input file(s) and writes the result to standard
output.  This output can be saved for later editting, inclusion in a
larger document, etc.
.PP
The options are:
.IP "\fB\-e\fP"
process a LaTeX file for embedded code.
.IP "\fB\-i\fP"
process source code file for inclusion in a LaTeX document.
.IP "\fB\-\fP"
take input from standard input.
.IP "\fB\-n\fP"
don't boldface keywords.
.IP "\fB\-c\fP"
don't treat @, etc. specially in comments.
.IP "\fB\-t\fP"
change tab width (default 8).
.IP "\fB\-h\fP"
specifies text to go into the header.
.IP "\fB\-d\fP"
specifies the language definitions file (default is
\fB/usr/lib/texmf/tex/latex/lgrind/lgrindef\fP).
.IP "\fB\-d!\fP"
same as above, but write patched executable.
.IP "\fB\-l\fP"
specifies the language to use.
.IP "\fB\-s\fP"
shows a list of currently known languages.
.PP
If LGrind is called without parameters, a help screen will be shown.
If neither \fB\-e\fP nor \fB\-i\fP are specified, a complete LaTeX
file is produced. When no language is specified, LGrind tries to find
out the language used itself; C is used when this fails.
.SH USAGE
For example, to include a C file named \fBfoo.c\fP
into your LaTeX document, first give the command:
.IP "\fC    lgrind -i -lc foo.c > foo.tex\fP"
.PP
This will generate \fCfoo.tex\fP, which will have the
pretty-printed version of \fCfoo.c\fP with a lot of LaTeX commands.
.PP
Then include \fClgrind.sty\fP as you include any other style,
namely with the \fC\eusepackage{lgrind}\fP line at
the beginning of your LaTeX document. Having done this,
within the document you can include \fCfoo.tex\fP using one of the
following commands:
.PP
.IP "\fC\elgrindfile{foo.tex}\fP"
which will simply include the file at that point
of text, and will draw horizontal lines before and
after the listing.
.PP
.IP "\fC\elagrind[htbp]{foo.tex}{caption}{label}\fP"
which will put the listing also within a figure
environment, using the float options, caption and
label you gave.
.PP
To produce a standalone LaTeX file from, say, a Yacc file:
.IP "\fC    lgrind -ly bary.y > bary.tex\fP"
This uses Piet van Oostrum's \fCfancyhdr.sty\fP to make the
headers and footers.
.PP
For a more detailed explanation of these commands, refer to
\fC/usr/TeX/texmf/doc/latex/lgrind.dvi\fP.
.PP
.SH "EMBEDDED PROGRAMS WITHIN A LaTeX FILE"
(From Jerry Leichter's notes.)
.PP
Within the text of your LaTeX file, you mark groups of lines as
either text- or display-style program code:
.PP
Text style:
.TS
l l.
.fT \*C
	The expression
	%(
	a + 3
	%)
	produces 10.
.fT
.TE
prints something like:  "The expression \fIa\fP + 3 produces 10."
(with "a + 3" set as a program.)
.PP
The same effect can be achieved with inline @'s.
.TS
l l.
.fT \*C
	The expression @a + 3@ produces 10.
.TE
.PP
Display style:
.TS
l l.
.fT \*C
	The statement
	%[
	a += 3;
	%]
	is an example of an incrementing operator.
.fT
.TE
prints something like:
.TS
l l.
	The statement
	      a += 3;
	is an example of an incrementing operator.
.TE
.PP
Important rules:
.IP
\fC%\fP and the following character must be the first two characters on
the line to be recognized.
.IP
Put \fInothing\fR on the line after the \fC%\fR and the key character.
If you do that, LGrind will provide a default environment that will
produce an \fC\ehbox\fP for \fC%(\fP \fC)%\fP, and a \fC\evbox\fP for
\fC%[\fP \fC-\fP \fC%]\fP.  If you put stuff on the line, LGrind
assumes you want to control the format completely.  Doing this
requires understanding \fIexactly\fP what the code LGrind produces is
doing. (Sometimes I'm not sure I do!)
.IP
\fC%)\fP and \fC%]\fP are, if I remember right, simply ignored outside
of a code group, but any extra \fC%(\fP or \fC%[\fP produces a
warning, so a missing \fC%)\fP or \fC%]\fP is usually caught.
.PP
You can insert your own code by using a line starting with \fC%=\fP in
the program text.  Whatever you enter after that is left in the
output, exactly as you typed it.  It will be executed in a strange
environment, so doing anything fancy is very tricky.  A macro, \fC\eLine\fP,
is provided to help you do simple things.  For example,
.TS
tab (/);
l.
.fT \*C
%[
%=\eLine{________\evdots}
        a = 1;
%]
.fT
.TE
produces:
.TS
tab (/);
l.
.fT \*C
        \.
        \.
        \.
        a = 1;
.fT
.TE
.PP
(Within the program text, \fC_\fP is active and expands to a
fixed-width space.  A whole bunch of macros are also defined.  If you
understand how LGrind sets lines up, you can replace the 8 \fC_\fP's
with a call to \fC\eTab\fP \(em but I'll let you hang yourself on that one.)
.PP
The output of LGrind always contains exactly one output line for each input
line.  Hence, you can look up line numbers in TeX error messages in your
original file, rather than in the lgrind'ed (lground?) file.  (Of course, if
the problem is in the LGrind output....)
.PP
Many things are controllable by re-defining various macros.  You can
change what fonts LGrind will use for various kinds of things, how
much it indents the output, whether it adds line numbers, and if so at
what interval it prints them and whether it sticks them on the left or
right, and so on.  This stuff is all described in \fClgrind.dvi\fP,
though probably not very well. The default settings produce output
that looks reasonable to me, though I can't say I'm ecstatic about it.
Doing a \fIreally\fP good job would require defining some special fonts.
.PP
.SH FILES
.IP "\fC/usr/bin/lgrind\fP"
Executable
.PP
.IP "\fC/usr/doc/lgrind/lgrind.dvi\fP"
Documentation
.PP
.IP "\fC/usr/lib/texmf/tex/latex/lgrind/lgrind.sty\fP"
LaTeX style file
.PP
.IP "\fC/usr/lib/texmf/tex/latex/lgrind/lgrindef\fP"
Language descriptions
.PP
.SH AUTHORS
Van Jacobson, Lawrence Berkeley Laboratory (based on
"vgrind" by Dave Presotto & William Joy of UC Berkeley),
wrote it for TeX.
.PP
Jerry Leichter of Yale University modified it for LaTeX.
.PP
George V. Reilly of Brown University changed the name to lgrind,
fixed up the man page, and added the program-text-within-comments
and @-within-LaTeX features.
.PP
Michael Piefel of Humboldt-University Berlin adapted it to
LaTeX2e and wrote decent documentation.
.PP
.SH "SEE ALSO"
\fBlatex\fR(1), \fBtex\fR(1), \fBvgrind\fR(1), \fBlgrindef\fR(5)