summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cweb/src/cwebparts.doc
blob: 3eec51882b16f7e80ac69181110d24eaf6b21b6f (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
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
% $StyleId: cwebparts.doc,v 1.1 1995/09/16 17:01:59 schrod Exp $
%----------------------------------------------------------------------
% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>.
% Copyright conditions see below.

%
% LaTeX package cwebparts
% include parts of CWEB programs in LaTeX documents
%
% [LaTeX in MAKEPROG]
% (history at end)

%% FIXME: The user manual is not in cwebparts-user.tex. Most probably
%% I'll make one user manual for the whole bundle; due to the usage of
%% cwebbase class and package have lots in common.
%%
%% % If you have received this style file without the user manual (in the
%% % file cwebparts-user.tex or the respective DVI file), it's incomplete and
%% % near to useless. If it was given to you as something that you shall
%% % use as an author -- complain bitterly to your provider. You need the
%% % documentation and you have a right on it! (Below you can find info
%% % where to get the reference version.)




\documentclass{progltx}

\usepackage{cweb-doc}			% document-specific markup
\usepackage{fullpage}


\RCS $StyleRevision: 1.1 $
\RCS $StyleDate: 1995/09/16 17:01:59 $


\begin{document}


\title{The \texttt{cwebparts} Package\\
    {\large (Implementation)}%
    }
\author{%			% LaTeX does not discard unnecessary glue...
    Joachim Schrod%
    \thanks{%
	\protect\raggedright
	TU~Darmstadt, Computer Science Department, WG Systems Programming,
	Alexanderstr.~10, D-64283~Darmstadt, Germany.
	Email: \texttt{schrod@iti.informatik.th-darmstadt.de}.%
	}%
    }
\date{%
    Revision \RCSStyleRevision\\
    (as of \RCSStyleDate)%
    }

\maketitle


% doesn't work with progltx yet
%\tableofcontents



\chap What's this style for?.

This style supports inclusion of \cweb{} program parts in \LaTeX{}
documents. For that it provides the environment |cweb| where \cweave{}
output may be stuffed in.

A more versatile explanation is available in the user manual of the
\cweb{} bundle; this package is part of that bundle.
%
\begin{fixme}
  Read: ``should be available'' -- there is no bundle user manual
  (yet). |cweb-user.tex| will be enhanced after first testing of this
  code.
\end{fixme}


\sect The internal interface is also not described in this source,
refer to the configuration documentation for this bundle.
%
\begin{fixme}
  Even worse: I don't even have written the internal specs for the
  \cls{cweb} class, not to speak of this package.
\end{fixme}




\chap Implementation.

Most of the implementation is made available by the module
\pkg{cwebbase}. We have to supply macros it demands from a user, and
have to deliver the |cweb| environment.


\sect This module reserves the namespace |cweb|. (This implies that it
cannot be used with the \cls{cweb} class. But you don't want to do
that anyhow. :--)

\beginprog
\ifx \cweb@loaded\undefined
    \def\cweb@loaded{$StyleRevision: 1.1 $}
\else
    \PackageWarningNoLine{cwebparts}%
        {Some other package already uses namespace `cweb'}
\fi
\endprog


\sect Let's identify this package.

\noindent The code below is explained in the implementation
documentation of the |rcs| package.

\beginprog
\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{cwebparts}{include CWEB program parts in LaTeX documents}
  $StyleDate: 1995/09/16 17:01:59 $: 9999/00/00 \endRCS
  $StyleRevision: 1.1 $: 0.0 \endRCS
\endgroup
\endprog


\sect This module 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 September~13,~1995.
It might have changed, although this is very unlikely. Use your
friendly nameserver.)


\sect This is freely distributable software; you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version~2 of the
License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but
\textbf{without any warranty}; without even the implied warranty of
\textbf{merchantability} or \textbf{fitness for a particular purpose}.
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License in
the file |License| along with this package; if not, write to the Free
Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA.


\sect Before we start we declare some shorthands for category codes.
By declaring the underscore~`(|_|)' as letter we can use it in our
macros. (I agree with \textsc{D.~Knuth} that
|\identifier_several_words_long| is more readable than
|\IdentifierSeveralWordsLong| and in every case better than |\p@@@s|.)

As this is a \LaTeX{} style file the at sign is a letter anyhow; so
we can use the ``private'' \LaTeX{} macros; and with the underscore we
can make our own macros more readable.  But as we have to restore this
category code at the end of this macro file we store its former value
in the control sequence |\CatUsCode|. This method is better than to
use a group because not all macros have to be defined global this way.

Since somebody might use more styles from me, this cseqs might be
defined already.

\beginprog
\ifx \CatEscape\undefined
    \chardef\CatEscape=0
    \chardef\CatOpen=1
    \chardef\CatClose=2
    \chardef\CatIgnore=9
    \chardef\CatLetter=11
    \chardef\CatOther=12
    \chardef\CatActive=13		% is defined in Plain already

    \chardef\CatUsCode=\catcode`\_
\fi

\catcode`\_=\CatLetter			% top level macro file
\endprog




\chap Typesetting \cweave{} output.

The module \pkg{cwebbase} handles that. It demands some cseqs to be
defined before it may be imported.
%
\begin{fixme}
  These cseqs should actually be implemented as package options. Have
  to extract the \pkg{keyvalx} code from the \cls{cweb} class first.
  Now I fix the usage I need for our Literate Programming book.
\end{fixme}

\begin{fixme}
  The options should not only be available as package options, but
  also on a per environment base. We might to typeset one part with
  flat and another one with hierarchic structure. Or we might to
  suppress format directives only in some parts, while other parts
  feature them. But this needs a change in \pkg{cwebbase}, there code
  is \emph{defined} depending on the cseqs below. It must be evaluated
  differently to support the stuff below. OTOH, this will cost
  performance -- is it worth it?
\end{fixme}

\beginprog
\def\cweb@structure{0 }			% hierarchic structure
\let\if@cweb@suppress@changehints@=\iffalse % no suppression whatsoever
\let\if@cweb@suppress@unchanged@=\iffalse
\let\if@cweb@suppress@format@=\iffalse

\input{cwebbase}
\endprog


\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.

\beginprog
\def\CwebNoLists{%
    \let\addtocontents\@gobbletwo
    \let\mark\@gobble
%%    \let\markboth\@gobbletwo
%%    \let\markright\@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}

\beginprog
\let\CwebEjectSection\@gobble
\endprog


\sect OK, what needs to be done for 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

\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
    \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\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.

\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}%
    \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).

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


\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.

\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
\newcommand\cweb@doc_markup_gobble[2][]{}
\newcommand*\cwebInput[1]{%
    \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{\aftergroup\inx}%
	]%
      \input{#1}%
    \end{cweb}%
    }
\endprog




\chap The end.

Well, after all we're finished with this style. We must not forget to
restore the underscore catcode.

\beginprog
\catcode`\_=\CatUsCode

\endinput
\endprog


%\sect I would like to thank those who helped me to improve this style.
% In particular, XXX provided XXXsubstantial parts of the code.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{rcslog}
$StyleLog: cwebparts.doc,v $
\Revision 1.1 1995/09/16 17:01:59 schrod
Add support for inclusion of \cweb{} files in \LaTeX{} documents.

\end{rcslog}



\end{document}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Local Variables:
mode: LaTeX
TeX-brace-indent-level: 4
indent-tabs-mode: t
TeX-auto-untabify: nil
TeX-auto-regexp-list: LaTeX-auto-regexp-list
compile-command: "make cwebparts.sty"
End: