summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cweb/src/cwebx.sty
blob: d20db59b171596004668ba25684a3ba9738f9a83 (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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
% $Id: cwebx.sty,v 3.1 1995/11/21 00:42:49 schrod Exp $
%----------------------------------------------------------------------

%
% LaTeX2e package cwebx
% extra stuff for cweb bundle, to be added there sometimes
%
% [LaTeX2e]
% (history at end)


% Identification. The code below is explained in the implementation
% documentation of the rcs package.

\begingroup
    \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{%
        \def\date{#4}\def\id{v#7}%
        \ProvidesPackage{#1}[\date\space\id\space #2]%
        }

  \RCSPackage{cwebx}{extra stuff for cweb bundle}
  $Date: 1995/11/21 00:42:49 $: 9999/00/00 \endRCS
  $Revision: 3.1 $: 0.0 \endRCS
\endgroup


%
% What's this package for?
%
% Additional macros for cweb.cls or cwebpart.sty, to be added there
% sometimes.
%


% requires that cweb base is loaded
\ifx \cwbb@loaded\undefined
    \PackageError{cwebx}{cweb base is not loaded}
            {This package requires the usage of either cweb.cls or
                cwebparts.sty.}
\fi


% This style is supported. Send bug reports, comments and repairs.
%
% The reference version may be retrieved via anonymous ftp from
% |ftp.th-darmstadt.de| [130.83.47.112], directory |pub/tex/latex|. It's
% placed there as a gzipped tar file. (The information on the
% IP~number is dated 27 Sep 95. It might have changed, also
% this is very unlikely. Use your friendly nameserver.)



\catcode`\_=\CatLetter



%%% ======================================================================


%%
%% Errors in cwebbase.doc
%%


% As \4 follows \B always, the \kern\CwebIndentUnit to neutralize that
% backspace must be made after run-in section, too. Between the chunk
% marker and the program code start is 1em then (inserted by LaTeX
% section start).

% FIXME: \4 does _not_ follow \B all the time. Check when it is
% issued. The code below was introduced to repair a problem that gets
% visible if one uses \cwebNoChunk with an indentation unit of 2em,
% obviously I have to look for a better repair possibility.

\CheckCommand*\B{%
    \cwbb@program
    \cwbb@indent 3\CwebIndentUnit  \hangindent\cwbb@indent
    \ifvmode
	\if@noskipsec
	    \indent		% add an empty documentation part
	\else
	    \noindent \kern\CwebIndentUnit
	\fi
    \fi
    \CwebNumberProgramPart
    }

\renewcommand\B{%
    \cwbb@program
    \cwbb@indent 3\CwebIndentUnit  \hangindent\cwbb@indent
    \ifvmode
	\if@noskipsec
	    \indent		% add an empty documentation part
	\else
	    \noindent
	\fi
    \fi
    \kern\CwebIndentUnit
    \CwebNumberProgramPart
    }


%%% ------------------------------------------------------------


%%
%% Macros from cwebparts.doc, to be moved to cwebbase.doc.
%%

% They are partly repaired and improved, where noted with `CHANGE'.


% \sect Now we can typeset pieces of \cweave{} output -- in principle.
% If these pieces have sections in them, they'll write entries to the
% |TOC| file. These entries will either mess up the structure of the
% document's table of contents or lead to \TeX{} error messages. That's
% because either toc entries for section types |part|, |chapter|, or
% |section| are written (causing the conflict); or toc entries for
% section types |chunk| and `|section|$i$' are written (being
% undefined).

% The best way seems to stop the included source to add anything to the
% table of contents or to do any mark processing. For that, we provide a
% macro |\CwebNoLists| that will locally redefine the \LaTeX{} cseqs
% that cause such actions to happen. That macro will be used at the
% start of the environment.

% CHANGE: Discard try code that redefines |\markboth| and |\markright|.

% \beginprog
\def\CwebNoLists{%
    \let\addtocontents\@gobbletwo
    \let\mark\@gobble
    }
% \endprog


% \sect Furthermore, section divisions should not start a new page.
% %
% \begin{fixme}
%   Currently, sections in the included parts are typeset exactly the
%   same way as they're typeset in the main document. That should be
%   different -- but how do I change it in a general way?
% \end{fixme}
%
% CHANGE: Moved to Cweb environment.


% CHANGE: Improved question.
%
% \sect OK, what gets destroyed by the environment? We need to save
% and restore counters that are changed globally by section commands.

% \beginprog
\ifx \chapter\undefined
    \let\cweb@save_c@chapter\@gobble
    \let\c@chapter\@gobble
\else
    \newcount\cweb@save_c@chapter
\fi
\newcount\cweb@save_c@part
\newcount\cweb@save_c@section
\newcount\cweb@save_c@chunk

\def\cweb@save_for_env{%
    %% save values changed globally by cwebbase macros
    \cweb@save_c@chapter\c@chapter
    \cweb@save_c@part\c@part
    \cweb@save_c@section\c@section
    \cweb@save_c@chunk\c@chunk
    \let\cweb@save_thechapter\thechapter
    \let\cweb@save_thesection\thesection
    %% set up typesetting of CWEB source
    \@nobreaktrue			% don't add space from first chunk
    }
\def\cweb@restore_env{%
    \global\c@chapter\cweb@save_c@chapter
    \global\c@part\cweb@save_c@part
    \global\c@section\cweb@save_c@section
    \global\c@chunk\cweb@save_c@chunk
    \global\let\thechapter\cweb@save_thechapter
    \global\let\thesection\cweb@save_thesection
    }
% \endprog


% \sect For the moment, we use list spacing around a |cweb| environment.
% \LaTeX{} supplies the |trivlist| environment for such purposes.

% But the environment content itself must not be typeset in a list
% context. Two problems exist: There must be at least one |\item|, it
% will actually add the vertical space and must therefore not be
% discarded. And list environments redefine |\par|, but the
% \pkg{cwebbase} macros need a more `normal' definition.

% An item label is stored by |\item| in the |\everypar| register. The
% label is only typeset if |@inlabel| is true. The flag |@newlist| tells
% most other \LaTeX{} macros, that there was no item yet; typically
% they'll add an empty paragraph if necessary.  As the content will
% start with a \LaTeX{} section division, or even with document markup,
% we don't want that empty paragraph and should skip the empty item
% label. (Often enough, due to the initialisation of |\everypar| in
% |\@startsection|, it will be thrown away anyhow). So we establish its
% postconditions, the next macro won't notice that the item hasn't been
% set actually.

% CHANGE: Added \CwebNoLists, as I consider it part of the env layout.

% CHANGE: Added paragraph below.
%
% Furthermore, section divisions should not start a new page.
% %
% \begin{fixme}
%   Currently, sections in the included parts are typeset exactly the
%   same way as they're typeset in the main document. That should be
%   different -- but how do I change it in a general way?
% \end{fixme}

% \begin{fixme}
%   Experimentally, we reduce the skip in front of a chunk to 1\,pc,
%   otherwise the distance between two chunks is far too wide compared
%   to other vertical distances in the text around the included stuff.
% \end{fixme}

% \beginprog
\def\CwebBeginEnvLayout{%
    %% use spacing of list, but switch off list handling afterwards
    \trivlist
    \@inlabelfalse			% don't go in horizontal mode
    \item\relax
    \global\@newlistfalse
    \global\@inlabelfalse\the\everypar
    \@setpar{\@@par}%
    %% now change cweb base layout, meant for classes
    \CwebNoLists
    \let\CwebEjectSection\@gobble
    \CwebChunkPreSkip 1pc plus 6pt minus 3pt
    }
\let\CwebEndEnvLayout=\endtrivlist
% \endprog


% \sect The environment gets trivial now. We supply a hook for a whole
% document and also environment-specific ones (as an optional
% environment argument).

% CHANGE: Renamed to `Cweb'. Lusers should actually not call that env
% directly, it's too dangerous.

% CHANGE: Added forgotten evaluation of \cweb@restore_env.

% \beginprog
\newenvironment{Cweb}[1][]%
    {%
	\CwebBeginEnvLayout
        \cweb@save_for_env
	\csname CwebEnvHook\endcsname
	#1
    }{%
        \cweb@restore_env
	\CwebEndEnvLayout
    }
% \endprog


% CHANGE: Have to improve the introduction of |cwebInput|. Now it has
% an additional optional parameter, where instance specific cseqs may
% be passed (like the cweb env).

% \sect An a convenience tag to include a complete \cweave{} file. Since
% we want to test the typesetting of our included \cweb{} program alone,
% we allow but ignore most kinds of document markup. Many of them have
% two arguments, one is optional.

% In the preambel, only |\documentclass| and |\usepackage| may appear.
% Titlepage material is handled, table of contents is discarded. The
% document environment does nothing, i.e., unlike the \cls{cweb} class,
% material behind |\end{document}| is not ignored.

% An |\end| tag is inserted by \cweave{} and must be redefined, we don't
% end an environment there. We'll open a group and will use that tag to
% close it again, as we know that we'll have reached the end of our
% \cweb{} file. Of course, |\end| must not be redefined during
% processing the actual program source -- environments are valid there.
% The redefinition is best be triggered by material inserted from
% \cweave{} at the very end, e.g., from |\inx|. But |\inx| may not be
% there (when \cweave{} is called with the `|-x|' option), we'll use
% |\enddocument| to add a |\inx| tag for safety reason. If the user
% didn't add an |\end{document}| to his file and used `|-x|', we're
% going to loose.

% CHANGE: Added handling of empty chunk. (@noskipsec was set after the
% environment, what messed up later invocations of program code if
% used with \cwebCodeExample.)

% \TeX{}nical note: |\document| must not have the same binding as
% |\relax|, as this would be interpreted as a non-existing environment
% by \LaTeX{}. (That's due to the |\csname| lossage.)

% \TeX{}nical note: Evaluating |\inx| in |\enddocument| will not have
% any effect, we're inside a group. That evaluation must be postponed
% after the group has been closed.

% \beginprog
\providecommand\cweb@doc_markup_gobble[2][]{}
\let\cwebInput\undefined
\newcommand*\cwebInput[2][]{%
    \begin{Cweb}
        [%
	    \begingroup
		\let\documentclass\cweb@doc_markup_gobble
		\let\usepackage\cweb@doc_markup_gobble
		\let\title\@gobble
		\let\author\@gobble
		\let\date\@gobble
		\let\maketitle\relax
		\let\tableofcontents\relax
		\let\document\empty
		\def\inx{\let\end\endgroup}%
		\let\fin\relax
		\let\con\relax
		\def\enddocument{%
		    \if@noskipsec	% empty chunk
		        \global\@noskipsecfalse
			\global\everypar{}%
		    \fi
		    \aftergroup\inx
		    }%
		#1%
	]%
      \input{#2}%
    \end{Cweb}%
    }
% \endprog


%%% ------------------------------------------------------------


%%
%% New macros for cwebbase.doc.
%%


% For production of code examples in CWEB documents. It's expected
% that the document consists of only \emph{one} chunk that has no
% documentation. Just the code is of interest. Neither chunk markers,
% nor chunk numbers, nor refinement numbers are typeset.
%
% But one may change that with the optional parameter.

\providecommand*\cwebCodeExample[2][]{%
    \cwebInput[%
        \def\CwebChunkHeading##1{\kern -1em}%
	\let\cwbb@marginal_chunkno\relax
	\let\CwebRefNumber\@gobble
	\CwebChunkPreSkip\z@skip
	#1%
	]{#2}%
    }


% Often one has an explanation for more than one refinement. (E.g.,
% when there's needed a definition and a declaration.) Then the
% documentation of the follow-up refinements shall consist solely of
% |\cwebNoChunk|. Then no chunk marker is set, and the refinement
% is typeset nearer to the previous refinement. Optically, we create
% one chunk with many refinements this way.

% \TeX{}nical note: No chunk marker is created by redefining macro
% |\@svsechd| that creates header for run-in \LaTeX{} section. Every
% header is followed by 1\,em space, we have to annulate that skip.
% (The refinement shall start at the beginning of the line.) One must
% not use |\hskip| to backup, an |\unskip| comes after the header and
% would discard that skip.

\providecommand\cwebNoChunk{%
    \vskip -\lastskip  \bigskip		% discard LaTeX's inter-section skip
    \def\@svsechd{\kern -1em}%
    }




\catcode`\_=\CatUsCode
\endinput


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% $Log: cwebx.sty,v $
% Revision 3.1  1995/11/21  00:42:49  schrod
%     version 1.1
%



%%%------------------------------------------------------------

% Local Variables:
% mode: LaTeX
% TeX-brace-indent-level: 4
% indent-tabs-mode: t
% TeX-auto-untabify: nil
% page-delimiter: "^%%%"
% End: