From Joachim Mon Jan 4 13:04:23 MEZ 1993
Date: Mon, 4 Jan 93 13:04:23 MEZ
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: VHDL Literate harware modeling ?
 
steve wrote:
>
> 	Of course, there is a small problem that I have with this.
> Normally I do my designs (VLSI that is), bottom up. A web, on the other
> hand, usually appears as a top down design.
 
It's often used so, but not necessarily. You can define program parts
before you use them. So a bottom-up design may be done as well,
without any loss.
    Actually, DEKs WEB programs (ie, WEB itself, TeX, METAFONT, etc.)
are an example of bottom-up design. I left it to the generous reader
to decide about the quality of this program design. ;-)
 
A happy and peaceful new year
 
    Joachim
 
From mcguire@cs.tamu.edu Mon Jan 4 14:34:31 CST 1993
Date: Mon, 4 Jan 93 14:34:31 CST
From: mcguire@cs.tamu.edu (Tim McGuire)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Literate Programming without TeX
 
Allen Holub's Arachne system is available from the author
(holub@violet.berkeley.edu) for a fee and runs on some kind of PC
system.  In his words (from a longer correspondence to me in June 1990):
 
  I wrote Arachne myself in order to write Compiler Design. It became
  clear as soon as I started that some sort of WEB-like preprocessor would be
  necessary for me to maintain my sanity, so I wrote a small one which has
  gradually expanded to a pretty powerful tool. I haven't written it up anywhere
  yet, however.
 
The language is C and the formatting language is troff.  It is not a derivative
of Thimbleby's cweb system; it was directly inspired by Knuth's original WEB.
My personal evaluation, based strictly on the Compiler Design book and
correspondence with Holub, is that Arachne does fit the literate paradigm.  In
general, it appears that Arachne encourages larger code modules than does WEB,
and thus the degree of code/documentation integration is not as high.
 
Comments from anyone who has used Arachne would be greatly appreciated.
 
Tim McGuire
mcguire@cs.tamu.edu
 
From gilligan@central.bldrdoc.gov Mon Jan 4 18:14:42 MST 1993
Date: Mon, 4 Jan 93 18:14:42 MST
From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: conditional processing and @d in CWEB
 
Here's an item for the wish list for a future release of CWEB:
 
I sometimes want to conditionally define a preprocessor macro that I
define with an @d in the definition block of a section.  I can work
around this problem by using change files or by moving the definition
to the C block of that section, but it would be nice to be able to
have a variant of @d that would allow me to conditionally define a
macro. I'd like to be able to write a web containing something like
 
@? if defined(TEST)
@d BAR foo
@? else
@d BAR fu
@? endif
 
(or something similar) and have it tangle into
 
#if defined(TEST)
#define BAR foo
#else
#define BAR fu
#endif
 
I know that I can just stuff my conditional definitions into the C
block of a section, but that's not always elegant, since I can have a
number of definitions that logically belong together in the definition
block of the section.
 
I'd like to know what other (more experienced) literate programmers
think. What would the preferred syntax be for such an extension?  Is
it better to leave CWEB as it now is and move my conditional
definitions or use change files (this gets annoying when there are
conditional definitions in an included file such as common.h)?  Is
there a better solution already out there or in the wings?
 
---Jon
 
Disclaimer --- The government probably disagrees with my opinions.
 
From Edward Mon Jan 04 21:13:39 EST 1993
Date: Mon, 04 Jan 1993 21:13:39 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Literate Programming
 
Why should I take the time to learn CWEB? What is the advantage of
literate programming over extensive commenting and good design in a
traditional language?
 
I do most of my work in C. I write short functions, each with a
descriptive header explaining what it does and how it does it. I
comment each of the parameters and all variables when they are
declared. I then run the code through a code formatter and cross
reference generator. I still find the code hard to read three months
later.
 
I read the article in the Jan. 1993 Computer Language, and have been
following this list for several weeks. I find the listings in CL and
posted here even harder to read than most C code (This is probably
because I have been reading C for eight years, and saw CWEB for the
first time last month).
 
In the article Silvio Levy says, "The gain in clarity obtained by
using Cweb over C should now be obvious." Maybe I'm a little slow.
Could someone please explain it to me?
 
	-Ed K.
 
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From mfy@sli.com Tue Jan 5 03:56:44 GMT 1993
Date: Tue, 5 Jan 93 03:56:44 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: conditional processing and @d in CWEB
 
Jonathan M. Gilligan wrote, as a prelude to a question:
 
>I sometimes want to conditionally define a preprocessor macro...
>... something like
>
>@? if defined(TEST)
>@d BAR foo
>@? else
>@d BAR fu
>@? endif
>
>(or something similar)...
 
I can't necessarily answer your question the way you would like, since I can't
read your mind from here; so I will just answer to what seems to be your
principal interest.
 
I use a processor in which every feature (with two very small exceptions) was
added only in response to a need, or at least a strong desire.  (The two
exceptions are underlining and overstriking of text.)  It still has no macro
processing; but conditionals were among the very first items implemented.
There are certainly a number of minor problems that could be solved well by
simple macros; but I'd advise a designer of such a tool to shy away from
elaborate macro processors.  Macros tend to be hard to debug; but besides this,
their presence tends to prevent simpler and better solutions from being
implemented when a clever but convoluted macro solution can be found.  (And
macro processors still tend to be slow.)  I do expect to eventually add macros,
but not soon.
 
I have some empirical evidence for this claim.  When I worked at Apollo (this
was before and during the merger with HP) I sent a survey to the users of this
tool: it was a list of possible new features plus a request to rate each one on
a scale of 0 to 10 for perceived usefulness.  I totaled the scores from each
response (there were 6 responses) to get an overall score, which I have used
since then to guide my implementation.  The scores fell into obvious groups:
0-1, 9, 17-19, etc. up to a high score of 39.  "Simple macros" was in the 0-1
group, which surprised me a great deal until I thought about it.
 
In the simplest case, your problem could be solved in Inscribe by writing
 
	@option bar = foo, fu;
	 ...
	@bar()
 
In more complex cases you would need to use @case(bar) ... @end-case(bar).
 
The history of this method might be of interest: Inscribe came into existence
to support an Ada compiler effort which started in 1983.  When first
implemented, there were just two commands, @case-host and @case-target: only
two options were allowed, and their names were "wired in."  At some point much
later, a third option became needed, and at that point it became clear that a
third special case (no pun intended) would be a bad idea.
 
I find the @case...@end-case construct (with what is essentially an enumeration
type as the selector type) much more natural than the rather stilted
conventions used in C preprocessor conditionals.  It is certainly less
error-prone: you cannot accidentally turn on two of the supposedly mutually
exclusive options, or leave them all turned off because the option you tried to
turn on didn't exist.
 
So: my recommendation to writers of literate programming tools is to implement
case statements as your primary mode of expressing conditionals in the program.
 
From mfy@sli.com Tue Jan 5 07:21:54 GMT 1993
Date: Tue, 5 Jan 93 07:21:54 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: mail without signature
 
My apologies for the mail message without a signature.
 
The reply to Jonathan Gilligan which talked about conditionals vs. macros was
mine.
 
	Michael F. Yoder [mfy@sli.com]
 
From Yves Tue Jan 5 16:31:59 +0100 1993
Date: Tue, 5 Jan 1993 16:31:59 +0100
From: Yves Arrouye <arrouye@aquilon.imag.fr>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: contacting the author of fweb
 
  Does anyone has the email of fweb's author?
 
  Thanks in advance.
 
--
Elle e'tait comme je vous la raconte sans que vous                 Yves Arrouye
  puissiez voir son visage ni entendre ses paroles,     arrouye@mistral.imag.fr
pas plus que je ne l'ai vu ni ne les ai entendues,         arrouye@imag.imag.fr
moi qui pourtant les ai si bien connus.                        (33) 76 57 48 61
 
From Edward Tue Jan 05 20:58:36 EST 1993
Date: Tue, 05 Jan 1993 20:58:36 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: lc++
 
Is anyone familiar with Macro S. Hyman's lc++? It was presented in the
July 1990 Computer Language and is written in Awk.
	-Ed K.
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From marcus@x4u.desy.de Wed Jan 6 09:12:47 +0100 1993
Date: Wed, 6 Jan 93 09:12:47 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: contacting the author of fweb
 
Yves>   Does anyone has the email of fweb's author?
 
  The author of FWEB is John A. Krommes <krommes@lyman.pppl.gov>.
  For FWEB, there is a list of Frequently Asked Questions (FAQ),too.
  The old version is at niord.shsu.edu in [FILESERV.FWEB].
  The next version of this FAQ (with many changes) will be posted
  to LitProg beginning of next week.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
From Yves Wed Jan 6 14:50:44 +0100 1993
Date: Wed, 6 Jan 1993 14:50:44 +0100
From: Yves Arrouye <arrouye@aquilon.imag.fr>
Reply-To: LitProg@SHSU.edu
To: Litprog@SHSU.edu
Subject: manrefs.tex for fweb 1.30 user's manual?
 
Hi,
 
I got the version 1.30 of fweb from lyman.pppl.gov but I can't find the
manrefs.tex file in order to print the manual... Does anybody know where I
can find it? (It seems to define \cite and other macros for TeX).
 
Yves.
 
--
Elle e'tait comme je vous la raconte sans que vous                 Yves Arrouye
  puissiez voir son visage ni entendre ses paroles,     arrouye@mistral.imag.fr
pas plus que je ne l'ai vu ni ne les ai entendues,         arrouye@imag.imag.fr
moi qui pourtant les ai si bien connus.                        (33) 76 57 48 61
 
From kml@ctrss1.lanl.gov Wed Jan 6 08:31:20 MST 1993
Date: Wed, 6 Jan 93 08:31:20 MST
From: kml@ctrss1.lanl.gov (Kuok Mee Ling)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  contacting the author of fweb
 
You can contact John Krommes at krommes@princeton.edu
 
From marcus@x4u.desy.de Wed Jan 6 16:33:23 +0100 1993
Date: Wed, 6 Jan 93 16:33:23 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: manrefs.tex for fweb 1.30 user's manual?
 
From the READ_ME file in:   /anonymous@lyman.pppl.gov:/pub/fweb:
 
-------------------------------------------------------------------
VERY IMPORTANT NOTICE (January 5, 1993):
 
  The directory /pub/fweb/v1.30 is NOT READY for release yet.  That will
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
happen in a few days.  Meanwhile, a few select people are testing it.
 
-------------------------------------------------------------------------------
 
Got it? Get the manual and all this from the directory "v1.23/manual"!
 
--Marcus Speh
--<marcus@x4u.desy.de>
 
From stevea@vast.unsw.edu.au Thu Jan 07 10:22:46 +1100 1993
Date: Thu, 07 Jan 93 10:22:46 +1100
From: stevea@vast.unsw.edu.au
Reply-To: LitProg@SHSU.edu
To: Literate Programming Mailing List <litprog@shsu.edu>
Subject: Comment on behaviour of weave
 
Hi all,
	This message is really intended just to solicit opinions on the
behaviour of weave (well cweave of both CWEB and Spidery WEB - others
may perform similarly though). At the moment, if I use the following
code:
 
	@ This is just an example.
 
		@<Type Definition@>=
		typedef ASCII char;
 
		@<Global Variable@>=
		ASCII letter;
 
It weaves to:
 
	1. This is just an example.
 
		<Type Definition>=
		typedef ASCII char;
		<Global Variable>=ASCII letter;
 
	This is not exactly how I want weave to behave, and my preferred
woven output should be obvious. This type of code also tangles to the
undesired output (although I must admit at least CWEB ctangle complains
- I'm not sure about Spider).
	Now for all I know, some people using weave might take advantage
of this "feature". What I would like to know is what output people
prefer: the current output, or my preferred output. If people don't
actually make use of this "feature", I'll probably hack around and try
to "fix" it.
 
	Any comments?
 
	cheers
	-steve
 
From Marty Wed Jan 6 18:00:30 PST 1993
Date: Wed, 6 Jan 1993 18:00:30 PST
From: "Marty Leisner" <leisner@eso.mc.xerox.com>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming
 
In message <2b48eedb.efkport@efkport.kew.com> you write:
>Why should I take the time to learn CWEB? What is the advantage of
>literate programming over extensive commenting and good design in a
>traditional language?
>
>I do most of my work in C. I write short functions, each with a
>descriptive header explaining what it does and how it does it. I
>comment each of the parameters and all variables when they are
>declared. I then run the code through a code formatter and cross
>reference generator. I still find the code hard to read three months
>later.
>
>
>In the article Silvio Levy says, "The gain in clarity obtained by
>using Cweb over C should now be obvious." Maybe I'm a little slow.
>Could someone please explain it to me?
>
>	-Ed K.
 
I'm not sure about the gain in clarity...I have no problem reading quality C code
months after the subject...
 
I generally don't use a formatter...I just follow formatting rules...
 
You really aren't supposed to look at the Webbed code (from what I've seen...you look at the
formatted comments, and the computer looks at the code...
 
I too am unsure whether its worth the time to learn and whether it improves readability
(although I think TeXinfo is a "good" think -- having the documentation on line and printed).
 
marty
leisner@eso.mc.xerox.com leisner.henr801c@xerox.com
Member of the League for Programming Freedom
"People cannot be managed.  Inventories can be managed, but people must be led"  -- H. Ross Perot
 
From bart@cs.tamu.edu Wed Jan 6 20:16:09 -0600 1993
Date: Wed, 6 Jan 93 20:16:09 -0600
From: bart@cs.tamu.edu
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Comment on behaviour of weave
 
I would prefer that it stop cold!  I think that only one
@<----@>=
should be allowed per section/module.
 
Bart Childs
 
From Timothy Wed Jan 6 20:16:09 -0600 1993
Date: Wed, 6 Jan 93 20:16:09 -0600
From: "Timothy Larkin" <Timothy_Larkin@qmrelay.mail.cornell.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Comment on behaviour o
 
        Reply to:   RE>> Comment on behaviour of
Bart Childs writes:
>I think that only one @<----@>=
>should be allowed per section/module.
in response to the observation of stevea@vast.unsw.edu.au that cweb doesn't
interpret correctly multiple @<----@>= per section.
 
I have found many instances in which it would be useful and logical to have
multiple code parts per section. For instance, I find that a code part often
consists of a function definition which tangles into @<functions@>. I would
like to include a prototype at that point in the web which would tangle into
@<prototypes@>. I can do this only by introducing a dummy section with an empty
TeX part, which offers no advantage to the reader or the writer. Again, I may
find it appropriate to introduce a global variable, destined for @<globals@>,
in the same section in which I define a function, destined for @<functions@>.
 
Granted, such a license might be abused. But web offsers as one of the primary
benefits to free the programmer from the arbitrary sequence of presentation
demanded by compilers, e.g. variables and functions need to be typed before
use. Thus in web, unlike C, rhetorical considerations determine the order of
presentation. In this spirit, it would be logical to allow additions to
multiple code parts within a single section if this localizes the presentation
of related elements which the C compiler requires to appear in unconnected
sections of the tangle.
 
Tim Larkin
tsl1@cornell.edu
 
From leew@cs.utexas.edu Thu Jan 7 10:13:56 -0600 1993
Date: Thu, 7 Jan 1993 10:13:56 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Comment on behaviour of weave
 
Steve Avery writes:
 
  > 	This message is really intended just to solicit opinions on the
  > behaviour of weave (well cweave of both CWEB and Spidery WEB - others
  > may perform similarly though). At the moment, if I use the following
  > code:
  >
  > 	@ This is just an example.
  >
  > 		@<Type Definition@>=
  > 		typedef ASCII char;
  >
  > 		@<Global Variable@>=
  > 		ASCII letter;
  >
  > It weaves to:
  >
  > 	1. This is just an example.
  >
  > 		<Type Definition>=
  > 		typedef ASCII char;
  > 		<Global Variable>=ASCII letter;
  >
  > 	This is not exactly how I want weave to behave, and my preferred
  > woven output should be obvious. This type of code also tangles to the
  > undesired output (although I must admit at least CWEB ctangle complains
  > - I'm not sure about Spider).
  > 	Now for all I know, some people using weave might take advantage
  > of this "feature". What I would like to know is what output people
  > prefer: the current output, or my preferred output. If people don't
  > actually make use of this "feature", I'll probably hack around and try
  > to "fix" it.
 
Aside from the fact that the typedef should be
 
	typedef char ASCII;
 
it's an interesting problem.  I use both Spidery WEB (which requires
another @<space> before the second named section definition) and NOWEB (which
doesn't).  I have to admit that, though I like being able to define a new
named section without having to remember about the @<space>, I think I
prefer it the way CWEB does it.  One section, one definition seems like the
right way to do things.
 
		-- Lee
 
From leew@cs.utexas.edu Thu Jan 7 10:46:52 -0600 1993
Date: Thu, 7 Jan 1993 10:46:52 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming
 
Edward F. Keith writes:
 
  > Why should I take the time to learn CWEB? What is the advantage of
  > literate programming over extensive commenting and good design in a
  > traditional language?
 
I can't speak for everyone, but there are 2 reasons why I switched to
literate programming from reasonably well commented, fairly clean code.
 
	1.  Maintenance.  Not only can I explain _why_ I'm doing something
	while I'm writing the code (these kind of explanations are not only
	awkward in normal programs, but often get in the way and
	overshadow the code), but I can also make little notes to myself
	about things that need to be changed, where an algorithm came from,
	etc (and put pointers to these notes in the index!).  The index of
	identifiers is invaluable in trying to figure out someone else's
	code.  In fact, my "Road to Damascus" came about when I was trying
	to get CWEB working on my PC.  There was an obscure bug involving
	pointer arithmetic in CWEAVE.  I spent a little over a week (during
	off-time at an ACM conference) poring over the woven listing, and
	found the bug.  I would have given up on a non-literate program of
	similar size (and have on several).
 
	2.  Structure.  Since TANGLE puts all the code sections in proper
	order, I can concentrate on writing the program in the order that I
	feel best for purposes of exposition.  I can write the program for
	human beings, rather than for the compiler (I think this is the
	most important point of all).  I can also modularize code
	without having to write a procedure (with its attendant overhead)
	by using a named section.\footnote{perhaps this is why Knuth used the
	term "module" in early versions}
 
In any event, I won't do without my literate programming tools.  I've
recently had to do some programming in PAL (Paradox Application Language).
When I discovered that Spidery WEB wasn't capable of dealing with PAL
(through not fault of its own -- PAL is fairly insane), I downloaded NOWEB,
adapted it to work under DOS (a rather painful process), and now use it for
all my PAL work.  Even the programmers in the office who do not use NOWEB
have no problems reading the woven listings.
 
Hope this goes a bit toward answering your question.  The best advice I can
give is: "Try it, you'll like it".
 
		-- Lee Wittenberg
 
From Roegel Thu Jan 7 18:06:13 +0100 1993
Date: Thu, 7 Jan 93 18:06:13 +0100
From: Roegel Denis <Denis.Roegel@loria.fr>
Reply-To: LitProg@SHSU.edu
To: LITPROG@SHSU.edu
Subject: bad CWEB formatting ?
 
Hello,
 
I am new to the list. I am just beginning to use CWEB and I have a formatting
problem.
 
Somewhere, I use a declaration like
 
  char line[100];
 
Ctangle gives me a correct C source that compiles without harm.
However, Cweave formats me line as if it was a type, and you can imagine
that the function where line is declared looks bad...
 
Of course, I know that line is defined in C (K&R), but the word is not
reserved. So, why does Cweave not understand ? Is there an other
solution than changing the name of my string ?
 
Thanks for your help.
 
Denis.
 
PS. I am running the TeX 3.14 distribution, etc.
 
From bart@cs.tamu.edu Thu Jan 7 12:22:24 -0600 1993
Date: Thu, 7 Jan 93 12:22:24 -0600
From: bart@cs.tamu.edu
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Defining multiple modules (sections) in one
 
I really don't consider it a big deal.  I don't see what is
wrong with
 
@ documentation
...
@<Something@>=
  stuff
 
@ @<Something else@>=
  more stuff
 
That extra `@ ' gives unique module identifiers to the index
entries in `Something' and `Something else'.  Tim's example
(Tim Larkin's response 7 Jan 93 -- 10:31 am) is one where this
is not much help.
 
I did a quick analysis of tex.web and find that Don Knuth had
505 occurrences of ``@ @<'' in tex.web and these reference
356 unique module names.  Most of these are quite readable and
this is due to the care he took in being consistent and descriptive
in the names.  They are not like `Something'.  Incidentally,
most came from `case' statements and only four of them were
`@ @<Global...'
 
The primary reason for my thinking simpler is better is much the
same as my understanding of the benefits of some of the
structured programming rules/slogans/...
1 return per function/subroutine/...
use only sequence, selection, and loop control structures
...
 
Again, it is not a big deal and simplicity and structure sure
offer lots of benefits.
 
Bart Childs
 
From mcguire@cs.tamu.edu Thu Jan 7 14:09:10 CST 1993
Date: Thu, 7 Jan 93 14:09:10 CST
From: mcguire@cs.tamu.edu (Tim McGuire)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Arachne (was: LitPgm w/o TeX)
 
I posted Allen Holub's e-mail address a few days ago in regard
to his Arachne system.  Apparently, you will get better response
if you contact him via phone or snail-mail.  I got the following
when fingering his account:
-------
[violet.berkeley.edu]
Login name: holub                       In real life: Allen Holub
 
You can also contact me C/O:    Software Engineering Consultants
                                PO Box 5679
                                Berkeley, CA 94705
                                telephone (415) 540-7954 (voice and FAX)
 
It's best to call if you post email to make sure that I log on and read it.
--------
 
Tim McGuire
mcguire@cs.tamu.edu
Institute for Scientific Computation
Texas A&M University
 
From stevea@vast.unsw.edu.au Fri Jan 08 10:16:04 +1100 1993
Date: Fri, 08 Jan 93 10:16:04 +1100
From: stevea@vast.unsw.edu.au
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Comment on behaviour of weave
 
Hi all,
	I seem to be getting all sorts of comments on this one, so I'll
field them all here rather than in separate messages. Be forewarned,
there's a bit of me standing on my soap-box here and expounding my
literate programming philosophy. Feel free to shoot holes in my
philosophy, but don't flame me for philosophising - you were warned.
 
	First up, Timothy Murphy <tim@maths.tcd.ie> sez:
 
  me> This is not exactly how I want weave to behave, and my preferred
  me> woven output should be obvious.
 
  tim> Not obvious to me.
 
	Okay, I should elaborate a bit. Timothy Larkin has provided a
much better example which I'll borrow (hope he doesn't mind).
	I'm frequently coding away, and come across a module/section
which would be much more readable if I were able to include two
@<section name@>= entries in it. Timothy's example would look like:
 
@*Read a String. This function....
 
	@<Functions@>=
	char *read_string()
	{
		.....
	}
 
	@<Prototypes@>=
	char *read_string();
 
This would weave to:
 
12. Read a String. This function...
 
<Functions>+=
char *read_string()
{
  .....
}
 
<Prototypes>+=
char *read_string();
 
Currently weave would produce:
 
12. Read a String. This function...
 
<Functions>+=
char *read_string()
{
  .....
}
<Prototypes> <- char *read_string();
 
	It makes a lot more sense to include the prototype in the same
section as the definition. However, at present, it is not possible to do
this with any of the weave's I've used (although Lee Wittenberg notes
that noweb will treat it as I would like it to).
	The current behaviour of weave is definitely undesirable. I
don't know how or why anyone would use a @<----@> section as part of an
expression when there is provision for defining macros.
	So, I believe it should be changed one way or the other. It
could either behave as I propose, or as preferred by Bart Childs
<bart@cs.tamu.edu>, who sez:
 
  bart> I would prefer that it stop cold!  I think that only one
  bart> @<----@>=
  bart> should be allowed per section/module.
 
	Lee Wittenberg also seems to agree with Bart's comments. Bart
goes on (in a later message), to suggest the preferred solution to the
problem should be:
 
@*Read a String. ...
 
@<Functions@>=
char *read_string()
...
 
@ @<Prototypes@>=
char *read_string();
 
	This uses an unnamed section to provide the extra chunk of code.
Bart sez:
 
  bart> That extra `@ ' gives unique module identifiers to the index
  bart> entries in `Something' and `Something else'.  Tim's example (Tim
  bart> Larkin's response 7 Jan 93 -- 10:31 am) is one where this is not
  bart> much help.
 
	I believe that there must be many other cases where the extra
section identifier is not of that much use. Bart goes on to cite
examples from tex.web by Knuth, where there are some 505 unnamed
sections with no textual explanation which reference 356 unique section
names.
	I'll go out on a limb here and say I don't much like Knuth's
code. This is not so much due to the code itself, but more the
restrictions placed on it by the original WEB. The code is very flat, as
WEB does not make much provision for any notion of a program hierarchy.
	I code pretty much the way I was originally taught - top-down,
decomposing the original problem into sub-problems, which are then
further decomposed. This leads to the idea of a program hierarchy. But
the original WEB only supported two levels of such an hierarchy, named
and unnamed sections. This restriction in turn tends to lead to flat
code, or at least code with no apparent hierarchy.
	If you look at Spider of FWEB (I believe) on the other hand,
they support seven levels of a hierarchy (@*=,@*,@*1-@*4,@ ), which
leads to a more intuitive programming style. (I still find this
restrictive, however, and have modified spider and cweb to provide
arbitrarily deep sectioning, but thats another story.) This idea of a
hierarchy is also in keeping with the idea of the literacy of a program
- how many of you would prefer a book with only paragraphs and rare
chapters as opposed to everything down to paragraph marks?
	Okay, next programming philosophy, I never use unnamed sections
- I find doing so counterproductive. The table of contents produced by
spider has the module names indented according to their level in the
program hierarchy, making it easy to work out what needs to be done
next, what's missing, the significance of a bit of code, etc.
	And now my final piece of programming philosophy, I always
include some description of the code in a section. This makes
maintenance easier, and enhances the overall readability of a program.
	Now, given my programming philosophy, it should become apparent
that using an unnamed section with no description is a big no-no for me,
which is why I would prefer to be able to have multiple sections of code
in a section.
	Anyhow, I'm probably beginning to babble, so I'll wind up here
with a suggestion: either way, the current behaviour of weave should be
ammended to either complain about multiple @<---@>= in a section, or to
weave/tangle it as I have suggested.
	Votes? I'd like to hear the opinions of those who maintain WEB
tools as the decision effectively remains up to them :-)
 
	cheers
	-steve
 
From mfy@sli.com Fri Jan 8 01:28:49 GMT 1993
Date: Fri, 8 Jan 93 01:28:49 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: benefits of Literate Programming
 
My experience with Literate Programming has given me a different slant on the
issue than most people have; I think the principal benefit is not so much that
you get good documentation (you don't always) but that you get correct
documentation.  I don't mean user manuals, which are generally correct but
irritatingly ambiguous due to the nature of natural languages: I am referring
to documents that purport to describe what a program's data structures and
algorithms are.
 
Without LP, my experience says that for programs longer than, say, ten pages of
code, the odds that such a document will be correct are zero.  I'm not being
ironic or exaggerating: I have literally never seen documentation in such cases
that was useful.  In most cases, either the documentation was written before
the program was (and never updated), or it was written just afterward and a
very incomplete job was done.  I particularly remember one document describing
a compiler IL that had quite correct detail about the tree portion of the IL,
but was sketchy on the leaf nodes and had virtually nothing on the symbol
table.  It isn't all that helpful to be told that the tree node representing
binary plus has two sons; you could have surmised that.  But this was the
easiest part of the documentation to write, and the writer was probably under
heavy time pressure and trying to get as much down as possible.
 
It is possible, of course, to work with the program directly, but this changes
maintenance from a science to an art.  This is not intrinsically bad, unless
human lives are involved.  But in any large program where no "big picture"
exists, fixing a bug consists of finding a likely-looking spot and changing it
to what feels right in the hopes that it *is* right.  If it doesn't work, you
repeat the process.  It would be better to *know* that such-and-such a routine
is supposed to deal with all comments, or macro expansions, or whatever,
because this can reduce the amount of code you must examine by an order of
magnitude or more.
 
Documents get out of date because they are separated from the source, and so
producing them in addition to the program becomes a two-pass process.  Besides
this, the documentation need not have any obvious 1-1 relationship to the
program; so it may be a nontrivial task just to determine what parts of the
documentation need to change after the program is modified.  No wonder that
most programmers take the easy way out and put off fixing the documentation
forever.
 
Why literate programming fixes this is partly obvious and partly due to
psychological effects I do not claim to understand.  It should be clear,
though, that when the documentation you must change is at most an editor screen
or so away from your program text, there is much less of a psychological
barrier to your changing it at the same time as the program.
 
There is one other obvious reason that LP helps: it makes the documentation and
program be done at the same time.  Once the program works, very few managers
*or* programmers are all that keen on spending several weeks producing quality
documentation; there's always other ways to spend this time that look more
attractive--such as doing firefighting on the project that's behind.
 
	Michael F. Yoder [mfy@sli.com]
 
From leew@cs.utexas.edu Fri Jan 8 15:02:53 -0600 1993
Date: Fri, 8 Jan 1993 15:02:53 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Defining multiple modules (sections) in one
 
Another point to add to the growing discussion:  It's a lot harder for
WEB to parse multiple section definitions together than to insist on separate
sections separated by @*'s and @ 's.  There's no way to tell (until the =
is reached) whether it's looking at a section definition or use.  Also, what
will WEB do with:
 
	x = @<Something that evaluates to an lvalue@> = 0;
 
or
 
	if (@<Something interesting@> == 18)
 
or other similar examples?  Both of these (slightly contrived, but similar
to code I have seen) would tangle _and_ weave to something unintended if we
allow multiple code definitions in a section.
 
NOWEB deals with this problem by requiring section definitions to start at
the beginning of a line.  It's really too late to require something like
that of WEB, CWEB, and the other tools that ignore spaces.
 
		-- Lee
 
From leew@cs.utexas.edu Fri Jan 8 15:12:22 -0600 1993
Date: Fri, 8 Jan 1993 15:12:22 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: bad CWEB formatting ?
 
Denis R. writes:
 
  > Somewhere, I use a declaration like
  >
  >   char line[100];
  >
  > Ctangle gives me a correct C source that compiles without harm.
  > However, Cweave formats me line as if it was a type, and you can imagine
  > that the function where line is declared looks bad...
  >
  > Of course, I know that line is defined in C (K&R), but the word is not
  > reserved. So, why does Cweave not understand ? Is there an other
  > solution than changing the name of my string ?
 
CWEAVE treats a number of non-reserved words (like line, ifdef, NULL) as if
they were reserved for simplicity.  Most C programmers do not redefine
these in their programs.  "line" is a bit of a problem, though.  It is a
natural for variable names.  The way around this problem is with the
following WEB code in the definition part of a section (assuming that you
never use a #line directive in your code):
 
	@f line x
 
This will treat "line" as if it were an identifier, which is what you want.
It also has the added advantage of documenting the fact that you are using
a standard identifier in a non-standard way.
 
Hope this helps.
 
	-- Lee
 
From gcrc!spinosaj@riscsm.scripps.edu Fri Jan 8 15:27:16 PST 1993
Date: Fri, 8 Jan 93 15:27:16 PST
From: gcrc!spinosaj@riscsm.scripps.edu (John Spinosa/MS219 4-9937)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: faq existence?
 
Is there an faq available concerning the different flavors of web (ie,
spidery web, cweb, etc) and what systems that they run on?  Also, is
there some sort of intro paper, book, etc. about literate programming for
a novice such as myself?  I'll summarize any the responses that I receive.
 
Thanks in advance
 
John Spinosa spinosaj@riscsm.scripps.edu
 
From Timothy Sat Jan 9 1:26:33 GMT 1993
Date: Sat, 9 Jan 93 1:26:33 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Brief communication from a bigot
 
I believe in C++.
I believe in LaTeX.
It has been revealed to me that I am right.
(It's such a relief to be certain about everything.)
 
It follows that the only True Web is CWEB++
producing LaTeX rather than TeX.
 
Unless Literate Programmers see the light,
WEB will be utterly swept away,
and entropy will at last attain its maximum.
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From plyon@emx.cc.utexas.edu Fri Jan 8 22:27:15 -0600 1993
Date: Fri, 8 Jan 93 22:27:15 -0600
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Defining multiple modules (sections) in one
 
Lee Wittenberg writes:
 
> NOWEB deals with this problem by requiring section definitions to start at
> the beginning of a line.  It's really too late to require something like
> that of WEB, CWEB, and the other tools that ignore spaces.
 
A better way of dealing with this is the method adopted in Ross
William's FunnelWeb programme. There are two parts to it.  The first
is to require that code sections be enclosed in an explicit pair of
delimiters, namely an opening `@{' and a closing `@}', and the second
is the requirement that any code section definition must begin with
one of two directives, either `@$' (an ordinary section definition) or
`@O' (a section defining an output file). Thus, a code section
definition looks like this:
 
   @$@<The name of the section@>==@{
   .....  code ....
   @}
 
If the code section may be unused, one puts `@>@Z==@{' at the end
instead of `@>==@{' (otherwise the programme complains about a section
defined but not used, and this does count as a syntax error), and if
it is to be invoked more than once, one puts `@>@M==@{' in place of
`@>==@{', lest FunnelWeb refuse to tangle or weave it. Finally, if the
section is to be incrementally defined one writes `+=@{' in place of
`==@{', and it is deemed an error to mix the two.
 
None of the options apply to output file definitions; these cannot be
incrementally defined, nor, sensibly enough, can one use the `@M'
modifier. So it will look like this:
 
   @O@<my_header.h@>==@{
   #ifdef _MY_HEADER_H
   #define _MY_HEADER_H 1
    ....  the contents ....
   #endif
   @}
 
Here, of course, the contents will mostly be code section invocations
for the function prototypes, data structures or class definitions,
and so on.
 
Now such definitions are definitely harder to type, and Funnelweb's
fussiness about the syntax is a nuisance, at least at first, but it
does allow multiple section definitions following explanatory text,
and thus a more free form source file, and the tighter error checking
does cut down somewhat on errors in writing the source.
 
The major disadvantage I see is related to the one mentioned by Bart
Childs, namely that allowing multiple code sections together with one
TeX section complicates the indexing of identifiers, both in terms of
the programming but, more importantly, in terms of the ease of finding
things using the index entries. This is not an issue in FunnelWeb as
it stands, because it is not language specific, so there is no
provision for identifier indexing. It would, however, be a problem if
one attempted to adapt the FunnelWeb scheme to a Web system with a
pretty printing parser of the kind in Cweb, Spiderweb, or Fweb.
 
For, we break the relationship between the numbering of the Web
sections (a stretch of exposition followed by one or more code
sections) and the numbering of the code sections. Now Williams dealt
with this by the simple expedient of not numbering the explanatory
text at all; only the code sections bear numbers, and they are only
cross-referenced for definition and use with respect to each other.
The organization of the exposition is entrusted to a hierarchy
of section headings which get ``mil spec'' numbering ('1.2.1' for
a sub-sub-heading, for example).
 
But if we do have an identifier (and ``control text'') index, and we
allow, as seems proper, that an index entry can reference occurrences
in the expository text (as `|identifier|' or by an explicit `@^', `@.'
or `@:' directive for control text) as well as ones in the code, then
we will need somehow to be able to direct the reader to the proper
place. But if text passage number 33 is associated with code sections
numbered 49--51, there is still apt to be confusion, even if we find a
typographically satisfactory way to distinguish a text passage
reference from a code section reference (say `T33' versus `C50' for
one unimaginative approach that might nonetheless work). Further, I am
assuming that we index things in macro definitions by reference to the
text passage immediately preceeding, but I suppose we could always add
a third number scheme... (Or, bite the bullet and convert to page
number index entries rather than section numbers for some or all of
this.)
 
[Aside, in FunnelWeb, there is no difference between macros and code
sections: ``code section'' names can have parameter lists. The syntax
is clumsy at best, and I have found little use for it. Williams made
many sensible design decisions, but I would not number this one among
them.]
 
For my part, I think the complexities of the indexing scheme are not a
decisive objection, but I suspect others will not agree.
 
Ciao,
 
Paul Lyon
 
From plyon@emx.cc.utexas.edu Fri Jan 8 22:27:15 -0600 1993
Date: Fri, 8 Jan 93 22:27:15 -0600
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Defining multiple modules (sections) in one
 
Lee Wittenberg writes:
 
> NOWEB deals with this problem by requiring section definitions to start at
> the beginning of a line.  It's really too late to require something like
> that of WEB, CWEB, and the other tools that ignore spaces.
 
A better way of dealing with this is the method adopted in Ross
William's FunnelWeb programme. There are two parts to it.  The first
is to require that code sections be enclosed in an explicit pair of
delimiters, namely an opening `@{' and a closing `@}', and the second
is the requirement that any code section definition must begin with
one of two directives, either `@$' (an ordinary section definition) or
`@O' (a section defining an output file). Thus, a code section
definition looks like this:
 
   @$@<The name of the section@>==@{
   .....  code ....
   @}
 
If the code section may be unused, one puts `@>@Z==@{' at the end
instead of `@>==@{' (otherwise the programme complains about a section
defined but not used, and this does count as a syntax error), and if
it is to be invoked more than once, one puts `@>@M==@{' in place of
`@>==@{', lest FunnelWeb refuse to tangle or weave it. Finally, if the
section is to be incrementally defined one writes `+=@{' in place of
`==@{', and it is deemed an error to mix the two.
 
None of the options apply to output file definitions; these cannot be
incrementally defined, nor, sensibly enough, can one use the `@M'
modifier. So it will look like this:
 
   @O@<my_header.h@>==@{
   #ifdef _MY_HEADER_H
   #define _MY_HEADER_H 1
    ....  the contents ....
   #endif
   @}
 
Here, of course, the contents will mostly be code section invocations
for the function prototypes, data structures or class definitions,
and so on.
 
Now such definitions are definitely harder to type, and Funnelweb's
fussiness about the syntax is a nuisance, at least at first, but it
does allow multiple section definitions following explanatory text,
and thus a more free form source file, and the tighter error checking
does cut down somewhat on errors in writing the source.
 
The major disadvantage I see is related to the one mentioned by Bart
Childs, namely that allowing multiple code sections together with one
TeX section complicates the indexing of identifiers, both in terms of
the programming but, more importantly, in terms of the ease of finding
things using the index entries. This is not an issue in FunnelWeb as
it stands, because it is not language specific, so there is no
provision for identifier indexing. It would, however, be a problem if
one attempted to adapt the FunnelWeb scheme to a Web system with a
pretty printing parser of the kind in Cweb, Spiderweb, or Fweb.
 
For, we break the relationship between the numbering of the Web
sections (a stretch of exposition followed by one or more code
sections) and the numbering of the code sections. Now Williams dealt
with this by the simple expedient of not numbering the explanatory
text at all; only the code sections bear numbers, and they are only
cross-referenced for definition and use with respect to each other.
The organization of the exposition is entrusted to a hierarchy
of section headings which get ``mil spec'' numbering ('1.2.1' for
a sub-sub-heading, for example).
 
But if we do have an identifier (and ``control text'') index, and we
allow, as seems proper, that an index entry can reference occurrences
in the expository text (as `|identifier|' or by an explicit `@^', `@.'
or `@:' directive for control text) as well as ones in the code, then
we will need somehow to be able to direct the reader to the proper
place. But if text passage number 33 is associated with code sections
numbered 49--51, there is still apt to be confusion, even if we find a
typographically satisfactory way to distinguish a text passage
reference from a code section reference (say `T33' versus `C50' for
one unimaginative approach that might nonetheless work). Further, I am
assuming that we index things in macro definitions by reference to the
text passage immediately preceeding, but I suppose we could always add
a third number scheme... (Or, bite the bullet and convert to page
number index entries rather than section numbers for some or all of
this.)
 
[Aside, in FunnelWeb, there is no difference between macros and code
sections: ``code section'' names can have parameter lists. The syntax
is clumsy at best, and I have found little use for it. Williams made
many sensible design decisions, but I would not number this one among
them.]
 
For my part, I think the complexities of the indexing scheme are not a
decisive objection, but I suspect others will not agree.
 
Ciao,
 
Paul Lyon
 
From plyon@emx.cc.utexas.edu Fri Jan 8 22:40:48 -0600 1993
Date: Fri, 8 Jan 93 22:40:48 -0600
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Brief communication from a bigot
 
Timothy Murphy writes:
 
> It follows that the only True Web is CWEB++
> producing LaTeX rather than TeX.
 
Actually it would have to be a gcc-web, using plain TeX, augmented
with something along the lines of Karl Berry's eplain package,
together with, say, PiCTeX, and maybe the table macros from TeXsis,
as well as any other useful bits that come to mind...
 
Then again, Fweb does do C++, and works with LaTex, so perhaps
Murphy's millenium is almost here...
 
Ciao,
 
Paul Lyon
 
From plyon@emx.cc.utexas.edu Fri Jan 8 22:40:48 -0600 1993
Date: Fri, 8 Jan 93 22:40:48 -0600
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Brief communication from a bigot
 
Timothy Murphy writes:
 
> It follows that the only True Web is CWEB++
> producing LaTeX rather than TeX.
 
Actually it would have to be a gcc-web, using plain TeX, augmented
with something along the lines of Karl Berry's eplain package,
together with, say, PiCTeX, and maybe the table macros from TeXsis,
as well as any other useful bits that come to mind...
 
Then again, Fweb does do C++, and works with LaTex, so perhaps
Murphy's millenium is almost here...
 
Ciao,
 
Paul Lyon
 
From marcus@x4u.desy.de Sat Jan 9 11:11:43 +0100 1993
Date: Sat, 9 Jan 93 11:11:43 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: faq existence?
 
>>>>> On Fri, 8 Jan 93 15:27:16 PST, (John Spinosa/MS219 4-9937) said:
 
> Is there an faq available concerning the different flavors of web (ie,
> spidery web, cweb, etc) and what systems that they run on?  Also, is
> there some sort of intro paper, book, etc. about literate programming for
> a novice such as myself?  I'll summarize any the responses that I receive.
 
  There is justified hope that the upcoming General FAQ
  for LitProg (not expected before February) will collect
  related information and provide pointers to other sources
  of information (care to comment, David?).
    The other existing FAQ for LitProg for FWEB (which inspite of
  its name is not a WEB for Fortran only, but also for ratfor, C, C++,
  TeX, running on a variety of systems, from a PC to the CRAY)
  gives a pointer to CWEB vs. FWEB (this will be merged into the
  FAQ for the 03-92 issue) and reflects a discussion on Funnelweb vs.
  FWEB (based on a posting by Paul Lyon).
    I will post a detailed announcement and the fweb-faq's text
  version next week -- please wait (GDG: got my mail?).
 
  And who's volunteering for the CWEB FAQ ? The longer you wait,
  the harder it will be to scan the wealth of information buried
  deep in LitProg's archives, IMO.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
From Klaus Sun Jan 10 21:40:41 GMT 1993
Date: Sun, 10 Jan 93 21:40:41 GMT
From: Klaus Elsbernd <elsbernd@dfki.uni-kl.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  bad CWEB formatting ?
 
Lee Wittenberg writes:
 
>  > Somewhere, I use a declaration like
>  >
>  >   char line[100];
>  >
>  > Ctangle gives me a correct C source that compiles without harm.
>  > However, Cweave formats me line as if it was a type, and you can imagine
>  > that the function where line is declared looks bad...
>  >
>  > Of course, I know that line is defined in C (K&R), but the word is not
>  > reserved. So, why does Cweave not understand ? Is there an other
>  > solution than changing the name of my string ?
>
>CWEAVE treats a number of non-reserved words (like line, ifdef, NULL) as if
>they were reserved for simplicity.  Most C programmers do not redefine
>these in their programs.  "line" is a bit of a problem, though.  It is a
>natural for variable names.  The way around this problem is with the
>following WEB code in the definition part of a section (assuming that you
>never use a #line directive in your code):
>
>        @f line x
>
>This will treat "line" as if it were an identifier, which is what you want.
>It also has the added advantage of documenting the fact that you are using
>a standard identifier in a non-standard way.
>
 
This mentioned problem is not only true if you use non-reserved words like
|line| as identifiers. I detected this problem in the following code
fragment too:
 
@<Typedef...@>=
struct g_process {
        int socket;
        struct msgh *msgh;
        char *buf;
        char owner[10];         /* user-id des Benutzers */
        time_t connect_time;
        time_t access_time;
        time_t give_ivory_time;
#ifdef DAEMON
        Board *p_board; /* ein zum \gproc-Proze\"s geh\"orendes board */
       struct g_process *next_g_process;
#else
        int pid;        /* process-id of a called process executing genera */
#endif /* DAEMON */
};
 
typedef struct g_process G_Process;
 
The code formats to
<Typedef declarations > =
 struct g_process {int socket;
   struct msg *msgh;
   ...
#ifdef DAEMON
   ...
#endif
 }; typedef struct g_process G_Process;
 
The solution is the same; I inserted
@f G_Process int
and CWEAVE did the right thing (insert a newline after the structure
definition). I hope I made it right and served not the symptom.
 
MfG
Klaus Elsbernd
 
From stevea@vast.unsw.edu.au Mon Jan 11 16:20:52 +1100 1993
Date: Mon, 11 Jan 93 16:20:52 +1100
From: stevea@vast.unsw.edu.au
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Defining multiple modules (sections) in one
 
leew@cs.utexas.edu (Lee Wittenberg) sez:
 
  leew> Another point to add to the growing discussion: It's a lot
  leew> harder for WEB to parse multiple section definitions together
  leew> than to insist on separate sections separated by @*'s and @ 's.
  leew> There's no way to tell (until the = is reached) whether it's
  leew> looking at a section definition or use.  Also, what will WEB do
  leew> with:
  leew> 	x = @<Something that evaluates to an lvalue@> = 0;
 
	Okay, my two bits worth (again) - this is not a very good
example of literate programming (imho of course). I was under the
impression that this sort of code is best handled by the @d mechanism
which web provides. I would even be quite suprised if weave was able to
handle this sort of code, as I am sure it would have difficulty parsing
a section which did not contain complete statements.
 
  leew> NOWEB deals with this problem by requiring section definitions
  leew> to start at the beginning of a line.  It's really too late to
  leew> require something like that of WEB, CWEB, and the other tools
  leew> that ignore spaces.
 
	I'm sure there's a way to do it if we know that @>= ALWAYS means
you are defining the code in a new section.
 
	cheers
	-steve
 
From stevea@vast.unsw.edu.au Mon Jan 11 16:38:02 +1100 1993
Date: Mon, 11 Jan 93 16:38:02 +1100
From: stevea@vast.unsw.edu.au
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Defining multiple modules (sections) in one
 
Hi all,
	Paul Lyon brings up a good point (which he attributes to Bart
Childs), which I must of missed some how, and that is about the problem
with indexing. This is obviously a fairly big problem, seeing as without
a sensible indexing scheme, maintenance of a WEB would soon become an
impossibility.
	However, I believe it is one that may be readily solved. If it
is made clear that having two code sections in one TeX section is to be
an exception rather than the rule, some sort of scheme where the index
numbers become 13a and 13b for section 13 could be used. This is a
fairly easy index to use (although it might be a pain to generate in a
one pass system), and saves the ugly T13, C24 type idea (although this
would also work).
	I don't like the idea of a purely page oriented scheme for the
index (although it would make it easier to find the page in a hurry, it
may be difficult to find the piece of code), and reckon that my proposed
scheme would not separate the notion of code and text.
	I'm sure everyone is familiar with this sort of scheme for
citations (how many people have multiple Knuth citations from the same
year in their bibliographies :-)), and is fairly intuitive.
	Of course, if it is decided to limit one code section to ever
TeX section, then the problem disappears pretty quick :-)
 
	cheers
	-steve
 
From marcus@x4u.desy.de Mon Jan 11 11:04:43 +0100 1993
Date: Mon, 11 Jan 93 11:04:43 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: Literate Programmers <litprog@shsu.edu>
Subject: Announcement: fweb-faq [01-93] updated
 
   /////////////////////////////////////////////////////////////////
            Another issue of the LitProg FAQ for FWEB is finished.
    Its text version will follow in a separate posting to LitProg.
 
        How to get the fweb-faq file(s):
        --------------------------------
        Retrieve them via anonymous FTP from the following sites
 
        Name:      niord.shsu.edu   [official FWEB FAQ host]
        Address:   192.92.115.8
        Directory: [FILESERV.FWEB]
 
        Name:      verdi.imada.ou.dk
        Address:   129.142.128.14
        Directory: pub/faq
 
        Name:      ftp.uni-stuttgart.de
        Address:   130.83.55.75
        Directory: pub/soft/tex/web/fweb/FAQ
 
        Name:      lyman.pppl.gov    [official FWEB host]
        Address:   192.55.106.129
        Directory: pub/fweb/faq
 
        To retrieve the (text) file via e-mail, include:
         SENDME FAQ.FWEB
        in the body of a mail message to FILESERV@SHSU.BITNET
        (FILESERV@SHSU.edu). To retrieve the full family of files
        (< 500 KByte), include SENDME FAQ.FWEB* instead.
 
       [At Niord and Verdi, it may take another day or two to get
        the files installed.]
 
        Changes for this issue of the fweb-faq:
        ---------------------------------------
           FWEB-related [and some general] postings from
        October--December 1992 were used for this update.
 
           The form of the fweb-faq changed in several respects.
        The principal source file is still written in Texinfo.
        The distribution now has a very simple Makefile for processing
        that source. I added version 2.90 of the macro file "texinfo.tex"
        which allows you to run plain TeX on the Texinfo source to obtain
        a DVI file (without index). A DVI file and a Postscript file
        (with index) are still included to satisfy everybody's needs.
        [Texinfo.tex can be retrieved from FILESERV as well---
         GDG will tell you how, I assume.]
 
        For more details, please look into the file "README.fweb-faq"
        and the Makefile of the distribution. Mainly as a result of the
        confusion which arose on the list after a premature discussion
        on the form of the FAQ file (my fault), I tried to improve on
        the description. Some Texinfo errors were corrected as well.
 
        The total size of the distribution is about 500 KBytes.
        Not because the FAQ is that big, but because of the support
        for different versions. If you think that is bad, flame me.
        I do find Texinfo a most convenient tool for the needs of a
        maximum number of readers---and I enjoy using it.
 
        Please note that a General LitProg FAQ by David B. Thompson
        is being worked on, thus reducing the the size of the fweb-faq.
        If possible, we will alternate with updates of these two faqs in
        intervals of 2--3 months. Related items were marked accordingly.
 
        Future FAQ author...
        --------------------
        ...If you want to use "fweb-faq.texi" as a template for your
        own principal FAQ source file, please do so. I would also like
        to hear about your experiences, in that case.
           Another FAQ for CWEB seems highly desirable, considering the
        relatively poor documentation (the FWEB User's Manual is so
        complete that it doesn't really need a FAQ, in FAQt). Also,
        the longer you wait volunteering for it, the harder it will be
        to scan the wealth of information buried deep in LitProg's archive
        files, IMO.
 
        Thanks to...
        ------------
         ...many readers whose suggestions were very helpful. I am
        especially grateful to John Krommes [designer of FWEB] for
        checking the final draft of the faq list, and to Bart Childs
        [co-designer and maintainer of the Emacs web-mode] for detailed
        comments on the previous issue and a pre-release of GNU Emacs'
        web-mode version 1.61. Thanks also to George Greenwade ["GDG",
        maintainer of FILESERV and LitProg] for support in all stages
        of the project.
 
        All kinds of comments, flames, suggestions will be appreciated.
 
        I hope you'll enjoy reading,
        --Marcus Speh
        --<marcus@x4u.desy.de>
 
       ////////////////////////////////////////////////////////////////
      //   marcus@x4u.desy.de     //  Marcus Speh                   //
     //  [131.169.30.33]         //  II. Institut f. Theor. Physik //
    // Phone: (040)8998-2260    //  Luruper Chaussee 149          //
   // FAX:   (040)8998-2267    //  2000 Hamburg 50 / Germany     //
  ////////////////////////////////////////////////////////////////
 
From marcus@x4u.desy.de Mon Jan 11 11:10:47 +0100 1993
Date: Mon, 11 Jan 93 11:10:47 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: Literate Programmers <litprog@shsu.edu>
Subject: fweb faq list [01-93]---text version
 
 This is text file `fweb-faq', produced by GNU Makeinfo-1.49 from
 the Texinfo file `fweb-faq.texi'.
 
>> To see the questions, display lines matching the regexp "^\[[1-9]" <<
>> To see the index,     display lines matching the regexp "^\* "     <<
>> To see a related question, follow the reference after "*note...:"  <<
 
   /////////////////////////////////////////////////////////////////////
  //            FWEB in Questions and Answers (01/93)                //
 /////////////////////////////////////////////////////////////////////
 
[last updated 5 Jan 1993]
 
[Send comments to: Marcus Speh, marcus@x4u.desy.de]
 
   This article contains frequently asked questions and their answers
concerning the FWEB system of "Literate Programming" from the "LitProg"
mailing list, until January 1993.
 
   Most of the answers are taken from the postings, with little
moderation from my side. The original postings are archived at
`niord.shsu.edu' in directory `[FILESERV.LITPROG]'.
 
   Comments, corrections and suggestions from several people were used
to improve single questions and answers (*note Acknowledgements::.).
Most notably, John Krommes, FWEB's designer, provided a wealth of
useful comments. I have dubbed him "JAK" in some places.
Inside quotes, my own comments are marked "[... -MS]".
Sections of the FWEB User's Manual are referred to by their section
numbers, as in "[M-10.2]" (*note What is the difference between the FAQ
and the manual?: Question 5.).
 
Introduction and Editorial
***************************
 
[1] What is FWEB?
 
   For a thorough discussion of the WEB system, I refer to the
extensive literature, collected in Nelson Beebe's bibliography (at
`ftp.math.utah.edu' in directory `pub/tex/bib'). For pointers, see the
upcoming "General FAQ" by Dave Thompson.
 
The WEB system.
---------------
 
   In D.E. Knuth's [author of the original WEB, coauthor of CWEB] own
words, [M-2.4]
 
   "The philosophy behind WEB is that an experienced system programmer,
who wants to provide the best possible documentation of his or her
software products, needs two things simultaneously: a language like TeX
for formatting, and a language like C for programming.
Neither type of language can provide the best documentation by itself;
but when both are appropriately combined, we obtain a system that is
much more useful than either language separately.
 
   The structure of a software program may be thought of as a "web"
that is made up of many interconnected pieces. To document such a
program we want to explain each individual part of the web and how it
relates to its neighbours. The typographic tools provided by TeX (1)
give us an opportunity to explain the local structure of each part by
making that structure visible, and the programming tools provided by
languages such as C or Fortran make it possible for us to specify the
algorithms formally and unambigously. By combining the two, we can
develop a style of programming that maximizes our ability to perceive
the structure of a complex piece of software, and at the same time the
documented programs can be mechanically translated into a working
software system that matches the documentation."
 
FWEB - a multilingual WEB variant.
----------------------------------
 
   FWEB which is being supported and upgraded by John Krommes is a
substantial extension of CWEB, FWEB supports C, C++, Fortran,
Fortran90, Ratfor, and TeX i.e. writing TeX macros (style files). It
runs on most platforms: VMS, PC, UNIX, and pretty much anything that
the GNU C compiler (GCC) is supported for.
 
   JAK [M-1]:
 
   "The principal design contributions to this version of WEB are
  1. the concept of a current language, so that one can process code
     written in multiple languages in the same WEB run;
 
  2. new production rules for Fortran, Ratfor, and TeX (and some
     modifications of Levy's (2) rules for C;
 
  3. a C-like built-in macro preprocessor;
 
  4. the ability to directly translate Ratfor into Fortran.
 
   In addition, many miscellaneous details have been changed and a
variety of convenience features has been added."
 
   ---------- Footnotes ----------
 
   (1) [which itself is written in Knuth's original Pascal WEB -MS]
 
   (2) [Levy and Knuth are the authors of the C variant of WEB -MS]
 
[2] How can I subscribe to LitProg?
 
   If you are not yet subscribed to LitProg, but you are interested,
send a MAIL message to `LISTSERV@SHSU.BITNET, or listserv@shsu.edu, or
LitProg-Request@shsu.edu' stating in the text of the MAIL: `SUBSCRIBE
LITPROG  your name in quotes'. The list itself is unmoderated: messages
sent to `litprog@shsu.edu' are automatically distributed to all
subscribers.
 
[3] How can I get the FWEB FAQ?
 
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
 
   - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq',
 
   - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq', and
     `ftp.uni-stuttgart.de' [130.83.55.75] in directory
     `pub/soft/tex/web/fweb/FAQ'.
 
   To retrieve the plain text file via e-mail, include
     SENDME FAQ.FWEB
   in the body of a mail message to
     FILESERV@SHSU.BITNET (fileserv@shsu.edu).
 
   Send the command
     SENDME FILELIST
   in a mail message to `FILESERV' to get valid information on the
names of the downloaded files if you'd like to have another version of
the fweb-faq (*note Which versions of the FAQ are available?: Question
4.).
 
   NOTE: do *not* include the message `SENDME FWEB' unless you want the
full FWEB distribution!
 
[4] Which versions of the FAQ are available?
 
   Besides the text file `fweb-faq', the FAQ is available as a Texinfo,
a PostScript, an Info or a DVI file.
All these can be generated from the Texinfo source file `fweb-faq.texi'.
The preprocessed DVI and PostScript files are not included anymore. See
the simple makefile which accompanies the fweb-faq distribution for
detailed information on how to process the Texinfo source. Short
instructions are given in the file `README.fweb-faq'.
 
   If you do not know anything about Texinfo, don't worry: With the
`texinfo.tex' macro package, the principal source file `fweb-faq.texi'
can be TeXed (1) like any ordinary TeX file at the expense of not
getting an index -- try it!
 
   If you would like to start with Texinfo, retrieve its latest version
from `prep.ai.mit.edu' in directory `pub/gnu' (*note How can I
contribute?: Question 6.).
 
   ---------- Footnotes ----------
 
   (1)
 
   If you do not have TeX, you may GNU's `texi2roff' for formatting.
 
[5] What is the difference between the FAQ and the manual?
 
   Most of the stuff in FAQs *is* in the manual, but people either
don't read the manual, or it is too hidden to be found (the FWEB User's
Manual currently has more than 200 pages). Thus the FAQ provides, if
you will, an index to the manual for those questions that come up
regularly. Where possible, sections of the User's Manual for the last
release (FWEB version 1.23a) are referred to by their section numbers
in square brackets, as in "[M-10.2]".
 
[6] How can I contribute?
 
   If you think that structure or content of this part of the FAQ can
be improved, or if you think you have discovered an error, either write
to me or post your comment to LitProg (with `fweb-faq (version)'
somewhere in the `Subject' line).
 
   If you find your name and email adress anywhere on these pages, I'd
be grateful if you check whether I got them right and inform me
otherwise. The same for errors in ftp site addresses and `Archive-Date'
(look into the `Makefile' to learn how to make these visible).
 
   "The FAQ" for Literate Programming will probably not exist before
the is a unified tool rather than a family of different environments.
On LitProg, all these environments are subject to discussion, and a
family of FAQ lists is planned, together with a master FAQ list for
general questions. This general FAQ will be maintained by David B.
Thompson <wqdbt@ttacs1.ttu.edu>.
 
   If you are interested in participating in one of the FAQ lists for
LitProg, either contact George D. Greenwade (E-mail: `bed_gdg@shsu.edu'
[Internet], `bed_gdg@shsu' [Bitnet], `shsu::bed_gdg' [DECnet]), who
maintains LitProg as well as the `FILESERV' repository at Sam Houston
State University, or simply announce your wish on the LitProg mailing
list.
 
   If you want to write a FAQ yourself, get "FAQ writer's FAQ" (by
Nathan Torkington and Ian Kluft) which originates from the
faq-maintainers mailing list. It can also be obtained via email by
including `SENDME FAQ.WRITING' in the body of a mail message to
`FILESERV', or retrieved from `niord.shsu.edu' in
`[FILESERV.FAQ]FAQ.WRITING'.
 
   If you want to write your FAQ list in Texinfo, use `fweb-faq.texi'
as a template for the principal source file (*note Which versions of
the FAQ are available?: Question 4.).
 
[7] What else should be included in the FAQ?
 
   * Merge the FAQs from the FWEB User's Manual with this list.
 
   * Remove items of more general character in favor of Dave Thompson's
     general FAQ for LitProg.
 
   * Give more details on the form of the FAQ file's Texinfo source?
 
   * Add thoughts on OOP using the FWEB system (*note Which WEB shall I
     use for C++: Question 16.)?
 
   * Should I include information on how to use FTP?
 
   * Should this or another member of the LitProg FAQ list family be
     cross-posted to USENET (`comp.text.tex', `news.answers')?
 
   Please send me your opinion on these items and suggest more things
which should be done!
 
Acknowledgements
 
   Thanks to all those whose postings in LitProg I have used and who
have sent me corrections, especially Bart Childs, Johannes Muller,
David Thompson and Don Petcher for this number of the FAQ, and to
Robert Chassell [FSF, GNU Texinfo and Elisp support] for help with some
Texinfo bugs.
 
   Thanks to the sysadmins who put up the files on FTP sites,
especially Thorbjoern Ravn Andersen (ftp.imada.ou.dk) and Joachim
Schrod (ftp.th-darmstadt.de).
 
   Special thanks to George D. Greenwade for maintaining the list and
the file archives at Sam Houston University, and to John Krommes for
checking this FAQ list for his child.
 
   Personally, I feel indebted to Thorsten Ohl for having introduced me
to FWEB in the first place, and having taught me many more things
related to computing.
 
FWEB sources/Manual/Installation
*********************************
 
[8] Where can I get FWEB?
 
   You can get FWEB (version 1.23a) via anonymous FTP either from
`lyman.pppl.gov', in directory `pub/fweb/v1.23':
 
       /anonymous@lyman.pppl.gov:/pub/fweb/v1.23:
 
       -rwxr-xr-x  1 4145     589          8396 Apr 14 22:45 INSTALL.FWEB*
       -rw-r--r--  1 4145     589         18967 Apr 14 22:45 Makefile
       -rw-r--r--  1 4145     589          3068 Apr 14 22:45 READ_ME.FWEB
       -rw-r--r--  1 4145     589            94 Apr 14 22:45 TAR.exclude
       -rw-r--r--  1 4145     589       1419071 Apr 14 22:45 TAR.v1.23.Z
       drwxr-sr-x  2 4145     589           512 Apr 14 22:45 demos/
       drwxr-sr-x  2 4145     589          1536 Apr 15 18:06 manual/
       ...
 
   Or from `niord.shsu.edu', in directory `[FILESERV.FWEB]':
 
       /anonymous@niord.shsu.edu:/ANON_DEV:/FILESERV/FWEB:
 
       FWEB-V1_23.TAR_Z;1       2772  21-JUL-1992 12:28 (RWE,RWED,RE,RE)
       FWEB-V1_23.ZIP;1         2370  21-JUL-1992 13:10 (RWE,RWED,RE,RE)
       ...
       INTRO.PS;1                175  22-JUL-1992 16:52 (RWE,RWED,RE,RE)
       ...
 
The PostScript file `INTRO.PS' gives a short introduction to Literate
Programming in general, combined with a simple Fortran example program
in FWEB.
   Note that there's also a user/syntax reference guide which can be
obtained independently of the full manual. If you are a seasoned WEB
user, the reference guide should be adequate.
 
[9] What is the latest version of FWEB?
 
   The latest version of FWEB is 1.23a - some time in January 1993,
version 1.30-beta is bound to come out.
 
   Versions that are explicitly intended to be beta versions are now
indicated as such--e.g., v1.30-beta--in the banner line from the
processors.
 
   JAK: "However, given the fragmented state of my time, in some sense
they're all beta."
 
   The latest version can be retrieved via anonymous FTP as described
in *Note Where can I get FWEB?: Question 8.
 
[10] Where can I get FWEB for the PC?
 
   The official FWEB PC executables are generated as part of each FWEB
release. Retrieve them from the FWEB distribution site `lyman.pppl.gov'
(*note Where can I get FWEB?: Question 8.) buried deep down in
`pub/fweb/v1.23/boot/ibm/pc':
 
      ...
      312 -rw-r--r-x  1 4145     589        304636 Apr 15  1992 ftangle.exe*
      272 -rw-r--r-x  1 4145     589        268878 Apr 15  1992 ftangle0.exe*
      280 -rw-r--r-x  1 4145     589        277032 Apr 15  1992 fweave.exe*
      ...
 
   `ftangle0.exe' is ftangle without the Ratfor preprocessor (*note Why
is FWEB so huge?: Question 26.).
 
   Hans-Hermann Bode <hhbode@dosuni1.bitnet> announced his precompiled
files for the PC. They can be retrieved from
 
   `anonymous@niord.shsu.edu:[FILESERV.PC-WEB]':
 
     00INDEX.;1                2  23-JUL-1992 16:26:54.85
     ...
     FWEBEXE.README;1          6  11-JUN-1992 00:15:18.00
     FWEBEXE.READ_ME;1        42   9-JUN-1992 12:13:34.00
     FWEBEXE.ZIP;1          1525  23-JUL-1992 16:06:33.26
     FWEBEXE.ZIP-LST;1         2  23-JUL-1992 16:22:24.54
     ...
 
   or in Europe from `dione.rz.uni-osnabrueck.de' (in directory:
`pub/msdos/tex/web'), and from `ftp.uni-stuttgart' (in directory
`soft/tex/web/cweb').
 
[11] Is FWEB small enough to compile on a PC?
 
   Yes.  It is known to compile with MicroSoft C 6.00 and Turbo C.
 
   JAK: "As a remark, it took some considerable pain to make this work.
 The larger sources, such as `ftangle.web', had to be split into as
many as 3 parts (handled by WEB macros and module names). The make file
compiles each of those parts separately, then combines them at link
stage.  Before this was done, compilers tended to bomb with messages
such as `Out of heap space'."
 
   On LitProg, Tero Laakkonen <laakkonen@cc.helsinki.fi> reported that
FWEB also compiles under linux-096c with gcc-2.2.2 on a 80386.
 
   In general, John Krommes offers support for porting FWEB to new
systems - contact <krommes@lyman.pppl.gov>.
 
[12] Has anyone installed FWEB on an HP machine?
 
   Either get GCC (the GNU C Compiler), or use (if you have it) the
unbundled Hewlett-Packard ANSI C Compiler, which is invoked with `cc
-Aa -D _HPUX_SOURCE' (as `cc(1)' explains in detail). Then `make'
should proceed without any problems.
 
Common Things People Want To Know
**********************************
 
[13] Can I use LaTeX with FWEB?
 
   In principle, you may use any package of TeX macros you like.
However, an arbitrary macro package may contain conflicts with macros
used in `fwebmac.sty'. Such conflicts are supposed to be eliminated for
LaTeX).
 
   As for LaTeX which is probably the package most widely used, you
have to do two things at minimum [M-19.7.22]:
  1. Use the command-line option `-PL' (or place them into your
     initialization file `~/.fweb' (*note Key differences for FWEB on
     different systems?: Question 25.).
 
  2. Process fweave's output with `latex' instead of `tex'.
 
   In most cases, to use LaTeX with FWEB it suffices to just say `latex
test' instead of `tex test'.  (I.e., an attempt is made to hide
internally whatever differences there are.) It never hurts, and
sometimes helps, to use the command-line option `-PL' (select
post-processor LaTeX). To print a `|' in a `verbatim' environment, use
`@|', like:  `\begin{verbatim} ... @| ... \end{verbatim}'.
 
   Since FWEB overrides the `\output' routine of LaTeX, some clever
page layout facilities will not work - e.g. there are no floating
bodies: while the `table' environment is lost, the `tabular'
environment still works. See [M-19.22] for details.
 
   Bart Childs reports that the use of AMSTeX causes some problems but
that it has been done.
 
   Difficulties with using LaTeX should be reported directly to Krommes.
 
   For bringing in `lex' and `yacc' scripts and the problem of using
LaTeX's `\footnote', *Note Can I use lex and yacc scripts with FWEB?:
Question 14.
 
[14] Can I use lex and yacc scripts with FWEB?
 
   Lewis Perin <m-lp9966@jed.cs.nyu.edu> reported that he has succeeded
bringing in `lex' and `yacc' UNIX scripts in for FWEB using LaTeX's
`verbatim' environment.
 
[15] Can I use the footnote environment from LaTeX?
 
   Lewis Perin reports that the superscripts of `\footnotes' appear in
the main text while the actual footnote is nowhere to be seen. In his
reply, Zdenek Wagner <wagner%csearn.bitnet@shsu.edu> refers to a style
file `ftn.sty' which he wrote to correct this (originally for use with
CWEB, it seems).
`ftn.sty' can be retrieved from `niord.shsu.edu' [192.92.115.8] in
directory `[FILESERV.STY]'.
 
[16] Which WEB shall I use for C++ ?
 
   As CWEB's coauthor Silvio Levy said, starting from version 2.9
(beta), CWEB will understand C++ syntax as well.
 
   Successful compilation on the PC with Borland-C++ was reported on
LitProg.
 
   In the opinion of many people, FWEB is the best CWEB available. It
also supports C, C++, F90, Ratfor, Ratfor-90, and writing TeX macros
wherein (f)tangle produces `.sty' files.
 
   As for the more general question of Object-Oriented Literate
Programming, a very interesting discussion was started by Paul Lyon in
December.
 
   Hopefully, this topic will make it to Dave Thompson's General FAQ
for LitProg (*note How can I contribute?: Question 6.).
 
[17] Does FWEB support Makefiles?
 
   Not yet. This is planned, though [M-10.2].
 
[18] FWEB with the GNU Emacs editor?
 
   If you are developing your FWEB programs using the GNU Emacs editor,
there is `web-mode.el' by Mark Motl <motl@cs.tamu.edu>; the
corresponding GNU Emacs "mode" can deal with WEB, CWEB and FWEB.
It is capable of many things, including jumping to sections and
modules, inserting (and previewing) index entries, hiding and exibiting
the body of a `.web' file (showing the tree), inserting, quoting, and
consistently renaming modules etc. It supports change files and journal
files. It is especially useful when dealing with large `.web' files not
to have to deal with "monolithic" FWEB files.
For more information, you may obtain a 30pp. User's Manual and the
source files from the author, from Bart Childs <bart@cs.tamu.edu>.
 
   The current version of `web-mode' (v 1.61, as of Dec 28, 1992) is
faster, more robust, and the documentation in the manual is improved
and more accurate now.
You may also obtain this version as a 220 KByte shell archive from me
<marcus@x4u.desy.de>.
 
[19] How do I turn off double sided pagination in FWEB?
 
   In FWEB, the command `\identicalpageheadstrue' [to be put in the so
called "limbo" part of your FWEB file] makes all page headers
identical, but it puts the page numbers in the upper LEFT corner and
the section numbers in the upper RIGHT corner. As Don Petcher pointed
out, to do it the other way around you can either change the macro
`\normaloutput' in `fwebmac.sty' as indicated:
 
     \def\normaloutput#1#2#3{\shipout\vbox{
       \ifodd\pageno\hoffset=\pageshift\fi
       \vbox to\fullpageheight
        {
         \iftitle\global\titlefalse
         \else\hbox to\pagewidth
             {\vbox to10pt{}%
             \ifidenticalpageheads#3\else  % THIS WAS ORIGINALLY #2 <---------
                 \ifodd\pageno
                     #3% Makes page numbers alternate left \& right.
                 \else#2\fi
             \fi
             }%
         \fi
         \vfill#1
         }}% Parameter |#1| is the page itself
       \global\advance\pageno by1}
 
or you can include the above version in your TeX file as a redefinition
of the macro.
 
[20] Can I define (and format) new reserved words?
 
   Assume you want to declare `far' to indicate a function pointer:
     void far (*reset)();
 
In order for fweave to treat `far' like a reserved word in C (or any of
the language supported by FWEB), say
       @f far int
 
   somewhere in your source. Weave does not by default recognize `|far|'
as a reserved word (this property extends to cweave as well).
 
   The formatting with `@f' is *language-specific*; it only applies to
identifiers used in the language in force at the point the format
statement is encountered. This feature allows a WEB programmer to
invent new reserved words and/or to unreserve some reserved identifiers
[M-11.12].
 
[21] Symbolic debugging of FWEB files?
 
   FWEB inserts sync lines `#line 137 foo.web' into the code, so any
compiler/debugger worth its money should respect them. (Including those
running under MS-DOS.)
 
   Extra FWEB comments in the tangled output can be suppressed by a
simple command line switch. See [M-14.2] for a list of command line
options.
 
   NB: well thought out code needs less time debugging - comments like
"since I've started using anyWEB, my debugger has just been collecting
dust ..." were reported from many people on the list.
 
[22] Inserting meta-comments in FWEB files?
 
   Johannes Muller reported strange output from fweave when defining
two macros "debug" and "gubed" to enclose optional code for debugging
purposes. As his global language, he chose C++.
 
     @m debug @(
     @m gubed @)
     @f debug do
     @f gubed while
 
   This worked fine for him using WEB with Pascal. `@(' and `@)' are
control codes which mark the begin and end of a "meta-comment", i.e.
commented out code that will appear in the output file [M-11.38].
Though I wasn't able to reproduce his errors, it should be remarked
that the preferred way is to use the WEB preprocessor construction
`@#if(0) ... @#endif' instead.
 
   JAK: "That Muller's example doesn't work probably points out a
problem with the macro preprocessor".
 
   For debugging purposes, one can bracket pieces of code by `@#ifdef
DEBUG ... @#endif', switching on DEBUG
 
   by the commandline flag `-mDEBUG' for ftangle [M-7.5].
 
[23] Automatic referencing in documentation sections?
 
   To produce the woven output
 
     For info on porting, see section 5
 
   As Steve Avery reported, you can cheat and, somewhere after you
start the module, just throw in something like `\let\refporting=\modno'
and then reference it by `see section~\refporting'.
 
   In FWEB, `\modno' is set to the number of the module being typeset.
 
   Another way to refer to a section is described in [M-19.7.18]:
 
     @ Porting.
     \modlabel{PORTING}
 
     ... more ...
 
     @ Another section.
     \modlabel{ANOTHER}
 
     For info on Porting, see \WEBsection{PORTING}.
 
   `section' is inserted automagically. In the same fashion, the label
`ANOTHER' allows the user to refer to that section number.
 
   In LaTeX, forward referencing works, in Plain TeX it doesn't. Unless
you're using LaTeX, the latter recipe requires that
`\modlabel{ANOTHER}' is defined before referring to it.
 
   If you want to say "module" instead of "section", use `\WEBmodule'
(or equivalently `\module') instead of `\WEBsection'.
 
[24] How do I make a title appear on the contents page?
 
   Bart Childs <bart@cs.tamu.edu> contributed three short files to
solve that problem. These listings will disappear here once the full
`web-mode.el' distribution (*note FWEB with the GNU Emacs editor?:
Question 18.) is available at `FILESERV':
 
   * `limbo.material' may be used as the initial skeleton for all WEB
     files. There is a line containing `\def\title' which should be
     modified to include the `title'. Also note that the first few
     lines are to encourage a little more documentation about the
     source. A few lines further into this is a similar convenience to
     add an abstract that will appear on the cover page too.
 
   * `limbo.sty' is a convenient place to record macros that are
     commonly used in WEB files.
 
   * `time.tex', required by `limbo.material'.
 
   Note that the `limbo' style-file parameter can be used to
automatically insert common material into the limbo section of an FWEB
file.
 
`limbo.material'
-----------------
 
     -----------------------  limbo.material ------------------
     %
     % ??????.web,   ?fweb version 1.23
     % Author
     % Address
     % e-mail and phone
     %
     %   LIMBO MATERIAL
     %
     \input limbo.sty
 
     \def\title{{\tt }}
 
     %% Comment the previous and uncomment this if you don't use web-mode
     %%\def\title{{\tt ?? I need a Title ??}}
 
     %%% begin Bottom of Contents Page macro
     \def\botofcontents{\vskip 0pt plus 1fil minus 1.5in
     {\bigskip\parskip6pt plus2pt \parindent20pt
     %% begin abstract
     \vskip0.5in
     \noindent{\bf Abstract. }\it
 
     }%% end abstract
 
     %% BC often puts this in as a comment about pre-release versions ...
 
     %\vskip0.5in
     %{\vfill\it %% comments on anything else ????
     %
     %\vfil}% end of comments on anything else
     \vfil
       \rightline{My Name}% You can personalize your output here, for example.
       \rightline{\today     }% today.tex should be preloaded, input it if not
       \rightline{\miltime   }% time.tex  should be preloaded, input it if not
 
     }%      end of botofcontents
 
     %   END OF LIMBO MATERIAL
     %
     %
     %   BEGINNING OF WEB
     %
 
     %% Delete the next line after appropriate substitution.
     %% In fweb's you want an @c, @c++, @n, @n9, or @Lx at this point
 
     @* First Module.
 
     @* Index.
 
`limbo.sty'
------------
 
     ------------------------  limbo.sty -------------------------
     % \input today %%%%% How Ridiculous, preload it!!!!!!!!!
     \font\ninett=cmtt9
     \font\ninerm=cmr9
     \let\mc=\ninerm % medium caps for names like UNIX
     \font\Csc=cmcsc10 % Computer Modern Computer Small Caps
     \def\PASCAL{{\rm Pascal}}% Does very little
     \def\WEB{{\ninett WEB}}%  use like \WEB{}  to make space significant
     \let\web=\WEB \def\FWEB{{\ninett FWEB}} \let\fweb=\FWEB
     \def\Fortran{{\Csc Fortran}} \def\Cee{{\bf C}}
     \def\Unix{{\mc UNIX}}  \let\unix=\Unix
     \def\BSl{{\rm\char'134}} \def\<{$\langle\,$} \def\>{$\,\rangle$}
     %
     %%% begin Top of Contents Page macro
     %
     \def\topofcontents{\hsize 6in
       \vglue -30pt plus 1fil minus 1.5in
       \centerline{\title}
       \vskip 15pt
       \centerline{\today}
     \bigskip \vfill
       \def\?##1]{\hbox to 1in{\hfil##1.\ }}}% end of topofcontents
 
`time.tex'
-----------
 
     --------------------------  time.tex  ----------------------
     \newcount\milhours\newcount\minutes\newcount\hours
     \def\thetime{\milhours=\time
     \divide\milhours by 60
     \minutes=\milhours
     \multiply \minutes by -60
     \advance\minutes by \time
     \hours=\time \divide\hours by 60
     \ifnum \hours>12 \advance \hours by -12 \fi
     \the\hours:\ifnum \minutes > 9 \the\minutes \else 0\the\minutes \fi}
 
     \def\miltime{\milhours=\time
     \divide\milhours by 60
     \minutes=\milhours
     \multiply \minutes by -60
     \advance\minutes by \time
     \the\milhours:\ifnum\minutes>9 \the\minutes\else 0\the\minutes \fi}
 
[25] Key differences for FWEB on different systems?
 
   The machine dependent files, especially `custom.h' and `defaults.mk'
necessary for bootstrapping, can be found in the current distribution
of FWEB (v1.23a) in subdirectory `/boot/'. See the `READ_ME.*' files
there for details.
 
   To run FWEB, commonly used options can be put into an initialization
file [M-14.3] (default name `.fweb'). The subdir's of `/boot/' contain
sample `.fweb' files with necessary commandline options for the system
on which FWEB was built.
 
[26] Why is FWEB so huge?
 
   Most of FWEB's size can be attributed to the need of supporting
vastly different languages.  The input routines for a free form
language are not usable for Fortran and vice versa.  Furthermore, FWEB
has a Ratfor processor built in (which is a *big* plus, though it is
not strictly related to literate programming).
 
   JAK: "Two other reasons for the large size are
 
  1. the built-in macro preprocessor, an extended version of that for
     ANSI C;
 
  2. the style-file mechanism.
 
   On the positive side, FWEB does most of its memory allocations
dynamically, so one can cut down the size of various tables if
necessary.  Type `ftangle -Y' to find out about the current
allocations; use the `-y' option to change them. The statistics option
`-s' is also helpful to find out how much a job actually uses."
 
   If you do not want the Ratfor preprocessor, you can make a smaller
`ftangle' with the option `LOAD\_RATFOR=0' (see the file
`web/ratfor0.web' of the FWEB distribution, and [5]).
 
[27] What is the difference between CWEB and FWEB?
 
   See [M-19.8], Appendix H, for a short list comparing these two
variants of the WEB system.
 
[28] What is the difference between FWEB and Funnelweb?
 
   The following was extracted from a text by Paul Lyon (and will
eventually be merged with a FAQ for Funnelweb ...):
 
   "FWEB and Funnelweb are quite distinct. FWEB is built on top of the
CWEB framework; although the parser in its weave processor can do
more--all of ratfor, C, C++, and (though the support is not complete),
TeX, it is still confined to those specific languages, and still
imposes on the user the formatting conventions that please its author.
To get something different you will have to hack the weave processor.
(One could possibly get somewhere by modifying the TeX macro package
that FWEB uses, but that might be the harder way to go, unless, of
course, you are already a TeXpert) ...
 
   Funnelweb, on the other hand, does not try to parse the "source" code
at all; it just takes the layout of the source as written, turns off
the meaning of plain TeX special characters, sets typewriter font, and
then invokes `\obeylines' and `\obeyspaces'; all this together causes
TeX to print the source verbatim (the paragraph formatting is turned
off, and TeX does not gobble spaces). The original WEB, CWEB, FWEB, and
Spiderweb all parse and format the source, inserting TeX math codes for
the operators, putting keywords in boldfont, adjusting the indentation,
and so on. If you like the style chosen for the programme, it looks
much nicer that way. Except for Spiderweb, which can be adapted to
various languages by allowing a fair range of variation in specifying
the pretty printing grammar using a large `awk' script to process the
grammar spec and generate replacement code for significant chunks of
weave, the pretty printing parser(s) in the other are hard coded. This
has it uses besides making the typeset code more attractive; WEB, CWEB,
FWEB, and Spiderweb all do an index of identifiers for the code that
can differentiate, for the most part, between declaration and use of an
identifier (they know enough about the grammar to do that, but not, of
course, as much as a compiler or interpreter) ..."
 
   [Rest deleted: continues with more details on Funnelweb.]
 
   JAK: "Don't hack `fweave'!  Many effects can be obtained by
modifying `fwebmac.sty'. (If one knows enough to hack `fweave', he
presumably knows enough to hack `fwebmac.sty' instead.) Note that the
style-file mechanism does provide some degree of customization."
 
   Please report customizations that are really necessary to John
Krommes.
 
[29] Do FWEB files necessarily have to be monolithic?
 
   [Later, this item might move to the general FAQ by David B. Thompson]
 
   There is no real support for multiple source files under FWEB. What
some might like to see is a solution similar to the one presented by
Cameron Smith in his `KR-CWEB-SAMPLE' distribution. He had to hack
CWEB's `cwebmac.sty' to get a neat table of contents and a combined
index distinguishing between entries from different source files [in
fact, `KR-CWEB-SAMPLE' illustrates many more things, all more or less
related to breaking up a literate C program into multiple source files].
For illustration, this is how the table of contents should look like
(sample from Cameron's files):
 
     source module 1: main         Sect Page
     introduction..................1.1  1.1
     main pgm......................1.4  1.2
     index.........................1.10 1.4
 
     source module 2: getop
     introduction..................2.1  2.1    etc.
 
   while entries of the combined index are separated like
 
     Index for source module 1: main
     ...
     Index for source module 2: getop
     ...
     ...
 
     Sections in source module 1: main
     <case for newlines 9> used in section 4...
     ...
 
   For FWEB, the inclusion of files using `@i' is a partial solution
[M-11-13] to avoid having to put all the source code in one file.  So
far, nobody has presented a solution in Cameron's spirit.
 
   This feature is put on JAK's list of possible future enhancements.
It will not be in c1.30, though. Note that CWEB has got an `@i' option,
too (although FWEB's is somewhat more general).
 
   Yet another approach (not limited to FWEB) is the use of a "smart"
editor like GNU Emacs, combined with a "smart" tool like `web-mode'
which is effectively hiding many of the mischiefs of monolithic source
files from the programmer. (*note FWEB with the GNU Emacs editor?:
Question 18.).
 
[30] How did tangle and weave get their names?
 
   [Later, this item might move to the general FAQ by David B. Thompson]
 
   In a reply, Cameron Smith wrote:
"One of the problems with having a single preeminent writer in a
language is that everyone always assumes that any enduring tidbit came
from his pen ...".
Fortunately, for the question "How did tangle and weave get their
names", the circulus vitiosus of erroneously quoting William
Shakespeare could be broken. The full answer:
 
       O, what a tangled web we weave
       When first we practise to deceive!
         -- Sir Walter Scott, _Marmion_, canto 6, verse xvii (1808)
 
   Cameron also suggested to include these lines by Richard Palais
(1982):
 
       O, what a tangled WEB we weave
       When TeX we practise to conceive!
 
   Concerning FWEB, JAK reluctantly remarks [M-1]: "We shall call this
new version FWEB when necessary ...".
 
   And more recently: "I now think the choice of `F' in FWEB was a
mistake. `F' stands for Fortran, which motivated this project, but the
ability of FWEB to handle multiple languages is one of its most
distinctive and useful features. But it's probably too late now."
 
   The question to which extent "WEB" inherits from certain German
words I'll leave to the native speakers (with a light heart).
 
[31] How am I supposed to abbreviate "Literate Programming"?
 
   [Later, this item might move to the general FAQ by David B.
Thompson.]
 
   There wasn't a clean vote on the mailing list. Most people seemed to
agree that one should not misuse common abbreviations like "LP", "LPR"
etc. Also, the acronym should be pronounceable (thus eliminating
"LitPgm" e.g.). The list's name "LitProg", proposed by Cameron Smith,
seems to be accepted by a majority now. This is also the acronym
adopted for the FAQ list.
 
General Questions/Bugs/Problems
********************************
 
[32] What if I think I found a bug in FWEB?
 
   John Krommes <krommes@lyman.pppl.gov> actively supports FWEB -- he
must be considered the ultimate source of wisdom.
 
   Once you think you've found a bug, put it out on the list. If nobody
responds, cut your file down to the smallest subfile that still
exhibits the problem you encountered. Then you may contact John.
 
[33] Problem opening a new output file for tangled code?
 
   If you're using FWEB's `@o' option in order to open a new output
file for tangled code (with local scope - i.e. for the duration of the
current section only [M-11.21]), you may see output looking like this:
 
     > ftangle test
     This is ScRaMbLeD FTANGLE [SunOS/UNIX version 1.23a (April 13, 1992)].
     Reading test.web ... *1 *4 *6
     Writing the output file(s):  (test.c)(getop.hQmSWs)
     Done.
     CPU = 0.3 sec.; REAL = 0.8 sec.  CPU/REAL = 45.0%.
     [FTANGLE:  No errors were found.]
 
   with spurious characters in the output file names.
 
   This is a bug which will be fixed in FWEB version 1.23b as promised
in the `README' file of the FWEB distribution v1.23a.
 
Preliminary Bug Report
......................
 
   Aside the list, Don Petcher reports a more specific version of the
problem (this seems to affect both the local `@o' and the global scope
command `@O'):
If you change output files with the `@O' command (or the `@o' command)
and the second filename is shorter than the first, then the second
filename gets spurious characters added.
 
   E.g. creating `*.cc' files and `*.h' files, the `*.h' file always
gets an extra character after the first writing to the `*.cc' file. A
temporary cludge is obvious - add an extra character to the `*' part of
the `*.h' file. So your file names don't go together well, but you
escape the problem.
 
   It now seems as if this bug is pretty much machine dependent. The
recipe pointed out in the last edition of this list, adding characters
to the name part of the secondary output file, only works for Don
Petcher on his NeXT workstation.
 
   Stirred up by Johannes' complaint Don and I tried a couple of silly
programs on his NeXT, on a HP9000, on an Apollo 700, on a Sun-4 and on
a Silicon Graphics workstation (SGI). The result was that none of the
machines behaves the same for the programs we tried. The Apollo did not
exhibit the bug at all, for the NeXT Don's cludge works. The HP accepts
output file names "g" and "g." but produces spurious characters for
"g.h" - the Sun only accepts "g" but not "g." and "g.h". The SGI
exhibits the error if the filename contains more than one underscore or
if the filename is longer than six letters.
 
   JAK: "I think this is fixed. I will attempt to thoroughly test this
out before releasing v1.30."
 
[34] Maximum number of equal characters in different section names?
 
   FWEB may have problems distinguishing section names, if one of them
is an exact subset of a longer name rather than a length.
 
   This is a bug in the mind of some, but it may as well be regarded a
good "feature" as it should be a warning that poor choices of names has
happened.
 
   JAK: "I think it's a feature, not a bug. And unless I screwed
something up, the behavior derives from CWEB."
 
[35] Must I leave leading blanks in my fortran FWEB file?
 
   Yes, you should. This is proven by the following example coming from
Bart Childs.
 
     @n
     @* The world is not perfect.
     This wonderfully short problem blows outputs garbage
     from fweave and ftangle if you don't have the leading
     six columns blank.  Be careful, because in many cases
     FWEB works fine without the requisite leading blanks.
 
     @a
        program final_exam
        implicit none
        integer i, j
        do i = 1, 7, 2
          do  j = 6, 1, -1
            write(*,*) i, j
            end do
          end do
        end
 
   To see the effect on fweave, indent with 4 leading blank spaces
instead of 6.
 
   JAK: "The input reader for Fortran--77 *follows the rules* of
Fortran--77--i.e., statement labels in columns 1--5, continuation
character in column 6, columns 6--72 for code.  However, note that
Ratfor uses free-form syntax, and Fortran--90 also has a free-form
syntax mode, which FWEB attempts to support."
 
Index
******
 
* Menu:
 
* #line:                                Question 21.
* -PL, select pre-processor LaTeX:      Question 13.
* -s, FWEB statistics option:           Question 26.
* .fweb:                                Question 13.
* /anonymous@lyman.pppl.gov/pub/fweb/v1.23: Question 8.
* /anonymous@niord.shsu.edu/FILESERV/FWEB: Question 8.
* @(:                                   Question 22.
* @):                                   Question 22.
* @f:                                   Question 20.
* @O:                                   Question 33.
* @o:                                   Question 33.
* @|, in LaTeX verbatim:                Question 13.
* AMSTeX:                               Question 13.
* anonymous FTP:                        Question 3.
* anonymous FTP:                        Question 8.
* anonymous@dione.rz.uni-osnabrueck.de: Question 10.
* anonymous@ftp.imada.ou.dk/pub/faq:    Question 3.
* anonymous@ftp.uni-stuttgart.de:       Question 10.
* anonymous@ftp.uni-stuttgart.de/pub/soft/tex/web/fweb: Question 3.
* anonymous@lyman.pppl.gov:             Question 10.
* anonymous@niord.shsu.edu/FILESERV/FWEB: Question 3.
* anonymous@niord.shsu.edu/[FILESERV.PC-WEB]: Question 10.
* ANSI C:                               Question 12.
* Appendix H:                           Question 27.
* Archive-Date:                         Question 6.
* Bart Childs <bart@cs.tamu.edu>:       Question 34.
* Bart Childs <bart@cs.tamu.edu>:       Acknowledgements.
* Bart Childs <bart@cs.tamu.edu>:       Question 13.
* Bart Childs <bart@cs.tamu.edu>:       Question 24.
* Bart Childs <bart@cs.tamu.edu>:       Question 18.
* Bugs:                                 Question 32.
* Bugs:                                 General Questions/Bugs/Problems.
* C:                                    Question 1.
* C++:                                  Question 16.
* C++:                                  Question 1.
* Cameron Smith <cameron@symcom.math.uiuc.edu>: Question 30.
* Cameron Smith <cameron@symcom.math.uiuc.edu>: Question 29.
* Change files:                         Question 18.
* Command line options:                 Question 21.
* Contents page:                        Question 24.
* CWEB:                                 Question 1.
* CWEB:                                 Question 16.
* CWEB, @i option in:                   Question 29.
* D.E. Knuth (DEK):                     Question 1.
* David Thompson <wqdbt@ttacs1.ttu.edu>: Question 1.
* David Thompson <wqdbt@ttacs1.ttu.edu>: Acknowledgements.
* Debugger:                             Question 21.
* Debugging:                            Question 22.
* DEK (Donald E. Knuth):                Question 1.
* Design contributions:                 Question 1.
* Distinguishing section names:         Question 34.
* Don Petcher <petcher@wuphys.wustl.edu>: Question 33.
* Don Petcher <petcher@wuphys.wustl.edu>: Question 19.
* Don Petcher <petcher@wuphys.wustl.edu>: Acknowledgements.
* Double sided pagination:              Question 19.
* FAQ for FWEB:                         Question 6.
* FAQ Writer's Guide:                   Question 6.
* FAQ, General:                         Question 6.
* FILESERV:                             Question 6.
* Floating bodies:                      Question 13.
* Footnotes in LaTeX:                   Question 15.
* Formatting:                           Question 1.
* Fortran:                              Question 1.
* Fortran--77:                          Question 35.
* Fortran--90:                          Question 35.
* Fortran90:                            Question 1.
* Ftangle:                              Question 33.
* ftangle, change allocation:           Question 26.
* ftangle, current allocation:          Question 26.
* ftn.sty:                              Question 15.
* Function pointer:                     Question 20.
* fweave:                               Question 28.
* FWEB executables:                     Question 26.
* FWEB for the PC:                      Question 10.
* FWEB for the PC, precompiled files:   Question 10.
* FWEB sources:                         FWEB sources/Manual/Installation.
* FWEB User's Manual:                   Top.
* FWEB User's Manual, quoting:          Question 5.
* FWEB, future enhancements:            Question 29.
* FWEB, latest version:                 Question 9.
* FWEB, painful work with:              Question 11.
* FWEB, v1.30-beta:                     Question 9.
* fweb-faq:                             Question 6.
* fweb-faq.dvi:                         Question 4.
* fweb-faq.info:                        Question 4.
* fweb-faq.ps:                          Question 4.
* fweb-faq.texi:                        Question 4.
* fwebmac.sty:                          Question 28.
* fwebmac.sty:                          Question 19.
* GCC:                                  Question 12.
* gcc-2.2.2:                            Question 11.
* General Questions:                    General Questions/Bugs/Problems.
* George D. Greenwade <bed_gdg@shsu.edu>: Question 6.
* Global scope:                         Question 33.
* GNU C compiler (GCC):                 Question 1.
* GNU Emacs editor:                     Question 18.
* GNU Emacs editor:                     Question 4.
* Hans-Hermann Bode <hhbode@dosuni1.bitnet>: Question 10.
* Hewlett-Packard:                      Question 12.
* How can I contribute?:                Question 6.
* HP:                                   Question 12.
* Ian Kluft <ikluft@uts.amdahl.com>:    Question 6.
* Initialization file:                  Question 13.
* Intel 80386:                          Question 11.
* Introduction and Editorial:           Introduction and Editorial.
* JAK (John A. Krommes):                Top.
* JAK (John A. Krommes):                Question 29.
* JAK, quoted:                          Question 9.
* JAK, quoted:                          Question 22.
* JAK, quoted:                          Question 11.
* JAK, quoted:                          Question 34.
* JAK, quoted:                          Question 1.
* JAK, quoted:                          Question 35.
* JAK, quoted:                          Question 33.
* JAK, quoted:                          Question 28.
* Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>: Acknowledgements.
* Johannes Muller <jmu@ccr.jussieu.fr>: Acknowledgements.
* Johannes Muller <jmu@ccr.jussieu.fr>: Question 22.
* John A. Krommes (JAK):                Top.
* John Krommes <krommes@lyman.pppl.gov>: Question 11.
* John Krommes <krommes@lyman.pppl.gov>: Question 1.
* John Krommes <krommes@lyman.pppl.gov>: Question 32.
* John Krommes <krommes@lyman.pppl.gov>: Acknowledgements.
* Journal files:                        Question 18.
* Language-specific:                    Question 20.
* LaTeX:                                Question 13.
* Lewis Perin <m-lp9966@jed.cs.nyu.edu>: Question 15.
* Lewis Perin <m-lp9966@jed.cs.nyu.edu>: Question 14.
* lex:                                  Question 14.
* limbo, style-file parameter:          Question 24.
* limbo.material:                       limbo.material.
* limbo.material:                       Question 24.
* limbo.sty:                            Question 24.
* limbo.sty:                            limbo.sty.
* linux-096c:                           Question 11.
* Literate Programming, abbreviation for: Question 31.
* LitProg Mailing List:                 Top.
* LitProg-Request@shsu.edu:             Question 2.
* Local scope:                          Question 33.
* Macro preprocessor:                   Question 1.
* Macro preprocessor:                   Question 22.
* mail-server@rtfm.mit.edu:             Question 8.
* Make:                                 Question 12.
* Makefile:                             Question 6.
* Makefile:                             Question 17.
* Makefiles, FWEB support:              Question 17.
* Marcus Speh <marcus@x4u.desy.de>:     Top.
* Mark Motl <motl@cs.tamu.edu>:         Question 18.
* Marmion, canto 6, verse xvii:         Question 30.
* Meta-comment:                         Question 22.
* Microsoft C 6.00:                     Question 11.
* MS-DOS:                               Question 21.
* Multilingual WEB variant:             Question 1.
* Nathan Torkington <Nathan.Torkington@vuw.ac.nz>: Question 6.
* Native speaker:                       Question 30.
* Nelson H. F. Beebe <beebe@math.utah.edu>: Question 1.
* niord.shsu.edu/FILESERV/LITPROG:      Top.
* Object-Oriented Literate Programming: Question 16.
* Paul Lyon <uunet!emx.cc.utexas.edu!plyon>: Question 28.
* PC:                                   Question 1.
* prep.ai.mit.edu:/pub/gnu:             Question 4.
* Programming, Literate (!):            Question 1.
* Question for the General FAQ:         Question 1.
* Question for the General FAQ:         Question 31.
* Question for the General FAQ:         Question 29.
* Question for the General FAQ:         Question 30.
* Ratfor:                               Question 1.
* Ratfor:                               Question 35.
* Ratfor processor:                     Question 26.
* README.fweb-faq:                      Question 4.
* Referencing:                          Question 23.
* Reserved words:                       Question 20.
* Richard Palais:                       Question 30.
* Robert J. Chassell <bob@gnu.ai.mit.edu>: Acknowledgements.
* Sam Houston State University:         Question 6.
* Section names, referencing of:        Question 23.
* Silvio Levy <levy@math.berkeley.edu>: Question 1.
* Silvio Levy <levy@math.berkeley.edu>: Question 16.
* Sir Walter Scott <not reachable via email>: Question 30.
* Steve Avery <stevea@vast.unsw.edu.au>: Question 23.
* SUBSCRIBE LITPROG:                    Question 2.
* support porting FWEB:                 Question 11.
* Sync lines:                           Question 21.
* table:                                Question 13.
* tabular:                              Question 13.
* Tangle:                               Question 16.
* Tero Laakkonen <laakkonen@cc.helsinki.fi>: Question 11.
* TeX:                                  Question 1.
* Texinfo system:                       Question 4.
* Thorbjoern Ravn Andersen <ravn@imada.ou.dk>: Acknowledgements.
* Thorsten Ohl <ohl@chico.harvard.edu>: Acknowledgements.
* time.tex:                             Question 24.
* time.tex:                             time.tex.
* Title:                                Question 24.
* Titlepage:                            Question 24.
* To-do-list:                           Question 7.
* Turbo C:                              Question 11.
* UNIX:                                 Question 1.
* version 1.23b:                        Question 33.
* VMS:                                  Question 1.
* Weave:                                Question 20.
* WEB:                                  Question 1.
* WEB preprocessor:                     Question 22.
* web-mode.el:                          Question 18.
* William Shakespeare:                  Question 30.
* yacc:                                 Question 14.
* Zdenek Wagner <wagner%csearn.bitnet@shsu.edu>: Question 15.
* [M-10.2]:                             Question 17.
* [M-11.12]:                            Question 20.
* [M-11.21]:                            Question 33.
* [M-11.38]:                            Question 22.
* [M-14.2]:                             Question 21.
* [M-19.7.18]:                          Question 23.
* [M-19.7.22]:                          Question 13.
* [M-19.8]:                             Question 27.
* [M-1]:                                Question 1.
* [M-2.4]:                              Question 1.
* [M-7.5]:                              Question 22.
* \footnote, LaTeX:                     Question 15.
* \identicalpageheadstrue:              Question 19.
* \modlabel:                            Question 23.
* \output:                              Question 13.
* \ref:                                 Question 23.
* \WEBsection:                          Question 23.
* |, in LaTeX verbatim:                 Question 13.
 
       //////////////////////////////////////////////////////////
      //   marcus@x4u.desy.de   //  Marcus Speh               //
     //  [131.169.30.33]       //  II. Inst. f. Theor. Phys. //
    // Phone: (040) 8998-2260 //  Luruper Chaussee 149      //
   // FAX: (040) 8998-2267   //  2000 Hamburg 50 / Germany //
  //////////////////////////////////////////////////////////
 
From leew@cs.utexas.edu Mon Jan 11 12:05:23 -0600 1993
Date: Mon, 11 Jan 1993 12:05:23 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  bad CWEB formatting ?
 
Klaus Elsbernd writes:
 
  > This mentioned problem is not only true if you use non-reserved words like
  > |line| as identifiers. I detected this problem in the following code
  > fragment too:
  >
  > @<Typedef...@>=
  > struct g_process {
  >         int socket;
  >         struct msgh *msgh;
  >         char *buf;
  >         char owner[10];         /* user-id des Benutzers */
  >         time_t connect_time;
  >         time_t access_time;
  >         time_t give_ivory_time;
  > #ifdef DAEMON
  >         Board *p_board; /* ein zum \gproc-Proze\"s geh\"orendes board */
  >        struct g_process *next_g_process;
  > #else
  >         int pid;        /* process-id of a called process executing genera */
  > #endif /* DAEMON */
  > };
  >
  > typedef struct g_process G_Process;
  >
  > The code formats to
  > <Typedef declarations > =
  >  struct g_process {int socket;
  >    struct msg *msgh;
  >    ...
  > #ifdef DAEMON
  >    ...
  > #endif
  >  }; typedef struct g_process G_Process;
  >
  > The solution is the same; I inserted
  > @f G_Process int
  > and CWEAVE did the right thing (insert a newline after the structure
  > definition). I hope I made it right and served not the symptom.
 
Actually, my guess is that it was a different formatting problem in your
case.  We tend to forget that the WEB formatters are (deliberately) pretty
simple.  They deal well with all the usual suspects, but can't deal with
more complicated stuff.  It may be that the embedded #ifdefs, etc. are
screwing up the parser.
 
Another possibility:  Is the typedef for Board before the section you
describe?  If not, the parser will not know that Board is "int_like" when
it is parsing this section.  If Board is in italics (rather than bold) in
the woven version (before the fix), this is probably what happened.
 
Or it could be something completely different.  What the hell, the fix
works (although it is always nice to know _why_ something works).
 
		-- Lee Wittenberg
 
From leew@cs.utexas.edu Mon Jan 11 12:11:55 -0600 1993
Date: Mon, 11 Jan 1993 12:11:55 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Defining multiple modules (sections) in one
 
Steve Avery writes (in response to an earlier message of mine):
 
  >   leew> 	x = @<Something that evaluates to an lvalue@> = 0;
  >
  > 	Okay, my two bits worth (again) - this is not a very good
  > example of literate programming (imho of course). I was under the
  > impression that this sort of code is best handled by the @d mechanism
  > which web provides. I would even be quite suprised if weave was able to
  > handle this sort of code, as I am sure it would have difficulty parsing
  > a section which did not contain complete statements.
 
I agree completely with Steve that this is a bad example of literate
programming and that an @d is much more appropriate.  The point is that
code like this exists (and there may be a more valid example out
there), and the extra overhead involved in typing an extra @<space>
is minimal compared to the extra overhead involved in  making a more
sophisticated parser that will almost certainly break existing code.
 
		-- Lee Wittenberg
 
From George Mon Jan 11 13:20:26 CST 1993
Date: Mon, 11 Jan 1993 13:20:26 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: RE: Announcement: fweb-faq [01-93] updated
 
On Mon, 11 Jan 93 11:04:43 +0100, marcus@x4u.desy.de (Marcus Speh) posted
about the update to his FAQ for FWEB. I have been a bad archivist on this
and should have been quicker to point out my plans on this -- my sincerest
apologies to Marcus about this, as well as any inconvenience this may cause
you.  Here is the major change at our site:
>        How to get the fweb-faq file(s):
>        --------------------------------
>        Retrieve them via anonymous FTP from the following sites
>
>        Name:      niord.shsu.edu   [official FWEB FAQ host]
>        Address:   192.92.115.8
>        Directory: [FILESERV.FWEB]
 
Please make this:
>        Directory: [FILESERV.FWEB-FAQ]
where I have made a ZIP archive of the entire distribution, in addition to
the individual files.
 
Also:
>        To retrieve the (text) file via e-mail, include:
>         SENDME FAQ.FWEB
>        in the body of a mail message to FILESERV@SHSU.BITNET
>        (FILESERV@SHSU.edu). To retrieve the full family of files
>        (< 500 KByte), include SENDME FAQ.FWEB* instead.
 
You can also use SENDME FWEB-FAQ for the entire distribution.  I am
appending the description file from FILESERV for your reference.  I expect
that this will be a stable placement (at least for now).
 
Again, my apologies for any inconvenience this may cause. As always, thanks
to Marcus for his leadership and effort in bringing this part of the
Literate Programming FAQ to us.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
                                 FWEB-FAQ
                                 --------
The FWEB-FAQ package includes Marcus Speh's <marcus@x4u.desy.de> answers to
frequently asked questions about the literate programming tool FWEB.  This
package includes a variety of formats for this file.
 
The principal source file is written in Texinfo.  The distribution now has
a very simple Makefile for processing that source.  Version 2.90 of the
macro file "texinfo.tex" is included, which allows you to run plain TeX on
the Texinfo source to obtain a DVI file (without index).  A DVI file and a
Postscript file (with index) are still included to satisfy everybody's
needs.
 
To retrieve the complete set of files, include:
 SENDME FWEB-FAQ
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu).
To retrieve a specific file, such as FWEB-FAQ.README, include:
 SENDME FWEB-FAQ.README
in your mail message to FILESERV.  For anonymous ftp retrieval, the
complete distribution is available as a ZIP archive in the directory
[FILESERV.FWEB-FAQ] on Niord.SHSU.edu (192.92.115.8).
 
Files in this package: (1 Block = 512 bytes)
File                 Blocks  Save file as:
-------------------------------------------------------------------------------
FWEB-FAQ.                        104  fweb-faq
FWEB-FAQ.ANNOUNCEMENT              9  Announcement
FWEB-FAQ.DVI_UUE_1OF5             79  FWEB-FAQ.DVI_UUE
FWEB-FAQ.DVI_UUE_2OF5             79     UUDECODEs to fweb-faq.dvi
FWEB-FAQ.DVI_UUE_3OF5             79
FWEB-FAQ.DVI_UUE_4OF5             79
FWEB-FAQ.DVI_UUE_5OF5             20
FWEB-FAQ.MAKEFILE                 14  Makefile
FWEB-FAQ.PS_1OF7                  79  fweb-faq.ps
FWEB-FAQ.PS_2OF7                  79
FWEB-FAQ.PS_3OF7                  79
FWEB-FAQ.PS_4OF7                  79
FWEB-FAQ.PS_5OF7                  79
FWEB-FAQ.PS_6OF7                  79
FWEB-FAQ.PS_7OF7                  18
FWEB-FAQ.README                   12  fweb-faq.README
FWEB-FAQ.TEXI                    116  fweb-faq.texi
FWEB-FAQ.TEXINFO_TEX_1OF4         79  texinfo.tex
FWEB-FAQ.TEXINFO_TEX_2OF4         79
FWEB-FAQ.TEXINFO_TEX_3OF4         79
FWEB-FAQ.TEXINFO_TEX_4OF4         10
 
Approximate total blocks in full FWEB-FAQ package = 1330
NOTE: The file FWEB-FAQ. is identical to the FAQ.FWEB file found in the FAQ
      package on FILESERV and the FAQ.FWEB file found in [FILESERV.FAQ] on
      Niord.SHSU.edu.
 
From ae1181t@stnfor.ae.ge.com Fri Jan 15 09:23:34 -0500 1993
Date: Fri, 15 Jan 93 09:23:34 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: fweb manual
 
I tried to TeX the manual but it failed due to missing "equiv.tex" file.
Does anyone have this file? Or is there postscript file already made?
thanks
8-)(
 
From marcus@x4u.desy.de Fri Jan 15 16:24:29 +0100 1993
Date: Fri, 15 Jan 93 16:24:29 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: fweb manual
 
|> I tried to TeX the manual but it failed due to missing "equiv.tex" file.
|> Does anyone have this file? Or is there postscript file already made?
|> thanks
 
  /anonymous@lyman.pppl.gov:/pub/fweb/v1.30/manual:
 
  -rw-r--r--  1 4145     589          1554 Jan 14 18:32 equiv.tex
 
   The User's Manual for the (stable) version 1.23a did not
   require equiv.tex, it seems. Anyway, according to the READ_ME
   file you should not expect that all the subdir's of v1.30
   are complete since v1.30 is BETA.
   v1.23 contains DVI output for all the parts
   of the manual. To begin with FWEB that should be sufficient.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
From Eric Fri Jan 15 16:24:29 +0100 1993
Date: Fri, 15 Jan 93 16:24:29 +0100
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Literate Programming?: Why not routines instead
 
LP versus procedures
 
I have been practicing literate programming for a long time and I feel very
happy with it. But very often when I try to explain what literate programming
is about, I get confused if people ask me what the advantages of LP are
compared to working with small independent well documented routines.
 
My experience learns me that there is a big difference indeed, but I untill
now I am not able to make this expicite. Note that Knuth in his 1984 paper
in The Computer Journal also avoided this point
 
My question to you, LITPROG netters, is to give me your opinion and suggestions
with respect to the problem above.
 
Eric W. van Ammers    (ammers@rcl.wau.nl)
 
From leew@cs.utexas.edu Wed Jan 20 15:29:19 -0600 1993
Date: Wed, 20 Jan 1993 15:29:19 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming?: Why not routines instead
 
Eric W. van Ammers writes:
 
 > I have been practicing literate programming for a long time and I feel very
 > happy with it. But very often when I try to explain what literate programming
 > is about, I get confused if people ask me what the advantages of LP are
 > compared to working with small independent well documented routines.
 >
 > My experience learns me that there is a big difference indeed, but I untill
 > now I am not able to make this expicite. Note that Knuth in his 1984 paper
 > in The Computer Journal also avoided this point
 
The FWEB User's manual has a nice discussion of this issue (section 4.11 in
the version 1.23 manual).  If you can't get hold of it, I'm sure John Krommes
would give permission to quote it here.
 
Knuth does address the issue somewhat (I recall) in one of the papers in
his new Literate Programming book.  I'm not sure which one it was.  Does
anyone out there know the reference?
 
		-- Lee Wittenberg
 
From dak@POOL.informatik.rwth-aachen.de Wed Jan 20 22:45:48 +0100 1993
Date: Wed, 20 Jan 93 22:45:48 +0100
From: dak@POOL.informatik.rwth-aachen.de
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Literate Programming?: Why not routines instead
 
>From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
>LP versus procedures
>
>I have been practicing literate programming for a long time and I feel very
>happy with it. But very often when I try to explain what literate programming
>is about, I get confused if people ask me what the advantages of LP are
>compared to working with small independent well documented routines.
>
>My experience learns me that there is a big difference indeed, but I untill
>now I am not able to make this expicite. Note that Knuth in his 1984 paper
>in The Computer Journal also avoided this point
 
Often you cannot really avoid lengthy routines without having to
formulate formal parameters, calling conventions etc.
 
In the WEB approach (not in all LPs, of course), documentation can include
readable mathematical formulas, which I consider a boon.
 
The problem is, that small, well documented procedures do the job as well.
However, you have to formulate calling parameters and other conventions.
Not only that they complicate comprehension slightly, you will simply
not find any programmer intent on serious work doing that.
 
The advantage of LitProg over small, well documented procedures is simply
psychological: splitting into sections a more complicated thing is
easy and done on the fly, splitting a procedure into distinct
procedures is a pain in the, needs additional consideration, reediting
and restructuring. So it simply isn't done.
 
Chances are, when you get both a LitProg program developped in haste
and with only a small amount of documentation beside the code, and
a procedural approach, that an outsider will with the LitProg understand
much more after a reasonable investment of time, than with the normal
program. That is because the structure of the program is more obvious,
although not necessarily by being split into disjoint procedures.
 
From mfy@sli.com Wed Jan 20 22:11:41 GMT 1993
Date: Wed, 20 Jan 93 22:11:41 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Literate Programming?: Why not routines instead
 
Good day all.  You, Eric W., asked:
 
>I have been practicing literate programming for a long time and I feel very
>happy with it. But very often when I try to explain what literate programming
>is about, I get confused if people ask me what the advantages of LP are
>compared to working with small independent well documented routines.
 
The reason you are "confused" is that the question is somewhat like being
asked, "Are you still beating your wife?"  The problem is the presupposition
that is behind the question.
 
There is no such thing as "small independent well documented routines" for any
program of a significant size.  Many people think they write them, but if you
try the only empirical test that matters--namely, seeing what happens when
someone else tries to use these routines when the author is gone--you will
almost certainly find it works badly.  Now, if you confront the author with
this fact, the last thing that will happen is that he or she will say "Oh,
drat.  I guess they weren't well enough documented after all."  What they will
instead say is "that person was just too dumb to understand my code."
 
Please don't take this example too literally; I'm trying to get my point across
in one try, and I need vivid imagery.
 
Unfortunately, I suspect this line of argument will be unconvincing, and you
will have to find another one.
 
There will probably be responses saying they have seen examples where my claim
isn't true, but I am going to disqualify a whole slew of them right off the
top.  I, too, have had cases where the approach seemed to work *when the
original author was available for consultation*.  But this is not
documentation; it is documentation plus folklore, and the folklore is usually
critical.  As far as I'm concerned, documentation is not adequate unless it
would suffice if the original author fell under a bus and became permanently
unavailable to the new programmer.  *This* is rare, and Literate Programming
does not guarantee it, but it makes it much more likely.
 
I also realize that it is possible to get by without really understanding the
code; this approach "works" in roughly the same sense that Communism "worked"
in the U.S.S.R. up to the point it collapsed.
 
Good luck with your discussions.
 
                Michael Yoder
 
From pcolsen@super.org Wed Jan 20 23:35:29 EST 1993
Date: Wed, 20 Jan 93 23:35:29 EST
From: pcolsen@super.org (Peter C Olsen)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: WEB for C++?
 
Perhaps this is a FAQ, but has anyone seen a WEB for C++?  I have a
copy of cpp2latex, but I would like to try a full-fledged WEB.
 
Peter
 
   Peter Olsen, n2ell, pcolsen@super.super.org  ...!uunet!super!pcolsen
          P.O. Box 410, Simpsonville, MD 21150; 410-997-8584
     "Engineering is the art of applying a professional knowledge of
   mathematics and the physical sciences to improve the quality of life"
 
From Glyn Thu Jan 21 09:04:10 GMT 1993
Date: Thu, 21 Jan 93 09:04:10 GMT
From: "Glyn Normington" <NORM@WINVMJ.VNET.IBM.COM>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Re:  Literate Programming?: Why not routines instead
 
>From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
>LP versus procedures
>
>I have been practicing literate programming for a long time and I feel very
>happy with it. But very often when I try to explain what literate programming
>is about, I get confused if people ask me what the advantages of LP are
>compared to working with small independent well documented routines.
>
>My experience learns me that there is a big difference indeed, but I untill
>now I am not able to make this expicite. Note that Knuth in his 1984 paper
>in The Computer Journal also avoided this point
 
Literate programming lets you structure your program into smaller chunks
without the run-time overhead of a subroutine or the effort of writing a macro.
 
It also has the advantage that a literate program is more than a collection of
program fragments as there may be high-level design documentation included
which would not fit nicely into a convention program.
 
The literate programming tools I use allow multiple programs and other files
to be generated from a single literate program (which may itself be split into
multiple files using an imbed mechanism).  This enables better grouping of
programs and data which form abstract datatypes, which our base programming
language does not support.
 
Glyn Normington
CICS Products,
IBM UK Laboratories Ltd,
Winchester, Hants,
England.
 
From Joachim Thu Jan 21 11:35:14 +0100 1993
Date: Thu, 21 Jan 1993 11:35:14 +0100 (MEZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: WEB for C++?
 
You wrote:
>
> Perhaps this is a FAQ, but has anyone seen a WEB for C++?
 
Both FWEB and the new CWEB (not yet out, but RSN) are said to support
C++.
    In fact, my experience shows that they don't -- they support a
reasonable subset. Eg, templates and exceptions are something which is
still missing.
 
Of course, this comments apply only to the WEAVE parts, not to the
TANGLE parts.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	    @d infinity=255 {$\infty$ (approximately)}
							[DEK, in weave.web]
 
From marcus@x4u.desy.de Thu Jan 21 11:39:57 +0100 1993
Date: Thu, 21 Jan 93 11:39:57 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: WEB for C++?
 
>>>>> On Wed, 20 Jan 93 23:35:29 EST, pcolsen@super.org (Peter C Olsen) said:
> Perhaps this is a FAQ, but has anyone seen a WEB for C++?  I have a
> copy of cpp2latex, but I would like to try a full-fledged WEB.
 
  This is a FAQ. Try Question [16] in the fweb-faq:
 
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
 
   - `lyman.pppl.gov' [192.55.106.129] in directory */pub/fweb/faq*,
 
   - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq', and
     `ftp.uni-stuttgart.de' [130.83.55.75] in directory
     `pub/soft/tex/web/fweb'.
 
    either .texi, .dvi, .ps, .info or plain text.
    --Marcus Speh
    --<marcus@x4u.desy.de>
 
From marcus@x4u.desy.de Thu Jan 21 13:52:37 +0100 1993
Date: Thu, 21 Jan 93 13:52:37 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Philonous and Malevolent
 
Cameron Smith <cameron@symcom.math.uiuc.edu>,
Eve Kovacs <KOVACS@fnald.fnal.gov>,
"Francesca M. Borzumati" <francesc@ips102.desy.de>
 
  In my tirade, Philonous (Ph) is a friend and user of the WEB
environment. He is arguing with Malevolent (Ma) who's finally
going to join the LitProg family. Eventually he'll pick up
a better name for himself.
[Malevolent still has a hard time to believe though that CWEB++ is
 the  "only True Web", and he will start and stay with FWEB]
IMO, this socratic dialogue could actually have happened like this.
 
They start as suggested by Eric van Ammers:
 
Ma: "What are the advantages of LitProg compared to working with small
     independent well documented routines?"
 
Ph: "One can still work with small, independent routines.
     They're just better documented now."
 
Ma: "I can do well without TeX for documentation."
 
Malevolent obviously does not believe in DEK. You wonder who's paying
him. Philonous does not really know how to answer to that. He probably
does not like troff. Or maybe Malevolent has got an eye problem?
 
Ma: "In fact, I hate to spend to much time thinking about how
     to explain things to others when I haven't even finished
     the program."
 
Ph: "Before I saw WEB, I wasted lots of time finding the
     right balance between doc and code. With WEB, it becomes
     easier to write doc along with the code. And update it."
 
I have only experiences with FWEB, and I haven't been using it
for more than one year. Before that, quite a lot of my time went
into trying to improve on the delicate balance between documentation
and code. None of my private efforts were really satisfying, though.
Maybe also because (like many people outside of CS) I never really
learnt how to program. Malevolent knows much more about programming,
but he's got other things to do as well:
 
Ma: "But isn't this a hell of a lot of extra effort?"
 
Ph: "When I saw FWEB, I wasn't even put off because of the
     extra effort in learning something new. Though I must confess
     that I asked people in my field of research how long they had
     needed to get accustomed to the new tool."
 
Since then, I freely give away the magic number of "10 days"---
if you know [La]TeX and the language(s) you want to code in.
 
Ma: "Ok,Ok,Ok. Now, if you compare how much time it costs you
     and how much you gain?"
 
(Malevolent is a tough calculator,it seems. He obviously got
 the message of the zeitgeist.)
 
Ph: "I cannot speak for you. LitProg also is a matter of taste.
     It is a useful tool for me. It definitely increased my level
     of reflection upon what I was doing.
        It saves me time because the programs mostly *do* run in
    the first place - it costs me time because I now like to treat
    many otherwise neglectable pieces of code like little diamonds -
    and cannot be sure that this will pay besides aesthetics."
 
Ma: "Of course I have heard about WEB. But I do not know anyone
     who is practicing it, really."
 
(Later, Philonous will tell him about the LitProg list.)
 
Ph: "True. The `evangelization' part sometimes is the most painful.
     There's no company working for WEB's success. No commercials
     placed. Thus, it definitely costs time because I am trying to
     convince my colleagues that they should try *WEB, too. But I am
     a born missionary anyway and so this meets my needs as well."
 
(He did not really have to emphasize the last point...)
 
   The time for our key-hole listening is running out.
It suffices to say that the two are having a lot more to discuss.
At the end, Malevolent (overloaded with manuals, introductory texts,
faqs, eager to try WEB) wants some advice how to evangelize others:
 
Ma: "Assuming you meet someone who's more benevolent than I am--
     how're you proceeding?"
 
Ph: "Upon meeting someone who likewise seems to suffer likewise,
     and who signalizes a genuine interest in learning something
     new, I first show him a HUGE woven output [yes, I am carrying
     such a volume around mainly for that purpose]. Before putting
     the word "WEB" into my mouth I want to hear a SIGH when he is
     confronted with something which looks unlike anything he has
     seen yet. Even better if I have presented some more or less
     complicated program in a talk before: then people are lost
     and WEAVE's output comes handy to explain---it has got tables,
     it has got plots, maybe, an index, a table of contents---
     Fine. Then the victim usually asks: `why did you put up all
       the extra work?'"
 
Ma: "That almost sounds like me, before I had seen the light!"
 
Ph: "Yes, that is the moment of truth indeed."
 
(Timothy Murphy would much better know how to put it, I'm sure ;-)
 
Ph: "I start explaining some things for real [forcing the victim to
     recur to the BEAUTIFUL output in regular intervals determined by
     the amount of healthy scepticism he's mobilizing to shield himself].
     Eventually I show a not-too-complicated .web file. And I give
     him the speech which I gave you already, my friend.
     Of course: If I have a FWEB-FAQ (*) output at hand,
     I'll pass it to him, too."
 
You have to judge whether this may happen with your
colleagues in the same way. Mine are definitely special
in that many of them are used that everything comes to
them pre-digested. If that is not the case, they'd
rather cut on their needs: for fine documentation, for
well-structured code etc. Probably this will not hold
for the majority of LitProg's readers.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
----------------------------------------------------------------------
(*)
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
   - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq/fweb'
   - `ftp.uni-stuttgart.de' [130.83.55.75] in directory
     `pub/soft/tex/web/fweb/FAQ'.
   - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq'
     (Texinfo/text only)
 
    either as .texi, .dvi, .ps, .info or plain text file.
 
       //////////////////////////////////////////////////////////
      //   marcus@x4u.desy.de   //  Marcus Speh               //
     //  [131.169.30.33]       //  II. Inst. f. Theor. Phys. //
    // Phone: (040) 8998-2260 //  Luruper Chaussee 149      //
   // FAX: (040) 8998-2267   //  2000 Hamburg 50 / Germany //
  //////////////////////////////////////////////////////////
 
From koopman@sgi84.ctc.com Thu Jan 21 08:35:12 -0500 1993
Date: Thu, 21 Jan 93 08:35:12 -0500
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Literate Programming?: Why not routines instead
 
In a message of 20 Jan 1993, Eric W. van Ammers <AMMERS@RCL.WAU.NL> writes:
>  I have been practicing literate programming for a long time and I feel very
>  happy with it. But very often when I try to explain what literate programming
>  is about, I get confused if people ask me what the advantages of LP are
>  compared to working with small independent well documented routines.
>    ...
>  My question to you, LITPROG netters, is to give me your opinion and suggestions
>  with respect to the problem above.
 
I am highly underqualified to respond to this question, therefore, I
feel it is my responsibility to broadcast my naiveity by the widest
distribution channel to which I have access, namely, the net.  So ....
 
I admit only limited "book knowledge" of Literate Programming,
including information from texts, journals, magazines and coffee
houses.  Perhaps others, like Eric W. van Ammers, who have first-hand,
experiential knowledge of LP can judge the validity of the following
benefits which I have presumed.
 
First, and foremost, LP provides associativity or "links" between the
comments and the coding.  This seems obvious in the name "Web" and a
plausible influence on the name choice.  This associativity knowledge
is used, primitively, by LP compilers as I know them.  That is, the
links are used strictly as handles to the associated information.
However, this associativity allows for "meta-compiler" activities not
easily supported by well-documented code which is not LP.  The
meta-compiler activities could include such actions as automated
commonality detection leading to abstraction via machine reasoning.
With limited natural language processing of the comments, in
conjunction with the associations identified by the code linkage,
elements of the code such as contexts and intention may be derived.  A
meta-compiler which interprets software with such abstract knowledge
makes possible software engineering methods I can not even imagine at
this time.  Advanced compilers could be developed which perform
abstract knowledge interpretation of well-documented modules, but LP
should make such activities easier.  Qualified comments about
intentional programming are requested, I merely prattle.
 
It also seems LP can help to bridge the gap between the languages.
Being unlikely that one code paradigm can offer the "right choice" for
all programs, LP should help in designing and maintaining large
programs.  Such are often composed of large subprogram modules in
different languages.  This requires an LP system which accepts more
than one compiled language code component, e.g., C, C++, Pascal and
Smalltalk.
 
Mike Koopman                          e-mail:  koopman@server1.ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904  USA               ICBM:  40-15'N-78-50'W
Std. Disclaimer:  Similarity to anyone living or dead is coincidental.
 
From Timothy Thu Jan 21 14:31:42 GMT 1993
Date: Thu, 21 Jan 93 14:31:42 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: WEB for C++?
 
> Perhaps this is a FAQ, but has anyone seen a WEB for C++?  I have a
> copy of cpp2latex, but I would like to try a full-fledged WEB.
 
The latest version of CWEB is called cweb++2.9 ,
and seems to cover C++.
Unfortunately it doesn't appear to have been released officially,
although it has been about for some time.
 
Could we have it now, please, Silvio and Don (Levy & Knuth)?
Please.
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Roger_Alexander@rock.intersolv.com Thu Jan 21 07:37:49 -0800 1993
Date: Thu, 21 Jan 93 07:37:49 -0800
From: Roger_Alexander@rock.intersolv.com
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: CWEB++
 
How can one obtain the latest copy of CWEB++ ?
 
Thanks,
 
Roger Alexander
roger_alexander@intersolv.com
 
From Silvio Thu Jan 21 07:37:49 -0800 1993
Date: Thu, 21 Jan 93 07:37:49 -0800
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: WEB for C++?
 
> From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
 
>     In fact, my experience shows that [FWEB and the new CWEB]
> don't [support C++] -- they support a
> reasonable subset. Eg, templates and exceptions are something which is
> still missing.
 
There is now support for templates in CWEB.  It is still
being tested.  I don't know what "exceptions" are.
 
Silvio
 
From Zdenek Thu Jan 21 10:59:27 MDT 1993
Date: Thu, 21 Jan 93 10:59:27 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: LP / procedures
 
At the beginning I would extend the postulate about non-existence of small
well documented procedures. From my own experience I know that my own small
well documented procedures do not work when transferred into another program
half year later. However, I can see how procedures can live together with LP.
 
I am now webifying my old C++ programs. During past non-literate times I develo
ped a buch of general procedures and pure virtual classes which I put into
private libraries in order to save compilation and linkage time. My intention
for the future is to write such procedures and classes in web, compile them
separately and place them into libraries. In this way I would take advantages
of both LP and independent procedures and moreover I will save disk space
since good web files tend to be long.
 
Regards
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `           ~~~  ~~/ '  '  ~~~
                              Zdenek Wagner______/
 
From dak@POOL.informatik.rwth-aachen.de Thu Jan 21 23:20:05 +0100 1993
Date: Thu, 21 Jan 93 23:20:05 +0100
From: dak@POOL.informatik.rwth-aachen.de
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Philonous and Malevolent
 
Oops, wrong subject. Well one obvious argument for webs over small, well
documented routines is especially nice: Ask the offender, who hopefully
believes in small routines, how often it has happened that she wished the
measure of indents was smaller than 8 because her lines wrapped
when correctly indenting. Oh, she indents only 4? How is one supposed
to immediately see what belongs together? Oh, use a ruler?
 
Well, how am I supposed to know what this third brace from the bottom in
this small, only 2-page procedure, belongs to, so that I know what the if
before that is about? Hmmmm, interesting.
 
Does she know the >> and << commands from vi? Oh, she uses them all the
time? Appealing.
 
Obviously, anybody who gets along that great does not need LitProg.
 
From Yves Fri Jan 22 09:02:23 +0100 1993
Date: Fri, 22 Jan 1993 09:02:23 +0100
From: Yves Arrouye <arrouye@aquilon.imag.fr>
Reply-To: LitProg@SHSU.edu
To: Litprog@SHSU.edu
Subject: WEB support for Objective C?
 
Does anybody know if there is a web supporting Objective C, or if somebody
is currently working on adding such a support to fweb?
 
--
Elle e'tait comme je vous la raconte sans que vous                 Yves Arrouye
  puissiez voir son visage ni entendre ses paroles,     arrouye@mistral.imag.fr
pas plus que je ne l'ai vu ni ne les ai entendues,         arrouye@imag.imag.fr
moi qui pourtant les ai si bien connus.                        (33) 76 57 48 61
 
From Eric Fri Jan 22 09:02:23 +0100 1993
Date: Fri, 22 Jan 1993 09:02:23 +0100
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Information please
 
LP versus procedures
 
With regard to my problem of LP versus procedures, Lee Wittenberg writes:
 
>The FWEB User's manual has a nice discussion of this issue (section 4.11 in
>the version 1.23 manual).  If you can't get hold of it, I'm sure John Krommes
>would give permission to quote it here.
 
>Knuth does address the issue somewhat (I recall) in one of the papers in
>his new Literate Programming book.  I'm not sure which one it was.  Does
>anyone out there know the reference?
 
I have the following questions:
    -	Is the FWEB User's manual FTP-able and if so, from which node (I could
	not find it on NIORD) or
    -	can someone supply a fax-copy of the above referred section to
		Eric W. van Ammers
		Computer Science Department
		Wageningen Agricultural University
		fax: +31 (0)8370 84731
    -	Who can give me a more precise reference to Knuth's discussion on this
	point.
 
Eric W. van Ammers    (ammers@rcl.wau.nl)
 
From George Fri Jan 22 09:48:55 CST 1993
Date: Fri, 22 Jan 1993 09:48:55 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: RE: Information please
 
On 22 Jan 1993 09:38 +0000 (GMT), "Eric W. van Ammers, LUW, tel:
(+31)8370-83356" <AMMERS@RCL.WAU.NL> posted:
> With regard to my problem of LP versus procedures, Lee Wittenberg writes:
> 
> >The FWEB User's manual has a nice discussion of this issue (section 4.11 in
> >the version 1.23 manual).  If you can't get hold of it, I'm sure John Krommes
> >would give permission to quote it here.
> 
> >Knuth does address the issue somewhat (I recall) in one of the papers in
> >his new Literate Programming book.  I'm not sure which one it was.  Does
> >anyone out there know the reference?
> 
> I have the following questions:
>     -	Is the FWEB User's manual FTP-able and if so, from which node (I could
> 	not find it on NIORD) or
>     -	can someone supply a fax-copy of the above referred section to
> 		Eric W. van Ammers
> 		Computer Science Department
> 		Wageningen Agricultural University
> 		fax: +31 (0)8370 84731
>     -	Who can give me a more precise reference to Knuth's discussion on this
> 	point.
 
The manual is contained within the distributions of FWEB.  However, I just
unpacked the manual directory and created the manual, which now appears on
Niord.SHSU.edu (192.92.115.8) in [FILESERV.FWEB]FWEBMAN-V1_23.* in
PostScript as well as the raw DVI file.  Since we don't have make on our
VMS machine, I simply tex'xed the fwebman.tex file (which appears to have
done everything as advertised in the Makefile).  Note that this is a 168
page document (I didn't look for the specific section to determine its
size).
 
Anyway, it's there now if you want to retrieve it.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Timothy Fri Jan 22 17:44:13 GMT 1993
Date: Fri, 22 Jan 93 17:44:13 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB++
 
> How can one obtain the latest copy of CWEB++ ?
 
You could try writing to Silvio Levy <levy@math.berkeley.edu>.
 
(Just going into my deepest bunker
to avoid Silvio's long-range missiles ...)
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From tfj@apusapus.demon.co.uk Fri Jan 22 23:27:19 GMT 1993
Date: Fri, 22 Jan 93 23:27:19 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: A programmer's first use of Literate Programming
 
I'm five days into my first real use of Literate Programming. I thought
that it might be of interest to some to read my observations.
 
Firstly, some background; I'm a programmer of approx 15 years experience. I
would claim that I write good code but with the usual slips in it. Like the
other day when I type + rather than - in an atoi type routine! My
programming style can best be described as "middles-out" neither "top-down"
nor "bottom-up" but expoliting both strategies simultaneously.
 
The second bit of background, I attended the London meeting where DEK gave
his first presentation of Literate Programming. I knew this was IT. This
was a methodology that I could use without changing my style or habits but
which would give them some rigour and provide me with a "mechanical" aid to
organise the pieces into the final program. None of my colleagues who
attend that meeting saw the necessity for what we know of as WEB.
 
The third bit of background. I'd ban programmers from using terminals for
program development! They should have to rely upon decks of cards and have
to run up seven flights of stairs to submit their deck for its only run of
the day. Well that's what I had to do when I started 15 years ago. However,
I firmly believe that the quality of my code dropped dramatically the day I
had access to a terminal. When I used a batch system I did all those things
that we know we should do: desk checking, dummy runs, peer review.
 
Now to today. The project I'm involved in is to convert data from one
proprietary format (USMARC) to another! The target format is very simple.
Unpicking the rats nest of MARC format is not simple. Therefore I decided
to use WEB (CWEB in reality) to write this convertor.
 
I've so far not tried to compile the code for real and I don't have TeX
readily available! I'm writting the application in the office but TeX is
only installed on a PC at home. Weave and Tangle are installed at both
``sites''. I run the WEB source through cweave fairly frequently at check
that there are no sections missing (or more likely mis-speelt); a couple of
times I've run the generated C code through a compiler which has picked up
a few mis-typed identifier names.
 
Whilst I've been working on this program I've been amazed at the ease with
the code can be written. I'd probably have written the same amount by now.
I'd have tried compiling it endless times and gotten more and MORE and
MOREEE frustrated. Using WEB has allowed me to concentrate upon the
microscopic concerns without having to be so concerned with the macroscopic
structure. Yet I was surprised by the ease with which I could flip between
the sections and still hold the whole structure in my head at the same
time. Even to the point of changing a major data structure mid-way, the
effect that this would have had upon me in the past would only have been
overshadowed by the effect upon the code itself. As it is the changes are
very localised into one or two sections and the knock on effect was
non-existant.
 
I have delayed running the woven output through TeX until tonight. The only
problem with this was that I'm running CWEB 2.8 on the office VAX and 2.7
on my PC. When I saw the output I started to read and there it was (or
rather there they were) errors. Sure I'd have found them eventually when I
got a segmentation fault or an access violation but it was just like the
early days, spot the errors when their still on the desk. Think of the
journey home as the climb up those seven flights of stairs. ;-)
 
My boss wont apprecaite the use of CWEB. My current boss wasn't one of
those who hear DEK speak indeed they dont even know how to program, they'll
only see that the task is complete. It'll be seen as an unecessary
complication! But I'll know that the code is solid and that it'll work
properly even in the presence of incorrect data. The customer will be
unaware as well.
 
A few things could make Literate Programming even better. A Windows based
WEB developement editor that caught mis-typed fragment names, that detected
errors in the C code (such as mis-spelt identifier names).
 
I glad that I went to that lecture all those years ago, I've been
infatuated with WEB ever since but today I fell in love. :-)
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England
email: tfj@apusapus.demon.co.uk                               radio: G6AJG
phone: +44 (0)923 776436
 
From George Sun Jan 24 15:06:39 CST 1993
Date: Sun, 24 Jan 1993 15:06:39 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: RE: A programmer's first use of Literate Programming
 
On Fri, 22 Jan 93 23:27:19 GMT, Trevor Jenkins <tfj@apusapus.demon.co.uk>
posted a very good overview (at least in this totally naive watcher's
opinion) of first efforts at CWEB.  Quite honestly, I will probably never 
appreciate what it is that is being accomplished by Literate Programming
nor what is facilitated on LitProg because I am not (nor do I really desire
to be) a programmer.  I can read just enough code to be dangerous; indeed
that's why we have the specialists in our Computer Services division as
well as those of you on this list.  As a long-time (18 years now; gosh, I'm
a dinosaur) non-programming user, I can appreciate his comments on limited
runs, flights of stairs, cards, etc. (everyone should have to do that at
least briefly to really appreciate where computing has moved in a
relatively short time period).  One point in the post which I would like to
comment on, though:
 
> My boss wont apprecaite the use of CWEB. My current boss wasn't one of
> those who hear DEK speak indeed they dont even know how to program, they'll
> only see that the task is complete. It'll be seen as an unecessary
> complication! But I'll know that the code is solid and that it'll work
> properly even in the presence of incorrect data. The customer will be
> unaware as well.
 
This is exactly where Literate Programming needs to be developed!  If my
understanding of what the WEB-type family of tools is correct, Literate
Programming is very likely the most economic way of writing available to
date.  While the initial project may or not have been expedited, it is my
guess that revisions are significantly easier since the original code
fragments are intentionally and by design better documented.  The customer,
while initially unaware of how what got where, will be aware that at least
it did.  The customer will very likely need some form of support, if not
another complete overhaul of proprietary-to-proprietary formats sometime in
the future since that appears to be the nature of competition in
proprietary software.  When those times come, again assuming I am cognizant
of what Literate Programming allows, the process should be somewhat more
streamlineable.  At that point, your boss will be appreciative (or at least
should be).
 
Recognizing the managerial aspects of Literate Programming may very soon be
a topic I pursue in the study of economics (occasionally I have to satisfy
my poobahs that what I do on the net has something to do with the field of
economics, so why not?).  Are my views outlined above misguided?  If not, I
may have stumbled upon a gold mine of research topics and will willingly
serve as a naive disciple attempting to win converts in the managerial side
on the advantages of Literate Programming.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From gilligan@central.bldrdoc.gov Sun Jan 24 21:37:04 MST 1993
Date: Sun, 24 Jan 93 21:37:04 MST
From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: A programmer's first use of Literate Programming
 
George D. Greenwade writes about the need to make managers more aware
of the benefits of literate programming as a tool to enhance the
efficiency of programmers. While I am a novitiate being converted to
LitProg in my own programming, I fear that for people who have
different concerns than mine will not agree with its benefits. (I am a
scientist and I'm always most concerned that my programs produce the
correct results---hence LitProg extends what I've always tried to do
in my comments: to make sure that I document exactly what I think I'm
doing so that years later, when I discover an anomalous result I can
understand what I thought I was doing and whether the problem arises
from implementing my strategy incorrectly or from using a flawed
strategy.  The ability to typeset equations is that much more of a
blessing.)
 
I fear that after looking at many of the extant Literate Programs
(TeX, METAFONT, bibTeX, etc.) one might conclude that to do literate
programming, she must first rewrite all the systems libraries and
stuff the rewritten routines into each literate program. (Why are the
basic character I/O routines present in TeX, METAFONT, and bibTeX
rather than stuffed into a library? This repetition of identical
source code in three different programs seems like something that
would make errors more likely since there is now the added problem
that when one program is updated, it is out of synch with the others.
Also, this kind of thing could cost more money, since now the
programmer must spend more time keeeping the three programs
synchronized.
 
The kludges that are necessary to keep common.w and common.h in CWEB
synchronized (there is no mechanism to handle changes to included
files and according to Silvio Levy, there are some bugs in wmerge; and
there is no mechanism to have a web file output another web file
containing declarations and prototypes---this feature would be a great
boon to program maintenance) illustrate the difficulties that emerge in
writing a small suite of related programs in the current literate style.
 
Clearly literate programming needs to evolve significantly if it is to
achieve the status of many of the other popular methods that have come
along.  I think that every zealot of LP should read carefully the
criticism of Knuth's word-frequency program from the Programming
Pearls column.  There is a lot of merit in that criticism and LP
devot\'es should pay attention.  However, thanks to Knuth and Levy
(and others like Krommes and Ramsey) there is a solid foundation on
which to experiment and build.
 
By confining my attention to some things I see as deficits to LP
tools, I do not mean to denigrate them---there are many good tools; I
just think that their merits are evident to most of the readers of
this list and do not need to be repeated. Personally, I am
particularly fond of CWEB even with the blemishes I have mentioned,
for it is a tool of manageable complexity, so I can understand it and
modify it---FWEB is just too big for me to understand in the amount of
time I am willing to give it.
 
---Jon
 
Disclaimer --- The government probably disagrees with my opinions.
 
From marcus@x4u.desy.de Mon Jan 25 15:01:44 +0100 1993
Date: Mon, 25 Jan 93 15:01:44 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: A programmer's first use of Literate Programming
 
>>>>> On Sun, 24 Jan 93 21:37:04 MST, Jonathan M. Gilligan said:
> Personally, I am particularly fond of CWEB even with the blemishes
> I have mentioned, for it is a tool of manageable complexity,
> so I can understand it and modify it---FWEB is just too big for me
> to understand in the amount of time I am willing to give it.
 
I agree with most of the other statements by Jonathan.
I do not agree with his statement on FWEB being "just too big":
FWEB is built on CWEB.  Due to excellent support by John Krommes,
it has evolved into a very stable tool. If you do not insist on
modifying it, there is no need to "understand" more of FWEB than
of CWEB. I stick to my previous statement on this list that it won't
take you more than 10 days to get used to FWEB [provided that you do
not have to learn [La]TeX, your programming language of choice, nor
how to use an operating system].
  Moreover, for people who want to program in C++/Fortran-77
[-90]/ratfor, there is no alternative (yet). I know there are
other tools who may, in principle, be adapted to any programming
language, but I am thinking of someone who'd like to start right
away without extensive hacking.
  It is true that FWEB has a richness of structure which is apt to
confuse the novice. He should keep in mind thought that there's no
reason (besides sheer curiosity) why he shouldn't restrict himself
to a small number of features. These will suffice to use FWEB e.g.
for better bookkeeping/documentation and program-formatting and
thereby satisfy a user's basic needs. While your needs grow
along with your skills, you may take advantage of FWEB's superiority,
since FWEB has many features built-in which are not shared by other
WEB tools.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
ps. Nevertheless,
    we're waiting for a volunteer to assemble the cweb-faq ;-)
------------------------------------------------------------------------
   FWEB has got a list of Frequently Asked Questions on LitProg.
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
   - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq/fweb'
   - `ftp.uni-stuttgart.de' [130.83.55.75] in directory
     `pub/soft/tex/web/fweb/FAQ'.
   - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq'
     (Texinfo/text only)
 
    either as .texi, .dvi, .ps, .info or plain text file.
 
From bart@cs.tamu.edu Mon Jan 25 11:44:24 -0600 1993
Date: Mon, 25 Jan 93 11:44:24 -0600
From: bart@cs.tamu.edu
Reply-To: LitProg@SHSU.edu
To: roger_alexander@rock.intersolv.com
Subject: CWEB C++ version
 
I suggest that you wait and watch for its availability.
Silvio has made it quite plain that it is in testing.  I think
that anybody who is willing to make such a contribution like
that should recieve the courtesy from us of living with his
schedule for testing and releasing.
 
In a previous message from our moderator:
 
In the interim, Cameron Smith <cameron@symcom.math.uiuc.edu> noted:
> CWEB v2.8 was released last October, so probably the best thing for you to
> do is to grab that directly from the source (labrea.stanford.edu,
> 36.8.0.47).  That should tide you over until next month, when CWEB v2.9++
> (featuring support for C++ and ANSI C) is released (as Silvio Levy
> indicated in a previous note).  I believe that v2.8 came out during the
> unfortunate interval when a combination of George's illness and hardware
> problems with the server prevented updating the archives, and it probably
> got overlooked.
 
The C++ support of FWEB is another alternative.
 
Bart Childs
 
From lenny@hobbs.hunt.inmet.com Mon Jan 25 11:54:03 PST 1993
Date: Mon, 25 Jan 93 11:54:03 PST
From: lenny@hobbs.hunt.inmet.com (Lenny Goodman)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  NIORD.SHSU.EDU
 
I tried doing anonymous ftp at the above site (to get FAQ),
using name "anonymous" and also "guest" and using a password
which was the same as the user-name; but I couldn't connect.
Could you tell me the right user-name and password to use.
Thanks.
   -- Len Goodman
 
From tfj@apusapus.demon.co.uk Mon Jan 25 20:53:46 GMT 1993
Date: Mon, 25 Jan 93 20:53:46 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: RE: A programmer's first use of Literate Programming
 
In message <00967181.9C6234C0.25630@SHSU.edu> George Greenwade comments
upon a part of my earlier posting:
 
> > My boss wont apprecaite the use of CWEB. My current boss wasn't one of
> > those who hear DEK speak indeed they dont even know how to program, they'll
> > only see that the task is complete. It'll be seen as an unecessary
> > complication! But I'll know that the code is solid and that it'll work
> > properly even in the presence of incorrect data. The customer will be
> > unaware as well.
>
> This is exactly where Literate Programming needs to be developed!  If my
> understanding of what the WEB-type family of tools is correct, Literate
> Programming is very likely the most economic way of writing available to
> date.
 
We (on this list) are rational people, unfortunately, my boss appears not
to be. The use of an argument such as the one that you suggest would be
seen as specious to them! Me, I'll use WEB anyway because I am convinced of
the argument. I've tried to get them to realise that expending a little bit
of effort now in order to same time in the future is well worth-while is
only greeted with "we dont do that sort of thing"!
 
This has been a somewhat personal comment but this is the sort of up-hill
fight that us Literate Programmers must contend with.
 
On more exciting things I've got some other comments upon the use of WEB
which I'll write up at the end of the week (which ought to be the end of
the project) so that a fuller picture can be had. I just wish that I could
provide quantative data rather than qualative assessments.
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England
email: tfj@apusapus.demon.co.uk                               radio: G6AJG
phone: +44 (0)923 776436
 
From George Mon Jan 25 15:49:58 CST 1993
Date: Mon, 25 Jan 1993 15:49:58 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  NIORD.SHSU.EDU
 
On Mon, 25 Jan 93 11:54:03 PST, Lenny Goodman <lenny@hobbs.hunt.inmet.com>
posted:
> I tried doing anonymous ftp at the above site (to get FAQ), using name
> "anonymous" and also "guest" and using a password which was the same as the
> user-name; but I couldn't connect. Could you tell me the right user-name
> and password to use.
 
The host name is Niord.SHSU.edu (casing shouldn't matter, at least as far I
am aware) and the IP address is 192.92.115.8.  The username "anonymous" is
supported (and since it is a VMS platform, casing positively doesn't
matter) and we strongly prefer for you to use your real username as your
password (we keep a log of activity and know what your IP address is when
you connect; your password in this case ought to be something along the
lines of lenny). 
 
The username "guest" is not supported (unless someone's been messing around
with something and I'm unaware of it).  Oh, about that activity log, no one
ever really looks at it, except to track traffic, so you needn't worry
about it (gotta keep the internal auditor happy). 8-)
 
My suspicion is (a) you were unable to connect due to a DNS problem (i.e.,
a line drop for some reason) or (b) there were already too many anonymous
ftp users logged in and you were bumped (we don't have a message to tell
you about that -- sorry -- we can only handle 50 anonymous users at any
point in time and we've been near that almost every day recently).
 
Looking forward to the final installation of the T1 line,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Timothy Mon Jan 25 23:04:38 GMT 1993
Date: Mon, 25 Jan 93 23:04:38 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB C++ version
 
> I suggest that you wait and watch for its availability.
> Silvio has made it quite plain that it is in testing.
 
Has he made it clear?
Several people wrote to me when I posted the tiny changes
to the (unposted, unofficial, unrecognised) CWEB2.9++
necessary for Borland-C,
asking me how I heard of it.
 
> I think
> that anybody who is willing to make such a contribution like
> that should recieve the courtesy from us of living with his
> schedule for testing and releasing.
 
I agree that we all owe Silvio gratitude for what he has done,
and is continuing to do.
I don't agree with the courtesy thing (as your late President would say).
When a beta-version of software is announced,
there is an obligation IMHO to circulate the public version
with minimal delay.
 
For one thing, I imagine many LitProggers
are wondering like me about the relative merits
of CWEB and FWEB for C++;
so the CWEB++ announcement puts a sort of embargo on FWEB.
 
The great selling point of CWEB lies in those magic initials, DEK.
Sadly, perhaps, I don't believe any other version of WEB
is likely to make it in the outside world
(outside TeXland, I mean).
Almost all the interest in WEB, and Literate Programming,
in the universe at large
arises from its association with Knuth and with TeX.
 
For this reason CWEB carries much more weight
than just another version of WEB.
It carries the Nihil Obstat, or Imprimatur, of our Pope.
 
> In a previous message from our moderator:
>
> In the interim, Cameron Smith <cameron@symcom.math.uiuc.edu> noted:
> > CWEB v2.8 was released last October, so probably the best thing for you to
> > do is to grab that directly from the source (labrea.stanford.edu,
> > 36.8.0.47).  That should tide you over until next month, when CWEB v2.9++
> > (featuring support for C++ and ANSI C) is released (as Silvio Levy
> > indicated in a previous note).
 
When was this posted?
Which month is next month?
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Timothy Mon Jan 25 23:22:33 GMT 1993
Date: Mon, 25 Jan 93 23:22:33 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: A programmer's first use of Literate Programming
 
> Why are the
> basic character I/O routines present in TeX, METAFONT, and bibTeX
> rather than stuffed into a library? This repetition of identical
> source code in three different programs seems like something that
> would make errors more likely since there is now the added problem
> that when one program is updated, it is out of synch with the others.
> Also, this kind of thing could cost more money, since now the
> programmer must spend more time keeeping the three programs
> synchronized.
 
Surely this was a necessary consequence of the choice of Pascal?
At the time when TeX was translated from SAIL to Pascal, at least
(I don't know if this is still true of official Pascal)
there was no such thing as a Pascal library --
a Pascal program was a single indivisible monstrosity.
 
Actually, WEB did meet this problem to some extent,
as quite large globs of code
were carried wholesale from one program to another.
 
But doesn't Levy's CWEB answer your point completely?
His common.w (shared by ctangle and cweave)
serves exactly the need you describe.
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Silvio Mon Jan 25 23:29:21 -0800 1993
Date: Mon, 25 Jan 93 23:29:21 -0800
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB C++ version
 
In response to various comments made about beta versions of cweb.  The
next release of cweb will be 3.0 (essentially the same as 2.9++, which
has been in testing but hasn't been released).  We expect to release
it in mid-February, but there is no guarantee.
 
People interested in testing the beta version are welcome to do so.
They should write to me and I'll send it to them.  "Beta testing"
means actually testing, ie. finding shortcomings.  (Bug fixes are most
appreciated.)
 
The release of cweb 3.0 is not meant to discourage the use of FWEB.
 
Silvio Levy
 
From Joachim Tue Jan 26 10:51:45 +0100 1993
Date: Tue, 26 Jan 1993 10:51:45 +0100 (MEZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: CWEB C++ version
 
Timothy Murphy wrote:
>
> > I think
> > that anybody who is willing to make such a contribution like
> > that should recieve the courtesy from us of living with his
> > schedule for testing and releasing.
>
> I agree that we all owe Silvio gratitude for what he has done,
> and is continuing to do.
> I don't agree with the courtesy thing (as your late President would say).
> When a beta-version of software is announced,
> there is an obligation IMHO to circulate the public version
> with minimal delay.
 
IMHO: Jargon. Acronym for In My Humble Opinion. Used to flag as an opinion
something that is clearly from context an opinion to everyone except the
mentally dense. Opinions flagged by IMHO are actually rarely humble. IMHO.
        (source: third unabridged dictionary of chuqui-isms).
							[Chuq Von Rospach]
 
There is *never* an obligation associated with free software. Except
in the eyes of arrogant people, who don't care that others who spent
work on free software have also other things to do.
    As long as you don't pay for it: shut up.
 
--
Joachim
 
From Timothy Tue Jan 26 16:29:44 GMT 1993
Date: Tue, 26 Jan 93 16:29:44 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB C++ version
 
> There is *never* an obligation associated with free software. Except
> in the eyes of arrogant people, who don't care that others who spent
> work on free software have also other things to do.
>     As long as you don't pay for it: shut up.
 
I doubt very much if Silvio Levy shares your viewpoint;
I know Don Knuth does not.
 
Philanthropy _does_ in fact create an obligation
on the part of both giver and receiver.
"The quality of mercy is not strained ..."
 
Thank goodness the pillars of TeX --
among whom I would include Levy,
with Knuth, Lamport, Shoepf, Rokicki, Jones, MacKay, Greenwade, Berry,
etc, etc --
don't take your legalistic and utilitarian attitutude.
 
I regard TeX, like GNU, as evidence
that there does exist a valid view of the world
beyond that so inelegantly expressed in your final remark.
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From gilligan@central.bldrdoc.gov Tue Jan 26 10:08:05 MST 1993
Date: Tue, 26 Jan 93 10:08:05 MST
From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: A programmer's first use of Literate Programming
 
Timothy Murphy writes:
 
   > Why are the
   > basic character I/O routines present in TeX, METAFONT, and bibTeX
   > rather than stuffed into a library? This repetition of identical
   > source code in three different programs seems like something that
   > would make errors more likely since there is now the added problem
   > that when one program is updated, it is out of synch with the others.
   > Also, this kind of thing could cost more money, since now the
   > programmer must spend more time keeeping the three programs
   > synchronized.
 
   But doesn't Levy's CWEB answer your point completely?
   His common.w (shared by ctangle and cweave)
   serves exactly the need you describe.
 
CWEB does answer the need somewhat (although note my cavils about the
difficulty of working with change files for common.h and the fact that
life would be nicer if there were a tool that would let us generate
common.h directly from common.w).
 
However, my point was not that the problem I mentioned in the
paragraph above was irremediable, but that a manager looking at
LitProg as a possible methodology [1] might look at examples of how
LitProg was used and {\em erroneously\/} conclude that this kind of
wholesale repetition was inherent to LitProg.
 
I call upon the LitProg community to provide better examples of
Literate Programming. It would be hard to improve on Knuth's skill as
a programmer, but surely we can stand on his shoulders and write code
in a less Proustian fashion (For a long time, Pascal used to choke on
seven-bit characters...)!  I conclude with a paraphrase of Strunk and
White: eliminate redundant code, eliminate redundant code, eliminate
redundant code. For my part, I'm trying to get used to LitProg by
rewriting in CWEB a curve-fitting program I wrote in grad school.
When (and if) I finish it I'll make it public for criticism.
 
CWEB, of course is a good step in the right direction, but Literate
Programming as a method applied to writing tools to do Literate
Programming is rather like meditating on one's navel (Let us remember
why the LitProg column in CACM folded). We need more examples of good
literate programs that accomplish real tasks (i.e., that are not
simply tools to write literate programs). If many people would supply
code for real literate programs, we could see a diversity of styles
emerge and let these inform our own. (Kudos to Cameron Smith, BTW, for
a step in the right direction for giving us a nice example (although
of a toy program) of multimodule programming under CWEB).
 
[1] Language query: I've always hated the work ``methodology,'' as it
seems to me that it would more appropriately describe a science that
studies methods {\em qua\/} methods---why, then, are so many people,
including myself, unable to break ourselves of the habit of using this
ungainly word when we really mean ``method,'' but don't find that
simple word sufficiently pretentious? Nonetheless, the stuffiness of
the word seems appropriate when discussing managers who tell their
underlings how to think about writing code ;-)
 
---Jon
 
Disclaimer --- The government probably disagrees with my opinions.
 
From marcus@x4u.desy.de Tue Jan 26 18:41:57 +0100 1993
Date: Tue, 26 Jan 93 18:41:57 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Philonous and Malevolent
 
dak> Oops, wrong subject.
 
Not quite: this is Philonous answering. Along with the usual
superfluous portion of (this time, editor) evangelism.
 
dak> Well, how am I supposed to know what this third brace from the bottom in
dak> this small, only 2-page procedure, belongs to, so that I know what the if
dak> before that is about? Hmmmm, interesting.
 
The editor I'm using (GNU Emacs) possesses a (language) mode (for c++,
c, fortran, ada, lisp, ....etc.) which, upon inserting a brace,
invokes (for C++ e.g.)  the function
 
	c++-electric-brace
	  Function: Insert character and correct line's indentation.
 
If the matching brace is still in the visible part of the buffer,
the cursor jumps back and forth, otherwise it tells me which line
precedes the matching other brace.
 
dak> Does she know the >> and << commands from vi? Oh, she uses them all the
dak> time? Appealing.
 
Having seen that, the question remains: who's using vi ?---There is
another ongoing discussion between Malevolent and Philonous on the
superior editor, but I think we can dispense with it. Needless to say
that Philonous is using Mark Motl's superior web-mode for GNU Emacs. Want
to know more? @-> fweb-faq, Question [18].
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
-----------------------------------------------------------------------
   FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg:
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
   - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq/fweb'
   - `ftp.uni-stuttgart.de' [130.83.55.75] in directory
     `pub/soft/tex/web/fweb/FAQ'.
   - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq'
     (Texinfo/text only)
 
    either as .texi, .dvi, .ps, .info or plain text file.
-----------------------------------------------------------------------
 
From gilligan@central.bldrdoc.gov Tue Jan 26 11:42:07 MST 1993
Date: Tue, 26 Jan 93 11:42:07 MST
From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB C++ version
 
Timothy Murphy writes,
 
> I agree that we all owe Silvio gratitude for what he has done,
> and is continuing to do.
> I don't agree with the courtesy thing (as your late President would say).
> When a beta-version of software is announced,
> there is an obligation IMHO to circulate the public version
> with minimal delay.
 
Actually, if beta testing is really testing (and Levy says that he
does mean testing) then it would be silly to make the beta test period
so short that there is a good chance that there will be serious
problems that don't get caught until the new version is officially
released. I applaud Levy for realizing that testing takes time. With
good fortune, we will get a CWEB 3.0 whenever Levy and Knuth think
it's ready and in return for our patience, we will be able to use it
confident that version 3.1 will not need to be rushed out a few months
later (as has happened with many software packages I have paid money
for).
 
It is especially important, if we are serious about converting people to
Literate Programming, that Literate Programming tools written by the
gurus of Literate Programming be completely bug free :-). After all,
how will I convince someone of the advantages of Literate Programming
if he is able to say, ``If LP is so good, why were there so many bugs
in CWEB 3.0, which had the imprimatur of Knuth? If Knuth and Levy
can't write bug-free software using LP, how is it going to help mere
mortals like you amd me?''
 
Meanwhile, if you really need to use C++, FWEB is an option, and so is
Hans Hermann Bode's CWEB-P, based on CWEB 2.7.
 
---Jon
 
Disclaimer --- The government probably disagrees with my opinions.
 
From adnan@odin.icd.ab.com Tue Jan 26 15:22:02 -0500 1993
Date: Tue, 26 Jan 93 15:22:02 -0500
From: adnan@odin.icd.ab.com (Adnan C. Yaqub)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Editing Tools (was RE: Philonous and Malevolent)
 
>>>>> On Thu, 21 Jan 93 23:20:05 +0100, dak@POOL.informatik.rwth-aachen.de said:
dak> Oops, wrong subject. Well one obvious argument for webs over small, well
dak> documented routines is especially nice: Ask the offender, who hopefully
dak> believes in small routines, how often it has happened that she wished the
dak> measure of indents was smaller than 8 because her lines wrapped
dak> when correctly indenting. Oh, she indents only 4? How is one supposed
dak> to immediately see what belongs together? Oh, use a ruler?
 
dak> Well, how am I supposed to know what this third brace from the bottom in
dak> this small, only 2-page procedure, belongs to, so that I know what the if
dak> before that is about? Hmmmm, interesting.
 
dak> Does she know the >> and << commands from vi? Oh, she uses them all the
dak> time? Appealing.
 
dak> Obviously, anybody who gets along that great does not need LitProg.
 
Although I am becoming a LitProg fan, I don't buy any of this
argument.  You see, I use GNU Emacs.  (Maybe she does too.)  I never
have trouble determining what goes with what and I have my `C' indent
set at 2 spaces.
 
Adnan Yaqub (adnan@icd.ab.com)
Allen-Bradley Company, Inc., 747 Alpha Drive, Highland Hts., OH 44143, USA
Phone: +1 216 646 4670 FAX: +1 216 646 4484
 
From stevea@vast.unsw.edu.au Wed Jan 27 10:23:54 +1100 1993
Date: Wed, 27 Jan 93 10:23:54 +1100
From: stevea@vast.unsw.edu.au
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: CWEB C++ version
 
  tim> I agree that we all owe Silvio gratitude for what he has done,
  tim> and is continuing to do.  I don't agree with the courtesy thing
  tim> (as your late President would say).  When a beta-version of
  tim> software is announced, there is an obligation IMHO to circulate
  tim> the public version with minimal delay.
 
	Well, in factual act, Silvio only announced that CWEB++ was in
alpha testing, and did so only to let people know that CWEB was still
under development. I would think it foolish if anyone wanted alpha
versions of software to be released to the public.
	I also consider it a bit foolish to make the beta release fully
available lest the public consider it an official release (come on - how
many people have you come across that really don't know what alpha and
beta releases are?).
	Additionally, Silvio has the responsibility of showing the code
to DEK prior to releasing it, after all, DEK's name is very closely
associated with it, and he should be allowed to veto the release if he
desires.
 
	cheers
	-steve
 
From John Wed Jan 27 10:23:54 +1100 1993
Date: Wed, 27 Jan 93 10:23:54 +1100
From: John Nesbitt <74020.3552@CompuServe.COM>
Reply-To: LitProg@SHSU.edu
To: <litprog@shsu.edu>
Subject: CWEB++ Discussion
 
     I read the back and forth concerning the release of the new
version of CWEB++ with mounting dismay.
 
     In a previous life, I released 'free' software.  This was
transaction processing software which was widely used and
depended upon within a particular community.  I NEVER felt any
legal obligation vis-a-vis release dates and features.  I did,
however, feel a strong moral obligation to the users of my
programs to fix bugs, to add useful features and to release
reliable programs.
 
     I learned through bitter experience to be extremely careful
in releasing beta versions: these things acquire a life of their
own.  It is time-consuming enough to support the 'official'
release without getting calls about old beta versions.
 
     It is a truism that software versions are never released on
time.  In the commercial world which I inhabit, one is paying
real money and often has the option of selecting a different
vendor (but not always: everybody is late).  In the world of
'free' software, I think that one pays in the coin of patience
and understanding for the developer, who doubtless has many other
things on his plate.
 
     On a more general note, I am distressed at the amount of
flaming in this discussion.  This is unfortunate and truly
unnecessary.  To paraphrase: abuse is the last resort of somebody
with a bad argument.
 
                    John Nesbitt, Geneva
 
From tfj@apusapus.demon.co.uk Wed Jan 27 02:08:24 GMT 1993
Date: Wed, 27 Jan 93 02:08:24 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Page 1 is (almost) entirely blank
 
When I run my CWEB source file through CWEAVE (2.7 [pl6]) and then through
TeX page 1 is ``blank''. (Actually it has the page number and the page
heading "CWEB output" and the word from the \ttitlefont call abutted to the
entire text of the \title call.) Is this correct behaviour?
 
I encountered another oddity with the same TeX run. At one point in my
source code I have the following construct
 
\.{message("! usage: MARCIT [-options] MARC_file [TFORM_file [report_file]]"
..}
 
TeX bitches that there's a missing $ sign missing and indicates the _. All
other use of _ are accepted okay so why not here?
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England
email: tfj@apusapus.demon.co.uk                               radio: G6AJG
phone: +44 (0)923 776436
 
From dak@POOL.informatik.rwth-aachen.de Wed Jan 27 11:59:39 +0100 1993
Date: Wed, 27 Jan 93 11:59:39 +0100
From: dak@POOL.informatik.rwth-aachen.de
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Editing Tools (was RE: Philonous and Malevolent)
 
>>>>>> On Thu, 21 Jan 93 23:20:05 +0100, dak@POOL.informatik.rwth-aachen.de said:
>dak> Oops, wrong subject. Well one obvious argument for webs over small, well
>dak> documented routines is especially nice: Ask the offender, who hopefully
>dak> believes in small routines, how often it has happened that she wished the
>dak> measure of indents was smaller than 8 because her lines wrapped
>dak> when correctly indenting. Oh, she indents only 4? How is one supposed
>dak> to immediately see what belongs together? Oh, use a ruler?
>
>dak> Well, how am I supposed to know what this third brace from the bottom in
>dak> this small, only 2-page procedure, belongs to, so that I know what the if
>dak> before that is about? Hmmmm, interesting.
>
>dak> Does she know the >> and << commands from vi? Oh, she uses them all the
>dak> time? Appealing.
>
>dak> Obviously, anybody who gets along that great does not need LitProg.
>
>Although I am becoming a LitProg fan, I don't buy any of this
>argument.  You see, I use GNU Emacs.  (Maybe she does too.)  I never
>have trouble determining what goes with what and I have my `C' indent
>set at 2 spaces.
>
>Adnan Yaqub (adnan@icd.ab.com)
 
Thanks for making my argument abundantly clear. If you need a special
editor mode just to find out what belongs where, you are doing
write-only code, and your listings will not necessarily reveal
the structure on editor-free reading.
 
If your C indent has wandered to merely 2 spaces, you are very likely
not to see the indenting structure when reading a listing, at least
not without a ruler. I was not arguing for complications in writing
code, I was arguing for the readability. And I had brought vi into
the discussion, because I wanted to point out that the use of >>,
and <<, as well as reducing indenting to 4, serves to make highly
indented, and thus not readily understandable when only skimming,
code. That you scoff on the primitivity of the features by vi, and
tell me Emacs does it better, is a sign that you have not got
my point.
 
I was blaming the need to use that features, not the inadequacies
of them. I do not want to have to use a tool merely to read
some code. I want a printout to be understandable as well.
That you have not even got my point is a dangerous sign, because
it implies that programmers take write-only code with high
level of small indentation for granted, and worry only about how
they can produce that with the least effort.
 
From dak@POOL.informatik.rwth-aachen.de Wed Jan 27 12:11:32 +0100 1993
Date: Wed, 27 Jan 93 12:11:32 +0100
From: dak@POOL.informatik.rwth-aachen.de
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Philonous and Malevolent
 
>dak> Oops, wrong subject.
>
>Not quite: this is Philonous answering. Along with the usual
>superfluous portion of (this time, editor) evangelism.
Sorry, but you missed my point. I was not fighting for vi's right to
be the best editor for writing unreadable code.
 
>
>dak> Well, how am I supposed to know what this third brace from the bottom in
>dak> this small, only 2-page procedure, belongs to, so that I know what the if
>dak> before that is about? Hmmmm, interesting.
>
>The editor I'm using (GNU Emacs) possesses a (language) mode (for c++,
>c, fortran, ada, lisp, ....etc.) which, upon inserting a brace,
>invokes (for C++ e.g.)  the function
>
>	c++-electric-brace
>	  Function: Insert character and correct line's indentation.
>
>If the matching brace is still in the visible part of the buffer,
>the cursor jumps back and forth, otherwise it tells me which line
>precedes the matching other brace.
 
Congratulations. So even if the structure of your code is incomprehensible,
you have a good chance of getting it to compile. Shit, I was not
worrying about producing something the compiler would not understand.
I was hoping for the humans.
>
>dak> Does she know the >> and << commands from vi? Oh, she uses them all the
>dak> time? Appealing.
>
>Having seen that, the question remains: who's using vi ?---There is
>another ongoing discussion between Malevolent and Philonous on the
>superior editor, but I think we can dispense with it.
Especially since this discussion was not about editors.
 
>Needless to say
>that Philonous is using Mark Motl's superior web-mode for GNU Emacs. Want
>to know more? @-> fweb-faq, Question [18].
 
If Philonous is using Mark Motl's superior Webmode in order to produce
highly indented, thoroughly nested code, he need not use a web at all.
 
From bart@cs.tamu.edu Wed Jan 27 07:26:56 CST 1993
Date: Wed, 27 Jan 93 07:26:56 CST
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Page 1 is (almost) entirely blank
 
Trevor Jenkins has run into a common pain for starting WEB'ers.
 
The file `limbo.material' is one of the appendages to the source
of the manual for our web-mode.  (We named the file webm-man.tex).
 
I have not created a brand new CWEB in a while, but when web-mode
starts up, it asks for the name of the file for limbo material
to be included and defaults to that file.
 
It then prompts for a `title' of the WEB and edits the inserted
limbo material to create a proper title page.
 
The TeX error is also commonly encountered by beginners (and sometimes
by experienced users).  If you include a comment in C code like:
/* some_variable */ this should be written as
/* |some_variable| */ because TeX reserves the underscore for the
subscript character and is supposed to be used in math mode....
 
Hope it helps.
 
Bart Childs
 
From fulling@sarastro.math.tamu.edu Wed Jan 27 09:30:17 CST 1993
Date: Wed, 27 Jan 93 09:30:17 CST
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  CWEB++ Discussion
 
I think that this discussion has drifted away from its original point:
Last fall most of us got the impression that the release of CWEB++ was
imminent; that was followed by several months of mystifying silence.
Silvio Levy has now confirmed that he hopes for a release within the
next month, thereby saving himself the annoyance of answering many
individual inquiries, I hope.  I think we all understand the problem of
the moving target.
 
Silvio has given us the information we needed, and gone back to work.
I agree with J. Nesbitt that the other disputants should stifle
themselves.
 
					      Steve Fulling
 
From Thompson, Wed Jan 27 09:30:17 CST 1993
Date: Wed, 27 Jan 93 09:30:17 CST
From: "Thompson, David B." <wqdbt@ttacs1.ttu.edu>
Reply-To: LitProg@SHSU.edu
To: "litprog" <litprog@shsu.edu>
Subject: RE: A programmer's first use of Literate Programming
 
I was amused by Jon's ruminations about the word "methodology."  FWIW,
I find its overuse offensive as well.  Another word in this category is
"utilize."
 
Perhaps we should agree to "use" a "method" instead of utilizing a
methodology?  <ducking and running>
 
-=d
 
From Roegel Wed Jan 27 17:16:08 +0100 1993
Date: Wed, 27 Jan 93 17:16:08 +0100
From: Roegel Denis <Denis.Roegel@loria.fr>
Reply-To: LitProg@SHSU.edu
To: LITPROG@SHSU.edu
Subject: bad CWEB formatting (cont'ed)
 
Two weeks ago, I had a question regarding the formatting
of a variable called 'line'.
 
Well, to format it correctly one has to do
 
@f line foo   (for instance)
 
But, when I do this I get---in the TeX file---something broken,
like that:
 
format  line
           foo
 
Is this a known problem ? Is it possible to achieve the right
formatting without printing the line "format line foo" ?
 
Another problem appears in a construct like
 
  if ...
  else {
    struct timeval udate;
    struct tm *pdate;
    gettimeofday(...);
    ...
    }
 
What I get is:
 
   if ...
   else {struct timeval udate;
     struct tm *pdate;
     gettimeofday(...);
     ...
     ...}
 
   (notice also the wrong positionning of the closing brace)
 
I tried to insert @/ after the opening brace or to write @f timeval foo
but it doesn't help. I'm desperately stuck!
 
Any idea ?
 
Thanks in advance.
 
Denis (roegel@loria.fr)
 
PS. And a late thank to those you pointed me to @f the last time.
Sorry for the delay!
 
From fulling@sarastro.math.tamu.edu Wed Jan 27 15:33:45 CST 1993
Date: Wed, 27 Jan 93 15:33:45 CST
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  A programmer's first use of Literate Programming
 
Jonathan M. Gilligan writes:
 
>I call upon the LitProg community to provide better examples of
>Literate Programming.... For my part, I'm trying to get used to
>LitProg by rewriting in CWEB a curve-fitting program I wrote in
>grad school.  When (and if) I finish it I'll make it public for
>criticism.
>
>CWEB, of course is a good step in the right direction, but
>Literate Programming as a method applied to writing tools to do
>Literate Programming is rather like meditating on one's navel
>(Let us remember why the LitProg column in CACM folded). We need
>more examples of good literate programs that accomplish real tasks
>(i.e., that are not simply tools to write literate programs). If
>many people would supply code for real literate programs, we could
>see a diversity of styles emerge and let these inform our own.
>(Kudos to Cameron Smith, BTW, for a step in the right direction
>for giving us a nice example (although of a toy program) of
>multimodule programming under CWEB).
 
After two years of reading about Literate Programming and thinking and
talking about what a great idea it is, over the holidays I finally
wrote my first literate programs.  I took two short programs written 12
years ago in C and redid them in CWEB.  Yes, I know that's not the way
you're supposed to do it, but I wanted my first hands-on experience
with CWEB syntax to be free of extraneous concerns such as correctness
of algorithms.
 
These programs "accomplish a real task": they calculate the terms in an
asymptotic expansion approximating the solution of a system of
differential equations.  They may therefore be of interest as examples
of CWEB that are not computer utilities, such as word-counting
programs.  They are probably short enough (7063 and 11532 bytes) to be
posted directly to the list, but I doubt that George Greenwade would
appreciate that precedent, so I'll ask his advice on how to make them
available.
 
The originals were the first C programs I ever wrote, in 1981.  In 1987
I revised them and added copious comments; at that time I flattered
myself that they were already fairly literate :-).  But the cramped
nature of program comments and especially the impossibility of
including typeset mathematics left the explanatory material
inadequate.  The WEB versions produce 3 times as many printed pages,
but the additional information is well worth it, I think.  I hope that
one can actually understand the purpose of the program now without
reading the associated journal article in SIAM J. Math. Anal.  Of
course, I modularized the programs too (perhaps overdoing it a bit).
 
				   Stephen A. Fulling
				   Professor of Mathematics,
      12 years experience as a second-order C programmer
(percentage of professional life devoted to research = O(epsilon),
percentage of research devoted to computation = O(epsilon))
 
From Timothy Thu Jan 28 18:07:13 GMT 1993
Date: Thu, 28 Jan 93 18:07:13 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB C++ version
 
> 	Additionally, Silvio has the responsibility of showing the code
> to DEK prior to releasing it, after all, DEK's name is very closely
> associated with it, and he should be allowed to veto the release if he
> desires.
 
I'd agree with this, at least,
if in fact it is the reason for the delay.
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Silvio Thu Jan 28 12:17:25 -0800 1993
Date: Thu, 28 Jan 93 12:17:25 -0800
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu
To: tfj@apusapus.demon.co.uk
Subject: Re: Page 1 is (almost) entirely blank
 
> When I run my CWEB source file through CWEAVE (2.7 [pl6]) and then through
> TeX page 1 is ``blank''. (Actually it has the page number and the page
> heading "CWEB output" and the word from the \ttitlefont call abutted to the
> entire text of the \title call.) Is this correct behaviour?
 
It doesn't sound correct, but I can't really figure out what you mean.
I assume you mean the first page of the program (that is, not the
title page)?  Perhaps you should create a minimal file that exhibits
the problem, and mail it to me.
 
> \.{message("! usage: MARCIT [-options] MARC_file [TFORM_file [report_file]]"}
 
The \. is only a TeX macro -- \.{foo} is the same as {\tt foo}.  TeX
has no way to know that _ is meant as a special character in a
verbatim string.
 
> All other uses of _ are accepted okay so why not here?
 
I think the only time _ is treated especially (ie., not as a math
subscript character) is in strings and character constants in C code.
 
Silvio
 
From Thorbjoern Thu Jan 28 21:17:43 MET 1993
Date: Thu, 28 Jan 93 21:17:43 MET
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Editing Tools (was RE: Philonous and Malevolent)
 
dak@POOL.informatik.rwth-aachen.de
 
| If your C indent has wandered to merely 2 spaces, you are very likely
| not to see the indenting structure when reading a listing, at least
| not without a ruler. I was not arguing for complications in writing
| code, I was arguing for the readability. And I had brought vi into
| the discussion, because I wanted to point out that the use of >>,
| and <<, as well as reducing indenting to 4, serves to make highly
| indented, and thus not readily understandable when only skimming,
| code. That you scoff on the primitivity of the features by vi, and
| tell me Emacs does it better, is a sign that you have not got
| my point.
 
Well.  I have never really figured why indenting 8 spaces (with a TAB)
should make C programs that much more readable than anything else bigger
than, say 2.
 
Being a Pascal programmer reluctantly forced into C (the great assembly
language of *real* machines) I have used an indentation of 2 with a very
consequent way of changing it for several years.  My experience shows
this to be more effective than moving code back and forth horizontally
on the page.  And, no,  I do not have bracket-matching in my editor. :-(
 
| I was blaming the need to use that features, not the inadequacies
| of them. I do not want to have to use a tool merely to read
| some code. I want a printout to be understandable as well.
| That you have not even got my point is a dangerous sign, because
| it implies that programmers take write-only code with high
| level of small indentation for granted, and worry only about how
| they can produce that with the least effort.
 
Agreed.  Small identations are, however, not implying unreadable code.
 
--
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From figuei@lutece.rutgers.edu Thu Jan 28 16:30:54 -0500 1993
Date: Thu, 28 Jan 93 16:30:54 -0500
From: figuei@lutece.rutgers.edu (Francisco Figueirido)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: (commented) source code and user documentation in FWEB
 
I have been using WEB (mostly FWEB) for about a year and am very happy with
the results. However, I think (please send flames to my e-mail address, not
to the mailing list!) that the WEB systems that exist today (actually, the
ones I know) have a common problem: they cannot handle very well the users'
documentation (as opposed to the programmer's documentation, that was the
original purpose of WEB). I have been playing a little with the idea of using
FWEB (since it is the only one that understands more than one language) to
write in the same .web file both the source code web AND the user
documentation. The idea, which might not be original, is to use TeX as the
default language and to have in the web file code like this:
 
@ This code will be sent to the file \.{usermanual.tex}.
@a
@O usermanual.tex
\title{MyProgram, A User Manual}
 
This is the user manual for the wonderful program MyProgram.
 
@<Description of the command line arguments@>
 
@ This code will be sent to the \Cee\ file \.{myprog.c}.
@a
@o myprog.c
extern int main(int argc, char **argv) @+ {
  @<Jump according to the command line arguments@> @;
  @<Rest of the code@> @;
}
 
   .
   .
   .
 
@ This fragment handles the command line arguments.
@<Jump according to the command line arguments@>=
  while (argc-- > 0) @+ {
    argv++;
    @<Big switch@> @;
  }
 
@ This section of \TeX\ code describes the command line arguments from a
users' point of view.
@<Description of the command line arguments@>=
\begin{itemize}
  \item[-v] Be verbose
  .
  .
  .
\end{itemize}
 
The rationale is that users (most of the time) couldn't care less about the
internals of the program; they just want a digested and very high level view
of how to interface with the program. And if this interface is complicated or
subject to change it is not a good idea to have separate sources for the
source code and the users' documentation. I would be very interested to know
other people's experiences and (+ or -) comments about this embrionic
proposal.
 
A further note: it would be nice in my opinion to have another start-of-module
symbol, say @w (if not in use), to mark modules as invisible to weave but not
to tangle. In this way one could write the user manual code as
 
@w This code will be sent to the file \.{usermanual.tex}.
@a
@O usermanual.tex
 
and this would not appear in the woven output. This way we can separate
programmer's and users' manuals while keeping them synchronized.
 
	Francisco Figueirido
	email: figuei@lutece.rutgers.edu
	phone: (908)932-3278
 
From Roegel Thu Jan 28 23:34:15 +0100 1993
Date: Thu, 28 Jan 93 23:34:15 +0100
From: Roegel Denis <Denis.Roegel@loria.fr>
Reply-To: LitProg@SHSU.edu
To: LITPROG@SHSU.edu
Subject: \long string in CWEB: how ?
 
Hello,
 
Here is another little problem I face. As a matter of fact, I am
translating some more or less old C programs into CWEB. I really
love to do it, but all possible problems occur. Here is one. With the next
static declaration, Cweave tells me that the string is too long.
How can I override this ?
 
static String   text_translationsD = "\
	<Key>Delete:    DeleteD() end-of-file() delete-previous-character()\n\
	<Key>BackSpace: DeleteD() end-of-file() delete-previous-character()\n\
	<Key>Return:    end-of-file() newline() DispatchD()\n\
	<Key>:		InsertD() end-of-file() insert-char()\n\
        <Btn1Down>:     select-start() \n\
        <Btn1Motion>:   extend-adjust() \n\
        <Btn1Up>:       extend-end(PRIMARY, CUT_BUFFER0) \n\
        <Btn3Down>:     extend-start() \n\
        <Btn3Motion>:   extend-adjust() \n\
        <Btn3Up>:       extend-end(PRIMARY, CUT_BUFFER0)";
 
Thanks in advance for your ideas.
 
Denis. (roegel@loria.fr)
 
From Eric Thu Jan 28 23:34:15 +0100 1993
Date: Thu, 28 Jan 93 23:34:15 +0100
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Who knows ...
 
Promoting Literate Programming
 
I'm trying to promote literate programming, but unfortunately I live in a
hostile environment. So I need hard arguments.
 
It would be an enormous help if I had reports on (controlled) experiments
with literate programming. For example like the one of
 
	Ramsey and Marceau
	Literate Programming on a Team Project
	Softw.Pract.&Exp. 21, 7, 677-683 (July 1991).
 
Also references to discussions on the merits of LP are welcome, as long as
they are in refereed journals. Of course I already have the Literate Programming
columns of CACM.
 
Eric W. van Ammers    (ammers@rcl.wau.nl)
 
From coates@spectro.jussieu.fr Fri Jan 29 18:07:10 +0100 1993
Date: Fri, 29 Jan 93 18:07:10 +0100
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Indent spacing
 
Dear Tony,
	On the subject, floating around of late, of the correct indent to use
for source code (C or C++ usually, for me), I have to say that I find 1 tab =
8 spaces to be too much, if one has a few levels of indenting.  There's no
space left for the code on the end of the line!  I use two spaces between
levels, and even then I keep asking myself if that isn't one space too many.
To avoid losing track of indenting levels, I prefer to use a system like
 
	if (condition) {
	  ...
	} /* end if (condition) */
 
to clearly mark which closing construct goes with which opening construct.
With this system, I find two spaces of indent per level to be quite enough.
	This is the bottom-end of "Literate Programming", I suppose, but that's
my 2c worth anyway.
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From Silvio Fri Jan 29 09:40:20 -0800 1993
Date: Fri, 29 Jan 93 09:40:20 -0800
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: \long string in CWEB: how ?
 
Here is one kludge that will work for very long strings.
 
@
 
\begingroup % temporarily redefine the way @& and @= print.
\def\J{\hfil\break}\let\vb\.
 
@c
static String   text_translationsD = @="\@>@&
@=<Key>Delete:    DeleteD() end-of-file() delete-previous-character()\n\@>@&
@=<Key>BackSpace: DeleteD() end-of-file() delete-previous-character()\n\@>@&
@=<Key>Return:    end-of-file() newline() DispatchD()\n\@>@&
@=<Key>:		InsertD() end-of-file() insert-char()\n\@>@&
@=<Btn1Down>:     select-start() \n\@>@&
@=<Btn1Motion>:   extend-adjust() \n\@>@&
@=<Btn1Up>:       extend-end(PRIMARY, CUT_BUFFER0) \n\@>@&
@=<Btn3Down>:     extend-start() \n\@>@&
@=<Btn3Motion>:   extend-adjust() \n\@>@&
@=<Btn3Up>:       extend-end(PRIMARY, CUT_BUFFER0)"@>;
 
@
\endgroup
 
From leew@cs.utexas.edu Fri Jan 29 13:13:39 -0600 1993
Date: Fri, 29 Jan 1993 13:13:39 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB C++ version
 
To veer slightly from the main discussion:
 
        Timothy Murphy quotes Shakespeare:  "The quality of mercy is not
        strained ..."
 
        As Richard Armour put it:  "If the quality of mercy is not strained,
        how is it kept from becoming lumpy?"
 
Nothing useful to contribute this time.
 
		-- Lee
 
From leew@cs.utexas.edu Fri Jan 29 13:45:39 -0600 1993
Date: Fri, 29 Jan 1993 13:45:39 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: A programmer's first use of Literate Programming
 
Jonathan M. Gilligan writes (among other things):
 
  > ... life would be nicer if there were a tool that would let us generate
  > common.h directly from common.w
 
Actually, CWEB does support this directly, with the @( facility (which I
make use of frequently to generate .h files for literate libraries (sic)).
However, I believe that the separate common.h file dates from the early
days of CWEB, before this facility was available.  I believe that the idea
was originally developed by Norman Ramsey for Spidery WEB, and was
added to CWEB later.
 
Personally, I would be a lot happier if common.w used @(common.h@>= to
generate the common.h file.
 
	-- Lee
 
From leew@cs.utexas.edu Fri Jan 29 14:04:49 -0600 1993
Date: Fri, 29 Jan 1993 14:04:49 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: \long string in CWEB: how ?
 
Roegel Denis (Denis Roegel?) writes:
 
  > Here is another little problem I face. As a matter of fact, I am
  > translating some more or less old C programs into CWEB. I really
  > love to do it, but all possible problems occur. Here is one. With the next
  > static declaration, Cweave tells me that the string is too long.
  > How can I override this ?
  >
  > static String   text_translationsD = "\
  > 	<Key>Delete:    DeleteD() end-of-file() delete-previous-character()\n\
  > 	<Key>BackSpace: DeleteD() end-of-file() delete-previous-character()\n\
  > 	<Key>Return:    end-of-file() newline() DispatchD()\n\
  > 	<Key>:		InsertD() end-of-file() insert-char()\n\
  >         <Btn1Down>:     select-start() \n\
  >         <Btn1Motion>:   extend-adjust() \n\
  >         <Btn1Up>:       extend-end(PRIMARY, CUT_BUFFER0) \n\
  >         <Btn3Down>:     extend-start() \n\
  >         <Btn3Motion>:   extend-adjust() \n\
  >         <Btn3Up>:       extend-end(PRIMARY, CUT_BUFFER0)";
 
For this problem I'd use a Standard C feature instead of a CWEB one.  ANSI C
automatically concatenates adjacent string constants (as did a number of
pre-standard compilers).  I'd write the above code (in CWEB) as:
 
    static String   text_translationsD =				      @/
      "<Key>Delete:    DeleteD() end-of-file() delete-previous-character()\n" @/
      "<Key>BackSpace: DeleteD() end-of-file() delete-previous-character()\n" @/
      "<Key>Return:    end-of-file() newline() DispatchD()\n"		      @/
      "<Key>:		InsertD() end-of-file() insert-char()\n"	      @/
      "    <Btn1Down>:     select-start() \n"				      @/
      "    <Btn1Motion>:   extend-adjust() \n"				      @/
      "    <Btn1Up>:       extend-end(PRIMARY, CUT_BUFFER0) \n"		      @/
      "    <Btn3Down>:     extend-start() \n"			      	      @/
      "    <Btn3Motion>:   extend-adjust() \n"			      	      @/
      "    <Btn3Up>:       extend-end(PRIMARY, CUT_BUFFER0)";
 
The @/s are, of course, CWEB formatting commands to put things on separate
lines.  @| might be better (so following lines will be indented).  You may
have to play around a bit to get the formatting you want.  Anyway, as
long as your C compiler supports the standard, you don't have to worry
about CWEB's maximum string length (or the C mishegoss using \ to continue
a string on the next line).
 
		-- Lee
 
From Marty Fri Jan 29 15:51:24 PST 1993
Date: Fri, 29 Jan 1993 15:51:24 PST
From: "Marty Leisner" <leisner@eso.mc.xerox.com>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Editing Tools (was RE: Philonous and Malevolent)
 
In message <9301282017.AA16722@imada.ou.dk> you write:
>dak@POOL.informatik.rwth-aachen.de
>
>Well.  I have never really figured why indenting 8 spaces (with a TAB)
>should make C programs that much more readable than anything else bigger
>than, say 2.
>
>Being a Pascal programmer reluctantly forced into C (the great assembly
>language of *real* machines) I have used an indentation of 2 with a very
>consequent way of changing it for several years.  My experience shows
>this to be more effective than moving code back and forth horizontally
>on the page.  And, no,  I do not have bracket-matching in my editor. :-(
>...
>Agreed.  Small identations are, however, not implying unreadable code.
 
I find code with 2 space identation a waste of my time...I thorugh such
code through indent...
 
Having a problem moving back and forth horizontally is an indication you have
to many levels in one function...
 
marty
leisner@eso.mc.xerox.com leisner.henr801c@xerox.com
Member of the League for Programming Freedom
"People cannot be managed.  Inventories can be managed, but people must be led"  -- H. Ross Perot
 
From tfj@apusapus.demon.co.uk Fri Jan 29 23:57:44 GMT 1993
Date: Fri, 29 Jan 93 23:57:44 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: A programmer's first WEB---week two
 
This week's installment of "A programmer's first WEB".
 
Nobody objected to last week's posting about writing my first Literate
Program so I've taken the liberty of wasting more bandwidth by writing
about this week's progress. I changed the experiment (as a result of last
week's message) in that I kept notes during the week; last week's report
was just Friday night recollections.
 
There are three sets of goals that my experiment ought to satisfy:
 
1   Donald E. Knuth's. As espoused in his writings on Literate Programming.
    Unfortunately, I've mislaid my copy of the Computer Journal with his
    original paper on the subject. :-( Must be somewhere in my loft. Also,
    few of the London bookstore's stocked his "Literate Programming" book
    and even fewer are likely to re-stock it. :-((
 
    All in all I shall refrain from saying anymore about his criteria/goals
    until after the project is finished.
 
2   My employers. As I wrote earlier this week they dont know that the
    experiment is being conducted; all they do know is that I'm writing the
    program to specification. Their goals are that the job is done with
    minimal effort in creating the utility and that it requires little effort
    to maintain it next year when the customer's data changes!
 
3   My own goals. I can wax lyrical about these. :-)
 
a   I wanted to use WEB (actually CWEB) on a real project. I had read DEK's
    paper; the stuff in Jon Bentley's "Programming Pearls" and then Van
    Wyck's (short-lived) "Literate Programming" column in the Comm of the
    ACM but now I felt it was time for me to do it myself.
 
b   The desire to use WEB was based upon my expectation of the complexity
    of the code. (Anyone who has ever tried to de-block a USMARC tape will
    understand what the problems are---because that is exactly what I'm
    doing.) I have to admit that I normally get ``flussered'' by the
    complexity of code that I've written after only a couple of hundred
    lines---I estimated that this conversion utility would be around 1,000
    to 1,500 lines in total, ie more than I wanted to have to cope with
    using my old skills. So I unilaterally decided that I would write the
    thing using CWEB.
 
    By the way, I've gotten the tape de-blocking working and some of the
    USMARC to internal format working. The CTANGLEd code for which is
    currently just over 500 lines. I have the reports/listings code to
    write and possibly some other manipulations of the data will be
    necessary. This latter because the specification of the data on the
    tape is not very clear---in fact it's opaque!
 
c   Reduce the debugging time.
 
    I think that this has happened. The major problem is that I'm not a C
    programmer. Until this project I was always a Pascal programmer but the
    employers have switched to C so... It does mean that the utility can be
    run on a Unix box if required, in addition to the VMS box that it's
    targeted for.
 
    Even if the debugging time is not reduced at least I'm calmer than I
    would be when trying to get the beast to run using my old working
    methods! :-)
 
d   I wanted to see what my own literate program would be like. It's rather
    like the first time that I held the card deck for the first production
    program I wrote. A great sense of satisfaction.
 
Summary of the week
 
Rather than bore you all with a diary of events I want to make some
observations about my usage of Literate Programming. In passing I'll make
suggestions for additional tools that would have made the programming task
easier.
 
The use of Literate Programming meant that recommencing work on Monday
morning was ``instantanious''. The reduction of complexity inherent in each
section of code meant that I could concentrate upon specific portions
that required correction and concentrate upon the specifics. The index to
the listing proved invaluable to getting on with it straight away.
 
It was easier to concentrate upon the code. Fragments of it remained in my
mind longer than such things do normally. Even when I was working on
fragment A, I found myself correcting fragment B and then going back to A
again without loosing my train of thought. It was easy to insert new code
quickly especially for a couple of things which had been forgotten.
 
Estimating the amount of work involved was/is difficult. KDSI is
inappropriate for a literate program as there are many lines of what would
only be exchanged in conversations between programmers (if at all).
 
I made the same ``slips of the pen'' that I would have made in a
non-literate program. However, they came to light very quickly. Usually
during a code reading.
 
Correcting complex boolean conditions became easier, though it was still
difficult to express them correctly.
 
On a number of occasions I wanted a CWEB macro feature. Not the @d
directive but rather some way to have CWEB macros for handling code that is
very similar. I resorted to cut-and-paste within the editor.
 
Any tendency to hack or patch the code could be resisted easily.
 
Working practices
 
A working pattern emerged very quickly. I commute to my office by London
Underground which means that I get to sit down for approximately one hour
before actually arriving at the office. I used this time to read through
the listing in preparation for the days work. Reading the listing also took
my mind of the delays in the journey---that is I arrived at my usual
time...late. :-)
 
On getting to the office I would correct the errors that I'd seen during
that early morning read-through. A lot of these early-bird worms were
``speelnig misteaks''. Once these were corrected I could start on some
portion of the code that had (so to speak) taking my fancy during the
journey. This thinking/editing work would continue until about 15:30 when I
would try to weave/tangle the web source. Once I'd corrected typing
mistakes in the .w file I could try compiling the .c file. When I had a
clean compilation I then ran the executable. Whilst one iteration of the
edit/compile/link/test cycle takes longer with WEB I think that the cycles
were more productive than before.
 
What fascinated me was that I rarely needed to read the source code to
figure out what was the problem. Because, as I said earlier, I had it all
in my head I could correct the problems quickly. (Well quicker than I used
to when using the non-literate programming paradigm.)
 
Some ``negatives''
 
It was a mistake to add several new sections into the .w file at the same
moment that I used my first change file. I nearly ``lost it'' then.
However, i decided that in future I would add new sections immediately
prior to the Index section until such time as I wanted/needed to generate a
complete listing when I would re-organise the exposition of sections in a
more instructive order.
 
Several times I wished for a Windows-based editor. I wanted to be able to
view the current section, the section in which it was used and the
definition of variables and macros at the same time. Clicking on a lexeme
whilst pointing at it and having all the relevant sections available wouyld
have been a great doon. I remember arguing this self-same case in an
examination answer during my Master's degree finals; these finals took
place not long after I heard DEK's London talk.
 
On my PC I have Microsoft's Programmer's Workbench which I used to compile
CWEAVE and CTANGLE. I was impressed by the fact that during symbolic
execution of the code it (PWB) honoured the #line directives. Shock and
horror then to discover that VMS debug did NOT honour them!!!!
 
My next task is to write a simple program that takes the output from the
VMS DIFFERENCES utility and creates a change file. This will of course be a
literate program.
literate program.
 
From tfj@apusapus.demon.co.uk Sat Jan 30 15:37:27 GMT 1993
Date: Sat, 30 Jan 93 15:37:27 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Indent spacing
 
In message <9301291707.AA15523@lutidine.spectro.jussieu.fr> you write:
 
> 	On the subject, floating around of late, of the correct indent to use
> for source code (C or C++ usually, for me),
 
As the only (production) program that I've written in C is the Literate
Program that I have been going on about for the last 10 days I haven't
developed an indetation style. However, when I started my little proggie I
indent the the C code within each section by three spaces. After a little
while I stopped doing that even as tangle rather mangles the indentation of
the .c files, I just got used to it.
 
> I have to say that I find 1 tab =
> 8 spaces to be too much,
 
I think that a tab stop of 8 is too large. I can still picture my first
sizeable Algol-68 program where I had one card with several nested
if/then/else/fi occurences together. The natural place to start the
indetation was column 45, this left me VERY little room to actually get the
expression to fit. (Thank goodness for the shorthand form of (||) which
made it possible to get the whole thing in.)
 
> ...mark which closing construct goes with which opening construct.
 
Personally, I find that sort of thing very intrusive when reading the
source. But then again I'm never going to revert to using illiterate
methods again! :-)
 
> ...that's my 2c worth anyway.
 
With the dollar/pound exchange rate at the moment that makes my 1p's worth
more valuable than yours. :-))
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England
email: tfj@apusapus.demon.co.uk                               radio: G6AJG
phone: +44 (0)923 776436
 
From figuei@lutece.rutgers.edu Mon Feb 22 22:15:33 -0500 1993
Date: Mon, 22 Feb 93 22:15:33 -0500
From: figuei@lutece.rutgers.edu (Francisco Figueirido)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: (commented) source code and user documentation in FWEB
 
David Kastrup <dak@pool.informatik.rwth-aachen.de> writes:
 
> >> I guess the whole case of putting user documentation into WEBs
> >> more or less evades me.
> >..
> >> user documentation tends to change slower than the program, esp.
> >> when betatest options are introduced.
> >	I think you just answered your own question.  User
> >documentation *does* tend to be behind the program; the point is that
> >is should not, since users what to know what the current version of
> >the program does, not the version of six months ago that has been
> >documented (probably incorrectly anyway).
> >
> >^.-.^ Mark Purtill, purtill@ccr-p.ida.org || purtill%idacrd@uunet.uu.net
> >((")) \@_: IDA/CCR-P, Thanet Road, Princeton NJ  08540;  (609) 924-4600.
> >Alternate email: purtill%idacrd@princeton.edu UUCP: uunet!idacrd!purtill
> >
> >
>  And will cramming them into the same file help? Perhaps you think
> about your user documentation during the extra processing time needed
> to skip the user doc, which has an entirely different structure than
> the WEB.
>
> Perhaps we should try thinking about a way of including the programmer's
> photograph in the WEB as well, so that it stays current. This single-file-
> and-see-how-everything-is-suddenly-magically-up-to-date-myth is
> very nice, but...
 
I don't agree that the user documentation has *an entirely different
structure* than the WEB. Here we have the example of a rather large program
(not written as a WEB!) whose documentation consists mostly of a description
of ``tasks'' and ``subtasks'' that could be very well integrated with the
WEB (if it existed!). Another example is a program I wrote (in FWEB) whose
kernel is a rather simple interpreter and most of the baggage is taken by
primitive functions. I was thinking about writing a user manual for this
program, and the idea of having a description of the usage of each primitive
very close to the place where the primitive is defined seems to me a good
idea. Moreover, this way it would be easier and less error prone to add (or
delete) primitives while keeping the documentation in synch.
 
From norman@bellcore.com Mon Feb 22 22:59:07 -0500 1993
Date: Mon, 22 Feb 93 22:59:07 -0500
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Portable C/F/WEB
 
look into david hanson's and robert sedgewick's loom tool.
it is not a true literate=programming tool (in the thimbleby sense)
but it does enable a semblance of literate programming using
standard source files and it will work with fortran.  see the
article in the (july?) 1987 cacm.
 
Norman
 
From brown_s@maths.su.oz.au Tue Feb 23 15:14:57 +1100 1993
Date: Tue, 23 Feb 93 15:14:57 +1100
From: brown_s@maths.su.oz.au (Stephen Brown)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Including FWEB output into a LaTeX document?
 
Two recent posts have touched on the subject of including FWEB output
into a LaTeX document;
 
Bart Childs writes
 > There was also a query about including the output of WEBs in TeX
 > documents.  The FWEB manuals have some examples of doing this
 > with some short demos.  A nice extension would be a set of
 > macros for demonstrating literate programs and doing this
 > in two column mode such that the examples would not run
 > pages and pages.
 
and Lew Perin writes
 > It sounds as if CWEB/LaTeX will be a wait, so the original poster
 > might well want to use FWEB with LaTeX.  I wouldn't want to leave the
 > impression that the combination of the two is as easy to use as either
 > alone, but it can be done.  I just submitted a Master's thesis of
 > about 130 pp. using the FWEB/LaTeX combination, with the added
 > complication of Gnuplot graphs; it was accepted, if anyone cares!
 
I am currently writing a thesis and would like to include excerpts
from the woven output of one of my programs written using FWEB.
The thesis is written using LaTeX.  The macros used in the FWEB manual
for including woven output into a TeX document don't seem to be
compatible with LaTeX.
 
Before I attempt to (re)invent the wheel, does anyone know if there
are any macro packages or files demonstrating how to include woven
output into a LaTeX document that are publically availiable?
Any help would be much appreciated.
 
Steve Brown
School of Mathematics and Statistics
University of Sydney
 
From Glyn Tue Feb 23 08:58:16 GMT 1993
Date: Tue, 23 Feb 93 08:58:16 GMT
From: "Glyn Normington" <NORM@WINVMJ.VNET.IBM.COM>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Alternatives to TeX and WEB
 
Stephen Cross writes:
 
> Do we realy need to use TeX and WEB?
 
No. We use IBM's Bookmaster markup language to do literate programming.  We
use tags to define and reference code fragments and have an equivalent tool
to Tangle which we run as a pre-processor to our compiler.  We don't need to
Weave since the formatting logic is built into the definition of the literate
programming tags.
 
>
> Why not write literate programs in a wordprocessor or some kind of WYSIWYG
> desktop publishing tool and extract the code from there.
> It seems to me that this approach would be far more programmer friendly.
> Such a system could make use of hypertext links to requirements, analysis,
> designs, and other source documents.
>
 
Although Bookmaster is not WYSIWYG, we can use a syntax-directed editor to
edit Bookmaster source in a readable form.
 
> Does any such system aready exist?  The reason why I ask is because I am
> thinking of writing such a tool as a final year project.  Any suggestions?
 
Our system exists but is internal to IBM.  However, if you define unambiguous
ways of delimiting and referencing code fragments, it is fairly simple to
write a Tangle-like program to produce compilable code.  I suggest you follow
the usual approach and make this program self-generating which will probably
require you to write a basic prototype to get you off the ground.  Our
prototype was a 230 line REXX program (REXX is an interpreted language a bit
like PL/1).
 
Hope this is helpful.
 
Glyn Normington
 
CICS Products
IBM UK Laboratories Ltd
Hursley Park
Winchester
England
 
From g07m@alf.zfn.uni-bremen.de Tue Feb 23 11:04:45 +0100 1993
Date: Tue, 23 Feb 1993 11:04:45 +0100
From: g07m@alf.zfn.uni-bremen.de (Lothar Meyer-Lerbs)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: weave+tangle for Oberon-2 ??
 
Has anyone created a beast like that? Or is FWEB going to do
that too (real soon now) ?
 
Thanks Lothar
 
From Edward Tue Feb 23 06:29:13 EST 1993
Date: Tue, 23 Feb 1993 06:29:13 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate Programming without WEB & TeX
 
On Mon, 22 Feb 93 14:32:28 GMT, S.C.Cross@bnr.co.UK wrote:
>
> Do we realy need to use TeX and WEB?
>
> Why not write literate programs in a wordprocessor or some kind of WYSIWYG
> desktop publishing tool and extract the code from there.  It seems to me
> that this approach would be far more programmer friendly.
>
> Does any such system aready exist?  The reason why I ask is because I am
> thinking of writting such a tool as a final year project.  Any suggestions?
>
 
I think it's a great idea. I've been considering writing a suite of
Winword macros with this aim mysself.
 
	-Ed K.
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From ae1181t@stnfor.ae.ge.com Tue Feb 23 07:59:32 -0500 1993
Date: Tue, 23 Feb 93 07:59:32 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Portable C/F/WEB
 
I used FWEB a little, but I think you might want to use FUNNELWEB. This
WEB is language independent, and the tangled code looks good compared to
the code produced from FWEB. Wowen code does not look as nice as FWEB's.
This is due to the language independence of FUNNELWEB. The program does
not need any extra style or tex files (FWEB does), so distribution is
easier, the manual is a lot smaller than FWEB's. Smaller number of
constructs need to be learned with Funnelweb. I just got mine built, think
it is a good litprog tool.
Osman Buyukisik
GE aircraft engines
 
From ae1181t@stnfor.ae.ge.com Tue Feb 23 08:18:13 -0500 1993
Date: Tue, 23 Feb 93 08:18:13 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Literate Programming without WEB & TeX
 
Stephen Cross writes ``Do we really need to use TeX and WEB?'' I beleive
the people who talk about using wordprocessors for program development
have not used any of the litprog tools. One of the biggest reasons for
using the tools is not because they produce good  looking code with
documentation, but because they allow the programmer to use the tool
as a program design language (PDL), and either top-down or bottom-up
design the program without being restrained by the target language
compilers. The same comment goes to NOWEB people, since that tool
does not expand macros and tangle.
Osman.
 
From Dominique Tue Feb 23 15:53:32 +0100 1993
Date: Tue, 23 Feb 93 15:53:32 +0100
From: Dominique Dumont / GND <domi@desire.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: (commented) source code and user documentation in FWEB
 
> >> I guess the whole case of putting user documentation into WEBs
> >> more or less evades me.
> >..
> >> user documentation tends to change slower than the program, esp.
> >> when betatest options are introduced.
> >	I think you just answered your own question.  User
> >documentation *does* tend to be behind the program; the point is that
> >is should not, since users what to know what the current version of
> >the program does, not the version of six months ago that has been
> >documented (probably incorrectly anyway).
> >
> >^.-.^ Mark Purtill, purtill@ccr-p.ida.org || purtill%idacrd@uunet.uu.net
> >((")) \@_: IDA/CCR-P, Thanet Road, Princeton NJ  08540;  (609) 924-4600.
> >Alternate email: purtill%idacrd@princeton.edu UUCP: uunet!idacrd!purtill
> >
> >
>
> And will cramming them into the same file help? Perhaps you think
> about your user documentation during the extra processing time needed
> to skip the user doc, which has an entirely different structure than
> the WEB.
>
> Perhaps we should try thinking about a way of including the programmer's
> photograph in the WEB as well, so that it stays current. This single-file-
 
How do you manage to make the photograph age along with the actual programmer ? ;-)
 
> and-see-how-everything-is-suddenly-magically-up-to-date-myth is
> very nice, but...
>
 
More seriously :
 
Indeed the user documentation structure is different from the structure of the
WEB file.
 
What I'd do in this case is create a user doc skeleton with a
consistent structure and import implementation or function details from the woven
file. This way all details are updated (they are the most prone to a change
during the debug phase of a code) and the structure of the user doc is
independent of the WEB file. The only drawback is that if your program changes
much you'll have to redesign the structure of your user doc (but I do hope that
it doesn't happen too often :-) ).
 
The second problem is that weave must produce 2 outputs :
- the internal doc for the programmer
- a lot of files which are to be imported in the user doc (I don't know if any WEB
  system can do that now). The information contained in these files may or may not
  be also included in the internal doc.
 
Hope this helps
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From Timothy Tue Feb 23 15:16:08 GMT 1993
Date: Tue, 23 Feb 93 15:16:08 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
> > Why not write literate programs in a wordprocessor or some kind of WYSIWYG
> > desktop publishing tool and extract the code from there.  It seems to me
> > that this approach would be far more programmer friendly.
>
> I think it's a great idea. I've been considering writing a suite of
> Winword macros with this aim mysself.
 
Isn't this more or less what TANGLE is?
I suppose you could add an in-built editor,
but is it really worth it?
 
You want WEAVE to output ASCII instead of TeX?
Surely that can't be too difficult.
Just cut out all the TeX commands it produces.
(Whether that is an advance or not is another matter ...)
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From idacrd!purtill@uunet.UU.NET Tue Feb 23 10:34:33 EST 1993
Date: Tue, 23 Feb 93 10:34:33 EST
From: idacrd!purtill@uunet.UU.NET (Mark Purtill)
Reply-To: LitProg@SHSU.edu
To: uunet!SHSU.edu!LitProg@uunet.UU.NET
Subject: Re: (commented) source code and user documentation in FWEB
 
David Kastrup <dak@pool.informatik.rwth-aachen.de> writes:
>>> I guess the whole case of putting user documentation into WEBs
>>> more or less evades me.
>>..
>>> user documentation tends to change slower than the program, esp.
>>> when betatest options are introduced.
Me:
>>	I think you just answered your own question.  User
>>documentation *does* tend to be behind the program; the point is that
>>is should not, since users what to know what the current version of
>>the program does, not the version of six months ago that has been
>>documented (probably incorrectly anyway).
David:
>And will cramming them into the same file help? Perhaps you think
>about your user documentation during the extra processing time needed
>to skip the user doc, which has an entirely different structure than
>the WEB.
	The time needed to skip the user docs is tiny compared with
compile (either of code or TeX) times.  Of course, nothing can *force*
the programmer to update the docs, but it's a lot more likely that the
-frobnatz flag will be documented if the documentation can go write
there, next to the code that does what the -frobnatz flag.  Of course,
some programs this will be more doable than others.  (Perhaps I
should make it clear that I have in mind a reference manual as the
"user docs", not a tutorial or such like.)
	And of course the reference manual will have a different
structure that the usual WEB output.  The WEB output has a whole
different structure than the program fed to the compiler: that's the
whole point of WEB.  The question was, how can another document, the
reference manual, with another structure, be included in a sensible
way.
 
.^ Mark Purtill, purtill@ccr-p.ida.org || purtill%idacrd@uunet.uu.net
((")) \@_: IDA/CCR-P, Thanet Road, Princeton NJ  08540;  (609) 924-4600.
Alternate email: purtill%idacrd@princeton.edu UUCP: uunet!idacrd!purtill
 
From Zdenek Tue Feb 23 11:03:58 MDT 1993
Date: Tue, 23 Feb 93 11:03:58 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: Literate Progaramming list <LitProg@SHSU.edu>
Subject: Re: CWEB with LaTeX: Possible?
 
To incorporate CWEB into LaTeX you have to do some changes. I received
change files for cweave from Hans Hermann Bode and then I extended
ccwebmac.tex to work with LaTeX (however, it still works with the original
CWEB). I will communicate with Silvio Levy so that it will be included in
the following versions. I can send it to you tomorrow (I have it at home)
but it is not tested thoroughly.
 
Regards
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `           ~~~  ~~/ '  '  ~~~
                              Zdenek Wagner______/
 
From preston@cs.rice.edu Tue Feb 23 14:16:36 CST 1993
Date: Tue, 23 Feb 93 14:16:36 CST
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Literate Programming without WEB & TeX
 
People who do work on unix don't usually have a wordprocessor handy.
Usually, we have a generic text editor, a make facility, a C compiler,
and (hopefully!) tex.
 
It's certainly easier to use (or even write) a tangle and weave
than it is to write a wysiwyg tool; though I think a nice tool
would be a joy to use.
 
Preston Briggs
 
From norman@bellcore.com Tue Feb 23 15:16:50 -0500 1993
Date: Tue, 23 Feb 93 15:16:50 -0500
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Literate Programming without WEB & TeX
 
> The same comment goes to NOWEB people, since that tool
> does not expand macros and tangle.
 
Be careful.  cnoweb does not tangle, but it uses cpp to expand macros
(as did cweb the last time i looked).  noweb tangles but does not
expand macros.  it says here that noweb doesn't have to expand macros
because it works smoothly with m4 and cpp.
 
Norman
 
From marcus@x4u.desy.de Tue Feb 23 21:55:31 +0100 1993
Date: Tue, 23 Feb 93 21:55:31 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Literate Programming without WEB & TeX
 
|> It's certainly easier to use (or even write) a tangle and weave
|> than it is to write a wysiwyg tool; though I think a nice tool
|> would be a joy to use.
 
What the heck is WYSIWIG? --
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
[Just a poor physicist]
 
From Edward Tue Feb 23 23:44:44 EST 1993
Date: Tue, 23 Feb 1993 23:44:44 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate Programming without WEB & TeX
 
On Tue, 23 Feb 93 15:16:08 GMT, "Timothy Murphy" <tim@maths.tcd.IE> wrote:
> > > Why not write literate programs in a wordprocessor or some kind of WYSIWYG
> > > desktop publishing tool and extract the code from there.  It seems to me
> > > that this approach would be far more programmer friendly.
> >
> > I think it's a great idea. I've been considering writing a suite of
> > Winword macros with this aim mysself.
>
> Isn't this more or less what TANGLE is?
> I suppose you could add an in-built editor,
> but is it really worth it?
>
> You want WEAVE to output ASCII instead of TeX?
> Surely that can't be too difficult.
> Just cut out all the TeX commands it produces.
> (Whether that is an advance or not is another matter ...)
 
Who said any thing about ASCII? Winword (aka Word for windows) is
GUI. You can include mathematical formulas, graphs, you could even
scan in your photo (as someone on this list suggested). I'm not a TeX
expert, but I suspect Word for Windows can do anything it can do,
with less of a learning curve.
 
	-Ed K.
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From Joan Wed Feb 24 00:56:15 -0500 1993
Date: Wed, 24 Feb 1993 00:56:15 -0500
From: Joan Boorstein <jboor@ra.cs.umb.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Literate Programming without WEB & TeX
 
Marcus asks:
> What the heck is WYSIWIG? --
 
WYSIWIG -- I assume this should be WYSIWYG -- is an acronym (as if you
needed one more) standing for 'What you See Is What You Get'. It was used
(if I recall correctly) to refer to a screen editor/word-processor whose
behavior allows a text's screen 'appearance' (this is not a good word
choice but I can't think of a better one at the moment) to be the same
(or nearly so) as its paper one.
 
Joan Boorstein (jboor@cs.umb.edu)
 
From Eric Wed Feb 24 04:12:41 -0500 1993
Date: Wed, 24 Feb 1993 04:12:41 -0500
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
It is very well possible to program literately without being tied to a
particular textprocessing environement and/or programming language.
We have been doing exectly this for a long time using the VAMP tool which
recently has been replaced by the more up-to-date CLiP (Code from Literate
Program).
More about CLiP in a separate posting.
 
Eric W. van Ammers (ammers@rcl.wau.nl)
 
From Paul Wed Feb 24 04:12:41 -0500 1993
Date: Wed, 24 Feb 1993 04:12:41 -0500
From: Paul Prescod <papresco@undergrad.math.uwaterloo.ca>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Literate Programming without WEB & TeX
 
> What the heck is WYSIWIG? --
 
What you see is what you get...like a graphical word processor.   TeX
would be more appropriately described as WYWIWYG, What you WANT is what
you get, but it would fail the WYSIWYG test because the formatting
codes look nothing like the final output.
 
From Eric Wed Feb 24 04:12:41 -0500 1993
Date: Wed, 24 Feb 1993 04:12:41 -0500
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: c-no-web and Adaweb
 
Who can help me on references describing the c-no-web and the AdaWEB
system?
 
Eric W. van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From eds2@cornell.edu Wed Feb 24 17:07:57 +0730 1993
Date: Wed, 24 Feb 1993 17:07:57 +0730
From: eds2@cornell.edu (Eric Scharff)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
On Tue, 23 Feb 23:44, "Edward F. Keith" <ed@efkport.kew.com> wrote:
 
>Who said any thing about ASCII? Winword (aka Word for windows) is
>GUI. You can include mathematical formulas, graphs, you could even
>scan in your photo (as someone on this list suggested). I'm not a TeX
>expert, but I suspect Word for Windows can do anything it can do,
>with less of a learning curve.
 
I've never used Microsoft Word for Windows, so I can't comment on its power
as a desktop publisher.  However, from what I know about its style sheets,
if you have a good understanding of the file format, it shouldn't be
difficult to WEAVE WEB output that would use these style options (for code
and such.)  However, are you suggesting a TANGLE that takes a Microsoft
Word for Windows file as input?  That sounds a bit more complex...
 
-Eric Scharff
 eds2@cornell.edu
 
From ajcd@dcs.ed.ac.uk Wed Feb 24 13:37:53 GMT 1993
Date: Wed, 24 Feb 93 13:37:53 GMT
From: ajcd@dcs.ed.ac.uk
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: c-no-web and Adaweb
 
>From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.nl>
>
>Who can help me on references describing the c-no-web and the AdaWEB
>system?
 
@InProceedings{pappas:reuse,
    author	 = "T. L. Pappas",
    title	 = "Literate Programming for Reusability: A Queue Package
                    Example",
    booktitle	 = "Proceedings of the Eighth Annual Conference on Ada
                    Technology",
    year	 = 1990,
    pages	 = "500--514",
    organization = "ANCOST, Inc. (Sponsor)",
    address	 = "Atlanta, Georgia",
    month	 = mar,
    review	 = "\sf This paper begins with a set of guidelines for writing
                    and documenting reusable Ada software. {\tt AdaWeb}, a
                    literate programming system combining Ada and \TeX\ is
                    described. A sample {\tt AdaWeb} package, {\em Bounded
                    Generic Queue Package}, is provided. Features of {\tt
                    AdaWeb} are explained as they are used in the literate
                    program."
}
 
From  Wed Feb 24 15:18:09 +0100 1993
Date: Wed, 24 Feb 1993 15:18:09 +0100
From: " (Bernhard Lang)" <Lang@tu-harburg.dbp.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Spiderweb on IBM RS6000 -- how it runs
 
Dear Members of the LitProg mailing list,
 
  some days ago I did mail a request for a running Spiderweb on IBM
  RS6000 Workstations.  In the following you find a changed version of
  the 'unbucket' procedure in weave.web that overcomes the hanging.
 
  Today I have another question: Can anybody tell me how I can subscribe
  to the LitProg mailing list?
 
Thanks Bernhard.
 
--------- begin of web code ---------
 
@ Procedure |unbucket| goes through the buckets and adds nonempty lists
to the stack, using the collating sequence specified in the |collate| array.
The parameter to |unbucket| tells the current depth in the buckets.
Any two sequences that agree in their first 255 character positions are
regarded as identical.
 
@d infinity = 255 /* $\infty$ (approximately) */
 
@u unbucket(d) /* empties buckets having depth |d| */
eight_bits d;
{
  /* originally the loop did run with |ASCII c|, but it did hang on an
     IBM RS6000 machine.  From preston@cs.rice.edu I got a tip to look
     for a loop with charater index where a signed variable is assumed
     but the compiler default is unsigned.  I found such a loop, added
     the |int| variable |i| and it works.  Thanks to preston!
     All changed or added lines I marked with ***.
     B. Lang, Feb. 3, 1993
  */
  int i;    /* *** |int| Variable added */
  ASCII c;  /* index into |bucket| */
  for (i=100; i>= 0; i--) { /* *** Loop-Variable changed from |c| to |i| */
    c = i;                  /* *** assigment guarantees previous situation */
    if (bucket[collate[c]]) {
      if (sort_ptr>=scrap_info_end) stat_overflow("sorting");
      sort_ptr++;
#ifdef STAT
      if (sort_ptr>max_sort_ptr) max_sort_ptr=sort_ptr;
#endif STAT
      if (c==0) sort_ptr->depth=infinity;
      else sort_ptr->depth=d;
      sort_ptr->head=bucket[collate[c]]; bucket[collate[c]]=NULL;
    }
  }
}
 
--------- end of web code ---------
 
---------------------------------------------------------------------------
Dr. Bernhard Lang                        TU Hamburg Harburg
                                         Technische Informatik I
                                         Harburger Schlossstrasse 20
                                         2100 Hamburg 90
                                         Tel.: +40/7718-2786
                                         FAX:          -2911
                                         email: lang@tu-harburg.dbp.de
---------------------------------------------------------------------------
.
 
From chavey@beloit.edu Wed Feb 24 08:59:47 -0600 1993
Date: Wed, 24 Feb 1993 08:59:47 -0600
From: chavey@beloit.edu (Darrah Chavey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Literate Programming without WEB & TeX
 
>Marcus asks:
>> What the heck is WYSIWIG? --
>
>WYSIWIG -- I assume this should be WYSIWYG -- is an acronym (as if you
>needed one more) standing for 'What you See Is What You Get'. ...
>
>Joan Boorstein (jboor@cs.umb.edu)
 
Gee, I always thought it stood for "What You So Intently Wish You'd Gotten"
:-)
 
--Darrah Chavey                  Department of Math & Computer Science
  chavey@beloit.edu              Beloit College, Beloit, Wisc.
 
From Les Wed Feb 24 10:50:18 EST 1993
Date: Wed, 24 Feb 93 10:50:18 EST
From: Les <clowney@gandalf.rutgers.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: CWEB with LaTeX: Possible?
 
Hi,
   I made a modified version of fwebmac.sty to use FWEB with  LaTeX,
I'd be interested in seeing your results for CWEB.
 
				les
 
From Timothy Wed Feb 24 15:51:55 GMT 1993
Date: Wed, 24 Feb 93 15:51:55 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Spiderweb on IBM RS6000 -- how it runs
 
>   some days ago I did mail a request for a running Spiderweb on IBM
>   RS6000 Workstations.  In the following you find a changed version of
>   the 'unbucket' procedure in weave.web that overcomes the hanging.
 
Isn't Spiderweb itself written in WEB?
In which case should changes not be in the form of .ch files?
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Eric Wed Feb 24 10:27:56 CST 1993
Date: Wed, 24 Feb 93 10:27:56 CST
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: CLiP: a universal literate programming tool
 
                  CLiP, a universal literate programming tool
 
                              Eric. W. van Ammers
 
    Abstract:
        CLiP (Code from Literate Program) is a tool which allows writing
    literate programs in virtually any programming language (Pascal,
    Fortran, C, C++, Assembler languages, etc) and in combination with
    almost any formatter (Runoff, Troff, TeX, LaTeX, etc.) or
    word-processor (Winword, Lotus Manuscript, Ami Pro, Word Perfect,
    Wordstar, etc).
        This posting explains the CLiP philosophy and compares it to the
    WEB approach. CLiP turns out much more general. In spite of this
    generality its disadvantages as compared to the WEB-family are few
    indeed.
        Currently we have two versions of CLiP, for VAX/VMS and for MS-DOS
    platform. Although only limited user documentation is available, this
    is not felt as a big problem since CLiP works fairly intuitively
 
    Remark: A postscript edition of this text can be anonymously FTP-ed
    from
 
        ftp_node:     sun01.info.wau.nl (IPnr 137.224.133.1)
        directory:    clip
        file:         clip_ann.ps
 
1  Introduction
 
It is clearly impossible to realise literate programming (LP) without a
supporting tool. Historically Knuth was the first to report the very idea of LP
using his WEB-system and most LP practitioners today employ WEB or one of its
derivatives. The original WEB philosophy was to provide a literate programming
tool for a particular programming language (Pascal) in a particular formatting
environment (TeX). Consequently a whole family of *WEB*'s have emerged to
satisfy the needs of individuals who wanted to program literately on different
platforms.
    However, the idea to extract compilable modules from documented refinement
steps (rather then to create modules and documentation separately) has
independently originated elsewhere too. Not surprisingly, the corresponding
LP-tools have been based on different principles and show rather distinct
characteristics. At the Wageningen Agricultural University e.g. we have
developed VAMP (1984) and later CLiP (1992) and these tools show interesting
differences as compared to the WEB-family [1,2,4,5]. Because the introduction
of CLiP made VAMP obsolete, we will focus our attention to the CLiP-system.
    First we explain the design philosophy of CLiP and we briefly sketch the
way CLiP works. Next we describe the major differences between the CLiP-system
and the WEB-family. These differences are mostly due to the difference in
philosophy of both systems. Then we report on the status of the CLiP project
and we conclude by a sketch of our activities in the near future. A more
extensive description of CLiP is in [5].
 
2  Design philosophy
 
CLiP (and formerly VAMP) was designed from the idea that "good" programming has
little or nothing to do with programming languages. We consider stepwise
refinement a "good" programming technique. So when we decided to build a tool
that would allow the extraction of modules from documented refinement steps, it
was evident this tool would have to operate independent of the programming
language involved. In addition this approach would be beneficial from the point
of view of maintenance. The latter perspective made us decide to design the
tool also as much as possible independent of formatter or word-processor.
    According to the CLiP approach the extracted modules definitely have a
function and should not be "deliberately unreadable" as Knuth proposes [2].
Since compiler and debugger messages relate to derived modules rather than to
the documentation proper, it should be easy to relate the code lines of the
generated modules to the corresponding documentation lines. For this reason we
want to copy the code lines of the documentation unchanged into the modules.
 
3  How CLiP works
 
A literate programming tool (LP-tool) has to extract modules from input files
(called "sourcefiles") that serve as (input for) documentation at the same
time. The first problem for an LP-tool to solve is to separate text segments
(that are meant as informal explanation) from code segments (that contain the
actual code to be extracted). The second problem is to merge the code segments
into output files (called "modules").
    For this purpose we have in a conventional literate programming environment
(like WEB or VAMP) special command lines that are added to the sourcefiles. The
command lines control the extraction of the modules by the module generator but
are ignored by the formatter. This technique does not work if the documentation
is processed by a word-processor, since the command lines would invariably show
up as lines in the documentation, which is highly undesirable.
    CLiP solves the problem by prescribing a special programming STYLE. Its
input files are either obtained directly by an editor or indirectly by an
ASCII-export from a word-processor. CLiP recognizes special comment lines as
indicators to guide the module extraction process. These comments look
'natural' in the context of the code. The syntax CLiP recognizes is
parameterized and can be adjusted to virtually any programming language.
 
4  CLiP compared to the WEB-family
 
The differences between the CLiP-system and the WEB-family are partly due to
general design decisions and partly to the difference in philosophy.
 
4.1  General design differences
 
*   CLiP works not "monolithic" (like WEB does). It processes up to 64 (the
     number can be adjusted) inputfiles in one run. From this input it produces
     as many modules as are specified by the user. Thus it is possible to
     generate a complete software system in one single CLiP-run.
*   CLiP composes modules from stubs which may be scattered over multiple
     sourcefiles.
*   CLiP allows a global redefinition of stubs. In this way one can
     temporarily put a stub in a given slot and replace it later on. This
     feature makes it possible to define abstraction levels in the description
     of a system. For instance one can introduce a particular record structure
     at a higher level as a simple name with only its most important fields and
     defer the definition of the other fields to a suitable lower level. Such a
     form of data abstraction is known as "partially specified data
     structures".
*   Unlike WEB, CLiP has no macro facilities.
 
4.2  Programming language independence
 
CLiP will work seamless with any programming language that allows comment lines
between the tokens of the language. Otherwise its applicability can in
principle be restricted, but we know of no language where this would be a
problem in practice.
    Since CLiP is completely programming language independent, it has no
knowledge of the programming language it is processing. Thus it will not
recognize keywords, identifiers or other tokens.
 
*   CLiP cannot automatically produce a X-reference list of identifiers the
     way WEB does (in this respect CLiP is definitely less powerful than WEB).
     With CLiP a X-reference list must be produced the same way as an index of
     an ordinary document. This feature is therefore highly dependent of the
     particular formatter or word-processor one applies. But with a modern
     word-processor like WinWord or Ami Pro, powerful tools exist to support
     the construction of an index.
*   CLiP can extract any sort of file from the documentation. So all kind of
     additional files can be documented also, rather than the pure code only.
     One can think of files containing the error message templates of a system,
     batch files, internal tables that are present as a file, etc.
*   The special lines that CLiP recognizes can be adjusted to suit virtually
     any programming language. However, the system operates strictly on a line
     basis.
*   CLiP allows a fine-tuning of the module generation process by means of
     "options". But these are cosmetical and will not be discussed here.
*   Unlike WEB, CLiP has no compiler like knowledge and it does not extend the
     programming language one uses in any way. Nor does it compensate any nasty
     features.
 
4.3  Formatter and word-processor independence
 
CLiP simply processes all the lines that are enclosed between a special type of
comment lines it recognizes. Such segment should contain only code. CLiP copies
the lines from the sources into the modules without any formatting (i.e.
"verbatim" or "literal").
    This means that CLiP will cooperate with any formatter that has a command
like "verbatim" or "literal" (all formatters that we know off do have such a
command).
CLiP will process the same files that otherwise would be formatted.
    In a word-processor environment it is required that the word-processor has
an adequate ASCII-export, which eliminates formatting information. CLiP will
analyse the ASCII-files rather than the original word-processor files and
generate the modules from there. Again we do not know of any word-processor
where there could be a problem in this respect.
 
*   The documentation of refinement steps using CLiP is entirely free and only
     limited by the text processing system one is using. No order is imposed
     for the refinements nor any hierarchy in terms of sections and subsections
     (WEB is fairly restricted here).
*   No restrictions exist, other than the limitation of the particular
     word-processing system one uses, to explain the program that is
     documented. Illustration by means of tables, diagrams, figures or pictures
     are no problem.
*   CLiP generates modules that strongly resemble the code one finds in the
     documentation. This is convenient for the programmer who wants to use them
     for debugging purposes and the like. Although this does not really solve
     the so called "preprocessor problem", it makes it a lot easier to live
     with than in a WEB-environment [3].
 
5  Project status
 
Currently CLiP experiences its second version which exists for VAX/VMS (written
in VAX-Pascal) and for MS-DOS (written in Turbo Pascal Vision). Both systems
are of course documented as CLiP literate programs themselves.
    The user documentation of CLiP currently consists of a short description of
how CLiP works and should be used. Although it definitely does not have the
status of a manual, it should allow programmers to get along with the
CLiP-system.
    Currently we only have a limited number of examples and demos which
moreover are fairly trivial. Better ones are on the priority list. Of course we
have real systems build with CLiP (e.g. CLiP itself is a literate program in
CLiP) but they are too complex to qualify as useful examples.
 
6  Future activities
 
From the discussion inside the LITPROG group we infer that CLiP, due to its
original design philosophy, may be a valuable addition to the set of literate
programming tools. Our goal is to make CLiP as quickly as possible available to
the LP audience by means of anonymous FTP. We aim at the following time
schedule:
1.  Executable versions of CLiP for VAX/VMS and MS-DOS + provisional operating
     manual + trivial example program will be FTP-able by March 15, 1993.
2.  More extensive example programs in different programming languages will
     follow incrementally in the successive months.
3.  We are looking for an opportunity to have CLiP ported to Unix. Resources
     for a job like this are currently extremely scarce at our university, and
     unfortunately we are unable to set a date yet. External help would be very
     welcome.
 
7  References
 
1.  Ammers E.W. van et.al. 1984. "VAMP: A Tool for Programming by Stepwise
     Refinement". Internal report. Department of Computer Science, Wageningen
     Agricultural University.
2.  Knuth D.E., 1984. "Literate Programming". The Computer Journal 27, 2, pg.
     97-111.
3.  Ramsey N., Marceau C. 1991. "Literate Programming on a Team Project".
     Software Practice and Experience 21, 7, pg 677-683.
4.  Ammers E.W. van, Kramer M.R. 1992. "VAMP: A Tool for Literate Programming
     Independent of Programming Language and Formatter". CompEuro '92
     Proceedings, May 4-8 1992, the Hague, pg. 371-376.
 
                             I N F O R M A T I O N
 
For any information on the CLiP-system please contact
 
              Eric W. van Ammers
              Wageningen Agricultural University
              Department of Computer Science
              Dreijenplein 2
              6703 HB  Wageningen
              The Netherlands
              Voice: +31 (0)8370 83356/84154
              Fax:   +31 (0)8370 84731
              E-mail: ammers@rcl.wau.nl
 
From bart@cs.tamu.edu Wed Feb 24 10:27:56 CST 1993
Date: Wed, 24 Feb 93 10:27:56 CST
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Literate Programming without WEB & TeX
 
Leslie Lamport once said that it means ``What you see is all you'll
get'' even though the letters don't match.
 
Bart Childs
 
From Frank Wed Feb 24 20:32 GMT 1993
Date: Wed, 24 Feb 93 20:32 GMT
From: Frank Pappas <0004238973@mcimail.com>
Reply-To: LitProg@SHSU.edu
To: LitProg <LitProg@shsu.edu>
Subject: Literate programming and Ada
 
Eric W. van Ammers writes
>Who can help me on references describing the c-no-web and the AdaWEB
>system?
 
This post is somewhat lengthy because in addition to answering part
of Eric's answer, I want to take the opportunity to let this group
know about what I'm doing with Ada and literate programming.
 
AdaWEB is an early effort to provide an Ada-based WEB written. It was
developed by Y. C. Wu and T. Baker at the University of Florida.
Adatangle differs from other tangle processors in that it produces
formatted source code. Adaweave bunches statements like the original
weave processor and doesn't support include files nor file modules.
 
I am writing a new Ada-based WEB, called AWEB, that properly formats
the entire Ada language, supports include files, file modules, and
much more. A short overview appears at the end of this posting. I'm
just putting the finishing touches on Aweave, the weave processor,
and hope to have Atangle finished in about two months. AWEB will be
released with the same type of copyright that CWEB has and will be
placed on the appropriate ftp and mail server sites.
 
I intend to provide two versions of Atangle. One to produce
unformatted Ada source and one to produce formatted Ada source. Wu
and Baker gave me permission to enhance their Adatangle and use a
CWEB-like copyright, so I will use that as starting point for the
formatting tangle, which I will call fangle for now.
 
A formatting tangle is useful for people who need to provide
formatted Ada source for contractual obligations but who prefer to
write in WEB. For that reason fangle will copy Ada comments to the
source file and not produce section number comments.
 
I'm interested in hearing what people think should be done with the
TeX part of a section. Should it be copied as inline comments?
(In the example that follows -- indicates an Ada comment. Ada is not
case sensitive but I use uppercase for predefined Ada identifiers.)
Consider the following sections:
 
     @ Finally, here is the body for the |prompts| package.
 
     @<Body of |prompts| package@>=
     with TEXT_IO; use TEXT_IO;
     package body prompts is
       @<|display| body@>
       @<|confirmed| body@>
     end prompts;
 
     @ This procedure is provided to allow the author to annoy users
       by asking for confirmation on even the most trivial operations.
       This is decidedly user-unfriendly.
 
     @<|confirmed| body@>=
     function confirmed(s : string) return BOOLEAN is
       c: CHARACTER;
     begin
       display(s);
       loop
         GET(c);
         @<Return if the user responded correctly@>
         display(s, bad => TRUE); -- tell user response was invalid
       end loop;
     end confirmed;
 
     @ As another example of
     user unfriendliness, we make the user respond in upper case.
 
     @<Return if the user responded correctly@>=
     if c = 'Y' then
        return TRUE;
     elsif c = 'N' then
        return FALSE;
     end if;
 
should fangle produce:
 
     -- Finally, here is the body for the |prompts| package.
 
     with Text_IO; use Text_IO;
     package body prompts is
 
       ... omitted body of display
 
       -- This procedure is provided to allow the author to annoy users
       -- by asking for confirmation on even the most trivial operations.
       -- This is decidedly user-unfriendly.
 
       function confirmed(s : string) return BOOLEAN is
         c: CHARACTER;
       begin
         display(s);
         loop
           get(c);
           -- As another example of
           -- user unfriendliness, we make the user respond in upper case.
           if c = 'Y' then
             return TRUE;
           elsif c = 'Y' then
             return FALSE;
           end if;
           display(s, bad => TRUE); -- tell user response was invalid
         end loop;
       end confirmed;
 
     end prompts;
 
Should it only copy Ada comments or should it be a user option? What
about code enclosed within | |, \&{}, @t...@>? What about TeX control
sequences?
 
 *************** overview of AWEB ***************
 
    - Formats the language as illustrated in the Ada reference manual;
      in particular:
        *  all the variations of the select statement
        *  choices in variants, case statements, and exception handlers
        *  nested blocks
        *  subprograms with long parameter lists:
             if the following appears in the AWEB file, it formats to
             a single line if it fits:
               procedure name(arg_1: type_1; arg_2: type_2;...arg_n: type_n);
             otherwise, it formats to:
                procedure name
                            (arg_1: type_1;
                             arg_2: type_2;
                             ...
                             arg_n: type_n);
 
     - Include files as in CWEB, with a flavor of FWEB:
         @i and @I controlled with separate switches; might use @i
         for boilerplate like Mil-Std 2167A, and @I for program
         documentation.
     - Web macros with parameters as in spider
     - Style files and command line arguments
         * ALL COMMAND LINE SWITCHES can be placed in a style file
         * nested and default style files
         * separate switch for size of each main data structures:
           max_bytes, max_texts, max_modules, max_names, max_scraps,
           max_tokens, max_refs, stack_size, input line length,
           output line length;
           for example max_refs can be specified as -mb10k or -mb10240
         * separate switches to control special treatment of assignment
           operation, relational operators, and/or operators, negation,
           and membership operations.
     - Limbo option for placing user limbo text in generated file
     - TeX and LaTeX support selectable from command line switch
          Features that depend on LaTeX output routine may not work;
          I try to do something about this for LaTeX 3.0
     - Special formatting of Ada predefined identifiers:
          identifiers, such as CHARACTER, TEXT_IO, and TRUE, are
          supplied via a text file; user can altered file contents to
          reflect particular compiler\environment.
     - Special formatting of user predefined identifiers:
          like Ada-predefined, but formatted using different macro;
          can be used to highlight identifiers from project lexicon, like
          motor, volt, cell, CPU, etc.
     - Switch to allow automatic xref of single letter identifiers
     - Automatic xref of operator symbols used in infix form
     - Index entry for identifier declaration is underlined; entry
       for body is in italics.
     - Special formatting of based numbers:
          #16#EF9# formatted as $EF9_{16}$
     - Atangle will probably allow command line replacement of web macros
     - Atangle will allow command line selection of which file modules
       should/should not be generated. (Eventually I plan to optionally
       generate only those modules that have changed, but I won't promise
       this for the coming release)
     - custom identifier as in CWEB
     - custom_i identifier:
         similar to custom, but identifier is placed in index, not the
         control sequence, and if the identifier is followed by a
         parenthesized list, the list is treated as the parameter list for
         the custom control sequence:
         * example:
                % place this in limbo
                \def\Inty(#1,#2){\int_{#1}^{#2}f(x)dx}
 
                -- place the following in a definition section
                @f Inty TeXi
 
                -- place the following in a code section
                s := Inty(a,b);
 
           Then Inty, not \Inty, is placed in the index and
                \|s := \Inty(\|a,\|b);
           is generated in the code section.
 
 *************** end of overview of AWEB ***************
 
In addition to Aweave and Atangle, all the examples in the Ada
reference manual in have been rewritten in AWEB. I also developed
some torture tests. Once I release AWEB I will add any user reported
problems to the test suite. I am writing all of my commercial
software in AWEB so I intend to make whatever corrections or
enhancements are necessary to keep it production quality. (Also, note
the name of the company.)
 
I know there some literate programming tools available, but since my
network access is limited to e-mail, ftpmail, and mail servers, I'd
appreciate any explicit pointers to these tools. I will modify these
to support AWEB and add them to the distribution.
 
When AWEB is ready I will post a short notice to this group. As I
said before, that should be in about two months.
 
T. L. (Frank) Pappas
AWEB Software Technology
phone:(215) 789-3206
e-mail: fpappas@mcimail.com
 
From Timothy Wed Feb 24 22:43:53 GMT 1993
Date: Wed, 24 Feb 93 22:43:53 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
> Who said any thing about ASCII? Winword (aka Word for windows) is
> GUI. You can include mathematical formulas, graphs, you could even
> scan in your photo (as someone on this list suggested). I'm not a TeX
> expert, but I suspect Word for Windows can do anything it can do,
> with less of a learning curve.
 
Doubt if you'll sell that one here ...
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From plyon@emx.cc.utexas.edu Wed Feb 24 18:19:12 -0600 1993
Date: Wed, 24 Feb 93 18:19:12 -0600
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Literate Programming without WEB & TeX
 
> Who said any thing about ASCII? Winword (aka Word for windows) is
> GUI. You can include mathematical formulas, graphs, you could even
> scan in your photo (as someone on this list suggested). I'm not a TeX
> expert, but I suspect Word for Windows can do anything it can do,
> with less of a learning curve.
 
I agree on the learning time for GUI based word processors, but TeX
has several advantages here that one needs to bear in mind.
 
First of all, TeX runs on much larger variety of platforms than any
GUI based word processor at present (so far as I know, at any rate),
and this seems unlikely to change any time soon.
 
Secondly, because TeX is (deliberately) limited to fonts that have TeX
font metrics files, it is able to do a better job of formatting than
word processor sytems that must cope with the vagarities of a thousand
and one printers. TeX is, after all, a *typesetter*, not a word
processor.
 
Thirdly, though its macro language is not easy to use, it does give
one a certain flexibility in formatting that GUI based word processors
do not often have. Adjustments in layout can be made as precisely as
one likes by altering TeX formatting parameters, repetitive bits can
be reduced to macros, and so on.
 
Fourthly, TeX is public domain. Not only is one not tied to a
proprietary system, but one can also benefit from the contributions of
others to the publically available pool of TeX (and LaTex, AMS Tex,
etc.) macros and macro packages. One need only obtain a copy of the
TeX-index from niord to see what is available. Provided that something
suitable is out there, one may be able to get around part of the
difficulties of TeX's command language courtesy the time and effort
that someone else has already put in. For example, if one wants
attractive tree diagrams in the woven source, one can use the TreeTeX
package that Anne Brueggemann-Klien and Derick Wood put together.
(Mind you, I have not tried TreeTeX with Cweb or Fweb, so I do not
whether there are any name conflicts in need of resolution, or the
like, that might prevent use of TreeTex as is.)
 
For me, at least, given that I have already invested the time and
energy to learn TeX (however imperfectly :-), these considerations are
sufficient.
 
Ciao,
 
Paul Lyon
 
From stephan@stack.urc.tue.nl Thu Feb 25 11:01:17 +0100 1993
Date: Thu, 25 Feb 1993 11:01:17 +0100 (MET)
From: stephan@stack.urc.tue.nl (Stephan Eggermont)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
> Who said any thing about ASCII? Winword (aka Word for windows) is
> GUI. You can include mathematical formulas, graphs, you could even
> scan in your photo (as someone on this list suggested). I'm not a TeX
> expert, but I suspect Word for Windows can do anything it can do,
> with less of a learning curve.
>
> 	-Ed K.
 
Apart from the problems noted by others, I see a few others:
- TeX has a lot less bugs, which is very important to those of us with
  deadlines;
- there is no way to automatically change font style for the (pascal) keywords
  in Word (at least the Mac version, does wordbasic help?);
- the interchange format of Word, RTF, is not very well defined (at least in
  the document Microsoft makes available), and is subject to changes.
 
Extracting code from an RTF document is rather trivial when you define a
code style, just copy the part after the '{\codestyle' till the corresponding
'}' into the code file.
 
  Stephan Eggermont
  stephan@stack.urc.tue.nl
 
From Joachim Thu Feb 25 11:41:55 +0100 1993
Date: Thu, 25 Feb 1993 11:41:55 +0100 (MEZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: CLiP: a universal literate programming tool
 
Eric. W. van Ammers wrote:
>
> 4.1  General design differences
>
> *   CLiP works not "monolithic" (like WEB does). It processes up to 64 (the
>      number can be adjusted) inputfiles in one run. From this input it produces
>      as many modules as are specified by the user. Thus it is possible to
>      generate a complete software system in one single CLiP-run.
 
Two questions:
 
(1) Where is WEB "monolithic"?
	(Please don't answer me that Pascal is monolithic. I ask where
    *WEB* itself is monolithic.)
 
(2) I get the impression that in the text above the ability to process
    only one file at time is synonym to "monolitic".
    	Is this correct?
        If yes, this would mean that a C++ compiler who can process
    only one C++ source file makes the C++ language monolithic...
 
Furthermore I have the impression that you compare mostly with the
original WEB (ie, Knuth's Pascal WEB).
    May you please include the capabilities of more modern WEBs (eg,
FWEB, CWEB, noweb, or FunnelWEB) in your comparison as well?
Otherwise I would not consider it objective.
    And if you talk of a ``WEB-environment'': May you also consider
some WEB environments as outlined in the usual bibligraphies on
Literate Programming? There has been dissertations and a lot of
publications in this area...
 
Oh yes, and I don't understand why pseudo-comments are better than
explicit tags. Both is markup.
 
Regards,
 
    Joachim
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Joachim Thu Feb 25 11:45:05 +0100 1993
Date: Thu, 25 Feb 1993 11:45:05 +0100 (MEZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate programming and Ada
 
Frank Pappas wrote:
>
> AdaWEB is an early effort to provide an Ada-based WEB written. It was
> developed by Y. C. Wu and T. Baker at the University of Florida.
 
Is this system freely distributable?
May you point us to a location where to get it from?
 
> I am writing a new Ada-based WEB, called AWEB
 
Hmm, there is already an AWEB, written by U. Schweigert.
 
I'm posting retrieval info RSN.
 
--
Joachim
 
From gilligan@central Thu Feb 25 09:41:03 MST 1993
Date: Thu, 25 Feb 93 09:41:03 MST
From: gilligan@central (Jonathan M. Gilligan)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Some thoughts on Word-for-Windows as part of a WEB system
 
Eric Scharff writes:
   On Tue, 23 Feb 23:44, "Edward F. Keith" <ed@efkport.kew.com> wrote:
 
   I've never used Microsoft Word for Windows, so I can't comment on its power
   as a desktop publisher.  However, from what I know about its style sheets,
   if you have a good understanding of the file format, it shouldn't be
   difficult to WEAVE WEB output that would use these style options (for code
   and such.)  However, are you suggesting a TANGLE that takes a Microsoft
   Word for Windows file as input?  That sounds a bit more complex...
 
Actually, WFW has a pretty powerful macro language (which bears a
strong resemblance to BASIC, surprising no one who's followed Bill's
excellent adventure) and it might be possible for an ambitious WFW
programmer to write a weave/tangle pair in WFW BASIC, avoiding the
problems of reading a weird file format, and with the added feature
that a Windows hypertext help-file could be generated at the same time
(a hypertext woven output with hotlinks between different parts of a
module would be a fantastic alternative to reading the unformatted WEB
or printing it out every day or two---I'm contemplating building a
texinfo-like interface to CWEB, but I need to become much more
familiar with WEB programming to be able to make appropriate design
decisions, so this idea is not even at the vapor stage yet). I am not
intimate with WFW, since I like TeX and don't want to spend lots of
time now learning a new system, but the possibilities seem promising
for the more WYSIWYG oriented.
 
It's possible that this could even be a quasi-real-time incremental
WYSIweave, although I'm not sure how one should handle
cross-references to still-undefined symbols.
 
The great advantage this would give a programmer is that I often want
to put a figure into my documentation and doing this with TeX and CWEB
is enough of a pain that I avoid doing it. If I could sketch a figure
in a drawing program and cut-and-paste into my WEB, that would be a
real treat.
 
---Jon
 
From adb-b@minster.york.ac.uk Thu Feb 25 16:54:14  1993
Date: Thu, 25 Feb 93 16:54:14
From: adb-b@minster.york.ac.uk
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: String pools
 
As part of my final year project I am investigating
literate programming, and in particular, an WEB system
for Ada. This is based very closely on Knuth's orginal
TANGLE and WEAVE.
 
Examining TANGLE, however, I am confused by the notion
of ``string pools''. Coming from an Ada background I
have not come across such a facility. I am especially
puzzled by the different handling by TANGLE of strings
terminated by '' and "".
 
Can anyone help?
 
thanks,
andy
 
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
| Andrew D. Brydon   |      Email:    adb-b@minster.york.ac.uk             |
| University of York |-----------------------------------------------------|
| York, ENGLAND.     |    Project:    Literate programming in Ada          |
| YO1 5DD            |     (email:    adb-b-web@minster.york.ac.uk)        |
|--------------------------------------------------------------------------|
|     "There are no bugs in my software - just undocumented features."     |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
From leew@cs.utexas.edu Thu Feb 25 12:14:47 -0600 1993
Date: Thu, 25 Feb 1993 12:14:47 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: weave+tangle for Oberon-2 ??
 
Lothar Meyer-Lerbs writes:
 
  > Has anyone created a beast like that? Or is FWEB going to do
  > that too (real soon now) ?
  >
  > Thanks Lothar
 
Spidery WEB is probably the tool you want to use to create an Oberon-based
WEB system.  The prettyprinting grammar should be relatively easy to write.
The only problem you might have is in using D instead of E in floating
point constants.  Spidery WEB has the character 'E' hard-coded into the
lexical analysis code.  However, you could create a simple change file for
the Oberon version, or don't use constructions like 7.5D27.
 
		-- Lee
 
From Timothy Thu Feb 25 18:14:53 GMT 1993
Date: Thu, 25 Feb 93 18:14:53 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Timpthy Murphy
 
> What are .ch files ?
 
In Knuth's WEB system, you run tangle
on x.web and x.ch to get the Pascal file x.pas.
 
tangle x.web x.ch |-> x.pas
 
Similarly with CWEB (to get x.c),
and I would presume all kinds of WEB.
 
(Similarly you run weave to get x.tex
 
weave x.web x.ch |-> x.tex
 
giving the documentation for your program.)
 
So eg there are tex.ch's, mf.ch's, ...
for different machines,
different compilers, etc.
Knuth says in tex.web that it may not be changed
under nameless penalty
"unless your name is Donald Knuth".
 
The idea in general -- to which I was referring --
is that web files are sacrosanct,
but anybody, no matter how humble,
can roll their own .ch file.
 
(.ch = change, I assume.)
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From leew@cs.utexas.edu Thu Feb 25 13:07:22 -0600 1993
Date: Thu, 25 Feb 1993 13:07:22 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: address of clowney???
 
Zdenek Wagner writes about an email address that looks like
"clowney@gandals.rutgers.edu" that didn't work.  It may be that "gandals"
should be "gandalf", as Tolkien is rather popular as a source for machine
names.
 
		-- Lee
 
From leew@cs.utexas.edu Thu Feb 25 13:22:38 -0600 1993
Date: Thu, 25 Feb 1993 13:22:38 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Portable C/F/WEB
 
Philip Rubini writes:
 
  >What I think I need is a small litprog tool that allows embedded
  >documentation but also keeps the destination code fairly visible so
  >that I can argue that I am using a documented form of, in my case,
  >Fortran, that is readily understandable to someone familiar with
  >Fortran. Obviously all of the features of a Web variant would be
  >usefull, such as contents lists, indexes, variable lists/xrefs etc.
 
You might want to look at Norman Ramsey's NOWEB (available via anonymous ftp
from princeton.edu in the pub/noweb directory.  It's programming-language
independent, and is compatible with either plain TeX or LaTeX.  It also
includes a tool called NOUNTANGLE, that "transforms a literate program into
a traditional commented program, without loss of information and with only
a modest penalty in readability."\footnote{from Ramsey's article,
"Literate-Programming Tools Need Not Be Complex", included in the NOWEB
distribution.}  NOUNTANGLE is designed so that if the literate programming
"experiment is unsatisfying, it is easy to abandon".\footnote{Ibid.}
 
NOWEB is mostly a collection of shell and awk scripts, so it should run on
almost any UNIX system.  It can also be converted (painfully) to run under
MS-DOS (if you need a DOS version, don't go through the agony yourself --
I'll be glad to send it to you).
 
Hope this helps.
 
		-- Lee
 
From Zdenek Thu Feb 25 15:21:19 MDT 1993
Date: Thu, 25 Feb 93 15:21:19 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: address of clowney???
 
I apologize myself for bothering you. I tried to answer to a person with
address  which looked as clowney@gandals.rutgers.edu. I made probably a
misprint somewhere so that it returned to me as undelivarable. Unfortunately,
due to small disk space, I have already scratched the original mail which
I received from LitProg. I therefore ask that person for a correct address
so that I can send the mail and files.
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `           ~~~  ~~/ '  '  ~~~
                              Zdenek Wagner______/
 
From bbeeton Thu Feb 25 15:21:19 MDT 1993
Date: Thu, 25 Feb 93 15:21:19 MDT
From: bbeeton <BNB@MATH.AMS.ORG>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
Edward F. Keith, 23 Feb 1992:
 
   "I'm not a TeX expert, but I suspect Word for Windows can do
    anything it can do, with less of a learning curve."
 
maybe it's not really relevant to literate programming, but some
of us represent publishers.  there are only a few text processing
systems that produce publishable-quality mathematics, and word
for windows is *not* one of them.  tex is the only one that is
not proprietary, and available at prices that our authors can
afford.
						-- bb
 
From  Thu Feb 25 18:25:43 +0100 1993
Date: Thu, 25 Feb 1993 18:25:43 +0100
From: " (Bernhard Lang)" <Lang@tu-harburg.dbp.de>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Timpthy Murphy
 
>
> >   some days ago I did mail a request for a running Spiderweb on IBM
> >...
>
> Isn't Spiderweb itself written in WEB?
> In which case should changes not be in the form of .ch files?
>
> Timothy Murphy
> ...
 
What are .ch files ?
 
Bernhard
 
----------------------------------------------------------------------
Dr. Bernhard Lang                        TU Hamburg Harburg
					 Technische Informatik I
                                         email: lang@tu-harburg.dbp.de
----------------------------------------------------------------------
 
From Timothy Thu Feb 25 23:34:09 GMT 1993
Date: Thu, 25 Feb 93 23:34:09 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: String pools
 
> Examining TANGLE, however, I am confused by the notion
> of ``string pools''. Coming from an Ada background I
> have not come across such a facility. I am especially
> puzzled by the different handling by TANGLE of strings
> terminated by '' and "".
 
Tangle removes all "This is a string" strings
and replaces them, effectively,
by the number of the string.
These strings are then saved in the file prog.pool,
assuming the program is prog.web .
(By convention 1-character strings "A", etc,
are replaced by their ASCII code,
but are not saved in prog.pool.
So the first string in prog.pool is actually no 128.)
 
I think one of the aims of this
was to facilitate multilingual programs,
but I'm not sure about that.
Or it may just have been to make the program smaller,
in the old days when a byte was a byte.
 
Not many web files actually use this facility --
I think only tex.web and mf.web.
The contents of tex.pool or mf.pool
are included in the .fmt and .base files.
That is why initex and inimf
require the appropriate pool files
to be present.
 
A string 'This is a string'
is just treated as a string in the usual way.
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From ae1181t@stnfor.ae.ge.com Thu Feb 25 20:22:32 -0500 1993
Date: Thu, 25 Feb 93 20:22:32 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
I think a lot of people are just talking about the look of the document.
But how about the code fragments and macro expansions that are done by
the WEB systems? I dont think that can be accomplished easily!
 
From ae1181t@stnfor.ae.ge.com Thu Feb 25 20:27:09 -0500 1993
Date: Thu, 25 Feb 93 20:27:09 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: weave+tangle for Oberon-2 ??
 
Spidery WEB and FunnelWEB are the only two that I know can be used for
most any language.
 
From Reino Fri Feb 26 09:38:11 +0100 1993
Date: Fri, 26 Feb 93 09:38:11 +0100
From: Reino de Boer <sysrb@cs.few.eur.nl>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: String pools
 
Timothy Murphy <tim@maths.tcd.ie> wrote
 
> I think one of the aims of this
> was to facilitate multilingual programs,
> but I'm not sure about that.
> Or it may just have been to make the program smaller,
> in the old days when a byte was a byte.
 
From page xii of "TeX: The Program":
 
	This makes it possible to circumvent Pascal's limited
	string-manipulation capabilities.
 
In the old days of the current version of standard Pascal level 0, it is not
possible to have variable length strings.  Strings are represented as
"packed array of char".  This means that a routine like
 
	function f(s : string) : boolean;
	begin
		{ check some condition for s, e.g., if it's in a table }
	end;
 
would need a type declaration like
 
	type	string = packed array [1..STRINGMAX] of char;
 
where "STRINGMAX" would be a suitably large constant.  These `strings' would
then be padded with blanks, making it almost mandatory to rewrite our function
as
 
	function f(s : string; len : integer) : boolean;
	...
 
I suspect that this is part of what Knuth meant by "limited string-manipulation
capabilities".
 
Reino
--
Reino R. A. de Boer
CS Dept, Faculty of Economics, Erasmus University Rotterdam
email: sysrb@cs.few.eur.nl
NIS has given `world readable' a somewhat broader meaning (Casper H.S. Dik)
 
From me028a@xdm001.ccc.cranfield.ac.uk Fri Feb 26 09:58:31 GMT 1993
Date: Fri, 26 Feb 93 09:58:31 GMT
From: me028a@xdm001.ccc.cranfield.ac.uk
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Portable C/F/Web - Summary
 
Recently I posted the following question regarding the portability of
Web programs ....
 
> I am keen to use a WEB variant but am concerned about the question of
> portability of my web code. I am developing a modest program of approx.
> 20000 lines of Fortran which will continue to be developed in the
> future, hence the desire to document the code. However the actual
> source code will be distributed to a number of different groups (those
> funding the research !) - here is my concern - if I write the code in a
> Web variant then I must distribute not only my code but possibly a much
> larger Web environment. It seems to me that a well written web code
> will not resemble the destination language to any great extent hence
> the second problem - those I distribute the code to must learn the Web
> syntax if they wish to further develop the code, which they probably will.
 
> What I think I need is a small litprog tool that allows embedded
> documentation but also keeps the destination code fairly visible so
> that I can argue that I am using a documented form of, in my case,
> Fortran, that is readily understandable to someone familiar with
> Fortran. Obviously all of the features of a Web variant would be
> usefull, such as contents lists, indexes, variable lists/xrefs etc.
 
The suggested possibilities are summarised below :-
 
1) Use FWEB for its features but suffer its complexities and pursuade those
   who receive my programs to learn FWEB or let them update only the Fortran
   code.
 
2) Use FunnelWeb - simpler than FWEB, produces readable program code, no pretty
   printing.
 
3) Use NoWeb - even simpler, no macros etc., produces readable program code.
 
4) Use Loom. Not a Web variant, extremely simple -suitable for documenting
   existing codes (?).
 
At present I think I can use both Loom and Noweb, Loom (or a Fortran
version of it) for existing programs and Noweb for new programs.
Personally I found FunnelWeb, although much simpler than FWeb, to still
have a confusing syntax with @'s everywhere (I would prefer readable
words like 'Begin macro' etc.). I do think that pretty printed code
would be nice (pretty !) - do (La)Tex pretty printers exists for C and
Fortran outside of the LitProg environment ?
 
Any other comments or additions would be most welcome.
 
Philip Rubini
 
School of Mechanical Engineering
Cranfield Institute of Technology
Cranfield
Bedfordshire, MK43 0AL
ENGLAND
 
Tel. +44 234 754649
Fax. +44 234 750728
 
Email.   p.rubini@uk.ac.cranfield    (UK - JANET)
         p.rubini@cranfield.ac.uk    (Elsewhere in the world)
 
From Edward Fri Feb 26 05:44:05 EST 1993
Date: Fri, 26 Feb 1993 05:44:05 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate Programming without WEB & TeX
 
On Wed, 24 Feb 1993 17:07:57 +0730, "Eric Scharff" <eds2@cornell.EDU> wrote:
>
> I've never used Microsoft Word for Windows, so I can't comment on its power
> as a desktop publisher.  However, from what I know about its style sheets,
> if you have a good understanding of the file format, it shouldn't be
> difficult to WEAVE WEB output that would use these style options (for code
> and such.)  However, are you suggesting a TANGLE that takes a Microsoft
> Word for Windows file as input?  That sounds a bit more complex...
>
That's what I'm suggesting. I'm not sure how to do it.
	-Ed K.
 
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From Edward Fri Feb 26 05:50:28 EST 1993
Date: Fri, 26 Feb 1993 05:50:28 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate Programming without WEB & TeX
 
On Wed, 24 Feb 93 22:43:53 GMT, "Timothy Murphy" <tim@maths.tcd.IE> wrote:
> > Who said any thing about ASCII? Winword (aka Word for windows) is
> > GUI. You can include mathematical formulas, graphs, you could even
> > scan in your photo (as someone on this list suggested). I'm not a TeX
> > expert, but I suspect Word for Windows can do anything it can do,
> > with less of a learning curve.
>
> Doubt if you'll sell that one here ...
 
I realize that this violates the religious dogma, and that no
rational argument can have any effect. So I will not press it.
 
"There is no got but DEK, and TeX is his holy word."
 
	-Ed K.
 
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From coates@spectro.jussieu.fr Fri Feb 26 13:51:03 +0100 1993
Date: Fri, 26 Feb 93 13:51:03 +0100
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
> I think a lot of people are just talking about the look of the document.
> But how about the code fragments and macro expansions that are done by
> the WEB systems? I dont think that can be accomplished easily!
>
 
I suspect that by writing a separate program under Windows, and hot-linking to
the WFW file via DDE, that you could do the macro expansions, etc., if it
seemed infeasible via WordBasic.  The code for this could be taken largely
from current WEB-type code, with the additions necessary for handling DDE.
It should be possible, as with other DDE hot-links, to then have the macros
updated whenever the sources are updated.  At least, in theory this all
should work anyway, but I'm not saying that I've yet done enough Windows
programming to be sure.
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From ae1181t@stnfor.ae.ge.com Fri Feb 26 08:28:36 -0500 1993
Date: Fri, 26 Feb 93 08:28:36 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Portable C/F/Web - Summary
 
I just learned of another litprog tool that claims to be universal:
CLiP from netherlands (sun01.info.wau.nl). But it not ready to be
distributed, will be by march 15. The only problem is that it works
on only VAX VMS and MSDOS !
 
From Frank Fri Feb 26 14:44 GMT 1993
Date: Fri, 26 Feb 93 14:44 GMT
From: Frank Pappas <0004238973@mcimail.com>
Reply-To: LitProg@SHSU.edu
To: LitProg <LitProg@shsu.edu>
Subject: Ada and literate programming
 
The mail I get from LitProg@shsu.edu does not provide the senders
mailing information. It has LitProg for the senders name and
MCI mail's INTERNET address as the sender's address. For that reason
I don't know Joachim's last name, but he writes
 
>> AdaWEB is an early effort to provide an Ada-based WEB written. It was
>> developed by Y. C. Wu and T. Baker at the University of Florida.
 
>Is this system freely distributable?
>May you point us to a location where to get it from?
 
First, let me correct a mistake on my part. Wu and Baker are from
Florida State University, not the University of Florida.
 
As for distribution, I have a copy but I don't think it would be
proper for me to distribute it. I will check with Baker if he still
wants to distribute it. However, you should be aware that AdaWeave is
written in Pascal and AdaTangle is written in Ada. Both are Sun
dialects.
 
I didn't mention it in my earlier posting, but my Ada web is written
in portable Ada and should compile and execute on a PC AT clone. I
have 286 and 386 Ada compilers from two different vendors, so I will
make sure it works properly under DOS and hopefully Microsoft
Windows.  I will distribute executables for DOS. By the end of the
year GNU Ada will available for DOS and (I think) UNIX, so you won't
have to go out and buy an Ada compiler.
 
There is a change in plan about releasing my AWEB. Someone is
seriously considering using it on a significant Ada project. The
project, which I won't mention unless they decide to go ahead with
using AWEB, will be a substantial example of literate programming
that doesn't involve TeX or web. The project will have a great deal
of visibility in the Ada programming community and in the U.S.
Department of Defense, and will be highly visible to the general
programming community as well.
 
Because I think this project provides an excellent opportunity to
demonstrate the applicability of literate programming, because the
project leader likes literate programming, and because I'm a really
nice guy, I have promised him that I would have the complete weave
and the nonformatting version of tangle ready in about two weeks.
Some of the items I planned for tangle that are not essential, like
command line replacement of macros, will be postponed.
 
Anyway, when I this release ready I will make it a general release
and place it on the appropriate archives. The formatting version of
tangle and the features I don't put in now, should still be ready in
about two months.
 
>> I am writing a new Ada-based WEB, called AWEB
 
>Hmm, there is already an AWEB, written by U. Schweigert.
 
>I'm posting retrieval info RSN.
 
Yes, I'm familiar with Schweigert's ``AWEB'' but I have decided to
use the name for several reasons. First, I don't think Schweigert's
version has been supported in years. Second, I have been using the
name for several years for an earlier version of web that I wrote
several years ago, but never released. Third, it happens to be part
of the name of my company, so it shows commitment to the product. In
some circles that is important.
 
Finally, with my apologies to Schweigert, the version I have access
to has problems. It may be that I have an old version or beta version
of his AWEB, or that someone modified it before placing it on the
archive I retrieved it from.  Anyway, It doesn't support real Ada
since it doesn't support Ada comments. Instead you must use @{, @}
for comments.  It doesn't support the allowable replacement symbols
which are probably useful in Europe. His weave bunches statements
together and could do a better job of formatting. I also ran into
runtime errors on legitimate web programs.
 
However, Schweigert's weave did provide me with some ideas for my
weave. His weave highlights Ada predefined identifiers, which gave me
the idea to add that to my weave. I used his grammar as a starting
point and then changed it significantly as I improved the formatting.
(I doubt if I'm using more that 10 percent of his original grammar).
There are a few other ideas I borrowed from his weave as well.
 
Actually, the introduction to my weave credits Schweigert, along with
Wu and Baker, and of course DEK, Silvio Levy, Norman Ramsey, and John
Krommes for influencing my Ada web system. Anyway, unless I hear from
Schweigert that he is actively planning to support his version and
bring it up to the level that I have brought mine, I will continue to
call my version AWEB. For that reason I would appreciate not having
Schweigert's version distributed.
 
If someone wants to use an Ada-based web immediately, try Norman
Ramsey's outstanding Spider to generate an Ada web. It generates a
weave and tangle for Ada, both of which are written in C. I know the
University of Washington Unix TeX archive has Spider. I don't know if
Norman still has his at princeton.edu.
 
If I remember correctly, there are some Ada limitations since Spider
is a general purpose web generator. For example, I think there are
some errors in its handling of lexical elements, which shouldn't be
too difficult to fix. Another problem is the grammar. It handles
much of Ada correctly but there are some places where the indentation
isn't handled properly. Let me emphasize that it is not a problem
with Spider, just the grammar, which you are free to modify.
 
If you want to use Spider's Ada web for now and my AWEB later, just
use lowercase for all of the control codes and don't use the @' or @`
control codes. Following those guidelines programs that weave and
tangle correctly with Spider's Ada web should also do so with my
AWEB, although the formatting will be different.
 
--Frank Pappas
  e-mail:fpappas@mcimail.com
  phone: (215) 789-3206
 
From Timothy Fri Feb 26 15:07:26 GMT 1993
Date: Fri, 26 Feb 93 15:07:26 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Portable C/F/Web - Summary
 
> I just learned of another litprog tool that claims to be universal:
> CLiP from netherlands (sun01.info.wau.nl). But it not ready to be
> distributed, will be by march 15. The only problem is that it works
> on only VAX VMS and MSDOS !
 
A universal program that works only on PC's.
This has to be an oxymoron ...
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Thompson, Fri Feb 26 15:07:26 GMT 1993
Date: Fri, 26 Feb 93 15:07:26 GMT
From: "Thompson, David B." <wqdbt@ttacs1.ttu.edu>
Reply-To: LitProg@SHSU.edu
To: "litprog" <litprog@shsu.edu>
Subject: Re: weave+tangle for Oberon-2 ??
 
> Spidery WEB and FunnelWEB are the only two that I know can be used for
 
> most any language.
 
FWIW, I think that Norman Ramsey's noweb will work too.  (Did someone
already say this??? ;-)
 
-=d
 
From S.C.Cross@bnr.co.uk Fri Feb 26 16:45:54 GMT 1993
Date: Fri, 26 Feb 93 16:45:54 GMT
From: S.C.Cross@bnr.co.uk
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
In my previous post to this group I wrote:
 
>
> Do we realy need to use TeX and WEB?
>
> Why not write literate programs in a wordprocessor or some kind of WYSIWYG
> desktop publishing tool and extract the code from there.  It seems to me that
> this approach would be far more programmer friendly.  Such a system could
> make use of hypertext links to requirements, analysis, designs, and other
> source documents.
>
> Does any such system aready exist?  The reason why I ask is because I am
> thinking of writting such a tool as a final year project.  Any suggestions?
>
> Steve.
>
 
Well all the followup posts have been very helpful and my current idea for a final year project is to:
 
(1) Look at extending the method for object oriented literate programming
 
(2) Look at how analysis and designs can be incorporated into a literate
    document
 
(3) Write Literate programs direct into a WYSIWYG word processor (ie write the
    woven document, no need to weave it from a source file)
 
(4) Look at how hypertext links could be used to improve the method
 
(5) Write a tool to extract (Tangle) the code from the word processor.  This
    could be done from within the word processor using macros, or a command
    line tool which processes a document file.
 
(6) The tool/method will support C++
 
I have not decided what operating system or word processor to use yet but it is likely to be one of
 
-  Unix/Framemaker
-  Windows/Framemaker
-  Windows/Word
-  Windows/Wordperfect
-  Windows/Amipro
 
It all depends on what I can get access to.  Framemaker or Word seem the most likely.
 
Your comments are welcome
 
Steve.
 
----------------------------------------------
Stephen Cross,  Systems & Software Engineering
BNR Europe Ltd, Harlow, Essex, England
Email: scc@bnr.co.uk
Internal Tel  : 742 2861
External Tel  : +44 (0)279 402861
 
From leew@cs.utexas.edu Fri Feb 26 11:15:11 -0600 1993
Date: Fri, 26 Feb 1993 11:15:11 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
Osman F Buyukisik writes:
 
  > I think a lot of people are just talking about the look of the document.
  > But how about the code fragments and macro expansions that are done by
  > the WEB systems? I dont think that can be accomplished easily!
 
True.  But I suspect that it can be done.  I suspect that a MS Word-based
WEB would provide a TANGLE menu item, which would produce the C, Pascal, or
whatever code (maybe even call the compiler!).  The tangling algorithm
could be ``borrowed'' from any of the extant tangle tools, and if internal
macros are desired, Kernighan & Plauger's "Software Tools" books provide a
lovely little macro preprocessor that could (probably) be translated into
WordBasic.
 
		-- Lee
 
From leew@cs.utexas.edu Fri Feb 26 11:25:27 -0600 1993
Date: Fri, 26 Feb 1993 11:25:27 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Portable C/F/Web - Summary
 
Philip Rubini asks:
 
  > I do think that pretty printed code
  > would be nice (pretty !) - do (La)Tex pretty printers exists for C and
  > Fortran outside of the LitProg environment ?
 
There is a cprog.sty file for typesetting C code.  It's available via
anonymous ftp somewhere (I forget where -- anyone?).  It does a pretty good
job of typesetting C, and is also supposed to work for C++, Pascal, and
Modula-2.
 
		-- Lee
 
From Timothy Fri Feb 26 19:46:39 GMT 1993
Date: Fri, 26 Feb 93 19:46:39 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
> On Wed, 24 Feb 93 22:43:53 GMT, "Timothy Murphy" <tim@maths.tcd.IE> wrote:
> > > Who said any thing about ASCII? Winword (aka Word for windows) is
> > > GUI. You can include mathematical formulas, graphs, you could even
> > > scan in your photo (as someone on this list suggested). I'm not a TeX
> > > expert, but I suspect Word for Windows can do anything it can do,
> > > with less of a learning curve.
> >
> > Doubt if you'll sell that one here ...
>
> I realize that this violates the religious dogma, and that no
> rational argument can have any effect. So I will not press it.
>
> "There is no got but DEK, and TeX is his holy word."
 
What I doubt if you will sell is that Word for Windows
will do anything TeX will do.
Especially printing mathematical formulae,
which you explicitly cite.
Do you claim that it does this as well as TeX?
If so, could you point to some published mathematical work
to support your claim?
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From dak@POOL.Informatik.RWTH-Aachen.DE Fri Feb 26 22:04:33 +0100 1993
Date: Fri, 26 Feb 93 22:04:33 +0100
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
>On Wed, 24 Feb 93 22:43:53 GMT, "Timothy Murphy" <tim@maths.tcd.IE> wrote:
>> > Who said any thing about ASCII? Winword (aka Word for windows) is
>> > GUI. You can include mathematical formulas, graphs, you could even
>> > scan in your photo (as someone on this list suggested). I'm not a TeX
>> > expert, but I suspect Word for Windows can do anything it can do,
>> > with less of a learning curve.
>>
>> Doubt if you'll sell that one here ...
>
>I realize that this violates the religious dogma, and that no
>rational argument can have any effect. So I will not press it.
>
>"There is no got but DEK, and TeX is his holy word."
 
Come on, take a break here. TeX works with ASCII, or even stranger
character sets. TeX is free, and available for almost any platform.
Even if you disregard that Winword must be paid for, and paid for
dearly, you cannot presume that everybody will only work under PCs,
and don't presume that DOS is the only thing (apart from its
succubus Windows) which will ever be of interest on these gadgets.
 
Besides, different versions of that word processing package have
a difficult time understanding each other. You can rely on TeX
remaining absolutely compatible, not because it is the best thing
possible around, but because it is a reasonable good and versatile
thing, INTENDED to stay fixed and free.
 
And you get complete source as well for the Literate Tools. That
ensures you that you can do a change of computing platform
painlessly. Winword would fix you on one Platform, and one
system typo, and one OS, and payable as well. While this might
be acceptable to a certain degree in companies, it is certainly
not so in an academic field, if you want to do something of
general interest.
 
From tfj@apusapus.demon.co.uk Fri Feb 26 23:28:38 GMT 1993
Date: Fri, 26 Feb 93 23:28:38 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
In message <9302261715.AA11809@im4u.cs.utexas.edu> you write:
> Osman F Buyukisik writes:
>
>   > I think a lot of people are just talking about the look of the document.
>   > But how about the code fragments and macro expansions that are done by
>   > the WEB systems? I dont think that can be accomplished easily!
>
> True.  But I suspect that it can be done.  I suspect that a MS Word-based
> WEB would provide a TANGLE menu item, which would produce the C, Pascal, or
> whatever code (maybe even call the compiler!).  The tangling algorithm
> could be ``borrowed'' from any of the extant tangle tools, and if internal
> macros are desired, Kernighan & Plauger's "Software Tools" books provide a
> lovely little macro preprocessor that could (probably) be translated into
> WordBasic.
 
I have long dreamt of such a tool. Shortly after hearing DEK's London talk
I wrote in answer to a question in my Master's examination that with (the
then emerging) powerful workstations ever programmer should have a WEB
system available.
 
As a result of my recent real use of Literate Programming (reported last
month) my thoughts have returned to the features that such a tool would
provide. My programming environment of choice (given that I paid for it
with my hard-earned pounds) is MS-Windows the discussion of using WordBasic
is interesting but I think misguided.
 
As a programmer I need assistance during the writing of the code. I need to
be able to examine another section of the (potentionally incomplete) WEB. I
want to be able to scroll through the code section, the macros and the text
description for any one section of the text. I want to be able to point at
a ``variable'' and have the details of the item shown to be, irrespective
of whether it is a named code section, a macro, a variable or something
that I've forgotten to define/decalre.
 
I dont think that WordBasic excellent as it might be (and I intend to
invest more of my hard-earned cash upon a copy soon) will actually be up to
performing all tose things.
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From pcolsen@super.org Sat Feb 27 07:37:19 EST 1993
Date: Sat, 27 Feb 93 07:37:19 EST
From: pcolsen@super.org (Peter C Olsen)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
Let me suggest another approach to Stephen Cross and his project...
 
I don't think that the objection most people have to WEB, CWEB, FWEB,
and friends is the "back end" *output* of TeX (which looks wonderful
and is a pleasure to the eye), but rather the *front* end (which often
looks like the set of characters you get when your parity is wrong).
I'm a regular TeX user, and I still find all the special WeB
constructs intimindating.
 
One way around this is to try to fix only that which is "broken" ---
the front end.  I don't think that "full WYSISYG" is the best way to
do that.  I think that most WYSIWYG word processors spend too much
time on their screen presentation and too little on making it easy to
write.  Even then their screen presentations aren't true WYSIWIG
because the paper *never* looks exactly like the screen.  I think that
there's a broad gulf between raw WEB and FrameMaker or Microsoft WORD
*and* that there are some tools that will let you nicely fill it.
 
One is, for example, Lucid Emacs 19 running under a windowing system.
As I understand it (unfortunately, my installation isn't working very
well yet), you can change the color or font of individual words to
mark different sections of text.  These changes could indicate all the
different attributes of WEB tokens.  Because emacs already contains a
powerful programming language (emacs LISP) built right in, it ought to
be straight-forward to write out the high-lighted file with the
equivalent WEB construct replacing all the colored highlights.  Now
just run weave and tangle on the output (for the "back end").  In
fact, in many windowing systems it ought to be possible to recognize
when a file is "WEB-able" and pop up a window showing the current page
as it would be output using an already existing previewer.
 
This seems to me both to be a much more feasible project that writing
a new WEB on top of either Framemaker or Microsoft WORD and, as Lucid
Emacs is under the GNU Public License, it seems more in keeping with
the noncommercial tradition of TeX.
 
Peter Olsen
 
   Peter Olsen, n2ell, pcolsen@super.super.org  ...!uunet!super!pcolsen
          P.O. Box 410, Simpsonville, MD 21150; 410-997-8584
     "Engineering is the art of applying a professional knowledge of
   mathematics and the physical sciences to improve the quality of life"
 
From Edward Sat Feb 27 09:02:48 EST 1993
Date: Sat, 27 Feb 1993 09:02:48 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate Programming without WEB & TeX
 
On Fri, 26 Feb 93 19:46:39 GMT, "Timothy Murphy" <tim@maths.tcd.IE> wrote:
> What I doubt if you will sell is that Word for Windows
> will do anything TeX will do.
> Especially printing mathematical formulae,
> which you explicitly cite.
> Do you claim that it does this as well as TeX?
> If so, could you point to some published mathematical work
> to support your claim?
 
I have never used TeX for mathematical formulae. I have used Word for
Windows. It is very easy, and I have never had asny complaints about
the results. However, I have never published anything.
 
A friend of mine used TeX for her thesis (very math intensive). She
now uses Word for Windows, and says she will never go back.
 
	-Ed K.
 
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From Edward Sat Feb 27 09:09:26 EST 1993
Date: Sat, 27 Feb 1993 09:09:26 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate Programming without WEB & TeX
 
On Fri, 26 Feb 93 16:45:54 GMT, S.C.Cross@bnr.co.UK wrote:
> Well all the followup posts have been very helpful and my current idea for a final year project is to:
>
> (1) Look at extending the method for object oriented literate programming
>
> (2) Look at how analysis and designs can be incorporated into a literate
>     document
>
> (3) Write Literate programs direct into a WYSIWYG word processor (ie write the
>     woven document, no need to weave it from a source file)
>
> (4) Look at how hypertext links could be used to improve the method
>
> (5) Write a tool to extract (Tangle) the code from the word processor.  This
>     could be done from within the word processor using macros, or a command
>     line tool which processes a document file.
>
> (6) The tool/method will support C++
>
>
> I have not decided what operating system or word processor to use yet but it is likely to be one of
>
> -  Unix/Framemaker
> -  Windows/Framemaker
> -  Windows/Word
> -  Windows/Wordperfect
> -  Windows/Amipro
>
> It all depends on what I can get access to.  Framemaker or Word seem the most likely.
>
> Your comments are welcome
 
Sounds like an excellent, and very useful project to me. Keep us
posted.
 
	-Ed K.
 
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sun Feb 28 01:29:42 +0100 1993
Date: Sun, 28 Feb 93 01:29:42 +0100
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
>From: S.C.Cross@bnr.co.uk
>
>In my previous post to this group I wrote:
>
>>
>> Do we realy need to use TeX and WEB?
>>
Some details about an aspired tool deleted.
>
>I have not decided what operating system or word processor to use yet but it is likely to be one of
>
>-  Unix/Framemaker
>-  Windows/Framemaker
>-  Windows/Word
>-  Windows/Wordperfect
>-  Windows/Amipro
>
>It all depends on what I can get access to.  Framemaker or Word seem the most likely.
That is one of the things going to make it very hard for you convincing
anyone here. As you said for yourself, you have to decide what commercial
OS you use, and what commercial Word Processor. So your tool would be
available for only a limited circle of users, and only on an architecture
probably seeming archane in a few years. I have developped serious
programs and libraries under CP/M once. Most in the bin by now.
 
The TeX/Weave/Tangle approach is VERY future-safe, because it works
on a vast variety of systems, and is freely available. It works, for
example, admiringly well on linux.
 
Second problem, most of these people on this list already have worked
with TeX. Although starters are difficult at first, the result achievable
are remarkable, and once you have invested the initial learning time,
you can produce amazing results in amazing time.
 
And when you can use TeX, the rest of the Weave/Tangle/Web design
is a breeze to master.
 
Honestly, I would rather not want to invest any time needed in
WYSIAYG systems to do the markup of typeset texts myself. I am
glad having TeX to do that for me.
 
 David Kastrup        dak@messua.informatik.rwth-aachen.de
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, W-5100 Aachen, Germany
 
From adb-b@minster.york.ac.uk Sun Feb 28 10:48:24  1993
Date: Sun, 28 Feb 93 10:48:24
From: adb-b@minster.york.ac.uk
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Pascal file handling
 
Thanks to all who answered my last question. Alas, I have
another:
 
I am interested in the reaction of the Pascal run-time
system to running tangle or weave with no change files.
>From my basic understanding of Pascal, and trials on our
local compiler, it appears that tangle and weave should
halt with an I/O message: file not found.
 
Is this the case? I appreciate that most Pascal compilers are
different [ :) ]; our local compiler claims compatability
with the BSI 6192:1982 definition of the language. Of all
the features most likely to change, in my experience, I/O
is the most likely.
 
My question: how does the run-time system treat the absence
of a change file? (A supplementary question: how does it treat
absence of a web file?!)
 
Thanks again.
 
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
| Andrew D. Brydon   |      Email:    adb-b@minster.york.ac.uk             |
| University of York |-----------------------------------------------------|
| York, ENGLAND.     |    Project:    Literate programming in Ada          |
| YO1 5DD            |     (email:    adb-b-web@minster.york.ac.uk)        |
|--------------------------------------------------------------------------|
|     "There are no bugs in my software - just undocumented features."     |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
From Timothy Sun Feb 28 19:21:07 GMT 1993
Date: Sun, 28 Feb 93 19:21:07 GMT
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Pascal file handling
 
> My question: how does the run-time system treat the absence
> of a change file? (A supplementary question: how does it treat
> absence of a web file?!)
 
I don't think this question has an answer,
as all the versions of tangle I have ever seen
have been compiled with tangle.ch's,
which generally start by dealing in their own special way
with exactly the question you raise.
For example, the standard UnixTeX tangle
takes the change file to be /dev/null if no change file is given.
(If you give no web file either,
it just advises you of the usage "tangle web-file [change-file]",
and exits.)
 
(I imitated this on the Mac with Think C
by inventing a file called "/dev/null",
which is a perfectly good file name on the Mac.
But this was universally regarded as Very Bad Taste.)
 
But if tangle.web were itself tangled without a tangle.ch,
and then compiled (in Pascal),
it would actually require a web-file and a change-file
to be provided, as the heading says
 
program TANGLE(web_file,change_file,Pascal_file,pool);
 
Timothy Murphy
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From leew@cs.utexas.edu Sun Feb 28 18:44:36 -0600 1993
Date: Sun, 28 Feb 1993 18:44:36 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: WEB for Scheme
 
 Anyone out there know of a WEB system for Scheme or LISP?  I've just
 started fooling around with Scheme, and naturally, prefer to work with a
 literate programming system.  If there already is a SchemeWEB, it will save
 me the trouble of hacking out a Spidery grammar.
 
 Thanks in advance.
 
 		-- Lee
 
From Eric Mon Mar 1 08:08:58 -0500 1993
Date: Mon, 1 Mar 93 08:08:58 -0500
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Looking for E-mail address of Kees van der Laan
 
Dear Kees van der Laan, chair NTG,
 
Please disclose your e-mail adress by writing me directly and not via
the LITPROG distribution system.
 
Eric W. van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From ae1181t@stnfor.ae.ge.com Mon Mar 1 08:08:58 -0500 1993
Date: Mon, 1 Mar 93 08:08:58 -0500
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  WEB for Scheme
 
There is a SchemeWEB, but has no macro expansion, just for pretty printing.
I think your best bet is to use funnelweb.
 
From Zdenek Mon Mar 01 13:43:25 MDT 1993
Date: Mon, 01 Mar 93 13:43:25 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: Literate Progaramming list <LitProg@SHSU.edu>
Subject: Re: Pascal file handling
 
I think that running tangle and weave without the change file is the question
of operating system. You have to specify a dummy file. For MS DOS its name is
"nul". On input it signals end of file, on output all bytes go somewhere.
 
Hope this helps
 
Regards
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `           ~~~  ~~/ '  '  ~~~
                              Zdenek Wagner______/
 
From coates@spectro.jussieu.fr Tue Mar 2 16:37:37 +0100 1993
Date: Tue, 2 Mar 93 16:37:37 +0100
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
In response to some of the suggestions that Word for Windows is a lesser medium
for doing literate programming than is a combination like Emacs/TeX, I have to
say that while I myself am an Emacs/LaTeX user, because of my need to typeset
a lot of mathematical expressions, and my preference for the formatting that
I get with LaTeX, I have many colleagues who far prefer Word for Windows
because they find it easier to use, and like to see how it looks at the moment
that it is written.
	The point is, if one compares the number of users of a program like
WordPerfect or Word for Windows to the number of users for (La)TeX, I suspect
that the former are firmly in the majority.  In the same way, if literate
programming is ever going to hit the *mainstream*, I suspect it will only be
on the back of a commercial package which has some sort of WYSIWYG/hypertext/
browser front-end (throw in whatever other buzz-words are necessary) which
combines the functions of current programming *environments* with the additions
necessary to actually create literate programs.
	Sure, I prefer myself not to use proprietary programs, and will
probably stay with the Emacs/(La)TeX brigade, but it's only one solution, and
I suspect not the one that will prove to be the most popular in the long run.
There has to be room for both approaches; if not, literate programming might
just fade away as yet good idea that never caught the imagination of the world
at large.  Anyway, another 2c worth.
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From leew@cs.utexas.edu Tue Mar 2 15:31:25 -0600 1993
Date: Tue, 2 Mar 1993 15:31:25 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming without WEB & TeX
 
For what it's worth, I agree with Tony Coates' observations that the
WinWord/WordPerfect/etc. crowd probably greatly outnumbers the La/TeX
crowd and that if LP is ever going to go ``mainstream'' it will need to
be available in a WYSIWYG form.  I'm also with Tony in that I'm not likely
to forsake my La/TeX tools for proprietary commercial ones.
 
My 2d worth as well (why is `d' the symbol for `pence'?).
 
		-- Lee
 
From dak@POOL.Informatik.RWTH-Aachen.DE Tue Mar 2 23:33:11 +0100 1993
Date: Tue, 2 Mar 93 23:33:11 +0100
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
>From: leew@cs.utexas.edu (Lee Wittenberg)
...
>
>My 2d worth as well (why is `d' the symbol for `pence'?).
>
Still stems from the time when there were 12 Shilling to a pound
and 20 pence to a shilling. Or was it 16/20 or 12/16 or what?
Anyhow, the currency made your stomach do somersaults, and that way it
could read the 'd' as a 'p'.
 
From Richard Wed Mar 3 11:46:31 +1100 1993
Date: Wed, 3 Mar 1993 11:46:31 +1100
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
> >From: leew@cs.utexas.edu (Lee Wittenberg)
> ...
> >
> >My 2d worth as well (why is `d' the symbol for `pence'?).
> >
> Still stems from the time when there were 12 Shilling to a pound
> and 20 pence to a shilling. Or was it 16/20 or 12/16 or what?
> Anyhow, the currency made your stomach do somersaults, and that way it
> could read the 'd' as a 'p'.
>
No way!
12 old pence to a shilling; 20 shillings to a pound.
 
Richard.
 
From Cameron Tue Mar 2 22:09:26 -0600 1993
Date: Tue, 2 Mar 1993 22:09:26 -0600
From: Cameron Smith <cameron@symcom.math.uiuc.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: d for pence (was Re: Literate Programming without WEB & TeX)
 
The "d" abbreviation for "pence" comes from the "denarius", which
my Webster's identifies as "a small silver coin of ancient Rome".
In fact, when I looked up the entry for "pence", one of the meanings
given was "denarius".  Similarly the symbol for the pound sterling is
a stylized L, derived from the Latin "libra", a unit of weight --
I assume that a monetary pound was supposed at one time to equal
this weight of gold or some other precious metal?  By the way, the
word "pound" itself is identified as "from Latin 'pondo'=pound,
akin to Latin 'pondus'=weight", so apparently that term was yet
another unit of measure.
 
All this of course has nothing to do with literate programming,
but after three posts on the subject I couldn't resist throwing
in my (ahem) 2d.
 
--Cameron Smith
  cameron@symcom.math.uiuc.edu
 
From Eric Tue Mar 2 22:09:26 -0600 1993
Date: Tue, 2 Mar 1993 22:09:26 -0600
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Literate Programming without WEB & Tex
 
Toney Coates writes:
 
>	The point is, if one compares the number of users of a program like
>WordPerfect or Word for Windows to the number of users for (La)TeX, I suspect
>that the former are firmly in the majority.  In the same way, if literate
>programming is ever going to hit the *mainstream*, I suspect it will only be
>on the back of a commercial package which has some sort of WYSIWYG/hypertext/
>browser front-end (throw in whatever other buzz-words are necessary) which
>combines the functions of current programming *environments* with the additions
>necessary to actually create literate programs.
 
I support Tony's vision. But it seems to me that it will be pretty laborious
to desing and build an LP tool for every combination of programming language
and text processing environment. Exactly for that reason I suggested
some time ago to that we should work towards an LP tool that is independent of
programming language and text processing environement...
 
Eric W. van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Edward Wed Mar 03 06:51:19 EST 1993
Date: Wed, 03 Mar 1993 06:51:19 EST
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: d for pence (was Re: Literate Programming without WEB & TeX)
 
On Tue, 2 Mar 1993 22:09:26 -0600, "Cameron Smith" <cameron@symcom.math.uiuc.EDU> wrote:
> The "d" abbreviation for "pence" comes from the "denarius", which
> my Webster's identifies as "a small silver coin of ancient Rome".
> In fact, when I looked up the entry for "pence", one of the meanings
> given was "denarius".  Similarly the symbol for the pound sterling is
> a stylized L, derived from the Latin "libra", a unit of weight --
> I assume that a monetary pound was supposed at one time to equal
> this weight of gold or some other precious metal?  By the way, the
> word "pound" itself is identified as "from Latin 'pondo'=pound,
> akin to Latin 'pondus'=weight", so apparently that term was yet
> another unit of measure.
 
Pounds and Ounces are still the primary units of weight in the U.S. I
believe the English Pound was once the value of a pound of sterling
silver. (I don't know why we use lbs. as the abbreviation for
pounds.)
 
Just my $0.02. (I've been told $ is a simplification of a
superimposed 'U' and 'S'.)
 
	-Ed K.
--
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From Paul Wed Mar 3 10:40:27 -0500 1993
Date: Wed, 3 Mar 1993 10:40:27 -0500
From: "Paul (X) Prescod" <papresco@undergrad.math.uwaterloo.ca>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Literate Programming without WEB & TeX
 
> 	The point is, if one compares the number of users of a program like
> WordPerfect or Word for Windows to the number of users for (La)TeX, I suspect
> that the former are firmly in the majority.  In the same way, if literate
> programming is ever going to hit the *mainstream*, I suspect it will only be
> on the back of a commercial package which has some sort of WYSIWYG/hypertext/
> browser front-end (throw in whatever other buzz-words are necessary) which
>combines the functions of current programming environments with the additions
> necessary to actually create literate programs.
> 	Sure, I prefer myself not to use proprietary programs, and will
> probably stay with the Emacs/(La)TeX brigade, but it's only one solution, and
> I suspect not the one that will prove to be the most popular in the long run.
> There has to be room for both approaches; if not, literate programming might
>just fade away as yet good idea that never caught the imagination of the world
> at large.  Anyway, another 2c worth.
 
Perhaps we should be encouraging someone to make a Word4Windows-type program
that produces TeX code.
 
Perhaps someone could even write a document filter for Word4Windows to do it.
The way document filters are implemented in W4Win is very extensible (they
are dynamically loaded).
 
From Paul Wed Mar 03 18:10:00 GMT 1993
Date: Wed, 03 Mar 93 18:10:00 GMT
From: "Paul L. Allen" <pla@sktb.demon.co.uk>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: d for pence (was Re: Literate Programming without WEB & TeX)
 
X-Mailer: ArcBM 1.11
 
In message <199303030409.AA13177@symcom.math.uiuc.edu> Cameron Smith
<cameron@symcom.math.uiuc.edu> writes:
 
> Similarly the symbol for the pound sterling is a stylized L, derived from
> the Latin "libra", a unit of weight -- I assume that a monetary pound was
> supposed at one time to equal this weight of gold or some other precious
> metal?  By the way, the word "pound" itself is identified as "from Latin
> 'pondo'=pound, akin to Latin 'pondus'=weight", so apparently that term was
> yet another unit of measure.
 
You've supplied enough information (pound sterling, weight, precious metal,
pondus = weight) that you should have been able to figure this one out for
yourself - a pound (monetary) sterling was originally worth one pound
(weight) of sterling (92.5% pure) silver.
 
Which just goes to show how badly inflation has devalued the pound over
the years - I remember when you could get a room for the night at an inn,
a good meal, your horse stabled, watered and fed, the landlord's daughter as
a bedmate, and still get change from a farthing. :-)
 
--Paul
 
From coates@spectro.jussieu.fr Wed Mar 3 19:35:37 +0100 1993
Date: Wed, 3 Mar 93 19:35:37 +0100
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Literate Programming without WEB & Tex
 
> From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@rcl.wau.nl>
> Toney Coates writes:
>
> >	The point is, if one compares the number of users of a program like
> >WordPerfect or Word for Windows to the number of users for (La)TeX, I suspect
> >that the former are firmly in the majority.  In the same way, if literate
> >programming is ever going to hit the *mainstream*, I suspect it will only be
> >on the back of a commercial package which has some sort of WYSIWYG/hypertext/
> >browser front-end (throw in whatever other buzz-words are necessary) which
> >combines the functions of current programming *environments* with the additions
> >necessary to actually create literate programs.
>
> I support Tony's vision. But it seems to me that it will be pretty laborious
> to desing and build an LP tool for every combination of programming language
> and text processing environment. Exactly for that reason I suggested
> some time ago to that we should work towards an LP tool that is independent of
> programming language and text processing environement...
 
Put it this way - I'm not suggesting that LP tools will be built for every
editor/programming language combination.  Quite the opposite, I'm suggesting
that only the most popular combinations will win.  I don't expect that most
users *care* whether an LP tool is general or not - how many users use more
that one word processor and one or maybe two languages?  Most users don't need
this, and so in my opinion the *winning* company in the future is unlikely to
provide such generality.  Oh, there will be some tools around that have this,
for the small group of users who need it, but I can't see this really being a
mainstream need.
	I won't start another currency argument this time :-) .
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From leew@cs.utexas.edu Wed Mar 3 13:45:42 -0600 1993
Date: Wed, 3 Mar 1993 13:45:42 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: d for pence (was Re: Literate Programming without WEB & TeX)
 
Cameron Smith asks (in the midst the a wonderful answer to my previous
question about "d == pence"):
 
  > I assume that a monetary pound was supposed at one time to equal
  > this weight of gold or some other precious metal?
 
This one I know.  The official name for the British Pound is ``pounds
sterling,'' implying that at one time it was equivalent to a pound of
sterling silver.
 
		-- Lee
 
From stevea@vast.unsw.edu.au Thu Mar 04 09:39:15 +1100 1993
Date: Thu, 04 Mar 93 09:39:15 +1100
From: stevea@vast.unsw.edu.au
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: $ symbols (absolutely nothing to do with literate programming)
 
> On Wed, 03 Mar 93 06:51:19 EST, "Edward F. Keith" <ed@efkport.kew.com> said:
 
  ed> Just my $0.02. (I've been told $ is a simplification of a
  ed> superimposed 'U' and 'S'.)
 
	This is correct, which is why the correct "$" symbol has two
bars for US currency, and only one bar for Australian currency.
 
	ObLitProg: ever noticed how much of a pain it is tracking down
that missing bracket somewhere in the middle of your WEB? The compiler
doesn't help much as I use a hierarchy in my WEBs, so the main module is
at the front, and the guts trailing behind, so I end up with a message
"insufficient } at line 105" when really I'm missing one at line 5000.
 
	cheers
	-steve
 
From Gary Thu Mar 4 22:16:48 -0800 1993
Date: Thu, 4 Mar 1993 22:16:48 -0800 (PST)
From: Gary Casterline <casterln@are.Berkeley.EDU>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu (Literate Programming List)
Subject: fweb's auto insert macro in ratfor
 
Hello
Am I doing something wrong here?  I'm trying to use fweb's
automatic insertion feature for ratfor described in
section 9.3.2 of the 1.30-beta (jan 1, 1993) manual.
 
This little web shows the problem.
-------
@r/
 
@ First Section.
This program simply prints {\tt Hello, world.} to standard output.
 
@ Try to define the automatic macro.
 
@m[pfs] AUTO implicit undefined(a-z)
 
@ The main program.
 
@a program hello
{
	@<print string@>;
	stop;
}
 
@ This is the little print section.
 
@<print string@>=
	print *, "Hello, world."
 
@ Index.
 
-------
Apparently fweave doesn't grok the '['.
-------
This is FWEAVE [SunOS/UNIX version 1.30--beta (February 3, 1993)].
Reading fweb.sty...
Reading autobug.web... *1 *5
Writing autobug.tex... *1
! (WEAVE):  Improper macro definition: expected identifier. (l. 8)
@m[
   pfs] AUTO implicit undefined(a-z)
*5
Writing autobug.idx...autobug.scn...
Done.
CPU = 0.1 sec.; REAL = 0.3 sec.  CPU/REAL = 45.9%.
[FWEAVE:  Pardon me, but I think I spotted something wrong.]
------
Can anyone see the error here?  Or, should I send this on to John Krommes?
BTW, ftangle does the right thing.
 
Thanks.
 
Gary Casterline                        Agricultural & Resource Economics
casterln@are.Berkeley.EDU              207 Giannini Hall
(510) 642-5583                         UC Berkeley, CA 94720
 
From leew@cs.utexas.edu Fri Mar 5 09:40:38 -0600 1993
Date: Fri, 5 Mar 1993 09:40:38 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: $ symbols (absolutely nothing to do with literate programming)
 
Steve Avery writes:
 
  > 	ObLitProg: ever noticed how much of a pain it is tracking down
  > that missing bracket somewhere in the middle of your WEB? The compiler
  > doesn't help much as I use a hierarchy in my WEBs, so the main module is
  > at the front, and the guts trailing behind, so I end up with a message
  > "insufficient } at line 105" when really I'm missing one at line 5000.
 
I always try to make sure that the brackets (or braces or parens or
whatever) match up within each section as I write it.  Although I will admit
that the #line directive can cause some problems with error messages in
this regard.
 
		-- Lee
 
From Trevor Sat Mar 06 12:18:32 GMT 1993
Date: Sat, 06 Mar 93 12:18:32 GMT
From: Trevor Jenkins <tfj@apusapus.demon.co.uk>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Errors in Knuth's "Literate Programming" compendium
 
I'm very surprised that I've not seen anyone comment upon the "errors" in
DEK's "Literate Programming" book.
 
Okay that are not big errors but still they're there; two in the chapter
"The Errors of TeX". :-) The most serious of these errors occurs on page
258 where text is missing.
 
The second error in that chapter (page 271) is the reference to Frank
Liang's thesis. The indicated reference [11] is not a citation of Liang's
work. In fact there isn't a citation for it at all in the reference list to
this chapter. (There is one in the "Further Reading" section at the end of
the book.
 
The other error I spotted is on page 48 where a reference number is wrong.
The text says [94]; I think it should say [95]. (A example of an off-by-1
error to which we are so prevalent. :-))
 
However, this is all just nit-picking.
 
What depressed me about the book that very little of outcome of Kunth's
early research has been taken up in industry tools. :-(
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From marcus@x4u.desy.de Mon Mar 8 15:01:29 +0100 1993
Date: Mon, 8 Mar 93 15:01:29 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: Literate Programmers Mailing List <litprog@shsu.edu>
Subject: Literate Programming entry to World Wide Web
 
[This is CC'd to www-bug@info.cern.ch, GDG, JAK, Levy for information]
 
Since a few days, the DESY lab experiences a World Wide Web
[aka WWW, W3, the Web] renaissance. Among the available
HyperText documents, there is an entry for "Literate
Programming".
 
  You can use one of the available browsers (xmosaic, viola,
  midas [xterm], or www [line mode]) to access the Web. All
  the necessary information is there.
 
  The Info Page for Literate Programming can be accessed directly:
 
  file://ftp.desy.de/pub/www/projects/LitProg.html
 
  Appended below is a formatted copy of the Info page. With WWW,
  you will be able in the future to access all the LitProg FAQs,
  sample files and information for beginners from _one_ panel.
     The WWW Overview Page [from CERN] contains a pointer sequence
  Computing -> Languages -> TeX -> GDG's archives at Niord, as I
  discovered recently.
     You can also access it from the DESY Home Page:
 
  file://ftp.desy.de/pub/www/default.html
 
  [going to the "LitProg" entry point from there].
     Since this service is experimental, I would very much appreciate
  some feedback from Literate Programmers, as well as suggestions and
  contributions. There is no restriction as to what format the
  document can have. The link may even simply be a pointer to an
  FTP archive [such as for Nelson Beebe's bibliography, or a couple
  of C++ files I wrote].
     Write to me if you have problems of any kind with this
  information service. WWW is compatible with the gopher and WAIS
  protocols as well. Thanks to Tim Berners-Lee (CERN-CN/WWW) for
  putting the pointers and giving lots of useful advice!
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
  [WWW] file://ftp.desy.de/pub/www/people/marcus.html
 
[PS: the IMO nicest XTerm browser for the WWW
 is "xmosaic". To avoid work, binaries for version 0.9
 for SGI, HP, Sun, ibm, dec, are available via anon FTP from
 /anonymous@ftp.ncsa.uiuc.edu:/Web/xmosaic]
 
The following is copied from the LitProg info page in the Desy Web.
The important informatin is hidden in so-called links (->), and does
not appear if you dont use a WWW browser; e.g. clicking with your
mouse on the marked word "->freeHEP" brings you straight to
ftp.freehep.scri.fsu.edu's Info page on the freeHEP project,
clicking on "->CWEB" gives you a database quick info on CWEB etc.
 Thus, the document below in fact branches to several [remote]
documents. No delay, no using zillions of different tools anymore.
-----------------------------------------------------------------
Literate Programming
********************
 
At ->DESY, some tools for so-called "Literate Programming" in a "WEB-like"
environment are installed for the public. These tools are ->CWEB for Literate
Programming in C or C++, and ->FWEB for Literate Programming in Fortran-77,
Fortran-90, Ratfor, C, C++ or ->TeX.
 
A couple of sample files for CWEB can be retrieved from the -> freeHEP server
(in directory -> pub/freehep/languages/cweb) as well.
 
->Why I must write readable programs.
   A philosophical warm-up for non-believers.
->What the heck is this "WEB" thing?
   A tidbit of technical information on the WEB environment.
->Further Reading.
   Access to Nelson H. Beebe's LitProg bibliography.
->LITPROG Mailing List.
   Information on the Literate Programming Mailing List.
->FWEB FAQ.
   A list of Frequently Asked Questions (FAQs) on the LitProg mailing list
   for the FWEB system of Literate Programming.
 
Last updated: March 8, 1993, by ->marcus
 
->Go back to DESY Home Page.
---------------------------------------------------------------
 
From Eric Mon Mar 8 15:01:29 +0100 1993
Date: Mon, 8 Mar 93 15:01:29 +0100
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: CLiP for MS_DOS is available
 
The CLiP system for literate programming has been briefly described in a
previous posting (24-feb-1993). CLiP for MS_DOS platforms is now anonymously
FTP-able from the directory
 
	clip\ms_dos
on
	sun01.info.wau.nl.
 
Note that a manual does not yet exist. This is partly compensated by the
information in the file READ_ME.TXT (or its postscript version READ_ME.PS)
together with the description of the CLiP system by the paper "The CLiP Style
of Literate Programming" (available as the files CLIP_STYLE.PS,
CLIP_STYLE_A.PS and CLIP_STYLE_B.PS from the directory CLIP).
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From leew@cs.utexas.edu Wed Mar 17 10:32:49 -0600 1993
Date: Wed, 17 Mar 1993 10:32:49 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Typesetting C assertions
 
I'm trying to build a web in which assertions don't look like just
another procedure call.  In particular, I'd like them to look something like
this:
 
        * Assertion:  <the actual assertion>
 
where the * represents a bullet.  In CWEB I'd like to be able to
"@f assert TeX" and "\def\assert(#1){\bullet\ {\rm Assertion:}\quad #1}".
Unfortunately, this doesn't work since the assertion may have parentheses
in it, and TeX doesn't nest parentheses in macro args (so the first right
paren will end the argument).  I _could_ use ");" as the argument-end
delimeter, but I'd also like to be able to generalize the technique so
that I can weave "sqrt(x)" into "\sqrt{x}", and the ); technique won't work
there.
 
Anyone out there got the TeXpertise to figure this one out?  Thanks in
advance.
 
		-- Lee
 
From George Wed Mar 17 14:00:21 CST 1993
Date: Wed, 17 Mar 1993 14:00:21 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: RE: CLiP for MS_DOS is available
 
On 17 Mar 1993 17:18 +0000 (GMT), "Eric W. van Ammers" <AMMERS@RCL.WAU.NL>
posted:
> The CLiP system for literate programming has been briefly described in a
> previous posting (24-feb-1993). CLiP for MS_DOS platforms is now
> anonymously FTP-able from the directory
>
>         clip\ms_dos
> on
>         sun01.info.wau.nl.
>
> Note that a manual does not yet exist. This is partly compensated by the
> information in the file READ_ME.TXT (or its postscript version READ_ME.PS)
> together with the description of the CLiP system by the paper "The CLiP
> Style of Literate Programming" (available as the files CLIP_STYLE.PS,
> CLIP_STYLE_A.PS and CLIP_STYLE_B.PS from the directory CLIP).
 
I have also copied the files to Niord.SHSU.edu (192.92.115.8) and placed
them in [FILESERV.CLIP] for access.  The files are available individually,
as on Eric's machine, or as a ZIP file (CLIP-1_0.ZIP) of the entire
distribution.  You can also retrieve the distribution by including:
 SENDME CLIP
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu)
and you will retrieve a 7-part UUENCODEd copy of the ZIP archive.
 
The files should also propagate to the web directory of the TeX archive
area on both ftp.tex.ac.uk and ftp.uni-stuttgart.de once they poll my Unix
host.  I am attempting to get the other literate programming tools in this
directory of the Comprehensive TeX Archive Network (CTAN) on a mirrored
basis.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From dentato@minerva.ing.uniroma1.it Thu Mar 18 17:00:41 +0100 1993
Date: Thu, 18 Mar 1993 17:00:41 +0100 (NFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: CLiP for MS_DOS is available
 
According to Eric W. van Ammers, LUW, tel::
 
 >> CLiP for MS_DOS platforms is now anonymously FTP-able from the directory
 
 What's the problem of having a Unix-CLiP? I read the first post on CLiP and
it looks intresting. May we unix-people hope?
 
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        ___ __
       //_/// \    e-mail: mc9275@mclink.it
      // \//__/    dentato@cadgroup.ing.uniroma1.it
     Remo Dentato
 
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
From norman@bellcore.com Thu Mar 18 19:33:44 -0500 1993
Date: Thu, 18 Mar 93 19:33:44 -0500
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LITPROG@SHSU.edu
Subject: ``Official'' noweb announcement
 
Although noweb has been available outside Princeton for more than two years,
I am now officially announcing its release.  What's ``official'' about this
release is that I now have time to support noweb and I promise to fix bugs.
noweb is available via anonymous ftp from bellcore.com in file
~ftp/pub/norman/noweb.shar.Z or from csservices.princeton.edu in file
~ftp/pub/noweb.shar.Z.  DOS code with binaries is available in the
same locations as dosnoweb.zip.  I do NOT support the DOS code and it
may or may not be the same as the supported source code.
 
The rest of this announcement repeats information in the noweb README
file; it contains a short sales pitch and a description of what you
get and on what terms.  I'm posting a longer article that contains a
more in-depth description and sales pitch.
 
Norman Ramsey
 
INTRODUCTION -- WHAT IS NOWEB?
 
noweb is designed to meet the needs of literate programmers while
remaining as simple as possible.  Its primary advantages are
simplicity, extensibility, and language-independence.  noweb uses 4
control sequences to WEB's 27, and its manual is only two pages.
noweb works ``out of the box'' with any programming language, and its
formatter-dependent part is under 50 lines.  The primary sacrifice
relative to WEB is the loss of the language-dependent features:
prettyprinting and an index of identifiers.
 
noweb provides extensibility by using the Unix toolkit philosophy.
The ``notangle'' and ``noweave'' commands are built from pieces, which
are then assembled in pipelines using shell scripts.  The pieces are:
 
  markup	convert noweb file from human syntax to tool syntax
  unmarkup	inverse of markup
  nt		`tangle' the tool form of the noweb file
  noxref	insert cross-reference information for latex
 
These pieces are combined by the scripts in the shell directory to
provide more than just weaving and tangling:
 
  notangle	analog of TANGLE
  noweave	analog of WEAVE
  nountangle	tangle, but keep interleaved documentation in comments
  noroots	print names of all root chunks in a noweb file
  nocount	count number of lines of code and documentation.
 
noweb has been used for three years both at Princeton and elsewhere.
It has been used for tens of thousands of lines of code in such
languages as awk, C, C++, Icon, Modula-3, Promela, and Standard ML.
 
If you already know you want to use noweb, you need only install it
and read the manual page.  If you're just curious about noweb, a sales
pitch appears in the technical report in doc/ieee.tex.
 
WHAT YOU GET IN THIS DISTRIBUTION
 
This distribution contains the following directories:
  contrib	software contributed by noweb users
  doc		man pages and a technical report
  examples	parts of noweb programs in different languages
  icon		Icon code for nonstandard weave and cross-referencer
  lib		noweave's cross-referencer
  shell		all the shell scripts that make up the actual commands
  src		source code for nt and markup
  tex		supporting tex code for /usr/local/lib/tex/macros
where appropriate, these directories have README files of their own.
 
WEAVING
 
The worst aspect of literate programming is the enormous amount of
time wasted wrangling over what prettyprinted output should look like.
Although noweb does no prettyprinting, it is not entirely immune---
several people have complained about noweave's output or have sent me
changes that add more options to noweave.  Having been down that road
with Spider, I won't be fooled again.  noweb doesn't try to be all
things to all programmers, but it is very easy to change.
 
If you don't like noweave's formatting, you can easily throw away
noweave and make your own.  To help you get started, the shell directory
in the distribution contains three versions of noweave:
  noweave		the standard (supposed to be latex-proof)
  noweave.nr		what I use (handles 90 columns of code)
  noweave.simple	simple, uses no special TeX hacking
The simple version can't handle code with @ signs.  The article in
doc/ieee.tex explains the intermediate language that noweb uses to
represent literate programs.
 
noweb comes with two cross-referencers for use with noweave.  The
standard one is written in awk, because that's what everybody has.
There is also a somewhat better cross-referencer written in Icon.
Neither cross-referencer has been thoroughly exercised.  See the
INSTALL file for more details.
 
noweb is designed to be extended with a language-dependent
prettyprinter and indexer.  I haven't written one because my
experience with Spider taught me that prettyprinting is far more
trouble than it's worth.  If someone else wants to write one, I will
be happy to help and advise.
 
NOTES
  doc/ieee.* contains a paper that has been submitted to IEEE Software.
  You must `make install' before attempting to format the paper, since
  it uses the noweb document style option.
 
  The paper documents the representation of noweb files that is used
  by the noweb tools, in case you want to write any tools of your own.
  Simple tools (e.g. count the number of lines of interleaved
  documentation) are trivial.  If you write any tools, or you want
  tools written (e.g. prettyprinters, index generators), let me know.
 
  The icon directory contains Icon programs that do most of the job
  of noweave.sh and noxref.  If you want to adapt noweb to work with a
  text processor other than TeX or latex, they might provide a better
  starting point.  I confess that the whole system should have been
  written in Icon from the beginning, but I'm not going to do it over.
  Icon is available by anonymous ftp from cs.arizona.edu.
 
  Thanks to Dave Hanson for cpif.
  Thanks to Joseph Reynolds for prodding me to fix [[...]].
  Thanks to Lee Wittenberg for the DOS binaries.
 
  Thanks to Gary Leavens and Lee Wittenberg for testing this version,
  especially the installation process.  I am, as always, responsible
  for errors and awkwardness that remain.
 
Send comments or questions to norman@bellcore.com.
 
I enjoy hearing from noweb users; if you have enjoyed noweb, why not
send me a local postcard for my collection?  My address is:
 
  Norman Ramsey
  Bellcore
  445 South Street
  Morristown, New Jersey 07960
               USA
 
COPYRIGHT
 
Noweb is copyright 1989-1993 by Norman Ramsey.  All rights reserved.
 
You may use and distribute noweb for any purpose, for free.  You may
modify noweb and create derived works, provided you retain the
copyright notice, but the result may not be called noweb without my
written consent.  You may not sell noweb itself, but you may do
anything you like with programs created with noweb.
 
From norman@bellcore.com Thu Mar 18 19:37:56 -0500 1993
Date: Thu, 18 Mar 93 19:37:56 -0500
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LITPROG@SHSU.edu
Subject: noweb in-depth article or sales pitch
 
This message contains an ASCII version of the technical report that
describes noweb and why you might care to use it.  The article may one
day be published in IEEE Software (it's been under review for more
than a year), but don't hold your breath.  If you get noweb from
csservices.princeton.edu, you get the TeX source for this article, and
you can make a version you might actually be able to read.
 
Norman Ramsey
 
   Literate-Programming Tools Need Not Be Complex
 
                  Norman Ramsey
 
     Department of Computer Science, Princeton University
 
        35 Olden Street, Princeton, New Jersey 08544
 
                    August 1992
 
                     Abstract
     When it was introduced, literate programming meant WEB. Desire
   to use WEB with languages other than Pascal led to the implementation
   of many versions. WEB is complex, and the difficulty of using WEB cre-
   ates an artificial barrier to experimentation with literate programming.
   noweb provides much of the functionality of WEB, with a fraction of the
   complexity. noweb is independent of the target programming language,
   and its formatter-dependent part is less than 40 lines. noweb is extensi-
   ble, because it uses two representations of programs: one easily edited
   by authors and one easily manipulated by tools.
     This paper explains how to use the noweb tools and gives examples
   of their use. It sketches the implementation of the tools and describes
   how new tools are added to the set. Because WEB and noweb overlap,
   but each does some things that the other cannot, this paper enumerates
   the differences.
 
  Key words: literate programming, readability, programming environments
 
Introduction
 
When literate programming was introduced, it was synonymous with WEB, a
tool for writing literate Pascal programs [6, Chapter 4]. The idea attracted
attention; several examples of literate programs were published, and a spe-
cial forum was created to discuss literate programming [1, 2, 6, 13]. WEB
was adapted to programming languages other than Pascal [3, 7, 8, 10, 12].
With experience, many WEB users became dissatisfied [9]. Some found WEB
not worth the trouble, as did one author of the program appearing in Ap-
pendix C of Reference 11. Others built their own systems for literate pro-
gramming. The literate-programming forum was dropped, on the grounds
 
                        1

 
that literate programming had become the province of those who could build
their own tools [14].
  WEB programmers interleave source code and descriptive text in a sin-
gle document. When using WEB, a programmer divides the source code into
modules. Each module has a documentation part and a code part, and mod-
ules may be written in any order. The programmer is encouraged to choose
an order that helps explain the program. The code parts are like macro
definitions; they have names, and they contain both code and references to
other modules. A WEB file represents a single program; TANGLE extracts that
program from the WEB source. One special module has a code part with
no name, and TANGLE expands the code part of that module to extract the
program. WEAVE converts WEB source to TEX input, from which TEX can
produce high-quality typeset documentation of the program.
  WEB is a complex tool. In addition to enabling programmers to present
pieces of a program in any order, it expands three kinds of macros, pret-
typrints code, evaluates some constant expressions, provides an integer rep-
resentation for string literals, and implements a simple form of version
control.  The manual for the original version documents 27 "control se-
quences" [5]. The versions for languages other than Pascal offer slightly
different functions and different sets of control sequences. Significant effort
is required to make WEB usable with a new programming language, even
when using a tool designed for that purpose [8].
  WEB's shortcomings make it difficult to explore the idea of literate pro-
gramming; too much effort is required to master the tool.  I designed a
new tool that is both simple and independent of the target programming
language.  noweb is designed around one idea: writing named chunks of
code in any order, with interleaved documentation. Like WEB, and like all
literate-programming tools, it can be used to write a program in pieces and
to present those pieces in an order that helps explain the program. noweb's
value lies in its simplicity, which shows that the idea of literate programming
does not require the complexity of WEB.
 
noweb
 
A noweb file contains program source code interleaved with documentation.
When notangle is given a noweb file, it writes the program on standard
output.  When noweave is given a noweb file, it reads the noweb source
and produces, on standard output, TEX source for typeset documentation.
 
                        2

 
  _________         _________
  |   foo.c|_________-cc|-cffoo.coo.o|_-ldEfoo.ox:::ecutable a.out
  |________|        |________|
 
      notangle foo.nw > foo.c
_________
|  foo.nw|
|________|
    A
    A noweave foo.nw > foo.tex
  ___AU____         _________
  |  foo.tex|________-tex|foofoo.dvi|_-dviTfooypeset documentation for foo
  |________|        |________|
 
      Figure 1: Using noweb to build code and documentation
 
Figure 1 shows how to use notangle and noweave to produce code and
documentation for a C program contained in the noweb file foo.nw.
  A noweb file is a sequence of chunks, which may appear in any order. A
chunk may contain code or documentation. Documentation chunks begin
with a line that starts with an at sign (@) followed by a space or newline.
They have no names. Code chunks begin with
 
   <<chunk name>>=
 
on a line by itself. The double left angle bracket (<<) must be in the first
column. Chunks are terminated by the beginning of another chunk, or by
end of file. If the first line in the file does not mark the beginning of a chu*
 *nk,
it is assumed to be the first line of a documentation chunk.
  Documentation chunks contain text that is ignored by notangle and
copied verbatim to standard output by noweave (except for quoted code).
noweave can work with LaTEX, or it can use a TEX macro package, supplied
with noweb, that defines commands like "chapter and "section.
  Code chunks contain program source code and references to other code
chunks. Several code chunks may have the same name; notangle concate-
nates their definitions to produce a single chunk, just as TANGLE does. Code
chunk definitions are like macro definitions; notangle extracts a program
by expanding one chunk (by default the chunk named <<*>>). The defini-
tion of that chunk contains references to other chunks, which are themselves
expanded, and so on. notangle's output is readable; it preserves the inden-
tation of expanded chunks with respect to the chunks in which they appear.
 
                        3

 
@ This program has no input, because we want to keep it
simple.  The result of the program will be to produce a
list of the first thousand prime numbers, and this list
will appear on the [[output]] file.
 
Since there is no input, we declare the value [[m = 1000]]
as a compile-time constant.  The program itself is capable
of generating the first [[m]] prime numbers for any
positive [[m]], as long as the computer's finite
limitations are not exceeded.
<<program to print the first thousand prime numbers>>=
program print_primes(output);
 const m = 1000;
      <<other constants of the program>>
 var <<variables of the program>>
   begin <<print the first [[m]] prime numbers>>
   end.
 
     Figure 2: Sample noweb input, from prime number program
 
  Code may be quoted within documentation chunks by placing double
square brackets around it ([[...]]).  These double square brackets are
ignored by notangle, but they are used by noweave to give code special
typographic treatment.
  If double left and right angle brackets are not paired, they are treated
as literal "<<" and ">>". Users can force any such brackets, even paired
brackets, to be treated as literal by preceding the brackets by an at sign
(e.g. "@<<").
  Figure 2 shows a fragment of a noweb program that computes prime
numbers. The program is derived from the example used in Reference 6,
Chapter 4, and Figure 2 should be compared with Figure 2b of that paper.
Figure 3 shows the program after processing by noweave and LaTEX. Figure 4
shows the beginning of the program as extracted by notangle. A complete
example program accompanies this paper.
 
                        4

 
This program has no input, because we want to keep it simple.
The result of the program will be to produce a list of the first
thousand prime numbers, and this list will appear on the output
file.
 
Since there is no input, we declare the value m = 1000 as a
compile-time constant.  The program itself is capable of gen-
erating the first m prime numbers for any positive m, as long as
the computer's finite limitations are not exceeded.
 
<program to print the first thousand prime numbers>
  program print_primes(output);
   const m = 1000;
        <other constants of the program>
   var <variables of the program>
     begin <print the first m prime numbers>
     end.
 
Figure 3: Output produced by noweave and LaTEX from Figure 2
 
                     5

 
program print_primes(output);
 const m = 1000;
      rr = 50;
      cc = 4;
      ww = 10;
      ord_max = 30;  - p_ord_max squared must exceed p_m "
 var p: array [1..m] of integer;
         - the first m prime numbers, in increasing order "
    page_number: integer;
   ..
   .
 
     Figure 4: Part of primes program as written by notangle
 
Using noweb
 
Experimenting with noweb is easy. noweb has little syntax: definition and
use of code chunks, marking of documentation chunks, quoting of code, and
quoting of brackets. noweb can be used with any programming language,
and its manual fits on two pages.
  On a large project, it is essential that compilers and other tools be
able to refer to locations in the noweb source, even though they work with
notangle's output [9]. Giving notangle the -L option makes it emit prag-
mas that inform compilers of the placement of lines in the noweb source. It
also preserves the columns in which tokens appear. If notangle is not given
the -L option, it respects the indentation of its input, making its output
easy to read. Large programs may also benefit from cross-reference infor-
mation. If given the -x option, noweave uses LaTEX to show on what pages
each chunk is defined and used.
  WEB files map one to one with to both programs and documents. The
mapping of noweb files to programs is many to many; the mapping of files
to documents is many to one. Source files are combined by listing their
names on notangle's or noweave's command line. Many programs may be
extracted from one source by specifying the names of different root chunks,
using notangle's -R command-line option.
  The simplest example of a one-to-many mapping of programs is that of
putting C header and program in a single noweb file. The header comes from
 
                        6

 
the root chunk <header>, and the program from the default root chunk, <*>.
The following rules for make automate the process:1
 
foo.c: foo.nw
      notangle -L foo.nw > foo.c
foo.h: foo.nw
      notangle -Rheader foo.nw > xfoo.h
      -cmp -s xfoo.h foo.h __ cp xfoo.h foo.h
 
A more interesting example is using noweb to interleave different languages
in one source file. I wrote an awk script that read a machine description and
emitted a disassembler for that machine, and I used noweb to combine the
script and description in a single file, so I could place each part of the input
next to the code that processed that input. The machine description was in
the root chunk <opcodes table>, and the awk script in the default root chunk.
The processing steps were:
 
notangle opcodes.nw > opcodes.awk
notangle -R'opcode table' opcodes.nw _
awk -f opcodes.awk > disassem.sml
 
  Many-to-one mapping of source to program can be used to obtain effects
similar to those of Ada or Modula-3 generics. Figure 5 shows generic C
code that supports lists. The code can be "instantiated" by combining it
with another noweb file. pair_list.nw, shown in Figure 6, specifies lists of
integer pairs. The two are combined by applying notangle to them both:
 
notangle pair_list.nw generic_list.nw > pair_list.c
 
noweb has no parameter mechanism, so the "generic" code must refer to a
fixed set of symbols, and it cannot be checked for errors except by compiling
pair_list.c. These restrictions make noweb a poor approximation to real
generics, but useful nevertheless.
  I have used noweb for small programs written in various languages, in-
cluding C, Icon, awk, and Modula-3. Larger projects have included a code
generator for Standard ML of New Jersey (written in Standard ML) and
a multi-architecture debugger, written in Modula-3, C, and assembly lan-
guage. A colleague used noweb to write an experimental file system in C++.
____________________1
   Using cmp avoids touching the header file when its contents haven't changed.*
 * This
trick is explained on pages 265-266 of Reference 4.
 
                        7

 
This list code supports circularly-linked lists represented by a pointer to
the last element. It is intended to be combined with other noweb code that
defines <fields of a list element> (the fields found in an element of a list) a*
 *nd
that uses <list declarations> and <list definitions>.
 
<list declarations>
 typedef struct list -
   <fields of a list element>
   struct list *_link;
 " *List;
 
 extern List singleton(void);   /* singleton list, uninitialized fields */
 extern List append(List, List); /* destructively append two lists */
 #define last(l)   (l)
 #define head(l)   ((l) ? (l)->next : 0)
 #define forlist(p,l) for (p=head(l); p; p=(p==last(l) ? 0 : p->next))
 
<list definitions>
 List append (List left, List right) -
    List temp;
    if (left == 0)  return right;
    if (right == 0) return left;
    temp = left->_link; left->_link = right->_link; right->_link = temp;
    return right;
 "
   ..
   .
 
        Figure 5: Generic code for implementing lists in C
 
<*>
 <list declarations>
 <list definitions>
 
<fields of a list element>
 int x;
 int y;
 
       Figure 6: Program to instantiate lists of integer pairs
 
                        8

 
The sizes of these programs are
 
    Program       Documentation linesTotal lines
 
    markup and nt       400        1,200
    ML code generator   900        2,600
    Debugger           1,400       11,000
    File system        4,400       27,000
 
Representation of noweb files
 
The noweb syntax is easy to read, write, and edit, but it is not easily manipu-
lated by programs. To make it easy to extend noweb, I have written markup,
which converts noweb source to a representation that is easily manipulated
by commonly used Unix tools like sed and awk. In this representation, every
line begins with @ and a key word. The possibilities are:
 
    @begin kind nStart a chunk
    @end kind n End a chunk
    @text stringstring appeared in a chunk
    @nl         A newline
    @defn name  The code chunk named name is being defined
    @use name   A reference to code chunk named name
    @quote      Start of quoted code in a documentation chunk
    @endquote   End of quoted code in a documentation chunk
    @file filenameName of the file from which the chunks came
    @literal textnoweave copies text to output
 
markup numbers each chunk, starting at 0. It also recognizes and undoes
the escape sequence for double brackets, e.g. converting "@<<" to "<<".
markup's output represents a sequence of files. Each file is represented by a
"@file filename" line, followed by a sequence of chunks.
  The representation of a documentation chunk is
 
    @begin docs nwhere n is the chunk number.
    docline     repeated an arbitrary number of times.
    @end docs n
 
where docline may be @text, @nl, @quote, or @endquote. Every @nl corre-
sponds to a newline in the original file. markup guarantees that quotes are
balanced and not nested.
 
                        9

 
  The representation of a code chunk is
 
    @begin code nwhere n is the chunk number.
    @defn name  name of this chunk.
    @nl         The newline following <<name>>= in the original file
    codeline    repeated an arbitrary number of times.
    @end code n
 
where codeline may be @text, @nl, or @use.
  The noweb tools are implemented by piping the output of markup to
other programs. notangle is a Unix shell script that builds a pipeline be-
tween markup and nt, which reads and expands definitions of code chunks.
noweave pipes the output of markup to a 24-line awk script that inserts
appropriate TEX or LaTEX formatting commands.
  Having a format easily read by programs makes noweb extensible; one
can manipulate literate programs using Unix shell scripts and filters. To be
able to share programs with colleagues who don't enjoy literate program-
ming, I modified notangle by adding to its pipeline a stage that places
each line of documentation in a comment and moves it to the succeeding
code chunk. The resulting script, nountangle, transforms a literate pro-
gram into a traditional commented program, without loss of information
and with only a modest penalty in readability. Figure 7 shows the results
of applying nountangle to the prime-number program shown in Figure 2.
noweave's cross-reference generation is also implemented as an extension;
the output of markup is piped through an awk script that uses @literal to
insert LaTEX cross-reference commands. Another simple tool finds all the
roots in a noweb file, making it easy to find definitions where chunk names
have been misspelled.
 
Comparing WEB and noweb
 
Unlike WEB, noweb is independent of the target programming language. WEB
tools can be generated for many programming languages, but those lan-
guages must be lexically similar to C. For example, WEB can't handle the
awk regular-expression notation "/:::/"; every such expression must quoted
using WEB's "verbatim" control sequence. The effort required to generate
WEB tools is significant; the prospective user must write a specification of
several hundred lines.
  Being independent of the target programming language makes noweb
simpler, but it also means that noweb can do less. Most of the differences
 
                       10

 
- This program has no input, because we want to keep it   "
- simple.  The result of the program will be to produce a  "
- list of the first thousand prime numbers, and this list  "
- will appear on the [[output]] file.                 "
  ..
  .
 
- <program to print the first thousand prime numbers>=    "
program print_primes(output);
  const m = 1000;
      - "section-The output phase-                         "
      -                                              "
      - <other constants of the program>=                   "
      rr = 50;
      cc = 4;
      ww = 10;
      - <other constants of the program>=                   "
      ord_max = 30;  - p_ord_max squared must exceed p_m "
  var - How should table [[p]] be represented? Two possibilities "
     - suggest themselves: We could construct a sufficiently   "
  ..
  .
 
    Figure 7: Output produced by nountangle from Figure 2
 
                      11

 
between WEB and noweb arise because WEB has language-dependent features
that are not present in noweb. These features include prettyprinting, type-
setting comments using TEX, generating an index of identifiers, expanding
macros, evaluating constant expressions, and converting string literals to
indices into a "string pool." Among these features, noweb users are most
likely to miss prettyprinting and the index of identifiers.
  Some differences arise because WEB and noweb implement similar features
differently. WEB's original TANGLE removed white space and folded lines to fill
each line with tokens, making its output unreadable [6, Chapter 4, Figure 3].
Later adaptations preserved line breaks but removed other white space.
By default, notangle preserves whitespace and maintains indentation when
expanding chunks. It can therefore be used with languages like Miranda and
Haskell, in which indentation is significant. TANGLE cannot.
  WEB's WEAVE assigns a number to each chunk, and its cross-reference
information refers to chunk numbers, not page numbers. noweb uses LaTEX
to emit cross-reference information that refers to page numbers. Anyone
who has read a large literate program will appreciate the difference.
  WEB works poorly with LaTEX; LaTEX constructs cannot be used in WEB
source, and getting WEAVE output to work in LaTEX documents requires te-
dious adjustments by hand. noweb works with both plain TEX and LaTEX.
Both WEAVE and noweave depend on the text formatter in two ways: the
source of the program itself, and the supporting macros. WEAVE's source
(written using WEB for C) is several thousand lines long, and the formatting
code is not isolated. noweave's source is a 57-line shell script, and only 31 of
those lines have to do with formatting. Both WEAVE and noweave use about
200 lines of supporting macros for plain TEX. noweb uses another 80 lines to
support LaTEX, most of which is used to eliminate duplicate page numbers
in cross-reference lists.
  noweb has two features that weren't in the original WEB, but that ap-
peared in some of WEB's later adaptations. They are the ability to inform
the compiler of the original locations of source lines and the ability to extra*
 *ct
more than one program from a single source file.
  Reviewers have had many expectations of literate-programming tools [13,
14]. The most important is verisimilitude: a single input should produce
both compilable program and publishable document, warranting the correct-
ness of the document. Others include flexible order of elaboration, ability
to develop program and documentation concurrently in one place, cross-
references, and indexing. WEB satisfies all these expectations, and noweb
satisfies all but one (it does not provide automatic indexing).
 
                       12

 
Discussion
 
WEB takes the monolithic approach to literate programming_it does every-
thing. noweb's approach is to compose simple tools that manipulate files
in the noweb format. Existing Unix tools provide some of the WEB features
that aren't found in noweb. Unix supplies two macro processors: the C pre-
processor and the m4 macro processor. xstr extracts string literals. patch
provides a form of version control similar to WEB's change files. Few of WEB's
remaining features will be missed; for example, many compilers evaluate
constant expressions at compile time. Experience with WEB has suggested
that prettyprinting may be more trouble than it is worth, and that the index
of identifiers, while useful, is not a necessity [9].
  Three things distinguish noweb from previous work.  noweb takes as
simple as possible a view of literate programming and the tools needed
to implement it. Instead of relying on a generator or re-implementation to
support different programming languages, noweb is independent of the target
programming language. noweave's dependence on its typesetter is small and
isolated, instead of being distributed throughout a large implementation.
  Experimenting with noweb is easy because the tools are simple and they
work with any language. If the experiment is unsatisfying, it is easy to
abandon, because notangle's output, unlike TANGLE's, is readable. noweb
is simpler than WEB and is easier to use and understand, but it does less. I
argue, however, that the benefit of WEB's extra features is outweighed by cost
of the extra complexity, making noweb better for writing literate programs.
  noweb can be obtained by anonymous ftp from
csservices.princeton.edu, in file pub/noweb.shar.Z.
 
Acknowledgements
 
Mark Weiser's invaluable encouragement provided the impetus for me to
write this paper, which I did while visiting the Computer Science Labo-
ratory of the Xerox Palo Alto Research Center.  Comments from David
Hanson and from the anonymous referees stimulated me to improve the pa-
per. The development of noweb was supported by a Fannie and John Hertz
Foundation Fellowship.
 
                       13

 
References
 
[1]P. J. Denning. Announcing literate programming. Communications of
   the ACM, 30(7):593, July 1987.
 
[2]D. Gries and J. Bentley. Programming pearls: Abstract data types.
   Communications of the ACM, 30(4):284-290, April 1987.
 
[3]K. Guntermann and J. Schrod. WEB adapted to C. TUGboat, 7(3):134-
   137, October 1986.
 
[4]B. W. Kernighan and R. Pike. The UNIX Programming Environment.
   Prentice-Hall, 1984.
 
[5]D. E. Knuth. The WEB system of structured documentation. Technical
   Report 980, Stanford Computer Science, Stanford, California, Septem-
   ber 1983.
 
[6]D. E. Knuth. Literate Programming, volume 27 of Center for the Study
   of Language and Information Lecture Notes. Leland Stanford Junior
   University, Stanford, California, 1992.
 
[7]S. Levy. WEB adapted to C, another approach. TUGBoat, 8(1):12-13,
   1987.
 
[8]N. Ramsey. Literate programming: Weaving a language-independent
   WEB. Communications of the ACM, 32(9):1051-1055, September 1989.
 
[9]N. Ramsey and C. Marceau. Literate programming on a team project.
   Software_Practice & Experience, 21(7):677-683, July 1991.
 
[10]W. Sewell. How to MANGLE your software: the WEB system for Modula-2.
   TUGboat, 8(2):118-128, July 1987.
 
[11]W. Sewell. Weaving a Program: Literate Programming in WEB. Van
   Nostrand Reinhold, New York, 1989.
 
[12]H. Thimbleby. Experiences of `literate programming' using cweb (a
   variant of Knuth's WEB). Computer Journal, 29(3):201-211, 1986.
 
[13]H. Thimbleby.  A review of Donald C. Lindsay's text file difference
   utility, diff. Communications of the ACM, 32(6):752-755, June 1989.
 
                       14

 
[14]C. J. Van Wyk. Literate programming: An assessment. Communica-
   tions of the ACM, 33(3):361-365, March 1990.
 
                       15
 
From Peter Fri Mar 19 13:26:37 MEZ 1993
Date: Fri, 19 Mar 93 13:26:37 MEZ
From: Peter Schmitt <A8131DAL@AWIUNI11.EDVZ.UNIVIE.AC.AT>
Reply-To: LitProg@SHSU.edu
To: leew@cs.utexas.edu, litprog@SHSU.edu
Subject: Re: Typesetting C assertions
 
On Wed, 17 Mar 1993 10:32:49 -0600 you said:
>I'm trying to build a web in which assertions don't look like just
>another procedure call.  In particular, I'd like them to look something like
>this:
>
>        * Assertion:  <the actual assertion>
>
>where the * represents a bullet.  In CWEB I'd like to be able to
>"@f assert TeX" and "\def\assert(#1){\bullet\ {\rm Assertion:}\quad #1}".
>Unfortunately, this doesn't work since the assertion may have parentheses
>in it, and TeX doesn't nest parentheses in macro args (so the first right
>paren will end the argument).  I _could_ use ");" as the argument-end
>delimeter, but I'd also like to be able to generalize the technique so
>that I can weave "sqrt(x)" into "\sqrt{x}", and the ); technique won't work
>there.
>
The following macros solve the problem by counting parentheses until
pairs are matched. This approach may not work in every case,
but it can be used for the two cases mentioned.
 
Hope this helps!
 
Peter
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcount\unmatched
\let\(=( \let\)=)
 
\catcode`\(\active \catcode`\)\active
\def({\ifnum \unmatched=0 \LEFT \else \(\fi
      \advance\unmatched by 1
     }
\def){\advance\unmatched by -1
      \ifnum \unmatched=0 \RIGHT \endgroup \else \)\fi
     }
\catcode`\( 12 \catcode`\) 12
 
\def\START{\begingroup \catcode`\(\active \catcode`\)\active \unmatched=0 }
 
\def\sqrtLEFT{\setbox0=\hbox\bgroup$}
\def\sqrtRIGHT{$\egroup $\Sqrt{\box0}$}
\let\Sqrt\sqrt
\def\sqrt{\START \let\LEFT\sqrtLEFT \let\RIGHT\sqrtRIGHT}
 
\def\assert{\START \let\LEFT\relax \let\RIGHT\egroup
            \noindent$\bullet$\quad\rm Assertion: \bgroup\it
            }
 
\sqrt(1)---a
 
\sqrt (1(2))---b
 
\sqrt (1(2)3(4(5)))---c
 
\assert(1)---a
 
\assert (1(2))---b
 
\assert (1(2)3(4(5)))---c
 
\bye
 
Peter Schmitt                             a8131dal@awiuni11.edvz.univie.ac.at
                                                        schmitt@awirap.bitnet
-----------------------------------------------------------------------------
Institute of Mathematics                                     Strudlhofgasse 4
University of Vienna                                              A-1090 Wien
                                                                      Austria
 
From George Fri Mar 19 09:45:45 CST 1993
Date: Fri, 19 Mar 1993 09:45:45 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: M.Piff@sheffield.ac.uk
Subject: PP on FILESERV/Niord
 
Mike Piff <M.Piff@sheffield.ac.uk> forwarded me a utility he has written
which converts Pascal and Modula-2 programs into input for LaTeX and TeX
files.  I am appending the description file for your reference.  In
addition to SHSU, these files should propagate to ftp.tex.ac.uk and
ftp.uni-stuttgart.de in the support areas of their TeX archive areas.
 
Regards and my thanks to Mike for his contribution,   George
 
                                    PP
                                    --
The PP package includes a UUENCODEd ZIP archive of Mike Piff's
<M.Piff@sheffield.ac.uk> utility to convert a free-standing Modula-2 or
Pascal program into a Pretty-Printed LaTeX/plain TeX file ready to input
into your document.  This is more attractive than a verbatim listing.  The
source code is included in this distribution, together with an MS-DOS
executable.  The output of PP is similar to that of WEB, say, but your
program is free-standing and you do not need to learn to use WEB.
 
To retrieve the single 59 512-byte block UUENCODEd ZIP archive, include:
 SENDME PP
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu). 
The ZIP file itself may be retrieved via anonymous ftp from Niord.SHSU.edu
(192.92.115.8) in [FILESERV.PP].
 
Files in PP.ZIP:
 Length  Method   Size  Ratio   Date    Time   Name ("^" ==> case
 ------  ------   ----  -----   ----    ----   ----   conversion)
      0  Stored       0   0%  03-19-93  09:12  pp/
  37824  Deflate  13118  65%  03-18-93  15:12  pp/pp.exe
  19884  Deflate   5397  73%  03-18-93  15:12  pp/pp.mod
    463  Deflate    177  62%  12-12-90  13:47  pp/pas.res
    536  Deflate    202  62%  09-26-90  15:43  pp/mod.res
   3329  Deflate   1588  52%  03-19-93  09:12  pp/README
 ------          ------  ---                   -------
  62036           20482  67%                   6      
 
From marcus@x4u.desy.de Sat Mar 20 11:21:57 +0100 1993
Date: Sat, 20 Mar 93 11:21:57 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: Literate Programmers <litprog@shsu.edu>
Subject: More LitProg Documents on the World Wide Web
 
I put a link to the CLiP and NOWEB (*) documents which I could access
into  the Literate Programming Page on the World Wide Web.
  If you have access to the Web, try the address
 
  http://x4u.desy.de:/
 
or directly
 
  http://x4u.desy.de:/gnu/ftp/pub/www/projects/LitProg.html
 
or via
 
  http://info.cern.ch/hypertext/DataSources/bySubject/Computing/Languages.html
 
(feed one of these to your WWW browser) and tell me what you think.
From the DESY Home Page you have to choose the "Literate Programming"
entry point, and from there the menu "Tools". I'd be eager to put some
processed example (maybe PostScript) into the "Examples" menu, too.
 
I'd be glad if other authors of WEB or general LitProg systems would
contribute something to the Web, too. At the moment I put a link to
the  UK TeX Archive (Ada, APL,...) and the freeHEP Database (FWEB, CWEB).
Contact me for more information.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
  [WWW] http://x4u.desy.de:80/gnu/ftp/pub/www/people/marcus.html
 
(*) Norman:
    I'd like to obtain an FTP address for the PS version of the 1992
    document whose plain version was sent to the list. Thanks in advance.
 
From marcus@x4u.desy.de Sat Mar 20 17:31:45 +0100 1993
Date: Sat, 20 Mar 93 17:31:45 +0100
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: grodecki@informix.com (Don Grodecki)
Subject: WWW
 
Stephen Cross <scc@bnr.co.uk>
 
More than one person has asked me, so I CC to LitProg.
 
|> What is the World Wide Web?  Some sort of HyperText thing?  Is the
|> browser for it available?
 
  The World Wide Web is a wide-area hypermedia information retrieval
initiative aiming to give universal access to a large universe of
documents (FTP, HTTP, gopher, WAIS protocols). It was developped
mainly at CERN.
  There is a couple of browsers available, the most comfortable being
Xmosaic (from: ftp.ncsa.uiuc.edu:/Web/xmosaic, also binaries for
some machines)...all the info is on the Web, but if you are not
connected yet, look at info.cern.ch:/pub or just say
 
telnet info.cern.ch
 
which will invoke the (dumb, but universal) WWW line mode browser.
From there, using the HEP link, you can go to DESY, and from there to
LITERATE PROGRAMMING (Just one possiblility). Or go out elsewhere to
the Web [and never be confused about "the Web" and our "WEB"].
 
|> Could this tool be used for linking together
|> function & design & code documents?
 
I think to explore this possibility will be one of the outcomes
of Stephen Cross' work which he outlined on this list some time
ago. If there is a way for using HyperText for Literate Programming,
we can undoubtedly use the universal capabilites of the World Wide
Web.
  HyperText can now also be produced with FrameMaker. Info is on
info.cern.ch.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
  [WWW] http://x4u.desy.de:80/gnu/ftp/pub/www/people/marcus.html
 
From Matthias Mon Mar 22 14:38:48 +0100 1993
Date: Mon, 22 Mar 1993 14:38:48 +0100
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Spidery WEB for Macintosh (MPW) available
 
A version if Spidery WEB for the Apple Macintosh is available by anonymous ftp
 
Site: nic.switch.ch [130.59.1.40]
File: software/mac/src/mpw_c/MPW_SpiderWEB_21Mar93.sit.bin
 
This file, stored in *MacBinary* format (don't forget to use binary mode
for transferring it), contains sources and binaries for Awk, ANSI C, and C++
tangle and weave. You need the Macintosh Programmers Workshop to run the
binaries or compile the sources.
 
Matthias
 
-----
Matthias Neeracher                                  neeri@iis.ee.ethz.ch
  "And that's why I am going to turn this world upside down, and make
   of it a fire so *bright* that someone real will notice"
                                -- Vernor Vinge, _Tatja Grimm's World_
 
From S.C.Cross@bnr.co.uk Mon Mar 22 13:43:20 GMT 1993
Date: Mon, 22 Mar 93 13:43:20 GMT
From: S.C.Cross@bnr.co.uk
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: WWW
 
>
> |> Could this tool be used for linking together
> |> function & design & code documents?
>
> I think to explore this possibility will be one of the outcomes
> of Stephen Cross' work which he outlined on this list some time
> ago. If there is a way for using HyperText for Literate Programming,
> we can undoubtedly use the universal capabilites of the World Wide
> Web.
>   HyperText can now also be produced with FrameMaker. Info is on
> info.cern.ch.
>
>   --Marcus Speh
>   --<marcus@x4u.desy.de>
>   [WWW] http://x4u.desy.de:80/gnu/ftp/pub/www/people/marcus.html
>
>
 
FYI I have a couple of references on Hypertext and Literate Programming
 
"A Hypertext System for Literate C++ Programming"
J. Sametinger, Journal of Object Oriented Programming,
Vol. 4, No. 8, January 1992, pp 24-29
 
"A Hypertext for Literate Programming"
M. Brown, Lecture Notes in Computer Science,
Vol 468, 1990, pp 250-259
 
----------------------------------------------
Stephen Cross,  Systems & Software Engineering
BNR Europe Ltd, Harlow, Essex, England
Email: scc@bnr.co.uk
Internal Tel  : 742 2861
External Tel  : +44 (0)279 402861
 
From grodecki@informix.com Wed Mar 24 16:17:02 CST 1993
Date: Wed, 24 Mar 93 16:17:02 CST
From: grodecki@informix.com (Don Grodecki)
Reply-To: LitProg@SHSU.edu
To: x4u.desy.de!marcus@uunet.pa.dec.com
Subject: HyperWeb
 
Marcus Speh writes:
 
> If there is a way for using HyperText for Literate Programming,
> we can undoubtedly use the universal capabilites of the World Wide
> Web.
 
Please read the article by Vista Technologies on HyperWeb Literate
Programming in ACM-SDE-12/92/VA.
 
Does anyone have any information on this interesting LitProg project?
 
From norman@bellcore.com Wed Mar 24 23:31:33 -0500 1993
Date: Wed, 24 Mar 93 23:31:33 -0500
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu, x4u.desy.de!marcus@uunet.pa.dec.com
Subject: Re:  HyperWeb
 
what in the world is ACM-SDE-12/92/VA?
 
From Eric Wed Mar 24 23:31:33 -0500 1993
Date: Wed, 24 Mar 93 23:31:33 -0500
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Provisional CLiP manual
 
A provisional manual for the CLiP/MS-DOS system has now been prepared.
The type-set version can be retrieved anonymously by FTP as the file
 
 			CLIP_MAN.PS
from the directory
			clip\ms_dos
on
			sun01.info.wau.nl.
 
I have also prepared and ASCII version as CLIP_MAN.ASC. But this is only meant
as an escape in case the type-set version does not print properly on your
laserprinter.
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From leew@cs.utexas.edu Fri Mar 26 16:59:36 -0600 1993
Date: Fri, 26 Mar 1993 16:59:36 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Announcing a WinWord WEB (such as it is)
 
I have just completed a crude (repeat crude) WEB system that works with
Microsoft Word for Windows (v2.0).  Anyone who wants to play with it is
welcome to get the file pub/leew/wordweb.zip via anonymous ftp to
bart.kean.edu.  The distribution includes a Word template with special
macros, menu items, and a paragraph style defined (WORDWEB.DOT), a
mercifully brief description of the system and how to use it (WORDWEB.DOC),
and a trivial example program (EXAMPLE1.DOC).
 
This distribution is really a case of what you see is all you get.  I do
not intend on supporting this product (I don't use it myself; I'm still an
unrepentant TeXXie), but there was such an extended discussion on the
network about such an animal that it seems worthwhile to make my efforts
generally available.  If anyone is interested in supporting WinWordWEB on a
regular basis, please let me know.
 
Ironically, the reason I ended up ``belling the cat'' myself (and being
hoist by my own petard) is due to a colleague's success using noweb.  I'd
finally convinced one of my coworkers here to try literate programming.
Once he got used to it, he was so ecstatic that everyone else was
interested in trying it, but no one wanted to learn a new tool.  WinWordWEB
is the result.
 
I'll be very interested in the experiences of anyone who tries using the
package, particularly if you're interested in taking over this project.
The program has a number of flaws, but is definitely usable.  I will
respond to all bug reports, but I don't promise to fix any of them.
 
Happy hunting.
 
		-- Lee
 
From George Sun Mar 28 11:12:37 CST 1993
Date: Sun, 28 Mar 1993 11:12:37 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: RE: Announcing a WinWord WEB (such as it is)
 
On Fri, 26 Mar 1993 16:59:36 -0600, leew@cs.utexas.edu (Lee Wittenberg)
announced:
> I have just completed a crude (repeat crude) WEB system that works with
> Microsoft Word for Windows (v2.0).  Anyone who wants to play with it is
> welcome to get the file pub/leew/wordweb.zip via anonymous ftp to
> bart.kean.edu.  The distribution includes a Word template with special
> macros, menu items, and a paragraph style defined (WORDWEB.DOT), a
> mercifully brief description of the system and how to use it (WORDWEB.DOC),
> and a trivial example program (EXAMPLE1.DOC).
 
I have placed the original ZIP distribution in [FILESERV.WORDWEB] as
WORDWEB-0_00.ZIP on Niord.SHSU.edu (192.92.115.8) for anonymous ftp
retrieval from here, and have UUENCODEd the ZIP file such that the command:
 SENDME WORDWEB
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu)
will also retrieve it via e-mail.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From se_haux@rcvie.co.at Mon Mar 29 09:59:41 +0200 1993
Date: Mon, 29 Mar 93 09:59:41 +0200
From: se_haux@rcvie.co.at (Michael Haux)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Request for WEB information
 
Hello,
 
I'm quite new on this mailing list and would appreciate some information.
 
- Is there an overview over available WEBS? I only know of CWEB, FWEB
and the newly announced WinWord-WEB.
 
- Has anyone created a WEB for Interleaf?
 
- Are there any literate programming systems (WEBS?) using hypertext
features available?
 
Thanks and regards,
 
               Michael Haux, Internet: Michael.Haux@rcvie.co.at
 
            V             Software Engineering Department
+-----------------------+ Alcatel Austria Forschungszentrum GmbH
|  A  L  C  A  T  E  L  | Ruthnergasse 1-7, A-1210 Vienna, Austria/EUROPE
+-----------------------+ Voice: +43 1 39 16 21 362    Fax:   +43 1 39 14 52
 
From Eric Mon Mar 29 09:59:41 +0200 1993
Date: Mon, 29 Mar 93 09:59:41 +0200
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu
To: LITPROG@shsu.edu
Subject: Problems with postscript files of CLiP
 
Some people have problems with the postscript files of the CLiP system
residing in the directory "ms_dos" of ftp node "sun01.info.wau.nl".
I have replaced these file by postscript files prepared with a different
driver. Hopefully this resolves the printing problems.
Should you continue to have problems with these postscript files you can
send me also your conventional mail adress and I will mail copies of the
desired files by conventional mail. Of course fax-ing is also a possibility
but due to the poor quality I only recommended this if you are really
in a hurry.
 
Eric W. van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Richard Wed Mar 31 16:31:14 +1000 1993
Date: Wed, 31 Mar 1993 16:31:14 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Mini-indexes in TeX:  The Program & METAFONT:  The Program
 
Dear LitProgrammers:
 
`TeX:  The Program' and `METAFONT:  The Program' have
`mini-indexes' on the bottom right of each
double page.  How were they done?  I weaved tex.web but I
didn't get any of these indexes in the output.
 
I'm surprised this isn't an FAQ.  (Or am I just na\"\i ve?)
 
Richard.
--
Richard Walker                            richard@cs.anu.edu.au
Department of Computer Science            Aust:  (06) 249 5687
The Australian National University        Intl: +61 6 249 5687
GPO Box 4, Canberra, ACT 2601, Australia
 
From stephan@stack.urc.tue.nl Wed Mar 31 10:29:20 +0200 1993
Date: Wed, 31 Mar 1993 10:29:20 +0200 (MET DST)
From: stephan@stack.urc.tue.nl (Stephan Eggermont)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX:  The Program & METAFONT:  The Program
 
> `TeX:  The Program' and `METAFONT:  The Program' have
> `mini-indexes' on the bottom right of each
> double page.  How were they done?  I weaved tex.web but I
> didn't get any of these indexes in the output.
>
> I'm surprised this isn't an FAQ.  (Or am I just na\"\i ve?)
 
Well, some time ago I asked the same question, so it might be...
 
Anyway, the answer I got was: by hand. I suppose there is too much hand-tuning
needed to get it working ok.
 
groetjes,
  Stephan Eggermont
 
From sanjeev@theory.cs.psu.edu Wed Mar 31 08:18:49 -0500 1993
Date: Wed, 31 Mar 1993 08:18:49 -0500
From: sanjeev@theory.cs.psu.edu (Sanjeev Y. Dharap)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Mini-indexes in TeX:  The Program & METAFONT:  The Program
 
You wrote:
 
| Dear LitProgrammers:
|
| `TeX:  The Program' and `METAFONT:  The Program' have
| `mini-indexes' on the bottom right of each
| double page.  How were they done?  I weaved tex.web but I
| didn't get any of these indexes in the output.
|
| I'm surprised this isn't an FAQ.  (Or am I just na\"\i ve?)
|
I inquired about this a couple of years ago on comp.text.tex. They
(especially Don Hosek) said that Knuth did them by hand.
 
thanx
 
sanjeev
 
From Silvio Wed Mar 31 06:44:17 -0800 1993
Date: Wed, 31 Mar 93 06:44:17 -0800
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
> `TeX:  The Program' and `METAFONT:  The Program' have
> `mini-indexes' on the bottom right of each
> double page.  How were they done?  I weaved tex.web but I
> didn't get any of these indexes in the output.
 
Knuth has a program "ctwill" that works in two passes to make the
mini-indexes.  However, it takes a large amount of hand intervention,
and for that reason he has not been distributing it.  Some people on
the list might have it, though.
 
Silvio
 
From ras@skanda.zko.dec.com Wed Mar 31 11:08:10 -0500 1993
Date: Wed, 31 Mar 93 11:08:10 -0500
From: ras@skanda.zko.dec.com (Bob Surtees)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Mini-indexes in TeX: The Program & METAFONT: The Program
 
Silvio> Knuth has a program "ctwill" that works in two passes to make the
Silvio> mini-indexes.  However, it takes a large amount of hand intervention,
Silvio> and for that reason he has not been distributing it.  Some people on
Silvio> the list might have it, though.
 
Silvio> Silvio
 
What does ``large amount of hand intervention'' mean.  I would also be very
interested in getting my hands on this program if it is available.
 
Bob Surtees (ras@zkanda.zko.dec.com)
 
From Nelson Wed Mar 31 09:29:35 MST 1993
Date: Wed, 31 Mar 93 09:29:35 MST
From: "Nelson H. F. Beebe" <beebe@math.utah.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
The story I got from David Fuchs, who wrote the code to do the mini-indexes
on each page of Volumes B and D of Computers and Typesetting, was that
the coding was a hack done just for those books, using a variety of non-portable
tools to get the job done.  I think those indexes are terrific, and keep hoping
that someday, someone will write an extended set of changes for weave that
will provide them.
 
Nelson H. F. Beebe                      Tel: +1 801 581 5254
Center for Scientific Computing         FAX: +1 801 581 4148
Department of Mathematics, 105 JWB      Internet: beebe@math.utah.edu
University of Utah
Salt Lake City, UT 84112, USA
 
From dak@POOL.Informatik.RWTH-Aachen.DE Wed Mar 31 18:30:59 +0200 1993
Date: Wed, 31 Mar 93 18:30:59 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  Mini-indexes in TeX:  The Program & METAFONT:  The Program
 
Regardless of how they were done, they make the "added value" the
books have over the free WEB sources. Note that unlike the TeXbook
and the METAFONTbook, which you are not allowed to reproduce
the WEBsources can be made into printable form as much as you like
(they are free!). But you will not get the little indexes that way.
 
From Frank Wed Mar 31 19:46 GMT 1993
Date: Wed, 31 Mar 93 19:46 GMT
From: Frank Pappas <0004238973@mcimail.com>
Reply-To: LitProg@SHSU.edu
To: LitProg <LitProg@shsu.edu>
Subject: ctwill
 
I would like to get a copy of ''ctwill'' to use with the Ada web I'm working
on. If someone could send me an e-mail address to get it from or if someone
could just mail a copy of it to me I would appreciate it.
 
Frank Pappas
e-mail: fpappas@mcimail.com
phone:  (215) 789-3206
 
From George Wed Mar 31 17:08:25 CST 1993
Date: Wed, 31 Mar 1993 17:08:25 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: info-tex@SHSU.edu, litprog@SHSU.edu, twg@SHSU.edu
Subject: SHSU to be down Thursday, 1 April 1993
 
A quick note to everyone:
 
Our T1 line was brought in on Monday and this afternoon we received the
necessary hardware to actually use it.  I cannot say exactly when, but
tomorrow (1 April -- what a great day to do this -- no this is NOT an April
Fool's joke [at least to the best of my knowledge]), we will have to take
down our network services while we move a few wires and coordinate a
changeover from the 56kB line to the T1 line with the University of Texas
Health Sciences Center in Houston (where we connect to T3 speed).  Exactly
how long we are to be down is anyone's guess at the moment, but it
shouldn't be more than a few hours.
 
I sincerely hope (and expect!) that this upgrade to our connectivity will
radically improve our connection speeds since we have literally saturated
the existing 56kB line.
 
Finally (gotta have a teaser to close, right?), within a few days (after I
see what kind of mess we've wrought for ourselves), watch for a major
announcement related to the mystical letters CTAN (pronounced see-tan).
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Richard Thu Apr 1 11:05:58 +1000 1993
Date: Thu, 1 Apr 1993 11:05:58 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
\begin{naive}
Would it be so hard to make the necessary modifications to
weave and to cwebmac.tex?  Actually, wouldn't LaTeX make the job
easier?  (Hint hint - I am eagerly awaiting CWEB 3.0.)
\end{naive}
 
Should we work towards producing these indexes?
I read the first 125+ sections of TeX:  The Program
recently, and those mini-indexes made it just *so* much easier.
 
Richard.                                  richard@cs.anu.edu.au
 
From S.C.Cross@bnr.co.uk Thu Apr 1 16:03:37 BST 1993
Date: Thu, 1 Apr 93 16:03:37 BST
From: S.C.Cross@bnr.co.uk
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Literate Programming Using FrameMaker
 
Here is a very quick and simple method for using FrameMaker to write
Literate Programs:-
 
(1)	Create two conditional_text tags (Special/Conditional Text...)
	Call the tags something like 'DocText' and 'CodeText'
 
(2)	Apply the CodeText Tag to all the code in the document
 
(3)	Apply the DocText Tag to everything else in the document
 
(4)	To Tangle the document simply change the Show/Hide options for the
	conditional text so that only the CodeText is shown
 
(5)	Save the Code to a text source file (File/Save As)
 
Okay so its nothing special, but it does work.  There are problably other
(better) ways of doing this, any ideas?
 
Steve.
 
----------------------------------------------
Stephen Cross,  Systems & Software Engineering
BNR Europe Ltd, Harlow, Essex, England
Email: scc@bnr.co.uk
Internal Tel  : 742 2861
External Tel  : +44 (0)279 402861
 
From preston@cs.rice.edu Thu Apr 1 10:38:34 CST 1993
Date: Thu, 1 Apr 93 10:38:34 CST
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
>Would it be so hard to make the necessary modifications to
>weave and to cwebmac.tex?
 
I don't see how it could be easy.
Consider the problem for a second.
 
Weave looks at the web and builds the .tex file,
inserting necessary TeX directives, cross reference info,
and the indices.  But it doesn't know where TeX is going
to make line breaks or page breaks.  Therefore, it's going to
have a hard time finding where to put mini-indices and what
identifiers to put in the indices.
 
Of course, we have a couple of exampoles that say it's possible,
but we also have Beebe saying it required lots of hand tweaking.
 
Much more doable would be indices at the end of every major section.
That way weave wouldn't have to know about page breaks.
 
Preston Briggs
 
From norman@bellcore.com Thu Apr 1 16:40:30 -0500 1993
Date: Thu, 1 Apr 93 16:40:30 -0500
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
> I don't see how it could be easy.
> Consider the problem for a second.
 
> Weave looks at the web and builds the .tex file,
> inserting necessary TeX directives, cross reference info,
> and the indices.  But it doesn't know where TeX is going
> to make line breaks or page breaks.  Therefore, it's going to
> have a hard time finding where to put mini-indices and what
> identifiers to put in the indices.
 
That part's not hard; you use insertions, which are TeX's way of
handling footnotes and floating figures.  The hard part is the sorting
and elimination of duplicates---these tasks are difficult to implement
in TeX.
 
Norman
 
From George Thu Apr 01 17:20:44 CST 1993
Date: Thu, 01 Apr 1993 17:20:44 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: litprog@SHSU.edu
Subject: Literate Programming Library on Gopher
 
Yesterday, Marcus Speh contacted me regarding where I had placed the
Literate Programming files within the Gopher Server on Niord.SHSU.edu
(192.92.115.8, port 70) so he could include them in his project.  Well, at
the time, I hadn't included these files (for no good reason -- I just
hadn't done it).
 
Anyway, I think I have a relatively comprehensive Literate Programming
library included now.  If you are interested, the library is located within
the "TeX-related Materials" item (number 9 presently) as "Literate
Programming Library" (also item 9 on that menu presently).  If all you are
interested in is a link to this item, the Gopherspace link is:
 
#####################################
## Literate Programming files at SHSU
Name=Literate Programming Library
Type=1
Port=70
Path=1gopher_root:[_DATA.LITPROG]
Host=Niord.shsu.edu
 
I think I have included just about everything in our archives there (maybe
a few are still missing, but I think it's pretty much there).  If you look
there, you will see that one of the last entries is to the "web" directory
on the Comprehensive TeX Archive Network (CTAN) -- I hope to propagate the
Literate programming packages to this directory sometime soon (still a few
finishing touches are in order there -- this is one of my intended
finishing touches).
 
The VMS server which runs Niord is grossly out of date (it's as up to date
as available for VMS, which is grossly out of date relative to all other
server platforms).  It has problems with executables, binary files, etc.
(which is one reason I like the link to the Unix server we run for the
CTAN), although the link above is stable -- promise! (even if all it
ultimately has is a link to the Unix host, the main Niord entry will be
stable; but a few of us here are working on a new VMS server, so........)
 
If you see that I am missing anything, please let me know and I will make
every effort to get in whatever I am missing.  Better still, if you are the
author of one of the packages and would consent to a routine mirroring of
your authoritative host into the CTAN (Aston, Stuttgart, and SHSU in case
you were wondering what hosts were involved), please let me know and I will
arrange for that to occur (which is probably the least painful way I can
think of to keep this updated, as well as widely propagated).  The basic
information I need is (a) host, (b) consistent directory and filename
string to expect, and (c) any limitations at your site I ought to respect
when ftp'ing in to mirror your files.
 
Have fun, folks!
 
--George
 
From Richard Fri Apr 2 12:38:46 +1000 1993
Date: Fri, 2 Apr 1993 12:38:46 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
> That part's not hard; you use insertions, which are TeX's way of
> handling footnotes and floating figures.  The hard part is the sorting
> and elimination of duplicates---these tasks are difficult to implement
> in TeX.
 
Well, Donald Arseneau seems to have done just that with his
cite.sty style for LaTeX (at least for version 3.0, October 1992).
It compresses and sorts lists of numerical citations:
e.g. what would be printed as [3,7,2,8,4,6,3] is now printed as
[2--4,6--8].
 
Richard.
 
From leew@cs.utexas.edu Fri Apr 2 15:53:19 -0600 1993
Date: Fri, 2 Apr 1993 15:53:19 -0600
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Literate Programming Using FrameMaker
 
Stephen Cross writes:
 
  > Here is a very quick and simple method for using FrameMaker to write
  > Literate Programs:-
  >
  > (1)	Create two conditional_text tags (Special/Conditional Text...)
  > 	Call the tags something like 'DocText' and 'CodeText'
  >
  > (2)	Apply the CodeText Tag to all the code in the document
  >
  > (3)	Apply the DocText Tag to everything else in the document
  >
  > (4)	To Tangle the document simply change the Show/Hide options for the
  > 	conditional text so that only the CodeText is shown
  >
  > (5)	Save the Code to a text source file (File/Save As)
  >
  > Okay so its nothing special, but it does work.  There are problably other
  > (better) ways of doing this, any ideas?
 
It's a nice approach, but it isn't exactly ``tangling,'' as the latter
involves rearranging the code chunks from an human ordering (the sections
in a web are supposed to be organized in a way that is easy for the human
reader to grasp) into a machine ordering (something a compiler can
accept).  Your approach has the advantage of being able to interleave code
and documentation, but it has the disadvantage that the code must still be
presented in an order dictated by the machine.  (cf. Dijkstra's  "... I
want the program written down as I can understand it, I want it written
down as I would like to explain it to someone." ["Notes on Structured
Programming", in _Structured_Programming_, Academic Press, 1972]).
 
		-- Lee
 
From CGL@RUGR86.RUG.NL Mon Apr 5 11:33:01 -0500 1993
Date: Mon, 5 Apr 1993 11:33:01 -0500 (EDT)
From: CGL@RUGR86.RUG.NL
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
Sorting hard in TeX?
For Aston I submitted a paper where I do sorting within TeX.
Just provide your comparison operator and it will be sorted.
Look out for those proceedings or the MAPS from the Dutch TeX Users Group,
 NTG.
---Kees---
 
From mstacey@mcs.kent.edu Mon Apr 5 11:33:01 -0500 1993
Date: Mon, 5 Apr 1993 11:33:01 -0500 (EDT)
From: mstacey@mcs.kent.edu (Michael Stacey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
Richard Walker says:
>
> > That part's not hard; you use insertions, which are TeX's way of
> > handling footnotes and floating figures.  The hard part is the sorting
> > and elimination of duplicates---these tasks are difficult to implement
> > in TeX.
>
> Well, Donald Arseneau seems to have done just that with his
> cite.sty style for LaTeX (at least for version 3.0, October 1992).
> It compresses and sorts lists of numerical citations:
> e.g. what would be printed as [3,7,2,8,4,6,3] is now printed as
> [2--4,6--8].
>
> Richard.
>
 
Is there any place where one can get the required macros to configure
FunnelWeb so that LaTeX is used as the typesetter rather than TeX?
 
+--------------------------------------------------+--------------------------+
| Michael Stacey                                                              |
| mstacey@mcs.kent.edu				   			      |
|									      |
| Department of Mathematical and Computer Sciences                            |
| Kent State University				   			      |
| Kent, Ohio  44240				   			      |
+--------------------------------------------------+--------------------------+
 
From Zdenek Mon Apr 05 11:02:10 MDT 1993
Date: Mon, 05 Apr 93 11:02:10 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: Literate Progaramming list <LitProg@SHSU.edu>
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
I can see a way how to make the mini-indexes. Of course the mini-index must
be built by TeX, not by weave. Wherever weave finds an item to be indexed,
it should emit some TeX command. When TeXing the woven file, TeX should
store the index items in the token register (or someone may find a better way).
Then you have to rewrite the output routine which would typeset the mini-index
from the token register and then clear it so that the token register starts
again from scratch at the next page.
 
Well, it seems easy but I know that the task is not trivial.
 
Regards
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi>
 
From Richard Tue Apr 6 11:36:54 +1000 1993
Date: Tue, 6 Apr 1993 11:36:54 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
>
> Is there any place where one can get the required macros to configure
> FunnelWeb so that LaTeX is used as the typesetter rather than TeX?
>
A good question.  I was thinking of doing it myself if no one
else has done it.  Ross Williams claims to be LaTeX-illiterate,
so any such effort will be third party.
Note however that the TeX preamble which fw spits out is hard-coded
into the program.  Hence making it LaTeX-compatible will require
changing the program . . .
 
I am thinking of using FunnelWeb to develop a compiler using
some compiler tools (the Grosch set from Karlsruhe).  The tools
each have their own language, so I can't see any other way (except
noweb, but I'm a fairly competent TeXnician, so fw seems the
better option).
 
Richard.
 
From plyon@emx.cc.utexas.edu Mon Apr 5 23:33:26 -0500 1993
Date: Mon, 5 Apr 93 23:33:26 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Mini-indexes in TeX: The Program & METAFONT: The Program
 
> A good question.  I was thinking of doing it myself if no one
> else has done it.  Ross Williams claims to be LaTeX-illiterate,
> so any such effort will be third party.
> Note however that the TeX preamble which fw spits out is hard-coded
> into the program.  Hence making it LaTeX-compatible will require
> changing the program . . .
 
It is possible that no change to the programme itself will be need.  I
am, as well, for the most part unfamiliar with LaTeX, but it seems to
me that it might suffice to redefine all the TeX macros used in
FunnelWeb to invoke LaTeX macros or LaTeX compatible macros, collect
the redefinitions in a file, and "\input" that file as the first line
in a FunnelWeb source file. When FunnelWeb weaves a source file, the
definitions built into the programme are prepended to the woven
source, so they will be read by TeX before any of the redefinitions
are read, hence the latter will override the former. Most of the
FunnelWeb control sequence names start with "fw" so those should not
conflict with any of the LaTeX macros. On the other hand, the
FunnelWeb stuff does invoke outright certain plain TeX control
sequences such as \obeylines and \raggedbottom. If there are no lplain
definitions for these things, then indeed the FunnelWeb source must be
changed. (Otherwise, just override the FunnelWeb settings in the
included file.) If this works it will, nonetheless be a unsightly
hack, but it might be preferable to modifying and then recompiling.
(In the OS/2 port of FunnelWeb that I posted to the main OS/2 archive
site I did make a couple of small changes in texhead.tex (the file
containing the FunnelWeb macros) so that the appearance of the printed
source was a bit more to my tastes...)
 
In any case, even if it is necessary to modify texhead.tex, incorporating
the results in a recompilation is simple enough; one merely invokes Funnelweb
with the command that will convert texhead.tex into texhead.ctx and
recompiles. I am, to be sure, assuming that LaTeX compatible equivalents
for the existing macros will suffice; if there is no good way to map
such things as FunnelWeb's section heading scheme onto LaTeX's chapter/
section stuff, then it may be necessary to rethink some of FunnelWeb's
design to make it more LaTeX compatible.
 
In any event, William's internal documentation for texhead.tex is
thorough and it should not take one learned in the ways of LaTeX all
that long to see whether the conversion can be done just by redefining
what is in texhead.tex.
 
Ciao,
 
Paul Lyon
 
From Richard Tue Apr 6 21:19:09 +1000 1993
Date: Tue, 6 Apr 1993 21:19:09 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
> It is possible that no change to the programme itself will be need.  I
> am, as well, for the most part unfamiliar with LaTeX, but it seems to
> me that it might suffice to redefine all the TeX macros used in
> FunnelWeb to invoke LaTeX macros or LaTeX compatible macros, collect
> the redefinitions in a file, and "\input" that file as the first line
> in a FunnelWeb source file
 
Exactly - you either have to:
1. write a script to strip off the preamble of the woven output,
   replace it with the LaTeX version, *and add a postamble*; or
2. modify the fw program to print out a better preamble *and postamble*.
 
I think a modification is better - at least to add a typesetter
directive, viz.:
@p typesetter = latex
 
Ah yes, but how to handle the preamble and postamble?  How
about something like this:
@p typesetter = latex latexhead latexfoot
This would make the woven output look like this:
\input latexhead
< Normal woven output, but *without* the `plain TeX'-specific
  preamble and postamble >
\input latexfoot
 
latexhead.tex would contain the preamble you want, e.g.:
--------------
\documentstyle[12pt,fw-latex,makeidx,a4]{article}
 
. . . more stuff . . .
 
\begin{document}
\maketitle
\tableofcontents      % Maybe not always . . .
 
--------------
(fw-latex.sty would define all the `fw...' macros)
and latexfoot.tex would contain the postamble, e.g.:
--------------
\bibliography{myprogram}
 
\printindex
 
\end{document}
--------------
 
When rewriting the implementation of the `fw...' macros I think
we would want to use LaTeX's sectioning and indexing facilities.
 
What do you think?
 
Richard.
 
From ae1181t@stnfor.ae.ge.com Tue Apr 6 07:44:53 -0400 1993
Date: Tue, 6 Apr 1993 07:44:53 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
In FunnelWeb, you can set the typesetter using @t typesetter=tex. May
be the code is easy to change so that LaTeX may be an option (or
others?).
 
From norman@bellcore.com Tue Apr 6 17:39:25 -0400 1993
Date: Tue, 6 Apr 93 17:39:25 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Mini-indexes in TeX: The Program & METAFONT: The Program
 
> Is there any place where one can get the required macros to configure
> FunnelWeb so that LaTeX is used as the typesetter rather than TeX?
 
I'll just take this opportunity to point out that noweb works with
Latex as distributed.  You can ftp noweb from
bellcore.com:pub/norman/noweb.shar.Z  or from
csservices.princeton.edu:pub/noweb.shar.Z.
 
Norman Ramsey
 
From plyon@emx.cc.utexas.edu Wed Apr 7 12:14:49 -0500 1993
Date: Wed, 7 Apr 93 12:14:49 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: LaTeX and FunnelWeb
 
In regards to LaTeX and FunnelWeb, Richard Walker writes:
 
> When rewriting the implementation of the `fw...' macros I think
> we would want to use LaTeX's sectioning and indexing facilities.
 
> What do you think?
 
Well, since I have never actually written anything substantial using
LaTeX, all I can say is that it seems plausble to me that this would
be the right way to go, especially if LaTeX makes it possible to
easily set up a table of contents from the calls to the section
control sequences. Taken together these mechanisms could fill some
of the gap between FunnelWeb and the language specific Webs in the
matter of indexes and the like. Perhaps this may entice me away
from plain TeX to LaTeX :-)
 
My thinking had taken a different turn up to now. It seems to me that
one could construct a FunnelWeb supplement macro file using some of
the pieces avaibable from niord and eslewheres. So far all I have is a
small file "fwsupl.tex" that combines some bits nicked from the Cweb
macros with some nicked from the TeXbook appendix E via TeXsis. In
addition, I use the ruled tables package out of TeXsis. I have been
pondering how to use Karl Berry's eplain macros with FunnelWeb, but
have not gotten very far with this (other things, such as the teaching
I am paid to do, keep getting in the way :-) In addition, I would like
to have other capabilities, such as those offered by epic or PiCTeX,
or the TreeTeX package.
 
On a related point, it seems to me that, at least at present, the
resources, in the way of time and effort, available to improve the
state of literate programming tools, are rather limited. We are still
waiting for the new version of Cweb, for example; I presume that this
is because Levy and Knuth have little time to devote to it.
Accordingly, it seems to me that such energy and time as we have to
spare ought to go into improving the tools we already have rather than
into the development of GUI based ("WYSIWYG") literate programming
tools. I, for one, was disheartened to read Lee Wittenberg's posting
about his beginning efforts using Word for Windows, and that by S.C.
Cross on using FrameMaker. Besides a better interface to pertinent TeX
or LaTeX macro packages, I can think of several things that would be
of aid to the literate programmer, such as better macro
processing---to be achieved by stealing as much as seems applicable
from GNU M4 (and perhaps also the macro capability in the preprocessor
for the COOL C++ library, and other places as well), or cross-indexing
over multi-module web source, and the like.
 
Ciao,
 
Paul Lyon
 
From plyon@emx.cc.utexas.edu Wed Apr 7 12:49:24 -0500 1993
Date: Wed, 7 Apr 93 12:49:24 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Noweb and LaTeX
 
Norman Ramsey writes:
 
> I'll just take this opportunity to point out that noweb works with
> Latex as distributed.
 
Well, this had not occurred to me, but in light of the discussion about
FunnelWeb and LaTeX, it now seems to me that using LaTeX with noweb could
help significantly in making use of it. I rather liked the design idea
of noweb when I first saw it, but thought more development was needed.
I did a few things with it, but then switched to FunnelWeb as soon as
I managed to make a working OS/2 2.0 port of the latter.
 
Though I know little of LaTeX, being heretofore strictly a plain TeX
person, I rather wonder if the additional capabilities of LaTeX might
not be enough so that I could do what I wanted using noweb as well.
I must say though, that I will have a hard time reconciling myself to
using `<<...>>' rather than `@<...>@' when doing C/C++ :-)
 
Could someone who is more LaTeX literate than I make some suggestions
about how using LaTeX would make for better woven Webs?
 
Ciao,
 
Paul Lyon
 
From preston@cs.rice.edu Wed Apr 7 23:13:42 CDT 1993
Date: Wed, 7 Apr 93 23:13:42 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: web tool
 
Inspired by all these nice new tools, especially FunnelWeb and noweb,
I've written yet another web-like system.  Currently I call it nuweb,
punning slighly on Ramsey's noweb.
 
It's similar to FunnelWeb in that it allows use of many programming
languages and allowing the creation of many output files.  On the other
hand, it is much simpler and depends on latex (versus tex).  I also
stole the idea of writing output files to temps first and comparing
before touching the final result.  This is a _really_ nice feature for
large programs; everyone should do it.
 
The big advantages I see for latex are the multilevel sectioning
commands and the support for pictures (and bibliographies,
crossreferences, etc).  On the other hand, latex does add some
overhead to programming.  It may make nuweb better for writing papers
and large programs than for smaller examples.
 
Basically, you write a latex document, being slightly careful about
using @ characters, but otherwise using all the features of latex.
You can sprinkle in file definitions and macro definitions throughout
the code.  These'll be recognized and formatted slightly (code just
comes out it \tt, with the no changes in line breaks or indentation).
 
There's only one program.  You run it on the web file and it spits out
the .tex file and all the output files at once.  Basically, it's so
fast, I don't see a lot of reason not to do everything at once.  On
the other hand, I defined flags to suppress different passes for use
on slower machines.
 
When the tex file is written, the file and macro definitions get cross
reference info similar that provided by weave.  I can make indices for
file names and macro names, but I can't make an index of identifiers.
 
Thus, the big losses compared to a lagnuage-sensitive system like CWEB
are: no pretty printing, no identifier index, and no line number info
inserted in the output files.  The big advantages are: no pretty
printing, speed, and precise control of the output.  It can be used it
on any language or combination of languages (C, C++, Fortran, yacc,
lex, awk, make, and so forth).
 
There aren't very many commands:
 
@@			puts a single @ into the result
			(tex or output file)
 
@i file_name		includes a file
 
@o file-name scrap	writes the scrap out to the file
 
@d macro-name scrap	defines a macro that can be invoked from
			within a scrap
 
where scrap is
 
	 @{anything@}	where "anything" doesn't include @o, @d,
			@m, @f, or @{ but may include @<macro-name@>
 
			Every character between the @{ and the @}
			is significant, so be careful of those
			carriage returns.
 
			In the .tex output, a $\Diamond$ is inserted
			to help show how many newlines are at the end
			of a scrap.
 
@f			makes an index of file names
 
@m			makes an index of macro names
 
@<macro-name@>		may appear in a scrap.  On output to a file,
			will be exapanded to include all the scraps
			making up a macro.  The expansion will be
			indented to match the invocation.
 
A file or a macro may be defined in several places.  All the scraps
contributing to their definitions are simply concatenated.
 
I allow ... at the end of macro names (a la Knuth), so you can type
 
	@d This...
 
as an abbreviation for
 
	@d This is a long macro name
 
I wrote it all in a hurry over a weekend.  Then I rewrote it in
nuweb.  This took a little longer, since I was being more careful
(and fixing features that had turned out poorly).  I'm still filling in
documentation -- always hard for me.  I'll be glad to share it around
if people will send me bug reports.  The code is all in C (old-style,
not ANSI C).  Seems to work on a Sun; ought to work on other things.
Doesn't require awk or anything; but it doesn't make a lot of sense
without latex.
 
Preston Briggs
 
From Richard Thu Apr 8 15:56:39 +1000 1993
Date: Thu, 8 Apr 1993 15:56:39 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: LaTeX and FunnelWeb
 
OK, I bit the bullet and did the necessary work to get FunnelWeb to
work with LaTeX.  I was surprised how easy it was!  I didn't even
need to modify the fw program (but I did need to modify some of
the TeX macros).
 
To see how it's done, anonymous ftp to dcssoft.anu.edu.au and
look in the directory pub/richard.  (Or email if you can't ftp.)
I've put the style file there, as well as an example program
(a Knuth program originally in (Pascal) WEB, which appeared in CACM).
(But DO read the README!)
 
Please send me reports of problems . . . .
 
Richard (richard@cs.anu.edu.au).
 
From coates@spectro.jussieu.fr Thu Apr 8 11:08:38 +0200 1993
Date: Thu, 8 Apr 93 11:08:38 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Future Developments
 
> From: plyon@emx.cc.utexas.edu (Paul Lyon)
...
> On a related point, it seems to me that, at least at present, the
> resources, in the way of time and effort, available to improve the
> state of literate programming tools, are rather limited. We are still
> waiting for the new version of Cweb, for example; I presume that this
> is because Levy and Knuth have little time to devote to it.
> Accordingly, it seems to me that such energy and time as we have to
> spare ought to go into improving the tools we already have rather than
> into the development of GUI based ("WYSIWYG") literate programming
> tools. I, for one, was disheartened to read Lee Wittenberg's posting
> about his beginning efforts using Word for Windows, and that by S.C.
> Cross on using FrameMaker. Besides a better interface to pertinent TeX
> or LaTeX macro packages, I can think of several things that would be
> of aid to the literate programmer, such as better macro
> processing---to be achieved by stealing as much as seems applicable
> from GNU M4 (and perhaps also the macro capability in the preprocessor
> for the COOL C++ library, and other places as well), or cross-indexing
> over multi-module web source, and the like.
>
> Ciao,
>
> Paul Lyon
 
	Disheartened?  This intrigues me.  After all, few of us have the
foresight to really know what is going to be the way of the future.  I for one
don't see that improving the tools used by an elite few (and we are, let's face
it, a minority) should take precedence over creating tools that could be more
acceptable to the programming community at large.  Fewer and fewer people use
command lines any more, and Emacs is still often only for the cogniscenti,
wonderful as it is.  Many of my colleagues write all their scientific papers in
Microsoft Word; if I was to try to convince them to use Literate Programming
tools, I would have no chance with an Emacs/TeX combination.  I might have a
small chance with a Word for Windows package; who knows, using the coming
abilities of the OLE 2.0 (Object Linking Environment) one could create a
hypertext-style environment that might be much more attractive than anything
currently seen under UNIX/TeX/Emacs (at least for now, we'll see what Sun can
offer in terms of objects and such in the future).
	OK, so the argument is that maybe there are too few of us to chase all
of these goals at once.  But then, maybe there are too few of us to yet come to
a consensus on what is best.  We will see.
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From Richard Thu Apr 8 23:58:46 +1000 1993
Date: Thu, 8 Apr 1993 23:58:46 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Noweb and LaTeX
 
> Could someone who is more LaTeX literate than I make some suggestions
> about how using LaTeX would make for better woven Webs?
 
Sure.  LaTeX gives you:
 
. cover page
. table of contents, lists of tables & figures
. sectioning, page headers & footers
. bibliography in any format known to mankind!
. glossaries
. indexes
. easy-to-use footnotes, margin paragraphs, lists, tables,
     plus other LaTeX environments . . .
. new font selection scheme (if you dare)
. easily changeable page sizes, two-sided output, etc.
 
With `standard' (third-party) LaTeX style files you get:
 
. easy support for other languages (e.g. with german.sty)
. PostScript pictures (PStricks etc.)
. easy PostScript fonts
. make transparencies/slides using (say) FoilTeX (or even SLiTeX!)
. all the other hundreds of third-party styles . . . .
 
Summary:  Plain TeX + web/cweb macros <<<...<<< LaTeX
(insert arbitrary number of `less than' signs).
 
Richard.
 
From Paul Thu Apr 8 14:18:21 -0400 1993
Date: Thu, 8 Apr 1993 14:18:21 -0400
From: Paul Prescod <papresco@undergrad.math.uwaterloo.ca>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: LaTeX and FunnelWeb
 
> On a related point, it seems to me that, at least at present, the
> resources, in the way of time and effort, available to improve the
> state of literate programming tools, are rather limited. We are still
> waiting for the new version of Cweb, for example; I presume that this
> is because Levy and Knuth have little time to devote to it.
> Accordingly, it seems to me that such energy and time as we have to
> spare ought to go into improving the tools we already have rather than
> into the development of GUI based ("WYSIWYG") literate programming
> tools. I, for one, was disheartened to read Lee Wittenberg's posting
> about his beginning efforts using Word for Windows, and that by S.C.
> Cross on using FrameMaker. Besides a better interface to pertinent TeX
> or LaTeX macro packages, I can think of several things that would be
> of aid to the literate programmer, such as better macro
> processing---to be achieved by stealing as much as seems applicable
> from GNU M4 (and perhaps also the macro capability in the preprocessor
> for the COOL C++ library, and other places as well), or cross-indexing
> over multi-module web source, and the like.
 
Good idea!  Instead of making Literate programming useful to the
masses of programmers using DOS, Windows, and Mac, we'll try to
contain it to an almost wholly Unix-based phenomenon.
 
In fact, this fits beautifully with the whole Unix/C philosophy.  If we
make the intellectual price of admitance high enough, we can keep the
riff-raff from getting involved.
 
From huff@ecn.purdue.edu Fri Apr 9 10:27:29 -0500 1993
Date: Fri, 9 Apr 93 10:27:29 -0500
From: huff@ecn.purdue.edu (John E Huff)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Location of eqalign.sty
 
Could someone please tell me where I can get the eqalign.sty that fweave
puts as an option when one uses the command line option "-PL".
 
Thank you,
 
John Huff
 
From marcus@x4u.desy.de Fri Apr 9 19:33:50 +0200 1993
Date: Fri, 9 Apr 93 19:33:50 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Location of eqalign.sty
 
>>>>> On Fri, 9 Apr 93 10:27:29 -0500, huff@ecn.purdue.edu (John E Huff) said:
 
|> Could someone please tell me where I can get the eqalign.sty that fweave
|> puts as an option when one uses the command line option "-PL".
 
  Sorry, I dont know where to get that file from (you probably tried
  archie, too). Maybe this helps, though:
    In fweb.sty (included in FWEB-v1.30 release at lyman.pppl.gov), I read:
----------------------------------
% Get LaTeX to include the optional style file eqalign.sty.
%LaTeX.options "eqalign"
----------------------------------
 
  And the FWEB User's Manual (or the shorter Guide) for v1.30 says
 (section 20.3.5) that, with  the switch "LaTeX.options" you can
 include any options for
 
 \documentstyle[options]{style}
 
  but that the default is "" (as it should be). Thus, if this line is
  not commented out, "-PL" should not ask for "equalign.sty"
  (unless you changed fwebmac.sty which is overridden by fweb.sty).
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
-----------------------------------------------------------------------
   FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg:
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `ftp.desy.de' [141.34.1.2] in directory `/pub/faq/web/fweb'
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
  [Either as .texi, .dvi, .ps, .info or plain text file, with makefile]
 
   NOTE: you can now access a wealth of Literate Programming documents,
   including the FWEB FAQ, on the World Wide Web [WWW] at
         http://x4u.desy.de:80/
   If you dont know about WWW, but you are on the Internet, try
         telnet info.cern.ch
   from there, go to "HEP" and then to "DESY" where you'll find an
   entry for "Literate Programming".
-----------------------------------------------------------------------
 
From Joachim Fri Apr 9 20:02:17 +0100 1993
Date: Fri, 9 Apr 1993 20:02:17 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu (Literate Programming Discussion List)
Subject: LaTeX support for CWEB, alpha test
 
An alpha test version for the LaTeX support within CWEB is available
by anonymous ftp from
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/incoming/schrod/cweb
 
You should "cd" to this directory with one command, the subdirectory
schrod/ is not readable for you.
 
NOTE 1:
    For the usage of LaTeX in CWEB you need a patched version of
CWEAVE. This patched version is built upon CWEB V3.0-- and is
available in the same directory, please read the README file first.
This patched version is not intended to be used in a production
environment, it's just for testing the style.
    The changes will be folded in the CWEB 3.0 release; Silvio Levy
has them. (At least, I think so. ;-)
 
NOTE 2:
    CWEB V3.0beta introduces @*<n> where <n> is a hint about the
importance of this starred section (to be expressed by layout). This
is not yet supported by the LaTeX style, but will be RSN. Watch this
space for announcements. :-)
 
NOTE 3:
    Please read the README files and the supplied documentation (for
the style: 3 pages user manual and 38 (fullpage.sty) pages on the
implementation) before you send questions to me...
 
Enjoy,
 
	Joachim
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Kayvan Tue Apr 13 02:12 PDT 1993
Date: Tue, 13 Apr 93 02:12 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: litprog@SHSU.edu
Subject: Experiences with litprog so far
 
Whew... I just spent about a day and a half reading the entire litprog
archives. I figured it would be good if I were a bit more informed
before I started sending to this list.
 
I'm new to Literate Programming, though I've known about it for some
years now. Recently, I had the pleasure of writing a real-world
literate program for a client (and then an in-house tool to aid in a
{\it large} and nontrivial global change to a massive amount of 4GL
source code).
 
The first program that I wrote, \.{dbstrip}, took about two days to
write, and about an hour or two to find and fix the one (fingers
crossed \smiley) bug. I originally wrote it in CWEB 2.8 but switched over
to FWEB (for reasons I'll talk about later). The purpose of the
\.{dbstrip} program is to strip unwanted characters from STRING fields
in a Unify database.
 
I wrote this program using WEB mostly as an experiement to save time
and effort (now and later). Part of my task was to write a design
document, have it approved by my client, and then write the actual
program. Using Literate Programming, I was able to produce an early
version of the program/document which showed the essentials of my
design, have it approved by the client, and then go on to complete the
project (and have a beautifully typeset technical document as a side
effect which I then delivered along with the code).
 
It also made the task of coding {\it much} more fun. :-)
 
To continue my tale, I now had a working program of high quality,
produced in less time than it would take to create and debug a
conventional program. I was ecstatic... but... ;-)
 
Delivering the tangled code to my client proved a bit problematic.
CWEB's ctangle produced uncommented, unformatted, {\t unreadable} C
code.  My client was not happy with this. I ran the code through
indent and that was a bit more palatable, but the stripping of my
copious comments was still annoying.
 
At this time, I ran into FWEB, and since I was also looking for ANSI
C/C++ support, I decided to try using FWEB. I brought it up on my ESIX
system (with only a minor bug fix) using gcc-2.3.3. I converted my
\.{dbstrip} program from CWEB to FWEB, and found, much to my pleasant
surprise, that FWEB was much more customizable than CWEB.
 
As a side comment, John Krommes, the author of FWEB, has been very
helpful and responsive to Email and worked with me on finding
solutions to various problems.
 
Anyway, I regenerated the tangled code using ftangle, with the "-v"
command line option that tells ftangle to keep the comments, ran the
code through indent, and delivered the final code (along with the web
file and a pointer to ftangle) to my client who was happy with the
code and impressed by the documentation.
 
The saga doesn't end here. :-) Upon porting this simple program to the
RS6000, I ran into a problem and I'm wondering if anyone has seen
anything similar to this:
 
(*) The program works correctly if it is compiled without optimization,
    but seg-faults if it is compiled with optimization.
 
This is obviously a copmpiler optimizer bug, but I'm wondering if
using LitProg techniques might exacerbate these kinds of bugs. The
tangled code from my web source includes a couple of {\it large}
functions with lots of loops and control structures... A direct
consequence of using named sections somewhat in place of function
calls.
 
The program works perfectly on some other machines I've tested it on.
Has anyone else run into a compiler limit like this one because of
using litprog techniques? What did you do?
 
My second literate program was written in C++ using FWEB, producing a
few files and being split across several sources with an attendant
generic Makefile that I developed. It also ran perfectly the first
time (and I credit that to the care I took when writing it and that
the act of writing {\it about} what I was doing clarified my own
thinking).
 
This post is long enough as it is. I hope to contribue more to this
list and I am particularly interested in insights that people have
about using Object Oriented Design and Literate Programming.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Kayvan Wed Apr 14 03:31 PDT 1993
Date: Wed, 14 Apr 93 03:31 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: I'm hooked now!!
 
The problem I was talking about in my last (long) post, with my first
{\em real} literate program, was just solved!
 
While I was relaxing, reading my woven output, I spotted a subtle bug
that only showed up on the RS6000. I fixed this bug, made some
performance improvements while I was at it, and tested the RS6000
build. It worked!!!
 
I'm very happy with the fact that I used Literate Programming, since
similar bugs in non-literate programs have stumped me for days,
sometimes weeks. Having written the program in an {\em expository}
mode, I made it easier for {\em myself} to understand and debug what I
was doing!
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Vince Wed Apr 14 18:17:17 EDT 1993
Date: Wed, 14 Apr 93 18:17:17 EDT
From: Vince Mehringer <vince@eye.com>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Current View of LitProg
 
Here's where I stand in relation to Literate Programming at the
moment.  Set me straight if I'm wide of the mark on something.
In any case I'd like to hear other opinions on the subject.
 
Background:
    - software developer ~10 years
    - mostly C and C++, though some FORTRAN early on
      and some Lisp recently
    - last project involved more than 40 people and resulted
      in more than 2 million lines of C, C++, and Lisp
    - bought _Literate Programming_ when it first came out
      and have ruminated on the subject since then
 
Problems Suitable for LitProg:
 
    Navigation
 
    One thing I've seen on project after project is that it is
    difficult to focus on the appropriate level of the code.  The
    indexing and cross-referencing I've seen in LP examples is
    very encouraging.  But one must be able to change contexts
    _fast_!  Double-clicking on the reference and having it on
    the screen is the kind of speed that is needed.
 
    Documentation
 
    If the code and text are in separate files, forget it.  And
    the farther away they are from each other in the same file,
    the less likely they will stay in synch.  I know LP doesn't
    guarantee code and documentation synchronization, but at
    least it seems to present small chunks of both at the same
    time.  This "in your face" presentation of the documentation
    seems the best approach so far.
 
Difficulties with Current Tools:
 
    Formatting Language
 
    I'm a software developer -- not a typesetter, and for now I
    refuse to get sucked into the black hole that is document
    layout.  We have developed coding style guidelines to avoid
    questions of how far to indent, what declarations should
    look like, etc.  These questions can be answered once, and
    then productivity is increased.  I should _not_ have to deal
    with learning and coding in a formatting language.  This is
    not a knock against TeX or any other formatting language --
    they are extremely useful in the appropriate domain.  But to
    a software developer any formatting language (if one is used)
    should be completely transparent.
 
    Debugging
 
    Ideally this would be on the same document that the program
    was written.  At the very least it should be on unaltered
    code.  I haven't tried CNOWEB, FWEB, or many of the other
    tools mentioned here, but I am encouraged to read that they
    transfer code for compilation without making changes.
 
    Illustrations
 
    Should be included in a document without difficulty.  Right
    now generating illustrations for a document is difficult
    enough.  Merging them into a literate program is another
    challenge.
 
Bottom Line:
 
    The hyptext navigation ability rings 100% true with me.  Does
    a tool exist for moving gracefully through the code?  The
    problem of code and documentation getting out of synch gnaws
    away, but some improvements have been made.  But the lack of
    a tool which hides the formatting language is a real killer.
 
    For now I will encourage the evolution of Literate Programming,
    dream about what an ideal tool should do, and keep looking for
    a tool which comes close to the ideal.  Oh, and continue
    developing software as effectively as possible.
 
Vince Mehringer
vince@eye.com
 
P.S. Thanks to all at SHSU for maintaining this forum!
 
From Kayvan Wed Apr 14 17:15 PDT 1993
Date: Wed, 14 Apr 93 17:15 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: All these WEBS... Quick thoughts
 
I've probably gone overboard, but what the hell. I grabbed all the WEB
tools I could get my hands on. Being between projects does strange
things to me, especially when I have ``programming fever''.
 
I've got CWEB-2.8, FWEB-v130, c-no-web, and noweb installed. Here's my
quick thoughts on all these packages:
 
1. CWEB-2.8 is fairly good for non-ansi C (and Cameron Smith shows a
   way to use it for ANSI C by his KR-CW-sample). Fairly solid. Nice
   features. It's not easily configurable, and works easily only with
   TeX. It's a medium sized package.
 
2. FWEB-v130 is my current favorite. It handles C, C++, TeX, and a
   bunch of outdated programming languages that I almost don't believe
   people are still using. :-) It's nicely configurable. Among its
   features are a *large* user manual. Among its drawbacks is a
   *large* user manual. :-) Works with TeX or LaTeX. Large package.
   Lots of nice features. I've used it the most.
 
3. NOWEB. I like its simplicity. It's small and elegant. I'll probably
   use it for shell scripts, perl scrips, Makefiles, and other
   applications where literate programming would be good and I have no
   need for indexes or prettyprinting. It's a nice tool. Works with
   TeX or LaTeX (probably could change it to work with other
   formatters too).
 
4. C-no-web. Cute idea. I'm not sure if I will ever use it. I don't
   see it as "Literate Programming" since one of the basic ideas of
   litprog is the ability to organize your input code in any order you
   want (not tied to the order required by the compiler). I could see
   using c-no-web to enhance documentation of existing non-literate
   programs, though.
 
Thoughts, comments, anyone?
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From fulling@sarastro.math.tamu.edu Wed Apr 14 21:05:57 CDT 1993
Date: Wed, 14 Apr 93 21:05:57 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Current View of LitProg
 
Vince Mehringer <vince@eye.com> writes:
 
Difficulties with Current Tools:
 
    Formatting Language
 
    I'm a software developer -- not a typesetter, and for now I
    refuse to get sucked into the black hole that is document
    layout.  We have developed coding style guidelines to avoid
    questions of how far to indent, what declarations should
    look like, etc.  These questions can be answered once, and
    then productivity is increased.  I should _not_ have to deal
    with learning and coding in a formatting language.  This is
    not a knock against TeX or any other formatting language --
    they are extremely useful in the appropriate domain.  But to
    a software developer any formatting language (if one is used)
    should be completely transparent.
 
Fair enough, but let's not confuse two very different things.  GLOBAL
formatting -- the layout of paragraphs and larger units -- can indeed
be coded once and for all into macro files, and surely should be in any
organization where many people have to work on the same document (or
program).  Same for coding style.
 
However, the LOCAL TeX conventions for representing typeset mathematics
in ASCII are too valuable in literate programming to give up.  The
ability to produce readable formulas in the documentation is one of the
principal advantages of *WEB, and the basic symbols and control
sequences needed to do a minimal job of that are presumably as easy to
learn as the codes for any word processor that does an even remotely
comparable job with mathematics.  TeX users quickly get into the habit
of using TeX notation in their e-mail, for direct mathematical
communication with another human being through an ASCII medium that
will never be typeset; TeX is now so nearly universal in academic math
and physics that most people don't even bother to inquire whether the
mail recipient is literate in the language.  I think that this TeX
coding will soon be learned by every calculus student.
 
Of course, one can't produce perfect typeset output without a deeper
knowledge of TeX.  However, most people don't worry about polishing
until the final draft, after all matters of substance have been
settled; in the corporate context this task will presumably be handled
by a specialist.  Anal compulsives like me who insist on getting every
thinspace right in the first draft will have no objection to learning
TeX in depth.
 
					Steve Fulling
 
From Kayvan Wed Apr 14 20:19 PDT 1993
Date: Wed, 14 Apr 93 20:19 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Current View of LitProg
 
>>>>> "Vince" == Vince Mehringer <apple!eye.com!vince> writes:
 
Vince> Navigation
[...]
 
I use the GNU Emacs based web-mode, which allows me to do outlining
(hiding various levels of the input source), jumping to sections and
modules, use the web-generated index to jump to uses of identifiers or
modules, and a lot more.
 
Vince> Documentation
[...]
 
This is one of the *big* plusses of LitProg for me. My recent
experiences have made me totally convinced of LitProg's utility to me
*now* (without all the cool Hypertext/GUI advances that are probably
in the wings).
 
Vince> Difficulties with Current Tools:
Vince>
Vince> Formatting Language
 
Not all LitProg implementations use TeX. NOWEB and FWEB both use LaTeX
(which stands for Lazy-TeX, I think :-)
 
You don't need to use all the features of TeX to get beautifully
typeset programs out of a good LitProg tool.
 
Vince> I'm a software developer -- not a typesetter,
 
Capt'n, I can't change the laws of software development!! :-)
 
But seriously, I'm not a typesetter, or a student, or a researcher, or
a professor. :-) I'm a software developer working in the real world,
developing systems...
 
Vince> and for now I refuse to get sucked into the black hole that is
Vince> document layout.  We have developed coding style guidelines to
Vince> avoid questions of how far to indent, what declarations should
Vince> look like, etc.  These questions can be answered once, and then
Vince> productivity is increased.  I should _not_ have to deal with
Vince> learning and coding in a formatting language.  This is not a
Vince> knock against TeX or any other formatting language -- they are
Vince> extremely useful in the appropriate domain.  But to a software
Vince> developer any formatting language (if one is used) should be
Vince> completely transparent.
 
Sounds like you might want to take a serious look at Norman Ramsey's
NOWEB. It is simple and elegant, completely language independant,
doesn't reformat your code, and is very easy to change for other
formatters (The WEAVE process is a small shell script).
 
Vince> Debugging
[...]
 
NOWEB, CWEB, and FWEB all provide support for including "#line"
directives into the tangled program. FWEB also provides a breakpoint
capability which I found useful in doing web-based debugging. Any
compiler/debugger worth the bytes it is written on should be able to
use these #line directives to jump you to the WEB source.
 
Vince> Illustrations
[...]
 
If you relax your prohibitions against TeX and LaTeX, this is actaully
not too hard. There are various ways of including postscript in TeX
documents (my company letterhead is generated this way).
 
I agree with you, though: My fantasy would be of a good GUI tool that
allows you to paste graphics right into the WEB document as you are
writing it.
 
Vince> Bottom Line:
 
Vince> The hyptext navigation ability rings 100% true with me.  Does
Vince> a tool exist for moving gracefully through the code?  The
Vince> problem of code and documentation getting out of synch gnaws
Vince> away, but some improvements have been made.  But the lack of
Vince> a tool which hides the formatting language is a real killer.
 
The web-mode for GNU Emacs that I spoke about above does most of this.
I use it all the time. It's great.
 
Vince> For now I will encourage the evolution of Literate Programming,
Vince> dream about what an ideal tool should do, and keep looking for
Vince> a tool which comes close to the ideal.  Oh, and continue
Vince> developing software as effectively as possible.
 
I'm starting to believe that Literate Programming provides many
benefits *now*, so while I agree with your sentiment, I'm not going to
sit by the sidelines and watch it grow... I'm jumping right into the
middle of it.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From ae1181t@stnfor.ae.ge.com Thu Apr 15 10:33:14 -0400 1993
Date: Thu, 15 Apr 1993 10:33:14 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  All these WEBS... Quick thoughts
 
there are a couple of more :
CLIP:  language independent, multiple files may be produced from one
	input, The WEB part looks like comment in the language you are
	using, order not important, you need to use your favorite Word
	processor/typesetter.
FUNNELWEB: language independent, same as above but hooked into TeX
	some people have a working LaTeX version. sizable manual and
	programmers' manual.
NUWEB: same as above but works with LaTeX. Couple of pages of manual.
	Program itself written in NUWEB. You get indices for the
	macros and files produced (just like in FWEB).
All of the above does not pretty print your code and does not produce
	an index for the words used (other real WEB's do!). They are
	language independent. If you want code to be pretty printed
	and use different languages than (c,c++,fortran, TeX) the only
	option I know is to use SPIDER and produce your own WEB.
I personally use NUWEB nowdays for everything. It is a small but powerful
program.
Osman.
 
From marcus@x4u.desy.de Thu Apr 15 19:06:28 +0200 1993
Date: Thu, 15 Apr 93 19:06:28 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Current View of LitProg
 
Thanks both to Vince and Kayvan Sylvan for their nice reports--keep
those keynotes coming, folks. I think communicating among LitProgrammers
on personal experiences cannot be overestimated.
 
>>>>> On Wed, 14 Apr 93 18:17:17 EDT, Vince Mehringer <vince@eye.com> said:
|> Bottom Line:
 
|>     The hyptext navigation ability rings 100% true with me.  Does
|>     a tool exist for moving gracefully through the code?
 
This topic has not been beaten to death yet, but seems to come up
regularly--for the sake of completeness: I was told by Tim Berners-Lee
(who founded the World Wide Web initiative) that the www hypertext
line mode browser (version 2.0) is capable of "Literate Programming"
as well. This is part of his original message:
 
	BTW ... did you know you can now literate program in
	HTML, by using (the latest)
 
	www -to text/x-c xxx.html > xxx.h
 
	to reformat the document as C, with everything except PRE sections
	commented out? 	I used txt2html.sed to make
	the original .html, then I used the nextstep editor to format the
	file nicely.
	"text/x-c" is an experimental (x-) MIME content type.
 	The "-to" and "-from" options take (from a limited set) a MIME
	content type value. You need version 2.0 or later.
	It's not documented yet. See
	http://info.cern.ch/hypertext/WWW/Library/Implementation/HTFormat.html
	for an example header file.
 
I dont have www 2.0, and no time to bring it up now, but maybe someone
who's experimenting with HyperText [HTML] wants to give it a try. All
the source is (on the Web and) on info.cern.ch in pub/www.
 
Note: the NeXTStep editor is not essential. There is also an Emacs mode
to format HTML documents nicely.
 
I'll put this (and Stephen Cross' earlier remark on using FrameMaker
into the LitProg info page on the World Wide Web (see below).
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
-----------------------------------------------------------------------
   FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg:
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `ftp.desy.de' [141.34.1.2] in directory `/pub/faq/web/fweb'
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
  [Either as .texi, .dvi, .ps, .info or plain text file, makefile
   included.]
 
   NEW: you can now access a wealth of Literate Programming documents,
   including the FWEB FAQ, on the World Wide Web [WWW] at
         http://x4u.desy.de:80/
   If you dont know about WWW, but you are on the Internet, try
         telnet info.cern.ch
   from there, go to "HEP" and then to "DESY" where you'll find an
   entry for "Literate Programming".
-----------------------------------------------------------------------
 
From leew@cs.utexas.edu Thu Apr 15 12:18:32 -0500 1993
Date: Thu, 15 Apr 1993 12:18:32 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Noweb and LaTeX
 
Adding my bit to the Noweb/FunnelWeb/plainTeX/LaTeX discussion:
 
I use CWEB for my C/C++ code (currently a Spidery WEB version, but the new
Levy/Knuth version should be out very soon -- it may be out already for all I
know; I just got back from vacation, and am only halfway through my accumulated
e-mail).  I prefer the nicely typeset code a la Algol-60 (sorry, Norman).
However, I also prefer LaTeX to plain TeX for most work, and Spidery WEBs
are not appropriate for many languages, so I use Noweb with LaTeX for
programs in these languages.  When I saw FunnelWeb used in an article in a
recent SIGPLAN Notices, I was very impressed and was planning on trying it,
but now that I know it doesn't support LaTeX, I think I'll stick to Noweb.
 
		-- Lee
 
From marcus@x4u.desy.de Thu Apr 15 19:28:45 +0200 1993
Date: Thu, 15 Apr 93 19:28:45 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Experiences with litprog so far
 
>>>>> On Tue, 13 Apr 93 02:12 PDT, Kayvan Sylvan <kayvan@satyr.Sylvan.COM> said:
|> My second literate program was written in C++ using FWEB, producing a
|> few files and being split across several sources with an attendant
|> generic Makefile that I developed.
 
Did you solve the problem (outlined in the FWEB-FAQ in Question [29])
of presenting a _nice_ table of contents and a combined index which
distinguishes between entries from different source files?
  The example I have in mind is Cameron Smith's hack of cwebmac.sty
for the CWEB-KR-sample files. I know that John Krommes has put it in
his long list of future enhancements (but it isnt contained in v1.30
as far as I can see).
 
On Kayvan's list of tools: should merge with David's general FAQ
(still in preparation). I only know CWEB (v3.0-beta, which I have
found to be faultless so far) and FWEB (v1.30 is beta but John keeps
eliminating bugs and it works fine for me). I agree with his opinions.
 
  I have CWEB,FWEB,NOWEB documents on the LitProg page for the World
Wide Web. Somebody volunteers to write a few lines (HyperText ?) for
C-No-Web along what I put up for the other LitProg tools? This mainly
means one or more links to first-hand information and possibly some
preprocessed examples.
 
BTW, I plan to update the FAQ for FWEB v1.30 not later than next month.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
-----------------------------------------------------------------------
   FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg:
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `ftp.desy.de' [141.34.1.2] in directory `/pub/faq/web/fweb'
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
  [Either as .texi, .dvi, .ps, .info or plain text file, makefile
   included.]
 
   NEW: you can now access a wealth of Literate Programming documents,
   including the FWEB FAQ, on the World Wide Web [WWW] at
         http://x4u.desy.de:80/
   If you dont know about WWW, but you are on the Internet, try
         telnet info.cern.ch
   from there, go to "HEP" and then to "DESY" where you'll find an
   entry for "Literate Programming".
-----------------------------------------------------------------------
 
From Joachim Thu Apr 15 19:17:52 +0100 1993
Date: Thu, 15 Apr 1993 19:17:52 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu (Literate Programming discussion)
Subject: Literate Programming Archive, preliminary announcement
 
Since the question on available WEBs came up recently on this list...
 
I'm in the process to build the Literate Programming Archive. It's
accessible by anonymous ftp at
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming
 
This archive features both WEB systems and Tools for the aid of
Literate Programming. All systems provided there are kept up to date
automatically.
    Please note, that the directory is _not_ a subtree of the TeX
directory tree. IMNSHO it's time that Literate Programming steps out
of TeX's shadow into the realm of programming support.
 
The archive isn't complete yet. Missing are Papers and other
documentation on Literate Programming, the WEB mode of Mark Motl and
Bart Childs, web_view, Sewell's MWEB, Sewell's webmerge, CLiP, some
systems specific for certain platforms and only available as
executables. (This list was not in any particular order, I just scetched
a file in my notebook.)
    In addition, a README file which explains the archive structure
and an OVERVIEW file which gives some hints on the highlights of the
archive is not (yet) available.
 
But I thought it might be of interest for you nevertheless. (Because
of a long illness I wasn't able to finish the archive setup and now
other (real ;-) work with higher priorities is to be done first.)
 
Enjoy.
 
    Joachim
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From ecprest@pocorvares.er.usgs.GOV Thu Apr 15 18:16:08 EDT 1993
Date: Thu, 15 Apr 93 18:16:08 EDT
From: ecprest@pocorvares.er.usgs.GOV (Eric Prestemon)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: (none)
 
I have a question about a possible feature for a weave, that I think
would be very useful.  I would be interested to hear comments on
whether you think it's a good idea, where the problems lie, and even
how happy you'll be when I write it. Or feel free to tell me it's
useless.
 
Being stuck on a PC with no printer, I can't just print out my woven
code. Also, we intend to ship a library with source, and we want to
include the source in the most useful form possible. But we don't
want to ship .dvi or postscript files.
 
My idea, then, is to have a weave which produces the following:
   A texinfo or info file, such as those used for the GNU project
documentation. The texinfo file is preferred, because it has the added
benefit of being printable with TeX, with fairly nice output. Indexing
and table of contents come about from the texinfo file.  On-line
info-viewers would let you follow references to where called modules
were defined, variables defined, etc. I think this has potential.
 
Of course, this would be ascii-based, and math-mode wouldn't be usable
(although it *is* possible to have the printed version of the texinfo
file contain TeX constructs.)
 
I had thought about suggesting producing an html file, which could be read
by a world-wide web browser, but I'm not sure how widely this format is
used. It would be an excellent format for on-line woven output.
 
Well, that's the general concept. Other issues, such as whethere this
should/could be integrated into a current *weave, or whether it should
be separate need to be addressed, also.
 
Any thoughts?
-Eric
 
From George Thu Apr 15 17:42:58 CDT 1993
Date: Thu, 15 Apr 1993 17:42:58 CDT
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: RE: Literate Programming Archive, preliminary announcement
 
On Thu, 15 Apr 1993 19:17:52 +0100 (MESZ),
Joachim Schrod <schrod@iti.informatik.th-darmstadt.de> posted:
 
> I'm in the process to build the Literate Programming Archive. It's
> accessible by anonymous ftp at
>
>        ftp.th-darmstadt.de [130.83.55.75]
>        directory pub/programming/literate-programming
>
> This archive features both WEB systems and Tools for the aid of Literate
> Programming. All systems provided there are kept up to date automatically.
>
> Please note, that the directory is _not_ a subtree of the TeX directory
> tree. IMNSHO it's time that Literate Programming steps out of TeX's shadow
> into the realm of programming support.
 
I have seen what Joachim is setting up had had been planning on mirroring
this into the web archive area on the TeX archive network linking together
Aston, Stuttgart, and SHSU.  If the concensus is to put Literate
Programming be within its own area, it's easily enough accomplished.
 
Will get the mirror set up some time soon (probably need a few private
messages between Joachim and me to look at some scheduling issues).
 
--George
 
From leew@cs.utexas.edu Thu Apr 15 18:32:04 -0500 1993
Date: Thu, 15 Apr 1993 18:32:04 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: (none)
 
Eric Prestemon writes:
 
  > My idea, then, is to have a weave which produces the following:
  >    A texinfo or info file, such as those used for the GNU project
  > documentation. The texinfo file is preferred, because it has the added
  > benefit of being printable with TeX, with fairly nice output. Indexing
  > and table of contents come about from the texinfo file.  On-line
  > info-viewers would let you follow references to where called modules
  > were defined, variables defined, etc. I think this has potential.
 
I don't see why this couldn't be done.  It should be fairly easy (sic) to
write a filter for Noweb that takes the output from markup and produces
texinfo instead of TeX or LaTeX output.  It should also be possible to do
this for the various prettyprinting WEBs, although it will require a lot
more messing around with the code.
 
		 -- Lee
 
From plyon@emx.cc.utexas.edu Sun Apr 18 17:09:00 -0500 1993
Date: Sun, 18 Apr 93 17:09:00 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Future Developments
 
In response to a previous post of mine, Tony Coates writes:
 
>	Disheartened?  This intrigues me.  After all, few of us have the
> foresight to really know what is going to be the way of the future.
 
To be sure, but then I was not thinking about the next few years so
much as I was thinking about the next few months, or perhaps a year or
so.  It seems unlikely there will be but one "way of the future", and
in any case I do not expect that literate programming will ever be
more than a minority pursuit (see below).
 
> I for one don't see that improving the tools used by an elite few (and
> we are, let's face it, a minority) should take precedence over
> creating tools that could be more acceptable to the programming
> community at large.  Fewer and fewer people use command lines any
> more, and Emacs is still often only for the cogniscenti, wonderful as
> it is.  Many of my colleagues write all their scientific papers in
> Microsoft Word; if I was to try to convince them to use Literate
> Programming tools, I would have no chance with an Emacs/TeX
> combination.
 
The urgency of spreading literate programming to the programming
community at large escapes me. For one thing, one would have to foster
better writing skills while one was at it. This pessimism on my part
may be parochial: some of the courses I teach here are courses "with a
substantial writing component", as it is put hereabouts. The
University wisely requires that all its undergraduates take such
courses in addition to the basic English composition course; judging
by the overall quality of the work I receive, the undergraduates are
much in need of practice and assistance. At that, the students I see
are mostly Liberal Arts students, and 3rd and 4th year ones to boot.
 
No doubt there is a significant non-overlap of the set of programmers
possessed of decent writing skills with the set of those prepared to
cope with TeX or LaTeX. Your colleagues may well be instances to the
point. But then, one of the improvements I would hope for in the
existing tools would be a better interface to TeX or LaTeX.  Surely we
can reach some agreement among us about what is desirable along these
lines? The other thing needed to bridge the gap, so it seems to me, is
a decent online help system for TeX or LaTeX, the which could be
extended to include Web commands. Embedded command formatting would
not be so difficult to deal with were one not constantly forgetting
which command sequence does what. A main advantage of the GUI-based
word processors is that they reduce the need for having the formatting
manual (the TeXbook, in my case) by one's side.
 
As for the gap between the text editors embedded the GUI-based word
processors with Emacs, surely the various X windows versions of Emacs
can serve as a bridge? Having posed this, I should note that I have
never actually used Epoch or Lucid Emacs.  The Emacs port to OS/2 2.0
is what I have to work with, and a Presentation Manager version of
that will not soon be available, alas.  [Emacs Version 19 will be a
precondition for such, but one grows weary waiting for that...]
Again, though, it seems to me that the major advantage of the
GUI-based editors is the menu/dialog box system, which reduces the
load on one's memory. Emacs could surely use some of that! (The Emacs
18 help system is clumsy at best; again, I mostly find myself reaching
for the printed manual.)
 
But I suppose this is mostly by-the-by; even with such improvements as
as these, I doubt you would be able to wean your colleagues away from
what they are using to consider tools that require Emacs plus TeX, or
some such combination. But then I wonder, what is so terribly wrong
with this state-of-affairs? Is it that you must use or maintain code
that they write? Or that they expect to use code that you write?
Trying to use literate programming tools on a multi-programmer project
when none of the others are, will, I agree, pose a significant
problem.
 
> I might have a small chance with a Word for Windows package; who
> knows, using the coming abilities of the OLE 2.0 (Object Linking
> Environment) one could create a hypertext-style environment that might
> be much more attractive than anything currently seen under
> UNIX/TeX/Emacs (at least for now, we'll see what Sun can offer in
> terms of objects and such in the future).
 
I am unfamiliar with OLE 2.0. But I wonder what the impact of
hypertext features would be on tangling and weaving. The hypertext
model is, after all, a general graph. The compiler and the formatter,
however, expect linear text in a fairly rigid order. What one could
do, I suspect, is to include the hypertext links in the web source to
make navigation among the parts of it easier when writing, but leave
the undelying text in the proper linear order, then have the tangle
and weave processors strip the links out before handing the results on
to the compiler and formatter.
 
> OK, so the argument is that maybe there are too few of us to chase
> all of these goals at once.  But then, maybe there are too few of us
> to yet come to a consensus on what is best.  We will see.
 
I think that there are enough of us to see what is better, if not what
is best :-) We all realize, for example, that user configurable
pretty-printing would be desirable in Cweb, Fweb, and the like. And
anyone who has stared at the code for Cweb, Fweb, and Spiderweb,
should realize that the existing code is not readily extended. Perhaps
the first thing that should be done with Cweb 3.0, when it is
released, is to rewrite it in C++, with appropriate care taken to do a
proper ``object-oriented'' job of it :-)
 
Ciao,
 
Paul Lyon
 
From fulling@sarastro.math.tamu.edu Sun Apr 18 20:28:56 CDT 1993
Date: Sun, 18 Apr 93 20:28:56 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Future Developments
 
plyon@emx.cc.utexas.edu (Paul Lyon) writes:
 
>The urgency of spreading literate programming to the programming
>community at large escapes me. For one thing, one would have to foster
>better writing skills while one was at it. This pessimism on my part
>may be parochial: some of the courses I teach here are courses "with a
>substantial writing component", as it is put hereabouts. The
>University wisely requires that all its undergraduates take such
>courses in addition to the basic English composition course; judging
>by the overall quality of the work I receive, the undergraduates are
>much in need of practice and assistance. At that, the students I see
>are mostly Liberal Arts students, and 3rd and 4th year ones to boot.
>
>No doubt there is a significant non-overlap of the set of programmers
>possessed of decent writing skills with the set of those prepared to
>cope with TeX or LaTeX.
 
All the more reasons why all students should be introduced to literate
programming and to TeX as early as possible!  At present they see a
total disconnect between "verbal" courses and "mathematical" courses
(and activities and occupations).  They also see precious little
connection between computing and other technical courses (e.g.,
calculus).  It should all be a seamless web.
 
Maybe it's parochial optimism, but I have the impression that when you
force them to TRY, most students produce much better written work than
their usual output.
 
				      S. A. Fulling
 
From norman@bellcore.com Mon Apr 19 15:29:07 -0400 1993
Date: Mon, 19 Apr 93 15:29:07 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: spiderweb status
 
copyright fixed
trying to iron out archive problems (as per bcc) so i can make an announcement.
 
N
 
From norman@bellcore.com Mon Apr 19 16:07:37 -0400 1993
Date: Mon, 19 Apr 93 16:07:37 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: TeXhax@cs.washington.edu, litprog@shsu.edu
Subject: Spidery WEB copyright restrictions lifted
 
I am pleased to announce that at long last the restrictive copyright
on Spidery WEB has been eased.  Spidery WEB may now be used freely for
any purpose, including writing software for profit.  I am also pleased
to announce that I am no longer supporting Spidery WEB.  (True de
facto for some time, but now true de jure.)  Bug fixes and bug reports
should be sent to the copyright holders, ORA Corporation, E-mail
address spider-bugs@oracorp.com.  The location at which Spidery WEB is
stored has also changed.  Spidery WEB is available by anonymous ftp
from pip.shsu.edu:tex-archive/web/spiderweb.  This location is
mirrored at other sites as part of the Comprehensive Tex Archive
Network.
 
Norman Ramsey
 
From leew@cs.utexas.edu Mon Apr 19 15:13:12 -0500 1993
Date: Mon, 19 Apr 1993 15:13:12 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Future Developments
 
Paul Lyon writes:
 
  > The urgency of spreading literate programming to the programming
  > community at large escapes me. For one thing, one would have to foster
  > better writing skills while one was at it. This pessimism on my part
  > may be parochial: some of the courses I teach here are courses "with a
  > substantial writing component", as it is put hereabouts. The
  > University wisely requires that all its undergraduates take such
  > courses in addition to the basic English composition course; judging
  > by the overall quality of the work I receive, the undergraduates are
  > much in need of practice and assistance. At that, the students I see
  > are mostly Liberal Arts students, and 3rd and 4th year ones to boot.
 
I find the same situation with my students, although I teach mostly CS
students.  We also have ``writing emphasis'' courses (I'm trying to develop
one in Literate Programming, e'en as we speak).  One of the things I've
found with LP, though, is that a poorly written literate program seems to
be easier to maintain than an average quality non-literate one.  Admittedly,
all my evidence is anecdotal, and I have yet to see a really horrible
literate program (perhaps once I've got a bunch of students trying it?),
but maintenance is such an important part (perhaps the most important part)
of CS, that LP seems worth pursuing for that reason alone.
 
  > No doubt there is a significant non-overlap of the set of programmers
  > possessed of decent writing skills with the set of those prepared to
  > cope with TeX or LaTeX. Your colleagues may well be instances to the
  > point. But then, one of the improvements I would hope for in the
  > existing tools would be a better interface to TeX or LaTeX.  Surely we
  > can reach some agreement among us about what is desirable along these
  > lines? The other thing needed to bridge the gap, so it seems to me, is
  > a decent online help system for TeX or LaTeX, the which could be
  > extended to include Web commands. Embedded command formatting would
  > not be so difficult to deal with were one not constantly forgetting
  > which command sequence does what. A main advantage of the GUI-based
  > word processors is that they reduce the need for having the formatting
  > manual (the TeXbook, in my case) by one's side.
 
Agreed, although I think that ``agreement...about what is desirable...'' is
one of those things that never happens, for various reasons.  Corporations
want standards, but they want everyone else to accept their standard rather
than accept someone else's (NeXT being a notable exception) -- witness the
current PC-database-standard wars between Microsoft and Borland (and the
various companies behind each one), not to mention the upcoming operating
system war.  Regarding ``embedded command formatting,'' I've noticed that
everyone who uses WinWord around here runs it with all of the formatting
symbols (paragraph marks, dots for spaces, etc.) displayed.  If they don't,
WinWord tends to do strange things when they delete invisible
``characters.''  Is this WYSIWYG or embedded commands?
 
One problem that surfaces with WYSIWYG editors, but not
text-editor/embedded-command systems is one of tools.  Most WYSIWYG
editors have undocumented (usually binary) file formats, so we can't rely
on the many text-based tools that have been developed (e.g. most everything
in UNIX).  We have to rely on the manufacturers to supply new tools, or
work out the file format (ugh!) and make our own.  One of the things I like
about the various WEB systems (and TeX as well) is that they are maintained
by people who actually use them on a regular basis, which is _not_ true for
(I would venture to say) most commercial software.
 
  > As for the gap between the text editors embedded the GUI-based word
  > processors with Emacs, surely the various X windows versions of Emacs
  > can serve as a bridge? Having posed this, I should note that I have
  > never actually used Epoch or Lucid Emacs.  The Emacs port to OS/2 2.0
  > is what I have to work with, and a Presentation Manager version of
  > that will not soon be available, alas.  [Emacs Version 19 will be a
  > precondition for such, but one grows weary waiting for that...]
  > Again, though, it seems to me that the major advantage of the
  > GUI-based editors is the menu/dialog box system, which reduces the
  > load on one's memory. Emacs could surely use some of that! (The Emacs
  > 18 help system is clumsy at best; again, I mostly find myself reaching
  > for the printed manual.)
 
I work with MS-Windows rather than OS/2, but I echo Paul's wish for a
Presentation Manager (Windows in my case) version of Emacs.  I've tried
the Micro Emacs Windows port, and while it's really good, there are a few
things (e.g., not highlighting mouse-selected text) that make it difficult
to use with any efficiency.
 
  > But I suppose this is mostly by-the-by; even with such improvements as
  > as these, I doubt you would be able to wean your colleagues away from
  > what they are using to consider tools that require Emacs plus TeX, or
  > some such combination. But then I wonder, what is so terribly wrong
  > with this state-of-affairs? Is it that you must use or maintain code
  > that they write? Or that they expect to use code that you write?
  > Trying to use literate programming tools on a multi-programmer project
  > when none of the others are, will, I agree, pose a significant
  > problem.
 
Emacs plus TeX, of course, gives you more control than does a WYSIWYG word
processor, but then again, most people don't seem to want that kind of
control.  I reckon Paul's right, here, too.
 
  > I think that there are enough of us to see what is better, if not what
  > is best :-) We all realize, for example, that user configurable
  > pretty-printing would be desirable in Cweb, Fweb, and the like. And
  > anyone who has stared at the code for Cweb, Fweb, and Spiderweb,
  > should realize that the existing code is not readily extended...
 
I kind of take exception to this statement (in a nice way, of course :-)).
While I haven't looked at the code for Fweb, I _have_ worked with both CWEB
and Spidery WEB, and was quite astonished at how easy they were to
understand and modify.  I had to fix several bugs before I could CWEB
working on my PC (all fixed now in the forthcoming 3.0 release), and have
made several major extensions to my copy of Spidery WEB.  All of these were
surprisingly easy, and did not break the existing code.
 
		-- Lee
 
From purtill@ccr-p.ida.org Tue Apr 20 10:23:59 EDT 1993
Date: Tue, 20 Apr 93 10:23:59 EDT
From: purtill@ccr-p.ida.org (Mark Purtill)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Future Developments
 
> Agreed, although I think that ``agreement...about what is desirable...'' is
> one of those things that never happens, for various reasons.  Corporations
> want standards, but they want everyone else to accept their standard rather
> than accept someone else's (NeXT being a notable exception)
	Sorry, have I missed a NeXT announcement of some sort?  Last
time I looked, NeXT was hardly an exception: Display PostScript rather
than standard X11, Objective C rather than standard C++.  True,
they're porting this non-standard software to a standard CPU (i486),
but not to one of the standard OSs, DOS, Windows, OS/2, Linux :-), but
as a new, non-standard OS.
	Or do you mean that NeXT is an exception to "corporations want
standards"?  That I'd believe.
 
^.-.^ Mark Purtill, purtill@ccr-p.ida.org;  UUCP: uunet!idacrd!purtill
((")) \@_: IDA/CCR-P, Thanet Road, Princeton NJ 08540; (609) 924-4600.
 
From leew@cs.utexas.edu Tue Apr 20 14:44:01 -0500 1993
Date: Tue, 20 Apr 1993 14:44:01 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Future Developments
 
Mark Purtill writes (in reply to a comment of mine):
 
Me:
 > > Agreed, although I think that ``agreement...about what is desirable...'' is
 > > one of those things that never happens, for various reasons.  Corporations
 > > want standards, but they want everyone else to accept their standard rather
 > > than accept someone else's (NeXT being a notable exception)
Mark:
 > 	Sorry, have I missed a NeXT announcement of some sort?  Last
 > time I looked, NeXT was hardly an exception: Display PostScript rather
 > than standard X11, Objective C rather than standard C++.  True,
 > they're porting this non-standard software to a standard CPU (i486),
 > but not to one of the standard OSs, DOS, Windows, OS/2, Linux :-), but
 > as a new, non-standard OS.
 > 	Or do you mean that NeXT is an exception to "corporations want
 > standards"?  That I'd believe.
 
What I meant was that, rather than invent their own ``standards,'' the
NeXT people looked around and said, ``What's already out there that we
can adopt as a standard?''  They decided (rightly or wrongly, possibly
both) on Unix as the operating system, PostScript as the display
language, and Objective C as a systems language.  There's no way of
knowing for sure but I believe their reasons were something like:
 
	1.  Unix because, let's face it, there isn't any other
	operating system that is implemented on a large number of
	different platforms.
 
	2.  Display Postscript so that they could use the same
	graphics language for printer and screen output.  X-Windows is
	lovely, but it would probably be a lot tougher to build an
	X11 printer than it was to build a PostScript video display.
 
	3.  At the time the NeXT came out, Objective C and C++ were
	pretty much running neck and neck as regards which language
	was C's ``legitimate object-oriented heir.''  C++'s current
	popularity seems to be as much from media attention as
	anything else, but the choice was not clear cut at the time.
	NeXT flipped a coin, and backed the wrong horse, although the
	decision to go with an object-oriented descendant of C
	accurately predicted the current trend.  [Actually, Objective-C
	still has its adherents.  Baby duck syndrome aside, whether
	you prefer Objective-C or C++ depends mostly on whether you
	come from the Smalltalk or the Simula school of
	object-oriented programming, the former advocating type
	checking at run-time, the latter, at compile time.  Most of us
	have strong opinions on this issue, but this forum really
	isn't the place to get involved in that religious war -- we
	have enough of our own.]
 
The main point I was railing at was the NIH (Not Invented Here)
problem that is rampant in our industry.  I chose NeXT as an example
because all of their choices involved ``standards'' developed
elsewhere that were already (somewhat) widely in use.  I apologize for
not making myself clearer the first time.
 
		 -- Lee
 
From bart@lanczos Tue Apr 20 15:54:17 -0500 1993
Date: Tue, 20 Apr 1993 15:54:17 -0500
From: bart@lanczos (Bart Childs)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Re: Future Developments
 
Lee W's comments are well founded.  He mentions anecdotal evidence.  Has anyone
done any careful measurements of this type?  I keep hoping to
find a graduate student who will want to but one really needs
funding to be able to support controlled studies with parallel
control populations...
 
Lee is a bit more optimistic about the file formats of WYSIWYG
editors.  We have worked on conversion programs from various
editor formats to TeX (or LaTeX).  It is not correct to call
them undocumented; the documentation is often out of date
(as most seems to be) or more often just nearly impossible to
find.  His sense was correct, but the biggest problem we found
was that the owner RESERVES THE RIGHT TO CHANGE IT AT ANY TIME
WITH NO NOTICE.  Indeed, the worst case implied by such a statement
has been done and only after you install the new version do you
learn that the binary format has changed.
 
Have you ever used WORD to wander around between DOS, MACs, and
NeXTs?  Even using RTF you don't have a panacea of portability.
Knuth said one of his design goals for TeX was that a real
``archive'' would be possible.  TeX written more than 10 years
ago still runs.  (It has been extended but not really changed.)
 
I long ago quit trying the evangelist business.  I don't try
to convince people that they should use TeX instead of a WP.
Most of them do a more than adequate job on memoranda, ...
Human nature still dominates and it is rare that I accept
statements of the nature that ``(any) WP does a good job of
formatting a document with mathematics (or a large number of
othere difficult items).''  Granted a lot of people say nobody
complained ...  The majority of the customers at MacDonalds
don't complain but they also don't try to convince others that
it is gourmet food ...
 
My compliments to Lee, Paul, and others for a really good set
of comments.
 
Bart Childs
 
From Paul Tue Apr 20 18:14:48 -0400 1993
Date: Tue, 20 Apr 1993 18:14:48 -0400
From: Paul Prescod <papresco@undergrad.math.uwaterloo.ca>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Future Developments
 
> The main point I was railing at was the NIH (Not Invented Here)
> problem that is rampant in our industry.  I chose NeXT as an example
> because all of their choices involved ``standards'' developed
> elsewhere that were already (somewhat) widely in use.  I apologize for
> not making myself clearer the first time.
 
Care to explain NeXTMail?  And what about X?  I get the impression that
NeXT Corp. would not add X to NeXTStep even if you programmed it up for them.
What they have is better, so what already exists is irrelevant!  Even if
they could work well together.
 
I wonder how standard their Unix implementation is too.
 
From John Wed Apr 21 09:28:10 +0100 1993
Date: Wed, 21 Apr 1993 09:28:10 +0100 (BST)
From: "John K Nicoll" <jkn@ohm.york.ac.uk>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: beginner seeks module decomposition advice
 
Well, after reading the LitProg mailings for a while now, I
got around to getting hold of WEB (FWEB, in fact, for my PC)
and trying things in anger. I'm at the stage where I can
convert/write a program (in C/C++) in a `modular' form, understand
the error messages, and generate output files.
 
What has so far taken me the longest time to sort out
is the `art' of decomposing into modules. The FWEB (and other, as
far as I can see) manuals are silent on this issue - perhaps due
to its FORTRAN background. I haven't got a feeling yet for how
to best arrange things between modules and functions,
and would appreciate advice from more seasoned WEBers on this issue.
An example of code written in C/C++ might be useful (perhaps in the
FAQ - which also seems silent on the `art').
 
Thanks for any help in advance.
 
	john nicoll
 
From marcus@x4u.desy.de Wed Apr 21 12:40:03 +0200 1993
Date: Wed, 21 Apr 93 12:40:03 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: re: beginner seeks module decomposition advice
 
>>>>> On Wed, 21 Apr 1993 09:28:10 +0100 (BST), "John K Nicoll" <jkn@ohm.york.ac.uk> said:
 
|> What has so far taken me the longest time to sort out
|> is the `art' of decomposing into modules. The FWEB (and other, as
|> far as I can see) manuals are silent on this issue - perhaps due
|> to its FORTRAN background.
 
The fact that it's linked to FORTRAN by name is somewhat unfortunate.
IMO, the reason why advice of that sort is lacking is because arrangement
of functions, modules and such rather seem to be a matter of personal
style.  I guess you will have to spent some time to find the way of
decomposing which suits you best [this statement is restricted below].
 
  I remember an early discussion on this list on "where to put the main
program", and another more recent one concerning the question of
whether to put more than one @<section name@>= entries into one
section/module [the nice summary by Steve Avery is in the LitProg archive,
 
From marcus@x4u.desy.de Wed Apr 21 12:40:03 +0200 1993
Date: Wed, 21 Apr 93 12:40:03 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: re: beginner seeks module decomposition advice
 
|> An example of code written in C/C++ might be useful (perhaps in the
|> FAQ - which also seems silent on the `art').
 
As for the FWEB FAQ, I'll try to improve on that in the upcoming issue
(John Krommes [JAK] does the checking for the final draft of the FAQ,
and he may have to say something worthwile, too). There is already a
remark on "multiple source files", though. This is on JAK's list of
future improvements.
 
  Some (rather silly) C++ examples are at ftp.desy.de in directory
pub/web/fweb -- a longer one is preprocessed and can be accessed on
the World Wide Web (see below). I am working on a C++ library which
will provide a fairly good example, too , but it won't be finished
before this summer.
 
  There are already very useful examples available as part of the
FWEB distribution:  The choice of C, C++ or Fortran should not be an
issue, IMO. The layout of your literate programs should rather follow
general guidelines as sufficiently described in various articles and
manuals. These imaginary 'guidelines' aren't just words: look into
the source code of the CWEB and FWEB releases. Probably Levy/DEK have
put parts of common.w into the User's Manual for this reason.
 
  Altogether, in _my_ programs, the decomposition does not change
essentially from one language to another.
  But again, I _do_ have a Fortran background, so maybe I'm missing the
point here. And I wouldnt claim to do an 'art', either.
 
Some comments on this last point by people with another background ?
 
	Hope that helps,
	Marcus
 
-----------------------------------------------------------------------
   FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg:
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `ftp.desy.de' [141.34.1.2] in directory `/pub/faq/web/fweb'
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]',
  [Either as .texi, .dvi, .ps, .info or plain text file, makefile
   included.]
 
   NOTE: you can now access a wealth of Literate Programming documents,
   including the FWEB FAQ, on the World Wide Web [WWW] at
         http://x4u.desy.de:80/
   If you dont know about WWW, but you are on the Internet, try
         telnet info.cern.ch
   from there, go to "HEP" and then to "DESY" where you'll find an
   entry for "Literate Programming".
-----------------------------------------------------------------------
 
From fulling@sarastro.math.tamu.edu Wed Apr 21 10:05:42 CDT 1993
Date: Wed, 21 Apr 93 10:05:42 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  beginner seeks module decomposition advice
 
John K Nicoll <jkn@ohm.york.ac.uk> writes:
 
>What has so far taken me the longest time to sort out
>is the `art' of decomposing into modules. The FWEB (and other, as
>far as I can see) manuals are silent on this issue - perhaps due
>to its FORTRAN background. I haven't got a feeling yet for how
>to best arrange things between modules and functions,
>and would appreciate advice from more seasoned WEBers on this issue.
>An example of code written in C/C++ might be useful (perhaps in the
>FAQ - which also seems silent on the `art').
 
Two books that contain discussions of this issue and example code:
 
1) Knuth's reprint book, "Literate Programming" (published at Stanford
but marketed (also) by the University of Chicago Press).
 
2) Wayne Sewell, "Weaving a Program" (Van Nostrand, available from TeX
Users Group).
 
The 3 programs in chapters 4-6 of Knuth's book are worth studying.  You
may not agree with all of Knuth's tastes and design decisions (I
don't), but as a "strict construction of the intent of the founding
fathers" they obviously can't be beat.  Original references:  Computer
Journal 27 ('84); Communications of the ACM 29 (May and June '86).
 
Unfortunately, most of the published model programs are in Pascal.
More attested C and C++ models are badly needed.  Several sample C
programs are distributed with CWEB, and there is another one in the
last appendix of Sewell's book.  Sewell discusses modularization
(specifically, the horrors of failing to modularize an old program that
is being converted (literated?)), but it has been several years since I
read the book, so I wouldn't presume to recommend particular chapters
at this point.
 
					  Steve Fulling
 
From dak@POOL.Informatik.RWTH-Aachen.DE Wed Apr 21 18:03:41 +0200 1993
Date: Wed, 21 Apr 93 18:03:41 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: beginner seeks module decomposition advice
 
   X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
   Warnings-To: <> Sender: LP-Mgr@SHSU.edu From: "John K Nicoll"
   <jkn@ohm.york.ac.uk> Reply-To: LitProg@SHSU.edu Date: Wed, 21 Apr
   1993 09:28:10 +0100 (BST) X-Mailer: ELM [version 2.4 PL20]
   Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII
   Content-Transfer-Encoding: 7bit Content-Length: 826
 
   Well, after reading the LitProg mailings for a while now, I got
   around to getting hold of WEB (FWEB, in fact, for my PC) and trying
   things in anger. I'm at the stage where I can convert/write a
   program (in C/C++) in a `modular' form, understand the error
   messages, and generate output files.
 
   What has so far taken me the longest time to sort out is the `art'
   of decomposing into modules. The FWEB (and other, as far as I can
   see) manuals are silent on this issue - perhaps due to its FORTRAN
   background. I haven't got a feeling yet for how to best arrange
   things between modules and functions, and would appreciate advice
   from more seasoned WEBers on this issue.  An example of code
   written in C/C++ might be useful (perhaps in the FAQ - which also
   seems silent on the `art').
 
One thing to look at, of course, are other WEBs. TeX, the program is
one to mention.
 
Another rule is that a function might be appropriate if we have things
done which are pretty capsulated, and when we might possibly call this
function several times.
 
If, on the other hand, we have something which is clearly intended to
do a specific subjob of something larger, and will not be of use for
anything else, a module is better used. In general, modules should
keep pretty small. If you need a nice editor to see which brace
belongs to which, chances are you had better split your source up a
bit sooner.
 
So, as a rule, modules should be plentiful as regarded to functions.
 
 David Kastrup dak@messua.informatik.rwth-aachen.de Tel: +49-241-72419
 Fax: +49-241-79502 Goethestr. 20, W-5100 Aachen, Germany
 
From leew@cs.utexas.edu Thu Apr 22 13:06:17 -0500 1993
Date: Thu, 22 Apr 1993 13:06:17 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: Future Developments
 
Paul Precod writes:
 
 > > The main point I was railing at was the NIH (Not Invented Here)
 > > problem that is rampant in our industry.  I chose NeXT as an example
 > > because all of their choices involved ``standards'' developed
 > > elsewhere that were already (somewhat) widely in use.  I apologize for
 > > not making myself clearer the first time.
 >
 > Care to explain NeXTMail?  And what about X?  I get the impression that
 > NeXT Corp. would not add X to NeXTStep even if you programmed it up for them.
 > What they have is better, so what already exists is irrelevant!  Even if
 > they could work well together.
 >
 > I wonder how standard their Unix implementation is too.
 
1.  Dunno about NeXTMail.  It seems to handle plain ol' Internet mail just
fine (unfortunately our NeXT is in NJ and I'm in TX, so I can't check
out any of this -- please take this and the following comments as my
impressions rather than gospel truth).
 
2.  I was under the impression that NeXTstep _did_ support X (I think
I read it in the documentation somewhere).  Maybe not.
 
3.  Their implementation of Unix is as standard as any I've seen.  In
fact, when I ftp something from the net, I usually try to build it on
the NeXT first, because it almost always builds correctly the first
time.  I occasionally have problems on other Unix machines.
[Relevant side issue:  Now that C is officially standardized, I find
it interesting that none of the cc compilers on any of the Unix
systems I have accounts on conforms to the standard.]
 
4.  I didn't claim the NeXT people were perfect -- just that they did
a few major things right IMHO :-).
 
		 	-- Lee
 
From plyon@emx.cc.utexas.edu Thu Apr 22 13:10:28 -0500 1993
Date: Thu, 22 Apr 93 13:10:28 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Future Developments
 
Lee Wittenberg writes:
 
> I find the same situation with my students, although I teach mostly CS
> students.  We also have ``writing emphasis'' courses (I'm trying to develop
> one in Literate Programming, e'en as we speak).
 
Well, I like this idea! A couple of suggestions, if I may.  Firstly,
you might want to look at Chapter 9 (``Mathematical Writing'') of
Knuth's ``Literate Programming'', if you have not already done so, for
some hints about how students at Stanford got on with literate
programming. I presume you are considering one or both of Knuth's book
and Wayne Sewell's ``Weaving a Program'' as texts. I am tempted to
suggest that if you feel that you can only use one, then Knuth is the
one to try, even though not all of it is about literate programming.
It seems to me that you are more apt to get them thinking about style
and organization of their writing this way.
 
It seems to me that one ought to play it straight here, namely to try
to get the students to follow the conventions of expository writing as
best they can, allowing for the differences between a literate
programme and other types of exposition writing. They should give a
proper introduction explaining to the reader what is coming, try to
follow a coherent narrative organization, ond so on. You are, after
all trying to help them improve their writing, albeit in a unusual
genre of exposition.
 
One interesting question about style is this: should they try to write
a proper conclusion to their programme summing up what it does and
what they think is most important among the ideas for the programme
they have previously discussed? The examples of literate programmes we
have from Knuth do not have a conclusion. More generally, it seems to
me that in literate programmes written in noweb or Funnelweb, as they
allow a more free form style, one may be able to use a model of
expository writing closer to the traditional models, than with those
written in Cweb, Fweb, or a Spidery Web. A proper conclusion may or
may not be useful, but one perhaps should try it to see.
 
In general, it seems to me, that since this is meant to be a writing
course, the students should include more by way of commentary in what
they write than they might in a literate programme written for use,
and you should insist on good organization and writing style.
 
The problem of expository structure in a literate programme raises a
second issue. Though they are certainly an improvement on manuscript
and typewriting, conventional text editors, including Emacs, do not
offer that much by way of support for crafting expository organization
nor do they provide much help for refining the ideas to be presented.
For that sort of thing, one needs an ``outliner''. Unfortunately, the
only ones that I know about are for MS-DOS or the Macintosh. Indeed,
the only two I have tried are both DOS programmes, viz. MaxThink and
Kamas.
 
I have used MaxThink for some years now in writing my lecture notes,
and am quite pleased with it. Now I find myself trying to use it for
literate programming as well. The idea is to think through the ideas
for the programme or programme or library modules, writing these in as
topics in the outline, adding source as appropriate as text attached
to a topic, then use the structuring features of MaxThink to work out
an organization for the web source, and finally have MaxThink write it
out in a suitable form to dump it into Emacs to finish the job.  Pity
that time constraints have prevented me thus far from completing this
process for any of the things I am working on :-)
 
As for Kamas (which is a DOS shareware product), I have only recently
downloaded it from one of the mirrors of the simtel20 archive (e.g.
ftp.uu.net, ~ftp/systems/ibmpc/msdos/simtel20/editor/kamas25.zip), and
have only played with it a bit, so I can't say much about it, sawe
that it seems to offer an interesting alternate approach to MaxThink,
and also seems to have some of the more useful features of MaxThink,
though not, by any means all. I should note that I also downloaded
PC-Outline while I was at it (this is, curiously, in the txtutl
subdirectory of the simtel20 archive---pco334.zip), but it seems to me
that PC-Outline lacks most of the amenities of MaxThink and Kamas, and
is decidedly less useful as a consequence. Yet even PC-Outline is
clearly more useful than the best Emacs package, namely ``allout.el'',
and never mind the equally inferior outlining components of Word and
Wordperfect. (I just downloaded web-mode.el, and notice that it too
offers some outlining capabilities, but no more, so it seems to me
than ``allout.el''. To be sure ``web-mode.el'' looks to be well
thought out and written; Bart Childs and Mike Motl have done a nice
job here.)
 
Having said this, I should note that I took the trouble to investigate
alternatives to MaxThink so as to be able to present alternatives to
the students in the ``writing component course'' I am teaching this
term, thinking that use of such a tool could help them with the
problems of expository organization that I saw in many of their
papers. My presentation of this idea to the class some weeks ago,
however, seems to have gone over like a lead ballon. I was pleased to
discover, though, through a conference with a student in that class
several days later, that her paper, which was unusually well
organized, had been written with the aid of the outline capability in
MS-Word. Primitive though that is, she had made good use of it in
structuring her exposition.
 
I am also moved to note a remark that Neil Larson, the designer of
MaxThink, included in the user manual, namely: ``Word processing
focuses on WYSIWYG---what you see is what you get'', but ``MaxThink
focuses on WYTIWYG---what you think is what you get''. Later on in the
manual, after remarking on the work it would take to convert MaxThink
from a text-mode DOS programme to MS-Windows, he explains his decision
not to undertake this thusly: ``After all this, the intellectual
processes for better thinking, writing, and planning are not improved
in the slightest.  Summary: While Windows may be fashionable, it does
not extend MaxThink's capabilities!'' (Apologies, sort of, to the
WYSIWYG fans, but this is a point worth pondering in that connection,
especially since Leslie Lamport makes a similar point, though with
rather less justification, early on in his LaTeX book.)
 
In any event, I am not actually recommending that one require students
to lay hands on a good outliner, but merely trying to make a few
points about appropriate tools for expository writing in general, and
literate programming in particular.
 
But I do commend Lee Wittenberg's idea to others reading this list who
teach CS students, and I would encourge Lee to post information about
the design for his course to the mailing list.
 
(I have more things to say about other matters of interest that Lee
Wittenberg raises in his thoughful comments, but I will do this in a
subsequent post.)
 
Ciao,
 
Paul Lyon
 
From plyon@emx.cc.utexas.edu Thu Apr 22 13:10:28 -0500 1993
Date: Thu, 22 Apr 93 13:10:28 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Future Developments
 
Lee Wittenberg writes:
 
> I find the same situation with my students, although I teach mostly CS
> students.  We also have ``writing emphasis'' courses (I'm trying to develop
> one in Literate Programming, e'en as we speak).
 
Well, I like this idea! A couple of suggestions, if I may.  Firstly,
you might want to look at Chapter 9 (``Mathematical Writing'') of
Knuth's ``Literate Programming'', if you have not already done so, for
some hints about how students at Stanford got on with literate
programming. I presume you are considering one or both of Knuth's book
and Wayne Sewell's ``Weaving a Program'' as texts. I am tempted to
suggest that if you feel that you can only use one, then Knuth is the
one to try, even though not all of it is about literate programming.
It seems to me that you are more apt to get them thinking about style
and organization of their writing this way.
 
It seems to me that one ought to play it straight here, namely to try
to get the students to follow the conventions of expository writing as
best they can, allowing for the differences between a literate
programme and other types of exposition writing. They should give a
proper introduction explaining to the reader what is coming, try to
follow a coherent narrative organization, ond so on. You are, after
all trying to help them improve their writing, albeit in a unusual
genre of exposition.
 
One interesting question about style is this: should they try to write
a proper conclusion to their programme summing up what it does and
what they think is most important among the ideas for the programme
they have previously discussed? The examples of literate programmes we
have from Knuth do not have a conclusion. More generally, it seems to
me that in literate programmes written in noweb or Funnelweb, as they
allow a more free form style, one may be able to use a model of
expository writing closer to the traditional models, than with those
written in Cweb, Fweb, or a Spidery Web. A proper conclusion may or
may not be useful, but one perhaps should try it to see.
 
In general, it seems to me, that since this is meant to be a writing
course, the students should include more by way of commentary in what
they write than they might in a literate programme written for use,
and you should insist on good organization and writing style.
 
The problem of expository structure in a literate programme raises a
second issue. Though they are certainly an improvement on manuscript
and typewriting, conventional text editors, including Emacs, do not
offer that much by way of support for crafting expository organization
nor do they provide much help for refining the ideas to be presented.
For that sort of thing, one needs an ``outliner''. Unfortunately, the
only ones that I know about are for MS-DOS or the Macintosh. Indeed,
the only two I have tried are both DOS programmes, viz. MaxThink and
Kamas.
 
I have used MaxThink for some years now in writing my lecture notes,
and am quite pleased with it. Now I find myself trying to use it for
literate programming as well. The idea is to think through the ideas
for the programme or programme or library modules, writing these in as
topics in the outline, adding source as appropriate as text attached
to a topic, then use the structuring features of MaxThink to work out
an organization for the web source, and finally have MaxThink write it
out in a suitable form to dump it into Emacs to finish the job.  Pity
that time constraints have prevented me thus far from completing this
process for any of the things I am working on :-)
 
As for Kamas (which is a DOS shareware product), I have only recently
downloaded it from one of the mirrors of the simtel20 archive (e.g.
ftp.uu.net, ~ftp/systems/ibmpc/msdos/simtel20/editor/kamas25.zip), and
have only played with it a bit, so I can't say much about it, sawe
that it seems to offer an interesting alternate approach to MaxThink,
and also seems to have some of the more useful features of MaxThink,
though not, by any means all. I should note that I also downloaded
PC-Outline while I was at it (this is, curiously, in the txtutl
subdirectory of the simtel20 archive---pco334.zip), but it seems to me
that PC-Outline lacks most of the amenities of MaxThink and Kamas, and
is decidedly less useful as a consequence. Yet even PC-Outline is
clearly more useful than the best Emacs package, namely ``allout.el'',
and never mind the equally inferior outlining components of Word and
Wordperfect. (I just downloaded web-mode.el, and notice that it too
offers some outlining capabilities, but no more, so it seems to me
than ``allout.el''. To be sure ``web-mode.el'' looks to be well
thought out and written; Bart Childs and Mike Motl have done a nice
job here.)
 
Having said this, I should note that I took the trouble to investigate
alternatives to MaxThink so as to be able to present alternatives to
the students in the ``writing component course'' I am teaching this
term, thinking that use of such a tool could help them with the
problems of expository organization that I saw in many of their
papers. My presentation of this idea to the class some weeks ago,
however, seems to have gone over like a lead ballon. I was pleased to
discover, though, through a conference with a student in that class
several days later, that her paper, which was unusually well
organized, had been written with the aid of the outline capability in
MS-Word. Primitive though that is, she had made good use of it in
structuring her exposition.
 
I am also moved to note a remark that Neil Larson, the designer of
MaxThink, included in the user manual, namely: ``Word processing
focuses on WYSIWYG---what you see is what you get'', but ``MaxThink
focuses on WYTIWYG---what you think is what you get''. Later on in the
manual, after remarking on the work it would take to convert MaxThink
from a text-mode DOS programme to MS-Windows, he explains his decision
not to undertake this thusly: ``After all this, the intellectual
processes for better thinking, writing, and planning are not improved
in the slightest.  Summary: While Windows may be fashionable, it does
not extend MaxThink's capabilities!'' (Apologies, sort of, to the
WYSIWYG fans, but this is a point worth pondering in that connection,
especially since Leslie Lamport makes a similar point, though with
rather less justification, early on in his LaTeX book.)
 
In any event, I am not actually recommending that one require students
to lay hands on a good outliner, but merely trying to make a few
points about appropriate tools for expository writing in general, and
literate programming in particular.
 
But I do commend Lee Wittenberg's idea to others reading this list who
teach CS students, and I would encourge Lee to post information about
the design for his course to the mailing list.
 
(I have more things to say about other matters of interest that Lee
Wittenberg raises in his thoughful comments, but I will do this in a
subsequent post.)
 
Ciao,
 
Paul Lyon
 
From Chris Fri Apr 23 13:22:37 MDT 1993
Date: Fri, 23 Apr 93 13:22:37 MDT
From: Chris Flatters <cflatter@aoc.nrao.edu>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Supressing index entries in FWEB
 
I am using FWEB to write an X Window System program.  I would like to
have the various types defined by the X Intrinsics (eg. XtPointer) typeset
as types but would prefer not to have a long list of @f definitions appear
in the woven output.  Since I keep the @f definitions in an included file
I can suppress them by including the file with an @I directive and using
the -i command line flag.  Unfortunately, index entries are still generated
for the new type which clutters up the index (particularly for identifiers
beginning with the letter 'x').  Is there any way of disabling the automatic
generation of index entries for @f definitions?
 
What I would really like to see, of course, is an escape that has the same
effect on formatting as @f but that neither appears in the woven output nor
generates an index entry (yes, I know this exists in CWEB but have reasons
for using FWEB).
 
	Chris Flatters
	cflatter@nrao.edu
 
From norman@bellcore.com Fri Apr 23 16:17:01 -0400 1993
Date: Fri, 23 Apr 93 16:17:01 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  beginner seeks module decomposition advice
 
In my opinion, one of the biggest problems of the LP community has
been that many people expend enormous effort on tools, while there is
not a good understanding of how to use even very simple tools.  When
Carla Marceau and I wrote our paper on our experiences building a
10-20 K line system using Spidery WEB, we tried to explain how
literate programming had made our proejct a success, and to be
prescriptive about how to use literate-programming tools well.  The
referees quite rightly pointed out that this part of teh paper was
vague if not actually content-free, and the final version of the paper
contains only some weasel words along the lines of ``we're really
pleased we used literate programming and we're not sure why.''
noweb was my effort to scrape away all the complexity of existing
tools in order to try to learn something more fundamental about
literate programming.  I'm pleased with the tool, but I haven't
learned the things I had hoped to learn from it.  The best advice I
can give to aspiring literate programmers is still the same advice I
give to students writing papers: write, read your work, and rewrite.
Peer review is invaluable if you can get it.
 
Anybody else making better progress?
 
Norman
 
From Kayvan Fri Apr 23 14:37 PDT 1993
Date: Fri, 23 Apr 93 14:37 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Supressing index entries in FWEB
 
Use
 
	@f @-XTypeName @-int
 
instead of
 
	@f XtypeName int
 
and I think that will solve your problem.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From bart@cs.tamu.edu Fri Apr 23 22:25:26 CDT 1993
Date: Fri, 23 Apr 93 22:25:26 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Comments on ? starting, simplicity, ..?
 
The inquiry from Chris Flatters on `Supressing index entries in FWEB'
and the thoughtful response from Norman Ramsey encourage me to add
a few more thoughts.
 
First, I seriously considered answering Chris' inquiry with:
1. Even if they are seriously long (like many pages), the value of
   this in most cases is too great to want to throw away.
2. If someone else is going to (possibly) maintain your code, then
   you really want them.
3. If you are using dvips (and most good drivers) it is fairly easy
   to create scripts to just not print those pages if that is the problem.
4. Can't that be put in a `.h' file that could have been done as a web
   and then kept for everybody to use?
 
Then Norman said:
``In my opinion, one of the biggest problems of the LP community has
  been that many people expend enormous effort on tools, while there is
  not a good understanding of how to use even very simple tools....
                  ... the final version of the paper
  contains only some weasel words along the lines of ``we're really
  pleased we used literate programming and we're not sure why.'' ''
 
That is his opinion and I think based on sound reasoning.
The postings on the subject `beginner seeks module decomposition advice'
are evidence enough.
 
He also said, ``The best advice I can give to aspiring literate
  programmers is still the same advice I give to students writing
  papers: write, read your work, and rewrite.  Peer review is
  invaluable if you can get it.''
 
Eloquent!  A word of warning, leave your feelings at the door.
We are seldom ready for others' constructive criticism.  It does not
help that most we will get to read our work will not understand what
literate programming is about and that we are frequently not true
to the intent.  (Also, remember this in the `new features' below.)
 
Finally, Kayvan Sulvan's help prompts one more thought.  Simplicity!
I have read the FWEB manual many times and don't remember that at all.
 
Have we lost sight of what we are after?  Norman's primary reason for
noweb was simplicity (his words were `scrape away all the complexity of
existing tools').  I look at WEBs and see that most rarely
use more than a small fraction of the available commands, features, or
whatever you want to call the @-things.  Yet, we have had a plethora
of postings of requests for `new features'.
 
I have observed that if a document is being prepared and a difficult
(formatting) challenge comes along, then there is a real dichotomy:
 
* if TeX (or the like) is being used the user may spend inordinate
  amounts of time trying to `make it perfect.'
 
* if it can't be found in two minutes on the WYSIWYG's pull down menu,
  the mind is quickly set to ``God did not intend such to be done!'
 
Of course the first * is from observations during the preparation
stage and the second from questioning `why this?' after seeing student
papers thought to be perfect because they: have an aligned right margin,
have been within a mile of a spell checker, and have a gaudy excedd
of bold font usage.
 
It seems to me that some of our problems are due to this `TeX nature.'
Don Knuth created some great research problems solving many aspects of
TeX's and MetaFont's problems.
 
Quotes from two I think deserve to be quoted:
 
    One way of improving efficiency is by restricting the
    power of the language --- Tony Hoare
 
    The need for more elaborate man/machine interaction can
    certainly be enhanced by designing more incomprehensible
    systems --- Edsger Dijkstra
 
Some of the themes that I hope are woven into this commentary are
what I feel we used as justification for the design decisions in
Mark Motl's web-mode for emacs.  We wanted it to be easy to do
some of the more difficult things like:
* Reuse section names (the @< .. @> things) with minimal typing.
  In web-mode's current form, a list of them are maintained and
  you select them by use of emacs completitions.  I never did like
  Knuth's use of ellipses although I certainly understand why...
* Navigation by chapters (major sections), sections, cross reference
  lists, index, ...  It can be considered to be a restricted
  hypertext mechanism.
* Creation and reuse of user supplied index entries (@. **@>,
  @^..@>, and the other one)
The outline editing was added later and has been a real winner too.
 
In much the spirit of Norman's comment, I would really like to get
a lot of data back on how people use it before we add a lot more
functions.  Unless it is defeated, a journal file is written that
we get lots of data from.  However, most have come from within
our local community.  Indeed, many users don't use a lot of the
functions that I believe would be of great benefit.  However, isn't
that the usual story?  I have seen a large number of people who will
move down 100 lines by 100 `down arrow's rather than 5 `page down's!
 
We finally have our anonymous ftp back, it is
 
ftp.cs.tamu.edu
 
In the directory /pub/web   exist the current form.
It is web-mode.el  (web-mode.elc can also be extracted).  The
manual is webm-man.tex.  The other files needed are after the
`\bye' in the manual.
 
There is also a subdirectory DOCs in which I am placing a few
documents that I hope can help in elementary LPing.  Those that
begin with `wm' are a set.  wm_0.tex describes the four steps
in an evolutionary web: wm_1.web begat wm_2.web, ..., wm_4.web.
 
Constructive criticism is appreciated.
 
Bart Childs
 
From leew@cs.utexas.edu Mon Apr 26 11:33:17 -0500 1993
Date: Mon, 26 Apr 1993 11:33:17 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  beginner seeks module decomposition advice
 
Norman Ramsey writes:
 
  > ... The best advice I
  > can give to aspiring literate programmers is still the same advice I
  > give to students writing papers: write, read your work, and rewrite.
  > Peer review is invaluable if you can get it.
  >
  > Anybody else making better progress?
 
I'll second Norman's advice.  We've got a few people here at Tipton
Cole + Co. getting started with literate programming (using noweb and
WinWordWEB), and we seem to get our best results by writing,
rewriting, and passing the programs around for comment.  One of the
best things about LP, I've found, is that it is possible to pass
around a (woven) listing of a program and have people actually read it
and make suggestions, something I cannot recall ever happening with a
regular ol' source listing.
 
		 -- Lee
 
From bos@mdd.comm.mot.com Mon Apr 26 11:05:54 PDT 1993
Date: Mon, 26 Apr 93 11:05:54 PDT
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re:  beginner seeks module decomposition advice
 
> We've got a few people here at Tipton
> Cole + Co. getting started with literate programming (using noweb and
> WinWordWEB), and we seem to get our best results by writing,
> rewriting, and passing the programs around for comment.  One of the
> best things about LP, I've found, is that it is possible to pass
> around a (woven) listing of a program and have people actually read it
> and make suggestions, something I cannot recall ever happening with a
> regular ol' source listing.
>
>		 -- Lee
Hi,
 
I'm doing a seminar for my MSE program at Seattle U on LP and I
saw this comment on WinWordWEB.  Since I'm in the land of WinWord,
I would like to know where I can acquire a copy of WinWordWEB.
 
Thanks for your information and comments.
 
mary bos
 
From Adrian Tue Apr 27 09:42:59 +0100 1993
Date: Tue, 27 Apr 93 09:42:59 +0100
From: Adrian F Clark <alien@essex.ac.uk>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Comments on ? starting, simplicity, ..?
 
On Fri, 23 Apr 93 22:25:26 CDT, bart%cs.tamu.edu@uk.ac.essex.mailhost (Bart Childs) said:
 
BC> In much the spirit of Norman's comment, I would really like to get
BC> a lot of data back on how people use it before we add a lot more
BC> functions.
 
I have put together Perl versions of most of Norman's excellent noweb
system for my own consumption (this was for use on DOS, before someone
came along with a DOS implementation of noweb).  One of the things my
Perl stuff can do is output statistics on the number of times each
internal `@' construct is used.  This was very helpful in optimizing
the order of processing each construct in a else..if chain.  Surely it
would be pretty simple to do this to any web-like package?  This would
yield invaluable information on precisely which features were
essential, which were highly desirable, and which totally superfluous.
Much more reliable than allegory.
 
For anyone burning to know, @nl is the most common noweb entity,
followed by @text.  For most of the programs I've looked at,
everything else is used less than one-tenth as frequently.
 
 Dr Adrian F. Clark                                   JANET: alien@uk.ac.essex
 INTERNET: alien%uk.ac.essex@nsfnet-relay.ac.uk          FAX: (+44) 206-872900
 BITNET: alien%uk.ac.essex@ac.uk              PHONE: (+44) 206-872432 (direct)
 Dept ESE, University of Essex, Wivenhoe Park, Colchester, Essex, C04 3SQ, UK.
 
From SMTP Tue Apr 27 09:42:59 +0100 1993
Date: Tue, 27 Apr 93 09:42:59 +0100
From: "SMTP MAILER" <postmaster@geemunu.stanford.edu>
Reply-To: LitProg@SHSU.edu
To: "LitProg" <LitProg@SHSU.edu>
Subject: Mail not delivered yet, still trying
 
 ----Mail status follows----
Have been unable to send your mail to <mckenzie@embezzle.stanford.edu>,
will keep trying for a total of three days.
At that time your mail will be returned.
 
 ----Transcript of message follows----
Date: 27 Apr 93 01:01:00 PST
From: LitProg@SHSU.edu
Subject: Re: Comments on ? starting, simplicity, ..?
To: "mckenzie" <mckenzie@embezzle.stanford.edu>
 
Return-Path: <LP-Mgr@SHSU.edu>
Received: from Niord.shsu.edu by geemunu.stanford.edu with SMTP ;
          Tue, 27 Apr 93 01:01:45 PST
X-ListName: Literate Programming Discussion List <LitProg@SHSU.edu>
Warnings-To: <>
Errors-To: LP-Mgr@SHSU.edu
Sender: LP-Mgr@SHSU.edu
Received: from sun2.nsfnet-relay.ac.uk by Niord.shsu.edu (MX V3.2) with SMTP;
          Tue, 27 Apr 1993 03:44:43 CDT
Via: uk.ac.essex; Tue, 27 Apr 1993 09:43:06 +0100
Received: from vulcan.essex.ac.uk by postman.essex.ac.uk with SMTP (PP) id
          <23347-0@postman.essex.ac.uk>; Tue, 27 Apr 1993 09:43:03 +0100
From: Adrian F Clark <alien@essex.ac.uk>
Reply-To: LitProg@SHSU.edu
Date: Tue, 27 Apr 93 09:42:59 +0100
Message-ID: <8917.9304270842@vulcan.essex.ac.uk.essex.ac.uk>
To: LitProg@SHSU.edu
In-Reply-To: Bart Childs's message of Fri, 23 Apr 93 22:25:26 CDT
    <9304240325.AA07480@neuron.cs.tamu.edu>
Subject: Re: Comments on ? starting, simplicity, ..?
 
On Fri, 23 Apr 93 22:25:26 CDT, bart%cs.tamu.edu@uk.ac.essex.mailhost (Bart Childs) said:
 
BC> In much the spirit of Norman's comment, I would really like to get
BC> a lot of data back on how people use it before we add a lot more
BC> functions.
 
I have put together Perl versions of most of Norman's excellent noweb
system for my own consumption (this was for use on DOS, before someone
came along with a DOS implementation of noweb).  One of the things my
Perl stuff can do is output statistics on the number of times each
internal `@' construct is used.  This was very helpful in optimizing
the order of processing each construct in a else..if chain.  Surely it
would be pretty simple to do this to any web-like package?  This would
yield invaluable information on precisely which features were
essential, which were highly desirable, and which totally superfluous.
Much more reliable than allegory.
 
For anyone burning to know, @nl is the most common noweb entity,
followed by @text.  For most of the programs I've looked at,
everything else is used less than one-tenth as frequently.
 
 Dr Adrian F. Clark                                   JANET: alien@uk.ac.essex
 INTERNET: alien%uk.ac.essex@nsfnet-relay.ac.uk          FAX: (+44) 206-872900
 BITNET: alien%uk.ac.essex@ac.uk              PHONE: (+44) 206-872432 (direct)
 Dept ESE, University of Essex, Wivenhoe Park, Colchester, Essex, C04 3SQ, UK.
 
From ark@mailhost.cs.pdx.edu Thu Apr 29 09:37:32 -0700 1993
Date: Thu, 29 Apr 1993 09:37:32 -0700 (PDT)
From: ark@mailhost.cs.pdx.edu (jim a arkenberg)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re: your mail
 
>
> SENDME Litprog.1993-04
>
 
Tex,
 
  Did you mean to mail this to me?  No reply necessary.
 
Jim Arkenberg
ark@rigel.cs.pdx.edu
 
From leew@cs.utexas.edu Fri Apr 30 10:35:41 -0500 1993
Date: Fri, 30 Apr 1993 10:35:41 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu
To: litprog@shsu.edu
Subject: Duplicate modules/sections and good webbing style
 
The recent discussions about the proper use of modules vs. procedures
and other points of style got me thinking about what would constitue
``good webbing practices.''  I'm not going to try to generate an
"Elements of Webbing Style" here, but a thought struck me about style
and duplicate code sections (the ones defined with +\equiv) that I
thought might be of general interest:
 
    It would seem that the interests of good style would dictate that
    the code in the different chunks of a duplicated section should be
    completely independent.  For example,
 
        @ @<A duplicated section@>=
            x = y + z;
 
        @ @<A duplicated section@>=
            a = b + c;
 
    would be okay, but
 
        @ @<A duplicated section@>=
            x = y + z;
 
        @ @<A duplicated section@>=
            a = x++;
 
    wouldn't.  The reason for this is that in the former case, a
    reorganization of the web is guaranteed not to screw up the
    program, while in the latter case, there is a very real danger
    that reorganizing will break the program (and this would be a very
    difficult bug to find).
 
    This has some very interesting implications.  If the duplicate
    sections are independent, then they can be executed in parallel,
    which leads to a very natural way to express parallelism (by way
    of literature):
 
        @*Chapter n.
        In this chapter, some really interesting stuff happens.
        @<The stuff that happens in the first chapter@>=
                /* A */
 
        @ Meanwhile, back at the ranch~$\ldots$
        @<The stuff that happens in the first chapter@>=
                /* B */
 
    A smart tangle could generate the equivalent of
 
        cobegin A; B coend
 
    Declarations, of course, would not need the cobegin/end, but they
    (conceptually) execute in parallel already.
 
    This technique will, of course, cause severe problems with my
    second example, but (as I pointed out earlier) it was bound to break
    eventually, anyway.
 
			-- Lee
 
From preston@cs.rice.edu Fri Apr 30 12:51:48 CDT 1993
Date: Fri, 30 Apr 93 12:51:48 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu
To: LitProg@shsu.edu
Subject: Re:  Duplicate modules/sections and good webbing style
 
I find that I use "duplicate sections" almost exclusively for
accumulating declarations and almost never for code.  When I want several
pieces of code to contribute to a single module, I organize it hierarchically,
and explain the subdivision right away.
 
For example, instead of
 
@<The main code@>=
  @<foo@>
 
@<The main code@>=
  @<bar@>
 
@<The main code@>=
  @<quux@>
 
possibly scattered throughout the document,
I prefer to write
 
@<The main code@>=
  @<foo@>
  @<bar@>
  @<quux@>
 
I find the idea of having tangle perform automatic parallelization
to be a little scary :-)
 
Preston Briggs
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sat May 1 16:55:16 +0200 1993
Date: Sat, 1 May 93 16:55:16 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Duplicate modules/sections and good webbing style
 
I find that I use duplicate sections for code as well: mostly for
cases in switches. There I have no bad feelings about them.
 
From Kayvan Mon May 3 22:18 PDT 1993
Date: Mon, 3 May 93 22:18 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Re: Experiences with litprog so far
 
>>>>> "Marcus" == Marcus Speh <apple!x4u.desy.de!marcus> writes:
 
Kayvan> My second literate program was written in C++ using FWEB,
Kayvan> producing a few files and being split across several sources
Kayvan> with an attendant generic Makefile that I developed.
 
Marcus> Did you solve the problem (outlined in the FWEB-FAQ in Question [29])
Marcus> of presenting a _nice_ table of contents and a combined index which
Marcus> distinguishes between entries from different source files?
 
No. I started to look into it, but real work priorities intruded. I'm
now looking for my next consulting gig, so I'm either going to be real
buisy or NOT. 1/2 :-)
 
Marcus> The example I have in mind is Cameron Smith's hack of cwebmac.sty
Marcus> for the CWEB-KR-sample files. I know that John Krommes has put it in
Marcus> his long list of future enhancements (but it isnt contained in v1.30
Marcus> as far as I can see).
 
No, it's not in FWEB yet. I have converted the CWEB-KR-sample to FWEB
and doing the combined table of contents and index is on my list of
things to do (though I don't want to duplicate any work that John
Krommes has already put into this).
 
Marcus> I have CWEB,FWEB,NOWEB documents on the LitProg page for the World
Marcus> Wide Web. Somebody volunteers to write a few lines (HyperText ?) for
Marcus> C-No-Web along what I put up for the other LitProg tools? This mainly
Marcus> means one or more links to first-hand information and possibly some
Marcus> preprocessed examples.
 
Along these lines, and mostly for fun (though I use it all the time
now), I developed a generalized Makefile for FWEB/CWEB using NOWEB!!!
It allows me to write Makefile fragments (reminiscent of imake and its
"Imakefile") that produce the real Makefile for a WEB-based
application. I call it MetaMake.
 
If people are interested, I can send it to them (or to the list).
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Kayvan Tue May 4 01:03 PDT 1993
Date: Tue, 4 May 93 01:03 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: beginner seeks module decomposition advice
 
>>>>> "John" == John K Nicoll <apple!ohm.york.ac.uk!jkn> writes:
 
John> What has so far taken me the longest time to sort out
John> is the `art' of decomposing into modules. The FWEB (and other, as
John> far as I can see) manuals are silent on this issue - perhaps due
John> to its FORTRAN background. [...]
 
Marcus> [...] The choice of C, C++ or Fortran should not be an issue,
Marcus> IMO. The layout of your literate programs should rather follow
Marcus> general guidelines as sufficiently described in various
Marcus> articles and manuals. These imaginary 'guidelines' aren't just
Marcus> words: look into the source code of the CWEB and FWEB
Marcus> releases. Probably Levy/DEK have put parts of common.w into
Marcus> the User's Manual for this reason.
 
I completely agree with Marcus here. Literate Programs should still
follow good programming style. You can do good programming in
assembler and bad programming in C++, it's not linked to language.
 
The layout of my literate programs follow a mixture of intuition and
computer science. I have a sense of what I want to accomplish and I
start by writing the documentation chunk that introduces the program
and the motivation for the program.
 
After the introduction of the program, I use outlining and
old-fashioned structured programming techniques (with a smattering of
object oriented design) to decompose the problem. I write an overview
of the program using named modules (to be defined further inside the
WEB). As I get to each module, I write the documentation chunk and
write the code, and often find that there is an obvious next step that
makes the writing and the programming flow.
 
Just as in my plain C or C++ programs, I define functions when the set
of operations is generic enough to be used by other parts of the
program. I use named modules when I am trying to decompose a piece of
code that is best understood in overview (rather than overwhelm my
reader with details). This makes for an easy to write and easy to
understand program.
 
I also find that object oriented design mixes in very well with
literate programming (and takes care of the classic OO problem of
how you document your classes in a meaningful way).
 
Literate programmers would do well to keep Miller's 7 +/- 2 law in
mind as they weave and tangle their webs.
 
As an aside: a side effect of literate programming for me has been
that my programs take less time to write because I'm having so much
fun writing them!
 
Marcus> Altogether, in _my_ programs, the decomposition does not
Marcus> change essentially from one language to another. But again, I
Marcus> _do_ have a Fortran background, so maybe I'm missing the point
Marcus> here. And I wouldnt claim to do an 'art', either.
 
Marcus> Some comments on this last point by people with another background ?
 
Well, I come from a mostly C/Unix background and I found your comments
to be emminently reasonable. I don't think you're missing the point.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Kayvan Tue May 4 01:24 PDT 1993
Date: Tue, 4 May 93 01:24 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Comments on ? starting, simplicity, ..?
 
>>>>> "Bart" == Bart Childs <apple!cs.tamu.edu!bart> writes:
 
[... about web-mode ...]
Bart> In much the spirit of Norman's comment, I would really like to
Bart> get a lot of data back on how people use it before we add a lot
Bart> more functions.  Unless it is defeated, a journal file is
Bart> written that we get lots of data from.  However, most have come
Bart> from within our local community.  Indeed, many users don't use a
Bart> lot of the functions that I believe would be of great benefit.
Bart> However, isn't that the usual story?  I have seen a large number
Bart> of people who will move down 100 lines by 100 `down arrow's
Bart> rather than 5 `page down's!
 
I use web-mode to do outlining, jumping back and forth between
sections, reading WEB code as well as writing it, view section names
and jump to it, look at a variable in the index and go back and forth
between code and index, etc. The most common operation I use is the
automatic module name generation and selection mechanism.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Kayvan Tue May 4 02:39 PDT 1993
Date: Tue, 4 May 93 02:39 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu
To: LitProg@SHSU.edu
Subject: Duplicate modules/sections and good webbing style
 
Lee Wittenberg makes some interesting points about duplicate code
sections.
 
Looking in my code, there are a few places where I use duplicate
(appended to) sections:
 
(*1*) Accumulating declarations. This is especially true in C (since I
can put declarations most anywhere in C++ and the need is lessened).
 
A typical example is:
 
    @ In |Print_Postscript_For_Board()|, we look at the Chess position and
    print the board using the Foresythe notation as implemented in
    Walker's chess font.
 
    @<Printing Routines@>=
    void Print_Postscript_For_Board( BOARD *my_board )
    {
	    @<Variables local to |Print_Postscript_For_Board()|@>@;
 
	    @<Prepare the postscript code@>@;
	    @<Output code to user-specified place, default |stdin|@>@;
    }
 
And then I can do something like this:
 
    @ To prepare the postscript code, we need to look at the structure
    elements in each cell of |my_board|. We use the |score| and
    |whose_move| variables in the code that follows.
 
    @<Variables local to |Print_Postscript_For_Board()|@>=
    int score;	/* this is part of the chess game listing */
    enum sides { WHITE, BLACK } whose_move;
 
    @ @<Prepare the postscript code@>=
    score = my_board[0].score;	/* the score for this snapshot */
    if (my_board[0].is_white)
	    whose_move = WHITE;
    else
	    whose_move = BLACK;
 
(*2*) Accumulating related functions. This mechanism makes it easy for
me to have *one* well-structured un-named section, rather than lots of
unnamed sections sprinkled throughout my code.
 
Example:
 
@ The {\tt foobarbletch} program needs to do many somewhat unrelated
things. Here is the overview of this program.
 
    @A @% FWEB un-named section (equivalent to @c in CWEB)
    @<Header Files@>@/
    @<Global Variables@>@/
    @<Chess Game Parsing Routines@>@/
    @<Postscript Output Routines@>@/
    @<The main program@>@/
    @<Utility Routines@>@/
 
And then @<Utility Routines@> becomes the catch-all bucket for any
useful function that I need to use elsewhere in the program.
 
(*3*) Un-tangling large switch statements. Various parsers and simple
state machines are best explained on a "case" by "case" basis.
 
    @ So now, we are ready to read and decompose our input file, producing
    the intermediate format that is easy for us to generate queries from.
 
    @<Parse input, producing balanced AVL tree@>=
    @<Read |token|, using lex@>@;
    switch(token)
    {
	    @<Appropriate actions based on value of |token|@>
    default:
	    /* We shouldn't get here!!! Ever!!! */
	    fprintf(stderr, "I'm DYING! I don't know about token: <%s>\n",
		    token.string);
	    abort();	/* maybe a core dump will do some good */
    }
 
    @ If we are handed a |QUERY| type, we need to perform the action that is
    specified by the |type| flag of |token|.
 
    @<Appropriate actions based on value of |token|@>=
    case QUERY:
	    run_actions(token, token.type);
	    break;
 
    @ If instead, we have an integer, push it onto our value stack so it
    can be used as an operand for later actions.
 
    @<Appropriate actions based on value of |token|@>=
    case INTEGER:
	    i = atoi(token.string); /* better add integer type to the lexer */
	    push_to_value_stack(i);
	    break;
 
That's pretty much it, I think. In general, I find that the pieces of
the named (multiply defined) section should be as modular and as
self-contained as possible. In the the switch statement, each case
block can be an independant, self-contained unit, and rearranging the
web should not cause it to break.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Kayvan Thu May 13 10:50 PDT 1993
Date: Thu, 13 May 93 10:50 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu
Subject: Anybody there?
 
Is litprog just being quiet?
 
What are other litproggers doing out there?
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| !!!! NOTE: Looking for contracts. Hire me now and avoid the rush! :-) !!!! |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From sboyle@wv.MENTORG.COM Thu May 13 13:05:52 -0700 1993
Date: Thu, 13 May 93 13:05:52 -0700
From: sboyle@wv.MENTORG.COM (Sean Boyle x1542)
Reply-To: LitProg@SHSU.edu, sboyle@WV.MENTORG.COM
To: LitProg@SHSU.edu
Subject: re: Anybody there?
 
Being a plebe to literate programming, I am still fiddling around.  I think
I've figured out that I like funnelWeb as I can use it for any arbitrary
language and it doesn't muck with it too bad.  I'm not fond of losing my tab
key, sigh...
 
Is there a review of the various systems out there somewhere?
 
I'd certainly like to see some good examples of literate programming so that
I can establish a discipline.  I've seen the bibliography listing and it
looks rather extensive.  It would be nice if some of the stuff was online
where I could get at it.
 
I suppose it is all new enough that there aren't a lot of hard and fast rules,
but there must be some scars that others *could* show me to save me from
some grief.  I appreciate the comments on style which the funnelWeb user's
guide points out, but I'd like more.
 
I suppose that the next battle I'm up against is a manager who believes that
all staff members should use Frame (I think it's supposed to be another
productivity tool...) so that we can share documents.  Unfortunately, this
system doesn't fit very well into that paradigm.  What is worse, my position
of having a tool which produces a document which in turn makes a code review
a breeze is somehow untenable.
 
            +------------------------+------------------------------+
            | sean_boyle@mentorg.com |  Mentor Graphics Corporation |
            | uunet!mntgfx!sboyle    |  8005 S.W. Boeckman Road     |
            |                        |  Wilsonville, OR 97070-7777  |
            |       "Intrinsically lazy, therefore creative"        |
            +------------------------+------------------------------+
 
From bos@mdd.comm.mot.com Thu May 13 14:12:03 PDT 1993
Date: Thu, 13 May 93 14:12:03 PDT
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
To: LitProg@SHSU.edu, sboyle@wv.mentorg.com
Subject: re: Anybody there?
 
From Sean Boyle
 
> I suppose that the next battle I'm up against is a manager who believes that
> all staff members should use Frame (I think it's supposed to be another
> productivity tool...) so that we can share documents.  Unfortunately, this
> system doesn't fit very well into that paradigm.  What is worse, my position
> of having a tool which produces a document which in turn makes a code review
> a breeze is somehow untenable.
> 
 
I, too, work in the land of FrameMaker (and associated products) users.  I've heard
rumour Frame technologies is working on a conversion package to take TeX files,
but no dates or anything definite.  
I
 
From Kayvan Thu May 13 15:50 PDT 1993
Date: Thu, 13 May 93 15:50 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: sboyle@WV.MENTORG.COM
Subject: re: Anybody there?
 
>>>>> "Sean" == Sean Boyle x1542 <apple!wv.MENTORG.COM!sboyle> writes:
 
Sean> Being a plebe to literate programming, I am still fiddling
Sean> around.  I think I've figured out that I like funnelWeb as I can
Sean> use it for any arbitrary language and it doesn't muck with it
Sean> too bad.  I'm not fond of losing my tab key, sigh...
 
What does funnelweb do to the sources? Is it like noweb (leaving it
all verbatim the way you typed it)? What about indexes or a table of
contents?
 
Sean> Is there a review of the various systems out there somewhere?
 
There have been several informal reviews by Marcus Seph, myself and
others. Look in the litprog archives. My present favorites are FWEB
for C/C++/TeX, and noweb for everything else (Perl scripts, Makefiles,
etc.)
 
With the final of FWEB 1.30 about to be released, I expect an even
better FWEB (in terms of robustness and support for multiple files,
etc.)
 
Sean> I'd certainly like to see some good examples of literate
Sean> programming so that I can establish a discipline.  I've seen the
Sean> bibliography listing and it looks rather extensive.  It would be
Sean> nice if some of the stuff was online where I could get at it.
 
There's Cameron Smith's multi-file CWEB example (KR-CWEB-SAMPLE or
something like that) that implements the calculator program from K&R
second edition. This is available from shsu.edu by anonymous ftp.
 
I'm working on an FWEB sample program in my copious spare time, see my
signature line ;-). My sample program will be made available when I
finish it. :-)
 
Sean> I suppose it is all new enough that there aren't a lot of hard
Sean> and fast rules, but there must be some scars that others *could*
Sean> show me to save me from some grief.  I appreciate the comments
Sean> on style which the funnelWeb user's guide points out, but I'd
Sean> like more.
 
Once again, check the archives. There was a discussion about this
recently with the subject: "beginner seeks module decomposition..."
If you don't have access to the archives, I can probably dig up the
relevant articles and send them to you.
 
Sean> I suppose that the next battle I'm up against is a manager who
Sean> believes that all staff members should use Frame (I think it's
Sean> supposed to be another productivity tool...) so that we can
Sean> share documents.
 
You may want to look into noweb and see how you can integrate it with
Frame. A lot of people would be interested in this (even though Frame
is far inferior to TeX in its abilities).
 
Sean> Unfortunately, this system doesn't fit very well into that
Sean> paradigm.  What is worse, my position of having a tool which
Sean> produces a document which in turn makes a code review a breeze
Sean> is somehow untenable.
 
How is it untenable? I've found that code reviews are a pleasure with
weaved output, versus being a boring and tedious exercise in
self-restraint ;-)
 
			---Kayvan
 
From j_mcarthur@BIX.com Thu May 13 15:50 PDT 1993
Date: Thu, 13 May 93 15:50 PDT
From: j_mcarthur@BIX.com
Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
To: LitProg@SHSU.edu
Subject: What are other litproggers doing out there?
 
You asked, so I will tell you.
 
I work for a Typesetting company.  I do a lot of TeX.  So I have
been working on my personal port of TeX.  This now works and
passes the Trip test.  This is done using TopSpeed Pascal and
WEB.
 
To do this job I had to convert Tangle 4.1 and Weave 4.4 to the
TopSpeed Pascal.  One of the other WEB programs I work with is
DVIAPS.  This is a propritary program that we bought from ArborText.
It takes .dvi files and converts them to .icl files for our
Aps typesetters.  I have extensively re-written DVIAPS.  It now works
with Borland Pascal 7.0 using the Dos Extender provided by Borland.
 
I have also started work on re-writing MANGLE and MEAVE, the Modula 2
versions of Tangle and Weave.  Personally, I think Mangle and Meave
are totally useless as they currently stand.
 
One of the things I want to do is write a version of Tange/Weave to
work with PAL.  I do a LOT of database programming in Paradox.
 
/--------------------------------------------------------------\
|  Jeffrey McArthur             ATLIS Publishing               |
|  phone: (301) 210-6655        12001 Indian Creek Court       |
|  fax:   (301) 210-4999        Beltsville, MD  20705          |
|  EMAIL: j_mcarthur@bix.com                                   |
|                                                              |
| "The man who fights for his ideals is the man who is alive." |
|      Cervantes, author of Don Quixote                        |
\--------------------------------------------------------------/
 
From Dominique Fri May 14 10:03:39 +0200 1993
Date: Fri, 14 May 93 10:03:39 +0200
From: Dominique Dumont / GND <domi@desire.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@DESIRE.GRENOBLE.HP.COM
To: LitProg@SHSU.edu, sboyle@wv.MENTORG.COM
Subject: Re: Anybody there?
 
In message <9305132005.AA26564@porkface.mentorg.com> you write:
> I suppose that the next battle I'm up against is a manager who believes that
> all staff members should use Frame (I think it's supposed to be another
> productivity tool...) so that we can share documents.  Unfortunately, this
> system doesn't fit very well into that paradigm.  What is worse, my position
> of having a tool which produces a document which in turn makes a code review
> a breeze is somehow untenable.
> 
Yep, I think I'm going to have the same problem. Most people think that if it's 
wysiwig it's better. But that heavily depends on the way you think and on the 
way you work. But now I'm preaching people who are already converted ...
 
BTW, if you want to know what I'm currently doing , I've quit hardware
devellopment and now I'm learning all I need to know about software 
(C++, smart methodologies [zut, how can I fit web in these ?], AIN,TMN ...)
Wish me luck I'm gonne be quite busy the next few months.
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From coates@spectro.jussieu.fr Fri May 14 13:20:05 +0200 1993
Date: Fri, 14 May 93 13:20:05 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu
Subject: What am I doing?
 
Dear Litproggers,
	I don't know if I have mentioned what I use FunnelWeb for, but I might
anyway, since it seems a little different from what most do.  My aim is to
create 'all-in-1' papers, where imbedded in the text for the paper is the code
which generates the results.  So far, this is little different to what anyone
else does.  The main difference is that I then want the results of the programs
inserted into the paper.  To achieve this, a common route is
(i) FunnelWeb generates a Maple file for the calculations and a '.ptx' file
    for LaTeX without results (.ptx is my own choice, signifying pre-TeX).
(ii) The Maple file is run and generate a small Maple-loadable library of
     results
(iii) The .ptx file is then processed by Dougal Scott's texproc program, which
      he kindly sent to me.  This program searches a TeX file for a set of
      commands bracketted by special comment lines, runs the text through the
      selected program, and then replaces the text with the result of the
      program.  For me, for each set of results, Maple is run and the library
      of results loaded.  At the appropriate point in the file, the appropriate
      results are automatically converted by Maple into LaTeX by some routines I
      wrote (I didn't like the LaTeX code generated by the 'latex' function
      supplied with LaTeX).
(iv) Finally, I end up with a LaTeX file with all the source code and results
     together.
 
	Perhaps the main area in which the current languages don't support such
a process is it is assumed that the TeX code with the documentation is to remain
immutable, and so, in FunnelWeb at least, one can't use macros within the TeX
code itself, only within the code sections.  For my application, this is
sometimes a nuisance, because I want macros, but the TeX ones won't work until
too late in the process, and the FunnelWeb ones won't allow me to affect the
text.  So any change in macros to change the document involves *2* sets of
macros, one for FunnelWeb, and one for LaTeX.  That said, I am very happy with
FunnelWeb, and I can hardly complain at my using it for something that it wasn't
really designed for.
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From bos@mdd.comm.mot.com Fri May 14 12:26:42 PDT 1993
Date: Fri, 14 May 93 12:26:42 PDT
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
To: LitProg@SHSU.edu, sboyle@wv.mentorg.com
Subject: re: Anybody there?
 
In a message dated 14 May 93 from Dominque Dumont
 
> 
> 
> In message <9305132005.AA26564@porkface.mentorg.com> you write:
> > I suppose that the next battle I'm up against is a manager who believes that
> > all staff members should use Frame (I think it's supposed to be another
> > productivity tool...) so that we can share documents.  Unfortunately, this
> > system doesn't fit very well into that paradigm.  What is worse, my position
> > of having a tool which produces a document which in turn makes a code review
> > a breeze is somehow untenable.
> > 
> Yep, I think I'm going to have the same problem. Most people think that if it's 
> wysiwig it's better. But that heavily depends on the way you think and on the 
> way you work. But now I'm preaching people who are already converted ...
> 
 
I just present a seminar on using LP to other fellow software engineering
students.  Most of my peers were hostile to LP and didn't like the idea
of code reviews using weave output.  Most of the reasons revolved around
not seeing the code directly, WYSIWIG, and the idea of writing english
and not compiler constructs. Now, if we are the current crop of SE's and
the future (?) crop of managers - LP still has a lot of persuading to do.
My peers might listen if the cost/benefits for LP (and WEB) were documented
versus the cost/benefits for the standard code construction (and documentation).
 
The positive side was WEB fits in well with the Object Oriented Programming
packaging on non-objected oriented compilers.  
 
Mary Bos
bos@mdd.comm.mot.com
bos@calvin.seattleu.edu
 
From leew@cs.utexas.edu Fri May 14 15:35:01 -0500 1993
Date: Fri, 14 May 1993 15:35:01 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, sboyle@wv.mentorg.com
Subject: re: Anybody there?
 
Sean Boyle writes:
 
  > Being a plebe to literate programming, I am still fiddling around.  I think
  > I've figured out that I like funnelWeb as I can use it for any arbitrary
  > language and it doesn't muck with it too bad.  I'm not fond of losing my tab
  > key, sigh...
 
You might want to try Noweb.  It's also language-independent, and in
addition, it allows you to specify tab stops (somewhat) with the -t
option.
 
  > Is there a review of the various systems out there somewhere?
 
Dunno. 
 
  > I'd certainly like to see some good examples of literate programming so that
  > I can establish a discipline.  I've seen the bibliography listing and it
  > looks rather extensive.  It would be nice if some of the stuff was online
  > where I could get at it.
  > 
  > I suppose it is all new enough that there aren't a lot of hard and fast rules,
  > but there must be some scars that others *could* show me to save me from
  > some grief.  I appreciate the comments on style which the funnelWeb user's
  > guide points out, but I'd like more.
 
Actually, one of the things I like about literate programming is
finding my own style guidelines.  I've found that I usually write a
first draft pretty much as ``stream of consciousness.''  Once I get it
working, I look at how lousy the structure is, and redo it (which
isn't as hard as it sounds, since most of the code chunks remain the
same; I only reorganize the explanations).
 
I think that recognizing good programming (or webbing) style requires
more reading than writing of programs.  In particular, I think this
comes from reading other peoples' programs (to which one has no
emotional attachment), and critiquing (sp?) them.  Some people can do
this for their own programs, but it's always easier to criticize someone
else's work.
 
I would be willing to compile an "Elements of Good Webbing Style"
list, and ``publish'' it via this discussion group, if people are
willing to send me (direct) lists of rules they've found useful.
Anyone who has such rules, please condense them to a short, simple
statement, and send them to me, along with a brief explanation of
how the rule is useful.  I'll compile them and post them to the list
in a week or two.  Also, let me know if you wish your contribution to
be anonymous, as I intend on crediting each contribution to its
original author (if you wish to be known as a contributor to the list,
but don't wish your name to be directly linked to your rules, we can
do that as well).
 
  > I suppose that the next battle I'm up against is a manager who believes that
  > all staff members should use Frame (I think it's supposed to be another
  > productivity tool...) so that we can share documents.  Unfortunately, this
  > system doesn't fit very well into that paradigm.  What is worse, my position
  > of having a tool which produces a document which in turn makes a code review
  > a breeze is somehow untenable.
 
I've got the same problem here (at Tipton Cole + Co., not UT Austin).
Two of us are producing lovely code using Noweb, but our boss and
another of our programmers are confirmed WYSIWYGers and can't be
bothered learning TeX.  The other programmers are interested in LP,
but are willing to go either way.  The boss is willing to do LP if he
can use Word for Windows, but is unwilling to see the advantages of
Noweb over WinWordWEB (automatic cross-referencing, RCS/PVCS version
control, freedom from Microsoft's whims, etc.).
 
I seem to recall someone mentioning that they were working on a WEB
system for Framemaker (or is that different than Frame -- it's hard to
keep things straight these days).  You may have to end up doing what I
did with Word for Windows -- developing your own Frame-based WEB
system.  WinWordWEB is primitive (Word's macro language doesn't permit
more), but it does the job, and it's better than no webbing at all.
A show of hands please:  How many of you out there have gotten so spoiled
by literate programming that you'll fight to the death rather than
program without your LP tools?  [Notice that my hand is raised.]
 
		-- Lee
 
From leew@cs.utexas.edu Fri May 14 15:58:37 -0500 1993
Date: Fri, 14 May 1993 15:58:37 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, j_mcarthur@bix.com
Subject: Re: What are other litproggers doing out there?
 
Jeffrey McArthur writes:
 
  > One of the things I want to do is write a version of Tange/Weave to
  > work with PAL.  I do a LOT of database programming in Paradox.
 
I spent a couple of months last year trying to use Spidery WEB to
generate a WEB system for PAL.  I gave it up when I discovered how
incredibly convoluted PAL syntax is.  Some keywords are reserved, some
aren't, and *so much* depends on context.  Spaces are significant in
some places but not in others, and it usually takes a bit of semantic
(in addition to syntactic) analysis to determine the appropriate
situation.  However, we do a lot of PAL programming here, and I am
loath to give up literate programming merely because of an intractable
language (see my previous reply to Sean Boyle's note).  I use Noweb
for all my PAL (and ObjectPAL) programming.  It works beautifully
(although the code is typeset as prettily as CWEB, FWEB, Spidery WEB,
etc.).  In fact, my boss is taking a notebook entitled "Literate
Programming in PAL and ObjectPAL" (containing about half a dozen 
Noweb PAL programs) to the Borland Conference in San Diego next week
in order to show around (and incite as much interest as possible in LP
techniques).  I am also trying to get the Paradox Informant to publish
one of my programs as an article.  Anyway, I know of 3 people
(including myself) who are doing literate programming in PAL.  Two of
us are using Noweb, and the third is using WinWordWEB (and has yet to
complete his first literate program, although I will admit what he has
so far looks pretty impressive).
 
I should also mention that, as far as I can tell, FunnelWEB is also a
worthwhile choice for PAL programming, although I've never actually
used it.  Noweb works perfectly for PAL, plus it allows me to use
LaTeX (I think FunnelWEB is restricted plain TeX, but I could be
wrong).  Noweb is available via anonymous ftp from bellcore.com (I
forget the directory).  I don't know where FunnelWEB is accessible
from, but I'm sure someone else on the net will know.
 
Hope this helps.
 
		-- Lee
 
From tfj@apusapus.demon.co.uk Fri May 14 21:03:14 GMT 1993
Date: Fri, 14 May 93 21:03:14 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: Re: Anybody there?
 
In message <m0nthQA-0005QOC@satyr.sylvan.com> you write:
> Is litprog just being quiet?
 
Yes, sadly. :-(
 
> What are other litproggers doing out there? 
 
Trying to drum up more support by exchanging long mail messages with at
least one other UK netter interested in literate programming.
 
I'm also trying to screw up the courage and ask "Has anyone got a version
of WEB that accepts VAX BASIC?" I'd rather use C/Cweb but the customer (and
the recalcitrant boss) have mandated VAX BASIC. :-| Oh well I've asked it
anyway. :-)
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From humberto@annexstein.csm.uc.EDU Sat May 15 09:14:56 -0400 1993
Date: Sat, 15 May 1993 09:14:56 -0400 (EDT)
From: humberto@annexstein.csm.uc.EDU (Humberto Ortiz Zuazaga)
Reply-To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
To: LitProg@SHSU.EDU, bos@MDD.COMM.MOT.COM
Subject: Code reviews.
 
   Date: Fri, 14 May 93 12:26:42 PDT
   From: bos@mdd.comm.mot.com (Mary Bos)
 
   In a message dated 14 May 93 from Dominque Dumont
   well into that paradigm.  What is worse, my position > > of having
   a tool which produces a document which in turn makes a code review
   > > a breeze is somehow untenable.  > > > Yep, I think I'm going to
 
   I just present a seminar on using LP to other fellow software
   engineering students.  Most of my peers were hostile to LP and
   didn't like the idea of code reviews using weave output.  Most of
   the reasons revolved around not seeing the code directly, WYSIWIG,
   and the idea of writing english and not compiler constructs. Now,
   if we are the current crop of SE's and the future (?) crop of
   managers - LP still has a lot of persuading to do.  My peers might
   listen if the cost/benefits for LP (and WEB) were documented versus
   the cost/benefits for the standard code construction (and
   documentation).
 
I think thay might have a point.  Woven code that uses \lnot and \neq
in the code takes some getting used to.  I think language constructs
should not be translated (or optionally translated).  In addition, it
takes a little time to get used to the out of order presentation of
the code, but with a little work on document structure, and by
presenting related sections close together the ordering can be a boon.
 
A poorly woven web is worse than a mediocre non-literate program, and
I was very poor at weaveing for a long time (and I already was good at
programming).  The added complexity does make for less understandable
programs until the idiom is mastered. (I still think I need some work
at web structure.)
--
Humberto Ortiz Zuazaga                                zuazaga@ucunix.san.uc.edu
 
From coates@spectro.jussieu.fr Sat May 15 18:35:21 +0200 1993
Date: Sat, 15 May 93 18:35:21 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu
Subject: FunnelWeb and LaTeX
 
Dear Litproggers,
	Lee Wittenberg writes
> ... stuff deleted ...
> I should also mention that, as far as I can tell, FunnelWEB is also a
> worthwhile choice for PAL programming, although I've never actually
> used it.  Noweb works perfectly for PAL, plus it allows me to use
> LaTeX (I think FunnelWEB is restricted plain TeX, but I could be
> wrong).  Noweb is available via anonymous ftp from bellcore.com (I
> forget the directory).  I don't know where FunnelWEB is accessible
> from, but I'm sure someone else on the net will know.
> 
> Hope this helps.
> 
> 		-- Lee
> 
	A few folks have commented about FunnelWeb and LaTeX.  As a FunnelWeb
user, let me point out that FunnelWeb was constructed with the idea of being
independent of the choice of formatting language, and so has it's own concept
of sections, subsections, etc.  Despite that, to date the only formatter it
supports is TeX.  However, it is possible to tell FunnelWeb (as I do) to forget
about it's own formatting conventions and just treat the text as a TeX file.
This is my preference; I find LaTeX's own sectioning comments fine for what I
want.  Yes, LaTeX, because once you tell FunnelWeb that you are writing in TeX,
you can write in LaTeX and just process the resulting text file in LaTeX.  Other
that a slight sensitivity about needing to place FunnelWeb macros after the 
\begin{document} line (I use the LaTeX 'article' style, but this is not at all
obligatory), there are no problems at all.
	For those who would rather use FunnelWeb's own sectioning commands with
LaTeX, I remember that in fact someone did write the appropriate code to
support this, but I can't remember who now (I don't use these sectioning
commands, so I don't use this code); can someone remind us who did the 
conversion, and where it is?
	In any case, I don't myself think that there is any bar to stop LaTeX
users working with FunnelWeb, though I would be interested in any opinions to
the contrary.
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From preston@cs.rice.edu Sat May 15 13:09:39 CDT 1993
Date: Sat, 15 May 93 13:09:39 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: code reviews
 
   I just present a seminar on using LP to other fellow software
   engineering students.  Most of my peers were hostile to LP and
   didn't like the idea of code reviews using weave output.
 
This is all wrong.
We've been doing walkthroughs with poorly-documented C, heavily
documented C, and woven cweb.  The cweb was far and away the best.
The indices and crossreferences are worth my weight in gold.  
Get 'em to actually try it try a walkthrough.
 
   if we are the current crop of SE's and the future (?) crop of
   managers - LP still has a lot of persuading to do.
 
This is fairly depressing.  If they worked for me, they'd be last
week's crop of SE's.  Not so much because they don't obey my every
whim, but because they don't recognize good ideas when they see them.
 
Preston Briggs
 
From Paul Sat May 15 15:06:42 -0400 1993
Date: Sat, 15 May 1993 15:06:42 -0400
From: Paul Prescod <papresco@undergrad.math.uwaterloo.ca>
Reply-To: LitProg@SHSU.edu, papresco@UNDERGRAD.MATH.UWATERLOO.CA
To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
Subject: Modula-3
 
Is there anyone out there doing literate programming for Modula-3?
 
What tools exist, and how well do they work?
 
From Matthias Sun May 16 15:36:27 +0200 1993
Date: Sun, 16 May 1993 15:36:27 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Re: Modula-3
 
In message <93May15.150650edt.43222-3@undergrad.math.uwaterloo.ca>
Paul Prescod <papresco@undergrad.math.uwaterloo.ca> writes:
>Is there anyone out there doing literate programming for Modula-3?
>
>What tools exist, and how well do they work?
 
I have no actual experience with Modula-3, but if I were looking for tools, I
would consider either doing a Spidery Web grammar or a modification of MWEB.
 
Matthias
 
-----
Matthias Neeracher                                neeri@iis.ee.ethz.ch
   "One fine day in my odd past..." -- Pixies, _Planet of Sound_
 
From Timothy Sun May 16 18:21:08 BST 1993
Date: Sun, 16 May 93 18:21:08 BST
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu, tim@MATHS.TCD.IE
To: LitProg@shsu.edu, neeri@iis.ee.ethz.ch
Subject: Re: Modula-3
 
> >Is there anyone out there doing literate programming for Modula-3?
> >What tools exist, and how well do they work?
> 
> I have no actual experience with Modula-3, but if I were looking for tools, I
> would consider either doing a Spidery Web grammar or a modification of MWEB.
 
It may be worth noting that OzTeX is written in Modula-2,
using a Modula-2 modification of tangle, I think.
(The sources are all available.)
 
Timothy Murphy  
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From ae1181t@stnfor.ae.ge.com Sun May 16 18:17:40 -0400 1993
Date: Sun, 16 May 1993 18:17:40 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
Subject: Re: Anybody there?
 
Hi, use language independent tools :  funnelweb,noweb,nuweb,clip(msdos only).
If you like indices and automatic code prettyprinting and have time try spider
web but you may have to build one for basic (200-300 lines of specs). 
Osman
 
From leew@cs.utexas.edu Mon May 17 10:56:29 -0500 1993
Date: Mon, 17 May 1993 10:56:29 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, tfj@apusapus.demon.co.uk
Subject: Re: Anybody there?
 
Trevor Jenkins asks:
 
  > I'm also trying to screw up the courage and ask "Has anyone got a version
  > of WEB that accepts VAX BASIC?" I'd rather use C/Cweb but the customer (and
  > the recalcitrant boss) have mandated VAX BASIC. :-| Oh well I've asked it
  > anyway. :-)
 
You might want to try Noweb, or FunnelWEB, or one of the other language-
independent LP systems.  If you want beautifully typeset code, you
might want to build your own BasicWEAVE/TANGLE with Spidery WEB.  A
language like Basic, with a fairly simple syntax, should be relatively
easy to generate a Spidery grammar for. 
 
Noweb is available via anonymous ftp from bellcore.com (I forget the
directory), Spidery WEB from pip.shsu.edu (tex-archive/web/spiderweb).
I'm afraid I don't know where FunnelWEB is available.
 
		-- Lee
 
P.S. Noweb has a feature that is nice if your boss (and customer)
decide that you have to ``give up this literate programming
nonsense.''  It comes with a tool called ``nountangle'' that tangles
your code into a program (as the regular notangle does), but includes
your internal documentation as program comments in the appropriate
places.  This allows you to experiment with LP, and in Norman Ramsey's
words, ``If the experiment is unsatisfying, it is easy to abandon,
because {\tt notangle}'s output, unlike {\tt TANGLE}'s is readable.''
 
Personally, I'd try building a Spidery WEB first.  I'm partial to
the better typesetting of code in the language-dependent WEB
systems, but that's a matter of personal taste.
 
From leew@cs.utexas.edu Mon May 17 11:11:27 -0500 1993
Date: Mon, 17 May 1993 11:11:27 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, humberto@annexstein.csm.uc.edu
Subject: Re: Code reviews.
 
Humberto Ortiz Zuazaga writes:
 
  >    In a message dated 14 May 93 from Dominque Dumont
  >    well into that paradigm.  What is worse, my position > > of having
  >    a tool which produces a document which in turn makes a code review
  >    > > a breeze is somehow untenable.  > > > Yep, I think I'm going to
  > 
  >    I just present a seminar on using LP to other fellow software
  >    engineering students.  Most of my peers were hostile to LP and
  >    didn't like the idea of code reviews using weave output.  Most of
  >    the reasons revolved around not seeing the code directly, WYSIWIG,
  >    and the idea of writing english and not compiler constructs. Now,
  >    if we are the current crop of SE's and the future (?) crop of
  >    managers - LP still has a lot of persuading to do.  My peers might
  >    listen if the cost/benefits for LP (and WEB) were documented versus
  >    the cost/benefits for the standard code construction (and
  >    documentation).
  > 
  > I think thay might have a point.  Woven code that uses \lnot and \neq
  > in the code takes some getting used to.
 
I agree with Humberto's observation, but think it's interesting that \lnot and
\neq (and \land, and \lor, etc.) should ``take some getting used
to.''  After all, the corresponding symbols NOT/!, <>/!=,
AND/&&/.AND., etc. were chosen simply because early card and tape
punches did not provide the necessary standard mathematical symbols!
Take a look at the Algol-60 Revised Report, with its hardware,
reference, and publication languages, and notice that the publication
language allows things like Greek letters as identifiers and raised
exponents.  Note also that the REFERENCE language used the standard
mathematical symbols for \neq, \lor, \times (!), etc.  It was only in
the hardware language that concessions were made to the machine.
 
We've gotten into the habit of designing our languages around machine
needs rather than human needs.  I see literate programming as a way of
going back to the latter (I say ``going back'' primarily because of
Algol-60).  Let's start designing new programming languages with an
eye for human readability, using standard symbols that have been
around for hundreds (sometimes thousands) of years (e.g. \times and
\neq) rather than those that have been around for less than 50 (e.g. *
and <>).
[End of Tirade]
 
		-- Lee
 
From leew@cs.utexas.edu Mon May 17 11:20:24 -0500 1993
Date: Mon, 17 May 1993 11:20:24 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, preston@cs.rice.edu
Subject: Re: code reviews
 
Preston Briggs writes:
 
  >    if we are the current crop of SE's and the future (?) crop of
  >    managers - LP still has a lot of persuading to do.
  > 
  > This is fairly depressing.  If they worked for me, they'd be last
  > week's crop of SE's.  Not so much because they don't obey my every
  > whim, but because they don't recognize good ideas when they see them.
 
Unfortunately, most bosses are not as open as Preston (and the guy I'm
working for this year while on sabbatical).  It seems to come down to
my father's theory of middle management:  ``It's easier for a middle
manager to say `no,' because that way he (or she) can't get into
trouble with the higher-ups.  Saying `yes' involves sticking one's
neck out.''
 
		-- Lee
 
From Kayvan Mon May 17 22:02 PDT 1993
Date: Mon, 17 May 93 22:02 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
Subject: re: Anybody there?
 
>>>>> "Lee" == Lee Wittenberg <apple!cs.utexas.edu!leew> writes:
 
Lee> A show of hands please:  How many of you out there have gotten so spoiled
Lee> by literate programming that you'll fight to the death rather than
Lee> program without your LP tools?  [Notice that my hand is raised.]
 
My hand is raised too.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Joachim Tue May 18 17:09:42 +0100 1993
Date: Tue, 18 May 1993 17:09:42 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu
Subject: Re: What are other litproggers doing out there?
 
Lee wrote:
> 
> Noweb is available via anonymous ftp from bellcore.com (I
> forget the directory).  I don't know where FunnelWEB is accessible
> from, but I'm sure someone else on the net will know.
 
Many of the literate programming systems are available from the
LitProg archive at Darmstadt:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming
 
The usual TeX archives (eg, SHSU and Aston) carries also a lot.
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From infmx!grodecki@uunet.UU.NET Tue May 18 11:45:17 CDT 1993
Date: Tue, 18 May 93 11:45:17 CDT
From: infmx!grodecki@uunet.UU.NET (Don Grodecki)
Reply-To: LitProg@SHSU.edu, infmx!grodecki@UUNET.UU.NET
To: uunet!SHSU.edu!LitProg@uunet.UU.NET, uunet!CS.UTEXAS.EDU!leew@uunet.UU.NET
Subject: Re: code reviews
 
> From uunet!SHSU.edu!LP-Mgr Mon May 17 20:44:08 1993
> X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
> Warnings-To: <>
> Sender: uunet!SHSU.edu!LP-Mgr
> From: uunet!cs.utexas.edu!leew (Lee Wittenberg)
> Reply-To: uunet!SHSU.edu!LitProg, uunet!CS.UTEXAS.EDU!leew
> Date: Mon, 17 May 1993 11:20:24 -0500
> To: LitProg@shsu.edu, preston@cs.rice.edu
> Subject: Re: code reviews
> 
> Preston Briggs writes:
> 
>   >    if we are the current crop of SE's and the future (?) crop of
>   >    managers - LP still has a lot of persuading to do.
>   > 
>   > This is fairly depressing.  If they worked for me, they'd be last
>   > week's crop of SE's.  Not so much because they don't obey my every
>   > whim, but because they don't recognize good ideas when they see them.
> 
> Unfortunately, most bosses are not as open as Preston (and the guy I'm
> working for this year while on sabbatical).  It seems to come down to
> my father's theory of middle management:  ``It's easier for a middle
> manager to say `no,' because that way he (or she) can't get into
> trouble with the higher-ups.  Saying `yes' involves sticking one's
> neck out.''
This is probably why the current theories are to "flatten" middle 
management out of the structure.  (PS: I am a middle manager who loves LitProg)
> 
> 		-- Lee
> 
 
From preston@cs.rice.edu Wed May 19 16:49:02 CDT 1993
Date: Wed, 19 May 93 16:49:02 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: language-independent indices
 
One of the winning features of web and cweb (and perhaps other
systems) is their automatically-constructed indices of source code
identifiers.  It's a great convenience, during code maintanence and
code walkthroughs, to be able to find where a procedure is defined and
used.
 
Unfortunately, language-independent web systems (Funnelweb, noweb,
nuweb, others?) don't build these indices automatically because they
can't know what an identifier looks like in each particular language.
For example, x_1 is a 3-letter id in C, but an expression in TeX.
+ is a valid id in some scheme systems.
 
As an experiment, I've modified nuweb to support semi-automatic index
construction. Basically, the programmer specifies each entry as it's
defined and nuweb finds all the other occurences (the references).
 
For example, if I've got a very short nuweb file
---------------------
Here's scrap 1
@o test
@{We are going to look for occurences of "he", "she", "his", and
"hers".  I'll mark them as defined in this scrap and let nuweb find
references to them in any other scraps. They're listed at the end of
the scrap, separated by whitespace.
@| he she his hers @}
 
And scrap 2
@o test
@{This is a test.
For the next sixty seconds...
@}
 
And scrap 3
@o test
@{She sells seashells by the seashore.
@}
---------------------
We'll get index entries
 
	he	1, 2, 3.
	hers	1.
	his	1, 2.
	she	1, 3.
 
(where the 1's are underlined).
 
I collect all the index entries during the first pass, while
accumulating all the scraps, and record their definition points.  Then
I build a finite automata that can search for all of the entries
simultaneously.  Finally, I use it to search through each scrap in
sequence, recording all occurences of each entry as a use (but
avoiding duplicates).  The string searcher is described in
 
	Efficient String Matching: An Aid to Bibliographic Search
	Aho and Corasick
	CACM, June 1975
 
There are advantages over the approach used by web and cweb, primarily
in that the index is much more controlled.  I find it useful to
include procedures, typedefs, and global variables.  I don't care so
much about the hordes of local variables I use everywhere.
 
Of course, simply using string equality isn't perfect.
If we're looking for the entry "arena", any occurence of
"arena_getmem" will also be flagged.  So far, I'm not too concerned
about these cases; perhaps further experience will suggest
alternatives.
 
Preston Briggs
 
From coates@spectro.jussieu.fr Thu May 20 12:26:48 +0200 1993
Date: Thu, 20 May 93 12:26:48 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu, preston@cs.rice.edu
Subject: Re: language-independent indices
 
Preston Briggs writes:
 
> One of the winning features of web and cweb (and perhaps other
> systems) is their automatically-constructed indices of source code
> identifiers.  It's a great convenience, during code maintanence and
> code walkthroughs, to be able to find where a procedure is defined and
> used.
> 
> Unfortunately, language-independent web systems (Funnelweb, noweb,
> nuweb, others?) don't build these indices automatically because they
> can't know what an identifier looks like in each particular language.
> For example, x_1 is a 3-letter id in C, but an expression in TeX.
> + is a valid id in some scheme systems.
 
I can't comment about other WEB systems, but for FunnelWeb users, global
variables and the like can by marked by enclosing each of them in it's own 
macro, which FunnelWeb then indexes.  This may not be the most elegant solution,
but if the number of global variables, procedures, or whatever is not too large,
it should be perfectly sufficient.  Anyway, just a quick thought.
 
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From Richard Thu May 20 22:14:46 +1000 1993
Date: Thu, 20 May 1993 22:14:46 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu, Richard.Walker@CS.ANU.EDU.AU
To: LitProg@SHSU.edu
Subject: Re: language-independent indices
 
Tony writes:
 
>I can't comment about other WEB systems, but for FunnelWeb users,
>global variables and the like can by marked by enclosing each of
>them in it's own macro, which FunnelWeb then indexes.  This may
>not be the most elegant solution, but if the number of global
>variables, procedures, or whatever is not too large, it should be
>perfectly sufficient.  Anyway, just a quick thought. 
 
Yep, that's right.  I have made a quick modification to FunnelWeb
and some changes to my LaTeX macros to do indexing of sections
and files - it works quite well.  I'm a bit reluctant to release
it as yet as I'm still working out if it's a good idea (plus
I'm not sure of copyright, etc.).
 
Richard.
 
From ae1181t@stnfor.ae.ge.com Thu May 20 09:19:51 -0400 1993
Date: Thu, 20 May 1993 09:19:51 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: litprog@shsu.edu
Subject: language-independent indices
 
I think to cover all the bases will be difficult at best. The example
Preson gave "arena_getmem" being flagged by an index entry for ``arena''
is a good one : in C arena_getmem is an identifier while in gnu smalltalk
it is an assignment statement like arena := getmem! It looks like using
LaTeX and  user interaction is necessary for the language-independent 
``WEB''s. However, I think nuweb's method of index collecting is better
than the one suggested for the funnelweb users (namely use macros for
each index entry); you are not cluttered with a macro for every global
variable! Even with the new additions, the nuweb users' manual is still
3-4 pages with only a 6 or so commands to learn, and one program that
both tangles and weaves, and uses LaTeX. Looks like a winner to me!
Osman
 
From coates@spectro.jussieu.fr Thu May 20 16:10:53 +0200 1993
Date: Thu, 20 May 93 16:10:53 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu, ae1181t@stnfor.ae.ge.com
Subject: Re: language-independent indices
 
Osman F Buyukisik writes
 
> I think to cover all the bases will be difficult at best. The example
> Preson gave "arena_getmem" being flagged by an index entry for ``arena''
> is a good one : in C arena_getmem is an identifier while in gnu smalltalk
> it is an assignment statement like arena := getmem! It looks like using
> LaTeX and  user interaction is necessary for the language-independent 
> ``WEB''s. However, I think nuweb's method of index collecting is better
> than the one suggested for the funnelweb users (namely use macros for
> each index entry); you are not cluttered with a macro for every global
> variable! Even with the new additions, the nuweb users' manual is still
> 3-4 pages with only a 6 or so commands to learn, and one program that
> both tangles and weaves, and uses LaTeX. Looks like a winner to me!
> Osman
> 
 
With regard to my suggestion that FunnelWeb users could use a macro for each
index entry, I did mention that it would work for a *not too many* global 
variables or procedures.  If you use hundreds of global variables (naughty you!)
then this method would almost certainly be a nuisance (essentially 4 extra
keystrokes for each identifier, plus you may not like all the cross-references
in the middle of the program output).
 
	In any case, I wasn't meaning to take anything away from nuweb, nor
suggesting that FunnelWeb macros were equivalent.  I was just pointing out the
quickest alternative I could think of for FW users, and noting that in some
cases it may be sufficient at the lower end of things.
 
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of these two sets is probably empty."
________________________________________________________________________________
 
From preston@cs.rice.edu Thu May 20 09:49:57 CDT 1993
Date: Thu, 20 May 93 09:49:57 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: identifiers indices
 
Tony Coates suggested wrapping each global variable declaration
(function declaration, type decalration, ...) in it's own private
macro as a way to achieve an index of identifiers.
(in the context of FunnelWeb).
 
I don't much like this because I'll need to use the macro name
everywhere instead of the variable/procedure/type name.
That is, I don't have to use the macro name; but if I use the variable
name, it won't appear in the index.
 
@<Seems@> @<like@> @<a@> @<lot@> @<of@> @<overhead@> @<to@> @<me@>
 
Preston Briggs
 
From ae1181t@stnfor.ae.ge.com Thu May 20 16:32:02 -0400 1993
Date: Thu, 20 May 1993 16:32:02 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, dthompson@coe2.coe.ttu.edu.ae.ge.com.ae.ge.com
Subject: RE: language-independent indices
 
I obtained nuweb from the author Preston Briggs (preston@cs.rice.edu).
It came as a shar file. Runs on unix (I  have Hp 710 hpux 8.07), dos
using djgpp (port of gcc to dos). I did not have to make any changes to 
run it under dos, so probably very portable if you have a form of gcc.
You also need LaTeX to get anything out of it. 
 
From David Thu May 20 13:36:00 PDT 1993
Date: Thu, 20 May 93 13:36:00 PDT
From: David Thompson <dthompson@coe2.coe.ttu.edu>
Reply-To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU
To: LitProg <litprog@shsu.edu>
Subject: RE: language-independent indices
 
Osman writes:
 
> However, I think nuweb's method of index collecting is better than the one 
 
> suggested for the funnelweb users (namely use macros for each index 
entry);
> you are not cluttered with a macro for every global variable!
 
I've seen nuweb mentioned on the mailing list several times.  However, I 
don't recall a source for the software.  Where is this software available 
and what platforms does it run on?
 
 -=d
 
David B. Thompson                             internet: wqdbt@ttacs1.ttu.edu
Assistant Professor of Civil Engineering      internet: 
dthompson@coe2.coe.ttu.edu
Texas Tech University                         internet: 
thompson@sun1.coe.ttu.edu
P.O. Box 41023
Lubbock, Texas 79409-1023
USA
 
From preston@cs.rice.edu Thu May 20 16:54:07 CDT 1993
Date: Thu, 20 May 93 16:54:07 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, dthompson@coe2.coe.ttu.edu
Subject: RE: language-independent indices
 
 David Thompson asked about nuweb.
I give it away to anyone who asks.
I'm still hacking on it, mostly trying to document the code,
so I haven't yet put it out for ftp at shsu.
 
It's written in C.  I run it on Unix and AIX.
Needs latex (based on TeX version 3.0 or up).
Probably an easy port to other machines, but I haven't tried.
 
If you'd like an early release, send me a note
 
Preston Briggs
 
From marcus@x4u.desy.de Mon May 24 19:59:52 +0200 1993
Date: Mon, 24 May 93 19:59:52 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: Literate Programmers <litprog@shsu.edu>
Subject: LitProg on the World Wide Web [regular posting]
 
[[This is a regular posting to LitProg mailing list and Comp/TeX discussion
  groups, formatted for Emacs outline mode. Cut here and copy rest to file.]]
 
-----------------------------------------------------------------------------
* Literate Programming on the World Wide Web
-----------------------------------------------------------------------------
   FYI, there is a wealth of information on Literate Programming,
   the art of structured programming and documentation [especially
   using WEB-like systems with TeX formatting] available on the
   World Wide Web [WWW], a distributed HyperText system, a network
   of documents connected by links which can be activated electronically.
   Examples for LitProg environments are WEB for Pascal (DEK), CWEB for C/C++
   (Levy/Knuth), FWEB for C/C++/Fortran/ratfor/TeX (Krommes)...and many more.
-----------------------------------------------------------------------------
* How to get to the Web
-----------------------------------------------------------------------------
   If you have a WWW browser up and running, try going to
 
		        http://info.desy.de:80/
 
   (this brings you to the DESY home page), and look for "User Documents"
   in the panel which appears. The precise URL is
 
	   http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
 
   If you have no clue what WWW is, you can go over the Internet with
 
        	telnet info.cern.ch
 
   which brings you to the WWW Home Page at CERN. You are now using the
   simple line mode browser. To move around the Web, enter the numbers
   given after an item. To go to the Literate Programming documents, enter
 
	go http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
 
   This is what you should see now:
-----------------------------------------------------------------------------
* What you will see here
-----------------------------------------------------------------------------
			 LITERATE PROGRAMMING
 
Getting Started[1]
   A first look into Literate Programming with WEB 
Editing 
   GNU Emacs mode for WEB programming: Sources[2] and 
   Manual[3] (PostScript) 
Tools[4] 
   List of common, freely available Literate Programming
   environments 
Examples[5] 
   Literate Programming archives and selected examples 
LitProg Library[6]
   George D. Greenwade's Literate Programming Library at
   Niord.shsu.edu 
FAQs[7]
   Lists of Frequently Asked Questions for WEB systems 
Further Reading 
   Nelson Beebe's Literate Programming bibliography at
   ftp.math.utah.edu in directory /pub/tex/bib[8] (files litprog.*) 
HyperLitProg[9]
   Literate Programming using HyperText[10] Techniques 
OO-LitProg[11]
   Thoughts on Object-Oriented[12] Literate Programming 
LITPROG Mailing List[13]
   Information on the Literate Programming Mailing List 
 
 [[Now you can continue climbing down the documentation tree by
   entering numbers 1-13 and follow your own interests]]
-----------------------------------------------------------------------------
* More on Browsing the Web
-----------------------------------------------------------------------------
   The by far nicest way of "browsing" through WWW uses the X-Terminal
   based tool "XMosaic". Binaries for many platforms (ready for use)
   and sources are available via anonymous FTP from
   ftp.ncsa.uiuc.edu in directory Web/xmosaic.
     The general FTP repository for browser software is info.cern.ch
  (including a hypertext browser/editor for NeXTStep 3.0)
-----------------------------------------------------------------------------
* Contact for Further Information
-----------------------------------------------------------------------------
   Please feel free to contact me for questions, suggestions and further
   contributions, or just to tell me whether you found this information
   useful in any way. For questions related to WWW, consult the WWW-FAQ:
   Its most recent version is available via anonymous FTP on rtfm.mit.edu
   in /pub/usenet/news.answers/www-faq , or on WWW at
   http://www.vuw.ac.nz:80/overseas/www-faq.html
   Enjoy.
 
  Marcus Speh
  E-mail:  INTERnet: marcus@x4u.desy.de
	   BITnet:   i02msp@dhhdesy3
	   DECnet:   13313::speh
-----------------------------------------------------------------------------
Local Variables:
mode: outline
outline-regexp: "^\*"
eval: (show-all)
End:
 
From Eric Wed May 26 11:34 +0000 1993
Date: Wed, 26 May 1993 11:34 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: Anybody there?
 
On 14-MAY-1993 Lee wrote
 
>A show of hands please:  How many of you out there have gotten so spoiled
>by literate programming that you'll fight to the death rather than
>program without your LP tools?  [Notice that my hand is raised.]
 
Although a bit late, I certainly would like to raise my hand. I have been
using the basic technique for many years and for me it is the most
convincing presentation of a program.
    The big problem I face, and all of us LP-ers expereince the same, is that
we cannot bring to words where exactly is the power of the LP paradigm. I have
several times before argued that we should discuss thIs sort of "phylosophical"
issues on the net. Once again I ask to all of you: Can we somehow make 
explicite the power of LP. Maybe this will finally convince managers to
 
						Eric
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From ralexand@mason1.gmu.edu Wed May 26 18:14:51 -0400 1993
Date: Wed, 26 May 1993 18:14:51 -0400 (EDT)
From: ralexand@mason1.gmu.edu (Roger T Alexander)
Reply-To: LitProg@SHSU.edu, ralexand@MASON1.GMU.EDU
To: litprog@shsu.edu
Subject: CWEB 3.0
 
Does anyone know when cweb 3.0 will be out ?
 
Roger Alexander.
rtalexander@acm.org
 
From ralexand@mason1.gmu.edu Wed May 26 18:16:12 -0400 1993
Date: Wed, 26 May 1993 18:16:12 -0400 (EDT)
From: ralexand@mason1.gmu.edu (Roger T Alexander)
Reply-To: LitProg@SHSU.edu, ralexand@MASON1.GMU.EDU
To: litprog@shsu.edu
Subject: Scientific Word
 
Does anyone know the phone number/address of the vendor for the TeX word
processing package called "Scientific Word" ?
 
Thanks,
 
Roger Alexander (rtalexander@acm.org)
 
From Gerry Wed May 26 17:17:20 MDT 1993
Date: Wed, 26 May 93 17:17:20 MDT
From: Gerry Rohling <rohling@mech.ubc.ca>
Reply-To: LitProg@SHSU.edu, rohling@MECH.UBC.CA
To: LitProg@shsu.edu, ralexand@mason1.gmu.edu
Subject: Scientific Word
 
Hi,
	The vendor for Scientific Word is ARSoftware. I talked to
a Mr. Sat Want Khalsa, who is the manager of marketing. His number
is (301)459-3773 (Fax: (301)459-3776)
 
Hope this helps.
 
Gerry
 
From Nelson Wed May 26 17:17:20 MDT 1993
Date: Wed, 26 May 93 17:17:20 MDT
From: "Nelson H. F. Beebe" <beebe@math.utah.edu>
Reply-To: LitProg@SHSU.edu, beebe@MATH.UTAH.EDU
To: ralexand@mason1.gmu.edu (Roger T Alexander)
Subject: Scientific Word
 
Scientific Word is distributed by 
 
	ARSoftware
	8201 Corporate Driver, Suite 1110
	Landover, MD 20785
	Tel: (310) 459-3773, (800) 257-0073
	FAX: (301) 459-3776
 
Nelson H. F. Beebe                      Tel: +1 801 581 5254
Center for Scientific Computing         FAX: +1 801 581 4148
Department of Mathematics, 105 JWB      Internet: beebe@math.utah.edu
University of Utah
Salt Lake City, UT 84112, USA
 
From David Wed May 26 16:37:00 PDT 1993
Date: Wed, 26 May 93 16:37:00 PDT
From: David Thompson <dthompson@coe2.coe.ttu.edu>
Reply-To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU
To: LitProg <litprog@shsu.edu>
Subject: Help for LitProg FAQ
 
Finally, my semester is over and teaching duties are finished! <yes!!!>  
I've redirected some of my attention to working on a FAQ I promised a few 
months ago.  It's time for some input from developers of literate 
programming tools.
 
If you are a developer or maintainer of a literate programming tool, please 
email me (see addresses below) the following information for inclusion in 
the FAQ.
 
* Name of tool.
* Name and email address of developer or maintainer.
* Hardware and operating system(s) supported.
* Software supported (programming languages/text formatters).
* Pointer to a location where the software can be retrieved via anonymous 
ftp.
* Pointer to a location where a brief document (readme) can be retrieved via 
anonymous ftp.
* A brief description of the tool.  In particular, what does it do, what are 
its strengths,
  what are it's weaknesses, and what future directions development is 
expected to take.
* A description of how support for the software is handled.  (Email, 
snailmail, none, ?)
 
Please, please, please email this information directly to me.  Don't post it 
on the mailing list.  (Of course, the previous statement was unnecessary. 
;-)
 
Thanks for your support.
 
 -=d
 
P.S.  I have a skeleton prepared.  All I need is the above text and a few 
hours to get something together.
 
David B. Thompson                             internet: wqdbt@ttacs1.ttu.edu
Assistant Professor of Civil Engineering      internet: 
dthompson@coe2.coe.ttu.edu
Texas Tech University                         internet: 
thompson@sun1.coe.ttu.edu
P.O. Box 41023
Lubbock, Texas 79409-1023
USA
 
From figuei@lutece.rutgers.edu Thu May 27 10:00:36 -0400 1993
Date: Thu, 27 May 93 10:00:36 -0400
From: figuei@lutece.rutgers.edu (Francisco Figueirido)
Reply-To: LitProg@SHSU.edu, figuei@lutece.rutgers.edu
To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
Subject: Re: formatting examples in CWEB
 
Zdenek Wagner writes:
 
> And now comes the question. The WEB file should contain examples which should
> be formatted in the similar way as the C-part. I do not like to study the
> macros from ``cwebmac.tex'' and dothe formatting by hand. I therefore need
> some trick to put blocks which will be ignored by tangle and formatted like C
> by weave. The trick with
 
I use FWEB rather than CWEB but I would suggest sending the C code to a
separate file (something like dustbin.c). This way tangle will happily throw
them away while weave will format them correctly (this works in FWEB).
 
From Zdenek Thu May 27 09:16:49 MDT 1993
Date: Thu, 27 May 93 09:16:49 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: formatting examples in CWEB
 
Dear LitProggers,
I am writing a C++ pure virtual class in CWEB. The class is intended to be
used by other programmers even those who do not know WEB (they will just get
the tangled code and printed documentation)and also those who are not very
familiar with object oriented programming. Therefore I should supply good
information how they will derive their own classes.
 
And now comes the question. The WEB file should contain examples which should
be formatted in the similar way as the C-part. I do not like to study the
macros from ``cwebmac.tex'' and dothe formatting by hand. I therefore need
some trick to put blocks which will be ignored by tangle and formatted like C
by weave. The trick with
 
@(nul@>=...
 
will not work because I intend to leave some modules unresolved. Imagine the
part of the example:
 
if (errorCode != 0) {
 @<Display error message@>@;
}
 
I will not specify how to display the error message because each programmer
has his own way for managing error messages or even his own libraries. It is
even more evident on data inputand output of results which does not depend
upon the properties of the base class but on the nature of the problem.
 
Is there a solution in CWEB?
 
Thanks in advance for your answers.
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi>
 
From Kayvan Thu May 27 13:38 PDT 1993
Date: Thu, 27 May 93 13:38 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: WAGNER%CSEARN.BITNET@cunyvm.cuny.edu
Subject: formatting examples in CWEB
 
>>>>> "Zdenek" == Zdenek Wagner <apple!CSEARN.BITNET!WAGNER> writes:
 
Zdenek> And now comes the question. The WEB file should contain
Zdenek> examples which should be formatted in the similar way as the
Zdenek> C-part. I do not like to study the macros from ``cwebmac.tex''
Zdenek> and dothe formatting by hand. I therefore need some trick to
Zdenek> put blocks which will be ignored by tangle and formatted like
Zdenek> C by weave. [...]
 
The way that comes to my mind is judicious use of #ifdef directives in
the C part of your code. This will make blocks that are tangled, but
ignored by your C compiler.
 
Zdenek> [...] I intend to leave some modules unresolved. Imagine the
Zdenek> part of the example:
 
Zdenek> if (errorCode != 0) {
Zdenek>  @<Display error message@>@;
Zdenek> }
 
Zdenek> I will not specify how to display the error message because
Zdenek> each programmer has his own way for managing error messages or
Zdenek> even his own libraries. It is even more evident on data
Zdenek> inputand output of results which does not depend upon the
Zdenek> properties of the base class but on the nature of the problem.
 
This would seem to imply that you're attempting to get these other
people to write WEB code that interfaces with yours. Are you? Or are
they going to be writing C++ code that uses the tangled output?
 
I think getting other people to write in WEB in small doses (and
getting them addicted!) is a Good Thing. :-)
 
However, it would seem to be a better solution to provide something
like:
 
    @ This code is for reporting errors. If you |#define DEFAULT| when
    compiling this code, the default error display will be used.
 
    @<Display err...@>=
    #ifdef DEFAULT
    cerr << "!! Error " << errorCode << " encountered.\n";
    #endif
 
That way, if the programmer wants to provide their own WEB additions,
they simply have to not define DEFAULT and *add* a @<Display err...@>=
definition, appending their error handling code to the above fragment.
 
Another solution comes to mind as I'm writing this.
 
The best of all possible worlds, in my opinion, would be to create
default error handlers as C macros and provide a mechanism for users
to override these macros (in a separate include file, perhaps). This
would make for a fully documented standard interface to your code. It
would also mean that consumers would never change the code directly.
 
This would look something like this. Early in your file, you would
define the user-changeable macros (in the C part or the definition
part of your WEB, doesn't matter).
 
    @ These default macros are used throughout the rest of this C++
    class.
 
    @<Generic Macros@>=
    #define ErrorDisplay(errorCode) \
	cerr << "!! Error " << errorCode << " encountered.\n"
 
Then you do something like:
 
    @ User-supplied redefinitions file. If you want to use all the
    defaults, just leave this file empty.
 
    @<User Redefinitions@>=
    #include "local-hacks.h"	// Redefine ErrorDisplay macro, etc.
 
And then later, just do:
 
   @<Display error@>=
   ErrorDisplay(errorCode);
 
The "local-hacks.h" could contain code like this:
 
   #undef ErrorDisplay
   #define ErrorDisplay(errorCode) \
   cerr << "Dude!! I seem to have encountered error " << errorCode << "\n"
 
Hope this helps.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From leew@cs.utexas.edu Fri May 28 15:20:58 -0500 1993
Date: Fri, 28 May 1993 15:20:58 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, ralexand@mason1.gmu.edu
Subject: Re: CWEB 3.0
 
Roger Alexander asks:
 
  > Does anyone know when cweb 3.0 will be out ?
 
Last I heard, it was supposed to be ready in April.  It seems that DEK
is still polishing off a few rough edges.  I suspect it's the C++
grammar that causing most of the problems.  C++ overloads a lot of
keywords (like ``public'') that require different formatting in
different contexts.  If he's trying to deal with templates as well,
he's got his work cut out for him.
 
		 -- Lee
 
From leew@cs.utexas.edu Fri May 28 15:32:16 -0500 1993
Date: Fri, 28 May 1993 15:32:16 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, WAGNER@csearn.bitnet
Subject: Re: formatting examples in CWEB
 
Zdenek Wagner writes:
 
 > Dear LitProggers,
 > I am writing a C++ pure virtual class in CWEB. The class is intended to be
 > used by other programmers even those who do not know WEB (they will just get
 > the tangled code and printed documentation)and also those who are not very
 > familiar with object oriented programming. Therefore I should supply good
 > information how they will derive their own classes.
 > 
 > And now comes the question. The WEB file should contain examples which should
 > be formatted in the similar way as the C-part. I do not like to study the
 > macros from ``cwebmac.tex'' and dothe formatting by hand. I therefore need
 > some trick to put blocks which will be ignored by tangle and formatted like C
 > by weave. The trick with
 > 
 > @(nul@>=...
 > 
 > will not work because I intend to leave some modules unresolved. Imagine the
 > part of the example:
 > 
 > if (errorCode != 0) {
 >  @<Display error message@>@;
 > }
 > 
 > I will not specify how to display the error message because each programmer
 > has his own way for managing error messages or even his own libraries. It is
 > even more evident on data inputand output of results which does not depend
 > upon the properties of the base class but on the nature of the problem.
 > 
 > Is there a solution in CWEB?
 
Even though CWEAVE complains about unresolved modules, it formats them
correctly (with a zero for the section number).  CTANGLE will also
complain, but carry on (expanding nothing into the specified slot,
which is what you want).  I use this facility quite a bit while
building and testing programs in a piecemeal fashion (I did this
yesterday, in fact).  If the problem is that your make program stops when
CTANGLE or CWEAVE exits with a non-zero value, you can do what I do:
change the command line in the makefile to begin with a ``-''.
For example:
 
	.w.tex:
	    -cweave $*
	.w.c:
	    -ctangle $*
 
As far as I know, the @(nul@>=  (or @(/dev/null@>= for Unix types)
should work.  I've thought about it, but never actually had occasion
to try it.
 
		 -- Lee
 
From Kayvan Sat May 29 21:21 PDT 1993
Date: Sat, 29 May 93 21:21 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: litprog@shsu.edu
Subject: Re:  NuWeb
 
Okay, I finally got around to using NuWeb.
 
I just finished converting a perl script I had written in noweb over
to nuweb. It was quick and painless and behaved exactly as I would
have expected.
 
Here are the features that make me recommend it over noweb at this
point for language-independant literate programming.
 
* NuWeb combines weave/tangle into one program (written in NuWeb, of
  course). This small program creates both the LaTeX code and the
  tangle output, and it's fast.
 
* NuWeb takes some care to keep all of a scrap on one page, if
  possible. 
 
* NuWeb lets you create multiple output files, and compares the output
  to avoid overwriting unchanged files (this is nice when you are
  working with make on a large program).
 
* The index of user-defined identifiers. This feature of NuWeb
  compensates in some part for the lack of the automatically generated
  identifier indices present in language-sensitive WEB systems.
 
NuWeb, like noweb, is {\em real} simple to use.
 
Thanks to Preston Briggs for a nice tool!!
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From geb@diktyon.han.de Sun May 30 15:49:42 +0200 1993
Date: Sun, 30 May 1993 15:49:42 +0200 (MET DST)
From: geb@diktyon.han.de (Martin Gebhardt)
Reply-To: LitProg@SHSU.edu, geb@DIKTYON.HAN.DE
To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
Subject: Re: NuWeb
 
Hello,
 
> Okay, I finally got around to using NuWeb.
 
I just wonder why I seem to have missed the original introduction to
NuWeb. It'd be nice if someone could send it to me. (Or if the author
could send me a copy, which is what this may lead to, anyway.)
 
Thanks, Martin.
 
From humberto@annexstein.csm.uc.EDU Tue Jun 01 08:43:10 -0400 1993
Date: Tue, 01 Jun 1993 08:43:10 -0400 (EDT)
From: humberto@annexstein.csm.uc.EDU (Humberto Ortiz Zuazaga)
Reply-To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
To: LitProg@SHSU.EDU
Subject: scraps with explicit arguments?
 
I was showing some noweb'ed C code to a professor the other day, and
he objected to my use of "implicit arguments" in a scrap (or whatever
the politically correct term for "module" is these days).  He would
prefer that scraps could take explicit arguments in their invocation.
Do any of the existing litprog tools have this feature?  I could make
it look like they do by putting the arguments into the scrap name:
 
<<process variables (x, y)>>
 
. . .
 
<<process variables (x, y)>>=
x += y * 23;
 
but perhaps this is a genuinely usefull feature to have.  It looks
like it could permit true inline functions in languages that do not
support them, and help improve the clarity of webbed code by
decreasing reliance on the previously declared variables.
--
Humberto Ortiz Zuazaga                                zuazaga@ucunix.san.uc.edu
 
From ae1181t@stnfor.ae.ge.com Tue Jun 1 10:45:52 -0400 1993
Date: Tue, 1 Jun 1993 10:45:52 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
Subject: Re: scraps with explicit arguments?
 
   Date: Tue, 01 Jun 1993 08:43:10 -0400 (EDT)
   From: humberto@annexstein.csm.uc.EDU (Humberto Ortiz Zuazaga)
 
   I was showing some noweb'ed C code to a professor the other day, and
   he objected to my use of "implicit arguments" in a scrap (or whatever
   the politically correct term for "module" is these days).  He would
   prefer that scraps could take explicit arguments in their invocation.
   Do any of the existing litprog tools have this feature?  I could make
   it look like they do by putting the arguments into the scrap name:
 
   <<process variables (x, y)>>
 
   . . .
 
   <<process variables (x, y)>>=
   x += y * 23;
 
   but perhaps this is a genuinely usefull feature to have.  It looks
   like it could permit true inline functions in languages that do not
   support them, and help improve the clarity of webbed code by
   decreasing reliance on the previously declared variables.
 
These scraps are just code fragments not functions or modules! I dont
think they should have args. SInce they are macros, they are expanded inline.
You may get away by explaining that you use LITPROG as a PDL and each 
scrap is not a program module or function. 
Osman
 
--
Osman F. Buyukisik  |  GE Aricraft Engines  | ae1181t@stnfor.ae.ge.com
 
From dentato@minerva.ing.uniroma1.it Tue Jun 1 17:18:08 +0100 1993
Date: Tue, 1 Jun 1993 17:18:08 +0100 (DFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
To: LitProg@shsu.edu
Subject: Nuweb
 
 It's possible to get Nuweb via anonymous-ftp? If not, how can I get a copy?
Thanks.
          ___ __
         //_/// \
        // \//__/
      Remo Dentato    dentato@cadgroup.ing.uniroma1.it
 
From preston@cs.rice.edu Tue Jun 1 11:46:44 CDT 1993
Date: Tue, 1 Jun 93 11:46:44 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, dentato@minerva.ing.uniroma1.it
Subject: Re:  Nuweb
 
>It's possible to get Nuweb via anonymous-ftp? If not, how can I get a copy?
 
It's not yet possible to get nuweb via anonymous ftp.
To get a copy, send me (preston@cs.rice.edu) a note.
 
Preston Briggs
 
From baum@astra.tamu.edu Tue Jun 1 13:38:39 -0500 1993
Date: Tue, 1 Jun 1993 13:38:39 -0500 (CDT)
From: baum@astra.tamu.edu (Steve Baum)
Reply-To: LitProg@SHSU.edu, baum@ASTRA.TAMU.EDU
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re: Nuweb
 
> 
> >It's possible to get Nuweb via anonymous-ftp? If not, how can I get a copy?
> 
> It's not yet possible to get nuweb via anonymous ftp.
> To get a copy, send me (preston@cs.rice.edu) a note.
> 
> Preston Briggs
> 
 
        Could you please send a copy of nuweb to me if that would
     be at all possible.  Thank you very much.
 
                                                  Steve Baum
                                                  Oceanography Dept.
                                                  Texas A&M University
                                                  baum@astra.tamu.edu
 
From leew@cs.utexas.edu Tue Jun 1 13:39:18 -0500 1993
Date: Tue, 1 Jun 1993 13:39:18 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, humberto@annexstein.csm.uc.edu
Subject: Re: scraps with explicit arguments?
 
Humberto Ortiz Zuazaga writes:
 
  > I was showing some noweb'ed C code to a professor the other day, and
  > he objected to my use of "implicit arguments" in a scrap (or whatever
  > the politically correct term for "module" is these days).  He would
  > prefer that scraps could take explicit arguments in their invocation.
  > Do any of the existing litprog tools have this feature?  I could make
  > it look like they do by putting the arguments into the scrap name:
  > 
  > <<process variables (x, y)>>
  > 
  > . . .
  > 
  > <<process variables (x, y)>>=
  > x += y * 23;
  > 
  > but perhaps this is a genuinely usefull feature to have.  It looks
  > like it could permit true inline functions in languages that do not
  > support them, and help improve the clarity of webbed code by
  > decreasing reliance on the previously declared variables.
 
As I recall, in one of the articles in his "Literate Programming"
book, Knuth recommends mentioning the variables explicitly in the
module name.  Something like
 
    <<Process variables [[x]] and [[y]]>>
    ...
    <<Process variables [[x]] and [[y]]>>=
    x += y * 23;
 
in Noweb, or
 
    @<Process variables |x| and |y|@>
    ...
    @<Process variables |x| and |y|@>=
    x += y * 23;
 
in CWEB.  This makes the use of the variables explicit, although not
automatic.
 
On a related note, I find that global variables often make my webs
easier to read than locals.  I also find that gotos are much better
than breaks and continues (in C code) when the jump occurs in a
section separate from the one in which the loop begins (and ends).
Of course, this is only true in a webbing system that automatically
indexes labels (like CWEB & FWEB), so breaks and continues are
probably better in Noweb, unless you explictly use \label and \ref
to build your own label index (separate from your ``regular'' index).
 
		-- Lee
 
From marcus@x4u.desy.de Tue Jun 1 21:11:48 +0200 1993
Date: Tue, 1 Jun 93 21:11:48 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu
Subject: Re: Nuweb
 
Preston Briggs was kind enough to send me an introductory text
which is now available on the World Wide Web [WWW] (look for "Tools" 
at http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html).
A copy of the relevant page is appended below. 
 
  Note that you can get any document from WWW via mail; send mail
to listserv@info.cern.ch with the word HELP in it for instructions
(You can, e.g., get the NUWEB PostScript file with the message
  send file://ftp.desy.de/pub/web/nuweb/nuweb.ps
to listserv@info.cern.ch).
 
	Marcus Speh
 
-------------------- from the World Wide Web -------------------------
                                      List of Literate Programming Tools
                   LIST OF LITERATE PROGRAMMING TOOLS
 
   Have a look at the LitProg Library[1] for a more complete overview
   and sources. Please tell me[2] if there are other documents you would
   like to see here
 
  CLiP (PostScript[3], plain[4])
                          A universal (language-independent) literate
                         programming tool, currently ported to VAX/VMS
                         and MS-DOS only. See also: CLiP Style[5] and
                         Manual[6] (PostScript)
 
   CWEB[7]                WEB System of Structured Documentation for C
                         and C++. References [v3.0, all PostScript]:
                         User's Manual[8], common[9], cweave[10],
                         ctangle[11]
 
   FunnelWEB[12]          Features and comparison with FWEB, by P. Lyon
                         (original message to LitProg[13] mailing list).
 
   FWEB[14]               WEB System of Structured Software Design and
                         Documentation for Fortran-77, Fortran-90,
                         Ratfor, C, C++ and TeX. References [v1.30, all
                         PostScript]: fwebmac[15] [40p.], User's Manual
                         [body[16], index[17], 200 p.], guide[18] [20p.]
 
   NOWEB (plain[19], PostScript[20])
                          "Literate-Programming Tools Need Not Be
                         Complex", by N. Ramsey.
 
   NUWEB[21] (PostScript)
                          Yet another simple Literate Programming tool
                         for arbitrary programming languages, with LaTeX
                         as formatter
 
                                               Last updated June 1, 1993
 

 
     References from this document:-
 
[1]  gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.LITPROG%5d
[2]  http://info.desy.de:80/gnu/ftp/pub/www/people/marcus.html
[3]  file://ftp.desy.de/pub/faq/web/clip/clip_ann.ps
[4]  http://info.desy.de:80/gnu/ftp/pub/faq/web/clip/clip_ann.plain
[5]  file://ftp.desy.de/pub/faq/web/clip/clip_ann.ps
[6]  file://sun01.info.wau.nl/clip/ms_dos/clip_man.ps
[7]  http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/CWEB/FULL
[8]  file://ftp.desy.de/pub/web/DOCUMENTS/cweb/cwebman.ps
[9]  file://ftp.desy.de/pub/web/DOCUMENTS/cweb/common.ps
[10]  file://ftp.desy.de/pub/web/DOCUMENTS/cweave.ps
[11]  file://ftp.desy.de/pub/web/DOCUMENTS/cweb/ctangle.ps
[12]  http://info.desy.de:80/gnu/ftp/pub/faq/web/funnelWEB/funnelWEB.html 
[13]  http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg-mailing.html
[14]  http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/FWEB/FULL
[15]  file://ftp.desy.de/pub/web/DOCUMENTS/fweb-manual/FWEBmac.ps
[16]  file://ftp.desy.de/pub/web/DOCUMENTS/fweb-manual/FWEBman1.ps
[17]  file://ftp.desy.de/pub/web/DOCUMENTS/fweb-manual/FWEBman2.ps
[18]  file://ftp.desy.de/pub/web/DOCUMENTS/fweb-manual/GUIDE.ps
[19]  http://info.desy.de:80/gnu/ftp/pub/faq/web/noweb/noweb.html
[20]  file://ftp.desy.de/pub/faq/web/noweb/noweb.ps
[21]  file://ftp.desy.de/pub/web/nuweb/nuweb.ps
 
From George Tue Jun 01 14:38:26 CST 1993
Date: Tue, 01 Jun 1993 14:38:26 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, baum@ASTRA.TAMU.EDU
Subject: Re: Nuweb
 
On Jun 1, 1993 11:46:44 CDT, "Preston Briggs" <preston@cs.rice.edu> posted:
> >It's possible to get Nuweb via anonymous-ftp? If not, how can I get a copy?
> 
> It's not yet possible to get nuweb via anonymous ftp.
> To get a copy, send me (preston@cs.rice.edu) a note.
> 
> Preston Briggs
> 
 
If you want to anonymous ftp to ftp.shsu.edu then 
 cd incoming 
 mkdir nuweb
 cd nuweb
 mput the_files
I can place them in the web archive area (tex-archive/web/nuweb/) or I can
place them in another publicly accessible area there (pub/nuweb/) until you
want them in the master library.  This ought to save a lot of work on
everyone's part, if you like.
 
--George
 
From dak@POOL.Informatik.RWTH-Aachen.DE Wed Jun 2 00:00:31 +0200 1993
Date: Wed, 2 Jun 93 00:00:31 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
Subject: scraps with explicit arguments?
 
As to having arguments to scraps: don't confuse them with procedures!
Scraps are usually NOT supposed to be called more than once! They are
only used to split a program into several logically units. If you had
to include interfaces in them, they would lose their advantage over
procedures. In addition, you would be temted to generate large code
pieces, instead of having to parameterize.
 
The large psychological advantage about WEBs is that you split large
tasks pretty automatically without thinking into smaller ones. The
moment you think of your code sections of parametrized pieces,
you start thinking of interfaces, and that is a work not of much
sense considering the small code sections you like to arrive at.
 
If you have parameters, use the mechanisms of the language.
That is my feeling.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, W-5100 Aachen, Germany
 
From dak@POOL.Informatik.RWTH-Aachen.DE Wed Jun 2 00:00:31 +0200 1993
Date: Wed, 2 Jun 93 00:00:31 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
Subject: scraps with explicit arguments?
 
As to having arguments to scraps: don't confuse them with procedures!
Scraps are usually NOT supposed to be called more than once! They are
only used to split a program into several logically units. If you had
to include interfaces in them, they would lose their advantage over
procedures. In addition, you would be temted to generate large code
pieces, instead of having to parameterize.
 
The large psychological advantage about WEBs is that you split large
tasks pretty automatically without thinking into smaller ones. The
moment you think of your code sections of parametrized pieces,
you start thinking of interfaces, and that is a work not of much
sense considering the small code sections you like to arrive at.
 
If you have parameters, use the mechanisms of the language.
That is my feeling.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, W-5100 Aachen, Germany
 
From George Tue Jun 01 16:42:20 CST 1993
Date: Tue, 01 Jun 1993 16:42:20 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: preston@cs.rice.edu
Subject: Re: Nuweb
 
On Tue, 1 Jun 93 15:23:02 CDT, Preston Briggs <preston@cs.rice.edu> posted
privately in response to my earlier post on LitProg:
> Hi,
>
> I put the shar'd up bundle of files in incoming/nuweb/nuweb.shar
>
> I don't know if this is the best format, but it seems reasonably
> convenient.
>
> I guess I don't mind you sticking it in the web archive area. I'm going so
> slowly on the documentation that it may be the end of the summer before it
> looks respectable (not to mention Knuthian).
>
> Thanks for your help with this,
> Preston
 
No problem!  Indeed, thanks to you!!  I have built the individual files
from the shar file Preston submitted and made them available for anonymous
ftp retrieval at:
 ftp.shsu.edu:/tex-archive/web/nuweb/
This represents (as best I can tell) version 0.6, which I have dated today,
1 June 1993.  The ftp server on ftp.shsu.edu can tar, tar.Z, zip, zoo,
tar.z the directory if you want it that way.
 
You can retrieve via e-mail a 3 part UUENCODEd ZIP archive of this
distribution by including:
 SENDME NUWEB
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu).
 
Finally, via gopher, you can get the individual files or a ZIP archive on
Niord.SHSU.edu (192.92.115.8, port 70) in:
 TeX-related materials/
   Literate programming library/
     Nuweb/
 
Oh, and a BTW:  I have updated the gopher server on Niord so that it now
properly handles binary files.  Also, I have included the LitProg archives
in the Literate programming library/ area.
 
Regards and thanks to Preston again,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Kayvan Tue Jun 1 17:30 PDT 1993
Date: Tue, 1 Jun 93 17:30 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re:  Nuweb
 
Hmmm...
 
Sorry for raising the demand for NuWeb (NOT) :-)
 
It's a nice tool. Thank you.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Manuel Wed Jun 2 13:20:16 BST 1993
Date: Wed, 2 Jun 93 13:20:16 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@SHSU.edu, preston@CS.RICE.EDU, baum@ASTRA.TAMU.EDU
Subject: Re: Nuweb
 
> > 
> > >It's possible to get Nuweb via anonymous-ftp? If not, how can I get a copy?
> > 
> > It's not yet possible to get nuweb via anonymous ftp.
> > To get a copy, send me (preston@cs.rice.edu) a note.
> > 
> > Preston Briggs
> > 
> 
> 
>         Could you please send a copy of nuweb to me if that would
>      be at all possible.  Thank you very much.
> 
>                                                   Steve Baum
>                                                   Oceanography Dept.
>                                                   Texas A&M University
>                                                   baum@astra.tamu.edu
> 
 
I don't know wether NuWEB is too big to send it via email, but anyway
I'm interested in a copy, too. (Well compressed and uuencoded, please.)
 
Manuel Carriba <M.Carriba@dcs.shef.ac.uk>
 
From Kayvan Sat Jun 5 00:07 PDT 1993
Date: Sat, 5 Jun 93 00:07 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu
Subject: The Literate Programming Philosophy
 
On May 26, 1993, Eric W. van Ammers (ammers@rcl.wau.nl) wrote:
 
Lee> A show of hands please:  How many of you out there have gotten so spoiled
Lee> by literate programming that you'll fight to the death rather than
Lee> program without your LP tools?  [Notice that my hand is raised.]
 
Eric> Although a bit late, I certainly would like to raise my hand. I have been
Eric> using the basic technique for many years and for me it is the most
Eric> convincing presentation of a program.
 
Completely agreed. I've only been using it for some months now, but I
was introduced to the conecpts of litprog years ago.
 
Eric> The big problem I face, and all of us LP-ers expereince the
Eric> same, is that we cannot bring to words where exactly is the
Eric> power of the LP paradigm. I have several times before argued
Eric> that we should discuss thIs sort of "phylosophical" issues on
Eric> the net. Once again I ask to all of you: Can we somehow make
Eric> explicite the power of LP. Maybe this will finally convince
Eric> managers too.
 
Okay. Here's a first shot at an verbalizing the power of LP.
 
First of all, literate programming is unabashedly fun!!! I know, I
know, this is not the type of thing that would sway a manager, but I
have to be honest first before getting to the objective measures.
 
As I write a literate program, I focus on the essentials of the
program at the higher levels of abstraction (without needing to deal
with the lower level details). This makes for a program that flows
nicely from high level overview to low level implementation details.
The resulting program is also easy to write and easy to read (for
someone else, or for myself, months later).
 
Most important of all, I'm not limited to the language's requirements
for program order or its documentation mechanisms. Literate
Programming allows me to document my program in small pieces, and to
present those pieces in whatever way makes the most sense for myself
and my reader. As in writing a story or a paper, being conscious of my
audience forces me to write better programs.
 
In terms of the process, I find literate programs, once you've learned
the methodology, take slightly more time to craft than non-literate
ones do. This is because you take more care with the pieces and you
are also writing documentation that goes along with the pieces.
 
The debugging time for literate programs, in my experience, is orders
of magnitude less than for non-literate ones. My literate programs
work reliably on at most the third or fourth iteration. Well-designed
non-literate programs are still much harder to debug and test, in my
limited experience. This is the real power of literate programming
in my business.
 
In short: Literate programming is fun. Literate programs are easier to
compose (since I can pseudo-code my way to completion in a stream of
consciousness fashion) than non-literate ones. Literate programs
require almost no debugging and many times will work the first time.
The products of literate programming are much better documented (and
thus much more maintainable) programs.
 
There's some investment of time in learning the tools, but the
investment pays off quite quickly in improved code quality and
maintainability.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From ddw2@sunbim.be Mon Jun 7 12:29:49 +0200 1993
Date: Mon, 7 Jun 93 12:29:49 +0200
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re:  Nuweb
 
I just got nuweb from the archives and intend to start LitProgramming
for my future projects. nuweb appears to be quite simple to learn and
use.To help me  start (and hopefully get some colleagues to look at
it too) I just made this one sheet summary which others
may find useful. Its easier to keep on my desk than the full manual
(though it may also hide more easily :-).
 
There it is, do what you want with it.
 
Dominique
 
----nuwebsum.tex---
\documentstyle[12pt]{article}
 
\begin{document}
\thispagestyle{empty}
 
\begin{center}
\Large\bf NUWEB Command summary
\end{center}
 
\section*{Invocation}
\verb@nuweb [-toc] files...@
\begin{description}
\item[-t:] Suppress generation of the tex file
\item[-o:] Suppress generation of the output file
\item[-c:] Avoid testing output file for changes before updating.
\item[files:] A number of file names. If no extension {\em .w\/} is added.
\end{description}
\section*{Commands}
\begin{description}
\item[@o {\em file flags scrap\/}] Output scrap to named file. Flags
  are further described as:
  \begin{description}
  \item[-d:]  Forces \verb@#line...@ directives in output.
  \item[-i:] Suppresses macro indentation.
  \item[-t:] Suppresses tab expansion in output (8 spaces).
  \end{description}
\item[@d {\em macro-name scrap\/}] Name this scrap.
\item[@O,@D] Variant of the above which allows to break across pages.
  Not very robust for short scraps.
\item[@\{ {\em anything\/} @\}] Scrap body.
\item[@\{ {\em anything\/} @$\mid$ {\em index entries\/} @\}] Scrap body
  with user selected index entries.
\item[@$<${\em macro-name\/}$>$@] Macro invocation.
\item[@@] Insert the at-sign in the output.
\item[@i {\em file\/}]  include the file (up to 10 levels).
\item[@f] Create file name index.
\item[@m] Create macro name index.
\item[@u] Create user index.
 
\end{description}
\end{document}
 
From Kayvan Mon Jun 7 10:39 PDT 1993
Date: Mon, 7 Jun 93 10:39 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
Subject: Re:  Nuweb
 
Thanks! That's quite useful.
 
			---Kayvan
 
From George Mon Jun 07 13:46:06 CST 1993
Date: Mon, 07 Jun 1993 13:46:06 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: litprog@SHSU.edu
Subject: Nuwebsum.tex in Nuweb directory at SHSU
 
Subject about says it all.  I extracted and gave notice of source, etc.,
but it is there for future reference.,
 
--GDG
 
From leew@cs.utexas.edu Mon Jun 7 16:51:24 -0500 1993
Date: Mon, 7 Jun 1993 16:51:24 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: litprog@shsu.edu
Subject: Info needed on language independent LP systems
 
I'm writing an article on literate programming in PAL (Paradox for
DOS) and ObjectPAL (Paradox for Windows) for the Paradox Informant.
I'm using noweb, so I'll be concentrating on it, but I would like to
mention the other LP tools that are available for working with
Paradox.  The only requirements are that they be language-independent
(PAL has some *really strange* syntax, and I sincerely doubt that a
PAL-based system exists), and they must run on PCs under DOS or
Windows.
 
The systems I know about that meet these requirements are:
 
    System    Formatter    Restrictions
    ------    ---------    ------------
    noweb     TeX/LaTeX    requires Awk
    nuweb     TeX/LaTeX    unofficial release(?)
    funnelWeb TeX/LaTeX
    CLiP         any
 
I'd appreciate knowing if I've missed any system, or if the
information above is inaccurate (restrictions I've missed).  I'd also
appreciate it if the authors of the various systems mentioned above
would let me know the prefered typographic treatment of the tool's
name (which letters should be capitalized, preferred typefaces,
etc.).  I want to make sure I get things right (as much as possible).
 
Thanks in advance.
 
		-- Lee
 
From marcus@x4u.desy.de Tue Jun 8 15:38:32 +0200 1993
Date: Tue, 8 Jun 93 15:38:32 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu
Subject: Re: Nuwebsum.tex in Nuweb directory at SHSU
 
>>>>> On Mon, 07 Jun 1993 13:46:06 CST, "George D. Greenwade" <bed_gdg@SHSU.edu> said:
 
|> Subject about says it all.  I extracted and gave notice of source, etc.,
|> but it is there for future reference.,
 
The PostScript version of the summary can also be read/retrieved 
on the LitProg page on the World Wide Web.
 
Marcus
 
From Lewis Tue Jun 8 09:43:30 EST 1993
Date: Tue, 8 Jun 93 09:43:30 EST
From: "Lewis Perin" <perin@cumc.cornell.edu>
Reply-To: LitProg@SHSU.edu, perin@cumc.cornell.edu
To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
Subject: RE:Info needed on language independent LP systems
 
Hi, Lee.  First let me take this opportunity to thank you for the pithy
stuff you've contributed to the LP list.
 
In Message Mon, 7 Jun 1993 16:51:24 -0500, you wrote:
 
>The systems I know about that meet these requirements are:
>
>    System    Formatter    Restrictions
>    ------    ---------    ------------
>    noweb     TeX/LaTeX    requires Awk
>
>I'd appreciate knowing if I've missed any system, or if the
>information above is inaccurate (restrictions I've missed).
 
I'm writing this at work where C++ is the law and my LP activities are
limited to CWEB (not that this makes me suffer!), so I can't check what I'm
about to say, BUT:
 
I don't think noweb really needs AWK; not if you have Icon.  At home where I
use OS/2 I've replaced the AWK parts of the "normal" LP activities (i.e.
tangle and weave) with the Icon code Ramsey supplied; it runs faster that
way.  I don't remember if the stuff that provides a way to make a program
"illiterate" again is AWK-only, but if so wouldn't that merit an asterisk?
 
By the way, I think it would be terrific if somebody (maybe me if I get
ambitious) would try replacing the shell code with Icon.  That would make it
more monolithic in a sense, but it would have 2 virtues:
 
- the thing would run faster (not to be sneezed at when it comes to tangle);
 
- it would be more portable; DOS users wouldn't need the MKS shell.
______________________________________________________
      __          perin@cumc.cornell.edu (212)746-2946
 |   |_  \    / : Lew Perin
 |__ |__  \/\/  : Home: (201)435-2679
 
From  Wed Jun 9 16:37:43 +0200 1993
Date: Wed, 9 Jun 1993 16:37:43 +0200
From: " (Bernhard Lang)" <Lang@tu-harburg.d400.de>
Reply-To: LitProg@SHSU.edu, Lang@TU-HARBURG.D400.DE
To: litprog@shsu.edu
Subject: nuweb on pc
 
i did install nuweb on pc using the gnu-djgpp compiler. it seems to work 
fine. where can i install the binaries that everybody of the litprog 
group can pic it up via ftp?
 
Bernhard
 
{{{  Dr. Bernhard Lang  -----------------------------------------------
     email: lang@tu-harburg.dbp.de         TU Hamburg Harburg
                                           Technische Informatik I
}}}
...  Enter this fold to view behind the scenes  -----------------------
 
From George Wed Jun 09 15:44:17 CST 1993
Date: Wed, 09 Jun 1993 15:44:17 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, Lang@TU-HARBURG.D400.DE
Subject: RE: nuweb on pc
 
On Wed, 9 Jun 1993 16:37:43 +0200, Bernhard Lang <Lang@tu-harburg.d400.de>
reported:
> i did install nuweb on pc using the gnu-djgpp compiler. it seems to work 
> fine. where can i install the binaries that everybody of the litprog  group
> can pic it up via ftp?
 
One of three ways will work by me.  Either (a) put them in a publicly
accessible ftp area and let me know where to fetch it from (no, this isn't
as dumb as it sounds -- I have come across quite a few sites which allow
very short-term storage for local users if someone else is coming in to get
them); or (b) pack the files up in (preferably a ZIP) an archive of some
sort, UUENCODE, XXENCODE, BTOA, VVENCODE, or some other encoding technique
that file, and mail it to me directly; or (c -- most preferable) use
anonymous ftp to ftp.shsu.edu then cd incoming and place the file(s) there. 
If you are going to deposit multiple files, it is highly preferable for you
to get into incoming, then:
 mkdir whatever_you_want_to_call_it
 cd whatever_you_want_to_call_it
then put the files in their own unique directory within the incoming/ area
at SHSU.
 
--George
 
From ravenek@chem.vu.nl Thu Jun 10 14:39:24 MET 1993
Date: Thu, 10 Jun 93 14:39:24 MET DST
From: ravenek@chem.vu.nl (Walter Ravenek)
Reply-To: LitProg@SHSU.edu, ravenek@CHEM.VU.NL
To: LitProg@SHSU.edu
Subject: Nuweb on Macintosh
 
I tried to install Nuweb on a Macintosh (using THINK C which
lets you enter a command line by using its console library).
The Mac simply freezes when I run the program. One thing I
have found is the dependency on file name construction.
Having bypassed this, the Mac freezes again.
 
Did someone else have a try at this?
 
P.S. Nuweb installed and worked fine on our RS6000
 
Walter Ravenek
Dept. of Chemistry
Vrije Universiteit
De Boelelaan 1083
1081 HV Amsterdam
The Netherlands
e-mail: ravenek@chem.vu.nl
 
From George Thu Jun 10 10:06:48 CST 1993
Date: Thu, 10 Jun 1993 10:06:48 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: Lang@tu-harburg.d400.de
Subject: RE: zip file for nuweb on PC available
 
On Thu, 10 Jun 1993 15:49:27 +0200, Bernhard Lang <Lang@tu-harburg.d400.de>
posted:
> Thank you for your reply concerning the ftp installation of nuweb for PC. 
> I did copy a .ZIP file to the incoming directory of ftp.shsu.edu. The name
> of the file is 'nuweb-pc.zip'. The zip file contains a README.TXT file
> with my first experiences using nuweb on PC and NUWEB.EXE as the
> executable. 
 
Thanks!  The file is available for anonymous ftp retrieval from
ftp.shsu.edu in tex-archive/web/nuweb/msdos/nuweb-pc.zip or via Gopher on
Niord.SHSU.edu (192.92.115.8, port 70) in:
  TeX-related Materials/
    Literate Programming Library/
      web/ directory from Comprehensive TeX Archive Network/
        nuweb/
          nuweb-pc/
 
I haven't got a mail version in place yet, but if there are requests, I
will get one together post haste.
 
--George
 
From ae1181t@stnfor.ae.ge.com Thu Jun 10 14:04:07 -0400 1993
Date: Thu, 10 Jun 1993 14:04:07 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: litprog@shsu.edu
Subject: "nuweb for pc"
 
I just found out why pc filenames and extensions were restricted. Nuweb
first tries to write to a temp file whose name is output name concatted
with ~, and tries to see if the temp is different from the old (existing)
file. So if you do not have an extension you can have at most 7 chars
for a filename. If you have an extention, then 8 chars + 2 chars allowed
as a file name. If a different mechanism is ised to name the temp files
than full 8 char and 3 char ext could be used. 
Osman
 
From preston@cs.rice.edu Thu Jun 10 14:23:48 CDT 1993
Date: Thu, 10 Jun 93 14:23:48 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, ae1181t@stnfor.ae.ge.com
Subject: Re:  "nuweb for pc"
 
>I just found out why pc filenames and extensions were restricted.
 
One way around this would be to write all temporary files to the same
file name (say foo.bar or some such).  Since each file is created and
renamed before progressing to the next file, we won't see any conflicts.
 
I'm not sure what the best temporary file name would be, accounting for all
possible systems :-)
 
On another note,
a friend suggested that nuweb write-protect output files
to help avoid accidental editing of what is effectively an intermediate file.
Sounds reasonable to me.  Does anyone hate the idea?
 
Preston
 
From ae1181t@stnfor.ae.ge.com Thu Jun 10 15:41:23 -0400 1993
Date: Thu, 10 Jun 1993 15:41:23 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: preston@cs.rice.edu
Subject: Re:  "nuweb for pc"
 
   From: preston@cs.rice.edu (Preston Briggs)
 
   >I just found out why pc filenames and extensions were restricted.
 
   One way around this would be to write all temporary files to the same
   file name (say foo.bar or some such).  Since each file is created and
   renamed before progressing to the next file, we won't see any conflicts.
 
   I'm not sure what the best temporary file name would be, accounting for all
   possible systems :-)
   On another note,
   a friend suggested that nuweb write-protect output files
   to help avoid accidental editing of what is effectively an intermediate file.
   Sounds reasonable to me.  Does anyone hate the idea?
 
   Preston
I tried nuweb~~~.tmp and it works on dos, unix. Write protect is a good
idea. I found myself screwing with the temp files intead of .w and then 
go back. This will remind the users to the best practice i.e. fix the .w
file!
Osman
 
--
Osman F. Buyukisik  |  GE Aricraft Engines  | ae1181t@stnfor.ae.ge.com
 
From George Thu Jun 10 15:54:27 CST 1993
Date: Thu, 10 Jun 1993 15:54:27 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: ae1181t@stnfor.ae.ge.com
Subject: RE: nuweb for pc
 
On Thu, 10 Jun 1993 14:48:55 -0400, Osman F Buyukisik
<ae1181t@stnfor.ae.ge.com> posted:
> I just uploaded nuweb.zip into incoming/nuweb/msdos dir. This includes a
> small fix for the filename problem the earlier one had. Also full source
> and make and a man page are included. The executable is smaller (44k). Used
> the same compiler (djgpp). 
 
Thanks!  I've superceded what was in the tex-archive/web/nuweb/msdos/
directory on pip (hence on Gopher) to include this larger distribution. 
 
--George
 
From ddw2@sunbim.be Fri Jun 11 10:04:03 +0200 1993
Date: Fri, 11 Jun 93 10:04:03 +0200
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re:  "nuweb for pc"
 
   Preston> One way around this would be to write all temporary files
   Preston> to the same file name (say foo.bar or some such).  Since
   Preston> each file is created and renamed before progressing to
   Preston> the next file, we won't see any conflicts.
 
   Preston> I'm not sure what the best temporary file name would be,
   Preston> accounting for all possible systems :-)
 
Why not keep the file name but put the temporary output 
in the directory indicated by the environment variable TMPDIR if it
exists or into \tmp\ 
 
   Preston> On another note, a friend suggested that nuweb
   Preston> write-protect output files to help avoid accidental
   Preston> editing of what is effectively an intermediate file.
   Preston> Sounds reasonable to me.  Does anyone hate the idea?
 
I'm not sure this is a good idea. I think that keeping the files in
another place, and automatically removing them is probably a better
protection and easier to implement (using unlink() on both systems).
 
Regards,
 
Dominique
 
Dominique de Waleffe             ddw@sunbim.be
BIM sa
Chaussee de Louvain, 510	 Tel: +32 2 719 26 14
B-1930 Zaventem			 Fax: +32 2 725 47 83
Belgium
 
From John Fri Jun 11 11:08:13 +0100 1993
Date: Fri, 11 Jun 1993 11:08:13 +0100 (BST)
From: "John K Nicoll" <jkn@ohm.york.ac.uk>
Reply-To: LitProg@SHSU.edu, jkn@OHM.YORK.AC.UK
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re: "nuweb for pc"
 
According to Preston Briggs:
> 
> >I just found out why pc filenames and extensions were restricted.
> 
> One way around this would be to write all temporary files to the same
> file name (say foo.bar or some such).  Since each file is created and
> renamed before progressing to the next file, we won't see any conflicts.
> 
> I'm not sure what the best temporary file name would be, accounting for all
> possible systems :-)
> 
 
The scheme I prefer (for DOS) is to have a separate directory,
specified by eg. an environment string (NUBACKUP=...). You would
then use the same basic filename but save in this directory. Only
if you couldn't access this backup directory would you then resort
to massaging the filename and saving in the current directory.
 
Of the several schemes various editors use for backups, this one
(used by Brief, & perhaps others) is the one I have found most
convenient.
 
	john N
> 
> Preston
> 
 
From Kayvan Fri Jun 11 04:30 PDT 1993
Date: Fri, 11 Jun 93 04:30 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: ddw2@SUNBIM.BE
Subject: Re:  "nuweb for pc"
 
>>>>> "Dominique" == Dominique de Waleffe <apple!sunbim.be!ddw2> writes:
 
Preston> On another note, a friend suggested that nuweb write-protect
Preston> output files to help avoid accidental editing of what is
Preston> effectively an intermediate file.  Sounds reasonable to me.
Preston> Does anyone hate the idea?
 
Dominique> I'm not sure this is a good idea. I think that keeping the
Dominique> files in another place, and automatically removing them is
Dominique> probably a better protection and easier to implement (using
Dominique> unlink() on both systems).
 
It seems like you're confusing two different issues. The intermediate
file (wherever it ends up being and whatever it's named) will be
unlink()'ed at the conclusion of the compare operation. I favor the
name "nuweb~~~.tmp" for the intermediate file.
 
The output files that Preston is talking about write-protecting are
the files produced by running nuweb over the web file. So if I'm
writing a C program, and I run nuweb over foo.web to get foo.c,
extern.h, and bar.c, those files would be write-protected. I think
this is a good idea. Users shouldn't be going around changing the
output of nuweb.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From ddw2@sunbim.be Fri Jun 11 14:27:03 +0200 1993
Date: Fri, 11 Jun 93 14:27:03 +0200
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Subject: Re:  "nuweb for pc"
 
Kayvan> It seems like you're confusing two different issues. The intermediate
 
You're right. My morning coffee was not strong enough.
 
Kayvan> The output files that Preston is talking about write-protecting are
Kayvan> the files produced by running nuweb over the web file. So if I'm
 
Agreed also. The output files could be write-protected. 
 
Sorry for the confusion I introduced.
 
Dominique
 
From Hans-Hermann Fri Jun 11 14:08:36 MEZ 1993
Date: Fri, 11 Jun 93 14:08:36 MEZ
From: Hans-Hermann Bode <HHBODE@dosuni1.rz.Uni-Osnabrueck.DE>
Reply-To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re:  "nuweb for pc"
 
>I'm not sure what the best temporary file name would be, accounting for all
>possible systems :-)
 
What about tmpfile()/tmpnam() (ANSI) or mktemp() (non-standard but frequently
used)? Of course, this would only work if the file name is not used outside
of a single program. (I havn't tried nuweb yet, so I don't know whether the
former is true.) I discourage from using the original file name in a TMP (or
so) directory, because the original file itself already may reside in TMP...
 
>a friend suggested that nuweb write-protect output files
>to help avoid accidental editing of what is effectively an intermediate file.
>Sounds reasonable to me.  Does anyone hate the idea?
 
In some cases, however, it can be reasonable to edit even an intermediate
file, e.g., for testing the effect of a small change without touching the
source file. If there are really people that can't distinguish between source
and intermediate files, they could write a shell/batch script and call
chmod/attrib after nuweb.
 
Hans-Hermann Bode
Arbeitsgruppe Systemforschung, Universitaet Osnabrueck
Tel.: (49)-541-9692545
e-mail: HHBODE@DOSUNI1.BITNET, hhbode@dosuni1.rz.uni-osnabrueck.de
 
From krommes@theory.pppl.gov Mon Jun 14 07:25:31 EDT 1993
Date: Mon, 14 Jun 93 07:25:31 EDT
From: krommes@theory.pppl.gov (John Krommes)
Reply-To: LitProg@SHSU.edu, krommes@THEORY.PPPL.GOV
To: litprog@shsu.edu
Subject: FWEB 1.30 now available --- FWEB 1.30 NOW AVAILABLE ---
 
  Version 1.30 (non-beta version) of FWEB is now available from
 
	lyman.pppl.gov:/pub/fweb/fweb-1.30.tar.Z
 
To obtain, use anonymous guest ftp in binary mode to obtain the tar file,
then:
 
	uncompress fweb-1.30.tar
	tar -xvf fweb-1.30.tar
 
This creates the directory fweb-1.30.  Note that the installation procedure
has changed for Unix users, as I slowly gravitate toward gnu-like
conventions.  FWEB now attempts to configure itself automatically to the
host environment:
 
	cd fweb-1.30
	./configure 
	cd web
	make bootstrap
	make -n install
(Use the -n option to see where various files are going to be put.  If you
need to make changes, make them in defaults.mk.in, then rerun ./configure.)
	[Log on as root]
	make install
 
  For a short list of things that have changed or been fixed between
fweb-1.30--beta and fweb-1.30, see /pub/fweb/READ_ME.
 
WHO SHOULD USE FWEB?
 
  FWEB is a language-sensitive WEB originally based on CWEB.  It was
initially intended to support Fortran (hence the 'F'); however, an
important feature of FWEB is its ability to support particular multiple
languages.  The significant features of FWEB are:
 
	* multiple language support (even within the same WEB run):
		C, C++, Fortran--77, Fortran--90, Ratfor, and (to a limited
extent) TeX;
 
	* built-in Ratfor translator (into either Fortran--77 or Fortran--90);
 
	* built-in ANSI-C-like macro preprocessor (with various
	  special-purpose extensions);
 
	* superior cross-referencing facilities for identifiers;
 
	* sophisticated  facilities for changing the typeset appearance of
	  operators and identifiers (these work either with the
	  operator-overloading features of C++ and Fortran--90, or
	  stand-alone); 
 
	* extensive customization facilities via a style file;
 
	* usable with either TeX or LaTeX;
 
	* has been installed successfully on a great variety of machines,
	  including everything from IBM-PCs to CRAYs.
 
You should use FWEB if:
 
	* you're a Fortran programmer;
 
	* you mix languages;
 
	* you need very flexible macro-processing facilities;
 
	* you enjoy a variety of convenience features.
 
You should (perhaps) not use FWEB if:
 
	* you like language-insensitive literate programming;
 
	* you need a very small and lean system (FWEB's internal tables are
larger than those of some other WEB's because of the multiple language
support and various advanced cross-referencing facilities; the macro
processor and convenience features enlarge it still more);
 
	* you program only in C or C++ and are perfectly happy with CWEB.
 
DOCUMENTATION
 
  If you're an experienced literate programmer and want to find out whether
FWEB is for you, tex and read the relatively short reference/syntax guide in
fweb-1.30/manual/guide:
 
	cd manual
	make guide
 
  FWEB also features a very large and complete user manual suitable for
beginners; this contains many examples and an extensive index and table of
contents:
 
	cd manual
	make manual
 
SUPPORT
 
  FWEB remains actively supported, although STRICTLY AS A SPARE-TIME
ACTIVITY.  It is available courtesy of Princeton University's Plasma
Physics Laboratory, a contractor of the U.S. Dept. of Energy whose mission
is research into fusion energy.  The nation fusion program is currently
under great stress, and this affects the feasible level of support.
Questions, bug reports, and suggestions of all kinds are still very
welcome; however, I can no longer guarantee immediate response.  I will
attempt to answer questions about installation quickly, and will provide
workarounds for egregious bugs.  Suggestions for new features are filed
away systematically and are reviewed periodically.
 
--- John
 
krommes@princeton.edu                           |  John A. Krommes
                                                |  Plasma Physics Laboratory
(Mail to krommes@princeton.edu is forwarded     |  P.O. Box 451
to krommes@lyman.pppl.gov == 192.55.106.129)    |  Princeton, NJ  08543
 
(To ftp files, you must use lyman.pppl.gov.)    |  Phone:  (609) 243--2606  
                                                |  Fax:    (609) 243--2662
 
From ravenek@chem.vu.nl Mon Jun 14 15:53:13 MET 1993
Date: Mon, 14 Jun 93 15:53:13 MET DST
From: ravenek@chem.vu.nl (Walter Ravenek)
Reply-To: LitProg@SHSU.edu, ravenek@CHEM.VU.NL
To: LitProg@SHSU.edu
Subject: Nuweb on Macintosh
 
I managed to get Nuweb running on the Macintosh. As Tim Larkin
correctly suggested the main difficulty was with the size of
an int (thanks). The changes I needed to make are as follows:
 
- the functions in arena.c assume that variables of type int
can be used to specify memory lengths. Use type size_t instead.
In fact, it suffices to make changes in two places only:
parameter n of arena_getmem, and variable m in the same function.
 
- use no multiple definitions of global variables; instead
use one definition and for the rest declarations (i.e., extern).
The easiest way to handle this is to make a header file (to be
included in all source files) and a file globals.c with the
definitions.
 
- the structure of file names is too UNIX dependent. On the
Macintosh directory names are separated by a colon. A simple
solution is to define a separation character by means of a
#define. One could also contemplate having the user specify
a pathname.
 
- function unlink is UNIX. Fortunately there is a unix library
with my developing system THINK C, but it should not be used.
 
Walter Ravenek
Dept. of Chemistry
Vrije Universiteit
De Boelelaan 1083
1081 HV Amsterdam
The Netherlands
e-mail: ravenek@chem.vu.nl
 
From iapa!ctrbdo@mailhost.ecn.uoknor.edu Mon Jun 14 12:47:14 CDT 1993
Date: Mon, 14 Jun 93 12:47:14 CDT
From: iapa!ctrbdo@mailhost.ecn.uoknor.edu (bryan d oakley)
Reply-To: LitProg@SHSU.edu, iapa!ctrbdo@MAILHOST.ECN.UOKNOR.EDU
To: litprog@shsu.edu
Subject: Help: "Change file entry did not match..."
 
The root of the problem is in installing TeX, but the actual problem
is related to an out of date (?) change file.  Bear with me if you
think you can help...  I realize that comp.text.tex might be a better
avenue but, alas, I don't have access to that newsgroup.
 
The problem is thus: To install TeX, I need C source, which requires a
working web2c to convert the pascal sources to C.  I need a working
tangle to convert the .web files to those pesky .p (pascal) files.
Some idealistic soul created a tangleboot.c from which to tangle
tangle.web to create tangle.p.  This compiled just fine, thank you.
However, when I run tangleboot on tangle.web to create tangle.p (and
thus create a full-blown tangle), I get the following:
 
> This is TANGLE, C Version 4.2
> *1*11*19*29*37*50*65*70*77*94*112*123*143*156*163*171*179*182*188*189
> ! Change file entry did not match. (change file l.61)
> @d banner=='This is TANGLE, Version 4.2'
> 
> Writing the output file.....500..
> Done.
> (Pardon me, but I think I spotted something wrong.)
> make: *** [tangle.p] Error 1
 
(love those error messages! "... Pardon me, ..." heh heh)
 
Because of this tangle refuses to build, and thus the dominos start to
fall in my TeX installation.
 
I am using sources obtained off of the prime-time freeware CD, so I
assume I have a complete and correct set of files (the TeX
version/distribution number is 5.851c).  Alas, I don't have ftp (other
than FTP-by-mail), so getting new sources is a real bear.
 
So, what do I have to do to keep the tangle bootstrap from complaining
about the change file entry not matching?  Do I _have_ to get new
versions of the source, or can I do some manual hacking?  Can I
recreate a .web from a .ch, or a .ch from a .web, or throw away the
.ch, or what?  I'm not overly adept at web programming; I've tinkered
around with FWEB on my machine (hence the need for TeX), but my pascal
is very rusty.  Perhaps I just need to take a day off and install that
copy of Pascal that we never use...
 
You know... installing TeX is not nearly as easy as most of the GNU
stuff I'm used to working with... :-(
 
If there is no quick solution, is there a single point I can go to
where I can get Everything_Necessary_For_TeX.tar.Z?  As stated
earlier, I think I have durn near everything from that CD (it has a
copy of the entire UK archive).  I realize I could throw some bucks at
TUG, but hey, bucks are hard to come by...
 
On retrospect, I may have clobbered one version of the change file in
favor of another.  The imaketex.tar file that came with the
distribution that I am working with had a tangle.ch but no tangle.web.
Perhaps when I untar'ed that it overwrote the .ch file that went with
the original tangle.web file.  Hmmmmm...
 
Argh.  
 
---------------------------------------------------------------------
Instrument Approach Procedures Automation             DOT/FAA/AMI-230
---------------------------------------------------------------------
Bryan D. Oakley                   ctrbdo%iapa@mailhost.ecn.uoknor.edu
KENROB and Associates, Inc.              voice: (405) 954-7176 (work)
5909 NW Expwy Suite 209                         (405) 366-6248 (home)
Oklahoma City, Ok.  73132            
 
From Timothy Tue Jun 15 15:37:33 BST 1993
Date: Tue, 15 Jun 93 15:37:33 BST
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu, tim@MATHS.TCD.IE
To: LitProg@shsu.edu, iapa!ctrbdo@mailhost.ecn.uoknor.edu
Subject: Re: Help: "Change file entry did not match..."
 
> > This is TANGLE, C Version 4.2
> > *1*11*19*29*37*50*65*70*77*94*112*123*143*156*163*171*179*182*188*189
> > ! Change file entry did not match. (change file l.61)
> > @d banner=='This is TANGLE, Version 4.2'
> > 
> > Writing the output file.....500..
> > Done.
> > (Pardon me, but I think I spotted something wrong.)
> > make: *** [tangle.p] Error 1
 
So, your tangle.web and tangle.ch do not match --
they correspond to different versions of tangle.
Just change the change file tangle.ch to read
 
@x
@d banner=='This is TANGLE, Version 4.1'
@y
 
or whatever, as in tangle.web .
 
Of course, there might be other changes that don't match,
though you might well be lucky --
even if tangle.web has been changed in the newer version,
these changes could easily have no intersection
with the changes in tangle.ch .
 
> You know... installing TeX is not nearly as easy as most of the GNU
> stuff I'm used to working with... :-(
 
The problem above seems to me _exactly_ the same as if you are
patching the wrong version of a file.
In fact I would say that tangle is much easier to use than diff/patch,
if less flexible.
 
Timothy Murphy  
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Joachim Tue Jun 15 18:09:28 +0100 1993
Date: Tue, 15 Jun 1993 18:09:28 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: litprog@shsu.edu (Literate Programming discussion)
Subject: LaTeX support for CWEB, 2nd round
 
Here we go again.
 
Version 0.2 of the cweb style is ready for distribution.
 
Most important changes:
  * `cweb' is a style now, not an option.
  * It supports (and needs) the recent version of CWEB (3.0 beta).
  * It runs with older versions of LaTeX, too.
 
cweb.sty is now considered as a stable alpha version. It's not beta
yet, since it still builds upon the article style. The final version
will be a style file on its own. I've appended the respective History
entry FYI.
 
Since it's stable, I moved it from the hidden directory to a public
area, namely the Literate Programming Archive:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/c.c++
	file cweb-sty-0.2.tar.Z
 
Use the archive at off-US [sic!] business hours, our international
bandwidth is narrow.
 
CWEB 3.0 beta is also there, but US folks might want to fetch it from
labrea.stanford.edu:/alpha.
 
Enjoy
    Joachim
 
---------------- History entry:
 
Version 0.2	[15 Jun 93]
 
	cweb is now a style, not an option.
 
	CWEAVE markup has changed in April '93. Documents and
	implements the new and changed tags.
	    In particular, supports the group level construct of
	starred sections, i.e., `@**', `@*1', etc.
 
	Handles  @( foo @>  constructs.
		[Problem reported by Michael Mueller <mimu@mpi-sb.mpg.de>]
 
	The detection of `@.' entries is more robust now.
 
	Works with LaTeX versions prior to 1992, too.
		[Problem reported by Michael Mueller <mimu@mpi-sb.mpg.de>]
 
	Allows an optional \con at the file end (was mandatory before).
	    Typesets identifier index or refinement list only when
	they exist.
 
	Improved the documentation, both internal and user.
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From leew@cs.utexas.edu Tue Jun 15 15:21:30 -0500 1993
Date: Tue, 15 Jun 1993 15:21:30 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, ravenek@chem.vu.nl
Subject: Re: Nuweb on Macintosh
 
Walter Ravenek notes:
 
  > - function unlink is UNIX. Fortunately there is a unix library
  > with my developing system THINK C, but it should not be used.
 
The corresponding Standard C function is ``remove.''  Quoting from
Plauger & Brodie's _Standard C_ book:
 
	    int remove(const char *filename);
 
	The function removes the file with the filename {\tt filename}
	and returns zero if successful.  If the file is open when you
	remove it, the result is implementation-defined.  Once you
	remove it, you cannot open it as an existing file.
 
I recommend to all concerned that they change all their ``unlinks''
(Unix) to ``removes'' (Standard).  If your compiler does not support
Standard C (as, alas, many compilers still do not), a #ifdef is in
order.
 
		 -- Lee
 
From leew@cs.utexas.edu Wed Jun 16 12:26:40 -0500 1993
Date: Wed, 16 Jun 1993 12:26:40 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu
Subject: Maintaining multiple implementations in a [C] web.
 
I've been having a bit of success with the following technique,
and I thought I ought to spread it around.  It should work in any LP
system that supports C programming (or any other language that supports
conditional compilation).
 
The problem is to write a web that will compile unchanged under both
Brand X and Brand Y compilers, which are notoriously incompatible.
The program has to do something (unspecified here) that cannot be
written in Standard C (or one of the compilers may not yet support the
standard).  Using CWEB notation, we can organize our program something
like this:
 
-----------
 
@*The Program.
Here we put all the portable stuff that will work unchanged,
regardless of the compiler.
@c
...
@<Now we do some non-portable stuff@>@;
...
 
@*Brand X Implementation.
Here we put all the code specific to the Brand X compiler.
@<Now we do some non-portable stuff@>=
#ifdef BRAND_X
@#
    @<Code specific to the Brand X compiler@>@;
@#
@#endif
 
@*Brand Y Implementation.
Here we put all the code specific to the Brand Y compiler.
@<Now we do some non-portable stuff@>=
#ifdef BRAND_Y
@#
    @<Code specific to the Brand Y compiler@>@;
@#
@#endif
 
-----------
 
The @#'s aren't really necessary, but they make the woven output look
nicer.  The trick is that when we tangle the web, all the compiler-
specific code is enclosed in #ifdef/#endif wrappers, so only the
appropriate code will be compiled by a given compiler.  Of course, the
BRAND_n constants have to be chosen to be unique to a the given
compiler, and preferably, supplied automatically, but that doesn't seem
to be a problem in practice.  I also tend to use the #ifdef/#endif
wrappers around every code part in the ``Brand $n$ Implementation''
sections.  It makes the web a little longer than need be, but it
allows me to safely use the same section names in each of the
implementation parts.
 
This technique doesn't displace change files; it supplements them.
The rule of thumb I use is that code I'm going to support goes into
the web.  Options I don't intend to support go into change files.
 
		-- Lee
 
From Denis Thu Jun 17 12:14:38 +0200 1993
Date: Thu, 17 Jun 93 12:14:38 +0200
From: Denis Roegel <Denis.Roegel@loria.fr>
Reply-To: LitProg@SHSU.edu, Denis.Roegel@LORIA.FR
To: LITPROG@SHSU.edu
Subject: CWEB: alphab. ordering of sections
 
I am using CWEB 2.8 and I ran into a small problem.
The names of my sections are french names, so some of them
have accents. The problem is that the list of the section names
doesn't put them in the right order when accents arise. 
Let me give an example:
 
Suppose I have two sections @<\'el\`eves@> and @<autres fonctions@>.
When processed by cweave, the list of the section names will show
@<\'el\`eves@> first, then @<autres fonctions@>, etc...
I would like @<\'el\`eves@> to be classified as @<eleves@> for instance.
 
So, is there any way to enforce an alphabetic order ?
 
Thanks in advance,
 
Denis. (roegel@loria.fr)
 
From Timothy Thu Jun 17 17:54:32 BST 1993
Date: Thu, 17 Jun 93 17:54:32 BST
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu, tim@MATHS.TCD.IE
To: LitProg@shsu.edu, schrod@iti.informatik.th-darmstadt.de
Subject: Re: LaTeX support for CWEB, 2nd round
 
> CWEB 3.0 is also there (as cweb.tar.Z), but US folks might want to
> fetch it from labrea.stanford.edu:/pub/cweb.
 
I don't think you said (this time) where "there" is.
 
Timothy Murphy  
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From leew@cs.utexas.edu Thu Jun 17 11:55:14 -0500 1993
Date: Thu, 17 Jun 1993 11:55:14 -0500
From: leew@cs.utexas.edu (Lee Wittenberg)
Reply-To: LitProg@SHSU.edu, leew@CS.UTEXAS.EDU
To: LitProg@shsu.edu, Denis.Roegel@loria.fr
Subject: Re: CWEB: alphab. ordering of sections
 
Denis Roegel asks:
 
  > I am using CWEB 2.8 and I ran into a small problem.
  > The names of my sections are french names, so some of them
  > have accents. The problem is that the list of the section names
  > doesn't put them in the right order when accents arise. 
  > Let me give an example:
  > 
  > Suppose I have two sections @<\'el\`eves@> and @<autres fonctions@>.
  > When processed by cweave, the list of the section names will show
  > @<\'el\`eves@> first, then @<autres fonctions@>, etc...
  > I would like @<\'el\`eves@> to be classified as @<eleves@> for instance.
  > 
  > So, is there any way to enforce an alphabetic order ?
 
[I'm working from a CWEB 3.0 beta listing rather than 2.8, but things
should be pretty similar.]
 
The only way I can see to do this is to play around with the
|web_strcmp| function in common.w (via change file, of course).
CTANGLE & CWEAVE put section names into a binary search tree. CWEAVE
simple writes these names using an inorder traversal to get the output
in alphabetical order.  It _should_ be fairly easy to get |web_strcmp|
to ignore certain TeX control sequences.  The only possible drawback
is that if you have both @<eleven something@> and @<\'el\`eves@> in a
web, then the prefix @<ele...@> is no longer unique.  I don't think it
should be much problem in practice, however.
 
Not a great solution, but it will work (without making any webs you
create non-standard -- they will still go through the standard CWEAVE;
the alphabetizing will just be different).
 
Is there a better, easier fix that I missed?  Anyone?
 
		 -- Lee
 
From Joachim Thu Jun 17 18:07:44 +0100 1993
Date: Thu, 17 Jun 1993 18:07:44 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: litprog@shsu.edu (Literate Programming discussion)
Subject: Re: LaTeX support for CWEB, 2nd round
 
I wrote:
> 
> Version 0.2 of the cweb style is ready for distribution.
 
It's version 0.3 now.
 
> Most important changes:
>   * `cweb' is a style now, not an option.
>   * It supports (and needs) the recent version of CWEB (3.0 beta).
>   * It runs with older versions of LaTeX, too.
 
Change from 0.2 to 0.3:
 
    * It supports (and needs) CWEB 3.0.
 
> [It's in the Literate Programming Archive]
> 
> CWEB 3.0 beta is also there, but US folks might want to fetch it from
> labrea.stanford.edu:/alpha.
 
CWEB 3.0 is also there (as cweb.tar.Z), but US folks might want to
fetch it from labrea.stanford.edu:/pub/cweb.
 
Enjoy
    Joachim
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Timothy Fri Jun 18 0:56:38 BST 1993
Date: Fri, 18 Jun 93 0:56:38 BST
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu, tim@MATHS.TCD.IE
To: litprog@shsu.edu
Subject: cweb-3.0 on the Mac
 
Here are change files for ctangle.w and common.w
using Think C on the Mac.
They can be retrieved from ftp.maths.tcd.ie
in pub/Mac/TeX .
The application ctangle and the project to make it
are also there, in HQX format.
 
This is the change file for CWEB's COMMON under Think C on the Macintosh.
 
created:
    17-JUN-1993 Timothy Murphy <tim@maths.tcd.ie>
 
modified:
	not yet!
 
@x l.5  (TGM)
% Version 3.0 --- June 1993
@y
% Version 3.0 --- June 1993
% With changes for THINK C on the Macintosh
% by Timothy Murphy <tim@@maths.tcd.ie> June 1993
@z
 
@x l.92  Memory for large arrays must be allocated dynamically
  @<Initialize pointers@>;
@y
  @<Allocate memory for large arrays@>;
  @<Initialize pointers@>;
@z
 
@x l.162  (TGM)
#include <stdio.h>
@y
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
@z
 
@x l.417  Memory for large arrays must be allocated dynamically
boolean changed_section[max_sections]; /* is the section changed? */
@y
boolean *changed_section; /* is the section changed? */
@z
 
@x l.590  Memory for large arrays must be allocated dynamically
char byte_mem[max_bytes]; /* characters of names */
char *byte_mem_end = byte_mem+max_bytes-1; /* end of |byte_mem| */
name_info name_dir[max_names]; /* information about names */
name_pointer name_dir_end = name_dir+max_names-1; /* end of |name_dir| */
@y
char *byte_mem; /* characters of names */
char *byte_mem_end; /* end of |byte_mem| */
name_info *name_dir; /* information about names */
name_pointer name_dir_end; /* end of |name_dir| */
@z
 
@x l.1403  (TGM)
extern int strlen(); /* length of string */
@y
extern size_t strlen(); /* length of string */
@z
 
@x l.1409 Memory for large arrays must be allocated dynamically
@** Index.
@y
@** Mac specific code.
Unfortunately, the variable |h| is pre-defined in |MacHeaders|.
(It represents the horizontal co-ordinate.)
So we replace it here by |H|.
 
@d h H
 
@ We allocate memory for large arrays dynamically.
 
@<Allocate memory for large arrays@>=
changed_section = (boolean*)calloc(max_sections, sizeof(boolean));
byte_mem = (char*)calloc(max_bytes, sizeof(char));
byte_mem_end= byte_mem+max_bytes-1;
name_dir = (name_info*)calloc(max_names, sizeof(name_info));
name_dir_end= name_dir+max_names-1;
if (changed_section==NULL || byte_mem==NULL || name_dir==NULL)
  fatal("common.c: ", "memory allocation failure");
 
@** Index.
@z
 
This is the change file for CWEB's CTANGLE under Think C on the Macintosh.
 
created:
    17-JUN-1993 Timothy Murphy <tim@maths.tcd.ie>
 
modified:
	not yet!
 
@x l.5
% Version 3.0 --- June 1993
@y
% Version 3.0 --- June 1993
% With changes for THINK C on the Macintosh
% by Timothy Murphy <tim@@maths.tcd.ie> June 1993
@z
 
@x l.75
extern int strlen(); /* length of string */
@y
extern size_t strlen(); /* length of string */
@z
 
@x l.93
  argc=ac; argv=av;
  program=ctangle;
@y
#ifdef THINK_C
  ac = ccommand(&av);
#endif
  argc=ac; argv=av;
  program=ctangle;
  @<Allocate memory for large arrays@>@;
@z
 
@x l.109
@d max_bytes 90000 /* the number of bytes in identifiers,
  index entries, and section names; used in |"common.w"| */
@d max_toks 270000 /* number of bytes in compressed \CEE/ code */
@d max_names 4000 /* number of identifiers, strings, section names;
  must be less than 10240; used in |"common.w"| */
@d max_texts 2500 /* number of replacement texts, must be less than 10240 */
@d hash_size 353 /* should be prime; used in |"common.w"| */
@d longest_name 1000 /* section names shouldn't be longer than this */
@y
@d max_bytes 45000 /* the number of bytes in identifiers,
  index entries, and section names; used in |"common.w"| */
@d max_toks 60000 /* number of bytes in compressed \cee/ code */
@d max_names 2000 /* number of identifiers, strings, section names;
  must be less than 10240; used in |"common.w"| */
@d max_texts 1250 /* number of replacement texts, must be less than 10240 */
@d hash_size 353 /* should be prime; used in |"common.w"| */
@d longest_name 500 /* section names shouldn't be longer than this */
@z
 
@x common.w l.152
#include <stdio.h>
@y
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#ifdef THINK_C
#include <console.h>
#endif
@z
 
@x common.w l.590 Memory for large arrays must be allocated dynamically
extern char byte_mem[]; /* characters of names */
extern char *byte_mem_end; /* end of |byte_mem| */
extern name_info name_dir[]; /* information about names */
@y
extern char *byte_mem; /* characters of names */
extern char *byte_mem_end; /* end of |byte_mem| */
extern name_info *name_dir; /* information about names */
@z
 
@x common.w l.417 Memory for large arrays must be allocated dynamically
extern boolean changed_section[]; /* is the section changed? */
@y
extern boolean *changed_section; /* is the section changed? */
@z
 
@x l.157 Memory for large arrays must be allocated dynamically
text text_info[max_texts];
text_pointer text_info_end=text_info+max_texts-1;
text_pointer text_ptr; /* first unused position in |text_info| */
eight_bits tok_mem[max_toks];
eight_bits *tok_mem_end=tok_mem+max_toks-1;
@y
text *text_info;
text_pointer text_info_end;
text_pointer text_ptr;
eight_bits *tok_mem;
eight_bits*tok_mem_end;
@z
 
@x l.1523 Memory for large arrays must be allocated dynamically
@** Index.
@y
@** Mac specific code.
Unfortunately, the variable |h| is pre-defined in |MacHeaders|.
(It represents the horizontal co-ordinate.)
So we replace it here by |H|.
 
@d h H
 
@ We allocate memory for large arrays dunamically.
 
@<Allocate memory for large arrays@>=
text_info = (text*)calloc(max_texts, sizeof(text));
text_info_end= text_info+max_texts-1;
tok_mem = (eight_bits*)calloc(max_toks, sizeof(eight_bits));
tok_mem_end= tok_mem+max_toks-1;
if (text_info==NULL || tok_mem==NULL)
  fatal("ctangle: ", "memory allocation failure");
 
@** Index.
@z
 
Timothy Murphy  
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From George Fri Jun 18 11:56:31 CST 1993
Date: Fri, 18 Jun 1993 11:56:31 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
Subject: Re: LaTeX support for CWEB, 2nd round
 
On Thu, 17 Jun 1993 18:07:44 +0100 (MESZ), Joachim Schrod
<schrod@iti.informatik.th-darmstadt.de> posted:
> CWEB 3.0 is also there (as cweb.tar.Z), but US folks might want to fetch it
> from labrea.stanford.edu:/pub/cweb.
 
Sorry, between the start of summer session, being ill, having to deal with
a few picky people on a grant request (which looks successful!), and a few
other things, I have gotten behind.  The CWEB 3.0 files are now on
Niord.SHSU.edu (192.92.115.8) in [FILESERV.CWEB] for consumption.  This
means for mail retrieval, you can use:
 SENDME CWEB
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu)
and get an 8 part UUENCODEd ZIP archive.  Also, for anonymoous ftp
retrieval, a the ZIP archive CWEB-3_0.ZIP is available there, or the
individual files in [FILESERV.CWEB-3_0...].  Finally, Niord's gopher server
has been updated to reflect the change in the directory path:
 TeX-related Materials/
   Literate Programming Library/
     CWEB (version 3.0)/
 
I know a few other things have been updated as well and hope to attend to
them soon.
 
--George
 
From ralexand@mason1.gmu.edu Fri Jun 18 14:57:37 -0400 1993
Date: Fri, 18 Jun 1993 14:57:37 -0400 (EDT)
From: ralexand@mason1.gmu.edu (Roger T Alexander)
Reply-To: LitProg@SHSU.edu, ralexand@MASON1.GMU.EDU
To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
Subject: Re: LaTeX support for CWEB, 2nd round
 
> 
> The CWEB 3.0 files are now on
> Niord.SHSU.edu (192.92.115.8) in [FILESERV.CWEB] for consumption.  This
> means for mail retrieval, you can use:
>  SENDME CWEB
> in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu)
> and get an 8 part UUENCODEd ZIP archive.  Also, for anonymoous ftp
> retrieval, a the ZIP archive CWEB-3_0.ZIP is available there, or the
> individual files in [FILESERV.CWEB-3_0...].  Finally, Niord's gopher server
> has been updated to reflect the change in the directory path:
>  TeX-related Materials/
>    Literate Programming Library/
>      CWEB (version 3.0)/
>
 
Does this meadn that CWEB 3.0 is "officially" released for general
consumption (i.e., not an alpha or beta version) ?
 
From Silvio Fri Jun 18 12:50:04 -0700 1993
Date: Fri, 18 Jun 93 12:50:04 -0700
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu, levy@MATH.BERKELEY.EDU
To: LitProg@shsu.edu
Subject: cweb 3.0
 
In response to Roger T Alexander's incredulous question:
 
Yes, cweb 3.0 is released as of June 16.  You can find it on labrea.
 
Silvio
 
From ohl@chico.harvard.edu Fri Jun 18 18:46:00 -0400 1993
Date: Fri, 18 Jun 93 18:46:00 -0400
From: ohl@chico.harvard.edu (Thorsten Ohl)
Reply-To: LitProg@SHSU.edu, ohl@CHICO.HARVARD.EDU
To: Literate Programming Discussion List <litprog@shsu.edu>
Subject: CWEB 3.0: funny indentation
 
The following (nonsense) WEB shows an inconsistency in the formatting
of CWEB 3.0 [both with the classic plain TeX version and in Joachim's
cweb.sty]:
 
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< cut here >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
% bug.w --
@ Here is a visible format definition.
@f bar int
@f foo int
@d foo 1
@d bar 2
 
@ Here is a hidden format definition, which causes a funny indentation
of the first macro definition.
@s baz int
@d foo 1
@d bar 2
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< cut again >>>>>>>>>>>>>>>>>>>>>>>>>>>>>
 
In my (not so) humble opinion, the first macro definition should
*not* be indented.
 
Cheers,
-Thorsten
 
/// Thorsten Ohl, Physics Dept, Harvard University, Cambridge, MA 02138, USA
//////// net: ohl@physics.harvard.edu, ohl@crunch.ikp.physik.th-darmstadt.de
////////////////////////////// voice: +1-617-495-3219,  fax: +1-617-496-8396
 
From Hans-Hermann Mon Jun 21 11:09:14 MEZ 1993
Date: Mon, 21 Jun 93 11:09:14 MEZ
From: Hans-Hermann Bode <HHBODE@dosuni1.rz.Uni-Osnabrueck.DE>
Reply-To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
To: LitProg@SHSU.edu, krommes@THEORY.PPPL.GOV, "George D. Greenwade" <bed_gdg@shsu.edu>, texinfo1@rusinfo.rus.uni-stuttgart.de
Subject: Re: FWEB 1.30 now available --- FWEB 1.30 NOW AVAILABLE ---
 
>  Version 1.30 (non-beta version) of FWEB is now available from
>
>        lyman.pppl.gov:/pub/fweb/fweb-1.30.tar.Z
 
I have again compiled an extract for quick and easy use on MS-DOS. It is
available as fweb130x.zip in the directory pub/msdos/tex/web at
ftp.rz.uni-osnabrueck.de. This file replaces fwebexe.zip. It is packed with
ZIP v1.9, so you must use UNZIP v5.0 or PKUNZIP v2.0 or later to unpack. I
append the readme file below.
 
Good luck,
 
Hans-Hermann Bode
Arbeitsgruppe Systemforschung, Universitaet Osnabrueck
Tel.: (49)-541-9692545
e-mail: HHBODE@DOSUNI1.BITNET, hhbode@dosuni1.rz.uni-osnabrueck.de
 
%--READ_ME.pc-from-fweb130x.zip-----------------------------------------------
								-*-Text-*-
This archive is an extract of John A. Krommes' ``WEB System of Structured
Software Design and Documentation for C, C++, Fortran, Ratfor, and TeX''
(Version 1.30)---briefly FWEB---, that contains everything necessary to run
the system on a PC. This collection has been compiled by Hans-Hermann Bode
(hhbode@dosuni1.rz.uni-osnabrueck.de or HHBODE@DOSUNI1.BITNET).
 
Herein are the following files:
 
./read_me.pc		this file
./read_me		readme file of the original distribution
./demos			directory containing several demo WEBs
./demos/read_me.dem
./demos/intro.tex
./demos/verbatim.sty
./demos/newton.f
./demos/newton.web
./demos/adj.web
./demos/breakpt.web
./demos/demo.ch
./demos/demo.web
./demos/macros.hwe
./demos/xnewton.web
./demos/series.web
./ftangle.exe		the tangle processor including Ratfor capability
./ftangle0.exe		the tangle processor excluding Ratfor capability
./fweave.exe		the weave processor
./guide.dvi		reference guide
./guid-inx.dvi		index of the reference guide
./fwebman.dvi		the manual
./fweb-inx.dvi		index of the manual
./fwebmac.dvi		documentation of the macro package
./fwebmac.sty		the macro package
./fweb.sty		sample style file
./fweb.man		manual page
 
Copy the three exe files into a directory where your executables reside and
fwebmac.sty into a directory where TeX looks for its input. Optionally, you
can (customize and) copy fweb.sty into your FWEB working directory (see the
manual page for further options). After printing (caution: fwebman.dvi
results in about 180 pages!) and reading the documentation you might be able
to run FWEB.
 
The problems you may run into most likely are---as always---due to memory
limitations under PC/MS-DOS. Both the weave and the tangle processors need a
minimum of approx. 500 KByte of available memory. If one of those complains
about insufficient memory, you should take the following measures into
account:
 
1. Clean-up your memory. Delete everything from your config.sys and
autoexec.bat files that installs resident in conventional memory but isn't
really needed. (Do you really need the display.sys driver?) After this,
reboot the system and try again.
 
2. If you don't need the Ratfor processor, you can use ftangle0 instead of
ftangle. Both tangle processors are identical except that ftangle0 doesn't
understand Ratfor and therefore gets along with about 30 KByte less than
ftangle.
 
3. If none of the solutions above will lead to success, look in the
documentation for the section on dynamic memory allocation (Appendix N) and
find out how you can customize the sizes of internal tables. You should
distinguish between two situations: first, the machine's memory may overflow
and you'll have to shrink some arrays to fit the processor in memory;
second, the sizes of one or more arrays may be too small for a certain job
and you'll have to enlarge them (clearly, neither method 1 nor 2 would help
in this case). For instance, I could tangle all the demos with 527360 Byte
available on the system using ftangle0 with -yn750 option.
 
Note that the files in this archive are only a small part of the whole FWEB
system. You should be able to obtain all sources, documentation, demos, and
installation stuff for various machines from the same site as you got the
archive described here.
									-h2b
 
From George Mon Jun 21 08:25:45 CST 1993
Date: Mon, 21 Jun 1993 08:25:45 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
Subject: Re: FWEB 1.30 now available --- FWEB 1.30 NOW AVAILABLE ---
 
On Mon, 21 Jun 93 11:09:14 MEZ, Hans-Hermann Bode
<HHBODE@dosuni1.rz.Uni-Osnabrueck.DE> posted:
> >  Version 1.30 (non-beta version) of FWEB is now available from
> >
> >        lyman.pppl.gov:/pub/fweb/fweb-1.30.tar.Z
>
> I have again compiled an extract for quick and easy use on MS-DOS. It is
> available as fweb130x.zip in the directory pub/msdos/tex/web at
> ftp.rz.uni-osnabrueck.de. This file replaces fwebexe.zip. It is packed with
> ZIP v1.9, so you must use UNZIP v5.0 or PKUNZIP v2.0 or later to unpack. I
> append the readme file below.
 
Thanks!!  I have retrieved the file and placed it in [FILESERV.FWEB130X] on
Niord.SHSU.edu (192.92.115.8) (renamed to FWEB130-X.ZIP for consistency
purposes with FILESERV).  To retrieve the 28-part UUENCODEd ZIP archive
Hans-Hermann created, include:
 SENDME FWEB130X
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu). 
Also, this is available for gopher retrieval from Niord (port 70) in:
  TeX-related Materials/
     Literate Programming Library/
 
--George
 
From Kayvan Mon Jun 21 09:35 PDT 1993
Date: Mon, 21 Jun 93 09:35 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
Subject: Re: FWEB 1.30 now available --- FWEB 1.30 NOW AVAILABLE ---
 
I hope this PC version was created from the fweb-1.30a.tar.Z of Jun 18th.
 
The earlier release (there for a day or two) had a couple of problems
that were quickly fixed.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Hans-Hermann Tue Jun 22 11:28:52 MEZ 1993
Date: Tue, 22 Jun 93 11:28:52 MEZ
From: Hans-Hermann Bode <HHBODE@dosuni1.rz.Uni-Osnabrueck.DE>
Reply-To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
Subject: Re: FWEB 1.30 now available --- FWEB 1.30 NOW AVAILABLE ---
 
>I hope this PC version was created from the fweb-1.30a.tar.Z of Jun 18th.
 
No, it wasn't.
 
>The earlier release (there for a day or two) had a couple of problems
>that were quickly fixed.
 
What are these problems? FWEB 1.30 has been in beta test for quite a long
time. Hence, they should not be too seriously. Anyway, updating fweb130x
now has a very low priority for me and I will not do it soon. If anyone
else will do it---fine.
 
Hans-Hermann Bode
 
From marcus@x4u.desy.de Wed Jun 23 17:37:52 +0200 1993
Date: Wed, 23 Jun 93 17:37:52 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: Literate Programmers <litprog@shsu.edu>
Subject: Literate Programming on the World Wide Web [regular posting]
 
[[This is a regular posting to LitProg mailing list and Comp/TeX discussion
  groups, formatted for Emacs outline mode. Cut here and copy rest to file.]]
 
-----------------------------------------------------------------------------
* Literate Programming on the World Wide Web
-----------------------------------------------------------------------------
   FYI, there is a wealth of information on Literate Programming,
   the art of structured programming and documentation [especially
   using WEB-like systems with TeX formatting] available on the
   World Wide Web [WWW], a distributed HyperText system, a network
   of documents connected by links which can be activated electronically.
   Examples for LitProg environments are WEB for Pascal (DEK), CWEB for C/C++
   (Levy/Knuth), FWEB for C/C++/Fortran/ratfor/TeX (Krommes)...and many more.
-----------------------------------------------------------------------------
* How to get to the Web
-----------------------------------------------------------------------------
   If you have a WWW browser up and running, try going to
 
		        http://info.desy.de:80/
 
   (this brings you to the DESY home page), and look for "User Documents"
   in the panel which appears. The precise URL is
 
	   http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
 
   If you have no clue what WWW is, you can go over the Internet with
 
        	telnet info.cern.ch
 
   which brings you to the WWW Home Page at CERN. You are now using the
   simple line mode browser. To move around the Web, enter the numbers
   given after an item. To go to the Literate Programming documents, enter
 
	go http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
 
   This is what you should see now:
-----------------------------------------------------------------------------
* What you will see here
-----------------------------------------------------------------------------
 
                           LITERATE PROGRAMMING
 
   __________________________________________________________________
 
  Getting Started[1]      A first look into Literate Programming with WEB
 
   Editing                GNU Emacs mode for WEB programming: Sources[2]
                         and Manual[3] (PostScript)
 
   Tools[4]               List of common, freely available Literate
                         Programming environments
 
   Examples[5]            Literate Programming archives and selected
                         examples
 
   LitProg Library[6]     George D. Greenwade's Literate Programming
                         Library at Niord.shsu.edu
 
   LITPROG Mailing List[7]
                          Information on the Literate Programming
                         Mailing List
 
   FAQs[8]                Lists of Frequently Asked Questions for WEB
                         systems
 
   Further Reading        Nelson Beebe's Literate Programming
                         bibliography at ftp.math.utah.edu in directory
                         /pub/tex/bib[9] (files litprog.*)
 
   HyperLitProg[10]       Literate Programming using HyperText[11]
                         Techniques
 
   OO-LitProg[12]         Thoughts on Object-Oriented[13] Literate
                         Programming
 
 [[Now you can continue climbing down the documentation tree by
   entering numbers 1-13 and follow your own interests]]
-----------------------------------------------------------------------------
* More on Browsing the Web
-----------------------------------------------------------------------------
   The by far nicest way of "browsing" through WWW uses the X-Terminal
   based tool "NCSA Mosaic". Binaries for many platforms (ready for use)
   and sources are available via anonymous FTP from
   ftp.ncsa.uiuc.edu in directory Web/xmosaic.
     The general FTP repository for browser software is info.cern.ch
  (including a hypertext browser/editor for NeXTStep 3.0)
     If you cannot go through TELNET, you can still retrieve WWW
   documents by e-mail: send a mail to listserv@info.cern.ch with a
   line in it saying just
				HELP
   to get back detailed instructions. Your mail system must have a
   mail gateway to the internet mail.
-----------------------------------------------------------------------------
* Contact for Further Information
-----------------------------------------------------------------------------
   Please feel free to contact me for questions, suggestions and further
   contributions, or just to tell me whether you found this information
   useful in any way. For questions related to WWW, consult the WWW-FAQ:
   a draft of this text is available via anonymous FTP from ftp.desy.de
   in /pub/faq/www/www-faq (it will later be avaible at rtfm.mit.edu,
   as other Usenet FAQ lists), or on WWW at
   http://www.vuw.ac.nz:80/who/Nathan.Torkington/ideas/www-faq.html
   Enjoy.
 
   13/06/93   Marcus Speh  E-mail:  INTERnet: marcus@x4u.desy.de
	                            BITnet:   i02msp@dhhdesy3
	                            DECnet:   13313::speh
-----------------------------------------------------------------------------
Local Variables:
mode: outline
outline-regexp: "^\*"
eval: (hide-body)
End:
 
From tfj@apusapus.demon.co.uk Wed Jun 23 19:11:54 GMT 1993
Date: Wed, 23 Jun 93 19:11:54 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: Literate programming in (sic) TeX
 
I need to write some TeX code. Being a believer in literate progamming I
therefore want to write my TeX code with some form of TANGLE/WEAVE. Anyone
know of the existence of versions of these tools which accept TeX as the
``programming language''? 
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From shell@mailhost.cs.pdx.edu Wed Jun 23 14:29:31 -0700 1993
Date: Wed, 23 Jun 1993 14:29:31 -0700 (PDT)
From: shell@mailhost.cs.pdx.edu (Edith M Brown)
Reply-To: LitProg@SHSU.edu, shell@MAILHOST.CS.PDX.EDU
To: LitProg@shsu.edu, marcus@x4u.desy.de
Subject: Re: Literate Programming on the World Wide Web [regular posting]
 
> 
> [[This is a regular posting to LitProg mailing list and Comp/TeX discussion
>   groups, formatted for Emacs outline mode. Cut here and copy rest to file.]]
> 
> -----------------------------------------------------------------------------
> * Literate Programming on the World Wide Web
> -----------------------------------------------------------------------------
>    FYI, there is a wealth of information on Literate Programming,
>    the art of structured programming and documentation [especially
>    using WEB-like systems with TeX formatting] available on the
>    World Wide Web [WWW], a distributed HyperText system, a network
>    of documents connected by links which can be activated electronically.
>    Examples for LitProg environments are WEB for Pascal (DEK), CWEB for C/C++
>    (Levy/Knuth), FWEB for C/C++/Fortran/ratfor/TeX (Krommes)...and many more.
> -----------------------------------------------------------------------------
> * How to get to the Web
> -----------------------------------------------------------------------------
>    If you have a WWW browser up and running, try going to
> 
> 		        http://info.desy.de:80/
> 
>    (this brings you to the DESY home page), and look for "User Documents"
>    in the panel which appears. The precise URL is
> 
> 	   http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
Hello,
I was using xmosaic to get to this URL, but I kept getting an error.  The
system kept telling me that the info server was not accessible or it was
refusing to serve the document to me.  I their some sort of special per-
mission I need for the server?
 
-- 
 
Edith Brown
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Taken from the Gummy Bears:
 
Black Knight:"What kind of fool do you take me for?"
 
Troll: "Duuuhhh, I don't know. How many kinds are there?"
 
From bart@cs.tamu.edu Wed Jun 23 18:55:38 CDT 1993
Date: Wed, 23 Jun 93 18:55:38 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: LitProg@shsu.edu, tfj@apusapus.demon.co.uk
Subject: Re:  Literate programming in (sic) TeX
 
FWEB does!  It outputs a .sty file unless you tell it to use a
different extension.
 
Bart Childs
 
From ae1181t@stnfor.ae.ge.com Wed Jun 23 20:54:46 -0400 1993
Date: Wed, 23 Jun 1993 20:54:46 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
Subject: Re: Literate programming in (sic) TeX
 
Try non-language specific webs : noweb,nuweb,funnelWeb, and on dos CLiP.
Also to some extent FWEB.
Hope this helps. 
Osman
 
From Kayvan Wed Jun 23 21:50 PDT 1993
Date: Wed, 23 Jun 93 21:50 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
Subject: Literate programming in (sic) TeX
 
>>>>> "Trevor" == Trevor Jenkins <apple!apusapus.demon.co.uk!tfj> writes:
 
Trevor> I need to write some TeX code. Being a believer in literate
Trevor> progamming I therefore want to write my TeX code with some
Trevor> form of TANGLE/WEAVE. Anyone know of the existence of versions
Trevor> of these tools which accept TeX as the ``programming
Trevor> language''?
 
FWEB will do what you want.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From Lang@tu-harburg.dbp.de Thu Jun 24 11:07:37 +0100 1993
Date: Thu, 24 Jun 1993 11:07:37 +0100 (METDST)
From: Lang@tu-harburg.dbp.de (Bernhard Lang)
Reply-To: LitProg@SHSU.edu, Lang@TU-HARBURG.DBP.DE
To: LitProg@SHSU.edu.d400.de, tfj@APUSAPUS.DEMON.CO.uk.d400.de
Subject: Re: Literate programming in (sic) TeX
 
> 
> I need to write some TeX code. Being a believer in literate progamming I
> therefore want to write my TeX code with some form of TANGLE/WEAVE. Anyone
> know of the existence of versions of these tools which accept TeX as the
> ``programming language''? 
> 
> Regards, Trevor.
> 
Try Nuweb, thats language independent. You can pick it from ftp.shsu.edu, 
directory tex-archive/web/nuweb.
 
Bernhard.
 
{{{  Dr. Bernhard Lang  -----------------------------------------------
     email: lang@tu-harburg.dbp.de         TU Hamburg Harburg
                                           Technische Informatik I
}}}
...  Enter this fold to view behind the scenes  -----------------------
 
From Dave Thu Jun 24 10:36:58 GMT 1993
Date: Thu, 24 Jun 93 10:36:58 GMT
From: Dave Love <d.love@daresbury.ac.uk>
Reply-To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
To: LitProg@SHSU.edu
Subject: Should be an FAQ [was: Literate programming in (sic) TeX]
 
>>>>> On Thu, 24 Jun 93 09:31:34 MDT, Zdenek Wagner <WAGNER%BITNET.CSEARN@edu.SHSU> said:
 
 > Literate programming in TeX is supported by DOC.STY and DOCSTRIP.TEX. 
 
Hear, hear.  I'd urge anyone writing TeX macros to use the doc system.
[It's in the CTAN archives like shsu in `macros/latex/distribs/doc'.]
 
Pros relative to WEB-like systems:
 
* Built on TeX, so it can cope with things like changing category
  codes and is customisable through TeX (e.g., building
  installation/configuration procedures on top of docstrip).  Needs no
  new syntax.
 
* Only depends on (La)TeX (plus makeindex if you want the index); you
  don't need to import another tool to process the stuff.
 
* It's the de facto standard for the job in the TeX world e.g., the
  LaTeX3 project.
 
Possible cons:
 
* Documentation needs to be written in LaTeX, but the code can be any
  TeX or, indeed, any language.  The dependence on TeX as the
  typesetting system is obviously not an issue!
 
* No WEB-like `module' system (substitution of code chunks), but this
  has limited usefulness with TeX: it's a macro language anyhow, and
  there aren't many problems with the ordering of code (like having
  declarations preceding code).
 
* No pretty-printing; but the dynamic lexical structure of TeX
  militates against that anyhow.
 
* Generating a code index is slow.
 
From mckearney_s Thu Jun 24 13:31:38 +0100 1993
Date: Thu, 24 Jun 1993 13:31:38 +0100
From: mckearney_s <mckearney_s@bt-web.bt.co.uk>
Reply-To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK
To: litprog@shsu.edu
Subject: Are modules necessary?
 
Hello,
 
I have developed a WEB for Word system, based around the WORDWEB 
developed elsewhere, that does almost everything most WEB systems do 
including : cross-references, code indexes, find definition, etc.
 
Some people here have been using it and we have come to the conclusion 
that the formal structure of Text Part - Code Part is unnecessary in 
this WYSIWYG environment.  Having code chunks appear throughout the 
text seems to lead to a slightly different style of programming.
 
Does anyone else feel that the numbered module structure is more than 
simply a carry over from the parsing of the source file in the 
original WEB?  Cross-references can be handled using page numbers etc.
 
Before someone goes on about how much better TeX is over Word, etc I 
should say that if I had a free choice it would be TeX/LaTeX and in 
my environment most people will not move away from WYSIWYG 
environments.
 
Stephen Mc Kearney
 
From ae1181t@stnfor.ae.ge.com Thu Jun 24 10:01:42 -0400 1993
Date: Thu, 24 Jun 1993 10:01:42 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, mckearney_s@bt-web.bt.co.uk.ae.ge.com.ae.ge.com
Subject: Re: Are modules necessary?
 
Yes, since they allow you develop code without regard to the particular
compilers needs (sequence). Does your web has the same limitation as
the earlier one namely the 64k limit on the program size (due to the
wordbasics string size limit)? Even though I like (La)TeX based webs,
I would like to try ``word'' based ones (If it is available).
Osman
 
From Zdenek Thu Jun 24 09:31:34 MDT 1993
Date: Thu, 24 Jun 93 09:31:34 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, tfj@APUSAPUS.DEMON.CO.UK
Subject: Re: Literate programming in (sic) TeX
 
Literate programming in TeX is supported by DOC.STY and DOCSTRIP.TEX. They
are a part of the Mainz distribution and they are fully documented by the
same tool. You should retrieve INSTALL.MZ0 (e.g. form Niord.shsu.edu or
Stuttgart or from elsewhere). You will also need program MakeIndex to print
the index of macros. This program is also available from Niord.shsu.edu
(latest version 2.11).
 
Regards
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From tfj@apusapus.demon.co.uk Thu Jun 24 20:03:00 GMT 1993
Date: Thu, 24 Jun 93 20:03:00 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: Re: Literate programming in (sic) TeX
 
In message <CMM.0.90.4.740870897.beebe@plot79.math.utah.edu> you write:
 
Thanks for the response...
 
> Literate programming in TeX has already been described by Don Knuth
> in Volumes B and D of Computers and Typesetting,
 
but no in there he describes Literate Programming WITH TeX :-)
 
My requirements/objectives are to write TeX macros using a Literate
Programming Style.  Not something that even Knuth attempts in volumes B
and D.
 
> @Article{Mittelbach:TB10-2-245-273,
>   author =       "Frank Mittelbach",
>   title =        "{{The {\tt doc}--option}}",
>   journal =      TUGboat,
>   year =         "1989",
>   volume =       "10",
>   number =       "2",
>   pages =        "245--273",
>   month =        Jul,
> }
> 
> for LaTeX. 
 
I'll have a look but from what I recall the {\tt doc} option merely
pretty-prints a LaTeX style file. Still something different from what I
want.
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From arouse@math.utexas.edu Thu Jun 24 15:09:54 -0500 1993
Date: Thu, 24 Jun 93 15:09:54 -0500
From: arouse@math.utexas.edu
Reply-To: LitProg@SHSU.edu, arouse@MATH.UTEXAS.EDU
To: LitProg@shsu.edu, mckearney_s@BT-WEB.BT.CO.UK
Subject: Are modules necessary?
 
mckearney_s said:
>Does anyone else feel that the numbered module structure is more than 
>simply a carry over from the parsing of the source file in the 
>original WEB?  Cross-references can be handled using page numbers etc.
	I think I agree with you.
	When I first heard of Lit. Prog. and read about the subject I
developed the impression that the final document would resemble a
chapter from a textbook or a book and not a numbered sequence of
text/code segments as is currently the case. 
	I imagined that the code would be in its own box (or area) in
the document in the same way that photographs and other images are
included in newspapers, dictionaries, texts. I also thought that
actual images could be included. For example, in a program that draws
a line its progress could be graphically shown by pixel diagrams. Or a
sorting algorithm could include a graph of its performance on random
data.
	In other words I feel that the ideal product of a Literate
Programmer is to be able to produce a final document which is
indistinguishable from an ordinary expository/descriptive treatise.
Perhaps the best description I could give of the ideal program is, as
I first said, "something that looks like a chapter/section from
'Intro. to Algorithms' or another such book"
 
Allen Rouse
 
From arouse@math.utexas.edu Thu Jun 24 15:09:54 -0500 1993
Date: Thu, 24 Jun 93 15:09:54 -0500
From: arouse@math.utexas.edu
Reply-To: LitProg@SHSU.edu, arouse@MATH.UTEXAS.EDU
To: LitProg@shsu.edu, mckearney_s@BT-WEB.BT.CO.UK
Subject: Are modules necessary?
 
mckearney_s said:
>Does anyone else feel that the numbered module structure is more than 
>simply a carry over from the parsing of the source file in the 
>original WEB?  Cross-references can be handled using page numbers etc.
	I think I agree with you.
	When I first heard of Lit. Prog. and read about the subject I
developed the impression that the final document would resemble a
chapter from a textbook or a book and not a numbered sequence of
text/code segments as is currently the case. 
	I imagined that the code would be in its own box (or area) in
the document in the same way that photographs and other images are
included in newspapers, dictionaries, texts. I also thought that
actual images could be included. For example, in a program that draws
a line its progress could be graphically shown by pixel diagrams. Or a
sorting algorithm could include a graph of its performance on random
data.
	In other words I feel that the ideal product of a Literate
Programmer is to be able to produce a final document which is
indistinguishable from an ordinary expository/descriptive treatise.
Perhaps the best description I could give of the ideal program is, as
I first said, "something that looks like a chapter/section from
'Intro. to Algorithms' or another such book"
 
Allen Rouse
 
From Eric Fri Jun 25 16:07 +0000 1993
Date: Fri, 25 Jun 1993 16:07 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LITPROG@shsu.edu
Subject: Support for Allen Rouse's view
 
Allen Rouse writes:
 
>	When I first heard of Lit. Prog. and read about the subject I
>developed the impression that the final document would resemble a
>chapter from a textbook or a book and not a numbered sequence of
>text/code segments as is currently the case. 
>	I imagined that the code would be in its own box (or area) in
>the document in the same way that photographs and other images are
>included in newspapers, dictionaries, texts. I also thought that
>actual images could be included. For example, in a program that draws
>a line its progress could be graphically shown by pixel diagrams. Or a
>sorting algorithm could include a graph of its performance on random
>data.
>	In other words I feel that the ideal product of a Literate
>Programmer is to be able to produce a final document which is
>indistinguishable from an ordinary expository/descriptive treatise.
>Perhaps the best description I could give of the ideal program is, as
>I first said, "something that looks like a chapter/section from
>'Intro. to Algorithms' or another such book"
 
Perfectly true. For exactly this reason I maintain that a literate 
programming tool should be capable to cooperate with any formatter 
or wordprocessor one wants to use, without imposing any restrictions on 
the use of the choosen text processing system.  I consider it a severe
disadvantage if the LP-tool imposes a particular structure of chapters and 
sections on the documentation or prohibits the use of figures or tables.  
 
Eric W. van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Zdenek Fri Jun 25 12:41:19 MDT 1993
Date: Fri, 25 Jun 93 12:41:19 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: RE: Literate programming in (sic) TeX
 
Dave Love <d.love@daresbury.ac.uk> writes:
 
> Possible cons:
 
> * Generating a code index is slow.
 
This does not matter because you do not need to do it frequently. Anyway, on
my AT286 it is not much slower than running ctangle/cweave/tex.
 
Trevor Jenkins <tfj@apusapus.demon.co.uk> writes:
 
> I'll have a look but from what I recall the {\tt doc} option merely
> pretty-prints a LaTeX style file. Still something different from what I
> want.
>
> Regards, Trevor.
 
DOC is not only pretty printer. Of course, each LP tool may be misused. You
can e.g. place the whole C program into a single module and WEB will also be
degraded to a pretty printer.
 
There are two reasons (not mentioned by Dave Love) why TeX (LaTeX, AMS-TeX,
LAMS-TeX, AMS-LaTeX, etc.) macros should be documented by DOC and DOCSTRIP:
 
Users of TeX macros may not necessarily be programmers. The web source of TeX
macros will be useless for non-programmers. However, each TeX user has TeX and
in principal may have LaTeX and he/she will know how to install LaTeX and
DOC/DOCSTRIP. If you want to distributed your documented macros to
non-programmers, you have to give not only the web source but also tangled and
woven code.
 
If a user does not have DOC/DOCSTRIP, the documented file can be used AS IS.
The concept is similar as in c-no-web.
 
Tangling is not necessary. In C you will write something like:
 
@c
void main () {
@<Read input data@>@;
@<Do the job@>@;
@<Output the results@>@;
}
 
Large macros in TeX might be defined via DOC as:
 
% \begin{macro}{\MainMacro}
%    \begin{macrocode}
\def\MainMacro{%
  \ReadInputData
  \DoTheJob
  \OutputTheResults
}
%    \end{macrocode}
% \end{macro}
 
Macros \ReadInputData, \DoTheJob, \OutputTheResults may be explained and
defined anywhere.
 
It looks as if modules in C were replaced by small functions. There are good
reasons why TeX macros should be defined this way. It makes possible for users
to customize the macro. If I include the macro package and I need a different
version of \ReadInputData, I just redefine it. My definition deletes the old
definition unless I save it somewhere. (This cannot be done in WEB.)
 
You may be missing change files. Again, they are not needed because yoou can
redefine any macro in your document. However, there are occasions where a change
file is helpful. In such cases I successfully use wmerge from cweb.
 
All TeX wizards should study DOC and DOCSTRIP -- they are very good examples
of LP in TeX.
 
(I would like to see good examples of LP for METAFONT)
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From bart@cs.tamu.edu Sun Jun 27 13:24:28 CDT 1993
Date: Sun, 27 Jun 93 13:24:28 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: litprog@shsu.edu
Subject: Modules are valuable
 
I feel strongly that sections are extremely valuable.  Can we do
without them? Sure!  Can we do without the index?  Sure!  Just look at
FunnelWeb, NOweb, and NUweb.  Can we do without good typesetting of
the code?  Sure! Just look at same list.  Can we do without the table
of contents?  Sure!
 
Then, let us look at the state of software.  It is often quoted that
the 60 to 80 percent of the cost of a code in its lifetime is
maintenance!  Code should be done carefully and with full attention
paid to the reading aids.  I think Don Knuth's design was the result
of careful study, consideration of many alternatives, ... that are
typical of his works.  The reason that Norman Ramsey did NOweb was
because of the difficulty of convincing users to try such a
complicated system as WEB.
 
I think the solution is training!  WEB like systems offer a reasonable
way of weaving documentation and code together to make it easier to
maintain...  We are embarking on an experiment to use it in beginning
courses.  We are confident that we will make a difference in their
problem solving and programming skills (and we hope writing skills
too).  Most webs use few of the available web commands and darned
few TeX commands too (of course TeX and METAFONT are exceptions).
I believe that cooperative efforts to share (like this discussion
list) is the way to improve understanding of literate programming.
I am pleasantly surprised how many have made good strides by
themselves.  I had the great pleasure of working with several good
graduate students who helped me greatly in understanding the
processes.
 
Have you ever imagined a (say) calculus book without an index, table
of contents, ...?  It can be such a disaster to try to study and
learn a technical subject without such aids.  Maintenance programming
is often similar to learning a new subject.
 
Cheers
 
Bart Childs
 
From ae1181t@stnfor.ae.ge.com Sun Jun 27 19:08:56 -0400 1993
Date: Sun, 27 Jun 1993 19:08:56 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, bart@cs.tamu.edu.ae.ge.com.ae.ge.com
Subject: Re: Modules are valuable
 
   I feel strongly that sections are extremely valuable.  Can we do
   without them? Sure!  Can we do without the index?  Sure!  Just look at
   FunnelWeb, NOweb, and NUweb.  Can we do without good typesetting of
   the code?  Sure! Just look at same list.  Can we do without the table
   of contents?  Sure!
   Bart Childs
I think nuweb has index and table of contents. Only the code typesetting
is missing due to its applicability to all languages.
Osman
 
From kotch@ulysses.att.com Sun Jun 27 19:22:30 EDT 1993
Date: Sun, 27 Jun 93 19:22:30 EDT
From: kotch@ulysses.att.com
Reply-To: LitProg@SHSU.edu, kotch@ULYSSES.ATT.COM
To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
Subject: Re: Modules are valuable
 
Bart, 
  True that a large part of the time is spent on maintenance, yet
that initial time is spent in front of a screen, not looking at a
peice of paper. That is where the problem lies. Give me a system
which will provide me the benifits of web and allow me to \italics{eaisly}
electronic code and I will buy it.
 
Brett
 
From norman@bellcore.com Mon Jun 28 12:44:03 -0400 1993
Date: Mon, 28 Jun 93 12:44:03 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK
Subject: Re: Are modules necessary?
 
> Some people here have been using it and we have come to the conclusion 
> that the formal structure of Text Part - Code Part is unnecessary in 
> this WYSIWYG environment.  Having code chunks appear throughout the 
> text seems to lead to a slightly different style of programming.
> 
> Does anyone else feel that the numbered module structure is more than 
> simply a carry over from the parsing of the source file in the 
> original WEB?  Cross-references can be handled using page numbers etc.
 
Yes.  noweb has no module structure and uses page numbers for
cross-reference.  I find it infuriating every time I dive into TeX or
METAFONT and have to cope with cross-references to module numbers.  I
confess that noweb does not do page numbers as well as I would like
(i.e. 17a, 17b, 17c for chunks appearing on page 17), but I just
haven't been able to force myself to try to write even such a simple
program using latex's brain-damaged cross-reference mechanism.
 
Norman
 
From norman@bellcore.com Mon Jun 28 12:53:32 -0400 1993
Date: Mon, 28 Jun 93 12:53:32 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
Subject: Re: Modules are valuable
 
> The reason that Norman Ramsey did NOweb was
> because of the difficulty of convincing users to try such a
> complicated system as WEB.
 
I'm being grossly maligned here (not on purpose, I know, Bart).  I
created noweb because extensive experience with WEB, CWEB, and Spidery
WEB convinced me that WEB should die.  I won't go into the details
here; they are in my papers.  I thought that literate programming was
a great idea hiding behind some poor tools.  Don Knuth is a brilliant
algorithmicist, but his tools can be awkward.  For example, the TeX
world seems to prefer latex to plain TeX, even though plain TeX is
better documented and has fewer bugs.  The reason must be that latex
comes closer to providing the tools people actually want to use to
make documents.  The goal of noweb was to eliminate the clutter and
awkwardness surrounding the tools so that people could experiment with
and evaluate literate programming without having to fight awkward
tools.
 
Norman
 
From norman@bellcore.com Mon Jun 28 13:09:27 -0400 1993
Date: Mon, 28 Jun 93 13:09:27 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
Subject: more flaming Re: Modules are valuable
 
> I feel strongly that sections are extremely valuable.  Can we do
> without them? Sure!  Can we do without the index?  Sure!  Just look at
> FunnelWeb, NOweb, and NUweb.  Can we do without good typesetting of
> the code?  Sure! Just look at same list.  Can we do without the table
> of contents?  Sure!
 
These exclamations are slightly unfair.  I can't speak to FunnelWEB
(ran screaming from the manual some time ago), but both noweb and
nuweb support table of contents and automatic indexing of
sections/macros/code chunks (use your favorite term).  nuweb has a
nice semi-automated solution to the indexing problem.  [This reminds
me---Preston, I couldn't find where you documented what an identifier
is... is it just characters delimited by whitespace?]  Even minimalist
old noweb supports the latex indexing mechanism.
 
> I think Don Knuth's design was the result
> of careful study, consideration of many alternatives, ... that are
> typical of his works.
 
I'm not so sure I agree.  Consider that the part of TeX that is
absolutely the most difficult to understand is *not* written as a
literate program (I refer to the TRIP test?).
 
> I think the solution is training!
 
I agree training is needed, but I think we should be teaching people
how to use the literate-programming paradigm, not how to use
particular tools.  Our experience using literate programming on a team
project showed us how difficult it was to teach people to write
literate programs, and how people can write truly horrendous programs
using literate-programming tools.  Carla Marceau and I wrestled with
this problem over two years, and we thought we had a coherent story
about how to write literate programs, but when we started passing our
analysis around it fell to bits.  We had a good understanding of the
issues involved in creating tools, but everything we learned about
writing programs can be stated in two words: peer review.
 
I encourage all of you to write down your ideas about how to write
literate programs.  The world needs an ``Introduction to writing
literate programs'' along the lines of Andrew Birrel's ``Introduction
to Programming with Threads.''
 
Norman
 
From mckearney_s Mon Jun 28 18:20:35 +0100 1993
Date: Mon, 28 Jun 1993 18:20:35 +0100
From: mckearney_s <mckearney_s@bt-web.bt.co.uk>
Reply-To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK
To: litprog@shsu.edu
Subject: Re:Are modules necessary?
 
I posted a message asking if people thought modules were an important 
part of the LP concept.  By modules I mean the format:
 
1. blah blah blah
 
<blah> = 
    code
    code
    code
 
The reason for my comment was because some people here have been using 
a WORD based WEB that I adapted from a previous version.  In this WEB 
we originally had numbered modules but discovered that with numbered 
sections and chapters the numbering of modules in this strict fashion 
was not necessary.  I am not saying you should remove the code module 
idea but simply be more flexible over the text.
 
As I expected the discussion has moved into the 'TeX is best' argument 
with some people advocating training etc.  Having recently moved from 
a university research environment into an industry research 
environment I can simply say that, although I like TeX/LaTeX, there is 
no way the majority of programmers will use TeX when things like WORD 
are relatively easy to use and look good - fact of life.
 
As for modules etc. the code we are producing does not seem to need 
numbering of modules and when you abandon numbering you seem to end up 
with something closer to a 'book'.  I think this is because the 
numbered module idea seems to set you thinking afresh for each module 
while without numbers the document feels more like a flowing 
description.  I get this feeling from most LP programs I have read 
that have been published.
 
I am very interested in the views expressed so far.
 
Stephen
 
From gilligan@central.bldrdoc.gov Mon Jun 28 12:27:41 MDT 1993
Date: Mon, 28 Jun 93 12:27:41 MDT
From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan)
Reply-To: LitProg@SHSU.edu, gilligan@CENTRAL.BLDRDOC.GOV
To: LitProg@SHSU.edu
Subject: Teaching literate programming (is it possible?)
 
Forgive my skepticism, and pardon my impertinence (I've never taught
programming above the high-school level, where I used LOGO most
illiterately), but to teach literate programming seems as though it
would be altogether different from teaching programming and much
closer to teaching expository writing. There is no simple how-to for
writing an essay that's a joy to read. You can give rules
(four-sentence paragraphs, making outlines, the technicalities of
footnotes and bibliographies) but the magic is ineffable and the
student can only learn it by example (read Orwell's prose, for
instance). Similarly, I would, with all humility, suggest that only by
publishing excellent literate programs will we give illiterate
programmers the tools they need to learn literacy.
 
Using the various tools themselves seems a small obstacle compared to
learning how to think in a literate manner.
 
Thus, I find completely plausible Norman Ramsey's statement that
nothing helped except peer review. Nothing else helps novelists or
poets either.
 
Jon
 
From preston@cs.rice.edu Mon Jun 28 14:00:01 CDT 1993
Date: Mon, 28 Jun 93 14:00:01 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, mckearney_s@bt-web.bt.co.uk
Subject: Re:Are modules necessary?
 
Stephen McKearney writes:
>I posted a message asking if people thought modules were an important
>part of the LP concept.  By modules I mean the format:
 
>1. blah blah blah
>
><blah> =
>    code
>    code
 
Sure, I (and others) agree with your points.
I write text, organized however I feel is best, with chapters,
sections, figures, tables, and everything else LaTeX provides.
I also happen to have code organized into scraps which are cross-referenced,
indexed, etc.
 
This is all in the context of nuweb.
Noweb and FunnelWeb have similar feature sets.
Nuweb does all the cross references in terms of scrap numbers.
Noweb does it all in terms of pages numbers.  I'd prefer page numbers;
but I couldn't figure out how to do it all as cleanly as I wanted.
 
Presumably others will reflect on their experience (and ours)
and will design new tools with different features that better support
their concept of literate programming.  Maybe we'll reach a consensus
or maybe not; I doubt it matters.
 
Preston
 
From Zdenek Mon Jun 28 13:04:18 MDT 1993
Date: Mon, 28 Jun 93 13:04:18 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: RE: modules are valuable
 
Bart Child writes:
 
  I think the solution is training!  WEB like systems offer a reasonable
  way of weaving documentation and code together to make it easier to
  maintain...  We are embarking on an experiment to use it in beginning
  courses.  We are confident that we will make a difference in their
  problem solving and programming skills (and we hope writing skills
  too).  Most webs use few of the available web commands and darned
  few TeX commands too (of course TeX and METAFONT are exceptions).
  I believe that cooperative efforts to share (like this discussion
  list) is the way to improve understanding of literate programming.
  I am pleasantly surprised how many have made good strides by
  themselves.  I had the great pleasure of working with several good
  graduate students who helped me greatly in understanding the
  processes.
 
Take for example the book by Niklaus Wirth: Algorithms + Data Structures =
Programs. This book shows how the program should be designed. It is written
in conventional Pascal but the way how the program grows in the examples is
exactly the same as in WEB. Using WEB in the courses for beginners (even those
who do not know TeX) will be easy provided TeX is already installed.
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From Zdenek Mon Jun 28 13:10:25 MDT 1993
Date: Mon, 28 Jun 93 13:10:25 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: RE: Support for Allen Rouse's view
 
Allen Rouse writes:
 
>       When I first heard of Lit. Prog. and read about the subject I
>developed the impression that the final document would resemble a
>chapter from a textbook or a book and not a numbered sequence of
>text/code segments as is currently the case.
>       I imagined that the code would be in its own box (or area) in
>the document in the same way that photographs and other images are
>included in newspapers, dictionaries, texts. I also thought that
>actual images could be included. For example, in a program that draws
>a line its progress could be graphically shown by pixel diagrams. Or a
>sorting algorithm could include a graph of its performance on random
>data.
>       In other words I feel that the ideal product of a Literate
>Programmer is to be able to produce a final document which is
>indistinguishable from an ordinary expository/descriptive treatise.
>Perhaps the best description I could give of the ideal program is, as
>I first said, "something that looks like a chapter/section from
>'Intro. to Algorithms' or another such book"
 
Eric W. van Ammers writes:
 
>Perfectly true. For exactly this reason I maintain that a literate
>programming tool should be capable to cooperate with any formatter
>or wordprocessor one wants to use, without imposing any restrictions on
>the use of the choosen text processing system.  I consider it a severe
>disadvantage if the LP-tool imposes a particular structure of chapters and
>sections on the documentation or prohibits the use of figures or tables.
 
 Who says that WEB imposes a particular structure of chapters? As I know
CWEB 2.7 (I have not retrieved CWEB 3 yet), it suggests a structure which
is probably used by everybody. You can change it if you redefine macros
in cwebmac.tex. CWEB 3 is probably most flexible. My documentation includes
tables and figures because it is supported by TeX. If you know TeX, you know
how to do it.
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From Manuel Mon Jun 28 22:30:30 BST 1993
Date: Mon, 28 Jun 93 22:30:30 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@SHSU.edu
Subject: NUWEB compiled for DOS?
 
Dear all,
 
if picked up a compiled DOS executable of Preston Briggs' NUWEB in 
ftp.shsu.edu:tex-archive/web/nuweb/msdos.
 
According to the 'readme.txt' file it is compiled with the DJGPP GCC Compiler
and combined with the GO32 extender.
 
I've tried to run the executable but my micro (Viglen 386SX) echos some
control characters on the screen and goes dead.
 
The retrieved zip file of the subdirectory msdos and it is ok! (no CRC errors.)
 
Someone knows what happened there? 
 
Manuel Carriba <M.Carriba@dcs.shef.ac.uk>
 
From Lang@tu-harburg.dbp.de Tue Jun 29 09:38:06 +0100 1993
Date: Tue, 29 Jun 1993 09:38:06 +0100 (METDST)
From: Lang@tu-harburg.dbp.de (Bernhard Lang)
Reply-To: LitProg@SHSU.edu, Lang@TU-HARBURG.DBP.DE
To: LitProg@SHSU.edu.d400.de, M.Carriba@DCS.SHEFFIELD.ac.uk
Subject: Re: NUWEB compiled for DOS -- pick up my version
 
> 
> 
> Dear all,
> 
> if picked up a compiled DOS executable of Preston Briggs' NUWEB in 
> ftp.shsu.edu:tex-archive/web/nuweb/msdos.
> 
> According to the 'readme.txt' file it is compiled with the DJGPP GCC Compiler
> and combined with the GO32 extender.
> 
> I've tried to run the executable but my micro (Viglen 386SX) echos some
> control characters on the screen and goes dead.
> 
> The retrieved zip file of the subdirectory msdos and it is ok! (no CRC errors.)
> 
> Someone knows what happened there? 
> 
> Manuel Carriba <M.Carriba@dcs.shef.ac.uk>
> 
 
In the nuweb program for DOS that you picked up not the GO32-extender was
included
but only a stub that calls GO32. I think you have an old GO32-extender, then
happen these things you describe.
 
You may pick up my nuweb DOS version from kirk.ti1.tu-harburg.de. It definitely includes the correct GO32-extender, thus it is bigger than the version you 
picked up. Login as user FTP and send your e-mail address as password.
You will find the executable and nuweb.w in the directory pub/nuweb/msdos.
 
If you fail retrieving the files, please let me know.
 
Bernhard
 
{{{  Dr. Bernhard Lang  -----------------------------------------------
     email: lang@tu-harburg.dbp.de         TU Hamburg Harburg
                                           Technische Informatik I
}}}
...  Enter this fold to view behind the scenes  -----------------------
 
From Adrian Tue Jun 29 10:57:16 +0100 1993
Date: Tue, 29 Jun 93 10:57:16 +0100
From: Adrian F Clark <alien@essex.ac.uk>
Reply-To: LitProg@SHSU.edu, alien@ESSEX.AC.UK
To: LitProg@SHSU.edu
Subject: Summary sheet for Nuweb
 
Just to let readers know that, with George's assistance, I have
uploaded a two-page summary of Nuweb to the
ftp.shsu.edu:/tex-archive/web/nuweb and to equivalent places at Aston
and Stuttgart.  It lists the mark-up commands, summarises Nuweb's
invocation, and gives a simple (language-independent) example.
 
It should print on both A4 and quarto paper.  For those of us in the
A4 part of the world, I find it best to photocopy the A4-sized master
to produce a double-sided A5-sized sheet.
 
The files are:
 
   nuweb-summary.ps        formatted version of the summary
   nuweb-summary.tex       LaTeX source of the summary
   nuweb-summary-sample.w  sample file for use with the nuweb-summary.tex
 
The .ps file uses Palatino as the body font, so it may not print on
baroque laser printers.  Before attempting to format the .tex file,
the sample .w file needs to be run through Nuweb.  It's unlikely to
look right unless your LaTeX uses the new font selection scheme.
 
Any comments concerning the summary sheet should be addressed to me,
not to Preston Briggs, Nuweb's author.  I'm sure he doesn't want to be
bothered with complaints about things he didn't write!
 
..Adrian
 
 Dr Adrian F. Clark                                   JANET: alien@uk.ac.essex
 INTERNET: alien%uk.ac.essex@nsfnet-relay.ac.uk          FAX: (+44) 206-872900
 BITNET: alien%uk.ac.essex@ac.uk              PHONE: (+44) 206-872432 (direct)
 Dept ESE, University of Essex, Wivenhoe Park, Colchester, Essex, C04 3SQ, UK.
 
From ae1181t@stnfor.ae.ge.com Tue Jun 29 07:41:49 -0400 1993
Date: Tue, 29 Jun 1993 07:41:49 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, mckearney_s@bt-web.bt.co.uk.ae.ge.com.ae.ge.com
Subject: Re: Re:Are modules necessary?
 
Hi, maybe I misunderstood the first time, but it looks like you are right
``numbers'' are not needed. Need a better method than just page numbers
for the indices (like what Norman said 17a, 17b,...). Is that possible
in WORD? Are you going to have it availble?
 
Osman
 
Ps: you have not answered about the code size restriction (<64k) of the
    earlier wordweb being still true?
 
From ae1181t@stnfor.ae.ge.com Tue Jun 29 08:09:29 -0400 1993
Date: Tue, 29 Jun 1993 08:09:29 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, Lang@tu-harburg.dbp.de.ae.ge.com.ae.ge.com
Subject: Re: NUWEB compiled for DOS -- pick up my version
 
Yes, It was my mistake 8*( ! I thought the package was ok but the computers
I tested both had go32.exe on the PATH. So people who picked up nuweb.zip
from pip.shsu need to get go32.exe. I will recreate the executable and
upload it as soon as possible (this time the executable will be appended so
no need for an extra go32.exe). Sorry for the inconvenience.
Osman
 
From John Tue Jun 29 13:22:09 +0100 1993
Date: Tue, 29 Jun 1993 13:22:09 +0100 (BST)
From: "John K Nicoll" <jkn@ohm.york.ac.uk>
Reply-To: LitProg@SHSU.edu, jkn@OHM.YORK.AC.UK
To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
Subject: Re: NUWEB compiled for DOS?
 
According to Manuel Carriba:
> 
> 
> Dear all,
> 
> if picked up a compiled DOS executable of Preston Briggs' NUWEB in 
> ftp.shsu.edu:tex-archive/web/nuweb/msdos.
> 
> According to the 'readme.txt' file it is compiled with the DJGPP GCC Compiler
> and combined with the GO32 extender.
> 
> I've tried to run the executable but my micro (Viglen 386SX) echos some
> control characters on the screen and goes dead.
> 
> The retrieved zip file of the subdirectory msdos and it is ok! (no CRC errors.)
> 
> Someone knows what happened there? 
> 
> Manuel Carriba <M.Carriba@dcs.shef.ac.uk>
> 
Hello Manuel
	I can't tell you what your problem is, but I compiled Nuweb
for DOS (before the gcc version was available). I haven't done much
work with it but you're welcome to a copy.
 
	john N
 
From mckearney_s Tue Jun 29 16:47:49 +0100 1993
Date: Tue, 29 Jun 1993 16:47:49 +0100
From: mckearney_s <mckearney_s@bt-web.bt.co.uk>
Reply-To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK
To: litprog@shsu.edu
Subject: WORDWEB limits
 
Osman writes
 
> Hi, maybe I misunderstood the first time, but it looks like you are 
> right ``numbers'' are not needed. Need a better method than just page 
> numbers for the indices (like what Norman said 17a, 17b,...). Is that 
> possible in WORD? Are you going to have it availble?
>
> Osman
>
> Ps: you have not answered about the code size restriction (<64k) of 
> the earlier wordweb being still true?
 
I never thought of indexing like this although I'm not sure it will be 
much more useful than just page numbers.
 
The code size restriction is just on generated code, that is, the 
output of the tangle phase.  I do not find this to be a problem 
because I tend to keep individual WEB files reasonably small and WORD 
provides facilities to create large documents from a number of files.  
For example, if you write a large thesis you might have files called 
CHAPTER1.DOC, CHAPTER2.DOC, etc.
 
A more serious problem was caused because the main tangle routine in 
the original version used recursion that VERY quickly ran out of memory. 
Judicious use of GOTOs etc. removed the recursion and it seems to 
handle reasonably large files now.
 
If people are interested in this version I can look into supplying it 
but I do not have FTP access.
 
Stephen
 
From uunet!SHSU.edu!LP-Mgr Tue Jun 29 13:17:08 1993
X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
Warnings-To: <>
Sender: uunet!SHSU.edu!LP-Mgr
X-Vms-To: R11F::SHSU.EDU::LITPROG
To: litprog@shsu.edu
From: mckearney_s
Reply-To: uunet!SHSU.edu!LitProg, uunet!BT-WEB.BT.CO.UK!mckearney_s
Subject: WORDWEB limits
Date: Tue, 29 Jun 1993 16:47:49 +0100
 
Osman writes
 
> Hi, maybe I misunderstood the first time, but it looks like you are 
> right ``numbers'' are not needed. Need a better method than just page 
> numbers for the indices (like what Norman said 17a, 17b,...). Is that 
> possible in WORD? Are you going to have it availble?
>
> Osman
>
> Ps: you have not answered about the code size restriction (<64k) of 
> the earlier wordweb being still true?
 
I never thought of indexing like this although I'm not sure it will be 
much more useful than just page numbers.
 
The code size restriction is just on generated code, that is, the 
output of the tangle phase.  I do not find this to be a problem 
because I tend to keep individual WEB files reasonably small and WORD 
provides facilities to create large documents from a number of files.  
For example, if you write a large thesis you might have files called 
CHAPTER1.DOC, CHAPTER2.DOC, etc.
 
A more serious problem was caused because the main tangle routine in 
the original version used recursion that VERY quickly ran out of memory. 
Judicious use of GOTOs etc. removed the recursion and it seems to 
handle reasonably large files now.
 
If people are interested in this version I can look into supplying it 
but I do not have FTP access.
 
Stephen
 
----- End Included Message -----
 
From Adrian Tue Jun 29 16:51:45 +0100 1993
Date: Tue, 29 Jun 93 16:51:45 +0100
From: Adrian F Clark <alien@essex.ac.uk>
Reply-To: LitProg@SHSU.edu, alien@ESSEX.AC.UK
To: litprog@shsu.edu
Subject: Updated Nuweb summary
 
Strange how these things always happen.  Although the Nuweb summary
sheet I announced earlier today had been proof-read by two people,
someone spotted a mistake in it -- and I've just found another one
myself.
 
I've uploaded the corrected summary sheet to shsu's /incoming
directory, and I'm sure it'll be put into place in the Nuweb directory
in the near future.
 
..Adrian
 
From M Tue Jun 29 12:09:38 EDT 1993
Date: Tue, 29 Jun 93 12:09:38 EDT
From: M Afzal <M.Afzal@greenwich.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Afzal@greenwich.ac.uk
To: LitProg@SHSU.edu
Subject: Ideal Literate Programming System?
 
X-cs: 
From:     Self <TECHA/AM0ZXR>
To:       arouse@math.utexas.edu
Subject:  Re: Ideal System for Literate Programming?
Reply-to: am0zxr@thames.ac.uk
Date:     25 Jun 93 12:45:52
 
Allen Rouse in his message 'Are modules nexessary?' writes:
 
>    In other words I feel that the ideal product of a Literate
> Programmer is to be able to produce a final document which is
> indistinguishable from an ordinary expository/descriptive treatise.
> Perhaps the best description I could give of the ideal program is,
> as I first said, "something that looks like a chapter/section from
> 'Intro. to Algorithms' or another such book"
 
I still expect something similar, as I haven't yet started using LP.
I have been reading through this discussion list and from literature
about Literate Programming.
 
I am a (Fortran based) software developer, prefer to concentrate more
on the design phase; with 2B Lead pencil, rubber and bunch of
papers; as only tools. This phase does involve the text, figures and
blocks of code. It takes me very small time in implementation, but a
good system  for LP could reduce it even further, and save me from
rewriting/puting it into computer.
 
Although the man-made systems and products are always evolving in
nature and need improvement, but still if some product could prvide
some mechanism to embed code, text and graphics; and with minimum
learning overhead would be much appreciated. One such system has been
proposed in recent issue of Software Engineering Journal:
 
Stephen Shum and Curtis Cook
    AOPS: an Abstraction-Oriented Programming System for Literate
    Programmin
        Software Engineering Journal, V 8, n 3, pp 113-120, May 1993
 
They claim, AOPS is text processor and programming language
independent, and can embed code, text and graphics in same source
AOPS file. It does have its browser and other tools. It is PC-based.
I have requested its copy from authors, which they have offered
free to anybody who (sends them a diskette and) wants to use it.
 
Afzal
 
From M Tue Jun 29 12:09:38 EDT 1993
Date: Tue, 29 Jun 93 12:09:38 EDT
From: M Afzal <M.Afzal@greenwich.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Afzal@greenwich.ac.uk
To: LitProg@SHSU.edu
Subject: Ideal Literate Programming System?
 
I attempted to comment on Allen Rouse' message, but something was
wrong in setup, so it couldn't be transmitted, to the discussion list.
Now I am enclosing the same comment as file, hopefully it would be of
interest to you all.
 
Regards
Afzal
 
From Hans-Hermann Tue Jun 29 16:58:16 MEZ 1993
Date: Tue, 29 Jun 93 16:58:16 MEZ
From: Hans-Hermann Bode <HHBODE@dosuni1.rz.Uni-Osnabrueck.DE>
Reply-To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
To: LitProg@SHSU.edu, levy@MATH.BERKELEY.EDU
Subject: Re: cweb 3.0
 
>Yes, cweb 3.0 is released as of June 16.  You can find it on labrea.
 
Although WEB systems recently have been declared to be dead, I have updated
my PC port. It is not based on the *-pc.ch change files provided with CWEB.
Especially, it can be compiled with (Turbo/Borland) compilers that have a
64 KByte limit for static data per file; nevertheless, all arrays except
for one still have their original size.
 
The port (including sources, change files, and executables) is available
from ftp.rz.uni-osnabrueck.de in the directory pub/msdos/tex/web. The file
is called cwb30p8c.zip and replaces cweb-p.zip. There is no successor for
cweb-p.tar.Z since everything interesting for non-PC users now is part of
CWEB itself. Below is the README file from cwb30p8c.
 
Hans-Hermann Bode
Arbeitsgruppe Systemforschung, Universitaet Osnabrueck, D-49069 Osnabrueck
Tel.: (49)-541-9692545
e-mail: HHBODE@DOSUNI1.BITNET, hhbode@dosuni1.rz.uni-osnabrueck.de
 
%--README-from-cwb30p8c.zip-------------------------------------------------
								-*-Text-*-
This file, README, is part of CWEB-p. The current version of CWEB-p is p8c.
 
The CWEB programs by Silvio Levy and Donald E. Knuth are based on programs by
Knuth. The PC port (i.e., Turbo-C++ change files and executables) is made by
Hans-Hermann Bode.
 
The programs are distributed WITHOUT ANY WARRANTY, express or implied.
 
This README file last updated 24 Jun 1993 by Hans-Hermann Bode.
 
Copyright (C) 1987,1990,1993 Silvio Levy and Donald E. Knuth
Copyright (C) 1991,1992,1993 Hans-Hermann Bode
 
Permission is granted to make and distribute verbatim copies of this
document provided that the copyright notice and this permission notice
are preserved on all copies.
 
Permission is granted to copy and distribute modified versions of this
document under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
 
Please send comments, suggestions, etc. to one of the following addresses:
  -- levy@geom.umn.edu (if related to the original CWEB system),
  -- hhbode@dosuni1.rz.uni-osnabrueck.de or HHBODE@DOSUNI1.BITNET (if
related to the PC port).
 
INTRODUCTION
 
The CWEB-p system is an adaptation of Silvio Levy's and Donald E. Knuth's
CWEB system that supports installation with the Turbo-C++ compiler and
provides PC-/MS-DOS executables.
 
CONTENTS OF THE DISTRIBUTION
 
The sources directory contains the following files from the original CWEB
distribution:
 
./sources/readme	README file from the original distribution
./sources/makefile	Makefile from the original distribution
./sources/common.h	header file to be included in ctangle.w and cweave.w
./sources/common.w	common code for ctangle and cweave
./sources/ctangle.w	the tangle processor
./sources/cweave.w	the weave processor
./sources/prod.w	production rules to be included in cweave.w
./sources/cwebmac.tex	macros for formatting
./sources/cwebman.tex	the user manual
./sources/cweb.1	manual page (nroff format)
./sources/cweb.el	elisp file for GNU Emacs
./sources/common.c	CTANGLEd product of common.w
./sources/ctangle.c	CTANGLEd product of ctangle.w
 
The examples directory contains examples of CWEB programming. They are from
the original distribution, too. For use on PC systems, they probably have to
be edited (for wmerge.w, that is used in the make process, a change file is
provided).
 
./examples/readme	README file from the original examples directory
./examples/makefile	generic Makefile for CWEB applications
./examples/wc.w		UNIX word-count utility
./examples/treeprin.w	tree-structured directory lister by Norman Ramsey
./examples/wmerge.w	WEB-like file merger by Silvio Levy
./examples/extex.w	spellchecking filter for TeX and CWEB by Don Knuth
./examples/wordtest.w	spellchecker by Don Knuth
./examples/xlib_typ.w	include file for XView programs
./examples/xview_ty.w	ditto
./examples/oemacs.w	example XView application by Don Knuth
./examples/kspell.el	Emacs interface to extex/wordtest
./examples/oemacs.el	Emacs interface to oemacs
 
The change files that set up the CWEB-p adaptation are in the changes
directory.
 
./changes/common-h.ch	for common.h
./changes/common.ch	for common.w
./changes/ctangle.ch	for ctangle.w
./changes/cweave.ch	for cweave.w
./changes/prod.ch	for prod.w
./changes/cwebmac.ch	for cwebmac.tex
./changes/wmerge.ch	for wmerge.w from the examples directory
 
Note that several sets of change files (*-man.ch, *-vms.ch, *-pc.ch,
*-amiga.ch) that come with the original CWEB system are not supported by and
not provided with CWEB-p.
 
Finally, in this (root) directory the following files do reside. The files
common.c, ctangle.c, and cwebmac.tex include the changes from the changes
directory .
 
./version		note about the current version of CWEB-p
./readme		this file
./makefile		Makefile for Turbo C++
./cweb.man		manual page (ASCII format)
./common.c		product of sources/common.w and changes/common.ch
./ctangle.c		product of sources/ctangle.w and changes/ctangle.ch
./wmerge.c		product of examples/wmerge.w and changes/wmerge.ch
./cwebmac.tex		product of sources/cwebmac.tex and changes/cwebmac.ch
./ctangle.exe		executable tangle processor for PC-/MS-DOS systems
./cweave.exe		executable weave processor for PC-/MS-DOS systems
./wmerge.exe		executable WEB-like file merger for PC-/MS-DOS systems
 
GETTING STARTED
 
Before starting, you should run cwebman.tex (needs cwebmac.tex!) through TeX
and print out the manual; the first step can be done by calling `make man'
from the Makefile.
 
Then, all you have to do to get a working CWEB system on PC-/MS-DOS is to
copy ctangle.exe and cweave.exe to your binaries directory and cwebmac.tex
(from the root directory) to your TeX-inputs directory; that's it, you are
ready to use CWEB!
 
NOTES
 
1. When you want to recompile the tangle and weave processors, for
bootstrapping you find a pretangled common.c, ctangle.c, and wmerge.c for
the Turbo-C++ compiler in the root directory of this distribution. From
these you can build working tangle and wmerge processors for CWEB, which in
turn are the basis for recompiling the whole system. For other PC-/MS-DOS
compilers, you must use the ctangle.exe and wmerge.exe from this
distribution (a ctangle from previous versions may or may not work); in this
case, delete common.c, ctangle.c, and wmerge.c from the root directory,
since they may not include the right changes.
 
Then, edit the Makefile corresponding to your environment and call make.
Note that the Makefile from the sources directory is lacking some
dependencies and will not work for this distribution. So, better use the
Makefile from the root directory as a template.
 
The Makefile from the root directory is intended for Turbo Make, Version 3.6
(earlier versions probably will not work!). If you are using the real-mode
version of Turbo Make 3.6, you should say `make -S all' to prevent from
running out of memory. The Makefile is prepared to use change files from a
`fixes' directory and from a `private' directory in addition to the
`changes' directory. If you use this feature, you must have Klaus
Guntermann's tie processor for concatenating multiple change files (take a
look at ftp.th-darmstadt.de); then you can call `make -S -D_fix all' to
include the files from the changes and fixes directory or `make -S -D_priv
all' to include the files from all three directories.
 
2. If you like to or have to make changes to the CWEB-p system, it is
recommended that you don't edit the files in the sources or changes
directories, but set up a complete new group of change files in a directory
called `fixes' or `private' and include it in the make process
appropriately. This will save much effort when you get a new version of
CWEB-p.
 
Incidentally, if you try the recompilation on a PC-/MS-DOS system with
another compiler than Turbo C++, you may have no luck with the Turbo-C++
changes. In this case, it's best to create a new set of change files similar
to the `changes' group and use the supplied executables to generate new .c
files rather than to edit the .c files themselves. You can set up such new
changes in a `fixes' or `private' directory by making use of the provided
changes and just calling make as described above.
 
3. If you want a full documentation of the tangle and weave programs, say
`make doc' (you may include the same options as described in Note 1). This
should produce the files common.dvi, ctangle.dvi, cweave.dvi, and---with the
Turbo Makefile---cwebman.dvi.
 
4. To delete all intermediate files created in the make processes say `make
clean', to delete even the DVI files with the Turbo Makefile say `make
veryclean'.
 
From ae1181t@stnfor.ae.ge.com Tue Jun 29 14:20:08 -0400 1993
Date: Tue, 29 Jun 1993 14:20:08 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, M.Afzal@greenwich.ac.uk.ae.ge.com.ae.ge.com
Subject: Re: Ideal Literate Programming System?
 
Hi, AOPS seems intersting. Is it possible for someone who has the program to
put it on one of the CTAN archives? Even if it is for msdos may be someone
will port it to other platforms. Are the authors reachable by email?
Thanks in advance.
Osman
 
From stevef@ttsi.tandem.com Tue Jun 29 14:00:27 CDT 1993
Date: Tue, 29 Jun 93 14:00:27 CDT
From: stevef@ttsi.tandem.com (Steve Farmer)
Reply-To: LitProg@SHSU.edu, stevef@TTSI.TANDEM.COM
To: LitProg@shsu.edu
Subject: WYSIWYG WEB system?
 
Stephen McKearney (mckearney_s@bt-web.bt.co.uk) states:
 
   I have developed a WEB for Word system, based around the WORDWEB 
   developed elsewhere, that does almost everything most WEB systems do 
   including : cross-references, code indexes, find definition, etc.
 
Are any of these WYSIWYG WEB systems available through anonymous ftp? I
understand that current word-processors are not ideal, but I think there
is a lot of potential in WYSIWYG that I would like to explore.
 
Steve Farmer
stevef@ttsi.tandem.com
Tandem Telecommunications
Plano, Texas, USA
 
From M Wed Jun 30 19:29:11 +1000 1993
Date: Wed, 30 Jun 1993 19:29:11 +1000
From: M Afzal <M.Afzal@greenwich.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Afzal@greenwich.ac.uk
To: LitProg@SHSU.edu
Subject: Ideal Literate Programming System?
 
    In reply to Osman's message:
 
>   AOPS seems intersting. Is it possible for someone who has the
>   program to put it on one of the CTAN archives? Even if it is for
>   msdos may be someone will port it to other platforms. Are the
>   authors reachable by email?
 
    Unfortunately, still most of the Jounals, even computer related
ones, do not give the authors' Email addresses, so I don't have any
idea for them. The journal does provide the surface mail addresses of
the authors as:
 
    Stephen Shum                Curtis Cook
    Computer Science Deptt      Computer Science Deptt
    Augustana College           Oregon State University
    Siox Falls                  Corvallis
    SD 57197, USA               OR 97331-3202, USA
 
    Hopefully this will work.
 
    Regards
    Afzal
 
From Richard Wed Jun 30 19:29:11 +1000 1993
Date: Wed, 30 Jun 1993 19:29:11 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu, Richard.Walker@CS.ANU.EDU.AU
To: LitProg@shsu.edu
Subject: Where is SpiderWeb's webkernel.tex?
 
Hi.  I finally got around to getting the latest Spider, but I
can't seem to find webkernel.tex anywhere.  Is it hiding?
 
I will be using it with LaTeX anyway, but it seems rather
strange that this crucial file is missing from the
distribution (certainly on pip.shsu.edu).
 
Richard.
 
From George Wed Jun 30 07:58:24 CST 1993
Date: Wed, 30 Jun 1993 07:58:24 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, M.Afzal@GREENWICH.AC.UK
Subject: RE: Receipt confirmation
 
On 30 Jun 93 10:32:44 GMT (and subsequently), LitProg received from M Afzal
<M.Afzal@greenwich.ac.uk>:
> Confirmation: message read at 10:32, 30 Jun 93
> Subject: Ideal Literate Programming System?
This user has been removed from the LitProg distribution list.  I am aware
of the variety of systems out there and how they operate, but I do not
personally condone these sorts of replies (for *any* purpose) unless they
are directed to the RFC822-compliant Return-Path: or From: specifications
(obviously, this software is using the RFC822 Reply-To: line).
 
I apologize to the list for this loop (which such software creates when
using the Reply-To: specification if the Reply-To: is set to a list
redistribution address, as is the case with LitProg; the other fields
specified above should, with very rare exception, always point to a single
or a well-defined and configurable small number of mailboxes).  
 
Additionally, I apologize to M Afzal for the unannounced unilateral removal
from this list.  However, I cannot allow a looping phenomenon to be created
(clearly this will happen as the arrival of another confirmation message
will create another confirmation message, and on and on, ad nauseum). 
Given the number of subscribers (now 327) and the network topology
associated with its geographically diverse audience, the use of bandwidth
created by this form of looping is inexcusable if knowingly allowed by the
host site for the list's management.
 
If you either disengage this piece of software (permanently or selectively
for this list) or (far less preferable) retain it but reconfigure it so it
works more appropriately for wide area networks, you are more than welcome
to return to this list by inluding:
 SUBSCRIBE LitProg "M Afzal"
in the body of a mail message to LISTSERV@SHSU.edu.
 
Your attention to this will be appreciated by everyone involved.  If you
have any questions about this, please contact me directly.
 
Regards and thanks for your interest in our services,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From drs@bach.pdb.bnl.gov Wed Jun 30 10:54:31 -0400 1993
Date: Wed, 30 Jun 1993 10:54:31 -0400
From: drs@bach.pdb.bnl.gov (drs)
Reply-To: LitProg@SHSU.edu, drs@BACH.PDB.BNL.GOV
To: LitProg@SHSU.edu
Subject: Fweb and C++
 
I seem to be spending an inordinate amount of effort forcing the format of C++
code in fweb. (It seems to want to stick an entire method on one line.) I can't
believe that this is correct.
 
Does anyone have a sample C++ web that I can use as a baseline model? The demos
that are shipped with fweb 1.3 are not useful in seeing what I am doing wrong.
 
Thanks.
 
Dave
 
From norman@bellcore.com Wed Jun 30 12:04:11 -0400 1993
Date: Wed, 30 Jun 93 12:04:11 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, Richard.Walker@CS.ANU.EDU.AU
Subject: Re: Where is SpiderWeb's webkernel.tex?
 
Oops.  Mea culpa.  I include the missing file at the end of this
message.  George, perhaps you would be kind enough either to pick it
up here and park it in spiderweb/src, or to grab a new spiderweb.tar.Z
from csservices.princeton.edu:pub?
 
Norman
 
# To unbundle, "sed '1,/^# To unbundle/d' < thisfile | sh"
# To unbundle, make sure both lines appear in the file
# Wed Jun 30 12:00:57 EDT 1993
echo webkernel.tex 1>&2
sed 's/^-//' >'webkernel.tex' <<'End of webkernel.tex'
-% Copyright 1989-92 by Norman Ramsey, Odyssey Research Associates
-% Not to be sold, but may be used freely for any purpose
-% For more information, see file COPYRIGHT
-
-%\let\plainmark=\mark
-%\def\mark#1{\message{(Marking ``#1'')}\plainmark{#1}}
-
-% standard macros for WEB listings (in addition to PLAIN.TEX)
-% rename some old favorites
-\let\amp=\&
-\let\SS=\S
-\let\PP=\P
-\let\em=\it % compatibility with latex
-
-\newif\iftwoside\twosidefalse
-\parskip 0pt % .1pt plus 0.1pt mins 0.1pt % no stretch between paragraphs
-\parindent 1em % for paragraphs and for the first line of Pascal text
-
-\font\eightrm=cmr8
-\font\sc=cmcsc10
-\let\mainfont=\tenrm
-\font\titlefont=cmr7 scaled\magstep4 % title on the contents page
-\font\ttitlefont=cmtt10 scaled\magstep2 % typewriter type in title
-\font\tentex=cmtex10 % TeX extended character set (used in strings)
-\let\idfont\it
-\let\reservedfont\bf
-
-\def\today{\ifcase\month\or
-  January\or February\or March\or April\or May\or June\or
-  July\or August\or September\or October\or November\or December\fi
-  \space\number\day, \number\year}
-
-\def\\#1{\leavevmode\hbox{\idfont#1\/\kern.05em}} % italic type for identifiers
-\def\|#1{\leavevmode\hbox{$#1$}} % one-letter identifiers look better this way
-\def\&#1{\leavevmode\hbox{\reservedfont#1\/}} % boldface type for reserved words
-\def\.#1{\leavevmode\hbox{\tentex % typewriter type for strings
-  \let\\=\BS % backslash in a string
-  \let\'=\RQ % right quote in a string
-  \let\`=\LQ % left quote in a string
-  \let\{=\LB % left brace in a string
-  \let\}=\RB % right brace in a string
-  \let\~=\TL % tilde in a string
-  \let\ =\SP % space in a string
-  \let\_=\UL % underline in a string
-  \let\&=\AM % ampersand in a string
-  #1}}
-\def\#{\hbox{\tt\char`\#}} % parameter sign
-\def\${\hbox{\tt\char`\$}} % dollar sign
-\def\%{\hbox{\tt\char`\%}} % percent sign
-\def\^{\ifmmode\mathchar"222 \else\char`^ \fi} % pointer or hat
-% circumflex accents can be obtained from \^^D instead of \^
-\def\AT!{@} % at sign for control text
-\def\@{@} % at sign in strings
-% EVERY WEAVE MUST DEFINE \? WHERE ? IS THE AT SIGN!!!!
-
-% Macros to surround text in |...|
-\def\CD{\relax\ifmmode\let\DC\egroup\hbox\bgroup\else\let\DC\relax\fi}
-\let\DC=\relax
-
-\chardef\AM=`\& % ampersand character in a string
-\chardef\BS=`\\ % backslash in a string
-\chardef\LB=`\{ % left brace in a string
-\def\LQ{{\tt\char'22}} % left quote in a string
-\chardef\RB=`\} % right brace in a string
-\def\RQ{{\tt\char'23}} % right quote in a string
-\def\SP{{\tt\char`\ }} % (visible) space in a string
-\chardef\TL=`\~ % tilde in a string
-\chardef\UL=`\_ % underline character in a string
-
-\newbox\bak \setbox\bak=\hbox to -1em{} % backspace one em
-\newbox\bakk\setbox\bakk=\hbox to -2em{} % backspace two ems
-
-\newcount\ind % current indentation in ems
-\def\0{\ifmmode\ifinner$\par % forced break
-  \hangindent\ind em\noindent\kern\ind em\ignorespaces$\fi
-  \else\par % forced break
-  \hangindent\ind em\noindent\kern\ind em\ignorespaces\fi}
-\def\1{\global\advance\ind by1\hangindent\ind em} % indent one more notch
-\def\2{\global\advance\ind by-1} % indent one less notch
-\def\3#1{\hfil\penalty#10\hfilneg} % optional break within a statement
-\def\4{\copy\bak} % backspace one notch
-\def\5{\hfil\penalty-1\hfilneg\kern2.5em\copy\bakk\ignorespaces}% optional break
-%\def\6{\ifmmode\else\par % forced break with no indentation
-%  \hangindent\ind em\noindent\kern\ind em\copy\bakk\ignorespaces\fi}
-\def\6{\ifmmode\else\par % forced break with no indentation
-  \hangindent\ind em\startline\ignorespaces\fi}
-\def\7{\Y\6} % forced break and a little extra space
-\def\8{\unskip} % no indentation--works only in code, not in |...|
-\def\startline{\noindent
-  \count255=\ind\advance\count255by-2
-  \hskip\count255 em}
-
-\let\yskip=\smallskip
-\def\note#1#2.{\Y\noindent{\hangindent2em\baselineskip10pt\eightrm#1 #2.\par}}
-\def\lapstar{\rlap{*}}
-\def\startsection{\Q\noindent{\let\*=\lapstar\bf\modstar.\quad}}
-\def\defin#1{\global\advance\ind by 2 \1\&{#1 }} % begin `define' or `format'
-\def\A{\note{See also}} % cross-reference for multiply defined section names
-\def\B{\mathopen{\.{@\commentbegin}}} % begin controlled comment
-\def\C#1{\ifmmode\gdef\XX{\null$\null}\else\gdef\XX{}\fi % C comments
-  \XX\hfil\penalty-1\hfilneg\quad
-	$\commentbegin\,${#1}$\,\commentend$\XX}
-\def\D{\defin{define}} % macro definition
-\def\F{\defin{format}} % format definition
-\def\J{\.{@\&}} % TANGLE's join operation
-\outer\def\M#1.{\MN#1.\ifon\vfil\penalty-100\vfilneg % beginning of section
-  \vskip12ptminus3pt\startsection\ignorespaces}
-\outer\def\N#1.#2.{\MN#1.\headcheck#2\headcheck
-  \edef\rhead{\uppercase{\ignorespaces\themodtitle}} % define running headline
-  \message{*\modno} % progress report
-  \edef\next{\write\cont{\thetocskip
-	\Z{\theopen\relax
-		\themodtitle}{\modno}{\noexpand\the\pageno}}}\next % to contents file
-  \ifon\startsection{\bf\ignorespaces\themodtitle.\quad}\ignorespaces}
-\def\MN#1.{\par % common code for \M, \N
-  {\xdef\modstar{#1}\let\*=\empty\xdef\modno{#1}}
-  \ifx\modno\modstar \onmaybe \else\ontrue \fi \mark{\modno}}
-\def\O#1{% octal, hex or decimal constant
-  {\def\?{\kern.2em}%
-  \def\${\ell}% long constant
-  \def\_{\cdot 10^{\aftergroup}}% power of ten
-  \def\~{\hbox{\rm\char'23\kern-.2em\it\aftergroup\?\aftergroup}}% octal
-  \def\^{\hbox{\rm\char"7D\tt\aftergroup}}% double quotes for hex constant
-  #1}}
-\def\P{\rightskip=0pt plus 100pt minus 10pt % go into Pascal mode
-  \sfcode`;=3000
-  \pretolerance 10000
-  \hyphenpenalty 10000 \exhyphenpenalty 10000
-  \global\ind=2 \1\startline}%\ \unskip}
-\def\Q{\rightskip=0pt % get out of Pascal mode
-  \sfcode`;=1500 \pretolerance 200 \hyphenpenalty 50 \exhyphenpenalty 50 }
-\def\T{\mathclose{\.{@\commentend}}} % terminate controlled comment
-\def\U{\note{This code is used in}} % cross-reference for uses of sections
-\def\X#1:#2\X{\ifmmode\gdef\XX{\null$\null}\else\gdef\XX{}\fi % section name
-  \XX$\langle\,$#2{\eightrm\kern.5em#1}$\,\rangle$\XX}
-\def\XF#1:#2\XF{\ifmmode\gdef\XX{\null$\null}\else\gdef\XX{}\fi % section name
-  \XX{\tt(#2{\eightrm\kern.5em#1})}\XX}
-\def\Y{\par\yskip}
-\def\){\hbox{\.{@\$}}} % sign for string pool check sum
-\def\]{\hbox{\.{@\\}}} % sign for forced line break
-\def\=#1{\kern2pt\hbox{\vrule\vtop{\vbox{\hrule
-        \hbox{\strut\kern2pt\.{#1}\kern2pt}}
-      \hrule}\vrule}\kern2pt} % verbatim string
-\let\~=\ignorespaces
-\let\*=*
-
-
-\def\DO{\hbox{\sl\char'044}} % slant dollar sign
-\let\G=\ge % greater than or equal sign
-\def\H{{\rm\char'136}} % hat
-\let\I=\ne % unequal sign
-\let\K=\gets % left arrow
-\let\L=\le % less than or equal sign
-\let\R=\lnot % logical not
-\let\S=\equiv % equivalence sign
-\let\TI\sim % tilde
-\let\V=\lor % logical or
-\let\W=\land % logical and
-\let\Z=\let % now you can \send the control sequence \Z
-
-
-\def\onmaybe{\let\ifon=\maybe} \let\maybe=\iftrue
-\newif\ifon \newif\iftitle \newif\ifpagesaved
-\def\lheader{\mainfont\the\pageno\eightrm\qquad\rhead\hfill\title\qquad
-  \tensy x\mainfont\topmark} % top line on left-hand pages
-\def\rheader{\tensy x\mainfont\topmark\eightrm\qquad\title\hfill\rhead
-  \qquad\mainfont\the\pageno} % top line on right-hand pages
-\def\lfooter{\hfil} % bottom line on left-hand-pages
-\def\rfooter{\hfil} % bottom line on left-hand-pages
-\def\page{\box255 }
-\def\normaloutput#1#2#3#4#5{%
-%\message{(At start top, first, and bottom marks: \topmark, \firstmark, \botmark)}%
-\shipout\vbox{
-  \iftwoside\else\ifodd\pageno\hoffset=\pageshift\fi\fi
-  \vbox to\fullpageheight{
-     \iftitle
-     \else\hbox to\pagewidth{\vbox to10pt{}%
-   	\ifodd\pageno#3\else
-		\iftwoside#2\else#3\fi
-	\fi}%
-     \fi
-     \vfill#1% parameter #1 is the page itself
-     \iftitle\global\titlefalse
-     \else\baselineskip=24pt\hbox to\pagewidth{\strut % see TeXbook p256
-	\ifodd\pageno#5\else
-		\iftwoside#4\else#5\fi
-	\fi}%
-     \fi
-  }%
-}%
-\global\advance\pageno by1
-%\message{(At end top, first, and bottom marks: \topmark, \firstmark, \botmark)}%
-}
-
-
-\def\rhead{\.{WEB} OUTPUT} % this running head is reset by starred sections
-\def\title{} % an optional title can be set by the user
-\def\topofcontents{\centerline{\titlefont\title}
-  \vfill} % this material will start the table of contents page
-\def\botofcontents{\vfill} % this material will end the table of contents page
-\def\contentspagenumber{0} % default page number for table of contents
-\newdimen\pagewidth \pagewidth=6.5in % the width of each page
-\newdimen\pageheight \pageheight=8.4in % the height of each page
-\newdimen\fullpageheight \fullpageheight=9in % page height including
-					     % headlines and footlines
-\newdimen\pageshift \pageshift=0in % shift righthand pages wrt lefthand ones
-\catcode`\@=11 % make at letter
-\def\m@g{\mag=\count@\pagewidth=6.5truein\pageheight=8.4truein
-  \fullpageheight=9truein\setpage}
-\catcode`\@=12 % make at other
-\def\setpage{\hsize\pagewidth\vsize\pageheight} % use after changing page size
-
-\edef\contentsfile{\jobname.toc } % file that gets table of contents info
-\def\readcontents{\expandafter\input \contentsfile}
-
-\newwrite\cont
-\output{\setbox0=\page % the first page is garbage
-  \openout\cont=\contentsfile
-  \write\cont{\string\catcode`\string\@=11}% a hack to make contents
-	  				   % take stuff in \.{---}
-  \global\output{\normaloutput\page\lheader\rheader\lfooter\rfooter}}
-\setpage
-\vbox to \vsize{} % the first \topmark won't be null
-% Delete as per bug report from kademan@stat.wisc.edu
-% Causes headings on first page to be missing
-% \eject
-
-\def\ch{\note{The following sections were changed by the change file:}
-  \let\*=\relax}
-\newbox\sbox % saved box preceding the index
-\newbox\lbox % lefthand column in the index
-\def\inx{\par\vskip6pt plus 1fil % we are beginning the index
-  \write\cont{} % ensure that the contents file isn't empty
-  \closeout\cont % the contents information has been fully gathered
-  \output{\ifpagesaved\normaloutput{\box\sbox}\lheader\rheader
-		\lfooter\rfooter\fi
-    \global\setbox\sbox=\page \global\pagesavedtrue}
-  \pagesavedfalse \eject % eject the page-so-far and predecessors
-  \setbox\sbox\vbox{\unvbox\sbox} % take it out of its box
-  \vsize=\pageheight \advance\vsize by -\ht\sbox % the remaining height
-  \hsize=.5\pagewidth \advance\hsize by -10pt
-    % column width for the index (20pt between cols)
-  \parfillskip 0pt plus .6\hsize % try to avoid almost empty lines
-  \def\lr{L} % this tells whether the left or right column is next
-  \output{\if L\lr\global\setbox\lbox=\page \gdef\lr{R}
-    \else\normaloutput{\vbox to\pageheight{\box\sbox\vss
-        \hbox to\pagewidth{\box\lbox\hfil\page}}}\lheader\rheader
-	\lfooter\rfooter
-    \global\vsize\pageheight\gdef\lr{L}\global\pagesavedfalse\fi}
-  \message{Index:}
-  \parskip 0pt plus .5pt
-  \outer\def\:##1, {\par\hangindent2em\noindent##1:\kern1em} % index entry
-  \def\[##1]{$\underline{##1}$} % underlined index item
-  \rm \rightskip0pt plus 2.5em \tolerance 10000 \let\*=\lapstar
-  \hyphenpenalty 10000 \parindent0pt}
-\def\fin{\par\vfill\eject % this is done when we are ending the index
-  \ifpagesaved\null\vfill\eject\fi % output a null index column
-  \if L\lr\else\null\vfill\eject\fi % finish the current page
-  \parfillskip 0pt plus 1fil
-  \def\rhead{NAMES OF THE SECTIONS}
-  \message{Section names:}
-  \output{\normaloutput\page\lheader\rheader\lfooter\rfooter}
-  \setpage
-  \def\note##1##2.{\quad{\eightrm##1 ##2.}}
-  \def\U{\note{Used in}} % cross-reference for uses of sections
-  \def\:{\par\hangindent 2em}\let\*=*}
-\def\con{\par\vfill\eject % finish the section names
-  \rightskip 0pt \hyphenpenalty 50 \tolerance 200
-  \setpage
-  \output{\normaloutput\page\lheader\rheader\lfooter\rfooter}
-  \titletrue % prepare to output the table of contents
-  \pageno=\contentspagenumber \def\rhead{TABLE OF CONTENTS}
-  \message{Table of contents:}
-  \topofcontents
-  \line{\hfil Section\hbox to3em{\hss Page}}
-  \def\Z##1##2##3{\line{{\ignorespaces##1}
-    \leaders\hbox to .5em{.\hfil}\hfil\ ##2\hbox to3em{\hss##3}}}
-  \readcontents\relax % read the contents info
-  \botofcontents \end} % print the contents page(s) and terminate
-%\tracingstats1 % temporary (during development)
-
-
-\def\vert{|}
-		
-%%% this stuff is to allow inital =,1,2,3,4 in starred modules
-%%% 	= means ``part'', don't skip page
-%%%	normal starred module is 0
-%%%		1,2,3,4 are submodules, and are indented
-%%%
-%%%	@*=	bold name in table of contents
-%%%		causes page eject
-%%%		suppresses page eject following
-%%%
-%%%	@*1,2	first level of indentation
-%%%	@*3,4	second level of indentation
-%%%
-%%%     @*1,3	cause page eject
-%%%     @*2,4	don't cause page eject
-%%%
-
-
-\newif\ifcancel\cancelfalse
-\catcode`\@=11
-\def\ifnextchar#1#2#3{\let\@tempe=#1\def\@tempa{#2}\def\@tempb{#3}\@ifnch}
-\def\@ifnch{\ifx \@tempc \@tempe\let\@tempd\@tempa\else\let\@tempd\@tempb\fi
-      \@tempd}
-\def\makethechar#1{\let\@tempc=#1}
-\catcode`\@=12
-
-\def\headcheck#1#2\headcheck{%
-	\makethechar{#1}%
-	\def\theskipper{\vfil\penalty-100\vfilneg\vskip12ptminus3pt}%
-				% skip before new module
-	\def\theopen{}% opening skip in toc entry
-	\def\thetocskip{}% vertical skip before toc entry
-	\def\themodtitle{{#2}}
-	\ifnextchar={%
-		\def\theskipper{\vfil\eject}%
-		\canceltrue
-		\def\theopen{\bf}%
-		\def\thetocskip{\vskip3ptplus1in\penalty-100
-			\vskip0ptplus-1in}%
-	}{\ifnextchar1{%
-		\cancelfalse
-		\def\theskipper{\vfil\eject}%
-		\def\theopen{\hskip2em}%
-	}{\ifnextchar2{%
-		\cancelfalse
-		\def\theopen{\hskip2em}%
-	}{\ifnextchar3{%
-		\cancelfalse
-		\def\theskipper{\vfil\eject}%
-		\def\theopen{\hskip4em}%
-	}{\ifnextchar4{%
-		\cancelfalse
-		\def\theopen{\hskip4em}%
-	}{% else 
-		\ifcancel\else
-			\def\theskipper{\vfil\eject}%
-		\fi
-		\cancelfalse
-		\def\themodtitle{#1{#2}}%
-	}}}}}%
-	\theskipper
-}
-
-
-%%%%%%%% for verbatim quoting of code
-% The following are copied from manmanc.tex and are taken from p421 of
-% the TeXbook  ... modified to \verbatim...\endverbatim
-% macros for verbatim scanning
-\chardef\other=12
-\def\ttverbatim{\begingroup
-  \catcode`\|=\other
-  \catcode`\\=\other
-  \catcode`\{=\other
-  \catcode`\}=\other
-  \catcode`\$=\other
-  \catcode`\&=\other
-  \catcode`\#=\other
-  \catcode`\%=\other
-  \catcode`\~=\other
-  \catcode`\_=\other
-  \catcode`\^=\other
-  \obeyspaces \obeylines \tt}
-{\obeyspaces\global\let =\ } % from texbook, p 381
-
-
-%\outer\def\verbatim{$$\let\par=\endgraf \ttverbatim \parskip=0pt
-%  \catcode`\|=0 \rightskip-5pc \ttfinish}
-%{\catcode`\|=0 |catcode`|\=\other % | is temporary escape character
-%  |obeylines % end of line is active
-%  |gdef|ttfinish#1^^M#2\endverbatim{#1|vbox{#2}|endgroup$$}}
-
-\outer\def\verbatimcode{\par\ttverbatim\leftskip=2em\parskip=0pt
-  \ttfinishcode}
-{\catcode`\|=0 |catcode`|\=\other % | is temporary escape character
-  |obeylines % end of line is active
-  |gdef|ttfinishcode#1^^M#2\endverbatimcode{#1|vbox{#2}|endgroup}}
-
-
-% end of manmac stuff
-
End of webkernel.tex
 
From marcus@x4u.desy.de Wed Jun 30 19:14:16 +0200 1993
Date: Wed, 30 Jun 93 19:14:16 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: Literate Programmers <litprog@shsu.edu>
Subject: re: Fweb and C++
 
>>>>> On Wed, 30 Jun 1993 10:54:31 -0400, drs@bach.pdb.bnl.gov (drs) said:
 
|> I seem to be spending an inordinate amount of effort forcing the format of C++
|> code in fweb. (It seems to want to stick an entire method on one line.) I can't
|> believe that this is correct.
 
|> Does anyone have a sample C++ web that I can use as a baseline model? The demos
|> that are shipped with fweb 1.3 are not useful in seeing what I am doing wrong.
 
I dont know whether some silly samples I wrote can be of help -- look
in ftp.desy.de, directory pub/web/fweb -- this information is also
contained (plus more samples) in the WWW LitProg info page which you
may consult. Whatever your findings are, write to me and I put it
in the next FWEB FAQ -- sorry for this brief answer, I am about to leave!
 
		Marcus
 
ps info how to get to WWW is in 
   pub/www/projects/Announce/LitProg.txt
 
From George Wed Jun 30 12:37:20 CST 1993
Date: Wed, 30 Jun 1993 12:37:20 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: ae1181t@stnfor.ae.ge.com
Subject: RE: nuweb msdos fix
 
On 29 Jun 1993 08:56:42 -0400, Osman F Buyukisik <ae1181t@stnfor.ae.ge.com>
posted:
> I just saw a message on the litprog on nuweb-msdos. It was my mistake. The
> executable that I uploaded earlier had assumed that the user has go32.exe
> (DJ's dos extender) on their path somewhere! So I uploaded go32.exe and a
> new executable which does not need go32.exe to incoming/nuweb-msdos-fix
> directory. Sorry for the inconvenience. 8*(
 
No problem.  I got backlogged and didn't check incoming yesterday and
haven't today until just now.  I have moved the files to
tex-archive/web/nuweb/msdos/ on ftp.shsu.edu for anonymous ftp retrieval
(or the gopher link from niord should work fine).
 
Thanks for the update and my apologies to the LitProg community for not
handling this yesterday.
 
--George
 
From ravn@imada.ou.dk Wed Jun 30 21:38:05 MET 1993
Date: Wed, 30 Jun 93 21:38:05 MET DST
From: ravn@imada.ou.dk (Thorbjoern Ravn Andersen)
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu
Subject: How to use several modes in Emacs when writing for NUWEB?
 
The sys-adms here at Odense University (myself included) have a small
problem arisen from this scenario.
 
* We use LaTeX for documentation, which is most convenient from Emacs
  using AUC-TeX (*) where LaTeX mode is a major mode.
 
* We write sys-adm programs in Perl (**) which has its own major mode
  with a lot of bells and whistles.
 
So far so good.
 
We have now started using NUWEB (***) for writing programs of all sorts
intermixed with LaTeX code, especially Perl programs.  This doesn't work
very well because we have to switch major modes manually and repeatedly
because code and documentation is interlaced.
 
Have anybody had the same problem, or is there an easy cure?
 
[I have posted this several places, which is why I explain all the tools
we are using here:
 
*:   AUC-TeX for Emacs is an excellent package for doing LaTeX stuff
     from within Emacs.  Recommended if this is your editor and
     typesetter.
 
**:  Perl is a shell-and-C-and-AWK featuring language which is great for
     doing sys-adm things, as well as "use awk" or "use grep"
     situations.
 
***: NUWEB is a language independent WEB translator used in Litterate
     Programming , or said in other words.  It allows producing
     documented code as well as the actual source code from a common
     file, in which the source code components are grouped according to
     function (or whatever the programmer wants) instead as dictated by
     the language chosen.  NUWEB builds on ideas and experience from
     users of WEB which Knuth wrote for making TeX.
]
 
Thanks in advance for any feedback -- if there is sufficient interest I
will summarize.
 
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From infmx!quivira!grodecki@uunet.UU.NET Wed Jun 30 16:55:28 CDT 1993
Date: Wed, 30 Jun 93 16:55:28 CDT
From: infmx!quivira!grodecki@uunet.UU.NET (Don Grodecki)
Reply-To: LitProg@SHSU.edu, infmx!quivira!grodecki@UUNET.UU.NET
To: uunet!SHSU.edu!LitProg@uunet.UU.NET, uunet!BT-WEB.BT.CO.UK!mckearney_s@uunet.UU.NET
Subject: WORDWEB limits
 
Can I get a copy somehow?  Perhaps send you diskettes in the mail with
a SASE for return?  I would need your surface address.
 
----- Begin Included Message -----
 
From mckearney_s Thu Jul 1 07:58:13 +0100 1993
Date: Thu, 1 Jul 1993 07:58:13 +0100
From: mckearney_s <mckearney_s@bt-web.bt.co.uk>
Reply-To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK
To: litprog@shsu.edu
Subject: WORDWEB
 
Some people have requested a copy of my adapted version of WORDWEB 
and I am looking into uuencoding it for email or something.  However, 
my company pay me to do another job so I am trying to fit it in to my 
free time.  I am doing my best to get this done.  Sorry for the 
delay.
 
Stephen
 
From Thorbjoern Thu Jul 1 12:33:53 MET 1993
Date: Thu, 1 Jul 93 12:33:53 MET DST
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu
Subject: Re: Re:Are modules necessary?
 
Osman F Buyukisik
| 
| Hi, maybe I misunderstood the first time, but it looks like you are right
| ``numbers'' are not needed. Need a better method than just page numbers
| for the indices (like what Norman said 17a, 17b,...). 
 
I accidentially deleted Normans message so I am replying to this one
instead. 
 
What was the main difficulty in using pagenumbers instead of scrap
numbers in nuweb?  As I gather it the \pageref macro in LaTeX should do
the job, perhaps with a slight addition to it that makes a count of the
references on the page like this
 
  Used on page $17_2$  .. or .. Used on page 17 (twice)
 
I like the general idea but an actual implementation is something else.
Perhaps making it an option?
 
Regards,
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From Adrian Thu Jul 1 13:36:08 +0100 1993
Date: Thu, 1 Jul 93 13:36:08 +0100
From: Adrian F Clark <alien@essex.ac.uk>
Reply-To: LitProg@SHSU.edu, alien@ESSEX.AC.UK
To: LitProg@SHSU.edu
Subject: Re: Are modules necessary?
 
On Thu, 1 Jul 93 12:33:53 MET DST, Thorbjoern Ravn Andersen <ravn%imada.ou.dk@uk.ac.essex.mailhost> said:
T> What was the main difficulty in using pagenumbers instead of scrap
T> numbers in nuweb?  As I gather it the \pageref macro in LaTeX should do
T> the job, perhaps with a slight addition to it that makes a count of the
T> references on the page like this
 
T>   Used on page $17_2$  .. or .. Used on page 17 (twice)
 
There's no real difficulty in using page numbers for cross-references
in Nuweb: one could use the same approach as in NOWEB.  However, the
only way I can see to produce the indices (which currently refer to
module numbers, remember) would be to generate LaTeX \index commands
and then use MakeIndex.  Not out of the question, but certainly less
neat then the current one-pass solution.
 
..Adrian
 
 Dr Adrian F. Clark                                   JANET: alien@uk.ac.essex
 INTERNET: alien%uk.ac.essex@nsfnet-relay.ac.uk          FAX: (+44) 206-872900
 BITNET: alien%uk.ac.essex@ac.uk              PHONE: (+44) 206-872432 (direct)
 Dept ESE, University of Essex, Wivenhoe Park, Colchester, Essex, C04 3SQ, UK.
 
From Thorbjoern Thu Jul 1 15:41:40 MET 1993
Date: Thu, 1 Jul 93 15:41:40 MET DST
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu, alien@ESSEX.AC.UK
Subject: Re: Are modules necessary?
 
Adrian F Clark
| 
| There's no real difficulty in using page numbers for cross-references
| in Nuweb: one could use the same approach as in NOWEB.  However, the
| only way I can see to produce the indices (which currently refer to
| module numbers, remember) would be to generate LaTeX \index commands
| and then use MakeIndex.  Not out of the question, but certainly less
| neat then the current one-pass solution.
 
That is true, but would that not be the case anyhow if page numbers
were chosen as the main reference (which would then go for the index as
well), as Nuweb has no idea of the actual placement of the scraps on the
pages?
 
Putting implementation issues aside -- what is the most convenient label
of modules for using a Web?  
 
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From drs@bach.pdb.bnl.gov Thu Jul 1 10:36:15 -0400 1993
Date: Thu, 1 Jul 1993 10:36:15 -0400
From: drs@bach.pdb.bnl.gov (drs)
Reply-To: LitProg@SHSU.edu, drs@BACH.PDB.BNL.GOV
To: LitProg@SHSU.edu
Subject: re: Fweb and C++
 
Hello folks,
 
Yesterday I sent a message to this group asking about the formatting of C++ code
with fweb. I recieved one response from Marcus Speh, which tried to be helpful,
but points out a weak point in the tex/web approach to LitProg, and a general
weakness that others have encountered with TeX in general.
 
Marcus pointed to a file on his system that gave an example of a C++ web, but
required latex to run. Fine - I have latex, ran it through fweave/latex and
recieved an error message. Maybe two weeks from now, I will be able to decode
the message, but just now I cannot. Marcus and I decided that it probably is
based on a difference in fwebmac.sty (?) files between his system and mine. His
is hacked, mine fresh from the box. (The message is attached below.)
 
If the purpose of LitProg is to communicate what we have done, then this is a
clear failure! Marcus has a web that is undecipherable to me, and even if I
manage to figure out this problem, that simply postpones the pain until next
time.
 
So, the question is, in general, how do we make webs (and other tex files)
transportable?
 
The basic question still remains however - how best to do LitProg in C++, and
how to get it properly formatted. In a few minutes, I'll post a rather crude C++
web that I've been working on as an example of what I am trying to do on a
development project that I am a part of. I will have to convince mgmt as well as
some skeptical programmers that this is worthwhile, so I'd like some opinions on
the general approach.
 
Dave
 
(PS - this isn't grumbling - I really want this to work!)
 
Error msg:
bach 151% fweave -PL IntArray.web
This is FWEAVE [UNIX version 1.30 (June 10, 1993)].
Reading IntArray.web... *1 *2 *30 *31 *37 *38
Writing IntArray.tex... *1 *2 *30 *31 *37 *38
Writing INDEX.tex...MODULES.tex...
Done.
CPU = 0.4 sec.; REAL <= 1.0 sec.  CPU/REAL = 39.0%.
[FWEAVE:  No errors were found.]
bach 152% latex IntArray.tex
This is TeX, Version 3.141 (C version d)
(IntArray.tex
LaTeX Version 2.09 <14 January 1991>
(/usr/bach.pdb.bnl.gov/lib/tex/macros/fwebmac.sty
LaTeX error.  See LaTeX manual for explanation.
              Type  H <return>  for immediate help.
! Missing \begin{document}.
\@latexerr ...for immediate help.}\errmessage {#1}
 
<to be read again>
                   e
l.128  e
        venit
? H
You're in trouble here.  Try typing  <return>  to proceed.
If that doesn't work, type  X <return>  to quit.
? X
No pages of output.
Transcript written on IntArray.log.
bach 153%
 
-Sigh-
 
On Jun 30,  7:14pm, Marcus Speh wrote:
> Subject: re: Fweb and C++
> >>>>> On Wed, 30 Jun 1993 10:54:31 -0400, drs@bach.pdb.bnl.gov (drs) said:
>
> |> I seem to be spending an inordinate amount of effort forcing the format of
C++
> |> code in fweb. (It seems to want to stick an entire method on one line.) I
can't
> |> believe that this is correct.
>
> |> Does anyone have a sample C++ web that I can use as a baseline model? The
demos
> |> that are shipped with fweb 1.3 are not useful in seeing what I am doing
wrong.
>
> I dont know whether some silly samples I wrote can be of help -- look
> in ftp.desy.de, directory pub/web/fweb -- this information is also
> contained (plus more samples) in the WWW LitProg info page which you
> may consult. Whatever your findings are, write to me and I put it
> in the next FWEB FAQ -- sorry for this brief answer, I am about to leave!
>
> 		Marcus
>
> ps info how to get to WWW is in
>    pub/www/projects/Announce/LitProg.txt
>
>
>
>-- End of excerpt from Marcus Speh
 
From drs@bach.pdb.bnl.gov Thu Jul 1 10:54:51 -0400 1993
Date: Thu, 1 Jul 1993 10:54:51 -0400
From: drs@bach.pdb.bnl.gov (drs)
Reply-To: LitProg@SHSU.edu, drs@BACH.PDB.BNL.GOV
To: litprog@shsu.edu
Subject: C++ web
 
This is a C++ web aimed at fweb 1.30. I created it with gnu emacs and it's web
mode. (What a super way to work!)
 
Some background, I'm not especially TeX literate, tho I know enough to run it
and get a listing.
 
I'm not concerned so much with the details of the internals of the class as I am
with the presentation. Here are my gripes:
 
1) Title on the title page is vanishingly small. (I can probably fix this.)
2) The words Model and List appear in italics before they are defined, bold
afterwards. I'd like to have them all appear in bold, but I don't want to bother
the user with the formatting details (The @f command is visible in the weave -
yuch!)
3) I wish the subsections used decimal notation (e.g. 3.1, 3.1.1, etc.) The
table of contents reflects the heirarchy of topics, but the document does not.
4) The formatting of code is good until it hits - well - code. It seems to use
the "fit as much code on one line as you can" formatting algorithm *except* if
it encounters a function with 0 or 1 line.
 
I have to tell you that I particularly like the idea of having hard wired (or at
least templated) sections for constructors/destructors/conversion
operators/assignment operators etc. in the web - it acts as a reminder to the
poor suffering C++ programmer who has a *lot* to worry about, and should be
aiming to have concrete classes!
 
In any case, it is early in the development cycle here, so if others have
templates, for C++ I'd love to see them.
 
Here is the web:
 
Dave
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                             %
%                       PROGRAM  :  Model.web                                 %
%                       CREATOR  :  drs [drs@@bach.pdb.bnl.gov]               %
%                 CREATION DATE  :  Tue Jun 29 08:42:10 1993                  %
%                                                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%% limbo.material used at aTm as of 7 Dec '92  cut-here
%
% ??????.web,   ?fweb version 1.23 ????
% e-mail and phone number ????
% More comments are helpful if not created with web-mode
%
 
%
%   LIMBO MATERIAL  Last edited by Bart Childs on December 1, 1992
%
\input limbo.sty
\input today.tex
\input time.tex
\def\title{{\bf Model Class}}
% web-mode edits the previous line when creating a new web.
% Make the previous a comment and edit the next if you don't use web-mode.
%\def\title{{\tt ?? I need a Title ??}}
% begin Bottom of Contents Page macro
\def\botofcontents{\vskip 0pt plus 1fil minus 1.5in
{\bigskip\parskip6pt plus2pt \parindent20pt
% begin abstract
\vskip0.5in
\noindent{\bf Abstract. }\it
% The abstract is put right here!
This web describes the Model base class, which is used to implement
the MVC paradigm from Smalltalk.
}% end abstract
% BC often puts this in as a comment about pre-release versions ...
%\vskip0.5in
%{\vfill\it % comments on anything else ????
%
%}% end of comments on anything else
\vfil
  \rightline{Dave Stampf}% You can personalize your output here, for example.
  \rightline{\today     }% today.tex should be preloaded, input it if not
  \rightline{\miltime   }% time.tex  should be preloaded, input it if not
}%      end of Bottom of Contents Page macro
 
%   This ends the limbo material and begins the WEB
%
% In fweb's you want an AT-c, AT-c++, AT-n, AT-n9, or AT-Lx at this point
%   and be sure to replace `AT-' with the obvious character!!!!!
 
@c++
 
@* Overview of Models.
 
@f Model int
@f List int
@f NULL int
 
The |Model| Class is a root level abstract class which gives a basic
functionality to all other derived classes. This functionality is
called a ``dependency'' between two objects, in that one object wishes to
know if another has been modified. It is at the heart of the
Model-View-Controller paradigm from Smalltalk. There, the View is
typically a bit-mapped graphic view of {\it something} which we call
generically a |Model|. When the |Model| changes state, it sends out a
``changed'' message to all of its dependents. Since the View is one such
dependent, it is notified when whatever it represents changes and so
takes action to keep up to date. Note that each object may have several
dependents.
 
@* Relation to Other Classes.
 
This is a root class. It inherits from no other class. It contains a reference
to a |List| class which
contains the list of dependents. Many classes are derived from the |Model|
class.
 
@<Model Interface Header@>=
 
class Model
 
@* Specific Behaviour.
 
@*1 Maintainence of the Dependency Relationship.
 
The core of the |Model| class is concerned with maintaining a list of
the |Model|'s dependents. Basically, one has to be able to append and
remove dependents.
 
@<Model Interface Definition@>=
 
public:
	void AddDependent(Model *aDependent);
	int  RemoveDependent(Model *aDependent);
 
@*1 Handling Modifications.
 
Every object which is derived from |Model| should send itself the
``changed'' message whenever it changes its state. It then sends the
message ``update'' to all of its dependents. For simplicity, I've put
all of these messages in the |Model| class, though in reality, it need
only appear in a separate View class.
 
@<Model Interface Definition@>=
 
public:
	void Changed(void);
	void Update(void);
	void GoodBye(void);
 
@* Representation.
 
The internal representation of the |Model| class is entirely private. It
consists only of a pointer to a |List| object. When that pointer is
|NULL|, there are no dependents.
 
@f List class
 
@<Model Interface Definition@>=
 
private:
	List *dependentsList;
 
@
 
Don't forget to declare |List| as a class. You don't have to provide
details in the |Model| header file, buy you do in the |Model| implementation.
 
@<Model Interface Includes@>=
 
class List;
 
@* Implementation of Behaviour.
 
The behaviour of the List class is determined by 4 functions.
AddDependent, RemoveDependent, Changed, and Update. As much as
possible, try to eliminate the |List| object for efficiency. (Most
methods should check to make sure it is not |NULL| before doing anything.
 
@*1 AddDependent.
 
Whenever you add a dependent, place it at the tail end of the
dependents list. If the list does not exist, create it first.
 
@<Model Implementation Body@>=
void Model::AddDependent(Model* aDependent)
{
	if (!dependentsList) {
		dependentsList = new List;
	}
	dependentsList->Append(aDependent);
}
 
@*1 RemoveDependent.
 
Remove the specified dependent if you can.
 
@<Model Implementation Body@>=
int Model::RemoveDependent(Model* aDependent)
{
	if (dependentsList) return dependentsList->Remove(aDependent);
	else return 0;
}
 
@*1 Changed.
 
Whenever an object changes state, it sends itself the ``changed''
message, which causes all of its dependents to be notified.
 
@<Model Implementation Body@>=
void Model::Changed(void)
{
	if (dependentsList) dependentsList->SendUpdateToAll();
}
 
@*1 Update.
 
Every class which depends upon another needs to define an Update
message. The generic response is to ignore it.
 
@<Model Implementation Body@>=
void Model::Update(void)
{
}
 
@*1 GoodBye.
 
Every class which depends upon another needs to define a GoodBye
message for when the object it depends on destructs. The generic
response is to ignore it.
 
@<Model Implementation Body@>=
void Model::GoodBye(void)
{
}
 
@* Making Models Concrete.
 
To really make this class useful, try to make it a first class C++
type. This requires only a few methods to be defined. First of all,
you need a decent constructor set and a destructor. Then you need to
redefine the assignment operator to behave reasonably.
 
@*1 Constructors.
 
There should be at least a default constructor, and one constructed
from a similar object to handle function calls.
 
@<Model Interface Definition@>=
 
public:
Model();
Model(const Model &aModel);
 
@
My feeling right now is that whenever a new
|Model| is constructed, it should not have any dependents. This would be
a mess with windows etc. Lets see just how it works.
 
@<Model Implementation Body@>=
 
Model::Model()
{
	dependentsList = 0;
}
 
Model::Model(const Model &aModel)
{
	dependentsList = 0;
}
 
@*1 Destructors.
 
When you have dynamic memory and complex relations, you must have a
destructor.
 
@<Model Interface Definition@>=
 
public:
~Model();
 
@
 
Whenever you destroy a |Model|, you should let all of its dependents
know that it is no longer around by sending all of them a Goodbye
message.
 
@<Model Implementation Body@>=
 
Model::~Model()
{
	if (dependentsList) dependentsList->SendGoodByeToAll();
	delete dependentsList;
}
 
@*1 Assignment Operator.
 
All first class C++ types can be assigned. This is no different.
 
@<Model Interface Definition@>=
public:
const Model& operator=(const Model& aModel);
 
@
 
Once again, don't bother to build up the dependents list on
assignment.
 
@<Model Implementation Body@>=
const Model& Model::operator=(const Model& aModel)
{
	Model *tmp = new Model;
 
	return *tmp;
}
 
@* Details.
 
About all that is left to take care of is to actually create the
files. Every class we create has two files associated with it. The
header (.h) file and the implementation (.c++) file.
 
@a
@o Model.h
 
#ifndef MODEL_H
#define MODEL_H
 
@<Model Interface Includes@>
 
@<Model Interface Header@>
{
@<Model Interface Definition@>
};
 
#endif
 
@
 
The implementation file is output directly.
 
@a
 
@<Model Implementation Includes@>
@<Model Implementation Body@>
 
@ @^Stub@>
@<Model Interface Includes@>=
/* empty */
 
@ @^Stub@>
@<Model Implementation Includes@>=
#include "Model.h"
#include "List.h"
 
@* Index.
 
%%% end of limbo.material
 
From preston@cs.rice.edu Thu Jul 1 11:21:42 CDT 1993
Date: Thu, 1 Jul 93 11:21:42 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: nuweb and page numbers
 
I think that pages numbers (or some sort) would be great.
However, I can't see a clean way to add them to nuweb.
The obvious approach is to use add a \label to each scrap
and use \pageref wherever I need to refer to a scrap
(in the crossreference lists and the indices).
 
Unfortunately, I can't eliminate duplicates before running latex
and I think the lists will look really ugly with lots of duplicate
page numbers.  However, it's an easy experiment if someone wants to
try it.
 
An alternative that might work out would be to inspect the .aux file
created by latex.  It'll have all the labels and page numbers from the
last run of latex and therefore should be reasonably close.
Hmmmm...  I like this idea.  I'll give it a shot in my copious
spare time.
 
Preston
 
From Zdenek Thu Jul 01 10:50:33 MDT 1993
Date: Thu, 01 Jul 93 10:50:33 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: CWEB for LaTeX?
 
Several days ago I saw an announcement of LaTeX support in CWEB. I erased
the message in the hope that it will appear in H. H. Bode's PC port. However,
this version does not contain CWEB.STY (it was announced to be the main style)
and I probably forgot the name of the Darmstadt ftp site (my four attempts
failed due to unknown host). Can someone help me to find the correct site?
 
Thanks in advance
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From ae1181t@stnfor.ae.ge.com Thu Jul 1 13:11:47 -0400 1993
Date: Thu, 1 Jul 1993 13:11:47 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, drs@BACH.PDB.BNL.GOV
Subject: re: Fweb and C++
 
Sounds like fweb produced a TeX version not LaTeX. Try using TeX on the
weaved file. There is a considerable learning curve on fweb, just look
at the manual! If you are not that interested in automatic formatting
of your code, and forgo the auto generated index, I would suggest trying
nuweb. It is laguage independent but uses LaTeX as typesetter. The only
system that I know that is also typesetter/word-processor independent is
CLiP (works only on msdos). In all of these systems you do the code
pretty-printing yourself. Nuweb offers user requested indices. These
systems that I mentioned are very easy to learn as their manuals are a
few pages long! 
Litprog paradigm is independent of  word-processor/editor/typesetter
and language independent. However TeX and LaTeX provide typeset quality
outputs and are used most often. You do need to know TeX or LaTeX to
use them. But there are a lot of ``litprog'' tools, just choose the
one that suits you.
Osman
 
From krommes@theory.pppl.gov Thu Jul 1 15:22:23 EDT 1993
Date: Thu, 1 Jul 93 15:22:23 EDT
From: krommes@theory.pppl.gov (John Krommes)
Reply-To: LitProg@SHSU.edu, Krommes@princeton.edu
To: litprog@shsu.edu
Subject: FWEB and C++
 
Dave Stampf's C++ example for FWEB 1.30 will weave much better if all the
@f statements are removed.  These are evidently in there to force certain
|class|-related identifiers to format correctly before they are defined in
the web.  The problem is analogous to difficulties in earlier web
processors with the |typedef| statement in C.  FWEAVE now processes
|typedef| statements during the first pass, rather than the second, so
|typedef|'d identifiers will format properly even before they are defined.
I haven't gotten around to doing the analogous thing for |class| yet; I
rely on users to let me know what's bothering them.
 
In FWEB 1.30, @f statements can be made invisible with the command-line
option ``-Wf''.
 
Various users have asked for subsections numbered as 3.1.1 etc.  This
feature will be provided in the next major FWEB release, along with a
general upgrade of the LaTeX support.
 
As a personal preference, I would prefer that this literate programming
discussion group not be used for the microscopic debugging of various
processors (whether it be my FWEB or anyone else's), detailed installation
questions, etc.  I think such details should be directed at the appropriate
author via ordinary, private e-mail.  I feel that the best use of this
discussion group is to address general conceptual issues---e.g., are
language-sensitive webs obsolete?  
 
Regarding this latter issue, I feel that if a language such as Fortran or C
is supported, use of a language-sensitive processor is far superior to an
insensitive one, for the reasons mentioned recently by Bart Childs.
However, it is clearly impractical to support all possible languages, so
tools such as NUWEB certainly have their place.  I expect that the next
release of FWEB will offer a ``no-language'' option, implemented as one of
FWEB's multiple languages.  This is a straightforward extension of FWEB's
meta-comment facilities and will enable one to move between language
sensitivity and NUWEB-type output at will.
 
--- John
 
krommes@princeton.edu                           |  John A. Krommes
                                                |  Plasma Physics Laboratory
(Mail to krommes@princeton.edu is forwarded     |  P.O. Box 451
to krommes@lyman.pppl.gov == 192.55.106.129)    |  Princeton, NJ  08543
 
(To ftp files, you must use lyman.pppl.gov.)    |  Phone:  (609) 243--2606  
                                                |  Fax:    (609) 243--2662
 
From Edward Thu Jul 01 18:33:07 EDT 1993
Date: Thu, 01 Jul 1993 18:33:07 EDT
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu, ed@EFKPORT.KEW.COM
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: re: Fweb and C++
 
On Thu, 1 Jul 1993 10:36:15 -0400, "drs" <drs@bach.pdb.bnl.GOV> wrote:
> 
> If the purpose of LitProg is to communicate what we have done, then this is a
> clear failure! Marcus has a web that is undecipherable to me, and even if I
> manage to figure out this problem, that simply postpones the pain until next
> time.
> 
> So, the question is, in general, how do we make webs (and other tex files)
> transportable?
> 
SGML? it is an ISO standard.
	-EdK
-- 
Ed Keith
Telephone: 1(703)370-5217      U.S. Snail: 4535 Taney Ave. #201
Internet : ed@efkport.kew.com              Alexandria, VA 22304
 
I am I, Don Quixote, The Lord of La Mancha . . .
 
From Chris Thu Jul 1 17:38:28 MDT 1993
Date: Thu, 1 Jul 93 17:38:28 MDT
From: Chris Flatters <cflatter@aoc.nrao.edu>
Reply-To: LitProg@SHSU.edu, cflatter@AOC.NRAO.EDU
To: LitProg@SHSU.edu
Subject: SGML (re: Fweb and C++)
 
> On Thu, 1 Jul 1993 10:36:15 -0400, "drs" <drs@bach.pdb.bnl.GOV> wrote:
> > 
> > If the purpose of LitProg is to communicate what we have done, then this is a
> > clear failure! Marcus has a web that is undecipherable to me, and even if I
> > manage to figure out this problem, that simply postpones the pain until next
> > time.
> > 
> > So, the question is, in general, how do we make webs (and other tex files)
> > transportable?
> > 
> SGML? it is an ISO standard.
> 
 
SGML is changing the playing field a little from TeX. SGML is a markup
language whereas TeX is a typesetting language. SGML describes the
structure of a document (eg. the following word is an identifier)
rather than its appearance (eg. the following word should appear in
italic type).
 
It would certainly make sense to have a WEB system that wove to SGML
since we should really be more concerned with the content of a woven
document than its appearance.  It might be even more useful if it
generated HTML (a version of SGML with hypertext extensions used for
the World-Wide Web project).
 
	Chris Flatters
	cflatter@nrao.edu
 
From norman@bellcore.com Thu Jul 01 20:55:38 -0400 1993
Date: Thu, 01 Jul 93 20:55:38 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
Subject: Re: Are modules necessary?
 
> Putting implementation issues aside -- what is the most convenient label
> of modules for using a Web?  
 
In my experience reading TeX and METAFONT, module numbers drove me
nuts.  I propose labelling each code chunk with the page number of its
first definition.  If more than one code chunk is defined on a page,
the page numbers should have lower-case letters appended; e.g., 17a,
17b, 17c. 
 
Norman
 
From Kayvan Fri Jul 2 00:06 PDT 1993
Date: Fri, 2 Jul 93 00:06 PDT
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
Subject: How to use several modes in Emacs when writing for NUWEB?
 
The only ideas I have are:
 
1. Look at yacc-mode and see how it does its context sensitive mode
   switching and do a lot of Elisp hacking to suit your Latex/perl
   purpose.
 
2. Bind perl-mode and latex-mode to some quick keystrokes. This is far
   easier than number 1.
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
 
From marcus@x4u.desy.de Fri Jul 2 13:37:30 +0200 1993
Date: Fri, 2 Jul 93 13:37:30 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, drs@bach.pdb.bnl.gov
Subject: Defense [was: Fweb and C++]
 
>>>>> On Thu, 1 Jul 1993 10:36:15 -0400, drs@bach.pdb.bnl.gov (drs) said:
 
|> Marcus and I decided that it probably is based on a difference in
|> fwebmac.sty (?) files between his system and mine.  His is hacked,
|> mine fresh from the box
 
Certainly I expressed myself wrongly in my answer -- the reason I
couldnt help is a) lack of time to go through my shelves to find my
collection of error reports, and b) that I did not get around to
install the released FWEB v1.30a [yes, it's a shame]. Thus I did not
feel like saying anything conclusive to Dave and merely proposed to
have a look at a different Web - the sample he mentions is only for
demonstration purposes [for WWW] to see what a nice job FWEB does
[thanks, JAK!] --
  Secondly, in February, I had problems with the NFSS extension of
LaTeX which JAK could not reproduce. Alas, I did not have time to look
into it -- but I assume there were no further reports to him.
 
|> If the purpose of LitProg is to communicate what we have done, then
|> this is a clear failure! Marcus has a web that is undecipherable to
|> me, and even if I manage to figure out this problem, that simply
|> postpones the pain until next time.
 
I agree with Dave on this point -- I am sure with the detailed error
report he will find help on this list ;-)
 
  I do NOT agree with JAK's opinion [recent message]: he undoubtedly
does not have the time to answer questions on [La]TeX and would have
to dismiss lots of justified newbie questions -- I plead for continued
'discussion' of what is trivial for experts and, once again, for some
folks to take the lead and FINALLY realize quick'n dirty FAQs for the
various processors around -- there's more than enough stuff in the
archives -- a FAQ is the place for this kind of discussion.
 
|> So, the question is, in general, how do we make webs (and other tex files)
|> transportable?
 
You may have noticed that inspite of extensive discussion earlier on
this list there is no tendency to converge towards a unified tool --
which I personally regret [though I am happy with FWEB].
 
|> ... I will have to convince mgmt as well as some skeptical programmers
|> that this is worthwhile, so I'd like some opinions on the general approach.
 
You are right, I hope, people will answer -- there is enough brain on
this net - my apologies for not helping myself again: gotta finish my Ph.D.
 
		Sympathetic,
		Marcus
 
From Dominique Fri Jul 02 14:15:31 +0200 1993
Date: Fri, 02 Jul 93 14:15:31 +0200
From: Dominique Dumont / GND <domi@petrus.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@PETRUS.GRENOBLE.HP.COM
To: LitProg@SHSU.edu
Subject: Use WEB in a business context (was Re: FWEB and C++ )
 
In message John Krommes writes :
> Regarding this latter issue, I feel that if a language such as Fortran or C
> is supported, use of a language-sensitive processor is far superior to an
> insensitive one, for the reasons mentioned recently by Bart Childs.
> However, it is clearly impractical to support all possible languages, so
> tools such as NUWEB certainly have their place.  I expect that the next
> release of FWEB will offer a ``no-language'' option, implemented as one of
> FWEB's multiple languages.  This is a straightforward extension of FWEB's
> meta-comment facilities and will enable one to move between language
> sensitivity and NUWEB-type output at will.
> 
 
Since I work in a company, I have other mandatory requirements to be able 
to use a Literate programming system : 
- the new method must be totally transparent ot others people in my group, so I
  must be able to tangle the web into a readable code with a certain amounts of
  comments (I don't know how much or if I can let TeX commands in the comments
  of the new generated source). May be I should also be able to mix classical
  program and literate ones.
- The code must be supportable by other people (others engineers, technical 
  marketing people) without a web system.
- I must be able to use it along with others software development tools :
  softbench, debuggers (I don't know yet what are the impacts for the web tools)
 
One future feature is to be able to generate man pages from the web along with
the code and the tangled doc.
 
Without that I will only be able to use noweb if I want to program in a literary
way.
 
From what I read on this list, people from university have different requirements
for their coding style compared to factory people. University guys tend to 
write monolithic programs which are seldom reused and are used by a few people.
(University guys can flame at will if I'm wrong :-) )
 
Whereas we write programs composed of several chunks written by different people 
with different coding styles (sometimes with differents languages). Furthermore
our programs are sold so they are used by a huge amount of people for several years
sometimes tens of years. So the program must be designed to be still upgradable 
in 10 or 20 years. Nobody knows what will be left of WEB systems in the next 
century, and we can't afford to support public domains tools , so we cannot take
the risk to write programs which depends on WEB to be upgraded. So at the end
of a developemnt I must provide a readable source codes with consistents comments.
(I don't think some LaTeX command here and there, or line numbers comments are a 
problem, The aim is that the program must be understandable without WEB tools).
 
In fact, what my boss says is that I can use WEB if it transparent to other people.
 
What do you, factory people, think of a WEB system in a business context ?
What are your requirements to be able to use it ?
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From Manuel Fri Jul 2 13:23:52 BST 1993
Date: Fri, 2 Jul 93 13:23:52 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re: nuweb and page numbers
 
preston@cs.rice.edu (Preston Briggs) writes on Thu, 1 Jul 93 11:21:42 CDT:
> 
> I think that pages numbers (or some sort) would be great.
> However, I can't see a clean way to add them to nuweb.
> The obvious approach is to use add a \label to each scrap
> and use \pageref wherever I need to refer to a scrap
> (in the crossreference lists and the indices).
> 
Pagenumbering can be done if you look closer in the latex.sty/doc docs.
The numbers for the scraps become very big, and it's quite undesireable
to look 100 pages back for a scrap that is referenced on the next third
chapter. To keep the numbers for the scraps small or local within
a specific chapter on should use the \thechapter label in addition
to the scrap numbering. An easy way to do this is to copy the
part of the figure environment of latex.sty/doc and include it
in the tangle process. So you will have `scrap 3.11' to denote a scrap
number 11 in chapter 3. If you use the article style option you simple
keep the usual scrap numbering. See the part (or parts `book/report' , 
`article' , and) `figure' for more details.
                  ~~~~~~
 
With this option you can easily maintain programs written in different 
programming languages. You can put all your C source in chapter X and
all your Pascal source in chapter Y.
 
> Unfortunately, I can't eliminate duplicates before running latex
> and I think the lists will look really ugly with lots of duplicate
> page numbers.  However, it's an easy experiment if someone wants to
> try it.
> 
To much pagenumbering makes your document not easy to read, but more 
complicated.
If you want to add a pagenumber you can easily use the \pageref
in addition to your \ref command if you've a \label mechanism in all
your scraps.
 
> An alternative that might work out would be to inspect the .aux file
> created by latex.  It'll have all the labels and page numbers from the
> last run of latex and therefore should be reasonably close.
 
That's what I mean. If you want to refer to an important part of your
scrap and detail it with a pagenumber you can do so, otherwise omit it.
 
Manuel
 
From vogelke@c-17igp.wpafb.af.mil Fri Jul 2 12:15:00 -0400 1993
Date: Fri, 2 Jul 93 12:15:00 -0400
From: vogelke@c-17igp.wpafb.af.mil (Contr Karl Vogel)
Reply-To: LitProg@SHSU.edu, vogelke@C-17IGP.WPAFB.AF.MIL
To: LitProg@SHSU.edu
Subject: SGML (re: Fweb and C++)
 
>> On Thu, 1 Jul 93 17:38:28 MDT, 
>> Chris Flatters <cflatter@aoc.nrao.edu> said:
 
Chris> It would certainly make sense to have a WEB system that wove to SGML
Chris> since we should really be more concerned with the content of a woven
Chris> document than its appearance.
 
       This definitely gets my vote.  The nicest thing about SGML is the
       fact that parsers for it are freely available.  I can write something
       to turn valid SGML into Texinfo or Troff a lot more easily than I can
       write something to manipulate (say) a given style of WEB code.
 
       The best thing about SGML is that it can be used to generate several
       representations of any document.  You can have a driver that reads an
       SGML document and generates output suitable for printing, or
       ready-to-compile code, or a hypertext representation of your program
       intended for easy browsing.
 
Chris> It might be even more useful if it generated HTML (a version of SGML
Chris> with hypertext extensions used for the World-Wide Web project).
 
       I have one minor quibble with this idea.  How stable is the HTML
       document definition?  It won't help us if the rules for creating an
       HTLM document are too fluid.
 
       We might be better off creating a document definition which is solely
       intended for literate programming types.  This way, we have more
       control over our own destiny; the HTML folks can do what they like,
       and it won't hurt us a bit.  I'm not saying that we couldn't borrow
       ideas from them; I just don't think we should tie our destiny to a
       style of document representation that's rooted in information
       retrieval rather than programming.
 
-- 
Karl Vogel			vogelke@c-17igp.wpafb.af.mil [134.136.19.253]
Control Data Systems, Inc.	ASC/YCOA, Wright-Patterson AFB, OH 45433
2970 Presidential Drive		513-255-7383 x4298	
Fairborn, OH 45324
 
A car is useless in New York, essential everywhere else.
The same with good manners.			--Ron "Asbestos" Dippold
 
From Eric Fri Jul 2 12:15:00 -0400 1993
Date: Fri, 2 Jul 93 12:15:00 -0400
From: Eric Landes <ericla@microsoft.com>
Reply-To: LitProg@SHSU.edu, ericla@MICROSOFT.COM
To: LITPROG@SHSU.edu
Subject: Microsoft Windows versions of FWEB 1.30a
 
I don't know if people on this list are interested, but I've built 
Microsoft Windows versions of
FWEB 1.30a.  They were built with Visual C++ as QuickWin applications, 
and work very
well when attached to the Tools menu of Visual C++.
 
If you want to do this yourself, all you need to do is add the 
following compiler switches:
 /Gx- /f- /Mq
and link with LLIBCEWQ.LIB instead of LLIBCE.LIB.  I also optimized for 
speed with /O2.
 
I can either email the binaries to interested parties, or if the demand 
is too great, I'll put
them on an FTP site.
 
Eric Landes
ericla@microsoft.com
 
From dentato@minerva.ing.uniroma1.it Fri Jul 2 17:48:13 +0100 1993
Date: Fri, 2 Jul 1993 17:48:13 +0100 (DFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
To: LitProg@SHSU.edu, ed@EFKPORT.KEW.COM
Subject: Re: Fweb and C++
 
 >> >> how do we make webs (and other tex files) transportable?
 
 >> SGML? it is an ISO standard.
 
 What is SGML? (OK, it's an ISO standard, but what's about?)
        ___ __
       //_/// \
      // \//__/    dentato@cadgroup.ing.uniroma1.it
     Remo Dentato
 
From George Fri Jul 02 12:15:02 CST 1993
Date: Fri, 02 Jul 1993 12:15:02 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: preston@cs.rice.edu
Subject: Nuweb 0.8 available at SHSU
 
On Thu, 1 Jul 93 20:24:41 CDT, Preston Briggs <preston@cs.rice.edu> posted:
> Here's a new version of nuweb (using noweb-style page numbering for the
> scraps).  If you could put it out for public consumption, I'd appreciate
> it.
> 
> I've called this version 0.8, hoping someday to progress to 1.0, with
> complete documentation.  Changes from previous versions include:
> 
> 	slightly improved typesetting in some odd corners.
> 
> 	a new command-line flag, -v (for verbose), which causes
> 	nuweb to write progress information to stdout.
> 
> 	I've removed calls to chmod() as being too system dependent.
> 
> 	I've cleaned up the C, adding several externs, statics, and
> 	a global.h file.
> 
> 	I've hopefully solved the problem of naming temporary files
> 	(using calls to tempnam()), though at least one tester has had
> 	to hack this area.
> 
> 	Most significantly, scraps are now uniformly referred to using
> 	a noweb-style page-numbering scheme.
> 
> There are a few other ideas people have sent along that didn't make it into
> this release.  They haven't been forgotten; hopefully, I'll get to them
> soon.
> 
> regards,
> Preston
 
Thanks for the update.  I have unpacked the files for ftp retrieval on
ftp.shsu.edu into tex-archive/web/nuweb/ (which is the nuweb entry on
SHSU's gopher server based at Niord.SHSU.edu). I've also placed the files
(as well as all other files -- samples, msdos, etc.) in
/pub/archive/web/nuweb at ftp.tex.ac.uk.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From George Fri Jul 02 13:00:23 CST 1993
Date: Fri, 02 Jul 1993 13:00:23 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: Where is SpiderWeb's webkernel.tex?
 
On Wed, 30 Jun 93 12:04:11 -0400, Norman Ramsey <norman@bellcore.com>
posted:
> Oops.  Mea culpa.  I include the missing file at the end of this message. 
> George, perhaps you would be kind enough either to pick it up here and park
> it in spiderweb/src, or to grab a new spiderweb.tar.Z from
> csservices.princeton.edu:pub?
 
Taken care of at ftp.shsu.edu (aka pip.shsu.edu).  I also updated the
pub/archive/web/spiderweb/... directory at ftp.tex.ac.uk while I was at it.
 
--George
 
From tfj@apusapus.demon.co.uk Fri Jul 02 21:01:42 GMT 1993
Date: Fri, 02 Jul 93 21:01:42 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: Re: re: Fweb and C++
 
In message <2c336624.efkport@efkport.kew.com> you write:
> On Thu, 1 Jul 1993 10:36:15 -0400, "drs" <drs@bach.pdb.bnl.GOV> wrote:
> > 
> > If the purpose of LitProg is to communicate what we have done, then this is a
> > clear failure! Marcus has a web that is undecipherable to me, and even if I
> > manage to figure out this problem, that simply postpones the pain until next
> > time.
 
> SGML? it is an ISO standard. 
 
Back in the days before the ISO 8879 (SGML) was published I was a member of
the British committee that participated in the work. For the technical
report on using SGML I had proposed that an example SGML DTD be written
which would allow WEB files to be analysed. I even volunteered to write
it.
 
My fellow committee members didn't see WEB as sophisticated enough---they
wanted a DTD for Z instead. Not being a Z expert I dropped the idea. Their
interest in Z was such that they didn't do anything either. On reflection I
wished that I had persevered with the WEB one. :-(
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From preston@cs.rice.edu Fri Jul 2 16:56:49 CDT 1993
Date: Fri, 2 Jul 93 16:56:49 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: mail address
 
I apologize for disturbing everyone; but...
I've got a mail message I can't reply to, from Bryan Oakley.
If you could send me mail with a better em-mail address
(hopefully not containing UUCP), I'll get back to you.
 
Preston
 
From j_mcarthur@BIX.com Fri Jul 02 22:55:42 -0400 1993
Date: Fri, 02 Jul 1993 22:55:42 -0400 (EDT)
From: j_mcarthur@BIX.com
Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
To: LitProg@SHSU.edu
Subject: SGML and TeX
 
>SGML is changing the playing field a little from TeX. SGML is a markup
>language whereas TeX is a typesetting language. SGML describes the
>structure of a document (eg. the following word is an identifier)
>rather than its appearance (eg. the following word should appear in
>italic type).
 
Just a few comments about SGML.  First, there are a lot of misconceptions
about SGML.  I know, I have had to learn a tremendous amount in the past
few weeks since I am now working on a massive SGML job.
 
TeX and SGML go together very nicely.  I am currently feeding raw
SGML files into TeX and typesetting them.  If are willing to write
some macros and play with catcodes you can relatively easilly typeset
SGML documents with TeX without the need for any pre-processor.
 
The much more serious problem with SGML is that it is almost impossible
to edit. Let me give you an idea.  This is from a real sgml document
that am printing via TeX:
 
<INGRDNTS ID="S2" NUMBER="2"><TITLE>HAZARDOUS INGREDIENTS
</TITLE><SUBSECT><TITLE>HAZARDOUS INGREDIENTS</TITLE><TABLE>
<TBLHEAD><TBLBODY><TBLCOLS><TBLCOL HALIGN="Justify"><TBLCOL
 HALIGN="Justify"><TBLCOL HALIGN="Justify"><TBLCOL
 HALIGN="Justify"></TBLCOLS><TBLROW><TBLCELL COLSTART="1"
 HALIGN="Center">Hazardous Components</TBLCELL><TBLCELL
 COLSTART="2" HALIGN="Center">OSHA PEL</TBLCELL><TBLCELL
 COLSTART="3" HALIGN="Center">ACGIH TLV</TBLCELL><TBLCELL
 COLSTART="4" HALIGN="Center">CAS Number</TBLCELL></TBLROW>
</TBLBODY></TBLHEAD><TBLBODY><TBLCOLS><TBLCOL HALIGN="Justify">
<TBLCOL HALIGN="Justify"><TBLCOL HALIGN="Justify"><TBLCOL
 HALIGN="Justify"></TBLCOLS><TBLROW><TBLCELL
 COLSTART="1">Calcium Carbonate</TBLCELL><TBLCELL
 COLSTART="2">3.75 mg/m<SUP>3</SUP> 1.4 mg/m<SUP>3</SUP> resp.
 dust</TBLCELL><TBLCELL
 COLSTART="3">10 mg/m<SUP>3</SUP></TBLCELL><TBLCELL COLSTART="4">1317-65-3
</TBLCELL></TBLROW><TBLROW><TBLCELL COLSTART="1">Pyrophyllite
</TBLCELL><TBLCELL COLSTART="2">50 mppcf</TBLCELL><TBLCELL
 COLSTART="3"></TBLCELL><TBLCELL COLSTART="4">12269-78-2
</TBLCELL></TBLROW><TBLROW><TBLCELL COLSTART="1">Muscovite
 (MICA)</TBLCELL><TBLCELL COLSTART="2">20 mppcf</TBLCELL>
<TBLCELL COLSTART="3"></TBLCELL><TBLCELL COLSTART="4">1318-94-1
</TBLCELL></TBLROW><TBLROW><TBLCELL COLSTART="1">Kaolinite
</TBLCELL><TBLCELL COLSTART="2">50 mppcf</TBLCELL><TBLCELL
 COLSTART="3">0.1 mg/m<SUP>3</SUP></TBLCELL><TBLCELL COLSTART="4">1332-58-7
</TBLCELL></TBLROW><TBLROW><TBLCELL COLSTART="1">Quartz (total)
</TBLCELL><TBLCELL COLSTART="2">30 mg/m<SUP>3</SUP> /(&percnt; quartz +2)
</TBLCELL><TBLCELL COLSTART="3">0.1 mg/m<SUP>3</SUP></TBLCELL><TBLCELL
 COLSTART="4">14808-60-7</TBLCELL></TBLROW></TBLBODY></TABLE>
</SUBSECT></INGRDNTS>
 
This is an extreem example.  Part of the problem is caused because
SGML does not normally break the file into separate lines.  It
is not unusual to run into a 200K SGML file without a single
line feed (or carridge return, or cr/lf, or carridge control, all
depending on what OS you are running under).  This breaks a lot
of tools (including TeX).
 
Another thing to realize is that it is possible to have commands
for italic, bold, and so on in an SGML file.  <ITALIC> is not
an uncommon tag.  Also the move verbose <EMPH TYPE="ITALIC"> is
also found.
 
Now the first example was a bit nasty because it had a table in
it.  So here is a second example, from the same document, that
is a bit easier to deal with:
 
<OTHER ID="S8" NUMBER="8"><TITLE>GENERAL CONTROL MEASURES
</TITLE><SUBSECT ID="S8-1"><TITLE>Ventilation</TITLE><PARA>None
 other than normal with ordinary use.</PARA></SUBSECT><SUBSECT
 ID="S8-2"><TITLE>Respiratory Protection</TITLE><PARA>None with
 ordinary use.  If prolonged exposure, wear a MSHA/NIOSH
 approved dust/pesticide respirator.  Avoid breathing dust.
</PARA></SUBSECT><SUBSECT ID="S8-3"><TITLE>Protective Gloves
</TITLE><PARA>None with ordinary use.  If handling spill, wear
 impervious gloves.</PARA></SUBSECT><SUBSECT ID="S8-4">
<TITLE>Eye Protection</TITLE><PARA>None with normal use.  Wear
 safety glasses with side shields or goggles if eye contact is
 possible.</PARA></SUBSECT><SUBSECT ID="S8-5"><TITLE>Other
 Protective Clothing and Equipment</TITLE><PARA>To avoid contact
 with skin, wear protective apparel during application.</PARA>
</SUBSECT></OTHER>
 
This is much more code intensive than TeX.  This is why SGML tools
try and and allow you to edit without the tags (Author/Editor for
example).
 
One final thought.  SGML can be viewed as a meta-markup-language.
You can define you own mark-up scheme in SGML if you are willing
to change the characterset (allowed in SGML) and so on.  I bet,
if you were seriously ambitious, you could almost write a DTD for
WEB (classic Pascal WEB).
 
    Jeffrey McArthur                  ATLIS Publishing
    phone: (301) 210-6655             12001 Indian Creek Court
    fax:   (301) 210-4999             Beltsville, MD  20705
    EMAIL: j_mcarthur@bix.com
 
From tfj@apusapus.demon.co.uk Sat Jul 03 11:47:00 GMT 1993
Date: Sat, 03 Jul 93 11:47:00 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: Re: SGML and TeX
 
In message <9307022255.memo.85394@BIX.com> you write:
> Just a few comments about SGML.  First, there are a lot of misconceptions
> about SGML.  I know, I have had to learn a tremendous amount in the past
> few weeks since I am now working on a massive SGML job.
 
SGML has always been plauged by this problem. During my stint in the
international standards work the problem was from the office people
(ODA/ODIF ISO 8613) who felt threatened tht SGML was encroaching upon their
remit. It doesn't in that SGML is aimed at high-end publishing where as
ODA/ODIF was aimed at the typical character-cell based office environment
(_personally_ I always felt that what ever the ODA crew were adding into
their architecture SGML already did and better. :-)
 
> The much more serious problem with SGML is that it is almost impossible
> to edit. Let me give you an idea.
 
That isn't really a problem with the Standard Generalized Markup
_Language_. If it were then one could make the same complaint about
programming languages, eg C, Pascal or even (dare I say it) Literate Code.
 
The work that Mike Cowlishaw (IBM) did for the OED project demonstrated
that an SGML oriented editing system ca be created and use with a very
complex document.
 
> ....Part of the problem is caused because
> SGML does not normally break the file into separate lines.
 
Again it does need to. Consider the output from TANGLE where there is the
same problem. If you automated text-generation then you will end up with
output that is impossible for human beings to read.
 
>  It
> is not unusual to run into a 200K SGML file without a single
> line feed (or carridge return, or cr/lf, or carridge control, all
> depending on what OS you are running under).  This breaks a lot
> of tools (including TeX).
 
I have received mail and news message which break my mailer/news-reader
that is not the fault of the message (which by the way didn't exceed the
minimum limits imposed by the appropriate RFCs) but rather laziness on the
part of the programmer. (I didn't really mean to insult DEK by that comment
:-)
 
> Another thing to realize is that it is possible to have commands
> for italic, bold, and so on in an SGML file.  <ITALIC> is not
> an uncommon tag.
 
Then its wrong.
>  Also the move verbose <EMPH TYPE="ITALIC"> is
> also found.
 
This is the purist-style and is indeed what the text of ISO 8879 mandates.
Not that it is possible to check for it.
 
> One final thought.  SGML can be viewed as a meta-markup-language.
> You can define you own mark-up scheme in SGML if you are willing
> to change the characterset (allowed in SGML) and so on.
 
SGML includes both a mechanism for specifying the structure of a document
(your meta-markup) AND how a document should be encoded so as to conform to
that structure. With public entity texts it is possible to create an SGML
that doesn't include the specific DTD being used though it must be
available when the document is processed.
 
>  I bet,
> if you were seriously ambitious, you could almost write a DTD for
> WEB (classic Pascal WEB).
 
I don't think that the task is that "ambitious". Nor do I think that it
need to be limited to classic Pascal WEB. Now I have to go off and prove it
dont I. ;-) 
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From Matthias Sat Jul 03 14:02:58 +0200 1993
Date: Sat, 03 Jul 1993 14:02:58 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Time for creating a newsgroup ?
 
Hello everybody,
 
Lately, I noticed that the number of messages on this mailing list has grown
considerably, which led me to think about whether it wouldn't make sense to
create a newsgroup for it.
 
Judging from the number of subscribers, there should be a good chance of
getting a sufficient majority for the creation of a group in the comp
hierarchy.
 
IMHO, a newsgroup has many advantages over a mailing list:
 
- Newsreaders are more effective at dealing with considerable numbers of
  messages than Mail readers by using techniques such as threading and 
  killfiles.
- Having a newsgroup would advertise literate programming to a wider audience.
- I personally prefer reading mail as soon as possible, while I read news at
  less frequent intervals, and I could imagine that others have similar
  preferences.
 
A disadvantage of newsgroups is certainly that not everybody who has mail can
read news. I think, tough, that this could be overcome by having a News <->
Mail gateway, as it is done for a few other groups.
 
As for the name of the group, I think that comp.programming.literate might be
appropriate.
 
What do others think about this idea?
 
Matthias
 
-----
Matthias Neeracher                                  neeri@iis.ee.ethz.ch
  "And that's why I am going to turn this world upside down, and make
   of it a fire so *bright* that someone real will notice"
                                -- Vernor Vinge, _Tatja Grimm's World_
 
From marcus@x4u.desy.de Sat Jul 3 14:28:46 +0200 1993
Date: Sat, 3 Jul 93 14:28:46 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, neeri@iis.ee.ethz.ch
Subject: Time for creating a newsgroup ?
 
>>>>> On Sat, 03 Jul 1993 14:02:58 +0200, Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch> said:
 
|> Lately, I noticed that the number of messages on this mailing list has grown
|> considerably, which led me to think about whether it wouldn't make sense to
|> create a newsgroup for it.
 
|> Judging from the number of subscribers, there should be a good chance of
|> getting a sufficient majority for the creation of a group in the comp
|> hierarchy.
 
|> As for the name of the group, I think that comp.programming.literate might be
|> appropriate.
 
|> What do others think about this idea?
 
I agree, especially because this would ease making contact between
people who only want to be helped with their specific tool -- the
wizards could concentrate on meta-topics. Though I think everyone
should be free to ask *any* question, I must admit that a long
discussion on the tool I am never going to use is difficult to take.
 
I offer to adapt the FWEB FAQ [after its update to v1.30a.....] which
I'm maintaining to the USEnet FAQ guidelines. It should also be mentioned
that the newsgroups are embedded in WWW already, which has a LitProg
page [ http://info.desy.de:80/pub/www/projects/LitProg.html ].
 
If there is sufficient interest, I'd like Matthias to explain the
procedere. The name is fine.
 
  --Marcus Speh
  --<marcus@x4u.desy.de>
 
From Cameron Sat Jul 3 15:29:10 -0500 1993
Date: Sat, 3 Jul 1993 15:29:10 -0500
From: Cameron Smith <cameron@symcom.math.uiuc.edu>
Reply-To: LitProg@SHSU.edu, cameron@SYMCOM.MATH.UIUC.EDU
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
I would *love* it if this group became a newsgroup.
 
I know that there are many who can receive email who can't get USENET,
but our beloved list administrator has already solved that problem for
the Info-TeX <-> comp.text.tex connection, so I can't imagine it would
be any harder for the LitProg <-> comp.programming.literate connection.
That would allow email support to continue for those who need it while
letting those who can use USENET have the advantages of that approach.
 
I used to post frequently to this group (when it first started up), but
now I have a hard time keeping up with it (I'm *much* busier than I was
a year ago), and the threading and archiving and searching facilities
that newsreaders typically offer would be a BIG advantage for me in
keeping up with the group and in finding old articles that I wanted to
refer to.
 
--Cameron Smith
  cameron@symcom.math.uiuc.edu
 
P.S. I just recently finished a very large TeX consulting project that
     involved literately documenting 1500 lines of TeX code and a few
     hundred lines of shell scripts, AWK programs, and other stuff.
     I used Mittelbach's doc.sty for the TeX stuff and Norm Ramsey's
     NOWEB (with many adjustments for personal preference) for the
     rest.  Both systems performed excellently.  I liked the line
     numbers and index in doc.sty; and I was happy to sacrifice the
     language-specific goodies in exchange for NOWEB's flexibility
     in allowing me to document any file of any kind.  Literate
     techniques made my job easier and the beautiful documentation
     made my client *VERY* happy!
 
From Thorbjoern Sat Jul 3 23:31:01 MET 1993
Date: Sat, 3 Jul 93 23:31:01 MET DST
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
Matthias Ulrich Neeracher
 
| Lately, I noticed that the number of messages on this mailing list has grown
| considerably, which led me to think about whether it wouldn't make sense to
| create a newsgroup for it.
 
I think it is a good idea.  Spreading the word is much more easy on the
news than on a subscription-based mailservice,  but I like the archive
facilities better of my mail reader, so I would probably use both mail
and news.
 
My recent request on the news [for Emacs stuff with a boring header] has
made three people ask about Nuweb and Literate programming, so if this
is an indication I think it is a good one.
 
| Judging from the number of subscribers, there should be a good chance of
| getting a sufficient majority for the creation of a group in the comp
| hierarchy.
 
What is the actual rules for this [I know -- it is probably in a FAQ]
but a summary would be nice.
 
| A disadvantage of newsgroups is certainly that not everybody who has mail can
| read news. I think, tough, that this could be overcome by having a News <->
| Mail gateway, as it is done for a few other groups.
 
Is this available on Niord, George?
 
| As for the name of the group, I think that comp.programming.literate might be
| appropriate.
 
Yes.
 
Regards,
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From Lee Sat Jul 3 22:26:09 EDT 1993
Date: Sat, 3 Jul 93 22:26:09 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, mckearney_s@bt-web.bt.co.uk
Subject: Re: Are modules necessary?
 
Stephen Mc Kearney writes:
 
> I have developed a WEB for Word system, based around the WORDWEB 
> developed elsewhere, that does almost everything most WEB systems do 
> including : cross-references, code indexes, find definition, etc.
 
As the author of the original (primitive) WORDWEB system, I 
would be interested in seeing what you came up with.
 
> Some people here have been using it and we have come to the conclusion 
> that the formal structure of Text Part - Code Part is unnecessary in 
> this WYSIWYG environment.  Having code chunks appear throughout the 
> text seems to lead to a slightly different style of programming.
 
> Does anyone else feel that the numbered module structure is more than 
> simply a carry over from the parsing of the source file in the 
> original WEB?  Cross-references can be handled using page numbers etc.
 
I agree.  My noweb style is quite different from my CWEB style.  I
rely on LaTeX for structuring noweb programs.  Each style has
something to recommend it, though.  It's a lot easier to find a
referenced chunk when the reference refers to a section rather than a
page (noweb's noxref generates page references;  I've experimented
with using \ref instead of \pageref, but unless each section is kept
very small, it's harder to deal with than the page numbers).
 
> Before someone goes on about how much better TeX is over Word, etc I 
> should say that if I had a free choice it would be TeX/LaTeX and in 
> my environment most people will not move away from WYSIWYG 
> environments.
 
You might be interested in my experiences at Tipton Cole + Co. using
WORDWEB.  A few people (who were diehard WYSIWYGers) started using
WORDWEB (including Tipton, the boss), but found that the advantages of
noweb/LaTeX far outweighed the advantages of the WYSIWYG world.  TCC
seems to be moving in the direction of a ``literate programming
shop,'' using noweb.  I'd be glad to put my boss in contact with your boss,
if you think it would help.
 
		-- Lee
 
From Lee Sat Jul 3 23:50:56 EDT 1993
Date: Sat, 3 Jul 93 23:50:56 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, domi@petrus.grenoble.hp.com
Subject: Re: Use WEB in a business context (was Re: FWEB and C++ )
 
Dominique Dumont writes:
 
>Since I work in a company, I have other mandatory requirements to be able 
>to use a Literate programming system : 
>- the new method must be totally transparent ot others people in my group, so I
>  must be able to tangle the web into a readable code with a certain amounts of
>  comments (I don't know how much or if I can let TeX commands in the comments
>  of the new generated source). May be I should also be able to mix classical
>  program and literate ones.
>- The code must be supportable by other people (others engineers, technical 
>  marketing people) without a web system.
>- I must be able to use it along with others software development tools :
>  softbench, debuggers (I don't know yet what are the impacts for the web tools)
 
I've just spent the best part of a year trying to introduce LP
techniques (via noweb) in a business environment.  noweb has the
"nountangle" tool to help meet your first criterion.  The second 2
have turned out not to be quite so important, as we have been
programming for Paradox, a system notoriously short of decent tools.
However, we have been able to use the ``standard'' Unix tools (awk,
grep, make, etc., in DOS versions) to ease software development
somewhat.
 
>One future feature is to be able to generate man pages from the web along with
>the code and the tangled doc.
 
We use a slightly modified manpage.sty file.  All our webs follow
pretty much the same structure (LaTeXish commands):
 
	\maketitle	% a title page followed by a copyright/version control info page
	\makecontents  % a table of contents
	\part{Interface}
		% manual pages go here
	\part{Implementation}
		% the web proper goes here
 
>Without that I will only be able to use noweb if I want to program in a literary
>way.
 
>From what I read on this list, people from university have different requirements
>for their coding style compared to factory people. University guys tend to 
>write monolithic programs which are seldom reused and are used by a few people.
>(University guys can flame at will if I'm wrong :-) )
 
I'm a university guy, but I understand what you're saying here.
 
>Whereas we write programs composed of several chunks written by different people 
>with different coding styles (sometimes with differents languages). Furthermore
>our programs are sold so they are used by a huge amount of people for several years
>sometimes tens of years. So the program must be designed to be still upgradable 
>in 10 or 20 years. Nobody knows what will be left of WEB systems in the next 
>century, and we can't afford to support public domains tools , so we cannot take
>the risk to write programs which depends on WEB to be upgraded. So at the end
>of a developemnt I must provide a readable source codes with consistents comments.
>(I don't think some LaTeX command here and there, or line numbers comments are a 
>problem, The aim is that the program must be understandable without WEB tools).
 
The people I've been working with are just starting on the LP
experiment, but seem committed to it.  noweb has 2 advantanges here:
(1) it's made up of several very simple tools that are quite easy to
maintain yourself (I speak from experience here -- I had to port noweb
to MS-DOS, which was surprisingly simple from the noweb side, although
a bit of a pain due to DOS restrictions -- I've found it quite easy to
to hack a new feature to noweb the few times I've needed to), and (2)
you can use nountangle to ``undo'' your webs into (more or less)
normally documented programs if the experiment fails.
 
>In fact, what my boss says is that I can use WEB if it transparent to other people.
 
What I did was just to use noweb for my stuff and pass the programs
around for comment.  I finally got one of my coworkers to try it as
well (a skeleton web and a one page summary of the necessary commands
-- @ and <<>> for noweb; \section (etc.), \em, and the special TeX
characters for LaTeX -- were all that was needed to get him started).
He was soon converted, and that got everyone else interested.  After a
brief fling with WinWordWEB, the shop seems to have settled on noweb.
It seems to have been a classic example of what Grace Hopper used to
refer to as ``the necessity of educating our bosses'' (and coworkers,
in this case).  LP seems to be one of those things that seem to be
more trouble than they're worth until you try them -- then you wonder
how you got along without them.  Anybody else remember the effort it
took to abandon your trusty line-oriented editors and use a screen
editor?
 
>What do you, factory people, think of a WEB system in a business context ?
>What are your requirements to be able to use it ?
 
I, too, would like to hear from ``factory people.''
 
		-- Lee
 
From Lee Sat Jul 3 23:57:33 EDT 1993
Date: Sat, 3 Jul 93 23:57:33 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, neeri@iis.ee.ethz.ch
Subject: Re: Time for creating a newsgroup ?
 
Matthias Neeracher has suggested that we set up a newsgroup to replace our
discussions via email.  Personally, I find newsgroups uncomfortable, and
quite enjoy the ``feel'' of an email discussion.  I vote to keep things as
they are.
 
		-- Lee
 
From Lee Sun Jul 4 0:37:49 EDT 1993
Date: Sun, 4 Jul 93 0:37:49 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, stevef@ttsi.tandem.com
Subject: Re: WYSIWYG WEB system?
 
Steve Farmer asks:
 
> Are any of these WYSIWYG WEB systems available through anonymous ftp? I
> understand that current word-processors are not ideal, but I think there
> is a lot of potential in WYSIWYG that I would like to explore.
 
The original WinWordWEB is available as WORDWEB.ZIP in the pub/leew
directory of bart.kean.edu.  I think it's available at some other
sites as well, but I don't recall wehere.  Bart is not really set up for
any large-scale ftp service; it's just the only machine I have access
to on which I can make stuff available to others.  If anyone knows of
another site for WinWordWEB, please let post a notice, as I'd prefer
to keep traffic down to a minimum on bart.
 
If Stephen McKearney will send me a floppy with his new version on it
in care of
 
	Computer Science Department
	Kean College of New Jersey
	Union, NJ   07083
 
I'll be glad to make it available as well (or, better still, I could
post it to the appropriate mirror site).
 
		-- Lee
 
From Ian Sun Jul 04 12:23:05 GMT 1993
Date: Sun, 04 Jul 93 12:23:05 GMT
From: Ian Cargill <ian@soliton.demon.co.uk>
Reply-To: LitProg@SHSU.edu, ian@soliton.demon.co.uk
To: LitProg@shsu.edu
Subject: Re: Time for creating a newsgroup ?
 
In message <CMM-RU.1.3.741758253.leew@pilot.njin.net> you write:
> Matthias Neeracher has suggested that we set up a newsgroup to replace our
> discussions via email.  Personally, I find newsgroups uncomfortable, and
> quite enjoy the ``feel'' of an email discussion.  I vote to keep things as
> they are.
> 
 
I vote for a newsgroup.  Why? well...
 
Personally, I find the 'feel' of a newsgroup discussion much the same 
as the 'feel' of an email discussion.  There is, I would admit, a
psychological aspect; a warm fuzzy feeling from belonging to a 
para-exclusive (?) community.
 
For me, however, the extra features of mail, *PARTICULARLY* threads,
are more important.  I also dislike having 'normal' mail swamped
by the mailing list stuff. 
 
 Ian Cargill         Email:  ian@soliton.demon.co.uk
 Phone:  +44 (0)372  375529 (Home),   +44 (0)71 510 7875 (Work)
-----------------------------------------------------------------
 C Users Group (UK): For Serious C & C++ Users (Mail for details)
 
From ae1181t@stnfor.ae.ge.com Sun Jul 4 09:56:21 -0400 1993
Date: Sun, 4 Jul 1993 09:56:21 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: WYSIWYG WEB system?
 
Why dont you put it on pip.shsu.edu  /incoming and drop a line to George and
he will put somewhere eveyone can access. It may already be there!
Osman
 
From vogelke@c-17igp.wpafb.af.mil Sun Jul 4 14:52:57 -0400 1993
Date: Sun, 4 Jul 93 14:52:57 -0400
From: vogelke@c-17igp.wpafb.af.mil (Contr Karl Vogel)
Reply-To: LitProg@SHSU.edu, vogelke@C-17IGP.WPAFB.AF.MIL
To: LitProg@SHSU.edu
Subject: Time for creating a newsgroup ?
 
>> On Sat, 3 Jul 93 23:31:01 MET DST, 
>> Thorbjoern Ravn Andersen <ravn@imada.ou.dk> said:
 
Thorbjoern> I think [creating a newsgroup] is a good idea.  Spreading the
Thorbjoern> word is much more easy on the news than on a subscription-based
Thorbjoern> mailservice, but I like the archive facilities better of my mail
Thorbjoern> reader, so I would probably use both mail and news.
 
	    I also like the idea of creating a newsgroup.  I use a program
	    called "pgnews" to read any new messages posted to several
	    different groups, and then place those messages into an
	    appropriately formatted mail file.  This way, I can just browse
	    the group using "nn" if I'm in a hurry, or I can look at
	    everything with my favorite mail handler if I have more time.
 
	    "pgnews" is written in PERL, and it works for sites that get
	    their news via NNTP.
 
-- 
Karl Vogel			vogelke@c-17igp.wpafb.af.mil [134.136.19.253]
Control Data Systems, Inc.	ASC/YCOA, Wright-Patterson AFB, OH 45433
2970 Presidential Drive		513-255-7383 x4298	
Fairborn, OH 45324
 
If you're not part of the solution, you're part of the precipitate.
						       --Steven Wright
 
From hetrick@phys.uva.nl Sun Jul 4 23:19:22 +0200 1993
Date: Sun, 4 Jul 1993 23:19:22 +0200
From: hetrick@phys.uva.nl (Jim Hetrick)
Reply-To: LitProg@SHSU.edu, hetrick@phys.uva.nl
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
Newsgroup vote:   yes!
 
<>------------------------------<*>---------------------------------<>
      James E. Hetrick             Institute for Theoretical Physics
     hetrick@phys.uva.nl                University of Amsterdam     
 
From se_haux@rcvie.co.at Mon Jul 5 09:58:01 +0200 1993
Date: Mon, 5 Jul 93 09:58:01 +0200
From: se_haux@rcvie.co.at (Michael Haux)
Reply-To: LitProg@SHSU.edu, se_haux@RCVIE.CO.AT
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
YES for a newsgroup!
 
               Michael Haux, Internet: Michael.Haux@rcvie.co.at
 
            V             Software Engineering Department
+-----------------------+ Alcatel Austria Forschungszentrum GmbH
|  A  L  C  A  T  E  L  | Ruthnergasse 1-7, A-1210 Vienna, Austria/EUROPE
+-----------------------+ Voice: +43 1 39 16 21 362    Fax:   +43 1 39 14 52       
 
From Eelco Mon Jul 05 10:08:08 +0200 1993
Date: Mon, 05 Jul 93 10:08:08 +0200
From: Eelco Visser <visser@fwi.uva.nl>
Reply-To: LitProg@SHSU.edu, visser@FWI.UVA.NL
To: LitProg@SHSU.edu, vogelke@C-17IGP.WPAFB.AF.MIL
Subject: Re: Time for creating a newsgroup ?
 
Unconditionally: yes
 
Eelco
 
From Joachim Mon Jul 5 12:36:23 +0100 1993
Date: Mon, 5 Jul 1993 12:36:23 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
Subject: Re: SGML and TeX
 
[This is a long response, sorry. I tried to cut it down, but I cannot
make it less text without loosing clarity.]
 
Jeffrey wrote:
> 
> >SGML is changing the playing field a little from TeX. SGML is a markup
> >language whereas TeX is a typesetting language. SGML describes the
> >structure of a document (eg. the following word is an identifier)
> >rather than its appearance (eg. the following word should appear in
> >italic type).
> 
> Just a few comments about SGML.  First, there are a lot of misconceptions
> about SGML.  I know, I have had to learn a tremendous amount in the past
> few weeks since I am now working on a massive SGML job.
 
Please, don't take this mail personally -- but it's my impression
that you have more to do. Your mail gives IMNSHO a completely wrong
presentation of SGML.
    In addition,
 
> TeX and SGML go together very nicely.  I am currently feeding raw
> SGML files into TeX and typesetting them.
 
Yes, that can be done for particular document types -- but it's really
not the ``canonical'' way. TeX isn't a programming language that's
really suited for this type of tasks.
 
Let me get a bit more structured, so that you can critizice me, too
;-): First I'll give an outline what SGML is. Then I'll attack your
statement that SGML documents are unreadable, both in principle and
with an example. At last I'll do a scetch of the `usual' connection
with SGML and TeX.
 
WHAT IS SGML?
 
SGML is an acronym, it stands for Standard Generalized Markup
Language. The important word herein to distinguish it from other
markup languages is ``Generalized''. We can distinguish four
categories of markup:
 
 1. presentational markup
	The document's structure is shown by laying out the content on
    the page/screen. This might seem trivial (introducing spaces and
    lines) and might be more (itemized lists, etc.) This is what I'm
    doing manually now...
 
 2. procedural markup
    	The text is interspersed with formatting commands, which
    explain how the document is to be formatted. (plain) TeX and
    [nt]roff are typical examples of this.
 
 3. generic or descriptive markup
    	The document is tagged to show its structure explicitely. The
    tags are defined externally. Scribe is the canonical example for
    this category. From its intent, LaTeX belongs here, too. But one
    has still the full access to the procedural facilities of TeX.
    (IMO the greatest strength and the greatest weakness of LaTeX.)
 
 4. generalized markup
    	The document is described on three levels, which build the
    parts of a complete document.
	The first level tells how the input will look like. It will
    describe the character set, what interpretations are associated
    with characters, how tags are created, etc. I.e., one explains the
    lexical conventions, how lexems to describe the document are built.
    	The second level defines the potential structure of the
    document. One explains explicitely which structural elements may
    occur and which relationships and attributes they have to another
    (consists-of, is-optional, etc.) I.e., one defines a grammar which
    explains the document structure.
    	The third level is the document's content, tagged according
    to the conventions introduced on level 1 and 2. This part is
    called document instance in SGML terminology.
 
SGML belongs to category 4. In so far as it contains a language to
**define** markup languages, it is more than ``yet another markup
language.'' That's the reason why it's called a meta-language by some
people. That's arguable, 'though I won't subscribe to this view -- we
describe full documents after all, and full documents have no
`meta'-ness whatsoever.
 
READABILITY OF DOCUMENT INSTANCES
 
Jeffrey presented horrible examples of SGML input. The problem here
is that one has to distinguish between two ways of working with SGML
documents: the ``wealthy way'' (with appropriate tools) and the
``poor man's way'' (by hand). If the example concerned the former way
it was simply wrong; if it concerned the latter, it was plain bad.
 
The wealthy way uses context-sensitive editors, embedded in author
systems. The author will (should ;-) never see the tagged text. As
somebody already noted, it's like not looking at the output of
TANGLE. So the readability of the internal [sic!] document
representation -- as presented by Jeffrey -- is not of any concern
here. The readability of the document as presented by the editor is
the point to ask for. And here you don't see that mess, you'll see a
nice presentation of your structure, with outlining possibilities and
all kind of things you dream of (querying for the contents of specific
elements and similar things).
 
The poor man's way uses a simple editor and types in the markup
declaration and the document instance. Then he or she will add
shortcuts which makes typing more easily. Tags can be ommitted from
the document instance, the SGML system will insert them for your
convenience. As a real life example, a document instance taken
(almost verbatim, minus the DTD and some ommitted text  declaration 
from a file here:
 
----------------
<itiman>
 
<headline>TUD/ITI
<name>sman
<chapter>1
<whatis>convert SGML itiman manual page to nroff man format
 
<synopsis>
<synline>sman [-esis] <em>file[.sgm]</>
</synopsis>
 
<description>
 
<mref>sman</> provides an easy way for converting manual pages in
SGML itiman format to nroff (conversion to TeXinfo is planned).
Either SUN and IBM/HP man package format is created automatically.
 
Two different kinds of document structures are supported: one for
command man pages that consist of sections like synopsis,
description, options, etc., and one for miscellaneous ones which only
consist of sections with arbitrary names.
 
For both, the text can contain markups for emphasized text,
description and option lists, verbatim mode, and more. A detailed
description of the markup can be found in the tutorial ``<em>How to
write a SGML itiman Manpage</em>''.
 
</description>
 
<options>
<optionlist>
   <option>     -esis
   <optiondesc> generate only the intermediate representation as created by 
		the sgmls frontend
</optionlist>
</options>
 
[...]
 
<seeAlso>
<mref>sgmls(1)</>, <mref>nroff(1)</>
</seeAlso>
 
</itiman>
----------------
 
To cite Jeffrey:
 
> The much more serious problem with SGML is that it is almost impossible
> to edit. Let me give you an idea.
 
I find the example above neither unreadable nor impossible to edit. My
idea is obviously different from yours -- the readers of this mail
should judge for themselves.
 
(I.e., the created nroff source:
 
----------------
.st "sman" 1 "TUD/ITI" \*(]W
.SH NAME
sman \- convert SGML manual page to nroff man format
.SH SYNOPSIS
.B sman [-esis] \fIfile[.sgm]\fR
.br
.SH DESCRIPTION
\fBsman\fR provides an easy way for converting manual pages in
SGML itiman format to nroff (conversion to TeXinfo is planned).
Either SUN and IBM/HP man package format is created automatically.
.PP
Two different kinds of document structures are supported: one for
command man pages that consist of sections like synopsis,
description, options, etc., and one for miscellaneous ones which only
consist of sections with arbitrary names.
.PP
For both, the text can contain markups for emphasized text,
description and option lists, verbatim mode, and more. A detailed
description of the markup can be found in the tutorial ``\fIHow to
write a SGML itiman Manpage\fR''.
.SH OPTIONS
.TP
.B      -esis
generate only the intermediate representation as created by
the sgmls frontend
----------------
 
[that's only a partly extraction] is IMHO much more unreadable...)
 
PROCESSING SGML DOCUMENTS  OR  _THE CONNECTION TO TeX_
 
> If are willing to write
> some macros and play with catcodes you can relatively easilly typeset
> SGML documents with TeX without the need for any pre-processor.
 
The pre-processor -- usually called SGML parser -- is exactly the tool
which makes SGML so valuable. It delivers a canonical form of the
document instance, where all ommitted tags and all shortcuts are
expanded. It checks the validity of the markup, i.e., one is sure
afterwards that the document is correctly tagged. Therefore it is easy
to transform this now into valid TeX markup.
    To program this validation and this `normalizing' in TeX itself
is a nightmare. (So much about the statement of Dominique that
companies are more concerned about maintainance, modularity, and the
ability to support it by other people, than universities. :-) That it
is doable, doesn't mean this work is well invested. (IMO, of course. But
I'm programming in TeX for 11 years now, and know its limitations
quite well.)
 
If you have enough money and work under UNIX systems -- have a look
at the SGML Publisher of Arbortext. (I have no connection to this
company except knowing a few people there personally.) It uses an
extended version of TeX as the publishing engine to SGML documents.
It's a great piece of software for professional document preparation.
Especially the table and math support is great (where traditionally
SGML systems were weak).
 
Author/Editor -- mentioned from Jeffrey already -- is a nice system.
 
DynaText from Electronic Book Technologies is often mentioned as
outstanding, 'though I hadn't the chance to look at it yet.
 
On the freely distributable (poor man's ;-) side: There are some
converters available, most notably gf and Format. A large archive of
freely distributable material is accessible by anonymous ftp at
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/text/sgml
 
In the subdir documentation/ there's also the c.t.sgml FAQ and the
famous SGML bibliography of Robin Cover.
 
Well, in principle -- currently non-European hosts cannot reach
Germany over the Internet. And a GB disk of our ftp server did crash
this morning -- we're closed until we have installed a new disk and
the backup. But regular business should be back at the end of the week.
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Joachim Mon Jul 5 12:36:23 +0100 1993
Date: Mon, 5 Jul 1993 12:36:23 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
Subject: Re: SGML and TeX
 
[This is a long response, sorry. I tried to cut it down, but I cannot
make it less text without loosing clarity.]
 
Jeffrey wrote:
> 
> >SGML is changing the playing field a little from TeX. SGML is a markup
> >language whereas TeX is a typesetting language. SGML describes the
> >structure of a document (eg. the following word is an identifier)
> >rather than its appearance (eg. the following word should appear in
> >italic type).
> 
> Just a few comments about SGML.  First, there are a lot of misconceptions
> about SGML.  I know, I have had to learn a tremendous amount in the past
> few weeks since I am now working on a massive SGML job.
 
Please, don't take this mail personally -- but it's my impression
that you have more to do. Your mail gives IMNSHO a completely wrong
presentation of SGML.
    In addition,
 
> TeX and SGML go together very nicely.  I am currently feeding raw
> SGML files into TeX and typesetting them.
 
Yes, that can be done for particular document types -- but it's really
not the ``canonical'' way. TeX isn't a programming language that's
really suited for this type of tasks.
 
Let me get a bit more structured, so that you can critizice me, too
;-): First I'll give an outline what SGML is. Then I'll attack your
statement that SGML documents are unreadable, both in principle and
with an example. At last I'll do a scetch of the `usual' connection
with SGML and TeX.
 
WHAT IS SGML?
 
SGML is an acronym, it stands for Standard Generalized Markup
Language. The important word herein to distinguish it from other
markup languages is ``Generalized''. We can distinguish four
categories of markup:
 
 1. presentational markup
	The document's structure is shown by laying out the content on
    the page/screen. This might seem trivial (introducing spaces and
    lines) and might be more (itemized lists, etc.) This is what I'm
    doing manually now...
 
 2. procedural markup
    	The text is interspersed with formatting commands, which
    explain how the document is to be formatted. (plain) TeX and
    [nt]roff are typical examples of this.
 
 3. generic or descriptive markup
    	The document is tagged to show its structure explicitely. The
    tags are defined externally. Scribe is the canonical example for
    this category. From its intent, LaTeX belongs here, too. But one
    has still the full access to the procedural facilities of TeX.
    (IMO the greatest strength and the greatest weakness of LaTeX.)
 
 4. generalized markup
    	The document is described on three levels, which build the
    parts of a complete document.
	The first level tells how the input will look like. It will
    describe the character set, what interpretations are associated
    with characters, how tags are created, etc. I.e., one explains the
    lexical conventions, how lexems to describe the document are built.
    	The second level defines the potential structure of the
    document. One explains explicitely which structural elements may
    occur and which relationships and attributes they have to another
    (consists-of, is-optional, etc.) I.e., one defines a grammar which
    explains the document structure.
    	The third level is the document's content, tagged according
    to the conventions introduced on level 1 and 2. This part is
    called document instance in SGML terminology.
 
SGML belongs to category 4. In so far as it contains a language to
**define** markup languages, it is more than ``yet another markup
language.'' That's the reason why it's called a meta-language by some
people. That's arguable, 'though I won't subscribe to this view -- we
describe full documents after all, and full documents have no
`meta'-ness whatsoever.
 
READABILITY OF DOCUMENT INSTANCES
 
Jeffrey presented horrible examples of SGML input. The problem here
is that one has to distinguish between two ways of working with SGML
documents: the ``wealthy way'' (with appropriate tools) and the
``poor man's way'' (by hand). If the example concerned the former way
it was simply wrong; if it concerned the latter, it was plain bad.
 
The wealthy way uses context-sensitive editors, embedded in author
systems. The author will (should ;-) never see the tagged text. As
somebody already noted, it's like not looking at the output of
TANGLE. So the readability of the internal [sic!] document
representation -- as presented by Jeffrey -- is not of any concern
here. The readability of the document as presented by the editor is
the point to ask for. And here you don't see that mess, you'll see a
nice presentation of your structure, with outlining possibilities and
all kind of things you dream of (querying for the contents of specific
elements and similar things).
 
The poor man's way uses a simple editor and types in the markup
declaration and the document instance. Then he or she will add
shortcuts which makes typing more easily. Tags can be ommitted from
the document instance, the SGML system will insert them for your
convenience. As a real life example, a document instance taken
(almost verbatim, minus the DTD and some ommitted text  declaration 
from a file here:
 
----------------
<itiman>
 
<headline>TUD/ITI
<name>sman
<chapter>1
<whatis>convert SGML itiman manual page to nroff man format
 
<synopsis>
<synline>sman [-esis] <em>file[.sgm]</>
</synopsis>
 
<description>
 
<mref>sman</> provides an easy way for converting manual pages in
SGML itiman format to nroff (conversion to TeXinfo is planned).
Either SUN and IBM/HP man package format is created automatically.
 
Two different kinds of document structures are supported: one for
command man pages that consist of sections like synopsis,
description, options, etc., and one for miscellaneous ones which only
consist of sections with arbitrary names.
 
For both, the text can contain markups for emphasized text,
description and option lists, verbatim mode, and more. A detailed
description of the markup can be found in the tutorial ``<em>How to
write a SGML itiman Manpage</em>''.
 
</description>
 
<options>
<optionlist>
   <option>     -esis
   <optiondesc> generate only the intermediate representation as created by 
		the sgmls frontend
</optionlist>
</options>
 
[...]
 
<seeAlso>
<mref>sgmls(1)</>, <mref>nroff(1)</>
</seeAlso>
 
</itiman>
----------------
 
To cite Jeffrey:
 
> The much more serious problem with SGML is that it is almost impossible
> to edit. Let me give you an idea.
 
I find the example above neither unreadable nor impossible to edit. My
idea is obviously different from yours -- the readers of this mail
should judge for themselves.
 
(I.e., the created nroff source:
 
----------------
.st "sman" 1 "TUD/ITI" \*(]W
.SH NAME
sman \- convert SGML manual page to nroff man format
.SH SYNOPSIS
.B sman [-esis] \fIfile[.sgm]\fR
.br
.SH DESCRIPTION
\fBsman\fR provides an easy way for converting manual pages in
SGML itiman format to nroff (conversion to TeXinfo is planned).
Either SUN and IBM/HP man package format is created automatically.
.PP
Two different kinds of document structures are supported: one for
command man pages that consist of sections like synopsis,
description, options, etc., and one for miscellaneous ones which only
consist of sections with arbitrary names.
.PP
For both, the text can contain markups for emphasized text,
description and option lists, verbatim mode, and more. A detailed
description of the markup can be found in the tutorial ``\fIHow to
write a SGML itiman Manpage\fR''.
.SH OPTIONS
.TP
.B      -esis
generate only the intermediate representation as created by
the sgmls frontend
----------------
 
[that's only a partly extraction] is IMHO much more unreadable...)
 
PROCESSING SGML DOCUMENTS  OR  _THE CONNECTION TO TeX_
 
> If are willing to write
> some macros and play with catcodes you can relatively easilly typeset
> SGML documents with TeX without the need for any pre-processor.
 
The pre-processor -- usually called SGML parser -- is exactly the tool
which makes SGML so valuable. It delivers a canonical form of the
document instance, where all ommitted tags and all shortcuts are
expanded. It checks the validity of the markup, i.e., one is sure
afterwards that the document is correctly tagged. Therefore it is easy
to transform this now into valid TeX markup.
    To program this validation and this `normalizing' in TeX itself
is a nightmare. (So much about the statement of Dominique that
companies are more concerned about maintainance, modularity, and the
ability to support it by other people, than universities. :-) That it
is doable, doesn't mean this work is well invested. (IMO, of course. But
I'm programming in TeX for 11 years now, and know its limitations
quite well.)
 
If you have enough money and work under UNIX systems -- have a look
at the SGML Publisher of Arbortext. (I have no connection to this
company except knowing a few people there personally.) It uses an
extended version of TeX as the publishing engine to SGML documents.
It's a great piece of software for professional document preparation.
Especially the table and math support is great (where traditionally
SGML systems were weak).
 
Author/Editor -- mentioned from Jeffrey already -- is a nice system.
 
DynaText from Electronic Book Technologies is often mentioned as
outstanding, 'though I hadn't the chance to look at it yet.
 
On the freely distributable (poor man's ;-) side: There are some
converters available, most notably gf and Format. A large archive of
freely distributable material is accessible by anonymous ftp at
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/text/sgml
 
In the subdir documentation/ there's also the c.t.sgml FAQ and the
famous SGML bibliography of Robin Cover.
 
Well, in principle -- currently non-European hosts cannot reach
Germany over the Internet. And a GB disk of our ftp server did crash
this morning -- we're closed until we have installed a new disk and
the backup. But regular business should be back at the end of the week.
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Joachim Mon Jul 5 13:15:58 +0100 1993
Date: Mon, 5 Jul 1993 13:15:58 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu, WAGNER@CSEARN.BITNET
Subject: Re: CWEB for LaTeX?
 
You wrote:
> 
> Several days ago I saw an announcement of LaTeX support in CWEB. [...]
> I probably forgot the name of the Darmstadt ftp site (my four attempts
> failed due to unknown host). Can someone help me to find the correct site?
 
I don't think you forgot it. Due to an organizational problem Germany
is cut off from the Internet at the moment. Connectivity should be
back at the end of the week (at least, I was told so :-).
 
Then you'll find cweb.sty in
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/c.c++
	file cweb-sty-<version>.tar.Z
 
I might switch to .gz (ie, gzip instead of compress) in the next release.
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Joachim Mon Jul 5 13:17:32 +0100 1993
Date: Mon, 5 Jul 1993 13:17:32 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
I would certainly vote in favor of a newsgroup.
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From George Mon Jul 05 15:01:58 CST 1993
Date: Mon, 05 Jul 1993 15:01:58 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: WYSIWYG WEB system?
 
On Sun, 4 Jul 93 0:37:49 EDT, Lee Wittenberg <leew@pilot.njin.net> posted:
> > Are any of these WYSIWYG WEB systems available through anonymous ftp? I
> > understand that current word-processors are not ideal, but I think there
> > is a lot of potential in WYSIWYG that I would like to explore.
>
> The original WinWordWEB is available as WORDWEB.ZIP in the pub/leew
> directory of bart.kean.edu.  I think it's available at some other sites as
> well, but I don't recall wehere.  Bart is not really set up for any
> large-scale ftp service; it's just the only machine I have access to on
> which I can make stuff available to others.  If anyone knows of another
> site for WinWordWEB, please let post a notice, as I'd prefer to keep
> traffic down to a minimum on bart.
 
I have it for ftp, mail, and gopher use on Niord (just added the gopher --
sorry for the prior omission).
 
Via e-mail:
 SENDME WORDWEB
in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu)
will get a UUENCODEd ZIP archive.
 
Anonymous ftp:
Niord.SHSU.edu:[FILESERV.WORDWEB]
 
Gopher:
Niord.SHSU.edu (port 70)
  TeX-related Materials/
    Literate Programming Library/
      WinWordWEB (WORDWEB)/
 
Will see about placement for ftp on ftp.shsu.edu -- but it's definitely on
Niord now.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Steve Tue Jul 06 23:15:59 +1000 1993
Date: Tue, 06 Jul 1993 23:15:59 +1000
From: Steve Avery <stevea@vast.unsw.edu.au>
Reply-To: LitProg@SHSU.edu, stevea@VAST.UNSW.EDU.AU
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Time for creating a newsgroup ?
 
	Lee votes no on the newsgroup proposal.  I tend to agree. From
previous experience of lists that have gone to newsgroups, the signal to
noise ratio tends to increase by at least an order of magnitude. The
only way around this is to have a moderated group, and I wouldn't wish
that task on anyone.
	Another problem which I have seen on some newsgroups, and which
may occur on the proposed newsgroup, is that people resent a lot of
traffic coming from a small group of people (the "in crowd" so to
speak). As that seems to be the case on this list, it is likely to
remain the case in a newsgroup, and the flamage which may result may
drive these people away. Just a pessimistic thought.
	I like a mailing list. It makes it easier to reply to people
without incurring the wrath of a larger audience...
 
	cheers
	-steve
 
From gafter@mri.com Tue Jul 06 08:25:26 -0700 1993
Date: Tue, 06 Jul 93 08:25:26 -0700
From: gafter@mri.com
Reply-To: LitProg@SHSU.edu, gafter@mri.com (Neal M Gafter)
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: Re: Time for creating a newsgroup ?
 
I agree and would support the creation of such a newsgroup.
 
Regards,
Neal
 
From Jim Tue Jul 6 08:54:49 -0700 1993
Date: Tue, 6 Jul 1993 08:54:49 -0700 (PDT)
From: Jim Flanagan <flanagan@amath.washington.edu>
Reply-To: LitProg@SHSU.edu, flanagan@AMATH.WASHINGTON.EDU
To: LitProg@SHSU.edu, stevea@vast.unsw.edu.au
Subject: Re: Time for creating a newsgroup ?
 
  Discussions of signal to noise ratio in mailing lists tend to degrade same.
 
  --Jim
 
From fulling@sarastro.math.tamu.edu Tue Jul 6 10:58:34 CDT 1993
Date: Tue, 6 Jul 93 10:58:34 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu, fulling@SARASTRO.MATH.TAMU.EDU
To: LitProg@shsu.edu
Subject: Re:Are modules necessary?
 
mckearney_s@BT-WEB.BT.CO.UK writes:
 
>As for modules etc. the code we are producing does not seem to need
>numbering of modules and when you abandon numbering you seem to end up
>with something closer to a 'book'.  I think this is because the
>numbered module idea seems to set you thinking afresh for each module
>while without numbers the document feels more like a flowing
>description.  I get this feeling from most LP programs I have read
>that have been published.
 
It occurred to me that this difference in style and taste is related to
the difference in the way mathematicians, as opposed to mathematical
scientists, write papers and books.  Hard-core mathematics is written
in little chunks, often numbered, and always labeled "Definition",
"Theorem", "Proof", "Example", etc.  Theoretical physicists write
ordinary, discursive, stream-of-consciousness prose frequently
interrupted by displayed equations.
 
This difference has something to do with subject matter [How often does
a physicist genuinely prove a theorem? :-) ] but it also has a lot to
do with habit, tradition, and taste.  Being raised as a physicist, I
have to make a conscious effort to remind myself to write in the
mathematical style; but I certainly recognize its advantages in certain
circumstances.
 
To my mind, one of the advantages of the modularized LitProg paradigm
is precisely that it "sets you thinking afresh" by isolating each main
idea or task in a separate piece, while also showing how that piece
plugs into the larger structure.  But, just as in my physics-oriented
papers, there may be circumstances where the "flowing description" is
more appropriate.
 
				       Steve Fulling
 
From wald@theory.lcs.mit.edu Tue Jul 06 12:03:56 EDT 1993
Date: Tue, 06 Jul 93 12:03:56 EDT
From: wald@theory.lcs.mit.edu (David Wald)
Reply-To: LitProg@SHSU.edu, wald@THEORY.LCS.MIT.EDU
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
In <9307032131.AA13119@imada.ou.dk> Thorbjoern Ravn Andersen
<ravn@imada.ou.dk> writes:
>
>Matthias Ulrich Neeracher
>| Judging from the number of subscribers, there should be a good
>| chance of getting a sufficient majority for the creation of a group
>| in the comp hierarchy.
>
>What is the actual rules for this [I know -- it is probably in a FAQ]
>but a summary would be nice.
 
Here's a brief summary of the newsgroup creation process.  The full
guidelines are available by ftp and mail server from rtfm.mit.edu, in
pub/usenet/news.announce.newusers.
 
1) A request for discussion, including the proposed name and charter
   of the group is posted on news.announce.newgroups and any other
   relevant groups.
2) Discussion ensues on news.groups, during which people will make
   suggestions about the charter, the name, and the appropriateness of
   the proposed newsgroup, as well as the ancestry and personal habits
   of the proponents.
3) If/when discussion settles down, and a consensus has been reached
   on the name and charter, a call for votes is posted on
   news.announce.newgroups.
4) At the end of the voting period (21-31 days), the ballots are
   counted.  The group passes if it has a 2/3 majority of yes-votes
   over no-votes as well as 100 more yes-votes than no-votes.
5) If the group passes, then, if there are no serious procedural
   objections after a 5-day waiting period, the group is created.
 
-David
 
From ae1181t@stnfor.ae.ge.com Tue Jul 6 13:29:47 -0400 1993
Date: Tue, 6 Jul 1993 13:29:47 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu
Subject: Time for creating a newsgroup ?
 
I dont care if people who cannot access news (like me) are hooked in
somehow through the mail system.
Osman
 
From iapa!ctrbdo@mailhost.ecn.uoknor.edu Tue Jul 6 13:35:26 CDT 1993
Date: Tue, 6 Jul 93 13:35:26 CDT
From: iapa!ctrbdo@mailhost.ecn.uoknor.edu (bryan d oakley)
Reply-To: LitProg@SHSU.edu, iapa!ctrbdo@MAILHOST.ECN.UOKNOR.EDU
To: LitProg@SHSU.edu
Subject: standard web front end, texinfo web, et. al
 
===> topic 1: web front end
 
I've been looking into literate programming in general, web systems in
particular.  An amazing source of confusion is the fact that there are
SO many different web systems, and they all look quite similar from
the source code perspective (you are in a *web* of twisty passages,
all different).  While testing these out, it became easy to forget
which version of a file was designed for a particular web.  I invision
the problem of getting public domain webs and not knowing which web to
run. 
 
Question:  has anyone ever given thought to (or be willing to
volunteer to write) a web front-end and set of conventions such that I
could enter 'web filename', and 'web' would execute fweb, cweb, nuweb,
etc. depending on the contents of 'filename'.  Perhaps get the various
webs to agree on a standard macro specifying what options to run (ala'
shell scripts and '#!/bin/sh').  
 
Perhaps it is not worth the effort...
 
===> topic 2: texinfo web
 
Is there a web system which generates texinfo files instead of TeX /
LaTeX?  Since texinfo can be used to create online documentation in
addition to printed documentation, it looks like it would be real
handy.
 
===> topic 3 WYSIWYG webs
 
Some folks have mentioned WYSIWYG webs.  At first blush it sounds like
a great idea.  However, when debugging a web file using a source
browser I generally like to see the web source, not the generated .c,
etc. source, and I like the compiler to complain by giving line
numbers in reference to the orignal web file as well.  If the file is
WYSIWYG, it seems to me that most (all?) compilers and debuggers would
choke on the WYSIWYG stuff.  Given all that, is there a FrameMaker web
out there somewhere?
 
... just a few stray thoughts by a web neophyte...
 
---------------------------------------------------------------------
Instrument Approach Procedures Automation             DOT/FAA/AMI-230
---------------------------------------------------------------------
Bryan D. Oakley                   ctrbdo%iapa@mailhost.ecn.uoknor.edu
KENROB and Associates, Inc.              voice: (405) 954-7176 (work)
5909 NW Expwy Suite 209                         (405) 366-6248 (home)
Oklahoma City, Ok.  73132            
 
From Silvio Tue Jul 06 12:51:14 -0700 1993
Date: Tue, 06 Jul 93 12:51:14 -0700
From: Silvio Levy <levy@math.berkeley.edu>
Reply-To: LitProg@SHSU.edu, levy@MATH.BERKELEY.EDU
To: LitProg@shsu.edu
Subject: Re: Time for creating a newsgroup ?
 
This discussion itself is a good indication that we need to switch to
a newsgroup.  There have been over 30 posts -- it wish I were able to
kill the thread.
 
Silvio
 
From Matthias Wed Jul 07 00:36:18 +0200 1993
Date: Wed, 07 Jul 1993 00:36:18 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
Silvio Levy writes:
>This discussion itself is a good indication that we need to switch to
>a newsgroup.  There have been over 30 posts -- it wish I were able to
>kill the thread.
 
I apologize for having generated so much traffic, and I would suggest that
further articles on this subject be addressed directly to me and be kept off
this list, unless there is substantially more discussion contained than just "I
am for/against creating a newsgroup". I *would*, however, like to hear from as
many people as possible about their opinions.
 
The email I have received so far was predominantly in favour of creating a
newsgroup, although a few important contributors to this list were opposed to
it. Based on this feedback, I feel encouraged to go ahead and try writing a
draft Request for Discussion (RFD), which I will post to this list in a week or
so. I am aware that I am by no means the ultimate authority on Literate
Programming, but a few knowledgeable people have agreed to work with me
"offline", and I hope that with their help I can produce a decent document to
turn loose on the net community.
 
Someone else has already posted the rules for a newsgroup creation, and I just
would like to add that there are slightly more than 300 subscribers to this
list, which means that it shouldn't be too hard to succeed in a vote provided
there is sufficient interest within the list itself.
 
I wish you less traffic and happy weaving (and wordmincing, or whatever the
WORDWEB users do)
 
Matthias
 
-----
Matthias Neeracher                                      neeri@iis.ee.ethz.ch
 "Neeracher can and no doubt will perform the usual cheerleader duties."
              -- ataylor@nmsu.edu in <ATAYLOR.92Dec8135851@gauss.nmsu.edu>
 
From J_Hamer@cs.aukuni.ac.nz Tue Jul 6 23:39:00 BST 1993
Date: Tue, 6 Jul 93 23:39:00 BST
From: J_Hamer@cs.aukuni.ac.nz (John Hamer)
Reply-To: LitProg@SHSU.edu, J_Hamer@CS.AUKUNI.AC.NZ
To: LitProg@SHSU.edu, iapa!ctrbdo@MAILHOST.ECN.UOKNOR.EDU
Subject: Re: standard web front end, texinfo web, et. al
 
>Bryan D. Oakley writes:
>...
>===> topic 2: texinfo web
>
>Is there a web system which generates texinfo files instead of TeX /
>LaTeX?  Since texinfo can be used to create online documentation in
>addition to printed documentation, it looks like it would be real
>handy.
 
The Glasgow Literate Programming System generates GNU Emacs .info (and
LaTeX) documents from a LaTeX-like input file.   You could find out more
from Will Partain (partain@dcs.glasgow.ac.uk).
 
-- John Hamer                           Email: J_Hamer@cs.aukuni.ac.nz
-- Department of Computer Science       Phone: +64 9 3737 599 x 8758
-- University of Auckland               Fax:   +64 9 3737 453
-- Private Bag 92019, Auckland, New Zealand.
 
From Manuel Tue Jul 6 23:39:00 BST 1993
Date: Tue, 6 Jul 93 23:39:00 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@shsu.edu, LitProg@SHSU.edu, levy@MATH.BERKELEY.EDU
Subject: Re: Time for creating a newsgroup ?
 
> 
> This discussion itself is a good indication that we need to switch to
> a newsgroup.  There have been over 30 posts -- it wish I were able to
> kill the thread.
> 
 
Why we don't assign someone to collect all the votes, sending them
directlty to him/her and not to the list?!
 
And I'll give my vote...
 
Manuel
 
From Manuel Tue Jul 6 23:39:00 BST 1993
Date: Tue, 6 Jul 93 23:39:00 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@shsu.edu, LitProg@SHSU.edu, levy@MATH.BERKELEY.EDU
Subject: Re: Time for creating a newsgroup ?
 
> 
> This discussion itself is a good indication that we need to switch to
> a newsgroup.  There have been over 30 posts -- it wish I were able to
> kill the thread.
> 
 
Why we don't assign someone to collect all the votes, sending them
directlty to him/her and not to the list?!
 
And I'll give my vote...
 
Manuel
 
From j_mcarthur@BIX.com Wed Jul 07 02:26:57 -0400 1993
Date: Wed, 07 Jul 1993 02:26:57 -0400 (EDT)
From: j_mcarthur@BIX.com
Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
To: LitProg@SHSU.edu
Subject: RE:  SGML and TeX
 
Let me respond to a few points Joachim raised.
 
>... TeX isn't a programming language that's
>really suited for this type of tasks.
 
Actually I find TeX to be extreemly well suited for this task.
It is much better than any alternative I can find.
 
Let me give you a bit of history about the data I presented.
The data was given to us in this fashion.  We received over 5000
separate SGML files.  Each of them coded this way.  Only 10% of the
files parsed.  This job has been a nightmare.  I have had to
work for several weeks just trying to get the data to parse and
resemble something reasonable.  (To give you an idea, as a parting
shot the previous contractor replaced all the occurances of "oc" in
all the files with the hex character A1 followed by an uppercase C.)
 
Your arguments are fine if you are working with rational people who
present you rational data.  We are not.  We received data that has
MANY problems.  Including entire sections miss-coded and so on.
 
This is inspite of the problem that the original DTD was very, very
sloppy.  We have done a lot of work re-writing the DTD so that it
has some semblance of order.
 
Let me explain it this way.  If you are writing from scratch and
using good tools, SGML is a wonderful tool.  If you are handed 50 Meg
of data which the client claims to be SGML (but only 10% of it parses)
and you have to deal with it in whatever way you can, well it is not
a pleasant task.
 
>Jeffrey presented horrible examples of SGML input. The problem here
>is that one has to distinguish between two ways of working with SGML
>documents: the ``wealthy way'' (with appropriate tools) and the
>``poor man's way'' (by hand). If the example concerned the former way
>it was simply wrong; if it concerned the latter, it was plain bad.
 
What would you do if you were give 5000 files, of which only 500 parsed,
and you had to edit the data?  For example, Author Editor will NOT
read in many of the files because they are coded wrong.  You have
no choice but to use the ``poor man's way''.  You have to look at the
coding.  You also need a parser which will show you the problems.
 
Context-sensitive editors work great if the data parses.  Consider a
common problem we run into.  We need to create an SGML document from
a hard copy source.  There is no electronic copy of the data.  We have
two options:  scanning and keying.  Scanning is fine, but you still have
to add all the tags.  Keying can have both done at the same time.  Most
keying houses can easilly add the SGML tags to a document.  However,
in both cases you will end up with documents that probably will not
parse on the first pass.  Also with keying you can run into some
structure problems, that is, the tags are wrong in such a way that
it conficts with the DTD.
 
In that case, there is no option, but the ``poor man's way''.
One of the serious problems with all the editing tools for SGML
is that they assume that the data is tagged in a reasonable in
accordance with the DTD.  This is what you want to end up with, but
you may not start with anything resembling that.
 
One of the serious problems with SGML is that the name has almost
become a "buzzword".  Not quit as bad as "object-oriented" but it
may get there.  We have another client who is moving in the direction
of SGML.  The data is not there yet.  They don't want to spend the
time nor the money to try and validate the 100 or so Meg of data
that they have.  But the tags are now consistant with SGML style,
and it may be possible to write a DTD for what they have.  But we
know that the data would not parse.  There are too many inconsistancies
in the data.  It would take a lot of time and effort to get all
the data to pass a parser.  But eventually they will do that,
but not this year, nor next year.
 
So what do you do if you receive a Pseudo-SGML document?  In our
case we MUST deal with it.  We try and point out the problems with
the document to our clients.  We will try and fix them, if we can.
 
So if you live in a world where you only deal with real SGML documents
that always parse, you have it easy.  I do not.  I must deal with
documents that don't parse, that are miss-tagged, and have structural
errors in them.  When I am through with them, they parse.
 
    Jeffrey McArthur                  ATLIS Publishing
    phone: (301) 210-6655             12001 Indian Creek Court
    fax:   (301) 210-4999             Beltsville, MD  20705
    EMAIL: j_mcarthur@bix.com
 
From kcousins@echidna.rp.CSIRO.AU Wed Jul 07 18:24:50 +1000 1993
Date: Wed, 07 Jul 93 18:24:50 +1000
From: kcousins@echidna.rp.CSIRO.AU
Reply-To: LitProg@SHSU.edu, kcousins@ECHIDNA.RP.CSIRO.AU
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
My vote: create a newsgroup and expand the reader base.
 
As for those who lack USENET access, can a USENET-mail 'gateway' of some sort 
solve their problem?
 
--Kevin.
________________________________________________________________________
    Kevin Cousins  |  kcousins@rp.csiro.au   | Ph: +61 2 868 0425
                                              Fax: +61 2 868 0490
 
      _--_|\     _   _   . _   _      CSIRO / Division of Radiophysics
     /      \   / ` ( ` / /_) / )     Cnr Vimiera & Pembroke Rds
     \_.--\_*  (_, ._) / / \ (_/      Marsfield  NSW  2121
           v
------------------------------------------------------------------------
 
From dentato@minerva.ing.uniroma1.it Wed Jul 7 09:38:49 +0100 1993
Date: Wed, 7 Jul 1993 09:38:49 +0100 (DFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
To: LitProg@SHSU.edu
Subject: Re: Time for creating a newsgroup ?
 
 I'm not against the list -> newsgroup conversion as long as the list
remains: I have no news access and I would miss this list!
 
 By the way, can anyone (privately) explain me how to obtain newsgroup?
        ___ __
       //_/// \
      // \//__/
 
From dak@POOL.Informatik.RWTH-Aachen.DE Wed Jul 7 14:29:49 +0200 1993
Date: Wed, 7 Jul 93 14:29:49 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, iapa!ctrbdo@MAILHOST.ECN.UOKNOR.EDU
Subject: Re: standard web front end, texinfo web, et. al
 
Sorry I am not too good at quoting, do not know Emacs good enough.
Someone wrote:
===> topic 2: texinfo web
 
Is there a web system which generates texinfo files instead of TeX /
LaTeX?  Since texinfo can be used to create online documentation in
addition to printed documentation, it looks like it would be real
handy.
 
---
Well, texinfo files are mainly there for user documentation, not
program documentation. However, possibility of hopping around cross-
references in the source would be a nice feature. It would be, however,
even when programming, or doing change files.
 
I believe that for users of Emacs, it would be most intelligent
incorporating those features in a WEB style, so that programming
and browsing of the source need not be different procedures and
files. Any good WEB-styles in Emacs lisp around?
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From Steve Thu Jul 08 00:10:38 +1000 1993
Date: Thu, 08 Jul 1993 00:10:38 +1000
From: Steve Avery <stevea@vast.unsw.edu.au>
Reply-To: LitProg@SHSU.edu, stevea@VAST.UNSW.EDU.AU
To: LitProg@SHSU.edu, neeri@iis.ee.ethz.ch
Subject: Re: Time for creating a newsgroup ?
 
Hi all,
	This is more looking for a volunteer than debating a newsgroup.
Would someone like to form a mail gateway for a newsgroup if it is
created? This way those that do not have access to a reliable newsfeed
(like me), or any newsfeed at all (which is why there are TeX mailing
lists isn't it?), would still be able to participate.
	Anyone interested? Anyone else want to have such a thing?
 
	Reply to me - not the list.
 
	cheers
	-steve  (stevea@vast.unsw.edu.au)
 
From George Wed Jul 07 11:09:14 CST 1993
Date: Wed, 07 Jul 1993 11:09:14 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: litprog@SHSU.edu
Subject: About a newsgroup.........
 
I've been following along on the newsgroup discussion quietly as I've
wanted to see what would transpire.  I hope you will humor me by allowing
me to interject here.  Also, please allow me to first state my personal
preferences so that you can see that this is a potentially biased view. 
Given the option of mail or news, mail wins out every time.
 
LitProg is now just about one year old -- when Cameron Smith first proposed
the idea, neither of us (nor anyone else) had any idea that it would be
this (a) big, (b) productive, nor (c) intermixed beween acedemia and
industrial applications.  That's what we wanted, but wants and gets are
often different.  Starting with the original two of us (and I am still
generally clueless about Literate Programming, but learning more as things
come in -- which I sincerely thank you for), the list today stands at 329
subscribers.
 
Doing a mail<->news gateway is not trivial, nor is it difficult -- I could
easily arrange a gateway along the lines of the dual port used for
INFO-TeX->comp.text.tex->ctt-Digest or along the lines of the mirror used
INFO-TPU<->vmsnet.tpu or a few other configurations which we already
support (indeed, vmsnet.tpu was originally INFO-TPU which spawned into a
supported gatewayed newsgroup, so I've gone through this before already).
 
A few things to consider, though.  First, getting mail into news is trivial
(I can tell you about 7 dozen different ways to do this) but getting news
into mail is not so trivial (easily done, but not as trivial).  The
technology exists and I can arrange a mirror or a dual port if a newsgroup
is created.  As a footnote -- someone asked about getting newsgroups via
mail:  as far as I am aware, this can't be done directly unless someone is
able to arrange a feed for you somehow; thus, unless someone volunteers to
set you up a specific single feed from news to mail or unless you find a
newsgroup which is ported or mirrored somehow, you're very probably out of
luck.
 
Second, and a larger concern, news is quite simply not as reliable as mail
for topics you really want to hear about.  Everything we get on INFO-TeX
definitely gets to comp.text.tex but not everything on comp.text.tex gets
to ctt-Digest due to routing (I assume).  If you want to blame our gateway
site, go ahead -- but be forewarned that it is probably in the top one or
two percent of news sites in terms of connectivity (it directly maps to 17
hosts for inbound and outbound transfers -- one of which is across the
Pacific and one of which is across the Atlantic).  I have verified this
with a few other users elsewhere -- sometimes a few items they see in news
aren't in ctt-Digest and there are a few in ctt-Digest which they never see
as news entries, so I assume that there is a drop somewhere along the line. 
Maybe a site really does get *everything* -- if so, please point me to it
so I can attempt to get our gateway connected to it.
 
Third, and this is an even larger concern, while there may be adequate
votes for a newsgroup, please recognize that with a newsgroup within a
legitimate hierarchy (comp, sci, etc.) news sites which carry everything
(often, if not always, the case) are going to have to carry the new group
-- whether or not readers use it locally.  This is a real resource
committment as somewhere the space for additional traffic has to be
accommodated.  True, LitProg hasn't generated all that much traffic in its
history, but that is a concern which I feel far too many people overlook
when discussing "let's start a newsgroup".  Given that space is not free
(inexpensive relative to a few years ago and getting more so every day it
seems), the economic principle of scarcity comes into play -- meaning
quicker expiration dates on other groups.  Also, expiration means that
long-term archives are harder to come by -- as things now stand, we have a
reliable and accurate archive of everything ever posted which is accessible
in a variety of manners.
 
Fourth, and a marginal benefit to me and our resources here, a newsgroup
means a reduced mail load, so I won't complain about that dimension (at
least until we get over 1,000 subscribers).  As I've already noted, I'll
work with the group whichever way it heads.
 
Finally, one very real benefit of a newsgroup is that it has essentially an
unlimited life.  Once created, it just never goes away.  Mail lists are a
function of support by someone somewhere and not as stable (to use the term
loosely).  It is my intent to continue support for each of our lists so
long as there is an interest (and I am successfully getting a cadre of
peopel locally to assist in most of the mundane tasks, so it's not as much
me anymore as it is SHSU in terms of committment).
 
As a side comment (which I can be flamed over if you like -- preferably
privately):  IMO, access to news allows more junk to be propagated than
just about anything else.  Not that news is bad and mail is good, per se --
we definitely see junk along the lines of bounces and (un)subscribe
requests -- just that it seems to me that the fact that people can jump in
and out of newsgroups so easily (essentialy, on a whim) leads to all kinds
of informational distortions (on this, the model I'm looking at is sci.econ
-- which is a mess and continues to be one, even though the moderated
sci.econ.research was just born in response to this phenomenon).  With
mail, people are more or less making some form of committment to the group
embodied in the list and it is far easier to propagate the mission of the
list and oversee it than on news.
 
In ending -- view this as an abstainment insofar as any vote on the topic;
I can live with your decision.  In fact, it you want a list to discuss a
LitProg-related newsgroup, let me know and I'll get it up for you.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From George Wed Jul 07 13:03:51 CST 1993
Date: Wed, 07 Jul 1993 13:03:51 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: darchen@univ-rennes1.fr
Subject: WYSIWYG LP System -- Literate Programming Workshop
 
On Tue, 6 Jul 1993 12:03:56 +0200, J.C Darchen (darchen@univ-rennes1.fr)
forwarded:
> There is a Wysiwyg LP System for the Mac; it is called the "Literate
> Programming Workshop" and is available from
>    ftp.apple.com  in  directory  /pub/literate.prog
> The tool is  shareware and the author is Norbert Lindenberg
 
Thanks!  I've fetched the file and it is in tex-archive/web/lpw on
ftp.shsu.edu for anonymous ftp retrieval, and it is gopherable from Niord
in the Literate Programming Library/.
 
As was submitted to me, attached is the README for this tool.  As I am
about as Mac illiterate as it gets (and rather proud of it!), if someone
would tell me what to include for mail purposes, I will get it over to
FILESERV (and continue working on the mail interface for ftp.shsu.edu so I
no longer have to screw with this moving, giving multiple locations, etc.). 
The files included are:
  LPW1.1.sit 
  LPW1.1.sit.hqx
  README
 
Regards and thanks again,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Literate Programming Workshop 1.1
 
The LPW1.1.sit StuffIt archive contains:
- Literate Programming Workshop
- LPW User Manual
- ParseErrors, which is both an example project and a tool you need for your
  work with LPW
 
The Literate Programming Workshop is an environment for the integrated
development of program source text and documentation in combined documents.
It consists of a WYSIWYG word processor based on a style sheet approach, a
mechanism to extract parts of the text in a document, and a project management
system that handles multi-document projects. The system is designed to be used
in conjunction with MPW: it prepares raw source text for the MPW compilers,
accepts MPW error messages, and shows them in the context of the original
documents. Automatic indexing and hypertext features allow for easy access to
both source text and documentation.
 
Compared to LPW 1.0, LPW 1.1 adds the following features:
- repeating tabs (the program editor kind)
- Shift Left and Shift Right commands
- triple clicking
- Close All and Save All commands
It also removes a few bugs.
 
LPW 1.1 is shareware - if you use it for more than two weeks, you have to
register your copy and pay the registration fee of $50.
 
- Norbert Lindenberg
 
From tsl1@cornell.edu Thu Jul 8 10:32:54 +0600 1993
Date: Thu, 8 Jul 1993 10:32:54 +0600
From: tsl1@cornell.edu (Tim Larkin)
Reply-To: LitProg@SHSU.edu, tsl1@CORNELL.EDU
To: LitProg@SHSU.edu, dak@pool.informatik.rwth-aachen.de
Subject: Re: standard web front end, texinfo web, et. al
 
>Any good WEB-styles in Emacs lisp around?
 
The CWEB 3.0 distribution contains a file, cweb.el, authored by DEK with
this discription:
 
;; This file contains extensions to GNU-Emacs, to wit:
; (1) some WEB-oriented functions that are also of general use
; (2) changes to the GNU-distributed TeX mode
; (3) definitions of simple WEB and CWEB modes
 
Tim Larkin
tsl1@cornell.edu
607-255-7008
 
From Richard Thu Jul 8 17:22:27 +1000 1993
Date: Thu, 8 Jul 1993 17:22:27 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu, Richard.Walker@CS.ANU.EDU.AU
To: LitProg@SHSU.edu
Subject: Status of Modula-2 WEB?
 
Hi everyone!  Does anyone know the current state of
Modula-2 WEB systems?  I am particularly interested to
hear if Sewell's system is available somewhere (by ftp).
I have tracked down (at Utah) some files (errata and
other bits related to Sewell's book) but not the system
itself.
 
Richard.
 
PS I vote for the newsgroup too.
 
PPS Has anyone thought more about the on-page mini-indexes of
    the TeXbook?  I am becoming increasingly convinced that
    they are a `good idea'.
 
From Ian Thu Jul 08 08:24:41 GMT 1993
Date: Thu, 08 Jul 93 08:24:41 GMT
From: Ian Cargill <ian@soliton.demon.co.uk>
Reply-To: LitProg@SHSU.edu, ian@soliton.demon.co.uk
To: LitProg@shsu.edu
Subject: Re: About a newsgroup.........
 
In message <0096F23F.9D5BD0E0.30973@SHSU.edu> you write:
> I've been following along on the newsgroup discussion quietly as I've
> wanted to see what would transpire.  I hope you will humor me by allowing
> me to interject here.  Also, please allow me to first state my personal
> preferences so that you can see that this is a potentially biased view. 
> Given the option of mail or news, mail wins out every time.
 
 *SNIP*
 
> Doing a mail<->news gateway is not trivial, nor is it difficult -- I could
> easily arrange a gateway along the lines of the dual port used for
> INFO-TeX->comp.text.tex->ctt-Digest or along the lines of the mirror used
> INFO-TPU<->vmsnet.tpu or a few other configurations which we already
> support (indeed, vmsnet.tpu was originally INFO-TPU which spawned into a
> supported gatewayed newsgroup, so I've gone through this before already).
 
 *SNIP*
 
If we stay as a mail list, there is one possible solution for some 
people at least.  I've just replied to a post offering a utility
which takes mail for a particular user (eg litprog@mymachine.domain.xx)
and converts it into a newsgroup locally.  This obviously depends on your
individual setup, but I am going to try it. (Alpha release :-) )
 
If it is a reasonably simple proceedure, other implementations may 
also be possible.  Of course, this may just be re-inventing the wheel.
Anyone know of any existing implementations?
 
 Ian Cargill         Email:  ian@soliton.demon.co.uk
 54 Windfield, Leatherhead, Surrey,\ UK   KT22 8UQ
 Phone:  +44 (0)372  375529 (Home),   +44 (0)71 510 7875 (Work)
-----------------------------------------------------------------
 C Users Group (UK): For Serious C & C++ Users (Mail for details)
 Note: Changing shortly to 'Assn. of C and C++ Users', ACCU.
 
From jmu@ccr.jussieu.fr Thu Jul 8 12:19:44 +0200 1993
Date: Thu, 8 Jul 1993 12:19:44 +0200
From: jmu@ccr.jussieu.fr (Johannes MULLER p73413)
Reply-To: LitProg@SHSU.edu, jmu@CCR.JUSSIEU.FR
To: litprog@shsu.edu
Subject: web-mode and emacs 19.15
 
Is there anybody who has experience with M.Motls and B.Childs web-mode
under emacs-19.15? I have serious problems with the list of sectionnames
and everything related (name completion and selection) with my newly
installed gnu emacs 19. I tested the web-mode I received on another
machine running emacs 18.5? and it works as I expected (ok, as in the manual).
Under emacs-19 the list of sectionnames is shortened to a handfull of
names like "." or "$" or "e" with (Defined)(Used) like "(3 5 12 67)(34 22 56)"
which has no real connection to my program...
Shure, I recompiled the .el file.
 
Any help is greatly appreciated
 
Johannes
 
From Timothy Thu Jul 8 22:22:50 BST 1993
Date: Thu, 8 Jul 93 22:22:50 BST
From: Timothy Murphy <tim@maths.tcd.ie>
Reply-To: LitProg@SHSU.edu, tim@MATHS.TCD.IE
To: LitProg@shsu.edu, Richard.Walker@cs.anu.edu.au
Subject: Re: Status of Modula-2 WEB?
 
> Hi everyone!  Does anyone know the current state of
> Modula-2 WEB systems?  I am particularly interested to
> hear if Sewell's system is available somewhere (by ftp).
> I have tracked down (at Utah) some files (errata and
> other bits related to Sewell's book) but not the system
> itself.
 
I don't think this is relevant,
but OzTeX is written in Modula-2,
using a web2modula developed by Andrew Trevorrow (sp?).
 
Timothy Murphy  
 
e-mail: tim@maths.tcd.ie
tel: +353-1-2842366 (home/office)
     +353-1-7021507 (university)
fax: +353-1-2842295
s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland
 
From Lee Thu Jul 8 20:30:59 EDT 1993
Date: Thu, 8 Jul 93 20:30:59 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, iapa!ctrbdo@mailhost.ecn.uoknor.edu
Subject: Re: standard web front end, texinfo web, et. al
 
Bryan Oakley writes:
 
> Some folks have mentioned WYSIWYG webs.  At first blush it sounds like
> a great idea.  However, when debugging a web file using a source
> browser I generally like to see the web source, not the generated .c,
> etc. source, and I like the compiler to complain by giving line
> numbers in reference to the orignal web file as well.  If the file is
> WYSIWYG, it seems to me that most (all?) compilers and debuggers would
> choke on the WYSIWYG stuff.  Given all that, is there a FrameMaker web
> out there somewhere?
 
A WYSIWYG web (at least the one I know about) creates a plain ASCII source
file that will certainly not choke any compiler when it is tangled. 
There is no reason that a WYSIWYG web system couldn't put #line
directives (or the equivalent) into the tangled output, as noweb does
if a switch is set on the command line.  Unfortunately, few languages
support a directive to ``fake out'' the compiler's line counting as
C's #line does :-(.
 
Hope this clears up some of the confusion.
 
		-- Lee
 
From j_mcarthur@BIX.com Thu Jul 08 23:08:56 -0400 1993
Date: Thu, 08 Jul 1993 23:08:56 -0400 (EDT)
From: j_mcarthur@BIX.com
Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
To: LitProg@SHSU.edu
Subject: Modula 2 WEB
 
> Hi everyone!  Does anyone know the current state of
> Modula-2 WEB systems?  I am particularly interested to
> hear if Sewell's system is available somewhere (by ftp).
> I have tracked down (at Utah) some files (errata and
> other bits related to Sewell's book) but not the system
> itself.
 
I have a copy of the version that is documented in 
Sewell's book.  Unfortunately there are several problems.
 
First, since Sewell's book a new release of Tangle, Weave,
and TeX were released.  The version documented in Sewell's
book is version 3.0 (see page 272 of Sewell's book).  The
current release of Tangle is 4.1 and Weave is up to 4.4.
 
The major change that these versions support is the 256
character-set that TeX 3.0 and above support.
 
The second problem is that MANGLE and MEAVE (the Modula-2
versions of Tangle and Weave) make a lot of the same assumptions
that Tangle and Weave do about Pascal.  This means that
it is a pain to use ANY library because the output is designed
for a case-insensitive language.  Modula-2 is case sensitive.
A WEB designed for Modula 2 should also be case sensitive.
Otherwise you have to go to a lot of trouble to quote all
the references that must be case sensitive.  Another problem
is that Modula-2 will do simple constant arithmatic.  So
there is no need for the WEB processor to give its limited
support to arithmatic operations.
 
On my "list of things to do" is to update the version of
Mangle and Meave.  I have an updated copy of Tangle and Weave.
I have change files for Tangle 4.1 for Borland Pascal 7.0
and for TopSpeed Pascal.  I also have change files for
Weave 4.0 for Borland Pascal (and I think for TopSpeed, but
I am not sure on this one).
 
Another "thing to do" is to extend Tangle and Weave to match
the syntax of Borland Pascal 7.0.  The object oriented extensions
of BP 7.0 make it a fairly nice tool to work with.  Plus it
includes a Dos-Extender so you can compile large programs.
 
    Jeffrey McArthur                  ATLIS Publishing
    phone: (301) 210-6655             12001 Indian Creek Court
    fax:   (301) 210-4999             Beltsville, MD  20705
    EMAIL: j_mcarthur@bix.com
 
From Detlef Mon Jul 12 12:53:42 CET 1993
Date: Mon, 12 Jul 93 12:53:42 CET
From: Detlef Lannert <TSOS@ze8.rz.uni-duesseldorf.de>
Reply-To: LitProg@SHSU.edu, TSOS@ZE8.RZ.UNI-DUESSELDORF.DE
To: <LitProg@SHSU.edu>
Subject: Re: Time for creating a newsgroup ?
 
In message <199307062236.AA11644@yggdrasil> you wrote:
>  
> I apologize for having generated so much traffic, and I would suggest that
> further articles on this subject be addressed directly to me and be kept off
> this list, unless there is substantially more discussion contained than just "I
> am for/against creating a newsgroup". I *would*, however, like to hear from as
> many people as possible about their opinions.
 
As a lurker who just reads this list to see what's going on with LP (I'm not 
practising it yet) I'd really prefer a newsgroup; it's easier to scan and 
doesn't clutter my mailbox. 
 
-- Ich sehe erst jetzt an der Zieladresse, dass ich wohl auch gleich haette 
deutsch schreiben koennen; sei's drum. Also: Eine Stimme fuer die Newsgroup. 
 
Schoenen Gruss, 
Detlef 
 
From Peter Mon Jul 12 15:14:03 MEZ 1993
Date: Mon, 12 Jul 93 15:14:03 MEZ
From: Peter Schmitt <A8131DAL@AWIUNI11.EDVZ.UniVie.AC.AT>
Reply-To: LitProg@SHSU.edu, A8131DAL@AWIUNI11.EDVZ.UNIVIE.AC.AT
To: litprog@shsu.edu
Subject: Time for creating a newsgroup ?
 
I am only following this list with casual interest, since
- at least at the moment - I do no programming, and therefore
do not need a WEB system.
Nevertheless I want to throw in an argument *pro* mailing list
and *contra* a newsgroup:
 
As far as I remember traffic on this list never was uniformly
--- there always were sharp peaks when some topic was discussed
followed by quiet periods with little or no messages.
In my opinion this fact favors a mailing list over a newsgroup:
  - mail appears automatically in the mailbox and thus alerts me
    that some discussion is going on, while
  - a newsgroup has to be selected actively. And if - for some
    period - there is no discussion going on, the newsgroup
    will not be checked regularly, thus discussion will slow down,
    and - maybe - some thread will even die out prematurely.
 
(Notice that, without this discussion on the merits of a newsgroup,
there would be no messages on this list just now!
I think that newsgroups are best suited for big and uniform traffic.)
 
Furthermore, the fact (already discussed)
that mailing lists reach a larger audience
is a convincing argument *for* the list.
 
Peter
 
Peter Schmitt                             a8131dal@awiuni11.edvz.univie.ac.at
                                                        schmitt@awirap.bitnet
-----------------------------------------------------------------------------
Institute of Mathematics                                     Strudlhofgasse 4
University of Vienna                                              A-1090 Wien
                                                                      Austria
 
From fulling@sarastro.math.tamu.edu Tue Jul 13 13:39:44 CDT 1993
Date: Tue, 13 Jul 93 13:39:44 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu, fulling@SARASTRO.MATH.TAMU.EDU
To: LitProg@shsu.edu
Subject: Re:  Time for creating a newsgroup ?
 
I agree with the opinions of Peter Schmitt "*pro* mailing list and
*contra* a newsgroup".  I will try to follow the discussion into Usenet
if that's where it goes, but I will be more comfortable if things stay
as they are.
 
I think there are sound rational arguments for the newsgroup, which is
why I didn't speak up as long as it seemed (incorrectly, it now
appears) that the newsgroup proponents were in the overwhelming
majority.  (If the network is not being observed by
sociology/psychology graduate students, it should be.)
 
					     S. A. Fulling
 
From norman@bellcore.com Tue Jul 13 16:12:16 -0400 1993
Date: Tue, 13 Jul 93 16:12:16 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@shsu.edu
Subject: Re:  Time for creating a newsgroup ?
 
I'm in favor of a mailing list.  S/N degrades too much in a newsgroup.
If I believed we could sell literate programming to a wide audience,
I would be in favor of a newsgroup, but I don't think the tools or techniques
(especially not the techniques) have reached that stage yet, so I prefer
to stay in a ghetto if possible.
 
Norman
 
From stephan@stack.urc.tue.nl Wed Jul 14 10:57:31 +0200 1993
Date: Wed, 14 Jul 1993 10:57:31 +0200 (MET DST)
From: stephan@stack.urc.tue.nl (Stephan Eggermont)
Reply-To: LitProg@SHSU.edu, stephan@STACK.URC.TUE.NL
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: S/N of newsgroups
 
> I'm in favor of a mailing list.  S/N degrades too much in a newsgroup.
 
I wonder how many people claiming S/N problems use inadequate 
newsreaders/posters. For me, the S/N ratio of mailing lists is much lower than
that of newsgroups, because they aren't threaded. In a newsgroup, I routinely 
kill up to 90% of all threads in a very short time. 
 
Stephan
 
From MCCOLLUM Wed Jul 14 10:14:25 -0600 1993
Date: Wed, 14 Jul 1993 10:14:25 -0600 (MDT)
From: MCCOLLUM DAVID SCOTT <mccollum@spot.Colorado.EDU>
Reply-To: LitProg@SHSU.edu, mccollum@SPOT.COLORADO.EDU
To: LitProg@SHSU.edu
Subject: Re:  Starting a newsgroup...
 
Although I currently only follow this ``mail list'', I also agree with others
that I prefer to keep things as they are now.
 
Dave McCollum
mccollum@spot.colorado.edu
 
From GBAILEY@ZEUS.TAMU.EDU Wed Jul 14 19:08:59 -0500 1993
Date: Wed, 14 Jul 1993 19:08:59 -0500 (CDT)
From: GBAILEY@ZEUS.TAMU.EDU
Reply-To: LitProg@SHSU.edu, GBAILEY@ZEUS.TAMU.EDU
To: litprog@shsu.edu
Subject: Tools/Techniques needed before wide acceptance of LP?
 
>I would be in favor of a newsgroup, but I don't think the tools or techniques
>(especially not the techniques) have reached that stage yet, so I prefer
>to stay in a ghetto if possible.
 
What tools or techniques do you think we still need before LP is 'ready for
the masses'?
 
Guy Bailey
gbailey@cs.tamu.edu
 
From norman@bellcore.com Wed Jul 14 21:55:53 -0400 1993
Date: Wed, 14 Jul 93 21:55:53 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, GBAILEY@ZEUS.TAMU.EDU
Subject: Re: Tools/Techniques needed before wide acceptance of LP?
 
> What tools or techniques do you think we still need before LP is 'ready for
> the masses'?
 
We have an incredible proliferation of different representations
(``systems'') for literate programs and suites of tools for
manipulating them.  No tool works with multiple representations.  To
my knowledge, only one representation is designed for easy
manipulation by tools.  That one has attracted a few tool writers, but
none of the more interesting or difficult tools (prettyprinters,
hypertext browsers, multi-mode editors) work with it.  Many
representations support at most a handful of programming languages (a
serious flaw) and typesetters (a minor flaw).  Many tools are overly
complex and perpetuate the problems identified by Ramsey and Marceau
(SPE, July 1991).  In short, the tools are immature.  Progress might
be made if we all tried getting behind a single representation and
went to work making it support *any* language, *any* typesetter
(including WYSIWYG), and if we created some simple but interesting
tools, with all the amenities people have grown accustomed to, like
automated indexing, prettyprinting, &c.  Then again, it might not.
 
As to techniques, I claim there aren't any.  We have Knuth's
admonishment to write for human readers, and mine to use lots of peer
review, and I think that about exhausts the contenders.  Our only book
on the subject spends hundreds of pages mostly guiding the reader
around the idiosyncracies of the tools.  We have exactly two published
literate programs of any size, programs which might never have been
published if not for the immense prestige their author earned in other
endeavors.  
 
Should a literate program resemble a novel, essay, encyclopedia,
textbook, or automobile-repair manual?  No one knows.  Probably none
of these---after all, it is a new literary form.  But do we create and
publish literate programs so that the community can study them, learn
from them, and perhaps build an understanding of what a literate
program is and how to write one?  No!  No, we write tools, because
that's the only thing we're smart enough to understand.  I count
myself doubly guilty, since I have written twice as many tool sets as
most other contenders.
 
Well, I apologize for the polemic.  Put it down to annoyance. I just
finished an article on yet another literate-programming tool, and the
article contained neither a clear description of the tool nor any
reference to the criteria so clearly set forth by Thimbleby.  I wish I
knew what the editors and referees were thinking of.
 
Norman Ramsey
 
From Ian Thu Jul 15 07:23:18 GMT 1993
Date: Thu, 15 Jul 93 07:23:18 GMT
From: Ian Cargill <ian@soliton.demon.co.uk>
Reply-To: LitProg@SHSU.edu, ian@soliton.demon.co.uk
To: LitProg@shsu.edu
Subject: Re: Tools/Techniques needed before wide acceptance of LP?
 
In message <9307150156.AA08660@mailee.bellcore.com> you write:
 
  *SNIP*
 
> Well, I apologize for the polemic.  Put it down to annoyance. I just
          ^^^^^^^^^^^^^^^^^^^^^^^^^
          DON'T !!
  I think this group needs more discussion of this type if we are 
  to advance the 'cause' of LP.  Since I joined the list, posts have
  been mostly about the mechanics of specific implementations.  I don't
  say that that is a bad thing, just that it must not be the ONLY thread.
  I'm a bare beginner, so I not ready to contribute much yet, but think
  we would all benefit from more discussion of the points that Norman
  has raised.
 
> finished an article on yet another literate-programming tool, and the
              ^^^^^^^^
              Any good? Reference?
> 
> Norman Ramsey
> 
 
 Ian Cargill         Email:  ian@soliton.demon.co.uk
 54 Windfield, Leatherhead, Surrey,\ UK   KT22 8UQ
 Phone:  +44 (0)372  375529 (Home),   +44 (0)71 510 7875 (Work)
-----------------------------------------------------------------
 C Users Group (UK): For Serious C & C++ Users (Mail for details)
 Note: Changing shortly to 'Assn. of C and C++ Users', ACCU.
 
From Dominique Thu Jul 15 09:37:24 +0200 1993
Date: Thu, 15 Jul 93 09:37:24 +0200
From: Dominique Dumont / GND <domi@petrus.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@PETRUS.GRENOBLE.HP.COM
To: LitProg@SHSU.edu
Subject: Re: Starting a newsgroup...
 
In message <199307141614.AA04858@spot.Colorado.EDU> you write:
> Although I currently only follow this ``mail list'', I also agree with others
> that I prefer to keep things as they are now.
> 
> Dave McCollum
> mccollum@spot.colorado.edu
> 
>
 
I agree. 
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From Will Thu Jul 15 12:55:04 +0100 1993
Date: Thu, 15 Jul 93 12:55:04 +0100
From: Will Partain <partain@dcs.gla.ac.uk>
Reply-To: LitProg@SHSU.edu, partain@DCS.GLA.AC.UK
To: LitProg@SHSU.edu
Subject: Glasgow literate programming system
 
A few people have asked about our system since it was mentioned in
passing.  [Sent to the list because I may not have saved all msgs.]
 
It's around, it works, some people use it, it is freely available.  It
is heavily unadvertised because I'm not working on it (it was done in
1990), and I can't promise a lot of attention to it.  (I work on the
Glasgow Haskell compiler in Real Life.)
                                                  vvvv
Here's the idea.  You write your code in a LaTeX-*like* notation,
                                                  ^^^^
with the code bits between \begin{code} and \end{code}.  You can then
process your stuff into a .dvi file (for typesetting) or into an Info
file (simple hypertext viewing).  It doesn't care what programming
language you are using, but it has "hooks" that let you run indexing
and/or typesetting filters over each of the code fragments.  As it
comes, the system "knows" about Haskell, C, Perl, and Fortran (but not
very much).  There's more, but that's the basic idea.
 
Implementation: the beast is more-or-less a Perl Script From Hell.
The language-specific parts are just little Perl fragments.  Anyone
who knows perl should be able to make it do stuff.  It shouldn't be
too bad to make it run on any Unix box that has perl on it.
 
Documentation: rambly, with lots of air-the-dirty-laundy sections.
Don't be put off.  I'd start with the "tutorial" section (Info node
"notation-tut").
 
Development: If anyone is taken with the ideas and wants to work on it
some more, please get in touch.  My remaining ambition is to
literatify the Haskell compiler better, then plug the whole thing into
the Worldwide Web :-)
 
You can get the following by anonymous FTP from ftp.dcs.glasgow.ac.uk,
in pub/haskell/glasgow:
 
	lit2x-0.16-src.tar.{Z,gz}	# full business
	lit2x-0.16-literate.info.Z	# just the documentation
	lit2x-0.16-literate.dvi.Z   	# ditto
 
I hope this is useful.
 
Will Partain
 
From dentato@minerva.ing.uniroma1.it Thu Jul 15 17:29:12 +0100 1993
Date: Thu, 15 Jul 1993 17:29:12 +0100 (DFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
To: LitProg@SHSU.edu
Subject: Tools/Techniques needed by LP
 
 I agree that this list need more discussions on the concepts of LP. Like
everyone else here, I presume, I was attracted by the idea of LP: what a
sense of freedom! The problem, I thought, are the tools: they are too
complex. So I started to write my own, simpler, literate tool. During
the development I introduced more and more commands, just because could
be useful have such commands, so my tool became just a bad copy of the  
others.
 Of course I threw away the tool. 
 But it wasn't wasted time: that experience turned to be useful because
I understood more about the literate style. Of course I'm just a novice
in the LP but I think that this new way of thinking is one of the best
things appened to programmers since the advent of full screen editors (:-)).
 
 I think, as before, that the problem is in the tools we use, but just  
because they are not powerful enough.  For example we have to navigate a
graph (our webfile) using a linear tool (an editor), it would be much
better to have an hypertext tools.  The formatting commands and the
special commands we use "obscure" the text and the code we are writing,
so a WYSIWYG hypertext tool should be even better!
 
 Of course we would to be platform independent (IMO one of the
biggest advantages of TeX is its availability for any platforms), and
typeset beautiful math and so on.
 
 But here is a problem: more powerful the tools, more powerful the
machines we have to use (I simply can't stand to wait too much for, say,
the generation of the indices) and I work on various machines that range
from IBM RS6000 to MS-DOS ( :-( ).   
 
 For now I have adopted the nuweb system from Preston Briggs, it's
clear, fast, language independent, and gives me all I need to be a
literate. IMO is the easiest and most natural tool I've used.
 
 The problem is: why using LP? Personally I have choosed LP first of all
for helping myself during development, and second for the others that,
finally, can read my code and understand what I intedend to do.
 
 During the development I absolutely don't want to be bothered with
typesetting problems (after all maybe none will read my code!) but I
still want indexes and cross referencing of macros etc, etc. so I'm
currently writing a tool that will do this kind of works for the nuweb
system.
 
 In conclusion I'm very interested in what do you think are the
"intimate essence" of literate programming (;-)), both from the   
experienced literate programmers, both the newcomers.
 
 Ok, I hope I wasn't too boring. Bye!
        ___ __
       //_/// \    e-mail: mc9275@mclink.it
      // \//__/    dentato@cadgroup.ing.uniroma1.it
     Remo Dentato
 
From se_haux@rcvie.co.at Thu Jul 15 18:42:34 +0200 1993
Date: Thu, 15 Jul 93 18:42:34 +0200
From: se_haux@rcvie.co.at (Michael Haux)
Reply-To: LitProg@SHSU.edu, se_haux@RCVIE.CO.AT
To: LitProg@SHSU.edu
Subject: Re: Tools/Techniques
 
I have for some time passively followed this discussion list. Literate programming seems to have interesting qualities, leading to better documented and readable code.
 
However, I agree with the recent postings concerning the focus of the list (see Norman Ramsey). The discussion of available tools should also be in the list, but for litprog to be practicable, I think there has to be more.
I would appreciate more discussion on themes like
- How does literate programming integrate in a SW development process? With software engineering methods?
- Methods and techniques for literate programming.
- Litprog feasibility for larger, "real-world" projects.
 
Just some ideas from a litprog novice,
 
Michael
 
BTW. My vote again: A newsgroup is in my opinion superior to a mailing list (reading it with xvnews in OpenWindows).
 
               Michael Haux, Internet: Michael.Haux@rcvie.co.at
 
            V             Software Engineering Department
+-----------------------+ Alcatel Austria Forschungszentrum GmbH
|  A  L  C  A  T  E  L  | Ruthnergasse 1-7, A-1210 Vienna, Austria/EUROPE
+-----------------------+ Voice: +43 1 39 16 21 362    Fax:   +43 1 39 14 52       
 
From Zdenek Thu Jul 15 13:40:28 MDT 1993
Date: Thu, 15 Jul 93 13:40:28 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, domi@PETRUS.GRENOBLE.HP.COM
Subject: Re: Starting a newsgroup...
 
I was silent because I thought that I belong to the minority of users who are
unable to receive newsgroups. I would also prefer the mail list.
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From George Thu Jul 15 15:32:00 CST 1993
Date: Thu, 15 Jul 1993 15:32:00 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: stevef@ttsi.tandem.com
Subject: RE: Repeat messages
 
On Thu, 15 Jul 93 14:41:39 CDT, stevef@ttsi.tandem.com (Steve Farmer)
posted:
> I have been receiving a number of messages from the mailing list that are
> duplicates of messages received about a week ago. Are others experiencing
> this? Can you tell me the cause?
 
To everyone addressed:
 
I managed to hose a few entries which were enqueued (and I had no record of
who had and had not received the posts in question).  What I did was to
re-enqueue every message which I messed up; hence, they were re-broadcast
to everyone on the affected lists on a theory of better safe than sorry.
 
My apologies for any and all inconvenience this may have caused.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From ctrbdo@oak.iapa.uucp Thu Jul 15 19:30:56 CDT 1993
Date: Thu, 15 Jul 93 19:30:56 CDT
From: ctrbdo@oak.iapa.uucp (bryan d oakley)
Reply-To: LitProg@SHSU.edu, ctrbdo@OAK.IAPA.UUCP
To: litprog@shsu.edu
Subject: standard web front end, texinfo web, et. al
 
>>Lee Wittenburg writes most eloquently:
>> Bryan Oakley writes:
 
> Some folks have mentioned WYSIWYG webs.  At first blush it sounds like
> a great idea.  However, when debugging a web file using a source
> browser I generally like to see the web source, not the generated .c,
> etc. source, and I like the compiler to complain by giving line
> numbers in reference to the orignal web file as well.  If the file is
> WYSIWYG, it seems to me that most (all?) compilers and debuggers would
> choke on the WYSIWYG stuff.  Given all that, is there a FrameMaker web
> out there somewhere?
 
>> A WYSIWYG web (at least the one I know about) creates a plain ASCII source
>> file that will certainly not choke any compiler when it is tangled. 
>> There is no reason that a WYSIWYG web system couldn't put #line
>> directives (or the equivalent) into the tangled output, as noweb does
>> if a switch is set on the command line.  Unfortunately, few languages
>> support a directive to ``fake out'' the compiler's line counting as
>> C's #line does :-(.
 
>> Hope this clears up some of the confusion.
 
Actually, No.  I guess I didn't make myself clear.  I realize that a
WYSIWYG web creates plain ascii files; that much is obvious.  However,
when it creates the code and inserts the #line declarations, I'm
concerned that they will be pretty much useless.  If I run a source
debugger I would prefer to see the ORIGINAL SOURCE (ie: the WYSIWYG
web file), _not_ the tangled code, much like I prefer to see the
source code instead of compiled machine or assembly code in
traditional software development (ie: I view a tangled source module
to be at the same level of abstraction as the ultimate compiled code
-- the language file, .c, .f, whatever, is purely a means to an end.
However, source debuggers make the assumption that the source is in
ASCII, not Word(im)Perfect, Word, Frame, or some other format so it
must show the tangled source code.  Well, that has no relationship on
the real 'source' code, which causes me grief.
 
I see web systems as truely an improvement when the tangled code is
merely a byproduct, and there are sufficient tools to allow one to
work with the original source in all phases of development.  Why
should I code in one language (a web system), then debug in another (a
traditional language)?  Admittedly, web systems provide great
documentation, but for the work I do, content (and useability) is much
more important that format.  I dare say that I can write equally
readable code with just my normal commenting.
 
>> -- Lee
 
--bryan
 
From norman@bellcore.com Thu Jul 15 21:32:00 -0400 1993
Date: Thu, 15 Jul 93 21:32:00 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, ian@soliton.demon.co.uk
Subject: Re: Tools/Techniques needed before wide acceptance of LP?
 
> > finished an article on yet another literate-programming tool, and the
>               ^^^^^^^^
>               Any good? Reference?
 
No. Garbage.  Reference withheld to protect the guilty.
 
Norman
 
From kcousins@echidna.rp.CSIRO.AU Fri Jul 16 11:40:48 +1000 1993
Date: Fri, 16 Jul 93 11:40:48 +1000
From: kcousins@echidna.rp.CSIRO.AU
Reply-To: LitProg@SHSU.edu, kcousins@ECHIDNA.RP.CSIRO.AU
To: LitProg@SHSU.edu, dentato@minerva.ing.uniroma1.it
Subject: Re: Tools/Techniques needed by LP
 
Fellow Literate People,
 
Recently, Remo Dentato gave an excellent summary of his experience with 
Literate Programming and opinions.
 
Some background: I work in very much an engineering environment surrounded by 
DEC & SUN workstations, PCs and MACs. Much of our software development is for 
PCs to act as controllers for various bits of lab equipment or devices we have 
built.
 
The sorts of code that is produced here tends to be extremely cryptic little 
device drivers (i.e. a couple of hundred lines of source C code) for DOS and 
WINDOWS :-( It is often difficult to explain all of the intricacies of a given 
piece of code even to other members of ones own project team. Witness me trying 
to illustrate code that writes a particular byte to some port in order to 
toggle specific bits on some home brew board. The illustration is rife with 
interruptions: Why that bit pattern? Why that port? Why perform that operation 
on this data? It seems that prolific /* commenting */ is not adequate
 
Project management started to come down on us poor code writers demanding 
better software specification from the programmers! :-o and pleading for better 
documentation of any code that gets written. (Why programmers are ever writing 
specifications I'll never understand---in MIS departments, the specification is 
handed to the programmer who is told "Go away and code something that does 
this!" True or false?)
 
It was at this point that Literate Programming came into my life :-) 
Unfortunately, given the depth of my search for information on the topic, it 
was not at all obvious how to write my short cryptic routines in such a way as 
to make them Literate. I have FWEB, am writing in C, use Emacs 18.57 with a 
web-mode, do not know very much about TeX (but have been through _The_TeX_Book_ 
once already and discovered there is not much that I have to know to get by on 
if I don't want anything too fancy), and am following this mailing list with 
avid interest. (Once again, I wouldn't mind at all if it became a news group: 
the more people that can read about our experiences, I feel, the faster this 
technique might mature and turn into something even more wonderful that some 
people already believe it to be! Seems to me thought that it doesn't matter 
whether my mail box is full or my news reader overflows---same problem, 
different windows!)
 
I have tried WinWordWEB, a nice little tool for those interested in WYSIWYG LP. 
There is no real provision there for hypertext-like coding, however. I feel 
that implementing a hypertext, WYSIWYG LP program using something like HTML 
could get very cumbersome unless appropriate tools are available to handle the 
messy repetitive details of the hypertext links. Certainly the idea of a 
hypertext coding environment has merit: the reason for this post is to broach 
the subject of Microsoft's Browse Utility which comes as part of their top end 
compiler packages.
 
We recently purchased MS C/C++ 7.0. From within their Programmer's WorkBench 
editor environment , it is possible to generate a 'browse database' containing 
cross references for any and all definitions and references to source files, 
data types, indentifiers, etc. present in your code. Relationships between 
source files and identifier references can be displayed, and almost everything 
is point and click: see a variable name, want to know where it is 
defined/referenced? double click on the name, up comes a dialog OR up comes an 
editor window scrolled to precisely the right point in the file. Which 
function(s) call(s) this library routine? Point and click!
 
The ability to have a global view of the code like this is extremely handy. It 
does absolutely nothing for improving documentation, but when writing code and 
in particular debugging it, this browse feature is most beneficial. Its a pity 
that it is solely a MS product, that it must be run on a PC under specific 
circumstances, but it certainly seems to be able to handle mixed languages (We 
tried with C and Fortran).
 
I'd like to see this sort of functionality in an X client. The PC stuff from MS 
gives you this psuedo-hypertext-like stuff through a hierarchy of dialog boxes.
Perhaps its not true hypertext , but it sure beats scrolling through hundreds 
(or thousands) of lines of code looking for what you want!
 
________________________________________________________________________
    Kevin Cousins  |  kcousins@rp.csiro.au   | Ph: +61 2 868 0425
                                              Fax: +61 2 868 0490
 
      _--_|\     _   _   . _   _      CSIRO / Division of Radiophysics
     /      \   / ` ( ` / /_) / )     Cnr Vimiera & Pembroke Rds
     \_.--\_*  (_, ._) / / \ (_/      Marsfield  NSW  2121
           v
------------------------------------------------------------------------
 
From ddw2@sunbim.be Fri Jul 16 15:03:08 +0200 1993
Date: Fri, 16 Jul 93 15:03:08 +0200
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu
Subject: Limited Emacs support for nuweb: nuweb.el
 
I was getting tired of always  switching from Latex-mode to lisp mode
for this tool I'm writing in Emacs lisp so I decided to make small
additions to the AucTeX, Latex mode I'm using to support editing
LitProg files.
 
a) - .w file are put in nuweb mode,
   - Web is the default command for those buffers instead of LateX,
and that calls nuweb, then latex, (doesnot know how to get back to .w
file in case of latex errors (C-c` takes you to the .tex file).
 
b) - C-c M-c when (point) is in a scrap body, puts the scrap body in a
new buffer in a source mode indicated by a buffer local variable
nuweb-source-mode.
 
   - In that source buffer, C-c C-c validates the text and installs
that as the new version of the scrap body. C-c M-c kills the buffer.
 
The original buffer in nuweb mode is put in read-only mode until one
of those two commands is used.
 
There are some missing features, bugs, etc but I think this might be
helpful for a number of people.
 
Comments, suggestion, bug reports welcome.
 
The requirement of AucTeX (used in a) could easily be removed from
the source.
 
Dominique
 
;;;;;-------nuweb.el--------------
;;;;; 
;;; Simple support for nuweb editing in Emacs
;;; Works on top of AucTeX
;;;
;;;  $Id: nuweb.el,v 1.6 1993/07/16 12:44:05 ddw2 Exp $ 
;;;
;;; Author: Dominique de Waleffe (ddw@sunbim.be)
;;;
;;; Copyright: Do anything with it, but dont forget to credit me 
;;; 
;;; Bug reports , suggestions are  welcome. I'll see if I can do anything in
;;; my copious spare time
;;;
;;; This obviously should have been written using nuweb... instead of being hacked in
;;; a few minutes.
;;;
;;;  To install:
;;;     (push auto-mode-alist '( "\\.w" . nuweb-mode))
;;;     (require 'nuweb)
;;; 
(require 'tex-site) ; I'm not sure that this is enough
 
;;; Extend the list of commands
(setq TeX-command-list
      (cons 
       (list "Web" "nuweb %s ; latex '\\nonstopmode\\input{%t}'" 'TeX-LaTeX-hook nil t)
       TeX-command-list))
 
;;; allow .w as extension
(setq TeX-file-extensions '("tex" "sty" "w"))
 
;;;
;;; Nuweb-Source-Mode can be set locally in each buffer
;;; \C-c\M-c will edit the current scrap body (if within one)
;;; into a buffer named *Source* put in the correct source mode
;;; allows to get correct indentations easily
;;; Of course what happens with further @ sequence is at best undefined
;;;  In the *Source* buffer, all the  commands of the mode are available 
;;;  plus 
;;;      \C-c\c-c to install the whole buffer contents as the new scrap body
;;;      \C-c\M-c to kill the edited scrap buffer and go back to the original
;;; Before any of those two commands are used, the original nuweb buffer is put 
;;; in read-only mode. The saving of the positions etc is rudimentary.
 
;;; Further strorage in global variables as I've done allows only to edit one 
;;; scrap at a time.
 
(defun nuweb-mode ()
  "Major mode to edit nuweb source files"
  (interactive)
  (latex-mode)
  (setq mode-name "nuweb")
  (make-variable-buffer-local 'nuweb-source-mode)
  (local-set-key "\C-c\M-c" 'edit-this-scrap)
  (setq TeX-default-extension "w")
  (setq TeX-command-default "Web"))
 
(setq-default nuweb-source-mode 'emacs-lisp-mode)
 
; only one of those in effect....
(defvar *last-scrap-pos* nil)
(defvar *last-scrap-begin* nil)
(defvar *last-scrap-end* nil)
 
(defun edit-this-scrap ()
  (interactive)
  (cond((or (null *last-scrap-pos*)
	    (y-or-n-p "You did not finish editing the previous scrap. Continue "))
	(setq *last-scrap-pos* (point-marker))
	(let* ((begin (and (search-backward "@{" nil t) (point)))
	       (end (and (search-forward "@}" nil t)
			 (>= (point) (marker-position *last-scrap-pos*))
			 (point)))
	       (text "")
	       (mode nuweb-source-mode))
	  (cond ( (and begin end)
		  (setq *last-scrap-begin* begin)
		  (setq *last-scrap-end* end)
		  (setq text (buffer-substring begin end))
		  (setq buffer-read-only t)
		  (switch-to-buffer-other-window "*Source*")
		  (erase-buffer)
		  (insert text)
		  (goto-char (point-min))
		  (funcall mode)
		  (local-set-key "\C-c\C-c" 'restore-this-scrap)
		  (local-set-key "\C-c\M-c" 'kill-this-scrap)
		  (message "C-c C-c to use source, C-c M-c to abort"))
		(t (error "Could not identify scrap")))))
       (t (message "Use C-x b and select buffer *Source* to finish"))))
 
(defun restore-this-scrap()
  (interactive)
  (back-to-pos) 
  (delete-region *last-scrap-begin* *last-scrap-end*)
  (insert-buffer "*Source*")
  (setq *last-scrap-pos* nil))
 
(defun kill-this-scrap() 
  (interactive)
  (back-to-pos) 
  (setq *last-scrap-pos* nil))
 
(defun back-to-pos()
  (switch-to-buffer (marker-buffer *last-scrap-pos*))
  (setq buffer-read-only nil)
  (delete-other-windows)
  (goto-char (marker-position *last-scrap-pos*))
  (recenter))
 
(provide 'nuweb)
 
From Eric Fri Jul 16 14:04 +0000 1993
Date: Fri, 16 Jul 1993 14:04 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LITPROG@shsu.edu
Subject: Re: Tools/Techniques needed by LP
 
Remo Dentato writes:
 
== In conclusion I'm very interested in what do you think are the
=="intimate essence" of literate programming (;-)), both from the   
==experienced literate programmers, both the newcomers.
 
I have asked this question several time to the LITPROG netters before. 
For myself I am getting more and more convinced that the essential quality
of litearte programming is to associate a given design step exactly with its
consequences in terms of the steps (code) of an algoritm, NOTHING MORE AND
NOTHING LESS. In other words, LP makes explicite which code lines are 
responsible for which design decisions
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Zdenek Fri Jul 16 09:50:56 MDT 1993
Date: Fri, 16 Jul 93 09:50:56 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, dentato@MINERVA.ING.UNIROMA1.IT
Subject: Re: Tools/Techniques needed by LP
 
I will write a very short message what LP brought me. I am not a novice but
I do not consider myself an expert either. I had my old programs written
about half year ago in CWEB. Each of these 4 programs had about 20 pages
of listing. Of course I have forgotten how these progams work inside. Now
I had to change these programs in order to alter their functionality. When
I counted the changed section, it was about 70% of the program. I managed
to do such drastical changes of 4 programs within 3 hours and all programs
worked fine after the first compilation without any debugging. I doubt whether
I would be able to do the same without LP.
 
                                                ,
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> but now it seems repaired.
 
From cdantoni@abacus.bates.edu Fri Jul 16 12:23:45 -0400 1993
Date: Fri, 16 Jul 1993 12:23:45 -0400 (EDT)
From: cdantoni@abacus.bates.edu (Chuck D'Antonio)
Reply-To: LitProg@SHSU.edu, cdantoni@ABACUS.BATES.EDU
To: LitProg@shsu.edu, domi@petrus.grenoble.hp.com
Subject: Re: Starting a newsgroup...
 
A recent post about a potential newsgroup:
 
> In message <199307141614.AA04858@spot.Colorado.EDU> you write:
> > Although I currently only follow this ``mail list'', I also agree with others
> > that I prefer to keep things as they are now.
> > 
> > Dave McCollum
> > mccollum@spot.colorado.edu
> > 
> >
> 
> I agree. 
 
It seems that too many posts are taking on this shape.  I realize that
it is important to have some idea about whether or not the readers of
this list are interested in a newsgroup, but it seem trivial that the
discussion is lasting so long.  What is the real problem with having
different sources for information?  Everyone is most concerned with
having both the group and the list connected, but for those who are
interested in a newsgroup to maintain a subscription to the mail list
wouldn't keep them from reading the news.  Maybe an alt group in
tandem with an active mailing list would give everyone a better feel
for which is more appropriate.  Or both could develop their own
charracter and the alt group could become a comp group with the list
still surviving.
 
Hopefully adding something to the debate,
Chuck
 
-- 
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- WRBC--91.5 FM -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Chuck D'Antonio	-- Foz on IRC	     <>    "Sleep is for lightweights"
internet: cdantoni@abacus.bates.edu  <>                  -- Henry Rollins
-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Apple II Forever  -=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 
From ae1181t@stnfor.ae.ge.com Fri Jul 16 12:36:44 -0400 1993
Date: Fri, 16 Jul 1993 12:36:44 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: tsl1@cornell.edu.ae.ge.com
Subject: Re: Tools/Techniques needed by LP
 
   Tim> I believe that WEB and CWEB share one critical characteristic which are
   Tim> missing from some other LP systems: the ability to create an exposition in
   Tim> the web which is organized *independently* of the requirements of the
   Tim> compiler. Of course I refer to the infamous modules, which permit me to
             .....
   Tim> of the compiler. If one cannot break the tyranny of the compiler, one might
   Tim> as well just write comments and make do with a pretty printer. I think this
 
I agree that the modules/scraps are very important, but I think that almost all
of the LP tools I tried had it! Nuweb, noweb, funnelweb, CLiP, WinWordWeb. 
Without that ability: ``to break the tyranny of the compiler'', they would be
quite useless as some do not even pretty-print the code! With the module
concept they help to implement the LP paradigm: make it read/look like a
book. 
Osman
 
Osman F. Buyukisik  |  GE Aricraft Engines  | ae1181t@stnfor.ae.ge.com
 
From George Fri Jul 16 15:55:50 CST 1993
Date: Fri, 16 Jul 1993 15:55:50 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, cdantoni@ABACUS.BATES.EDU
Subject: Re: Starting a newsgroup...
 
On Fri, 16 Jul 1993 12:23:45 -0400 (EDT), cdantoni@abacus.bates.edu (Chuck
D'Antonio) posted:
> It seems that too many posts are taking on this shape.  I realize that it
> is important to have some idea about whether or not the readers of this
> list are interested in a newsgroup, but it seem trivial that the discussion
> is lasting so long.  What is the real problem with having different sources
> for information?  Everyone is most concerned with having both the group and
> the list connected, but for those who are interested in a newsgroup to
> maintain a subscription to the mail list wouldn't keep them from reading
> the news.  Maybe an alt group in tandem with an active mailing list would
> give everyone a better feel for which is more appropriate.  Or both could
> develop their own charracter and the alt group could become a comp group
> with the list still surviving.
 
Let me put this in the best Texan talk I can -- LitProg just ain't gonna
die off.  If a newsgroup is established, it will be gatewayed whether the
news folks like it or not (just as comp.text.tex has to live with INFO-TeX
whether they like it or not and mail readers have ctt-Digest as a news
alternative -- but a digest there is simply due to traffic; I have five
other lists which are true mirrors, interactive in every dimension).  This
aspect of the discussion is null and void.  Don't think of this as a "news
will lead to the demise of LitProg" issue -- it just ain't that now and it
ain't gonna be that any time soon!!
 
--George
 
From tsl1@cornell.edu Sat Jul 17 10:09:45 +0600 1993
Date: Sat, 17 Jul 1993 10:09:45 +0600
From: tsl1@cornell.edu (Tim Larkin)
Reply-To: LitProg@SHSU.edu, tsl1@CORNELL.EDU
To: LitProg@SHSU.edu, dentato@minerva.ing.uniroma1.it
Subject: Re: Tools/Techniques needed by LP
 
> In conclusion I'm very interested in what do you think are the
>"intimate essence" of literate programming (;-)), both from the   
>experienced literate programmers, both the newcomers.
 
I believe that WEB and CWEB share one critical characteristic which are
missing from some other LP systems: the ability to create an exposition in
the web which is organized *independently* of the requirements of the
compiler. Of course I refer to the infamous modules, which permit me to
describe part of function A, then part of function B, then some more of A,
followed by some of C, and so forth. Modules free the programmer from
having the development of the explanation restricted by linear processing
of the compiler. If one cannot break the tyranny of the compiler, one might
as well just write comments and make do with a pretty printer. I think this
characteristic is close to the "essence" of LP, since it allows
explanations to follow literate patterns directed toward human readers. I
consider it to be more important than tables of contents, indices, or
hypertext links.
 
Tim Larkin
tsl1@cornell.edu
607-255-7008
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sat Jul 17 12:11:31 +0200 1993
Date: Sat, 17 Jul 93 12:11:31 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
Subject: Re: Tools/Techniques needed by LP
 
Note that the "doc" style option for Literate Programming of TeX
macro files does not have order independency or modules. So this is
an exception of your list of Literate Programming tools all having
sections. However, with TeX macros this problem is alleviated a bit
because you usually can define macros in whatever order you like.
 
In addition, TeX scraps in macros are, due to changes of catcodes
and other things, much less representable as syntactic units as
in other languages with a fixed syntax.
 
I would, however, strongly recommend using the "doc" style option
for doing literate TeX programming. It has the additional advantage
that you do NOT need tangle or weave programs, since all typesetting
(I believe this might be the case in Noweb as well) appears as comments
to TeX when using the style, and TeX is pretty fast in skipping them.
 
This is ok for testing, and for production versions you can use
docstrip for getting the comments out.
 
Sorry for this disgression, but I think the "doc" style option is mentioned
not often enough, and it really makes TeX programming literate.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From Joachim Sat Jul 17 18:22:25 +0100 1993
Date: Sat, 17 Jul 1993 18:22:25 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
Subject: Re: Starting a newsgroup...
 
You wrote:
> 
> Let me put this in the best Texan talk I can -- LitProg just ain't gonna
> die off.  If a newsgroup is established, it will be gatewayed whether the
> news folks like it or not
 
I wanted to keep quite on this subject, but this is too much.
 
You are ridiculous. Who from the `news folks' demanded that the
Litprog mailing list is shut down? The question was posed by news
proponents more than once: How can (1) a newsgroup be established for
those who like the comfort and the effectivity of newsreaders, *and*
(2) a gateway established for those who have either USENET connection
or who like mail lists more.
 
George raised legitimite concerns about such a gateway, he asked
questions who nobody of the mail proponents has answered until now.
Since he runs more than one gateway already -- perhaps you might
address these points and share your point of view in this regard
instead of insulting us?
 
For myself, it's clear. I get about 150 personal mails each day. If I
won't get Litprog out of my mailbox soon, I'll unsubscribe. It
interfers too much with my real work. Therefore I'm one of the `news
folks.' But I see it as a necessity to establish means how those who
need or want mail access *and* how those who need or want News access
can be `part of the crowd.'
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16.07.93
 
From Joachim Sat Jul 17 18:38:24 +0100 1993
Date: Sat, 17 Jul 1993 18:38:24 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
Subject: Re: Modula 2 WEB
 
Just to point out that there is another Modula-2 WEB system. Christine
and I once created it as a student project. It is derived from Knuth's
WEB, i.e., it is written in WEB. But not through changefiles, by
changing the code. User documentation is available.
 
Some problems Jeffrey mentioned concerning Sewell's MWEB are not in
this version (in particular, it is case sensitive). It is not
supported, though -- like Sewell's MWEB. ;-) And it was never used
for production software, so I can't guarantee for anything. Note, that
I don't use Modula-2, I don't even have a Modula-2 compiler available
on my workstation.
 
Oh yes, the access information. It's available from the Literate
Programming Archive (like all the packages which were announced and
mentioned here the last few weeks).
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/modula-2
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16 Jul 93
 
From Joachim Sat Jul 17 19:03:33 +0100 1993
Date: Sat, 17 Jul 1993 19:03:33 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu
Subject: Re: Starting a newsgroup...
 
A PS to my mail: To be honest, I just now detected that I was
replying to George. My gripes are still the same. But please exchange
the paragraph
 
> George raised legitimite concerns about such a gateway, he asked
> questions who nobody of the mail proponents has answered until now.
> Since he runs more than one gateway already -- perhaps you might
> address these points and share your point of view in this regard
> instead of insulting us?
 
to
 
  You raised legitimite concerns about such a gateway, you asked
  questions who nobody of the mail proponents has answered until now.
  Since you run more than one gateway already -- perhaps you might
  address these points and share your personal point of view in this
  regard instead of insulting us?
 
  After all, you're not only a potential gateway organizer, you're a
  mail proponent, too. Are you willing to provide a gateway? Unwilling?
  Is it much hassle for you? Please get back to such questions instead
  of throwing accusations around.
 
My apologies for reading the sender not more carefully. (But, you can
see that I'm paying more attention to the content than to the
addressee... :-)
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16 Jul 93
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sun Jul 18 16:45:04 +0200 1993
Date: Sun, 18 Jul 93 16:45:04 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, Yves.Arrouye@IMAG.FR
Subject: Re: unsuscribe litprog
 
I think the number of unsubscribers accidently writing to the list address
is alarming. Probably in a newsgroup they would skip articles they don't
like, such as it is, they skip Literate Programming.
 
If Literate Programming wishes to address a suitable audience (and a good
technique should be shared so that a broad base may benefit in the long
run) I think it should not balk at leaving the closet.
 
Count me in for newsgroups.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From Lee Sun Jul 18 13:47:49 EDT 1993
Date: Sun, 18 Jul 93 13:47:49 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, norman@bellcore.com
Subject: Re: Tools/Techniques needed before wide acceptance of LP?
 
Norman Ramsey states (in the middle of a ``polemic,'' most of which I agree
with):
 
> Should a literate program resemble a novel, essay, encyclopedia,
> textbook, or automobile-repair manual?  No one knows.  Probably none
> of these---after all, it is a new literary form.  But do we create and
> publish literate programs so that the community can study them, learn
> from them, and perhaps build an understanding of what a literate
> program is and how to write one?  No!  No, we write tools, because
> that's the only thing we're smart enough to understand.  I count
> myself doubly guilty, since I have written twice as many tool sets as
> most other contenders.
 
I agree with Norman that we need to start publishing our literate
programs.  One of the problems, however, is that many editors don't
know what to do with them.  We need to ``educate our editors,'' to
paraphrase Grace Hopper.
 
On the plus side (in the ``toot my own horn'' department) the _Paradox
Informant_ (Jerry Coffey, Elightened Editor) will be publishing a
literate program of mine (written using noweb) in the September issue
along with another article on _Literate Programming in PAL &
ObjectPAL_ (``God willing and the crick don't rise'').  I'm also
planning on rewriting my Baby Manchester Mark I simulator in CWEB
specifically with the idea of publication.
 
Obviously, I'm not even close to the first to publish a literate
program, but it seems that the momentum in the LP community has picked
up to the point where we need to stop ``reinventing the wheel,'' and
start using the wheels we have.  [The phrasing is a bit too strong,
but the idea is there.]  Remember that the LP column in CACM died
because people were just building tools rather than using existing
ones, and that was a good 5 years ago.
 
		-- Lee
 
From Lee Sun Jul 18 14:13:08 EDT 1993
Date: Sun, 18 Jul 93 14:13:08 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, kcousins@echidna.rp.csiro.au
Subject: Re: Tools/Techniques needed by LP
 
I'd like to add something to the discussion of LP techniques that is,
fortunately, starting to take over from the mail/newsgroup fracas :-).
 
I've noticed that there is a significant difference in _purpose_
between text chunks in webs and ``normal'' program comments.  In a
non-literate program, the documentation is there to ``comment'' on the
program source (hence the name).  The code itself is definitive.  Weinberg's
suggestion (Psych. of Comp. Pgmg) that comments be covered during
debugging comes from this.
 
On the other hand, the *text* in a web is what is definitive.  I find
that most of my debugging consists of making sure that the code chunks
agree with their respective text chunks.  I would suggest that, when
debugging a web, the _code_ sections be covered (at least initially).
The names of the code chunks also provide significant information.
For example, a recent program of mine included the the following
(embarrassingly stupid) bug:
 
  @<Do something if |set| is not empty@>=
	if (set == NULL) do_something();
 
Note that the bug is in the code, not the documentation.  When the
code in a literate program disagrees with its documentation, the fault
usually lies in the code, while the opposite is true in traditional
programs.
 
This all reflects on what Norman Ramsey said earlier.  LP is still in
its infancy; we've all got a helluva lot to learn.  Actually, that's
one of the things I like about it.
 
		-- Lee
 
From Lee Sun Jul 18 14:36:25 EDT 1993
Date: Sun, 18 Jul 93 14:36:25 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, oak.iapa!ctrbdo@rutgers.edu
Subject: Re: standard web front end, texinfo web, et. al
 
Bryan D. Oakley writes:
 
> ... text omitted ...
> 
> when it creates the code and inserts the #line declarations, I'm
> concerned that they will be pretty much useless.  If I run a source
> debugger I would prefer to see the ORIGINAL SOURCE (ie: the WYSIWYG
> web file), _not_ the tangled code, much like I prefer to see the
> source code instead of compiled machine or assembly code in
> traditional software development (ie: I view a tangled source module
> to be at the same level of abstraction as the ultimate compiled code
> -- the language file, .c, .f, whatever, is purely a means to an end.
> However, source debuggers make the assumption that the source is in
> ASCII, not Word(im)Perfect, Word, Frame, or some other format so it
> must show the tangled source code.  Well, that has no relationship on
> the real 'source' code, which causes me grief.
 
I agree, but _someone_ has to ``bell the cat.''  Would you be willing to
write such a source debugger yourself?
 
> I see web systems as truely an improvement when the tangled code is
> merely a byproduct, and there are sufficient tools to allow one to
> work with the original source in all phases of development.  Why
> should I code in one language (a web system), then debug in another (a
> traditional language)?
 
Again, all it takes is for someone to build the tool.  
 
> Admittedly, web systems provide great
> documentation, but for the work I do, content (and useability) is much
> more important that format.  I dare say that I can write equally
> readable code with just my normal commenting.
 
I disagree totally with this last statement.  The code I produce using
CWEB and noweb are significantly more readable than anything I have
ever produced before.  I have also had occasion to delve into other
people's literate code, and can testify from experience that even
mediocre literate code is easier to modify than good non-literate
code.  Honesty, however, forces me to admit that when I first read
about LP (in the CACM column), my opinion was ``My code is quite
`literate' as it is, thank you.  I don't need any fancy typesetting
tools.''  I was wrong.  I find it more productive to give up my source
debuggers in favor of LP tools than vice versa.
 
Adding more fuel to the fire,
 
		-- Lee
 
From Matthias Sun Jul 18 21:01:02 +0200 1993
Date: Sun, 18 Jul 1993 21:01:02 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Newsgroup creation 1 of 3: Overview
 
The discussion about newsgroup creation has now lasted two weeks.  To summarize
what progress has been made:
 
- I tried to count votes, and so far, I counted 25 subscribers in favor of
  newsgroup creation, 10 against.
- I learned from George Greenwade that he will set up a gateway if a newsgroup
  is created, and that he will keep archiving postings. Thanks, George!
- By compiling information from various sources, I was able to draft a Request
  for Discussion (RFD) to start discussion on the net.
 
As I have the impression that the opinions have been stated and that further
discussion will not yield substantial new insights, I would like to go ahead by
posting the RFD here. In a separate post, I'm trying to summarize the
objections to newsgroup creation that have been made, and try to answer them.
 
Feel free to comment on these posts by (preferably) replying to me or, if you
think it is beneficial for the discussion, by replying to the LitProg mailing
list. Unless massive objections are made, I will post this RFD to the
newsgroups mentioned by the end of this week thereby initiating the Usenet
discussion.
 
Matthias
 
-----
Matthias Neeracher                                      neeri@iis.ee.ethz.ch
 "Neeracher can and no doubt will perform the usual cheerleader duties."
              -- ataylor@nmsu.edu in <ATAYLOR.92Dec8135851@gauss.nmsu.edu>
 
From Matthias Sun Jul 18 21:02:11 +0200 1993
Date: Sun, 18 Jul 1993 21:02:11 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.EDU
Subject: Newsgroup creation 2 of 3: Draft RFD
 
Remarks:
 
- The RFD will be posted to
      news.announce.newgroups
      news.groups
      comp.programming
      comp.software-eng
      comp.text.tex
 
- The information presented here has been compiled from information provided
  by
      George D. Greenwade <bed_gdg@SHSU.edu>
      Marcus Speh         <marcus@x4u.desy.de>
      David B. Thompson   <dthompson@coe2.coe.ttu.edu>
 
  any remaining errors are of course mine.
 
      Request for Discussion: comp.programming.literate
      -------------------------------------------------
 
Proposed name:              comp.programming.literate
Proposed moderation status: unmoderated
 
Proposed Charter: A forum for the discussion of issues related
   to literate programming.
 
(1) To discuss the merits of the currently existing literate
    programming tools.
 
(2) To discuss the design of new literate programming tools.
 
(3) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
Background: What is Literate Programming?
 
Literate programming is the combination of documentation and source
together in a fashion that is readable to human beings.  It was
created by D.E. Knuth during the development of his TeX typsetting
software.
 
Knuth's original work revolved around a particular literate programming
tool called WEB.  Knuth says:
 
     The philosophy behind WEB is that an experienced system
     programmer, who wants to provide the best possible
     documentation of his or her software products, needs two
     things simultaneously: a language like TeX for formatting,
     and a language like C for programming.  Neither type of
     language can provide the best documentation by itself; but
     when both are appropriately combined, we obtain a system
     that is much more useful than either language separately.
 
     The structure of a software program may be thought of as a
     web that is made up of many interconnected pieces.  To
     document such a program we want to explain each individual
     part of the web and how it relates to its neighbours. The
     typographic tools provided by TeX give us an opportunity to
     explain the local structure of each part by making that
     structure visible, and the programming tools provided by
     languages such as C or Fortran make it possible for us to
     specify the algorithms formally and unambigously. By
     combining the two, we can develop a style of programming
     that maximizes our ability to perceive the structure of a
     complex piece of software, and at the same time the
     documented programs can be mechanically translated into a
     working software system that matches the documentation.
 
Existing Resources
 
The mailing list LitProg@SHSU.EDU has existed for about a year. There
are currently more than 300 subscribers and an average of about 80
messages (corresponding to about 150K of traffic) per month in the
first 6 months of this year.
 
If a newsgroup is created, mechanisms are already in place to support
a mirrored gateway between it and the existing mailing list.  For
reference purposes, the newsgroup will be fully archived by the host
sponsoring the mailing list.
 
Discussion
 
Discussion should be confined to news.groups. Please do not post
responses to any other groups. Discussions may also be e-mailed to
neeri@iis.ee.ethz.ch if posting is not possible.
 
Assuming there is a consensus that the group comp.programming.literate
should be created, voting will start 21 days from the first posting
date of this request.  Voting instructions will be published in a Call
for Votes to the same newsgroups that see this Request for Discussion.
Both this Request for Discussion and the Call for Votes will be
crossposted to the "litprog@shsu.edu" mailing list.
 
From Matthias Sun Jul 18 21:04:20 +0200 1993
Date: Sun, 18 Jul 1993 21:04:20 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Newsgroup Creation 3 of 3: Addressing the Objections
 
In this article, I would like to address the arguments against the creation
of a newsgroup that have been mentioned in the discussion of the past two
weeks. LitProg in this article refers to the discussion about literate
programming, either by mail or by news. Questions/concerns are prefixed by
">". Where I have quoted verbatim, I have attributed the quote,
non-attributed quotes are paraphrased by me.
 
It has been my impression that responses fell mostly into two groups:
 
- Users who prefer news, and who will switch to reading LitProg by news if
  a newsgroup is created.
- Users who prefer email, and who will continue to read LitProg by mail, even
  if a newsgroup is created.
 
I would like to address these two groups separately, and since I think that
the News people are easier to convince, I start with them.
 
QUESTIONS OF NEWS USERS:
 
> What do I gain from the creation of comp.programming.literate ?
 
- Newsreaders are more efficient at reading many articles, or at skipping
  over them.
- Newsreaders can thread articles by subject, allowing you to get a better
  overview of a discussion.
- A newsgroup is likely to attract more contributors to LitProg, and to
  raise awareness of Literate Programming in the net community.
 
Peter Schmitt writes:
> mail appears automatically in the mailbox and thus alerts me that some
> discussion is going on, while a newsgroup has to be selected actively. And
> if - for some period - there is no discussion going on, the newsgroup will
> not be checked regularly, thus discussion will slow down, and - maybe -
> some thread will even die out prematurely.
 
In my experience, most newsreaders have a set of "active" newsgroups, i.e.,
even if c.p.l should fall silent for two weeks, most users who are
subscribed to the group will automatically notice if messages start to
appear again.
 
Chuck D'Antonio writes:
>Everyone is most concerned with having both the group and the list
>connected, but for those who are interested in a newsgroup to maintain a
>subscription to the mail list wouldn't keep them from reading the news.
 
I don't think this is such a good idea. It is true that this solves the
problem of mailing list readers getting inappropriate traffic, but this also
keeps *appropriate* traffic from them. Even readers of both would probably
see interesting threads split across both media. Additionally, this solution
does not help with the traffic on the mailing list: it still won't be possible
to use a newsreader there.
 
Chuck D'Antonio writes:
>Maybe an alt group in tandem with an active mailing list would give
>everyone a better feel for which is more appropriate. Or both could
>develop their own charracter and the alt group could become a comp group
>with the list still surviving.
 
Experience shows that it is virtually impossible to get rid of an alt group
once it is created. Also, I don't see the necessity of an alt group as a proof
that the LitProg debate is serious and lively enough to deserve a group: The
mailing list has shown this clearly enough.
 
QUESTIONS OF MAIL USERS:
 
> What do I gain from the creation of comp.programming.literate ?
 
A newsgroup is likely to attract more contributors to LitProg, and to
raise awareness of Literate Programming in the net community.
 
> Won't the Signal-to-Noise ratio of a newsgroup be significantly
> worse than for a mailing list? 
 
I think this is the crucial concern for mail users, and I wish I could
give an autoritative and reliable prediction to this, but I'm afraid I
can't. I have some reasons to belive, though, that the noise will not
increase significantly. Noisy groups are usually characterized by
 
 - High volume
 - A subject that many people intuitively feel competent in
 - The dominant contributors have a tendency to turn technical
   arguments into flame wars.
 
None of this is likely to be true for comp.programming.literate:
 
 - The current volume (2.6 messages a day) is comparable to the following
   comp groups:
 
      2.42 comp.databases.pick
      2.42 comp.os.research
      2.50 comp.os.mach
      2.50 comp.theory.dynamic-sys
      2.58 comp.ai.fuzzy
      2.58 comp.lang.clos
      2.58 comp.protocols.kerberos
      2.58 comp.sys.ibm.pc.demos
      2.58 comp.windows.suit
      2.67 comp.binaries.mac
      2.67 comp.os.os9
      2.75 comp.sys.amiga.introduction
      2.75 comp.sys.ti
      2.83 comp.compression.research
      2.83 comp.edu
      2.83 comp.infosystems.wais
      2.83 comp.protocols.snmp
      3.00 comp.lang.vhdl
      3.00 comp.os.os2.networking
      3.00 comp.soft-sys.nextstep
      3.17 comp.lang.modula2
 
   In comparison, noisy groups like comp.lang.c have almost 60 posts a day
   and comp.os.linux has even 160 posts a day. Even comp.text.tex with
   more than 40 posts a day has a relatively decent S/N ratio.
 
 - It is rather unlikely that as many people intuitively feel
   competent in LitProg as in politics, sex, economics, or C, to
   name a few noisy topics.
 
 - The dominant authorities on LitProg so far all have shown civilized
   behaviour, and, assuming they will continue to contribute, there is
   no reason to assume they suddenly will turn nasty :-)
 
On the other hand, while I don't expect from the newsgroup much
inappropriate traffic, I expect that the amount of *appropriate*
traffic will increase through the creation of a newsgroup, and you might
see that as a disadvantage.
 
> Isn't a newsgroup less reliable than a mailing list?
 
I might be at a privileged site, but here, there is no noticeable
difference. As an experiment, our news administrator (thanks, Andi
Karrer!) compared three days of traffic in comp.lang.c between
csd-newshost.stanford.edu and bernina.ethz.ch, which have quite
different feeds and a considerable number of hops between them. All
174 articles he saw had arrived at both hosts!
 
> Will we lose full archiving of the mailing list?
 
No. Thanks to the efforts of George Greenwade, we will have a gateway
between mailing list and newsgroup, and an archive of all the traffic
on both.
 
Norman Ramsey writes:
>If I believed we could sell literate programming to a wide audience,
>I would be in favor of a newsgroup, but I don't think the tools or techniques
>(especially not the techniques) have reached that stage yet, so I prefer
>to stay in a ghetto if possible.
 
While I certainly cannot dispute Norman's experience and judgement on
this point, I think he is somewhat too pessimistic. In my opinion, the
mailing list has already been a considerable success in
 
 - Demonstrating that interest in LitProg is alive.
 - Bringing practicioners and implementers of LitProg together.
 - Intensifying debate about LitProg techniques.
 
I hope that a newsgroup can in a first stage reach more people to
further the above goals, especially as a newsgroup is easier for the
casual reader to handle.
 
From humberto@annexstein.csm.uc.EDU Sun Jul 18 21:38:13 -0400 1993
Date: Sun, 18 Jul 1993 21:38:13 -0400 (EDT)
From: humberto@annexstein.csm.uc.EDU (Humberto Ortiz Zuazaga)
Reply-To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
To: LitProg@SHSU.EDU
Subject: standard web front end, texinfo web, et. al
 
   X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
   Date: Sun, 18 Jul 93 14:36:25 EDT
   From: Lee Wittenberg <leew@pilot.njin.net>
   fancy typesetting tools.''  I was wrong.  I find it more productive
   to give up my source debuggers in favor of LP tools than vice
   versa.
 
I use gdb on some 45 pages of noweb C source without any problems. One
thing that I did need to get used to was jumping around from module to
module, as it looks like a function call from the top level but the
debugger only sees inline code.  This might even be fixed by adding
additional #line directives (i.e., bracket module expansions with the
#line of the module invocation.)
 
With xemacs and linux this is one very nice debugging setup. (Not that
my code _ever_ needs any debugging :-)
--
Humberto Ortiz Zuazaga                                zuazaga@ucunix.san.uc.edu
 
From Richard Mon Jul 19 11:48:10 +1000 1993
Date: Mon, 19 Jul 1993 11:48:10 +1000
From: Richard Walker <Richard.Walker@cs.anu.edu.au>
Reply-To: LitProg@SHSU.edu, Richard.Walker@CS.ANU.EDU.AU
To: LitProg@SHSU.edu
Subject: Still searching for Modula-2!!!
 
Hi all.  I'm still searching for a Modula-2 WEB.
It looks like Sewell's version is not going to be
up to the task, and Joachim's version doesn't have
a change file for Unix.
 
So, does anyone have a Spider description?  I thought
I heard about one for Modula-3.  I'd be delighted
to hear from anyone who has a Spider description for
either Modula-2 or Modula-3 - but especially the former.
 
Richard.
 
From Yves Mon Jul 19 09:37:36 +0200 1993
Date: Mon, 19 Jul 1993 09:37:36 +0200
From: Yves Arrouye <Yves.Arrouye@imag.fr>
Reply-To: LitProg@SHSU.edu, Yves.Arrouye@IMAG.FR
To: LitProg@SHSU.edu, dak@pool.informatik.rwth-aachen.de
Subject: Re: unsuscribe litprog
 
>If Literate Programming wishes to address a suitable audience (and a good
>technique should be shared so that a broad base may benefit in the long
>run) I think it should not balk at leaving the closet.
>
>Count me in for newsgroups.
 
Count me in too. I like Literate Programming, I used it and will use
it again, but I can't stand having my mailbox cluttered everyday. A
newsgroup will *really* be better.
 
Yves.
 
P.S.: sorry for the bad address when unsuscribing...
 
-- 
With one processor, we verify that the time spent                  Yves Arrouye
      in controlling parallelism is not too long.       arrouye@mistral.imag.fr
                                                           arrouye@imag.imag.fr
                        -- Yannick Tre'molet, LMC              (33) 76 57 48 61
 
From Eric Mon Jul 19 08:50 +0000 1993
Date: Mon, 19 Jul 1993 08:50 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: Newsgroup creation 2 of 3: Draft RFD
 
What does the abbreviation "RDF" mean????
 
From Joachim Mon Jul 19 12:37:07 +0100 1993
Date: Mon, 19 Jul 1993 12:37:07 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu, neeri@iis.ee.ethz.ch
Subject: Re: Newsgroup creation 2 of 3: Draft RFD
 
[I thought this is of more general interest.]
 
Matthias wrote in the proposed c.p.l charter
> 
> Knuth's original work revolved around a particular literate programming
> tool called WEB.  Knuth says:
> 
>      The philosophy behind WEB is that an experienced system
>      programmer, who wants to provide the best possible
>      documentation of his or her software products, needs two
>      things simultaneously: a language like TeX for formatting,
>      and a language like C for programming.  Neither type of
>      language can provide the best documentation by itself; but
>      when both are appropriately combined, we obtain a system
>      that is much more useful than either language separately.
> 
>      The structure of a software program may be thought of as a
>      web that is made up of many interconnected pieces.  To
>      document such a program we want to explain each individual
>      part of the web and how it relates to its neighbours. The
>      typographic tools provided by TeX give us an opportunity to
>      explain the local structure of each part by making that
>      structure visible, and the programming tools provided by
>      languages such as C or Fortran make it possible for us to
>      specify the algorithms formally and unambigously. By
>      combining the two, we can develop a style of programming
>      that maximizes our ability to perceive the structure of a
>      complex piece of software, and at the same time the
>      documented programs can be mechanically translated into a
>      working software system that matches the documentation.
 
I don't like the binding to WEB tools. As it was addressed here more
than once, the available tools are not quite state-of-the-art,
compared to other programming environments. In addition, IMO TeX is
mentioned too often -- and many people already have the opinion that
one can't do LitProg without TeX. Let's note promote this erroneous
opinion further.
 
I think better quotes may be found in the _Literate Programming_
article of DEK. Something along
 
    \begin{quote}
    \noindent Let us change our traditional attitude to the construction
    of programs: Instead of imagining that our main task is to
    instruct a {\it computer\/} what to do, let us concentrate
    rather on explaining to {\it human beings\/} what we want
    to do.
 
    The practitioner of literate programming can be regarded
    as an essayist, whose main concern is with exposition and
    excellence of style. Such an author, with thesaurus in hand,
    chooses the names of variables carefully and explains what
    each variable means. [\dots]
    \end{quote}
 
    \rightline{\it D. E. Knuth, 1984}
 
Especially the first paragraph gives IMO a better view on the
paradigm, independent from the tools. The quote above is taken from
the article's introduction, the very first paragraph of this
introduction also might contribute to a charter. If there are many
people who don't have this article, and if there is enough interest,
I might send the complete introduction to this mailing list.
 
Btw, the full article is available from the Literate Programming Archive:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/Documentation
	file knuth.literate-programming.tar.Z
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From mpalma@usb.ve Mon Jul 19 12:59:18 -500 1993
Date: Mon, 19 Jul 1993 12:59:18 -500
From: mpalma@usb.ve (Prof. Marcos E. Palma Marin)
Reply-To: LitProg@SHSU.edu, mpalma@USB.VE
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: Re: Newsgroup creation 2 of 3: Draft RFD
 
Please!  Send me again "Newsgroup creation 1 of 3: Draf RFD"
         I only receive 2 of 3 and 3 of 3.
 
Thanks in advance
---------------------------------------------------------------------
Prof. Marcos E. Palma M.     |  Eng. Marcos E. Palma M.
Dpto.Procesos y Sistemas     |  Centro de Informatica y Comunicaciones
Universidad Simon Bolivar    |  Universidad Simon Bolivar
Valle de Sartenejas          |  Valle de Sartenejas
CARACAS-VENEZUELA            |  CARACAS-VENEZUELA
Apto. Postal 89000           |  Apto. Postal 89000
---------------------------------------------------------------------
Phone:  (58) (2) 963-3022    |  e-mail: mpalma@usb.ve
         Ext 3920, 3922      |
FAX:    (58) (2) 93-8420     |
---------------------------------------------------------------------
 
From George Mon Jul 19 11:30:20 CST 1993
Date: Mon, 19 Jul 1993 11:30:20 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
Subject: Re: Newsgroup creation 2 of 3: Draft RFD
 
On Mon, 19 Jul 1993 08:50 +0000 (GMT), Eric W. van Ammers
<AMMERS@RCL.WAU.NL> posted:
> What does the abbreviation "RDF" mean????
 
The term "RFD" is short for "Request for Discussion" -- a necessary first
step in the process of creating a newsgroup on USENET.  It gets posted to
the lists intended for discussing the topic (as well as news.groups and
news.announce, generally).  Once the discussion period ends (which, to the
best of my knowledge, has no specified time table), a "CFV" -- short for
"Call for Votes" is issued.  The CFV time period is well-specified as 21
days (unless some rare and justifiable reason can be provided for
modification of this).  At the end of the CFV period, the person who is
responsible for counting and verifying votes (by no means trivial as you
can change your vote so long as it is within the specified time period)
reports back if the vote has met the guidelines for the creation of a new
newsgroup (again, as a very rough rule, at least 100 votes total must be
involved with at least 2/3 in favor of creation).
 
--George
 
From mbrown@athos.cs.ua.edu Mon Jul 19 13:18:37 -0500 1993
Date: Mon, 19 Jul 1993 13:18:37 -0500 (CDT)
From: mbrown@athos.cs.ua.edu (Marcus Brown)
Reply-To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU
To: LitProg@SHSU.edu
Subject: Experience with a WEB source level debugger
 
Bryan D. Oakley writes:
 
> ... text omitted ...  
> 	Talks about the need for the debugger to work with the
> 	WEB source code, not the tangled, unreadable garbage.
> 
> I see web systems as truely an improvement when the tangled code is
> merely a byproduct, and there are sufficient tools to allow one to
> work with the original source in all phases of development.  Why
> should I code in one language (a web system), then debug in another (a
> traditional language)?
> 
 
It was a few years ago now, but I was writing CWEB on a Sun workstation.
Sun provided a graphical 'dbxtool', which merely put a graphical
front end on the 'dbx.'  The good thing about it was that it followed the
'#line' declarations in the tangled C code, and showed the actual CWEB
source code in the 'source code' window.
 
I would think that any tool which followed the '#line' declarations would
be able to do this with a minimum of trouble.
 
One problem I ran into:  I had a particular section which (like a good
general purpose section should) was plugged into several different sections.
That is, I needed to @<Normalize the data@> in several places, so that
section was used several times.  Trying to debug that section caused a
problems:  When I placed a break point in the section, 'dbx' wouldn't stop
there! I tried it several times, putting breakpoints before and after
the section was 'called' ... It just wouldn't stop inside of that section!
Finally I set a breakpoint just before the section, then stepped through
one line at a time... This worked fine, and I figured out my bug.
 
The question that remained was: Why wouldn't 'dbx' honor the breakpoint
I set in that section?
 
"This exercise is left to the reader..."
Just for fun, I'll let you think about it for a while, then give
the answer in a few days...
 
Anyway, my experience showed that an 'off-the-shelf' debugger CAN
be used to show the WEB source code, with only a few minor problems.
 
-- 
Marcus Brown
mbrown@cs.ua.edu
Computer Science Dept, Univ of Alabama
 
From norman@bellcore.com Mon Jul 19 14:26:13 -0400 1993
Date: Mon, 19 Jul 93 14:26:13 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu
Subject: Re: proposed charter of newsgroup
 
Joachim Schrod writes about the proposed charter:
> I don't like the binding to WEB tools. As it was addressed here more
> than once, the available tools are not quite state-of-the-art,
> compared to other programming environments. In addition, IMO TeX is
> mentioned too often -- and many people already have the opinion that
> one can't do LitProg without TeX. Let's note promote this erroneous
> opinion further.
> ...
> The quote above is taken from
> the article's introduction, the very first paragraph of this
> introduction also might contribute to a charter. 
 
I agree completely.  I think also that any charter should take a
paragraph or two to summarize Thimbleby's criteria for
literate-programming systems (June 1989 CACM, pp 752-755).
 
Norman Ramsey
 
From Matthias Mon Jul 19 22:28:03 +0200 1993
Date: Mon, 19 Jul 1993 22:28:03 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: proposed charter of newsgroup
 
In message <9307191826.AA10801@mailee.bellcore.com> you write:
>Joachim Schrod writes about the proposed charter:
>> I don't like the binding to WEB tools. As it was addressed here more
>> than once, the available tools are not quite state-of-the-art,
>> compared to other programming environments. In addition, IMO TeX is
>> mentioned too often -- and many people already have the opinion that
>> one can't do LitProg without TeX. Let's note promote this erroneous
>> opinion further.
>> ...
>> The quote above is taken from
>> the article's introduction, the very first paragraph of this
>> introduction also might contribute to a charter. 
>
>I agree completely.  I think also that any charter should take a
>paragraph or two to summarize Thimbleby's criteria for
>literate-programming systems (June 1989 CACM, pp 752-755).
 
Thanks for the suggestion. I had already decided after seeing Joachims
article that the paragraph as present had to be modified. I have snarfed
the CACM article you suggested (Which was, thanks to WAIS, rather painless),
and I will take a close look at it tomorrow.
 
I assume that by "criteria" you mean passages as the following?
 
Literate programming encourages a programmer to elaborate his program with
documentation, and presents the program nicely, in a form conducive to
reading.  These should be a single source document (or file) containing both
documentation and program.  Program and documentation can be developed
concurrently in the same place, without overhead [...]
 
Matthias
 
-----
Matthias Neeracher                                  neeri@iis.ee.ethz.ch
  "And that's why I am going to turn this world upside down, and make
   of it a fire so *bright* that someone real will notice"
                                -- Vernor Vinge, _Tatja Grimm's World_
 
From ctrbdo@oak.iapa.uucp Mon Jul 19 17:00:47 CDT 1993
Date: Mon, 19 Jul 93 17:00:47 CDT
From: ctrbdo@oak.iapa.uucp (bryan d oakley)
Reply-To: LitProg@SHSU.edu, ctrbdo@OAK.IAPA.UUCP
To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU
Subject: Experience with a WEB source level debugger
 
>>>>> Marcus Brown writes:
=> Bryan D. Oakley writes:
 
> ... text omitted ...  
> 	Talks about the need for the debugger to work with the
> 	WEB source code, not the tangled, unreadable garbage.
> 
> I see web systems as truely an improvement when the tangled code is
> merely a byproduct, and there are sufficient tools to allow one to
> work with the original source in all phases of development.  Why
> should I code in one language (a web system), then debug in another (a
> traditional language)?
> 
 
=> It was a few years ago now, but I was writing CWEB on a Sun workstation.
=> Sun provided a graphical 'dbxtool', which merely put a graphical
=> front end on the 'dbx.'  The good thing about it was that it followed the
=> '#line' declarations in the tangled C code, and showed the actual CWEB
=> source code in the 'source code' window.
 
=> I would think that any tool which followed the '#line' declarations would
=> be able to do this with a minimum of trouble.
 
*sigh*  Context is being lost here.  I am aware of what the #line
directives do, and also what dbxtool does.  However, I was refering to
WYSIWYG webs.  For example, if I web'ed using, say, WordPerfect,
dbxtool would have a veritable fit if it tried to display a
WordPerfect document in it's source window.  Non-WYSIWYG webs I
presume would pose no challenge to the average (or at least above
average) source code debugger.
 
{stuff deleted...}
=> Anyway, my experience showed that an 'off-the-shelf' debugger CAN
=> be used to show the WEB source code, with only a few minor problems.
 
Except, as mentioned, with WYSIWYG webs...
 
=> -- 
=> Marcus Brown
=> mbrown@cs.ua.edu
=> Computer Science Dept, Univ of Alabama
 
---------------------------------------------------------------------
Instrument Approach Procedures Automation             DOT/FAA/AMI-230
---------------------------------------------------------------------
Bryan D. Oakley                   ctrbdo%iapa@mailhost.ecn.uoknor.edu
KENROB and Associates, Inc.              voice: (405) 954-7176 (work)
5909 NW Expwy Suite 209                         (405) 366-6248 (home)
Oklahoma City, Ok.  73132            
 
From dak@POOL.Informatik.RWTH-Aachen.DE Tue Jul 20 11:49:47 +0200 1993
Date: Tue, 20 Jul 93 11:49:47 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, ctrbdo@OAK.IAPA
Subject: Re: Experience with a WEB source level debugger
 
As to source level debugging, and the inability of coping with WYSIWYG
LP systems: A REAL LP debugger would show the lines in the prepared
document, not in the WEB source. This could be an interesting challenge
for interface design: the source lines had to be \special led into
the .dvi-file, and the previewer had to react on messages of the
source code debugger and show the appropriate lines.
 
But with TeX WEBs we have at least the possibility of debugging based
on the WEB code. Remember though, that this is not the final
solution! And the problems to do "the real thing" with TeX WEBS
are about as complicated as with WYSIWYG, only that with TeX WEBs
and, say, xdvi, one COULD design a working solution given time and
work because the relevant sources (xdvi, gdb, tangle&weave) are all
available to the public, and open to discussion, whereas the WYSIWIG
approach of the more common editors would entail persuading the
producers of commercial systems to build in appropriate support.
 
And, of course, debbuging in the WEBs is a tolerable intermediate
solution.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From Joachim Tue Jul 20 11:18:09 +0100 1993
Date: Tue, 20 Jul 1993 11:18:09 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu
Subject: Re: proposed charter of newsgroup
 
Matthias wrote:
> 
> I assume that by "criteria" you mean passages as the following?
> 
> Literate programming encourages a programmer to elaborate his program with
> documentation, and presents the program nicely, in a form conducive to
> reading.  These should be a single source document (or file) containing both
> documentation and program.  Program and documentation can be developed
> concurrently in the same place, without overhead [...]
 
Another thought: When I asked DEK what the `essence' of Literate
Programming is for him, he answered (paraphrased):
 
``Technical Writing taught us that you have to say everything twice:
Once informal, in prose, with graphics, etc., to explain it. And once
formal to define it precisely. The intermix between `documentation
parts' and `code parts', i.e., between explanation and definition,
that is the essence.''
 
He explicitely recurred to Technical Writing as the discipline which
influenced him most concerning this topic.
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16 Jul 93
 
From humberto@annexstein.csm.uc.EDU Tue Jul 20 07:43:51 -0400 1993
Date: Tue, 20 Jul 1993 07:43:51 -0400 (EDT)
From: humberto@annexstein.csm.uc.EDU (Humberto Ortiz Zuazaga)
Reply-To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
To: LitProg@SHSU.EDU
Subject: Experience with a WEB source level debugger
 
   X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
   Warnings-To: <>
   Sender: LP-Mgr@SHSU.edu
   Date: Tue, 20 Jul 93 11:49:47 +0200
   From: dak@POOL.Informatik.RWTH-Aachen.DE
   Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
 
   As to source level debugging, and the inability of coping with WYSIWYG
   LP systems: A REAL LP debugger would show the lines in the prepared
   document, not in the WEB source. This could be an interesting challenge
 
This would be even more difficult than debugging in WYWSIWYG webs, as
you can't edit the .dvi (or .ps) file.
--
Humberto Ortiz Zuazaga                                zuazaga@ucunix.san.uc.edu
 
From dentato@minerva.ing.uniroma1.it Tue Jul 20 13:15:26 +0100 1993
Date: Tue, 20 Jul 1993 13:15:26 +0100 (DFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
Subject: Off-topic
 
>> [...] When I asked DEK what the `essence' of Literate Programming [...]
 
Sorry for the off topic but is there anybody out there that knows when
(if ever) we will see the other volumes of "Art of Computer
Programming"? I liked the first three and I'd like to have the others!
        ___ __
       //_/// \
      // \//__/   dentato@cadgroup.ing.uniroma1.it
     Remo Dentato
 
From Joachim Tue Jul 20 13:30:44 +0100 1993
Date: Tue, 20 Jul 1993 13:30:44 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.edu
Subject: Re: Off-topic
 
You wrote:
> 
> Sorry for the off topic but is there anybody out there that knows when
> (if ever) we will see the other volumes of "Art of Computer
> Programming"? I liked the first three and I'd like to have the others!
 
About 350 pages of Vol. 4 are written. He plans to prerelease them
RSN, in three volumes (A, B, and C). I don't remember the name of the
publication where this will happen.
 
He's confident that he'll write Vol. 5 soon. (His wife Jill commented
dryly that it will most probably never be written... She also told
about the start of the series: He wanted to write them in their
honeymoon, as a short-term project. But he denies it, according to
him he planned for three months after the honeymoon. :) Doesn't that
remind anybody of other projects of him? :) :)
 
-- 
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Anselm Tue Jul 20 14:32:50 +0100 1993
Date: Tue, 20 Jul 93 14:32:50 +0100
From: Anselm Lingnau <lingnau@math.uni-frankfurt.de>
Reply-To: LitProg@SHSU.edu, lingnau@MATH.UNI-FRANKFURT.DE
To: LitProg@SHSU.edu, humberto@ANNEXSTEIN.CSM.UC.EDU
Subject: Re: Experience with a WEB source level debugger
 
Humberto Ortiz Zuazaga (humberto@annexstein.csm.uc.EDU) writes in answer to
David Kastrup (dak@POOL.Informatik.RWTH-Aachen.DE), who said:
 
>    As to source level debugging, and the inability of coping with WYSIWYG
>    LP systems: A REAL LP debugger would show the lines in the prepared
>    document, not in the WEB source. This could be an interesting challenge
> 
> This would be even more difficult than debugging in WYWSIWYG webs, as
> you can't edit the .dvi (or .ps) file.
 
It shouldn't be too difficult just to *show* the lines in the prepared
document, given a previewer that is smart enough. I suppose a DVI previewer
with a suitable Tcl/Tk interface would come in very helpful here.
 
Of course, then you'd also like to have a debugger and editor which use
Tcl/Tk so that they can interact. For instance, if you single-step through a
program, the DVI document and the ASCII source will scroll in sync to always
display the line that's being executed.
 
But once we're all programming literately, we'll be able to understand all
our programs a lot better, and after a while, the code we write will be
working right off the bat, so we won't need debuggers anymore. Or will we? :-)
 
Anselm
--
Anselm Lingnau .................................. lingnau@math.uni-frankfurt.de
[The] Internet is so big, so powerful and pointless that for some people it is
a complete substitute for life.                                --- Andrew Brown
 
From infmx!quivira!grodecki@uunet.UU.NET Tue Jul 20 09:51:19 CDT 1993
Date: Tue, 20 Jul 93 09:51:19 CDT
From: infmx!quivira!grodecki@uunet.UU.NET (Don Grodecki)
Reply-To: LitProg@SHSU.edu, infmx!quivira!grodecki@UUNET.UU.NET
To: uunet!SHSU.edu!LitProg@uunet.UU.NET
Subject: source level debugger
 
> I would think that any tool which followed the '#line' declarations would
> be able to do this with a minimum of trouble.
> 
 .......
 
> Anyway, my experience showed that an 'off-the-shelf' debugger CAN
> be used to show the WEB source code, with only a few minor problems.
> 
> 
> -- 
> Marcus Brown
> mbrown@cs.ua.edu
> Computer Science Dept, Univ of Alabama
> 
> 
 
In the same fashion those using WYSIWYG Webs should be able to have an
untangled ASCII version of their Webs show up in the debugger.  This ASCII
file dumped from the Web could be used as the input to "tangle".  This would
be almost as good as seeing the Web itself, as the debugger source view is
usually "read-only" anyway.
 
From kcousins@echidna.rp.CSIRO.AU Wed Jul 21 09:51:27 +1000 1993
Date: Wed, 21 Jul 93 09:51:27 +1000
From: kcousins@echidna.rp.CSIRO.AU
Reply-To: LitProg@SHSU.edu, kcousins@ECHIDNA.RP.CSIRO.AU
To: LitProg@SHSU.edu
Subject: Re: source level debugger
 
Don Grodecki writes:
> In the same fashion those using WYSIWYG Webs should be able to have an
> untangled ASCII version of their Webs show up in the debugger.  This ASCII
> file dumped from the Web could be used as the input to "tangle".  This would
> be almost as good as seeing the Web itself, as the debugger source view is
> usually "read-only" anyway.
 
Here, here! Is there not a utility called 'detex'? I had occasion to use this 
years ago, so that my thesis could be run through spelling and grammar checkers 
without the TeX macros appearing.
 
It seems a trivial matter to detex the 'woven' WEB to get a plain ascii version 
of the final document, which I should expect would be a great way to see the 
thing in a source level debugger. Any ideas for coordinating '#line's?
 
--
________________________________________________________________________
    Kevin Cousins  |  kcousins@rp.csiro.au   | Ph: +61 2 868 0425
                                              Fax: +61 2 868 0490
 
      _--_|\     _   _   . _   _      CSIRO / Division of Radiophysics
     /      \   / ` ( ` / /_) / )     Cnr Vimiera & Pembroke Rds
     \_.--\_*  (_, ._) / / \ (_/      Marsfield  NSW  2121
           v                          Sydney, AUSTRALIA
------------------------------------------------------------------------
 
From vieth@convex.rz.uni-duesseldorf.de Wed Jul 21 15:48:36 +0200 1993
Date: Wed, 21 Jul 93 15:48:36 +0200
From: vieth@convex.rz.uni-duesseldorf.de (Ulrik Vieth                )
Reply-To: LitProg@SHSU.edu, vieth@CONVEX.RZ.UNI-DUESSELDORF.DE
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: Re:  Newsgroup creation 1 of 3: Overview
 
Matthias Neeracher wrote:
> 
> Feel free to comment on these posts by (preferably) replying to me or, if you
> think it is beneficial for the discussion, by replying to the LitProg mailing
> list. Unless massive objections are made, I will post this RFD to the
> newsgroups mentioned by the end of this week thereby initiating the Usenet
> discussion.          ^^^^^^^^^^^^^^^^^^^^^^^
 
Hello,
 
it just came to my mind, that the end of this week might not be the ideal
date to start the newsgroup creation process, since several of the most
prominent LitProgers will probably be away next week for the TUG meeting 
in Aston. So if any serious questions or objections are raised on Usenet,
the absence of the `in-crowd' might give us a bad start. Maybe we should
delay the RfD just another week, don't you think?
 
Anyway, I'm in favor of a newsgroup since the mail load on LitProg makes
mail handling rather cumbersome when reading it only once a week during
the holiday period. So you can expect a yes vote from me. 
 
Greetings,
 
Ulrik Vieth
--
Ulrik Vieth, HHU Duesseldorf 	<vieth@convex.rz.uni-duesseldorf.de>
 
``Some day we will have personal computers and live more normally.''
	-- Donald E. Knuth, `The Errors of TeX', 14 March 1978
 
From norman@bellcore.com Wed Jul 21 10:12:11 -0400 1993
Date: Wed, 21 Jul 93 10:12:11 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, kcousins@ECHIDNA.RP.CSIRO.AU
Subject: Re: source level debugger
 
> Here, here! Is there not a utility called 'detex'? I had occasion to use this
 
> years ago, so that my thesis could be run through spelling and grammar checke
  rs 
> without the TeX macros appearing.
> 
> It seems a trivial matter to detex the 'woven' WEB to get a plain ascii versi
  on 
> of the final document, which I should expect would be a great way to see the 
> thing in a source level debugger. 
 
detex is unsuitable for this purpose; look at the output sometime.
dvi2tty would be much better.
 
it would be an interesting exercise to build a literate-program viewer
along the lines of Marcus Brown's work but showing the *output* of TeX
instead of the (unreadable) input---an essential property in my view.
Coordinating such a viewer with a debugger would not be difficult.
One approach that would be relatively easy to implement in noweb would
be to make a special TeX run in which each documentation chunk appears
on a single, arbitrarily large page.  The viewer could then display
these chunks using standard dvi technology, but could display code
chunks in simple ASCII, properly associated with source-line numbers
for easy debugging.
 
A propos of debugging, planting breakpoints with replicated chunks is
isomorphic to function inlining, and it breaks most debuggers---but
not ldb! (small ad for my dissertation project :-).
 
Norman
 
From Lee Wed Jul 21 16:40:10 EDT 1993
Date: Wed, 21 Jul 93 16:40:10 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, Richard.Walker@cs.anu.edu.au
Subject: Re: Still searching for Modula-2!!!
 
Richard Walker asks:
 
> Hi all.  I'm still searching for a Modula-2 WEB.
> It looks like Sewell's version is not going to be
> up to the task, and Joachim's version doesn't have
> a change file for Unix.
> 
> So, does anyone have a Spider description?  I thought
> I heard about one for Modula-3.  I'd be delighted
> to hear from anyone who has a Spider description for
> either Modula-2 or Modula-3 - but especially the former.
 
I don't know of a Spider grammar for M-2 or M-3, but they shouldn't
be too hard to write if you want to tackle it yourself.  The Modulas
are ``small'' languages without too many keywords or constructs.  I
was playing around with a grammar for Oberon (Wirth's latest) for a
while.  It would have been quite straightforward (if I had ever
actually gone to the trouble to get it working!).
 
		-- Lee
 
From Matthias Wed Jul 21 22:49:34 +0200 1993
Date: Wed, 21 Jul 1993 22:49:34 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@shsu.edu
Subject: RFD, 2nd iteration, 1 of 2: Overview
 
My first draft of the RFD was justly criticized for being much too
WEB/TeX-heavy, so I tried to rewrite the background section along the
suggestions of Joachim Schrod and Norman Ramsey.
 
I would welcome any suggestions about what programming languages and
documentation systems should be added to the list (Am I right about
Framemaker being supported, BTW?).
 
Because of the substantial rewrite, I will probably wait a few days
longer to post the RFD to the net, and since it has to be approved by a
moderator first, it will most likely appear by the end of *next* week.
 
If the proposal should get to vote, I managed to secure the services of
an universally respected vote taker, so the actual vote should proceed
smoothly.
 
Comments welcome, preferably to me, if necessary to the list.
 
Matthias
 
-----
Matthias Neeracher                                  neeri@iis.ee.ethz.ch
  "And that's why I am going to turn this world upside down, and make
   of it a fire so *bright* that someone real will notice"
                                -- Vernor Vinge, _Tatja Grimm's World_
 
From Matthias Wed Jul 21 22:49:37 +0200 1993
Date: Wed, 21 Jul 1993 22:49:37 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@shsu.edu
Subject: RFD, 2nd iteration, 2 of 2: Draft RFD
 
Remarks:
 
- The RFD will be posted to
      news.announce.newgroups
      news.groups
      comp.programming
      comp.software-eng
      comp.text.tex
 
- The information presented here has been compiled from information provided
  by
      George D. Greenwade <bed_gdg@SHSU.edu>
      Marcus Speh         <marcus@x4u.desy.de>
      David B. Thompson   <dthompson@coe2.coe.ttu.edu>
      Joachim Schrod 	  <schrod@iti.informatik.th-darmstadt.de>
      Norman Ramsey       <norman@bellcore.com>
 
  any remaining errors are of course mine.
 
- Feedback by email is, as always, welcome.
 
      Request for Discussion: comp.programming.literate
      -------------------------------------------------
 
Proposed name:              comp.programming.literate
Proposed moderation status: unmoderated
 
Proposed Charter: A forum for the discussion of issues related
   to literate programming.
 
(1) To discuss the merits of the currently existing literate
    programming tools.
 
(2) To discuss the design of new literate programming tools.
 
(3) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
Background: What is Literate Programming?
 
In an article published in _The Computer Journal_ 27 (1984), 97-111,
Donald E. Knuth proposed a "literate" programming style:
 
     Let us change our traditional attitude to the construction of
     programs: Instead of imagining that our main task is to instruct
     a *computer* what to do, let us concentrate rather on explaining
     to *human beings* what we want a computer to do.
 
     The practitioner of literate programming can be regarded as an
     essayist, whose main concern is with exposition and excellence of
     style. Such an author, with thesaurus in hand, chooses the names
     of variables carefully and explains what each variable means. He
     or she strives for a program that is comprehensible because its
     concepts have been introduced in an order that is best for human
     understanding, using a mixture of formal and informal methods that
     reinforce each other.
 
A literate programming system can be characterized by the following
properties:
 
 - The compilable program and the publishable documentation should be
   generated *automatically* from a *single* document.
 
 - The program can be presented in the order that is best for human
   understanding, regardless of any requirements of the programming
   language.
 
 - The program should be automatically indexed and cross-referenced.
 
Knuth's original system, called WEB, generated Pascal code and a TeX
documentation. Most tools relating to the TeX system have been written
using WEB, and the TeX and Metafont programs have been published in book
form.
 
Today, there are literate programming systems for a wide range of
programming languages and documentation systems. Specialized literate
programming tools have been written for Ada, Awk, C, C++, Fortran,
Modula-2, Pascal and Scheme, and generic tools exist that can generate
almost any programming language (including Perl and sh).
 
Documentation systems supported include TeX, Troff, Framemaker, and
Word for Windows.
 
Existing Resources
 
The mailing list LitProg@SHSU.EDU has existed for about a year. There
are currently more than 300 subscribers and an average of about 80
messages (corresponding to about 150K of traffic) per month in the
first 6 months of this year.
 
If a newsgroup is created, mechanisms are already in place to support
a mirrored gateway between it and the existing mailing list.  For
reference purposes, the newsgroup will be fully archived by the host
sponsoring the mailing list.
 
Discussion
 
Discussion should be confined to news.groups. Please do not post
responses to any other groups. Discussions may also be e-mailed to
neeri@iis.ee.ethz.ch if posting is not possible.
 
Assuming there is a consensus that the group comp.programming.literate
should be created, voting will start 21 days from the first posting
date of this request.  Voting instructions will be published in a Call
for Votes to the same newsgroups that see this Request for Discussion.
Both this Request for Discussion and the Call for Votes will be
crossposted to the "litprog@shsu.edu" mailing list.
 
From kahl@informatik.unibw-muenchen.de Thu Jul 22 09:13:59 +0200 1993
Date: Thu, 22 Jul 93 09:13:59 +0200
From: kahl@informatik.unibw-muenchen.de (Wolfram Kahl)
Reply-To: LitProg@SHSU.edu, kahl@INFORMATIK.UNIBW-MUENCHEN.DE
To: LitProg@shsu.edu, neeri@IIS.EE.ETHZ.CH
Subject: Re: RFD, 2nd iteration, 2 of 2: Draft RFD
 
Hallo,
 
  after the "Background" section in the revised RFD has been liberated from
too much TeX/WEB heaviness, the sequencing in the "Charter" irritates me even
more than the first time through. Here is the proposal:
 
>Proposed Charter: A forum for the discussion of issues related
>   to literate programming.
>
>(1) To discuss the merits of the currently existing literate
>    programming tools.
>
>(2) To discuss the design of new literate programming tools.
>
>(3) To share ideas, questions, experiences, and knowledge about the
>    reading and writing of literate programs.
 
In light of the recent discussion it is probably not only my opinion that the
order should really be reversed, yielding more of a top down approach, like
 
(1) (former 3) To share ideas ...       (What is literate programming?)
(2) (former 2) To discuss the design... (What should the tools look like?)
(3) (former 1) To discuss the merits... (How do the available tools fit?)
 
Wolfram
                                          _____________________________________
                                          | Wolfram Kahl                      |
                                          | kahl@informatik.unibw-muenchen.de |
                                          -------------------------------------
 
From George Thu Jul 22 07:24:07 CST 1993
Date: Thu, 22 Jul 1993 07:24:07 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, kahl@INFORMATIK.UNIBW-MUENCHEN.DE
Subject: Re: RFD, 2nd iteration, 2 of 2: Draft RFD
 
On Thu, 22 Jul 93 09:13:59 +0200,
kahl@informatik.unibw-muenchen.de (Wolfram Kahl)
posted: 
> after the "Background" section in the revised RFD has been liberated from
> too much TeX/WEB heaviness, the sequencing in the "Charter" irritates me
> even more than the first time through. Here is the proposal:
> 
> >Proposed Charter: A forum for the discussion of issues related
> >   to literate programming.
> >
> >(1) To discuss the merits of the currently existing literate
> >    programming tools.
> >
> >(2) To discuss the design of new literate programming tools.
> >
> >(3) To share ideas, questions, experiences, and knowledge about the
> >    reading and writing of literate programs.
> 
> In light of the recent discussion it is probably not only my opinion that
> the order should really be reversed, yielding more of a top down approach,
> like
> 
> (1) (former 3) To share ideas ...       (What is literate programming?)
> (2) (former 2) To discuss the design... (What should the tools look like?)
> (3) (former 1) To discuss the merits... (How do the available tools fit?)
 
I would agree with this sentiment, as well.  Going back to July 1992 (when
Cameron and I first discussed this list), that was more or less the
ordering.  While lists do not have "charters", per se, I think that the
general public announcement, as well as the welcome message received by new
subscribers, could be viewed as something close to a charter (a mission
statement definitely).  My apologies to Matthias for not catching the
ordering sequencing earlier, before posted it publicly.  
 
For reference, the general discussion in these documents reads:
> LitProg is a network list dealing with topics related to Literate
> Programming.  This includes general issues of style and philosophy, such as
> "what is literate programming?" or "is literate programming compatible with
> writing portable programs?", as well as specific issues relating to
> particular literate programming systems, such as "is it possible to use
> CWEB with ANSI C?"  
or,
(1) philosophy  -- need to propagate the concept's worthiness; sell the concept
(2) ideas       -- exchange in general; what, why, how, etc.;
(3) design      -- what the tools should look like
(4) application -- how the available tools fit
 
Just my \$0.02.
 
--George
 
From Matthias Thu Jul 22 17:22:42 +0200 1993
Date: Thu, 22 Jul 1993 17:22:42 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Re: RFD, 2nd iteration, 2 of 2: Draft RFD
 
George D. Greenwade writes:
>kahl@informatik.unibw-muenchen.de (Wolfram Kahl) posted: 
>> after the "Background" section in the revised RFD has been liberated from
>> too much TeX/WEB heaviness, the sequencing in the "Charter" irritates me
>> even more than the first time through. Here is the proposal:
>> 
>> >Proposed Charter: A forum for the discussion of issues related
>> >   to literate programming.
>> >
>> >(1) To discuss the merits of the currently existing literate
>> >    programming tools.
>> >
>> >(2) To discuss the design of new literate programming tools.
>> >
>> >(3) To share ideas, questions, experiences, and knowledge about the
>> >    reading and writing of literate programs.
>> 
>> In light of the recent discussion it is probably not only my opinion that
>> the order should really be reversed, yielding more of a top down approach,
>> like
>> 
>> (1) (former 3) To share ideas ...       (What is literate programming?)
>> (2) (former 2) To discuss the design... (What should the tools look like?)
>> (3) (former 1) To discuss the merits... (How do the available tools fit?)
>
>I would agree with this sentiment, as well.  Going back to July 1992 (when
>Cameron and I first discussed this list), that was more or less the
>ordering.
>[...]
>or,
>(1) philosophy  -- need to propagate the concept's worthiness; sell the concep
t
>(2) ideas       -- exchange in general; what, why, how, etc.;
>(3) design      -- what the tools should look like
>(4) application -- how the available tools fit
 
I agree that I had my priorities all mixed up, and that ideas (and possibly
philosophy, thanks for the suggestion) should come first. I disagree about the
order of the last two, however. IMHO, the strengths and weaknesses of existing
systems have to be taken into consideration before designing new systems.
 
Therefore, I think that the goals in the charter should be:
 
(0) To propagate the idea of literate programming.
 
(1) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
(2) To discuss the merits of the currently existing literate
    programming tools.
 
(3) To discuss the design of new literate programming tools.
 
I don't like my formulation for (0), though. Although every newsgroup or
mailing list, up to a certain degree, evangelizes for its subject matter, I'm
not sure if explicitely stating this in the charter would be a good idea. I
would therefore welcome suggestions for a better (0).
 
Matthias
 
-----
Matthias Neeracher                                    neeri@iis.ee.ethz.ch
  "I didn't get where I am today by being wise!" -- Lawrence D'Oliveiro
 
From Cameron Thu Jul 22 11:32:22 -0500 1993
Date: Thu, 22 Jul 1993 11:32:22 -0500
From: Cameron Smith <cameron@symcom.math.uiuc.edu>
Reply-To: LitProg@SHSU.edu, cameron@SYMCOM.MATH.UIUC.EDU
To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
Subject: Re: RFD, 2nd iteration, 2 of 2: Draft RFD
 
Just a quick note to second George's endorsement of Wolfram's objection...
(wait, this is getting complicated...)  Anyway, what he said.
Philosophy first, nitty-gritty details last.
 
And thanks to George for supporting this list!
(No special reason to say that now, but I don't say it often enough
and now is as good a time as any to be grateful!)
 
--Cameron
 
From plyon@emx.cc.utexas.edu Thu Jul 22 15:28:44 -0500 1993
Date: Thu, 22 Jul 93 15:28:44 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu, plyon@EMX.CC.UTEXAS.EDU
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: RFD, 2nd iteration, 2 of 2: Draft RFD
 
Matthias Neeracher writes:
 
> - The RFD will be posted to
>      news.announce.newgroups
>      news.groups
>      comp.programming
>      comp.software-eng
>      comp.text.tex
 
Suggestion: 
 
It might be helpful to post the RFD to several other news groups, one
candidate being comp.compilers. There was a discussion last year
therein about source code comments and such which took a turn in the
direction of literate programming; at any rate I did construe it
so and posted a message about the existence of this mailing list :-)
 
It might also be worth posting the RFD to language specific news
groups for which we currently have language specific Web systems;
comp.lang.c or comp.lang.c++. Periodically one gets a lengthy thread
in such newsgroups about source code documentation: surely some of the
parties to such discussions would be interested in a
comp.programming.literate news group?
 
After all, if one is going to try to spread the idea why not start at
once with the RFD for the proposed news group :-)
 
Ciao,
 
Paul Lyon
 
From plyon@emx.cc.utexas.edu Thu Jul 22 15:28:44 -0500 1993
Date: Thu, 22 Jul 93 15:28:44 -0500
From: plyon@emx.cc.utexas.edu (Paul Lyon)
Reply-To: LitProg@SHSU.edu, plyon@EMX.CC.UTEXAS.EDU
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: RFD, 2nd iteration, 2 of 2: Draft RFD
 
Matthias Neeracher writes:
 
> - The RFD will be posted to
>      news.announce.newgroups
>      news.groups
>      comp.programming
>      comp.software-eng
>      comp.text.tex
 
Suggestion: 
 
It might be helpful to post the RFD to several other news groups, one
candidate being comp.compilers. There was a discussion last year
therein about source code comments and such which took a turn in the
direction of literate programming; at any rate I did construe it
so and posted a message about the existence of this mailing list :-)
 
It might also be worth posting the RFD to language specific news
groups for which we currently have language specific Web systems;
comp.lang.c or comp.lang.c++. Periodically one gets a lengthy thread
in such newsgroups about source code documentation: surely some of the
parties to such discussions would be interested in a
comp.programming.literate news group?
 
After all, if one is going to try to spread the idea why not start at
once with the RFD for the proposed news group :-)
 
Ciao,
 
Paul Lyon
 
From Matthias Thu Jul 22 23:19:47 +0200 1993
Date: Thu, 22 Jul 1993 23:19:47 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@shsu.edu
Subject: Re: RFD, 2nd iteration, 2 of 2: Draft RFD
 
Paul Lyon writes:
>Matthias Neeracher writes:
>> - The RFD will be posted to
>>      news.announce.newgroups
>>      news.groups
>>      comp.programming
>>      comp.software-eng
>>      comp.text.tex
>
>It might be helpful to post the RFD to several other news groups, one
>candidate being comp.compilers.
 
I'll ask the moderator of comp.compilers about it. It might be a good idea.
 
>It might also be worth posting the RFD to language specific news
>groups for which we currently have language specific Web systems;
>comp.lang.c or comp.lang.c++. Periodically one gets a lengthy thread
>in such newsgroups about source code documentation: surely some of the
>parties to such discussions would be interested in a
>comp.programming.literate news group?
 
Why not. At least
 
comp.lang.ada
comp.lang.c
comp.lang.c++
comp.lang.pascal
comp.lang.misc 
 
might be candidates. Ada because of the software methodology aspect (though
I don't know if LitProg is DoD approved :-), C, C++, and Pascal since 
I'm sure that LitProg is being done in these languages. c.l.misc since they
are interested both in the target languages and *WEB as a language itself.
 
I'm not sure about:
 
comp.lang.scheme
comp.lang.perl
comp.lang.fortran
comp.lang.apl
comp.lang.modula-2
 
although I'm fairly sure that *some* LitProg has been done. As far as I know,
it isn't considered good taste to crosspost an RFD to too many groups, so
it might be best to limit ourselves to 10 groups. On the other hand, there
is nothing sacrosanct about my 5 candidates; especially software-eng might
be dropped.
 
Matthias
 
-----
Matthias Neeracher                                      neeri@iis.ee.ethz.ch
   "We realize that this means the destruction of solar systems, but
    consider the alternative."     -- Vernor Vinge _A Fire Upon the Deep_
 
From norman@bellcore.com Sat Jul 24 22:57:17 -0400 1993
Date: Sat, 24 Jul 93 22:57:17 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: Re: RFD, 2nd iteration, 2 of 2: Draft RFD
 
consider comp.lang.modula3.
i have written a lot of m3 code using literate-programming tools, although
i do not call the results a literate program.  and the modula-3 people have
cooked up for themselves a `literate' style best described as the
analog of cnoweb (which i would argue is not literate at all since it
does not permit the code to be reorderd).  in any case, there's definite
interest in literate techniques among the m3 commmunity.
 
Norman
 
From Dominique Mon Jul 26 18:19:36 +0200 1993
Date: Mon, 26 Jul 93 18:19:36 +0200
From: Dominique Dumont / GND <domi@petrus.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@PETRUS.GRENOBLE.HP.COM
To: litprog@shsu.edu
Subject: bug on noweb on hpux
 
Hi all
 
I've found a bug in the noweave.hpux script. Somehow the awk code has a slight bug:
I had to replace the line 44 which was
gsub("{", "\\{", line) ; gsub("}", "\\}", line)
with 
gsub("\{", "\{", line) ; gsub("}", "\\}", line)
 
Don't ask me why, I'm no awk guru (I just began to learn it this afternoon :-( )
 
I wish it was written in perl, I'd have found the bug in a jiffy ...(hint hint)
 
Cheers
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
PS : by hint hint I mean all of you who currently use shell, sed or awk to write
your scripts you should really consider to switch to perl. It's faster, more
powerfull in terms of possibilities, and it's free. I'll send a perl faq to
anyone who asks it.
 
From Thorbjoern Mon Jul 26 21:17:01 +0200 1993
Date: Mon, 26 Jul 1993 21:17:01 +0200 (MET DST)
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: litprog@shsu.edu
Subject: Nuweb 0.8 and AUC-TeX 7 -- a solution
 
I have now found an unofficial solution to the problem for people using
AUC-TeX (*) with Nuweb.  You need AUC-TeX 7 for these undocumented
facilities to work, but it should work with both TeX 2 and TeX 3.  
 
[I am working on getting official (that is, documented) hooks for Webs in
AUC-TeX]
 
Due to the numerous little changes the patch file grew to ~32K, so you'll
have to get it with ftp from 
 
  /anonymous@ftp.imada.ou.dk:/pub/misc/nuweb
 
  -rw-rw-r--        372 Jul 23 21:45 README
  -rw-rw-r--      31346 Jul 26 20:03 nuweb.auctex.patch <= Just the patch
  -rw-rw-r--     155775 Jul 26 20:10 nuweb.auctex.shar  <= AUC 0.8 dist
  -rw-r--r--     169067 Jul  2 18:05 nuweb.shar         <= Original 0.8 dist
 
Unless you have the nuweb-0.8 source handy, grab "nuweb.auctex.shar".
 
(*) Preston reminded me that a few lines of description would be
appropriate; so here goes...[snip snip from the README]
 
    *** AUC-TeX for GNU Emacs
 
    AUC-TeX is a comprehensive customizable integrated environment for
    writing input files for LaTeX using GNU Emacs.
 
    AUC-TeX lets you run TeX/LaTeX and other LaTeX-related tools, such as
    a output filters or post processor from inside Emacs.  Especially
    `running LaTeX' is interesting, as AUC-TeX let's you browse through
    the errors TeX reported, while it moves the cursor directly to the
    reported error, and displays some documentation for that particular
    error.  This will even work when the document is spread over several
    files.
 
    AUC-TeX automatically indents your `LaTeX-source', not only as you
    write it---you can also let it indent and format an entire document.
    It has a special outline feature, which can greatly help you `getting
    the overview' of a document.
 
    Apart from these special features, AUC-TeX provides an large range of
    handy Emacs macros, which in several different ways can help you
    write your LaTeX documents fast and painless.
 
The latest version is available from
 
    /anonymous@iesd.auc.dk:/pub/emacs-lisp   as   auctex.tar.gz
 
Comments and criticism are very welcome.
 
Regards,
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
[I speak of AUC-TeX as a happy user only; we have nothing to do with iesd]
 
From Matthias Mon Jul 26 22:39:56 +0200 1993
Date: Mon, 26 Jul 1993 22:39:56 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@shsu.edu
Subject: RFD, 3rd Iteration, 1 of 2: Overview
 
I think the second draft was already somewhat closer to acceptable, but
as the comments demonstrated, there still was ample room for improvement.
 
Major changes were:
 
The list of target newsgroups has been extended. There is now a two-level
hierarchy of interested newsgroups. The "inner" level gets to see all RFDs and
all CFVs (6 postings in all). The "outer" level just gets a single reminder at
the beginning of the discussion period. The reasons for the outer level are on
one hand that comp.compilers is moderated and the moderator doesn't want more
than one announcement on the topic and on the other hand that crossposting an
RFD to too many groups is not recommended by the USENET guidelines. None of the
RFDs I have seen were posted to more than 6 groups, so 8 is already rather
high.
 
The goals in the charter have been reordered. The old order was clearly wrong.
Several posters suggested a different order of (2) and (3) than I have now, but
I need more convincing to change that.
 
The Knuth quote has been extended by one paragraph.
 
Comments to me welcome. This *might* be the last iteration before the RFD is
posted. Note, however, that there is no problem in amending the charter during
the RFD period.
 
Matthias
 
-----
Matthias Neeracher                                      neeri@iis.ethz.ch
  "Rock and Roll adolescent hoodlums storm the streets of all nations."
                            -- William Burroughs, _The Naked Lunch_
 
From Matthias Mon Jul 26 22:40:00 +0200 1993
Date: Mon, 26 Jul 1993 22:40:00 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@shsu.edu
Subject: RFD, 3rd Iteration, 2 of 2: Draft RFD
 
Remarks:
 
- The RFD will be posted to
 
      news.announce.newgroups
      news.groups
      comp.programming
      comp.text.tex
      comp.lang.misc
      comp.lang.c
      comp.lang.c++
      comp.lang.fortran
 
   Additionally, the following groups will get a post at the beginning
   informing them that a group creation process has started:
 
      comp.software-eng
      comp.compilers
      comp.lang.ada
      comp.lang.modula3
 
- The information presented here has been compiled from information provided
  by
      George D. Greenwade <bed_gdg@SHSU.edu>
      Marcus Speh         <marcus@x4u.desy.de>
      David B. Thompson   <dthompson@coe2.coe.ttu.edu>
      Joachim Schrod 	  <schrod@iti.informatik.th-darmstadt.de>
      Norman Ramsey       <norman@bellcore.com>
 
  and several other contributors. Any remaining errors are of course mine.
 
- Feedback by email is, as always, welcome.
 
      Request for Discussion: comp.programming.literate
      -------------------------------------------------
 
Proposed name:              comp.programming.literate
Proposed moderation status: unmoderated
 
Proposed Charter: A forum for the discussion of issues related
   to literate programming.
 
(1) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
(2) To discuss the merits of the currently existing literate
    programming tools.
 
(3) To discuss the design of new literate programming tools.
 
Background: What is Literate Programming?
 
In an article published in _The Computer Journal_ 27 (1984), 97-111,
Donald E. Knuth proposed a "literate" programming style:
 
     I believe that the time is ripe for significantly better
     documentation of programs, and that we can best achieve this by
     considering programs to be works of literature. Hence, my title:
     "Literate Programming."
 
     Let us change our traditional attitude to the construction of
     programs: Instead of imagining that our main task is to instruct
     a *computer* what to do, let us concentrate rather on explaining
     to *human beings* what we want a computer to do.
 
     The practitioner of literate programming can be regarded as an
     essayist, whose main concern is with exposition and excellence of
     style. Such an author, with thesaurus in hand, chooses the names
     of variables carefully and explains what each variable means. He
     or she strives for a program that is comprehensible because its
     concepts have been introduced in an order that is best for human
     understanding, using a mixture of formal and informal methods that
     reinforce each other.
 
A literate programming system can be characterized by the following
properties:
 
 - The compilable program and the publishable documentation should be
   generated *automatically* from a *single* document.
 
 - The program can be presented in the order that is best for human
   understanding, regardless of any requirements of the programming
   language.
 
 - The program should be automatically indexed and cross-referenced.
 
Knuth's original system, called WEB, generated Pascal code and a TeX
documentation. Most tools relating to the TeX system have been written
using WEB, and the TeX and Metafont programs have been published in book
form.
 
Today, there are Literate Programming systems for a wide range of
programming languages and documentation systems. Specialized Literate
Programming tools have been written for Ada, Awk, C, C++, Fortran,
Modula-2, Modula-3, Pascal and Scheme, and generic tools exist that
can generate almost any programming language (including Perl and sh).
 
Documentation systems supported include TeX, Troff, and Word for
Windows.
 
Existing Resources
 
The mailing list LitProg@SHSU.EDU has existed for about a year. There
are currently more than 300 subscribers and an average of about 80
messages (corresponding to about 150K of traffic) per month in the
first 6 months of this year.
 
If a newsgroup is created, mechanisms are already in place to support
a mirrored gateway between it and the existing mailing list.  For
reference purposes, the newsgroup will be fully archived by the host
sponsoring the mailing list.
 
Discussion
 
Discussion should be confined to news.groups. Please do not post
responses to any other groups. Discussions may also be e-mailed to
neeri@iis.ee.ethz.ch if posting is not possible.
 
Assuming there is a consensus that the group comp.programming.literate
should be created, voting will start 21 days from the first posting
date of this request.  Voting instructions will be published in a Call
for Votes to the same newsgroups that see this Request for Discussion.
Both this Request for Discussion and the Call for Votes will be
crossposted to the "litprog@shsu.edu" mailing list.
 
From Lee Tue Jul 27 11:21:18 EDT 1993
Date: Tue, 27 Jul 93 11:21:18 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, domi@petrus.grenoble.hp.com
Subject: Re: bug on noweb on hpux
 
Dominique Dumont points out a bug in a noweave awk script.
 
I, too, have had problems with that particular line.  However, it seems to be
more of an Awk bug than a noweave one.  gsub is a rather complex function,
and it seems, is rather bug-prone (MKS Awk, which I use, has a different gsub
bug that screws up the line in question).  The problems seem to come in 2
areas:
 
	1) dealing with backslashes (and other special characters) in pattern
	   strings can get quite hairy (and counterintuitive)
 
	2) UNIX and POSIX do not agree about (1).
 
Not really wanting to get into the Perl/Awk debate, I was still wondering if
the same kind of problems crop up in the various perl implementations.
 
		-- Lee
 
From Matthias Tue Jul 27 19:01:37 +0200 1993
Date: Tue, 27 Jul 1993 19:01:37 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Re: bug on noweb on hpux
 
In message <CMM-RU.1.3.743786478.leew@pilot.njin.net> you write:
>Dominique Dumont points out a bug in a noweave awk script.
>
>I, too, have had problems with that particular line.  However, it seems to be
>more of an Awk bug than a noweave one.  gsub is a rather complex function,
>and it seems, is rather bug-prone 
>[...]
>	1) dealing with backslashes (and other special characters) in pattern
>	   strings can get quite hairy (and counterintuitive)
>
>	2) UNIX and POSIX do not agree about (1).
>
>Not really wanting to get into the Perl/Awk debate, I was still wondering if
>the same kind of problems crop up in the various perl implementations.
 
No. There is but one Perl and Larry Wall is its prophet :-) As opposed to 
Awk, whose original source was proprietary and which was relatively easy 
to imitate, the source of Perl is copylefted and it's almost impossible 
to write a Perl clone without borrowing the original parser (Perl has a 
syntax which is from a computer's point of view quite nasty).
 
As to the suggestion to use Perl instead of Awk for WEB work, I'm not sure.
On one hand, Perl code can be very portable across platforms and Perl is 
IMHO much more powerful than Awk. On the other hand, Perl itself is almost
unparseable for a literate programming tool and therefore at least not suited
to literate programming with any tools that try to format source code.
 
Matthias
 
-----
Matthias Neeracher                                      neeri@iis.ethz.ch
   "A system without PERL is like a hockey game without a fight."
                 		           -- Mitch Wright
 
From Dominique Wed Jul 28 10:22:06 +0200 1993
Date: Wed, 28 Jul 93 10:22:06 +0200
From: Dominique Dumont / GND <domi@petrus.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@PETRUS.GRENOBLE.HP.COM
To: LitProg@SHSU.edu
Subject: Re: bug on noweb on hpux
 
In message <199307271701.AA11529@err.ethz.ch> you write:
> As to the suggestion to use Perl instead of Awk for WEB work, I'm not sure.
> On one hand, Perl code can be very portable across platforms and Perl is 
> IMHO much more powerful than Awk. On the other hand, Perl itself is almost
> unparseable for a literate programming tool and therefore at least not suited
> to literate programming with any tools that try to format source code.
> 
This may be a problem if you want to do literate programming with pretty printed
perl (Do you ?). On the other hand tgrind works quite well with perl 
so the problem of parsing perl may not be that difficult.
 
This was just a 0.02 $ contribution :-)
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From Lee Sat Jul 31 11:57:18 EDT 1993
Date: Sat, 31 Jul 93 11:57:18 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: Thoughts on symbolic debugging in CWEB
 
It has occurred to me that it should be rather simple (although not trivial)
to create a WYSIWYGish symbolic CWEB debugger by wedding a standard debugger
to a dvi driver.  Some fairly simple changes can be made to the macros in
cwebmac.tex -- only \N, \A, and \U need be changed, as best I can figure --
to have these macros insert \specials into the dvi file with section
cross-references to be used by the debugger.  CWEAVE could also be modified
(again, simply but not trivially) to put #line information into
\specials, as well.  The debugger could use this to establish a
correspondence between the .dvi file and whatever debugging info is
stored in the object code.  It could then generate error message,
trace info, etc. geared to the dvi file, allowing debugging to take
place completely (or so) with regard to the woven web.  It would
still be necessary to make fixes to the .w file, but you can't have
everything.
 
A more ambitious debugger might also be able to use the info in the
generated index.
 
Unfortunately, I have neither the time nor the expertise to follow up
this project myself, although I would be willing to help in any way I
can, if anyone cares to adopt it as their own.
 
		-- Lee
 
-----------------------------------------------------------------
"Never again will I climb on a lava cliff in my underwear."
                            -- Thor Heyerdahl
 
From Lee Sat Jul 31 12:03:06 EDT 1993
Date: Sat, 31 Jul 93 12:03:06 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: CWEB output as in Knuth LP book
 
I'm trying to play with the CWEB macros to get output like Knuth's in
_Literate Programmming_:  \hrules instead of page breaks, etc.  I'm having a
bit (ha!  I'm having a _lot_) of trouble getting \inx and \fin to cooperate
in allowing the section names to follow on the  same page as the index, after
an \hrule.  I would be grateful for any help anyone can give me with this.
 
Thanks in advance.
 
		-- Lee
 
From Matthias Mon Aug 02 11:24:06 +0200 1993
Date: Mon, 02 Aug 1993 11:24:06 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: litprog@shsu.edu
Subject: RFD for comp.programming.literate has been posted
 
The RFD for comp.programming.literate has been posted on Usenet last week, and
discussion so far was mostly in favor of a newsgroup creation. I don't think it
is necessary to repost it here, as the posted version is practically identical
to the 3rd iteration posted here a week ago (If you would like a copy of the
RFD that was posted, send me mail, and I'll mail you one).
 
I made a mistake in the post by omitting comp.lang.pascal and
comp.lang.modula2, which will be included in the 2nd RFD which is posted around
Wednesday.
 
Matthias
 
-----
Matthias Neeracher                                  neeri@iis.ee.ethz.ch
  "And that's why I am going to turn this world upside down, and make
   of it a fire so *bright* that someone real will notice"
                                -- Vernor Vinge, _Tatja Grimm's World_
 
From aaron@bcstec.ca.boeing.com Mon Aug 2 7:32:31 PDT 1993
Date: Mon, 2 Aug 93 7:32:31 PDT
From: aaron@bcstec.ca.boeing.com (Aaron)
Reply-To: LitProg@SHSU.edu, aaron@BCSTEC.CA.BOEING.COM
To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
Subject: Re: RFD for comp.programming.literate has been posted
 
Matthias Ulrich Neeracher said:
> 
> The RFD for comp.programming.literate has been posted on Usenet last week, and
> discussion so far was mostly in favor of a newsgroup creation. I don't think it
> is necessary to repost it here, as the posted version is practically identical
 
I only reposted that part of the post necessary to give some context to my
question, and deleted the rest.
 
-- 
aaron@bcstec.ca.boeing.com        (206)655-5369  |Aaron
                                                 |Boeing Commercial Airplanes
                                                 |PO BOX 3707       M/S 11-PT
I know enough to know that I don't know enough.  |Seattle WA 98124
 
From aaron@bcstec.ca.boeing.com Mon Aug 2 22:33:49 PDT 1993
Date: Mon, 2 Aug 93 22:33:49 PDT
From: aaron@bcstec.ca.boeing.com (Aaron)
Reply-To: LitProg@SHSU.edu, aaron@BCSTEC.CA.BOEING.COM
To: LitProg@SHSU.edu (Literate Programming Mailing List)
Subject: cweb and tex, overwhelmed
 
I just ftpmailed the cweb files from labrea.something.stanford.
 
I realize from cruising through the files that I also need tex.
Looking through the tex directories at labrea.something.stanford
has overwhelmed me. I'm pretty sure I don't want _all_ that tex stuff.
 
Would someone be kind enough to post on this mail list:
   - what files to get, for "just enough tex" to make cweb work
   - best place to get 'em if not stanford
 
Your most humble slave,
 
-- 
aaron@bcstec.ca.boeing.com        (206)655-5369  |Aaron
                                                 |Boeing Commercial Airplanes
                                                 |PO BOX 3707       M/S 11-PT
I know enough to know that I don't know enough.  |Seattle WA 98124
 
From aaron@bcstec.ca.boeing.com Mon Aug 2 22:41:16 PDT 1993
Date: Mon, 2 Aug 93 22:41:16 PDT
From: aaron@bcstec.ca.boeing.com (Aaron)
Reply-To: LitProg@SHSU.edu, aaron@BCSTEC.CA.BOEING.COM
To: LitProg@SHSU.edu (Literate Programming Mailing List)
Subject: cweb & tex books/resources
 
Would someone be kind enough to list their favorite books or
files(with location) that constitute "just enough" to help
a beginner get going with cweb?  My focus is cweb, I only want
to know enough tex to work and produce effectively in cweb.
 
Thanks,
 
-- 
aaron@bcstec.ca.boeing.com        (206)655-5369  |Aaron
                                                 |Boeing Commercial Airplanes
                                                 |PO BOX 3707       M/S 11-PT
I know enough to know that I don't know enough.  |Seattle WA 98124
 
From norman@bellcore.com Tue Aug 3 14:30:36 -0400 1993
Date: Tue, 3 Aug 93 14:30:36 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: books
 
Wayne Sewell's book (Weaving a Program?) is the only one I know of that
addresses dirty details of web tools.  It may be out of print, and you
may find it disappointing, but that's what there is.
 
Norman Ramsey
 
From Lee Wed Aug 4 12:39:29 EDT 1993
Date: Wed, 4 Aug 93 12:39:29 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, aaron@bcstec.ca.boeing.com
Subject: Re: cweb & tex books/resources
 
The best books I've found for beginners are:
 
_TeX for the Beginner_ by Wynter Snow (Is this the author's real name?)
    Addison-Wesley, 1992.
 
_A Beginner's Book of TeX_ by Raymond Seroul and Silvio Levy,
    Springer-Verlag, 1991.
 
The former is a bit more ``hand-holding,'' while the latter contains
more details.  Check them out and see which one ``speaks to you.''
Both are still in print and can be ordered by your local bookstore.  Barnes &
Noble stores (and derivatives, like BookStop) usually carry one or both in
stock.
 
Michael Doob's "A Gentle Introduction to TeX" is excellent, and available
via anonymous ftp (I'm sure there's a copy at pip.shsu.edu, but
"archie gentle.tex" should find it for sure).  Unfortunately, you need
TeX to generate a copy, unless a PostScript version is also available
at the ftp site. I think I have a copy somewhere and could email you
the PostScript version, if you like.
 
In your previous message, you said you were looking for a copy of TeX
for yourself.  What machine (and operating system) do you want it to
run on?  I use emTeX, an excellent implementation for MS-DOS and OS/2
systems, which is available via anonymous ftp from pip.shsu.edu (and
elsewhere).  However, emTeX won't be of much help if you don't have a
PC or clone.
 
		-- Lee
 
From David Wed Aug 04 10:22:00 PDT 1993
Date: Wed, 04 Aug 93 10:22:00 PDT
From: David Thompson <dthompson@coe2.coe.ttu.edu>
Reply-To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU
To: LitProg <litprog@shsu.edu>
Subject: books
 
> Wayne Sewell's book (Weaving a Program?) is the only one I know of that
> addresses dirty details of web tools.  It may be out of print, and you
> may find it disappointing, but that's what there is.
 
It is still available.  I found my copy at Computer Literacy Bookstore in 
the Silicon Valley.
 
 -=d
 
David B. Thompson                 internet: wqdbt@ttacs1.ttu.edu
Civil Engineering Dept.           internet: dthompson@coe2.coe.ttu.edu
Texas Tech University             internet: thompson@sun1.coe.ttu.edu
P.O. Box 41023
Lubbock, Texas 79409-1023
USA
 
From aaron@bcstec.ca.boeing.com Wed Aug 4 10:40:10 PDT 1993
Date: Wed, 4 Aug 93 10:40:10 PDT
From: aaron@bcstec.ca.boeing.com (Aaron)
Reply-To: LitProg@SHSU.edu, aaron@BCSTEC.CA.BOEING.COM
To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU
Subject: Re: books
 
David Thompson said:
> > Wayne Sewell's book (Weaving a Program?) is the only one I know of that
> > addresses dirty details of web tools.  It may be out of print, and you
> > may find it disappointing, but that's what there is.
> 
> It is still available.  I found my copy at Computer Literacy Bookstore in 
> the Silicon Valley.
 
thanks, I'll check it out.
 
-- 
aaron@bcstec.ca.boeing.com        (206)655-5369  |Aaron
                                                 |Boeing Commercial Airplanes
                                                 |PO BOX 3707       M/S 11-PT
I know enough to know that I don't know enough.  |Seattle WA 98124
 
From Christian Thu Aug 5 09:13:19 +0200 1993
Date: Thu, 5 Aug 1993 09:13:19 +0200
From: Christian Lynbech <lynbech@daimi.aau.dk>
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: cweb & tex books/resources
 
> X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
> Warnings-To: <>
> Errors-To: LP-Mgr@SHSU.edu
> Sender: LP-Mgr@SHSU.edu
> Date: Wed, 4 Aug 93 12:39:29 EDT
> From: Lee Wittenberg <leew@pilot.njin.net>
> Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
> X-Charset: LATIN1
> X-Char-Esc: 29
> 
[... stuff deleted...]
> 
> In your previous message, you said you were looking for a copy of TeX
> for yourself.  What machine (and operating system) do you want it to
> run on?  I use emTeX, an excellent implementation for MS-DOS and OS/2
> systems, which is available via anonymous ftp from pip.shsu.edu (and
> elsewhere).  However, emTeX won't be of much help if you don't have a
> PC or clone.
> 
 
I guess that TeX has been ported to most systems by now. It certainly is also
available for the atari, so check out your favourite ftp site, or try archie.
 
Incidently, there is a shorter document on setting up a TeX system on the
atari, aimed at the first-time user. I do not know how specific to the atari
port it is, but if I remember correctly it takes the time to explain what the
various files and programs are supposed to do, and that should be general
enough. I can dig up a copy if you are interested.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From bart@cs.tamu.edu Thu Aug 5 09:44:00 CDT 1993
Date: Thu, 5 Aug 93 09:44:00 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: litprog@shsu.edu
Subject: WEB-MODE problems with emacs 19.??
 
I am finally back from international travel and a three week
interruption due to a death in the family.  I have done the
following checkouts of the problem:
 
1. using emacs 19.16 and web-mode.elc that was byte-compiled on
   emacs 18.58.4 it works like a charm.
2. using emacs 19.16 and byte compiling a new version I get
   a lot of warnings but no error that is apparent to me in
   making a new web-mode.elc
3. The new web-mode.elc is just a bit shorter and absolutely
   will not work.
 
Has anybody else tried similar steps?  Please let me know.
 
I will be letting our locals who communicate with FSF about
this and asking them to inquire as to possible problems with
version 19 or new rules in 19 that we are violating in
web-mode.el.
 
Thanks
 
Bart Childs
 
From Christian Fri Aug 6 08:59:31 +0200 1993
Date: Fri, 6 Aug 1993 08:59:31 +0200
From: Christian Lynbech <lynbech@daimi.aau.dk>
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.edu, bart@cs.tamu.edu
Subject: Re: WEB-MODE problems with emacs 19.??
 
> I am finally back from international travel and a three week
> interruption due to a death in the family.  I have done the
> following checkouts of the problem:
> 
> 1. using emacs 19.16 and web-mode.elc that was byte-compiled on
>    emacs 18.58.4 it works like a charm.
> 2. using emacs 19.16 and byte compiling a new version I get
>    a lot of warnings but no error that is apparent to me in
>    making a new web-mode.elc
> 3. The new web-mode.elc is just a bit shorter and absolutely
>    will not work.
> 
 
> Bart Childs
 
This sounds rather mysterious to me. If the V18 compiled version works and the
V19 compiled one does not, then it is a bug.
 
I assume that you are trying to get web-mode.elc to work with 19.16, because
the byte-codes has changed, and one compiled on V19 will not work on a V18
emacs, though goeing the other way shoudl always work, and has done for me. 
 
You may however try fidling with the variables byte-compile-compability and
byte-optimize, which controls various features of the new bytecompiler.  You
could also look at the warnings, and watch out for any obsolete.
 
But it still sounds very much like a bug in the byte-compiler and/or the
optimizer to me.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From bos@mdd.comm.mot.com Fri Aug 6 15:38:54 PDT 1993
Date: Fri, 6 Aug 93 15:38:54 PDT
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
To: LitProg@SHSU.edu
Subject: Publishing WEB programs
 
I've been reviewing my litprog mail and came across Lee Wittenberg's
comment about publishing literate programs.
 
How about in the LP newsgroup, we have literate programming submissions 
(non-proprietary programs, of course)?  For those of us still floundering
around in the various WEB's, reading other people's weaves may help us
gain a style and code organization. 
 
Also, it might help those of use trying to sell management to try WEB
to have more examples than what we personally produce.
 
After all, Knuth said, "When was the last time you curled up
with a good program to read?"  
 
-mary
 
From Anselm Sat Aug 07 11:49:25 +0100 1993
Date: Sat, 07 Aug 93 11:49:25 +0100
From: Anselm Lingnau <lingnau@math.uni-frankfurt.de>
Reply-To: LitProg@SHSU.edu, lingnau@MATH.UNI-FRANKFURT.DE
To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
Subject: Re: Publishing WEB programs
 
Mary Bos writes:
 
> How about in the LP newsgroup, we have literate programming submissions 
> (non-proprietary programs, of course)?  For those of us still floundering
> around in the various WEB's, reading other people's weaves may help us
> gain a style and code organization. 
 
True. Maybe we should go for comp.sources.literate as well.
 
Anselm
---
Anselm Lingnau .................................. lingnau@math.uni-frankfurt.de
Programming graphics in X is like finding sqrt(pi) using Roman numerals.
                                                              --- Henry Spencer
 
From preston@cs.rice.edu Sat Aug 7 16:21:23 CDT 1993
Date: Sat, 7 Aug 93 16:21:23 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, lingnau@math.uni-frankfurt.de
Subject: Re: Publishing WEB programs
 
>> How about in the LP newsgroup, we have literate programming submissions
> (non-proprietary programs, of course)?  For those of us still floundering
> around in the various WEB's, reading other people's weaves may help us
> gain a style and code organization.
 
How should we publish?
Mailing 20 or 100 page postscript files to the whole group
seems excessive.
 
Perhaps a collection could be maintained at an ftp site?
 
Preston
 
From koopman@sgi84.ctc.com Sun Aug 8 19:52:33 -0400 1993
Date: Sun, 8 Aug 93 19:52:33 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: FWEB '//' comments problem - FWEAVE of F77 code
 
Literate Programmers:
 
I seem to be having problems with fweave of fweb.1.30 on F77 code.
The "//" and "/*" comments are enabled in F77 with @n/ and \.{FTANGLE}
is happy but \.{FWEAVE} has major problems.  The comments are eaten as
F77 code in \.{FWEAVE} and generate many variable entries in the
index.  The \TeX mode processing is not effective on the comments,
either.
 
I'm a newbie to LitProg, \TeX, \.{FWEB} and am stuck with F77.  That
combination does not identify qualifications to spot bugs.  However,
it seems the demo program with the v1_30 distribution (ftp.shsu.edu)
has the same problems that my code does regarding the comments.  I
intend to use a bogus fix with Fortran column one commenting, YUK.
Any suggestions are appreciated.
 
BTW: I have found FWEB and web-mode for emacs relatively easy to learn
and expect to see great benefits despite the added complexity of the
method.  Learning to master the method and \TeX hack is a more
significant challenge.  Benefits without mastery are apparent in the
ease with which a comprehensible program document can be produced.
 
Sincerely,
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
 
From Lee Mon Aug 9 11:03:33 EDT 1993
Date: Mon, 9 Aug 93 11:03:33 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, preston@cs.rice.edu
Subject: Re: Publishing WEB programs
 
Preston Briggs writes (in response to Mary Bos' original suggestion):
 
>> How about in the LP newsgroup, we have literate programming submissions
>> (non-proprietary programs, of course)?  For those of us still floundering
>> around in the various WEB's, reading other people's weaves may help us
>> gain a style and code organization.
>
> How should we publish?
> Mailing 20 or 100 page postscript files to the whole group
> seems excessive.
>
> Perhaps a collection could be maintained at an ftp site?
 
Perhaps the .sources newsgroup could be used for announcements and the actual
sources (dvi and PostScript) could be kept at a central ftp site.
 
Which brings to mind a problem I've been pondering for a while.  For
those of us in a ``publish or perish'' situation, how do we convince
our administrators that literate programs made available via ftp (or,
indeed, articles in the same situation) are bona fide publications (as
I would maintain they are).  I've been toying with the idea of using a
``Virtual Press'' designation, but haven't actually done anything
in that vein as yet.  Any ideas?
 
			-- Lee
 
From preston@cs.rice.edu Mon Aug 9 11:26:52 CDT 1993
Date: Mon, 9 Aug 93 11:26:52 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: Publishing WEB programs
 
Lee Wittenberg writes:
>Perhaps the .sources newsgroup could be used for announcements and the actual
>sources (dvi and PostScript) could be kept at a central ftp site.
 
In general, that sounds fine.  However, there's some details that should
be hammered out.  The "source" of a web isn't really posctscript of dvi;
it's the cweb or nuweb or noweb file.  I think the typeset output will be fine,
though some systems won't make .dvi files (are there any that can't make
Postscript)?
 
>Which brings to mind a problem I've been pondering for a while.  For
>those of us in a ``publish or perish'' situation, how do we convince
>our administrators that literate programs made available via ftp (or,
>indeed, articles in the same situation) are bona fide publications
 
Well, I don't think they really should count as publications.
The essence of a "publication", for tenure consideration, is the
review process, right?  Papers in unrefereed journals are not considered
important.  Same'll be true for most forms of electronic publication
(unless there's a respected reviewing process).
 
Preston Briggs
 
From bos@mdd.comm.mot.com Mon Aug 9 11:34:11 PDT 1993
Date: Mon, 9 Aug 93 11:34:11 PDT
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
To: LitProg@shsu.edu
Subject: Publishing WEB programs
 
Lee Wittenberg writes:
 
>Which brings to mind a problem I've been pondering for a while.  For
>those of us in a ``publish or perish'' situation, how do we convince
>our administrators that literate programs made available via ftp (or,
>indeed, articles in the same situation) are bona fide publications
 
and Preston Briggs responds
 
>Well, I don't think they really should count as publications.
>The essence of a "publication", for tenure consideration, is the
>review process, right?  Papers in unrefereed journals are not considered
>important.  Same'll be true for most forms of electronic publication
>(unless there's a respected reviewing process).
 
Why not have a refereed "Virtual Press" or electronic forum?  Reiterating
my initial statement, "For those of us still floundering
around in the various WEB's, reading other people's weaves may help us
gain a style and code organization."  
 
Refereeing would help me better appreciate fine workmanship from first efforts -
after all engineers learn from elegant solutions to a solved problems, why
shouldn't LPer's?  There could be two forums perhaps? One unrefereered and
and one refereered. 
 
Mary Bos
 
From mbrown@athos.cs.ua.edu Mon Aug 9 14:20:20 -0500 1993
Date: Mon, 9 Aug 1993 14:20:20 -0500 (CDT)
From: mbrown@athos.cs.ua.edu (Marcus Brown)
Reply-To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Publishing WEB programs
 
Lee Wittenberg wrote:
> 
>  [Stuff deleted...]
> 		....  For
> those of us in a ``publish or perish'' situation, how do we convince
> our administrators that literate programs made available via ftp (or,
> indeed, articles in the same situation) are bona fide publications (as
> I would maintain they are).  I've been toying with the idea of using a
> ``Virtual Press'' designation, but haven't actually done anything
> in that vein as yet.  Any ideas?
> 
> 			-- Lee
> 
My promotion & tenure committees want 'Refereed Publications' -
which means that any publications, whether 'paper' or 'program',
would need to be refereed --  In their eyes, if it is not refereed,
it is probably trash.
 
Somehow, we would need to set up a jury of referees who would review
the submission, pass judgement on its merit, and suggest
improvements/additions/...  This refereeing is usually anonymous,
although some journals also require that at least one member of the
'editorial board' personally endorse a paper before it is included in
the 'Refereed, Meritorious' category.
 
It may be good to have a repository for any submissions, whether
refereed and approved, or not.  However, for academic 'publication'
credit, there must be a peer review process to certify the relative
merit and contribution of each publication.
 
I think that the development of a 'Virtual Press' (as opposed to a
physical journal printed on paper) is a great idea, and I heartily
endorse thinking and planning about how this could be accomplished. 
In the beginning, it would need support by some well-known, respected
figures to establish the 'academic respectability' of this new form
of journal.
 
Unfortunately, I expect that this is more work than the average
readership of a mailing list and/or newsgroup would want to volunteer
for.
 
-- 
Marcus Brown
mbrown@cs.ua.edu
Computer Science Dept, Univ of Alabama
 
From preston@cs.rice.edu Mon Aug 9 16:41:00 CDT 1993
Date: Mon, 9 Aug 93 16:41:00 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: an example nuweb program
 
The group I work with here at Rice is busy writing an entire optimizer
in web.  The intent is to eventually distribute the entire collection
of webs (1 for each pass of the optimizer).  The first passes should start
filtering out soon.  The rest should follow over a period of months.
 
As a warmup, I put a small web out for ftp access.
It's one I wrote to illustrate how a particular algorithm
should be implemented.  It'll eventually be incorporated
as a chapter in a larger web; in the meantime, it serves
as a reference for our group.
 
It's written in nuweb, using a combination of latex and C.
Both the web source and the final postscript are available.
Use anonymous ftp to
 
        cs.rice.edu
 
and look in the directory
 
        public/preston
 
for the files
 
        multiply.ps
        multiply.w
 
It's about 20 pages.  Unfortunately, I believe it's too short to serve
as a good example of a large program.  On the other hand, it does
illustrate one approach towards algorithm explanation.  It hasn't
been extensively reviewed, though comments are welcome.
 
Preston Briggs
 
From aaron@bcstec.ca.boeing.com Mon Aug 9 15:45:43 PDT 1993
Date: Mon, 9 Aug 93 15:45:43 PDT
From: aaron@bcstec.ca.boeing.com (Aaron)
Reply-To: LitProg@SHSU.edu, aaron@BCSTEC.CA.BOEING.COM
To: LitProg@SHSU.edu
Subject: Re: Publishing WEB programs
 
Marcus Brown said:
[deletia]
> I think that the development of a 'Virtual Press' (as opposed to a
> physical journal printed on paper) is a great idea, and I heartily
> endorse thinking and planning about how this could be accomplished. 
> In the beginning, it would need support by some well-known, respected
> figures to establish the 'academic respectability' of this new form
> of journal.
> 
> Unfortunately, I expect that this is more work than the average
> readership of a mailing list and/or newsgroup would want to volunteer
> for.
 
Some group like ACM or a journal could probably do it best, since they
already have the basic review mechanism in place.
 
-- 
aaron@bcstec.ca.boeing.com        (206)655-5369  |Aaron
                                                 |Boeing Commercial Airplanes
                                                 |PO BOX 3707       M/S 11-PT
I know enough to know that I don't know enough.  |Seattle WA 98124
 
From Hans-Hermann Tue Aug 10 11:56:03 MEZ 1993
Date: Tue, 10 Aug 93 11:56:03 MEZ
From: Hans-Hermann Bode <HHBODE@dosuni1.rz.Uni-Osnabrueck.DE>
Reply-To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
To: LitProg@SHSU.edu, koopman@ctc.com
Subject: Re: FWEB '//' comments problem - FWEAVE of F77 code
 
Michael G. Koopman wrote:
 
>I seem to be having problems with fweave of fweb.1.30 on F77 code.
>The "//" and "/*" comments are enabled in F77 with @n/ and \.{FTANGLE}
>is happy but \.{FWEAVE} has major problems.  The comments are eaten as
>F77 code in \.{FWEAVE} and generate many variable entries in the
>index.  The \TeX mode processing is not effective on the comments,
>either.
>
>I'm a newbie to LitProg, \TeX, \.{FWEB} and am stuck with F77.  That
>combination does not identify qualifications to spot bugs.  However,
>it seems the demo program with the v1_30 distribution (ftp.shsu.edu)
>has the same problems that my code does regarding the comments.  I
 
Are you sure you have version 1.30? I experienced that behaviour with
FWEAVE 1.23, but in 1.30 the bug has been fixed as I can see from my
own examples. Also, although demo.web has some problems, the comments are
allright here, too. So, please check and send a short example if the problem
still exists.
 
Hans-Hermann Bode
Arbeitsgruppe Systemforschung, Universitaet Osnabrueck, D-49069 Osnabrueck
Tel.: (49)-541-9692545
e-mail: HHBODE@DOSUNI1.BITNET, hhbode@dosuni1.rz.uni-osnabrueck.de
 
From Joey Tue Aug 10 08:06:34 -0400 1993
Date: Tue, 10 Aug 1993 08:06:34 -0400 (EDT)
From: Joey Gibson <aix3!wjg@sun1.ema.com>
Reply-To: LitProg@SHSU.edu, aix3!wjg@SUN1.EMA.COM
To: LitProg Mail-List <netcomsv!LITPROG@SHSU.edu>
Subject: Fweb 1.30 under Linux
 
Has anyone gotten FWeb 1.30 to work under Linux (.99pl6)? It compiles
fine, but when I try to weave demos/demo.web I get an
 
	IOT error (core dumped)
 
error. I first ran configure and tehn compiled what it produced. I
then copied the config.h and defaults.mk from boot/unix/ansi and
recompiled. Same thing. Does anyone have any suggestions?
 
Joey
///////////////////////////////////////////////////////////////////
/     wjg@sun1.ema.com     /  Joey Gibson - Computer Services     /
/  Phone: (404) 261-5256   /  EDS/Energy Management Associates    /
/  FAX  : (404) 848-7472   /  Atlanta, GA                         /
///////////////////////////////////////////////////////////////////
 
From Joachim Tue Aug 10 17:38:09 +0100 1993
Date: Tue, 10 Aug 1993 17:38:09 +0100 (MESZ)
From: Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: litprog@shsu.edu (Literate Programming discussion)
Subject: Update of CWEB style is ready
 
A new release of the cweb style package (0.4) is ready for
distribution. Thanks to Michael M\"uller and Zden\v{e}k Wagner for
their valuable input. FYI, I've appended the relevant parts of the
History file to this mail.
 
As usual, the cweb style package may be fetched from the Literate
Programming Archive:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/c.c++
	file cweb-sty-0.4.tar.Z
		(a compressed tar file)
 
A diff from 0.3 to 0.4 is there as well.
 
For those who haven't heard about this package: It adds LaTeX support
for CWEB 3.
 
Enjoy,
    Joachim
 
---------- excerpt from History:
 
Version 0.4	[10 Aug 93]
 
	Added cwebarray.sty to the official release.
	Added cwebzw.sty as contributed option.
 
	Left shift operator (`<<') is now defined correctly.
	CWEB macro and program part in one section works now.
	Typed numbers now produce a subscript, as in the plain version.
 
	Cross references to section numbers do not output a period
	after the section number any more.
 
	Updated user documentation.
 
	Start new page on main section only if @*2 or higher (configurable).
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Charles Tue Aug 10 12:02:40 -0700 1993
Date: Tue, 10 Aug 1993 12:02:40 -0700 (PDT)
From: Charles Bass <chuckb@u.washington.edu>
Reply-To: LitProg@SHSU.edu, chuckb@U.WASHINGTON.EDU
To: LitProg@SHSU.edu
Subject: How do I view .idx .scn and .tex files on SGI?
 
I built the cweave package and would like to view the files generated by
the examples.  I have access to postscript hardcopy and ghostscript.
Unfortunately I don't have a tex veiwer (not one that man -k could find).
Any pointers would be appreciated.
 
chuckb
 
From norman@bellcore.com Tue Aug 10 16:26:14 -0400 1993
Date: Tue, 10 Aug 93 16:26:14 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Publishing WEB programs
 
> Which brings to mind a problem I've been pondering for a while.  For
> those of us in a ``publish or perish'' situation, how do we convince
> our administrators that literate programs made available via ftp (or,
> indeed, articles in the same situation) are bona fide publications (as
> I would maintain they are).  I've been toying with the idea of using a
> ``Virtual Press'' designation, but haven't actually done anything
> in that vein as yet.  Any ideas?
 
You don't, because they're not.  More than anything else, they are
like technical reports, many of which are made available for ftp these
days.  The problem with ftp is that the audience is unknown (but
probably small), and there is no review process.  Some publications,
like SIGPLAN Notices, require only the concurrence of the editor for
publication.  Others require peer review.  In my experience, peer
review improves work enormously.  I seldom spend time reading
technical reports available by ftp if the same work has been published
in a reputable conference or journal.
 
SIGPLAN Notices may be a reasonable place to attempt to publish a
literate program.  So might Software---Practice & Experience, if the
program met SP&E's charter of having something useful to offer to
practitioners.
 
Norman
 
From Lee Wed Aug 11 11:00:12 EDT 1993
Date: Wed, 11 Aug 93 11:00:12 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, bos@mdd.comm.mot.com
Subject: Re: Publishing WEB programs
 
Mary Bos writes:
 
> Why not have a refereed "Virtual Press" or electronic forum?  Reiterating
> my initial statement, "For those of us still floundering
> around in the various WEB's, reading other people's weaves may help us
> gain a style and code organization."  
 
Sounds like a good idea to me.  Although I do not have the
organizational skills to run such a forum, I would certainly be
willing to serve as a referee.  Perhaps Mary would be willing to serve
as coordinator, as no actual webbing experience is necessary for the
job (although an interest is certainly helpful).
 
		-- Lee
 
From Lee Wed Aug 11 11:21:30 EDT 1993
Date: Wed, 11 Aug 93 11:21:30 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, chuckb@u.washington.edu
Subject: Re: How do I view .idx .scn and .tex files on SGI?
 
Charles (Chuck?) Bass writes:
 
> I built the cweave package and would like to view the files generated by
> the examples.  I have access to postscript hardcopy and ghostscript.
> Unfortunately I don't have a tex veiwer (not one that man -k could find).
> Any pointers would be appreciated.
 
I had the same problem with a NeXT machine that we have.  It turned
out that there was a copy of ``dvips'' on the machine, even though
``man'' couldn't find it.  You might want to try dvips or dvi2ps (?),
both of which are available via ftp (from the usual places).  The
source code for the former (and probably the latter, as well) is also
available, if you need to compile a new version.
 
		-- Lee
 
From Matthias Wed Aug 11 18:44:57 +0200 1993
Date: Wed, 11 Aug 1993 18:44:57 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu
Subject: Re: How do I view .idx .scn and .tex files on SGI?
 
Lee Wittenberg <leew@pilot.njin.net> writes:
>Charles (Chuck?) Bass writes:
>> I built the cweave package and would like to view the files generated by
>> the examples.  I have access to postscript hardcopy and ghostscript.
>> Unfortunately I don't have a tex veiwer (not one that man -k could find).
>> Any pointers would be appreciated.
>
>I had the same problem with a NeXT machine that we have.  It turned
>out that there was a copy of ``dvips'' on the machine, even though
>``man'' couldn't find it.  You might want to try dvips or dvi2ps (?),
 
Depending on what Charles meant by 'viewer', he might also want xdvi,
which displays TeX output on the screen.
 
Matthias
 
-----
Matthias Neeracher                                neeri@iis.ee.ethz.ch
   "One fine day in my odd past..." -- Pixies, _Planet of Sound_
 
From bos@mdd.comm.mot.com Wed Aug 11 10:19:50 PDT 1993
Date: Wed, 11 Aug 93 10:19:50 PDT
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
To: LitProg@shsu.edu, leew@pilot.njin.net
Subject: Re: Publishing WEB programs
 
> From leew@pilot.njin.net Wed Aug 11 08:00:34 1993
> Date: Wed, 11 Aug 93 11:00:12 EDT
> From: Lee Wittenberg <leew@pilot.njin.net>
> To: LitProg@shsu.edu, bos@mdd.comm.mot.com
> Subject: Re: Publishing WEB programs
> Content-Length: 590
> 
> Mary Bos writes:
> 
> > Why not have a refereed "Virtual Press" or electronic forum?  Reiterating
> > my initial statement, "For those of us still floundering
> > around in the various WEB's, reading other people's weaves may help us
> > gain a style and code organization."  
> 
> Sounds like a good idea to me.  Although I do not have the
> organizational skills to run such a forum, I would certainly be
> willing to serve as a referee.  Perhaps Mary would be willing to serve
> as coordinator, as no actual webbing experience is necessary for the
> job (although an interest is certainly helpful).
> 
> 		-- Lee
> 
Mary replies
 
Sure, if others will explain what the co-ordinator needs to do.
 
mary bos
 
From preston@cs.rice.edu Wed Aug 11 12:57:25 CDT 1993
Date: Wed, 11 Aug 93 12:57:25 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: Re: How do I view .idx .scn and .tex files on SGI?
 
Given the subject line, I think you want to run tex first.
Tex takes a .tex file as input and produces a .dvi file.
The .dvi can often be printed directly, perhaps using
 
	lpr -d zap.dvi
 
or converted to postscript, via
 
	dvips -o zap.ps zap.dvi
 
You really want to find some local tex expert to introduce you to
all the tools.
 
Preston Briggs
 
From marcus@x4u.desy.de Wed Aug 11 19:58:25 +0200 1993
Date: Wed, 11 Aug 93 19:58:25 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, bos@mdd.comm.mot.com
Subject: Re: Publishing WEB programs
 
If there is sufficient interest, you may use the organization of
Usenet University for the 'virtual press'. UU has already got a
Virtual Campus on the MediaMOO at MIT.
I have recently entered UU's board of directors, and we can talk about
it (Mary, and who else is interested) any time, maybe privately.
 
----------------------- UU-NNA on the World Wide Web ---------------------
For info on UU-NNA's info pages on www, please send mail to
listserv@info.cern.ch, with the body of the mail containing the message
 
   send file://ftp.desy.de/pub/www/projects/Announce/UsenetUniversity
 
if you already are on the WWW, try URL
 
	http://uu-nna.mit.edu:8001/
 
From Martin Fri Aug 13 12:36:07 +0200 1993
Date: Fri, 13 Aug 1993 12:36:07 +0200
From: Martin Prange <prange@cs.tu-berlin.de>
Reply-To: LitProg@SHSU.edu, prange@CS.TU-BERLIN.DE
To: LitProg@SHSU.edu
Subject: Usenet-Newsgroup
 
YES,YES,YES
 
From Dave Fri Aug 13 17:22:10 BST 1993
Date: Fri, 13 Aug 93 17:22:10 BST
From: Dave Barton (visitor) <dbarton@computer-science.manchester.ac.uk>
Reply-To: LitProg@SHSU.edu, dbarton@COMPUTER-SCIENCE.MANCHESTER.AC.UK
To: LitProg@shsu.edu
Subject: A Related Effort
 
I spotted this on one of the comp.lang newsgroups, and thought it
might be of interest to the literate programming community.  It might
prove a useful adjunct to things such as noweb which do not attempt
typsetting of their code.
					Dave Barton
					dlb@hudson.wash.inmet.com
----------------------------------------------------------------
Path: mucs!nessie!uknet!glasgow!pop
From: pop@dcs.glasgow.ac.uk (Robin Popplestone)
Newsgroups: comp.lang.c,comp.lang.functional,comp.lang.pop
Subject: Re: Coding Standards ... we are in the 90's
Date: 12 Aug 93 10:35:16 GMT
Organization: Computing Sci, Glasgow Univ, Scotland
Lines: 41
Xref: mucs comp.lang.c:65549 comp.lang.functional:3367 comp.lang.pop:511
 
When I started computing (in 1963) I thought a teletype was a wonderful
device. Give or take the odd extra case, almost all computer scientists still
think so - the presentation of computer programs is STILL determined by the
ways in which electro-mechanical devices could put marks on pieces of paper,
and for that matter, what is taught as the "theory" of computer languages is
still too often about how a sequence of ascii characters can be parsed.
 
Strangely, the rest of the world has moved on, and communes daily with bitmap
displays and laser printers. *Pantechnicon* is an attempt to persuade
programmers that they actually live in 1993. Essentially, it supports
a mapping from the abstract syntax (AS) of a program to typographical abstract
syntax (TAS), which is then displayed using the capabilities of a modern
machine. TAS is loosely based on TEX, but of course is a datatype not
a concrete syntax.
 
The latest version, under development at Glasgow, and funded by HMG is, in a
broad sense, object oriented in a modern (i.e. Hindley-Milner typed)
functional context.  It is intended to be used to present *any* programming
language in a style which is uniform across standard programming constructs.
Object orientation is implemented by *method maps* which have the type
signature (SML convention)
 
      Identifier -> 'a Expr -> 'a Style -> TAS
 
Uniformity of presentation is derived by inheritance of a standard suite of
methods, for presenting constructs like addition, while-loops, conditionals.
To define a presenter for a given language, a parser is needed, together with
methods for constructs whose detail is usually specific to the language,
like  for-loops and function/procedure definitions.
 
The default treatment of identifiers is to parse the identifier into
<root>_<suffix>. Thus x_max parses into x and max. Both root and suffix
may then be mapped into non-ascii characters. E.g. alpha is mapped into the
greek symbol. This mapping is "soft" and carried in a Style record (my first
attempt to present C had int mapped into the integral sign, since I was using
a mathematical map derived from Latex...).
 
Robin Popplestone.
 
From Charles Fri Aug 13 22:02:15 -0500 1993
Date: Fri, 13 Aug 1993 22:02:15 -0500
From: Charles Blair <ceblair@ux1.cso.uiuc.edu>
Reply-To: LitProg@SHSU.edu, ceblair@UX1.CSO.UIUC.EDU
To: LitProg@SHSU.edu
Subject: cweave 3.0: problem with \UNIX/
 
   While trying to print the treeprin example, I get an error message
from TeX complaining about the control sequence \UNIX\ in treeprin.tex
(created by cweave) not being understood by cwebmac.tex, which has
a definition beginning 
 
    \def\UNIX/{{ ...
 
From krommes@theory.pppl.gov Mon Aug 16 09:23:19 EDT 1993
Date: Mon, 16 Aug 93 09:23:19 EDT
From: krommes@theory.pppl.gov (John Krommes)
Reply-To: LitProg@SHSU.edu, Krommes@princeton.edu
To: litprog@shsu.edu
Subject: FWEB on the SGI: processing // comments
 
Recently Michael Koopman reported to this mailing list that FWEB didn't
process short (//) comments correctly in Fortran on the SGI.  This problem
results from the SGI header file ctype.h, which violates the ANSI standard:
it doesn't deal correctly with characters with the high bit set.  See
ftp/pppl/gov:/pub/fweb/READ_ME for the SGI fix.  I'll deal with this more
generally for future releases.
 
--- John                      (Mail to krommes@princeton.edu is forwarded to
                              krommes@lyman.pppl.gov == 198.35.4.70.  
krommes@princeton.edu         Ftp files to/from ftp.pppl.gov, NOT princeton.edu
                              or lyman.pppl.gov.)
 
From Lee Tue Aug 17 9:15:51 EDT 1993
Date: Tue, 17 Aug 93 9:15:51 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, ceblair@ux1.cso.uiuc.edu
Subject: Re: cweave 3.0: problem with \UNIX/
 
>    While trying to print the treeprin example, I get an error message
> from TeX complaining about the control sequence \UNIX\ in treeprin.tex
> (created by cweave) not being understood by cwebmac.tex, which has
> a definition beginning 
> 
>     \def\UNIX/{{ ...
> 
 
It looks like treeprin.w was developed under an earlier version of
CWEB, when \UNIX was def'ed as
 
	\def\UNIX{{ ...
 
The fix is simply to change \UNIX\ in treeprin.w to \UNIX/, and
everything should work fine.  Actually, this should be changed in the
original at labrea.stanford.edu (mirror sites as well).  There are
probably other obsolete macro problems in some of the other examples.
 
		-- Lee
 
From Matthias Tue Aug 17 16:47:11 +0200 1993
Date: Tue, 17 Aug 1993 16:47:11 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: litprog@shsu.edu
Subject: Progress on comp.programming.literate newsgroup creation
 
The discussion period for comp.programmin.literate will last one more week. The
call for votes will appear next monday, and a copy, containing detailed voting
instructions, will appear on this mailing list. Voting will start August 23rd
and will last for 22 days and 22 nights :-).
 
If you would like a copy of the newsgroup proposal, mail me.
 
Matthias
 
-----
Matthias Neeracher                                    neeri@iis.ee.ethz.ch
  "I didn't get where I am today by being wise!" -- Lawrence D'Oliveiro
 
From norman@bellcore.com Sat Aug 21 12:50:11 -0400 1993
Date: Sat, 21 Aug 93 12:50:11 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: tex/latex help wanted
 
I'm trying to rig some nifty new index support for noweb, and I'm running
into trouble because my TeX is rusty.  I want to define a macro
  \countme#1{...}
such that I can use \countme{...} where TeX normally expects a <number>,
e,g,
  \count255=\countme{...}
  \ifnum\countme{...}=1 page\else pages\fi
 
So far the best I have been able to come up with is a macro that makes a 
global assignment to a counter, which I then use. e.g,
 
  \countme{...}\count255=\countmecounter
  \countme{...}\ifnum\countmecounter=1 page\else pages\fi
 
I find this ugly and nonintuitive.  Can anyone help?
 
Norman
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sun Aug 22 09:38:49 +0200 1993
Date: Sun, 22 Aug 93 09:38:49 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: tex/latex help wanted
 
   From: norman@bellcore.com (Norman Ramsey)
   Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
 
   I'm trying to rig some nifty new index support for noweb, and I'm running
   into trouble because my TeX is rusty.  I want to define a macro
     \countme#1{...}
   such that I can use \countme{...} where TeX normally expects a <number>,
   e,g,
     \count255=\countme{...}
     \ifnum\countme{...}=1 page\else pages\fi
 
   So far the best I have been able to come up with is a macro that makes a 
   global assignment to a counter, which I then use. e.g,
 
     \countme{...}\count255=\countmecounter
     \countme{...}\ifnum\countmecounter=1 page\else pages\fi
 
   I find this ugly and nonintuitive.  Can anyone help?
 
W E L L, the easiest way to let a macro represent a number is
plain text.
After
\def\xxx{123 }, you can use \xxx almost anywhere where you can use
a number. Suppose you want to assign it from a count variable
called \foo. You can do this by saying
\edef\xxx{\number\foo\space}
I am using \space here to produce the number-ending space, because
simply typing a space won't work (skipped after the control word
\foo). Of course, you can write things like
\ifnum\xxx=1
For your specific problem you have not given the circumstances,
what \countme should produce from its arguments, so I cannot be of
any more help.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sun Aug 22 09:38:49 +0200 1993
Date: Sun, 22 Aug 93 09:38:49 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: tex/latex help wanted
 
   From: norman@bellcore.com (Norman Ramsey)
   Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
 
   I'm trying to rig some nifty new index support for noweb, and I'm running
   into trouble because my TeX is rusty.  I want to define a macro
     \countme#1{...}
   such that I can use \countme{...} where TeX normally expects a <number>,
   e,g,
     \count255=\countme{...}
     \ifnum\countme{...}=1 page\else pages\fi
 
   So far the best I have been able to come up with is a macro that makes a 
   global assignment to a counter, which I then use. e.g,
 
     \countme{...}\count255=\countmecounter
     \countme{...}\ifnum\countmecounter=1 page\else pages\fi
 
   I find this ugly and nonintuitive.  Can anyone help?
 
W E L L, the easiest way to let a macro represent a number is
plain text.
After
\def\xxx{123 }, you can use \xxx almost anywhere where you can use
a number. Suppose you want to assign it from a count variable
called \foo. You can do this by saying
\edef\xxx{\number\foo\space}
I am using \space here to produce the number-ending space, because
simply typing a space won't work (skipped after the control word
\foo). Of course, you can write things like
\ifnum\xxx=1
For your specific problem you have not given the circumstances,
what \countme should produce from its arguments, so I cannot be of
any more help.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From norman@bellcore.com Mon Aug 23 14:28:55 -0400 1993
Date: Mon, 23 Aug 93 14:28:55 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: tex/latex help redux
 
OK, sorry I didn't give everyone enough information.
I'm trying to write a TeX macro that counts the number of elements in
a list and produces the result as a <number>, so I can write, for
example, \count99=\countme{\\{a}\\{b}\\{c}} and have that be
equivalent to \count99=3.  Similarly I'd like to write
 
\def\pageword#1{\ifnum\countme{#1}=1 page\else pages\fi}
 
But I haven't been able to figure out how to do it --- the best I can
do is have the macro make a global assignment to a counter and then
test the counter.  This is ugly.  Here's the code I've defined:
 
  \newcount\nwix@counter
  \def\nwix@listcount#1{% {list with \\}
    {\count255=0
     \def\\##1{\advance\count255 by 1 }%
     #1\global\nwix@counter=\count255 }}
 
Here's an example use:
 
  \newcount\@commacount
  \def\commafy#1{%
    {\nwix@listcount{#1}\@commacount=\nwix@counter
     \let\@comma@each=\\%
     \ifcase\@commacount\let\\=\@comma@each\or\let\\=\@comma@each\or
       \def\\{\def\\{ and \@comma@each}\@comma@each}\else
       \def\\{\def\\{, %
                     \advance\@commacount by -1
                     \ifnum\@commacount=1 and \fi\@comma@each}\@comma@each}\fi
     #1}}
 
Any help would be appreciated.
 
Norman
 
From dak@POOL.Informatik.RWTH-Aachen.DE Tue Aug 24 08:16:37 +0200 1993
Date: Tue, 24 Aug 93 08:16:37 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: norman@bellcore.com
Subject: Re: tex/latex help redux
 
   Date: Mon, 23 Aug 93 14:28:55 -0400
   From: norman@bellcore.com (Norman Ramsey)
   Cc: dak@pool.Informatik.RWTH-Aachen.DE, levy@math.berkeley.edu
 
   OK, sorry I didn't give everyone enough information.
   I'm trying to write a TeX macro that counts the number of elements in
   a list and produces the result as a <number>, so I can write, for
   example, \count99=\countme{\\{a}\\{b}\\{c}} and have that be
   equivalent to \count99=3.  Similarly I'd like to write
 
   \def\pageword#1{\ifnum\countme{#1}=1 page\else pages\fi}
 
Uh oh. You have a problem. The way you use \countme here, it needs to
work by expansion, and TeX does not do assignments or arithmetic when
expanding.
 
You Could do this by emulating the process of counting up with
carrying by expansion, but I have to work on this.
 
   But I haven't been able to figure out how to do it --- the best I can
   do is have the macro make a global assignment to a counter and then
   test the counter.  This is ugly.  Here's the code I've defined:
 
     \newcount\nwix@counter
     \def\nwix@listcount#1{% {list with \\}
       {\count255=0
	\def\\##1{\advance\count255 by 1 }%
	#1\global\nwix@counter=\count255 }}
 
Personally, I'd prefer not to do this globally, and not in a separate group.
If your \\ definition needs to be local, you can make the assignment
nonlocal by ending with:
\expandafter}\expandafter\nwix@counter\number\count255\relax}
This will temporarily convert the number into literal form.
 
However, instead of using \nwix@counter, I'd pass a counter name to be used
to your counting macro.
 
From Jim Tue Aug 24 08:00:13 -0400 1993
Date: Tue, 24 Aug 93 08:00:13 -0400
From: Jim Van Zandt <jrv@mbunix.mitre.org>
Reply-To: LitProg@SHSU.edu, jrv@MBUNIX.MITRE.ORG
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: Publishing WEB programs
 
In message <9308102026.AA27701@mailee.bellcore.com> you write:
>
>> Which brings to mind a problem I've been pondering for a while.  For
>> those of us in a ``publish or perish'' situation, how do we convince
>> our administrators that literate programs made available via ftp (or,
>> indeed, articles in the same situation) are bona fide publications (as
>> I would maintain they are).  
>
>The problem with ftp is that the audience is unknown (but
>probably small), and there is no review process.  Some publications,
>like SIGPLAN Notices, require only the concurrence of the editor for
>publication.  Others require peer review.  In my experience, peer
>review improves work enormously.  I seldom spend time reading
>technical reports available by ftp if the same work has been published
>in a reputable conference or journal.
> 
 
How about publishing in comp.sources.reviewed?
 
Incidently, it's a volunteer effort - have you reviewed something
published there recently?  (No, I haven't either.)
 
                                   - Jim Van Zandt <jrv@mitre.org>
 
From kap1@tao.cpe.uchicago.edu Tue Aug 24 11:15:17 CDT 1993
Date: Tue, 24 Aug 93 11:15:17 CDT
From: kap1@tao.cpe.uchicago.edu (Dietrich Kappe)
Reply-To: LitProg@SHSU.edu, kap1@TAO.CPE.UCHICAGO.EDU
To: litprog@shsu.edu
Subject: Litprog Digest
 
``I can already envision the appearance of a new journal, to be
entitled {\it Webs}, for the publication of literate programs; I
imagine that it will have a large backlog and a large group of
dedicated editors and referees.''
 
	--- Donald  E. Knuth, ``Literate Programming (1984)''
 
Seeing as this once failed (ACM ?) in printed form, perhaps an
electronic form, somewhat later in the day, might succeed. I am
interested in organizing/editing.
 
I envision the distribution to be in source/tex/postscript form.
Any interested parties should contact me by email.
 
---
 
Dietrich Kappe
kap1@wimpy.uchicago.edu
 
From Dave Tue Aug 24 17:45:42 GMT 1993
Date: Tue, 24 Aug 93 17:45:42 GMT
From: Dave Love <d.love@daresbury.ac.uk>
Reply-To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
To: litprog@shsu.edu
Subject: [comp.lang.dylan] The Igor Project
 
The proposed `hypercode' system described in this edited version of a
posting to usenet may be of general interest.  (Or maybe not, as
no-one else has sent it on...)
 
------- Start of forwarded message -------
Newsgroups: comp.lang.dylan
From: sef@sef-pmax.slisp.cs.cmu.edu
Subject: The Igor Project
Nntp-Posting-Host: sef-pmax.slisp.cs.cmu.edu
Organization: School of Computer Science, Carnegie Mellon
Date: Tue, 17 Aug 1993 05:04:48 GMT
 
Igor is a new ARPA-funded research project in Carnegie Mellon University's
School of Computer Science.  I am the project leader, and it is staffed by
the wizards of the former CMU Common Lisp project, plus a few new faces.
We have been working informally on Igor and Dylan since last April, while
finishing up some loose ends on CMU CL.  As I announced earlier, CMU CL
will still be available, and we will continue to support it, though at a
considerably reduced level of effort.
 
[...]
 
The Igor development environment will be built around a concept we call
"hypercode" (analogous to "hypertext").  Code in Igor will not be a linear
string of ASCII characters, but rather a complex data structure linking
together routines, class definitions, comments, specifications, diagrams,
test code, edit histories, configuration info, and more.  The programmer
will be able to view and browse this hypercode at many levels of detail,
and the code definitions can be presented in whatever order makes the most
sense at the time.  (In some ways this is reminiscent of the old Interlisp
environment.)  An extensive library of classes and functions will also be
available, with librarian software to guide users in finding what they
needs.
 
[...]
 
-- Scott
 
Scott E. Fahlman			Internet:  sef+@cs.cmu.edu
Senior Research Scientist		Phone:     412 268-2575
School of Computer Science              Fax:       412 681-5739
Carnegie Mellon University		Latitude:  40:26:33 N
5000 Forbes Avenue			Longitude: 79:56:48 W
Pittsburgh, PA 15213
 
------- End of forwarded message -------
 
From norman@bellcore.com Tue Aug 24 15:40:26 -0400 1993
Date: Tue, 24 Aug 93 15:40:26 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: publishing programs
 
I think part of the difficulty in publishing literate programs is that
the program itself must be of interest, and it is hard to find
interesting programs that warrant treatment at less than book length.
The kinds of things I have seen published in the past include
algorithms, tools, and systems.  Algorithms tend to be so small that
any form of presentation works, although I suspect there might be a
niche for complete implementations of complex algorithms and data
structures.  The implementation of tools tends to be mostly of
pedagogical interest, and it is more likely to be found in textbooks
than in journal articles.  The best example is _Software Tools_, which
I think is a classic of literate programming, although it predates the
coinage of the term.
 
So systems is where I think the action is.  For example, I think Wirth
and Gutknecht's book on the Oberon project could have been improved
substantially by the use of literate-programming tools.  Ditto Holub's
_Compiler Design in C_.  I can think of a number of ``how to cope with
DOS/Windows/NT'' sorts of books that could benefit from such
treatment.  Unfortunately my friends and I don't write these books,
and I don't know who does.
 
Does anyone out there have experience writing or publishing books
containing lots of code?
 
Norman Ramsey
 
From Matthias Wed Aug 25 11:39:41 +0200 1993
Date: Wed, 25 Aug 1993 11:39:41 +0200
From: Matthias Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: litprog@shsu.edu
Subject: Vote on newsgroup creation
 
[The vote on the creation of a newsgroup to supplement this mailing
 list has started, and you are welcome to participate in the vote by
 following the instructions below. However, try to make sure that your
 vote *ONLY* goes to the vote taker, and *NOT* to the mailing list. 
 Unfortunately, a lot of mail software is configured to send a copy 
 to the list by default -- Matthias]
 
                      CALL FOR VOTES (1st of 2)
 
Unmoderated group comp.programming.literate
 
Newsgroups line:
comp.programming.literate	Literate programs and programming tools.
 
Votes must be received by 14 Sep 1993 23:59:59 GMT.
 
This vote is being conducted by a neutral third party. For voting
questions only, contact dave@dogwood.com. For questions about the
proposed group, contact Matthias Neeracher <neeri@iis.ee.ethz.ch>.
 
A copy of this Call For Votes will be sent to LitProg@shsu.edu after
the original Call For Votes appears in news.announce.newgroups.
 
STANDARD VOTING INFO
 
You should send MAIL (posts to a group are invalid) to
      vote@dogwood.com
(just replying by MAIL to this message should work). Your mail
message should contain one and only one of the following statements:
 
      I vote YES on comp.programming.literate
or
      I vote NO on comp.programming.literate
 
You may add a comment, but anything other than a definite statement
involving the group name and "yes", "no", "for", or "against" on a
single line may be rejected by the automatic vote counting program.
If you later change your mind you may also use send in an "abstain"
vote in the same manner, using "abstain" in place of "yes" or "no".
 
Standard Guidelines for voting apply - one vote per person (not per
account). 100 more YES votes than NO votes and 2/3 of all votes being
YES are the requirements for group creation.
 
Votes will be acknowledged by email; a list of bounced acknowledgements
will be posted with the second Call For Votes. A mass acknowledgement
will NOT be posted. You may inquire about the status of your vote by
emailing the vote-taker (dave@dogwood.com).
 
After the results have been announced a complete list of the votes
will be posted in news.groups and will be mailed on request (email
requests to dave@dogwood.com).
 
The vote-taker can accept no responsibility for improperly configured
mailers.
 
CHARTER
 
Charter: A forum for the discussion of issues related
   to literate programming.
 
(1) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
(2) To discuss the merits of the currently existing literate
    programming tools.
 
(3) To discuss the design of new literate programming tools.
 
If a newsgroup is created, it will be mirrored to the existing mailing list
LitProg@shsu.edu.  For reference purposes, the newsgroup will be fully archived
by the host sponsoring the mailing list.
 
Background: What is Literate Programming?
 
Literate programming is a programming technique invented by Donald. E. Knuth.
A literate programming system can be characterized by the following properties:
 
 - The compilable program and the publishable documentation should be
   generated *automatically* from a *single* document.
 
 - The program can be presented in the order that is best for human
   understanding, regardless of any requirements of the programming
   language.
 
 - The program should be automatically indexed and cross-referenced.
 
Knuth's original system, called WEB, generated Pascal code and a TeX
documentation. Most tools relating to the TeX system have been written
using WEB, and the TeX and Metafont programs have been published in book
form.
 
Today, there are Literate Programming systems for a wide range of
programming languages and documentation systems. Specialized Literate
Programming tools have been written for Ada, Awk, C, C++, Fortran,
Modula-2, Modula-3, Pascal and Scheme, and generic tools exist that
can generate almost any programming language (including Perl and sh).
 
Documentation systems supported include TeX, Troff, and Word for
Windows.
-- 
Dave Cornejo                                There is nothing so subtle
Dogwood Media                                           as the obvious
Fremont, California
 
From ddw2@sunbim.be Wed Aug 25 11:49:36 +0200 1993
Date: Wed, 25 Aug 93 11:49:36 +0200
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@shsu.edu
Subject: nuweb.el (1.15)
 
For those who use nuweb, FSF Emacs 19, and auctex.
 
A while back I sent a very early version of this mode on the list.
Meanwhile, it has evolved and has become more robust and flexible.
 
Basically it visits .w files in Latex mode augmented with a few
commands which allow to insert scrap templates and to edit scrap
bodies in the correct language mode.
 
Hope some of you find it useful. I do....
 
Dominique
 
Dominique de Waleffe             ddw@sunbim.be
BIM sa
Chaussee de Louvain, 510	 Tel: +32 2 719 26 14
B-1930 Zaventem			 Fax: +32 2 725 47 83
Belgium
 
;;;-------------------------------------------------------------------
;;; nuweb.el --- major mode to edit nuweb files with AucTex
;;;
;;;  $Id: nuweb.el,v 1.15 1993/08/13 06:59:35 ddw2 Exp ddw2 $ 
;;;
;;; Author: Dominique de Waleffe (ddw@sunbim.be)
;;; Maintainer: Dominique de Waleffe (ddw@sunbim.be)
;;;
;;; Copyright (C) BIM sa, Everberg, Belgium 1993
;;;
;;; This nuweb support package is free software, just as GNU Emacs; 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, or (at your option) any later version.
 
;; GNU Emacs is distributed in the hope that it will be useful, but
;; WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or 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
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
;;; 
;;; Bug reports , suggestions are  welcome. I'll see if I can do anything in
;;; my copious spare time :-)
 
;;; DOCUMENTATION (short) there is no long version yet:-)
;;;  To install:
;;;     ; if your version of nuweb does not know about @% comments 
;;;     (setq nuweb-comment-leader "") 
;;;     ; if you want to activate the mode for .w files
;;;     (push auto-mode-alist '( "\\.w" . nuweb-mode))
;;;     ; To load it
;;;     (require 'nuweb)
;;; 
;;; When called, nuweb-mode calls latex-mode and adds the following
;;; bindings: 
;;;       C-c C-z nuweb-edit-this scrap 
;;;           Edit the scrap point is on in its own buffer *Source*
;;;           put into the mode specified by the buffer local variable
;;;           nuweb-source-mode (defaults "emacs-lisp") or into the
;;;           mode specified after @{ (on same line)  the scrap body as
;;;           -*-mode-name-*- 
;;;           The *Source* buffer is then put into Nuweb minor mode
;;;           which adds two bindings:
;;;           C-c C-z nuweb-install-this-scrap
;;;               Which takes the *Source* buffer contents and puts
;;;               it back into the web buffer in place of the old
;;;               version of the scrap.
;;;           C-c M-k nuweb-kill-this-scrap
;;;               Which restores the old scrap, ignoring changes
;;;               made.
;;;           The original buffer is put in read-only mode until you
;;;           call one of the two above functions or kill the
;;;           *Source* buffer. 
;;;       C-@ nuweb-insert-scrap
;;;           With no argument: inserts an empty scrap template at
;;;           point.
;;;           With an argument: prompt for scrap type (oDdD), scrap
;;;           name and language mode. A new scrap is inserted and
;;;           edited as if nuweb-edit-this-scrap had been called.
;;;
;;; CUSTOMISATION: 
;;;
;;; Change language mode for scraps
;;; (setq-default nuweb-source-mode "mode-name-function(without -mode)")
;;; (setq-default nuweb-source-mode "prolog") ;default for all buffers
;;; or (setq nuweb-source-mode "emacs-lisp") ; current one only
;;;
;;; Support for nuweb comments @% (I have patches to nuweb for that)
;;; (setq nuweb-comment-leader "@%")
 
;;; PROBLEMS:                    SOLUTION:
;;; -) Requires AucTex		 Get it from /iesd.auc.dk:
;;; -) Relies on FSF Emacs 19    Upgrade or make the package
;;; 				 back-compatible 
;;; -) Functions are not well    I should have used nuweb for this
;;;    documented
;;; -) Bindings may not suit     Change as you like
;;;    every one
;;;
;;; WISH LIST:
;;; -) movement through nuweb items (outline? tags?)
;;; -) menu?
;;;
;;; CONTRIBUTIONS:
;;; Thorbj{\o}rn Andersen <ravn@imada.ou.dk> suggested the use of C-c C-z
;;;      I used it to get into the *source* and as normal exit key.
;;;      Also suggested the simple (no prompts) insertion  of a scrap
;;;      template, and other things.
;;; 
;;; AVAILABILITY:
;;; Should be available SHSU archives
;;; or from ftp.imada.ou.dk (thanks to <ravn@imada.ou.dk>
;;; or from by email from me
;;;
 
(require 'tex-site) ; I'm not sure that this is enough
 
;;; Extend the list of commands
(setq TeX-command-list
      (cons 
       (list "Web" "nuweb %s ; latex '\\nonstopmode\\input{%t}'" 'TeX-LaTeX-hook nil t)
       TeX-command-list))
 
;;; allow .w as extension
(setq TeX-file-extensions '("tex" "sty" "w"))
 
(defvar nuweb-mode-map nil)
 
(defun nuweb-mode ()
  "Major mode to edit nuweb source files"
  (interactive)
  (latex-mode)
  (setq mode-name "nuweb")
  ;; Make sure the nuweb map exist
  (cond ((or (not (boundp 'nuweb-mode-map))
	     (null nuweb-mode-map))
	 ;; this keymap inherit the current local bindings
	 (setq nuweb-mode-map (cons 'keymap LaTeX-mode-map))
	 (define-key nuweb-mode-map 
	   "\C-c\C-z" 'nuweb-edit-this-scrap)
	 (define-key nuweb-mode-map 
	   "\C-c@" 'nuweb-insert-scrap)))
  ;; make sure we have our own keymap
  ;; we use a copy for in buffer so that outline mode is 
  ;; properly initialized
  (use-local-map (copy-keymap nuweb-mode-map))
  (make-local-variable 'nuweb-source-mode)
  (setq TeX-default-extension "w")
  (setq TeX-auto-update 'silent) ; disable untabify
  (setq TeX-command-default "Web"))
 
;; set this to "" if you dont have comments in nuweb
;; (I have patches to support @%)
(defvar nuweb-comment-leader "")
 
(defvar nuweb-last-scrap-title "") ; !!! look in above function
 
(defun nuweb-insert-scrap(arg)
  "Insert a scrap at current cursor location. With an argument, 
prompts for the type, name and editing mode then directly enter
the *Source* buffer. If no argument given, simply inserts a template
for a scrap"
  (interactive "P")
  (if arg
      (apply 'nuweb-insert-scrap-intern 
	     (list 
	      (concat (read-from-minibuffer "Type of scrap: " "d")" ")
	      (concat (setq nuweb-last-scrap-title 
			    (read-from-minibuffer
			     "Scrap title:" 
			     nuweb-last-scrap-title)) 
		      " ")
	      (read-from-minibuffer "Mode name:" nuweb-source-mode)
	      ;; edit if interactive
	      t))
    ;; first, shadow the variable use for default value
    (let (nuweb-last-scrap-title)
      (save-excursion 
	(nuweb-insert-scrap-intern "" "\n" nuweb-source-mode nil))
      (forward-char 1))))
 
(defun nuweb-insert-scrap-intern(type title modename editp)
  (save-excursion 
    (insert (format "@%s%s@{%s%s\n\n@| @}\n"
		    type title
		    nuweb-comment-leader
		    (if (equalp modename nuweb-source-mode)
			""
		      (concat " -*-" modename "-*-")))))
  (cond ( editp
	  (forward-line 1)
	  (nuweb-edit-this-scrap))))
 
; only one of those in effect....
(defvar *nuweb-last-scrap-pos* nil)
(defvar *nuweb-last-scrap-begin* nil)
(defvar *nuweb-last-scrap-end* nil)
 
(defun nuweb-edit-this-scrap ()
  (interactive)
  (cond((or (null *nuweb-last-scrap-pos*)
	    (y-or-n-p 
	     "You did not finish editing the previous scrap. Continue "))
	(setq *nuweb-last-scrap-pos* (point-marker))
	(let* ((begin (and (re-search-backward "@[dDoO{]" nil t) (point)))
	       (offset (- (marker-position *nuweb-last-scrap-pos*) begin))
	       (end (and (search-forward "@}" nil t)
			 (>= (point) (marker-position *nuweb-last-scrap-pos*))
			 (point)))
	       (text "")
	       (source-mode nuweb-source-mode))
	  (cond ( (and begin end)
		  (setq *nuweb-last-scrap-begin* begin)
		  (setq *nuweb-last-scrap-end* end)
		  (setq text (buffer-substring begin end))
		  (setq buffer-read-only t)
		  (switch-to-buffer-other-window "*Source*")
		  (erase-buffer)
		  (insert text)
		  (goto-char (point-min))
		  ;; look for -*-modename-*- behind @{
		  (search-forward "@{")
		  (if (looking-at ".*-\\*-[ \\t]*\\(.*\\)[ \t]*-\\*-.*$")
		      (setq source-mode 
			    (buffer-substring (match-beginning 1)
					      (match-end 1))))
		  (funcall (intern (concat 
				    (downcase source-mode) 
				    "-mode")))
		  ; go to same relative position
		  (goto-char (+ (point-min) offset))
		  ;; clean up when killing the *source* buffer
		  (make-local-variable 'kill-buffer-hook)
		  (add-hook 'kill-buffer-hook 
			    (function (lambda()
					(save-excursion
					  (nuweb-kill-this-scrap)))))
		  (nuweb-minor-mode 1)
		  (message "C-c C-z to use source, C-c M-k to abort"))
		(t (goto-char (marker-position *nuweb-last-scrap-pos*))
		   (setq *nuweb-last-scrap-pos* nil)
		   (error "Could not identify scrap")))))
       (t (message "Use C-x b and select buffer *Source* to finish"))))
 
(defvar nuweb-minor-mode-map nil)
(cond ((or (not (boundp 'nuweb-minor-mode-map))
	   (null nuweb-minor-mode-map))
       (setq nuweb-minor-mode-map (make-sparse-keymap))
       (define-key nuweb-minor-mode-map "\C-c\C-z" 'nuweb-install-this-scrap)
       (define-key nuweb-minor-mode-map "\C-c\M-k" 'nuweb-kill-this-scrap)
       ))
 
(defvar nuweb-minor-mode nil)
 
(make-variable-buffer-local 'nuweb-minor-mode)
 
(or (assq 'nuweb-minor-mode minor-mode-alist)
    (setq minor-mode-alist (cons '(nuweb-minor-mode " Nuweb")
				 minor-mode-alist)))
(or (assq 'nuweb-minor-mode minor-mode-map-alist)
    (setq minor-mode-map-alist (cons (cons 'nuweb-minor-mode 
					   nuweb-minor-mode-map)
				     minor-mode-map-alist)))
 
;;; The function is there but has nothing to do (thanks to Emacs 19 
;;; function for minor mode bindings
;;; It is here if anyone cares to make it Emacs 18 compatible.
(defun nuweb-minor-mode (arg)
  (interactive "P")
  (setq nuweb-minor-mode
	(if (null arg) (not nuweb-minor-mode)
	  (> (prefix-numeric-value arg) 0)))
  (cond (nuweb-minor-mode
	 ;; turn it on
	 ;; Nothin to do yet...
	 t
	 )
	(t
	 ;; turn it off
	 ;; Nothin to do yet...
	 nil
	 )))
 
(defun nuweb-install-this-scrap()
  (interactive)
  (let ((offset (point)))
    (nuweb-back-to-pos)
    (delete-region *nuweb-last-scrap-begin* *nuweb-last-scrap-end*)
    (insert-buffer "*Source*")
    (forward-char (- offset 1))
    (setq *nuweb-last-scrap-pos* nil)))
 
(defun nuweb-kill-this-scrap() 
  (interactive)
  (nuweb-back-to-pos) 
  (setq *nuweb-last-scrap-pos* nil))
 
(defun nuweb-back-to-pos()
  (setq kill-buffer-hook nil)
  (switch-to-buffer (marker-buffer *nuweb-last-scrap-pos*))
  (setq buffer-read-only nil)
  (delete-other-windows)
  (goto-char (marker-position *nuweb-last-scrap-pos*))
  (recenter))
 
(provide 'nuweb)
 
From hurst@vistatech.com Wed Aug 25 15:29:50 CDT 1993
Date: Wed, 25 Aug 93 15:29:50 CDT
From: hurst@vistatech.com (Dave Hurst)
Reply-To: LitProg@SHSU.edu, hurst@VISTATECH.COM
To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
Subject: Re: [comp.lang.dylan] The Igor Project
 
Hello!
 
I received a copy of your posting to comp.lang.dylan about the Igor
development environment, forwarded from the literate programming mailing 
list.
 
> The Igor development environment will be built around a concept we call
> "hypercode" (analogous to "hypertext").  Code in Igor will not be a linear
> string of ASCII characters, but rather a complex data structure linking
> together routines, class definitions, comments, specifications, diagrams,
> test code, edit histories, configuration info, and more.  The programmer
> will be able to view and browse this hypercode at many levels of detail,
> and the code definitions can be presented in whatever order makes the most
> sense at the time.  (In some ways this is reminiscent of the old Interlisp
> environment.)  An extensive library of classes and functions will also be
> available, with librarian software to guide users in finding what they
> needs.
 
This parallels work which we've been doing for the last 4-5 years in this
area.  We've developed a technology, called HyperWeb(tm), which supports
hypermedia-based software engineering and have spun off a product from that
development work, called PCTE Workbench(tm).  HyperWeb is an innovative
hypermedia-based software development environment which supports
development and maintenance activities.  You can model software as a web of
small components that reflects its natural design rather than the
constraints of your programming language.  The complex relationships between
the various software artifacts---requirements, designs, specifications,
code, test scripts, configurations, etc.---comprising a system are captured
and represented explicitly.  Frequently this knowledge exists only in the
minds of the individual developers working on the software.  Maintenance
programmers spend much of their time trying to recapture this knowledge.
With HyperWeb, this knowledge will not be lost when people leave a project.
The system supports not just text, but documents of any sort, so diagrams,
pictures, even voice annotations can be linked into the web.
 
Annotation, decomposition, and refinement operations provide support for
restructuring and documentation of the software artifacts.  Annotations are
an electronic version of yellow sticky notes stuck on a listing.  You can
annotate software artifacts to capture designer knowledge or to add
comments for on-line code inspections.  Decompositions are small conceptual
units within a larger software system.  Each decomposition focuses on
clearly presenting its logic and omits irrelevant details.  The
relationships between these decompositions represent the natural structure
of the system design.  The decompose operation allows you to break up
existing software into a smaller units during maintenance.  The refinement
operation allows you to create decompositions during new development.
 
HyperWeb augments the facilities provided by Unix, allowing you to use the
standard tools that you are already familiar with and to reap the benefits
of the software web approach.  Early on, we decided that trying to build
specialized editors to support hypertext was a waste of time because nobody
would use them.  Programmers are a fickle lot and get real upset if you try
to take away their favorite editor (or other tools), even if what you're
replacing it with is ``better.''  The sophisticated tool integration
framework provided by HyperWeb enables you integrate your existing set of
analysis, design, and development tools, so you need only change your work
habits minimally to get started.  As you become more experienced with it,
the benefits increase dramatically.  Ultimately, large parts of your
software development process can be automated with scripts customized for
your specific needs.
 
We have written a paper summarizing this work, which was published in
SIGSOFT SDE 5 last December:
 
	"HyperWeb: a Framework for Hypermedia-Based Environments",
	James C. Ferrans, David W. Hurst, et. al.
 
Another paper describing our work in building various hypermedia-based
environments, including HyperWeb, with our PCTE Workbench toolkit:
 
	"Building Diverse Environments with PCTE Workbennch," Adarsh K.
	Arora, David W. Hurst, and James C. Ferrans.  To appear at the
	PCTE '93 conference this November.
 
I'd be very interested in knowing more about the work you're doing.  Could
you possibly e-mail me more information about it?
 
--DaveH
----------------------------------------------------------------------------
David Hurst				internet: David-Hurst@vistatech.com
Vista Technologies, Inc.		voice: (708) 706-9300
1100 Woodfield Road			fax: (708) 706-9317
Schaumburg, IL  60173-5124  USA
 
		"Be excellent to each other!"
 
From hurst@vistatech.com Wed Aug 25 15:38:06 CDT 1993
Date: Wed, 25 Aug 93 15:38:06 CDT
From: hurst@vistatech.com (Dave Hurst)
Reply-To: LitProg@SHSU.edu, hurst@VISTATECH.COM
To: LitProg@SHSU.edu
Subject: Re: [comp.lang.dylan] The Igor Project
 
From the cyberdeck of Dave Love:
> The proposed `hypercode' system described in this edited version of a
> posting to usenet may be of general interest.  (Or maybe not, as
> no-one else has sent it on...)
>[...]
> The Igor development environment will be built around a concept we call
> "hypercode" (analogous to "hypertext").  Code in Igor will not be a linear
> string of ASCII characters, but rather a complex data structure linking
> together routines, class definitions, comments, specifications, diagrams,
> test code, edit histories, configuration info, and more.  The programmer
> will be able to view and browse this hypercode at many levels of detail,
> and the code definitions can be presented in whatever order makes the most
> sense at the time.  (In some ways this is reminiscent of the old Interlisp
> environment.)  An extensive library of classes and functions will also be
> available, with librarian software to guide users in finding what they
> needs.
 
This parallels work which we've been doing for the last 4-5 years in
this area.  Our original idea was to combine hypertext technology with
Knuth's WEB methodology.  As a result, we've developed a technology,
called HyperWeb(tm), which supports hypermedia-based software
engineering and have spun off a product from that development work,
called PCTE Workbench(tm).  HyperWeb is an hypermedia-based software
development environment which supports development and maintenance
activities.  You can model software as a web of small components that
reflects its natural design rather than the constraints of your
programming language.  The complex relationships between the various
software artifacts---requirements, designs, specifications, code, test
scripts, configurations, etc.---comprising a system are captured and
represented explicitly.  Frequently this knowledge exists only in the
minds of the individual developers working on the software.
Maintenance programmers spend much of their time trying to recapture
this knowledge.  With HyperWeb, this knowledge will not be lost when
people leave a project.  The system supports not just text, but
documents of any sort, so diagrams, pictures, even voice annotations
can be linked into the web.
 
Annotation, decomposition, and refinement operations provide support for
restructuring and documentation of the software artifacts.  Annotations are
an electronic version of yellow sticky notes stuck on a listing.  You can
annotate software artifacts to capture designer knowledge or to add
comments for on-line code inspections.  Decompositions are small conceptual
units within a larger software system.  Each decomposition focuses on
clearly presenting its logic and omits irrelevant details.  The
relationships between these decompositions represent the natural structure
of the system design.  The decompose operation allows you to break up
existing software into a smaller units during maintenance.  The refinement
operation allows you to create decompositions during new development.
 
HyperWeb augments the facilities provided by Unix, allowing you to use the
standard tools that you are already familiar with and to reap the benefits
of the software web approach.  Early on, we decided that trying to build
specialized editors to support hypertext was a waste of time because nobody
would use them.  Programmers are a fickle lot and get real upset if you try
to take away their favorite editor (or other tools), even if what you're
replacing it with is ``better.''  The sophisticated tool integration
framework provided by HyperWeb enables you integrate your existing set of
analysis, design, and development tools, so you need only change your work
habits minimally to get started.  As you become more experienced with it,
the benefits increase dramatically.  Ultimately, large parts of your
software development process can be automated with scripts customized for
your specific needs.
 
We have written a paper summarizing this work, which was published in
SIGSOFT SDE 5 last December:
 
	"HyperWeb: a Framework for Hypermedia-Based Environments",
	James C. Ferrans, David W. Hurst, et. al.
 
Another paper describing our work in building various hypermedia-based
environments, including HyperWeb, with our PCTE Workbench toolkit:
 
	"Building Diverse Environments with PCTE Workbennch," Adarsh K.
	Arora, David W. Hurst, and James C. Ferrans.  To appear at the
	PCTE '93 conference this November.
 
As it turns out, I've just unsub'ed from LitProg because I'm going on
vacation for a week or so.  But please CC any replies to this posting
to me directly.  I will be back on in about 10 days.
 
--DaveH
----------------------------------------------------------------------------
David Hurst				internet: David-Hurst@vistatech.com
Vista Technologies, Inc.		voice: (708) 706-9300
1100 Woodfield Road			fax: (708) 706-9317
Schaumburg, IL  60173-5124  USA
 
		"Be excellent to each other!"
 
----- End Included Message -----
 
From WMILHEIM@PSUGV.PSU.EDU Wed Aug 25 16:56:47 -0400 1993
Date: Wed, 25 Aug 1993 16:56:47 -0400 (EDT)
From: WMILHEIM@PSUGV.PSU.EDU (William Milheim)
Reply-To: LitProg@SHSU.edu, WMILHEIM@PSUGV.PSU.EDU
To: LITPROG@SHSU.EDU
Subject: Internet Survey
 
                              INTERNET SURVEY
 
                     Adele F. Bane <AFB2@PSUVM.PSU.EDU>
                 William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
              The Pennsylvania State University at Great Valley
________________________________________________________________________________
This electronic mail survey is being conducted to identify the functions of the 
Internet that are most used by the academic community.  You have been chosen as 
a member of a selected academic list service (LISTSERV) to participate.  
Results of this survey will form the basis of a journal article to be published 
later this year.  Please answer all survey questions.  
________________________________________________________________________________ 
 
INTERNET INSIGHTS:  A Survey
 
We will begin by asking a few questions about yourself:
 
	How many years of computer experience do you have?	_____  
	How long have you used e-mail of any type?		_____
	How long have you been an Internet user?		_____	
 
Three primary functions of the Internet have been identified.  They are 
electronic mail, Telnet or remote log-in, and FTP or file transfer.  An 
estimated 15 million users take advantage of these functions daily.  
This survey explores the use of each of these services.
 
1.  E-Mail Use:  How often do you make these connections?
 
	   (Insert the appropriate number beside items below:)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Private Email:					_____
 
		Discussion group(s):				_____
			(Specify)
 
		Usenet (or Netnews)				_____
 
		Electronic journal(s)/newsletters(s):		_____
			(Specify)
 
2.  Telnet Use:  How often do you connect to remote databases?
 
	   (Insert appropriate number beside items below.)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Games/Simulations:		_____
		Library Catalogs:		_____
	.	Specialized Databases:		_____
 
2a.  How frequently do you connect these Internet sources:
 
	   (Insert appropriate number beside items below.)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		American Mathematical Society BBS		_____
		American Psychological Assn.			_____
		CARL						_____
		CITADEL						_____
		Cleveland FreeNet				_____
		Dartmouth Dante					_____
		Dialog						_____
		Dow-Jones News Retrieval			_____
		Dranet						_____
		EDIN						_____
		EPA						_____
		ERIC						_____
		FEDIX/MOLIS					_____
		GenBank						_____
		Geographic Name Server				_____
		International Centre for Distance Learning	_____
		ISAAC						_____
		Lexis						_____
		Market/Business Report				_____
		National Education BBS				_____
		Netfind						_____
		Nexis						_____
		Oceanic Information Center			_____
		OCLC						_____
		PENpages					_____
		RLIN						_____
		SpaceLink					_____
		STIS						_____
		TC Forum					_____
		Weather Underground				_____
		Webster Dictionary				_____
 
		Other  (Please specify):
 
3.  FTP Use:  How often do you download files from FTP archive sites?
 
	   (Insert appropriate number beside each item)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Computers and Academic Freedom			_____
		EASI						_____
		History  					_____
		LIBSOFT						_____
		Lyric and Discography				_____
		NASA 						_____
		Online Libraries Directory			_____
		Science Education				_____
		SIMTEL20					_____
		SUMEX-AIM					_____
		U.S. Supreme Court Decisions			_____
		Washington Uni. Public Domain Archives		_____
 
		Other (Please Specify):
 
4.	Several navigational aids have been developed for the Internet.
	How often do you use these network guides?
 
	   (Insert appropriate number beside items below.)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Archie						_____
		Campus-wide Information Systems			_____		
		Gopher						_____
		WAIS (Wide-area information servers)		_____
		WWW (WorldWideWeb)				_____
		Veronica					_____
		HYTELNET					_____
		Other (Please specify):
 
Personal experiences can be the most helpful to other users.  Please comment on 
the following:
 
5.  	The importance of the Internet to your work?
 
6.  	Advantages the Internet offers over other resources?
 
7.  	Barriers to using the Internet?
 
8.  	Your most memorable use of the Internet?
 
9  These questions will help us interpret the results of this study:
 
	Title:	________________________________________
	Affiliation:  __________________________________	
	Discipline:  ___________________________________	
	Research Interest(s):____________________________________
	_________________________________________________________
 
Please return the completed survey to: WMILHEIM@PSUGV.EDU
by September 3, 1993.
 
If you would like a summary of the survey results, please place your
e-mail address here:  _____________________.
 
            :) Thank you for taking the time to participate :)
 
From Charles Wed Aug 25 16:06:33 -0700 1993
Date: Wed, 25 Aug 1993 16:06:33 -0700 (PDT)
From: Charles Bass <chuckb@u.washington.edu>
Reply-To: LitProg@SHSU.edu, chuckb@U.WASHINGTON.EDU
To: LitProg@SHSU.edu, WMILHEIM@PSUGV.PSU.EDU
Subject: Re: Internet Survey
 
On Wed, 25 Aug 1993, William Milheim wrote:
 
>                               INTERNET SURVEY
> 
>                      Adele F. Bane <AFB2@PSUVM.PSU.EDU>
>                  William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
>               The Pennsylvania State University at Great Valley
> ________________________________________________________________________________
> This electronic mail survey is being conducted to identify the functions of the 
> Internet that are most used by the academic community.  You have been chosen as 
> a member of a selected academic list service (LISTSERV) to participate.  
> Results of this survey will form the basis of a journal article to be published 
> later this year.  Please answer all survey questions.  
> ________________________________________________________________________________ 
> 
> INTERNET INSIGHTS:  A Survey
> 
> We will begin by asking a few questions about yourself:
> 
> 	How many years of computer experience do you have?	_12____  
> 	How long have you used e-mail of any type?		_3____
> 	How long have you been an Internet user?		_3____	
> 
> Three primary functions of the Internet have been identified.  They are 
> electronic mail, Telnet or remote log-in, and FTP or file transfer.  An 
> estimated 15 million users take advantage of these functions daily.  
> This survey explores the use of each of these services.
> 
> 1.  E-Mail Use:  How often do you make these connections?
> 
> 	   (Insert the appropriate number beside items below:)
> 
> 	1=Not at all			4=About 2-3 times a month
> 	2=A few times			5=Once a week
> 	3=About once a month		6=More than once a week
> 
> 		Private Email:					__6___
> 
> 		Discussion group(s):				___1__
> 			(Specify)
> 
> 		Usenet (or Netnews)				___6__
> 
> 		Electronic journal(s)/newsletters(s):		___5__
> 			(Specify)
> 
> 
> 
> 2.  Telnet Use:  How often do you connect to remote databases?
> 
> 	   (Insert appropriate number beside items below.)
> 
> 	1=Not at all			4=About 2-3 times a month
> 	2=A few times			5=Once a week
> 	3=About once a month		6=More than once a week
> 	
> 		Games/Simulations:		__1___
> 		Library Catalogs:		__3___
> 	.	Specialized Databases:		__1___
> 		
> 
> 2a.  How frequently do you connect these Internet sources:
> 
> 	   (Insert appropriate number beside items below.)
> 
> 	1=Not at all			4=About 2-3 times a month
> 	2=A few times			5=Once a week
> 	3=About once a month		6=More than once a week
> 			
> 		American Mathematical Society BBS		_1____
> 		American Psychological Assn.			_1____
> 		CARL						_1____
> 		CITADEL						_1____
> 		Cleveland FreeNet				_1____
> 		Dartmouth Dante					_1____
> 		Dialog						_1____
> 		Dow-Jones News Retrieval			_1____
> 		Dranet						_1____
> 		EDIN						_1____
> 		EPA						_1____
> 		ERIC						_1____
> 		FEDIX/MOLIS					_1____
> 		GenBank						_1____
> 		Geographic Name Server				_1____
> 		International Centre for Distance Learning	_1____
> 		ISAAC						_1____
> 		Lexis						_1____
> 		Market/Business Report				_1____
> 		National Education BBS				_1____
> 		Netfind						_1____
> 		Nexis						_1____
> 		Oceanic Information Center			_1____
> 		OCLC						_1____
> 		PENpages					_1____
> 		RLIN						_1____
> 		SpaceLink					_1____
> 		STIS						_1____
> 		TC Forum					_1____
> 		Weather Underground				_1____
> 		Webster Dictionary				_1____
> 	
> 		Other  (Please specify):
> 
> 
> 3.  FTP Use:  How often do you download files from FTP archive sites?
> 
> 	   (Insert appropriate number beside each item)
> 
> 	1=Not at all			4=About 2-3 times a month
> 	2=A few times			5=Once a week
> 	3=About once a month		6=More than once a week
> 	
> 		Computers and Academic Freedom			__6___
> 		EASI						__1___
> 		History  					__1___
> 		LIBSOFT						__1___
> 		Lyric and Discography				__1___
> 		NASA 						__1___
> 		Online Libraries Directory			__1___
> 		Science Education				__1___
> 		SIMTEL20					__5___
> 		SUMEX-AIM					__1___
> 		U.S. Supreme Court Decisions			__1___
> 		Washington Uni. Public Domain Archives		__1___
> 			
> 		Other (Please Specify):
> 
> 
> 4.	Several navigational aids have been developed for the Internet.
> 	How often do you use these network guides?
> 
> 	   (Insert appropriate number beside items below.)
> 
> 	1=Not at all			4=About 2-3 times a month
> 	2=A few times			5=Once a week
> 	3=About once a month		6=More than once a week
> 	
> 		Archie						___5__
> 		Campus-wide Information Systems			___5__		
> 		Gopher						___5__
> 		WAIS (Wide-area information servers)		___1__
> 		WWW (WorldWideWeb)				___1__
> 		Veronica					___1__
> 		HYTELNET					___1__
> 		Other (Please specify):
> 
> 
> Personal experiences can be the most helpful to other users.  Please comment on 
> the following:
> 
> 5.  	The importance of the Internet to your work?
> 
>      Very important because technical people with similar interest can be
       reached very rapidly and cheaply.
> 
> 6.  	Advantages the Internet offers over other resources?
>      
>       It is cheap and fast and offers wide bandwidth.
> 
> 7.  	Barriers to using the Internet?
> 
>      None yet...
> 
> 8.  	Your most memorable use of the Internet?
> 
>       I was able to fix a dead workstation in about 15 minutes using email
        with to an "expert".  After about 3 times back and forth we got it 
        up and running.  (this was at 1am on a Monday!) 
> 
> 9  These questions will help us interpret the results of this study:
> 
> 	Title:	__Systems Analyst________________________________
> 	Affiliation:  _University of Washington__________________	
> 	Discipline:  _Mechanical Engineering_____________________	
> 	Research Interest(s):____________________________________
> 	_________________________________________________________
> 
> Please return the completed survey to: WMILHEIM@PSUGV.EDU
> by September 3, 1993.
> 
> If you would like a summary of the survey results, please place your
> e-mail address here:  _chuckb@u.washington.edu____________________.
> 
> 
>             :) Thank you for taking the time to participate :)
> 
 
From Denys Wed Aug 25 19:27:05 -0400 1993
Date: Wed, 25 Aug 93 19:27:05 -0400
From: Denys Duchier <dduchier@csi.UOttawa.CA>
Reply-To: LitProg@SHSU.edu, dduchier@CSI.UOTTAWA.CA
To: litprog@shsu.edu
Subject: expandable \countme
 
Norman Ramsey asked how to write an expandable TeX macro for counting
the elements of a sequence; i.e. such that \countme{\\{a1}...\\{an}}
expands into n.  Here is a solution.  It is rather more complicated
than seems necessary because care is required to avoid running out of
parameter stack too soon.
 
--Denys
 
% --------------------------------------------------------------------
% Denys Duchier, University of Ottawa, Aug 1993
% --------------------------------------------------------------------
 
\def\defmarker#1{%
  \def#1{\errmessage{Attempted to expand marker \noexpand#1}}}
 
\defmarker\Last
 
\def\fst#1#2{#1}
\def\snd#1#2{#2}
 
% --------------------------------------------------------------------
% \IFX{x}{y}{true}{false}
%	==> true	\ifx xy
%	==> false	\else
% \expandafter forces the expansion mechanism to consider, and
% therefore remove the remainder of the conditional, e.g. the
% terminal \fi.
% --------------------------------------------------------------------
 
\def\IFX#1#2{\ifx#1#2\expandafter\fst\else\expandafter\snd\fi}
 
% --------------------------------------------------------------------
% \reverse{t1 ... tn}\continuation ==> \continuation{tn ... t1}
% --------------------------------------------------------------------
\def\reverse#1{\reverseX{}#1\Last}
 
\def\reverseX#1#2{%
  \IFX\Last{#2}{\continue{#1}}{\reverseX{#2#1}}}
 
\def\continue#1#2{#2{#1}}
 
% --------------------------------------------------------------------
% \increment{n}\continuation ==> \continuation{n+1}
% --------------------------------------------------------------------
\def\increment#1{\reverse{#1}\incrementC}
 
% Hack alert! \Ten is used both as a delimiter and as an extra digit.
\chardef\Ten=10
 
\def\incrementC#1{\incrementX{}#1\Ten}
 
% --------------------------------------------------------------------
% \IFCASE{n}{n=0}...{n=9}{n=\Ten} is a 11 way branching test,
% according to the value of n as an integer.
% \expandafter has same purpose as in \IFX.
% --------------------------------------------------------------------
 
\def\IFCASE#1{%
  \ifcase#1
    \expandafter\casezero \or
    \expandafter\caseone  \or
    \expandafter\casetwo  \or
    \expandafter\casethree\or
    \expandafter\casefour \or
    \expandafter\casefive \or
    \expandafter\casesix  \or
    \expandafter\caseseven\or
    \expandafter\caseeight\or
    \expandafter\casenine \or
    \expandafter\caseten  \else
    \errmessage{Fell through IFCASE}\fi}
 
\def\casefst#1#2#3{#1}
 
\def\casezero #1#2#3#4#5#6#7#8#9{\casefst{#1}}
\def\caseone  #1#2#3#4#5#6#7#8#9{\casefst{#2}}
\def\casetwo  #1#2#3#4#5#6#7#8#9{\casefst{#3}}
\def\casethree#1#2#3#4#5#6#7#8#9{\casefst{#4}}
\def\casefour #1#2#3#4#5#6#7#8#9{\casefst{#5}}
\def\casefive #1#2#3#4#5#6#7#8#9{\casefst{#6}}
\def\casesix  #1#2#3#4#5#6#7#8#9{\casefst{#7}}
\def\caseseven#1#2#3#4#5#6#7#8#9{\casefst{#8}}
\def\caseeight#1#2#3#4#5#6#7#8#9{\casefst{#9}}
\def\casenine #1#2#3#4#5#6#7#8#9{\fst}
\def\caseten  #1#2#3#4#5#6#7#8#9{\snd}
 
% \incrementX is propagating the carry in the reversed list of digits,
% i.e. from lowest to highest.
% #1 is the accumulated list of lower digits
% #2 is the next higher digit
 
\def\incrementX#1#2{%
  \IFCASE #2
    {\incrementXX{#11}}% 0
    {\incrementXX{#12}}% 1
    {\incrementXX{#13}}% 2
    {\incrementXX{#14}}% 3
    {\incrementXX{#15}}% 4
    {\incrementXX{#16}}% 5
    {\incrementXX{#17}}% 6
    {\incrementXX{#18}}% 7
    {\incrementXX{#19}}% 8
    {\incrementX{#10}}%  9
    {\reverse{#11}}}%   10
 
\def\incrementXX#1#2\Ten{\reverse{#1#2}}
 
% --------------------------------------------------------------------
% \countme{\\{a1}...\\{an}} ==> n
% --------------------------------------------------------------------
 
\def\countme#1{\countmeX 0#1\Last\Last}
 
\def\countmeX#1#2#3{%
  \IFX\Last{#2}{#1}{\increment{#1}\countmeX}}
 
From kcousins@rp.csiro.au Thu Aug 26 15:53:02 +1000 1993
Date: Thu, 26 Aug 93 15:53:02 +1000
From: kcousins@rp.csiro.au
Reply-To: LitProg@SHSU.edu, kcousins@RP.CSIRO.AU
To: LITPROG@shsu.edu, WMILHEIM@psugv.psu.edu (William Milheim)
Subject: Internet Survey
 
                              INTERNET SURVEY
 
                     Adele F. Bane <AFB2@PSUVM.PSU.EDU>
                 William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
              The Pennsylvania State University at Great Valley
_______________________________________________________________________________
_
This electronic mail survey is being conducted to identify the functions of the 
Internet that are most used by the academic community.  You have been chosen as 
a member of a selected academic list service (LISTSERV) to participate.  
Results of this survey will form the basis of a journal article to be published 
later this year.  Please answer all survey questions.  
_______________________________________________________________________________
_ 
 
INTERNET INSIGHTS:  A Survey
 
We will begin by asking a few questions about yourself:
 
	How many years of computer experience do you have?	_15____  
	How long have you used e-mail of any type?		_8____
	How long have you been an Internet user?		_2____	
 
Three primary functions of the Internet have been identified.  They are 
electronic mail, Telnet or remote log-in, and FTP or file transfer.  An 
estimated 15 million users take advantage of these functions daily.  
This survey explores the use of each of these services.
 
1.  E-Mail Use:  How often do you make these connections?
 
	   (Insert the appropriate number beside items below:)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Private Email:					_6____
 
		Discussion group(s):				_6____
			(Specify)
				Literate Programming, 'LitProg'
				Mathematica 'MathGroup'
 
		Usenet (or Netnews)				_6____
 
		Electronic journal(s)/newsletters(s):		_2____
			(Specify)
				DECnews
 
2.  Telnet Use:  How often do you connect to remote databases?
 
	   (Insert appropriate number beside items below.)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Games/Simulations:		_3____
		Library Catalogs:		_4____
	.	Specialized Databases:		_2____
 
2a.  How frequently do you connect these Internet sources:
 
	   (Insert appropriate number beside items below.)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		American Mathematical Society BBS		_1____
		American Psychological Assn.			_1____
		CARL						_1____
		CITADEL						_1____
		Cleveland FreeNet				_1____
		Dartmouth Dante					_1____
		Dialog						_1____
		Dow-Jones News Retrieval			_1____
		Dranet						_1____
		EDIN						_1____
		EPA						_1____
		ERIC						_1____
		FEDIX/MOLIS					_1____
		GenBank						_1____
		Geographic Name Server				_1____
		International Centre for Distance Learning	_1____
		ISAAC						_1____
		Lexis						_1____
		Market/Business Report				_1____
		National Education BBS				_1____
		Netfind						_2____
		Nexis						_1____
		Oceanic Information Center			_1____
		OCLC						_1____
		PENpages					_1____
		RLIN						_1____
		SpaceLink					_1____
		STIS						_1____
		TC Forum					_1____
		Weather Underground				_1____
		Webster Dictionary				_1____
 
		Other  (Please specify):
 
3.  FTP Use:  How often do you download files from FTP archive sites?
 
	   (Insert appropriate number beside each item)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Computers and Academic Freedom			_1____
		EASI						_1____
		History  					_1____
		LIBSOFT						_1____
		Lyric and Discography				_1____
		NASA 						_3____
		Online Libraries Directory			_1____
		Science Education				_1____
		SIMTEL20					_2____
		SUMEX-AIM					_1____
		U.S. Supreme Court Decisions			_1____
		Washington Uni. Public Domain Archives		_2____
 
		Other (Please Specify):
 
4.	Several navigational aids have been developed for the Internet.
	How often do you use these network guides?
 
	   (Insert appropriate number beside items below.)
 
	1=Not at all			4=About 2-3 times a month
	2=A few times			5=Once a week
	3=About once a month		6=More than once a week
 
		Archie						_4____
		Campus-wide Information Systems			_2____		
		Gopher						_2____
		WAIS (Wide-area information servers)		_2____
		WWW (WorldWideWeb)				_6____
		Veronica					_1____
		HYTELNET					_2____
		Other (Please specify):
 
Personal experiences can be the most helpful to other users.  Please comment on 
the following:
 
5.  	The importance of the Internet to your work?
 
	Very important, both as a communication tool and as an information
	source.
 
6.  	Advantages the Internet offers over other resources?
 
	(Relative) ease of use, fast turnaround, low cost, high bandwidth
 
7.  	Barriers to using the Internet?
 
	I feel that the access to Internet resources has been hampered by
	a lack of comprehensive tools. It is one thing to expect hardened
	programmers and scientists to fiddle with the intricacies of some
	utilities (ftp, X11 protocols, network addressing stuff, etc.)...
	quite another to hand these things to the sorts of people who
	would baulk at a UNIX command line (doctors, artists, perhaps
	historians, etc.).
 
8.  	Your most memorable use of the Internet?
 
9  These questions will help us interpret the results of this study:
 
	Title:	_Experimental Scientist_________________
	Affiliation:  __________________________________	
	Discipline:  _Electrical Engineering____________	
	Research Interest(s):_High speed wireless local area_____ 		
	networking_______________________________________________
 
Please return the completed survey to: WMILHEIM@PSUGV.EDU
by September 3, 1993.
 
If you would like a summary of the survey results, please place your
e-mail address here:  _kcousins@rp.csiro.au____________________.
 
            :) Thank you for taking the time to participate :)
 
From kcousins@rp.csiro.au Thu Aug 26 15:54:41 +1000 1993
Date: Thu, 26 Aug 93 15:54:41 +1000
From: kcousins@rp.csiro.au
Reply-To: LitProg@SHSU.edu, kcousins@RP.CSIRO.AU
To: LitProg@shsu.edu, neeri@iis.ee.ethz.ch
Subject: Re: Vote on newsgroup creation
 
      I vote YES on comp.programming.literate
 
From Dave Thu Aug 26 14:06:29 GMT 1993
Date: Thu, 26 Aug 93 14:06:29 GMT
From: Dave Love <d.love@daresbury.ac.uk>
Reply-To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
To: LitProg@SHSU.edu
Subject: Re: publishing programs
 
There is at least one other book which is executable like the TeX and
METAFONT programs: 
%A S.L. Peyton\0Jones
%A D.R. Lester
%T Implementing Functional Languages: A Tutorial
%D 1992
%I Prentice-Hall
%C Hemel Hempstead
%O ISBN 0-13-721952-0.
which uses TeX and Miranda.  I've also seen Haskell articles which are
executable, but I don't know if they have been published in journals.
 
[Haskell-like (lazy functional) languages usually support an `inverse
comment' convention which is enshrined in the language report.
Program source is indicated by leading `> ' and everything else is
commentary.  Your (literate) program can then be fed either to the
Haskell compiler or to, say, LaTeX asis.]
 
The journal TUGboat has lots of literate programming, albeit only in
TeX.
 
From coates@spectro.jussieu.fr Thu Aug 26 17:44:59 +0200 1993
Date: Thu, 26 Aug 93 17:44:59 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu
Subject: Re: Internet Survey
 
Dear LitProggers,
 
>                               INTERNET SURVEY
> 
>                      Adele F. Bane <AFB2@PSUVM.PSU.EDU>
>                  William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
>               The Pennsylvania State University at Great Valley
> _______________________________________________________________________________
> _
> This electronic mail survey is being conducted to identify the functions of the 
> Internet that are most used by the academic community.  You have been chosen as 
> a member of a selected academic list service (LISTSERV) to participate.  
> Results of this survey will form the basis of a journal article to be published 
> later this year.  Please answer all survey questions.  
> ______________________________________________________________________________
 
Messrs Bane and Milheim made the mistake of putting the litprog mailing address
in the `Reply-To:' field of their original posting.  So if you just reply, it
will come to litprog too.  I don't to see what you wrote, so please make sure
that you only reply to WMILHEIM@PSUGV.PSU.EDU if you choose to answer.
	Otherwise, have fun!
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux 
 ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of
 these two sets is probably empty."
________________________________________________________________________________
 
From ae1181t@stnfor.ae.ge.com Thu Aug 26 11:56:48 -0400 1993
Date: Thu, 26 Aug 1993 11:56:48 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, d.love@daresbury.ac.uk.ae.ge.com.ae.ge.com
Subject: Re: publishing programs
 
I would not consider the `inverse comment method' literate programming.
For one thing you do not have the freedom to write the code-segments
in any order you like. If the compiler needs them in a certain order,
then you are stuck! However this argument may be mute for functional
languages.
Osman
 
From Dave Thu Aug 26 18:19:40 GMT 1993
Date: Thu, 26 Aug 93 18:19:40 GMT
From: Dave Love <d.love@daresbury.ac.uk>
Reply-To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
To: LitProg@SHSU.edu
Subject: Re: publishing programs
 
>>>>> On Thu, 26 Aug 1993 11:56:48 -0400, ae1181t@com.ge.ae.stnfor (Osman F Buyukisik) said:
 
 Osman> I would not consider the `inverse comment method' literate programming.
 Osman> For one thing you do not have the freedom to write the code-segments
 Osman> in any order you like. If the compiler needs them in a certain order,
 Osman> then you are stuck! However this argument may be mute for functional
 Osman> languages.
 
Indeed, in most instances (moot).  The same with the LaTeX `doc' system.
 
You might however, have, say, some long boring lexical code and want
to relegate part of it to an appendix, as I've seen in one instance.
The compiler does need the cases kept together.  You could do this
with a LaTeX hack to float bits around or elide some inside a comment
envirnoment, as I've had occasion to.
 
From preston@cs.rice.edu Thu Aug 26 14:22:54 CDT 1993
Date: Thu, 26 Aug 93 14:22:54 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, d.love@daresbury.ac.uk
Subject: Re: publishing programs
 
 Osman> I would not consider the `inverse comment method' literate programming.
 Osman> For one thing you do not have the freedom to write the code-segments
 Osman> in any order you like.
 
And there's no automatically-generated navigational support
(i.e., table of contents, indices, cross references).
In fact, is it any better (or different) than ordinary commented source?
 
Preston Briggs
 
From Paul Thu Aug 26 13:59:03 PDT 1993
Date: Thu, 26 Aug 93 13:59:03 PDT
From: Paul Palmer <palmerp@MATH.ORST.EDU>
Reply-To: LitProg@SHSU.edu, palmerp@MATH.ORST.EDU
To: LitProg@SHSU.edu, kcousins@RP.CSIRO.AU
Subject: Re: Vote on newsgroup creation
 
>>       I vote YES on comp.programming.literate
 
you sent your vote to the wrong address
 
From jham1@cs.aukuni.ac.nz Thu Aug 26 13:59:03 PDT 1993
Date: Thu, 26 Aug 93 13:59:03 PDT
From: jham1@cs.aukuni.ac.nz
Reply-To: LitProg@SHSU.edu, jham1@CS.AUKUNI.AC.NZ
To: LitProg@SHSU.edu
Subject: Re: publishing programs
 
 Osman> I would not consider the `inverse comment method' literate programming.
 Osman> For one thing you do not have the freedom to write the code-segments
 Osman> in any order you like.
 
 Preston> And there's no automatically-generated navigational support
 Preston> (i.e., table of contents, indices, cross references).
 Preston> In fact, is it any better (or different) than ordinary commented source?
 
I have used the inverse comment method (aka ``Bird tracks'') for many
(smallish) functional programs, and find it *much* better than ordinary
commented source, since I can feed the file through LaTeX (or
_whatever_) without change---tangle and weave are no-ops!
 
Having a conventionalised---albeit no-frills---means of writing
``executable'' reports should not be trivialised.  This *is* literate
programming, make no mistake.  Tools that do code re-ordering are mainly
patching up deficiencies in languages like `C; this is not a necessary
feature of LP.  Many visual programming tools provide for (the effect
of) code re-ordering, but I would not consider these literate
programming tools.
 
Having said that, I must admit to using nuweb for larger programs.  The
gains are not enormous.
 
-- John Hamer                                Email: J_Hamer@cs.auckland.ac.nz
-- Department of Computer Science            Phone: +64 9 3737 599 x8758
-- University of Auckland                    Fax:   +64 9 3737 453
-- Private Bag 92019, Auckland, New Zealand.
 
From narsu@agni.hks.com Fri Aug 27 10:16:24 -0400 1993
Date: Fri, 27 Aug 1993 10:16:24 -0400
From: narsu@agni.hks.com (Uttam M. Narsu)
Reply-To: LitProg@SHSU.edu, narsu@AGNI.HKS.COM
To: litprog@shsu.edu
Subject: Question from a novice
 
Hi,
 
I taken a look at some examples of literate programming (Knuth's
TeX book, and the K&R samples on 192.92.115.8) and I was wondering
if one has to learn TeX to be able to do literate programming. It
seems that many of the macros one wants to use can be hidden through
the selection of an appropriate view in an extensible editor.
 
Has anyone implemented a multi-window literate programming editor?
(I just don't see our programmers being very happy about learning
TeX in order to do literate programming.)
 
Cheers
Uttam
 
-- 
 
Uttam M. Narsu                          E-mail: narsu@hks.com
 
Hibbitt, Karlsson & Sorensen, Inc.      Tel:    (401) 727-4200 x 4442
1080 Main Street, Pawtucket RI 02860    Fax:    (401) 727-4208
 
From bart@cs.tamu.edu Fri Aug 27 10:43:59 CDT 1993
Date: Fri, 27 Aug 93 10:43:59 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: litprog@shsu.edu
Subject: You need very little TeX
 
I have looked at several dozen WEBs from a wide array of programmers.
The sad truth is that nearly everybody that use WEBs will put in
almost no TeX commands on their own.   I say that is sad because just
a few can be a significant help.
 
A user can buy Art Samuels' ``First Grade TeX'' from the TeX users
group for less than $10.  It is 40 pages long and has more TeX than
is used in 99% of the WEBs written by 95% of the users.
 
Donald Knuth, Silvio Levy, and John Krommes are not in that majority.
Some of the WEBs I have written use more TeX, but most don't.  The
most common exception to this is that I often include lists (item
type commands) in documentation portions of the code.  In these I
will nest these [bgroup -- egroup]s and change the parindent and
parskip to format them in a manner that is more suitable to my tastes.
 
Our web-mode for emacs has almost no TeX support because it is not
really needed.  The AUC-TeX from Denmark has a great amount of TeX
support and we might incorporate a little of it in the future.
 
I was visiting with Ross Williams (the author of Funnel WEB) last
month.  I pointed out that I thought the lack of HLL sensitivity and
therefore the lack of index features was a great lacking of his
contribution.  He readily acknowledged that Funnel WEB had short-
comings but made an eloquent statement that I will try to do justice
to.  It was something like this:
    ``The great contribution of the WEB style of programming
      is that you can organize the code in the same way you
      think of it.  I outline the code in a logical way and
      supplement that with documentation as I need.  When I want
      to finish the details of a part, it is easy with the guidance
      I have provided and I simply do it.  I rarely make a printed
      version of the code.''
I offer Ross my apologies for any inaccuracies.
 
I strongly believe that `the use of TeX is an excuse (and not a
reason) to avoid literate programming.'  A one-day training course
in TeX is far more than is needed and gives more formatting
capabilities than is even possible with most WYSIWYG systems.
TeX could be made invisible to most literate programming users.
 
Bart Childs
 
PS: ftp.cs.tamu.edu    is down right now.  Hopefully it is back
                       today or early next week.
 
From dak@POOL.Informatik.RWTH-Aachen.DE Fri Aug 27 17:45:39 +0200 1993
Date: Fri, 27 Aug 93 17:45:39 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, narsu@AGNI.HKS.COM
Subject: Re: Question from a novice
 
   From: narsu@agni.hks.com (Uttam M. Narsu)
 
   Hi,
 
   I taken a look at some examples of literate programming (Knuth's
   TeX book, and the K&R samples on 192.92.115.8) and I was wondering
   if one has to learn TeX to be able to do literate programming. It
   seems that many of the macros one wants to use can be hidden through
   the selection of an appropriate view in an extensible editor.
 
   Has anyone implemented a multi-window literate programming editor?
   (I just don't see our programmers being very happy about learning
   TeX in order to do literate programming.)
 
W E L L, strictly speaking the use of CWEB/WEB using the appropriate
tangle/weave programs is straightforward, not needing any knowledge
of TeX.
 
The macros and constructs are particular to WEB, but the front end
does not really require much if any knowledge of TeX (although
you may not use characters like $&^#{} etc.). However, at least
a knowledge of TeX formulas is to be heavily recommended, because
one of the WEB advantages is that it is possible to include
mathematical basics of algorithms in a readable form (And I do not
consider forms like sin((2*PI*N/180.0)+phi)*xyz)*cos((2*PI*N/180.0)+theta)
a particularly readable form).
 
And of course, the inclusion of tables is a real pain in the ...
If the current version of CWEB runs with LaTeX, than this at least
is simplified.
 
I agree, however, that the better you make the documentation part, the
more of TeX resp LaTeX resp. whatever formatter is used, shines through.
 
The current WEBs are fixated mainly on TeX because
1) Knuth sort of started the whole biz
2) They are ASCII input, good typeset output
3) freely available, so that the fixation does not seem as severe
   restrictive as orientation on a certain commercial product would
   seem.
 
It would be easily possible to adapt those WEBs to other typesetting
software, however, such advances would make the approach less portable
probably. There are degrees, however.
 
For instance, I think that a Wordperfect WEB would suffer from serious
portability problems, although not necessarily from acceptance problems
(although, I admit, I am TeX-spoiled and do not want to learn some
stupid WYSIWYG system with slightly better than typewriter appearance.
This is a topic for other fruitless "I have better SW than you"
discussions, however).
 
Basically, however, one could design sort of a "generic" WEB, which would,
through the use of text processing definition files, produce output for
dedicated word processors. I am afraid, however, that pagination and
indexing would have to be included into the WEBs because much of the
work here in current WEBs is done by TeX (and why not?).
 
With a bit of discipline, sources could be kept somewhat formatter-
independent, although leaving out formulas etc would seem too harsh
a restriction for me. But better a literate program without nice
formulas than none at all!
 
So what's the point? Maybe you should try selling your programmer's
TeX through the back door, show them that a WEB need not contain much
TeX knowledge. Have at least one TeX guy ready to help doing formulas
etc. Support the development of formatter-independent WEBs.
 
BTW, LaTeX is not that hard to start with, and I think that CWEB 3.xx
will support LaTeX as well (although I am not that sure).
 
I AM pretty sure, however, that it would be preposterous to demand
that all of your programmers should learn mastering plain TeX. This
would be madness. But LaTeX should be on the tolerable side.
 
It is unfortunate that there are not that much WEB systems around
which support other word processors. Thus you are forced promoting
LP AND TeX at the same time, a bit on the heavy side.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From dak@POOL.Informatik.RWTH-Aachen.DE Fri Aug 27 17:45:39 +0200 1993
Date: Fri, 27 Aug 93 17:45:39 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.edu, narsu@AGNI.HKS.COM
Subject: Re: Question from a novice
 
   From: narsu@agni.hks.com (Uttam M. Narsu)
 
   Hi,
 
   I taken a look at some examples of literate programming (Knuth's
   TeX book, and the K&R samples on 192.92.115.8) and I was wondering
   if one has to learn TeX to be able to do literate programming. It
   seems that many of the macros one wants to use can be hidden through
   the selection of an appropriate view in an extensible editor.
 
   Has anyone implemented a multi-window literate programming editor?
   (I just don't see our programmers being very happy about learning
   TeX in order to do literate programming.)
 
W E L L, strictly speaking the use of CWEB/WEB using the appropriate
tangle/weave programs is straightforward, not needing any knowledge
of TeX.
 
The macros and constructs are particular to WEB, but the front end
does not really require much if any knowledge of TeX (although
you may not use characters like $&^#{} etc.). However, at least
a knowledge of TeX formulas is to be heavily recommended, because
one of the WEB advantages is that it is possible to include
mathematical basics of algorithms in a readable form (And I do not
consider forms like sin((2*PI*N/180.0)+phi)*xyz)*cos((2*PI*N/180.0)+theta)
a particularly readable form).
 
And of course, the inclusion of tables is a real pain in the ...
If the current version of CWEB runs with LaTeX, than this at least
is simplified.
 
I agree, however, that the better you make the documentation part, the
more of TeX resp LaTeX resp. whatever formatter is used, shines through.
 
The current WEBs are fixated mainly on TeX because
1) Knuth sort of started the whole biz
2) They are ASCII input, good typeset output
3) freely available, so that the fixation does not seem as severe
   restrictive as orientation on a certain commercial product would
   seem.
 
It would be easily possible to adapt those WEBs to other typesetting
software, however, such advances would make the approach less portable
probably. There are degrees, however.
 
For instance, I think that a Wordperfect WEB would suffer from serious
portability problems, although not necessarily from acceptance problems
(although, I admit, I am TeX-spoiled and do not want to learn some
stupid WYSIWYG system with slightly better than typewriter appearance.
This is a topic for other fruitless "I have better SW than you"
discussions, however).
 
Basically, however, one could design sort of a "generic" WEB, which would,
through the use of text processing definition files, produce output for
dedicated word processors. I am afraid, however, that pagination and
indexing would have to be included into the WEBs because much of the
work here in current WEBs is done by TeX (and why not?).
 
With a bit of discipline, sources could be kept somewhat formatter-
independent, although leaving out formulas etc would seem too harsh
a restriction for me. But better a literate program without nice
formulas than none at all!
 
So what's the point? Maybe you should try selling your programmer's
TeX through the back door, show them that a WEB need not contain much
TeX knowledge. Have at least one TeX guy ready to help doing formulas
etc. Support the development of formatter-independent WEBs.
 
BTW, LaTeX is not that hard to start with, and I think that CWEB 3.xx
will support LaTeX as well (although I am not that sure).
 
I AM pretty sure, however, that it would be preposterous to demand
that all of your programmers should learn mastering plain TeX. This
would be madness. But LaTeX should be on the tolerable side.
 
It is unfortunate that there are not that much WEB systems around
which support other word processors. Thus you are forced promoting
LP AND TeX at the same time, a bit on the heavy side.
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From Dave Fri Aug 27 15:47:10 GMT 1993
Date: Fri, 27 Aug 93 15:47:10 GMT
From: Dave Love <d.love@daresbury.ac.uk>
Reply-To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
To: LitProg@SHSU.edu
Subject: Re: publishing programs
 
>>>>> On Thu, 26 Aug 93 14:22:54 CDT, preston@edu.rice.cs (Preston Briggs) said:
 
 Preston> And there's no automatically-generated navigational support
 Preston> (i.e., table of contents, 
 
LaTeX, for instance, has \tableofcontents, \section, \index etc. and
I've used them to generate hypertext documents for navigation around
literate programs, albeit not for serious use.
 
 Preston> indices, cross references).
 
You could get variable indices if you cared to generate them with an
extra tool and you can use \index; you don't get the index from the
current noweb either.
 
 Preston> In fact, is it any better (or different) than ordinary
 Preston> commented source?
 
IMHO, yes, although based on experience with TeX and Lisp/Scheme
rather than Haskell.  (You can hack your Lisp reader to obey
conventions about the input format.)  For instance, the difference
between the (extensive) comments in the source of LaTeX and the
add-ons documented with the doc option is considerable, I think.  The
inverse commenting reflects the emphasis on the commentary rather than
the code.  It marks what's code and what's commentary if you want to
be cleverer with extra tools, and there's no overhead if you don't.  I
can't imagine a book of normal commented code c.f. the Peyton
Jones/Lester one.  I think what you get from the typography is
considerable, especially if you've got mathematics to present in the
commentary.
 
From preston@cs.rice.edu Fri Aug 27 10:48:48 CDT 1993
Date: Fri, 27 Aug 93 10:48:48 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: Question from a novice
 
>I was wondering
>if one has to learn TeX to be able to do literate programming. It
>seems that many of the macros one wants to use can be hidden through
>the selection of an appropriate view in an extensible editor.
 
>Has anyone implemented a multi-window literate programming editor?
>(I just don't see our programmers being very happy about learning
>TeX in order to do literate programming.)
 
One of the central features of literate programming is high-quality
output.  Most systems use Tex (or Latex) though there are some now
that use Word and older approachs using troff.
 
I think the use of macros (scraps, modules, ...) is orthogonal to the
use of Tex.  A fancy editor is nice, but not essential.
 
About learning Tex, ...
maybe there's 2 kinds of programmers: 'philes and 'phobes.
The 'phobes aren't going to like learning anything new,
but the 'philes will enjoy it.  Lots of us really _like_ being able,
finally, after all these years, to make our programs look nice!
I'd try and hire more of the enthusiastic sort and weed out the others.
 
Preston Briggs
 
From Zdenek Fri Aug 27 09:59:15 MDT 1993
Date: Fri, 27 Aug 93 09:59:15 MDT
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, coates@SPECTRO.JUSSIEU.FR
Subject: Re: Internet Survey
 
On Thu, 26 Aug 93 17:44:59 +0200 <coates@spectro.jussieu.fr> said:
>Dear LitProggers,
>
>>                               INTERNET SURVEY
>>
>>                      Adele F. Bane <AFB2@PSUVM.PSU.EDU>
>>                  William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
>>               The Pennsylvania State University at Great Valley
>>
>______________________________________________________________________________
>_
>> _
>> This electronic mail survey is being conducted to identify the functions of
>th
>e
>> Internet that are most used by the academic community.  You have been chosen
>a
>s
>> a member of a selected academic list service (LISTSERV) to participate.
>> Results of this survey will form the basis of a journal article to be
>publishe
>d
>> later this year.  Please answer all survey questions.
>>
>______________________________________________________________________________
>
>Messrs Bane and Milheim made the mistake of putting the litprog mailing address
>in the `Reply-To:' field of their original posting.  So if you just reply, it
>will come to litprog too.  I don't to see what you wrote, so please make sure
>that you only reply to WMILHEIM@PSUGV.PSU.EDU if you choose to answer.
 
This is not the mistake of the authors of the survey. It is just the way
how LitProg is configured -- the same happens with all postings (unlike
e.g. Info-TeX).
 
>        Otherwise, have fun!
>                                                Cheers,
>                                                                Tony.
>_______________________________________________________________________________
>_
>A.B.Coates (Tony)
>Laboratoire de Spectroscopie Hertzienne de l'ENS
>Universite Pierre et Marie Curie
>Case 74, 4 place Jussieu                Email:     coates@spectro.jussieu.fr
>F-75252 Paris CEDEX 05                  Telephone: +33 1 44 27 44 09
>France                                  Fax:       +33 1 44 27 38 45
>
>"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux
> ensembles est probablement vide."
>"I have my opinions.  The university has its opinions.  The intersection of
> these two sets is probably empty."
>_______________________________________________________________________________
>_
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From Lee Fri Aug 27 12:04:31 EDT 1993
Date: Fri, 27 Aug 93 12:04:31 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, jham1@cs.aukuni.ac.nz
Subject: Re: publishing programs
 
John Hamer writes:
 
> ....  Tools that do code re-ordering are mainly
> patching up deficiencies in languages like `C; this is not a necessary
> feature of LP.  Many visual programming tools provide for (the effect
> of) code re-ordering, but I would not consider these literate
> programming tools.
 
This is probably a bit of a flame, but I think I ought to say it
anyway.  IMHO the thing that makes LP ``work'' is the ability to have
a program [in Djikstra's words] ``written down as I can understand it,
I want it written down as I would like to explain it to someone.''
Code re-ordering is what allows this.  
 
John's point about visual programming tools is well taken, though.  In
many ways the LP and VP philosophies are diametrically opposed.
 
I would suggest that code re-ordering is a necessary, but not
sufficient feature of LP.
 
		-- Lee
 
From Lee Fri Aug 27 12:18:37 EDT 1993
Date: Fri, 27 Aug 93 12:18:37 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, dak@pool.informatik.rwth-aachen.de
Subject: Re: Question from a novice
 
In response to Uttam Narsu's question, David Kastrup says:
 
> For instance, I think that a Wordperfect WEB would suffer from serious
> portability problems, although not necessarily from acceptance problems
> (although, I admit, I am TeX-spoiled and do not want to learn some
> stupid WYSIWYG system with slightly better than typewriter appearance.
> This is a topic for other fruitless "I have better SW than you"
> discussions, however).
 
I don't know about Wordperfect, but the WinWordWEB system certainly
suffers from these deficiencies.  Although the output is much better
than ``typewriter appearance,''  I find it much easier to use noweb
with LaTeX, for the same results.
 
		-- Lee
 
From narsu@agni.hks.com Fri Aug 27 16:35:05 -0400 1993
Date: Fri, 27 Aug 1993 16:35:05 -0400
From: narsu@agni.hks.com (Uttam M. Narsu)
Reply-To: LitProg@SHSU.edu, narsu@AGNI.HKS.COM
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Question from a novice
 
I guess I was less than clear in my original message; I'm not
terribly interested in a WYSIWYG system, nor am I averse to
learning TeX (or the WEB constructs) (after all it's just another language),
but I am interested in leveraging knowledge that I or my colleagues
already possess.
 
We currently use EMACS for most of our editing or source (much of the
maintenance of our C++ coding standards is handled through emacs macros).
 
So I suppose an emacs package (which I understand is available with FWEB)
would probably do just fine.
 
As a finite element analysis shop, just the ability to document/typeset
equations with the code would be tremendously useful.
 
uttam
 
-- 
 
Uttam M. Narsu                          E-mail: narsu@hks.com
 
Hibbitt, Karlsson & Sorensen, Inc.      Tel:    (401) 727-4200 x 4442
1080 Main Street, Pawtucket RI 02860    Fax:    (401) 727-4208
 
From narsu@agni.hks.com Fri Aug 27 16:57:43 -0400 1993
Date: Fri, 27 Aug 1993 16:57:43 -0400
From: narsu@agni.hks.com (Uttam M. Narsu)
Reply-To: LitProg@SHSU.edu, narsu@AGNI.HKS.COM
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re: Question from a novice
 
On Aug 27, 10:48am, Preston Briggs wrote:
 
> About learning Tex, ...
> maybe there's 2 kinds of programmers: 'philes and 'phobes.
> The 'phobes aren't going to like learning anything new,
> but the 'philes will enjoy it.  Lots of us really _like_ being able,
> finally, after all these years, to make our programs look nice!
> I'd try and hire more of the enthusiastic sort and weed out the others.
 
And then there are those of us who love learning new things, but
honestly don't have the time. That is the reality of life in a commercial
concern with schedules and managers deciding whether we are phobes or
philes.
 
-- 
 
Uttam M. Narsu                          E-mail: narsu@hks.com
 
Hibbitt, Karlsson & Sorensen, Inc.      Tel:    (401) 727-4200 x 4442
1080 Main Street, Pawtucket RI 02860    Fax:    (401) 727-4208
 
From fulling@sarastro.math.tamu.edu Fri Aug 27 16:15:46 CDT 1993
Date: Fri, 27 Aug 93 16:15:46 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu, fulling@SARASTRO.MATH.TAMU.EDU
To: LitProg@shsu.edu, narsu@agni.hks.com
Subject: Re: Question from a novice
 
>As a finite element analysis shop, just the ability to
document/typeset
>equations with the code would be tremendously useful.
>
>uttam
 
To repeat what others have said (very well),
 
(1) This is precisely the place where TeX is most valuable.  (Accept no
substitutes!-)
 
(2) The basic TeX needed to set equations is easy to learn, and most of
the WEB users do not need to know more TeX, provided that there are a
few people around to help out in difficult situations and you are
prepared to live with occasional infelicities of spacing, etc.
 
					     Steve
 
From marcus@x4u.desy.de Fri Aug 27 23:17:38 +0200 1993
Date: Fri, 27 Aug 93 23:17:38 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, narsu@agni.hks.com
Subject: Re: Question from a novice
 
[[copied from the HyperText info on LitProg which I am maintaining--
 for more, see ftp.desy.de:/pub/www/projects/Announce/LitProg.txt --Marcus]]
 
Editing WEB files with the GNU Emacs editor
*******************************************
 
If you are developing your WEB, CWEB or FWEB programs
using the GNU Emacs editor, there is web-mode.el by Mark
Motl <motl@cs.tamu.edu>; the corresponding GNU Emacs 
mode can deal with WEB, CWEB and FWEB.  
 
It is capable of many things, including jumping to sections and
modules, inserting (and previewing) index entries, hiding and
exibiting the body of a .web file (showing the tree), inserting,
quoting, and consistently renaming modules etc.  It supports
change files and journal files.  It is especially useful when
dealing with large .web files not to have to deal with monolithic
files.  
 
Detailed information is contained in the User's Manual
(PostScript).  Here is a reference card (PostScript).  The
sources can be retrieved from here.  The latest version should
always be available via anonymous FTP from ftp.cs.tamu.edu,
or in Europe from ftp.th-darmstadt.de as web-mode.tar.Z 
[in directory /pub/programming/literate-programming/Tools]
 
From mfy@sli.com Fri Aug 27 21:33:39 GMT 1993
Date: Fri, 27 Aug 93 21:33:39 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.edu
Subject: code reordering
 
Lee Wittenberg, responding to John Hamer, wrote:
 
    I would suggest that code re-ordering is a necessary, but not
    sufficient feature of LP.
 
Although this sounds plausible, it is unsupported by empirical evidence.  My
tool does not reorder code; this seemed to be a serious obstacle precisely
once.  On that occasion, I just sent the various parts to separate files and
catenated them together in the build.
 
The same holds for macro processing: it isn't part of the tool, and this tool
was created by adding features as they became needed.  If you need macro
processing, you can write your code in a macro language like m1; this is simple
because the tool is independent of source language.  I strongly believe LP
tools should not have intrinsic language dependencies; what is the point of
hobbling yourself this way?  At a minimum, most of the LP texts I write emit
both source code and UNIX makefiles.  Frequently, they emit shell, awk, or sed
scripts as well, and sometimes it is necessary to include C or assembly code in
a program that is mainly written in (say) Ada or Pascal.
 
What is done well by other tools need not be part of a LP processor.  Code
re-ordering can be useful, but it is by no means necessary.
 
	Michael F. Yoder [mfy@sli.com]
 
From koopman@sgi84.ctc.com Fri Aug 27 19:18:18 -0400 1993
Date: Fri, 27 Aug 93 19:18:18 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, mfy@SLI.COM
Subject: code reordering
 
Michael F. Yoder wrote in High Level Language:
>     I would suggest that code re-ordering is a necessary, but not
>     sufficient feature of LP.
>
> Although this sounds plausible, it is unsupported by empirical evidence.  My
> tool does not reorder code; this seemed to be a serious obstacle precisely
> once.  On that occasion, I just sent the various parts to separate files and
> catenated them together in the build.
 
As a newbie I find high level language sensitivity and code reordering
a great benefit.  Code reordering by the web processor may not be
necessary for literate programming but it seems much easier than your
alternatives.  Certainly we must agree that the order of code which
makes the compilers happy is unlikely to be the same as that which
allows the literate programmer to enlighten her audience.
 
> What is done well by other tools need not be part of a LP processor.  Code
> re-ordering can be useful, but it is by no means necessary.
 
Tools that can't parse code would have difficulty providing the pretty
printing capability which greatly enhances the appearance and improves
readability of the code scraps, IMNHO.  To perform the pretty printing
and not provide for code reordering seems like going out in the rain
with an umbrella full of holes.  To add many macro executives or file
creating directives seems like a lot more work than the programmer
should like to manage, especially in the light of relatively simple
techniques for code reordering with tools like FWEB.
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
 
From norman@bellcore.com Fri Aug 27 23:17:51 -0400 1993
Date: Fri, 27 Aug 93 23:17:51 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: TeX and literate programming
 
There's been much discussion of whether TeX is essential to literate
programming, and if so, why.  Ignoring the argument that TeX is used
because it produces superior documents, I think there are two reasons:
one sociological and one technical (and partly sociological).
 
The sociological reason is that literate programming has achieved what
credibility it has primarily because of the enthusiastic support of
Don Knuth.  People who are willing to follow Don out on a limb to
practice literate programming are also likely to follow him in the use
of TeX---after all, there is a much stronger consensus about the value
of TeX in its arena.
 
The technical reason is that all literate-programming tools have to
manipulate an underlying representation of a document to produce code.
Of lesser stature are the non-reordering tools like doc.sty and
cnoweb, which manipulate code to produce a docuement.  In both cases
life is infinitely easier if the underlying representation is well
documented, and preferably ASCII.  (The only counterexample I know is
Lee Wittenberg's WinWordWeb, which I am eager to hear more about.)
Before TeX83, there were quite a few of these things around: Scribe,
troff, Waterloo/IBM Script.  (I don't count gml since that was and is
a markup language, not a formatter.)  Scribe is dead (?), and heaven
knows what goes on in the IBM world, but troff is certainly alive and
well in large parts of the old Bell organization.
 
So why don't literate programmers use troff?  They used to---one of
the first non-Knuth tools was Harold Thimbleby's cweb with troff.  One
answer is that many literate programmers are young people---the young
are always more willing to try new things---and I don't think many
young people are learning troff these days.  TeX is too much better.
Another is that I've posed the question wrong; it should be ``why
don't troff users write literate programs?''  Why, because they have
no tools.  It's bad enough to try something new, but it's worse if you
have to jettison your years of troff experience.
 
I have a standing offer open to any troff user interested in literate
programming: if you will show me how to get the stuff to look right on
the page, and if you promise to write at least one literate program, I
will write a troff back end for noweb.  Tell your friends.
 
Norman
 
From ae1181t@stnfor.ae.ge.com Sun Aug 29 20:00:42 -0400 1993
Date: Sun, 29 Aug 1993 20:00:42 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, mfy@sli.com.ae.ge.com.ae.ge.com
Subject: Re: code reordering
 
It seems like some people use LP to pretty print/document the code. 
I think it can be very useful in the design phase as a PDL if the LP tool
can reorder code. To some just documenting (even with the aid of TeX) seems
to be enough to be an LP tool. I disagree. It also has to be language
independent as sed, make and other `languages' are used often, and reorder
code, files, and has a minumum indexing feature. However, this area seems
to be wide open to personal feelings.
Osman
 
From Christian Mon Aug 30 08:56:43 +0200 1993
Date: Mon, 30 Aug 1993 08:56:43 +0200
From: Christian Lynbech <lynbech@daimi.aau.dk>
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.edu, narsu@AGNI.HKS.COM
Subject: Re: Question from a novice
 
Let me just repeat what many people has already said. Learning the basic use of
TeX or LaTeX is not very complicated. I only really know LaTeX, but the basics
are in fact quite easy. I claim that a few hours of reading/training, and a
copy of the refcard, you can start produce nice looking documents.
 
Beware, however, that disagreeing with the decisions made by TeX/LaTeX, in
spacing or placement of things like figures, may need considerable experience,
if you want to have your way. Too many newcomers are frustrated by this, in my
experience at least. I, as a happy LaTeX'er, find this a feature rather than a
problem, far outweighed by the power.
 
Alternatively, you may want to check out the FunnelWEB package. I haven't
looked much into it myself, but I vaguely remember from my browsing through the
manual, that it sort of supports formatting, in the sense that it provides a
simple set of formatting commands. The nice part is that it can get you started
formatting very quick (and in a TeX indepedent way). The bad part is that you
are likely to find the possibilities rather limited. But if your requirements
aren't fancy, perhaps this would be something for you.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From dentato@minerva.ing.uniroma1.it Mon Aug 30 15:37:41 +0100 1993
Date: Mon, 30 Aug 1993 15:37:41 +0100 (DFT)
From: dentato@minerva.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
To: litprog@shsu.edu
Subject: Nuweb for Mac
 
 A friend of mine is intersted about nuweb for Macintosh after I showed him
the Unix version. I remember someone ported nuweb on Mac, is it possible to
have a copy of it?
 
 Thanks.
 
      ___ __          Universita' di Roma "La Sapienza"
     //_/// \         Dipartimento di Informatica e Sistemistica
    // \//__/         Via Buonarroti 12    00184 Roma  (Italy)
   Remo Dentato       tel: +39-6-4873689   fax: +39-6-4873628
                      email:  dentato@cadgroup.ing.uniroma1.it  
 
From Lee Mon Aug 30 10:38:53 EDT 1993
Date: Mon, 30 Aug 93 10:38:53 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, bart@cs.tamu.edu
Subject: Re: You need very little TeX
 
Bart Childs writes:
 
> I have looked at several dozen WEBs from a wide array of programmers.
> The sad truth is that nearly everybody that use WEBs will put in
> almost no TeX commands on their own.   I say that is sad because just
> a few can be a significant help.
 
I can support this as well.  The webs my colleagues at Tipton Cole +
Co.  are writing use a minimal amount, mostly from a template I
provided that includes things like PVCS support, tables of contents,
etc.  Whenever I get a chance, I try to point out an interesting
TeX/LaTeXism that might be helpful.  I also try to exercise TeX a bit
more than necessary in my webs to take advantage of the ``Gee whiz,
can I do that, too?'' factor.
 
> A user can buy Art Samuels' ``First Grade TeX'' from the TeX users
> group for less than $10.  It is 40 pages long and has more TeX than
> is used in 99% of the WEBs written by 95% of the users.
 
I would also add Michael Doob's excellent _A Gentle Introduction to
TeX_ to this list (sic).  It's freely available over the Internet; I
got my copy from pip.shsu.edu.
 
> I strongly believe that `the use of TeX is an excuse (and not a
> reason) to avoid literate programming.'  A one-day training course
> in TeX is far more than is needed and gives more formatting
> capabilities than is even possible with most WYSIWYG systems.
> TeX could be made invisible to most literate programming users.
 
Again, I agree completely.  The necessary TeX/LaTeX commands (for
noweb use, at least) take less than a page -- less than half a page,
actually, since this list includes the \section commands, which are
not _absolutely_ necessary (but incredibly useful).  I've found that
it only takes about an hour to teach someone the basics.
 
		-- Lee
 
From sboyle@wv.MENTORG.COM Mon Aug 30 09:54:51 -0700 1993
Date: Mon, 30 Aug 93 09:54:51 -0700
From: sboyle@wv.MENTORG.COM (Sean Boyle x1542)
Reply-To: LitProg@SHSU.edu, sboyle@WV.MENTORG.COM
To: LitProg@SHSU.edu, norman@bellcore.com
Subject: TeX and literate programming
 
To be fair, it should be pointed out that [nt]roff has one strength
over TeX, the ability to produce straight text output.  I am often
required to send out a document for review via Email.  With TeX, the
only choices I have are sending out the source file, the DVI file
(uuencoded) or PostScript.  Any of the above choices are clearly
unacceptable to most of my peers and management.  Yes, I know about
dvi2tty and such utilities.  Theoutput fromthese isunacceptable,
probably dueto kerningit lookslike this...  Without a *lot* of mucking
around with the text, it looks terrible.  Nroff does a fair job of
coming up with a straight text representation.
 
BTW, I still use TeX (until my manager kills me).
 
   X-Listname: Literate Programming Discussion List <LitProg@SHSU.edu>
   Warnings-To: <>
   Sender: LP-Mgr@SHSU.edu
   Date: Fri, 27 Aug 93 23:17:51 -0400
   From: norman@bellcore.com (Norman Ramsey)
   Reply-To: LitProg@SHSU.edu, norman@bellcore.com
 
                               .
                               .
                               .
   So why don't literate programmers use troff?  They used to---one of
   the first non-Knuth tools was Harold Thimbleby's cweb with troff.  One
   answer is that many literate programmers are young people---the young
   are always more willing to try new things---and I don't think many
   young people are learning troff these days.  TeX is too much better.
   Another is that I've posed the question wrong; it should be ``why
   don't troff users write literate programs?''  Why, because they have
   no tools.  It's bad enough to try something new, but it's worse if you
   have to jettison your years of troff experience.
                               .
                               .
                               .
 
From koopman@sgi84.ctc.com Mon Aug 30 19:19:21 -0400 1993
Date: Mon, 30 Aug 93 19:19:21 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, sboyle@WV.MENTORG.COM
Subject: TeX and literate programming
 
Sean Boyle wrote to the good readers of LitProg:
> To be fair, it should be pointed out that [nt]roff has one strength
> over TeX, the ability to produce straight text output.  I am often
> required to send out a document for review via Email.  With TeX, the
> only choices I have are sending out the source file, the DVI file
> (uuencoded) or PostScript.
...
 
Does some TeX hack know of a good detex utility?  I have discovered
the utilities described in the following excerpt from the README file
found in the examples directory under ftp/cweb on anon ftp at
labrea.stanford.edu.  Their purpose is not to remove TeX and leave a
semblance of formatting, though.
 
"The extex and wordtest programs, by Don Knuth, are useful spellcheckers.
After "make extex.run" say also "ln extex excweb"; this gives
you two filter programs, extex and excweb, that remove extraneous
material from TeX and CWEB source files, respectively. To use them,
you can say for example
   cat foo.w | excweb | spell
(or replace "cat foo.w" with "wmerge foo.w bar.ch"). A similar pipeline
for TeX files would be
   cat foo.tex | extex | spell
Even better is to replace "spell" by "wordtest /usr/local/lib/dict/words",
if you have a suitable dictionary. One such dictionary in the public domain
can be found in directory ~ftp/pub/dict at labrea.stanford.edu, available
via anonymous ftp. To make your own dictionary from given ones,
   cat dict1 dict2 dict3 dict4 | wordtest > words
is quick and effective. See the documentation of wordtest for more info."
 
>    From: norman@bellcore.com (Norman Ramsey)
...
>    So why don't literate programmers use troff?  They used to---one of
...
>    no tools.  It's bad enough to try something new, but it's worse if you
>    have to jettison your years of troff experience.
 
Know of no help with this, except, doesn't all that [nt]roff knowledge
easily map over to the TeX domain?  Perhaps you need the wetware
upgrade? ;-)
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
 
From bart@cs.tamu.edu Mon Aug 30 21:28:02 CDT 1993
Date: Mon, 30 Aug 93 21:28:02 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: litprog@shsu.edu
Subject: One more comment on troff
 
Re: Thimbleby's paper on cweb using C and troff.
It is not worth my time to go back and read it carefully, but I recall
a point made in that paper is that the limitations of troff were one
of the most significant problems in creating the system.
 
If having something that can produce a screen oriented version is that
important, doesn't texinfo do that to some extent?  I would rather work
on the future rather than ...  TeX and laser printers are so reasonably
priced that I wonder what the gain is?
 
Cheers
 
Bart Childs
 
From Christian Tue Aug 31 09:11:53 +0200 1993
Date: Tue, 31 Aug 1993 09:11:53 +0200
From: Christian Lynbech <lynbech@daimi.aau.dk>
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.edu, bart@cs.tamu.edu
Subject: Re: One more comment on troff
 
Texinfo should do the trick on straight text output. There is even the added
feature of being able to produce an info file, i.e. a hypertext representation
of the program! I have had this idea in the back of my head for quite some
time, but I haven't had time to investigate it much. Certainly, producing a
*usefull* program.info file, takes some care and consideration.
 
I am not much of a texinfo hacker myself, but since texinfo is a juiced down
version of TeX (sort of), wouldn't that also solve some of the learning
problems reported by people. Some of the principle behind texinfo (as I
understand it), is exactly to provide those macros you need and use, rather than
the full power of TeX, enabling a precise and nice looking ascii equivalent.
There is also a standalone version of texinfo (available from GNU), so you can
use it without having neither TeX nor emacs.
 
Incidently, there is also a LaTeXinfo package, for those already into LaTeX. I
have had a chance to look into it, and it feels pretty complete, i.e. it has
most of the stuff I tend to be using all the time, including some list making
environments. More important perhaps, it looks as ordinary LaTeX, you write
\section rather than @section and \begin{description}\end{description} rather
than whatever the Texinfo equivalent looks like.
 
The downside is that its maintainance situation is a bit in the dark. There was
a discussion on gnu.misc.discuss about how to reach the author, and apparently
nobody had succeeded. But the package works pretty well as it stands. I've got a
copy of what appeared to be the latest version at the time, if anybody is
interested. 
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From sven@robots.oxford.ac.uk Tue Aug 31 9:52:08 BST 1993
Date: Tue, 31 Aug 93 9:52:08 BST
From: sven@robots.oxford.ac.uk
Reply-To: LitProg@SHSU.edu, sven@ROBOTS.OXFORD.AC.UK
To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
Subject: texinfo
 
Bart Childs wrote
> If having something that can produce a screen oriented version is that
> important, doesn't texinfo do that to some extent?  
 
Ghee, *what* is texinfo? 
 
Thanks, Sven 
 
(Sven Utcke)
 
From marcus@x4u.desy.de Tue Aug 31 11:10:18 +0200 1993
Date: Tue, 31 Aug 93 11:10:18 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, lynbech@daimi.aau.dk
Subject: Re: One more comment on troff
 
Since HyperText is the talk of town again--what happened to Stephen
Cross' project on hypertextified literate programming?
 
|> The downside is that its maintainance situation is a bit in the
|> dark. There was a discussion on gnu.misc.discuss about how to reach
|> the author, and apparently nobody had succeeded. 
 
I did not follow the dicussion on gnu.misc.discuss. I have very good
experiences with Texinfo maintenance, though. The relevant guy is
Roland McGrath (FSF), roland@gnu.ai.mit.edu. He is very responsive and
gets into contact with the Texinfo author(s) fast.
 
 Incidentally, I agree with all of Christian's conclusions.
 
From marcus@x4u.desy.de Tue Aug 31 11:17:56 +0200 1993
Date: Tue, 31 Aug 93 11:17:56 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, sven@robots.ox.ac.uk
Subject: re: texinfo
 
Bart> If having something that can produce a screen oriented version is that
Bart> important, doesn't texinfo do that to some extent?  
 
Sven> Ghee, *what* is texinfo? 
 
[repost from Dec 92]
 
Texinfo is a documentation system that uses a single source file to
produce both on-line information [preferably using the GNU Emacs info
reader] and printed output.
 
Texinfo does not the GNU Emacs editor -- it's just much simpler
if you have one [the same is true for the Info facility -- there is
a standalone "info" executable].
The current distribution [texinfo-2.1?.tar.Z]
can be retrieved via Anonymous FTP prep.ai.mit.edu
in directory pub/gnu. Installation is easy since
the FSF [Free Software Foundation] provides self-configuring files
for a wide variety of machines. Without Emacs, what the minimum
needed is two executables,
o "texi2dvi" for the step .texinfo -> .dvi, and
o "makeinfo" for the step .texinfo -> .info (i.e. text),
together with a collection of macros
o "texinfo.tex".
   If you have Emacs on your system, most probably you will also
have those files somewhere in a /local/ dir.
 
There is also the texi2roff formatter which makes you independent of TeX
available from prep.ai.mit.edu.
 
From Christian Tue Aug 31 11:33:22 +0200 1993
Date: Tue, 31 Aug 1993 11:33:22 +0200
From: Christian Lynbech <lynbech@daimi.aau.dk>
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: marcus@x4u.desy.de
Subject: (La)TeXinfo (was Re: One more comment on troff)
 
Unfortunately, the LaTeXinfo package was not created by the GNU folks. 
 
My manual (dated june 17, 1992, version 1.7) states Michael Clarkson as author
(in addition to R. Stallman and R.  Chassell, but that must refer to the
original texinfo package).
 
I quote here another mail I got on the subject, for any interested parties.
 
> Date: Tue, 31 Aug 93 09:42:35 +0100
> From: Will Partain <partain@dcs.gla.ac.uk>
> X-Charset: LATIN1
> X-Char-Esc: 29
> 
> Our homebrew "literate programming" system is a Texinfo-based system
> (actually) that tries to look like LaTeX.  I posted a note about it a
> while back.  You'll find all the stuff on ftp.dcs.glasgow.ac.uk,
> pub/haskell/glasgow/lit2x-0.16*.  The .dvi and .info documentation
> files are both there.
> 
> Will
> 
 
-- Christian
 
From ddw2@sunbim.be Tue Aug 31 12:20:09 +0200 1993
Date: Tue, 31 Aug 93 12:20:09 +0200
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
Subject: Re: One more comment on troff
 
   Christian> Texinfo should do the trick on straight text
   Christian> output. There is even the added feature of being able
   Christian> to produce an info file, i.e. a hypertext
   Christian> representation of the program! I have had this idea in
   Christian> the back of my head for quite some time, but I haven't
   Christian> had time to investigate it much. 
 
I've had this in mind for a while and have been considering making
nuweb work also for texinfo files. I think it would not be hard to
quickly do if one abandons some of the nice formatting stuff that are
available under Latex. 
 
But then it seems possible to exploit the referencing features of
texinfo to provide navigational aids to browse the source under info.
 
  Christian> Certainly, producing a *usefull* program.info file,
  Christian> takes some care and consideration.
 
In the project I'm working on, all system, manuals and program
documentation must be written using TeXinfo. Then as usual that
allows discrepancies (often quite large) between the real code and
its associated documentation. I started using nuweb to provide
additional documented code for the project, but now I would like to
convert this to texinfo but without loosing the literate programming
approach. This would allow me to convince other people of the
benefits.
 
   Christian> I am not much of a texinfo hacker myself, but since
   Christian> texinfo is a juiced down version of TeX (sort of),
   Christian> wouldn't that also solve some of the learning problems
   Christian> reported by people. Some of the principle behind
 
As I said earlier, texinfo is rather limited in typographical
capabilities while the literate approach benefits a lot from such
typography to include navigational references in the printed output
while keeping those non-annoying (verbosity,length,size...)
 
   Christian> Incidently, there is also a LaTeXinfo package, for
   Christian> [text deleted]
 
   Christian> The downside is that its maintainance situation is a
   Christian> [text deleted]
 
That's the reason why texinfo was chosen for the project mentionned
above, but we did look at latexinfo too and found that it would allow
better looking documentation to be produced. 
 
Maybe we could start a discussion on what would be
required/nice/ideas related to modifying nuweb to support texinfo.
 
(I already have a version that can use a character other than @ for
commands)
 
Dominique
 
Dominique de Waleffe             ddw@sunbim.be
BIM sa
Chaussee de Louvain, 510	 Tel: +32 2 719 26 14
B-1930 Zaventem			 Fax: +32 2 725 47 83
Belgium
 
From marcus@x4u.desy.de Tue Aug 31 14:17:34 +0200 1993
Date: Tue, 31 Aug 93 14:17:34 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: Literate Programmers <litprog@shsu.edu>
Subject: Glasglow litprog tool doc on WWW
 
Will Partain let me access the Texinfo source for the documentation of
the Glasgow tools--you can access them now on the World Wide Web:
 Try the links in "Tools" or "HyperLitProg". The direct address is
 
  http://info.desy.de:80/pub/www/projects/Litprog/glasgow/top.html
 
From mfy@sli.com Tue Aug 31 15:51:59 GMT 1993
Date: Tue, 31 Aug 93 15:51:59 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.edu
Subject: code reordering
 
Greetings to Michael Koopman and other literate programmers.
 
Your response in some measure fits into a very common pattern in discussions:
you have stated true statements which don't contradict what I said.  You find
code reordering to be useful: I can't contradict that.  I find it unnecessary;
presumably you don't disagree with that either.  However, there are some
statements I do disagree with, for example:
 
>Certainly we must agree that the order of code which
>makes the compilers happy is unlikely to be the same as that which
>allows the literate programmer to enlighten her audience.
 
No: I do not agree.  There is not a single best way of enlightening the
audience, as your phrase "the same as" would suggest, but many.  There are also
many orders for presenting the code in a way that makes the compiler happy, in
the common case where it is a package or module being presented rather than a
program.  (Perhaps because of my various programming biases, including LP, my
programs tend to be made of many modules and a small "main" program.)  In the
languages I use (mostly Ada and extended Pascal), I find it easy to present the
code in an order also useful for exposition.  It is particularly easy with Ada,
which allows subunits.
 
>...  To add many macro executives or file
>creating directives seems like a lot more work than the programmer
>should like to manage, especially in the light of relatively simple
>techniques for code reordering with tools like FWEB.
 
This would be true if it applied, but one directive in nine years of using the
tool hardly counts as "many."  The directive takes up 7 lines in a make file:
not a significant amount of extra work for a nine year span.  It is absolutely
certain (to me, anyway) that the amount of extra work caused by the absence of
the reordering ability has been far less than the work it would have taken to
implement a macro capability.  (If there were enough users of the tool, this
would presumably change, but it isn't clear where the crossover point is.)
 
Finally, you opined that pretty printing was an important capability.  Again I
disagree: my pretty printing is (in effect) done by Emacs as the code is put
onto the electronic page, so I consider this a feature duplicating the
capabilities of other tools.  And I would ten thousand times rather have
language independence than pretty printing, even aside from the fact that my
personal experience with "pretty" printing is that it often comes out ugly.
 
Lest I seem too negative, let me say that I believe a macro capability to be
useful enough that a maximally good LP tool "ought" to have it.  But the gains
are more political than practical: there are enough people who won't touch a LP
tool that lacks it that one lacking it can't succeed even if it were
technically quite sufficient.  Put another way: the real gains are small, but
the perceived gains are large.  But by no means do I mean to imply that the
gains are zero.
 
	Michael F. Yoder [mfy@sli.com]
 
From mfy@sli.com Tue Aug 31 18:35:25 GMT 1993
Date: Tue, 31 Aug 93 18:35:25 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.edu
Subject: TeX needed for LP?
 
To add a single datapoint to the pool: my tool doesn't need TeX; it has three
output modes, one of which produces LaTeX.  It has a mode in which it generates
LN03 output directly which is only used in special situations and when
desperate; the third mode generates Interleaf(tm) ASCII form, and the output is
of quality comparable to the quality of the LaTeX output.
 
The mode which makes the Interleaf form was commissioned by Apollo Computer
(before it became part of HP): this is because they had standardized on
Interleaf for documentation.
 
Opinion: an LP tool ought to be mostly formatter independent but allow for
escape sequences so formatter commands can be included directly.  I often use
these to insert Tex or LaTeX sequences, and it is usually simple to arrange
that the commands are ignored in other modes so the only effect is to have the
output be prettier in TeX mode than the others.  Occasionally I assume that the
document will only be printed in the TeX mode.
 
	Michael F. Yoder [mfy@sli.com]
 
From Christian Tue Aug 31 21:20:15 +0200 1993
Date: Tue, 31 Aug 1993 21:20:15 +0200
From: Christian Lynbech <lynbech@daimi.aau.dk>
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.edu, mfy@sli.com
Subject: Re: code reordering
 
> From: mfy@sli.com (Mike Yoder)
[...stuf deleted...]
> >Certainly we must agree that the order of code which
> >makes the compilers happy is unlikely to be the same as that which
> >allows the literate programmer to enlighten her audience.
> 
> No: I do not agree.  There is not a single best way of enlightening the
> audience, as your phrase "the same as" would suggest, but many.  There are also
> many orders for presenting the code in a way that makes the compiler happy, in
> the common case where it is a package or module being presented rather than a
> program.  (Perhaps because of my various programming biases, including LP, my
> programs tend to be made of many modules and a small "main" program.)  In the
> languages I use (mostly Ada and extended Pascal), I find it easy to present the
> code in an order also useful for exposition.  It is particularly easy with Ada,
> which allows subunits.
[...more stuff deleted...]
 
I'm sorry if I'm goeing back on something already discussed.
 
I do not think that code reordering, in itself, is the true virtue of literate
programming. To many languages has sufficiently `presentation freedom' to keep
both the compiler and the audience (somewhat) happy.
 
It is more the ability to interleave explanation and (totally order indepedent)
code, in manageable chunks and at the power of report formatting/production. A
nicely formatted report (or the like) with a something like a table of
contents, nested sections and cross references (you were talking about FWEB,
weren't you?), is far superior in my view. But it is not the ability to start
with the main procedure, but rather the ability to have a properly formatted
piece of text, explainig the finer points, that makes literate programming take
off. I have yet to see any program so thoroughly documented that it rivals any
of the (admitted somewhat few) literate programs with regards to readability and
understandability.
 
But remember, the issue is not whether it is *possible* at all, to program
without literate programming in this or that form. The majority of the world
seems to be doeing reasonably fine without it.
 
From coates@spectro.jussieu.fr Tue Aug 31 21:59:00 +0200 1993
Date: Tue, 31 Aug 93 21:59:00 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu
Subject: Re: code reordering
 
Dear Litproggers,
	On the subject of the value of code reordering, I have to say that even
if it isn't *necessary*, for the C++ code that I write (using FunnelWeb), I
find it invaluable to put the definitions and implementations of the methods
beside one another in the FunnelWeb source, although they end up in separate
files (.h and .cc) afterwards.  This may not be necessary, but if one of the
goals of LP is to reduce programmer errors, then having the definitions side
by side with the implementation certainly helps me.  The errors usually aren't
serious, in the sense that the compiler tells me of any mismatch, but I just
save a lot of time when the two are together, because I can see instantly
that the both declarations match.  Yes, with Emacs I can look at both a .h and
a .cc file at once, but I just don't find it as convenient as having things
together in one file.
	So, for me, a LitProg tool that couldn't reorder code and generate
multiple source files would not be nearly so useful as what I have now.  You
can argue whether I *really* save so much time, but I have to say that having
related declarations together in one file is much easier for my poor little
brain than having them spread across two or more files.
	Anyway, just my 2 centimes worth ...
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux 
 ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of
 these two sets is probably empty."
________________________________________________________________________________
 
From mfy@sli.com Tue Aug 31 21:00:44 GMT 1993
Date: Tue, 31 Aug 93 21:00:44 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.edu
Subject: reordering code etc.
 
Good day to Tony Coates and the Literate Programming bunch.  You wrote:
 
>	So, for me, a LitProg tool that couldn't reorder code and generate
>multiple source files would not be nearly so useful as what I have now.
 
I may have created a false impression with my earlier postings.  My tool makes
multiple source files, but doesn't reorder code within them.  Its processing of
the files is mostly limited to conditional inclusion, e.g. "@case host" and
"@case target" where 'host' and 'target' are user-defined enumeration types.
 
	Michael F. Yoder [mfy@sli.com]
 
From Lee Tue Aug 31 17:30:20 EDT 1993
Date: Tue, 31 Aug 93 17:30:20 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, mfy@sli.com
Subject: Re: code reordering
 
Michael Yoder brings up an interesting point:
 
> Lest I seem too negative, let me say that I believe a macro capability to be
> useful enough that a maximally good LP tool "ought" to have it.  But the gains
> are more political than practical: there are enough people who won't touch a LP
> tool that lacks it that one lacking it can't succeed even if it were
> technically quite sufficient.  Put another way: the real gains are small, but
> the perceived gains are large.  But by no means do I mean to imply that the
> gains are zero.
 
The interesting thing is that code reordering IS macro expansio, at
least in the LP systems I am familar with.  To be more precise, it is
macro expansion without parameters (the possibility of allowing
parameters in chunk names generated a lot a traffic a while ago, so I
won't delve into that again).  
 
A rose by any other name?
 
		-- Lee
 
From koopman@sgi84.ctc.com Tue Aug 31 21:55:12 -0400 1993
Date: Tue, 31 Aug 93 21:55:12 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
Subject: code reordering
 
>Christian Lynbech <lynbech@daimi.aau.dk>
>
>> From: mfy@sli.com (Mike Yoder)
>[...stuf deleted...]
>> >Certainly we must agree that the order of code which
>> >makes the compilers happy is unlikely to be the same as that which
>> >allows the literate programmer to enlighten her audience.
>> 
>> No: I do not agree.  There is not a single best way of enlightening the
>> audience, as your phrase "the same as" would suggest, but many.  There are also
>> many orders for presenting the code in a way that makes the compiler happy, in
>> the common case where it is a package or module being presented rather than a
>> program. 
 
I concur that there is not a single best exposition for any
communication involving a literate program (WEB) or it's artifact
(WEAVE).  However, independence from order restrictions imposed by the
compilers is significant to the use of LP tools in the maintenance of
existing large implementations.  Unfortunately I must work with a
legacy of non-highly order independent programs, e.g., C, Fortran.  Of
course, burning all this Neanderthal code and restarting from scratch
with *modern* tools is the Right Thing.  Chipping away with WEB based
exposition regarding the algorithms and implementation strategies has
low utility.  Rewrites where necessary to attain the elegance of right
thinking post-modern Application Interfaces is kludgy beyond
acceptable limits, except for the minor requirement of delivery.
 
Anyone have a foolproof software paradigm conformal mapping
implementation?  A tool to test if a software paradigm is defined on
an orthogonal basis would help, too.
 
>I do not think that code reordering, in itself, is the true virtue of literate
>programming. To many languages has sufficiently `presentation freedom' to keep
>both the compiler and the audience (somewhat) happy.
 
Turning the NIH (not invented here) volume to maximum and rewriting
all existing code in, admittedly, highly improved implementations,
such as OOA/D and ADA 9x, would be marvelous and the code order
restrictions of the compiler could be reduced to acceptable limits.
This approach may not be possible for many.
 
>It is more the ability to interleave explanation and (totally order indepedent)
>code, in manageable chunks and at the power of report formatting/production. A
>nicely formatted report (or the like) with a something like a table of
>contents, nested sections and cross references (you were talking about FWEB,
>weren't you?), is far superior in my view.
 
A brief retrace to pretty printing.  Language sensitivity is a boon to
the programmer in automagically generating an index and cross
references.  Language independence is valuable, also.  The two are not
mutually exclusive.  However, the complexity of the LP tool that
generates index entries by parsing code is greater than one which
requires the author's interjection of 'escaped sequences' to
accomplish the same.  In this same breath, the escaped sequences are
hazardous to the health of language independence.
 
A WEB should not be a static document, i.e., equivalent to it's
current WEAVE.  If I need to create an exposition with a focus
different than the current WEAVE, or need to present the same WEB to a
different audience, I want to be able to move, splice, dice, fold,
spin and mutilate the current WEAVE and still end up with a compilable
TANGLE.  I loose all my impact if the WEB breaks and can no longer do
the stupid dog trick of the compiled TANGLE.  The goal of a coherent
exposition (logical WEAVE) should eliminate much of the pathology
associated with arbitrarily moving pieces of code scraps about in the
WEB.  (I seem to have abstracted beyond a valuable thesis;
hypothetical premise).
 
>But remember, the issue is not whether it is *possible* at all, to program
>without literate programming in this or that form. The majority of the world
>seems to be doeing reasonably fine without it.
 
Drat, the Real World, again.  FOO.
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
A technology's benefit must outweigh the risk in dollars & sense.
 
From preston@cs.rice.edu Wed Sep 1 09:06:30 CDT 1993
Date: Wed, 1 Sep 93 09:06:30 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: indexing and language-independence
 
Koopman writes:
>A brief retrace to pretty printing.  Language sensitivity is a boon to
>the programmer in automagically generating an index and cross
>references.  Language independence is valuable, also.  The two are not
>mutually exclusive.  However, the complexity of the LP tool that
>generates index entries by parsing code is greater than one which
>requires the author's interjection of 'escaped sequences' to
>accomplish the same.
 
The only new idea in nuweb was a way to semi-automatically generate
an index for a language-independent LP system.  Works fine and requires
no escape sequences.  IMHO, the results are more useful than the automatically
generated variety produced by weave and cweave.
 
Norman Ramsey has adapted the same approach to noweb and it could also
be adapted to funnelweb (or weave and cweave, for that matter).
 
Preston Briggs
 
From ravenek@chem.vu.nl Mon Sep 6 15:20:48 MET 1993
Date: Mon, 6 Sep 93 15:20:48 MET DST
From: ravenek@chem.vu.nl (Walter Ravenek)
Reply-To: LitProg@SHSU.edu, ravenek@CHEM.VU.NL
To: LitProg@SHSU.edu, dentato@MINERVA.ING.UNIROMA1.IT
Subject: Re: Nuweb for Mac
 
> A friend of mine is intersted about nuweb for Macintosh after I showed him
>the Unix version. I remember someone ported nuweb on Mac, is it possible to
>have a copy of it?
>
> Thanks.
>
>      ___ __          Universita' di Roma "La Sapienza"
>     //_/// \         Dipartimento di Informatica e Sistemistica
>    // \//__/         Via Buonarroti 12    00184 Roma  (Italy)
>   Remo Dentato       tel: +39-6-4873689   fax: +39-6-4873628
>                      email:  dentato@cadgroup.ing.uniroma1.it  
 
Hi,
I was away for some time, hence the delay.
I have ported nuweb to the Mac. It runs with THINK C. Do
you want my changes to the source or the apllication I
generated?
Walter Ravenek
Dept. of Chemistry
Vrije Universiteit
De Boelelaan 1083
1081 HV Amsterdam
The Netherlands
e-mail: ravenek@chem.vu.nl
 
From mpalma@usb.ve Thu Sep 09 16:08:26 -500 1993
Date: Thu, 09 Sep 1993 16:08:26 -500
From: mpalma@usb.ve (Prof. Marcos E. Palma Marin)
Reply-To: LitProg@SHSU.edu, mpalma@USB.VE
To: LitProg@SHSU.edu, kcousins@RP.CSIRO.AU
Subject: Re: Internet Survey
 
>                              INTERNET SURVEY
>
>                     Adele F. Bane <AFB2@PSUVM.PSU.EDU>
>                 William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
>              The Pennsylvania State University at Great Valley
>_______________________________________________________________________________
>_
>This electronic mail survey is being conducted to identify the functions of 
the 
>Internet that are most used by the academic community.  You have been 
chosen as 
>a member of a selected academic list service (LISTSERV) to participate.  
>Results of this survey will form the basis of a journal article to be 
published 
>later this year.  Please answer all survey questions.  
>_______________________________________________________________________________
>_ 
>
>INTERNET INSIGHTS:  A Survey
>
>We will begin by asking a few questions about yourself:
>
>	How many years of computer experience do you have?	_15____  5 year  
>	How long have you used e-mail of any type?		_8____   1 year
>	How long have you been an Internet user?		_2____	 1 year
>
>Three primary functions of the Internet have been identified.  They are 
>electronic mail, Telnet or remote log-in, and FTP or file transfer.  An 
>estimated 15 million users take advantage of these functions daily.  
>This survey explores the use of each of these services.
>
>1.  E-Mail Use:  How often do you make these connections?
>
>	   (Insert the appropriate number beside items below:)
>
>	1=Not at all			4=About 2-3 times a month
>	2=A few times			5=Once a week
>	3=About once a month		6=More than once a week
>
>		Private Email:					_6____ 2
>
>		Discussion group(s):				_6____ 2
>			(Specify)
>				Literate Programming, 'LitProg'
>				Mathematica 'MathGroup'
>
>		Usenet (or Netnews)				_6____  1
>
>		Electronic journal(s)/newsletters(s):		_2____  1
>			(Specify)
>				DECnews
>
>
>
>2.  Telnet Use:  How often do you connect to remote databases?
>
>	   (Insert appropriate number beside items below.)
>
>	1=Not at all			4=About 2-3 times a month
>	2=A few times			5=Once a week
>	3=About once a month		6=More than once a week
>	
>		Games/Simulations:		_3____1
>		Library Catalogs:		_4____1
>	.	Specialized Databases:		_2____1
>		
>
>2a.  How frequently do you connect these Internet sources:
>
>	   (Insert appropriate number beside items below.)
>
>	1=Not at all			4=About 2-3 times a month
>	2=A few times			5=Once a week
>	3=About once a month		6=More than once a week
>			
>		American Mathematical Society BBS		_1____1
>		American Psychological Assn.			_1____1
>		CARL						_1____1
>		CITADEL						_1____1
>		Cleveland FreeNet				_1____1
>		Dartmouth Dante					_1____1
>		Dialog						_1____1
>		Dow-Jones News Retrieval			_1____1
>		Dranet						_1____1
>		EDIN						_1____1
>		EPA						_1____1
>		ERIC						_1____1
>		FEDIX/MOLIS					_1____1
>		GenBank						_1____1
>		Geographic Name Server				_1____1
>		International Centre for Distance Learning	_1____1
>		ISAAC						_1____1
>		Lexis						_1____1
>		Market/Business Report				_1____1
>		National Education BBS				_1____1
>		Netfind						_2____1
>		Nexis						_1____1
>		Oceanic Information Center			_1____1
>		OCLC						_1____1
>		PENpages					_1____1
>		RLIN						_1____1
>		SpaceLink					_1____1
>		STIS						_1____1
>		TC Forum					_1____1
>		Weather Underground				_1____1
>		Webster Dictionary				_1____1
>	
>		Other  (Please specify):
>
>
>
>3.  FTP Use:  How often do you download files from FTP archive sites?
>
>	   (Insert appropriate number beside each item)
>
>	1=Not at all			4=About 2-3 times a month
>	2=A few times			5=Once a week
>	3=About once a month		6=More than once a week
>	
>		Computers and Academic Freedom			_1____1
>		EASI						_1____1
>		History  					_1____1
>		LIBSOFT						_1____1
>		Lyric and Discography				_1____1
>		NASA 						_3____1
>		Online Libraries Directory			_1____1
>		Science Education				_1____1
>		SIMTEL20					_2____1
>		SUMEX-AIM					_1____1
>		U.S. Supreme Court Decisions			_1____1
>		Washington Uni. Public Domain Archives		_2____
>			
>		Other (Please Specify):
>
>
>
>4.	Several navigational aids have been developed for the Internet.
>	How often do you use these network guides?
>
>	   (Insert appropriate number beside items below.)
>
>	1=Not at all			4=About 2-3 times a month
>	2=A few times			5=Once a week
>	3=About once a month		6=More than once a week
>	
>		Archie						_4____3
>		Campus-wide Information Systems			_2____1		
>		Gopher						_2____1
>		WAIS (Wide-area information servers)		_2____1
>		WWW (WorldWideWeb)				_6____1
>		Veronica					_1____1
>		HYTELNET					_2____
>		Other (Please specify):
>
>
>Personal experiences can be the most helpful to other users.  Please 
comment on 
>the following:
>
>5.  	The importance of the Internet to your work?
>
>	Very important, both as a communication tool and as an information
>	source.
>
>
>
>6.  	Advantages the Internet offers over other resources?
>
>	(Relative) ease of use, fast turnaround, low cost, high bandwidth
>
>
>7.  	Barriers to using the Internet?
>
>	I feel that the access to Internet resources has been hampered by
>	a lack of comprehensive tools. It is one thing to expect hardened
>	programmers and scientists to fiddle with the intricacies of some
>	utilities (ftp, X11 protocols, network addressing stuff, etc.)...
>	quite another to hand these things to the sorts of people who
>	would baulk at a UNIX command line (doctors, artists, perhaps
>	historians, etc.).
>
>8.  	Your most memorable use of the Internet?
>
>
>
>9  These questions will help us interpret the results of this study:
>
>	Title:	_Experimental Scientist_________________
>	Affiliation:  __________________________________	
>	Discipline:  _Electrical Engineering____________	
>	Research Interest(s):_High speed wireless local area_____ 		
>	networking_______________________________________________
>
>Please return the completed survey to: WMILHEIM@PSUGV.EDU
>by September 3, 1993.
>
>If you would like a summary of the survey results, please place your
>e-mail address here:  _kcousins@rp.csiro.au____________________.
>
>
>            :) Thank you for taking the time to participate :)
>
>
>
---------------------------------------------------------------------
Prof. Marcos E. Palma M.     |  Eng. Marcos E. Palma M.
Dpto.Procesos y Sistemas     |  Centro de Informatica y Comunicaciones
Universidad Simon Bolivar    |  Universidad Simon Bolivar
Valle de Sartenejas          |  Valle de Sartenejas
CARACAS-VENEZUELA            |  CARACAS-VENEZUELA
Apto. Postal 89000           |  Apto. Postal 89000
---------------------------------------------------------------------
Phone:  (58) (2) 963-3022    |  e-mail: mpalma@usb.ve
         Ext 3920, 3922      |
FAX:    (58) (2) 93-8420     |
---------------------------------------------------------------------
 
From Dave Thu Sep 9 18:04:37 GMT 1993
Date: Thu, 9 Sep 93 18:04:37 GMT
From: Dave Love <d.love@daresbury.ac.uk>
Reply-To: LitProg@SHSU.edu, d.love@DARESBURY.AC.UK
To: LitProg@SHSU.edu
Subject: Re: TeX and literate programming
 
>>>>> On Mon, 30 Aug 93 09:54:51 -0700, sboyle@COM.MENTORG.wv (Sean Boyle x1542) said:
 
 Sean> Yes, I know about
 Sean> dvi2tty and such utilities.  Theoutput fromthese isunacceptable,
 Sean> probably dueto kerningit lookslike this...  Without a *lot* of mucking
 Sean> around with the text, it looks terrible.  Nroff does a fair job of
 Sean> coming up with a straight text representation.
 
If this sort of thing is important, I think you *can* do a reasonable
job with (La)TeX, but you have to use an appropriate style and fonts
to produce the dvi file, although I don't know of an entirely
satisfactory solution at present.  I may end up doing some work on
this in the near future as a means of avoiding TeXinfo.  If anyone
really feels a need for it, let me know.
 
From Richard Thu Sep 9 23:07:38 +0200 1993
Date: Thu, 9 Sep 1993 23:07:38 +0200 (MET DST)
From: Richard Kooijman <R.Kooijman@et.tudelft.nl>
Reply-To: LitProg@SHSU.edu, R.Kooijman@ET.TUDELFT.NL
To: d.love@daresbury.ac.uk
Subject: Re: TeX and literate programming
 
On Thu, 9 Sep 1993, Dave Love wrote:
 
> >>>>> On Mon, 30 Aug 93 09:54:51 -0700, sboyle@COM.MENTORG.wv (Sean Boyle x1542) said:
> 
>  Sean> Yes, I know about
>  Sean> dvi2tty and such utilities.  Theoutput fromthese isunacceptable,
>  Sean> probably dueto kerningit lookslike this...  Without a *lot* of mucking
>  Sean> around with the text, it looks terrible.  Nroff does a fair job of
>  Sean> coming up with a straight text representation.
> 
> If this sort of thing is important, I think you *can* do a reasonable
> job with (La)TeX, but you have to use an appropriate style and fonts
> to produce the dvi file, although I don't know of an entirely
> satisfactory solution at present.  I may end up doing some work on
> this in the near future as a means of avoiding TeXinfo.  If anyone
> really feels a need for it, let me know.
 
I use dvidoc myself and I am very satisfied. As long as you need
ASCII output, you put in a style called 'dvidoc', run LaTeX and
use dvidoc to display the material.
For final output you remove 'dvidoc' style and use your regular
dvi2something.
 
Richard.
 
From Vince Thu Sep 9 17:50:30 EDT 1993
Date: Thu, 9 Sep 93 17:50:30 EDT
From: Vince Mehringer <vince@eye.com>
Reply-To: LitProg@SHSU.edu, vince@EYE.COM
To: LitProg@SHSU.edu, mpalma@usb.ve
Subject: Re: Internet Survey
 
Your mailer is off!!  I received this completed survey -- but it was
not mine.  I can only hope that MY completed survey is not being
mailed around the world to somebody else.
 
Vince
 
> 
> >                              INTERNET SURVEY
> >
> >                     Adele F. Bane <AFB2@PSUVM.PSU.EDU>
> >                 William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
> >              The Pennsylvania State University at Great Valley
> >_______________________________________________________________________________
> >_
> >This electronic mail survey is being conducted to identify the functions of 
> the 
> >Internet that are most used by the academic community.  You have been 
> chosen as 
> >a member of a selected academic list service (LISTSERV) to participate.  
> >Results of this survey will form the basis of a journal article to be 
> published 
> >later this year.  Please answer all survey questions.  
> >_______________________________________________________________________________
> >_ 
> >
> >INTERNET INSIGHTS:  A Survey
> >
> >We will begin by asking a few questions about yourself:
> >
> >     How many years of computer experience do you have?      _15____  5 year  
> >     How long have you used e-mail of any type?              _8____   1 year
> >     How long have you been an Internet user?                _2____   1 year
> >
> >Three primary functions of the Internet have been identified.  They are 
> >electronic mail, Telnet or remote log-in, and FTP or file transfer.  An 
> >estimated 15 million users take advantage of these functions daily.  
> >This survey explores the use of each of these services.
> >
> >1.  E-Mail Use:  How often do you make these connections?
> >
> >        (Insert the appropriate number beside items below:)
> >
> >     1=Not at all                    4=About 2-3 times a month
> >     2=A few times                   5=Once a week
> >     3=About once a month            6=More than once a week
> >
> >             Private Email:                                  _6____ 2
> >
> >             Discussion group(s):                            _6____ 2
> >                     (Specify)
> >                             Literate Programming, 'LitProg'
> >                             Mathematica 'MathGroup'
> >
> >             Usenet (or Netnews)                             _6____  1
> >
> >             Electronic journal(s)/newsletters(s):           _2____  1
> >                     (Specify)
> >                             DECnews
> >
> >
> >
> >2.  Telnet Use:  How often do you connect to remote databases?
> >
> >        (Insert appropriate number beside items below.)
> >
> >     1=Not at all                    4=About 2-3 times a month
> >     2=A few times                   5=Once a week
> >     3=About once a month            6=More than once a week
> >     
> >             Games/Simulations:              _3____1
> >             Library Catalogs:               _4____1
> >     .       Specialized Databases:          _2____1
> >             
> >
> >2a.  How frequently do you connect these Internet sources:
> >
> >        (Insert appropriate number beside items below.)
> >
> >     1=Not at all                    4=About 2-3 times a month
> >     2=A few times                   5=Once a week
> >     3=About once a month            6=More than once a week
> >                     
> >             American Mathematical Society BBS               _1____1
> >             American Psychological Assn.                    _1____1
> >             CARL                                            _1____1
> >             CITADEL                                         _1____1
> >             Cleveland FreeNet                               _1____1
> >             Dartmouth Dante                                 _1____1
> >             Dialog                                          _1____1
> >             Dow-Jones News Retrieval                        _1____1
> >             Dranet                                          _1____1
> >             EDIN                                            _1____1
> >             EPA                                             _1____1
> >             ERIC                                            _1____1
> >             FEDIX/MOLIS                                     _1____1
> >             GenBank                                         _1____1
> >             Geographic Name Server                          _1____1
> >             International Centre for Distance Learning      _1____1
> >             ISAAC                                           _1____1
> >             Lexis                                           _1____1
> >             Market/Business Report                          _1____1
> >             National Education BBS                          _1____1
> >             Netfind                                         _2____1
> >             Nexis                                           _1____1
> >             Oceanic Information Center                      _1____1
> >             OCLC                                            _1____1
> >             PENpages                                        _1____1
> >             RLIN                                            _1____1
> >             SpaceLink                                       _1____1
> >             STIS                                            _1____1
> >             TC Forum                                        _1____1
> >             Weather Underground                             _1____1
> >             Webster Dictionary                              _1____1
> >     
> >             Other  (Please specify):
> >
> >
> >
> >3.  FTP Use:  How often do you download files from FTP archive sites?
> >
> >        (Insert appropriate number beside each item)
> >
> >     1=Not at all                    4=About 2-3 times a month
> >     2=A few times                   5=Once a week
> >     3=About once a month            6=More than once a week
> >     
> >             Computers and Academic Freedom                  _1____1
> >             EASI                                            _1____1
> >             History                                         _1____1
> >             LIBSOFT                                         _1____1
> >             Lyric and Discography                           _1____1
> >             NASA                                            _3____1
> >             Online Libraries Directory                      _1____1
> >             Science Education                               _1____1
> >             SIMTEL20                                        _2____1
> >             SUMEX-AIM                                       _1____1
> >             U.S. Supreme Court Decisions                    _1____1
> >             Washington Uni. Public Domain Archives          _2____
> >                     
> >             Other (Please Specify):
> >
> >
> >
> >4.   Several navigational aids have been developed for the Internet.
> >     How often do you use these network guides?
> >
> >        (Insert appropriate number beside items below.)
> >
> >     1=Not at all                    4=About 2-3 times a month
> >     2=A few times                   5=Once a week
> >     3=About once a month            6=More than once a week
> >     
> >             Archie                                          _4____3
> >             Campus-wide Information Systems                 _2____1         
> >             Gopher                                          _2____1
> >             WAIS (Wide-area information servers)            _2____1
> >             WWW (WorldWideWeb)                              _6____1
> >             Veronica                                        _1____1
> >             HYTELNET                                        _2____
> >             Other (Please specify):
> >
> >
> >Personal experiences can be the most helpful to other users.  Please 
> comment on 
> >the following:
> >
> >5.   The importance of the Internet to your work?
> >
> >     Very important, both as a communication tool and as an information
> >     source.
> >
> >
> >
> >6.   Advantages the Internet offers over other resources?
> >
> >     (Relative) ease of use, fast turnaround, low cost, high bandwidth
> >
> >
> >7.   Barriers to using the Internet?
> >
> >     I feel that the access to Internet resources has been hampered by
> >     a lack of comprehensive tools. It is one thing to expect hardened
> >     programmers and scientists to fiddle with the intricacies of some
> >     utilities (ftp, X11 protocols, network addressing stuff, etc.)...
> >     quite another to hand these things to the sorts of people who
> >     would baulk at a UNIX command line (doctors, artists, perhaps
> >     historians, etc.).
> >
> >8.   Your most memorable use of the Internet?
> >
> >
> >
> >9  These questions will help us interpret the results of this study:
> >
> >     Title:  _Experimental Scientist_________________
> >     Affiliation:  __________________________________        
> >     Discipline:  _Electrical Engineering____________        
> >     Research Interest(s):_High speed wireless local area_____               
> >     networking_______________________________________________
> >
> >Please return the completed survey to: WMILHEIM@PSUGV.EDU
> >by September 3, 1993.
> >
> >If you would like a summary of the survey results, please place your
> >e-mail address here:  _kcousins@rp.csiro.au____________________.
> >
> >
> >            :) Thank you for taking the time to participate :)
> >
> >
> >
> ---------------------------------------------------------------------
> Prof. Marcos E. Palma M.     |  Eng. Marcos E. Palma M.
> Dpto.Procesos y Sistemas     |  Centro de Informatica y Comunicaciones
> Universidad Simon Bolivar    |  Universidad Simon Bolivar
> Valle de Sartenejas          |  Valle de Sartenejas
> CARACAS-VENEZUELA            |  CARACAS-VENEZUELA
> Apto. Postal 89000           |  Apto. Postal 89000
> ---------------------------------------------------------------------
> Phone:  (58) (2) 963-3022    |  e-mail: mpalma@usb.ve
>          Ext 3920, 3922      |
> FAX:    (58) (2) 93-8420     |
> ---------------------------------------------------------------------
 
From coates@spectro.jussieu.fr Fri Sep 10 10:31:28 +0200 1993
Date: Fri, 10 Sep 93 10:31:28 +0200
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu
Subject: Re: Internet Survey
 
Dear Litproggers,
 
> Your mailer is off!!  I received this completed survey -- but it was
> not mine.  I can only hope that MY completed survey is not being
> mailed around the world to somebody else.
> 
> Vince
> 
> 
> > 
> > >                              INTERNET SURVEY
> > >
> > >                     Adele F. Bane <AFB2@PSUVM.PSU.EDU>
> > >                 William D. Milheim <WMILHEIM@PSUGV.PSU.EDU>
> > >              The Pennsylvania State University at Great Valley
 
We had this discussion once before.  To summarise, such is the way LitProg
works that if you just *reply* to such a survey, a copy goes to LitProg as well.
And, well, we don't want to read your survey, do we??  ;-)  So, please, when
answering this or any other such thing that arrives in the future, please try
to check whether your mailer is sending the reply just to the author, or to
LitProg as well.  Otherwise, have fun!
						Cheers,
								Tony.
________________________________________________________________________________
A.B.Coates (Tony)
Laboratoire de Spectroscopie Hertzienne de l'ENS
Universite Pierre et Marie Curie
Case 74, 4 place Jussieu		Email:	   coates@spectro.jussieu.fr
F-75252 Paris CEDEX 05			Telephone: +33 1 44 27 44 09
France					Fax:	   +33 1 44 27 38 45
 
"J'ai mes opinions.  L'universite a ses opinions.  L'intersection de ces deux 
 ensembles est probablement vide."
"I have my opinions.  The university has its opinions.  The intersection of
 these two sets is probably empty."
________________________________________________________________________________
 
From Matthias Fri Sep 10 16:57:23 +0200 1993
Date: Fri, 10 Sep 1993 16:57:23 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, vote@dogwood.com
To: LitProg@shsu.edu
Subject: 2nd CFV: comp.programming.literate
 
[The above article contains Instructions on how to vote for or against the
 creation of a newsgroup mirrored to this mailing list. Note that your
 vote should be sent to vote@dogwood.com and *ONLY* to vote@dogwood.com.
 Due to the way mailing lists work, it is highly unlikely that simply replying
 to this article without manually editing the address will do the right
 thing -- Matthias]
 
                      SECOND CALL FOR VOTES
                (this is the last Call For Votes)
 
Unmoderated group comp.programming.literate
 
Newsgroups line:
comp.programming.literate	Literate programs and programming tools.
 
Votes must be received by 14 Sep 1993 23:59:59 GMT
 
SPECIAL NOTE: Due to technical problems, dogwood.com was off the net
from Thursday morning through Saturday afternoon. Some votes may have
been returned by your local system, please resend them!
 
This vote is being conducted by a neutral third party. For voting
questions only, contact dave@dogwood.com. For questions about the
proposed group, contact Matthias Neeracher <neeri@iis.ee.ethz.ch>.
 
A copy of this Call For Votes will be sent to LitProg@shsu.edu after
the original Call For Votes appears in news.announce.newgroups.
 
STANDARD VOTING INFO
 
You should send MAIL (posts to a group are invalid) to
      vote@dogwood.com
(just replying by MAIL to this message should work). Your mail
message should contain one and only one of the following statements:
 
      I vote YES on comp.programming.literate
or
      I vote NO on comp.programming.literate
 
You may add a comment, but anything other than a definite statement
involving the group name and "yes", "no", "for", or "against" on a
single line may be rejected by the automatic vote counting program.
If you later change your mind you may also use send in an "abstain"
vote in the same manner, using "abstain" in place of "yes" or "no".
 
Standard Guidelines for voting apply - one vote per person (not per
account). 100 more YES votes than NO votes and 2/3 of all votes being
YES are the requirements for group creation.
 
Votes will be acknowledged by email; a list of bounced acknowledgements
will be posted with the second Call For Votes. A mass acknowledgement
will NOT be posted. You may inquire about the status of your vote by
emailing the vote-taker (dave@dogwood.com).
 
After the results have been announced a complete list of the votes
will be posted in news.groups and will be mailed on request (email
requests to dave@dogwood.com).
 
The vote-taker can accept no responsibility for improperly configured
mailers.
 
CHARTER
 
Charter: A forum for the discussion of issues related
   to literate programming.
 
(1) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
(2) To discuss the merits of the currently existing literate
    programming tools.
 
(3) To discuss the design of new literate programming tools.
 
If a newsgroup is created, it will be mirrored to the existing mailing list
LitProg@shsu.edu.  For reference purposes, the newsgroup will be fully archived
by the host sponsoring the mailing list.
 
Background: What is Literate Programming?
 
Literate programming is a programming technique invented by Donald. E. Knuth.
A literate programming system can be characterized by the following properties:
 
 - The compilable program and the publishable documentation should be
   generated *automatically* from a *single* document.
 
 - The program can be presented in the order that is best for human
   understanding, regardless of any requirements of the programming
   language.
 
 - The program should be automatically indexed and cross-referenced.
 
Knuth's original system, called WEB, generated Pascal code and a TeX
documentation. Most tools relating to the TeX system have been written
using WEB, and the TeX and Metafont programs have been published in book
form.
 
Today, there are Literate Programming systems for a wide range of
programming languages and documentation systems. Specialized Literate
Programming tools have been written for Ada, Awk, C, C++, Fortran,
Modula-2, Modula-3, Pascal and Scheme, and generic tools exist that
can generate almost any programming language (including Perl and sh).
 
Documentation systems supported include TeX, Troff, and Word for
Windows.
 
"BOUNCED" ACKNOWLEDGEMENTS:
 
none
-- 
Dave Cornejo                                There is nothing so subtle
Dogwood Media                                           as the obvious
Fremont, California
 
From Thorbjoern Mon Sep 13 14:47:05 +0200 1993
Date: Mon, 13 Sep 1993 14:47:05 +0200 (MET DST)
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu, vote@dogwood.com
Subject: Re: 2nd CFV: comp.programming.literate
 
Matthias Ulrich Neeracher
| 
| [The above article contains Instructions on how to vote for or against the
|  creation of a newsgroup mirrored to this mailing list. Note that your
|  vote should be sent to vote@dogwood.com and *ONLY* to vote@dogwood.com.
|  Due to the way mailing lists work, it is highly unlikely that simply replying
|  to this article without manually editing the address will do the right
|  thing -- Matthias]
| 
|                       SECOND CALL FOR VOTES
|                 (this is the last Call For Votes)
|  
| Unmoderated group comp.programming.literate
|  
| Newsgroups line:
| comp.programming.literate	Literate programs and programming tools.
| 
| Votes must be received by 14 Sep 1993 23:59:59 GMT
| 
| SPECIAL NOTE: Due to technical problems, dogwood.com was off the net
| from Thursday morning through Saturday afternoon. Some votes may have
| been returned by your local system, please resend them!
| 
| This vote is being conducted by a neutral third party. For voting
| questions only, contact dave@dogwood.com. For questions about the
| proposed group, contact Matthias Neeracher <neeri@iis.ee.ethz.ch>.
| 
| A copy of this Call For Votes will be sent to LitProg@shsu.edu after
| the original Call For Votes appears in news.announce.newgroups.
| 
| 
| STANDARD VOTING INFO
| 
| You should send MAIL (posts to a group are invalid) to
|       vote@dogwood.com
| (just replying by MAIL to this message should work). Your mail
| message should contain one and only one of the following statements:
| 
|       I vote YES on comp.programming.literate
| or
|       I vote NO on comp.programming.literate
| 
| You may add a comment, but anything other than a definite statement
| involving the group name and "yes", "no", "for", or "against" on a
| single line may be rejected by the automatic vote counting program.
| If you later change your mind you may also use send in an "abstain"
| vote in the same manner, using "abstain" in place of "yes" or "no".
| 
| Standard Guidelines for voting apply - one vote per person (not per
| account). 100 more YES votes than NO votes and 2/3 of all votes being
| YES are the requirements for group creation.
| 
| Votes will be acknowledged by email; a list of bounced acknowledgements
| will be posted with the second Call For Votes. A mass acknowledgement
| will NOT be posted. You may inquire about the status of your vote by
| emailing the vote-taker (dave@dogwood.com).
| 
| After the results have been announced a complete list of the votes
| will be posted in news.groups and will be mailed on request (email
| requests to dave@dogwood.com).
| 
| The vote-taker can accept no responsibility for improperly configured
| mailers.
| 
| CHARTER
| 
| Charter: A forum for the discussion of issues related
|    to literate programming.
| 
| (1) To share ideas, questions, experiences, and knowledge about the
|     reading and writing of literate programs.
| 
| (2) To discuss the merits of the currently existing literate
|     programming tools.
| 
| (3) To discuss the design of new literate programming tools.
| 
| If a newsgroup is created, it will be mirrored to the existing mailing list
| LitProg@shsu.edu.  For reference purposes, the newsgroup will be fully archived
| by the host sponsoring the mailing list.
| 
| Background: What is Literate Programming?
| 
| Literate programming is a programming technique invented by Donald. E. Knuth.
| A literate programming system can be characterized by the following properties:
| 
|  - The compilable program and the publishable documentation should be
|    generated *automatically* from a *single* document.
| 
|  - The program can be presented in the order that is best for human
|    understanding, regardless of any requirements of the programming
|    language.
| 
|  - The program should be automatically indexed and cross-referenced.
| 
| Knuth's original system, called WEB, generated Pascal code and a TeX
| documentation. Most tools relating to the TeX system have been written
| using WEB, and the TeX and Metafont programs have been published in book
| form.
| 
| Today, there are Literate Programming systems for a wide range of
| programming languages and documentation systems. Specialized Literate
| Programming tools have been written for Ada, Awk, C, C++, Fortran,
| Modula-2, Modula-3, Pascal and Scheme, and generic tools exist that
| can generate almost any programming language (including Perl and sh).
| 
| Documentation systems supported include TeX, Troff, and Word for
| Windows.
| 
| "BOUNCED" ACKNOWLEDGEMENTS:
| 
| none
| -- 
| Dave Cornejo                                There is nothing so subtle
| Dogwood Media                                           as the obvious
| Fremont, California
| 
| 
 
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From bart@cs.tamu.edu Mon Sep 13 09:14:30 CDT 1993
Date: Mon, 13 Sep 93 09:14:30 CDT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: LitProg@shsu.edu, ravn@imada.ou.dk
Subject: Re: 2nd CFV: comp.programming.literate
 
       I vote YES on comp.programming.literate
 
From ravenek@chem.vu.nl Mon Sep 13 16:39:48 MET 1993
Date: Mon, 13 Sep 93 16:39:48 MET DST
From: ravenek@chem.vu.nl (Walter Ravenek)
Reply-To: LitProg@SHSU.edu, ravenek@CHEM.VU.NL
To: LitProg@SHSU.edu
Subject: Nuweb for Macintosh
 
I have received some requests for the changes for porting
nuweb to the Macintosh. Since the changes are so few, I
think it is overkill to give the full source code.
I am using the THINK C development system; the nuweb
version I am using is 0.85 (available from cs.rice.edu
in directory /public/preston).
 
The 3 changes required are:
 
- file main.c
- add after line 1:
#include <console.h>
 
- file main.c
- replace line 6:
  int arg = 1;
- by
  int arg;
  argc = ccommand(&argv);
  arg = 1;
 
- file output.c
- replace line 10:
      char *temp_name = tempnam(".", 0);
- by
      char *temp_name = tmpnam(NULL);
 
That's all.
Walter Ravenek
Dept. of Chemistry
Vrije Universiteit
De Boelelaan 1083
1081 HV Amsterdam
The Netherlands
e-mail: ravenek@chem.vu.nl
 
From Thorbjoern Mon Sep 13 18:01:19 +0200 1993
Date: Mon, 13 Sep 1993 18:01:19 +0200 (MET DST)
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu, ravn@imada.ou.dk
Subject: Re: 2nd CFV: comp.programming.literate
 
Thorbjoern Ravn Andersen
 
I apologize for my posting which included the CFV instructions.  My
intent was to "forget" the letter, but I mistyped.
 
Hopefully this hasn't been too much of an inconvenience
 
Regards,
 
-- 
Thorbj{\o}rn Andersen
ravn@imada.ou.dk
 
From dak@POOL.Informatik.RWTH-Aachen.DE Mon Sep 13 19:50:42 +0200 1993
Date: Mon, 13 Sep 93 19:50:42 +0200
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: litprog@shsu.edu
Subject: CWEB for LaTeX?
 
I guess I habe read about a webmac for LaTeX, but cannot seem to find
it. And, what is the newest version of CWEB? (Need C++, need LaTeX
support.)
Thanks,
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From marcus@x4u.desy.de Mon Sep 13 20:14:57 +0200 1993
Date: Mon, 13 Sep 93 20:14:57 +0200
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.edu, dak@POOL.Informatik.RWTH-Aachen.DE
Subject: CWEB for LaTeX?
 
>>>>> On Mon, 13 Sep 93 19:50:42 +0200, dak@POOL.Informatik.RWTH-Aachen.DE said:
 
|> I guess I habe read about a webmac for LaTeX, but cannot seem to find
|> it. And, what is the newest version of CWEB? (Need C++, need LaTeX
|> support.)
 
Do I understand correctly that we need a (minimal) FAQ for CWEB... :-)
 
->> CWEB 3.0 (labrea.stanford.edu:/pub/cweb/),
and it has C++ cupport. 
 
->> cweb-sty-0.4 from ftp.th-darmstadt.de:/programming/literate-programming/
 
But, again, FWEB has both as well.
 
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de> BITNET:<I02MSP@DHHDESY3>  DECnet:<13313::SPEH>
 
From db@big_ben Mon Sep 13 14:56:00 EDT 1993
Date: Mon, 13 Sep 93 14:56:00 EDT
From: db@big_ben (Derek Bradley)
Reply-To: LitProg@SHSU.edu, psych!big_ben!db@PSYCH.TORONTO.EDU
To: LitProg@shsu.edu
Subject: Re: 2nd CFV: comp.programming.literate
 
       I vote YES on comp.programming.literate
 
From beezer@ups.edu Mon Sep 13 11:54:26 -0800 1993
Date: Mon, 13 Sep 1993 11:54:26 -0800
From: beezer@ups.edu (Rob Beezer)
Reply-To: LitProg@SHSU.edu, beezer@UPS.EDU
To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
Subject: Re: CWEB for LaTeX?
 
C++ and LaTeX both work with FWEB without doing anything special.  You need
only avoid the \\ of LaTeX.  If you need the \\, a command line switch will
make it possible.
 
Rob Beezer
 
>I guess I habe read about a webmac for LaTeX, but cannot seem to find
>it. And, what is the newest version of CWEB? (Need C++, need LaTeX
>support.)
>Thanks,
> David Kastrup        dak@pool.informatik.rwth-aachen.de          
> Tel: +49-241-72419 Fax: +49-241-79502
> Goethestr. 20, D-52064 Aachen
 
From wald@theory.lcs.mit.edu Mon Sep 13 16:21:51 EDT 1993
Date: Mon, 13 Sep 93 16:21:51 EDT
From: wald@theory.lcs.mit.edu (David Wald)
Reply-To: LitProg@SHSU.edu, wald@THEORY.LCS.MIT.EDU
To: LitProg@SHSU.edu
Subject: Re: 2nd CFV: comp.programming.literate
 
This obviously bears repeating.  From Matthias's original posting of
the call for votes to this list:
 
>[The above article contains Instructions on how to vote for or against
> the creation of a newsgroup mirrored to this mailing list. Note that
> your vote should be sent to vote@dogwood.com and *ONLY* to
> vote@dogwood.com.  Due to the way mailing lists work, it is highly
> unlikely that simply replying to this article without manually
> editing the address will do the right thing -- Matthias]
 
By the rules for USENET votes, votes which are not sent to
vote@dogwood.com cannot be counted.  Please be careful to check the
addresses when you mail your votes.
 
-David
 
From Matthias Mon Sep 13 23:15:12 +0200 1993
Date: Mon, 13 Sep 1993 23:15:12 +0200
From: Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.edu, psych!big_ben!db@PSYCH.TORONTO.EDU
Subject: Re: 2nd CFV: comp.programming.literate
 
In message <9309131856.AA18051@big_ben.toronto.edu> you write:
>
>       I vote YES on comp.programming.literate
 
Thanks, but votes to the mailing list cannot be counted. Please
send your vote to vote@dogwood.com.
 
Matthias
 
-----
Matthias Neeracher                                  neeri@iis.ee.ethz.ch
  "And that's why I am going to turn this world upside down, and make
   of it a fire so *bright* that someone real will notice"
                                -- Vernor Vinge, _Tatja Grimm's World_
 
From Zdenek Tue Sep 14 11:09:24 MET 1993
Date: Tue, 14 Sep 93 11:09:24 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
Subject: Re: CWEB for LaTeX?
 
On Mon, 13 Sep 93 19:50:42 +0200 <dak@POOL.Informatik.RWTH-Aachen.DE> said:
>I guess I habe read about a webmac for LaTeX, but cannot seem to find
>it. And, what is the newest version of CWEB? (Need C++, need LaTeX
>support.)
>Thanks,
> David Kastrup        dak@pool.informatik.rwth-aachen.de
> Tel: +49-241-72419 Fax: +49-241-79502
> Goethestr. 20, D-52064 Aachen
 
The latest version of CWEB is 3.0 and it supports also C++. Joachim Schrod
made a style ``cweb.sty'' which enables the use of CWEB with LaTeX.
Everything is available from Darmstadt. If I remember it well, the site is
ftp.th-darmstadt.de, directory:
pub/programming/literate-programming/c.c++
 
Regards
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From Zdenek Tue Sep 14 11:15:14 MET 1993
Date: Tue, 14 Sep 93 11:15:14 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, wald@THEORY.LCS.MIT.EDU
Subject: Re: 2nd CFV: comp.programming.literate
 
On Mon, 13 Sep 93 16:21:51 EDT <wald@theory.lcs.mit.edu> said:
>This obviously bears repeating.  From Matthias's original posting of
>the call for votes to this list:
>
>>[The above article contains Instructions on how to vote for or against
>> the creation of a newsgroup mirrored to this mailing list. Note that
>> your vote should be sent to vote@dogwood.com and *ONLY* to
>> vote@dogwood.com.  Due to the way mailing lists work, it is highly
>> unlikely that simply replying to this article without manually
>> editing the address will do the right thing -- Matthias]
>
Our system has the command ``reply from'' for this purpose. Something
similar may work for you - ask your system manager.
 
>By the rules for USENET votes, votes which are not sent to
>vote@dogwood.com cannot be counted.  Please be careful to check the
>addresses when you mail your votes.
>
>-David
 
Sorry for bothering all of you with remarks not connected with LP.
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From ZABOROWSKY_BENJAMIN_R@Lilly.com Tue Sep 14 18:03:44 +0000 1993
Date: Tue, 14 Sep 1993 18:03:44 +0000 (GMT)
From: ZABOROWSKY_BENJAMIN_R@Lilly.com
Reply-To: LitProg@SHSU.edu, ZABOROWSKY_BENJAMIN_R@LILLY.COM
To: litprog@shsu.edu
Subject: nuweb for c-shell scripts
 
Has anyone used nuweb to write c-shell scripts?  I find my self putting
a lot of comments inline with the script code to explain not only the
script, but to add additional information that is necessary to understand
and appreciate why the script exists in the first place.  I can envision
a document with many, many lines of prose for each line of "code" (100:1 ?).
 
The information has to exist (should exist!) some where, so why not in the
same file as the script?
 
Any guidance, suggestions, or examples will be appreciated.  Thanks,
 
--Ben Zaborowsky      benz@lilly.com
 
From Lee Wed Sep 15 9:58:33 EDT 1993
Date: Wed, 15 Sep 93 9:58:33 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, ZABOROWSKY_BENJAMIN_R@lilly.com
Subject: Re: nuweb for c-shell scripts
 
Ben Zaborowsky asks:
 
> Has anyone used nuweb to write c-shell scripts?  I find my self putting
> a lot of comments inline with the script code to explain not only the
> script, but to add additional information that is necessary to understand
> and appreciate why the script exists in the first place.  I can envision
> a document with many, many lines of prose for each line of "code" (100:1 ?).
> 
> The information has to exist (should exist!) some where, so why not in the
> same file as the script?
> 
> Any guidance, suggestions, or examples will be appreciated.  Thanks,
 
I don't know about nuweb, but I do know that noweb can be used (and has
been) for shell scripts, and just about everything else.
 
		-- Lee
 
From ae1181t@stnfor.ae.ge.com Wed Sep 15 12:18:47 -0400 1993
Date: Wed, 15 Sep 1993 12:18:47 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: nuweb for c-shell scripts
 
Yes I have used nuweb for all kinds of scripts. You just have to run nuweb
first to obtain the script (from the nuweb file which contains the docs, etc).
nuweb has one page info sheet (only 3-4 commands to know), 
and is easy to learn.
 
Osman
 
From Manuel Wed Sep 15 17:32:39 BST 1993
Date: Wed, 15 Sep 93 17:32:39 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@shsu.edu, ZABOROWSKY_BENJAMIN_R@lilly.com, LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: nuweb for c-shell scripts
 
Lee Wittenberg writes:
>
> Ben Zaborowsky asks:
> 
> > Has anyone used nuweb to write c-shell scripts?  I find my self putting
> > a lot of comments inline with the script code to explain not only the
> > script, but to add additional information that is necessary to understand
> > and appreciate why the script exists in the first place.  I can envision
> > a document with many, many lines of prose for each line of "code" (100:1 ?).
> > 
> > The information has to exist (should exist!) some where, so why not in the
> > same file as the script?
> > 
> > Any guidance, suggestions, or examples will be appreciated.  Thanks,
> 
> I don't know about nuweb, but I do know that noweb can be used (and has
> been) for shell scripts, and just about everything else.
 
nuweb is language independent and can be used with any programming 
language. I'm currently using it with a multi-tasking programming language
and an assembler language for hardware devices. It makes it also easy to 
combine several threats of different languages, and it looks pretty good
on its documentation with LaTeX (nuweb weaves its source to a LaTeX document).
 
Anyway I don't see any problems to tangle c-shell scripts, but I don't
have an example here at the moment :-)
 
Have fun,
Manuel Carriba (M.Carriba@dcs.shef.ac.uk)
 
From Manuel Wed Sep 15 17:32:39 BST 1993
Date: Wed, 15 Sep 93 17:32:39 BST
From: Manuel Carriba <M.Carriba@dcs.sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@DCS.SHEFFIELD.AC.UK
To: LitProg@shsu.edu, ZABOROWSKY_BENJAMIN_R@lilly.com, LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: nuweb for c-shell scripts
 
Lee Wittenberg writes:
>
> Ben Zaborowsky asks:
> 
> > Has anyone used nuweb to write c-shell scripts?  I find my self putting
> > a lot of comments inline with the script code to explain not only the
> > script, but to add additional information that is necessary to understand
> > and appreciate why the script exists in the first place.  I can envision
> > a document with many, many lines of prose for each line of "code" (100:1 ?).
> > 
> > The information has to exist (should exist!) some where, so why not in the
> > same file as the script?
> > 
> > Any guidance, suggestions, or examples will be appreciated.  Thanks,
> 
> I don't know about nuweb, but I do know that noweb can be used (and has
> been) for shell scripts, and just about everything else.
 
nuweb is language independent and can be used with any programming 
language. I'm currently using it with a multi-tasking programming language
and an assembler language for hardware devices. It makes it also easy to 
combine several threats of different languages, and it looks pretty good
on its documentation with LaTeX (nuweb weaves its source to a LaTeX document).
 
Anyway I don't see any problems to tangle c-shell scripts, but I don't
have an example here at the moment :-)
 
Have fun,
Manuel Carriba (M.Carriba@dcs.shef.ac.uk)
 
From Andrew Wed Sep 15 12:18:34 -0700 1993
Date: Wed, 15 Sep 1993 12:18:34 -0700 (PDT)
From: Andrew Tucker <a_tucker@paul.spu.edu>
Reply-To: LitProg@SHSU.edu, a_tucker@PAUL.SPU.EDU
To: LitProg@SHSU.EDU
Subject: Knuth's original WEB report
 
I am trying to obtain Knuth's original WEB report (Stanford TR 980) form
Sept. 1983.  I wrote to Stanford and they say it is only available on
microfiche.  Does anyone have a copy of this report that they could
photocopy and mail me?  I would really appreciate it.
 
BTW, I do know that I could probably get a very similar thing by printing
out a current copy of WEB but, for reasons I won't go into, I do need/want
Knuth's original.  Thanks.
 
/* Andrew */
 
"C makes it easy to shoot yourself in the foot, C++ makes it harder,
but when you do, it blows away your whole leg" -- Bjarne Stroustrup
 
From preston@cs.rice.edu Thu Sep 16 09:58:26 CDT 1993
Date: Thu, 16 Sep 93 09:58:26 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, ZABOROWSKY_BENJAMIN_R@lilly.com
Subject: Re:  nuweb for c-shell scripts
 
We've used nuweb for shell scripts, make files, C, Fortran, and ML.
You ought to be able to use it for any other language you can dream up.
Same goes for noweb and FunnelWeb.
 
Preston
 
From Matthias Thu Sep 16 22:49:24 +0200 1993
Date: Thu, 16 Sep 1993 22:49:24 +0200
From: Matthias Neeracher <neeri@iis.ee.ethz.ch>
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@shsu.edu
Subject: RESULT: comp.programming.literate passes 354:31
 
[I'm very happy about this result and from the vote result, I assume that
 I'm not the only one :-) Unless anybody posts a serious objection to 
 news.groups within the next days, comp.programming.literate will be 
 created in about 5 days. For bandwidth reasons, I omitted the full list
 of votes. Those interested may retrieve it by ftp from ftp.uu.net in the
 file usenet/news.announce.newgroups/comp/comp.programming.literate or by
 asking me for a copy by email. Hope to see you soon on USENET -- Matthias]
 
comp.programming.literate group vote results - 385 votes
 
 Yes   No : 2/3? >100? : Pass? : Group
---- ---- : ---- ----- : ----- : -------------------------------------------
 354   31 :  Yes   Yes :   Yes : comp.programming.literate
 
CHARTER
 
Charter: A forum for the discussion of issues related
   to literate programming.
 
(1) To share ideas, questions, experiences, and knowledge about the
    reading and writing of literate programs.
 
(2) To discuss the merits of the currently existing literate
    programming tools.
 
(3) To discuss the design of new literate programming tools.
 
If a newsgroup is created, it will be mirrored to the existing mailing list
LitProg@shsu.edu.  For reference purposes, the newsgroup will be fully archived
by the host sponsoring the mailing list.
 
[Full text available by ftp or email request to me]
 
Matthias
 
-----
Matthias Neeracher                                      neeri@iis.ee.ethz.ch
  "Paranotions, which designate constructs, may now contain metanotions and
   ``hypernotions'' have been introduced in order to designate protonotions"
                -- A. van Wijngaarden et al., _ALGOL 68 Revised Report_
 
From Trevor Sat Sep 18 17:24:03 GMT 1993
Date: Sat, 18 Sep 93 17:24:03 GMT
From: Trevor Jenkins <tfj@apusapus.demon.co.uk>
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: MS-DOS cweb v3 executable wanted
 
I've looked through the cweb directories of both pip.shsu.edu and tex.ac.uk
and cannot find any (MS-DOS) executables for cweb v3. I can find the
sources okay (at least on pip) but I'm after the EXEs. Anyone know of an
FTP site that has said thingies?
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From Hans-Hermann Sun Sep 19 17:27:09 MEZ 1993
Date: Sun, 19 Sep 93 17:27:09 MEZ
From: Hans-Hermann Bode <HHBODE@dosuni1.rz.Uni-Osnabrueck.DE>
Reply-To: LitProg@SHSU.edu, HHBODE@DOSUNI1.RZ.UNI-OSNABRUECK.DE
To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
Subject: Re: MS-DOS cweb v3 executable wanted
 
Trevor Jenkins wrote:
 
>I've looked through the cweb directories of both pip.shsu.edu and tex.ac.uk
>and cannot find any (MS-DOS) executables for cweb v3. I can find the
>sources okay (at least on pip) but I'm after the EXEs. Anyone know of an
>FTP site that has said thingies?
 
Get the file pub/msdos/tex/web/cwb30p8c.zip from ftp.rz.uni-osnabrueck.de.
On pip.shsu.edu it's in the directory tex-archive/web/c_cpp/cwb30p8c. On
tex.ac.uk I couldn't find it, too.
 
Incidentally, I'm sorry for the somewhat cryptic identifier, but I thought
it should contain the version numbers both of the original CWEB and of the
port and---since it's dedicated for MS-DOS---it should be a legal MS-DOS
file name.
 
Hermann
 
From Lee Mon Sep 20 12:40:49 EDT 1993
Date: Mon, 20 Sep 93 12:40:49 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, a_tucker@paul.spu.edu
Subject: Re: Knuth's original WEB report
 
Andrew Tucker(?) asks:
> 
> I am trying to obtain Knuth's original WEB report (Stanford TR 980) form
> Sept. 1983.  I wrote to Stanford and they say it is only available on
> microfiche.  Does anyone have a copy of this report that they could
> photocopy and mail me?  I would really appreciate it.
 
I believe that the report is available via anonymous ftp from
labrea.stanford.edu with the original WEB distribution.
Unfortunately, I don't know the directory, but it can't be hard to
find, since I found it once, myself :-).  If you need a hardcopy, I
have a copy somewhere I could xerox and send to you via snail mail, if
you'll send me your address.
 
		-- Lee
 
From David Mon Sep 20 09:46:00 PDT 1993
Date: Mon, 20 Sep 93 09:46:00 PDT
From: David Thompson <dthompson@coe2.coe.ttu.edu>
Reply-To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU
To: LitProg <litprog@shsu.edu>
Subject: FW: request for signature lines...
 
I apologize right up front and have put on my flame-proof suit (so flame 
away about being off-topic), but is it out of line for me to ask posters to 
please include an email address in their signature line?  In the wisdom of 
my network administrator, all internet headers are stripped before mail is 
forwarded to our individual mailboxes.  (Yes, I'm using MSMail on my pc and 
it's an all-or-none setting.  Instead of all users receiving the header, 
none of us do.  Go figure.)  I often would like to respond privately to a 
message read here, but cannot because I have no address.  So, rather than 
clutter the mailing list, I hold my tongue (so to speak).  So, if it isn't 
too much trouble, will posters please attach an email address as part of 
their signature?
 
 -=d
 
David B. Thompson                 internet: wqdbt@ttacs1.ttu.edu
Civil Engineering Dept.           internet: dthompson@coe2.coe.ttu.edu
Texas Tech University             internet: thompson@sun1.coe.ttu.edu
P.O. Box 41023
Lubbock, Texas 79409-1023
USA
 
From Lee Mon Sep 20 13:12:46 EDT 1993
Date: Mon, 20 Sep 93 13:12:46 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, tfj@apusapus.demon.co.uk
Subject: Re: MS-DOS cweb v3 executable wanted
 
Trevor Jenkins asks:
 
> I've looked through the cweb directories of both pip.shsu.edu and tex.ac.uk
> and cannot find any (MS-DOS) executables for cweb v3. I can find the
> sources okay (at least on pip) but I'm after the EXEs. Anyone know of an
> FTP site that has said thingies?
 
The official distribution at labrea.stanford.edu has a set of change
files for compiling under the Borland compilers (and should be easy to
modify for other PC compilers), but I don't think there are any DOS
executables floating around on the net.
 
I have a set of executables that I compiled (using said change files).
If you like, contact me directly, and we'll see about sending you
copies.
 
		-- Lee
 
From George Mon Sep 20 14:19:53 CST 1993
Date: Mon, 20 Sep 1993 14:19:53 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: litprog@SHSU.edu
Subject: About signing off LitProg
 
               !!!PLEASE READ THIS ADMINISTRIVIA POSTING!!!
 
Given that the comp.programming.literate newsgroup has been (or, more
precisely, will soon be) created and given that I am sure that more than a
few of you will elect to drop your mail subscription to LitProg in favor of
the newsgroup, please accept this message as merely pre-emptory in nature.
 
It is my understanding that the newsgroup will come into existence sometime
within the next week or two.  I have already made arrangements so that as
soon as the newsgroup is created at my gateway host site, the bidirectional
gateway between LitProg and comp.programming.literate will be made
operational. There {\em may} be a brief window when duality is not present,
but it will be brief (if at all).
 
To avoid misdirected (read "junk", "noise", "impertinent", "dumb user
error", or whatever) posts to either the list or the newsgroup in your
attempts to unsubscribe, please send a MAIL message to:
                 LISTSERV@SHSU.BITNET (LISTSERV@SHSU.edu)
                                 -- or --
                         LitProg-Request@SHSU.edu
stating in the body of the MAIL message:
 SIGNOFF LitProg
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % Please do NOT send the SIGNOFF message to the list address,  %
     % LitProg@SHSU.BITNET (LitProg@SHSU.edu), as this is the       %
     % redistribution address for the list.  All posting to LitProg %
     % are distributed to its worldwide list of subscribers, as     %
     % well as to the comp.programming.literate newsgroup, once it  %
     % is activated.                                                %
     %                                                              %
     % Please note that the LISTSERV which serves LitProg is MAIL   %
     % oriented only and is not conventional interactive LISTSERV.  %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
If, for some reason, LISTSERV cannot handle your request automagically, it
will be forwarded to me (promise!!) for my manual attention.  Also, any
mail enqueued to LitProg prior to your signing off which is still enqueued
for you will continue to be delivered until the queue clears (generally,
you should receive nothing more within three days (if at all), give or
take, once you receive confirmation that you have been removed).
 
If you have any questions, are in need of specific assistance, etc., please
contact {\em me} directly rather than the list address.  I will make every
honest effort to migrate users out of LitProg as can be made.  My main
concern, though, is that you not get hot and bothered and waste valuable
bandwidth posting administrative requests to the list nor that you report
to everyone that automatic handling didn't occur here in the middle of the
night (my time) and you "can't get off the list" or other diatribe.
 
As always, I thank each of you for your interest in our services and retain
my open offer to discuss any and all ideas you might have for enhancing
them.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
LitProg data: Announced    -- July 19, 1992
              Subscribers  -- September 20, 1993: 423
 
From craig@gpu.utcc.utoronto.ca Tue Sep 21 20:33:37 GMT 1993
Date: Tue, 21 Sep 1993 20:33:37 GMT
From: craig@gpu.utcc.utoronto.ca (Craig Hubley)
Reply-To: LitProg@SHSU.edu, craig@GPU.UTCC.UTORONTO.CA
To: LitProg@SHSU.EDU
Subject: What does literate programming mean to you?
 
Of course I am familiar with the original idea but to me it seems
like an evocative term so I wonder what other definitions it suggests.
 
To me, "literate programming" implies that all information relevant to
the construction of the system is embedded within it.  Ideally this would
work in a hypertext fashion, so that I can easily trace requirements, find 
descriptions of limitations where they are imposed (i.e. in design, or in a
particular implementation).  It makes it simple to answer questions posed at
any point in the code like "why is this here?" or "what is this doing?" or
"what else is affected by this?".
 
In other words, perhaps to me the most important thing about literate
programming is the glossary and the index... :)
 
Craig
-- 
  Craig Hubley -- Consultants in object-oriented technology & techniques, --
  Craig Hubley & Associates -- user interface design & user productivity  --
  craig@gpu.utcs.Utoronto.CA   UUNET!utai!utgpu!craig   craig@utorgpu.BITNET
  Toronto 416-969-2826 24hr, 416-469-4825, 463-2284 FAX   Boston 617-322-2481  
 
From freeland@harlequin.com Tue Sep 21 22:08:16 GMT 1993
Date: Tue, 21 Sep 1993 22:08:16 GMT
From: freeland@harlequin.com (Freeland Abbott)
Reply-To: LitProg@SHSU.edu, freeland@HARLEQUIN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <CDq142.M07@gpu.utcc.utoronto.ca> craig@gpu.utcc.utoronto.ca (Craig Hubley) writes:
 
   In other words, perhaps to me the most important thing about literate
   programming is the glossary and the index... :)
 
You forgot the guarantee.  ``What guarantee?'' you ask... I mean the
guarantee that the information is up-to-date and therefore likely to be
correct; it's the difficultly of providing that which makes the job hard.
--
 
-fka3
 
From marcus@x4u.desy.de Tue Sep 21 22:35:08 GMT 1993
Date: Tue, 21 Sep 1993 22:35:08 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Literate Programming on the World Wide Web
 
-----------------------------------------------------------------------------
* Literate Programming on the World Wide Web
-----------------------------------------------------------------------------
   FYI, there is a wealth of information on Literate Programming,
   the art of structured programming and documentation [especially
   using WEB-like systems with TeX formatting] available on the
   World Wide Web [WWW], a distributed HyperText system, a network
   of documents connected by links which can be activated electronically.
   Examples for LitProg environments are WEB for Pascal (DEK), CWEB for C/C++
   (Levy/Knuth), FWEB for C/C++/Fortran/ratfor/TeX (Krommes)...and many more.
-----------------------------------------------------------------------------
* How to get to the Web
-----------------------------------------------------------------------------
   If you have a WWW browser up and running, try going to
 
		        http://info.desy.de:80/
 
   (this brings you to the DESY home page), and look for "User Documents"
   in the panel which appears. The precise URL is
 
	   http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
 
   If you have no clue what WWW is, you can go over the Internet with
 
        	telnet info.cern.ch
 
   which brings you to the WWW Home Page at CERN. You are now using the
   simple line mode browser. To move around the Web, enter the numbers
   given after an item. To go to the Literate Programming documents, enter
 
	go http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
 
   [If you haven't telnet either, see below.]
   This is what you should see now:
-----------------------------------------------------------------------------
* What you will see here
-----------------------------------------------------------------------------
 
                           LITERATE PROGRAMMING
 
   Recent changes [1]--Mail additions to this list to <marcus@x4u.desy.de>
   __________________________________________________________________
 
   Getting Started[2]      A first look into Literate Programming with
                          WEB
 
   Editing[3]             GNU Emacs mode for WEB programming
 
   Tools[4]               Common, freely available Literate Programming
                         environments
 
   Examples[5]            Literate Programming archives and selected
                         examples
 
   LitProg Library[6]     George D. Greenwade's Literate Programming
                         Library at Niord.shsu.edu
 
   LITPROG Discussion List[7]
                          Information on the Literate Programming
                         Mailing List. Now, there is also
                         comp.literate.programming
 
   FAQs[8]                Lists of Frequently Asked Questions for WEB
                         systems
 
   Further Reading        Nelson Beebe's Literate Programming
                         bibliography at ftp.math.utah.edu in directory
                         /pub/tex/bib[9] (files litprog.*)
 
   HyperLitProg[10]        Literate Programming using HyperText[11]
                         Techniques
 
   OO-LitProg[12]         Thoughts on Object-Oriented[13] Literate
                         Programming
 
 [[Now you can continue climbing down the documentation tree by
   entering numbers 1-13 and follow your own interests]]
-----------------------------------------------------------------------------
* More on Browsing the Web
-----------------------------------------------------------------------------
   The by far nicest way of "browsing" through WWW uses the X-Terminal
   based tool "NCSA Mosaic". Binaries for many platforms (ready for use)
   and sources are available via anonymous FTP from
   ftp.ncsa.uiuc.edu in directory Web/xmosaic.
     The general FTP repository for browser software is info.cern.ch
  (including a hypertext browser/editor for NeXTStep 3.0)
     If you cannot go through TELNET, you can still retrieve WWW
   documents by e-mail: send a mail to listserv@info.cern.ch with a
   line in it saying just
				HELP
   to get back detailed instructions. Your mail system must have a
   mail gateway to the internet mail.
-----------------------------------------------------------------------------
* Contact for Further Information
-----------------------------------------------------------------------------
   Please feel free to contact me for questions, suggestions and further
   contributions, or just to tell me whether you found this information
   useful in any way. 
     For questions related to WWW, consult the WWW-FAQ: available via
   anonymous FTP from rtfm.mit.edu in directory 
   pub/usenet/news.answers/www/faq, or on WWW at URL
   http://www.vuw.ac.nz:80/who/Nathan.Torkington/ideas/www-faq.html
   Enjoy.                                                          Sept 22-93 
 
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de> BITNET:<I02MSP@DHHDESY3>  DECnet:<13313::SPEH>
 
From eugene@wilbur.nas.nasa.gov Tue Sep 21 22:39:33 GMT 1993
Date: Tue, 21 Sep 1993 22:39:33 GMT
From: eugene@wilbur.nas.nasa.gov (Eugene N. Miya)
Reply-To: LitProg@SHSU.edu, eugene@WILBUR.NAS.NASA.GOV
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
I just visited the newly moved Comp. Lit Bookshop now at the Apple R&D Center.
I picked up DEK's book based on a discussion we had over dinner a couple
months ago.
 
Literate Programming means (to me) Don's book on the subject.
It's a "Fabrege egg" to quote Doug McIlroy in my Favorite Programming Pearl
with Don, Doug, and Jon Bentley.  It's an unfinished Art of Computer
Programming with a highly acclaimed text processing system which makes
documents look like assembly language.  It's The Errors of TeX.
It lacks the empirical study of Fortran programs.  It avoids the hype
of topics like AI and virtual reality.  It requires an informed, well-read
readership.
 
--eugene miya, NASA Ames Research Center, eugene@orville.nas.nasa.gov
  Associate Editor, Software and Publication Reviews
  Scientific Programming
  {uunet,mailrus,other gateways}!ames!eugene
Seeking Books to buy:	Bongard, Pattern Recognition
			3 down 1 to go.
 
From evan@hplerk.hpl.hp.com Wed Sep 22 01:39:36 GMT 1993
Date: Wed, 22 Sep 1993 01:39:36 GMT
From: evan@hplerk.hpl.hp.com (Evan Kirshenbaum)
Reply-To: LitProg@SHSU.edu, kirshenbaum@hpl.hp.com
To: LitProg@SHSU.EDU
Subject: Tools for multi(programming)lingual literate programming?
 
I would very much like to experiment with WEB-style (or otherwise)
literate programming.  Unfortunately, my programs tend to be written
in several languages at once.  As an example, my most likely first
candidate is a second generation of a document formatting tool, and
will include:
 
   o The formatter, written in C++,
 
   o A set of PostScript functions used by the PostScript code output
     by the formatter,
 
   o Emacs-lisp functions to allow easy specification of the formatter
     input,
 
   o A (default) configuration file in a format to be specified by me,
 
   o A man page written in (ugh!) nroff, and
 
   o (probably) a few perl scripts
 
One of the attractions of programming in expositional order is the
ability to have a section on, say, line breaking, in which I can
include the code to process relevant arguments, the code to break the
lines, the PostScript support routines that deal with continuation
lines, and the man page entry documenting these arguments.  As it
stands now, the code is distributed throughout several files.
 
I know that there are WEB-like tools that allow you to customize the
programming language, but does anyone know of a tool in which each
different code fragments can be in different languages?
 
Evan Kirshenbaum		       +------------------------------------
    HP Laboratories		       | It is a popular delusion that the
    3500 Deer Creek Road, Building 26U | government wastes vast amounts of
    Palo Alto, CA  94304	       | money through inefficiency and sloth.
				       | Enormous effort and elaborate
    kirshenbaum@hpl.hp.com	       | planning are required to waste this
    (415)857-7572		       | much money
				       |                   P.J. O'Rourke
 
From cgra@btma74.nohost.nodomain Wed Sep 22 01:39:36 GMT 1993
Date: Wed, 22 Sep 1993 01:39:36 GMT
From: cgra@btma74.nohost.nodomain (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: Subscription to mailing list LitProg
 
I am a little confused by this posting --- are comp.programming.literate
subscribers being invited to join the LitProg list, or is the newsgroup
a mutation of the list, or what?  Or maybe this LitProg document is
intended to serve as a FAQ for comp.prog.lit?  (Are abbreviations
allowed on this group or are they ``considered illiterate'')?
 
In any case it's good to see this group --- I first read about DEK's work
in this area ooh, must be nearly ten years ago, and I'm still living in
an illiterate environment.
 
Anecdote: a few years ago the company introduced a rule that each (CHILL)
procedure should be accompanied by an SDL.pr representation (a verbal
flowchart).  The programmers demanded, and got, a tool which would auto-
matically generate the SDLs from the code, thereby ensuring that the SDLs
were always up-to-date. :]
__________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
   Ignore my broken mailer - the addresses above are the only truth
__________________________________________________________________________
Alle menschen sind Auslaender.                              Fast ueberall.
 
From tsl1@cornell.edu Wed Sep 22 10:28:03 +0600 1993
Date: Wed, 22 Sep 1993 10:28:03 +0600
From: tsl1@cornell.edu (Tim Larkin)
Reply-To: LitProg@SHSU.edu, tsl1@CORNELL.EDU
To: LitProg@SHSU.edu, craig@gpu.utcc.utoronto.ca
Subject: Re: What does literate programming mean to you?
 
>Of course I am familiar with the original idea but to me it seems
>like an evocative term so I wonder what other definitions it suggests.
 
To me, literate programming means writing a program text for a human reader
rather than for a compiler. Hypertext, index, glossary, pretty printing,
these are tactics, not to be confused with the goal. A literate
programmer's first priority isn't to be clever or efficient: his first
priority is to explain the problem and the solution so that a human reader
will understand them and will enjoy learning about them. As Horace
counselled, to entertain and to instruct.
 
Tim Larkin
tsl1@cornell.edu
607-255-7008
 
From Dominique Wed Sep 22 11:38:10 +0200 1993
Date: Wed, 22 Sep 93 11:38:10 +0200
From: Dominique Dumont / GND <domi@petrus.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@PETRUS.GRENOBLE.HP.COM
To: LitProg@SHSU.edu, cgra@se.alcbel.be
Subject: Re: Subscription to mailing list LitProg
 
In message <2006@se.alcbel.be> you write:
> 
> Anecdote: a few years ago the company introduced a rule that each (CHILL)
> procedure should be accompanied by an SDL.pr representation (a verbal
> flowchart).  The programmers demanded, and got, a tool which would auto-
> matically generate the SDLs from the code, thereby ensuring that the SDLs
> were always up-to-date. :]
 
Shouldn't it be the other way ? From SDL to code .
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From krommes@theory.pppl.gov Wed Sep 22 08:00:47 -0400 1993
Date: Wed, 22 Sep 1993 08:00:47 -0400
From: krommes@theory.pppl.gov (John Krommes)
Reply-To: LitProg@SHSU.edu, Krommes@Princeton.EDU
To: LitProg@SHSU.EDU
Subject: Re: Tools for multi(programming)lingual literate programming?
 
Evan Kirshenbaum writes:
 
>> I know that there are WEB-like tools that allow you to customize the
>> programming language, but does anyone know of a tool in which each
>> different code fragments can be in different languages?
 
  FWEB features multiple language support, and one can easily switch between
languages within a single web source file.  Presently the supported
languages are
 
	C
	C++
	Fortran-77 and Fortran-90
	Ratfor-77 and Ratfor-90
	TeX
 
I am completing work on a language-independent mode.  If you are very
interested in that feature, please correspond with me privately; the speed
with which that project is completed will depend on the number of requests.
 
  FWEB is available from
 
	lyman.pppl.gov:/pub/fweb
 
A new release with a few bug fixes and substantially improved LaTeX support
should be available sometime in the next two weeks.
 
--
--- John                      (Mail to krommes@princeton.edu is forwarded to
                              krommes@lyman.pppl.gov == 198.35.4.70.  
krommes@princeton.edu         Ftp files to/from ftp.pppl.gov, NOT princeton.edu
                              or lyman.pppl.gov.)
 
From ae1181t@stnfor.ae.ge.com Wed Sep 22 08:00:47 -0400 1993
Date: Wed, 22 Sep 1993 08:00:47 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, kirshenbaum@hpl.hp.com
Subject: Re: Tools for multi(programming)lingual literate programming?
 
Try nuweb, noweb. The first is one executable. noweb consists of a number of
programs. I think for a beginner nuweb is easier to learn (just a few commands
). In either case you need to know a little LaTex or TeX. Yeah, Funnelweb is
also another choice but a few more commands (an TeX only I think), and
wit ha much bigger manual than the either of the first two. I think all
can or already are ported to quite a few platforms including DOS.
Hope this helps.
Osman
 
From marcus@x4u.desy.de Wed Sep 22 12:40:58 GMT 1993
Date: Wed, 22 Sep 1993 12:40:58 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: Tools for multi(programming)lingual literate programming?
 
[This is copied from World Wide Web pages on Literate Programming--
 I'd like to get more doc on litprog systems here. The easiest way
 to get a document, is to look up (from the number) the doc REFERENCE
 at the end, and send mail to listserv@info.cern.ch with the message
	send REFERENCE
 e.g. "send file://desy.de/pub/www/projects/Announce/LitProg.txt" for info
 on accessing these pages -- Marcus Speh]
 
--------------------------------------------------------------------
From: postmaster@nxoc01.cern.ch (Mail robot)
To: marcus
Subject: Re: send http://info.desy.de:80/pub/www/projects/LitProg/Tools.html
Date: Wed, 22 Sep 93 13:59:29 MET DST
 
The requested document follows. Linked documents may be obtained
using SEND <address> where the addresses are listed at the end.
________________________________________________________________________
                                      List of Literate Programming Tools
                   LIST OF LITERATE PROGRAMMING TOOLS
 
   Have a look at the LitProg Library[1] for a more complete overview
   and sources.
 
  CLiP (PostScript[2], plain[3])
                          A universal (language-independent) literate
                         programming tool, currently ported to VAX/VMS
                         and MS-DOS only. See also: CLiP Style[4] and
                         Manual[5] (PostScript)
 
   CWEB[6]                WEB System of Structured Documentation for C
                         and C++. References [v3.0, all PostScript]:
                         User's Manual[7], common[8], cweave[9],
                         ctangle[10]
 
   FunnelWEB[11]          Features and comparison with FWEB, by P. Lyon
                         (original message to LitProg[12] mailing list).
 
   FWEB[13]               WEB System of Structured Software Design and
                         Documentation for Fortran-77, Fortran-90,
                         Ratfor, C, C++ and TeX. References [v1.30, all
                         PostScript]: fwebmac[14] [40p.], User's Manual
                         [body[15], index[16], 200 p.], guide[17] [20p.]
 
   Glasgow LitProg Tools
                          A GNU Texinfo-based suite of literate
                         programming tools from Glasgow, at
                         ftp.dcs.glasgow.ac.uk:/pub/haskell/glasgow/.
                         Here is the documentation[18] [PostScript[19]].
 
   NOWEB (plain[20], PostScript[21])
                          "Literate-Programming Tools Need Not Be
                         Complex", by N. Ramsey.
 
   NUWEB[22] (PostScript)
                          Yet another simple Literate Programming tool
                         for arbitrary programming languages, with LaTeX
                         as formatter. Command Summary[23] (ps)
 
   WinWordWEB[24]         A WORDWEB (HyperText literate programming[25])
 
                                            Last updated August 31, 1993
 
------------------------------------------------------------------------
 
     References from this document:-
 
[1]  gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.LITPROG%5d
[2]  http://info.desy.de:80/pub/faq/web/clip/clip_ann.ps
[3]  http://info.desy.de:80/gnu/ftp/pub/faq/web/clip/clip_ann.plain
[4]  http://info.desy.de:80/pub/faq/web/clip/clip_ann.ps
[5]  file://sun01.info.wau.nl/clip/ms_dos/clip_man.ps
[6]  http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/CWEB/FULL
[7]  http://info.desy.de:80/pub/web/DOCUMENTS/cweb/cwebman.ps
[8]  http://info.desy.de:80/pub/web/DOCUMENTS/cweb/common.ps
[9]  http://info.desy.de:80/pub/web/DOCUMENTS/cweave.ps
[10]  http://info.desy.de:80/pub/web/DOCUMENTS/cweb/ctangle.ps
[11]  http://info.desy.de:80/pub/faq/web/funnelWEB/funnelWEB.html 
[12]  http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg/Mailing.html
[13]  http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/FWEB/FULL
[14]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/macros.ps
[15]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/manual.ps
[16]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/index.ps
[17]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/guide.ps
[18]  http://info.desy.de:80/pub/www/projects/LitProg/glasgow/top.html
[19]  http://info.desy.de:80/gnu/doc/litprog/lit2x-0.16-literate.ps
[20]  http://info.desy.de:80/gnu/ftp/pub/faq/web/noweb/noweb.html
[21]  http://info.desy.de:80/pub/faq/web/noweb/noweb.ps
[22]  http://info.desy.de:80/pub/web/nuweb/nuweb.ps
[23]  file://ftp.shsu.edu/tex-archive/web/nuweb/nuweb-summary.ps
[24]  gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.FILESERV.WORDWEB%5d
[25]  http://info.desy.de:80/pub/www/projects/LitProg/HTML.html
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de> BITNET:<I02MSP@DHHDESY3>  DECnet:<13313::SPEH>
 
From prechelt@i41s18.ira.uka.de Wed Sep 22 13:58:25 GMT 1993
Date: Wed, 22 Sep 1993 13:58:25 GMT
From: prechelt@i41s18.ira.uka.de (Lutz Prechelt)
Reply-To: LitProg@SHSU.edu, prechelt@I41S18.IRA.UKA.DE
To: LitProg@SHSU.EDU
Subject: Re: Tools for multi(programming)lingual literate programming?
 
In article <9309221200.AA06614@stnfor.ae.ge.com>, ae1181t@stnfor.ae.ge.com
 (Osman F Buyukisik) writes:
|> ). In either case you need to know a little LaTex or TeX. Yeah, Funnelweb is
|> also another choice but a few more commands (an TeX only I think), and
|> wit ha much bigger manual than the either of the first two.
 
You can use FunnelWeb with LaTex, too.
Just say
  \def\bye{\relax}
at the beginning of your FunnelWeb document and there you go.
(To use 11pt or 12pt style, you have to redefine a few commands)
 
FunnelWeb is quite powerful (e.g. parameterized macros).
The manual is really very large, but that does not mean that you cannot
get started within 10 minutes with FunnelWeb: the basics are quite
similar to the way the simple Webs like NoWeb work.
 
  Lutz
 
-- 
Lutz Prechelt   (email: prechelt@ira.uka.de)            | Whenever you 
Institut fuer Programmstrukturen und Datenorganisation  | complicate things,
Universitaet Karlsruhe;  76128 Karlsruhe;  Germany      | they get
(Voice: ++49/721/608-4068, FAX: ++49/721/694092)        | less simple.
 
From marcus@x4u.desy.de Wed Sep 22 13:58:25 GMT 1993
Date: Wed, 22 Sep 1993 13:58:25 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: FWEB (v1.30) Info Hypertextified
 
I have 'hypertextified' John Krommes' FWEB Info (new with version
v1.30a from June 1993). The URL on the World Wide Web is:
 
  http://info.desy.de:80/pub/www/projects/LitProg/info/top.html
 
FAQ:
  I have (finally) rebuilt FWEB on my SGI-Iris5 and
  am working on the update of the FWEB FAQ for v1.30a.
 
[For info on how to get there, retrieve via anonymous FTP
 ftp.desy.de:/pub/www/projects/Announce/LitProg.txt ]
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de> BITNET:<I02MSP@DHHDESY3>  DECnet:<13313::SPEH>
 
From George Wed Sep 22 08:32:38 CST 1993
Date: Wed, 22 Sep 1993 08:32:38 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: litprog@SHSU.edu
Subject: For the news distribution..........
 
Unbelievable.  In just the first few hours of its existence,
comp.programming.literate (c.p.l) has been at least as active as LitProg
when it first fired up and virtually all of the posts are from "newbies"
(defined as not prior LitProg subscribers).
 
As owner of LitProg, please allow me to intervene on a few topics which
have already arisen.
 
On 22 Sep 93 06:31:27 GMT, cgra@btma74.nohost.nodomain (Chris Gray) asked
about the "Subscription to mailing list LitProg" post:
> I am a little confused by this posting --- are comp.programming.literate
> subscribers being invited to join the LitProg list, or is the newsgroup a
> mutation of the list, or what?  Or maybe this LitProg document is intended
> to serve as a FAQ for comp.prog.lit?  (Are abbreviations allowed on this
> group or are they ``considered illiterate'')?
 
LitProg was begun July 19, 1992, as the sole (as far as anyone involved in
its initiation knew, anyway) source of discussion focused exclusively on
literate programming.  I don't believe that anyone involved expected that
the list would grow as it did, nor that its subscribership or activity
would get anywhere close to where it did as quickly as it did.  To give
credit where it's due, Cameron Smith <cameron@symcom.math.uiuc.edu> was the
original proponent of the list, followed closely by Don Hosek
<DHOSEK@HMCVAX.CLAREMONT.EDU>.  The core group (who are too numerous to
list, but are very appreciated) created one of the better lists, IMO, on
the nets.
 
Due to the growth of LitProg and a few side discussions on the list,
Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch> posted the RFD and CFV for
c.p.l, which is completely gatewayed with LitProg.  Anything posted to
LitProg@SHSU.edu (LitProg@SHSU.BITNET) will get to c.p.l (so those who wish
to use news in lieu of mail may do so) and anything posted to c.p.l will
get to LitProg (so those who wish to use mail instead of news or because
they lack access to news may do so).
 
Next, the thread of "What does literate programming mean to you?" has
already arisen (which I sort of expected).  Please allow me to point out to
news users (especially those with no prior contact with LitProg!) that this
has been thrashed out previously on LitProg (not that it doesn't deserve
rethrashing -- the *concept* of literate programing may be one of the more
important items in gaining wider acceptance to literate programming as a
real life production vehicle for programmers).
 
For reference, LitProg is fully archived (and I may soon begin a complete
Gopher-based index-searchable archive -- this will require a little more
time than I have at present, but I have the tools available to do so).  You
can retrieve the LitProg archives via ftp from Niord.SHSU.edu (192.92.15.8)
in the directory [FILESERV.LITPROG] (Niord is a VMS machine).  The files
LITPROG.yyyy-mm are the archives, with "yyyy" being the year and "mm" the
month (i.e., this post will be included in LITPROG.1993-09 since it's now
September, 1993).
 
Next, Marcus Speh has already pointed out his World Wide Web literate
programing library at info.desy.de (Marcus, please check your directory
specifications for the files at SHSU, BTW -- I just tried and failed to get
back here and my server logs indicate it is due to a bad request at your
end).  In addition to the WWW resource Marcus provides, Niord.SHSU.edu runs
a Gopher server on port 70.  I just moved a "Literate Programming Library"
entry to the top-level menu there (it is still included in the "TeX-related
Materials" menu for those of you who are used to getting to it from there).
This gopher burrow at SHSU includes the archives of LitProg, access to the
web/ directory on SHSU's host of the Comprehensive TeX Archive Network
(CTAN), and access to most literate programming tools available from SHSU
(and if you know of one or more I've omitted, please let me know and I'll
get it in place).  I just added an HTML link to Marcus' host so those of
you with gopher clients which are HTML compatible can get there in one jump
from Niord's Gopher server.  I plan on working with Joachim Schrod (who
you'll come to know as a valuable resource, if you don't already) on
getting a parallel literate programming library arranged from and between
his host in Darmstadt (Germany) and one of mine here (and make every effort
to make it gopherable from here, as well).  In other words, there is
already a wealth of information and resources available for your use (and
further development!).
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From norman@bellcore.com Wed Sep 22 12:27:45 -0400 1993
Date: Wed, 22 Sep 93 12:27:45 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, kirshenbaum@hpl.hp.com
Subject: Re: Tools for multi(programming)lingual literate programming?
 
> I would very much like to experiment with WEB-style (or otherwise)
> literate programming.  Unfortunately, my programs tend to be written
> in several languages at once... does anyone know of a tool in which each
> different code fragments can be in different languages?
 
noweb was designed precisely for this purpose (and for simplicity).  A
stable version is available via ftp from ftp.cs.princeton.edu:pub or
from bellcore.com:pub/norman.  An alpha test version is available from
me by email.  The alpha version adds many improvements to the LaTeX
output, language-independent identifier cross-reference and indexing,
and bugs.  Lots of bugs.
 
Norman Ramsey
norman@bellcore.com
 
From Lee Wed Sep 22 12:35:36 EDT 1993
Date: Wed, 22 Sep 93 12:35:36 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, kirshenbaum@hpl.hp.com
Subject: Re: Tools for multi(programming)lingual literate programming?
 
Evan Kirshenbaum writes:
 
> I would very much like to experiment with WEB-style (or otherwise)
> literate programming.  Unfortunately, my programs tend to be written
> in several languages at once.  As an example, my most likely first
> candidate is a second generation of a document formatting tool, and
> will include:
> 
>    o The formatter, written in C++,
> 
>    o A set of PostScript functions used by the PostScript code output
>      by the formatter,
>      
>    o Emacs-lisp functions to allow easy specification of the formatter
>      input,
> 
>    o A (default) configuration file in a format to be specified by me,
> 
>    o A man page written in (ugh!) nroff, and
> 
>    o (probably) a few perl scripts
> 
> One of the attractions of programming in expositional order is the
> ability to have a section on, say, line breaking, in which I can
> include the code to process relevant arguments, the code to break the
> lines, the PostScript support routines that deal with continuation
> lines, and the man page entry documenting these arguments.  As it
> stands now, the code is distributed throughout several files.
> 
> I know that there are WEB-like tools that allow you to customize the
> programming language, but does anyone know of a tool in which each
> different code fragments can be in different languages?
 
noweb can definitely handle the job.  I believe that nuweb and
FunnelWeb will also do the trick, as will CLiP.  I, myself, have
written a single noweb web (awkward phrase, but I couldn't think of a
better one) that contains a C program and a DOS batch file that
invoked it.  Jon Krom's cross indexer for noweb contains a Unix shell
script, a DOS batch file, and an Awk script all in one web.
 
The main point here is that what you want is eminently doable with
already existing tools.
 
		-- Lee
		   leew@pilot.njin.net
 
From hzhu@liverpool.ac.uk Wed Sep 22 16:52:00 GMT 1993
Date: Wed, 22 Sep 1993 16:52:00 GMT
From: hzhu@liverpool.ac.uk (Mr. H. Zhu)
Reply-To: LitProg@SHSU.edu, hzhu@LIVERPOOL.AC.UK
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <FREELAND.93Sep21220816@scoupe.harlequin.com>, freeland@harlequin.com (Freeland Abbott) writes:
> 
> In article <CDq142.M07@gpu.utcc.utoronto.ca> craig@gpu.utcc.utoronto.ca (Craig Hubley) writes:
> 
>    In other words, perhaps to me the most important thing about literate
>    programming is the glossary and the index... :)
> 
> 
> You forgot the guarantee.  ``What guarantee?'' you ask... I mean the
> guarantee that the information is up-to-date and therefore likely to be
> correct; it's the difficultly of providing that which makes the job hard.
> --
 
The difficulty arises from the fact that computers and humans read completely
different parts of a literate program.  Following are some ideas of how
this can be avoided.
 
At present we have 'pure programing languages' like C, 'pure text formatting
languages' like TeX.  Their combination is the so-called literate programs.
However, we also have many computer algebra software, (also called symbolic
computation).  If they are added to the programs, the results can be
far more robust against change.  Here's a sample C function.
 
---------------
void f(float a)
{
				//requires: a>0
	float b, c, d;
	b = sqrt(a);		//guaranttees: b>0
	scanf("%f", c);		//requires: c>0
	d = c+1/c;		//guaranttees: d>2
				//invariant: a
}
--------------
This is what an "ideal compiler" should say:
 
assertion at line 3 (a>0) passed to linker.
assertion at line 6 (c>0) changed to run time checking.
assertion at line 7 (d>2) not guarantteed. Best possible: d>=2.
 
_______________
 
In this way, the compiler reads the program and assertions, and make
sure that they agree with each other.  The typesetting mechinism 
makes the assertions part of the *text*, so that humans can read them
easily.  Of cause this idea comes from the programming language Eiffel,
but what I would like is a full symbolic computation mechanism.
 
It will be really great if there is a universal mechanism by which
programing language, symbolic computation software, and text
formatting software can be combined, even if they are designed without
regard to each other.
 
Sounds like a dream?
 
-- 
Huaiyu Zhu			hzhu@liverpool.ac.uk
Dept. of Stat. & Comp. Math., University of Liverpool, L69 3BX, UK
 
From koopman@sgi84.ctc.com Wed Sep 22 16:34:21 -0400 1993
Date: Wed, 22 Sep 93 16:34:21 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, tsl1@CORNELL.EDU
Subject: What does literate programming mean to you?
 
Tim Larkin wrote to LitProg (a.k.a. comp.programming.literate):
>To me, literate programming means writing a program text for a human reader
>rather than for a compiler. 
 
Some of the webs written for literate programming tools do not appear
to be enhanced expositions of the principles underlying the behavior
of the program (while including the code scraps).  Such leading,
literate program authors could be considered hypocrit infidels not
practicing what they seem to preach (false names are used to protect
the innocent).  A comprehensive and well structured presentation
(printed document, hypertext, other) that compiles to realize the
description is what I expect from literate programming.
 
Techniques that may benefit web reading and writing and have not been
discussed (my wish list) include:
 
An outline mode - with multiple levels of exposition.
 
A hypertext tree allowing for "outlines" for different points of view
(audiences).
 
Chart, figure and graphics support capabilities (perhaps, SGML).
{ OK, TeX does this - but it is 'non-trivial' with TeX or LaTeX ]
Also, audio and other presentation media inclusion.
 
The web tools I have seen allow the literate programmer to improve (or
demote) modularity, localization and other principles of software
design.  The structure of the web (hopefully, with "meta-comments")
depicts the implementation of these design principles in its totality.
Maintainability (and reusability) can also be improved (or reduced)
with a web design.  These latter principle seems to be the ones which
literate programming can improve most.  Providing short, relatively
cryptic titles for code scraps and providing no discussion on the
algorithm and implementation which the code realizes is not only
opposed to what I expect from literate programming but is not literate
programming, at all, IMNSHO.
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
A technology's benefit must outweigh the risk in dollars & sense.
 
From freeland@harlequin.com Wed Sep 22 20:53:51 GMT 1993
Date: Wed, 22 Sep 1993 20:53:51 GMT
From: freeland@harlequin.com (Freeland Abbott)
Reply-To: LitProg@SHSU.edu, freeland@HARLEQUIN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <CDrLIq.LAH@liverpool.ac.uk> hzhu@liverpool.ac.uk (Mr. H. Zhu) writes:
 
   In article <FREELAND.93Sep21220816@scoupe.harlequin.com>, freeland@harlequin.com (Freeland Abbott) [hey---that's me!] writes:
 
   > You forgot the guarantee.  ``What guarantee?'' you ask... I mean the
   > guarantee that the information is up-to-date and therefore likely to be
   > correct; it's the difficultly of providing that which makes the job hard.
 
   The difficulty arises from the fact that computers and humans read
   completely different parts of a literate program.  Following are some
   ideas of how this can be avoided.
 
   [intervening stuff deleted]
 
   ---------------
   void f(float a)
   {
				   //requires: a>0
	   float b, c, d;
	   b = sqrt(a);		//guaranttees: b>0
	   scanf("%f", c);		//requires: c>0
	   d = c+1/c;		//guaranttees: d>2
				   //invariant: a
   }
   --------------
   This is what an "ideal compiler" should say:
 
   assertion at line 3 (a>0) passed to linker.
   assertion at line 6 (c>0) changed to run time checking.
   assertion at line 7 (d>2) not guarantteed. Best possible: d>=2.
   _______________
 
Well, first of all, *my* ideal compiler would complain about the syntax
error on line 6, where you want &c.  ;-)  
 
Um... although I agree that this is part of the difficulty, I don't think
it's all of it, and perhaps not even the hardest part... although your
hypothetical compiler's figuring out not only that line 7 isn't guaranteed,
but also that d >= 2 is the best approximation, is mighty impressive.  But
the difficulty also comes from the fact that computers have difficulty
grasping high-order concepts, and *that* is what people are usually
interested in.  So, although your example is fine as far as it goes, I'd
rather be able to make assertions like ``the queue contains no unmarked
events'' or ``none of these objects are mapped to the screen'' or the like.
I can look at your line 7 and see (with only a very little thought) that
yes, d must be at least 2.0.  It's harder to look at an arbitrary function
call (with arbitrary subcalls) and know what that will guarantee, in
semantic as well as mathematical terms.
 
Having programmatic checking of the mathematical effects is certainly
computable, of course---if, in your example, d were a global variable, for
example, a program could certainly know that a call to f() would guarantee
that the global d was at least 2.0 after the call.  But imagine that the
number were instead added to some sort of (dynamically allocated, globally
scoped) list which recorded c+1/c for a number of inputs c, which would
then be manipulated.  Various mathematic constraints could be proven,
certainly, but they would tend not to capture the notion ``d, which is at
least 2.0, is in the list after a call to f()''.... it'd be more like ``the
value field of the struct node pointed to by listHead is at least 2.0, and
the next field of the struct is either null or non-null; if it is non-null,
the value field of the struct node pointed to by listHead is at least 2.0,
and the next fiend of the struct is either...,'' which would continue
infinitely.
 
So, how do you catch the semantics of a singly-linked list in a scheme like
this?  The constraint I'd like to get out of that version of f() is ``after
a call to f(), the list will not be empty, the first element of it will be
the sum of most recent input and its multiplicative inverse, and the rest
of it will be the previous list.''
 
   Sounds like a dream?
 
Depends: the not-very-useful mathematical form doesn't, although it sounds
hard (especially relative to its benefit to me).  The more useful semantic
form, yes, sounds dream-like.
--
 
-fka3
 
From bks@s27w007.pswfs.gov Wed Sep 22 20:53:51 GMT 1993
Date: Wed, 22 Sep 1993 20:53:51 GMT
From: bks@s27w007.pswfs.gov (Bradley K. Sherman)
Reply-To: LitProg@SHSU.edu, bks@S27W007.PSWFS.GOV
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
The literate programmer writes code that I, another literate
programmer, can understand.   Polished in her style, she
can anticipate the areas of the code most likely to be
altered and provides comments in tight grammatical English.
 
The literate programmer knows that the code is the essence of
the program.  The commentary, code and whitespace are in
harmony.  He is obsessed with making good lexical choices.
 
The literate programmer knows that copyright protection of
source code is absurd; knowing the right approach to
the problem --and which problem to approach-- is everything.
 
The literate programmer is a poet not a novelist.
 
    --bks
 
p.s. Please freely substitute for English in the first paragraph,
per locale.
 
-- 
Bradley K. Sherman               P.O. Box 245                    
Computer Scientist               Berkeley, CA, 94701
Dendrome Project                 510-559-6437 FAX: 510-559-6440  
Institute of Forest Genetics     Internet: bks@s27w007.pswfs.gov
 
From shf@netcom.com Thu Sep 23 07:24:21 GMT 1993
Date: Thu, 23 Sep 1993 07:24:21 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
+-- In article <>, freeland@harlequin.com (Freeland Abbott) writes:
| You forgot the guarantee.  ``What guarantee?'' you ask... I mean the
| guarantee that the information is up-to-date and therefore likely to be
| correct; it's the difficultly of providing that which makes the job hard.
 
I say phooey.  "What guarantee?" indeed.  What guarantee do I have for
any given random piece of code that it operates correctly?  I have the
word only of the original programmer, and their reputation which I must
evaluate and trust or not.  In a world of literate programmers, keeping
the information up to date and accurate is part of the job.  Innacurate
commentary is unprofessional.  Dammit.
-- 
		Stuart Ferguson		(shf@netcom.com)
			"Oh Dear Lord -- the canary exploded!"
 
From d.love@dl.ac.uk Thu Sep 23 07:24:21 GMT 1993
Date: Thu, 23 Sep 1993 07:24:21 GMT
From: d.love@dl.ac.uk (Dave Love)
Reply-To: LitProg@SHSU.edu, d.love@DL.AC.UK
To: LitProg@SHSU.EDU
Subject: emacs tags technology for web-like systems?
 
Does anyone have anything to allow the use of tags files in emacs with
web-like systems (I'm interested in noweb, but I guess anything else
would adapt straightforwardly).  What I have in mind is treating code
modules/chunks or whatever you call them on the same basis as
identifiers.
 
From mclay@cfdlab.ae.utexas.edu Thu Sep 23 07:24:21 GMT 1993
Date: Thu, 23 Sep 1993 07:24:21 GMT
From: mclay@cfdlab.ae.utexas.edu (Robert T. McLay)
Reply-To: LitProg@SHSU.edu, mclay@CFDLAB.AE.UTEXAS.EDU
To: LitProg@SHSU.EDU
Subject: Big Programs & Separate files & Make & Incremental Compilation & Web
 
I would like to start a discussion about web's and Big projects.  I
freely admit to be a complete newbie when it comes to webs but my
reading seems to say that programs in web tend to be much bigger that
you might typically see in a unix style development.  I believe that
tex program is stored in 6-10 files.
 
What I want to know is how well web's work when the programs are say
20,000 to 100,000 lines of code.  If  I make a small change in the
program I  would certainly like not to have to recompile all of the
code.
 
Now I freely admit that a program in web will be less error prone, so
I might need less re-compiling but I still like quick re-compiles
possible with make.
 
So one way to answer my question is which of the webs handle a program
spread over many files and are easily coupled with make.
 
Another question is how well have people handled several people
working on the same project w/ web.
 
--
 
______________________________________________________________________________
Robert McLay                   | Kayak Rules of Life:
Manager CFD Lab                |   a) lose altitude
Dept ASE-EM                    |   b) Surf waves and holes.
University of Texas at Austin  |   c) Do enders.
WRW 111                        |
Austin, TX 78712               |
                               |
mclay@cfdlab.ae.utexas.edu     |
 
From hubert@masi.ibp.fr Thu Sep 23 07:24:21 GMT 1993
Date: Thu, 23 Sep 1993 07:24:21 GMT
From: hubert@masi.ibp.fr (Stephane HUBERT (DEA IARFA))
Reply-To: LitProg@SHSU.edu, hubert@MASI.IBP.FR
To: LitProg@SHSU.EDU
Subject: Literate knowledges
 
 I am, personnaly, interested in the knowledges-based systems. I think that if we
want that a system handle some knowledges, this knowledges must be given in a
literate form. This condition is essential for systems whixh wants to act on the
knowledges (ie learn, classify, ...).
 An other point of view is th systems which observes themself. If such a system
don't have acces to a literate form of he, he can't know what he is doing.
 
 I think that literate programming is essential to be able to do some
intelligent systems.
 
Stephane HUBERT (student in meta-knowledge area )
e-mail: hubert@ecoledoc.ibp.fr
 
From foster@jed.cs.uidaho.edu Thu Sep 23 11:11:48 GMT 1993
Date: Thu, 23 Sep 1993 11:11:48 GMT
From: foster@jed.cs.uidaho.edu ()
Reply-To: LitProg@SHSU.edu, foster@JED.CS.UIDAHO.EDU
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <shfCDspwL.1D6@netcom.com> shf@netcom.com (Stuart Ferguson) writes:
>
>I say phooey.  "What guarantee?" indeed.  What guarantee do I have for
>any given random piece of code that it operates correctly?  I have the
>word only of the original programmer, and their reputation which I must
>evaluate and trust or not.  In a world of literate programmers, keeping
>the information up to date and accurate is part of the job.  Innacurate
>commentary is unprofessional.  Dammit.
 
This led me to an interesting thought (quick, bring an ice pack!)...
 
Why not include a formal proof that the code has been verified, along with
an informal description of what it does (you know, traditional
unprofessional documentation)?  A good untangler could strip the proof, if
it exists, and run it through a theorem verifier in order to certify it.
Now you need only check the English documentation against the assumptions in
the verification proof.
 
Before everyone gives the usual complaints against formal verification, let
me remind you that 1) they don't matter, we're discussing literate
programming and a proof should be part of this if it exists; 2) most of
those arguments are obsolete; 3) sometimes there is no alternative to
formally verified code (ever tried to debug a pacemaker?).
 
-- 
James A. Foster                           foster@cs.uidaho.edu
Laboratory for Applied Logic              Dept. of Computer Science
University of Idaho  
 
From marcus@x4u.desy.de Thu Sep 23 11:11:48 GMT 1993
Date: Thu, 23 Sep 1993 11:11:48 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
Bradley> The literate programmer writes code that I, another literate
Bradley> programmer, can understand.   Polished in her style, she
Bradley> can anticipate the areas of the code most likely to be
Bradley> altered and provides comments in tight grammatical English.
 
Bradley> The literate programmer knows that the code is the essence of
Bradley> the program.  The commentary, code and whitespace are in
Bradley> harmony.  He is obsessed with making good lexical choices.
 
Bradley> The literate programmer is a poet not a novelist.
 
*Very* nice account on literate programming, I like that!
 
Bradley> The literate programmer knows that copyright protection of
Bradley> source code is absurd; knowing the right approach to
Bradley> the problem --and which problem to approach-- is everything.
 
Agreed, cum grano salis: I do put a copyright under the GNU "copyleft"
which I think is suitable also for literate programs. This copyleft is
transferred to Global Network Academy, Inc. (Usenet University), an
educational institution, thus not violating "Bradley's Law" :-)
 
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u.desy.de Thu Sep 23 11:27:40 GMT 1993
Date: Thu, 23 Sep 1993 11:27:40 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Can the LitProg Archives be made searchable?
 
The LitProg mailing list is less than one year old -- and nevertheless
discussions have touched upon many topics which are being revived 
in this newsgroup now---I feel it would be a pity to leave the huge
archives at SHSU unnoticed, with the lot of good postings buried
there.
  Soon enough, we'll have postings from newcomers
"Where is the FAQ for this group" - given that many questions 
[e.g. "What does LitProg mean to you?", "Experiences with large
projects?" etc.] are non-technical but rather philosophical, a FAQ
may not be the best way of presentation. Also, I don't really see
anyone searching the volumes by hand and putting the archive numbers
together...therefore: can we think of a way to make the LitProg
archives (the Subject headers, maybe) searchable? I have seen this
with gopher and WWW. For WWW, see
 
 http://info.cern.ch/hypertext/WWW/Administration/Mailing/Overview.html
 
for an example (archive of the WWW mailing lists).
 
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From preston@cs.rice.edu Thu Sep 23 11:41:17 CDT 1993
Date: Thu, 23 Sep 93 11:41:17 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, koopman@ctc.com
Subject: Re:  What does literate programming mean to you?
 
koopman@ctc.com writes:
>Some of the webs written for literate programming tools do not appear
>to be enhanced expositions of the principles underlying the behavior
>of the program (while including the code scraps).  Such leading,
>literate program authors could be considered hypocrit infidels not
>practicing what they seem to preach
 
Hmm.  Certainly nuweb (I wrote it) is worse in this respect than any
other tools I've examined.  So why did I write such an illiterate program?
 
I have to consider it incomplete.  It'll get more complete as I spend more
effort on it.  In the meantime, I (and others) are able to use it without
worrying about whether I've finished describing it all.  It's just a tool,
not an end in itself.  A hammer doesn't need a dissertation attached to
be useful.
 
Preston Briggs
 
From norman@bellcore.com Thu Sep 23 12:58:20 -0400 1993
Date: Thu, 23 Sep 93 12:58:20 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, koopman@ctc.com
Subject: Re: What does literate programming mean to you?
 
> Some of the webs written for literate programming tools do not appear
> to be enhanced expositions of the principles underlying the behavior
> of the program (while including the code scraps).  Such leading,
> literate program authors could be considered hypocrit infidels not
> practicing what they seem to preach (false names are used to protect
> the innocent).  
 
I confess that my tool, noweb, is at best of poor quality when
considered as a literate program.  In mitigation I offer these two
observations:
  i)  Making a good-quality literate program is 3-4 times as expensive
      as just making a working program using literate-programming tools.
  ii) I have been unable to develop really good literate programs
      without peer review.
I tolerate my ugly ``literate'' programs because in my work a program
is seldom an artifact of the first importance.   Far more often the
paper is what matters (and what gets polished).
 
Norman Ramsey
 
From mayoff@austin.ibm.com Thu Sep 23 17:42:58 GMT 1993
Date: Thu, 23 Sep 1993 17:42:58 GMT
From: mayoff@austin.ibm.com (Rob Mayoff)
Reply-To: LitProg@SHSU.edu, mayoff@AUSTIN.IBM.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <CDrLIq.LAH@liverpool.ac.uk> hzhu@liverpool.ac.uk (Mr. H. Zhu) writes:
> 	scanf("%f", c);		//requires: c>0
> 	d = c+1/c;		//guaranttees: d>2
 
> This is what an "ideal compiler" should say:
 
> assertion at line 6 (c>0) changed to run time checking.
> assertion at line 7 (d>2) not guarantteed. Best possible: d>=2.
 
I think you mean
 
assertion at line 7 (d>2) not guaranteed. Best possible: d>=0.
 
Consider the case of c == 2 (which makes d = 1.5) .
 
And to be reliable your compiler must not only be able to solve systems
of inequalities, but it must know some numerical methods, too.
Consider:
 
	double a, b;
	int i;
 
	// case one
	a = 7e-1;		// guarantees: a=0.7
	scanf("%d", &i);
	b = (double)i - a;	// guarantees: b<i
 
	// case two
	a = 7e-100;		// guarantees: a=7e-100
	scanf("%d", &i);
	b = (double)i - a;	// guarantees: b<i
 
In the first case, the second guarantee is certainly true.  b will
always be less than i.  In the second case, the second guarantee will
not be true on any machine I've ever used!  Even a 128-bit double does
not have enough precision to store 1 - 7e-100 differently than 1.0.
But algebraically, if a>0 then i-a < i for *any* i.  So what's a
compiler (or really, a compiler writer) to do?
 
Of course, you might allow this kind of guarantee:
 
	// case three
	a = 7e-100;		// guarantees: a=7e-100
	scanf("%d", &i);	// guarantees: i=floor(i) && i=ceil(i)
	b = (double)i - a;	// guarantees: b<i
 
Now the compiler could see that the best guarantee it can make about b
is b<=i.  But of course now your inequality solver is getting pretty
darn complex.  And of course now the programmer sometimes has to do a
lot of work to get his guarantees and requires correct.
 
From steve@crc.ricoh.COM Thu Sep 23 17:42:58 GMT 1993
Date: Thu, 23 Sep 1993 17:42:58 GMT
From: steve@crc.ricoh.COM (Stephen R. Savitzky)
Reply-To: LitProg@SHSU.edu, steve@CRC.RICOH.COM
To: LitProg@SHSU.EDU
Subject: Readable programs -- an alternative to Web, Tangle and Weave
 
My approach to literate programming is to write programs that can be
read, rather than the Web approach of writing programs that can be
processed to make them readable.  I do this because I rarely, if ever,
get a listing; I much prefer to edit on the screen.  I want my
programs to be as readable as possible when I do.
 
My coding standards for readable programs are:
 
o Comments that describe a single code unit such as a declaration or
  statement *follow* that code unit, indented as if they were a
  statement continuation.  (Comments describing a C++ class
  or C structure declaration follow the first line.)
 
  This has the effect of making the declaration a header for the
  comment rather than the other way around. 
 
o Therefore, comments need contain no information that is already in
  the code.  This avoids problems with comments and code getting out
  of sync.  In particular, comments must not contain either a
  rephrasing of the declaration they describe, or any cross-reference
  information that is derivable from the code.
 
o Comments describing or summarizing a group of code units *preceed*
  the members of that group.
 
I *do* have a (TeX-based) typesetter for C++ programs that uses a set
of very simple rules; the typesetter is only used for header files,
and the rules produce something that can be used as a programmer's
manual for the modules described by the header.
 
The typesetting rules are:
 
o Code is printed in a monospaced font to preserve its formatting.
 
o Comments are printed in a proportionally-spaced font, and may be
  paragraph-wraped.  Any indentation to the left of them, however, is
  printed with the same spacing as code.
 
o Comments consisting of a line of comment-start characters print as
  horizontal rules, and their first line is used as a section header.
 
o Any comment line ending in ":" is boldfaced to serve as a subsection
  head. 
 
o Code that appears to be function bodies (i.e., in C, code that
  starts with a left brace in the left-hand column, plus inlined
  functions in C++)  is omitted.
 
o There is a distinctive set of comment delimiters that cause anything
  between them to be omitted.  These are used to keep kludgery out of
  the user-level documentation.
 
Example:
 
	class Point {
	    // Description:
	    // 	  a trivial example -- C++ version of a point in polar
	    //	  and cartesian coordinates.
 
	    // Private data:
 
	    float x_, y_;
 
	    // Cartesian coordinates
 
	    float x();
	    float y();
 
	    // Polar coordinates:
 
	    float rho();
		// Radius.
	    float theta();
		// Angle.
	};
 
--
\ --Steve Savitzky--  \    343 Leigh Ave   \ REAL HACKERS USE AN AXE!
 \ steve@crc.ricoh.COM \ San Jose, CA 95128 \     Free Cyberia!
  \ w: 415-496-5710     \   h:408-294-6492   \ 
   \_________________________________________________________________________
 
From koopman@sgi84.ctc.com Thu Sep 23 14:06:39 -0400 1993
Date: Thu, 23 Sep 93 14:06:39 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: preston@cs.rice.edu, norman@bellcore.com
Subject: What does literate programming mean to you?
 
> Preston Briggs: So why did I write such an illiterate program?
> Norman Ramsey: I confess that my tool, noweb, is ...
 
As a novice and a "father confessor," concurrently :-) ....  Both of
your works are certainly valuable literate programming tools.  Perhaps
your self-evaluations are a bit critical with regards to these webs as
examples.  The structure of the web (irrespective of the depth of
exposition in English [other]) and the code scraps provide the reader
versed in the programming language quite a bit to go on.  Simply the
structure of the weave (index, cross ref.s) is a blessing compared to
"illiterate" programs.
 
Certainly, a working tool with a minimal description is more valuable
than a description sans working implementation.  Are these tools
examples which prove that literate programming is only a benefit in
certain cases?  How is the crossover point to be determined?  Expected
life and audience of the program should be factors.
 
> Norman Ramsey: 
>  i)  Making a good-quality literate program is 3-4times as expensive
>     as just making a working program using literate-programming tools.
> ii) I have been unable to develop really good literate programs
>     without peer review.
 
How does a literate programmer address these isues without risking
intellectual property and justifying costs?
 
Mike Koopman <koopman@ctc.com>
 
From preston@cs.rice.edu Thu Sep 23 13:23:54 CDT 1993
Date: Thu, 23 Sep 93 13:23:54 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, koopman@ctc.com
Subject: What does literate programming mean to you?
 
>Are these tools [nuweb and noweb]
>examples which prove that literate programming is only a benefit in
>certain cases?  How is the crossover point to be determined?  Expected
>life and audience of the program should be factors.
 
I think nuweb is better expressed in nuweb than in raw C.
And I think it'll be even better in the future.
However, your question remains: Are there programs that would not benefit?
 
For myself, I'm not sure.  I generally use nuweb now instead of plain C,
even when prototyping.  On the other hand, I don't use it for Makefiles
(though I might if I ever did anything hard).
 
I think your point about "audience" is very important.
Certainly we're constantly told to consider the intended audience
when writing ordinary papers.  And we obviously consider the audience
when speaking (e.g., how you speak to your parents, your colleages,
your children, a waiter, etc).  However, I'm sure what advice to give.
I feel very much like I'm learning as I go.
 
Preston Briggs
 
From aaron@halcyon.com Thu Sep 23 13:23:54 CDT 1993
Date: Thu, 23 Sep 93 13:23:54 CDT
From: aaron@halcyon.com (Aaron)
Reply-To: LitProg@SHSU.edu, aaron@HALCYON.COM
To: LitProg@SHSU.EDU
Subject: Re: Subscription to mailing list LitProg
 
In article <9309220938.AA02048@petrus.grenoble.hp.com>,
Dominique Dumont / GND  <domi@petrus.grenoble.hp.com> wrote:
[...]
>> flowchart).  The programmers demanded, and got, a tool which would auto-
>> matically generate the SDLs from the code, thereby ensuring that the SDLs
>> were always up-to-date. :]
>
>Shouldn't it be the other way ? From SDL to code .
 
What difference does it make?
If you think in code, write in code and generate documentation.
If you think in documentation, write in doc and generate the code.
If you don't think, don't write.  :)
 
-- 
aaron@halcyon.com
I know enough to know that I don't know enough.
 
From mfy@sli.com Thu Sep 23 18:33:25 GMT 1993
Date: Thu, 23 Sep 1993 18:33:25 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.EDU
Subject: Re: Big Programs & Separate files & Make & Incremental Compilation & Web
 
Quoting Robert T. McLay:
 
    What I want to know is how well web's work when the programs are say
    20,000 to 100,000 lines of code.  If  I make a small change in the
    program I  would certainly like not to have to recompile all of the
    code.
 
There is a simple method which accomplishes this and even more: if you change
only the documentation, you need not recompile anything.  As your programming
scale goes up, this feature gradually changes from being pleasant to being
essential.
 
In order to avoid elaborate circumlocutions, I will describe the particular
system I use rather than a general one.
 
Inscribe generates some number of files when it is run over its source (in what
WEB users would call tangle mode, though this verb isn't appropriate here).
For the sake of concreteness say they are m1.h through m9.h and m1.c through
m9.c.
 
Logically, what happens is that new versions of m1.h etc. are generated and
compared to their corresponding old versions.  If two such are identical, the
new one is deleted, leaving the old one untouched; otherwise it replaces the
old one.  On UNIX, this is done literally (the new files are named m1.h+ etc.);
on VMS, the new file is a more recent generation of the old one.  (On UNIX, the
old one is renamed m1.h~ to provide 1-level backup of old versions, but this
isn't essential to the method.)
 
The critical thing is that if m1.h doesn't change, it isn't touched, so a
"make" won't trigger recompilations.  A naive implementation, obviously, would
generate completely fresh versions of all generated files, and so any change at
all would require "recompiling the world."
 
A side effect of this is that just typing "make" isn't enough; you must first
run Inscribe, then make.  This doesn't bother me because I think the make file
should itself be made from the Inscribe source, but some have considered this a
negative aspect.  (I have also observed that nearly all large software projects
use some kind of makemake facility layered on top of make, so this "misfeature"
is not likely to matter.)
 
This approach has the advantage that you may be able to layer it on top of
existing LP tools via scripts.  I recommend it highly.
-- 
	Michael F. Yoder [mfy@sli.com]
 
From koopman@sgi84.ctc.com Thu Sep 23 17:02:49 -0400 1993
Date: Thu, 23 Sep 93 17:02:49 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
Subject: Can the LitProg Archives be made searchable?
 
Marcus Speh writes to the newly formed comp.programming.literate newsgroup:
>  Soon enough, we'll have postings from newcomers
>"Where is the FAQ for this group" - given that many questions 
>[e.g. "What does LitProg mean to you?", "Experiences with large
>projects?" etc.] are non-technical but rather philosophical, a FAQ
>may not be the best way of presentation. Also, I don't really see
>anyone searching the volumes by hand and putting the archive numbers
>together...therefore: can we think of a way to make the LitProg
>archives (the Subject headers, maybe) searchable?
 
How about keywords and comment fields.  Perhaps starting a discussion
regarding the meaning of relevant terms would lead to a glossary of
terms after some likely heated disagreements.  Then, the "final"
glossary - perhaps three months hence - could lend itself to a
classification scheme.  A "lucky" person could then add the keywords
and comment fields which apply to the archive.  The glossary could go
with the FAQ and those with enough concern for their postings could
attempt to fit keywords to their new posts.  If the glossary is
sensible, good keywords should be obvious.
 
Can *I* help in such an effort? .... OOPS there's my phone ... sorry,
no time. :-)
 
Mike <koopman@ctc.com>
 
From preston@cs.rice.edu Thu Sep 23 16:03:24 CDT 1993
Date: Thu, 23 Sep 93 16:03:24 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, mclay@cfdlab.ae.utexas.edu
Subject: Re:  Big Programs & Separate files & Make & Incremental Compilation & Web
 
Most web tools support the creation of multiple output files
(certainly nuweb, noweb, CWEB 3.0, FWEB, FunnelWeb).
That is, within a single web, I can specify many files of code
that will be created by the web tool.  Many (all?) of tese tools
have a provision that avoids overwriting a code file if it would
be unchanged.  Thus, it's easy to avoid massive recompiles when 
using make.
 
Avoiding big TeX costs is harder.  I'd like to modify nuweb to take
advantage of the Latex \include mechanism, but haven't done so yet.
 
Multi-person projects are harder to coordinate.
In our case, we work on a multipass compiler, so there's a fairly
natural division of labor and we have divided the project into a number of
webs, one per pass, with a single overview/coordinating web that
describes the common elements of each pass.  I'm not sure how best to
arrange more complex programs.
 
Preston Briggs
 
From rdp@butler.cps.com Thu Sep 23 16:03:24 CDT 1993
Date: Thu, 23 Sep 93 16:03:24 CDT
From: rdp@butler.cps.com (Ronald D. Parker)
Reply-To: LitProg@SHSU.edu, rdp@butler.cps.com
To: LitProg@SHSU.edu, d.love@dl.ac.uk
Subject: emacs tags technology for web-like systems?
 
> Does anyone have anything to allow the use of tags files in emacs
> with web-like systems (I'm interested in noweb, but I guess anything
> else would adapt straightforwardly).  What I have in mind is
> treating code modules/chunks or whatever you call them on the same
> basis as identifiers.
 
While we are at it is there a good emacs ``mode'' for editing WEB text
or one of its derivations?
 
--
Ron Parker                                    Butler Manufacturing Company
                  			      BMA Tower -- 4th Floor
rdp@butler.cps.com			      Post Office Box 419917
Phone: (816) 968-3537			      Kansas City, Missouri 64141-0917
 
From esj%tuesday@leia.polaroid.com Thu Sep 23 16:03:24 CDT 1993
Date: Thu, 23 Sep 93 16:03:24 CDT
From: esj%tuesday@leia.polaroid.com (Eric S. Johansson)
Reply-To: LitProg@SHSU.edu, esj%temerity@leia.polaroid.com
To: LitProg@SHSU.EDU
Subject: What does literate programming mean to you?
 
   In article <shfCDspwL.1D6@netcom.com> shf@netcom.com (Stuart Ferguson) writes:
   >
   >I say phooey.  "What guarantee?" indeed.  What guarantee do I have for
   >any given random piece of code that it operates correctly?  I have the
   >word only of the original programmer, and their reputation which I must
   >evaluate and trust or not.  In a world of literate programmers, keeping
   >the information up to date and accurate is part of the job.  Innacurate
   >commentary is unprofessional.  Dammit.
 
   This led me to an interesting thought (quick, bring an ice pack!)...
 
   Why not include a formal proof that the code has been verified, along with
   an informal description of what it does (you know, traditional
   unprofessional documentation)?  A good untangler could strip the proof, if
   it exists, and run it through a theorem verifier in order to certify it.
   Now you need only check the English documentation against the assumptions in
   the verification proof.
 
   Before everyone gives the usual complaints against formal verification, let
   me remind you that 1) they don't matter, we're discussing literate
   programming and a proof should be part of this if it exists; 2) most of
   those arguments are obsolete; 3) sometimes there is no alternative to
   formally verified code (ever tried to debug a pacemaker?).
 
Another variant on this theme is inclusion of a formal derivation of a
program.  for examples, look at the Z specification methodologies (set
based) and Ed Cohen's book, "Programming in the 1990's" (predicate based)
I am a fan of formal derivation of programs because it is something we can do
today instead of the someday promised by the verification folks.
 
In the informal "what can we do now" vein, I think literate programming can
help trace requirements from the initial requirements document to the
actual implementation because indexing/cross reference capability present
on the text processing side of the house.  trying to track what code
satisfies what requirement is a laborious manual process that mostly counts
on a coder's memory of the code and the requirements document.
 
--- eric
 
From George Thu Sep 23 17:16:15 CST 1993
Date: Thu, 23 Sep 1993 17:16:15 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, koopman@ctc.com
Subject: RE: Can the LitProg Archives be made searchable?
 
On Thu, 23 Sep 93 17:02:49 -0400, Michael G. Koopman
<koopman@sgi84.ctc.com> posted in response to Marcus Speh's 
<marcus@X4U.DESY.DE> earlier inquiry:
> How about keywords and comment fields.  Perhaps starting a discussion
> regarding the meaning of relevant terms would lead to a glossary of terms
> after some likely heated disagreements.  Then, the "final" glossary -
> perhaps three months hence - could lend itself to a classification scheme. 
> A "lucky" person could then add the keywords and comment fields which apply
> to the archive.  The glossary could go with the FAQ and those with enough
> concern for their postings could attempt to fit keywords to their new
> posts.  If the glossary is sensible, good keywords should be obvious.
 
How about a complete string search of everything in the archives??  I'm
compiling the indices right now (and will let them continue as I'm about to
leave for the day).  Come in to the LitProg Archives (guess I better
re-name them the LitProg/comp.programming.literate Archives soon) on the
Gopher server on Niord.SHSU.edu (192.92.115.8, port 70)
 Literate Programming Library/
   Archives of the LitProg list/
     Search LitProg Archives (**experimental**) <?>
 
and see what ensues.  Please, please, please, please don't try this until
after 2100 CDT (-5 GMT) as it may take at least that much longer to create
the indices required for this to work (actually, it's kinda neat how we got
this to work under VMS).  I am building the archives so that you can enter
a string (which will hopefully be found) and it will report back the
"Archive-Date:" of the post.  Once I see how it handles the task, I will
re-build this based on the "Subject:" or "From:" fields (if you have a
preference for any of these, let me know; "Keyword:", while nice, is not a
standard RFC 822 header field, so the available choices are:
 From:
 Date:
 To: -- (NO!! -- sez me)
 Subject:
 Archive-Date: (a field we enter in all of our archives)
 
Have fun (and hope I don't kill te machine as it indexes!!),   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Lewis Thu Sep 23 18:29:15 EST 1993
Date: Thu, 23 Sep 93 18:29:15 EST
From: "Lewis Perin" <perin@cumc.cornell.edu>
Reply-To: LitProg@SHSU.edu, perin@cumc.cornell.edu
To: LitProg@SHSU.edu
Subject: Re: Big Programs & Separate files & Make & Incremental Compilation &          Web
 
In Message Thu, 23 Sep 1993 18:33:25 GMT, mfy@sli.com (Mike Yoder) writes:
 
>    [...] I  would certainly like not to have to recompile all of the
>    code.
>
>There is a simple method which accomplishes this and even more: if you change
>only the documentation, you need not recompile anything.  As your programming
>scale goes up, this feature gradually changes from being pleasant to being
>essential.
>
> [details of exactly how he does it]
 
Unless I'm missing something this doesn't conquer the problem.  Those of us
who don't get their code right the first time (disgusting wretches we,
failing even with LP tools;-) tend to rely on our tangles inserting hints to
the target language debugger as to where in the web the source code can be
found.  Trouble is, change the documentation significantly and the locations
will change.
 
If the source code hasn't changed but has been relocated in the web, a
tangle smart enough to notice this can either go ahead and fool make (good)
and the debugger (bad), or it can let the compilation steps cascade.  Right?
 
Cheers,
______________________________________________________
      __          perin@cumc.cornell.edu (212)746-2946
 |   |_  \    / : Lew Perin
 |__ |__  \/\/  : Home: (201)435-2679
 
From ae1181t@stnfor.ae.ge.com Thu Sep 23 20:57:37 -0400 1993
Date: Thu, 23 Sep 1993 20:57:37 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, steve@cache.crc.ricoh.com
Subject: Re: Readable programs -- an alternative to Web, Tangle and Weave
 
Here is a short reply :
 IMHO you are missing a lot if you just rely on commenting. Just try
nuweb or noweb. You also get to arrange your code in a more 
understandable way (good for during the initial design phase). Need to
live with LaTeX though! I like the printed stuff but in your case 
if you are using DOS/Windows try WinWordWEB, this is a WYSIWYG system. May
be others are working on a unix/X system. 
This way you dont have to make up a strict commenting system and 
remember how to use it!  
 
Osman
 
From Mark Fri Sep 24 11:39:09 +1000 1993
Date: Fri, 24 Sep 1993 11:39:09 +1000 (EST)
From: Mark Ng <raemn@kittyhawk.aero.rmit.OZ.AU>
Reply-To: LitProg@SHSU.edu, raemn@KITTYHAWK.AERO.RMIT.OZ.AU
To: LitProg@shsu.edu, norman@bellcore.com
Subject: Re: What does literate programming mean to you?
 
> I confess that my tool, noweb, is at best of poor quality when
 
  You say that it is of poor quality but rest assured that it is 
beging put to good use :)
 
>   i)  Making a good-quality literate program is 3-4 times as expensive
>       as just making a working program using literate-programming tools.
 I could not agree more
 
>   ii) I have been unable to develop really good literate programs
>       without peer review.
 
 I've used noweb for some time now and I enjoy using it because it is so 
 simple. I went through most the different litprog tools and found noweb
 best suit to my task of multiple languages in one file.
 
 Thank you for your contribution of noweb as a tool :)
 
-----------------------------------------------------------------------------
Mark Ng                              email: raemn@kittyhawk.aero.rmit.oz.au
Assistant Systems Administrator      Phone: +61 3 6603142
Department of AeroSpace Engineering  Fax  : +61 3 6602053
 
      "All is hidden in the citadel of the heart..."
-------------------------------------------------------------------------
 
From karna@pobox.upenn.edu Fri Sep 24 11:39:09 +1000 1993
Date: Fri, 24 Sep 1993 11:39:09 +1000 (EST)
From: karna@pobox.upenn.edu (Animesh Karna)
Reply-To: LitProg@SHSU.edu, karna@POBOX.UPENN.EDU
To: LitProg@SHSU.EDU
Subject: Web-like system that doesn't use TeX?
 
One of the things stopping me from using Web (or CWeb) is that the
"readable" output is in TeX.  Does anyone know of a version of
Web/CWeb/something similar that can produced other kinds of output -- like
plain text or RTF or something like that?
 
Thanks!
 
--
Definition of the PC Movement: It's what happens when Liberals start acting
like Conservatives.
 
From gurari@news.cis.ohio-state.edu Fri Sep 24 11:39:09 +1000 1993
Date: Fri, 24 Sep 1993 11:39:09 +1000 (EST)
From: gurari@news.cis.ohio-state.edu (Eitan Gurari)
Reply-To: LitProg@SHSU.edu, gurari@NEWS.CIS.OHIO-STATE.EDU
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
Literate programming offers me a natural medium for
 
1.  Communicating information between different phases of code
    development
 
2.  Arguing with myself about my code by explaining its meaning.
 
    Since an explanation of subject matter is a description of an
    understanding of the subject matter, a programmer who provides an
    explanation for code must closely inspect his or her understanding of
    the code as the description of this understanding of the code is being
    produced. Such a mode of operation encourages programmers to take a
    critical look at their code, and it results in code that is prepared
    with a lot of care.
 
Macro-based abstractions with natural language oriented titles for
code segments, fragmentation of code segments, prose, figures, and
mechanisms to structure documents are the ingredients that are
important to me in the medium that I am using.
 
I consider it a worthless effort to polish the exposition and
appearance of literate programs that are not intended to be consumed
by others (i.e., documents that are not intended for peer review---see
norman's note).  Consequently, documents that serve as literate
programs to me might be cryptic creatures to other readers.
 
-eitan
 
From <s925578@hp720a.csc.cuhk.hk> Fri Sep 24 13:22:03 +0800 1993
Date: Fri, 24 Sep 93 13:22:03 +0800
From: <s925578@hp720a.csc.cuhk.hk>
Reply-To: LitProg@SHSU.edu, s925578@hp720a.csc.cuhk.hk
To: LitProg@SHSU.edu, karna@pobox.upenn.edu
Subject: RE:Web-like system that doesn't use TeX?
 
In Message 24 Sep 93 01:58:37 GMT,
  karna@pobox.upenn.edu (Animesh Karna) writes:
 
>One of the things stopping me from using Web (or CWeb) is that the
>"readable" output is in TeX.  Does anyone know of a version of
>Web/CWeb/something similar that can produced other kinds of output -- like
>plain text or RTF or something like that?
>
>Thanks!
>
>--
>Definition of the PC Movement: It's what happens when Liberals start acting
>like Conservatives.
 
From Dominique Fri Sep 24 09:25:45 +0200 1993
Date: Fri, 24 Sep 93 09:25:45 +0200
From: Dominique Dumont / GND <domi@petrus.grenoble.hp.com>
Reply-To: LitProg@SHSU.edu, domi@PETRUS.GRENOBLE.HP.COM
To: LitProg@SHSU.edu, aaron@halcyon.com
Subject: Re: Subscription to mailing list LitProg
 
In message <27qvgt$5je@nwfocus.wa.com> you write:
> [...]
> >> flowchart).  The programmers demanded, and got, a tool which would auto-
> >> matically generate the SDLs from the code, thereby ensuring that the SDLs
> >> were always up-to-date. :]
> >
> >Shouldn't it be the other way ? From SDL to code .
> 
> What difference does it make?
> If you think in code, write in code and generate documentation.
> If you think in documentation, write in doc and generate the code.
> If you don't think, don't write.  :)
> 
IMO, the SDL is more synthetic. You have an overall view of the functionnality
of your future program and its interractions with the outside world (OS, other
program...). It's easier to think with this form. And if the code is generated
from the SDL, you're done when the SDL is done and you don't have to care about
a lot of details needed to write your code. 
 
I must state that I'm not yet experienced in writing programs then my opinion
can be wrong. The feeling I have
is drawn from my past experience in chip systhesis from a VHDL model. That worked
fine, but I would have loved to have VHDL generated from the state machine I
drawed for the chip.
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 53 20
-----------------------------------------------------------------------------
 
From ziegler@mpi-sb.mpg.de Fri Sep 24 10:15:42 +0200 1993
Date: Fri, 24 Sep 93 10:15:42 +0200
From: ziegler@mpi-sb.mpg.de (Joachim Ziegler)
Reply-To: LitProg@SHSU.edu, ziegler@MPI-SB.MPG.DE
To: LitProg@SHSU.edu, mfy@SLI.COM
Subject: Re: Big Programs & Separate files & Make & Incremental Compilation & Web
 
M. Yoder writes:
 
> Inscribe generates some number of files when it is run over its source (in what
> WEB users would call tangle mode, though this verb isn't appropriate here).
 
Can anyone please explain me what "Inscribe" is?
 
From zen@death.corp.sun.com Fri Sep 24 10:15:42 +0200 1993
Date: Fri, 24 Sep 93 10:15:42 +0200
From: zen@death.corp.sun.com (d ... 415-336-0742)
Reply-To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <9309231641.AA21487@dawn.cs.rice.edu> preston@cs.rice.edu (Preston Briggs) writes:
> koopman@ctc.com writes:
> >Some of the webs written for literate programming tools do not appear
> >to be enhanced expositions of the principles underlying the behavior
> >of the program (while including the code scraps).  Such leading,
> >literate program authors could be considered hypocrit infidels not
> >practicing what they seem to preach
> Hmm.  Certainly nuweb (I wrote it) is worse in this respect than any
> other tools I've examined.  So why did I write such an illiterate program?
 
> I have to consider it incomplete.  It'll get more complete as I spend more
> effort on it.  In the meantime, I (and others) are able to use it without
> worrying about whether I've finished describing it all.  It's just a tool,
> not an end in itself.  A hammer doesn't need a dissertation attached to
> be useful.
 
Talk about justifying your actions... you could say the same thing about
any tool or program -- they're just not finished.  I've had to use,
modify, and throw away countless programs that aren't commented or are
poorly written, just because the author(s) thought that it wasn't worth
the effort or that they'd get around to it later.  One of the worse
things you can do to a program is to comment/document it (or
"literalize" it?)  *after* it's a working piece of code.  IMHO, writing
literate or even just a "good" program (if you can consider a program to
be good if it doesn't follow the literate standards set by knuth and
others) very nearly *requires* you to have as good design as possible
from the start, and then to follow the same standards in every phase of
the code that you want to have when it's a finished product at the end;
tacking it on at the end is something that is almost never gotten around
to, and is almost guaranteed to be of lesser quality than something that
was done right the first time.
 
> I (and others) are able to use it without worrying about whether I've
> finished describing it all
 
Why ever bother making it literate, then, if it works fine without it?
 
-- d
 
From zen@death.corp.sun.com Fri Sep 24 10:15:42 +0200 1993
Date: Fri, 24 Sep 93 10:15:42 +0200
From: zen@death.corp.sun.com (d ... 415-336-0742)
Reply-To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <27qkip$fa3@overload.lbl.gov> bks@s27w007.pswfs.gov (Bradley K. Sherman) writes:
> The literate programmer...
 
  I would hope, in addition to everything else, the LP would be
concerned that programs written in the literate style actually work (but
see below, I don't know).
 
> The literate programmer knows that copyright protection of
> source code is absurd; knowing the right approach to
> the problem --and which problem to approach-- is everything.
 
  Copyrights are absurd?  Do you mean algorithm copyrighting or
that *all* code should be free to everyone else?  What does the latter
have to do with LP'ing?
 
> The literate programmer is a poet not a novelist.
 
  Poetry can obscure meanings.  I'd rather read code written in the
style of dickens rather than e.e. cummings... to me, I think the key is
functionality and clarity first, not style.  I wonder if people here
view LP'ing as more of an art form, something that has inherent
usefulness, or as a vehicle to produce "better" (whatever that means)
programs.
 
 -- d
 
From zen@death.corp.sun.com Fri Sep 24 10:15:42 +0200 1993
Date: Fri, 24 Sep 93 10:15:42 +0200
From: zen@death.corp.sun.com (d ... 415-336-0742)
Reply-To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <9309231658.AA25879@mailee.bellcore.com> norman@bellcore.com writes:
>     ii) I have been unable to develop really good literate programs
>	 without peer review.
 
Why is that?  Is it too hard to recognize literacy when seen, or is it
that you don't have enough practice, the tools aren't there, or ...?
 
 -- d
 
From marcus@x4u.desy.de Fri Sep 24 10:55:17 GMT 1993
Date: Fri, 24 Sep 1993 10:55:17 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: Readable programs -- an alternative to Web, Tangle and Weave
 
>>>>> On 23 Sep 1993 18:03:01 GMT, steve@crc.ricoh.COM (Stephen R. Savitzky) said:
 
|> My coding standards for readable programs are:
 
[..very interesting stuff deleted..]
 
Hey, this is another interesting article--as far as I know the first
time that the word of "coding standard" comes up in connection with 
literate programming, though we've been discussing litprog 'habits'
at length in the past
[I checked with the archives through gorgeous gopher search, only
one entry found which refers to pretty-printing of fortran output
using sed(1) :-) ].
I have often thought this is something we should have-- I (and many
of my colleagues) did profit from such a document for c++ (called
RULES AND RECOMMENDATIONS --> ftp.desy.de:/pub/c++/misc/c++.rules.ps),
though any standardization document is (and should) usually subject to
heated discussion.
 
  Now, is it heresy to think of a "coding standard", as a set of
minimal rules for the practicing lierate programmer? Clearly, such a
text should be independent of the particular litprog tool--for the
same reason it may support unifying tendencies, which I would welcome. 
 
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u.desy.de Fri Sep 24 11:00:05 GMT 1993
Date: Fri, 24 Sep 1993 11:00:05 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: LitProg (experimental) archive search on WWW
 
I have put a link to this gopher index on the LitProg home page
on the world wide web. It's fast!
 
[for info, refer to ---> ftp.desy.de:/pub/www/projects/Announce/LitProg.txt]
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From cgra@btma74.nohost.nodomain Fri Sep 24 11:00:05 GMT 1993
Date: Fri, 24 Sep 1993 11:00:05 GMT
From: cgra@btma74.nohost.nodomain (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <9309222034.AA13126@sgi84.ctc.com>, koopman@sgi84.ctc.com (Michael G. Koopman) writes:
>Some of the webs written for literate programming tools do not appear
>to be enhanced expositions of the principles underlying the behavior
>of the program (while including the code scraps).  Such leading,
>literate program authors could be considered hypocrit infidels not
>practicing what they seem to preach (false names are used to protect
>the innocent).  A comprehensive and well structured presentation
>(printed document, hypertext, other) that compiles to realize the
>description is what I expect from literate programming.
 
To which norman@bellcore.com, author of noweb, retorts:
>
>[...]I tolerate my ugly ``literate'' programs because in my work a program
>is seldom an artifact of the first importance.   Far more often the
>paper is what matters (and what gets polished).
 
Well that's a pretty straightforward admission that to this guy at least 
literate programming is just an academic fad which enables you to get
papers published, not a serious proposal to enhance the quality of our
programs (and our lives).  If that's true then I'm wasting my time reading
this stuff and I should get back to work mungeing my design documentation
into comments in the source code.
 
Apparently preston@cs.rice.edu (Preston Briggs) also feels his ears burning:
 
>Hmm.  Certainly nuweb (I wrote it) is worse in this respect than any
>other tools I've examined.  So why did I write such an illiterate program?
 
>I have to consider it incomplete.  It'll get more complete as I spend more
>effort on it.  In the meantime, I (and others) are able to use it without
>worrying about whether I've finished describing it all.  It's just a tool,
>not an end in itself.  A hammer doesn't need a dissertation attached to
>be useful.
 
To which I say: phooey (tm).  Games and demo's aside, all programs are tools.
Lotus 1-2-3 is a tool, Cubase and KCS are tools.  The programs which
programmers call ``tools'' are the ones which they use to make other programs.
It is precisely these programs which people are most likely to feel the need
to hack into and rearrange and modify in order to provide support for their
company  documentation scheme, network file server, GUI, and Nintendo Power
Glove. These are programs written by programmers for programmers, and they
 _should_ be exemplary.
 
__________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
   Ignore my broken mailer - the addresses above are the only truth
__________________________________________________________________________
``phooey'' is a trade mark of shf@netcom.com (Stuart Ferguson)
 
Disclaimer: the author is a total hypocrite whose programs arouse much
comment by containing little.
 
From ae1181t@stnfor.ae.ge.com Fri Sep 24 08:02:47 -0400 1993
Date: Fri, 24 Sep 1993 08:02:47 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, zen@death.corp.sun.com.ae.ge.com.ae.ge.com
Subject: Re: What does literate programming mean to you?
 
>>>>> On 24 Sep 93 01:15:30, zen@death.corp.sun.com.ae.ge.com (d ... 415-336-0742) said:
 
	d> Talk about justifying your actions... you could say the same thing about
	d> any tool or program -- they're just not finished.  I've had to use,
	d> modify, and throw away countless programs that aren't commented or are
	d> poorly written, just because the author(s) thought that it wasn't worth
	d> the effort or that they'd get around to it later.  One of the worse
	d> things you can do to a program is to comment/document it (or
	d> "literalize" it?)  *after* it's a working piece of code.  IMHO, writing
	d> literate or even just a "good" program (if you can consider a program to
	d> be good if it doesn't follow the literate standards set by knuth and
	d> others) very nearly *requires* you to have as good design as possible
	d> from the start, and then to follow the same standards in every phase of
	d> the code that you want to have when it's a finished product at the end;
	d> tacking it on at the end is something that is almost never gotten around
	d> to, and is almost guaranteed to be of lesser quality than something that
	d> was done right the first time.
 
I can think of one reason to literalize it: so that it may the first example
for a new user, and also you tend to find bugs or better ways of doing
the same thing, or so that you can, at a later time, understand what you did
without spending a lot of time. Even though Preston(nuweb's author)
thought nuweb was not literate, I had no problem with it. It was an
example of how to use the tool, and I was able to understand what he did
even though I am not a programmer (engineer)! 
 
> I (and others) are able to use it without worrying about whether I've
> finished describing it all
 
	d> Why ever bother making it literate, then, if it works fine without it?
 
Same comment as above.
 
Osman
 
Osman F. Buyukisik  |  GE Aricraft Engines  | ae1181t@stnfor.ae.ge.com
 
From George Fri Sep 24 07:44:38 CST 1993
Date: Fri, 24 Sep 1993 07:44:38 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, nigel_jones@VNET.IBM.COM
Subject: RE: Literate programming - would like to unsubscribe
 
                        READ THIS POSTING, PLEASE
On Fri, 24 Sep 93 07:28:33 +0000, Nigel Jones <nigel_jones@vnet.IBM.COM>
posted:
> I am not sure how to unsubscribe to this mailing list. Sorry to disrupt the
> conversation.. but can anyone tell me how?
 
As list owner, I've unsubscribed Nigel.  As promised, here is a second
(modified, much shorter) posting of my message of a few days ago.
 
--George
 
Given that the comp.programming.literate newsgroup has been created and it
has been proven that an efficient gateway between mail and news exists, I
am sure some subscribers to LitProg will elect to drop their mail
subscription in favor of the newsgroup.
 
To avoid misdirected posts to either the list or the newsgroup in your
attempts to unsubscribe, please send a MAIL message to:
                 LISTSERV@SHSU.BITNET (LISTSERV@SHSU.edu)
                                 -- or --
                         LitProg-Request@SHSU.edu
stating in the body of the MAIL message:
 SIGNOFF LitProg
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % Please do NOT send the SIGNOFF message to the list address,  %
     % LitProg@SHSU.BITNET (LitProg@SHSU.edu), as this is the       %
     % redistribution address for the list.  All posting to LitProg %
     % are distributed to its worldwide list of subscribers, as     %
     % well as to the comp.programming.literate newsgroup.          %
     %                                                              %
     % Please note that the LISTSERV which serves LitProg is MAIL   %
     % oriented only and is not conventional interactive LISTSERV.  %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
If, for some reason, LISTSERV cannot handle your request automagically, it
will be forwarded to me (promise!!) for my manual attention.  Also, any
mail enqueued to LitProg prior to your signing off which is still enqueued
for you will continue to be delivered until the queue clears (generally,
you should receive nothing more within three days (if at all), give or
take, once you receive confirmation that you have been removed).
 
As always, I thank each of you for your interest in our services and retain
my open offer to discuss any and all ideas you might have for enhancing
them.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From preston@cs.rice.edu Fri Sep 24 08:59:58 CDT 1993
Date: Fri, 24 Sep 93 08:59:58 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu, zen@death.corp.sun.com
Subject: Re: What does literate programming mean to you?
 
I wrote:
>I have to consider it [nuweb] incomplete.
>It'll get more complete as I spend more effort on it.
 
and zen@death.corp.sun.com (somebody?) writes:
>Talk about justifying your actions... you could say the same thing about
>any tool or program -- they're just not finished.
 
Of course I justify my actions; what did you expect?
And nuweb does keep improving, both in functionality and documentation.
When it's finished, I won't work on it any more.
 
>One of the worse
>things you can do to a program is to comment/document it (or
>"literalize" it?)  *after* it's a working piece of code.
 
Why?  It may not turn out as well as a beutiful example, worked up from scratch,
but it won't hurt the code.
 
In the case of nuweb, I wrote the spec first, then an initial cut at the
code in CWEB.  Once it would handle itself, I translated the web into nuweb
and continued from there (why? as an experiment to see what it was like to
use nuweb.)  At some point, I said to myself "This is cool, I like it,
I wonder if others will?" and I started giving it away.  This garnered
a lot of comments and ideas as more people used it (and modified it)
and I've been able to build some of the better ideas into the system.
Eventually it'll settle down, as it either approaches perfection or
bumps up against the basic limitations of its approach.  When one these things
happens, I'll either rewrite it, rationalizing some of the code, or I'll
chunk it and begin using a better tool.
 
>Why ever bother making it literate, then, if it works fine without it?
 
I wrote it in nuweb (and CWEB initially) so I could practice using web,
so I could experiment with different ways of explaining things, so I
(and readers) could benefit from the indices and crossreferences
and free code arrangment, and so I could take advantage of the features
of Latex to help explain my code.
 
Preston Briggs
 
From Edward Fri Sep 24 09:57:23 -0500 1993
Date: Fri, 24 Sep 1993 09:57:23 -0500 (CDT)
From: "Edward M. Robinson" <Robinson@UH.EDU>
Reply-To: LitProg@SHSU.edu, Robinson@UH.EDU
To: LitProg@SHSU.edu
Subject: "Literizing" programs
 
The following caught my eye since I am working on something similar.
 
Osman F Buyukisik wrote :
>
>I can think of one reason to literalize it: ...
 
What thoughts do you have on the merits of "literizing" programs?
 
For example, I am working on the skeleton portion of Berkely YACC
to have it perform some additional actions. Since the skeleton was,
probably, never meant for human consumption, I have decided to
rewrite it in FWEB. My hope is that in the future it will be easier
to modify and enhance. The questions that persist in nagging me are
"Is this worth it?" and "Are there any tools (free GNU stuff please,
I am but a poor RA :-) out there to aid in this?"
 
Any ideas?
 
-- Ed Robinson
Robinson@uh.edu
 
From ae1181t@stnfor.ae.ge.com Fri Sep 24 12:28:26 -0400 1993
Date: Fri, 24 Sep 1993 12:28:26 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, Robinson@UH.EDU
Subject: Re: "Literizing" programs
 
The only tools that I know are free! nuweb,noweb,fweb,cweb,spider,...
Also there are a couple of emacs modes for webs. I like auctex and nuweb
mode. I think that it will pay off in a big way if you literalize your
programs. Better yet start using them in the design phase. Nowdays
I do not use any language by itself but with nuweb. There are some
functional languages (like haskell) that have inverse comment method
(every line is a comment unless it starts with a '>' char). That is
better than regualr comments but still misses on index,xref, and
ability to write your code parts in any order you want. 
Osman
 
From zen@death.corp.sun.com Fri Sep 24 12:28:26 -0400 1993
Date: Fri, 24 Sep 1993 12:28:26 -0400
From: zen@death.corp.sun.com (d ... 415-336-0742)
Reply-To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <9309241359.AA09604@dawn.cs.rice.edu> preston@cs.rice.edu (Preston Briggs) writes:
> I wrote:
> >I have to consider it [nuweb] incomplete.
> >It'll get more complete as I spend more effort on it.
> and zen@death.corp.sun.com (somebody?  That's me!) writes:
> >Talk about justifying your actions... you could say the same thing about
> >any tool or program -- they're just not finished.
> Of course I justify my actions; what did you expect?
 
  No less, of course.  The point I was trying to make was that your
justification was being hypocritical to the (*grin* -- well, *my* ideal,
of course!) ideal of literate programming.
 
> >One of the worse
> >things you can do to a program is to comment/document it (or
> >"literalize" it?)  *after* it's a working piece of code.
> Why?  It may not turn out as well as a beutiful example, worked up
> from scratch, but it won't hurt the code.
 
  It almost certainly will.  IMO, literalizing the code is an integral
part of the design and coding process, something that grows as the
program does.  It helps you write a better program; that's the point.
When you try to go back post facto and slap it in, you have several
problems (off the top o' my head):
 
1) It probably won't get done.  Very rarely are working programs
rewritten -- time is too much of a factor.
 
2) If, as is often the case with most programs, it doesn't do what you
want, you have to start again from scratch, then you never get around to
writing a good program.
 
3) You lose the advantage of doing it right from the start; if you
accept the premise that the program will be better, both from a design
and coding standpoint if literalized, then you lose both the extra time
you take to do the job twice *and* the advantages of design that you
gain from the literalizing.
 
4) WRT quality, it will be all the worse for not being literal (until
you run back and make it right.)  People won't use it or accept it as
much, and the original programmer(s) won't have incentive to improve it.
 
5) If no one writes literate programs, then no one will see the
advantages.  You throw something together, it works, and everyone is
happy, right?  Well, "works" is a very subjective thing.  If I write a
program I don't usually want it just to work for me.  I want others to
be able to use it, modify it, and understand it.  To me, that's all part
of the joy and purpose of programming.
 
  It's early in the morning, but there are lots of other reasons...
 
> In the case of nuweb, I wrote the spec first, then an initial cut at the
> code in CWEB.  Once it would handle itself, I translated the web into nuweb
> and continued from there (why? as an experiment to see what it was like to
> use nuweb.)  At some point, I said to myself "This is cool, I like it,
> I wonder if others will?" and I started giving it away.  This garnered
> a lot of comments and ideas as more people used it (and modified it)
> and I've been able to build some of the better ideas into the system.
 
  You would have gotten more and better comments if people could have
*read* what you wrote and how you implemented your decisions.  Someone
said that they couldn't write a literate program without peer review; I
claim that in most nearly all cases that you're not going to get that
peer review if you don't write it literally.
 
> Eventually it'll settle down, as it either approaches perfection or
> bumps up against the basic limitations of its approach.  When one these things
> happens, I'll either rewrite it, rationalizing some of the code, or I'll
> chunk it and begin using a better tool.
 
  *sigh*  That's what happens to code.  People write it, use it, then
move on.  Nothing ever gets done *right*, it's all just another
justification for not literalizing it.  If you had done this right, I
maintain that not only would the chances of you scrapping it and
starting from fresh be greatly decreased, you would learn a lot more on
how to design and implement this sort of program.  A quick reference --
have you read knuth and his experiences, when he first starts to program
a large project, and why he believes in literate programming?
 
  Going back to your other article:
 
> It's just a tool,
> not an end in itself.  A hammer doesn't need a dissertation attached to
> be useful.
 
  It's just an amazing statement, esp. on this newsgroup.  But to
address it again, your program isn't a hammer.  It has lots of features,
lots of ideas packed into it, lots of ways to use it by lots of people
using lots of systems.  But even that lowly hammer needs to be made
right; constructing a good hammer means you have to consider what it's
going to be used for, to choose the right materials.  It means you have
to communicate to the user what it can and should be used for (claw vs
sledge hammers, for instance).
 
  I find it amazingly ironic that a program to do literate program isn't
written in a literate manner, but far more ironic that the programmer
behind it thinks that it was the right thing to do.
 
 -- d
 
From mfy@sli.com Fri Sep 24 19:42:16 GMT 1993
Date: Fri, 24 Sep 1993 19:42:16 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.EDU
Subject: Re: Big Programs & Separate files & Make & Incremental Compilation &
 
Lewis Perrin wrote, in response to my deathless prose:
 
>Unless I'm missing something this doesn't conquer the problem.  Those of us
>who don't get their code right the first time (disgusting wretches we,
>failing even with LP tools;-) tend to rely on our tangles inserting hints to
>the target language debugger as to where in the web the source code can be
>found.  Trouble is, change the documentation significantly and the locations
>will change.
>
>If the source code hasn't changed but has been relocated in the web, a
>tangle smart enough to notice this can either go ahead and fool make (good)
>and the debugger (bad), or it can let the compilation steps cascade.  Right?
 
You did miss something, but only because I omitted to tell you.  Inscribe
automatically inserts #line directives for generated C and C++ files, so the
debugger's source is the Inscribe source in those cases; I call this "direct
debuggability," which may be my private jargon, but I think I appropriated the
term from people in this forum.  It would be simple to generate equivalent
directives for other languages if their compilers paid attention to them, e.g.
"pragma Line" for an Ada compiler.
 
Also, I have an Emacs function which lets me find the Inscribe line which
corresponds to line N of a given produced file: thus if the compiler says I
have an error on line 32 of Pascal file foo.p, I find some occurrence of source
for foo.p and invoke "C-Z g" with an argument of 32, and it goes to the
appropriate place.  This is crude but quite effective and reliable.
-- 
	Michael F. Yoder [mfy@sli.com]
 
From tfj@apusapus.demon.co.uk Fri Sep 24 20:28:21 GMT 1993
Date: Fri, 24 Sep 93 20:28:21 GMT
From: tfj@apusapus.demon.co.uk (Trevor Jenkins)
Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK
To: LitProg@shsu.edu
Subject: Re: Web-like system that doesn't use TeX?
 
In message <149307@netnews.upenn.edu> you write:
> One of the things stopping me from using Web (or CWeb) is that the
> "readable" output is in TeX.  Does anyone know of a version of
> Web/CWeb/something similar that can produced other kinds of output -- like
> plain text or RTF or something like that? 
 
I fail to see :-) how RTF is any more readable than TeX. The intent is to
process the woven TeX to produce the real readable output which is the
listing.
 
As for plain text why not use the .w file. I only have TeX installed on my
PC at home but I still use Literate Programming for my work as I have
cweave/ctangle installed at the office. Whilst at the office rely on
printing out the .w and only occasionally do I actually use cweave and TeX
to produce the formal listings.
 
Regards, Trevor.
 
---------------------------------------------------------------------------
Trevor Jenkins                                                Re: "deemed!"
134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England
email: tfj@apusapus.demon.co.uk   phone: +44 (0)923 776436     radio: G6AJG 
 
   "We need bigger and better books", Jimmy Tingle (Damned in the USA)
 
From bart@cs.tamu.edu Fri Sep 24 14:32:50 CST 1993
Date: Fri, 24 Sep 1993 14:32:50 CST
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: LitProg@SHSU.EDU
Subject: Big Projects and What Literate Programming Means
 
Some comments by Bart Childs on recent postings.
 
I agree with the characteristics that Bradley Sherman gave for
literate programming.  I have written several introductory
documents on this that we use for introductory purposes.
They are available for anonymous ftp from:
  ftp.cs.tamu.edu
  /pub/tex-web/web/DOCs  is the directory.
I will email them to individuals who cannot ftp.  They
are too long for posting here.
 
Bradley noted that literate programs are written for other readers.
That is easily overlooked (Norman Ramsey was eloquent about peer
review in the LitProg discussion list.)  Review will not automatically
convert programs into publications (as in tenure and promotion
documents.)  He used the phrase ``tight grammatical English'' and
there have been a number of suggestions that may be over simplified by
just ``hypertextize the specifications and the other 2167A
documents.''  Samuel Johnson wrote:
  ``What is written without effort is in general
    read without pleasure.''
The point is that quality documentation is never free or accidental.
It takes work, work, ...  Hypertext links to specs... can be
valuable but is no replacement for real documentation of the
thoughts behind programming decisions.
 
Foster@jed.cs.uidaho.edu stated
  ``Why not include a formal proof that the code has been verified,
    along with an informal description of what it does (you know,
    traditional ...
    Before everyone gives the usual complaints against formal
    verification, let me remind you that 1) they don't matter,
    we're discussing literate programming and a proof should be
    part of this if it exists; ...''
Of course, if the proof exists it should be a part of the
documentation or as a minimum a ``reference'' to its availability.
Another item of the same type is that graphics and EVERY other aid
to understanding how, why, ... should be part of a literate program.
All that takes is work, work, ... (editing is work).
 
What portion of our codes could be formally proven...?  I guess
that I am a cynic on that and would guess ... well, a small percentage.
 
Norman Ramsey and Preston Briggs have been modest about their work.
Both have made statements about `simple tools.'  Edsger Dijkstra
repeatedly points out ``if you want to make a user interface more
difficult to use, add functionality to it.''  Ramsey and Briggs
have created simpler tools (than DEK's original ...)  I think the
addition of the capabilities of multiple output files is a typical
example of added functionality that is so easily handled otherwise.
 
Sure, there is value in having a script that is associated with
a huge code in the same file, but if you change (say) the
documentation of the script that should not imply the code needs
recompilation too (in a make sense).
 
There have been several postings over the past year that indicate
a desire for perturbations to major changes in LP systems.  I think
we don't know for sure what they should be like and we need a lot
of documented use of the existing systems.  I have not found that
WEB (original, F, or C) is difficult for (even) students to learn.
It takes a little training.  We can't be sure of the contributions
of literate programming until we write lots of programs, document
their maintenance, and make them available for study.
 
Norman Ramsey and Carla Marceau's paper (see the LitProg archives)
is still one of the few papers about using WEB in a professional
environment, several programmers ...
 
Stephen Savitzky stated:
  ``My approach to literate programming is to write programs that
    can be read, rather than the Web approach of writing programs
    that can be processed to make them readable.  I do this because
    I rarely, if ever, get a listing; I much prefer to edit on the
    screen.  I want my programs to be as readable as possible
    when I do.  ...''
I am not saying that his codes are not wonderful expositions, but
this indicates the goal is not the future reader, but his instant
self gratification (apologies, if that is taken as a flame.)
 
Incidentally, there has been some previous discussion about the
index or lack thereof in some LP systems.  (Indexes of variable
names obviously require knowledge of the HLL.)  Some users have
stated the use of the `formalized procedures of pseudo-code'
(my words) as the greatest value of the whole LP process.  I can
understand this opinion at writing time, but years later at
maintenance it will be greatly diminished.  The use of the
`formalized procedures of pseudo-code' is only a part of
literate programming.
 
Aaron (aaron@halcyon.com) stated the status quo:
  ``What difference does it make?
    If you think in code, write in code and generate documentation.
    If you think in documentation, write in doc and generate the code.
    If you don't think, don't write.  :)''
The commonly stated statistic varies from 60% to 80% for the cost
of the maintenance portion of a code in its lifetime.  I think that
literate programming can aid that.
 
Robert T. McLay started a discussion with this subject:
Subject: Big Programs & Separate files & Make ...
He offered some numbers that I wish to correct.
TeX and METAFONT are each about 25k lines of Pascal code.
(Count the semicolons and realize that most Pascal code has
a significant number of lines without them too.)  Both are
written in the monolithic form required by the Pascal compilers
of the early 1980's.
 
I recommend that literate programming be used in a manner that
does not cause a dramatic change to the usual software life cycle
for many developers.  The only part that should really change is
the code development part.  Most developers use (something like)
make and the dependencies just get one more item.  Sure it slows
it down a bit, but the paybacks are large in comparison (IMHO).
Knuth stated it was true but never gave any statistics to prove
it.  He also keeps a detailed diary and could well have the
data to prove it.
 
Also see comment about Ramsey and Marceau above.
 
Mike Yoder (mfy@sli.com) described a tool (process?) that saves
significant recompiling ...  Each of these should always cause
a reflection on the Dijkstra quote.  Is the additional complexity
of another tool ... worth it?  How much is the cost of the
additional (wasted) compiles?
 
>From: zen@death.corp.sun.com (d ... 415-336-0742)
>Subject: Re: What does literate programming mean to you?
>Date: 24 Sep 93 01:29:49
>
>In article <...@mailee.bellcore.com> norman@bellcore.com writes:
>>     ii) I have been unable to develop really good literate programs
>>	 without peer review.
>
>Why is that?  Is it too hard to recognize literacy when seen, or is it
>that you don't have enough practice, the tools aren't there, or ...?
 
I think the answer is two-fold.  First, we are terrible judges of our
own work, whether writing, dancing, speaking, programming, ...
Secondly, the process of programming is intensive and often
characterized by our having tunnel vision, not being able to find a
forest because we keep bumping into trees, ...
 
I am sure there are people who can write well and don't need as much
peer review.  Much of Don Knuth's work would likely qualify.  Careful
reading of his work also shows that he gets it reviewed by as many
people as he can.  Most readers of this list will likely claim to
be in environments where it is not practical to get said review.
 
Zen also discusses this in a later posting and expresses the desire
to know more about why certain design decisions were made.  These are
available for Knuth's original WEB.  Some of these are couched in the
large variability of Pascal compilers at the time.  This same info
is available for CWEB and FWEB, but not all questions will be answered.
His point is made.
 
>From: cgra@btma74.nohost.nodomain (Chris Gray)
>Subject: Re: What does literate programming mean to you?
>Date: 24 Sep 93 11:04:05 GMT
>...
>In article <...@sgi84.ctc.com>, koopman@sgi84.ctc.com (Michael G. Koopman)
>>Some of the webs written for literate programming tools do not appear
>>...
>
>To which norman@bellcore.com, author of noweb, retorts:
>>
>>[...]I tolerate my ugly ``literate'' programs because in my work a program
>>is seldom an artifact of the first importance.   Far more often the
>>paper is what matters (and what gets polished).
>
>Well that's a pretty straightforward admission that to this guy at least 
>literate programming is just an academic fad which enables you to get
>papers published, not a serious proposal to enhance the quality of our
 
M. Gray is 180 degrees out of phase.  Norman has at least one paper
(mentioned earlier) in LP, but his dissertation was on ``Retargettable
Debuggers'' and his professional work is more in that line, distributed
systems ..., I think.
 
If literate programming is an academic fad, I would like to know the
schools participating in this hype.  I am sure that I would be one of
the most guilty.  I have taught a graduate `special topics' course on
the subject twice and we are now experimenting with a freshman class.
Although there are several journals that encourage papers on LP, few
have appeared.  Some of us are trying to change those small numbers,
but fad it is not.
 
Keywords: 
 
From George Fri Sep 24 14:32:50 CST 1993
Date: Fri, 24 Sep 1993 14:32:50 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: bg@dymaxion.ns.ca
Subject: RE: VMS Clip via SHSU gopher (Was:DOWNFor the news distribution)
 
On Fri, 24 Sep 1993 15:25:04 ADT, Ben Armstrong <bg@dymaxion.ns.ca> posted
privately:
> I tried to access the VAX/VMS entry under Clip and got "Nothing Available". 
> What's the problem?
 
When I pulled the files over from sun01.info.wau.nl sometime earlier this
year, the files were present for the ms_dos subdirectory only (I inquired
at the time and someone -- I don't think it was Eric van Ammers, though --
told me that there was a problem with the VMS distribution and it had been
removed.  I just checked its host and the files were present in the vax_vms
subdirectory, and I fetched them, but.....  
 
Some of the files are VMS executables (i.e., they should possess some
specific RMS file characteristics) and I tried to tweak them every way I
know of and was unable to get any of the executables to run under VMS
(5.4-2).  By default, some of these files will not be gopherable (at least
until I verify that they work somehow); if you just *have* to have them
(although they are, IMO, broken -- at least until someone enlightens me on
how to run them under VMS) they are available for anonymous ftp retrieval
from Niord.SHSU.edu in [FILESERV.CLIP.CLIP-1_0.VAX_VMS].
 
Might anyone know where a VMS set for CLiP resides so I can get t
into the archives here??
 
--George
 
From preston@cs.rice.edu Fri Sep 24 15:49:06 CDT 1993
Date: Fri, 24 Sep 93 15:49:06 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: What does literate programming mean to you?
 
zen@death.corp.sun.com writes a lot of stuff.  I won't quote it.
He says I'm a hypocrite for writing nuweb in a less-than-perfectly-literate
fashion.  I disagree.  I'm not preaching LP, I'm just a user.
 
I wrote nuweb and I use it.  Since I also boss some
programmers, I make them use nuweb.  Some of my friends here use it,
and many people in the newsgroup use it.
 
Why?  Because it's got a nice combination of features.
It provides value at very little cost.
The question of how it's coded is an entirely orthogonal issue.
 
In fact, I'd say there are 3 orthogonal issues here (and these apply to
nuweb, noweb, cweb, ...)
 
        1) The "language" definition -- the features (and misfeatures) of
           the system
 
        2) The actual collection of tools that support the language
           (in the case of web, the tangle and weave programs, and maybe
            the TeX processor and Pascal compiler)
 
        3) How each of the tools is implemented
 
The interesting part to me, and perhaps others, is behind door number 1.
Door #2 is also interesting to many people who'd like to use nuweb
(or noweb or cweb or whatever).  They actually want to run the code!
As a user, I have an interest in this part too.
 
Door #3 is, in the case of nuweb, quite dull.
It's a straightforward programming task and I wouldn't hesitate to
give it to any undergraduate.
 
When I give out copies of nuweb and people send me comments, they send
me, by and large, suggestions and complaints about the language and
capabilities.  This is great; just the sort of feedback I'm interested in.
Sometimes people point out portability problems, usually with fixes.
That's great too; we fix them and get back to the interesting questions.
Nobody has commented on how I implement my state machines or how I
parse command-line arguments or how I allocate memory.  Why?  Because
those're just boring details.  I'm not trying to teach people how to program,
I'm trying to learn what makes a nice language for LP.
 
>have you read knuth and his experiences, when he first starts to program
>a large project, and why he believes in literate programming?
 
Yes, I believe I've read everything Knuth has published about programming.
I also believe I've read everything that's been published about LP.
Why, praytell?  Are we not to think and experiment for ourselves?
 
I also wrote:
> It's just a tool,
> not an end in itself.  A hammer doesn't need a dissertation attached to
> be useful.
 
and zen@death notes
>  It's just an amazing statement, esp. on this newsgroup.  But to
>address it again, your program isn't a hammer.
 
No, it's really an experiment with the idea of hammering, kind of like
a big, flat rock.  It's Preston, the caveman programmer, saying "Guys,
look at this!  You can beat on things even harder than with your fist.
Hmmm... Do you think it needs a handle?  Yeah, look!  It's even better."
 
>you have to communicate to the user what it can and should be
>used for (claw vs sledge hammers, for instance).
 
But nobody knows these things, least of all me.
We're all very interested in what it might be good for and we find out more
all the time.  And someday, someone is going to have a drastically better idea
and I'm going to let nuweb die.  For example, noweb has a some ideas I really
like.  If, after some experience, I'm persuaded that his approach is better,
I'll switch.  It isn't a matter of how nuweb is written, it's a matter of
the language design.  In fact, I could fairly easily adapt my program to
handle noweb source rather than nuweb source,
so I'd claim (again!) that the tool and the language are seperate entities.
 
>  I find it amazingly ironic that a program to do literate program isn't
>written in a literate manner, but far more ironic that the programmer
>behind it thinks that it was the right thing to do.
 
If I wrote an assembler, I'd write it in a higher-level language.
I am writing a Fortran compiler in C.  Further, I don't write in either
assembler or Fortran.  The irony is just overwhelming!?
 
Preston Briggs
 
From zen@death.corp.sun.com Fri Sep 24 15:49:06 CDT 1993
Date: Fri, 24 Sep 93 15:49:06 CDT
From: zen@death.corp.sun.com (d ... 415-336-0742)
Reply-To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
To: LitProg@SHSU.EDU
Subject: literate books 'n' stuff
 
Any "must have/read" stuff out there that people would care to share?
Other than donald knuth and jon bentley, that is, my two fav's for
what I refer to as literate programming (I sometimes include _the
mythical man month_ for a similar kind of philosophy on a strategic,
rather than tactical, level; I was very pleased to see knuth include
a few chapters by bentley in his recent book).
 
I greatly appreciate the *readability* of both these authors published
work (though esp. knuth can get a bit terse/dense) as well, which speaks
well to their philosophy, although I wish bentley would do more than
rehashing old stuff in his "software exploritorium" columns (or whatever
the title is.)
 
 -- d
 
From perin@cumc.cornell.edu Fri Sep 24 15:49:06 CDT 1993
Date: Fri, 24 Sep 93 15:49:06 CDT
From: perin@cumc.cornell.edu (Lewis Perin)
Reply-To: LitProg@SHSU.edu, perin@cumc.cornell.edu
To: LitProg@SHSU.EDU
Subject: Re: Big programs, separate files, "unnecessary" recompilations
 
In article <MFY.93Sep24144216@ravel.sli.com> mfy@sli.com (Mike Yoder)
writes:
 
>Lewis Perrin wrote, in response to my deathless prose:
 
(One "r" in the surname, please)
 
>>Unless I'm missing something this doesn't conquer the problem.  Those of us
>>who don't get their code right the first time (disgusting wretches we,
>>failing even with LP tools;-) tend to rely on our tangles inserting hints to
>>the target language debugger as to where in the web the source code can be
>>found.  Trouble is, change the documentation significantly and the locations
>>will change.
>>
>>If the source code hasn't changed but has been relocated in the web, a
>>tangle smart enough to notice this can either go ahead and fool make (good)
>>and the debugger (bad), or it can let the compilation steps cascade.  Right?
 
>You did miss something, but only because I omitted to tell you.  Inscribe
>automatically inserts #line directives for generated C and C++ files, so the
>debugger's source is the Inscribe source in those cases; I call this "direct
>debuggability," which may be my private jargon, but I think I appropriated the
>term from people in this forum.  It would be simple to generate equivalent
>directives for other languages if their compilers paid attention to them, e.g
>"pragma Line" for an Ada compiler.
 
OK, Inscribe does what CWEB, FWEB and noweb (at least) do in this
respect.  Sorry, but I still don't see how this gets around the
dilemma of code relocation within the web mentioned in the second
paragraph of my original posting.
 
>Also, I have an Emacs function which lets me find the Inscribe line which
>corresponds to line N of a given produced file: thus if the compiler says I
>have an error on line 32 of Pascal file foo.p, I find some occurrence of
source
>for foo.p and invoke "C-Z g" with an argument of 32, and it goes to the
>appropriate place.  This is crude but quite effective and reliable.
 
Yes, but will the *debugger* find the code if the latter's been relocated
without being recompiled?
 
Cheers,
______________________________________________________
      __          perin@cumc.cornell.edu (212)746-2946
 |   |_  \    / : Lew Perin
 |__ |__  \/\/  : Home: (201)435-2679
 
From koopman@sgi84.ctc.com Fri Sep 24 18:07:19 -0400 1993
Date: Fri, 24 Sep 93 18:07:19 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
Subject: What does literate programming mean to you?
 
zen@DEATH.CORP.SUN.COM responding to Bradley K. Sherman:
>> The literate programmer is a poet not a novelist.
>
>  Poetry can obscure meanings.  I'd rather read code written in the
>style of dickens rather than e.e. cummings... to me, I think the key is
>functionality and clarity first, not style.  I wonder if people here
>view LP'ing as more of an art form, something that has inherent
>usefulness, or as a vehicle to produce "better" (whatever that means)
>programs.
 
Which is e.e. cummings and which is Dickens: 'C'syntax or CWEB?
Certainly code scraps come on little cat paws and fog the purpose of
the particular implementation.  This is especially true of the seldom
commented nuances; the "real" work the programmer labored over.
 
>  I would hope, in addition to everything else, the LP would be
>concerned that programs written in the literate style actually work
 
Interpolating Preston Briggs:
>>  It'll get more complete as I spend more effort on it.  In the
>>meantime, I (and others) are able to use it without worrying about
>>whether I've finished describing it all.  It's just a tool, not an end
>>in itself.  A hammer doesn't need a dissertation attached to be
>>useful.
 
I view a program as an art form analogous to a symphony.  There *is*
elegant code.  Preston Briggs discussed one of his "unfinished"
symphonies.  The symphony is played for the end user.  Literate
programming is just an improvement in the sheet music.
 
Mike Koopman <koopman@ctc.com>
 
From perin@cumc.cornell.edu Fri Sep 24 18:07:19 -0400 1993
Date: Fri, 24 Sep 93 18:07:19 -0400
From: perin@cumc.cornell.edu (Lewis Perin)
Reply-To: LitProg@SHSU.edu, perin@cumc.cornell.edu
To: LitProg@SHSU.EDU
Subject: What does literate programming mean to you?
 
A certain amount of hell's broken loose on LitProg since two of our favorite
tool builders have "confessed" to what some regard as sins.  Perhaps an
analogy will convince the Calvinists that Briggs and Ramsey do deserve the
respect they've long enjoyed here.
 
Think of literacy *outside* the realm of programming.  We communicate with
each other for many purposes, and to each purpose a certain amount of
precision is appropriate.  In informal conversation, if I tried
to be as clear as I've hopefully been in some academic ventures, the person
sitting next to me would stalk off impatiently before I got my first word
off!  Informal conversation isn't *worse* than the writing of a formal
paper, it's just *different*.
 
Where I work, they're nice enough to pay me to write C++ "even though" I use
CWEB.  The webs are arranged for narrative coherence up to a point (I'd go
crazy if I hadn't the ability to rearrange scraps), and there are plenty of
grammatical English paragraphs free of the restrictions of C++ commenting,
but none of it's publishable.  Sure, this is a compromise, but a tenable one
in my opinion.
 
As I remember, Kafka wrote reports for an insurance company by day, writing
his lucid stories on his own time.  Presumably his case reports were above
average in clarity, but he'd have been fired quickly if he'd given them the
care he devoted to his fiction.
 
Cheers,
______________________________________________________
      __          perin@cumc.cornell.edu (212)746-2946
 |   |_  \    / : Lew Perin
 |__ |__  \/\/  : Home: (201)435-2679
 
From norman@bellcore.com Fri Sep 24 19:15:22 -0400 1993
Date: Fri, 24 Sep 93 19:15:22 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, cgra@se.alcbel.be
Subject: Re: What does literate programming mean to you?
 
I wrote:
> >[...]I tolerate my ugly ``literate'' programs because in my work a program
> >is seldom an artifact of the first importance.   Far more often the
> >paper is what matters (and what gets polished).
 
And Chris Gray responds:
 
> Well that's a pretty straightforward admission that to this guy at least 
> literate programming is just an academic fad which enables you to get
> papers published, not a serious proposal to enhance the quality of our
> programs (and our lives).  
 
I think Mr. Gray is slightly misinformed about publication.  The days
of literate programming as a publishing fad have come and gone.  Major
publications are not amused by article about literate programming, and
papers on literate program do not weigh heavily with those who play
the publication game.  So *I* wouldn't waste *my* time on literate
programming if all I cared about was getting published.
 
I will now follow up with yet another variation on my standard polemic
about literate programming.  Longtime readers may want to skip it :-)
 
The single, sad truth that Mr. Gray has unwittingly uttered is that
after nine years literate programming is still at the proposal stage.
It is *proposed* that literate programming will improve the quality of
our programs.  There's almost no evidence in favor of this
proposition.  The only cases I know of in which literate programming
was used for production code and someone troubled to evaluate the
results are Knuth's ``Errors of TeX'' and my ``Literate programming on
a team project'' (with Carla Marceau).
 
There's little evidence that literate-programming tools can really
give us better programs (although there are True Believers, of whom I
am one).  There is no method that tells one *how* to apply
literate-programming tools to get good results.  If I had the evidence
and the method, I could take *any* of the existing tools to our
development organization and put them into use.  If I had only the
method, I might find a project that would be willing to gamble on the
results.  I could never go to a project and say ``here are some good
tools; if you use them you will get good results.''  I have seen what
damage novices can do with sharp instruments.
 
I am disappointed by the vast amount of work put into tools when what
we desparately need is an attempt at ``How (and how not) to write a
good literate program no matter what tool you are using.''  There are
endless implementations of tools and discussions of same because it's
much easier to write tools and to evaluate tools than it is to teach
people to program differently and to measure the quality of the
results.  Too bad.
 
Norman Ramsey
 
From karna@pobox.upenn.edu Fri Sep 24 19:15:22 -0400 1993
Date: Fri, 24 Sep 93 19:15:22 -0400
From: karna@pobox.upenn.edu (Animesh Karna)
Reply-To: LitProg@SHSU.edu, karna@POBOX.UPENN.EDU
To: LitProg@SHSU.EDU
Subject: Re: Readable programs -- an alternative to Web, Tangle and Weave
 
:  IMHO you are missing a lot if you just rely on commenting. Just try
: nuweb or noweb. You also get to arrange your code in a more 
: understandable way (good for during the initial design phase). Need to
: live with LaTeX though! I like the printed stuff but in your case 
: if you are using DOS/Windows try WinWordWEB, this is a WYSIWYG system. May
: be others are working on a unix/X system. 
: This way you dont have to make up a strict commenting system and 
: remember how to use it!  
 
This WinWordWEB sounds interesting . . . is it available via anon. ftp? 
If so, at what sight?  Thanks!
 
--
Definition of the PC Movement: It's what happens when Liberals start acting
like Conservatives.
 
From zen@death.corp.sun.com Fri Sep 24 19:15:22 -0400 1993
Date: Fri, 24 Sep 93 19:15:22 -0400
From: zen@death.corp.sun.com (d ... 415-336-0742)
Reply-To: LitProg@SHSU.edu, zen@DEATH.CORP.SUN.COM
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <9309242049.AA19181@dawn.cs.rice.edu> preston@cs.rice.edu (Preston Briggs) writes:
   zen@death.corp.sun.com writes a lot of stuff.  I won't quote it.
>   He says I'm a hypocrite for writing nuweb in a less-than-perfectly-literate
>   fashion.  I disagree.  I'm not preaching LP, I'm just a user.
 
As a clarification, I didn't say that you were hypocritical for writing
a literate tool using non-literate methods.  I said the *justification*
you used seemed hypocritical to *my* ideal literate programming.  I
didn't say, nor am I trying to imply that nuweb is a poor program at
all (I think the only thing I implied about nuweb is that it, like any
program, would be better if written in a literal fashion; I suppose we
would agree there, but that's not my issue.)
 
Ok, just a couple of points; specifics in where we disagree:
 
> The question of how it's coded is an entirely orthogonal issue.
> In fact, I'd say there are 3 orthogonal issues here [...]
>   1) The "language" definition -- the features (and misfeatures) of
>      the system
>   2) The actual collection of tools that support the language
>      (in the case of web, the tangle and weave programs, and maybe
>       the TeX processor and Pascal compiler)
>   3) How each of the tools is implemented
 
  Ideally, perhaps, features should be independent or implementation and
tools used and available.  I think, however, in practice, they are
connected; I would say especially #3, and perhaps even more so #2, how
they are implemented -- using literate programming or not -- is of
extreme importance, *iff* you believe that it adds to the value of the
program.  In addition, when you use these tools to build other systems
or tools, then it becomes even more important and non-orthogonal.  I
think that literate programming has less import in an ideal world than
in the real world for those same issues you mention.
 
> Nobody has commented on how I implement my state machines or how I
> parse command-line arguments or how I allocate memory.  Why?  Because
> those're just boring details.  I'm not trying to teach people how to program,
> I'm trying to learn what makes a nice language for LP.
 
  Perhaps people would comment on them, if they could read your code
(and I don't mean just making it available to them.)
 
 -- d
 
From ae1181t@stnfor.ae.ge.com Fri Sep 24 22:44:44 -0400 1993
Date: Fri, 24 Sep 1993 22:44:44 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, karna@POBOX.UPENN.EDU
Subject: Re: Readable programs -- an alternative to Web, Tangle and Weave
 
try niord.shsu.edu or pip.shsu.edu.
Osman
 
From fj@iesd.auc.dk Fri Sep 24 22:44:44 -0400 1993
Date: Fri, 24 Sep 1993 22:44:44 -0400
From: fj@iesd.auc.dk (Frank Jensen)
Reply-To: LitProg@SHSU.edu, fj@IESD.AUC.DK
To: LitProg@SHSU.EDU
Subject: Re: Big Programs & Separate files & Make & Incremental Compilation &
 
>>>>> On Fri, 24 Sep 1993 19:42:16 GMT, mfy@sli.com (Mike Yoder) said:
 
> Lewis Perrin wrote, in response to my deathless prose:
 
> >Unless I'm missing something this doesn't conquer the problem.  Those of us
> >who don't get their code right the first time (disgusting wretches we,
> >failing even with LP tools;-) tend to rely on our tangles inserting hints to
> >the target language debugger as to where in the web the source code can be
> >found.  Trouble is, change the documentation significantly and the locations
> >will change.
> >
> >If the source code hasn't changed but has been relocated in the web, a
> >tangle smart enough to notice this can either go ahead and fool make (good)
> >and the debugger (bad), or it can let the compilation steps cascade.  Right?
 
> You did miss something, but only because I omitted to tell you.  Inscribe
> automatically inserts #line directives for generated C and C++ files, so the
> debugger's source is the Inscribe source in those cases; I call this "direct
> debuggability," which may be my private jargon, but I think I appropriated the
> term from people in this forum.  It would be simple to generate equivalent
> directives for other languages if their compilers paid attention to them, e.g.
> "pragma Line" for an Ada compiler.
 
The original poster meant something different: he already has a tool
that inserts such #line directives in the tangled output files (C
source files).  The problem is that if you have one relatively large
web file that generates a number of C source files and you change
something near the beginning of the web file, then all the output
files will change (because the line numbers in the #line directives
change).  If you ignore this type of difference when you compare
files, then Make will not recompile the files, but the debugger will
be confused because it relies on the #line directives to identify
offending code.  Or you don't ignore the difference, i.e., all files
will compare unequal and recompilation will take a long time.
 
The real source of the problem is that the web is contained in one
file.  The way I solve this problem is to have one web file that
includes a lot of small web files.  Each of these small web files
corresponds to one C source file.  Thus, if I edit one of the small
web files, it won't affect the line numbers of all the other files,
and recompilation will be fast and the debugger will not be confused.
 
---
Frank Jensen,   fj@iesd.auc.dk
Department of Mathematics and Computer Science
Aalborg University
DENMARK
 
From oauld@ponder.csci.unt.edu Sat Sep 25 18:40:20 GMT 1993
Date: Sat, 25 Sep 1993 18:40:20 GMT
From: oauld@ponder.csci.unt.edu (Orion Auld)
Reply-To: LitProg@SHSU.edu, oauld@PONDER.CSCI.UNT.EDU
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In <ZEN.93Sep24093228@death.corp.sun.com> zen@death.corp.sun.com (d ... 415-336-0742) writes:
 
>In article <9309241359.AA09604@dawn.cs.rice.edu> preston@cs.rice.edu (Preston Briggs) writes:
>> I wrote:
>> >I have to consider it [nuweb] incomplete.
>> >It'll get more complete as I spend more effort on it.
>> and zen@death.corp.sun.com (somebody?  That's me!) writes:
>> >Talk about justifying your actions... you could say the same thing about
>> >any tool or program -- they're just not finished.
>> Of course I justify my actions; what did you expect?
 
>  No less, of course.  The point I was trying to make was that your
>justification was being hypocritical to the (*grin* -- well, *my* ideal,
>of course!) ideal of literate programming.
 
You may be a literate programmer, but your degree of English literacy is
underwhelming.  The word "hypocritical" implies a contradiction of self, not
a contradiction of someone else, and hence is usually regarded as being much
more serious.  Perhaps you meant to use "contradictory", in which case you
would have to specify an object.
 
-- 
***** Orion Auld *****     *----------------------------------------------*
"We are only fabulous      | "Men go crazy in congregations but they only |
 beasts, after all."       |     get better one by one."  Gordon Sumner   |
 -- John Ashberry          *----------------------------------------------*
 
From ross@wattle.itd.adelaide.edu.au Sun Sep 26 00:09:38 GMT 1993
Date: Sun, 26 Sep 1993 00:09:38 GMT
From: ross@wattle.itd.adelaide.edu.au (Ross Williams)
Reply-To: LitProg@SHSU.edu, ross@WATTLE.ITD.ADELAIDE.EDU.AU
To: LitProg@SHSU.EDU
Subject: FunnelWeb - a practical literate programming tool.
 
Netters,
 
I've just noticed this newsgroup so I thought I'd put in a free plug
for FunnelWeb. Ra ra!
 
FunnelWeb is not the most sophisticated literate programming tool
around, but I truly believe that it is one of the most practical. I've
engineered it for simplicity and portability and reliability, and it's
well documented. It has almost no bugs. I think it's a good entry
point for anyone wishing to try out literate programming.
 
Ross Williams
 
+--------------------------------------------------------------+
| Name    : Dr Ross N. Williams                                |
| Company : RockSoft Pty Ltd    (Reg TM Australia, TM USA)     |
| Net     : ross@guest.adelaide.edu.au.                        |
| Fax     : +61 8 373-4911    24 hours                         |
| Phone   : +61 8 379-9217    24 hours                         |
| Snail   : 16 Lerwick Avenue, Hazelwood Park 5066, Australia  |
| Archive : ftp.adelaide.edu.au/pub/compression and /funnelweb |
+--------------------------------------------------------------+
 
FUNNELWEB
 
FunnelWeb is a production-quality literate-programming tool that emphasises
simplicity and reliability. It provides a macro facility, and assists in the
production of typeset documentation. FunnelWeb runs on most popular machines
(Sun, VAX, Mac, PC) and its highly portable source code in C is freely
available under a GNU license.
 
Features:
   + Provides a simple macro preprocessor facility.
   + Assists in the generation of typeset documentation.
   + Runs on Sun, VMS VAX, Macintosh, and PC.
   + Portable C source code distributed under GNU licence.
   + Comprehensive user's manual (115 pages).
   + Input-programming-language independent.
   + Allows complete control over the output text.
   + Regression test suite with over 200 tests.
   - Requires TeX to produce typeset documentation.
   - Typesets program code using TT font only.
 
How to Obtain FunnelWeb
-----------------------
FunnelWeb can be obtained by anonymous FTP from:
 
Machine  : ftp.adelaide.edu.au
File     : ~pub/funnelweb/
 
FUNNELWEB CUSTOMER TESTIMONIALS
 
"I've been fooling around with FunnelWeb for about three days now, and
I'm convinced that this is one of the most powerful tools I have
encountered in almost two decades of programming. I'm in the process
of converting several thousand lines of very repetitive code to
FunnelWeb macros; I can't believe how EASY it is, and how GOOD the
resulting source code and documentation are. Thank you for this tool!"
 
        -- Jerry Callen (jcallen@world.std.com)
           Runtime Engineer,
           Thinking Machines Corporation,
           Boston, USA.
           22-Jun-1992 (Authorized to be quoted 16-Oct-1992).
 
"I really like the 'quality' of the FW distribution. Well done Ross!
I cannot call it 'professional quality' because much of the
'professional' software I have seen has been VERY POOR.  Your package
is better than 'professional', but I don't know of an appropriate
adjective."
 
        -- George Vokalek (gvokalek@augean.eleceng.adelaide.edu.au).
           Hardware Engineer,
           University of Adelaide,
           South Australia, Australia.
           14-Jun-1992 (Authorized to be quoted 18-Oct-1992).
 
"I have used FunnelWeb on two ASSEMBLER modules. Written for a
microcontroller with NO DEBUGGING POSSIBLE, so correctness and
emphasis on getting it right was important.
 
I found it forced me to reorganise the code a bit, to get my concepts
straight. By the time I did this, and documented what I was doing,
[including a C version of an algorithm in one module] It looked good,
and worked in a few passes.
 
I am VERY happy with the results. ...
 
And, I got a very nice listing to present the customer!!"
 
        -- John Skaller (maxtal@extro.ucc.su.oz.au)
           Maxtal Pty Ltd,
           Sydney, Australia.
           09-Jul-1992 (Authorized to be quoted 17-Oct-1992).
 
"...the manual is about 10 times better than any other user manual
I've ever read."
 
        -- Barry Dwyer (dwyer@cs.adelaide.edu.au)
           Senior Lecturer, Department of Computer Science,
           The University of Adelaide.
           Australia.
           17-Jun-1992 (Authorized to be quoted 21-Oct-1992).
 
"I've done the regression testing, and it worked without a hitch.
You've done a nice job making the sucker portable. My system is a mono
NeXTstation running NeXTSTEP 2.1 with 16 MB of RAM."
 
        --John Dawson (john@arissoft.com)
          Software Developer,
          Arissoft Development Corporation,
          Texas, USA.
          11-Jun-1992. (Authorized to be quoted 17-Oct-1992).
 
--<End of Posting>--
 
From nts3cjc@cabell.vcu.edu Sun Sep 26 00:09:38 GMT 1993
Date: Sun, 26 Sep 1993 00:09:38 GMT
From: nts3cjc@cabell.vcu.edu (Christopher J. Cioffi)
Reply-To: LitProg@SHSU.edu, nts3cjc@CABELL.VCU.EDU
To: LitProg@SHSU.EDU
Subject: FAQ for c.p.l.??
 
Hello,
 
Is there a FAQ for this group??  If so, where?  Thanks.
 
Chris
 
From ross@wattle.itd.adelaide.edu.au Sun Sep 26 00:09:38 GMT 1993
Date: Sun, 26 Sep 1993 00:09:38 GMT
From: ross@wattle.itd.adelaide.edu.au (Ross Williams)
Reply-To: LitProg@SHSU.edu, ross@WATTLE.ITD.ADELAIDE.EDU.AU
To: LitProg@SHSU.EDU
Subject: What literate progamming means to me.
 
Netters,
 
There has been some discussion in this newsgroup of "what literate
programming means to me". I thought I'd put in my two cents worth.
 
Ross.
 
+--------------------------------------------------------------+
| Name    : Dr Ross N. Williams                                |
| Company : RockSoft Pty Ltd    (Reg TM Australia, TM USA)     |
| Net     : ross@guest.adelaide.edu.au.                        |
| Fax     : +61 8 373-4911    24 hours                         |
| Phone   : +61 8 379-9217    24 hours                         |
| Snail   : 16 Lerwick Avenue, Hazelwood Park 5066, Australia  |
| Archive : ftp.adelaide.edu.au/pub/compression and /funnelweb |
+--------------------------------------------------------------+
 
What is Literate Programming?
-----------------------------
(From Chapter 1 of The FunnelWeb Manual. FunnelWeb is available from
ftp.adelaide.edu.au/pub/funnelweb.)
 
"In literate programming the emphasis is reversed. Instead of writing
code containing documentation, the literate programmer writes
documentation containing code.
 
...
 
The effect of this simple shift of emphasis can be so profound as to
change one's whole approach to programming. Under the literate
programming paradigm, the central activity of programming becomes that
of conveying meaning to other intelligent beings rather than merely
convincing the computer to behave in a particular way. It is the
difference between performing and exposing a magic trick.
 
...
 
With this structure in place, the literate programming system can
provide far more than just a reversal of the priority of comments and
code. In its full blown form, a good literate programming facility can
provide total support for the essential thrust of literate
programming, which is that computer programs should be written more
for the human reader than for the compiler.
 
...
 
In the end, the details don't matter. The most significant benefit
that literate programming offers is ITS CAPACITY TO TRANSFORM THE
STATE OF MIND OF THE PROGRAMMER. It is now legend that the act of
explaining something can transform one's understanding of it. This is
one of the justifications behind the powerful combination of research
and teaching in universities. Similarly, by constantly explaining the
unfolding program code in English to an imaginary reader, the
programmer transforms his perception of the code, laying it open,
prone, to the critical eye.
 
The result of this exposure is a higher quality of programming. When
exposed to the harsh light of the literate eye, bugs crawl out,
special cases vanish, and sloppy code evaporates. ... Thus literate
programming does not merely assist in the preparation of
documentation, but also makes significant contributes to the process
of programming itself. In practice this has turned out to be a
contribution far more important than the mere capacity to produce
typeset documentation."
 
--<End of Posting>--
 
From tzs@stein1.u.washington.edu Sun Sep 26 00:09:38 GMT 1993
Date: Sun, 26 Sep 1993 00:09:38 GMT
From: tzs@stein1.u.washington.edu (Tim Smith)
Reply-To: LitProg@SHSU.edu, tzs@STEIN1.U.WASHINGTON.EDU
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <CDtIJn.59p@austin.ibm.com>,
>> 	d = c+1/c;		//guaranttees: d>2
..
>> assertion at line 7 (d>2) not guarantteed. Best possible: d>=2.
>
>I think you mean
>
>assertion at line 7 (d>2) not guaranteed. Best possible: d>=0.
>
>Consider the case of c == 2 (which makes d = 1.5) .
 
Ever hear of precedence?  c+1/c means c+(1/c), not (c+1)/c.
 
--Tim Smith
-- 
"Pope moved that we strike from the State's brief and appendix a selection from
the Year Book of 1484 written in Medieval Latin and references thereto.  The
State provided no translation and conceded a total lack of knowledge of what it
meant.  The motion is granted"  396 A.2d 1054                       --Tim Smith
 
From marcus@x4u.desy.de Sun Sep 26 12:57:06 GMT 1993
Date: Sun, 26 Sep 1993 12:57:06 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: FAQ for c.p.l.??
 
>>>>> On Sun, 26 Sep 1993 00:09:38 GMT, nts3cjc@cabell.vcu.edu (Christopher J. Cioffi) said:
 
Christopher> Is there a FAQ for this group??  If so, where?  Thanks.
 
i am working on an update for the fweb faq, for fweb v1.30.
it will  have to go to john krommes for his comments, and to
news-answers-request@mit.edu for approval as a usenet faq.
all this will probably not be done before end of october.
 
Below is info how to get the old version.
 
------------------------------------------------------------------------ 
   FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg:
   You may obtain the latest version of this FAQ via anonymous FTP from
   - `ftp.desy.de' [141.34.1.2] in directory `/pub/faq/web/fweb' [EUROPE]
   - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]' [USA]
  [Either as .texi, .dvi, .ps, .info or plain text file, makefile 
   included.]
 
   NEW: you can now access a wealth of Literate Programming documents,
   including the FWEB FAQ, on the World Wide Web [WWW] at
         http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
   If you dont know about WWW, but you are on the Internet, try
         telnet info.cern.ch
   then type 
         go http://info.desy.de:80/gnu/ftp/pub/www/projects/LitProg.html
   at the prompt to go to the LitProg documents. If you don't happen to
   have telnet on your computer, but you are at an Internet mail gateway,
   send email to listserv@info.cern.ch with a line in it saying
	 HELP
   to get back instructions how to access WWW documents via mail.
-------------------------------------------------------------------------
 
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From xiao@ie.utoronto.ca Sun Sep 26 16:46:57 GMT 1993
Date: Sun, 26 Sep 1993 16:46:57 GMT
From: xiao@ie.utoronto.ca (Yan Xiao)
Reply-To: LitProg@SHSU.edu, xiao@IE.UTORONTO.CA
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
tzs@stein1.u.washington.edu (Tim Smith) writes:
 
>In article <CDtIJn.59p@austin.ibm.com>,
>>> 	d = c+1/c;		//guaranttees: d>2
>..
>>> assertion at line 7 (d>2) not guarantteed. Best possible: d>=2.
>>
>>I think you mean
>>
>>assertion at line 7 (d>2) not guaranteed. Best possible: d>=0.
>>
>>Consider the case of c == 2 (which makes d = 1.5) .
 
>Ever hear of precedence?  c+1/c means c+(1/c), not (c+1)/c.
 
Consider the case of c = -1.  d = (-1) + ( 1/(-1)) = (-1) + (-1) = -2.
Or worse when c = 0.
 
I missed something or what!?  Should this group be better called 
comp.programming.ILliterate?
 
On a serious side, I haven't heard people mentioning a tool
called FlexOr, developped by a fellow (Gunnar) at York University.
It really looks like Web to me, though.
 
Xiao
Yan Xiao, Department of Industrial Engineering, University of Toronto
4 Taddle Creek Road, Toronto, Ontario, M5S 1A4
 
- "What, doc? 500 bucks for putting me to sleep!?!"
- "Well, it only takes 50 to do that, but it takes 450 to wake yo up"
 
From David Sun Sep 26 14:18:41 -0400 1993
Date: Sun, 26 Sep 1993 14:18:41 -0400
From: David Reeve Sward <sward+@CMU.EDU>
Reply-To: LitProg@SHSU.edu, sward+@CMU.EDU
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
Excerpts from netnews.comp.programming.literate: 26-Sep-93 Re: What does
literate prog.. by Yan Xiao@ie.utoronto.ca 
> >>>     d = c+1/c;              //guaranttees: d>2
>  
> Consider the case of c = -1.  d = (-1) + ( 1/(-1)) = (-1) + (-1) = -2.
> Or worse when c = 0.
>  
> I missed something or what!?  Should this group be better called 
> comp.programming.ILliterate?
 
There was a previous assertion of c>0.
-- 
David Sward     sward+@cmu.edu     Finger or email for PGP public key 3D567F
Encryption is an envelope for your email; read alt.security.pgp for details.
 
From sven@robots.ox.ac.uk Sun Sep 26 21:29:17 GMT 1993
Date: Sun, 26 Sep 1993 21:29:17 GMT
From: sven@robots.ox.ac.uk (Sven Utcke)
Reply-To: LitProg@SHSU.edu, sven@ROBOTS.OX.AC.UK
To: LitProg@SHSU.EDU
Subject: footnotes in FWEB
 
Yes, I know it's a FAQ (it's also in the FWEB-FAQ).
 
Only:
 
a) I deleted it (stupid me).
 
b) I tried the "hint" given in the FAQ about a month ago --- without
   even the slightest bit of success. I'm obviously not bright enough
   to follow the FAQ's advise. I therefore need someone who will tell
   me how to do it in that slow and methodical way normally used with
   imbeciles.
 
And is there any way to get margin notes (get \marginpar to work)?
 
Also something else: Does Funnelweb work with LaTeX?
 
Thanks for you help
 
Sven
 
From ross@wattle.itd.adelaide.edu.au Sun Sep 26 21:29:17 GMT 1993
Date: Sun, 26 Sep 1993 21:29:17 GMT
From: ross@wattle.itd.adelaide.edu.au (Ross Williams)
Reply-To: LitProg@SHSU.edu, ross@WATTLE.ITD.ADELAIDE.EDU.AU
To: LitProg@SHSU.EDU
Subject: Literate implementations of literate tools.
 
I've noticed someone suggesting that it is hypocritical to write a
literate programming tool in a non-literate style.
 
I disagree. Writing a literate tool using itself is just asking for
trouble. What if the only executable is accidentally deleted?! Better
to keep the implementation of the literate tool "clean".
 
I wrote FunnelWeb in raw C on purpose. My attitude was: "One million
billion non-literate programs have already been written. For the sake
of implementation safety, just one more won't hurt." Of course, I
haven't written an illiterate program since.
 
:-)
 
Ross.
 
+--------------------------------------------------------------+
| Name    : Dr Ross N. Williams                                |
| Company : RockSoft Pty Ltd    (Reg TM Australia, TM USA)     |
| Net     : ross@guest.adelaide.edu.au.                        |
| Fax     : +61 8 373-4911    24 hours                         |
| Phone   : +61 8 379-9217    24 hours                         |
| Snail   : 16 Lerwick Avenue, Hazelwood Park 5066, Australia  |
| Archive : ftp.adelaide.edu.au/pub/compression and /funnelweb |
+--------------------------------------------------------------+
 
From seiferth@bandelier.cs.unm.edu Mon Sep 27 00:59:39 GMT 1993
Date: Mon, 27 Sep 1993 00:59:39 GMT
From: seiferth@bandelier.cs.unm.edu (Justin Seiferth)
Reply-To: LitProg@SHSU.edu, seiferth@BANDELIER.CS.UNM.EDU
To: LitProg@SHSU.EDU
Subject: Printing funnelweb documentation
 
Have you managed to turn the funnelweb documentation into a postscript
document?  I'm no TeX/LaTeX weanie and have been unable to figure out
why I can't process the tex documents which come with the distribution.
My attempts to process the documents result in the following error:
 
% latex u_manual.tex
This is TeX, C Version 3.14t3
(u_manual.tex
! Undefined control sequence.
l.73 \documentstyle
		   [titlepage]{book}
		   ? 
 
If I type "RUN", a multitude of errors appear and a bogus .dvi file
(1 page long) is produced.
 
If someone could point me towards a ps copy of the documentation or
tell me how I can LaTeX the documents myself I'd greatly appreciate it.
 
Thanks...
Justin
seiferth@bandelier.cs.unm.edu
 
From dentato@aleph Mon Sep 27 10:45:37 +0100 1993
Date: Mon, 27 Sep 93 10:45:37 +0100
From: dentato@aleph
Reply-To: LitProg@SHSU.edu, dentato@ALEPH
To: LitProg@SHSU.edu
Subject: Re: What does literate programming mean to you?
 
Norman Ramsey said:
 
 >There's little evidence that literate-programming tools can really
 >give us better programs (although there are True Believers, of whom I
 >am one).  There is no method that tells one *how* to apply
 >literate-programming tools to get good results.
 
I'm a Tre Believer too, and I agree with you. Now the problem is:
there is such a method? As far I know there is no method to follow to write 
better novels, poems, and so on.
 
Now I became a little mistic: writing code (literate or not), painting, 
composing music and other are a sort of illuminatio: you can show the results to 
others, you can try to expalain your Way to others, but you can't give them a 
recipe to follow.
 
We could look for statical proof that literate programs are "better" (in some 
sense) but I don't know if there are enough test-cases.
 
I agree with you that the discussion shoul move to "How write literate 
programs", but I don't know how to start such a discussion!
 
I know that you (and many others in this list) have a long experience in the 
literate programming field, could you (and others) suggest a starting point on 
the topic ``How (and how not) to write a
good literate program no matter what tool you are using.''?
 
      ___ __          Universita' di Roma "La Sapienza"
     //_/// \         Dipartimento di Informatica e Sistemistica
    // \//__/         Via Buonarroti 12    00184 Roma  (Italy)
   Remo Dentato       tel: +39-6-4873689   fax: +39-6-4873628
                      email:  dentato@cadgroup.ing.uniroma1.it  
 
From cgra@se.alcbel.be Mon Sep 27 10:45:37 +0100 1993
Date: Mon, 27 Sep 93 10:45:37 +0100
From: cgra@se.alcbel.be (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <9309242315.AA15424@mailee.bellcore.com>, norman@bellcore.com writes:
Path: se.alcbel!alcbel!ub4b!mcsun!uunet!seismo!esosun.css.gov!mvb.saic.com!litprog
From: norman@bellcore.com
Newsgroups: comp.programming.literate
Subject: Re: What does literate programming mean to you?
Message-ID: <9309242315.AA15424@mailee.bellcore.com>
Date: 24 Sep 93 23:15:22 GMT
Organization: Litprog<==>Comp.Programming.Literate Gateway
Lines: 51
X-Gateway-Source-Info: Mailing List
 
Norman Ramsey wrote:
> >[...]I tolerate my ugly ``literate'' programs because in my work a program
> >is seldom an artifact of the first importance.   Far more often the
> >paper is what matters (and what gets polished).
 
And I responded:
 
> Well that's a pretty straightforward admission that to this guy at least 
> literate programming is just an academic fad which enables you to get
> papers published, not a serious proposal to enhance the quality of our
> programs (and our lives).  
 
To which Mr. (or possibly Dr.) Ramsey retorts:
 
>I think Mr. Gray is slightly misinformed about publication.  The days
>of literate programming as a publishing fad have come and gone.
 
Come to think of it I haven't seen a lot on the subject recently, and
my backlog of unread Computer Journals seems to be reaching the two-year
mark.  But the statement that that the program is unimportant compared
to the published paper did remind me of some of the less satisfying aspects
of my last job in an academic institution.
 
>[...]
>The single, sad truth that Mr. Gray has unwittingly uttered is that
>after nine years literate programming is still at the proposal stage.
 
Then maybe I should shut up and go away and implement the proposal.
That's the sort of thing I'm paid for anyway, not for shooting my
mouth off in inappropriate fora.
 
Bye,
 
Chris     (still 180 \deg out of phase, woleb ees)
__________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
__________________________________________________________________________
CanBe ( "(at-same-time C lisp FORTH) USING", confusing);
 
From dak@messua.informatik.rwth-aachen.de Mon Sep 27 10:45:37 +0100 1993
Date: Mon, 27 Sep 93 10:45:37 +0100
From: dak@messua.informatik.rwth-aachen.de (David Kastrup)
Reply-To: LitProg@SHSU.edu, dak@MESSUA.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.EDU
Subject: Re: Printing funnelweb documentation
 
seiferth@bandelier.cs.unm.edu (Justin Seiferth) writes:
 
>Have you managed to turn the funnelweb documentation into a postscript
>document?  I'm no TeX/LaTeX weanie and have been unable to figure out
>why I can't process the tex documents which come with the distribution.
>My attempts to process the documents result in the following error:
 
>% latex u_manual.tex
>This is TeX, C Version 3.14t3
>(u_manual.tex
>! Undefined control sequence.
>l.73 \documentstyle
>		   [titlepage]{book}
>		   ? 
 
>If I type "RUN", a multitude of errors appear and a bogus .dvi file
>(1 page long) is produced.
 
This looks as if your installation is at fault. Obviously, latex
does not call up LaTeX, but plain TeX (or virtex, maybe).
 
Try the following things:
latex "&lplain" u_manual
*or* write virtex or tex instead of latex. The double quotes are OS
specific. In unix, you need them to avoid shell interpretation
of &.
 
Your OS might or might not need them. If all else fails, try
latex (or tex, or virtex) <return>
tex gives a prompt
**
to which you type
&lplain u_manual <return>
If even this does not work, probably LaTeX was never installed at all at
your site. Try the nearest help.
-- 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From hallam@dxal18.cern.ch Mon Sep 27 14:17:42 GMT 1993
Date: Mon, 27 Sep 1993 14:17:42 GMT
From: hallam@dxal18.cern.ch (HALLAM-BAKER Phillip)
Reply-To: LitProg@SHSU.edu, hallam@alws.cern.ch
To: LitProg@SHSU.EDU
Subject: RE: New Math Notation #3107
 
In article <9309261452.memo.19736@BIX.com>, Jeffrey McArthur <j_mcarthur@BIX.com> writes:
 
|>[John Goodwin]
|>
|>|   <H2>Formulas in General</H2> This, of course, is the touchy part--what
|>|   to do with all those beloved Greek symbols, wierd connectives, and so
|>|   on.  Actually, except for fractions and the relative paucity of symbols
|>|   available, E-text can be fairly friendly towards Math.<P>
|>|   
|>|   FORTRAN and similar languages have tackled this problem admirably.
|>|   Probably a C-like notation would be preferred today (except for
|>|   exponents, which would likely use the FORTRAN).  One problem with C as
|>|   a standard is its use of E-mail unsafe characters, whence the infamous
|>|   ANSI trigraphs.  We need workable alternates for those.<P>
|>
|>I disagree strongly with these statements.  Literate Programming is an
|>attemp to FIX the serious problems with C and FORTRAN style notation.  C
|>and FORTRAN can be very difficult to understand.  Particularly if you are
|>doing vector or tensor calculations.  The notation used is almost
|>unintelligable.  Mathmatical notation is much cleaner.  That is why, using
|>literate programming, it is desirable to include as part of the program the
|>full mathmatical description.
|>
|>Literate programming uses additional fonts and symbols to make the code
|>much more intelligable.  Instead of using .NE., <>, or != to mean "not
|>equals", literate programs print and display the code using a standard
|>mathmatical not-equals sign.  Assignments are shown using a left pointing
|>arrow.  There are literate programming tools for C, C++, Fortran, Pascal,
|>Modula 2, and several others, as well as some "generic" literate
|>programming tools that let you define you own syntax.  Using literate
|>programming, array indicies are printed as subscripts.
|>
|>The proposal John Goodwin makes, is in complete opposition to one of the
|>basic ideas behind one of Usenet's newest newsgroups:
|>comp.programming.literate.
 
I don't see these ideas as mutually contradictory. Standard computer languages
are poor in this area, but standard maths is also poor in certain areas -
the use of juxtaposition to impy multiplication is a dreadful feature
for example that should be removed from standard notation. It prevents the
use of meaningful identifiers with multiple characters.
 
Using more than ISO-LATIN is obvioulsy the beginings of such a system.
but it is also important to realise that notation can also get in the way.
For example is blackboard bold P [] any easier to understand than PowerSet []?
 
Symbols are very usefull for ideas that recur frequently. They also have a cost
penalty since unless you know what they mean you have no clue as to their
function. There is a usefull compromise between insisting on the use
of the word plus to indicate addition and the use of a symbol to indicate
every posible function. 
 
--
Phillip M. Hallam-Baker
 
Not Speaking for anyone else.
 
From lbartho@scsun.unige.ch Mon Sep 27 16:41:15 GMT 1993
Date: Mon, 27 Sep 1993 16:41:15 GMT
From: lbartho@scsun.unige.ch (BARTHOLDI Laurent)
Reply-To: LitProg@SHSU.edu, lbartho@SCSUN.UNIGE.CH
To: LitProg@SHSU.EDU
Subject: Scheme-WEB & Knuth
 
Hi folks,
I was thinking about porting Knuth's WEB to Scheme, a LISP-like dialect.
I wanted to make sure nobody was on the same track; or (even worse)
that the whole thing had already been done.
If somebody has a useful tip to give me, I would also be welcome.
My intention was to modify the grammar rules in CWEB.
Thanks to all people whoe read this.
--
----------
That was Larry `Hacker' Bartholdi, University of Geneva, Switzerland
E-Mail:	lbartho@cui.unige.ch
S-Mail:	Larry Bartholdi
	Barillette 11
	1260 NYON
	Switzerlan
 
From rogerb@eiffel.demon.co.uk Mon Sep 27 16:44:10 +0000 1993
Date: Mon, 27 Sep 1993 16:44:10 +0000
From: rogerb@eiffel.demon.co.uk (Roger Browne)
Reply-To: LitProg@SHSU.edu, rogerb@eiffel.demon.co.uk
To: LitProg@SHSU.EDU
Subject: Literate Programming in Eiffel and PRO-IV
 
Hi,
 
If you are involved with Literate Programming using the PRO-IV 4GL
(which is ideal for literate business programming), I would be interested
to hear from you, as I have been using PRO-IV in this way for some years.
 
If you are involved with Literate Programming using Eiffel, I would also
be interested to hear from you, as I would like to hear about any
available tools or interesting techniques.
 
Eiffel already goes a small part of the way with its executable
assertions, expected comments in certain positions, short and flat
forms, indexing clause, obsolete clause, etc.
-- 
-- Roger Browne, 6 Bambers Walk, Wesham, PR4 3DG, UK   | Ph 0772-687525
-- Everything Eiffel: compilers/libraries/publications | +44-772-687525
 
From George Mon Sep 27 10:44:26 CST 1993
Date: Mon, 27 Sep 1993 10:44:26 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: What does literate programming mean to you?
 
On Fri, 24 Sep 93 19:15:22 -0400, Norman Ramsey <norman@bellcore.com>
posted:
>.....
> I think Mr. Gray is slightly misinformed about publication.  The days of
> literate programming as a publishing fad have come and gone.  Major
> publications are not amused by article about literate programming, and
> papers on literate program do not weigh heavily with those who play the
> publication game.  So *I* wouldn't waste *my* time on literate programming
> if all I cared about was getting published.
>.....
 
[As if I didn't already have enough to do with network stuff].  I've been
meaning to ask this for some time now of this group (for lurkers, news
newbies, and others who are unaware of it, while I proudly "own" the
LitProg list and you are sure to see my e-mail address more than you
probably would/will want, I am generally clueless about programming; I'm an
economist who enjoys the network).
 
What would the group think of a "refereed electronic periodical" for
literate programming; maybe "Literate Programming Review" or some other
less mundane name??  What I have in mind is a model we are developing for
economics -- you have the usual cadre of people, an editor, etc., with a
panel of blind reviewers; articles are submitted via e-mail to the editor,
who then strips author-identifying items, and forwards the submissions to a
subset of the reviewers; the reviewers comment on the submission to the
editor, who in turn forwards blind (stripped) reviews to the author; the
author makes modifications, resubmits, etc.  Once the reviewers and editor
say so, the article is ready for inclusion in a mail-based "journal" (which
can easily be linked into c.p.l).  The address for the journal is
completely private for posting -- only selected addresses (say, only the
editor) can post to it -- but completely public for subscriptions.  An
alias (or the direct editor's e-mail address) can be used for submissions.
 
As I see it, this would accomplish at least two things now missing and
sorely needed.  First, Norman's
>                                                               Major
> publications are not amused by article about literate programming,
is removed as a major journal, devoted exclusively to literate programming,
would exist.  It would be THE journal for this not-so-limited topic. 
Insofar as whether ot not it is a "journal", getting a unique ISSN for it
is not a concern.  Second, and IMO more important, it would have the
ability to provide examples (where literate programming is sorely lacking)
and discussions of real life constraints in both the philisophy as well as
application of this concept of programming, with reference to a specific
dimension covered in the article.
 
The electronic forum is an excellent place for this, IMO.  First, it will
be a long time before any major print periodical develops (or for a
dedicated space for the topic within an existing print periodical is
created) as I don't think a lot of people even understand the concept of
literate programming (while I admittedly am not a programer, my
understanding of its benefits makes me wonder why it is not more applied
than it appears to be; I often -- possibly mistakenly -- think that I have
a better conceptualization of literate programming than many professional
programmers out there who could really benefit from it).  Until the concept
is spread, this form of print-related distribution is just about out of the
question; without a distribution of some sort, the concept can't be spread
-- sort of a serious Catch-22.
 
Second, the costs of production and distribution (which, as a former editor
of a few print jourals, I can assure you are not trivial), as well as the
costs of start up are minimized (rapidly approaching zero).  Third, space
constraints, such as number of physical pages per issue, simply do not
exist in the electronic medium.  Fourth, and related to the items above,
periodicity is merely a side issue -- if a monthly format is used, with one
or 200 articles or a statement that "nothing is included this month", so be
it; the underlying concern is that the number of issues and when to expect
their distribution are basically fixed in nature.
 
I'm not offering to edit this, but I am more than willing to provide a few
resources to it (sort of serve as publisher, I guess) and discuss what can
and (IMO) should be considered in doing this.  It's a real opportunity for
the enhancement of literate programming to maybe gain wider acceptance.  If
anyone is interested, let me know.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From prechelt@i41s18.ira.uka.de Mon Sep 27 10:44:26 CST 1993
Date: Mon, 27 Sep 1993 10:44:26 CST
From: prechelt@i41s18.ira.uka.de (Lutz Prechelt)
Reply-To: LitProg@SHSU.edu, prechelt@I41S18.IRA.UKA.DE
To: LitProg@SHSU.EDU
Subject: FunnelWeb and LaTeX (was: footnotes in FWEB)
 
In article <1993Sep26.212917.28346@hotspur.robots.ox.ac.uk>, sven@robots.ox.ac.uk (Sven Utcke) writes:
...
|> Also something else: Does Funnelweb work with LaTeX?
 
If you begin with something like
 
@P typesetter = tex
\documentstyle....
\def\bye{\relax}
 
You can go straight ahead with LaTeX without problems.
If you want to use 11pt or 12pt style, however, you have to redefine
a number of commands used by FunnelWeb to select fonts.
 
  Lutz
 
-- 
Lutz Prechelt   (email: prechelt@ira.uka.de)            | Whenever you 
Institut fuer Programmstrukturen und Datenorganisation  | complicate things,
Universitaet Karlsruhe;  76128 Karlsruhe;  Germany      | they get
(Voice: ++49/721/608-4068, FAX: ++49/721/694092)        | less simple.
 
From Lee Mon Sep 27 12:50:26 EDT 1993
Date: Mon, 27 Sep 93 12:50:26 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, gurari@news.cis.ohio-state.edu
Subject: Re: What does literate programming mean to you?
 
Eitan Gurari (?) writes:
 
> I consider it a worthless effort to polish the exposition and
> appearance of literate programs that are not intended to be consumed
> by others (i.e., documents that are not intended for peer review---see
> norman's note).  Consequently, documents that serve as literate
> programs to me might be cryptic creatures to other readers.
 
I disagree.  The time spent polishing exposition, in my experience,
helps to find latent bugs.  In addition, the better the web looks, the
more likely I am to pass it around for an informal peer review (and
the more likely others are to actually read it).  I think a quote from
Kernighan & Plauger's "Elements of Programming Style" might be in
order here:
 
    One excuse for writing an unintelligible program is that it is a
	private matter.  Only the original programmer will ever look at
	it, and surely he need not spell out everything when he has it all
	in his head.  This can be a strong argument, particularly if you
	don't program professionally.  It is the same justification you
	use for writing ``qt milk, fish, big box'' for a grocery list
	instead of composing a proper sentence.  If the list is intended
	for someone else, of course, you had better specify what kind of
	fish you want and what should be inside that big box.  But even if
	only you personally want to understand the message, if it is to be
	readable a year from now you must write a complete sentence.  So
	in your diary you might write, ``Today I went to the supermarket
	and bought a quart of milk, a pound of halibut, and a big box of
	raisins.''
 
	You learn to write as if you someone else because ~next year you
	will be ``someone else.''
 
I must admit that I find even half-hearted webs (such as the source
for noweb -- sorry, Norman) easier to read (and modify) than well
documented & structured non-web code (such as the GNU project stuff)
that I've attempted to play with in the past.
 
My webbing style seems to focus on the documentation rather than the
code.  I'm not a formal program-prover, but I try to use the text
chunks (to use noweb terminology) to explain and ``prove'' the
algorithm.  The code chunks must match the documentation.  I do this
because I find it easier to reason in English than in C, Pascal, Awk,
or any other non-human language.  These days, when I find an error,
it is usually because incorrect code does not match correct
documentation, rather than the other way around.
 
Adding fuel to the fire,
 
		-- Lee
		   leew@pilot.njin.net
 
From dat91msu@ludat.lth.se Mon Sep 27 12:53:08 EDT 1993
Date: Mon, 27 Sep 93 12:53:08 EDT
From: dat91msu@ludat.lth.se (Martin Sunnerdahl)
Reply-To: LitProg@SHSU.edu, dat91msu@LUDAT.LTH.SE
To: LitProg@SHSU.EDU
Subject: Multiple 'find & replace'?
 
Hi.
A friend of mine is working as a translator, translating between Swedish and
Danish, two very similar language. He feels that it would save a vast amount of 
time if he could have a wordbank of, say, fivehundred words that he could use
for doing some kind of multiple 'search & replace' on his mac.
My question is this: is there a program that does multiple search and replace
(automated)? And where can he find it. I assume there must be a program like 
that out there, so please help me out!
 
 yrs, well, truly
 		 /Martin
 -
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 | Martin Sunnerdahl                   /. .\               Lilla Tvargat 14|
 | dat91msu@ludat.lth.se              [  ^  ]              S-22353 LUND    |
 | +46 46-126058                        |||                SWEDEN          |
 | 	   -V I  V E R I  V E N I V E R S U M  V I V U S  V I C I-        |
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
From gurari@news.cis.ohio-state.edu Mon Sep 27 12:53:08 EDT 1993
Date: Mon, 27 Sep 93 12:53:08 EDT
From: gurari@news.cis.ohio-state.edu (Eitan Gurari)
Reply-To: LitProg@SHSU.edu, gurari@NEWS.CIS.OHIO-STATE.EDU
To: LitProg@SHSU.EDU
Subject: Re: Literate Programming for non-imperative languages
 
>  From: dmason@uwaterloo.ca (Dave Mason)
 
>  Right now I'm trying a new
>  approach for multi-lingual WEBs that will run within TeX itself.  It
>  will be quite easy to customize for multiple languages, and you can
>  get as much, or as little, pretty-printing as you want.  Pictures at 11.
 
I tried to build a similar system. It can be ftp'ed from
cis.ohio-state.edu (directory pub/tex/osu/gurari):
 
ProTex.sty   -- Literate programming tool
AlProTex.sty -- Tailored adjustments to ProTex.sty
 
The manual (``TeX and LaTeX: Drawing and Literate Programming.
McGraw-Hill'' ISBN 0-07-025208-4) will be published by McGraw-Hill in
the very near future (currently in print).
 
-eitan
 
From Lee Mon Sep 27 12:53:08 EDT 1993
Date: Mon, 27 Sep 93 12:53:08 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, karna@pobox.upenn.edu
Subject: Re: Web-like system that doesn't use TeX?
 
Animesh Karna asks:
 
> One of the things stopping me from using Web (or CWeb) is that the
> "readable" output is in TeX.  Does anyone know of a version of
> Web/CWeb/something similar that can produced other kinds of output -- like
> plain text or RTF or something like that?
 
The only systems I know of that meet your specifications are CLiP and
WinWordWEB.  The former can run under any system with any word
processor; the latter requires DOS, Windows, and MS Word for Windows.
 
		-- Lee
		   leew@pilot.njin.net 
 
From Lee Mon Sep 27 13:21:06 EDT 1993
Date: Mon, 27 Sep 93 13:21:06 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, bed_gdg@shsu.edu
Subject: Re: What does literate programming mean to you?
 
George Greenwade suggests:
 
> What would the group think of a "refereed electronic periodical" for
> literate programming; maybe "Literate Programming Review" or some other
> less mundane name??  What I have in mind is a model we are developing for
> economics -- you have the usual cadre of people, an editor, etc., with a
> panel of blind reviewers; articles are submitted via e-mail to the editor,
> who then strips author-identifying items, and forwards the submissions to a
> subset of the reviewers; the reviewers comment on the submission to the
> editor, who in turn forwards blind (stripped) reviews to the author; the
> author makes modifications, resubmits, etc.  Once the reviewers and editor
> say so, the article is ready for inclusion in a mail-based "journal" (which
> can easily be linked into c.p.l).  The address for the journal is
> completely private for posting -- only selected addresses (say, only the
> editor) can post to it -- but completely public for subscriptions.  An
> alias (or the direct editor's e-mail address) can be used for submissions.
 
I think this would be a wonderful idea (although I was under the
impression that someone ~was~ already working on similar lines).  I
would be happy to volunteer my services as a reviewer (without my
contact lenses, I am legally blind :-), but not as an editor (sorry, I
have very few organizational skills, and no desire to acquire any
more).  I would also certainly contribute the odd article, whether it
was a ``respected journal'' or not.  I think it can be an important
forum for LP (although I also think that this mailing list/newsgroup
is an important forum in and of itself).
 
		-- Lee
		   leew@pilot.njin.net
blind, 
 
From norman@bellcore.com Mon Sep 27 14:20:25 -0400 1993
Date: Mon, 27 Sep 93 14:20:25 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: "George D. Greenwade" <bed_gdg@SHSU.edu>
Subject: Re: What does literate programming mean to you?
 
> What would the group think of a "refereed electronic periodical" for
> literate programming; maybe "Literate Programming Review" or some other
> less mundane name??  
 
Short answer: it would be a super idea if you got some real
heavyweights on the editorial board.  People like Bentley, Van Wyk, or
Hanson.  The actual editor who does the dirty work needn't be such a
heavyweight, but without some such backing I don't think it would be
taken seriously outside a very small group.
 
I don't know where you would find an editor who would be willing to
put time into making it work.  I can ask around...
 
Norman
 
From schrod@iti.informatik.th-darmstadt.de Mon Sep 27 15:31:09 -0400 1993
Date: Mon, 27 Sep 1993 15:31:09 -0400
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <287i4uINNcc3@rs18.hrz.th-darmstadt.de>, schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) writes:
 
By god, you're fast. I wrote
 
> has a middle sized system, i.e., something larger than 1MB WEB source
> size. Going above ~ 20 MB
 
To save myself from further questions: I would not even *think* about
writing a source file of 1 MB. I meant total size of WEB documents,
whereby I count specifications and implementations. Documents
concerning analysis, design, test, configuration, and the (iterative)
software process itself are not included in this figure.
 
--
Joachim
 
From schrod@iti.informatik.th-darmstadt.de Mon Sep 27 15:31:09 -0400 1993
Date: Mon, 27 Sep 1993 15:31:09 -0400
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <009732AB.BC7FD640.23292@SHSU.edu>, "George D. Greenwade" <bed_gdg@SHSU.edu> writes:
> On Fri, 24 Sep 93 19:15:22 -0400, Norman Ramsey <norman@bellcore.com>
> posted:
> >.....
> > I think Mr. Gray is slightly misinformed about publication.  The days of
> > literate programming as a publishing fad have come and gone.  Major
> > publications are not amused by article about literate programming, and
> > papers on literate program do not weigh heavily with those who play the
> > publication game.  So *I* wouldn't waste *my* time on literate programming
> > if all I cared about was getting published.
> 
> What would the group think of a "refereed electronic periodical" for
> literate programming; maybe "Literate Programming Review"
 
Not much. The point is, IMNSHO, that the problems where LitProg gets
interesting are too large to get published.
 
In particular, we have found that LitProg is of great value if one
has a middle sized system, i.e., something larger than 1MB WEB source
size. Going above ~ 20 MB the LitProg paradigm gets irrelevant since
other problems plague you more. (Yes, we wrote a system in this size.
And we wrote some smaller systems with approx. 5 MB code.) How do you
want to publish that?
    Another point: LitProg is very nice in a group where you have a
high fluctuation of people working on a project. (Like we have here at
the university.) The positive effects of LitProg are in the
maintainance phase, not in the development phase.
 
There lies also the problem with Norman's demand of empiric results:
Who has the resources to create a controlled experiment that has to
last for at least two years with a lot of people? We surely don't. Not
that it would matter, IMO: The journals flourish with papers about
methods where nobody even bothered to use them in toy projects. Our
problem is more that we must introduce more formulisms...
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16 Jul 93
 
From schrod@iti.informatik.th-darmstadt.de Mon Sep 27 15:31:09 -0400 1993
Date: Mon, 27 Sep 1993 15:31:09 -0400
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Scheme-WEB & Knuth
 
In article <1993Sep27.164115.29945@news.unige.ch>, lbartho@scsun.unige.ch (BARTHOLDI Laurent) writes:
 
> I was thinking about porting Knuth's WEB to Scheme, a LISP-like dialect.
> I wanted to make sure nobody was on the same track; or (even worse)
> that the whole thing had already been done.
 
There's schemeweb, though I don't know how good it is. Please post a
review, after you've looked at it!
 
The Literate Programming Archive in Darmstadt:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/lisp/
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From schrod@iti.informatik.th-darmstadt.de Mon Sep 27 15:31:09 -0400 1993
Date: Mon, 27 Sep 1993 15:31:09 -0400
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Literate Programming for non-imperative languages
 
In article <9309271651.AA03219@rhinoceros.cis.ohio-state.edu>, gurari@news.cis.ohio-state.edu (Eitan Gurari) writes:
> 
> >  Right now I'm trying a new
> >  approach for multi-lingual WEBs that will run within TeX itself.  It
> >  will be quite easy to customize for multiple languages, and you can
> >  get as much, or as little, pretty-printing as you want.  Pictures at 11.
> 
> I tried to build a similar system. 
> 
> ProTex.sty   -- Literate programming tool
> AlProTex.sty -- Tailored adjustments to ProTex.sty
 
Might you tell more about your system? What are its principles, where
are its strenghts, etc.? Comparison to other Litprog systems?
 
Needn't be long, just an abstract. You'll make PR for your book. :-)
 
> It can be ftp'ed from
> cis.ohio-state.edu (directory pub/tex/osu/gurari):
 
I'll mirror it to the Literate Programming Archive.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16 Jul 93
 
From gurari@news.cis.ohio-state.edu Mon Sep 27 15:31:09 -0400 1993
Date: Mon, 27 Sep 1993 15:31:09 -0400
From: gurari@news.cis.ohio-state.edu (Eitan Gurari)
Reply-To: LitProg@SHSU.edu, gurari@NEWS.CIS.OHIO-STATE.EDU
To: LitProg@SHSU.EDU
Subject: Re: Literate Programming for non-imperative languages
 
> From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
> 
> In article <9309271651.AA03219@rhinoceros.cis.ohio-state.edu>, gurari@news.cis.ohio-state.edu (Eitan Gurari) writes:
> > 
> > >  Right now I'm trying a new
> > >  approach for multi-lingual WEBs that will run within TeX itself.  It
> > >  will be quite easy to customize for multiple languages, and you can
> > >  get as much, or as little, pretty-printing as you want.  Pictures at 11.
> > 
> > I tried to build a similar system. 
> > 
> > ProTex.sty   -- Literate programming tool
> > AlProTex.sty -- Tailored adjustments to ProTex.sty
> 
> Might you tell more about your system? What are its principles, where
> are its strenghts, etc.? Comparison to other Litprog systems?
 
I'll try.
 
ADVANTAGES
 
a. Standard advantages of other systems of similar
   nature (e.g., FunnelWeb, noweb, nuweb): language-
   independence, concurrent support for development
   of different pieces of code, simple to use
   and learn (at its basic level)
 
b. Full integration with (La)TeX: single compilation
   by (La)TeX produces the document and the code, 
   files decomposition (with \input), portability 
   as (La)TeX  
 
c. A small base system (ProTeX, 10K) that is very 
   easy to adjust to different specifications, IF you
   are  familiar with TeX and the system.
 
   Well, currently I am the only one belonging to this
   category, and I don't expect or recommend that many 
   will join me. (I'll be happy to augment AlProTex with 
   additional options if a demand will arise.)
 
DISADVANTAGES
 
a. Poor support for debugging.
 
b. Poor and slow index facilities (automated only for
   code titles)
 
c. No cross-referencing for code titles. (Such a 
   feature can be implemented, but it probably 
   will slow the system. Personally I prefer to 
   use explicit \Ref and \Tag commands at the few 
   places where I care about cross referencing.)
 
d. No typesetting of code (some of us may consider this
   property an advantage)
 
> Needn't be long, just an abstract.
 
Hopefully, I stayed within acceptable limits...:-)
 
>  You'll make PR for your book. :-)
>
> > It can be ftp'ed from
> > cis.ohio-state.edu (directory pub/tex/osu/gurari):
> 
> I'll mirror it to the Literate Programming Archive.
 
Thanks.
 
--eitan
 
From ross@wattle.itd.adelaide.edu.au Mon Sep 27 15:31:09 -0400 1993
Date: Mon, 27 Sep 1993 15:31:09 -0400
From: ross@wattle.itd.adelaide.edu.au (Ross Williams)
Reply-To: LitProg@SHSU.edu, ross@WATTLE.ITD.ADELAIDE.EDU.AU
To: LitProg@SHSU.EDU
Subject: Re: Printing funnelweb documentation
 
seiferth@bandelier.cs.unm.edu (Justin Seiferth) writes:
 
>Have you managed to turn the funnelweb documentation into a postscript
>document?  I'm no TeX/LaTeX weanie and have been unable to figure out
>why I can't process the tex documents which come with the distribution.
>My attempts to process the documents result in the following error:
 
>% latex u_manual.tex
>This is TeX, C Version 3.14t3
>(u_manual.tex
>! Undefined control sequence.
>l.73 \documentstyle
>                  [titlepage]{book}
>                  ?
 
>If I type "RUN", a multitude of errors appear and a bogus .dvi file
>(1 page long) is produced.
 
>If someone could point me towards a ps copy of the documentation or
>tell me how I can LaTeX the documents myself I'd greatly appreciate it.
 
>Thanks...
>Justin
>seiferth@bandelier.cs.unm.edu
 
A week or so ago I was in the US and installed a copy of FunnelWeb for
a friend on a DecStation. The installation went fine except for one
detail and that was the titlepage in the manual - exactly what you
have run into. I have no idea why some LaTeXs have a problem with this
- it works on my copy of LaTeX and is documented in the LaTeX user's
guide and reference manual by Lamport.
 
The quick fix is simply to delete the code in u_manual.tex or
u_ch0.tex (I can't remember which) and do without a titlepage.
 
The good news is that this is the ONLY problem you are likely to
ru up against in typesetting the manual. And I had no other problems
installing FunnelWeb on the DecStation. So zap the titlepage code and
KEEP TRYING!
 
Ross. (Creator of FunnelWeb)
 
+--------------------------------------------------------------+
| Name    : Dr Ross N. Williams                                |
| Company : RockSoft Pty Ltd    (Reg TM Australia, TM USA)     |
| Net     : ross@guest.adelaide.edu.au.                        |
| Fax     : +61 8 373-4911    24 hours                         |
| Phone   : +61 8 379-9217    24 hours                         |
| Snail   : 16 Lerwick Avenue, Hazelwood Park 5066, Australia  |
| Archive : ftp.adelaide.edu.au/pub/compression and /funnelweb |
+--------------------------------------------------------------+
 
From sheeran@ndg.co.jp Tue Sep 28 03:39:42 GMT 1993
Date: Tue, 28 Sep 1993 03:39:42 GMT
From: sheeran@ndg.co.jp (Sheeran Frank)
Reply-To: LitProg@SHSU.edu, sheeran@NDG.CO.JP
To: LitProg@SHSU.EDU
Subject: Re: RE: New Math Notation #3107
 
> |>Literate programming uses additional fonts and symbols to make the code
> |>much more intelligable.  Instead of using .NE., <>, or != to mean "not
> |>equals", literate programs print and display the code using a standard
> |>mathmatical not-equals sign.  Assignments are shown using a left pointing
> |>arrow.
 
This is like an American making Japanese change their word order to
that of English, and saying, "There, much more understandable, right?"
 
The fact is many programmers have more experience with, say, C than
with math notation.  Just as you can't say "Latin is better grammar
than French" you can't rank math notation as "better" than C.
 
Languages and notations communicate, and I am communicated to better
with a != than a slashed equals sign.  I don't stop and think "Gee, an
exclamation point followed by an equals sign, how wierd" every time I
see it.
 
A source browser that let people select the notation they were most
used to would be apropos.  Most people understand most quickly the
notation they are most used to; let them select it off a menu.
 
I agree that no notation is good in all circumstances - math and its
one-character identifiers, C and its  . * precedence foulup, but I am
more efficient at a bad C I am used to than a new notation.  I still
type QWERTY for the same reason (though I *have* written an article on
a new keyboard layout for Japanese :)
 
Frank Sheeran, Omron Data General KK, Tokyo
from addresses outside of Japan, please e-mail to sheeran_f@odg.ceo.dg.com
 
From bill@cygnus.com Tue Sep 28 03:39:42 GMT 1993
Date: Tue, 28 Sep 1993 03:39:42 GMT
From: bill@cygnus.com (Bill Cox)
Reply-To: LitProg@SHSU.edu, bill@CYGNUS.COM
To: LitProg@SHSU.EDU
Subject: Re: Multiple 'find & replace'?
 
>A friend of mine is working as a translator, translating between Swedish and
>Danish, two very similar language. He feels that it would save a vast amount of 
>time if he could have a wordbank of, say, fivehundred words that he could use
>for doing some kind of multiple 'search & replace' on his mac.
>My question is this: is there a program that does multiple search and replace
>(automated)? And where can he find it. I assume there must be a program like 
>that out there, so please help me out!
 
Under either DOS or Unix, I would recommend using a 'sed'
script.  You can feed 'sed' a file that looks like this:
 
s/car/auto/
s/boy/young man/
...
 
and it will replace each occurence of 'car' with 'auto'.
One of the pitfalls is that it will also replace 'scar',
with 'sauto'.  
 
Try the O'Reilly book titled "Sed and Awk". ISBN 0-937175-59-5.
 
There is a GNU version of sed, available from prep.ai.mit.edu
as C source code, so you or your friend might have to compile
the C source and make a mac executable...
--
bill@cygnus.com       IBM, DEC and Honeywell, HP, DG and Wang
	      Amdahl, NEC and NCR, they don't know anything
	      They make big bucks on systems, so they never want it known
	      That you can build a mainframe from the things you find at home.
		 - Bill Sutton on "The Funniest Computer Songs" tape
 
From monnier@hebe.nectar.cs.cmu.edu Tue Sep 28 06:40:15 GMT 1993
Date: Tue, 28 Sep 1993 06:40:15 GMT
From: monnier@hebe.nectar.cs.cmu.edu (Stefan Monnier)
Reply-To: LitProg@SHSU.edu, monnier@HEBE.NECTAR.CS.CMU.EDU
To: LitProg@SHSU.EDU
Subject: Re: What does literate programming mean to you?
 
In article <CDyzyA.82z@ie.utoronto.ca>, Yan Xiao <xiao@ie.utoronto.ca> wrote:
>tzs@stein1.u.washington.edu (Tim Smith) writes:
>
>>In article <CDtIJn.59p@austin.ibm.com>,
>>>> 	d = c+1/c;		//guaranttees: d>2
>>..
>>>> assertion at line 7 (d>2) not guarantteed. Best possible: d>=2.
>>>
>>>I think you mean
>>>
>>>assertion at line 7 (d>2) not guaranteed. Best possible: d>=0.
>>>
>>>Consider the case of c == 2 (which makes d = 1.5) .
>
>>Ever hear of precedence?  c+1/c means c+(1/c), not (c+1)/c.
>
>Consider the case of c = -1.  d = (-1) + ( 1/(-1)) = (-1) + (-1) = -2.
>Or worse when c = 0.
 
Ahem: the line right before was a "read c" with a "require c>0"
 
>I missed something or what!?  Should this group be better called 
>comp.programming.ILliterate?
 
maybe comp.programming.blind ? :-)
 
	Stefan
-- 
 
-----------------------------------------------------
-- On the average, people seem to be acting normal --
-----------------------------------------------------
 
From dentato@aleph.ing.uniroma1.it Tue Sep 28 11:07:11 +0100 1993
Date: Tue, 28 Sep 93 11:07:11 +0100
From: dentato@aleph.ing.uniroma1.it
Reply-To: LitProg@SHSU.edu, dentato@ALEPH.ING.UNIROMA1.IT
To: LitProg@SHSU.edu
Subject: Re: Literate implementations of literate tools.
 
 >I've noticed someone suggesting that it is hypocritical to write a
 >literate programming tool in a non-literate style.
 >
 >I disagree. Writing a literate tool using itself is just asking for
 >trouble. What if the only executable is accidentally deleted?! Better
 >to keep the implementation of the literate tool "clean".
 
I strongly disagree! I think that a literate programming tool should be the 
first example of using the tool itself.
 
The problems of accidentally erase your executable is a matter of organization. 
I've written a nuweb-compatible litprog tool that use only ascii (I've not 
finished the formatting part, but the generation of code is very fast and uses 
very little memory: I've to work on micros too :-)).
 
Anyway, it was the first program written using itself and I had no problems of 
loosing executables or such.
 
       Remo Dentato.
 
Oh! By the way: I call my tool Aracne, let me know if there are some tool with 
the same name!!
 
      ___ __          Universita' di Roma "La Sapienza"
     //_/// \         Dipartimento di Informatica e Sistemistica
    // \//__/         Via Buonarroti 12    00184 Roma  (Italy)
   Remo Dentato       tel: +39-6-4873689   fax: +39-6-4873628
                      email:  dentato@cadgroup.ing.uniroma1.it  
 
From Eric Tue Sep 28 12:08 +0000 1993
Date: Tue, 28 Sep 1993 12:08 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LITPROG@shsu.edu
Subject: Re: What LP means to you
 
Recently the question of using literate programming to prove the code of
a program, has been discussed. IMO this is aspect is one of the more important
characteristics of LP and it should be exploited. Remember that Dijkstra 
promoted the idea that programs and their proofs should be developped 
simultaniously. A comparable opinion can be found in Brooks "No silver Bullit".
 
LP is very well suited to this task. One has the option to argue the 
correctness of the code by informal arguments or by proofs in the style of
a mathematical textboork (often referred as "informal rigor"). In the 
exceptional case that the code is verfied by a therem prover, the provers 
report can be included.
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From ae1181t@stnfor.ae.ge.com Tue Sep 28 08:15:40 -0400 1993
Date: Tue, 28 Sep 1993 08:15:40 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, lbartho@scsun.unige.ch.ae.ge.com.ae.ge.com
Subject: Re: Scheme-WEB & Knuth
 
Hi, I know that there is a SCHEMEWEB but it is only a TeX commenting scheme!
It is not a full literate programming tool. However I would try the spider web
repositories first. 
Osman
 
From everettm@merlin.think.com Tue Sep 28 08:15:40 -0400 1993
Date: Tue, 28 Sep 1993 08:15:40 -0400
From: everettm@merlin.think.com (Mark J. Everett)
Reply-To: LitProg@SHSU.edu, everettm@MERLIN.THINK.COM
To: LitProg@SHSU.EDU
Subject: Re: Multiple 'find & replace'?
 
In article <2874sb$k3a@nic.lth.se> dat91msu@ludat.lth.se (Martin Sunnerdahl) writes:
 
   Hi.
   A friend of mine is working as a translator, translating between Swedish and
   Danish, two very similar language. He feels that it would save a vast amount of 
   time if he could have a wordbank of, say, fivehundred words that he could use
   for doing some kind of multiple 'search & replace' on his mac.
   My question is this: is there a program that does multiple search and replace
   (automated)? And where can he find it. I assume there must be a program like 
   that out there, so please help me out!
 
I would be surprised if there weren't some version of awk that didn't run
on the Mac.  It is very simple to program.  I would guess, however, that he
wants to search and replace word processing files rather than plain text.
That would be much more difficult.
--
 
DISCLAIMER:  These opinions are mine, all mine.
 
From lynbech@daimi.aau.dk Tue Sep 28 08:15:40 -0400 1993
Date: Tue, 28 Sep 1993 08:15:40 -0400
From: lynbech@daimi.aau.dk (Christian Lynbech)
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.EDU
Subject: Re: New Math Notation #3107
 
Thus spake sheeran@ndg.co.jp (Sheeran Frank):
 
>> |>Literate programming uses additional fonts and symbols to make the code
>> |>much more intelligable.  Instead of using .NE., <>, or != to mean "not
>> |>equals", literate programs print and display the code using a standard
>> |>mathmatical not-equals sign.  Assignments are shown using a left pointing
>> |>arrow.
 
>This is like an American making Japanese change their word order to
>that of English, and saying, "There, much more understandable, right?"
 
>The fact is many programmers have more experience with, say, C than
>with math notation.  Just as you can't say "Latin is better grammar
>than French" you can't rank math notation as "better" than C.
 
[...rest deleted...]
 
I think the important is not as much math vs. C, but rather the full capability
of (say) TeX typesetting vs. the severe restrictions of a typical C compiler
(i.e. dvi vs. latin 1)
 
What to do with the additional power of typesetting is a matter for the writer.
Truely, condensed maths with lots of greek letters and subtle implications from
simple equations, can be as confusing as an obscure pointer feature.
 
The important point (to me at least) is that Literate Programming generally
makes this possible, by the interweaving of typesetting and programming.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From lynbech@daimi.aau.dk Tue Sep 28 08:15:40 -0400 1993
Date: Tue, 28 Sep 1993 08:15:40 -0400
From: lynbech@daimi.aau.dk (Christian Lynbech)
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.EDU
Subject: LitProg Review (was Re: What does literate programming mean to you?)
 
Thus spake norman@bellcore.com:
 
>> What would the group think of a "refereed electronic periodical" for
>> literate programming; maybe "Literate Programming Review" or some other
>> less mundane name??  
 
>Short answer: it would be a super idea if you got some real
>heavyweights on the editorial board.  People like Bentley, Van Wyk, or
>Hanson.  The actual editor who does the dirty work needn't be such a
>heavyweight, but without some such backing I don't think it would be
>taken seriously outside a very small group.
 
It depends much upon what you want to acheive. If academic fame is required,
only the heavyweights will do, but if the emphasis is more on producing better
programs, any board of knowledgeable and experienced LitProg'ers (or even just)
programmers should suffice.
 
But as someone else (Joachim Schrod?) has mentioned, the real significance
comes for real projects, i.e. large examples of thousands of lines. And I would
very much doubt that anybody would want to go into that game, unless being part
of the development itself, as seen in companies using reviews to produce better
code.
 
But from an educational point of view, it may make sense after all. People
experimenting with LitProgramming (or using it for small 1 person projects),
could have their code reviewed, and perhaps published in whatever fora. This
would give all contributors valuable critique and evaluation, and provide
everyone with a body of nice, reviewed works, to learn from.
 
>I don't know where you would find an editor who would be willing to
>put time into making it work.  I can ask around...
 
I definitely like the idea. Perhaps it even applies to the Usenet University
(not that I no much about that).
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From ciemjw@sealion.ssd.lmsc.lockheed.com Tue Sep 28 08:15:40 -0400 1993
Date: Tue, 28 Sep 1993 08:15:40 -0400
From: ciemjw@sealion.ssd.lmsc.lockheed.com (Jon Weygandt)
Reply-To: LitProg@SHSU.edu, ciemjw@SEALION.SSD.LMSC.LOCKHEED.COM
To: LitProg@SHSU.EDU
Subject: Re: New Math Notation #3107
 
I new to literate programming, but not engineering and could not
resist jumping in on this topic ...
 
>In article <1993Sep27.141742.1104@dxcern.cern.ch> hallam@dxal18.cern.ch (HALLAM-BAKER Phillip) writes:
>   In article <9309261452.memo.19736@BIX.com>, Jeffrey McArthur <j_mcarthur@BIX.com> writes:
>
...
>   |>I disagree strongly with these statements.  Literate Programming is an
>   |>attemp to FIX the serious problems with C and FORTRAN style notation.  C
>   |>and FORTRAN can be very difficult to understand.  Particularly if you are
>   |>doing vector or tensor calculations.  The notation used is almost
>   |>unintelligable.  Mathmatical notation is much cleaner.  That is why, using
                                               ^^^^^^^^^^^^ 
                                               but not always complete ...
>   |>literate programming, it is desirable to include as part of the program the
>   |>full mathmatical description.
>   |>
...
>   I don't see these ideas as mutually contradictory. Standard computer languages
>   are poor in this area, but standard maths is also poor in certain areas -
>   the use of juxtaposition to impy multiplication is a dreadful feature
>   for example that should be removed from standard notation. It prevents the
>   use of meaningful identifiers with multiple characters.
...
 
2 specific examples of where real world engineering notation omit some
very cirtical information necessary for precise implementation, the
information is apparent in the context of how it is used, but even to
the human reader it may not be obvious:
 
Vectors:
	The standard vector notation does not differentate between
"free vectors" and "bound vectors".  A "free vector" is a vector that
has magnitude and direction.  A "bound vector" is one that has
magnitude, direction and is attached to the origin, or said
differently describes a position in space.  This distinction needs to
be made in the area of geometry modeling, since points in space are
bound.  Operations such as vector addition on two bound vectors is
invalid, however one can do a difference and produce a free vector.
One can also add a bound and free to produce a free.  Also
transformation upon a bound vector must take into account the
translation of the origin, whereas transformation of free vectors only
consider rotation (speaking of only basic rotations and translation in
cartesian space, what perspective transformations and others mean for
for free vectors I haven't yet considered)
 
Units, Temperatures:
	It is standard to apply a simple unit designation after a
number, but in the case of temperature there is a similar concept as
to vectors.  There exist actual temperatures of objects "absolute
temperatures" and there exist temperature differences "relative
temperatures".  Similar restrictions on addition, subtraction, and
unit transformation exist. (eg. In the real world we could have two
rooms, say one at 60 deg F and one at 70 deg F.  It would not be
defined to say add the two room temperatures togeter and get 130 deg F
(or even worse xxx deg R) but it would make sense to say the
difference between two rooms is 10 deg F (note the same notation for
the values:-)).
 
--
 
        Jon Weygandt
 
        Lockheed Missiles and Space Co.
        Sunnyvale CA
 
From Eric Tue Sep 28 12:49 +0000 1993
Date: Tue, 28 Sep 1993 12:49 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: What does literate programming mean to you?
 
Norman Ramsey writes
 
==There's little evidence that literate-programming tools can really
==give us better programs (although there are True Believers, of whom I
==am one).  
 
I'm a true bleleiver too and I'm slightly less pessimistic here. The work of
Oman is at least a hint at the value of literate programming. 
    -	Oman, Typographical style is more than cosmetic, CACM 33, 5, 506-520
    -	Oman, the book paradigm for imporved maintenance, IEEE software 1990
	pg 39-45
 
Eric van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Lee Tue Sep 28 12:01:17 EDT 1993
Date: Tue, 28 Sep 93 12:01:17 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, lbartho@scsun.unige.ch
Subject: Re: Scheme-WEB & Knuth
 
Larry Bartholdi writes:
 
> Hi folks,
> I was thinking about porting Knuth's WEB to Scheme, a LISP-like dialect.
> I wanted to make sure nobody was on the same track; or (even worse)
> that the whole thing had already been done.
> If somebody has a useful tip to give me, I would also be welcome.
> My intention was to modify the grammar rules in CWEB.
> Thanks to all people whoe read this.
 
You might want to try using Spidery WEB instead of doing it by hand.
You specify the grammar, and it generates the programs.
 
If you're interested, I have the beginnings of a Spidery grammar for
Scheme.  My grammar (very rudimentary -- it was just a test to see if
I could do it) typesets the normal Scheme S-expressions in a form more
like McCarthy's original M-expressions, which I find to be much more
readable.  Send me direct mail (not to the list) if you'd like me to
send you a copy.
 
		-- Lee
		   leew@pilot.njin.net
 
From marcus@x4u.desy.de Tue Sep 28 16:43:56 GMT 1993
Date: Tue, 28 Sep 1993 16:43:56 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: LitProg Review (was Re: What does literate programming mean to you?)
 
 >>>>> On 28 Sep 1993 13:04:31 GMT, lynbech@daimi.aau.dk (Christian Lynbech) said:
 
|> Thus spake norman@bellcore.com:
 
>> What would the group think of a "refereed electronic periodical" for
>> literate programming; maybe "Literate Programming Review" or some other
>> less mundane name??  
 
[...]
 
|> But from an educational point of view, it may make sense after all. People
|> experimenting with LitProgramming (or using it for small 1 person projects),
|> could have their code reviewed, and perhaps published in whatever fora. This
|> would give all contributors valuable critique and evaluation, and provide
|> everyone with a body of nice, reviewed works, to learn from.
 
>I don't know where you would find an editor who would be willing to
>put time into making it work.  I can ask around...
 
|> I definitely like the idea. Perhaps it even applies to the Usenet University
|> (not that I no much about that).
 
  I can speak for Usenet University since I am on its board of
directors. We are currently discussing the curriculum for our first
semester on the internet (spring 94)-- we would certainly be honored to host
a LitProg Review enterprise, though I can't say whether we can
allocate any manpower for it.
 
  We would like to bundle any sort of "virtual" educational
activity -- a journal which is unlikely to ever never appear on real
paper fits in this category. We already have: a list of electronic
consultants, a collaborative (Hyper-) textbook project, an internet
meta library, and a virtual campus.
 
  To offer a beginner's course on LitProg would be another nice course
offer. Any help/suggestion is welcome.
 
  I will bring up the Review issue on the next board meeting
on Thursday [a virtual meeting on MediaMOO at MIT].
 
------------------------------------ UU Net Information.
 
FYI, Usenet University--Global Network Academy [GNA], Inc. is a non-profit
corporation incorporated in the state of Texas, affiliated with the
Usenet University project.
The bulk of information on GNA is available via WWW:
 
http://uu-gna.mit.edu:8001/index.html
 
For info on how to get there, get
 
	/pub/outgoing/WWW-Access.txt
 
from ftp.desy.de [131.169.10.38] via anonymous ftp.
To be included on our mailing list discussing internet curricular
questions, send empty Email to 
 
		listserv@moose.uvm.edu
 
General discussion on GNA maaters takes place on the Usenet group
alt.uu.future.
 
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From sboyle@wv.MENTORG.COM Tue Sep 28 11:25:54 -0700 1993
Date: Tue, 28 Sep 93 11:25:54 -0700
From: sboyle@wv.MENTORG.COM (Sean Boyle x1542)
Reply-To: LitProg@SHSU.edu, sboyle@WV.MENTORG.COM
To: LitProg@SHSU.edu
Subject: Literate Programming for non-imperative languages
 
   I tried to build a similar system. It can be ftp'ed from
   cis.ohio-state.edu (directory pub/tex/osu/gurari):
 
   ProTex.sty   -- Literate programming tool
   AlProTex.sty -- Tailored adjustments to ProTex.sty
 
   The manual (``TeX and LaTeX: Drawing and Literate Programming.
   McGraw-Hill'' ISBN 0-07-025208-4) will be published by McGraw-Hill in
   the very near future (currently in print).
 
   -eitan
 
Do you have any other documentation on it until this comes out?  Is there
.tex files to work with plain TeX instead of LaTeX?  I had thoughts of doing a
similar sort of thing myself, but I'm not a power TeX programmer.  This would
be a boon, not having a million support programmes in order to weave and
tangle.  
 
Also, do you have an emacs mode for this?
            +------------------------+------------------------------+
            | sean_boyle@mentorg.com |  Mentor Graphics Corporation |
            | uunet!mntgfx!sboyle    |  8005 S.W. Boeckman Road     |
            |                        |  Wilsonville, OR 97070-7777  |
            |       "Intrinsically lazy, therefore creative"        |
            +------------------------+------------------------------+
 
From Edward Tue Sep 28 18:48:25 EDT 1993
Date: Tue, 28 Sep 1993 18:48:25 EDT
From: "Edward F. Keith" <ed@efkport.kew.com>
Reply-To: LitProg@SHSU.edu, ed@EFKPORT.KEW.COM
To: "Literate Programming List" <LitProg@SHSU.edu>
Subject: Re: Literate implementations of literate tools.
 
On Tue, 28 Sep 93 11:07:11 +0100, dentato@aleph.ing.uniroma1.IT wrote:
> Oh! By the way: I call my tool Aracne, let me know if there are some tool with 
> the same name!!
 
In the preface to Holub's book "Compiler Design in C" he says that he used 
a tool call arahne. I know nothing more about it.
        -EdK
 
From C. Tue Sep 28 18:07:36 CDT 1993
Date: Tue, 28 Sep 93 18:07:36 CDT
From: "C. M. Sperberg-McQueen" <U35395%UICVM.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU
To: litprog@SHSU.edu
Subject: Bootstrapping and LP tools
 
In the discussion over whether literate-programming tools should or
should not be implemented in the languages they define, I think the
humility of Preston Briggs and Norman Ramsey may have allowed a
misconception to take root.  Nuweb, at least, is in fact implemented in
nuweb, and provides a nice little test of literate programming tools:
is the program easier to understand even when the document is still
incomplete?  (Remember, this is version 0.8!)
 
Nuweb passes this test with flying colors.  Even though the commentary
becomes rather sparse during the chapter on The Overall Structure, and
mostly non-existent in the chapter on The Support Routines, nuweb is
still more legible than the other C programs of comparable size and
complexity that I have come into contact with, because of the
cross-referencing between scraps of code and because of the index.
 
I can make this comparison with some confidence, because I just finished
porting nuweb to VM/CMS, in about three hours of work (including
probably forty-five minutes wasted trying to remember how the debugger
works, and interrupted by several hours during which my subconscious
mulled over the problems, and eventually realized that ASCII is a
seven-bit and EBCDIC an eight-bit character set).  This compares
favorably with other software I have ported, which has taken days or (in
one case, where the thing never did actually run) weeks.  Of course,
this could be because Preston Briggs writes cleaner code, but perhaps he
does that because he's using a web system.
 
While I agree that more commentary would make nuweb a more readable
program, I disagree firmly with those who claim it isn't literate, in
any useful sense, now.
 
If anyone else can use a VM/CMS version of nuweb, they should let me
know.
 
-C. M. Sperberg-McQueen
 ACH / ACL / ALLC Text Encoding Initiative
 University of Illinois at Chicago
 u35395@uicvm.uic.edu / u35395@uicvm
 
From bvd@sserve.cc.adfa.oz.au Tue Sep 28 23:39:27 GMT 1993
Date: Tue, 28 Sep 1993 23:39:27 GMT
From: bvd@sserve.cc.adfa.oz.au (Brian Denehy)
Reply-To: LitProg@SHSU.edu, bvd@SSERVE.CC.ADFA.OZ.AU
To: LitProg@SHSU.EDU
Subject: Re: Printing funnelweb documentation
 
In article <ross.749180721@wattle.itd.adelaide.edu.au> ross@wattle.itd.adelaide.edu.au (Ross Williams) writes:
>seiferth@bandelier.cs.unm.edu (Justin Seiferth) writes:
>
>
>>% latex u_manual.tex
>>This is TeX, C Version 3.14t3
>>(u_manual.tex
>>! Undefined control sequence.
>>l.73 \documentstyle
>>                  [titlepage]{book}
>>                  ?
>
>>If I type "RUN", a multitude of errors appear and a bogus .dvi file
>>(1 page long) is produced.
>
>>If someone could point me towards a ps copy of the documentation or
>>tell me how I can LaTeX the documents myself I'd greatly appreciate it.
>
>>Thanks...
>>Justin
>>seiferth@bandelier.cs.unm.edu
>
>A week or so ago I was in the US and installed a copy of FunnelWeb for
>a friend on a DecStation. The installation went fine except for one
>detail and that was the titlepage in the manual - exactly what you
>have run into. I have no idea why some LaTeXs have a problem with this
>- it works on my copy of LaTeX and is documented in the LaTeX user's
>guide and reference manual by Lamport.
 
The error message above would suggest that TeX can't find the titlepage
set of macros in its path. Install the following as titlepage.sty in the
directory in which you have the documentation or with the rest of the TeX
macros if you have access to that directory.
 
------snip-here---------------------------
% titlepage.sty  27 Jan 85
\def\maketitle{\begin{titlepage}
\let\footnotesize\small \let\footnoterule\relax \setcounter{page}{0}
\null
\vfil
\vskip 60pt \begin{center}
{\LARGE \@title \par} \vskip 3em {\large \lineskip .75em
\begin{tabular}[t]{c}\@author 
\end{tabular}\par} 
\vskip 1.5em {\large \@date \par} \end{center} \par
\@thanks
\vfil
\null
\end{titlepage}
\setcounter{footnote}{0} \let\thanks\relax
\gdef\@thanks{}\gdef\@author{}\gdef\@title{}\let\maketitle\relax} 
\def\abstract{\titlepage
\null\vfil
\begin{center}
{\bf Abstract}
\end{center}}
\def\endabstract{\par\vfil\null\endtitlepage}
------snip-here-------------------------------
-- 
Brian Denehy,			   Internet: B-Denehy@adfa.oz.au
Computing Services 	  	   MHSnet:   B-Denehy@cc.adfa.oz.au
Australian Defence Force Academy   UUCP:!uunet!munnari.oz.au!cc.adfa.oz.au!bvd
Northcott Dr. Campbell ACT Australia 2600  +61 6 268 8141  +61 6 268 8150 (Fax)
 
From kcousins@rp.csiro.au Wed Sep 29 10:08:10 +1000 1993
Date: Wed, 29 Sep 93 10:08:10 +1000
From: kcousins@rp.csiro.au
Reply-To: LitProg@SHSU.edu, kcousins@RP.CSIRO.AU
To: LitProg@shsu.edu
Subject: Re: What does literate programming mean to you?
 
Eric van Ammers writes:
 
>     -	Oman, Typographical style is more than cosmetic, CACM 33, 5, 506-520
>     -	Oman, the book paradigm for imporved maintenance, IEEE software 1990
> 	pg 39-45
 
Nice articles. If anyone on LitProg hasn't already checked them out, get them 
now. Honestly, trying to write code that uses this book paradigm can get to be 
a real pain in the ass. To discover an entire battery of tools available (ala 
LitProg) is a real blessing, despite al the recent arguments about their 
relevance.
 
--Kevin.
________________________________________________________________________
    Kevin Cousins  |  kcousins@rp.csiro.au   | Ph: +61 2 868 0425
                                              Fax: +61 2 868 0490
      _--_|\     _   _   . _   _      CSIRO / Division of Radiophysics
     /      \   / ` ( ` / /_) / )     Cnr Vimiera & Pembroke Rds
     \_.--\_*  (_, ._) / / \ (_/      Marsfield  NSW  2121
           v
------------------------------------------------------------------------
 
From Eric Wed Sep 29 08:24 +0000 1993
Date: Wed, 29 Sep 1993 08:24 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: LitProg Review (was Re: What does literate programming mean to you?)
 
>  We would like to bundle any sort of "virtual" educational
>activity -- a journal which is unlikely to ever never appear on real
>paper fits in this category. We already have: a list of electronic
>consultants, a collaborative (Hyper-) textbook project, an internet
>meta library, and a virtual campus.
 
I like the ida very much, but my mainproblem is the following. 
Scientists in a university environment are (at least in my country, Holland) 
graded mainly by there so called output, ie. publications in scientific 
journals. How likely is it for such an electronic journal to be appreciated
on this level. More precisely, will there be a change that it will be
considered for citation indexes and the like? 
 
Eric
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From George Wed Sep 29 08:34:09 CST 1993
Date: Wed, 29 Sep 1993 08:34:09 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
Subject: Re: LitProg Review (was Re: What does literate programming mean to you?)
 
On Wed, 29 Sep 1993 08:24 +0000 (GMT), "Eric W. van Ammers"
<AMMERS@RCL.WAU.NL> posted:
> >  We would like to bundle any sort of "virtual" educational
> >activity -- a journal which is unlikely to ever never appear on real
> >paper fits in this category. We already have: a list of electronic
> >consultants, a collaborative (Hyper-) textbook project, an internet
> >meta library, and a virtual campus.
>
> I like the ida very much, but my mainproblem is the following.  Scientists
> in a university environment are (at least in my country, Holland)  graded
> mainly by there so called output, ie. publications in scientific  journals.
> How likely is it for such an electronic journal to be appreciated on this
> level. More precisely, will there be a change that it will be considered
> for citation indexes and the like? 
 
I think your "output" model can be expanded to most academics in most
fields in most nations (so long as the periodical is recognized as being
within the generalized field of the individual).  The concept of electronic
publishing is new to the universe, so how it is perceived is undoubtedly
still subject to question.  Should a new untenured faculty member seeking
recognition publish in this media if alternate already-recognized media
exists?  If the output model is followed as it presently stands, very
probably not; (s)he'd be much beter off following the traditional course.
 
More to the specific point of what I asked (and everyone who has responded
about this -- thanks, you've not been forgotted; I've simply been swamped
in recent days, but you'll hear):
> How likely is it for such an electronic journal to be appreciated on this
> level. More precisely, will there be a change that it will be considered
> for citation indexes and the like? 
This is a semi-unique case, IMO (or following Joachim, it should really be
IMNSHO, which is basically how you can always read my IMO's) as the area of
literate programming is not presently being served by the traditional
media, at least insofar as I can discern.  If literate programming (or any
underserved field) is indeed an area of research and discourse, an
electronic journal may be one of the singly most appreciated periodicals
within its field -- and very likely will show up in citation indices (I
know of two instances presently in psychology where electronic periodicals
are routinely included in citation indices).
 
Is this a risky venture for the author?  Yes, as there are few existing
models to compare it against.  Is it a venture with potentially high merit? 
Yes, as it facilitates discourse in an underserved area.  Is this a project
which has a multitude of spin-offs?  Yes, as it assists in developing the
model which subsequent tasks in other areas may compare themselves to.  Is
this an "open" project?  Yes, due to an entirely different set of costs,
academics, practitioners, and developers may have complete exchanges since
the cost and page limitations are removed.  Is this a grounds for extending
the field covered by the periodical?  Yes, due to quick turnaround,
publishing queues are minimized -- meaning that research, developments, and
ideas can quickly come into the focus of discussions (I don't know about
your field(s), but in economics, the publishing queues for some journals
now approach 3 years, meaning that the articles are stale by the time
readers actually get to them).
 
In other words, can I (or anyone) promise that publishing in such a forum
is a guarantee for parallel recognition to publishing in, say, the ACM? 
No. However, can you (or anyone) promise that publishing in such a forum
will not be viewed as superior to the ACM within a short period of time if
the contents of the effort are on-point and extensible?  No.
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From Lee Wed Sep 29 11:10:35 EDT 1993
Date: Wed, 29 Sep 93 11:10:35 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: Notation issues
 
A number of people have expressed opinions on the subject of LP and
mathematical notation, and I guess I just can't keep my big mouth
shut.
 
It has often been noted that the bulk of programming language
discussions center around points of syntax, rather than more
substantive issues.  While I agree that notation (language) shapes the
way we think, and is therefore important, I believe that is important
not to forget that the purpose of notation (language) is
~communication~.  Therefore, I think that some kind of standardization
of notation is useful, regardless of which notation is chosen as the
standard.
 
Today's common programming languages provide multiple examples of what
I mean.  On the plus side, almost every language uses `*' for
multiplication, and the rules for identifiers are pretty much the
same.  On the other hand, the assignment and logical operators vary
widely (e.g., `=', `:=', `SET/TO' for the former).
 
The primary reason I prefer the ``formatting'' LP systems (like CWEB)
to the ``nonformatting'' systems (like noweb) is that they provide
a more standardized notation.  I can look at a WEB, CWEB, or FWEB, and
not have to remember what the assignment operator is for the
particular base language -- they all use (or can use) `\gets'.
Although I am (like many of you are) more comfortable with programming
than mathematical notation, like Gulliver, I believe that getting the
egg open is more important than which end you crack.  Mathematical
notation for logical operators has been around a great deal longer
than any of the programming notations, so I'm perfectly willing to
``standardize'' on it, rather than search for the elusive perfect
notation.  
 
		-- Lee
		   leew@pilot.njin.net
 
From Lee Wed Sep 29 11:50:29 EDT 1993
Date: Wed, 29 Sep 93 11:50:29 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, U35395@uicvm.bitnet
Subject: Re: Bootstrapping and LP tools
 
C. M. Sperberg-McQueen writes of the ease of porting nuweb to VM/CMS
(see below).  I would like to echo his comments, at least in regard to
noweb.  Because noweb is (minimally) implemented in itself, it was
very easy to port to MS-DOS.  In fact, the only problems I had were
bugs in MKS Awk and the draconian restrictions MS-DOS imposes on batch
files.
 
The same comments hold true for porting CWEB, and I presume, FWEB,
FunnelWEB, CLiP, and the rest :-).
 
			-- Lee
			   leew@pilot.njin.net
-------------
> In the discussion over whether literate-programming tools should or
> should not be implemented in the languages they define, I think the
> humility of Preston Briggs and Norman Ramsey may have allowed a
> misconception to take root.  Nuweb, at least, is in fact implemented in
> nuweb, and provides a nice little test of literate programming tools:
> is the program easier to understand even when the document is still
> incomplete?  (Remember, this is version 0.8!)
> 
> Nuweb passes this test with flying colors.  Even though the commentary
> becomes rather sparse during the chapter on The Overall Structure, and
> mostly non-existent in the chapter on The Support Routines, nuweb is
> still more legible than the other C programs of comparable size and
> complexity that I have come into contact with, because of the
> cross-referencing between scraps of code and because of the index.
> 
> I can make this comparison with some confidence, because I just finished
> porting nuweb to VM/CMS, in about three hours of work (including
> probably forty-five minutes wasted trying to remember how the debugger
> works, and interrupted by several hours during which my subconscious
> mulled over the problems, and eventually realized that ASCII is a
> seven-bit and EBCDIC an eight-bit character set).  This compares
> favorably with other software I have ported, which has taken days or (in
> one case, where the thing never did actually run) weeks.  Of course,
> this could be because Preston Briggs writes cleaner code, but perhaps he
> does that because he's using a web system.
> 
> While I agree that more commentary would make nuweb a more readable
> program, I disagree firmly with those who claim it isn't literate, in
> any useful sense, now.
> 
> If anyone else can use a VM/CMS version of nuweb, they should let me
> know.
> 
> 
> -C. M. Sperberg-McQueen
>  ACH / ACL / ALLC Text Encoding Initiative
>  University of Illinois at Chicago
>  u35395@uicvm.uic.edu / u35395@uicvm
> 
 
From Lee Wed Sep 29 12:09:49 EDT 1993
Date: Wed, 29 Sep 93 12:09:49 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, AMMERS@rcl.wau.nl
Subject: Re: LitProg Review (was Re: What does literate programming mean to you?)
 
Eric van Ammers writes:
 
> >  We would like to bundle any sort of "virtual" educational
> >activity -- a journal which is unlikely to ever never appear on real
> >paper fits in this category. We already have: a list of electronic
> >consultants, a collaborative (Hyper-) textbook project, an internet
> >meta library, and a virtual campus.
> 
> I like the ida very much, but my mainproblem is the following. 
> Scientists in a university environment are (at least in my country, Holland) 
> graded mainly by there so called output, ie. publications in scientific 
> journals. How likely is it for such an electronic journal to be appreciated
> on this level. More precisely, will there be a change that it will be
> considered for citation indexes and the like? 
 
We have the same problem here in the States.  However, if we think the
electronic journal is a Good Thing (and I do), I say we should ``damn the
torpedoes; full speed ahead!''  The Internet is changing the way
Academia works, and it is up to us to educate our administrators as to
the way things work today.  This discussion group, for example, has
been worth more to me than a dozen traditional conferences or journals
would have been.  The only downside is not being able to get together
over coffee or lunch and talk things over face to face, although in
some cases that might be an advantage :-).
 
		-- Lee
		   leew@pilot.njin.net
 
From gurari@news.cis.ohio-state.edu Wed Sep 29 12:09:49 EDT 1993
Date: Wed, 29 Sep 93 12:09:49 EDT
From: gurari@news.cis.ohio-state.edu (Eitan Gurari)
Reply-To: LitProg@SHSU.edu, gurari@NEWS.CIS.OHIO-STATE.EDU
To: LitProg@SHSU.EDU
Subject: Re: Literate Programming for non-imperative languages
 
>  From: sboyle@wv.MENTORG.COM (Sean Boyle x1542)
>  
> >   It can be ftp'ed from cis.ohio-state.edu
 
Correction to my previous posting:
 
`ftp.cis.ohio-state.edu'  instead of `cis.ohio-state.edu'
 
> >   The manual ... will be published ... in the very near future
 
I got my copy today, so I guess that the book is already out.
 
>  Do you have any other documentation on it until this comes out?
 
I added to my ftp directory a file `Examples.tex' that produces few
pieces of code from my book.  Some of these pieces might give an idea
on how ProTeX+AlProTex work (their names start with `exr222').
 
Also, I'll be happy to demonstrate my system (through private
communication) to you and others by converting into literate form
short files that will be mailed to me.
 
>  Is there  .tex files to work with plain TeX instead of LaTeX? 
 
I am not sure that I understand the problem.  Do you mean that your
system doesn't provide for direct access to .sty files like
`ProTex.sty'?  (In the environment that I am using I just need 
to issue commands of the form `\input ProTex.sty'.)
 
>  Also, do you have an emacs mode for this?
 
Unfortunately, no (I am a nonsophisticated heavy user of emacs).
 
--eitan
 
From marcus@x4u.desy.de Wed Sep 29 21:29:50 GMT 1993
Date: Wed, 29 Sep 1993 21:29:50 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: LitProg Review (was Re: What does literate programming mean to
 
Marcus:
>  We would like to bundle any sort of "virtual" educational
>activity -- a journal which is unlikely to ever appear on real
>paper fits in this category. We already have: a list of electronic
>consultants, a collaborative (Hyper-) textbook project, an internet
>meta library, and a virtual campus.
 
Eric van Ammers:
|> I like the idea very much, but my main problem is the following. 
|> Scientists in a university environment are (at least in my country,Holland) 
|> graded mainly by there so called output, ie. publications in scientific 
|> journals. How likely is it for such an electronic journal to be appreciated
|> on this level. More precisely, will there be a change that it will be
|> considered for citation indexes and the like? 
 
   It is our long-term goal to create an fully accredited online
university. GNA is also the world's first virtual corporation, and
therefore also serves as a testbed for running organizations in the
21st century. 
 
   That any kind of "virtual" activity still carries the stigma of
non-seriousness is mainly due to the fact that the whole field is
very young and under hectic development - count the articles on the
"Information super highway" in international news magazines...I think
the world doesn't have a definition for "multimedia" yet -- it is
important to start a non-profit enterprise right now.
 
   Nobody can foresee how accepted such a (purely electronic) journal 
will be. In High Energy Physics I have witnessed the rise of preprint
bulletin boards which are in fact so much wanted by people (working
scientists, between Bombay and Berkeley) that they endanger the
existence of regular journals with their paper and staff costs etc.
   Our central library (of the biggest HEP lab in Germany) has almost
ceased to  distribute anything else but electronic preprints--I take
things like this as a sign for change. This is not to say that
mechanisms like peer review etc would (or should) be given up--their
adequate translations for electronic media have to be found (examples
do exist). Also I second Norman's view that "big names" are needed to
convince people of the nobility of the endeavour.
 
Thank you for your interest!
--
/////////////////////////////////////////////////////////////////////////////
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From fulling@sarastro.math.tamu.edu Wed Sep 29 20:48:17 CDT 1993
Date: Wed, 29 Sep 93 20:48:17 CDT
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu, fulling@SARASTRO.MATH.TAMU.EDU
To: LitProg@shsu.edu, bed_gdg@shsu.edu
Subject: Refereed electronic periodical for Literate Programming
 
>Date: Mon, 27 Sep 1993 10:44:26 CST
>From: "George D. Greenwade" <bed_gdg@SHSU.edu>
>What would the group think of a "refereed electronic periodical" for
>literate programming[?]
 
In principle I am very interested in this.  However, there are some
practical problems that need to be considered.
 
First, in what format will the journal be distributed?  Considering the
subject, surely it would be a frustrating travesty to be limited to a
pure ASCII end product.  So, do we get LaTeX files?  PostScript?
Example webs in their original source code?  (If so, I need to have
every tool -- AWEB, BWEB, CWEB, ... -- installed on my workstation,
just to read the journal.)  All of the above?
 
>It will be a long time before any major print periodical develops ...
 
Well, if the whole thing gets into PostScript, or even TeX, form, then
it will BE a print journal for anybody who chooses to send it through a
laser printer.  More seriously, if we expect that most readers will be
saving trees and reading the journal on a screen previewer, then
consideration should be given to making the page shape landscape rather
than portrait.  (I try to do this myself with preprints I receive
electronically, by halving the \vsize, but this often plays havoc with
the author's carefully adjusted page layout.)
 
Second, will the editor(s) perform the usual editorial functions of
copy editors of print journals, including correcting typographical and
grammatical errors and beating everything into a reasonably uniform
format?  I think this is essential for respectability, for being taken
seriously as a "real" journal of high standards.  Furthermore, this
task is even more important (and difficult) if we have the
technological problem of making TeX files compilable on every
subscriber's system (see above).
 
But this task (or even the simpler one of sending files back and forth
between authors and referees) is horrendous -- a full-time job.  At a
minimum I think it will require a secretarial-level person full time
and a professional-level person half time.  So now we need a source of
salary money....  Help!
 
			       Steve Fulling
			       fulling@math.tamu.edu
 
From Stefan.Farestam@cerfacs.fr Wed Sep 29 20:48:17 CDT 1993
Date: Wed, 29 Sep 93 20:48:17 CDT
From: Stefan.Farestam@cerfacs.fr
Reply-To: LitProg@SHSU.edu, Stefan.Farestam@CERFACS.FR
To: LitProg@SHSU.EDU
Subject: Re: LitProg Review (was Re: What does literate programming mean to
 
On Wed, 29 Sep 1993 08:24 +0000 (GMT), "Eric W. van Ammers"
<AMMERS@RCL.WAU.NL> posted:
> >  We would like to bundle any sort of "virtual" educational
> >activity -- a journal which is unlikely to ever never appear on real
> >paper fits in this category. We already have: a list of electronic
> >consultants, a collaborative (Hyper-) textbook project, an internet
> >meta library, and a virtual campus.
>
> I like the ida very much, but my mainproblem is the following.  Scientists
> in a university environment are (at least in my country, Holland)  graded
> mainly by there so called output, ie. publications in scientific  journals.
> How likely is it for such an electronic journal to be appreciated on this
> level. More precisely, will there be a change that it will be considered
> for citation indexes and the like? 
 
 Just to fuel this debate further (in a positive direction), I'm including
 below two announcements of electronic journals within the field of
 numerical analysis. If someone pursues this idea further, which I
 definitely think should be done, then it might be worth contacting the
 editors of those journals to maybe gain some valuable insights.
 
 Note that both of the journals listed below will also be printed in a small
 quantity, so as to be available by inter library loans.
 
 /Stefan Farestam
 
-----------------------------------------------
 
From: Lothar Reichel <reichel@mcs.kent.edu>
Date: Tue, 11 May 93 16:03:12 EDT
Subject: Electronic Transactions on Numerical Analysis
 
                           Call for Papers
            Electronic Transactions on Numerical Analysis
 
Scope: 
 
Electronic Transactions on Numerical Analysis (ETNA) is an electronic journal
for the publication of significant new and important developments in numerical
analysis and scientific computing. Papers of the highest quality that deal with
the analysis of algorithms for the solution of continuous models and numerical 
linear algebra are appropriate for ETNA, as are papers of similar quality that 
discuss implementation and performance of such algorithms. New algorithms for 
current or new computer architectures are appropriate provided that they are 
numerically sound. However, the focus of the publication should be on the 
algorithm rather than on the architecture. The journal is published by the Kent
State University Library in conjunction with the Institute of Computational 
Mathematics at Kent State University. Mathematical Reviews will receive all
papers accepted for publication in the journal and review them as appropriate.
ETNA is registered with the Library of Congress and has ISSN 1068-9613.
 
Dissemination: 
 
On a quarterly basis, accepted manuscripts will be posted in a directory which 
is publicly accessible through Internet. The titles and abstract of these 
manuscripts will be e-mailed to registered departments and individuals and 
posted on public bulletin boards such as NA-digest. An individual who wishes 
to obtain a copy of a current or back manuscript can get a copy through 
anonymous FTP or by using a netlib-type mailer. We also plan to install 
Gopher. All manuscripts will be available in Post Script format. The first 
issue of ETNA will appear September 1, 1993. Funds made available by the 
Kent State University Library and the Kent State University make free 
subscription possible for at least three years. After this time period we 
may have to charge an annual fee from institutional subscribers. Since the 
operating costs for the journal are low, we envision that this fee will not 
be above $100 for institutional subscribers. Everybody at the subscribing 
institution will have access to ETNA by FTP, a netlib-type mailer or Gopher.
In addition, articles in ETNA can be obtained through interlibrary loan from
Kent State University Library. 
 
To register to receive ETNA's quarterly titles and abstract lists, please send
an e-mail message to etna@mcs.kent.edu. The subject of the message should be: 
ETNA registration. Titles and abstracts of papers published in ETNA will be 
e-mailed quarterly to the return addresses of all such requests. Inquiries for
further information should also be e-mailed to etna@mcs.kent.edu.
 
Submission, Acceptance and Refereeing:
 
Authors will normally submit papers for publication via e-mail, and they will 
be required to submit their manuscript in LaTeX or TeX using macros we provide.
Requests for macros can be sent by e-mail to etna@mcs.kent.edu. All papers will
be refereed. As soon as a paper has been accepted for publication in ETNA, it
will be entered into the ETNA data base. There are no annual page limitations, 
and, therefore, we are in a position to publish accepted manuscripts faster 
than many other journal. Manuscripts can be submitted NOW by sending them to 
the address etna@mcs.kent.edu.
 
Current Editorial Board:
 
L. Reichel         Kent State University
editor-in-chief    reichel@mcs.kent.edu
 
R.S. Varga         Kent State University 
editor-in-chief    varga@mcs.kent.edu
 
A. Ruttan          Kent State University
managing editor    ruttan@mcs.kent.edu
 
G.S. Ammar         Northern Illinois University         
J.W. Demmel        University of California, Berkeley    
J.J. Dongarra      University of Tennessee               
I.S. Duff          Rutherford Appleton Laboratory
M. Eiermann        University of Karlsruhe               
J.A. George        University of Waterloo                
G.H. Golub         Stanford University                    
W.B. Gragg         Naval Postgraduate School                   
M.H. Gutknecht     Swiss Federal Institute of Technology                   
V. Mehrmann        Technical University of Chemnitz-Zwickau
D.C. Sorensen      Rice University                   
G.W. Stewart       University of Maryland                   
O.B. Widlund       New York University
 
------------------------------
 
From: Julio G. Dix <JD01%SWTEXAS.BITNET@ricevm1.rice.edu>
Date: Fri, 14 May 93 10:48 CDT
Subject: Electronic Journal of Differential Equations
 
          ELECTRONIC JOURNAL OF DIFFERENTIAL EQUATIONS. (EJDE)
 
  The EJDE is published by Southwest Texas State University and
the University of North Texas. This is  a strictly electronic journal:
Articles are to be submitted and then provided to the mathematical
community  electronically.
 
                         SCOPE
 The EJDE will accept only first-rate original work,  subject to as
rigid a peer review process as is applied by the finest of today's
journals.
 
                         DISSEMINATION
 Abstracts of articles will be sent to subscribers as soon as accepted
for publication (free of charge).  Manuscripts and abstracts will be
posted in a directory which is publicly accessible through Internet.
Also, the American Mathematical Society will provide access to this
journal through the E-math gopher.
  Manuscripts will be available as TeX files. Which means that your
local computer needs TeX processing facilities. Manuscripts can be
obtained also as also as DVI or POSTSCRIPT files.
  Hard copies will be preserved for posterity. The publishers will
originate and maintain copies at the libraries of both institutions.
Photocopies of articles can be obtained from these libraries using the
Interlibrary Loan system.  (We are in the process of obtaining the ISSN
number.)
 For information through internet make sure your computer emulates a
VT100 terminal and the type
        telnet ejde.math.unt.edu
at the login prompt type "gopher" (without quotations), then select 1
for EJDE and follow the instructions on the screen.
 
                        EDITORIAL BOARD
 
 P. Bates (Brigham Young University)
 A. Bloch (Ohio State University)
 J. Bona (Pennsylvania State University)
 L. Caffarelli (Institute for Advanced Study)
 C. Castillo-Chavez (Cornell University)
 C. Chui (Texas A & M University)
 M. Crandall (University of California at Santa Barbara)
 E. Di Benedetto (Northwestern University)
 G. B. Ermentrout (University of Pittsburgh)
 J. Escobar (Indiana University)
 L. C. Evans (University of California at Berkeley)
 J. Goldstein (Louisiana State University)
 C. Groetsch (University of Cincinnati)
 I. Herbst (University of Virginia)
 C. Kenig (University of Chicago)
 R. Kohn (Courant Institute)
 A. Lazer (Miami University)
 J. Neuberger (University of North Texas)
 P. Rabinowitz (University of Wisconsin)
 R. Shivaji (Mississippi State University)
 R. Showalter (University of Texas)
 H. Smith (Arizona State University)
 P. Souganidis (University of Wisconsin)
 N. Walkington (Carnegie-Mellon University)
 P. Waltman (Emory University)
 
                        SUBMISSIONS
 Submissions should be files in one of the following formats:
TeX, LaTeX, AMS (LaTeX or TeX). Graphics can be attached using either
PicTeX or Postcript.  There is no page charge.
 We are accepting manuscripts NOW; send your files via E-mail to
                        editor@ejde.math.unt.edu
 Please keep a copy of your submissions;  we are not responsible  for
lost files.
 
                        COPYRIGHTS
 By submitting a manuscript the author(s) agree that the copyright
of the  article is transferred to the publisher if and when the
article is accepted for publication.
 
 Thanks for your attention and I am looking forward to see your
sumissions to the EJDE.
 
 Julio G. DiX
 Department of Mathematics
 Southwest Texas State University.
 
From cgra@btma74.nohost.nodomain Wed Sep 29 20:48:17 CDT 1993
Date: Wed, 29 Sep 93 20:48:17 CDT
From: cgra@btma74.nohost.nodomain (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: New Math Notation #3107
 
In article <CIEMJW.93Sep28071522@sealion.ssd.lmsc.lockheed.com>, ciemjw@sealion.ssd.lmsc.lockheed.com (Jon Weygandt) writes:
 
>I new to literate programming, but not engineering and could not
>resist jumping in on this topic ...
 
And I said only a day or two ago that I would "shut up", but I can't resist
responding...
 
>2 specific examples of where real world engineering notation omit some
>very cirtical information necessary for precise implementation, the
>information is apparent in the context of how it is used, but even to
>the human reader it may not be obvious:
>
>Vectors:
>	The standard vector notation does not differentate between
>"free vectors" and "bound vectors".
 
This is due to the pernicious influence of Newton's theory of relativity. ;>
But if you need to have a "point alpha" in your system then you do what
everyone else does, you extend the notation.  Bound vectors in upright
bold and unbound in sloping bold, perhaps?  Or maybe underpin the bound
vectors with an underscore or a dot?  Then define your algebra:
(B = bound, U = unbound, S = scalar (printed in non-bold type))
 
S + S -> S            S - S -> S         S * S -> S        S / S -> S
B + S is invalid      B - S is invalid   B * S -> B        B / S -> B
U + S is invalid      U - S is invalid   U * A -> U        U / S -> U
B + B is invalid      B - B -> U         B * B -> S        B / B is invalid
B + U -> B            B - U -> B         B * U may or may not be valid, it
depends on what vector product means in your application... anyway I hope
you get my drift by now.  My point is that once you Define Your Notation,
mathematics is way more expressive than C or FORTRAN.  You could use a
language like C++ to enforce this algebra through classes, and you could
use some kind of Hungarian notation to incorporate the class of every object
into its name, but it doesn't exactly leap out of the page at you, does it?
 
>[...]
>Units, Temperatures:
>	It is standard to apply a simple unit designation after a
>number, but in the case of temperature there is a similar concept as
>to vectors.  There exist actual temperatures of objects "absolute
>temperatures" and there exist temperature differences "relative
>temperatures".  [...]
 
Easy peasy.  Use \deg K for absolute temperatures and \deg C for relative.
Just remember to Define Your Notation, so we all know what is going on.
 
>        Jon Weygandt
>
>        Lockheed Missiles and Space Co.
>        Sunnyvale CA
 
__________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
   Ignore my broken mailer - the addresses above are the only truth
__________________________________________________________________________
Alle menschen sind Auslaender.                              Fast ueberall.
 
From sven@robots.ox.ac.uk Thu Sep 30 13:21:22 GMT 1993
Date: Thu, 30 Sep 1993 13:21:22 GMT
From: sven@robots.ox.ac.uk (Sven Utcke)
Reply-To: LitProg@SHSU.edu, sven@ROBOTS.OX.AC.UK
To: LitProg@SHSU.EDU
Subject: cnoweb for LaTeX?
 
Hi everyone,
 
I wonder if there is something like cnoweb for LaTeX. I think I could
sell that to me colleagues and consequently get them hooked on literate
programming after a while.
 
Only: There is no way to get ANY of them using plain TeX. So what I
need is a LaTeX-version!
 
Thanks
 
Sven
 
From sven@robots.ox.ac.uk Thu Sep 30 13:22:52 GMT 1993
Date: Thu, 30 Sep 1993 13:22:52 GMT
From: sven@robots.ox.ac.uk (Sven Utcke)
Reply-To: LitProg@SHSU.edu, sven@ROBOTS.OX.AC.UK
To: LitProg@SHSU.EDU
Subject: \footnote in FWEB
 
Hi everyone,
 
I have a simple question (hope same holds true for the answer):
 
How can I use \footnote in FWEB?
 
Thanks for any help
 
Sven
 
From Eric Thu Sep 30 15:56 +0000 1993
Date: Thu, 30 Sep 1993 15:56 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LITPROG@shsu.edu
Subject: CLiP for VAX/VMS
 
[A			CLiP for VAX/VMS
 
A VAX/VMS version of the CLiP system is available by anonymous ftp on
 
		sun01.info.wau.nl
 
from the directory
 
		/clip/vax_vms
 
Remark that the EXE-files are binaries which should be copied in BINARY mode.
All other files can be copied in ASCII mode.
 
For additional information which is not in the READ_ME or MANUAL files 
please contact me at the address below.
 
Eric van Ammers
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From krommes@theory.pppl.gov Thu Sep 30 15:56 +0000 1993
Date: Thu, 30 Sep 1993 15:56 +0000 (GMT)
From: krommes@theory.pppl.gov (John Krommes)
Reply-To: LitProg@SHSU.edu, Krommes@Princeton.EDU
To: LitProg@SHSU.EDU
Subject: Re: \footnote in FWEB
 
Sven Utcke writes:
 
>> How can I use \footnote in FWEB?
 
Footnotes may not work properly in FWEB versions through 1.30, which
inherited a \output routine from previous authors.  This problem is fixed
in version 1.40, to be released shortly.  This version offers much more
faithful LaTeX support, in that the LaTeX \output routine, sectioning
commands, etc. are used.
 
--
--- John                      (Mail to krommes@princeton.edu is forwarded to
                              krommes@lyman.pppl.gov == 198.35.4.70.  
krommes@princeton.edu         Ftp files to/from ftp.pppl.gov, NOT princeton.edu
                              or lyman.pppl.gov.)
 
From Nelson Thu Sep 30 14:31:29 MDT 1993
Date: Thu, 30 Sep 93 14:31:29 MDT
From: "Nelson H. F. Beebe" <beebe@math.utah.edu>
Reply-To: LitProg@SHSU.edu, beebe@MATH.UTAH.EDU
To: LitProg@SHSU.edu
Subject: Literate programming bibliography: a plea for contributions
 
The literate programming bibliography stored in the files litprog.* in
/pub/tex/bib on ftp.math.utah.edu (via e-mail: "send index from
tex/bib" and "help" to tuglib@math.utah.edu) is now at edition 1.30,
with 61 entries.
 
In view of the substantially increased activity on this list in the
last several months, I suspect that publications have increased as
well, so PLEASE SEND ME YOUR CONTRIBUTIONS of new publications about
literate programming, after checking that they are not already present
in the latest litprog.bib.
 
It will save me time if your contributions are already in BibTeX form,
with complete author/editor lists, full titles, page ranges (for
journal articles), and publisher/address/year for books.  I can
usually get ISBN and LCCN (Library of Congress Catalog Number) entries
from on-line library catalogs if you cannot supply them.
 
I have utilities for converting UNIX bib/refer entries to BibTeX form,
so that format is convenient too.
 
Here is the latest entry (entered yesterday), as an indication of
style and contents:
 
@String{pub-MH          = "McGraw-Hill"}
@String{pub-MH:adr      = "New York, NY, USA"}
 
@Book{Gurari:TLD94,
  author =       "Eitan M. Gurari",
  title =        "{\TeX} and {\LaTeX}: Drawing and Literate
                 Programming",
  publisher =    pub-MH,
  year =         "1994",
  address =      pub-MH:adr,
  bibdate =      "Wed Sep 29 17:55:14 1993",
  acknowledgement = ack-nhfb,
}
 
[This book is apparently not yet out, but should soon be.  I've asked
the author to supply ISBN, LCCN, and price values as soon as they are
available.]
 
Each entry carries an acknowledgement key/value pair, so you get a
candlepower of lasting glory for your help in keeping this
bibliography up-to-date.
 
Only material published in books or refereed journals will normally be
included.  Technical reports are rarely widely available, and are soon
out of print, so I tend to exclude them.  However, if they are
actively maintained in electronic form, and are Internet-accessible,
then they will be included in litprog.bib.
 
Nelson H. F. Beebe                      Tel: +1 801 581 5254
Center for Scientific Computing         FAX: +1 801 581 4148
Department of Mathematics, 105 JWB      Internet: beebe@math.utah.edu
University of Utah
Salt Lake City, UT 84112, USA
 
From ross@wattle.itd.adelaide.edu.au Thu Sep 30 14:31:29 MDT 1993
Date: Thu, 30 Sep 93 14:31:29 MDT
From: ross@wattle.itd.adelaide.edu.au (Ross Williams)
Reply-To: LitProg@SHSU.edu, ross@WATTLE.ITD.ADELAIDE.EDU.AU
To: LitProg@SHSU.EDU
Subject: A C exceptions package written using FunnelWeb.
 
Dear Literates,
 
One thing that FunnelWeb has lacked since its release is a good example.
Now I've written one. I hope you find it of interest either from a literate
programming point of view, or simply as a useful C package.
 
Ross.
 
A C Exceptions Package Written Using the FunnelWeb Literate Programming Tool
 
Date   : 29 September 1993.
Author : Ross N. Williams (ross@guest.adelaide.edu.au).
Snail  : 16 Lerwick Avenue, Hazelwood Park 5066, Australia.
Phone  : +61 8 379-9217 (24 hours).
Fax    : +61 8 373-4911 (24 hours).
Status : This covering document is Copyright (C) Ross Williams, 1993.
         However, permission is granted to make and distribute verbatim
         copies of this document provided that this information block
         and copyright notice is included.
 
     ABSTRACT: This document describes the release of a C package that
     provides Ada-like exceptions for the C programming language. The
     package is written in a literate style using the FunnelWeb literate
     programming tool, and so acts not only as a useful C package, but
     also as an example of a literate program written in a commercial
     environment. This distribution provides enough dependent files to
     allow the package to be printed and used without having to install
     FunnelWeb.
 
Introduction
------------
Since releasing my literate programming tool FunnelWeb over one year
ago, I have been aware of the pressing need for an example program
written using FunnelWeb. Despite the fact that I have written ALL my
code since that time using FunnelWeb, I haven't felt motivated to
release any of the code, partly because most of it is proprietary, and
partly because I didn't want to have to go through the detail of
extracting and shipping the header files upon which the published code
would depend.
 
Recently, however, I identified a package that I felt motivated to
publish for three reasons. First, it is a package that many C
programmers could find extremely useful. Second, it is a tricky
package and so it demonstrates very well the benefits of literate
programming without in any way being a contrived example. Third, being
a low-level package, it does not depend on many other packages or
header files (only my style file and a tiny assertions package). For
these reasons I have decided to make the package public. I am hoping
that the package will not only act as a useful piece of software for C
programmers, but will also act as a flagship example for FunnelWeb and
literate programming in general.
 
Brief Package Description
-------------------------
The package is written in C and provides a very clean and safe
implementation of Ada-like exceptions for the C programming language.
The package is implemented using the ANSI standard setjmp and longjmp
functions.
 
Here is an example of the sort of facility the package provides. The
example is contrived, but gives a taste of what the package can do.
The first line is the declaration of the exception and appears in the
variable declaration section.
 
   EX_LOCAL(read_err,"read_err: Error reading an input file.");
   ...
   EX_BEGIN
      while (more_input(input))
        {
         read_file(input,buffer);
         write_output(output,buffer);
        }
   EX_FORGET
      EX_WHEN(read_err)
         error_flag = TRUE;
         fprintf(logfile,"Read error. Aborting read.");
         file_close(input);
   EX_END
 
A "Normal" Package
------------------
An important aspect of this publication is that this exceptions
package was not in any way "polished" for publication. The exceptions
package was chosen because it is a tricky package and demonstrates the
use of literate programming well (other, more boring, packages are
quite-rightly less-intensely documented). But apart from this aspect,
the literate programming style embodied in "except.fw" is
representative of the way I normally do programming, and if you
looked, you would find a dozen or so similarly-prepared modules in my
personal C library. In fact the exceptions package was prepared in a
text editor (using FunnelWeb to generate except.h and except.c and
ex_test.c) without ever generating except.tex, or printing or
previewing the typeset documentation at all. The only concession made
to publication was that just before publication, I typeset and printed
except.tex once (just to make sure that the whole document wasn't set
in italics or something :-) and subsequently corrected 23 minor
grammatical and spelling errors in the documentation parts of the
document before shipping.
 
This exception package and other packages like it were constructed as
part of the development of a commercial product which my company
Rocksoft^tm Pty Ltd intends to release "real soon now". Thus, this
exceptions package represents the practical use of FunnelWeb in a
real commercial environment.
 
How To Print The Package
------------------------
To print the package, FTP the file "except.tex" OR "except.ps" from
ftp.adelaide.edu.au/pub/funnelweb/examples/except.tex (or .ps) and
print out a copy of the FunnelWeb-prepared documentation. The document
is 43 pages long (the actual code is much shorter).
 
If you like what you read, you can then FTP the other files from the
same directory and start using the package. You don't need FunnelWeb
to print or use the package, as I have done all the FunnelWeb
processing for you. The C package itself is embodied in except.h and
except.c which in turn require style.h and as.h and as.c. All of
these files are supplied.
 
FunnelWeb itself is available in "ftp.adelaide.edu.au/pub/funnelweb/".
 
Portability
-----------
So far I have only compiled and tested this package on a Macintosh
using THINK C. However, I expect it to be fairly portable, as I have
become very aware of portability issues in the last few years, and
this sensitivity should manifest itself in the code.
 
If you do decide to FTP and compile the source code for the exceptions
package, even if you do encounter one or two portability problems, the
test suite provided in ex_test.c will provide assurance that the
package is working.
 
Summary of Files
----------------
The following table describes the files in the distribution. Each file
is either "Source" (i.e. hand written) or was generated from another
file. "except.h", "except.c", "ex_text.c", and "except.tex" were all
generated by applying FunnelWeb to the file "except.fw" using the
command "fw except -t". "except.ps" was generated from "except.tex"
using TeX and a .dvi-to-PostScript conversion program (OzTeX/OzTeX in
this case).
 
Although the exceptions package is basically self-contained in
except.fw, the code it generates is written using my normal C style
and so is dependent on two external packages: my assertions package
(as) and my style header file. Instead of incorporating these packages
into the exceptions package, I have chosen to provide stripped down
versions of these support files with the exceptions package. These two
packages provide a few minor stylistic definitions. I decided not to
ship FunnelWebized forms of these files because 1) I didn't want to
detract attention from the main exception package, 2) they were big
and messy and only part of them was required, 3) they were remenants
from the non-FunnelWebized FunnelWeb source code itself, and for this
reason have so far eluded FunnelWebization in my C library (i.e.
FunnelWebized forms don't yet exist :-).
 
+------------+---------------------------------------------------------------+
| Gen From   | File         Description                                      |
+------------+---------------------------------------------------------------+
| Source     | 0README    - This summary file.                               |
| Source     | as.c       - Assertion package implementation file.           |
| Source     | as.h       - Assertion package specification  file.           |
| except.fw  | except.c   - Exceptions package implementation file.          |
| Source     | except.fw  - FunnelWeb source file for exceptions package.    |
| except.fw  | except.h   - Exceptions package specification file.           |
| except.tex | except.ps  - PostScript file with typeset form of except.fw   |
| except.fw  | except.tex - TeX file containing a typeset form of except.fw. |
| except.fw  | ex_test.c  - Test program for the exceptions package.         |
| Source     | style.h    - Style header file.                               |
+------------+---------------------------------------------------------------+
 
--<End of Announcement>--
 
From johnson@cs.uiuc.edu Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: johnson@cs.uiuc.edu (Ralph Johnson)
Reply-To: LitProg@SHSU.edu, johnson@CS.UIUC.EDU
To: LitProg@SHSU.EDU
Subject: Re: Interactive literate programming
 
>   >There is a fairly nice system for the Apple Macintosh. It's called the
>   >"Literate Programmer's Workshop" and you'll find it at ftp.apple.com,
>   >pub/literate.prog and doubtlessly in other places.
 
>Does this require MPW?
 
LPW will convert your document into a set of files that you can feed
to MPW, and it will take error messages from MPW and show you where
they came from in your document.  So, LPW seems to require MPW to
actually compile programs, but it doesn't require it just to print
documentation or to edit files.
 
There is a humorous comment in their documentation where they say
that LPW will run on any version of Mac O.S. and requires 600 K,
but that it is not very useful without MPW, which requires System 7
and 4 megabytes.  This seems like a problem that needs to be fixed!
 
-Ralph
 
From warren@math.psu.edu Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: warren@math.psu.edu (Warren Wood)
Reply-To: LitProg@SHSU.edu, warren@MATH.PSU.EDU
To: LitProg@SHSU.EDU
Subject: Re: Interactive literate programming
 
In article <CF2pnE.CsC@cs.uiuc.edu> johnson@cs.uiuc.edu (Ralph Johnson) writes:
 
   >There is a fairly nice system for the Apple Macintosh. It's called the
   >"Literate Programmer's Workshop" and you'll find it at ftp.apple.com,
   >pub/literate.prog and doubtlessly in other places.
 
   i got a copy of it.  It *is* a nice system.  The basic idea behind
   it is a lot different from Web-like systems.  You write a document using
   a WYSIWYG editor.  Every section has a different "style" that is
   defined by a style sheet.  The document is designed to be readable
   by humans.  You get the machine-readable documents by selecting
   sections of particular styles and running them through various
   translators.  This is all automatic, and it looks like you only
   have to worry about the details if you are trying to make it work
   with a new language.
 
   You have to have a Mac to read the documentation, which is written
   in itself, of course.  But I'd advise anyone interested in these kinds
   of systems to find a Mac and at least try to print off the documentation.
 
   -Ralph Johnson
 
Does this require MPW?
 
From dak@hathi.informatik.rwth-aachen.de Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: dak@hathi.informatik.rwth-aachen.de (David Kastrup)
Reply-To: LitProg@SHSU.edu, dak@HATHI.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.EDU
Subject: Lack of ftp-able LitTool Examples
 
I have one problem: there are lots of tools around now, and lots
of FAQs and so on. I would like to decode on one specific tool
to choose for most tasks. There might be quite a point in having
at least one language independent tool for Makefiles, weird scripts,
shell programming, data arrangement, you name it. But I digress.
 
Woukd it be possible that the fiercest advocates of any tool do
not
1) proudly claim all their systems advantages, but
2) Make a presentation consisting of
a) small examples displaying all important features, both as verbatim source
   text and tangled (or whatever) graphic result.
b) compile this in a small .dvi file, and put it at ONE ftp-able place
   in one directory with *JUST* other representations in the same place.
It would be prudent (possibly) to include a ps-version as well, since
LitProgging might not always stay at TeX, and a WinWeb or so should have
a way to make such a rep as well (and some might decide on their
formatter only *after* they have seen how the tools which need it
are). If Word cannot produce ps, w e l l...
 
It would be even better to have one .dvi file with all that (or ps-file),
but I doubt that the different macro packages needed would be *very*
compatible. Besides, some work only with TeX, some with LaTeX, some
with both...
 
But let's leave the advocacies for later...
 
Volunteers? This might help a lot...
-- 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From schrod@iti.informatik.th-darmstadt.de Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Usage of RCS in *WEB Documents (was Re: Some thoughts)
 
In article <1993Oct14.160744.252@kocrsv01.delcoelect.com>,
c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) described
his problems in the usage of RCS & *WEB.
 
I've worked on this a few months ago, and I can release the results if
there is enough interest. But first a few comments on this article, I don't
quote fully due to its length.
 
 -- I don't agree that information about the history of a program are
    ``almost always of short term value, if any.'' For me, they are an
    integral part of any software development. (Those who don't know
    their past are condemned to repeat it...) How many times has an
    error been repeated because it was `obviously' the right way to do
    it; and nobody knew that it was done before already?
 
 -- ``I find it annoying that I have to thumb through multiple pages of
    these before I get to the first source line.'' I agree with you --
    put them in an appendix at the end and put a reference to this
    appendix at the start of your document.
 
 -- [On the work with RCS]: ``Each time, a source file is checked back
    in, people put a line or two of comments.''
    	This is a major problem. RCS logs like `Fixed.' (from your
    example) are useless. But RCS encourages these types of logs since
    it simply reads them from the standard input. In our experiences
    providing an editor for typing in log messages leads to longer,
    better phrased log messages.
 
So, what did we do?
 
 -- We changed RCS. In our version, it's possible to
 
	. define the used RCS keywords in configuration file(s).
	     I.e., one can use $XConsortium$ instead of $Id$... ;-)
 
	. define the way the revision log is output.
	     E.g., one can output it as
 
	     	\begin{RCSlog}
                $Log: rcs.doc,v $
                \Revision 1.2  1993/09/08  15:49:00  schrod
                Used canonical names for category codes.
 
	  	...
                \end{RCSlog}
 
	  Of course, it isn't difficult to write an appropriate
	  environment to typeset this.
 
	. use an editor for the input of the Log text.
 
	. have a better approximation of the comment leader.
 
 -- I wrote a new rcs style option. This style option is upward
    compatible both to the one by Piet v.Oostrum and to a previous revision
    from me. (It was a Bad Thing anyhow that there were two incompatible
    style options with the same name.)
    	This style option supports typesetting of revision logs, if
    used together with the new RCS.
 
Why didn't we distribute it yet?
 
 -- We need a smoother integration into CVS, we're not interested in
    RCS per se.
 
But if there is enough interest, I can make a pre-release ready.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From lynbech@daimi.aau.dk Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: lynbech@daimi.aau.dk (Christian Lynbech)
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.EDU
Subject: Re: Revision Control
 
It wasn't exactly clear to me what RCS style Lee Wittenberg was referring to,
so I thought I would post the most excellent rcs.sty written by 
Piet van Oostrum. Not necessarily the one true way, but nice if you haven't
something of the sort in advance. Check out the stuff below my signature.
 
The way I use it, is to mark each page with state, revision number and date in
the footers, using fancyheadings.sty
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
office: R0.32   phone: 5034	| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
%%
%% REVISION CONTROL 
%% Piet van Oostrum, Dept of Computer Science, Utrecht University,
%% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands.
%% Telephone: +31 30 531806   Uucp:   uunet!mcsun!ruuinf!piet
%% Telefax:   +31 30 513791   Internet:  piet@cs.ruu.nl
%%
%% To use the RCS field XXX (e.g. XXX=Header or XXX=Date) in a (La)TeX
%% document include
%%  \RCS$XXX$
%% This is expanded by RCS into \RCS$XXX: <value> $
%% The TeX macro above defines (globally) \RCSXXX to be <value>.
%% If the field XXX is not RCS-expanded \RCSXXX is defined as the null string.
%%
%% Exception:
%% For XXX=Date, if the macro \today is defined, the RCS date is
%% reparsed into the format defined by \today, with \year, \month and \day
%% bound to the values in the RCS Date field. This allows you to get a
%% language-dependent date format, e.g. by using dutch.sty, german.sty etc.
%% The time part is put into the macro \RCSTime. The original RCS date can
%% be found in \RCSRawDate.
%% Also the default value for \RCSDate is the value of \today.
%%
%% Note: This kind of special-casing can be applied to other fields also by
%% defining a macro \RCS@XXX. This macro will be called with the field
%% <value> as argument and should do all the work (including defining \RCSXXX).
%%
%% N.B:
%% Verbatim insertion can not be done in this way. Just use \verb$XXX$, or
%% put $XXX$ in a verbatim environment. And of course you can put a field
%% in comment (useful for the Log entry).
 
\def\RCS$#1${\RCS@#1:$}
\def\RCS@#1:#2${%
        {\def\temp@{#2}%
        \ifx\temp@\empty
                \RCS@@#1:$%
        \else
                \RCS@@@#1:#2$%
        \fi}
}
\def\RCS@@#1:#2${\RCS@@@#1: #2 :$}
\def\RCS@@@#1: #2 :${%
        \expandafter\ifx\csname RCS@#1\endcsname\relax
                \expandafter\gdef\csname RCS#1\endcsname{#2}
        \else
                        \csname RCS@#1\endcsname{#2}
        \fi
}
\def\RCS@Date#1{%
        \gdef\RCSRawDate{#1}%
        \ifx\today\relax
                \gdef\RCSDate{#1}%
        \else
                \ifx\temp@\empty %Note: temp@ still valid from the \RCS@ call
                        \gdef\RCSDate{\today}%
                \else
                        \RCS@@Date #1$%
                \fi
        \fi
}
\def\RCS@@Date #1/#2/#3 #4${
        \gdef\RCSTime{#4}%
        \def\year{#1}\def\month{#2}\def\day{#3}% Note: we are in a group by RCS@
         \xdef\RCSDate{\today}
}
\def\RCSTime{}
 
From d.love@dl.ac.uk Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: d.love@dl.ac.uk (Dave Love)
Reply-To: LitProg@SHSU.edu, d.love@DL.AC.UK
To: LitProg@SHSU.EDU
Subject: Re: Some thoughts
 
>>>>> On Fri, 15 Oct 93 16:08:34 +0100, coates@spectro.jussieu.fr said:
 
 coates> current LitProg tools are certainly geared towards telling
 coates> you how the code works, as opposed to why it went wrong after
 coates> it was working in the first place.
 
The `doc' system for TeX does include a `\changes' feature to record
brief information about what was changed when and why; this is indexed
by version number at the end.  Major explanations of this sort of
thing probably belong in the commentary, though.
 
From rml@genesis.MCS.COM Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: rml@genesis.MCS.COM (Ryan Lee)
Reply-To: LitProg@SHSU.edu, rml@GENESIS.MCS.COM
To: LitProg@SHSU.EDU
Subject: compu transcript
 
        Could someone tell me what sorts of programming contests/
 
activities/etc. I could put on my transcript for college? Although 
 
I don't plan to major in computer sciences, I am a computer enthusiast 
 
who programs intermediately with C and will likely remain involved with
 
computers. But unfortunately my high-school offers very few computer 
 
science courses and I haven't been able to fit any in. As a hobby my
 
knowlege of computers/programming is pretty decent but my transcript
 
does not show it.
 
        So, I have really two questions. The first is: will colleges look
 
at extracurricular computer science activities? And the second is:
 
what kind of activity could I do?
 
                                                        rml
 
From dak@hathi.informatik.rwth-aachen.de Mon Oct 18 14:57:30 GMT 1993
Date: Mon, 18 Oct 1993 14:57:30 GMT
From: dak@hathi.informatik.rwth-aachen.de (David Kastrup)
Reply-To: LitProg@SHSU.edu, dak@HATHI.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.EDU
Subject: Re: Lack of Literate Examples
 
Lee Wittenberg <leew@pilot.njin.net> writes:
 
>> What I really want to say, is (just repeating others) that some standard for
>> uploading should be defined, and I think this should require postscript source
>> to be included in the upload. 
 
>I agree.  I think that, at the very least, the original source (.w,
>.web, .nw, etc.) and a PostScript version of the typeset output should
>be provided.  I think this would disenfranchise the least number of
>people.
 
I agree on both of these to be included, for they have a certain chance to
allow a glance for those not yet into TeX and WEBs. The WEBs are, of
course, important to show how it is done, and the ps for the results.
It is a bad idea to require you download tools before glancing at them.
 
However, where appropriate, I would opt for a formatting system dependent
file as well which needs as few additions as possible.
 
For troff, this would mean a source file with macro package *included*
(if an own is required), for TeX a .dvi-file should be ok.
 
Note that there are TeX systems around without Postscript support, and
the same goes for troff.
-- 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From bart@cs.tamu.edu Mon Oct 18 17:37:58 GMT 1993
Date: Mon, 18 Oct 1993 17:37:58 GMT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: LitProg@SHSU.EDU
Subject: Inline comments and abstraction
 
It was written that the ordinary C-style comments were not even
well typeset.  I have no idea what was meant by that unless it was
desired to have them not typeset at all.  What was done is the comments
are formatted like the documentation portions of sections.
 
There are some places where this style of comment is a great help and
far better than having an excess of trivial sections.  A good example
is section 11 of TeX.web.  DEK declared a large number of constants
and a comment on each.  That comment often includes a wonderfully
informative statement about relationships that must exist between
other constants...  These comments make extensive use of the same
`escape to TeX mode' that also exists throughout his webs.  Most
will reference variables.
This kind of precision is a great help.  I remember being confused
in my early reading about unix.  The feature of being case sensitive
is often mentioned and then when a command starts a sentence it is
capitalized!
 
I also note that he called these small parts sections or modules.
(He used the words interchangeably.)  I think that is a far better
term than scraps because they were intentional, not leftovers as
in most of the definitions of scrap.
 
Bart Childs
 
From vrkaramc@mtu.edu Mon Oct 18 17:37:58 GMT 1993
Date: Mon, 18 Oct 1993 17:37:58 GMT
From: vrkaramc@mtu.edu (Varada R. Karamchedu)
Reply-To: LitProg@SHSU.edu, vrkaramc@MTU.EDU
To: LitProg@SHSU.EDU
Subject: Chuck Moore etc etc THANKS !!
 
To all who replied by email and posted on the net answering 
my query, thank you very much.  Catch you later.
 
-Raj
 
From schrod@iti.informatik.th-darmstadt.de Mon Oct 18 17:37:58 GMT 1993
Date: Mon, 18 Oct 1993 17:37:58 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Levels of Abstraction
 
In article <shfCF3szB.EDC@netcom.com>, shf@netcom.com (Stuart Ferguson) writes:
> 
> It seemed like a step backwards to me to have a nicely typeset document
> describing a program and then have the code scraps contain untypeset
> comments in the code as if it were going to be read by a machine. [...]
> For some reason, Knuth chose to use inline
> comments to describe portions of his code instead of TeX,
 
Sorry, but I don't understand you. The inline comments of CWEB are of
course in TeX mode, and therefore you can make use of TeX markup
there as well. If it's good style (and good looking ;-) to put a
picture environment there might be questionable, but it's possible. I
prefer to regard inline comments as the footnotes of program code:
Used with care they can enhance the understanding of the document at
large.
 
Btw, that's no new feature. WEB did it already -- see my sig.
 
So, would you please elaborate your critique that CWEB/WEB/FWEB
inline comments are (a) not TeX material, and (b) useless?
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	    @d infinity=255 {$\infty$ (approximately)}
							[DEK, in weave.web]
 
From shf@netcom.com Mon Oct 18 17:37:58 GMT 1993
Date: Mon, 18 Oct 1993 17:37:58 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: Levels of Abstraction
 
+-- C. M. Sperberg-McQueen <U35395@uicvm.uic.edu> writes:
| Stuart Ferguson wrote:
| > A good example of how literate programming tools break down is the
| > example CWEB text that Knuth himself provides.  In his toy example
| > of a word count program, the code scraps often contain ordinary
| > C-style comments.  These comments (not even well typeset) indicate
| > the need for a finer granularity of abstraction than that provided
| > by the scrap mechanism.  In-line comments allow descriptions of
| > fragments of scraps that CWEB does not.
| I am finding it hard to understand how your logic works here:  as
| a demonstration that literate programming tools cannot handle comments
| on fine-grained details, you point out that Knuth's web for wc
| contains (how odd) comments on fine-grained details.  Since Cweb
| allows inline comments, how is it possible for "In-line comments
| [to] allow descriptions ... that CWEB does not"?
 
It seemed like a step backwards to me to have a nicely typeset document
describing a program and then have the code scraps contain untypeset
comments in the code as if it were going to be read by a machine.  Part
of what I expect from a literate programming tool is the ability to write
prose which describes each and every important detail of a program at the
level at which it occurs.  For some reason, Knuth chose to use inline
comments to describe portions of his code instead of TeX, and I think he
did this not because it was a good way to write commentary, but because
the alternative was worse.  He could have added another scrap for each
item which he felt needed comment, but I would guess that Knuth thought
that would break the code up too much.  This suggests a problem to me --
that the scrap mechanism is not sufficient for properly explaining all 
the details in a C program.
 
Saying that "Cweb allows inline comments" is not the same as saying that
Cweb handles inline comments *well*.  It's a small point, and it wasn't 
the main thrust of what I was trying to say, but it really did bother me.
Those few C-style comments seemed to poison the whole idea of programs
written for people and not compilers.
-- 
		Stuart Ferguson		(shf@netcom.com)
			"Oh Dear Lord -- the canary exploded!"
 
From schrod@iti.informatik.th-darmstadt.de Mon Oct 18 17:37:58 GMT 1993
Date: Mon, 18 Oct 1993 17:37:58 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <29v3ne$8l0@TAMUTS.TAMU.EDU>, bart@cs.tamu.edu (Bart Childs) writes:
> 
> I also note that he called these small parts sections or modules.
> (He used the words interchangeably.)  I think that is a far better
> term than scraps because they were intentional, not leftovers as
> in most of the definitions of scrap.
 
I prefer the simple term `program part'.
 
For me, section is ok most of the time, but sometimes one must stress
the difference between this `numbered entities' and their subparts.
 
I _hate_ the term module. (In fact, Klaus and myself were one of the
pushers to delete this word of CWEB.) A module is an entity with a
distinct specification and implementation. One does not find this
distinction in WEB. The concept of a module, first outlined by
Parnas, later refined by Dennis, Ehrig & Mahr, and nowadays
modernized by Booch, is a central one to all software engineering
activities. It has _nothing_ to do with these WEB pieces. Please,
don't throw away the CS terms we have worked so long for!
 
For what it's worth, here is a definition of terms I use usually:
 
    Before we start with an overview of the implementation I want to
    explain the \cweb{} vocabulary I use while I guide you through this
    document. The commonly used terms sometimes denote two entities, but
    for the purpose of this style we need exact terms. I've tried to stick
    to a ``canonical'' computer science terminology.
 
    \begin{quotation}
 
    I distinguish two different structures in a \cweb{} file: The {\sl
    document structure\/} and the {\sl program structure}.
 
    A \cweb{} document consists of a series of {\sl sections}. Within
    this series some sections are especially emphasized, we call them the
    {\sl main sections}. (They are also called {\sl starred sections},
    since their corresponding \cweb{} tag is~|@*|.) These main sections
    have a title, ordinary sections are untitled. A table of contents may
    therefore list only the main sections. Note that there is no
    hierarchy in the sections, they are all on the same level, ie, they
    are numbered subsequently.
 
    Each section consists of three parts: (1)~the {\sl documentation
    part}, (2)~the {\sl definition part}, and (3)~the {\sl program part}.
    Each of these parts can be empty. The documentation part is mostly text
    with \LaTeX{} tags. In this text material from {\sl restricted program
    mode\/} can appear. The definition part consists of a series of either
    {\sl macro\/} or {\sl format definitions}. The program part is one
    piece of a refinement, identified by a name (see below).
 
    A \cweb{} program consists of a tree of {\sl refinements}. A
    refinement is a list of program parts with the same name, ordered in
    appearence. The root of the tree is the refinement with the special
    name~|@c|. The program text is defined by the DFS (ie, infix-order)
    traversal of the tree.
 
    \end{quotation}
 
    \noindent The terminology outlined above is an overspecification for
    the \LaTeX{} style we're implementing here---nevertheless, the
    context of my explanation should be clear now.%
 
(That's a verbatim copy from the cweb style.)
 
Any critic? comments?
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
    ``Real programmers can write Fortran in any language.'' [... Well,]
    Real interface programmers can implement vi in any software envionment.
						[Hartson, Brandenburg, Hix]
 
From bart@cs.tamu.edu Mon Oct 18 17:37:58 GMT 1993
Date: Mon, 18 Oct 1993 17:37:58 GMT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: LitProg@SHSU.EDU
Subject: Sections  modules  chapters
 
Thanks to Joachim for his posting that addressed an omission from
my previous posting.  He (and others) were eloquent some time ago
about the use of the term module ...
 
I had intended to reference that an point out that we adopted some
of that for the latest rewrite on web-mode earlier in the year.
 
We call the sections that begin with @* (in WEB, CWEB, and FWEB)
by the name `chapter' and the others simply `section.'
 
Thus we have keybindings like C-c gc  `go to chapter' ,,,
 
Bart Childs
 
From marcus@x4u.desy.de Tue Oct 19 13:51:54 GMT 1993
Date: Tue, 19 Oct 1993 13:51:54 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: Revision Control
 
>>>>> On 18 Oct 1993 09:10:38 GMT, lynbech@daimi.aau.dk (Christian Lynbech) said:
 
|> It wasn't exactly clear to me what RCS style Lee Wittenberg was referring to
 
He was referring to the standard rcs.sty from the CTAN archives
(e.g. pip.shsu.edu:/tex-archive/archive-tools/fileshdr/rcs.sty),
by Nelson Beebe (acc. to private communication).  I have had problems
using the only keyword \RCSID{$Id$} in noweb pgms though. Will be
happy to try this one now.
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u.desy.de Tue Oct 19 14:09:13 GMT 1993
Date: Tue, 19 Oct 1993 14:09:13 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: Usage of RCS in *WEB Documents (was Re: Some thoughts)
 
>>>>> On 18 Oct 1993 11:22:23 GMT, schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) said:
 
[...comments on RCS & WEB and a new RCS style by Schrod...]
 
|> Why didn't we distribute it yet?
 
|>  -- We need a smoother integration into CVS, we're not interested in
|>     RCS per se.
 
|> But if there is enough interest, I can make a pre-release ready.
 
I am also not particularly interested in having such a style for RCS
alone. I am trying to drag a local collaboration into the use of
both CVS [easy, with Per Cederquist's  nice Texinfo tutorial existing
now] and a language independent LitProg tool [well, you may guess how
hard *that* is -- will see what happens if they notice that all their
user documentation has become "literate" over night.. :-) ]. 
  I would be very interested in obtaining even a prerelease.
 
-----------------
[Some Literati not in CS may wonder (as I would have 1 year ago): 
 CVS ("concurrent versions system") is a front end to RCS ("revision
 control system") which extends the notion of revision control from a
 collection of files in a single directory to a hierarchical
 collection of directories consisting of revision controlled files. 
 These directories and files can be combined together to form a
 software release. Both obtainable from prep.ai.mit.edu in pub/gnu.
 Per's tutorial (release 0.7) is in ftp.desy.de:/pub/gnu/cvs/cvs-tutorial.ps.
     Not everyone -even in CS- may know that there is a version to work
 with CVS in a group of developers at *remote* sites, developed at
 SLAC and mainly in use in the High Energy Physics community.
 rCVS patches: ftp.slac.stanford.edu:/pub/sources/rcvs-0.6.4.tar.Z]
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u.desy.de Tue Oct 19 14:21:03 GMT 1993
Date: Tue, 19 Oct 1993 14:21:03 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: compu transcript
 
>>>>> On 18 Oct 1993 12:41:10 -0500, rml@genesis.MCS.COM (Ryan Lee) said:
 
Ryan>         Could someone tell me what sorts of programming contests/
Ryan> activities/etc. I could put on my transcript for college? Although 
Ryan> I don't plan to major in computer sciences, I am a computer enthusiast 
Ryan> who programs intermediately with C and will likely remain involved with
Ryan> computers. But unfortunately my high-school offers very few computer 
Ryan> science courses and I haven't been able to fit any in. As a hobby my
Ryan> knowlege of computers/programming is pretty decent but my transcript
Ryan> does not show it.
Ryan>         So, I have really two questions. The first is: will colleges look
Ryan> at extracurricular computer science activities? And the second is:
Ryan> what kind of activity could I do?
 
If you can wait for the Spring 94 semester, GNA (Global Network Academy)
will offer programming courses on the Internet on college level. 
A course program will be out by January 94. The first semester
will include topics like C, parallel and literate programming,
astrophysics, computer & writing ...etc.
 
For further information please refer to one or all of
 
Usenet group   -> alt.uu.future
World Wide Web -> http://sturgeon.mit.edu:8001/
MediaMOO       -> telnet microworld.mit.edu 8888
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u.desy.de Tue Oct 19 14:32:25 GMT 1993
Date: Tue, 19 Oct 1993 14:32:25 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: Lack of ftp-able LitTool Examples
 
[The following is copied from my World Wide Web Info pages on LitProg,
 sections "Tools" and "Examples". The appendix tells you what is
 where. To retrieve e.g. the PS version of the latest FWEB User's Manual,
 do FTP to ftp.desy.de [131.169.10.38] to directory pub/web/DOCUMENTS/
 and get the file. _all_ files listed with "http" addresses are also
 retrievable via FTP on our server (this is not usually so on WWW).
 I include this as a reply to David Kastrup's request for LitProg
 samples and tool descriptions. -- Marcus Speh]
 
Subject: Re: send http://info.desy.de/pub/www/projects/LitProg/Tools.html
Date: Tue, 19 Oct 93 14:57:26 MET
 
The requested document follows. Linked documents may be obtained
using SEND <address> where the addresses are listed at the end.
________________________________________________________________________
                                      List of Literate Programming Tools
                   LIST OF LITERATE PROGRAMMING TOOLS
 
   Have a look at the LitProg Library[1] for a more complete overview
   and sources.
 
  CLiP (PostScript[2], plain[3])
                          A universal (language-independent) literate
                         programming tool, currently ported to VAX/VMS
                         and MS-DOS only. See also: CLiP Style[4] and
                         Manual[5] (PostScript)
 
   CWEB[6]                WEB System of Structured Documentation for C
                         and C++. References [v3.0, all PostScript]:
                         User's Manual[7], common[8], cweave[9],
                         ctangle[10]
 
   FunnelWEB[11]          Features and comparison with FWEB, by P. Lyon
                         (original message to LitProg[12] mailing list).
 
   FWEB[13]               WEB System of Structured Software Design and
                         Documentation for Fortran-77, Fortran-90,
                         Ratfor, C, C++ and TeX. References [v1.30, all
                         PostScript]: fwebmac[14] [40p.], User's Manual
                         [body[15], index[16], 200 p.], guide[17]
                         [20p.]. Here is John Krommes' hypertextified
                         FWEB Info[18]
 
   Glasgow LitProg Tools
                          A GNU Texinfo-based suite of literate
                         programming tools from Glasgow, at
                         ftp.dcs.glasgow.ac.uk:/pub/haskell/glasgow/.
                         Here is the documentation[19] [PostScript[20]].
 
   NOWEB (plain[21], PostScript[22])
                          "Literate-Programming Tools Need Not Be
                         Complex", by N. Ramsey.
 
   NUWEB[23] (PostScript)
                          Yet another simple Literate Programming tool
                         for arbitrary programming languages, with LaTeX
                         as formatter. Command Summary[24] (ps)
 
   WinWordWEB[25]         A WORDWEB (HyperText literate programming[26])
 
                                         Last updated September 22, 1993
 

 
     References from this document:-
 
[1]  gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.LITPROG%5d
[2]  http://info.desy.de:80/pub/faq/web/clip/clip_ann.ps
[3]  http://info.desy.de:80/gnu/ftp/pub/faq/web/clip/clip_ann.plain
[4]  http://info.desy.de:80/pub/faq/web/clip/clip_ann.ps
[5]  file://sun01.info.wau.nl/clip/ms_dos/clip_man.ps
[6]  http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/CWEB/FULL
[7]  http://info.desy.de:80/pub/web/DOCUMENTS/cweb/cwebman.ps
[8]  http://info.desy.de:80/pub/web/DOCUMENTS/cweb/common.ps
[9]  http://info.desy.de:80/pub/web/DOCUMENTS/cweave.ps
[10]  http://info.desy.de:80/pub/web/DOCUMENTS/cweb/ctangle.ps
[11]  http://info.desy.de:80/pub/faq/web/funnelWEB/funnelWEB.html 
[12]  http://info.desy.de/pub/www/projects/LitProg/Mailing.html
[13]  http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/FWEB/FULL
[14]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/macros.ps
[15]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/manual.ps
[16]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/index.ps
[17]  http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/guide.ps
[18]  http://info.desy.de/pub/www/projects/LitProg/info/top.html
[19]  http://info.desy.de/pub/www/projects/LitProg/glasgow/top.html
[20]  http://info.desy.de:80/gnu/doc/litprog/lit2x-0.16-literate.ps
[21]  http://info.desy.de:80/gnu/ftp/pub/faq/web/noweb/noweb.html
[22]  http://info.desy.de:80/pub/faq/web/noweb/noweb.ps
[23]  http://info.desy.de:80/pub/web/nuweb/nuweb.ps
[24]  file://ftp.shsu.edu/tex-archive/web/nuweb/nuweb-summary.ps
[25]  gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.FILESERV.WORDWEB%5d
[26]  http://info.desy.de/pub/www/projects/LitProg/HTML.html
 
Subject: Re: send http://info.desy.de/pub/www/projects/LitProg/Samples.html
Date: Tue, 19 Oct 93 15:01:48 MET
 
The requested document follows. Linked documents may be obtained
using SEND <address> where the addresses are listed at the end.
________________________________________________________________________
                                          Archives and Examples Overview
                     ARCHIVES AND SELECTED EXAMPLES
 
Literate Programming Archives
 
   Various stuff, including WEB systems for Maple, Reduce, Ada and APL,
   CNOWEB, DOSNOWEB, FunnelWEB, MWEB, PC-WEB, SpiderWEB,... can be found
   at the following archives in the US and in Europe:
 
  George D. Greenwade's archive at Niord.shsu.edu[1] (gopher server)
  the repository at ftp.uni-stuttgart.de in directory
 pub/soft/tex/web[2]
  the UK TeX Archive at ftp.tex.ac.uk[3]
  Joachim Schrod's archive at ftp.th-darmstadt.de[4].
 
Selected Samples
 
   Sample programs for FWEB are contained in the FWEB distribution at
   lyman.pppl.gov[5]. Here, you can look at woven sample output
   (PostScript[6], ASCII[7]).
 
   A couple of sample files for CWEB can be retrieved from the
   freeHEP[8] server (in directory pub/freehep/languages/cweb[9]) as
   well. Here, you can look at woven sample output (PostScript[10],
   ASCII[11]).
 
   More sample programs for CWEB are contained in the CWEB distribution
   at labrea.stanford.edu in directory pub/cweb/examples[12].
 
   The simple desk calculator program from the Kernighan & Ritchie
   standard text on C was transformed into a instructive LitProg example
   for multiple source files by Cameron Smith. It can be retrieved via
   anonymous FTP from ftp.desy.de[13] in directory
   pub/web/cweb/kr-cweb-sample. Here, you can look at its woven output
   (PostScript[14], ASCII[15]).
 
                                              Last updated June 20, 1993
 

 
     References from this document:-
 
[1]  gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.LITPROG%5d
[2]  file://ftp.uni-stuttgart.de/pub/soft/tex/web
[3]  gopher://ftp.tex.ac.uk:70/11/archive/Archive%20directory/web
[4]  file://ftp.th-darmstadt.de/pub/programming/literate-programming
[5]  file://lyman.pppl.gov/pub/fweb/v1.30/demos
[6]  http://info.desy.de:80/pub/web/fweb/IntArray.ps
[7]  http://info.desy.de:80/pub/web/fweb/IntArray.html
[8]  http://heplibw3.slac.stanford.edu:80/FIND/FHMAIN.HTML
[9]  file://freehep.scri.fsu.edu/freehep/languages/cweb
 
[10]  http://info.desy.de:80/pub/web/cweb/String-sample/String2.ps
[11]  http://info.desy.de:80/pub/web/cweb/String-sample/String2.html
[12]  file://labrea.stanford.edu/pub/cweb/examples
[13]  http://info.desy.de:80/pub/web/cweb/kr-cweb-sample
[14]  http://info.desy.de:80/pub/web/cweb/kr-cweb-sample/calc.ps
[15]  http://info.desy.de:80/gnu/ftp/pub/web/cweb/kr-cweb-sample/calc.html
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u.desy.de Tue Oct 19 14:44:20 GMT 1993
Date: Tue, 19 Oct 1993 14:44:20 GMT
From: marcus@x4u.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE
To: LitProg@SHSU.EDU
Subject: LitProg on the World Wide Web [regular posting]
 
-----------------------------------------------------------------------------
* Literate Programming on the World Wide Web
-----------------------------------------------------------------------------
   FYI, there is a wealth of information on Literate Programming,
   the art of structured programming and documentation [especially
   using WEB-like systems with TeX formatting] available on the
   World Wide Web [WWW], a distributed HyperText system, a network
   of documents connected by links which can be activated electronically.
   Examples for LitProg environments are WEB for Pascal (DEK), CWEB for C/C++
   (Levy/Knuth), FWEB for C/C++/Fortran/ratfor/TeX (Krommes)...and many more.
-----------------------------------------------------------------------------
* How to get to the Web
-----------------------------------------------------------------------------
   If you have a WWW browser up and running, try going to
 
		        http://info.desy.de/
 
   (this brings you to the DESY home page), and look for "User Documents"
   in the panel which appears. The precise URL is
 
	   http://info.desy.de/pub/www/projects/LitProg.html
 
   If you have no clue what WWW is, you can go over the Internet with
 
        	telnet info.cern.ch
 
   which brings you to the WWW Home Page at CERN. You are now using the
   simple line mode browser. To move around the Web, enter the numbers
   given after an item. To go to the Literate Programming documents, enter
 
	go http://info.desy.de/pub/www/projects/LitProg.html
 
   This is what you should see now:
-----------------------------------------------------------------------------
* What you will see here
-----------------------------------------------------------------------------
 
  Getting Started[2]   A first look into Literate Programming with WEB
 
   Editing[3]          GNU Emacs mode for WEB programming
 
   Tools[4]            Common, freely available Literate Programming
                       environments
 
   Examples[5]         Literate Programming archives and selected examples
 
   LitProg Library[6]  George D. Greenwade's Literate Programming Library at
                       Niord.shsu.edu. Experimental service: Archive Search[7]
 
   LITPROG Discussion List[8]
                       Information on the Literate Programming Mailing List.
                       Now, there is also a newsgroup,
                       comp.programming.literate[9]
 
   FAQs[10]            Lists of Frequently Asked Questions for WEB systems
 
   Further Reading     Nelson Beebe's Literate Programming bibliography at
                       ftp.math.utah.edu in directory /pub/tex/bib[11]
                       (files litprog.*)
 
   HyperLitProg[12]    Literate Programming using HyperText[13] Techniques
 
   OO-LitProg[14]      Thoughts on Object-Oriented[15] Literate Programming
 
 [[Now you can continue climbing down the documentation tree by
   entering numbers 1-14 and follow your own interests]]
-----------------------------------------------------------------------------
* More on Browsing the Web
-----------------------------------------------------------------------------
   The by far nicest way of "browsing" through WWW uses the X-Terminal
   based tool "NCSA Mosaic". Binaries for many platforms (ready for use)
   and sources are available via anonymous FTP from
   ftp.ncsa.uiuc.edu in directory Web/xmosaic.
     The general FTP repository for browser software is info.cern.ch
  (including a hypertext browser/editor for NeXTStep 3.0)
     If you cannot go through TELNET, you can still retrieve WWW
   documents by e-mail: send a mail to listserv@info.cern.ch with a
   line in it saying just
				HELP
   to get back detailed instructions. Your mail system must have a
   mail gateway to the internet mail.
-----------------------------------------------------------------------------
* Contact for Further Information
-----------------------------------------------------------------------------
   Please feel free to contact me for questions, suggestions and further
   contributions, or just to tell me whether you found this information
   useful in any way. 
     For questions related to WWW, consult the WWW-FAQ: available via
   anonymous FTP from rtfm.mit.edu in directory 
   pub/usenet/news.answers/www/faq, or on WWW at URL
   http://www.vuw.ac.nz:80/who/Nathan.Torkington/ideas/www-faq.html
   Enjoy.                                                          Oct 19-93 
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
E-mail: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From preston@cs.rice.edu Tue Oct 19 10:10:47 CDT 1993
Date: Tue, 19 Oct 93 10:10:47 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: scraps, modules, sections
 
I agree with Joachim Schrod about "module" already being heavily
overloaded in computer science.  Unfortunately, I also feel that
"section" has an adequate meaning, at least in the context of Latex.
Therefore, I've tried to use "scrap" where possible.
Of course, people will be able to find errors in my usage, but "scrap" is    
goal, even if I fall down occasionally in practice.
 
Yes, "scrap" has a perhaps unfortunate implication of leftover or remnant
that might put off some people.  However, it has the big advantage of
not having any more precise CS meaning.
 
Preston Briggs
 
From ucacgcj@ucl.ac.uk Tue Oct 19 15:42:05 GMT 1993
Date: Tue, 19 Oct 1993 15:42:05 GMT
From: ucacgcj@ucl.ac.uk (Gordon C Joly)
Reply-To: LitProg@SHSU.edu, ucacgcj@UCL.AC.UK
To: LitProg@SHSU.EDU
Subject: SOLVE tags and Meta Tags (was Re: Some thoughts)
 
In article <CMM-RU.1.3.750701006.leew@pilot.njin.net> Lee Wittenberg <leew@pilot.njin.net> writes:
>Shaker writes:
>
>> I program in Perl. Our source files are under RCS. Each time, a source
>> file is checked back in, people put a line or two of comments. These
>> comments are almost always of short term value, if any. In other
>> words, if different programmers work on a source file within the same
>> week (or month) say, these comments help to identify who changed what,
>> when. As long term documentation, these are useless. 
>>[...]
>I don't know of any general feature that will help you, but Tipton
>Cole+Co. (where I worked last year) dealt with the same problem in the
>following way (code is written using noweb & LaTeX):
>
>	[...]
>
>	As the the $LOG$ stuff (which your question was about), we never
>	came up with a really good solution.  "\RCSdef{$LOG$}" (I forget the
>	exact syntax) didn't really work well (at least we couldn't tame
>	it), so we just leave the $LOG$ at the end of the .nw file where
>	programmers can get to it if they want, but it doesn't get into
>	the woven output.
>
>Hope this helps.
>
>		-- Lee
>		   leew@pilot.njin.net
 
I wanted to do this type of thing with a code browser. My solution is
to invent a language "on the fly" and then use a standard browser like
UNIX ctags or extensions. Here is a short abstract (RN/92/78 at
UCL.CS). Comments by email welcome.
 
                -------------------------------
 
       Dynamically defined tags for annotation at the
                     description level.
 
                         G. C. Joly
 
              Department of Computer Science,
                 University College London,
                       Gower Street,
                   LONDON WC1E 6BT, U.K.
                 Email: G.Joly@cs.ucl.ac.uk
 
                          ABSTRACT
 
          This paper shows how the user can  manipulate
     the  process of searching for known (method) func-
     tions and at the same time provide their own  tag-
     ging mechanism through a single interface.
 
1.  Introduction.
 
     One  of the fundamental concepts that is debated in the
field of Object Oriented programming (and now OO design)  is
that  of reuse.  The Cognitive Browser (CogBrow) project [1]
has been developing a set of browsing tools  that  extend  a
class  browser,  such as the Smalltalk Class Browser, to aid
the programmer in their search for objects to reuse.  Exper-
imental  work  has shown that the user changes their view of
the code very rapidly, that is to say from one  day  to  the
next.  The  use  of tags, applied to spreadsheet designs, is
reported in [2], and this paper reports a direct application
to  OO systems.  Programmers and designers will often sketch
a flow chart then turn to writing pseudo-code,  and  CogBrow
will  support  this flexibility as much as possible.  If the
Cognitive Browser is left standing idle and the  user  turns
to pencil and paper then the Browser is of little value.
 
     A  prototype system has been built using the EMACS edi-
tor and a short PERL script; we  call  this  system  "stags"
(for  "super-tags"  or "SOLVE tags": for further information
on the SOLVE language, see for example [1]).
 
2.  Arbitrary placing of tags and browsing using EMACS.
 
     Stallman [3] developed the EMACS "editor" for  extensi-
bility. The EMACS Lisp language in which EMACS is now mostly
written can be used to modify the behaviour of the  "editor"
in  different  "modes".  New  "modes"  are created, which be
 
                            - 2 -
 
viewed in text windows, either by the  user  or  as  library
packages.  Currently EMACS can act (among other things) as a
folding editor, an interface to a mail system and  a  source
level debugger. Each mode is dynamically self documenting.
 
     Source  code,  in  multiple  files  which may be spread
across many directories, can be browsed using the EMACS tags
facility  "etags".   In  a sense, "etags" allows the dynamic
generation of an index over all the code.   Since  tags  are
language dependent, (the context of) the mode (corresponding
to a distinct "language"), is used to create  and  scan  the
tags  tables. For example, in C any function, in FORTRAN any
function or subroutine and in  (EMACS)  Lisp,  any  function
defined  with  defun and any variable defined with defvar or
defconst (see Schoonover et al [4]).
 
     Further extensions to "etags" (EMACS  tags)  have  been
added  to  the TeX and LaTeX document preparation languages,
where commands `chapter', `section', `subsection',  `subsub-
section',  `eqno',  `label',  `ref',  `cite',  `bibitem' and
`typeout' are all tags. In this case,  instances  of  (equa-
tion)  labels  and chapter (headings) will both be found (if
the text strings correspond); in fact the user may have this
notion in mind.
 
     The  extension  of  "etags" (for the C language) to C++
was carried out by Yacko [5].  Here, the system could search
for  classes  and  includes the notion of a class hierarchy,
which is displayed in a textual form, using  indentation  to
denote  subclassing.  Note  that  a similar program in EMACS
Lisp  is  currently  maintained  by   Sam   Kendall   (email
kendall@centerline.com), which allows the user to search for
classes using command line completion.
 
3.  An extension of EMACS style tags for browsing
 
     Payne and Green [6] describe a TAG  (task-action  gram-
mar) as "a formal device... a description of a task as a set
of semantic components".  In contrast, the system of "stags"
proposed  in  this  paper  takes the view that user is fully
aware of the semantics and it is the system  which  provides
the  mechanical browsing (on text files).  Therefore "stags"
are completely free, without any notion of formal grammar or
structure.
 
     A   small   script  by  David  Megginson  (email  dmeg-
gins@acadvm1.uottawa.ca) called PETAGS and  written  in  the
Perl  language, as described in [7] allowed the extension of
tags to an arbitrary computer language, which Pascal,  COBOL
or BASIC. From this starting point, it is possible to extend
the idea further.  We consider three  modifications:  super-
sets  of languages, sub-sets of languages, and the "descrip-
tion level", that is  "arbitrary  attributes  and  relation-
ships... in a browsable form", see [1]
 
                            - 3 -
 
     In  the  first case, a user could take the standard set
of tag words by the tags program (described above)  and  add
further  tag words. One example of this sort of procedure is
where some PostScript (tm) interpreters  will  process  code
inside a comment.
 
     The  second category allows faster browsing of a subset
of the language. Consider the standard etags definitions  of
EMACS  Lisp.  It would be possible to interactively restrict
tagging to ``defun'' and not to ``defvar'' and ``defconst''.
 
     The  final  case could be any hybrid, "stags", in which
the user chooses dynamically over the (fixed) source  files.
It would be possible to tag comments dynamically to existing
code so that the user could browse comments  only,  if  they
wished.  Note  that the users themselves may or may not have
added the comments to the code.  If they for  example  added
their  own initials when making changes, then these could be
tagged.
 
     In this case, since the "stags"  are  processed  simply
(by  a  search  operation), the user would have to produce a
meaningful set of tag words. If the user chose to  find  all
entries  with  their  own  initials in a comment field, they
should be able to search for any words after the tag word up
to the "end of comment". For example, if comments begin with
``//'', then the following lines
   // xxyz changed size of windows
   // and filled in background
would allow a search for all occurrences of  ``changed''  or
``window'',  for  user  (that  is to say tag word) ``xxyz''.
Note that the support for tags searches in EMACS allows this
operation  to  be carried out over more than one (UNIX (tm))
directory.
 
4.  Conclusions
 
     The proposal is to perform some experiments  with  this
system  of "stags" with a small set of users, to see if this
arbitrary scanning of code is fruitful for code  reuse.  The
base language of choice for would be a fully Object Oriented
language, such as SOLVE, but C++ or another  language  could
be  considered,  or  even  software  written in several lan-
guages. The current browsing method  is  through  the  EMACS
editor,  but an extension to form part of the graphical user
interface of the Cognitive Browser is planned. The  proposed
system  is far from complete in any sense, but may provide a
new dimension for browsing source code.
 
References
 
1.   Green, T. R. G., Gilmore, D. J., Blumenthal, B, Davies,
     S.,  and  Winder,  R., "Towards a cognitive browser for
 
                            - 4 -
 
     OOPS," International Journal on Human-Computer Interac-
     tion, vol. 4, no. 1, pp. 1-34, 1991.
 
2.   Hendry,  D.,  Green, T. R. G., Gilmore, D., and Davies,
     S.,  "Improving  the  communicability   of   speadsheet
     designs: Annotating with descriptive tags," in Psychol-
     ogy in  Programming  Interest  Group  -  5th  Workshop,
     Paris, (unpublished), 1992.
 
3.   Stallman,  R. M., "EMACS: The Extensible, Customizable,
     Self-Documenting Display Editor," in  Interactive  Pro-
     gramming  Environments, ed. David R. Barstow, Howard E.
     Shrobe and Erik Sandwell., McGraw-Hill, New York, 1986.
 
4.   Schoonover,  Micheal  A.,  Bowie,  John S., and Arnold,
     William R., GNU Emacs: Unix Text Editing  and  Program-
     ming, Addison Wesley, Reading, Mass, 1992.
 
5.   Yacko,  Nancy  Jane,  "A GNU Emacs Browser for C++ Code
     Development," M.Sc. Thesis, University of  Illinois  at
     Urbana-Champaign, Urbana, Illinois, 1987.
 
6.   Payne,  Stephen  J.  and  Green, T. R. G., "Task-Action
     Grammar: the model and its developments," in Task anal-
     ysis for human-computer interaction, ed. D. Diaper, pp.
     75-107, Ellis Horwood Publishers, Chichester, 1989.
 
7.   Wall, Larry and Schwartz, Randall L., Programming perl,
     O'Rielly & Associates Inc., Sebastopol, CA, 1990.
 
                -------------------------------
 
--
Gordon Joly      Phone  +44 71 380 7777 ext 3703      FAX  +44 71 387 1397
Internet: G.Joly@cs.ucl.ac.uk                            ucacgcj@ucl.ac.uk
Computer Science, University College London, Gower Street, LONDON WC1E 6BT
 
From coates@spectro.jussieu.fr Tue Oct 19 17:37:12 +0100 1993
Date: Tue, 19 Oct 93 17:37:12 +0100
From: coates@spectro.jussieu.fr
Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR
To: LitProg@shsu.edu
Subject: (My) long postings
 
Dear Readers,
	I wrote that maybe my postings were too long.  I had two or three
personal replies saying they were, and complaining about my long .sig (it is
true that my laboratory has a long address, plus I have a bilingual disclaimer).
I'll leave out the .sig this time.
	There was a comment that my postings might be more interesting to read
if I included less of what the previous poster said.  I'm not sure whether I am
interested in creating postings that are quicker and more interesting to read, 
but unreasonably biased by my own interpretation of what was said before.  I'll
have to decide that.
	Otherwise, let me quickly note that I will sign off from LitProg at
the end of this week, when I return to Australia, but will be back again at
the end of November, from Brisbane, Australia.
							Cheers,
									Tony.
 
From Lee Tue Oct 19 15:42:35 EDT 1993
Date: Tue, 19 Oct 93 15:42:35 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, lynbech@daimi.aau.dk
Subject: Re: Revision Control
 
A number of people have remarked on the rcs.sty file I mentioned in
one of my messages.  Until now, I didn't know there was more than one.
The one I was referring to is by Tom Verhoeff, and boils down to the
following 2 definitions:
 
\def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.}
\def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}}
 
I apologize for any confusion.  Mea culpa.
 
		-- Lee
		   leew@pilot.njin.net
 
From Lee Tue Oct 19 16:06:20 EDT 1993
Date: Tue, 19 Oct 93 16:06:20 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: Literate Programming Examples
 
As David Kastrup has resuscitated the issue of LP examples, I no
longer have to apologize for my delay in making such examples
available.
 
I have put a couple of literate programs of mine in the
~/pub/leew/samples.LP directory of bart.kean.edu, where anonymous
ftp'ers can grab them if they so desire.  I would prefer not to use bart
for this, but until there is a central repository for LP examples, it
will have to do.
 
Both programs are written in CWEB, and are provided in .w, .dvi, and .ps
format (CWEB, TeX output, and PostScript, for the uninitiated).  When
I can, I will add a few noweb programs (for various reasons I can't
do it now).  I also plan to put all non-proprietary programs I write
from now on (excepting trivial stuff) in this directory (or a central
repository, if one is available.  I hope other LP'ers will do
likewise.
 
The 2 programs are called ``Puzzle'' and ``EventLib.''  The former is
a simple little program I wrote to try to solve a brainteaser
presented by a student.  The student was neither a CS major nor
interested in programming, so I wrote the program with the idea of his
being able to read it.  It should be a nice example for beginners.
 
EventLib is a prototype library of routines for event-driven programming
that avoids the agony of event loops (``EventLib'' stands for both ``event
library'' and ``event liberation'').  It began life as a non-literate
program, was translated to Spidery C (my first major LP project), and
from thence to CWEB 3.0 (as CWEB now supports Standard C).  Because of
its many lives, it's a bit of a mixed bag, and does not use any LP
techniques I have since discovered.  It also has a semi-major (known)
bug.  However, it's an interesting idea, and a reasonably good
literate program, and I can't think of any reason not to let people
see it.  It is also a ``work in progress,'' so any comments or
criticisms you might care to make will be cheerfully incorporated into
future versions (assuming I find the time -- or funding -- to get back
to the project).  More information is contained in the README file.
 
I'm looking forward to your critical comments (he said, putting on a
brave face :-).
 
		-- Lee
		   leew@pilot.njin.net
 
From Lee Tue Oct 19 16:12:24 EDT 1993
Date: Tue, 19 Oct 93 16:12:24 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: CWEB comments
 
I'm a bit confused.  A number of people have made the claim that
CWEB does not typeset comments.  As far as I know, CWEB typesets
comments exactly as it does the text sections:  in roman type, with
TeX codes completely usable.  The cwebmac.tex macros also include
options to typeset comments in sans serif and to use special symbols
as comment markers.
 
Am I missing something here?
 
		-- Lee
		   leew@pilot.njin.net
 
From Lee Tue Oct 19 16:23:20 EDT 1993
Date: Tue, 19 Oct 93 16:23:20 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, schrod@iti.informatik.th-darmstadt.de
Subject: Re: Inline comments and abstraction
 
Joachim Schrod mentioned the terribleness (is that a word?) of the
term ``module'' as used in the original WEB literature.  I agree with
him as to the superiority of ``section'' in this regard.  So does DEK,
apparently, as this terminology has been adopted in the most recent
versions of CWEB.
 
However, my hands down favorite in the terminology game is Norman
Ramsey's use of ``chunks'' in noweb.  The word chunk carries no
``excess baggage,'' as to both module and section (the former in
programming, the latter in word processing).  It's unambiguous to
speak of ``code chunks'' and ``text chunks'' and the terms are readily
understandable.  Chunk also has the advantage that it's only one
syllable, and therefore, easier to say.
 
I don't mean to force anyone to adopt a new terminology, or to start
any new religious wars.  I just wanted to make the ``chunk''
terminology a bit more widely known.
 
		-- Lee
   		leew@pilot.njin.net
 
From preston@cs.rice.edu Tue Oct 19 16:06:13 CDT 1993
Date: Tue, 19 Oct 93 16:06:13 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: Literate Programming Examples
 
Our group at Rice is writing an experimental optimizer,            
mostly in C, using nuweb.  I've put several examples
arising from our efforts out for anonymous ftp, from cs.rice.edu,
in the directory public/preston
 
They're all in postscript form.  They're also fairly heavy reading
if you're not familiar with the literature.  We haven't settled into
a particular style of literate programming, so they tend to vary
in form, depending on the author's (evolving) preferences.
 
3 of the programs are optimizations.
 
1 is an experimental implementation of a particular algorithm
        to be incorporated into another optimization.
 
1 is a testing facility (generates make files, among other things)
 
1 is in progress, and will describe the entire project.
        Currently, it describes the intermediate language and
        the interface to a large body of shared utilities.
 
Each program was written by a different person, so there's some variety
in the approaches to the problems.  However, they were all viciously
criticised in walkthroughs, so you'll also see some common ideas.
 
Nota bene -- Printing all these files will require about 300 pages of paper.
I'd preview them first, and print only what looks interesting or
representative.
 
Preston Briggs
 
From schrod@iti.informatik.th-darmstadt.de Tue Oct 19 16:06:13 CDT 1993
Date: Tue, 19 Oct 93 16:06:13 CDT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: WEB mode (was Re: Sections  modules  chapters)
 
In article <2a0rqv$qt5@TAMUTS.TAMU.EDU>, bart@cs.tamu.edu (Bart Childs) writes:
> 
> Thus we have keybindings like C-c gc  `go to chapter' ,,,
 
Btw, that was a gripe I have always with the WEB mode (besides that it
doesn't support AUC-TeX and c++-mode): It binds `C-c LETTER'. From the
elisp manual:
 
   * Please do not define `C-c LETTER' as a key in your major modes.
     These sequences are reserved for users; they are the *only*
     sequences reserved for users, so we cannot do without them.
 
     Instead, define sequences consisting of `C-c' followed by a
     non-letter.  These sequences are reserved for major modes.
 
     Changing all the major modes in Emacs 18 so they would follow this
     convention was a lot of work.  Abandoning this convention would
     waste that work and inconvenience the users.
 
This $@#!!@# mode redefines all my user-specific definitions...
(Of course, it isn't the only one. bibtex-mode and html-mode do the
same. :-( )
 
And if you might add a web-mode-load-hook, that would be great, too.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From schrod@iti.informatik.th-darmstadt.de Tue Oct 19 16:06:13 CDT 1993
Date: Tue, 19 Oct 93 16:06:13 CDT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Revision Control
 
In article <MARCUS.93Oct19145154@x4u.desy.de>, marcus@x4u.desy.de (Marcus Speh) writes:
> >>>>> On 18 Oct 1993 09:10:38 GMT, lynbech@daimi.aau.dk (Christian Lynbech) said:
> 
> |> It wasn't exactly clear to me what RCS style Lee Wittenberg was referring to
> 
> He was referring to the standard rcs.sty from the CTAN archives
> by Nelson Beebe
 
Thank you for this hint to yet another rcs style.
 
Perhaps I should add that this style is by no means standard. In
fact, it's the third rcs.sty, I'm aware of: One by Piet v.Oostrum,
this one, and one by myself (you see, I'm biased. :-). Piet's is the
one which is the best known, it's the one which may be found in the
latex/contrib/misc directory of the CTAN.
    (My style option will be available from latex/contrib/rcs after
one of the CTAN managers has answered my question posed a month ago.
Hint, hint... ;-) Currently, you can fetch it from
ftp.th-darmstadt.de:pub/tex/latex/.
 
I had a look at Nelson's style just a few minutes ago. Luckily it
doesn't conflict with one of the others. I will add support for the
tags defined there to my rcs style. Dave Love already pointed out
another shortcoming (usage with co -kv) which will be addressed, too.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From shf@netcom.com Tue Oct 19 21:40:49 GMT 1993
Date: Tue, 19 Oct 1993 21:40:49 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: Levels of Abstraction
 
+-- schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) writes:
| In article <>, shf@netcom.com (Stuart Ferguson) writes:
| > It seemed like a step backwards to me to have a nicely typeset document
| > describing a program and then have the code scraps contain untypeset
| > comments in the code as if it were going to be read by a machine. [...]
| Sorry, but I don't understand you. The inline comments of CWEB are of
| course in TeX mode, and therefore you can make use of TeX markup
| there as well. If it's good style (and good looking ;-) to put a
 
I could easily be mistaken on this point, as I only looked at the
Knuth articles for a short time.  I was convinced that the inline
comments were printed in teletype font between "/*" and "*/" with a
very distracting word wrap.  I'll go back and see if I can find that
article again.
 
In any case, the point is somewhat irrelevant, since CWEB apparently
*does* support typeset inline comments.  I'm pleased to hear this, 
since I think this is an important feature for literate C programing.
-- 
		Stuart Ferguson		(shf@netcom.com)
			"Oh Dear Lord -- the canary exploded!"
 
From bdubbs@cs.tamu.edu Tue Oct 19 21:40:49 GMT 1993
Date: Tue, 19 Oct 1993 21:40:49 GMT
From: bdubbs@cs.tamu.edu (Bruce Dubbs)
Reply-To: LitProg@SHSU.edu, bdubbs@CS.TAMU.EDU
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <2a0lj8INNl5d@rs18.hrz.th-darmstadt.de>,
Joachim Schrod <schrod@iti.informatik.th-darmstadt.de> wrote:
|In article <29v3ne$8l0@TAMUTS.TAMU.EDU>, bart@cs.tamu.edu (Bart Childs) writes:
|> 
|> I also note that he called these small parts sections or modules.
|> (He used the words interchangeably.)  I think that is a far better
|> term than scraps because they were intentional, not leftovers as
|> in most of the definitions of scrap.
|
|I prefer the simple term `program part'.
|
|For me, section is ok most of the time, but sometimes one must stress
|the difference between this `numbered entities' and their subparts.
|
|I _hate_ the term module. (In fact, Klaus and myself were one of the
|pushers to delete this word of CWEB.) A module is an entity with a
|distinct specification and implementation. One does not find this
|distinction in WEB. The concept of a module, first outlined by
|Parnas, later refined by Dennis, Ehrig & Mahr, and nowadays
|modernized by Booch, is a central one to all software engineering
|activities. It has _nothing_ to do with these WEB pieces. Please,
|don't throw away the CS terms we have worked so long for!
|
Personally, I like the term `block', although `chunk' is OK too.
Actually, a block of code can be considered in direct correlation to
the cognitive chunks in psychology.
   -- Bruce
 
|For what it's worth, here is a definition of terms I use usually:
|
|    Before we start with an overview of the implementation I want to
|    explain the \cweb{} vocabulary I use while I guide you through this
|    document. The commonly used terms sometimes denote two entities, but
|    for the purpose of this style we need exact terms. I've tried to stick
|    to a ``canonical'' computer science terminology.
|    
|    \begin{quotation}
|
|    I distinguish two different structures in a \cweb{} file: The {\sl
|    document structure\/} and the {\sl program structure}.
|    
|    A \cweb{} document consists of a series of {\sl sections}. Within
|    this series some sections are especially emphasized, we call them the
|    {\sl main sections}. (They are also called {\sl starred sections},
|    since their corresponding \cweb{} tag is~|@*|.) These main sections
|    have a title, ordinary sections are untitled. A table of contents may
|    therefore list only the main sections. Note that there is no
|    hierarchy in the sections, they are all on the same level, ie, they
|    are numbered subsequently.
|    
|    Each section consists of three parts: (1)~the {\sl documentation
|    part}, (2)~the {\sl definition part}, and (3)~the {\sl program part}.
|    Each of these parts can be empty. The documentation part is mostly text
|    with \LaTeX{} tags. In this text material from {\sl restricted program
|    mode\/} can appear. The definition part consists of a series of either
|    {\sl macro\/} or {\sl format definitions}. The program part is one
|    piece of a refinement, identified by a name (see below).
|    
|    A \cweb{} program consists of a tree of {\sl refinements}. A
|    refinement is a list of program parts with the same name, ordered in
|    appearence. The root of the tree is the refinement with the special
|    name~|@c|. The program text is defined by the DFS (ie, infix-order)
|    traversal of the tree.
|
|    \end{quotation}
|    
|    \noindent The terminology outlined above is an overspecification for
|    the \LaTeX{} style we're implementing here---nevertheless, the
|    context of my explanation should be clear now.%
|
|(That's a verbatim copy from the cweb style.)
|
|Any critic? comments?
|
|--
|Joachim
|
|=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
|Computer Science Department
|Technical University of Darmstadt, Germany
|
|    ``Real programmers can write Fortran in any language.'' [... Well,]
|    Real interface programmers can implement vi in any software envionment.
|						[Hartson, Brandenburg, Hix]
 
-- 
Bruce Dubbs                   |  Oxymorons of note:
                              |  Honest Politician, Political Science,
bdubbs@hal.kelly.af.mil       |  Scrupulous Lawyer
 
From norman@bellcore.com Tue Oct 19 18:49:07 -0400 1993
Date: Tue, 19 Oct 93 18:49:07 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Literate Programming Examples
 
I think it's high time we had a central repository of literate-programming
examples.  I think CTAN is the natural place for it, but if CTAN isn't 
interested, I'll ask my management if we can arrange something here.
(The problem is that our lawyers won't let us make an ftp area that is
both readable and writable, and it takes real staff hours to move things
from an incoming to a readable directory.)
 
Norman
 
From mbrown@athos.cs.ua.edu Tue Oct 19 18:12:15 -0500 1993
Date: Tue, 19 Oct 1993 18:12:15 -0500 (CDT)
From: mbrown@athos.cs.ua.edu (Marcus Brown)
Reply-To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Inline comments and abstraction
 
Lee Wittenberg wrote:
> 
> However, my hands down favorite in the terminology game is Norman
> Ramsey's use of ``chunks'' in noweb.  The word chunk carries no
> ``excess baggage,'' ...
> 
> 		-- Lee
>    		leew@pilot.njin.net
 
Hear! Hear!  ``chunks'' is an excellent choice.  As a matter of fact,
``chunks'' does carry a certain amount of background, but it is very
appropriate in this case.  The term ``chunk'' is often used in
discussing how many items a person can keep in short-term memory at
one time: the magic number 7 +/- 2 chunks, usually where each chunk is
a single idea/concept/unit/...  These chunks may be decomposed into
smaller chunks, and will be different for different people.  For
example, an entire chessboard with pieces across it might be a single
chunk to a chess master, while it might be several chunks for the rest
of us.  On the other hand, for an good programmer, a `push' or `pop'
or even `bubble sort' might be a single chunk.  Any of these chunks
could be broken down into smaller chunks or steps later.
 
The meaning carrys over nicely, because we can talk about a `chunk' of
code as being a single unit, even if it is later broken down into further
chunks.  I really like the term `chunks,' and hereby go on record as
recommending it for canonization as the _APPROVED_ term for the code
fragments (with associated documentation, macros, etc.) which make up
a WEB.
-- 
Marcus Brown
mbrown@cs.ua.edu
Computer Science Dept, Univ of Alabama
 
From conrado@lsi.upc.es Wed Oct 20 09:03:50 GMT 1993
Date: Wed, 20 Oct 1993 09:03:50 GMT
From: conrado@lsi.upc.es (Conrado Martinez-Parra)
Reply-To: LitProg@SHSU.edu, conrado@lsi.upc.es
To: LitProg@SHSU.EDU
Subject: prettyprinting
 
Hello,
 
In my opinion, prettyprinting can be a useful feature but it is not 
necessary to provide it as a built-in feature of a WEB system. 
What is really needed is that the WEB system produces intermediate files, 
with standard 'formats'. Different specialized tools can then
work on the appropriate file to generate xrefs, indexes, prettyprinted (pp) 
output, etc.
This is the kind of approach that Norman Ramsey used in his noweb system, and 
it is the right one, in my opinion.
If one likes pp, the only thing that is needed is a program that 
takes the weave'd file and includes pp macros in the code sections. If you don't 
like pp, don't use the pp program.
 
I will use a particular example to make clear what I mean. 
Suppose we are working with noweb and LaTeX. After weaving the web file (.nw), 
one obtains a LaTeX file (.tex) where the
code goes inside 'code' environments, for example,
 
\begin{code}{<xref info>}
...
int gcd(int x, int y)
{
  while (x != y)
       ...
}
\end{code}
 
This 'code' environment is very similar to the
standard 'verbatim' environment and therefore you'll not have pp output.
The pp tool takes this LaTeX file as input, leaves everything outside the 
'code' environments untouched and includes 
the pp macros within the code sections:
 
\begin{ppcode}{<xref info>}
...
|int|\ |gcd|(|int| x, |int| y) 
\{
\while (x \ne y) 
...
\end{ppcode} 
 
I have developed such a 'ppcode' environment and the pp program for Dijkstra's 
command language. The pipeline 'noweb | d2tex' 
works rather well (although, it is a Beta version and the pp output sometimes 
looks terrible :-) ).
Finally, it seems to me that a tool for generating such prettyprinters would be 
very useful and not very difficult to produce (the Spidery WEB system includes, 
in some sense, such a generator, doesn't it?).
 
Conrado.
---
 +-------------------------------+--------------------------------+
 | Conrado Martinez-Parra        | Dept. of Software (LSI)        |
 | e-mail : conrado@lsi.upc.es   | Univ. Politecnica de Catalunya |
 | phone:   (34-3) 401-73-36     | Pau Gargallo, 5                |
 | fax:     (34-3) 401-70-14     | E-08028 Barcelona, Spain       |
 +-------------------------------+--------------------------------+
 
From wstomv@wsinpa04.win.tue.nl Wed Oct 20 09:03:50 GMT 1993
Date: Wed, 20 Oct 1993 09:03:50 GMT
From: wstomv@wsinpa04.win.tue.nl (Tom Verhoeff)
Reply-To: LitProg@SHSU.edu, wstomv@WSINPA04.WIN.TUE.NL
To: LitProg@SHSU.EDU
Subject: Re: Revision Control
 
In article <CMM-RU.1.3.751059755.leew@pilot.njin.net>,
Lee Wittenberg  <leew@pilot.njin.net> wrote:
>A number of people have remarked on the rcs.sty file I mentioned in
>one of my messages.  Until now, I didn't know there was more than one.
>The one I was referring to is by Tom Verhoeff, and boils down to the
>following 2 definitions:
>
>\def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.}
>\def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}}
 
The definitions are very concise (and sort of unreadable).
Here are (i) the condensed style file and (ii) its fully documented version.
(By the way, it is mentioned in the TeX-index maintained (?) by David Jones
<dmjones@theory.lcs.mit.edu>.)
 
----- (i) condensed version of RCS.sty -----
 
% This style file, RCS.sty, is for use with RCS (a Revision Control System).
%
% Author: Tom Verhoeff, Dept. of Math. & C.S., Eindhoven Univ. of Technology
% E-mail: wstomv@win.tue.nl
%
\def\filedate {1 July 1992}
%
\typeout{Documentstyle option `RCS': RCS keyword defines <\filedate>.}
%
% DOCUMENTATION in RCS.doc
%
\def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.}
\def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}}
%
% END of RCS.sty
 
----- (ii) fully documented version of RCS.sty -----
 
% This style file, RCS.sty, is for use with RCS (a Revision Control System).
%
% Author: Tom Verhoeff, Dept. of Math. & C.S., Eindhoven Univ. of Technology
% E-mail: wstomv@win.tue.nl
%
\def\filedate {1 July 1992}
%
\typeout{Documentstyle option `RCS': RCS keyword defines <\filedate>.}
%
%
% PURPOSE
%
%   Make it possible to include RCS (Revision Control System) keyword strings
%   (also called identification markers) in a LaTeX document such that
%   the keyword values can be referred to in the document.
%
%
% USAGE
%
%   In the LaTeX document, include `RCS' among the document style options:
%	\documentstyle[...,RCS,...]{...}
%
%   Include an RCS keyword string in the document as:
%	\RCSdef $<Kw>$
%   or
%	\RCSdef $<Kw>: <val> $
%   where <val> is a nonempty value string.  Note the spaces around <val>.
%   The keyword string is echoed to the log file.
%
%   Refer to the value of keyword <Kw> as:
%	\RCS<Kw>
%
%   For a list of valid RCS keyword strings see the manual page of co(1).
%
%
% EXAMPLE
%
%   To have RCS maintain the revision number of a file inside that file
%   one acts as follows.  Include the keyword string
%
%	$Revision$
%
%   in the initial version of the file and submit the file to RCS by the
%   check-in command ci(1).  The check-out command co(1) subsequently
%   replaces this string by
%
%	$Revision: value $
%
%   where value is the current revision number of the file.
%
%   Here is a LaTeX document that defines two RCS keyword strings, viz.
%   for a revision number and a revision date, and that prints the
%   revision date and number on the title page:
%
%	\documentstyle[RCS]{article}
%	\RCSdef $Revision$
%	\RCSdef $Date$
%	\title{Usage Example of RCS Style Option}
%	\author{Tom Verhoeff}
%	\date{\RCSDate (Rev.\ \RCSRevision)}
%	\begin{document}
%	\maketitle
%	Test of RCS style option.
%	\end{document}
%
%
% MOTIVATION
%
%   Two trivial---but problematic---ways to include RCS keyword strings in
%   LaTeX source files are the following.
%
%   1. Put the keyword string in a TeX comment, i.e. following a percent
%      sign (`%').  For instance,
%
%	% $Date$
%	% $Revision$
%
%   2. Put the keyword string in a place where you want the value printed.
%      For instance, in the title page definition of a LaTeX document write
%
%	\date{$Date$ $Revision$}
%
%   The problem with the first approach is that the keyword value is no
%   longer available for TeX processing (such as printing).
%   In the second approach you have to live with the fact that TeX processes
%   the keyword string in math mode and includes both the keyword string
%   identifier and its current value.
% 
%   Our solution is the following.  Define a macro that takes the keyword
%   string as argument and that assigns the value to a control sequence
%   whose name is derived from the string's identifier.
%
%
% IMPLEMENTATION DETAILS
%
%   \RCSdef takes arguments of the form
%	$Keyword$
%   or
%	$Keyword: value $
%   The first form is a special case of the second with empty value string.
%   N.B. * There is a space after the colon (`:') AND another one before
%          the closing dollar-sign (`$').
%        * The dollar-signs act as argument delimiters; do NOT use braces.
%
%   \RCSdef strips the enclosing dollar-signs and invokes \RCS@def to
%   define the control sequence \RCSKeyword as value.
%
%   More precisely,
%	\RCSdef $Keyword$
%   expands to
%	\RCS@def Keyword: {} :.
%   And
%	\RCSdef $Keyword: value $
%   expands to
%	\RCS@def Keyword: value : {} :.
%
%   \RCS@def takes arguments of the form
%	Keyword: value :garbage.
%   and defines \RCSKeyword as value.
%
%   For example,
%	\RCSdef $Revision$
%   translates into
%	\def\RCSRevision{}
%   And
%	\RCSdef $Revision: 1.2 $
%   translates into
%	\def\RCSRevision{1.2}
%
%   This way one can embed RCS keyword strings in a LaTeX source file and
%   use their values as well.  For instance, when including
%	\RCSdef $Revision$
%   in the initial version of a LaTeX source, one can use \RCSRevision
%   in a header or footer to produce the current revision number.
%   The command co(1) updates the keyword string with a new value to reflect
%   changes.  Re-LaTeX-ing propagates the changes into you document.
%   N.B. The command co(1) includes the appropriate spaces around value.
%
%   WARNING: Do NOT write
%	\RCSdef $Revision:$
%   since occurrence of the colon (`:') requires two additional spaces (` ').
%   Because TeX lumps consecutive spaces in the input into a single space,
%   writing
%	\RCSdef $Revision:  $
%   does not work.  Control spaces (`\ ') do not work either because they
%   differ %   from ordinary spaces.  An empty value string could be written as
%	\RCSdef $Revision: {} $
%   However, there is no need for this form, since $Revision$ is preferred.
%
%
% TEX CODE
% 
\def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.}
\def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}}
%
% END of RCS.sty
-- 
INTERNET: wstomv@win.tue.nl  /    Eindhoven University of Technology
VOICE: +31 40 47 41 25      /    Dept of Mathematics & Computing Science
FAX: +31 40 43 66 85       /    PO Box 513, NL-5600 MB Eindhoven, Netherlands
 
From schrod@iti.informatik.th-darmstadt.de Wed Oct 20 09:03:50 GMT 1993
Date: Wed, 20 Oct 1993 09:03:50 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Revision Control
 
In article <CMM-RU.1.3.751059755.leew@pilot.njin.net>, Lee Wittenberg <leew@pilot.njin.net> writes:
> A number of people have remarked on the rcs.sty file I mentioned in
> one of my messages.  Until now, I didn't know there was more than one.
> The one I was referring to is by Tom Verhoeff
 
ARGHHH! The 4th one...
 
--
Joachim
 
From Eric Wed Oct 20 09:14 +0000 1993
Date: Wed, 20 Oct 1993 09:14 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: Inline comments and abstraction
 
Lee writes:
 
............
>However, my hands down favorite in the terminology game is Norman
>Ramsey's use of ``chunks'' in noweb.  The word chunk carries no
>``excess baggage,'' as to both module and section (the former in
>programming, the latter in word processing).  It's unambiguous to
>speak of ``code chunks'' and ``text chunks'' and the terms are readily
>understandable.  Chunk also has the advantage that it's only one
>syllable, and therefore, easier to say.
.........
 
There is another, much more important reason to standarize on the use
of the word "chunk". Psychologist use "chunk" to identify the mental units
one manipulates in his/her wetware (brain) when we are thinking. In a
literate program we try to document individually the chunks that play a 
role in  understanding a program.
 
Eric
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Mark.Probert@nms.otc.com.au Wed Oct 20 19:00:33 GMT 1993
Date: Wed, 20 Oct 93 19:00:33 GMT
From: Mark.Probert@nms.otc.com.au (Mark Probert)
Reply-To: LitProg@SHSU.edu, Mark.Probert@NMS.OTC.COM.AU
To: LitProg@SHSU.edu, preston@cs.rice.edu
Subject: Re:  cf. Chuck Moore, VLSI, Forth
 
Preston Briggs...
> 
> Chuck Moore invented Forth.  Doesn't have much to do with
> literate programming.  He also designed one (or more?) 
> micros intendedespecially to run Forth well.
> I don't believe they actually had a compiler built in;
> rather, they had exactly the registers and stacks required to
> run a Forth interpreter efficiently, and no more.
>
The only ``commercial'' micro made was the Harris RTX2000, which
used Forth as it microcode. All of the basic words you needed were
there in ``hardware'' with optimised stack access. Great chip for
it's day, pity Harris axed it so quickly.
 
> 
> Enquire on comp.arch or comp.lang.forth for details.
> 
Yep.
 
-- 
mark.    (probertm@nms.otc.com.au) ph: (02) 339 3705  fax: (02) 339 3917
 
From Thompson, Wed Oct 20 13:14:00 PDT 1993
Date: Wed, 20 Oct 93 13:14:00 PDT
From: "Thompson, David" <dthompson@coe2.coe.ttu.edu>
Reply-To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU
To: LitProg <litprog@shsu.edu>
Subject: literate programming faq
 
I've posted the first version of the literate programming faq on the 
faq-server.  It should be forthcoming within the next day or so.
 
I solicit your comments, and request that you understand the rough nature of 
the document.  It will mature, but it takes time.
 
Also, thanks to all of you who helped make the faq possible.  See the 
document for a specific listing of individuals.
 
 -=d
 
David B. Thompson               internet: wqdbt@ttacs1.ttu.edu
Civil Engineering Dept.         internet: dthompson@coe2.coe.ttu.edu
Texas Tech University           internet: thompson@sun1.coe.ttu.edu
P.O. Box 41023
Lubbock, Texas 79409-1023       "Get a haircut and get a *real* job."
 
From schrod@iti.informatik.th-darmstadt.de Wed Oct 20 13:14:00 PDT 1993
Date: Wed, 20 Oct 93 13:14:00 PDT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <9310192312.AA22346@athos.cs.ua.edu>, mbrown@athos.cs.ua.edu (Marcus Brown) writes:
> 
> I really like the term `chunks,' and hereby go on record as
> recommending it for canonization as the _APPROVED_ term for the code
> fragments (with associated documentation, macros, etc.) which make up
> a WEB.
 
I like the term `chunks', too. But, not as a replacement for `section'
-- as a replacement for `program part'. Or did I misunderstand you,
and you talk about the same?
 
Nevertheless, I would also like to keep the term `refinement' as a
notion for the catenation of all chunks with the same name. I.e., for
one node in the tree that constitutes the `real' source, after all.
I think the disctinction is important, since we're on different
abstraction levels here.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
	When it comes to Literate Programming, I get irrational.
							--- DEK, 16 Jul 93
 
From George Wed Oct 20 17:06:22 CST 1993
Date: Wed, 20 Oct 1993 17:06:22 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
Subject: Re: Revision Control
 
On 19 Oct 1993 21:33:36 GMT, schrod@iti.informatik.th-darmstadt.de (Joachim
Schrod) posted:
>    (My style option will be available from latex/contrib/rcs after
> one of the CTAN managers has answered my question posed a month ago.
> Hint, hint... ;-) Currently, you can fetch it from
> ftp.th-darmstadt.de:pub/tex/latex/.
 
Hmmmmmm.  I guess I missed your question -- sorry.  I have no idea what it
was and quite honestly have no idea where I would have filed it away (it
isn't in my file I keep on you, Joachim).
 
If anyone ever needs to get to me about the CTAN here (or whoever might be
watching it for me in my absence, assuming I ever get a vacation), you can
post to:
 CTAN-Mgr@SHSU.edu
Alternately, we have a list which only has the people directly involved in
the CTAN subscribed to but which is open for posts from anyone anywhere --
you can post to and get everyone's attention whose attention needs getting
to.  To post to it, use the address:
 CTAN@SHSU.edu
 
Regards,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From George Wed Oct 20 17:19:45 CST 1993
Date: Wed, 20 Oct 1993 17:19:45 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: LitProg@SHSU.edu, norman@BELLCORE.COM
Subject: Re: Literate Programming Examples
 
On Tue, 19 Oct 93 18:49:07 -0400, <norman@bellcore.com> posted:
> I think it's high time we had a central repository of literate-programming
> examples.  I think CTAN is the natural place for it, but if CTAN isn't 
> interested, I'll ask my management if we can arrange something here. (The
> problem is that our lawyers won't let us make an ftp area that is both
> readable and writable, and it takes real staff hours to move things from an
> incoming to a readable directory.)
 
It isn't that the CTAN isn't interested (at least as far as SHSU is
concerned w.r.t. interest anyway); instead (unless something's happened in
the past few days I am unaware of), it's that the CTAN is quickly running
out of space on the hosts.  Right now, SHSU has about 1.27 gig of stuff on
a 1.2 gig drive.  I have another 2.4 gig of archive space coming Real Soon
Now for our Unix host (and I've actually seen the purchase order and
outbound requisition, so RSN may actually be RSN) and about .8 gig of that
is already taken.  I'm just hoping that the remaining 1.6 will be enough to
get me through the next calendar year.
 
Anyway, moral of the story for SHSU's leg of the CTAN, is that as soon as I
have the space available, I will be going back to a proactive stance on
adding things; however, until we can get some additional resources for the
other hosts, I can't guarantee that the LitProg-related stuff can or will
be propagated from SHSU to the other hosts.  Until then, the only way I
could support it would be by traversing multiple hosts, which I prefer not
to do for a variety of reasons (but will if everyone feels it has to be
done).
 
--George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From norman@bellcore.com Wed Oct 20 22:54:10 -0400 1993
Date: Wed, 20 Oct 93 22:54:10 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: "George D. Greenwade" <bed_gdg@SHSU.edu>
Subject: Re: Literate Programming Examples
 
> On Tue, 19 Oct 93 18:49:07 -0400, <norman@bellcore.com> posted:
> > I think it's high time we had a central repository of literate-programming
> > examples.
> [the CTAN is quickly running out of space on the hosts]
> [I have another 2.4 gig of archive space coming Real Soon Now]
> [I will be going back to a proactive stance]
 
OK.  If I understand correctly, you are willing to maintain an archive
of examples at SHSU once your new disk arrives.  Other CTAN sites
might or might not mirror it depending on space consumption.  If RSN
doesn't arrive, or if people perceive a pressing need, I can probably
arrange a temporary archive at Princeton.
 
Norman
 
From norman@bellcore.com Wed Oct 20 23:00:27 -0400 1993
Date: Wed, 20 Oct 93 23:00:27 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LITPROG@SHSU.edu
Subject: Prettyprinting
 
While we're on the topic of prettprinting, has anyone found any good
monospace fonts?  The PostScript Courier fonts are *ugly*.  I'm especially
curious to know whether any METAFONT wizards out there have tried to
use the META-ness to create monospace versions of Computer Modern Roman,
Bold, and Text Italic.
 
Norman
 
From greyham@research.canon.oz.au Thu Oct 21 07:51:54 GMT 1993
Date: Thu, 21 Oct 1993 07:51:54 GMT
From: greyham@research.canon.oz.au (Graham Stoney)
Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU
To: LitProg@SHSU.EDU
Subject: c2man-2.17: Automatic C documentation generator is now under review.
 
c2man is an automatic documentation generator which generates functional
interface documentation from C source code and comments. Patches 10 thru 17
to c2man are currently under review in comp.sources.reviewed. If you are a
C user and are interested in not having to write documentation manually,
please consider reviewing these patches.
 
With this new version of c2man, OS/2 and MSDOS are supported, and texinfo
output can be generated in addition to the usual nroff -man.
 
These patches will be posted after the review is complete and any significant
problems have been addressed. If you fetch the package for review, please
return your review in a timely manner, since the sooner the reviews are
returned, the sooner the patches will be posted.
 
If you are already using c2man at patchlevel 17, please consider sending in
a review anyway.
 
[comp.sources.reviewed Moderator's info]
 
This package contains a C program to convert C source to `nroff -man' input,
plus 7 patch files and a shell dirver to unpack the lot.  This product has
been reviewed and posted before.  Check it out.
 
If you are interested in *reviewing* this package send a mail message
to the csr mail-server:
 
	To: csr@cc.purdue.edu
	Subject: send c2man
 
	<thanks>
	<sig>
 
and the mail server will send you the stuff.
 
Initial comments:
	- I unpacked the parts, and applied the patches.
	- I include a script to do the same for you
	- I configured the product and it runs on sun4-sunos4.1.3.
	- you get 17 parts, but 3 of them are padding for the mail-server
 
If you need help with the mail-server send a note like
	To: csr@cc.purdue.edu
	Subject: help
 
	<thanks>
	<sig>
 
Graham
-- 
Graham Stoney, Hardware/Software Engineer
Canon Information Systems Research Australia
Ph: + 61 2 805 2909	Fax: + 61 2 805 2929
 
From creilly@maths.tcd.ie Thu Oct 21 07:51:54 GMT 1993
Date: Thu, 21 Oct 1993 07:51:54 GMT
From: creilly@maths.tcd.ie (Colman Reilly)
Reply-To: LitProg@SHSU.edu, creilly@MATHS.TCD.IE
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
detig@iti.informatik.th-darmstadt.de (Christine Detig) writes:
 
>I think `chunk' is fine, but as a non-native speaker, I'm not sure if
>this word contains some sloppyness --- I mean, the kind of words you
>say but don't write. Could some native speakers, probably from both
>sides of the Atlantic, comment on this?
 
Chunk is an execellent word to use actually, as it doesn't have any other
technical meaning I'm aware of. As someone new to literate programming I
found the word scrap  very strange in this context - my code isn't a _scrap_
or leftover anything, no matter what my lecturers say. :-)
 
Colman
-- 
Colman Reilly (creilly@maths.tcd.ie) [+353-(0)1-7022280]
c/o School of Mathematics,18.05 Westland Row,Trinity College,Dublin.
PGP Public Key on Request
"Nothing so strong as gentleness; nothing so gentle as real strength." 
 
From detig@iti.informatik.th-darmstadt.de Thu Oct 21 07:51:54 GMT 1993
Date: Thu, 21 Oct 1993 07:51:54 GMT
From: detig@iti.informatik.th-darmstadt.de (Christine Detig)
Reply-To: LitProg@SHSU.edu, detig@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <2a2f1d$3a0@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes:
> Personally, I like the term `block', although `chunk' is OK too.
> Actually, a block of code can be considered in direct correlation to
> the cognitive chunks in psychology.
 
In many programming languages, `block' is used for parts of code which
have a common scope. Thus, our chunks would in general spread over
several blocks or contain only parts of them, which seems to make the term
unappropriate to me.
 
I think `chunk' is fine, but as a non-native speaker, I'm not sure if
this word contains some sloppyness --- I mean, the kind of words you
say but don't write. Could some native speakers, probably from both
sides of the Atlantic, comment on this?
 
Christine
detig@iti.informatik.th-darmstadt.de
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Good documentation, it seems, is like the weather: everyone is talking
about it, but few people are doing anything about it.
 
From mbrown@athos.cs.ua.edu Thu Oct 21 08:58:34 -0500 1993
Date: Thu, 21 Oct 1993 08:58:34 -0500 (CDT)
From: mbrown@athos.cs.ua.edu (Marcus Brown)
Reply-To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU
To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
Subject: Re: Inline comments and abstraction
 
Joachim Schrod wrote:
> 
> In article <9310192312.AA22346@athos.cs.ua.edu>, mbrown@athos.cs.ua.edu (Marcus Brown) writes:
> > 
> > I really like the term `chunks,' ...
> 
> I like the term `chunks', too. But, not as a replacement for `section'
> -- as a replacement for `program part'. Or did I misunderstand you,
> and you talk about the same?
>  [Stuff deleted]
> --
> Joachim
> 
I would like to use the term in referring to both the program part
and the associated documentation.  After all, in a 'Literate' program,
the code is not complete without the accompanying documentation, etc.
 
However, I would not object to the term being used specifically with
reference to the code alone.
 
-- 
Marcus Brown
mbrown@cs.ua.edu
Computer Science Dept, Univ of Alabama
 
From koopman@sgi84.ctc.com Thu Oct 21 11:07:25 -0400 1993
Date: Thu, 21 Oct 93 11:07:25 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU
Subject: Inline comments and abstraction
 
Marcus Brown wrote:
 
>Joachim Schrod wrote:
>> I like the term `chunks', too. But, not as a replacement for `section'
>> -- as a replacement for `program part'. Or did I misunderstand you,
>> and you talk about the same?
>> 
>I would like to use the term in referring to both the program part
>and the associated documentation.  After all, in a 'Literate' program,
>the code is not complete without the accompanying documentation, etc.
>
>However, I would not object to the term being used specifically with
>reference to the code alone.
 
How about chunklet for the code or documentation part.  Cryptic code
or poor documentation could be "dark" chunklet and code that took
forever to write could be "milk" chunklet.
 
Mike <koopman@ctc.com>
 
From Lee Thu Oct 21 13:37:40 EDT 1993
Date: Thu, 21 Oct 93 13:37:40 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, schrod@iti.informatik.th-darmstadt.de
Subject: Re: Inline comments and abstraction
 
Joachim Schrod writes:
 
> I like the term `chunks', too. But, not as a replacement for `section'
> -- as a replacement for `program part'. Or did I misunderstand you,
> and you talk about the same?
 
Generally, I use `chunk' for program part, but the noweb documentation
refers to ``text chunks'' and ``code chunks,'' and I use those terms
as well.
 
> Nevertheless, I would also like to keep the term `refinement' as a
> notion for the catenation of all chunks with the same name. I.e., for
> one node in the tree that constitutes the `real' source, after all.
> I think the disctinction is important, since we're on different
> abstraction levels here.
 
That's a good point.  I like the term `refinement' in this context.
It works well with the way `refinement' is used in the ABC programming
language.
 
		-- Lee
		   leew@pilot.njin.net
 
From thompson@sun1.coe.ttu.edu Thu Oct 21 13:37:40 EDT 1993
Date: Thu, 21 Oct 93 13:37:40 EDT
From: thompson@sun1.coe.ttu.edu
Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu
To: LitProg@SHSU.EDU
Subject: comp.programming.literate FAQ
 
Archive-name: literate-progamming-faq
Last-modified: 1993/10/15
Version: 1.0.1
 
Welcome to the Literate Programming Frequently Asked Questions List
 -------------------------------------------------------------------
 
This version was created Fri 10/15/1993 and should considered stale
after 90 days.  Information contained in this document is the best
available at preparation.
 
Disclaimer: "This FAQ is presented with no warranties or guarantees of
ANY KIND including correctness or fitness for any particular purpose.
The author of this document has attempted to verify correctness of the
data contained herein; however, slip-ups can and do happen.  If you use
this data, you do so at your own risk."
 
Copyright 1993 David B. Thompson.  All rights reserved.  Permission is
granted to copy this document for free distribution so long as it
remains intact and unmodified.
 
* Introduction:
 ---------------
 
This document is for new and experienced users of literate programming
tools.  The purpose is to explain the concept of literate programming and
to provide a resource for locating files of interest to literate
programmers and those interested in literate programming.
 
The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list
is maintained by Dave Thompson, who can be reached at:
 
    thompson@sun1.coe.ttu.edu     * Preferred mailing address for FAQ
                                    related comments/questions.
    dthompson@coe2.coe.ttu.edu    * Preferred for purposes other than FAQ.
    wqdbt@ttacs1.ttu.edu          * Forwarded to me.
 
Comment and constructive criticism is welcome.  Direct flames to
/dev/null (or > nul if you're a msdos user! ;-)  If you find an error,
please report it.  I'm particularly interested in establishing the
locations of generally available literate programming tools.  If you are
the author of such a tool and wish to have it included in this list,
please send email.
 
Please note this is a work-in-progress.  It is *not* complete, and
probably will not be complete for some months.  Nevertheless, the
information contained herein may be useful to some.  Use it as it is
intended.
 
 - ----------------------------------------------------------------------
 
 - Typography:
 -------------
 
Major sections of the FAQ are divided by double lines (====).  Minor
sections and other divisions are separated by single lines (----).
Major topics use a "* " as a leader.  Minor topics use a "- " as a
leader.  This should simplify searching for topics.
 
Table of Contents:
 ------------------
 
* Introduction
    - Typography.
* How to get the FAQ.
    - Literate Programming FAQ.
    - FWEB FAQ.
* The LitProg newsgroup.
* Internet nodes of interest to literate programmers.
* What is literate programming?
* How do I begin literate programming?
* What tools are available and where are they?
    - FWEB
    - CWEB
    - NOWEB
    - NUWEB
    - FunnelWeb
    - SchemeWEB
    - c2latex
* Languages supported with literate programming tools.
* What other resources are available?
* Code examples.
    - Cameron Smith's KR-CWEB
    - Bart Child's examples for FWEB
    - Examples with CWEB
    - Examples with FWEB
* Bibliographies.
* How to anonymously ftp.
* Acknowledgements.
* Notes.
 
* How to get the FAQ:
 ---------------------
 
 - Literate Programming FAQ.
 ---------------------------
 
You have many ways to get a current copy of this FAQ.  One is to use
anonymous ftp (if you don't know how, see a later section in this FAQ)
to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites
or the literate programming archive and retrieve a copy of the file.
(For more information on CTAN and the literate programming archive, see
the section below entitled "Internet Nodes of Interest to Literate
Programmers.")
 
An alternative is to use the fileserver at SHSU.  Send a message to
FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message
 
    SENDME FAQ.LITPROG
 
The file server will forward a copy of the file to you via email.
 
 - ----------------------------------------------------------------------
 
 - FWEB FAQ:
 -----------
 
Marcus Speh <marcus@x4u.desy.de> maintains the FWEB FAQ.  It can be
retrieved in the same way as this FAQ; either by anonymous ftp or
through the SHSU file server.  On the SHSU server, the file name is
FAQ.FWEB.  Invoke your ftp software, open a connection to NIORD.SHSU.EDU
[192.92.115.8], attach to the directory FAQ, and transfer the file
FAQ.FWEB.
 
Alternatively, send a message to the file server, FILESERV@SHSU.EDU
(FILESERV@SHSU.BITNET), and include the following text in a one line
message:
 
    SENDME FAQ.FWEB
 
The file server will send the current version of the file via email.
 
The FWEB FAQ exists in various formats, including HyperText (see other
resources below). In Europe, the complete distribution can also be
obtained from ftp.desy.de [131.169.10.38] in directory
/pub/faq/web/fweb/.
 
* The LitProg Newsgroup:
 ------------------------
 
One of the most important resources is the literate programming
newsgroup, comp.programming.literate.  You can read this newsgroup using
your standard reader.  Altenatively, the newsgroup is gated to a mailing
list hosted by George Greenwade and Sam Houston State University.  You
can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or
LISTSERV@SHSU.BITNET), and include in the message one line of text:
 
    SUBSCRIBE LITPROG  "your name in quotes"
 
The list is unmoderated; messages sent to litprog@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.programming.literate.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory litprog.
 
* Internet Nodes of Interest to Literate Programmers:
 -----------------------------------------------------
 
The principal nodes of interest to literate programmers are the Literate
Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX
Archive Network).
 
The Literate Programming Archive is:
 
  Node:       ftp.th-darmstadt.de [130.83.55.75]
  Directory:  pub/programming/literate-programming
  Notes:      Fastest response during off-U.S. [yep] business hours.
 
The CTAN sites are:
 
ftp host             IP            CTAN root    Institution and Sponsor
 -------------------------------------------------------------------------
ftp.TeX.ac.UK        134.151.79.32 pub/archive  Aston Univ./UK TeX U.G.
ftp.Uni-Stuttgart.DE 129.69.1.12   soft/tex     Univ. Stuttgart/DANTE e.V
ftp.SHSU.edu         192.92.115.10 tex-archive  Sam Houston State Univ.
 
Other nodes and directories of interest include:
 
  Node:       niord.shsu.edu [192.92.115.8]
  Directory:  various (do some snooping!)
  Notes:      Has a gopher server.
 
  Node:       ftp.desy.de [131.169.10.38]
  Directory:  pub/web. Various documents, samples, and the FWEB FAQ.
  Notes:      Has a www server, http://info.desy.de:80/
 
* What is Literate Programming?
 -------------------------------
 
Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings.  In fact,
literate programs should be enjoyable reading, even inviting!  (Sorry
Bob, I couldn't resist!)  In general, literate programs combine source
and documentation in a single file.  Literate programming tools then
parse the file to produce either readable documentation or compilable
source.  The WEB style of literate programming was created by D.E. Knuth
during the development of his TeX typsetting software.
 
All the original work revolves around a particular literate programming
tool called WEB.  Knuth says:
 
     The philosophy behind WEB is that an experienced system
     programmer, who wants to provide the best possible
     documentation of his or her software products, needs two
     things simultaneously: a language like TeX for formatting,
     and a language like C for programming.  Neither type of
     language can provide the best documentation by itself; but
     when both are appropriately combined, we obtain a system
     that is much more useful than either language separately.
 
     The structure of a software program may be thought of as a
     web that is made up of many interconnected pieces.  To
     document such a program we want to explain each individual
     part of the web and how it relates to its neighbours. The
     typographic tools provided by TeX give us an opportunity to
     explain the local structure of each part by making that
     structure visible, and the programming tools provided by
     languages such as C or Fortran make it possible for us to
     specify the algorithms formally and unambigously. By
     combining the two, we can develop a style of programming
     that maximizes our ability to perceive the structure of a
     complex piece of software, and at the same time the
     documented programs can be mechanically translated into a
     working software system that matches the documentation.
 
* How to begin literate programming:
 ------------------------------------
 
A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate
Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk).
 
Another is D.E. Knuth's collection of articles (1992) "Literate
Programming," Center for the Study of Language and Information,
Stanford University, ISBN 0-937073-80-6 (pbk).  This is more of
historical interest than Sewell's book, but is a good read.
 
Some talk exists in the newsgroup/mailing list for a Usenet University
course in literate programming.  I'm sure discussion of this topic will
be welcomed.  If you are interested, please participate.
 
* What Tools are Available:
 ---------------------------
 
A significant number of tools for literate programming are available.
Most have been ported from their original systems, so support multiple
computer platforms.  If you are the developer of such a tool, and would
like to make the software freely available, please send me email and
I'll reply with a form (like those below) for you to fill in.  (Or
short-circuit the process and kludge a form from below. :-)
 
 - FWEB:
 -------
 
Developer:
            John A. Krommes
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX.
 
Availability:
            anonymous ftp from lyman.pppl.gov/pub/fweb
            anonymous ftp from CTAN/web/fweb
            anonymous ftp from LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            It also has a well-developed user's manual and its own FAQ
            (see above). It runs on most platforms: VMS, PC, UNIX, and
            pretty much anything that the GNU C compiler (GCC) is
            supported for.
 
Support:
            bug reports to krommes@princeton.edu
 
 - ----------------------------------------------------------------------
 
 - CWEB:
 -------
 
Developer:
            Silvio Levy and D.E. Knuth
 
System(s) supported:
            Unix systems (dos port available)
 
Software supported:
            C, C++, TeX, and LaTeX.
 
Availability:
            anonymous ftp from labrea.stanford.edu/pub/cweb
            anonymous ftp from CTAN/web/c_cpp/cweb
            anonymous ftp from CTAN/web/c_cpp/cwb30p8c  (dos version)
 
Readme:
            bundled with above
 
Brief description:
 
Support:
            bugs to levy@math.berkeley.edu
 
 - ----------------------------------------------------------------------
 
 - NOWEB:
 --------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            All programming languages, (La)TeX formatters.
 
Availability:
            anonymous ftp from csservices.princeton.edu/pub/noweb.shar.Z
            anonymous ftp from bellcore.com/pub/norman/noweb.shar.Z
 
Readme:
            with bundle above
 
Brief description:
 
               noweb is designed to meet the needs of literate programmers
            while remaining as simple as possible.  Its primary
            advantages are simplicity, extensibility, and
            language-independence.  noweb uses 4 control sequences to
            WEB's 27, and its manual is only two pages. noweb works
            ``out of the box'' with any programming language, and its
            formatter-dependent part is under 50 lines.  The primary
            sacrifice relative to WEB is the loss of the
            language-dependent features: prettyprinting and an index of
            identifiers.
 
Support:
            by email to the author
 
 - ----------------------------------------------------------------------
 
 - NUWEB:
 --------
 
Developer:
            Preston Briggs: preston@cs.rice.edu
 
Systems supported:
            Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS.
 
Software supported:
            It's written in C.  It works with any programming language
            (or combination of programming languages) and Latex
 
Availability:
            anonymous ftp from CTAN/web/nuweb     (UNIX)
            anonymous ftp from CTAN/web/nuweb-pc  (MSDOS)
            anonymous ftp from LPA
 
Readme:
            Send mail to preston@cs.rice.edu
 
Brief description:
 
            A single program that takes a web file written in a
            combination of latex and any programming language(s) and
            produces a latex file that can be pretty printed and a set
            of files containing code for compilation/interpretation by
            the appropriate language processors.
 
            Strengths include speed, simplicity, multiple languages,
            nice indices and cross-references, latex.  Doesn't require
            any special macros or macro files.
 
            Drawbacks: latex-dependent, no code pretty printing, harder
            to make indices than cweb.
 
            More good stuff: nice support for make, doesn't reformat
            source files, so they're easy to debug.  Lots of control
            without too much effort.  That is, it doesn't do too much!
 
            Future directions... Very little change planned, except
            perhaps refinements in the indexing software.
 
Support:
            Hack it yourself or send e-mail to preston@cs.rice.edu
 
 - ----------------------------------------------------------------------
 
 - FunnelWeb:
 ------------
 
Developer:
            Ross N. Williams: ross@guest.adelaide.edu.au
 
Systems supported:
            MSDOS, Mac, VMS, Sun.  Other ports reported.
 
Software supported:
            For printing, TeX.  Otherwise no restrictions.
 
Availability:
            anonymous ftp from CTAN/web/funnelweb
            anonymous ftp from ftp.adelaide.edu/pub/funnelweb
 
Readme:
            With bundle above.
 
Brief description:
            FunnelWeb is a production-quality literate-programming tool
            that emphasises simplicity and reliability. Everything about
            FunnelWeb, from the simplicity of its language to the
            comprehensive tutorial in the user's manual, has been
            designed to make this as simple, as practical, and as usable
            a tool as possible.
 
            Features:
               + Provides a simple macro preprocessor facility.
               + Can produce typeset documentation.
               + Runs on Sun, VMS VAX, Macintosh, PC, and others.
               + Portable C source code distributed under GNU licence.
               + Comprehensive user's manual including tutorial.
               + Programming-language independent.
               + Can generate multiple output files.
               + Allows complete control over the output text.
               + Regression test suite with over 200 tests.
               + Fully worked example (in /pub/funnelweb/examples).
               - Requires TeX to produce typeset documentation.
               - Typesets program code using TT font only.
 
Support:
            No formal support available.  Mailing list maintained with
            about 50 subscribers.  Informal assistance available from
            mailing list.
 
 - ----------------------------------------------------------------------
 
 - SchemeWEB:
 ------------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Programming language: Any dialect of Lisp.
            Text formatter: LaTeX.
 
Availability:
            The Unix version is in the Scheme Repository and it is
            available via anonymous ftp from nexus.yorku.ca in
            /pub/scheme/utl.
 
            The DOS version is part of the PCS/Geneva Scheme system
            which is available via anonymous ftp from cui.unige.ch in
            /pub/pcs.
 
Readme:
            In bundle with above.
 
Brief description:
            SchemeWEB is a Unix or DOS filter that translates
            SchemeWEB source into LaTeX source or Lisp source.
            Lisp code is formatted in typewriter type font and
            the comments are passed to LaTeX unchanged.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
 - ----------------------------------------------------------------------
 
 - C2LaTeX:
 ----------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix
 
Software supported:
            Programming language: C.
            Text formatter: LaTeX but it's easy to change the formatter.
 
Availability:
            Anonymous ftp from
                omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex.
 
Readme:
            Absent.  Documentation is in the C source for c2latex.
 
Brief description:
            C2latex provides simple support for literate programming
            in C.  Given a C source file in which the comments have
            been written in LaTeX, c2latex converts the C source file
            into a LaTeX source file.  It can be used to produce
            typeset listings of C programs and/or documentation
            associated with the program.
 
            C2latex produces LaTeX source by implementing a small
            number of rules.  A C comment that starts at the beginning
            of a line is copied unmodified into the LaTeX source
            file.  Otherwise, non-blank lines are surrounded by a pair
            of formatting commands (\begin{flushleft} and
            \end{flushleft}), and the lines are separated by \\*.
            Each non-blank line is formatted using LaTeX's \verb
            command, except comments within the line are formatted in
            an \mbox.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
* Other resources:
 ------------------
 
An untapped resource (by me anyway ;-) is the World Wide Web.  Marcus
Speh has expended considerable effort in this regard.  If you're
connected to WWW, then access:
 
  http://info.desy.de/pub/www/projects/LitProg.html
 
If you aren't connected to WWW, telnet to info.cern.ch and explore.
You can reach Marcus' literate programming pages by typing:
 
  go http://info.desy.de/pub/www/projects/LitProg.html
 
Help for people who have only Email and neither WWW nor telnet, can be
obtained by Email from LISTSERV@INFO.CERN.CH by sending a message
containing the command HELP.  Instructions will be returned by email.
For literate programming documents, you can try anonymous ftp to
ftp.desy.de [131.169.30.33] and attach to directory:
 
  /pub/www/projects/Announce
 
Another resource of interest to literate programmers is the info-tex
mailing list.  If you're using (La)TeX as your typsetting system and
have access to internet, then you should investigate this mailing list.
Mail list service is available through the SHSU list-server.  To
subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET),
and include in the message one line of text:
 
    SUBSCRIBE INFO-TEX "your name in quotes"
 
The list is unmoderated; messages sent to info-tex@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.text.tex.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory info-tex.
 
* Code Examples:
 ----------------
 
Examples of web programs are included with the FWEB distribution.  Also,
demonstration programs are included with the CWEB distribution.
 
Bart Childs converted the K&R calculator program into a literate
program.   It can be retrieved from niord.shsu.edu [192.92.115.8] from
directory kr-cweb-sample as krcwsamp.zip.
 
Ross Williams has released a funnelweb example.  You can retrieve this
file from node ftp.adelaide.edu.au [129.127.40.3] as
  /pub/funnelweb/examples/except.*
This file should be on CTAN as well.
 
* Bibliographies:
 -----------------
 
Nelson Beebe has collected an extensive bibliography treating literate
programming.  His work is available for anonymous ftp from
ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files:
    litprog.bib
    litprog.ltx.
Although I have not verified this, LPA is an alternate source for these
files.  Note that they are updated frequently (Nelson says several times
each week), so be sure to get a fresh copy before extensive use.
Joachim Schrod indicates that these files may be updated daily and can
be retrieved via anonymous ftp at LPA/documentation.
 
* How to anonymously ftp:
 -------------------------
 
Pretty much everything mentioned here is available by anonymous FTP.
FAQ lists cross-posted to news.answers and rec.answers can be gotten
from rtfm.mit.edu (18.70.0.224), under /pub/usenet/news.answers or under
/pub/usenet/more.specific.group.name
 
"anonymous FTP" is just a way for files to be stored where anyone
can retrieve them over the Net.    For example, to retrieve the
latest version of the literate programming FAQ, do the following:
 
> ftp rtfm.mit.edu              /* connect to the site; message follows */
> anonymous                     /* type this when it asks for your name */
> <your email address>          /* type your address as the password    */
> cd /pub/usenet                /* go to the directory you want to be   */
> cd comp.programming.literate  /* one level down (no slash).           */
> dir                           /* look at what's there                 */
> get litprog.faq               /* get the file; case-sensitive         */
> quit                          /* stop this mysterious thing           */
 
If your FTP program complains that it doesn't know where the site you
want to use is, type the numerical address instead of the sitename:
 
> ftp 18.70.0.224       /* connect with numerical address */
 
If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu
with the single word "help" in the body of the message.
 
Getting binary files (executables, or any compressed files) is only
slightly more difficult.   You need to set binary mode inside FTP before
you transfer the file.
 
> binary            /* set binary transfer mode  */
> ascii             /* set back to text transfer mode */
 
FAQs and spoiler lists are generally ascii files; everything else is
generally binary files.
 
Some common extensions on binary files in archive sites are:
 
  .Z           Compressed; extract with uncompress
  .tar.Z       Compressed 'tape archive'; uncompress then untar or tar -xvf
  .gz or .z    Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu)
  .sit         (Mac) StufIt archive
  .zip         (PC) Extract with Zip or Unzip
  .zoo         (PC) Yet another archive/compress program
  .lhe         (Amiga) ?
  .exe         (PC) Self-extracting archives - just execute them.
  .uue or .UUE Transfer as text file; use uudecode to convert to binary
  .hqx         (Mac) BinHex format; transfer in text mode
 
Generic help can be found in the FAQs of comp.binaries.<your_system_type>
for how to transfer, extract, and virus-check binary files.  (At
rtfm.mit.edu)
 
If you can't FTP from your site, use one of the following ftp-by-mail
servers:
 
  ftpmail@decwrl.dec.com
  ftpmail@src.doc.ic.ac.uk
  ftpmail@cs.uow.edu.au
  ftpmail@grasp.insa-lyon.fr
 
For complete instructions, send a message reading "help" to the server.
 
If you don't know exactly what you're looking for, or exactly where it
is, there are programs and servers that can help you.  For more info,
send e-mail to mail-server@rtfm.mit.with with the body of the
message reading send usenet/news.answers/finding-sources
 
Thanks to Aliza R. Panitz (the "buglady") for this text.  I copied it
verbatim from her post on faq-maintainers with only minor modifications.
 
* Acknowledgements:
 -------------------
 
This document would not have happened without the help of many people.
Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim
Schrod, Piet van Oostrum, and Ross N. Williams.  A special thanks to
Aliza R. Panitz for the text describing how to execute an anonymous ftp
for files of interest.
 
Any omissions from these acknowledgements should be considered an act of
stupidity on my part.  Of course, the authors of literate programming
tools mentioned above all play a vital role in the vitality of literate
programming. Furthermore, participants in the comp.programming.literate
newsgroup (and associated mailing list) all contributed in various
fashions. Thank all of you.
 
* Notes:
 --------
 
This document will be evolving over the next few months.  I'm planning
on adding entries for additional literate programming tools and will
expand the sections on examples as more examples become available. Tools
I will include are web (the original pascal version), funnelweb,
spiderweb, and cnoweb for starters. Others will be added as I find and
document them.  Omission of a particular tool should not be considered a
snub in any sense--simply an error or oversight on my part.
 
History:
 
  First release: Fri 10/15/1993 -- Yep, I finally did it!
 
From Lee Thu Oct 21 13:42:32 EDT 1993
Date: Thu, 21 Oct 93 13:42:32 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, norman@bellcore.com
Subject: Re: Prettyprinting
 
Norman Ramsey asks:
 
> While we're on the topic of prettprinting, has anyone found any good
> monospace fonts?  The PostScript Courier fonts are *ugly*.  I'm especially
> curious to know whether any METAFONT wizards out there have tried to
> use the META-ness to create monospace versions of Computer Modern Roman,
> Bold, and Text Italic.
 
There's a really nice monospaced PostScript font that came with our
NeXT machine.  It's named after the guy who designed it, but I forget
who (and the machine's half-way across campus).  I can check it out if
no one else knows.
 
		-- Lee
		   leew@pilot.njin.net
 
From cgra@se.alcbel.be Thu Oct 21 15:43:03 -0500 1993
Date: Thu, 21 Oct 1993 15:43:03 -0500 (CDT)
From: cgra@se.alcbel.be (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: Prettyprinting
 
In article <16721946@MVB.SAIC.COM>, norman@bellcore.com (Norman Ramsey) writes:
 
>While we're on the topic of prettprinting, has anyone found any good
>monospace fonts?  The PostScript Courier fonts are *ugly*.  I'm especially
>curious to know whether any METAFONT wizards out there have tried to
>use the META-ness to create monospace versions of Computer Modern Roman,
>Bold, and Text Italic.
 
>Norman
 
Might not  cmtt be a  place to start?Or is that considered even uglier than
Courier?
 
(I've just bought the  MF book.  A  bold or sloping cmtt  should be a good
practical  exercise.  When  I  get  that  round  tuit  I  keep asking for.)
 
__________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
 
From Edward Thu Oct 21 15:43:03 -0500 1993
Date: Thu, 21 Oct 1993 15:43:03 -0500 (CDT)
From: "Edward M. Robinson" <Robinson@UH.EDU>
Reply-To: LitProg@SHSU.edu, Robinson@UH.EDU
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Prettyprinting
 
Lee Wittenberg wrote :
>
>Norman Ramsey asks:
>> While we're on the topic of prettprinting, has anyone found any good
>> monospace fonts?  The PostScript Courier fonts are *ugly*.  I'm especially
>> curious to know whether any METAFONT wizards out there have tried to
>> use the META-ness to create monospace versions of Computer Modern Roman,
>> Bold, and Text Italic.
>
>There's a really nice monospaced PostScript font that came with our
>NeXT machine.  It's named after the guy who designed it, but I forget
>who (and the machine's half-way across campus).  I can check it out if
>no one else knows.
 
The name is 'ohlfs'.
 
Proprietary?
 
-- Ed Robinson
Robinson@uh.edu
 
From Roger Fri Oct 22 11:41 GMT0BST-1 1993
Date: Fri, 22 Oct 93 11:41 GMT0BST-1
From: Roger Horne <rhorne@cix.compulink.co.uk>
Reply-To: LitProg@SHSU.edu, rhorne@cix.compulink.co.uk
To: litprog@shsu.edu
Subject: Re: Prettyprinting
 
  >> monospace fonts?  The PostScript Courier fonts are *ugly*. 
  >> I'm especially curious to know whether any METAFONT wizards
  >> out there have tried to use the META-ness to create
  >> monospace versions of Computer Modern Roman, 
 
Try changing monospace:=true to monospace:=false in eg cmr12.mf (and rename
it to say cmr12m) and run Metafont on it. Voila, a monospaced cmr12. The
result is interesting, but hardly pretty. (The letter m looks even more
compressed than usual.)
 
Roger Horne
roger@number7.demon.co.uk
 
From marcus@x4u2.desy.de Fri Oct 22 14:01:34 GMT 1993
Date: Fri, 22 Oct 1993 14:01:34 GMT
From: marcus@x4u2.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
To: LitProg@SHSU.EDU
Subject: LitProg FAQ on WWW
 
I have put Dave Thompson's FAQ [recently posted to c.p.l.] on the
World Wide Web, URL
 
	http://info.desy.de/pub/faq/web/FAQ.txt
 
or (for the "collection" :-)
 
	http://info.desy.de/pub/www/projects/LitProg/FAQs.html
 
For subsequent editions, I will also put a "diff" file to that place.
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From C. Fri Oct 22 10:12:53 CDT 1993
Date: Fri, 22 Oct 93 10:12:53 CDT
From: "C. M. Sperberg-McQueen" <U35395%UICVM.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU
To: LitProg@SHSU.edu, detig@ITI.INFORMATIK.TH-DARMSTADT.DE
Subject: Re: Inline comments and abstraction
 
On 21 Oct 1993 15:41:40 GMT <detig@iti.informatik.th-darmstadt.de> said:
>I think `chunk' is fine, but as a non-native speaker, I'm not sure if
>this word contains some sloppyness --- I mean, the kind of words you
>say but don't write. Could some native speakers, probably from both
>sides of the Atlantic, comment on this?
 
I think your instinct is correct, Christine:  at least to this native
speaker of AmE, 'chunk' is marked for informality, and is more likely to
be found in spoken than in formal written English.  That is, of course,
part of its appeal to some of us (me, I like 'scrap' even better, partly
because it is an even less predictable term and partly because in the
context I work in, 'chunk' has already been assigned a technical meaning
as the name of a class of SGML elements).  So it is not at all out of
place in normal AmE computer science-type discourse, but it is perhaps
the kind of word (like 'memory' and 'flavor') bound to meet with the
disapproval of Edsger Dijkstra and others who share some of his less
flexible notions concerning proper terminology.
 
-C. M. Sperberg-McQueen
 
From norman@bellcore.com Fri Oct 22 13:54:26 -0400 1993
Date: Fri, 22 Oct 93 13:54:26 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
> [``chunk''] is perhaps
> the kind of word (like 'memory' and 'flavor') bound to meet with the
> disapproval of Edsger Dijkstra
 
What stronger endorsement could anyone ask for?
 
Norman
 
From Lee Fri Oct 22 15:49:49 EDT 1993
Date: Fri, 22 Oct 93 15:49:49 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, detig@iti.informatik.th-darmstadt.de
Subject: Re: Inline comments and abstraction
 
Christine Detig writes:
 
> I think `chunk' is fine, but as a non-native speaker, I'm not sure if
> this word contains some sloppyness --- I mean, the kind of words you
> say but don't write. Could some native speakers, probably from both
> sides of the Atlantic, comment on this?
 
As a native speaker (West Side of Atlantic/East Side of Pacific chapter --
we shouldn't forget the other ocean; native English speakers seem to
like distancing themselves from each other :-), `chunk' has the right
ring to my ears.  However, having been born in Brooklyn, I might have to
be disqualified.
 
`Chunk' also works well on paper, having acquired legitimacy from
Psychology (as a number of participants in this discussion have already
pointed out).
 
		-- Lee
 
From bdubbs@cs.tamu.edu Fri Oct 22 15:49:49 EDT 1993
Date: Fri, 22 Oct 93 15:49:49 EDT
From: bdubbs@cs.tamu.edu (Bruce Dubbs)
Reply-To: LitProg@SHSU.edu, bdubbs@CS.TAMU.EDU
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <16782125@mvb.saic.com>,
Lee Wittenberg  <leew@pilot.njin.net> wrote:
|Christine Detig writes:
| 
|> I think `chunk' is fine, but as a non-native speaker, I'm not sure if
|> this word contains some sloppyness --- I mean, the kind of words you
|> say but don't write. Could some native speakers, probably from both
|> sides of the Atlantic, comment on this?
|
|As a native speaker (West Side of Atlantic/East Side of Pacific chapter --
|we shouldn't forget the other ocean; native English speakers seem to
|like distancing themselves from each other :-), `chunk' has the right
|ring to my ears.  However, having been born in Brooklyn, I might have to
|be disqualified.
|
|`Chunk' also works well on paper, having acquired legitimacy from
|Psychology (as a number of participants in this discussion have already
|pointed out).
|
|		-- Lee
 
The problem with `chunk' is that it does have this use in Psychology.
The more complete term is `cognitive chunk'.  I have proposed the term
`cognitve block' in a paper now being refereed.  In writing code,
using the style of literate programming or not, the author presents
code in groupings.  The degree of mapping of these groupings or
`cognitive blocks' to the reader's psychological `cognitive chunks'
really dictates the readability or understandability of the code.  My
research indicates that WEB style literate programming tends to
provide a better mapping between blocks and chunks.
    -- Bruce
-- 
R. Bruce Dubbs, Jr., Ph.D.             email: bdubbs@tis.kelly.af.mil     
Mission Critical Software Division
Kelly AFB, Tx
 
From marcus@x4u2.desy.de Sat Oct 23 21:15:13 GMT 1993
Date: Sat, 23 Oct 1993 21:15:13 GMT
From: marcus@x4u2.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
To: LitProg@SHSU.EDU
Subject: nuweb doesnt like Emacs outline-regexp
 
I have a little problem with nuweb. Since I am working in GNU Emacs,
I'd like to use the outline mode [which all users of web-mode will
appreciate]. Thus, I usually insert a line like
 
% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*-
 
[my actual mode line also uses regexps for LaTeX headings etc.]
to be able to reduce the visible part of the document to something
like 
 
@o file -t @{
...
@}
 
@d HEADER @{
...
@}
...
 
etc. Now, nuweb refuses to follow and aborts with
 
	nuweb: bad @ sequence (file.nu, line 1)
 
There is no problem with that in noweb, where I am simple warned 
if I have "<<" in the mode-line for a possibly incomplete chunk def
or a missing "=".
 
  I would wish nuweb would switch from error to warning too. Anybody
ever ran into this problem? Is there a simple solution?
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From yjc@po.cwru.edu Sat Oct 23 23:19:27 -0500 1993
Date: Sat, 23 Oct 1993 23:19:27 -0500
From: yjc@po.cwru.edu (Jerome Chan)
Reply-To: LitProg@SHSU.edu, yjc@PO.CWRU.EDU
To: LitProg@SHSU.EDU
Subject: CWeb for the Macintosh
 
Where can I find any of these? I've looked into the FAQ list and I don't
see it. :(
 
-- 
 The Evil Tofu (Only Human)
 
From dmason@uwaterloo.ca Sun Oct 24 04:29:12 GMT 1993
Date: Sun, 24 Oct 1993 04:29:12 GMT
From: dmason@uwaterloo.ca (Dave Mason)
Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA
To: LitProg@SHSU.EDU
Subject: Luminary abuse (was Re: Inline comments and abstraction)
 
In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes:
   > [``chunk''] is perhaps
   > the kind of word (like 'memory' and 'flavor') bound to meet with the
   > disapproval of Edsger Dijkstra
 
   What stronger endorsement could anyone ask for?
 
Wow, one week Preston says that Knuth doesn't write readable webs, and
the next week Norman implies that any putative anti-endorsement by
Dijkstra is good enough for him!  What can we say bad about Tony
Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
:-)  (apologies to any luminaries I forgot to nominate for abuse :-)
 
I'm no-one to talk, but I tend to agree with Preston. (Knuth is
brilliant, but I believe TeX-the-Program and Metafont-the-Program are
significant dis-incentives to the spread of literate programming.
Virtually anyone I've tried to interest in literate programming who
has seen TtP uses it as a counter to my arguments.  This may be an
argument that TtP is outside the domain of program sizes for which web
works well -- maybe hypertext web would be better.  I'm not sure the
programs Knuth wrote for Jon Bentley's column are completely
convincing either -- I think they are perhaps too clever and
didactic.)
 
While Dijkstra has many extreme ideas, I think anybody dismisses him
at their intellectual peril.  My experience is that ideas like
literate programming mesh very well with Dijkstra's ideas on program
development. (I'm not implying that Norman was dismissing him.)
 
In general I think ritual luminary abuse is probably not very
constructive.
 
../Dave
 
From dmason@uwaterloo.ca Sun Oct 24 04:29:12 GMT 1993
Date: Sun, 24 Oct 1993 04:29:12 GMT
From: dmason@uwaterloo.ca (Dave Mason)
Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA
To: LitProg@SHSU.EDU
Subject: Luminary abuse (was Re: Inline comments and abstraction)
 
In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes:
   > [``chunk''] is perhaps
   > the kind of word (like 'memory' and 'flavor') bound to meet with the
   > disapproval of Edsger Dijkstra
 
   What stronger endorsement could anyone ask for?
 
Wow, one week Preston says that Knuth doesn't write readable webs, and
the next week Norman implies that any putative anti-endorsement by
Dijkstra is good enough for him!  What can we say bad about Tony
Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
:-)  (apologies to any luminaries I forgot to nominate for abuse :-)
 
I'm no-one to talk, but I tend to agree with Preston. (Knuth is
brilliant, but I believe TeX-the-Program and Metafont-the-Program are
significant dis-incentives to the spread of literate programming.
Virtually anyone I've tried to interest in literate programming who
has seen TtP uses it as a counter to my arguments.  This may be an
argument that TtP is outside the domain of program sizes for which web
works well -- maybe hypertext web would be better.  I'm not sure the
programs Knuth wrote for Jon Bentley's column are completely
convincing either -- I think they are perhaps too clever and
didactic.)
 
While Dijkstra has many extreme ideas, I think anybody dismisses him
at their intellectual peril.  My experience is that ideas like
literate programming mesh very well with Dijkstra's ideas on program
development. (I'm not implying that Norman was dismissing him.)
 
In general I think ritual luminary abuse is probably not very
constructive.
 
../Dave
 
From dmason@uwaterloo.ca Sun Oct 24 04:29:12 GMT 1993
Date: Sun, 24 Oct 1993 04:29:12 GMT
From: dmason@uwaterloo.ca (Dave Mason)
Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA
To: LitProg@SHSU.EDU
Subject: Luminary abuse (was Re: Inline comments and abstraction)
 
In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes:
   > [``chunk''] is perhaps
   > the kind of word (like 'memory' and 'flavor') bound to meet with the
   > disapproval of Edsger Dijkstra
 
   What stronger endorsement could anyone ask for?
 
Wow, one week Preston says that Knuth doesn't write readable webs, and
the next week Norman implies that any putative anti-endorsement by
Dijkstra is good enough for him!  What can we say bad about Tony
Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
:-)  (apologies to any luminaries I forgot to nominate for abuse :-)
 
I'm no-one to talk, but I tend to agree with Preston. (Knuth is
brilliant, but I believe TeX-the-Program and Metafont-the-Program are
significant dis-incentives to the spread of literate programming.
Virtually anyone I've tried to interest in literate programming who
has seen TtP uses it as a counter to my arguments.  This may be an
argument that TtP is outside the domain of program sizes for which web
works well -- maybe hypertext web would be better.  I'm not sure the
programs Knuth wrote for Jon Bentley's column are completely
convincing either -- I think they are perhaps too clever and
didactic.)
 
While Dijkstra has many extreme ideas, I think anybody dismisses him
at their intellectual peril.  My experience is that ideas like
literate programming mesh very well with Dijkstra's ideas on program
development. (I'm not implying that Norman was dismissing him.)
 
In general I think ritual luminary abuse is probably not very
constructive.
 
../Dave
 
From neeri@iis.ee.ethz.ch Sun Oct 24 12:10:15 GMT 1993
Date: Sun, 24 Oct 1993 12:10:15 GMT
From: neeri@iis.ee.ethz.ch (Matthias Neeracher)
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.EDU
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
dmason@uwaterloo.ca (Dave Mason) writes:
>In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes:
>   > [``chunk''] is perhaps
>   > the kind of word (like 'memory' and 'flavor') bound to meet with the
>   > disapproval of Edsger Dijkstra
 
>   What stronger endorsement could anyone ask for?
 
>Wow, one week Preston says that Knuth doesn't write readable webs, and
>the next week Norman implies that any putative anti-endorsement by
>Dijkstra is good enough for him!  What can we say bad about Tony
>Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
 
This is a little off-topic, but how about Alan Perlis et al. abusing 
Tony Hoare?
 
 "C.A.R. Hoare has been quoted as saying,
 
    ``In many applications, algorithm plays almost no role and
      certainly presents almost no problems.''
 
  (We wish we could report that he thereupon threw up his hands and
   abandoned verification, but no such luck.)"
          -- DeMillo, Lipton, and Perlis,
             _Social Processes and Proofs of Theorems and Programs_
 
>I'm no-one to talk, but I tend to agree with Preston. (Knuth is
>brilliant, but I believe TeX-the-Program and Metafont-the-Program are
>significant dis-incentives to the spread of literate programming.
 
I disagree. While they IMHO might profit from some more global documentation
(maybe a diagram of where the various parts fit in), I still believe that
they are excellent examples of literate programming.
 
>While Dijkstra has many extreme ideas, I think anybody dismisses him
>at their intellectual peril.
 
My problem with Dijkstra is that he pontificates about topics that he 
appears to have less and less experience with. Does anybody here happen
to know when Dijkstra last wrote *himself* a program of any substantial 
size? I would assume that he has not done so for at least 15 years.
 
Dijkstra is bound to generate resentment with people actually working 
with computers when he declares that advanced debuggers are unnecessary
and harmful, and some system designers actually take him seriously, or
when he declares that he does not have time to use word processors and
writes everything with a fountain pen (As he did in a CACM article; I 
don't remember him having made any mention of his Secretary in that
article).
 
>  My experience is that ideas like
>literate programming mesh very well with Dijkstra's ideas on program
>development. 
 
This is probably true, as literate programming is very well suited to
stepwise refinement and having comments typeset is very advantageous
if you want to do formal reasoning on the program.
 
>In general I think ritual luminary abuse is probably not very
>constructive.
 
I'm not so sure of that. Dijkstra himself seems to have built a 
considerable part of his reputation on polemics (I mean, who would
remember him without "goto statement considered harmful") and has 
never stopped short of abusing his colleagues (Dijkstras "Selected
Writings on Computing: A Personal Perspective" contains a few remarks
so nasty that the names of the targets had to be removed out of legal
concerns).
 
Matthias
 
-----
Matthias Neeracher                                   neeri@iis.ethz.ch
        "I came to the conclusion that sex is a sublimation
         of the work instinct" -- David Lodge, _Small World_
 
From neeri@iis.ee.ethz.ch Sun Oct 24 12:10:15 GMT 1993
Date: Sun, 24 Oct 1993 12:10:15 GMT
From: neeri@iis.ee.ethz.ch (Matthias Neeracher)
Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH
To: LitProg@SHSU.EDU
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
dmason@uwaterloo.ca (Dave Mason) writes:
>In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes:
>   > [``chunk''] is perhaps
>   > the kind of word (like 'memory' and 'flavor') bound to meet with the
>   > disapproval of Edsger Dijkstra
 
>   What stronger endorsement could anyone ask for?
 
>Wow, one week Preston says that Knuth doesn't write readable webs, and
>the next week Norman implies that any putative anti-endorsement by
>Dijkstra is good enough for him!  What can we say bad about Tony
>Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
 
This is a little off-topic, but how about Alan Perlis et al. abusing 
Tony Hoare?
 
 "C.A.R. Hoare has been quoted as saying,
 
    ``In many applications, algorithm plays almost no role and
      certainly presents almost no problems.''
 
  (We wish we could report that he thereupon threw up his hands and
   abandoned verification, but no such luck.)"
          -- DeMillo, Lipton, and Perlis,
             _Social Processes and Proofs of Theorems and Programs_
 
>I'm no-one to talk, but I tend to agree with Preston. (Knuth is
>brilliant, but I believe TeX-the-Program and Metafont-the-Program are
>significant dis-incentives to the spread of literate programming.
 
I disagree. While they IMHO might profit from some more global documentation
(maybe a diagram of where the various parts fit in), I still believe that
they are excellent examples of literate programming.
 
>While Dijkstra has many extreme ideas, I think anybody dismisses him
>at their intellectual peril.
 
My problem with Dijkstra is that he pontificates about topics that he 
appears to have less and less experience with. Does anybody here happen
to know when Dijkstra last wrote *himself* a program of any substantial 
size? I would assume that he has not done so for at least 15 years.
 
Dijkstra is bound to generate resentment with people actually working 
with computers when he declares that advanced debuggers are unnecessary
and harmful, and some system designers actually take him seriously, or
when he declares that he does not have time to use word processors and
writes everything with a fountain pen (As he did in a CACM article; I 
don't remember him having made any mention of his Secretary in that
article).
 
>  My experience is that ideas like
>literate programming mesh very well with Dijkstra's ideas on program
>development. 
 
This is probably true, as literate programming is very well suited to
stepwise refinement and having comments typeset is very advantageous
if you want to do formal reasoning on the program.
 
>In general I think ritual luminary abuse is probably not very
>constructive.
 
I'm not so sure of that. Dijkstra himself seems to have built a 
considerable part of his reputation on polemics (I mean, who would
remember him without "goto statement considered harmful") and has 
never stopped short of abusing his colleagues (Dijkstras "Selected
Writings on Computing: A Personal Perspective" contains a few remarks
so nasty that the names of the targets had to be removed out of legal
concerns).
 
Matthias
 
-----
Matthias Neeracher                                   neeri@iis.ethz.ch
        "I came to the conclusion that sex is a sublimation
         of the work instinct" -- David Lodge, _Small World_
 
From ras@salomon.Princeton.EDU Mon Oct 25 01:19:10 GMT 1993
Date: Mon, 25 Oct 1993 01:19:10 GMT
From: ras@salomon.Princeton.EDU (Robert Shillingsburg)
Reply-To: LitProg@SHSU.edu, ras@SALOMON.PRINCETON.EDU
To: LitProg@SHSU.EDU
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
marcus@x4u2.desy.de (Marcus Speh) writes:
 
>I have a little problem with nuweb. Since I am working in GNU Emacs,
>I'd like to use the outline mode [which all users of web-mode will
>appreciate]. Thus, I usually insert a line like
 
>% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*-
...
>etc. Now, nuweb refuses to follow and aborts with
 
>	nuweb: bad @ sequence (file.nu, line 1)
 
The problem, of course, is that nuweb trips over the @ sign in the
mode-specifier line.  In many cases, you can replace the @ with @@,
but in this case, the @ sign is needed by a processor (emacs) which
looks at the text before nuweb can change the @@ to a single @.
 
>  I would wish nuweb would switch from error to warning too. Anybody
>ever ran into this problem? Is there a simple solution?
 
I think a better solution is to use a nuweb comment character (like
Preston's proposed @%).  Then your mode line will look like:
 
@% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*-
 
and nuweb will never see the single @ sign.
 
Now, if we can only convince Preston to implement @%.... :-)  Or just
hack it up yourself.
 
-Rob
 
-- 
***********************************************************************  (___)
* Rob Shillingsburg             Princeton University Computer Science *  |===|
* ras@cs.princeton.edu          This is a *UNIX* system! I know this! *   \_/
*********************************************************************** RoboCow
 
From Steve Mon Oct 25 11:27:09 +1000 1993
Date: Mon, 25 Oct 1993 11:27:09 +1000
From: Steve Avery <stevea@vast.unsw.edu.au>
Reply-To: LitProg@SHSU.edu, stevea@VAST.UNSW.EDU.AU
To: LitProg@SHSU.edu, dmason@uwaterloo.ca
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
Dave Mason <dmason@uwaterloo.ca> sez:
 
> Knuth is brilliant, but I believe TeX-the-Program and
> Metafont-the-Program are significant dis-incentives to the spread of
> literate programming. 
 
	Sure, but you must admit that the original Web for Pascal was a
bit primitive (as probably was the version of Pascal that was used). In
all fairness, I think it would be wise to wait for Knuth's next book
(the precursor to Volume 4) which apparently has literate programs in
it, hopefully using CWEB.
 
	cheers
	-steve
 
	p.s. And you can't cite CWEB as an example of Knuth's poor
programming, as most of it isn't his (and I don't think its that bad an
example of programming either).
 
From kasper@iesd.auc.dk Mon Oct 25 11:27:09 +1000 1993
Date: Mon, 25 Oct 1993 11:27:09 +1000
From: kasper@iesd.auc.dk (Kasper OEsterbye)
Reply-To: LitProg@SHSU.edu, kasper@IESD.AUC.DK
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In this wonderful line of chunks and scraps, I would as a native speaker
(of Danish) and a naive speaker (of english) just throw in that
I use the word "fragment". I kind of like it because it is exactly what
it should be in danish, and seems to work just fine in foreign too.
Also it sounds more formal and better suited for papers.
 
-- Kasper
 
--
Kasper Osterbye                        Internet: kasper@iesd.auc.dk
Aalborg University                     FAX: +45 98 15 81 29
Fredrik Bajers vej 7E, 9220 Aalborg    Phone:  (W) +45 98 15 85 22
DENMARK.                                       (H) +45 98 11 09 25
 
From mpharr@lecter.us.oracle.com Mon Oct 25 02:07:16 GMT 1993
Date: Mon, 25 Oct 1993 02:07:16 GMT
From: mpharr@lecter.us.oracle.com (Matt Pharr)
Reply-To: LitProg@SHSU.edu, mpharr@us.oracle.com
To: LitProg@SHSU.EDU
Subject: CWEB support for hilit19.el?
 
Has anyone figured out a nice set of regexps for CWEB code for Jonathan
Stigelman's hilit19.package for GNU Emacs? I've tried to put something
together, failed miserably, and wanted to see if someone else has tackled
this.
 
(Hilit19 is distributed with Emacs 19 and automatically hilights text in
buffers--e.g. for C code, comments are in red text, strings are green,
keywords are blue, etc... All this is highly customizable.)
 
-Matt
--
Matt Pharr   (mpharr@us.oracle.com)    | "It's funny how the colors of the real
Technical Staff                        |  world only seem real when you see
Sun Products Group                     |  them on the screen"
Oracle Corporation                     |     -- A Clockwork Orange
 
From norman@bellcore.com Sun Oct 24 22:55:57 -0400 1993
Date: Sun, 24 Oct 93 22:55:57 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, dmason@UWATERLOO.CA
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
> Wow, one week Preston says that Knuth doesn't write readable webs, and
> the next week Norman implies that any putative anti-endorsement by
> Dijkstra is good enough for him!
 
Actually I have the greatest respect for Dijkstra's work on program
correctness and the calculus of guarded commands.  I also, however, have
the greatest amusement for his handwriting fetish and other eccentricities.
Doubtless I will never make a formalist.
 
> What can we say bad about Tony
> Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
> :-)  (apologies to any luminaries I forgot to nominate for abuse :-)
 
Now wait a minute!  Tony Hoare is my hero.
 
> I'm no-one to talk, but I tend to agree with Preston. 
 
Me too (all kidding aside).  The details of character translation are
much less interesting than the line-breaking and other algorithms.
 
> I'm not sure the
> programs Knuth wrote for Jon Bentley's column are completely
> convincing either -- I think they are perhaps too clever and
> didactic.)
 
I find them completely convincing for what they are --- I think
MacIlroy used the phrase ``industrial-strength Faberg\'e egg.''
Impressive and repays careful study.  I am eagerly looking forward to
the upcoming book.
 
> While Dijkstra has many extreme ideas, I think anybody dismisses him
> at their intellectual peril.  My experience is that ideas like
> literate programming mesh very well with Dijkstra's ideas on program
> development. (I'm not implying that Norman was dismissing him.)
 
The disappointing thing about those ideas is that 
  a) they haven't been advanced, changed, or enriched in 15 years
  b) they are tremendously difficult to apply beyond toy examples
In my travels I have met one programmer who uses Dijkstra's methods to
write serious software---and this is a guy who is brilliant and has
made original contributions to program correctness as well as other
areas.  This is not to say Dijkstra's methods are useless to mere
mortals---I use them every time I write a loop---but to say that they
have never delivered on their grand promises.
 
> In general I think ritual luminary abuse is probably not very
> constructive.
 
But I'm having such fun!  OK, so we're far afield from literate
programming.  I promise to keep my lip buttoned from here on.
 
Norman
 
From ddw2@sunbim.be Mon Oct 25 09:42:31 +0100 1993
Date: Mon, 25 Oct 93 09:42:31 +0100
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
Subject: nuweb doesnt like Emacs outline-regexp
 
   Marcus> % -*- Mode: outline; outline-regexp: "[@]"; eval:
   Marcus> (hide-body); -*-
 
The problem is that 'standard' nuweb has no comments of itself. This
why I proposed to Preston to include @% as commenting sequence,
eating up to the next newline. This is supported by some patches I
have for nuweb 0.8 (I have to rebuild them for the current nuweb).
 
   Marcus>   I would wish nuweb would switch from error to warning
   Marcus> too. Anybody ever ran into this problem? Is there a simple
   Marcus> solution?
 
I will be able toi have some time to merge the patches in the current
nuweb and am willing to post or the diffs with nuweb 0.87.
 
By the way, you might be interested to look for nuweb.el which work
above AucTeX, and mainly (so far) supports editing scraps in their
own buffer in another mode.
I am currently rewriting this mode in order to also provide navigation
across defs and uses of scrap names. This new version will also be
able to work without AucTeX.
 
Regards,
 
Dominique
 
Dominique de Waleffe             ddw@sunbim.be
BIM sa
Chaussee de Louvain, 510	 Tel: +32 2 719 26 14
B-1930 Zaventem			 Fax: +32 2 725 47 83
Belgium
 
From Kevin Mon Oct 25 09:39:37 GMT 1993
Date: Mon, 25 Oct 1993 09:39:37 GMT
From: Kevin Mitchell <kevin@dcs.ed.ac.uk>
Reply-To: LitProg@SHSU.edu, kevin@DCS.ED.AC.UK
To: LitProg@SHSU.EDU
Subject: Re: CWeb for the Macintosh
 
Subject: CWeb for the Macintosh
From: Jerome Chan, yjc@po.cwru.edu
Date: Sat, 23 Oct 1993 23:19:27 -0500
In article <yjc-231093231927@b61539.student.cwru.edu> Jerome Chan,
yjc@po.cwru.edu writes:
>Where can I find any of these? I've looked into the FAQ list and I don't
>see it. :(
 
I've been playing around with a port of cweb for the Mac for a few months
now and it seems fairly stable.  Once I was convinced of this fact I was
going to send the mods to Silvio Levy for inclusion in the cweb
distribution.  However, if anyone wants to try the port before this
happens then they can find the applications in pub/kevin on
ftp.dcs.ed.ac.uk  Please let me know of any problems you encounter.
 
Here's what I did to get it working on the Mac.  First, I needed to
allocate a lot of the large arrays dynamically to get around the 32K
limit on static arrays.  I also had to split common.c into two files,
this time to get around the 32K limit on code segment sizes.  The
interface is a drag and drop one, i.e. you drag the web file over the
tangle or weave application (or an alias), and it runs the application on
the file.  If you select two files (i.e. using shift-click) then it
assumes one of them is a change file and uses the file extension to
distinguish between them.  Errors are written to a log file and you get a
pop-up alert if the log file contains any errors at the end of the run. 
The file types for the .tex and .[ch] files are currently set so that the
created files 'belong' to Textures and THINK C respectively.  I've
created icons for the tangle and weave applications, but I'm no artist
and so these are pretty primitive.    The main extensions I'd like to do
are 1) to avoid overwriting a code file if it hasn't changed (although
I'll probably wait a bit to see if this implemented in a later release of
cweb) and 2) to try and integrate ctangle into Think C 6.0 as a
translator so that it gets  called automatically. 
 
Enjoy, 
 
Kevin.
 
From Eric Mon Oct 25 12:41 +0000 1993
Date: Mon, 25 Oct 1993 12:41 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: Inline comments and abstraction
 
I'm surprised that this discussion about 'chunks' has not referred to
serious research that has been done already. For instance Soloway [1,2] finds
that programmers tend to think in 'plans' and it looks like these plans
are closely related to the refinements we want to document in our literate
programs
 
Eric
 
1.  Soloway E., Learning to Program= Learning to Construct Mechanisms and 
    Explanations, CACM 29, 9, 850-858 (1986)
2.  Soloway E., Designing Documentaion to Compensate for Delocalized Plans,
    CACM 31, 11, 1259-1267 (1988)
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From schrod@iti.informatik.th-darmstadt.de Mon Oct 25 12:41 +0000 1993
Date: Mon, 25 Oct 1993 12:41 +0000 (GMT)
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
In article <neeri.751464615@yggdrasil>, neeri@iis.ee.ethz.ch (Matthias Neeracher) writes:
 
> Dijkstra himself seems to have built a 
> considerable part of his reputation on polemics (I mean, who would
> remember him without "goto statement considered harmful") 
 
At least, I would. For his work on structured programming, his work
on multi-processing, his work on compiler construction, on the formal
definition of programming languages, on the essence of control
structures, on non-determinism, and, and, and.
 
In addition, I can't find polemics in his CACM letter. It was a well
reasoned statement about the consequences of the (ab)use of certain
control structures. Go ahead and read it again! The discussion
afterwards was heated and filled with polemics, but not the letter.
 
Yes, he's a very arrogant person and he seems not to be in touch with
reality often enough -- but he's brilliant, too.
 
Concerning Literate Programming and Dijkstra: Knuth himself
acknowledges the influence of the paradigms of Dijkstra on his ideas
of programming style.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From schrod@iti.informatik.th-darmstadt.de Mon Oct 25 12:41 +0000 1993
Date: Mon, 25 Oct 1993 12:41 +0000 (GMT)
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: CWeb for the Macintosh
 
In article <yjc-231093231927@b61539.student.cwru.edu>, yjc@po.cwru.edu (Jerome Chan) writes:
> Where can I find any of these? I've looked into the FAQ list and I don't
> see it. :(
 
An update will be in the next FAQ issue.
 
Timothy Murphy did a port of CTANGLE which is available from the
Literate Programming Archive:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/machines/mac/cweb
 
I don't know of a port of CWEAVE.
 
--
Joachim
[THD Literate Programming Archive, maintainer]
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From c21vc@kocrsv01.delcoelect.com Mon Oct 25 15:30:24 GMT 1993
Date: Mon, 25 Oct 1993 15:30:24 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: Some general thoughts on literate programming
 
In my nineteen years of working as a programmer (a field that I have
considered leaving a couple of times because it is not satisfying
enough), literate programming is one of the most exciting developments 
that I have come across. (The only other that even comes close, 
subjectively speaking of course, is Smalltalk.) I wouldn't have known 
about it if it weren't for the present newsgroup.
 
Some general thoughts. I had a chance to look at Norman Ramsey's paper
(Software-Practice and Experience Vol.21(7),677-683) this weekend. He
points out that 'The right model for a literate program is ... not the
novel but the car repair manual.' In fact, terms like 'literate',
'publishable', 'books', etc. may cause companies (like ours) to 'run
away' from these techniques (in the belief that these are for
academia, and other types of companies). Yet, companies like
ours can benefit a lot from these techniques. The advantage of these
techniques (as I see it in my present state of understanding) is that
programs written this way make it possible for a maintenance
programmer to take effective action even when his level of familiarity
is not high; car repair manual is a good analogy. For me, some of the
best written manuals are the manuals that come with HP Laser Jet
printers. Their purpose is to enable someone to act effectively (to
solve a problem or achieve an intended result for instance, to change
the toner cartridge) without going through a lot of 
preparation/reading/training. The manual makes up for the lack of 
preparation/reading/training. Techniques for communicating effectively 
in this way are available and it makes a lot of sense to make use of 
these in programming. 'literate' and the like have purposes such as 
'amusing the reader', produce specific emotional effects,etc. These 
will be frowned upon as being inappropriate for serious business 
endeavors. Though, judicious use of these do make the process of using 
a manual/program quite entertaining and should indeed be welcomed. 
(The allusion to 'what a tangled web we weave' dawned on me this weekend. 
I also like the 'copyleft' policy of some GNU utilities.) As for emotional 
effects, having to make changes to a very badly written program, of 
course, has moved many to tears.
 
A final thought. B.F.Skinner has a theory of language (stated in
Verbal Behavior, 1957). Programming behavior (including that done in
a conventional language like English - which is documentation - and
that done in a programming language which is of course code) can be 
profitably analyzed using Skinner's theories; I think that this a rich 
territory waiting to me mined. (I am aware that many people think of 
this approach as a 'dead' one - Chomsky etc. After about nineteen
years of involvment in this as a hobby, I don't think so). For instance, 
some project/software methodologies actually make a programmer's job a 
lot harder/unsatisfactory; behavior analytic explanations shed good light 
on why this is so. 
 
Also, the following may be of some interest to readers of present
newsgroup: Skinner has a short paper that helps one enjoy the writing
process more and produce better results. (I didn't use it in writing
the present posting. I didn't want to go to the extra trouble it
takes. I use it usually when I am struggling with a particular piece
of writing.) If anyone is interested, please contact me; I
will provide the reference.
 
I also appreciate very much this opportunity to exchange ideas with 
(what I think are) kindred souls. For the record, I also want to say
(1) English is a non-native language to me (though I have writing
aspirations) (2) apologies to those who feel that this is wasteful of
their resources (limited e-mail allowance). 
 
Shaker
 
From mfy@sli.com Mon Oct 25 16:00:12 GMT 1993
Date: Mon, 25 Oct 1993 16:00:12 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.EDU
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
Matthias neeracher wrote:
 
>I'm not so sure of that. Dijkstra himself seems to have built a 
>considerable part of his reputation on polemics (I mean, who would
>remember him without "goto statement considered harmful") and has 
 
A fact which may be relevant in this context: Dijkstra did not choose this
title; it was placed over what had been simply a letter to the editor, as it
were, by the publisher.  I have read the letter and don't remember its contents
as being particularly polemical; perhaps that is because I have seen the claims
about the potential harm of gotos borne out both in professional and in
academic contexts.  Others may disagree, but in my judgment saying that X is
harmful isn't polemical when X is, in fact, harmful; nor is it usually
polemical even when X isn't harmful.  The speaker may, after all, be mistaken.
 
	Michael F. Yoder [mfy@sli.com]
 
From mfy@sli.com Mon Oct 25 16:02:32 GMT 1993
Date: Mon, 25 Oct 1993 16:02:32 GMT
From: mfy@sli.com (Mike Yoder)
Reply-To: LitProg@SHSU.edu, mfy@SLI.COM
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
Let me, as one whose native language is English, loudly endorse Kasper
OEsterbyte's use of "fragment."  It has the correct meaning in plain,
non-technical English, and doesn't collide with existing jargon.
 
	Michael F. Yoder [mfy@sli.com]
 
From Lee Mon Oct 25 12:32:34 EDT 1993
Date: Mon, 25 Oct 93 12:32:34 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, dmason@uwaterloo.ca
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
Dave Mason writes:
 
> Wow, one week Preston says that Knuth doesn't write readable webs, and
> the next week Norman implies that any putative anti-endorsement by
> Dijkstra is good enough for him!  What can we say bad about Tony
> Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week?
> :-)  (apologies to any luminaries I forgot to nominate for abuse :-)
 
I have to admit that I thought about making the same kind of crack
about Dijkstra, myself;  I'm glad Norman beat me to it :-).  Seriously
though, Dijkstra does tend to take extreme positions.  I like to
believe that he does it primarily to start discussion, rather than
because he actualy advocates the extremes, but I tend to think the
best of people :-).
 
> I'm no-one to talk, but I tend to agree with Preston. (Knuth is
> brilliant, but I believe TeX-the-Program and Metafont-the-Program are
> significant dis-incentives to the spread of literate programming.
> Virtually anyone I've tried to interest in literate programming who
> has seen TtP uses it as a counter to my arguments.  This may be an
> argument that TtP is outside the domain of program sizes for which web
> works well -- maybe hypertext web would be better.  I'm not sure the
> programs Knuth wrote for Jon Bentley's column are completely
> convincing either -- I think they are perhaps too clever and
> didactic.)
 
I agree with Preston and Dave on this one, but let us not forget that
TeX the Program was Knuth's ~first~ literate program.  Remember your
own early attempts at LP, and look at how far you've come since then.
I'm sure that if Knuth were to write TeX now, the exposition and
layout would be totally different.  Of course, Knuth does have a
Turing-like streak that occasionally substitutes cleverness for
clarity, but perhaps that is one of the marks of greatness.
 
> In general I think ritual luminary abuse is probably not very
> constructive.
 
Agreed, but it is fun.
 
		-- Lee
		   leew@pilot.njin.net
 
``Laugh at the kings, or they'll make you cry.''
		-- Stephen Sondheim, "Anyone Can Whistle"
 
From Lee Mon Oct 25 12:38:04 EDT 1993
Date: Mon, 25 Oct 93 12:38:04 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, kasper@iesd.auc.dk
Subject: Re: Inline comments and abstraction
 
Kasper Osterbye suggests:
 
> In this wonderful line of chunks and scraps, I would as a native speaker
> (of Danish) and a naive speaker (of english) just throw in that
> I use the word "fragment". I kind of like it because it is exactly what
> it should be in danish, and seems to work just fine in foreign too.
> Also it sounds more formal and better suited for papers.
 
`Fragment' is certainly acceptable, but I think the final sentence
above is an argument ~against~ it.  Part of the problem with formal
papers is that they use too many 2-bit words.  As I keep telling my
students:  ``People who use long words either don't know what they're
talking about, or don't want you to know what they're talking about.''
 
My vote still goes to `chunk,'  the only one-syllable contender.
 
		-- Lee
		   leew@pilot.njin.net
 
From rfrankel@us.oracle.com Mon Oct 25 19:39:16 GMT 1993
Date: Mon, 25 Oct 1993 19:39:16 GMT
From: rfrankel@us.oracle.com (Rick Frankel)
Reply-To: LitProg@SHSU.edu, rfrankel@US.ORACLE.COM
To: LitProg@SHSU.EDU
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
Rob write:
   marcus@x4u2.desy.de (Marcus Speh) writes:
 
   >I have a little problem with nuweb. Since I am working in GNU Emacs,
   >I'd like to use the outline mode [which all users of web-mode will
   >appreciate]. Thus, I usually insert a line like
 
   >% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*-
   ...
   >etc. Now, nuweb refuses to follow and aborts with
 
   >	nuweb: bad @ sequence (file.nu, line 1)
 
   The problem, of course, is that nuweb trips over the @ sign in the
   mode-specifier line.  In many cases, you can replace the @ with @@,
   but in this case, the @ sign is needed by a processor (emacs) which
   looks at the text before nuweb can change the @@ to a single @.
 
How about adding '(("\\.nu" . web-outline-mode)) to auto-mode-alist
and then:
	(defun web-outline-mode ()
		(web-mode)
		(outline-minor-mode) ;; emacs-19 minor mode. MUCH preferred
		(make-local-variable outline-regexp)
		(setq outline-regexp "[@]")
		(hide-body))
 
This should automatically do the right thing(TM) any time you edit a
.nu file.
 
just a thought...
rick
 
--
rfrankel@us.oracle.com
richard.frankel@amail.amdahl.com
 
From koopman@sgi84.ctc.com Mon Oct 25 17:21:55 -0400 1993
Date: Mon, 25 Oct 93 17:21:55 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, mfy@SLI.COM
Subject: Fragment Grenadier
 
Mike Yoder wrote:
 
>Let me, as one whose native language is English, loudly endorse Kasper
>OEsterbyte's use of "fragment."  It has the correct meaning in plain,
>non-technical English, and doesn't collide with existing jargon.
 
There is technical jargon which uses the word `fragment'.  Aside from
sentence fragment.  The word `fragment' is used to describe the pieces
scattered about after a shell or other item is fractured, such as by
an explosive charge.  The weaving and tangling does ``anti-fracture''
the bits of text and code scattered about the web.  I still like the
taste of `chunklet' better than `fragment,' however.
 
Michael Koopman (mike)    Associate Computer Systems Specialist
Concurrent Technologies Corporation     e-mail: koopman@ctc.com
1450 Scalp Avenue                        phone: +1-814-269-2637
Johnstown, PA  15904-3321  USA         telefax: +1-814-269-2666
 
From norman@bellcore.com Mon Oct 25 17:31:20 -0400 1993
Date: Mon, 25 Oct 93 17:31:20 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu
Subject: Results of SURVEY ON PRETTYPRINTING
 
Thanks to the 17 respondents to my survey.  Here are the results.
 
Recall the scale:
 
>   -2 not useful
>   -1 seldom useful
>    0 often useful
>   +1 useful; can get along without, but only painfully
>   +2 indispensible
>   NA I never heard of this, have no opinion
 
In addition, I asked what people preferred among several alternatives.
Some people gave preferences; others preferred to rate the alternatives.
 
prettyprinting (PP)          rated -0.3 +/- 0.3 (17 ratings)
table of contents (TOC)      rated +1.4 +/- 0.2 (17 ratings)
identifier cross-ref (IX)    rated +0.6 +/- 0.2 (16 ratings), 1 NA
  automatically (AUTOIX)     rated +1.0 +/- 0.4 (4 ratings), preferred 8 times
  by the programmer (USERIX) rated -0.8 +/- 0.5 (4 ratings), preferred 1 time
  semi-automatic (SEMIIX)    rated -0.7 +/- 0.3 (3 ratings), preferred 4 times,
                                                          OK 3 times, one ``?''
index of identifiers (II)    rated +1.3 +/- 0.2 (16 ratings)
  automatically (AUTOII)     rated +1.5 +/- 0.3 (4 ratings), preferred 8 times,
                           				 one ``?''
  by the programmer (USERII) rated -0.3 +/- 0.9 (4 ratings), preferred 1 time
  semi-automatic (SEMIII)    rated -0.7 +/- 0.3 (3 ratings), preferred 3 times,
                                                         OK 3 times, one ``?''
chunk cross-reference (CX)   rated +1.8 +/- 0.1 (17 ratings)
chunk index (CI)             rated +1.0 +/- 0.2 (17 ratings)
chunk numbers (CN)           rated +0.7 +/- 0.3 (14 ratings), preferred 1 time
numbers for cross-reference
  page numbers (PAGENO)      rated +0.5 +/- 0.3 (6 ratings), preferred 2 times
  consecutive (CONSEC)       rated +0.4 +/- 0.5 (5 ratings), preferred 3 times
  `1, 2a, 2b, &c' (SUBPAGE)  rated +1.3 +/- 0.3 (4 ratings), preferred 8 times
 
Two respondents mentioned that they wanted fully automatic indexing
but that the ability to supplement the index manually was important.
 
Here are the ratings in order of importance.  I've left out some I
took to be preferences.  As you can see, differences between nearby
features are not significant.  Prettyprinting comes out dead last and
has the largest margin of difference between it and its neighbors.
 
chunk cross-reference CX         rated +1.8 +/- 0.1 (17 ratings)
automatic indexing    AUTOII     rated +1.5 +/- 0.3 (4 ratings)
table of contents     TOC        rated +1.4 +/- 0.2 (17 ratings)
index of identifiers  II         rated +1.3 +/- 0.2 (16 ratings)
sub-page numbers      SUBPAGE    rated +1.3 +/- 0.3 (4 ratings)
chunk index           CI         rated +1.0 +/- 0.2 (17 ratings)
chunk numbers         CN         rated +0.7 +/- 0.3 (14 ratings)
identifier cross-ref  IX         rated +0.6 +/- 0.2 (16 ratings)
page numbers          PAGENO     rated +0.5 +/- 0.3 (6 ratings)
consecutive chunk nos CONSEC     rated +0.4 +/- 0.5 (5 ratings)
prettyprinting        PP         rated -0.3 +/- 0.3 (17 ratings)
 
Finally, here is the original survey and the coding of responses.
 
Please rate these features:
  prettyprinting
  table of contents
  identifier cross-reference (local, on-page info about local defns & uses)
    if useful, do you prefer that definitions and uses be identified
      -- completely automatically
      -- by the programmer
      -- programmer marks definitions, uses are identified automatically
  index of identifiers at end of document
    if useful, do you prefer that definitions and uses be identified
      -- completely automatically
      -- by the programmer
      -- programmer marks definitions, uses are identified automatically
  module/chunk cross-reference (automatically generated)
  module/chunk index (automatically generated)
  module/chunk numbers (are they important, or do page numbers suffice?)
  if you use cross-reference or index info, what numbers should be used?
    -- use page numbers
    -- use (consecutive) module/chunk numbers
    -- use module/chunk numbers, but number them by page of appearance
       (e.g. 1, 2a, 2b, 3, 4a, 4b, 4c) instead of consecutively.
 
Answers: (X means preferred, OK means not preferred but acceptable)
 
(Name of respondent deleted)
 PP=-1 TOC=+1 IX=+1 AUTOIX=+1 USERIX=-1 SEMIIX=0 II=+1 AUTOII=+1
 USERII=-1 SEMIII=0 CX=+1 CI=+1 CN=0 PAGENO=+1 CONSEC=0 SUBPAGE=+1
(Name of respondent deleted)
 PP=-1 TOC=+2 IX=0 SEMIIX=X II=+2 SEMIII=X CX=+2 CI=+1 CN=0 SUBPAGE=X
(Name of respondent deleted)
 PP=0 TOC=+2 IX=+2 AUTOIX=+2 USERIX=-2 SEMIIX=-1 II=+1 AUTOII=+2
 USERII=-2 SEMIII=-1 CX=+2 CI=0 CN=0 PAGENO=0 CONSEC=+1 SUBPAGE=+2
(Name of respondent deleted)
 PP=0 TOC=+2 IX=+2 AUTOIX=X SEMIIX=OK AUTOII=X SEMIII=OK CX=+2 CI=+2 
 SUBPAGE=X
(Name of respondent deleted)
 PP=-1 TOC=+1 IX=+2 AUTOIX=+1 USERIX=0 SEMIIX=-1 II=+2 AUTOII=+1
 USERII=0 SEMIII=-1 CX=+2 CI=+2 CN=0 PAGENO=0 CONSEC=0 SUBPAGE=+1
(Name of respondent deleted)
 PP=+2 TOC=+2 IX=+1 AUTOIX=0 USERIX=0 SEMIIX=?  II=+2 AUTOII=+2
 USERII=+2 SEMIII=?  CX=+2 CI=+2 CN=+2 PAGENO=+2 CONSEC=+2 SUBPAGE=X
 AUTOII=?
(Name of respondent deleted)
 PP=-2 TOC=0 IX=0 AUTOIX=X II=0 AUTOII=X CX=0 CI=0 PAGENO=0
(Name of respondent deleted)
 PP=-1 TOC=0 IX=0 AUTOIX=X II=+1 AUTOII=X CX=+1 CI=0 CN=X
 CONSEC=X SUBPAGE=X
(Name of respondent deleted)
 PP=+1 TOC=+1 IX=-1 AUTOIX=X II=+1 AUTOII=X CX=+2 CI=+1 CN=+2 CONSEC=X 
(Name of respondent deleted)
 PP=+1 TOC=+2 IX=0 AUTOIX=X SEMIIX=OK II=+1 AUTOII=X
 SEMIII=OK CX=+2 CI=+2 CN=+2 SUBPAGE=X
(Name of respondent deleted)
 PP=0 TOC=0 IX=+1 AUTOIX=X  II=+1 AUTOII=X CX=+2 CI=+1 CN=0 SUBPAGE=X
(Name of respondent deleted)
 PP=+1 TOC=0 IX=NA AUTOIX=X II=+2 AUTOII=X CX=+2 CI=0 CN=+2 CONSEC=X
(Name of respondent deleted)
 PP=+1 TOC=+2 IX=0 SEMIIX=X II=+2 SEMIII=X CX=+2 CI=+2 CN=-2
 PAGENO=X
(Name of respondent deleted)
 PP=-1 TOC=+2 IX=0 AUTOIX=X SEMIIX=OK II=+2 AUTOII=X SEMIII=OK CX=+2 CI=+2 
 CN=+1 SUBPAGE=X
(Name of respondent deleted)
 PP=-1 TOC=2 IX=0 USERIX=X II=2 USERII=X CX=2 CI=0 CN=0 PAGENO=X
(Name of respondent deleted)
 PP=-2 TOC=+2 IX=0 SEMIIX=X II=+2 SEMIII=X CX=+2 CI=+2 CN=+2 SUBPAGE=X
(Name of respondent deleted)
 PP=-1 TOC=+2 IX=+1 SEMIIX=X II=-1 CX=+2 CI=-1 CN=+1 PAGENO=0 CONSEC=-1
 SUBPAGE=+1
 
From sriram@glock.tcs.com Mon Oct 25 18:16:50 EST 1993
Date: Mon, 25 Oct 93 18:16:50 EST
From: sriram@glock.tcs.com (Sriram Srinivasah)
Reply-To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM
To: LitProg@SHSU.EDU
Subject: Literate programming in Framemaker.
 
I like the concept of LP (or what I understand of it). 
My understanding is -
	-  Source and documentation is all present in one document
	-  The same document can be compiled, either for execution by a machine,
	   or for publication.
	-  The tools that implement LP provide a framework to achieve the above, 
	   and macros to format the stuff effectively.
 
Unfortunately, all the examples that I have seen seem to use Tex as a base.
I use FrameMaker for all my documents, and using Tex is simply too much effort
devoted to formatting, IMHO.
 
In the current set of tools, one requires a lot of "inband signalling" . That is,
one has to have special symbols within the document that tag a certain paragraph
as a piece of code, or as a part of the body, etc. The resulting document looks
really messy, and it's painful to eyeball the document quickly.
 
I can achieve the same using FrameMaker or most other word processing tools, which
allow you to tag paragraph types. So, I can have a paragraph template called "Code",
that identifies the Code sections. Now, I can intermix graphics, tables, all kinds
of formatting like automatic line numbering, cross-referencing, indexes etc.
What I see on the screen is the final output, uncluttered by meta-information.
Separating the code from the chaff is very easy, once a Frame file is converted to 
a MIF file (an awk script is given below)
 
THE $(10^6) question:
	IS THIS IDEA WORTH EXPLORING FURTHER?
 
I'd dearly like your comments on this subject. I am absolutely new to LP, and
haven't read much beyond the FAQ, and some examples.
 
I would think this can be achieved in say, Word for windows etc. which can save
to an RTF format. 
 
For those with access to framemaker, this is what I propose:
 
1. Have a paragraph tag called 'Code', and write all your code in this format.
2. Save as a mif file (or use fmbatch).
3. Run this thru the following awk script
 
BEGIN	{
		code = 0
	}
 
/<PgfTag \`Code\'/ 	{
		code = 1
		next
	}
 
/<PgfTag/ {
		code = 0
		next
	}
 
(code == 1) && /^ *<String \`/{
		# Ignore all other paragraph formats, and get only strings from
		# Code formats.
 
		# Need to strip this, for example ..
		# <String `printf (\xd2 Hello World\\n\xd3);'>
 
		# Strip junk in front
		sub(/^[ ]*<String `/,"")
 
		# Trailing junk
		sub(/'>$/,"")
 
		# Convert smart quotes to standard quotes
		sub(/\\xd2/,"\"")
		sub(/\\xd3/,"\"")
 
		print
		next
	}
 
4. If you want pieces of code to go to different files, one can always have a 
special paragraph type ("File") that identifies a specific file type.
 
-Sriram Srinivasan
(sriram@tcs.com)
 
From Lewis Mon Oct 25 18:16:50 EST 1993
Date: Mon, 25 Oct 93 18:16:50 EST
From: "Lewis Perin" <perin@med.cornell.edu>
Reply-To: LitProg@SHSU.edu, perin@med.cornell.edu
To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
Subject: Re: Inline comments and abstraction
 
In Message Mon, 25 Oct 93 12:38:04 EDT,
  Lee Wittenberg <leew@pilot.njin.net> writes:
 
>My vote still goes to `chunk,'  the only one-syllable contender.
 
My heart still belongs to the saltier `scrap', equally monosyllabic and
properly evocative of a piece of paper that can be cut and pasted.  (Of
course, it also evokes the dog's dinner, but I happen to *like* that
association.)
______________________________________________________
      __          perin@cumc.cornell.edu (212)746-2946
 |   |_  \    / : Lew Perin
 |__ |__  \/\/  : Home: (201)435-2679
 
From Charles Mon Oct 25 19:15:16 -0700 1993
Date: Mon, 25 Oct 1993 19:15:16 -0700 (PDT)
From: Charles Bass <chuckb@u.washington.edu>
Reply-To: LitProg@SHSU.edu, chuckb@U.WASHINGTON.EDU
To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM
Subject: Re: Literate programming in Framemaker.
 
I think that your idea with framemaker is the only way to go.  I looked 
at a package called ~ winwordweb that was a set of macros for Word for 
Windows that did what you are doing in Frame.  In my opinion this is the 
nicest way to go because the front end is easy to use WSIWIG etc.  The 
downside is that it is difficult for others to modify your LP program 
unless the have Frame.  The tek based tools are (fairly) portable across 
unix and dos platforms.
 
At any rate I like your idea of  using Frame.
 
chuckb
 
From ae1181t@stnfor.ae.ge.com Tue Oct 26 07:52:08 -0400 1993
Date: Tue, 26 Oct 1993 07:52:08 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu, ras@SALOMON.PRINCETON.EDU
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
How about nuweb recognizing the TeX/LaTeX comment delimiter `%'? Then the users
do not have learn another command!
Osman
 
From johnson@cs.uiuc.edu Tue Oct 26 13:08:52 GMT 1993
Date: Tue, 26 Oct 1993 13:08:52 GMT
From: johnson@cs.uiuc.edu (Ralph Johnson)
Reply-To: LitProg@SHSU.edu, johnson@CS.UIUC.EDU
To: LitProg@SHSU.EDU
Subject: Re: Literate programming in Framemaker.
 
This is basically what the Literate Programmers Workbench from
apple.com does.  It is a fine idea.
 
-Ralph Johnson
 
From Thorbjoern Tue Oct 26 14:18:53 +0100 1993
Date: Tue, 26 Oct 1993 14:18:53 +0100 (MET)
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu, c21vc@kocrsv01.delcoelect.com
Subject: Re: Some general thoughts on literate programming
 
Venkataraman Chandrasekhar
 
| Also, the following may be of some interest to readers of present
| newsgroup: Skinner has a short paper that helps one enjoy the writing
| process more and produce better results. (I didn't use it in writing
| the present posting. I didn't want to go to the extra trouble it
| takes. I use it usually when I am struggling with a particular piece
| of writing.) If anyone is interested, please contact me; I
| will provide the reference.
 
I am about to write my first larger Lit programme, and I would
appreciate reading Skinners paper before starting.  I intend to do this
as right as I can.
 
I agree with your comment on the LaserJet documentation.  I installed a
LaserJet 4L yesteday for the first time, and it was a breeze thanks to
the excellent manual.  I will take heed of your comment regarding using
this as inspiration for my own work.
 
So if you would provide references for the Skinner paper, as well as a
ftp-location for Norman Ramseys paper I would appreciate it very much.
 
Thanks in advance
 
Regards,
-- 
Thorbjo/rn Andersen
ravn@imada.ou.dk
 
From norman@bellcore.com Tue Oct 26 10:15:17 -0400 1993
Date: Tue, 26 Oct 93 10:15:17 -0400
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM
Subject: Re: Literate programming in Framemaker.
 
snd@cs.princeton.edu has done some literate programming using FrameMaker.
You might want to ask him about his results.
 
Norman
 
From lynbech@daimi.aau.dk Tue Oct 26 14:19:36 GMT 1993
Date: Tue, 26 Oct 1993 14:19:36 GMT
From: lynbech@daimi.aau.dk (Christian Lynbech)
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.EDU
Subject: Literary nomenclature (was: Re: Inline comments and abstraction)
 
>Let me, as one whose native language is English, loudly endorse Kasper
>OEsterbyte's use of "fragment."  It has the correct meaning in plain,
>non-technical English, and doesn't collide with existing jargon.
 
In fact, the term is used (and probably in more instances than the following).
 
A locally developed OO programming language, the Beta language, uses a
`fragment system' as the main vehicle of tying program modules
together. An interesting fact is that this fragment system is roughly
as powerfull as the tangle part of (say) nuweb, i.e. you define named
fragments which are then inserted into `slots'. The system is, as I
understand it, derived from grammars (in some appropriate sense), with
slots corresponding to non-terminals.
 
Whether this counts against or for `fragment', is a good question.
 
I have untill this thread started used the term `scrap', which I got
from spider webs langauge defition files. The process of
prettyprinting the code is described as forming bigger scraps from
smaller scraps, and though this has nothing to do directly with
tangling, it corresponds nicely to my understanding of the tangling
process. And since I also find chunk overly informal, I will support
the scrap camp.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
				| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From jacojn@inet.uni-c.dk Tue Oct 26 14:19:36 GMT 1993
Date: Tue, 26 Oct 1993 14:19:36 GMT
From: jacojn@inet.uni-c.dk (Jacob Nielsen)
Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK
To: LitProg@SHSU.EDU
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
Rick (rfrankel@us.oracle.com) writes:
 [munch]
 
 How about adding '(("\\.nu" . web-outline-mode)) to auto-mode-alist
 and then:
	 (defun web-outline-mode ()
		 (web-mode)
		 (outline-minor-mode) ;; emacs-19 minor mode. MUCH preferred
		 (make-local-variable outline-regexp)
		 (setq outline-regexp "[@]")
		 (hide-body))
 
 This should automatically do the right thing(TM) any time you edit a
 ..nu file.
 
Well, it doesn't work with my Emacs but this does:
 
(defun nuweb-outline-mode ()
  (interactive) ; so I can call it via M-x
  (nuweb-mode) 
  (setq outline-regexp "@[dDoO]") ; search pattern
  (outline-minor-mode) ;; emacs-19 minor mode. MUCH preferred
  (hide-body))
 
Regards,
Jacob
--
Jacob Nielsen
Email: jacojn@inet.uni-c.dk (my private account)
   or  bc898574@sgi18.bbar.dth.dk (my account at the university)
 
From preston@cs.rice.edu Tue Oct 26 09:33:40 CDT 1993
Date: Tue, 26 Oct 93 09:33:40 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: nuweb doesnt like Emacs outline-regexp
 
I like the hacks to emacs as a way of Preston avoiding work.
However, I still plan to add a nuweb comment sequence, say @% meaning ignore
through the end-of-line.
 
I don't really like using % by itself.
Two reasons: got to be smart to avoid tripping over % in C code,
and I like the invariant that every nuweb command begins with an @ sign.
In other words, it's all latex until you see an @ character.
 
Preston
 
From Lee Tue Oct 26 10:41:54 EDT 1993
Date: Tue, 26 Oct 93 10:41:54 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, sriram@glock.tcs.com
Subject: Re: Literate programming in Framemaker.
 
Sriram Srinivasan writes:
 
> 
> I like the concept of LP (or what I understand of it). 
>		[ stuff omitted ]
> I use FrameMaker for all my documents, and using Tex is simply too much effort
> devoted to formatting, IMHO.
> 
> In the current set of tools, one requires a lot of "inband signalling" . That is,
> one has to have special symbols within the document that tag a certain paragraph
> as a piece of code, or as a part of the body, etc. The resulting document looks
> really messy, and it's painful to eyeball the document quickly.
> 
> I can achieve the same using FrameMaker or most other word processing tools, which
> allow you to tag paragraph types. So, I can have a paragraph template called "Code",
> that identifies the Code sections. Now, I can intermix graphics, tables, all kinds
> of formatting like automatic line numbering, cross-referencing, indexes etc.
> What I see on the screen is the final output, uncluttered by meta-information.
> Separating the code from the chaff is very easy, once a Frame file is converted to 
> a MIF file (an awk script is given below)
> 
> THE $(10^6) question:
> 	IS THIS IDEA WORTH EXPLORING FURTHER?
> 
> I'd dearly like your comments on this subject. I am absolutely new to LP, and
> haven't read much beyond the FAQ, and some examples.
> 
> I would think this can be achieved in say, Word for windows etc. which can save
> to an RTF format. 
 
Actually, what you propose is precisely the way WinWordWEB works,
except that it uses internal Word macros instead of saving an RTF
file.  The idea of a CODE style paragraph that tools can recognize
(and tangle and weave, as desired) seems to be the way to go.  I
recommend you forge on ahead.  A lot of people have expressed
interest in a Framemaker-based LP tool.
 
		-- Lee
		   leew@pilot.njin.net
 
From koopman@sgi84.ctc.com Tue Oct 26 12:29:26 -0400 1993
Date: Tue, 26 Oct 93 12:29:26 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
Subject: Some general thoughts on literate programming
 
Thorbjo/rn Andersen wrote regarding Venkataraman Chandrasekhar's article
 
>I agree with your comment on the LaserJet documentation.  I installed a
>LaserJet 4L yesteday for the first time, and it was a breeze thanks to
>the excellent manual.  I will take heed of your comment regarding using
>this as inspiration for my own work.
 
This document is a User's Manual, not a Technical Manual.  I am not
criticizing the document or denying it's value to the intended
audience.  However, I do not believe this document is a good template
for a literate program of significant depth.  Of course, diagrams and
directions for every contingency plausible owing to correct and
incorrect use, and use under failure conditions for a complex program
would be nice, but seems a daunting task.  Much discussion centers
around the methods for simplifying the complex program implementation
into `User Manual descriptions' with literate techniques.  I do not
feel such efforts are strictly ``academic'' or infeasible in the
``Real World' of ``Real Programmers.''
 
The diversity of the User's Manual and the Technical Manual seems
relevant to questions concerning literate techniques which support
multiple expositions for different audiences.  It seems that some
readers want a Literate Program to fulfill the User's Manual purpose
while others desire a document oriented toward maintenance and
enhancement of the code and algorithms.  A document (web) which serves
both purposes (weave*s*), and contains the implementation (tangle) may
be the ideal.
 
>I am about to write my first larger Lit programme, and I would
>appreciate reading Skinners paper before starting.
 
Skinner is nothing but a black box to me.
 
Michael Koopman (mike)    Associate Computer Systems Specialist
Concurrent Technologies Corporation     e-mail: koopman@ctc.com
1450 Scalp Avenue                        phone: +1-814-269-2637
Johnstown, PA  15904-3321  USA         telefax: +1-814-269-2666
 
From sven@robots.ox.ac.uk Tue Oct 26 17:16:24 GMT 1993
Date: Tue, 26 Oct 1993 17:16:24 GMT
From: sven@robots.ox.ac.uk (Sven Utcke)
Reply-To: LitProg@SHSU.edu, sven@ROBOTS.OX.AC.UK
To: LitProg@SHSU.EDU
Subject: Re: Literate programming in Framemaker.
 
In article <2ahgk7$dcj@tcsi.tcs.com> sriram@glock.tcs.com (Sriram Srinivasah) writes:
>
>I like the concept of LP (or what I understand of it). 
>My understanding is -
>	-  Source and documentation is all present in one document
>	-  The same document can be compiled, either for execution by a machine,
>	   or for publication.
>	-  The tools that implement LP provide a framework to achieve the above, 
>	   and macros to format the stuff effectively.
 
Well, my pet concept is missing: the possibility to write the code in
any order I could dream off.
 
>I can achieve the same using FrameMaker or most other word processing tools, which
>allow you to tag paragraph types. So, I can have a paragraph template called "Code",
>that identifies the Code sections. Now, I can intermix graphics, tables, all kinds
>of formatting like automatic line numbering, cross-referencing, indexes etc.
>What I see on the screen is the final output, uncluttered by meta-information.
>Separating the code from the chaff is very easy, once a Frame file is converted to 
>a MIF file (an awk script is given below)
>
>THE $(10^6) question:
>	IS THIS IDEA WORTH EXPLORING FURTHER?
 
I certainly like the idea. Although I'm unlikely to ever use it myself
(I'm hooked on LaTeX and wouldn't even consider using one of nowadays
WYSIWYG-formater --- the output is much to ugly), it seems to be a
good way to introduce more people to the concept of literate
programming.
 
If only the "chunk"-concept would be used (but that can't be so
difficult).
 
On the other hand: Isn't that what CLiP is doing?
 
Sven
 
From c21vc@kocrsv01.delcoelect.com Tue Oct 26 19:04:39 GMT 1993
Date: Tue, 26 Oct 1993 19:04:39 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: Reference to Skinner's article on writing
 
I am having trouble locating my copy at home.
Of the top of my head here are the details:
 
A Thinking Aid, B.F.Skinner, Journal of Applied Behavior Analysis, after 1985 for
sure.
 
I will look for the actual issue at Purdue University this weekend. (This is
where I got Norman Ramsey's article.) I will post again when I have more specific
details.
 
Thanks for your interest.
 
Shaker
 
From cgra@btma74.nohost.nodomain Tue Oct 26 21:01:37 GMT 1993
Date: Tue, 26 Oct 1993 21:01:37 GMT
From: cgra@btma74.nohost.nodomain (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: Luminary abuse (was Re: Inline comments and abstraction)
 
In article <neeri.751464615@yggdrasil>, neeri@iis.ee.ethz.ch (Matthias Neeracher) writes:
 
>[...]
 
>Dijkstra is bound to generate resentment with people actually working 
>with computers when he declares that advanced debuggers are unnecessary
>and harmful, and some system designers actually take him seriously,
 
Hear hear hear hear hear.   The system on which I  have spent half of my
working life started out with that kind of thinking---no need for online
debugging, everything  will be ``finite message machines''  individually
tested beforehand,...  several years later,  the debugging stuff was all
there,  but not until the project  had soaked up enough unbudgeted  man-
power to bring  one of  the world's  great multinationals to its  knees.
 
Disclaimer: any resemblance to actual great multinationals, whether
living or dead, is entirely coincidental.
__________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
 
From schrod@iti.informatik.th-darmstadt.de Tue Oct 26 21:01:37 GMT 1993
Date: Tue, 26 Oct 1993 21:01:37 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Contents of the Literate Programming Archive
 
Finally, I've found the time to write an overview of the contents of
the LitProg Archive. I thought it might be of interest for the readers
of this newsgroup. (Of course, this file itself is available from the
LPA: ftp.th-darmstadt.de:pub/programming/literate-programming/Contents.)
 
Still to add: webmerge, scanweb, the WEB Mac port of Kevin Mitchell
(when it's got released eventually).
 
Enjoy,
	Joachim
 
---------------- included file follows:
 
# literate-programming/Contents			27 Oct 93  -*- Indented-Text -*-
#------------------------------------------------------------
 
The material available from the Literate Programming Archive is
categorized, each category is put in a directory tree. While this
structure (which is described in the README files) supports browsing,
the need for quick access to a specific Literate Programming tool
remains.
 
This file shall assist you in this need. It presents the *WEB systems
and tools available, in an alphabetic order, and names the directory
where you can find it.
    In addition to the systems mentioned below, the LitProg Archive
features texts in the directory Documentation: FAQs, papers, and an
extensive bibliography in BibTeX format.
 
Since this file is updated manually, I cannot guarantee that it's up
to date. Send reports about inconsistency of description and reality
to Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>.
 
SYSTEM		    DIRECTORY			REMARK
------		    ---------			------
APLWEB		    apl				w/o source, but under the GPL!
					[this was an error by the author]
AWEB		    ada/aweb			not supported any more
cfa		    Tools			Change File Analyzer
CLiP
 -- for DOS	    machines/ms-dos
 -- for VMS	    machines/vms
cnoweb		    c.c++
CWEB (Levy/Knuth)				C++, ANSI C, K&R C
 -- source	    c.c++
 -- DOS port	    machines/ms-dos
 -- Mac port	    machines/mac/cweb		only CTANGLE
cweb style	    c.c++			CWEB programs as LaTeX documents
CWEB (Schrod)	    <not available>		not supported any more
						send me mail if you have
						historic interests :-)
Funnelweb	    independent
FWEB						multi-lingual WEB
 -- source	    fweb
 -- DOS port	    machines/ms-dos
Knit		    pascal			not supported any more
lit2x		    independent			[????] from Glasgow
LPW		    machines/mac		CAVEAT: Shareware!
MapleWEB	    maple			[SpiderWEB?]
MWEB (Schrod/Detig) modula-2			not supported any more
MWEB (Sewell)	    modula-2			not supported any more
noweb		    independent			uses the UNIX toolbox paradigm
nuweb		    independent
ProTex		    independent			[really a LitProg system?]
RWEB		    reduce			[SpiderWEB?]
SpiderWEB					WEB generator, in awk
 -- source	    spiderweb
 -- DOS port	    machines/ms-dos
 -- OS/2 port	    machines/os2
 -- Mac port	    machines/mac
TIE		    Tools			Change File Merger
WEB		    				The basis, it started with it...
 -- source	    pascal
 -- DOS port	    machines/ms-dos
WEB mode	    Tools			for GNU Emacs
 
Systems without support of refinements
--------------------------------------
 
MAKEPROG	    independent			is here for my own convenience
						:-)
SchemeWEB	    lisp
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
[THD Literate Programming Archive, maintainer]
 
From c21vc@kocrsv01.delcoelect.com Tue Oct 26 21:01:37 GMT 1993
Date: Tue, 26 Oct 1993 21:01:37 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: Effective instructions for maintenance programmers
 
The subject is HP Users's Manual as an example of something that provides good
instructions to its intended readers so that they can act effectively in 
solving their problems
 
>This document is a User's Manual, not a Technical Manual.  I am not
>criticizing the document or denying it's value to the intended
>audience.  However, I do not believe this document is a good template
>for a literate program of significant depth.  Of course, diagrams and
>directions for every contingency plausible owing to correct and
>incorrect use, and use under failure conditions for a complex program
>would be nice, but seems a daunting task.  Much discussion centers
>around the methods for simplifying the complex program implementation
>into `User Manual descriptions' with literate techniques.  I do not
>feel such efforts are strictly ``academic'' or infeasible in the
>``Real World' of ``Real Programmers.''
>
>The diversity of the User's Manual and the Technical Manual seems
>relevant to questions concerning literate techniques which support
>multiple expositions for different audiences.  It seems that some
>readers want a Literate Program to fulfill the User's Manual purpose
>while others desire a document oriented toward maintenance and
>enhancement of the code and algorithms.  A document (web) which serves
>both purposes (weave*s*), and contains the implementation (tangle) may
>be the ideal.
 
Some responses to Michael Koopman's recent posting quoted above: 
 
I did not intend to imply that the HP User's Manual is a
'good template for a literate program ...' nor did I have
'diagrams and directions for every contingency ... ' in mind.
What I was thinking was these: the HP User's Manual does a
terrific job in helping its intended audience do user type
functions - changing toner cartridges, loading different
fonts,etc. Information is organized in an easy to find way.
The whole experience is generally pleasing. Not a lot of prior
experience is required. Not a lot of 'look under another topic'
type of stuff is required. The whole thing is geared to the
reader taking effective action. I can imagine a programmer's
manual doing a similarly terrific job in helping its intended
audience do maintenance programmer type of functions. To
give an example (based on a recent experience): in some system, 
the requirement is to do one type of checksum if the year
invloved is 94 and do another type of checksum if the year
invloved is > 94. An existing program had code calculating
checksums for 94 and 95. For 96 etc., it did nothing. This
error had to be fixed. The maintenance programmer function
involved here is to change a test such that for any year >94,
the previous 95 logic is executed. I can imagine a good
version of this system which provides most (if not all) of the
advantages I have listed above for the HP User's Manual.
Namely, what is done for the various years (for checksumming)
should be very easy to locate by someone with no experience
with the system (for instance, someone with 'college level
curiosity'). In other words, a new maintenance programmer
should be able to realize pretty easily from the program that
nothing is done for the years >95. It should also be easy to
realize that the requirement for years >95 is the same as that
for 95. (In fact, if the original programmer had organized her
program/document this well, she would have realized that she
is not providing any checksumming function for >95.) In sum,
if the program/document makes it very easy for someone new to
make this change and do it without getting irritated (just
like using the HP User's Manual one can change toner cartridges 
without much irritation; without such a nice manual, a few
cusswords and kicking of the printer are highly likely), it has met 
the criterion of aiding/enhancing effective action by a new reader/user.
Outside of such maintenance programmer's manual, of course,
enduser(nonprogrammer) manuals are needed for people to type
in commands to perform checksum on actual parts etc. Instructions for
these readers may/may not belong in a literate program. (Of course, these
manuals can be written providing the above benefits, etc.) 
 
Also, judicious decisions should be made (based on intended audience 
and several other factors) in areas like how much spoonfeeding to make 
etc. If a lot users are likely to be so angry that they cannot even
see the print on a book when they are likely to use the book (as when 
going to the printer manual when their printer suddenly stops working),
perhaps all the possible 'spoonfeeding' (i.e., diagrams and directions for 
every contingency plausible owing to correct and incorrect use, and use 
under failure conditions, etc.) should be considered. I certainly do
not expect the program/document for the above case to tell me, for
instance, 'if year = 96, add code to handle this'. If the
program/document guides me quickly to go the section invloved, no other 
info is needed (other than what the reqmt for years >95 is). If the
instructions quickly take me to a certain depth and if I am assured
that the instructions are accurate, asking a maintenance programmer to
dig through the next several levels is not unreasonable. Having to
reinvent the wheel evey single time is what I want to avoid. Also, in
my view, maintenance programmers needs are less important than
endusers needs, if there is a contention for resources. However, most
of the times both constituencies can be served well without one having
to sacrifice for the other; what is in short supply is the knowhow/desire to
do it.
 
I hope that these type of postings are of some value. If you guys
start complaining, I will have to take my thoughts to
alt.professional.wrestling. Also, my friend Ron Peithman told me
yesterday that the following is the full quote:
 
'What a tangled web we weave, when we pratice to deceive'.
 
Some project manager types that I know are indeed literate programmers 
without realizing that they are: they do weave tangled webs; practice 
quite a bit of deception.
 
Shaker
 
From cgra@btma74.nohost.nodomain Tue Oct 26 21:01:37 GMT 1993
Date: Tue, 26 Oct 1993 21:01:37 GMT
From: cgra@btma74.nohost.nodomain (Chris Gray)
Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <2abjai$965@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes:
 
In article <16782125@mvb.saic.com>, Lee Wittenberg  <leew@pilot.njin.net> wrote:
 
>The problem with `chunk' is that it does have this use in Psychology.
>The more complete term is `cognitive chunk'.  I have proposed the term
>`cognitve block' in a paper now being refereed.  
 
Ooerr.  In that context `cognitive block' makes me think of `mental block'
or `writer's block'.
 
_________________________________________________________________________
Chris Gray        cgra@se.alcbel.be         Compu$erve: 100065.2102       
 
From Lee Tue Oct 26 17:27:28 EDT 1993
Date: Tue, 26 Oct 93 17:27:28 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: New version of WinWordWEB
 
Stephen McKearney has made a few improvements to the original
WinWordWEB, including some support for cross-referencing and an index
of chunk names.  I've tried it out (minimally) on a copy of WinWord in
an office down the hall from mine, and it seems to work.  I've  made
the new, improved version (wordweb2.zip) available for anonymous ftp 
in the pub/leew directory of bart.kean.edu.  The original version is
still there, as well.  I understand that there are several ftp sites
out there that also make copies of WordWEB available.  I'd appreciate
it if everyone could keep traffic on bart down to a minimum, and wait
until these other sites get the new version (assuming that they do).
 
This brings me to the problem of maintenance.  WinWordWEB was intended
to be an unsupported product, but there seems to be enough interest in
it that I feel a moral responsibility to provide some sort of
support.  However, I do not actually use the product, nor do I have
easy access to a copy of Word for Windows.  I see 3 alternatives (in
order of preference):
 
1.  Someone out there who uses WordWEB volunteers to support it.  This
would involve fixing the known bugs, and coordinating any modifications
and improvements that may be suggested by users.  This is really the
only way that users can get the support they deserve.
 
2.  Someone out there has contacts with Microsoft who are interested
in seeing this project continue, and are willing to provide me with a
current copy of WinWord and updates, in return for my supporting the
product myself.  Perhaps Microsoft might care to include the package
with their compiler products?
 
3.  Someone out there has a legal copy of WinWord that they are not
using and can send to me, so that I will be able to support WinWordWEB
as best I can (at least with the current version of WinWord).
 
Anyone fitting one of the above categories (particularly #1) should contact
me directly.  Thanks in advance.
 
		-- Lee
		   leew@pilot.njin.net
 
From ddw2@sunbim.be Wed Oct 27 09:38:56 +0100 1993
Date: Wed, 27 Oct 93 09:38:56 +0100
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
   Osman> How about nuweb recognizing the TeX/LaTeX comment delimiter
   Osman> `%'? Then the users do not have learn another command!
 
This would not allow putting some kinds of comments in the body of
scraps or make problems with C expresssions like x = y % z; 
 
@o f.pro @{ @% -*- prolog -*-
% this comment should appear in the source
test.
@}
 
or would impose treating % differently within or outside scrap bodie.
 
Dominique
 
From ae1181t@stnfor.ae.ge.com Wed Oct 27 07:50:04 -0400 1993
Date: Wed, 27 Oct 1993 07:50:04 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: ddw2@sunbim.be
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
>>>>> On Wed, 27 Oct 93 09:38:56 +0100, ddw2@sunbim.be (Dominique de Waleffe) said:
 
	Dominique> @o f.pro @{ @% -*- prolog -*-
	Dominique> % this comment should appear in the source
	Dominique> test.
	Dominique> @}
 
	Dominique> or would impose treating % differently within or outside scrap bodie.
 
I thought there would be no need to have comments in scraps, but may be 
mistaken. My problem was with web mode emacs I have a limbo.nuweb and it
had my email address in a LaTeX comment which nuweb did not like. So I put
@@. But also created a diff file to nuweb0.87 that allows % as comment
anywhere LaTeX allowed (just doesnt process @ until end of line). Seems
to work and not affect the code section. 
Osman
 
From collins@ny.cs.wm.edu Wed Oct 27 12:23:32 GMT 1993
Date: Wed, 27 Oct 1993 12:23:32 GMT
From: collins@ny.cs.wm.edu (Bob Collins)
Reply-To: LitProg@SHSU.edu, collins@NY.CS.WM.EDU
To: LitProg@SHSU.EDU
Subject: Re: Literate programming in Framemaker.
 
Sriram Srinivasah recommends using FrameMaker for literate programming.
However, Sriram Srinivasah did not mention all the advantages of FrameMaker.
FrameMaker is, among other things, a hypertext document generator. One
can construct (semi-automatically in FrameMaker 4) a set of hypertext
links so that clicking on a hypertext word or picture will display
related text. One can have the effect of a table of contents or index
without page numbers. One can click on the "title" of a related code
fragment to display the code fragment.
 
Consider the primary advantage of a hypertext WYSIWYG document. One is
always working with the latest version of the final document. No wasting
of printer resources *or* working from slightly outdated printed
documents.
 
FrameMaker also has an easy to use book concept with multiple chapters.
This is the most logical way to break up a large document. FrameMaker
will maintain and regenerate all sorts of links across documents. No
need to write obscure macros. No need to modify these macros.
 
FrameMaker allows all sorts of tagging (invisible to the eye but denoted
in the bottom margin) of paragraphs and text. Uses of these can be so
that lists can be generated and text extracted. This is how one can
an automatic cross-reference and make it a hypertext cross-reference.
There will no need to use cryptic marks in the text to indicate special
things (like the continuation of the body of a code fragment. Use tags
and a special typographic standard. Use variables to say "continued."
All of these are easily feasible.
 
Sven Utcke objects that he would no longer be able to write code in
an arbitrary fashion. Well, he may have misunderstood Sriram Srinivasah
who claimed that *with almost no effort* one can use FrameMaker for
literate programming. [Indeed, using conditional text for code,
within FrameMaker one can view just the code using a simple dialog box.
This requires no work at all.] Don't forget that the Knuth system involves
running programs to put code fragments together in the correct order.
One can also write a program to do a similar thing to MIF output of
FrameMaker documents. MIF is Maker Interchange Format, a TeX- or RTF-
like marked ASCII text.
 
I have been reading this group for some time. I agree with all those
who say the biggest drawback to literate programming is learning a new
language -- TeX. TeX, written in the late 70's and popularized in the
80's is very much a 60's product in its interface. Granted it does things
that were not done in the 60's. But it sure feels like JCL. Knuth,
a wise and witty man, is a hacker at heart. He thinks obscurely and at
a low level. He chooses low-level assembly language to describe algorithms.
I cannot figure out how he has such a delightful sense of humor and
an assembly language mentality. We seem to apotheosize the one person
who least practices the things that make literate programming such a
nice idea. [Knuth reminds me of a story (apocryphal?) about John von Neumann.
At a party von Neumann was asked the puzzle: two trains 100 miles apart
are approaching each other at 50 mph. A bumblebee, starting at one train,
travels between trains at 25 mph, reversing directions when reaching an
aproaching train. How far does the bumblebee travel before being crushed?
von Neumann thought a short moment and promptly answered 25 miles. When
asked if he knew the trick, he acted puzzled and said that he summed the
infinite series.]
 
The *only* advantages of TeX that I know of are that it does mathematical
typesetting nicely and it's free. FrameMaker does mathematical typesetting
sufficiently well for literate programming.
 
Bob Collins, collins@cs.wm.edu
CS Dept, Coll of Wm & Mary (est 1693)
 
From sriram@glock.tcs.com Wed Oct 27 12:23:32 GMT 1993
Date: Wed, 27 Oct 1993 12:23:32 GMT
From: sriram@glock.tcs.com (Sriram Srinivasah)
Reply-To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM
To: LitProg@SHSU.EDU
Subject: Re: Literate programming in Framemaker.
 
In article <1993Oct27.122332.22052@cs.wm.edu>, collins@ny.cs.wm.edu (Bob Collins
) writes:
> Sriram Srinivasah recommends using FrameMaker for literate programming.
> However, Sriram Srinivasah did not mention all the advantages of FrameMaker.
> FrameMaker is, among other things, a hypertext document generator. One
> can construct (semi-automatically in FrameMaker 4) a set of hypertext
> links so that clicking on a hypertext word or picture will display
> related text. One can have the effect of a table of contents or index
> without page numbers. One can click on the "title" of a related code
> fragment to display the code fragment.
>
>  [ FrameMaker plug deleted ....]
> 
> I have been reading this group for some time. I agree with all those
> who say the biggest drawback to literate programming is learning a new
> language -- TeX. TeX, written in the late 70's and popularized in the
> 80's is very much a 60's product in its interface. 
>
 
You can say this again!
 
Now, for the downside of using Frame, or any other word processor. Note that
I'm definitely NOT in favor of Tex still ..
 
o	Speed of development - I am a power Emacs/Vi user, and Frame or WFW
	simply doesn't cut it in terms of development speed.
 
o	All my text processing tools can't be used - egrep, class browsers,
	awk, sed, sdiff, tags, and a zillion others.
	I managed to fix my mifToCode script to generate the correct line 
	numbers, so that GDB isn't confused - but you see the point - I now have
	to worry about issues that weren't in text-land.
 
o	SCCS isn't very happy either. Have to move my stuff over to RCS, to
	be able to check in or out stuff. Either that, or have to convert 
	all files to MIF before using SCCS.
 
o	Integrating this with other code in a production development environment
	seems to be a pain (I tried). (Other code - stuff already developed).
 
o	Using Tex and remaining in text-mode is a concept I find very 
	painful. I do not want to think formatting when I am into development.
	Bob Collins has already said all I would have wanted to.
 
I guess I need a powerful argument for undergoing these hassles, especially
the development cycle speed, before I really change my ways. Practically,
how does it payback? Does it result in fewer edit/compile/run cycles? 
Has anyone used it for projects that have, say, 2 million lines of code, and 
has to be pushed out, say, yesterday? (Someone other than Knuth, that is!)
 
Meanwhile, I convinced one of my friends to use my scripts and paragraph
formats for a book he's working on. At the very least, we can test out the
code that is going into the book by extracting all of it and compiling it.
He's not completely in favor of doing development inside Frame yet.
 
Sriram Srinivasan. -- Note: my name is misspelt by the mailer. 
(sriram@tcs.com)
 
From ddw2@sunbim.be Wed Oct 27 13:29:58 +0100 1993
Date: Wed, 27 Oct 93 13:29:58 +0100
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Subject: Re: nuweb doesnt like Emacs outline-regexp
 
   >>>>>> On Wed, 27 Oct 93 09:38:56 +0100, ddw2@sunbim.be (Dominique
   >>>>>> de Waleffe) said:
   Dominique> @o f.pro @{ @% -*- prolog -*- % this comment should
   Dominique> appear in the source test.  @}
 
   Dominique> or would impose treating % differently within or
   Dominique> outside scrap bodie.
 
   Osman> I thought there would be no need to have comments in
   Osman> scraps, but may be mistaken. My problem was with web mode
 
The comment I put in describe the emacs mode in which to edit the
scrap. But there's not only comments... I use that in nuweb.el (which
has been posted on the list a while back, with a new version coming
soon, as well as being mentionned in the next version of the FAQ).
 
   Osman> emacs I have a limbo.nuweb and it had my email address in a
   Osman> LaTeX comment which nuweb did not like. So I put @@. But
   Osman> also created a diff file to nuweb0.87 that allows % as
 
A long time ago, I did suggest to Preston that @% be included as commenting
sequence in nuweb. I belive the best thing is for Preston to include
that in nuweb 0.88 as soon as possible, as it looks like eveybody is
making up his own commenting patch...
 
For your info, this is a summary of what exists and what's coming up
in nuweb.el (I could post the current version, but would rather clean
it up first. Those that really wnat to try, just ask by email).
 
Existing: in litprog archives version:
;;; A) Help for editing scraps in language dependent mode
;;;
;;;       C-c C-z nuweb-edit-this scrap 
;;;           Edit the scrap point is on in its own buffer *Source*
;;;           put into the mode specified by the buffer local variable
;;;           nuweb-source-mode (defaults "emacs-lisp") or into the
;;;           mode specified after @{ (on same line)  the scrap body as
;;;           -*-mode-name-*- 
;;;           The *Source* buffer is then put into Nuweb minor mode
;;;           which adds two bindings:
;;;           C-c C-z nuweb-install-this-scrap
;;;               Which takes the *Source* buffer contents and puts
;;;               it back into the web buffer in place of the old
;;;               version of the scrap.
;;;           C-c M-k nuweb-kill-this-scrap
;;;               Which restores the old scrap, ignoring changes
;;;               made.
;;;           The original buffer is put in read-only mode until you
;;;           call one of the two above functions or kill the
;;;           *Source* buffer. 
;;;       C-@ nuweb-insert-scrap
;;;           With no argument: inserts an empty scrap template at
;;;           point.
;;;           With an argument: prompt for scrap type (oDdD), scrap
;;;           name and language mode. A new scrap is inserted and
;;;           edited as if nuweb-edit-this-scrap had been called.
;;;
;;;   The AucTex action list has a Web entry, that calls nuweb then
;;; latex, and this is the default action for .w files.
 
Only in my current alpha version:
 
;;; B) Help for navigation on definitions and uses
;;;
;;;       C-c C-d r nuweb-compute-d-u
;;;           Recompute all defs and uses in current buffer.
;;;       C-c C-d p
;;;           Pop back to previous def/use
;;;       C-c C-d s
;;;           Find first definition for scrap name at point
;;;       C-c C-d n
;;;           Find next definition of same scrap name
;;;       C-c C-u s
;;;           Find first use of scrap name at point
;;;       C-c C-u n
;;;           Find next use of smae scrap name
;;;       M-mouse3
;;;           Find first def or first use (if on a def -> use, if on a
;;;           use -> def)
;;;
;;;
 
Coming RSN:
 
-) The mode in which to edit a scrap defined by @o or @O will be that
determined by the filename (using auto-mode-alist) by default,
 
-) The nuweb annotations will be removed from the scrap buffer (they
screw up indentation in some modes.
 
-) Also works with standard latex mode
 
Dominique
 
From dmason@uwaterloo.ca Wed Oct 27 17:41:10 GMT 1993
Date: Wed, 27 Oct 1993 17:41:10 GMT
From: dmason@uwaterloo.ca (Dave Mason)
Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA
To: LitProg@SHSU.EDU
Subject: Re: Reference to Skinner's article on writing
 
In article <1993Oct26.190439.12488@kocrsv01.delcoelect.com> c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) writes:
 
> I am having trouble locating my copy at home.
> Of the top of my head here are the details:
> 
> A Thinking Aid, B.F.Skinner, Journal of Applied Behavior Analysis, after 1985 for
> sure.
 
1987.  v20, pp189-190
 
A very brief article describing essentially a physical manifestation
of an outline editor.  Several useful comments as well.
 
I certainly concur that outline editors are *very* useful for writing
papers.
 
../Dave
 
From philipr@extro.ucc.su.OZ.AU Wed Oct 27 22:37:15 GMT 1993
Date: Wed, 27 Oct 1993 22:37:15 GMT
From: philipr@extro.ucc.su.OZ.AU (Philip Rhoades)
Reply-To: LitProg@SHSU.edu, philipr@EXTRO.UCC.SU.OZ.AU
To: LitProg@SHSU.EDU
Subject: Re: New version of WinWordWEB
 
Lee Wittenberg <leew@pilot.njin.net> writes:
 
>Stephen McKearney has made a few improvements to the original
>WinWordWEB, including some support for cross-referencing and an index
>of chunk names.  I've tried it out (minimally) on a copy of WinWord in
>an office down the hall from mine, and it seems to work.  I've  made
>the new, improved version (wordweb2.zip) available for anonymous ftp 
>in the pub/leew directory of bart.kean.edu.  The original version is
>still there, as well.  I understand that there are several ftp sites
>out there that also make copies of WordWEB available.  I'd appreciate
>it if everyone could keep traffic on bart down to a minimum, and wait
>until these other sites get the new version (assuming that they do).
 
What is WinWordWEB actually for? Integrating WfW with WWW?
 
-- 
Philip Rhoades  *  First Year Biology  *  University of Sydney
phil@biox.bio.su.OZ.AU (best) or philipr@extro.ucc.su.OZ.AU
Phone: +61 2 692 2765  *  Fax: +61 2 692 2175
 
From shf@netcom.com Thu Oct 28 05:49:08 GMT 1993
Date: Thu, 28 Oct 1993 05:49:08 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: Reference to Skinner's article on writing
 
+-- dmason@uwaterloo.ca (Dave Mason) writes:
| I certainly concur that outline editors are *very* useful for writing
| papers.
 
Yes they are.  This leads me to ask about an idea that's been troubling
me for a few weeks.  Is there any interest in, or tools for, treating
the text portion of a literate program as a web?  This would let one
write prose in the top-down, structured manner of an outline editor.
 
For the most part I can live with moving blocks of text around in an
editor for this, except for one thing.  I would like to be able to
generate a *set* of documents from one literate program.  The program
itself, a client interface reference, a user primer, change log, etc.
I can do this to some extent by selectivly including only certain
portions of the main text into each document, but I cannot reorder
text selections to put them in the most logical order in each document.
 
And you know, if any programming language needs to be more literate,
it's TeX.
 
	- "Meta-man" Ferguson
-- 
		Stuart Ferguson		(shf@netcom.com)
			"Oh Dear Lord -- the canary exploded!"
 
From greyham@research.canon.oz.au Thu Oct 28 08:42:39 GMT 1993
Date: Thu, 28 Oct 1993 08:42:39 GMT
From: greyham@research.canon.oz.au (Graham Stoney)
Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU
To: LitProg@SHSU.EDU
Subject: An Automatic C++ documentation compilation project.
 
Writing and maintaining documentation has often been a thorn in the side of the
Software Engineer and Programmer. After spending a great deal of time and
effort writing documentation about a program or software system, the code
invariably changes, quickly rendering the documentation out of date. The
documentation becomes misleading, gets neglected, and quickly becomes useless.
 
"Literate Programming" is one approach to solving this problem. It effectively
introduces a whole new (typesetting) language, requires a quite radical shift
on the part of the "non-literate" programmer and still requires a good deal of
effort on the part of the programmer[1].
 
I'd like to suggest a different approach which lies considerably closer to
more traditional programming practices, and can offer quite immediate benefits
when functional interface documentation is the main documentation required.
 
The primary philosophy here is to use the programming language as far as
possible to express the programmer's intentions, and to use comments only when
the programming language is not sufficiently expressive. A comment can then
become part of the language grammar which is recognised by a "documentation
compiler". This tool parses a superset of the programming language and can
automatically generate documentation in human-readable form by associating the
programmer's comments with the objects in the code by their context.
 
Whilst the idea of extracting documentation from comments in source code is by
no means new, the difference here is that the comments actually form part of
the grammar of the language recognised by the documentation compiler[2].
 
Comments should not repeat information that is already represented in the
program code; for instance, a comment describing a function argument should not
repeat the name and type of that argument (since that information has already
been included, for the compiler), but should appear near the argument.
 
For example, in C, the programmer should write this:
 
	/* include an example in the article */
	enum Result example(int page	/* page it appears on */);
 
Rather than this:
 
	/* include an example in the article
	 *
	 * PARAMETERS:
	 *	int page	page it appears on
	 *
	 * RETURNS:
	 *	RESULT_YES		The readers agreed
	 *	RESULT_NO		The readers disagreed
	 *	RESULT_YOURE_JOKING	The readers disagreed strongly
	 *	RESULT_BLANK_LOOKS	The readers didn't understand
	 */
	enum Result example(int page);
 
Also in this example, the documentation compiler knows the possible enumerated
values that the function can return (as does the "real" compiler), so it is
unnecessary for the programmer to restate them. The comments need simply be
included in the definition for "enum Result" for the "RETURNS" information to
be generated automatically:
 
    enum Result {
	RESULT_YES,		/* The readers agreed */
	RESULT_NO,		/* The readers disagreed */
	RESULT_YOURE_JOKING,	/* The readers disagreed strongly */
	RESULT_BLANK_LOOKS	/* The readers didn't understand */
    };
 
Critics have suggested that the latter style in the example is easier to read
for someone wishing to call the function in question. Of course, this is a
style question which depends on each person's tastes; but the criticism is tied
to the notion that the source code needs to look "beautiful" because it is the
primary reference for someone wishing to use that function. This becomes much
less significant once documentation is available which is known to _always_ be
up to date. Of course, the latter style takes longer to write and maintain,
and can become out of date should the name or type of the parameter be
changed, yet the comment get neglected.
 
I have implemented one such documentation compiler for the C language called
"c2man", which is freely available[3]. The response from users has been
extremely encouraging; I suspect this is partly because of the wide variety of
styles of comment placement that are recognised: it often correctly recognises
comments that weren't written with c2man in mind at all. While it's use is
focused solely on functional interface documentation and it doesn't have
anywhere near the power of a full Literate Programming system, the focus is on
reducing the effort required by the programmer to the absolute minimum, and
seeing how much documentation we can get essentially "for free".
 
Many people have requested C++ support be added to c2man, and I suspect that
this philosophy would be even more suitable and powerful for documenting
interfaces to C++ classes automatically.
 
Here is an example of how I envisage this philosophy would work when applied to
C++. It's interesting to note that this code was written a couple of years ago
exactly as you see it here, without the idea of generating documentation from
it in mind at all:
 
    // generic Timer class
    class Timer
    {
    private:
	static int numactive;	// number of constructed timers.
	static Timer *first;	// first one in list.
	Timer *next;		// next one in linked list.
	Time ticksdiff;		// ticks we take to expire once at front.
 
	enum
	{
		INACTIVE,	// timer is not in chain.
		STARTED,	// one-shot
		RUNNING		// continuous.
	} state;
 
	// original interrupt vector value.
	static void interrupt (far *old_vector)(...);
 
	void (*timeout_function)(int);	// function called when we time out
	int timeout_parameter;		// gets passed to timeout_function
	Time duration;			// timer length (ticks)
 
	static void interrupt far tick(...);	// clock tick routine.
 
	void insert();	// add into active chain.
	void remove();	// remove from active chain.
	void set(Time milliseconds);	// set duration from ms.
 
    public:
	// constructor
	Timer(Time time=0,		// milliseconds
	      void (*function)(int)=0,	// called at timeout
	      int param=-1);		// param for function
 
	// destructor
	~Timer();
 
	// start (or restart) a timer running.
	void Start();
	void Start(Time duration);	// how long to run for
 
	// start a timer running continuous.
	void Run();
 
	// stop a timer.
	void Stop();
 
	// is a timer active?
	boolean Active() const { return state != INACTIVE; };
    };
 
Processing this class declaration could generate the following automatically:
 
    NAME
	    Timer - generic timer class
 
    SYNOPSIS
	    class Timer
	    {
	    public:
		    Timer(Time time=0,
			    void (*function)(int)=0,
			    int param=-1);
		    ~Timer();
		    void Start();
		    void Start(Time duration);
		    void Run();
		    void Stop();
		    boolean Active() const;
	    };
 
    PARAMETERS
	Time time
	    Milliseconds
 
	void (*function)(int)
	    called at timeout.
 
	int param
	    Param for function.
 
	Time duration
	    How long to run for.
 
    DESCRIPTION
	Timer
	    Constructor
 
	~Timer
	    Destructor
 
	Start
	    Start (or restart) a timer running.
 
	Run
	    Start a timer running continuous.
 
	Stop
	    Stop a timer.
 
	Active
	    Is a timer active?.
 
It should also be possible to extract this information from the implementation
of the class (rather than the declaration), if that's where the user prefers to
put the comments describing each member function and their parameters.
 
Unfortunately, at present I do not have sufficient spare time to make the
additions to c2man required to support C++. It would be a great contribution to
the C++ community, not to mention the documentation time saved by themselves,
for someone involved in C++ work to add this support and release the result[4].
 
If you work with a team developing C++ code, please consider having one of your
developers on a ``Usenet Sabbatical'' to extend this philosophy to C++, and
start reaping the benefits in documentation time savings.
 
It could also make an ideal Computer Science student compiler project.
 
Please contact me via E-mail if you are interested in undertaking such a
project.
 
Graham Stoney
 
Footnotes:
1. Advocates of Literate Programming would argue that Literate Programming is
   much more than snazzy documents and that it encourages this extra effort to
   focus early on in the design of the software, which pays off later.
 
2. To get a better idea, see the file grammar.y in the c2man distribution.
 
3. c2man has been posted on comp.sources.reviewed. It should be available from:
	comp.sources.reviewed archive volume 3, or ask archie.
    N.America:	ftp.wustl.edu:/usenet/comp.sources.reviewed/volume03/c2man*
    Europe:	ftp.informatik.uni-stuttgart.de:
				      /pub/archive/comp.sources/reviewed/c2man*
    Patches:	lth.se:/pub/netnews/sources.bugs/volume93/sep/c2man*
 
4. c2man's copyright requires that all derivative works remain freely
   available.
 
-- 
Graham Stoney, Hardware/Software Engineer
Canon Information Systems Research Australia
Ph: + 61 2 805 2909	Fax: + 61 2 805 2929
 
From mckearney_s Thu Oct 28 08:57:40 +0000 1993
Date: Thu, 28 Oct 1993 08:57:40 +0000
From: mckearney_s <mckearney_s@bt-web.bt.co.uk>
Reply-To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK
To: litprog@shsu.edu
Subject: Re: New version of WinWordWEB
 
Hello,
 
I use WinWordWeb and have continued to make minor changes to it.  I would 
be willing to try to support and co-ordinate it.  The main constraint 
would be that it does not become such a large task as to require a lot 
of time.  Lee, thanks for distributing the version of WinWordWeb I 
changed.  The problem I had in distributing to people who requested 
it (through ftp) has been solved, I think.  Can it be placed in the 
LitProg archive?  If no one else offers their services I will try to 
support it.
 
Stephen Mc Kearney
 
From Lee Thu Oct 28 7:35:55 EDT 1993
Date: Thu, 28 Oct 93 7:35:55 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, mckearney_s@bt-web.bt.co.uk
Subject: Re: New version of WinWordWEB
 
Stephen:
 
> I use WinWordWeb and have continued to make minor changes to it.  I would 
> be willing to try to support and co-ordinate it.  The main constraint 
> would be that it does not become such a large task as to require a lot 
> of time.  Lee, thanks for distributing the version of WinWordWeb I 
> changed.  The problem I had in distributing to people who requested 
> it (through ftp) has been solved, I think.  Can it be placed in the 
> LitProg archive?  If no one else offers their services I will try to 
> support it.
 
I don't know about the LitProg archive.  I assume that it will end up
there eventually, anyway.  I just don't have the time to follow up on
all these things myself.
 
If no one else offers their services, as you say, I'll let you know,
and you can take over.  Thanks for the offer.
 
		-- Lee
 
From schrod@iti.informatik.th-darmstadt.de Thu Oct 28 7:41:02 EDT 1993
Date: Thu, 28 Oct 93 7:41:02 EDT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Literate programming in Framemaker.
 
In article <1993Oct27.122332.22052@cs.wm.edu>, collins@ny.cs.wm.edu (Bob Collins) writes:
 
> Knuth,
> a wise and witty man, is a hacker at heart. He thinks obscurely and at
> a low level. He chooses low-level assembly language to describe algorithms.
> I cannot figure out how he has such a delightful sense of humor and
> an assembly language mentality. 
 
How? Simple: he's a scientist. How do you do *exact* analysis of
run-time behaviour without an exact notion of the cost of basic
operations? Give me the answer, and then we can see if we can get rid
of MIX. Btw, Vol. 4 won't have MIX any more.
 
> The *only* advantages of TeX that I know of are that it does mathematical
> typesetting nicely and it's free. FrameMaker does mathematical typesetting
> sufficiently well for literate programming.
 
How do you edit your FrameMaker documents on more than 40 different
operating systems, ranging from 8086 PCs to Crays?
    How do you use FrameMaker in a convenient way as a background system?
    How do you use many languages? (Remember: Not everyone writes in
English...)
 
Don't get me wrong: FrameMaker is surely one of the better commercial
systems around -- but your evalution of the differences between
TeX and FrameMaker is not even.
 
--
Joachim
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From Lee Thu Oct 28 7:41:02 EDT 1993
Date: Thu, 28 Oct 93 7:41:02 EDT
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, philipr@extro.ucc.su.oz.au
Subject: Re: New version of WinWordWEB
 
Philip Roades asks:
 
> What is WinWordWEB actually for? Integrating WfW with WWW?
 
WinWordWEB is a collection of macros that provide a simple literate
programming environment.  It provides a ``code'' paragraph style for
inserting chunks [sic] of code into documents, and macros for naming
code chunks, and ``tangling'' them into a compilable program.
 
If you're a  WfW user and interested in LP (which is practically a
given, if you read the newgroup/maillist), please grab yourself a copy
and play around with it.  
 
		-- Lee
		   leew@pilot.njin.net
 
From c21vc@kocrsv01.delcoelect.com Thu Oct 28 14:55:28 GMT 1993
Date: Thu, 28 Oct 1993 14:55:28 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: Re: Reference to Skinner's article on writing
 
I would like to make a couple of points here.
 
1. Skinner has devoted all his professional life to
   discovering basic (learning processes and) responding 
   (behaving/acting) processes that happen at particular
   instances in time as a function of several variables.
   His statement of responding processes do not appeal to a
   behavior initiating mind; what happens in the mind is not
   ignored; it is explained as more effects (and not causes
   of responses i.e. dependent variable instead of independent
   variable). I am aware that his conclusions are far from
   universally accepted. (Based on my experience, I have no
   doubt that something like what he says is correct; or as
   Kennneth McCorquadale wrote about this approach to verbal 
   behavior, in response to Chomsky's scathing review of 
   Skinner's book 'Verbal Behavior':
 
   'Like it or not, the camel's nose is in the tent'.
 
   (This review is in the Journal of Experimental Analysis of
   Behavior; this journal has a good index.)
 
   My point is this 'outline editor' may have somthing else
   going for it; the method is developed by some one who
   has thought a lot about the fundamental process by which
   actions come out of individuals; Skinner also used the
   method in his writings during the last few years.
 
2. He also says in the article that this can be easily
   programmed. I am wondering whether someone is interested in
   attempting something like this. I can help. Of course, the
   Skinner's family and the journal have to be contacted to
   get permission; I can help here also. 
 
   Shaker
 
From Mark Thu Oct 28 12:09:36 EDT 1993
Date: Thu, 28 Oct 93 12:09:36 EDT
From: Mark R. Friedman <markf@sequoia.sequoia.com>
Reply-To: LitProg@SHSU.edu, markf@SEQUOIA.SEQUOIA.COM
To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
Subject: Re: Literate programming in Framemaker.
 
From Joachim's response to Bob Collins' comments on Framemaker's strengths:
> 
> > The *only* advantages of TeX that I know of are that it does mathematical
> > typesetting nicely and it's free. FrameMaker does mathematical typesetting
> > sufficiently well for literate programming.
> 
> How do you edit your FrameMaker documents on more than 40 different
> operating systems, ranging from 8086 PCs to Crays?
>     How do you use FrameMaker in a convenient way as a background system?
>     How do you use many languages? (Remember: Not everyone writes in
> English...)
> 
I'll add 2 even ``lower-end'' systems to the editing list --- I often take
notes & revise drafts on an _ancient_ Tandy T102 (not even MS-DOS, but it can
spit out ascii), and I have 3 daughters (ages 11 to 18) that ``share'' an
80286 to (La)TeX documents created on a trio of (also ancient) Apple ]['s.
The point, of course is quite simple --- if it can produce ascii outout,
_anything_ can be used for entry & editing.
 
As for the oft cited difficulty of learning LaTeX, my daughters have done _all_
their school reports since 3rd grade as well as lots of other ``documents''
(my 15 year old produces Girl Scout troop meeting minutes, plans & budgets),
in English, French, German, Spanish and even ASL (American Sign Language --- 
a one-off report using a wonderful `hands' Metafont file). Overkill? Absolutely,
but they happen to love it (they're even more critical of sloppy or ugly
documents that I am, and I thought I was the perfectionist in the family).
It has also led to various amusing incidents, like when my oldest was in 7th
grade her English teacher stated that there was ``only one right way to format
a bibliograpy''. Allyson's response was to take my copy of the Chicago Manual of
Style to school, along with about a dozen versions of her assignment's
bibliography, all formatted by different .bst styles, and ask which one
was the ``right'' one... 
 
-- 
|---------------------------------------------------------------|
| Mark R. Friedman    |                                         |
| markf@sequoia.com   |                                         |
|---------------------------------------------------------------| 
 
From c21vc@kocrsv01.delcoelect.com Thu Oct 28 17:04:20 GMT 1993
Date: Thu, 28 Oct 1993 17:04:20 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: FrameMaker
 
I am wondering whether someone will post some details on FrameMaker.
Is it a desktop publishing program ? (I did note that it has hypertext
capabilities.) Several years ago, I played around with PagMaker a little bit.
 
How would FrameMaker compare with Interleaf or Teamwork (the two packages
available here) in the general type of functions provided. Does it belong in teh
same (utility) class or would it be used for other purposes usually ?
 
Thanks.
 
Shaker
 
From norman@bellcore.com Thu Oct 28 17:54:04 -0400 1993
Date: Thu, 28 Oct 93 17:54:04 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: Announcing a new version of noweb
 
(In case you didn't know, noweb is a language-independent
literate-programming tool whose watchwords are simplicity and
extensibility.  If you're not already familiar with noweb, the full
README file will follow in a separate message.  It has complete
information about noweb, including how to get sources by anonymous ftp.
If you know something about noweb, read on.)
 
I am very pleased to be able to announce a major new release of noweb.
The major change visible to users is support for local identifier
cross-reference and an index of identifiers.  Those of us who write
Icon, TeX, or yacc code can enjoy the dubious benefits of automatic
discovery of definitions and uses; others will have to fall back on a
scheme by which definitions are marked manually and uses are
discovered automatically.
 
There are serious changers under the hood which should be of profound
interest to the small cadre of noweb hackers out there.  A -filter
option in the notangle and noweave scripts makes it easy to attach
tools that manipulate noweb information in language-dependent or other
customized ways.  For example, the automatic indexing codes for Icon,
TeX, and yacc are about 30 lines each.  I hope that one of you will
write a tool that automatically recognizes definitions of interesting
identifiers in C or C++ programs.  The same hooks have been used in
two different contributed prettyprinters.
 
Finally, the LaTeX support is drastically revised, and you have far too
many options and hooks to use in fiddling with the output.  Many of
these revisions are in response to complaints by users that they wanted
things formatted differently.
 
Major thanks are due to Preston Briggs and Dave Love, without whom
there wouldn't be a noweb 2.5.  Thanks also to Lee Wittenberg for
finding innumerable bugs and to George Greenwade for helping set up
the distribution.
 
Norman Ramsey
norman@bellcore.com
 
From norman@bellcore.com Thu Oct 28 17:54:20 -0400 1993
Date: Thu, 28 Oct 93 17:54:20 -0400
From: norman@bellcore.com (Norman Ramsey)
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: litprog@shsu.edu
Subject: noweb README file
 
This is version 2.5 of ``noweb'', a low-tech literate programming
tool.  noweb is available via anonymous ftp from the Comprehensive TeX
Archive Network, in directory web/noweb.  CTAN includes
hosts ftp.shsu.edu, ftp.tex.ac.uk, and ftp.uni-stuttgart.de.  These
sites mirror the master directory bellcore.com:pub/norman/noweb.
You can also get the master shar file bellcore.com:pub/norman/noweb.shar.Z.
The file INSTALL tells how to build noweb.
 
Changes to this version are so extensive that they are detailed in a
separate CHANGES file.  They include:
  -- major enhancements of latex support & INCOMPATIBLE changes to noweave
  -- language-independent support for an index of identifiers and 
     for local identifier cross-reference.
  -- a `noweb' command that ``extracts everything.''
  -- contributed prettyprinters for Icon, Object-Oriented Turing,
     and a variant of Dijkstra's language of guarded commands.
  -- restructured shell scripts to make things easier for hackers
     (especially -filter).
  -- bug fixes.
 
INTRODUCTION
 
noweb is designed to meet the needs of literate programmers while
remaining as simple as possible.  Its primary advantages are
simplicity, extensibility, and language-independence.  noweb uses 5
control sequences to WEB's 27.  The simple noweb manual is only 2
pages; documenting the full power of noweave and notangle requires
another 3 pages.  noweb works ``out of the box'' with any programming
language, and its formatter-dependent part is a 60-line nawk program.
The primary sacrifice relative to WEB is that code is not prettyprinted.
 
noweb provides extensibility by using the Unix toolkit philosophy.
The ``noweb,'' ``notangle,'' and ``noweave'' commands are built from
pieces, which are then assembled in pipelines using shell scripts.
The pieces include:
 
  markup	convert noweb file from human syntax to tool syntax
  unmarkup	inverse of markup
  totex		convert from tool syntax to TeX/latex markup
  nt		`tangle' the tool form of the noweb file
  mnt		discover roots, then act like nt
  noidx		insert indexing and cross-reference information for latex
  finduses	finds uses of identifiers
 
These pieces are combined by the scripts in the shell directory to
provide more than just weaving and tangling:
 
  noweb		analog of nuweb
  notangle	analog of TANGLE
  noweave	analog of WEAVE
  nountangle	tangle, but keep interleaved documentation in comments
  noroots	print names of all root chunks in a noweb file
  nocount	count number of lines of code and documentation.
  nodefs	extract defined identifiers for noweave -indexfrom
  noindex	build an external index for multi-file documents
 
noweb has been used for four years both at Princeton and elsewhere.
It has been used for tens of thousands of lines of code in such
languages as awk, C, C++, Icon, Modula-3, PAL, perl, Promela, and
Standard ML.
 
If you already know you want to use noweb, you need only install it
and read the manual page.  If you're just curious about noweb, a sales
pitch appears in the technical report in xdoc/ieee.tex.  This paper
describes version 2.3, so it's somewhat out of date.
 
WHAT YOU GET IN THIS DISTRIBUTION
 
This distribution contains the following directories:
  contrib	software contributed by noweb users
  examples	parts of noweb programs in different languages
  icon		Icon code for nonstandard weave and cross-referencer
  lib		noweave's cross-referencer
  shell		the shell scripts that make up the actual commands
  src		source code for nt and markup
  tex		supporting tex code for /usr/local/lib/tex/macros
  xdoc		man pages and a technical report (named to be unpacked last)
where appropriate, these directories have README files of their own.
Distributions available by ftp also have DOS binaries, which are
always out of date:
  DOS		zip file containing old MS-DOS binaries
 
WEAVING --- A TAR PIT
 
The worst aspect of literate programming is the enormous amount of
time wasted wrangling over what ``woven'' output should look like.
Although noweb does no prettyprinting, it is not entirely immune---
several people have complained about noweave's output or have sent me
changes that add more options to noweave.  I resisted for years, but
with version 2.5 I finally succumbed.  I let the number of options to
noweave double, and I have provided for too many options and hooks for
customizing the latex output.  I won't let it happen again.
 
noweb doesn't try to be all things to all programmers, but it is very
easy to change.  If you don't like noweave's formatting, you can read
tex/support.nw to learn how to customize it; look for the words
``style hook.''  (Reading noweb.sty directly is not recommended.)  For
simple formatting, it might be easier to throw away noweave and make
your own.  To help you get started, the shell directory contains
noweave.simple, a simplified version of noweave that Dave Hanson
created for use with C programs (it can't handle code with @ signs).
The article in xdoc/ieee.tex explains the intermediate language that
noweb uses to represent literate programs.
 
The intermediate language makes it possible to extend noweave with a
language-dependent prettyprinter, as shown by contributions of an Icon
prettyprinter by Kostas Oikonomou and a guarded-command prettyprinter
by Conrado Martinez-Parra.  (I haven't written a prettyprinter myself
because my experience with Spider taught me that prettyprinting is far
more trouble than it's worth.)  Further contributions of
prettyprinters are welcome.
 
noweb comes with two cross-referencers for use with noweave.  The
standard one is written in awk, because that's what everybody has.
There is also one written in Icon, which is slightly better because it
ignores case when alphabetizing chunk names. See the INSTALL file for
more details.
 
Cross-referencing makes formatting even more of a tar pit; the
cross-referencer itself takes about 300 lines, and extensive LaTeX
support is also required.  I haven't made the attempt to write
cross-reference code for plain TeX.  Anyone who has ideas for reducing
the number of options or for other ways to restore sanity to the
situation is urged to write to norman@bellcore.com.
 
INDEX AND IDENTIFIER CROSS-REFERENCE
 
To noweb, any string of nonwhite characters can be an identifier.  A
human being or a language-dependent tool must mark definitions of
identifiers; noweb finds the uses using a language-independent
algorithm.  The algorithm relies on an idea taken from the lexical
conventions of Standard ML.  Characters are divided into three
classes: alphanumerics, symbols, and delimiters.  If an identifier
begins with an alphanumeric, it must be delimited on the left by a
symbol or a delimiter.  If it begins with a symbol, it must be
delimited on the left by an alphanumeric or a delimiter.  If it begins
with a delimiter, there are no restrictions on the character
immediately to the left.  Similar rules apply on the right-hand side.
The default classifications are chosen to make sense for commonly used
programming languages, so that noweb will not recognize `zip' when it
sees `zippy', or `++' when it sees `++:='.  This trick works
surprisingly well, but it does not prevent noweb from spotting
identifiers in comments or string literals.
 
The basic assumption in noweb is that a human being will identify
definitions using the
@ %def mumble foo quux
construct.  I have, however, found it very useful to write simple
filters that attempt to identify global definitions automatically.
Filters for Icon, TeX, and yacc all take about 30 lines of Icon code
and are included in the noweb distribution.  Contributions for other
languages are encouraged.  If you write a filter of your own, you can
put it in the $LIB directory with a name like `autodefs.pascal'.
 
noweave -index works well for short programs, but nodefs, noindex, and
noweave -indexfrom are there for large multi-file programs,  See the
noindex man page for details.
 
NOTES
  xdoc/ieee.* contains a paper that has been submitted to IEEE Software.
  You must `make install' before attempting to format the paper, since
  it uses the noweb document style option.  This paper doesn't discuss
  features that are new in version 2.5.
 
  The paper documents the representation of noweb files that is used
  by the noweb tools, in case you want to write any tools of your own.
  Simple tools (e.g. count the number of lines of interleaved
  documentation) are trivial.  If you write any tools, or you want
  tools written (e.g. prettyprinters, index generators), let me know.
 
  The icon directory contains Icon versions of many of the pipeline
  stages.  If you want to adapt noweb to work with a text processor
  other than TeX or latex, they might provide a better starting point.
  I confess that the whole system should have been written in Icon from
  the beginning, but I'm not going to do it over.  Icon is available by
  anonymous ftp from cs.arizona.edu.
 
  I have a standing offer open to troff users: I will adapt noweb to
  troff if you will tell me what the output should look like and you
  will try to use the results.
 
  Thanks to Preston Briggs for the Aho-Corasick recognizer, and for
		helpful discussions.
  Thanks to Dave Hanson for cpif.
  Thanks to Dave Love for LaTeX wizardry.
  Thanks to Joseph Reynolds for prodding me to fix [[...]].
  Thanks to Lee Wittenberg for the DOS binaries.
 
Send comments or questions to norman@bellcore.com.  
 
I enjoy hearing from noweb users; if you have enjoyed noweb, why not
send me a local postcard for my collection?  My address is:
 
  Norman Ramsey
  Bellcore
  445 South Street
  Morristown, New Jersey 07960
               USA
 
COPYRIGHT
 
Noweb is copyright 1989-1993 by Norman Ramsey.  All rights reserved.
 
You may use and distribute noweb for any purpose, for free.  You may
modify noweb and create derived works, provided you retain the
copyright notice, but the result may not be called noweb without my
written consent.  You may not sell noweb itself, but you may do
anything you like with programs created with noweb.
 
Noweb is not a Bellcore product.  Bellcore makes no warranty and
accepts no liability for any software in this distribution.  If you
find something useful, we're all surprised.
 
From greyham@research.canon.oz.au Fri Oct 29 08:00:58 GMT 1993
Date: Fri, 29 Oct 1993 08:00:58 GMT
From: greyham@research.canon.oz.au (Graham Stoney)
Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU
To: LitProg@SHSU.EDU
Subject: c2man reviews needed by Friday 5 November 1993 (Hassle, Hassle, ...)
 
This is a final prod to anyone interested in reviewing patches 10 thru 17 to
c2man. I'd like to get all reviews in by Friday 5 November 1993 so these
patches can be posted as soon as possible.
 
c2man is an automatic documentation generator which generates functional
interface documentation from C source code and comments. Patches 10 thru 17
to c2man are currently under review in comp.sources.reviewed. If you are a
C user and are interested in not having to write documentation manually,
please consider reviewing these patches.
 
With this new version of c2man, OS/2 and MSDOS are supported, and texinfo
output can be generated in addition to the usual nroff -man.
 
No reviews have been recieved as yet, which is suprising considering the
wide potential user base. It may be that everyone is leaving it to everyone
else; in other words, to no-one - and that makes the whole review process
break down. We want patches expedited, so please consider participating in
this review, and if you do fetch them, _please send in a review_. If you're
short of time, you don't need a big speil; just a "OK" or "It's busted" is
fine, but please send _something_ in.
 
Also, If you are already using c2man at patchlevel 17, please consider sending
in a review.
 
[comp.sources.reviewed Moderator's info]
 
This package contains a C program to convert C source to `nroff -man' input,
plus 7 patch files and a shell dirver to unpack the lot.  This product has
been reviewed and posted before.  Check it out.
 
If you are interested in *reviewing* this package send a mail message
to the csr mail-server:
 
	To: csr@cc.purdue.edu
	Subject: send c2man
 
	<thanks>
	<sig>
 
and the mail server will send you the stuff.
 
Initial comments:
	- I unpacked the parts, and applied the patches.
	- I include a script to do the same for you
	- I configured the product and it runs on sun4-sunos4.1.3.
	- you get 17 parts, but 3 of them are padding for the mail-server
 
If you need help with the mail-server send a note like
	To: csr@cc.purdue.edu
	Subject: help
 
	<thanks>
	<sig>
 
Graham
 
-- 
Graham Stoney, Hardware/Software Engineer
Canon Information Systems Research Australia
Ph: + 61 2 805 2909	Fax: + 61 2 805 2929
 
From collins@ny.cs.wm.edu Fri Oct 29 10:59:28 GMT 1993
Date: Fri, 29 Oct 1993 10:59:28 GMT
From: collins@ny.cs.wm.edu (Bob Collins)
Reply-To: LitProg@SHSU.edu, collins@NY.CS.WM.EDU
To: LitProg@SHSU.EDU
Subject: Re: Literate programming in Framemaker.
 
Folks,
 
   This is my one response to my complaint about TeX and Knuth.
I have the feeling this might turn into a jihad. FrameMaker is
a commercial product suitable for producing large printed and
hypertext documents, especially those that need maintenance and
involve technical material and drawings. FrameMaker cannot do all
things and some of what it does it does poorly. FrameMaker is
not even my word processor of choice, but I use it because of
its universality.
 
   Joachim Schrod wrote
> How do you edit your FrameMaker documents on more than 40 different
> operating systems, ranging from 8086 PCs to Crays?
 
   FrameMaker is available on all the major platforms that can
support it, that is, that have sufficient power and memory and
that allow bitmap displays. This means most Unix systems, Macs,
and MS Windows. Don't blame FrameMaker if it doesn't work on an
AT. One cannot have its power for free. TeX is a filter -- all
it does is translate from one form to another, like a compiler.
Therefore it needs far fewer resources. FrameMaker integrates
what TeX does, what your favorite editor does, what previewers
do, what drawing programs do, and what dvi2lp utilities do. Face
it -- how many of you wished that you could edit your preview
when you found some error that you overlooked? How many of you
preview on an 8086?
 
   Joachim Schrod wrote
> How do you use FrameMaker in a convenient way as a background system?
 
   FrameMaker (on Unix) has both a macro system and a batch system.
Both allow background processing. [In a silly moment I might ask,
how do you allow foreground processing of TeX commands while you edit?]
 
   Joachim Schrod wrote
> How do you use many languages? (Remember: Not everyone writes in
> English...)
 
   Last I checked, FrameMaker is available in 11 languages. (12, if
you separate American English and Proper English.) This support is
available in the dictionaries, thesaurus, system variables (like dates),
and numbering schemes.
 
   Mark Friedman wrote
> I'll add 2 even ``lower-end'' systems to the editing list --- I often take
> notes & revise drafts on an _ancient_ Tandy T102 (not even MS-DOS, but it can
> spit out ascii), and I have 3 daughters (ages 11 to 18) that ``share'' an
> 80286 to (La)TeX documents created on a trio of (also ancient) Apple ]['s.
> The point, of course is quite simple --- if it can produce ascii outout,
> _anything_ can be used for entry & editing.
 
   One can import text into FrameMaker. FrameMaker will even get rid of
extraneous spaces and turn straight quote marks into curly ones while it
imports (if you want). In addition, FrameMaker supports MML import. MML
stands for Maker Mark-up Language and is a SMGL-like form for typographic
conventions. So your kids can edit their instructions in their text,
read it into FrameMaker, and then edit the preview-like display.
 
   Mark Friedman wrote
> As for the oft cited difficulty of learning LaTeX, my daughters have done _all_
> their school reports since 3rd grade as well as lots of other ``documents''
> (my 15 year old produces Girl Scout troop meeting minutes, plans & budgets),
> in English, French, German, Spanish and even ASL (American Sign Language --- 
> a one-off report using a wonderful `hands' Metafont file). Overkill? Absolutely,
> but they happen to love it (they're even more critical of sloppy or ugly
> documents that I am, and I thought I was the perfectionist in the family).
> It has also led to various amusing incidents, like when my oldest was in 7th
> grade her English teacher stated that there was ``only one right way to format
> a bibliograpy''. Allyson's response was to take my copy of the Chicago Manual of
> Style to school, along with about a dozen versions of her assignment's
> bibliography, all formatted by different .bst styles, and ask which one
> was the ``right'' one... 
 
   Well, Mr. Friedman has a smart set of kids. I congratulate them and him.
I have my own set of computer-literate kid stories, and I will be pleased
to share them. I wish all children had entre to computer-wise parents and
equipment at the earliest age. It would help me as a university professor.
[My favorite kid story is how my son, when 5, learned how to use a paint
program by memorizing what the menus did. He could not read, but he knew the
alphabet.]
 
   However, I have gone through the hassle of trying to help graduate students
try to write using LaTex. The learning curve is steeeep. In fact, some of
our faculty couldn't figure out how to get rid of a space before a grammar
production in our comprehensive examination question list. The number of
macros (written by different folks) confused the issue. The smartest people
can get turned off by TeX. Is literate programming closed to them?
 
   Let's get serious, however. For those who know, TeX works great. Just
like punch cards for editing. However, most people found interactive editing
much easier. And those who were used to punch cards sometimes found it
difficult or unnecessary to change. And they were right. You can do anything
you want with a punch card. Make a wish list for literate programming. Don't
worry about how it can be accomplished, or how the typesetting is done. I
think that most of us would like to edit the finished product rather than
the marked-up product. [I would like to do it by voice, e.g., Bob Collins:
Show me the code fragment for the input loop. Computer: Did you mean code
fragment or chunk?] At the least, this means interactive TeX. Let's aim
for that. Meanwhile, I think that FrameMaker offers a reasonable alternative.
 
   These are my final words. Flame on.
 
Bob Collins, collins@cs.wm.edu
CS Dept, Coll of Wm & Mary (est 1693)
 
From schrod@iti.informatik.th-darmstadt.de Fri Oct 29 13:20:36 GMT 1993
Date: Fri, 29 Oct 1993 13:20:36 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: New version of WinWordWEB
 
In article <16900707@MVB.SAIC.COM>, Lee Wittenberg <leew@pilot.njin.net> writes:
> Stephen McKearney has made a few improvements to the original
> WinWordWEB, [...]
 
> I've  made
> the new, improved version (wordweb2.zip) available for anonymous ftp 
> in the pub/leew directory of bart.kean.edu.  The original version is
> still there, as well.  I understand that there are several ftp sites
> out there that also make copies of WordWEB available.  I'd appreciate
> it if everyone could keep traffic on bart down to a minimum, and wait
> until these other sites get the new version (assuming that they do).
 
Literate Programming Archive:
 
	ftp.th-darmstadt.de [130.83.55.75]
	directory pub/programming/literate-programming/machines/ms-dos
	files wordweb*
 
(Usually I mirror weekly, on Sundays. I triggered it by hand this
time.)
 
> This brings me to the problem of maintenance.  WinWordWEB was intended
> to be an unsupported product, but there seems to be enough interest in
> it that I feel a moral responsibility to provide some sort of
> support.
 
:-) You're listed as the contact person at the LPA. ;-)
 
--
Joachim
[THD Literate Programming Archive, maintainer]
 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From rhl20@cas.org Fri Oct 29 13:20:36 GMT 1993
Date: Fri, 29 Oct 1993 13:20:36 GMT
From: rhl20@cas.org (Robert H. Ledwith)
Reply-To: LitProg@SHSU.edu, rhl20@cas.org
To: LitProg@SHSU.EDU
Subject: Re: An Automatic C++ documentation compilation p
 
I am currently struggling with creating low-maintenance C++ documentation and have
an additional comment concerning automatically collecting and presenting 
documentation for C++ programs.  This comment actually applies to any object-oriented
programming language.
 
When a programmer is faced with documentation for a class, it is desirable to have the
entire interface for the class presented in a complete and well organized manner.  In addition
to the problems and issues involved in presenting information for C language program units,
one is now faced with inheritance.  If class B is derived from class A, when I inspect the 
documentation for class B, I wish to see class A's public interface as well.  This situation is
potentially very messy, when you begin to take into account multiple inheritance and run-time
binding (such as mixins).  When I've looked at this problem, I have been unable to come up
with any modest-effort solutions to it.  Has anyone else thought about this problem and come
up with workable solutions?
 
From bdubbs@tis.kelly.af.mil Fri Oct 29 13:38:33 GMT 1993
Date: Fri, 29 Oct 1993 13:38:33 GMT
From: bdubbs@tis.kelly.af.mil
Reply-To: LitProg@SHSU.edu, bdubbs@tis.kelly.af.mil
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In <2177@se.alcbel.be>, cgra@btma74.nohost.nodomain (Chris Gray) writes:
>
>In article <2abjai$965@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes:
>
>In article <16782125@mvb.saic.com>, Lee Wittenberg  <leew@pilot.njin.net> wrote:
>
>>The problem with `chunk' is that it does have this use in Psychology.
>>The more complete term is `cognitive chunk'.  I have proposed the term
>>`cognitve block' in a paper now being refereed.  
>
>Ooerr.  In that context `cognitive block' makes me think of `mental block'
>or `writer's block'.
>
 
I see.  We are talking about nouns and you think about verbs. ;-)
   -- Bruce
 
From mynard@vmark.co.uk Fri Oct 29 13:55:30 GMT 1993
Date: Fri, 29 Oct 93 13:55:30 GMT
From: mynard@vmark.co.uk (Alan Mynard)
Reply-To: LitProg@SHSU.edu, mynard@VMARK.CO.UK
To: LitProg@SHSU.EDU
Subject: Re: FrameMaker
 
From article <1993Oct28.170420.18976@kocrsv01.delcoelect.com>, by c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar):
> 
> I am wondering whether someone will post some details on FrameMaker.
> Is it a desktop publishing program ? (I did note that it has hypertext
> capabilities.) Several years ago, I played around with PagMaker a little bit.
> 
> How would FrameMaker compare with Interleaf or Teamwork (the two packages
> available here) in the general type of functions provided. Does it belong in teh
> same (utility) class or would it be used for other purposes usually ?
 
FrameMakeer is a DTP with similar capabilities to Interleaf. It runs on
UNIX workstations and there is a cut-down version that runs under Windows
on PC's.
 
Alan
 
-- 
Alan Mynard			  ---		VMark Software Ltd.	
eMail: mynard@vmark.co.uk	\/o o\/		Power House, Davy Avenue,
Tel: +44 908 234990		 \ | /		Knowlhill, Milton Keynes,
Fax: +44 908 234992		  |v|		MK5 8HJ, UK	
 
From rudolf@ergon.ch Fri Oct 29 14:44:20 GMT 1993
Date: Fri, 29 Oct 1993 14:44:20 GMT
From: rudolf@ergon.ch (Jim Rudolf)
Reply-To: LitProg@SHSU.edu, rudolf@ERGON.CH
To: LitProg@SHSU.EDU
Subject: FrameMaker for LP output, not input
 
Charles Bass <chuckb@u.washington.edu> writes:
>I think that your idea with framemaker is the only way to go.
 
Personally, I think using FrameMaker is a good idea, but not
necessarily by *editing* in FrameMaker.  We are just a bunch of
programmers who use vi and work fast in it.  We want to be able
to document our code too, and embedding the doc in the source
code (keeping in mind the readability of the source for us
programmers, of course) means we are more likely to update the
doc when we update the code.
 
Our solution was to write a couple perl scripts to do documentation
generation for us.  One script scans the source file for a few
keywords that can describe the entire module or individual procedures.
Once all the info for a file is collected, another set of scripts will
create a file either in man page or MML format.  The two formats are
quite different, as the man page format is used internally, and the MML
format is used to make a FrameMaker book for customers.  Other back-end
scripts could easily be written when needed.
 
We've found this to be a good combination for us.  Has anyone else had
any experience (good or otherwise) with this approach?
 
Cheers,
 
Jim
 
-- 
 
Jim Rudolf
Ergon Informatik AG
rudolf@ergon.ch
 
From sriram@glock.tcs.com Fri Oct 29 14:44:20 GMT 1993
Date: Fri, 29 Oct 1993 14:44:20 GMT
From: sriram@glock.tcs.com (Sriram Srinivasan)
Reply-To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM
To: LitProg@SHSU.EDU
Subject: Re: FrameMaker
 
In article <1993Oct28.170420.18976@kocrsv01.delcoelect.com>, c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) writes:
> 
> How would FrameMaker compare with Interleaf or Teamwork (the two packages
> available here) in the general type of functions provided. Does it belong in teh
> same (utility) class or would it be used for other purposes usually ?
 
FrameMaker competes directly with Interleaf. Amusing aside : If you type 
"InterLeaf" in a FrameMaker document, the spelling checker asks if you want to 
correct it to "FrameMaker". 
 
Sriram
(sriram@tcs.com)
 
From jacojn@inet.uni-c.dk Fri Oct 29 14:47:44 GMT 1993
Date: Fri, 29 Oct 1993 14:47:44 GMT
From: jacojn@inet.uni-c.dk (Jacob Nielsen)
Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK
To: LitProg@SHSU.EDU
Subject: Practical language independecy
 
When we're programming in a language independent literate programming 
system, (e.g. nuweb), why not make the programming language clear to 
the reader? Normally we do one of two things:
 
1) rely on the readers expertice with programming languages to detect
which language we're programming in now.
 
2) mention the programming language in the documentation text.
 
Both options have clear drawbacks (required expertice when reading 
the documentation and bad language in the text)
 
These problems could be solved by making the choice of programming
language a part of the definition of a scrap/macro.
 
So, instead of writing (in nuweb):
 
This part is written in the C language (see [K&R])
 
<Main Function> =
  main()
  {<Variables>
   <Function prototypes>
   <Functions>
  }
 
we could write something like:
 
<Main Function> =
  main()
  {<Variables>
   <Function prototypes>
   <Functions>
  }
\smallfont{Scrap written in the C language}
 
This would also eliminate the need for a web comment (like '@%')
used to hide things like '-*-*-C++-*-*-', that users of the
emacs nuweb mode can use.
 
As an user of nuweb, I suggest that we adopt an new optional option '@L' in
the definition of scraps, that specifies the language of the scrap.
  It should be optional because in projects where we have one main
language, it could clutter the documentation with multiple 
'language: C++' and therefore be of no practical use.
 
PS: English is not my native language, so please bare with my typos :-)
 
Jacob Nielsen
--
Email: jacojn@inet.uni-c.dk (my private account)
  or   bc898574@bbar.dth.dk (my account at the university)
 
From preston@cs.rice.edu Fri Oct 29 13:03:56 CDT 1993
Date: Fri, 29 Oct 93 13:03:56 CDT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@shsu.edu
Subject: mailing list or newsgroup?
 
Are we a newsgroup yet?
Is it supposed to be comp.programming.literate?
 
Thanks,
Preston
 
From koopman@sgi84.ctc.com Fri Oct 29 18:18:59 -0400 1993
Date: Fri, 29 Oct 93 18:18:59 -0400
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, collins@NY.CS.WM.EDU
Subject: Literate programming in Framemaker.
 
Bob Collins wrote:
 
>   This is my one response to my complaint about TeX and Knuth.
>I have the feeling this might turn into a jihad. FrameMaker is
>a commercial product suitable for producing large printed and
>hypertext documents, especially those that need maintenance and
>involve technical material and drawings. FrameMaker cannot do all
>things and some of what it does it does poorly. FrameMaker is
>not even my word processor of choice, but I use it because of
>its universality.
 
I don't believe you'll see an uprising from your comments on TeX.  I
have not heard anyone pining over the punch card machine nor against
an interactive TeX editor/previewer.  The TeX hacks promote the
capability, portability and succintness of the language.  Whether or
not FrameMaker is as clever as TeX seems somewhat irrelevant.  If you
want a FrameMaker web then what qualities of the web are critical and
which of these 'requirements' are met by FrameMaker and not met by
TeX.  That is, why does literate programming in FrameMaker detract
from literate programming in TeX?  Does FrameMaker read TeX input, or
more importantly, can FrameMaker read a CWEB, FWEB, etc. web and not
munge it beyond recognition?  Let's not hack each other up in
religious wars over the "right" editor or typesetting mechanism.
Let's focus on the benefits and needed improvements in the literate
programming techniques at hand, instead.
 
Peace be with the Literati,
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
 
From calderwt@redbaron.wosc.osshe.edu Fri Oct 29 23:51:33 GMT 1993
Date: Fri, 29 Oct 1993 23:51:33 GMT
From: calderwt@redbaron.wosc.osshe.edu (Timothy Calderwood)
Reply-To: LitProg@SHSU.edu, calderwt@REDBARON.WOSC.OSSHE.EDU
To: LitProg@SHSU.EDU
Subject: Fast Sort
 
I am not sure this is where to ask, but for a class project I have, I need a 
really fast sort on 10,000 random integers.  If anybody out their has any 
algorithms or code that might help, drop me a note.  I really dont care how 
ugly the code might be.
 
Thanks  
 
From ae1181t@stnfor.ae.ge.com Fri Oct 29 21:06:53 -0400 1993
Date: Fri, 29 Oct 1993 21:06:53 -0400
From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik)
Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM
To: LitProg@SHSU.edu
Subject: Re: FrameMaker for LP output, not input
 
People seems to be missing the main point about litprog. It is not just
a documentation scheme! You start from the design phase and use whatever
form of editor/TP you want to explain the code and write the code in a 
way that is independent of the whims of the compiler that you will use.
In the end, the final product should resemble a `book'. Because of these
points I dont think c2man and others like it are litprog tools. You can
use framemaker/interleaf but someone has to write some expansion to it
so that `tangle' command is available in the menu (like the WinWordWeb).
No one is forcing TeX/LateX but these tools are FREE and widely available.
People should not be flaming each other instead if you want a framemaker
litprog tool just create it and announce it to the net. For myself
I cannot see how hypertext helps since I like the printed output! I use
interleaf at work and all the formulas and graphs do not look the same
on the screen as printed on paper, and are hard on the eyes.
My $0.02 contribution.
Osman
 
From marcus@x4u2.desy.de Sat Oct 30 01:19:46 GMT 1993
Date: Sat, 30 Oct 1993 01:19:46 GMT
From: marcus@x4u2.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: An Automatic C++ documentation compilation project.
 
The following is taken from Leif Loennblad's "CLHEP-Class Library for
High Energy Physics" project. Leif advocates and distributes the 'classdoc'
awk(1) script which I have found to be very useful too. It is one of
the options in an ongoing effort to make C++ library code (in HEP)
fully accessible through the World Wide Web (since man pages can be
turned into HTML on the fly).
 
---------------------- from CLHEP/README --------------------------
The classdoc program
 
All the header files in this distribution are written to be easily
converted to a unix-style manual page by the classdoc program written
by Dag Bruck. I think that this program provides a very easy-to-use
class documentation - simply write the code and put in comments where
you usually would put them (there are of course also a few small
tricks you can use to get nicer output) and classdoc will do the
rest.
-------------------------------------------------------------------
 
You can get the classdoc(1) program as part of CLHEP from the freeHEP
server in any of the CLHEP releases from
 
	freehep.scri.fsu.edu:/hep-projects/CLHEP/
 
Needless to say: I myself would prefer people would write their code
using one of the "true" literate programming tools. But classdoc(1)
isnt too bad if you'd like to save the effort.
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From Sikander Fri Oct 29 22:35:45 CDT 1993
Date: Fri, 29 Oct 1993 22:35:45 CDT
From: Sikander Waheed <U17868@uicvm.uic.edu>
Reply-To: LitProg@SHSU.edu, U17868@UICVM.UIC.EDU
To: LitProg@SHSU.EDU
Subject: Quality metrics for OO methods?
 
I have two questions:
1. With the advent of Object-Oriented development methods, what are some
   of the productivity metrics that work better with object-orientation?
   By productivity here I mean Programmer's productivity.
2. What are some of the Object-Oriented quality metrics? That is only
   those metrics that are related to OO.
 
Thanks,
Sikander
 
From stewart@cs.umd.edu Fri Oct 29 22:35:45 CDT 1993
Date: Fri, 29 Oct 1993 22:35:45 CDT
From: stewart@cs.umd.edu (G. W. Stewart)
Reply-To: LitProg@SHSU.edu, stewart@CS.UMD.EDU
To: LitProg@SHSU.EDU
Subject: Re: Inline comments and abstraction
 
In article <CFnv8A.M9v@sadis01.kelly.af.mil> bdubbs@tis.kelly.af.mil writes:
#In <2177@se.alcbel.be>, cgra@btma74.nohost.nodomain (Chris Gray) writes:
#>
#>In article <2abjai$965@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes:
#>
#>In article <16782125@mvb.saic.com>, Lee Wittenberg  <leew@pilot.njin.net> wrote:
#>
#>>The problem with `chunk' is that it does have this use in Psychology.
#>>The more complete term is `cognitive chunk'.  I have proposed the term
#>>`cognitve block' in a paper now being refereed.  
#>
#>Ooerr.  In that context `cognitive block' makes me think of `mental block'
#>or `writer's block'.
#>
#
#I see.  We are talking about nouns and you think about verbs. ;-)
#   -- Bruce
#
 
A trip to the dictionary is useful here.  My American Heritage (1st
edition) defines
 
fragment 1. A part broken off or detached from a whole.  2. Something
         incomplete; an odd bit or piece.  3. An extant part of an
         unfinished or lost text.
 
and
 
chunck. 1. A thick mass or piece of something.  2. A fair or
        substantial amount.
 
Definitions, of course, vary from dictionary to dictionary; but the
point is that the word "fragment" stresses the relation of the part to
the whole, unlike chunk, lump, clump, scrap, etc.  It seems to me that
"fragment" fits naturally into the literate programming framework,
whereas the alternatives are slightly forced.
 
Pete Stewart
 
From preston@dawn.cs.rice.edu Thu Nov 18 00:10:51 GMT 1993
Date: Thu, 18 Nov 1993 00:10:51 GMT
From: preston@dawn.cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU
To: LitProg@SHSU.EDU
Subject: Re: installing nuweb on a pc
 
>On Tue, 16 Nov 1993, Dave Thompson wrote:
>I want to program on my pc.
 
>Nuweb on my pc requires go32.exe, which won't run under winders.  I
>know I can close winders, but shouldn't be required to dump my
>principal operating evnironment
 
I agree that you ought not have to dump Windows or your PC to enjoy
literate programming.  I disagree that nuweb requires go32.exe
(whatever that is) to run on a PC.
 
The whole question comes up, I believe, because an early version was
compiled for the PC using gcc (which somehow made code relying on
go32.exe to work).  This version was put out somewhere for ftp and a
lot of people grabbed it and have been hacking happily away.
 
As an alternative, I recommend that new users (and old ones, too) get
the latest version and start fresh with your favorite C compiler.  The
latest version, along with several large examples, are always
available for anonymous ftp from cs.rice.edu, in the directory
public/preston.  Alternatively, you can send me a note and I'll e-mail
the latest version to you.
 
The lastest version is 0.87
 
I can't promise everyone it'll compile with their compiler since there
are so many compilers out there (especially on PCs).  However, it's
getting closer all the time, primarily due to the efforts of all the
users who beat on it 'til it works and then tell me what they did.
 
In the meantime, I'm working on a new version which will correct all
the known portability problems, along with a few other complaints at
the same time.  Known portability problems are:
 
	thinks / is used to separate directory names inside a path name
 
		Should make it an easily customized definition.
 
	thinks a tab should be 8 spaces
 
		A toughie, but I can expose it for easy customization.
		Fortunately, it's also relatively unimportant.
 
	uses long names that aren't unique in the first 6 characters
 
		Some linkers still rely on this.
 
	uses tempnam()
 
		The ANSI alternatives don't work so well on my
		systems (though they seem to on PCs).
		I need to write my own that'll work anywhere.
 
	assumes alignment to 8 bytes will be adequate when allocating
	memory
 
		Probably will be for years, but 4 was fine for years too!
		Need to throw out the special memory allocator.
 
	the conventions for command-line arguments and error reporting
	differ widely on different operating systems.
 
		No clue what to do about this.  Probably ignore.
 
If you've got more (that haven't already been fixed in 0.87), let me
know soon.
 
Preston Briggs
 
From Zdenek Thu Nov 18 10:03:44 MET 1993
Date: Thu, 18 Nov 93 10:03:44 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, R.Kooijman@ET.TUDELFT.NL
Subject: Re: WEB-Wars (Was: Which one [F|C|NO|NU|Funnel|Scheme]WEB? Flame war)
 
On Tue, 16 Nov 1993 23:32:56 +0100 (MET) Richard Kooijman said:
>On Tue, 16 Nov 1993, Dave Thompson wrote:
>
>> I want to program on my pc.  [No guffaws out there!]  Therefore, the
>> tool of choice must run on my hardware platform.  If you tool writers
>> out there want me to program literately, then provide me with the tools.
>
>I didn't see offers in hard cash here.
>
>> Furthermore, it its too difficult to install, I won't do it.  I don't
>> have the time.
>
I work only on a PC. I took CWEB ported to MS-DOS by Hans Hermann Bode. I
just unzipped it, placed to directory which is scanned automatically and
everything worked. I downloaded the LaTeX support made by Joachim Schrod,
put the cweb.sty file into the directory where TeX wants the style files
and everything worked. I use TeX and LaTeX which I received from the
Czechoslovak TeX Users Group (it is good to ask your nearest TeX Users Group
fro help). I suppose that you managed to install e.g. Windows and some
compilers but according to my own experience installing MS Windows is much
more difficult than installing CWEB.
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From Zdenek Thu Nov 18 10:25:27 MET 1993
Date: Thu, 18 Nov 93 10:25:27 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, chris@KD3BJ.UUCP
Subject: Re: LP Failure Story (Scoping)
 
On 17 Nov 93 02:57:42 GMT <chris@kd3bj.uucp> said:
>
>Thank you, everyone that pointed out that there were now SuperDuper
>versions of WEB that answered most of my criticisims. I am now attempting
>to collect and evaluate some of these. With luck I'll find ONE version
>that has most of my wish-list entries in the 3-4 hrs per month I have
>free to experiment with new tools---we don't get much play time
>where I work.
>
>The only unanswered criticism was the issue of scoping. Steve Avery
>made an attempt to answer it, which I find inadequate.
>
>stevea@vast.unsw.edu.au (Steve Avery) writes:
>
>>       I don't go along with your notion of having locality of
>>reference in a WEB. The sort of code you are proposing is working
>>against the grain of what literate programming is about - ie. lots of
>>words not few words :-). If you must have several "Initialize"
>>statements, then they should have different names. This then allows you
>>to easily distinguish between different sections in both the index, list
>>of sections, and code itself.
>
>Clearly Steve understands my complaint about the lack of scoping in
>web. I know this, because he tells me what I do now. Every time I try
>to merge a perfectly good piece of code with another---even if they
>are targeted for separate files---I have to worry about name collisions.
>The ability to abbreviate scrap names makes this worse.
>
>I like all my C files to have the same basic format. Why do I have
>to rename all the sections in the top-level template when I apply it to
>a new module. This is unneeded work and it's error prone.
>
>Although I'd like a flexible scoping system, basic file target scoping
>would help me a lot. Here's one way to do it:
>
>Make @i attach an invisible source filename code on the begining of every
>scrap name in the file that is included. The bulk of tangle and weave
>processing would treat these names as unique, but they'd look the same
>after they are TeX'ed. Next,  rewrite the index generation stuff in weave
>to make this source filename visible again. Lastly, provide an override
>mechanism on the @i and the @< to force global scoping, deleting the
>invisible filename reference.
>
>I think that should do the trick.
>
>--
>73 de KD3BJ (Chris Nadovich, chris@kd3bj.ampr.org)
 
I am afraid that generally files input @i are not easily includable into
any web. However, if they contain only functions and/or class implementations,
I fell better to build a private library. I do it with my functions and classes
and I am rewriting the old libraries into CWEB. Thus my programs are smaller
and compile faster. Just as you put
 
#include <stdio.h>
 
I use
 
#include <myclass.h>
 
or something similar. Then I specify the library in the project so that the
linker can find it. If I don't remember something, I know there is another
volume of a woven file and I have to look there for explanation.
 
Regards
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From Zdenek Thu Nov 18 10:35:34 MET 1993
Date: Thu, 18 Nov 93 10:35:34 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, Mark.Probert@NMS.OTC.COM.AU
Subject: Re: Reuse of LP code
 
On Thu, 18 Nov 93 9:13:57 GMT <Mark.Probert@nms.otc.com.au> said:
>I got to thinking about using LP tools with the more modern
>languages, such as C++ and Modula-2, and wondered, "Does anyone
>have any experience with reuse of LP code?"
>
>--
>mark.    (probertm@nms.otc.com.au) ph: (02) 339 3953  fax: (02) 339 3688
 
As I wrote as a response to another's posting, if I want to have some
code reusable, I design my private library (functions, class implementation).
Then I need the .h files and .lib file. Somewhere I have the printed vowen
file so that I can refer to it.
 
Regards
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete.
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From marcus@x4u2.desy.de Thu Nov 18 11:27:35 GMT 1993
Date: Thu, 18 Nov 1993 11:27:35 GMT
From: marcus@x4u2.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: WEB-Wars (Was: Which one [F|C|NO|NU|Funnel|Scheme]WEB? Flame war)
 
>>>>> "Richard" == Richard Kooijman <R.Kooijman@et.tudelft.nl> writes:
>> That's enough of this tirade.  I'll conclude with an apology in
>> advance and a wish that readers of this post will ignore the
>> emotionalism/passion of my statements and consider what little
>> logic appears herein.  I've got to go teach class -- pity my
>> students.
 
Richard> First tirading and then apologizing? Why didn't you think
Richard> before that and use the delete-line feature of your editor?
Richard> If you did have so many problems compiling nuweb and noweb,
Richard> why didn't you simply ask someone to help you instead of
Richard> demanding and tirading afterwards?
 
I value Thompson's posting and the questions contained in it as
valuable contribution to the problems more than 1/2 of the readers of
this list have --
installation (to mention only one of the points Dave Thompson touched upon)
can pose a serious problem - I am doing all the installations for
the fweb, cweb, nuweb and noweb tools on 3 clusters of our lab and I
often felt that if I would be leaving most probably 'mere users' of 
LitProg tools may not want to carry on with that (it takes too much of
my time anyway).
 
  Moreover, I don't like the style of Kooijman's answer - it lacks the
humbleness which I appreciate from many knowledgeable people on c.p.l.
 
  The posting by Eitan Gurari on 'minimal configurations' to get
started with literate programming is one of the best I have seen. It
hadnt been posted I assume hadnt Dave formulated his problems.
I think we need more of this approach if we want LitProg to become a 
widely used paradigm and not just an academic exercise. 
 
Respectfully,
Marcus Speh
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From marcus@x4u2.desy.de Thu Nov 18 13:15:19 GMT 1993
Date: Thu, 18 Nov 1993 13:15:19 GMT
From: marcus@x4u2.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: CLiP for Unix available
 
I have updated all the links to the CLiP ftp directory on the
World Wide Web pages on Literate Programming. Please report
difficulties if there are any.
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Internet: <marcus@x4u.desy.de>, <na.speh@na-net.ornl.gov>
 
From Richard Thu Nov 18 15:47:27 +0100 1993
Date: Thu, 18 Nov 1993 15:47:27 +0100 (MET)
From: Richard Kooijman <R.Kooijman@et.tudelft.nl>
Reply-To: LitProg@SHSU.edu, R.Kooijman@ET.TUDELFT.NL
To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
Subject: Re: WEB-Wars (Was: Which one [F|C|NO|NU|Funnel|Scheme]WEB? Flame war)
 
On Thu, 18 Nov 1993, Marcus Speh wrote:
 
> I value Thompson's posting and the questions contained in it as
> valuable contribution to the problems more than 1/2 of the readers of
> this list have --
> installation (to mention only one of the points Dave Thompson touched upon)
> can pose a serious problem - I am doing all the installations for
> the fweb, cweb, nuweb and noweb tools on 3 clusters of our lab and I
> often felt that if I would be leaving most probably 'mere users' of 
> LitProg tools may not want to carry on with that (it takes too much of
> my time anyway).
 
What a lot of people forget is that the tools you can get here are to be
installed by configuring, compiling and copying to binary directories.
If you buy a commercial product, you buy binaries. Binaries for a
certain architecture run out of the box most of the time. Sources need to
be compiled first and this adds up to the complexity/difficulties
during installation. Not only your run-time environment becomes
important, but also your compile-time environment.
 
If you buy a product you may expect support. If your run-time
environment isn't configured right you can ask them for help. 
Binaries make you configure your run-time environment, sources lets
you configure the tools themselves.
 
Thompson had problems installing both sources and binaries of 
LP tools. In the instances he metioned, there were clear prerequisites
or solutions in the accompanying docs. Not very uncommon.
 
There are PD tools who have a sort of auto-configure which determines
your compile time environment. Very nice, but also a lot of work
to make your sources suitable for this.
Products are for free here, please remember that. The designers are
solving problems for others voluntary and in their own time. No
need to tirade, simply ask, they might help and they might not, but don't
start demanding things, now that's lacking humbleness.
 
>   Moreover, I don't like the style of Kooijman's answer - it lacks the
> humbleness which I appreciate from many knowledgeable people on c.p.l.
 
Thompson himself said he was tirading. I have never seen questions here
from him asking for some installation help.
Seeing the other responses, a lot of people have installed several 
products without trouble. Maybe Thompson isn't experienced enough.
Should he be? It can come in handy, compiling and installing software
might require some work sometimes. You simply can't expect
everything to be free.
 
IMHO Thompson was to quick with his tirade and could have asked questions
first. There seem to be a lot of people who succeeded where he failed and
they were not all Gods.
 
A lot of products both PD (copylefted etc.) and commercial will install
without problems on standard computer machines. If you have an extraordinary
machine, or compiler in case of sources, you may be out of luck and
you'll have to work to get it right.
 
For example, Thompson had difficulties with nuweb. This tool compiles
and runs on a lot of UNIX machines/types without hassles. Thompson
has a PC and had a problem with a binary version of nuweb. 
Apparently that version needed the go32 DOS extender.
He could have downloaded the sources which would have compiled fresh
without problems if he had taken a at the README where the solution was.
 
Richard.
 
From Steve Fri Nov 19 01:52:41 +1100 1993
Date: Fri, 19 Nov 1993 01:52:41 +1100
From: Steve Avery <stevea@vast.unsw.edu.au>
Reply-To: LitProg@SHSU.edu, stevea@VAST.UNSW.EDU.AU
To: LitProg@SHSU.edu
Subject: Re: LP Failure Story (Scoping)
 
Chris <chris@kd3bj.uucp> talks about scoping and include files. To be
quite honest, my original idea with the arbitrarily deep sectioning was
to have included files be included at the current level or next level
down (never did work out which was better) in the hierarchy. In this
way, the top level of the hierarchy could simply be a place where the
files were explained and included - supposedly making it possible to
have a whole suite of files easily made into one document. (It would be
possible to denote where a section is from by having the filename in the
margin for each section, and possibly in the list of sections as well.)
 
I talked (or rather emailed back and forward) with Lee Wittenberg about
this, and he pointed out a few flaws, the least of which was the hassle
with what to do with the TeX waffle (sorry, forgot the terminology) at
the front of each web file. There are other hassles too, but I'm sure
there is a way around them given enough thought and coding (it might
mean that some new requirements, like the waffle go in a separate file,
need be imposed on webs).
 
Anyways, if this idea were to be implemented, it might make scoping
easier (okay, it probably would). I still don't like the idea, but that
doesn't mean it shouldn't be implemented for those that do.
 
Oh, for those that haven't guessed, the web I'm talking about is CWEB.
 
	cheers
	-steve
 
p.s. Chris - if you want it so bad, consider putting it in yourself, and
then giving Silvio a copy for a look-see. It may well get into the next
release.
 
p.p.s. I'd be interested in knowing what people think about the idea of
including files at a certain level in the hierarchy. It may also be able
to be over-ridden with a switch on @i (like @i0).
 
From Lee Thu Nov 18 10:14:15 EST 1993
Date: Thu, 18 Nov 93 10:14:15 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, Mark.Probert@nms.otc.com.au
Subject: Re: Reuse of LP code
 
Mark Probert writes:
 
> I got to thinking about using LP tools with the more modern
> languages, such as C++ and Modula-2, and wondered, "Does anyone 
> have any experience with reuse of LP code?" 
>  
> When I code in "straight" C++, for instance, the class definition 
> is in the header and the implementation is in .cc file. But when I
> use an LP tool, both of these are in the same file, as I believe it
> should be. Now, at reuse time, I have either to use the generated
> header, which may be "unreadable" (CWEB), or look at the web, which
> has implementation details that I shouldn't see. 
>   
> The problem appears to be a contradiction between information hiding 
> and correctly documenting code.
>    
> Can anyone shed any light, or have any opinions :-), on this issue?
 
What I do (when I'm diligent) is to generate manual pages for the
class within the web (usually in ``limbo,'' before the first
section).  That way I can maintain the manpages along with the code,
but still xerox them separately for users.  In noweb, I usually have a
\part{Interface}, which contains the manual pages, followed by a
\part{Implementation}, which contains the web proper.  I haven't yet
done any C++ programming in noweb, so I'm not sure where I would put
the class declaration, but I suspect I would keep it in the
Implementation part, saving Interface for purely human issues.
 
Yet another technique stolen from Steve Avery.
 
		-- Lee
		   leew@pilot.njin.net
 
From dmason@uwaterloo.ca Thu Nov 18 16:12:39 GMT 1993
Date: Thu, 18 Nov 1993 16:12:39 GMT
From: dmason@uwaterloo.ca (Dave Mason)
Reply-To: LitProg@SHSU.edu, dmason@uwaterloo.ca (Dave Mason)
To: LitProg@SHSU.EDU
Subject: Re: Literate ML Code
 
Hi Chet,
 
I have a Spiderweb for SML that I think exploits ML's differences
well.  I also have a literate program that I wrote, although it
doesn't have a lot of (enough) prose.  I'm going to clean it up and
send it off to SIGPLAN Notices, but in the meantime I have put the .dvi
file in an anonymous ftp place, where you could pick it up.  ftp to
plg.uwaterloo.ca in pub/smlweb.  I put the .web file and the .sml
files there too so you can see what they look like.
 
../Dave
 
From thompson@sun1.coe.ttu.edu Thu Nov 18 11:29:46 CST 1993
Date: Thu, 18 Nov 93 11:29:46 CST
From: thompson@sun1.coe.ttu.edu (Dave Thompson (3/1/93))
Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU
To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU
Subject: Re: installing nuweb on a pc
 
> >Nuweb on my pc requires go32.exe, which won't run under winders.  I
> >know I can close winders, but shouldn't be required to dump my
> >principal operating evnironment
 
> I agree that you ought not have to dump Windows or your PC to enjoy
> literate programming.  I disagree that nuweb requires go32.exe
> (whatever that is) to run on a PC.
 
You're right and again I say mea culpa.  (I've got a pig-latin hangup
these days ;-)  The version I picked up at CTAN was 0.6pc and requires
use of the go32.exe.  That was the first problem.  A more recent version
will probably clean up the host of problems I encountered when trying
to compile nuweb with msc.  You've had a rundown on the other difficulties
I encountered while trying to port that version to msc, so I won't repeat
them here.  I certainly appreciate your willingness to help, as well as
your willingness to spend time (a valuable commodity) on a freely 
available program.
 
> The lastest version is 0.87
 
Can we ensure that the current version is on CTAN?  The msdos version on
ftp.shsu.edu seems to be version 0.6pc, which is the one I picked up.  How
about we trash that one and put the current version up for ftp?
 
Thanks and I'll be in touch.
 
-=d
 
David B. Thompson               internet: thompson@sun1.coe.ttu.edu 
Civil Engineering Dept.         internet: dthompson@coe2.coe.ttu.edu
Texas Tech University           internet: wqdbt@ttacs1.ttu.edu 
P.O. Box 41023
Lubbock, Texas 79409-1023       "Get a haircut and get a *real* job."
 
From Lee Thu Nov 18 14:03:39 EST 1993
Date: Thu, 18 Nov 93 14:03:39 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, dmason@uwaterloo.ca (Dave Mason)
Subject: Re: Literate ML Code
 
> Hi Chet,
> 
> I have a Spiderweb for SML that I think exploits ML's differences
> well.  I also have a literate program that I wrote, although it
> doesn't have a lot of (enough) prose.  I'm going to clean it up and
> send it off to SIGPLAN Notices, but in the meantime I have put the .dvi
> file in an anonymous ftp place, where you could pick it up.  ftp to
> plg.uwaterloo.ca in pub/smlweb.  I put the .web file and the .sml
> files there too so you can see what they look like.
> 
> ../Dave
> 
> 
 
I'm not sure you meant to post this to the net in general, but I, for
one, am interested (I've already downloaded the .dvi file).  You might
also want to post the .spider file, as the .web is kind of useless
without it.  There are also some of us (like me) who are really
interested in the various Spidery grammars.
 
		-- Lee
 
From mcguire@cs.utexas.edu Thu Nov 18 19:17:24 GMT 1993
Date: Thu, 18 Nov 93 19:17:24 GMT
From: mcguire@cs.utexas.edu (Tommy Marcus McGuire)
Reply-To: LitProg@SHSU.edu, mcguire@CS.UTEXAS.EDU
To: LitProg@SHSU.EDU
Subject: Re: featurism, complexity, portability, and extensibility (Was: Which
 
In article <shfCGJwMB.Ez0@netcom.com>, Stuart Ferguson <shf@netcom.com> wrote:
>+-- norman@bellcore.com writes:
>| I happen to disagree with Stuart here, but this is a perfect example
>| of how to take advantage of an extensible tool.  noweb's default
>| behavior is to make whitespace significant, but that behavior can be
>| changed by a one-line noweb filter:
>|    sed -e '/^@use /s/[ \t][ \t]*/ /g' -e '/^@defn /s/[ \t][ \t]*/ /g'
 
I actually understood this, and I have not done more than glance at
noweb.  Does this make me a bad person?
 
>
>This isn't quite what I was talking about.  For example, I also
>mentioned wanting case insensitivity, but using the appropriate line
>of sed gibberish to perform case folding on identifiers will not do
>the right thing.  The formatted document should respect the case and
>spacing I specified, but identifiers should be matched independent
>of case and spacing.
>-- 
>	Stuart Ferguson		(shf@netcom.com)
>			"Just Once or Twice .. is Good for your Soul"
>		Ten weeks to Midnight.
 
Are you sure you really want case insensitivity?  I know I'd wind up with
<Do some work>, <Do Some Work>, <do some Work>, etc., running all through
the program.  That would tend to make regular expression searches while
editing the thing useless, not to mention confusing the heck out of 
anyone reading the final document and wondering why these case distinctions
keep showing up.
 
Personally, I am pretty ambivalent about using the ``...'' completion for
[chunk|fragment|scrap] names.  I can see where someone else might like 
it, but I don't use it.
 
-----
Tommy McGuire
mcguire@cs.utexas.edu
mcguire@austin.ibm.com
 
"...I will append an appropriate disclaimer to outgoing public information,
identifying it as personal and as independent of IBM...."
 
From Manuel Thu Nov 18 19:17:24 GMT 1993
Date: Thu, 18 Nov 93 19:17:24 GMT
From: Manuel Carriba <M.A.Carriba@sheffield.ac.uk>
Reply-To: LitProg@SHSU.edu, M.Carriba@dcs.sheffield.ac.uk
To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU, thompson@SUN1.COE.TTU.EDU
Subject: Re: installing nuweb on a pc
 
> > The lastest version is 0.87
>  
> Can we ensure that the current version is on CTAN?  The msdos version on
> ftp.shsu.edu seems to be version 0.6pc, which is the one I picked up.  How
> about we trash that one and put the current version up for ftp?
> 
 
Maybe Preston's nuweb should output a small message like 'This is nuweb,
version 0.85' whenever you run the program ;-)
 
Manuel.
 
From mcguire@cs.utexas.edu Thu Nov 18 19:17:24 GMT 1993
Date: Thu, 18 Nov 93 19:17:24 GMT
From: mcguire@cs.utexas.edu (Tommy Marcus McGuire)
Reply-To: LitProg@SHSU.edu, mcguire@CS.UTEXAS.EDU
To: LitProg@SHSU.EDU
Subject: Re: Ordering Dependencies and Scoping
 
In article <17628520@mvb.saic.com>,
Michael G. Koopman <koopman@sgi84.ctc.com> wrote:
>
>Two recent posts related to name spaces, one on scope and one on
>dependencies, reek of creeping featurism which I desire as a creepy
>feature user.  Norman Ramsey boasts of file scoping capability in
>noweb (which can be managed with make utilities?).  Stuart Ferguson
>has trouble collecting up C typedefs from "top-down" chunks.
>
[...]
>
>Stuart Ferguson wrote [Ordering Dependencies]:
>
>>One problem that I am noticing is that of final ordering of elements
>>in the output program text.  Like most one pass compilers, C requires
>>that objects be declared before they are used.  This lends a decidedly
>>"bottom-up" quality to raw C code.  I am finding that my literate
>>programs tend to be more "top-down," with declarations of higher level
>>objects before the lower level components which they require.  The
>>problem is that if I use some generic refinement like << Public Data
>>Types >> to collect up my typedef's, for example, then the objects
>>are declared in the wrong order for the compiler.
>...
>>
>>As usual, I have a suggestion about how to do this.  Normally a single
[...]
>
>The concepts described are not exactly clear to me.  I would not want
>chunks to "float" about anywhere.  Rather than levitating chunks I
>would like to chain them down.  I believe the ancillary information
>should be dependency information.  An index tag could allow dependency
[...]
>Michael Koopman (mike)                e-mail:  koopman@ctc.com
[...]
 
Pardon me for being terribly dense today, but is this a non-problem?
If type Foo depends on the definition of type Bar, shouldn't there
be a scrap
 
<<Public Data Types>>=
  <Define Type Bar>
  <Define Type Foo>
 
just to make the dependency explicit?
 
Far be it from me to resist the addition of features of extreme complexity
and beauty, of course.
 
-----
Tommy McGuire
mcguire@cs.utexas.edu
mcguire@austin.ibm.com
 
"...I will append an appropriate disclaimer to outgoing public information,
identifying it as personal and as independent of IBM...."
 
From gurari@cis.ohio-state.edu Thu Nov 18 19:17:24 GMT 1993
Date: Thu, 18 Nov 93 19:17:24 GMT
From: gurari@cis.ohio-state.edu (Eitan Gurari)
Reply-To: LitProg@SHSU.edu, gurari@CIS.OHIO-STATE.EDU
To: LitProg@SHSU.EDU
Subject: Re: LP Failure Story (Scoping)
 
<> From: Steve Avery <stevea@vast.unsw.edu.au>
 
<> Chris <chris@kd3bj.uucp> talks about scoping and include files. To be
<> quite honest, my original idea with the arbitrarily deep sectioning was
<> to have included files be included at the current level or next level
<> down (never did work out which was better) in the hierarchy. In this
<> way, the top level of the hierarchy could simply be a place where the
<> files were explained and included - supposedly making it possible to
<> have a whole suite of files easily made into one document... 
 
Hierarchical scoping of code fragments seems to me to be the way to
follow in two-dimensional (e.g., hypertext-oriented) environments that
exhibit these relationships in a natural manner. In linear environments,
hierarchical scoping might require extra discipline from users (like
me) that appreciate the cut-and-paste mode of operation.
 
Personally I like the idea of linear scoping for code files. In
(Al)ProTex I addressed this concept with two features: a feature to
clear all the existing definitions of code (option `ClearCode'), and a
feature for decomposing indexes. Normally I tie the above features with
top-level sectioning commands, like \Part or \Chapter, of prose.
(Note: indexes that are produced within ProTeX have poor outcome
and are big time consumers.)
 
-eitan
 
From Eric Thu Nov 18 12:29:27 PST 1993
Date: Thu, 18 Nov 93 12:29:27 PST
From: Eric Landes <ericla@microsoft.com>
Reply-To: LitProg@SHSU.edu, ericla@MICROSOFT.COM
To: litprog@shsu.edu
Subject: Microsoft Windows version of FWEB 1.30a.
 
This has now been made available for anonymous FTP at the following site:
 
 ftp.shsu.edu:/tex-archive/web/fweb/v1_30/mswin/fweb130w.zip
 
This is exactly like the command line version, it's just a Windows app 
now.  Handy
for avoiding DOS memory crunch, or for tangling and weaving from the Visual C++
Tools menu.
 
If you have problems with this port, please don't hesitate to ask.
 
Thanks!
 
Eric Landes
ericla@microsoft.com
 
From shf@netcom.com Thu Nov 18 21:48:17 GMT 1993
Date: Thu, 18 Nov 1993 21:48:17 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: LP Failure Story (Scoping)
 
+-- chris@kd3bj.uucp (C. T. Nadovich) writes:
| The only unanswered criticism was the issue of scoping.
	[...]
| Every time I try
| to merge a perfectly good piece of code with another---even if they
| are targeted for separate files---I have to worry about name collisions. 
| The ability to abbreviate scrap names makes this worse. 
 
I tend to agree.  One of my first thoughts when finally understanding
the design of WEB was, "My God, everything's globally scoped!"  How
1970's-ish.
 
That said, and my language design bias out in the open, the real issue
for literate programming is making the scoping decisions understandable
to the reader.  Where the programmer is comfortable with micro scoping,
I think any normal reader will be find a more large scale scoping 
easier to cope with.  I would suggest scoping by section or chapter
only, for example, and not in smaller units.  I might also insist that
the introduction to any scoped section list the public tags and
certainly highlight them in a more bold font in the text.  Limiting
scoping blocks to sections seems like a reasonable compromise between
providing the programmer with a powerful tool and keeping the document
readable.
 
There are plenty of ways to lay out the index and cross reference to
make clear the locality of reference.
 
| I like all my C files to have the same basic format. Why do I have
| to rename all the sections in the top-level template when I apply it to 
| a new module. This is unneeded work and it's error prone.
 
This ties into one of the ideas I've had which I posted here recently,
about boilerplate and literate macros.  If your web tool had text
substitution macros which could be instantiated forward and backwards,
you would only need to define your template once and could envoke it
with a different module name for each instance.  This would obviate 
the need for scoping in this case.
-- 
	Stuart Ferguson		(shf@netcom.com)
			"Just Once or Twice .. is Good for your Soul"
		Ten weeks to Midnight.
 
From plessel@oz.rtpnc.epa.gov Thu Nov 18 23:02:18 GMT 1993
Date: Thu, 18 Nov 1993 23:02:18 GMT
From: plessel@oz.rtpnc.epa.gov (Todd Plessel)
Reply-To: LitProg@SHSU.edu, plessel@OZ.RTPNC.EPA.GOV
To: LitProg@SHSU.EDU
Subject: A naive question: Is LP interactive and WYSIWYG?
 
I'm new to this newsgroup and not really familiar with literate
programming. But if the idea is to support writing software that
maximizes understandability, then I'd certainly like to learn more.
 
Following the book paradigm (that's the basic idea, right?), it seems
to me that one would certainly want automatic support for such things
as code formatting with, for example, reserved words in boldface and
comments and free-text in itallics, a table of contents, a bibliography,
an index, embeded graphics (a picture is worth ...) and so forth. However,
extending the book paradigm, I'd like the ability to navigate by zoomming
in and out to reveal different views of a software system. For example,
support for displaying design structures such as block diagrams, class
clusters (if OO) and other high-level system architechture components.
And zooming in to reveal the low-level code within a routine and zooming
to various levels in between such as class interfaces, cluster interfaces,
subsystem interfaces and other imaginable constructs. (Granted this implies,
in some manner, paradigm and language sensitive support.)
 
The point is, these features call for an interactive, WYSIWYG capability
rather than a programmed (batch-mode) model. By interactive, I'm referring
to a WIMP operational model as opposed to a batch-mode embedded-command
(e.g., TeX) model (which is the impression I'm getting about LP).
(Kind of like the difference in operational style between, say, WordPerfect
on an IBM PC vs Microsoft Word on a Macintosh - am I right about this or
have I completely (hopefully) misunderstood this crucial aspect (the
operational model) of LP?)
 
My question is this: Are there literate programming environments that
support such interactive WYSIWYG features as described or are they all
geared at producing a paper document? If there are, I'd _really_ like
to get my hands on one! If the answer is no then it seems to me that the
value of LP is significantly diminished.
 
After all, today's high-resolution monitors can display text and graphics as
well as the laser printers (or at least well enough). I haven't printed code
on paper in many years despite the presence of (crude, but helpful)
pretty-printers. The printed copy is usually outdated very quickly. (And
forget about recycling the paper - save trees by not printing in the first
place.)
 
But my real point is this: all of the benifits of LP (and I'm convinced of
its basic premise) should be obtainable interactively and in a WYSIWYG mode.
If this is not the case and LP simply requires me to do even _more
programming_ (e.g., in a TeX-like language) to yield a very nicely formatted
paper document, then I'd deem the benefits (increased understandability) as
not worth the cost (substantial additional programming effort).
 
Someone please tell me if I've misunderstood LP. (Or have LPers simply reached
a different conclusion: that it is worth the extra effort and that interactive
WYSIWYG is not really as important as I've claimed?)
 
Todd
plessel@vislab.rtpnc.epa.gov
 
From koopman@sgi84.ctc.com Thu Nov 18 19:38:38 -0500 1993
Date: Thu, 18 Nov 93 19:38:38 -0500
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, gurari@CIS.OHIO-STATE.EDU
Subject: LP Failure Story (Scoping)
 
Eitan Gurari wrote:
 
>Hierarchical scoping of code fragments seems to me to be the way to
>follow in two-dimensional (e.g., hypertext-oriented) environments that
>exhibit these relationships in a natural manner. In linear environments,
>hierarchical scoping might require extra discipline from users (like
>me) that appreciate the cut-and-paste mode of operation.
 
Is the underlying issue reuse of literate code (here, within the same
web)?  Does it seem likely that collections of chunks of a web that
describe and implement a reuse object could be written such that the
natural language descriptions, method names, attributes, etc., could
be defined to allow reuse/renaming?  That is, does it seem reasonable
to pursue reuse of literate code above the source code cut and paste
level; i.e., classes of fully literate code?  How close can ADA be
considered to approach such capacity without literate support tool?
 
Has anyone written a literate code segment such that the description
and code fragments incorporate named macros that can be renamed to
implement an equivalent class in a different domain without needing to
overhaul the code or descriptive text?  Seems like a library of these
things could be powerful medicine.  A web tool that supports
``common'' weave structures could be used to place the various chunks
into the desired locations in the web for which they have been
decomposed.  Has anyone achieved enough familiarity and experience
with literate techniques to support or deny the potential for such
speculative methods?  At a more practical level, inclusion of macro
text in the chunk name may avoid some name collisions.
 
Michael Koopman (mike)    Associate Computer Systems Specialist
Concurrent Technologies Corporation     e-mail: koopman@ctc.com
1450 Scalp Avenue                        phone: +1-814-269-2637
Johnstown, PA  15904-3321  USA         telefax: +1-814-269-2666
 
From koopman@sgi84.ctc.com Thu Nov 18 20:09:47 -0500 1993
Date: Thu, 18 Nov 93 20:09:47 -0500
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, plessel@OZ.RTPNC.EPA.GOV
Subject: A naive question: Is LP interactive and WYSIWYG?
 
Todd Plessel wrote:
>I'm new to this newsgroup and not really familiar with literate
>programming. But if the idea is to support writing software that
>maximizes understandability, then I'd certainly like to learn more.
>
>Following the book paradigm (that's the basic idea, right?),
 
I think he is playing coy with the newsgroup.  This sounds an awful
lot like ``hitting the nail on the head'' to me.  Beginner's Luck?
 
> it seems
>to me that one would certainly want automatic support for such things
>as code formatting with, for example, reserved words in boldface and
>comments and free-text in itallics, a table of contents, a bibliography,
>an index, embeded graphics (a picture is worth ...) and so forth. However,
>extending the book paradigm, I'd like the ability to navigate by zoomming
>in and out to reveal different views of a software system. For example,
>support for displaying design structures such as block diagrams, class
>clusters (if OO) and other high-level system architechture components.
>And zooming in to reveal the low-level code within a routine and zooming
>to various levels in between such as class interfaces, cluster interfaces,
>subsystem interfaces and other imaginable constructs. (Granted this implies,
>in some manner, paradigm and language sensitive support.)
 
Fanning the language sensitive flame wars - and introducing paradigm
and paradigm presentation method wars!  E-R-D, SA, Rumbaugh, Coad and
Yourdon, ADM4 ....?  Which is the true faith?
 
>The point is, these features call for an interactive, WYSIWYG capability
>rather than a programmed (batch-mode) model. By interactive, I'm referring
>to a WIMP operational model as opposed to a batch-mode embedded-command
>(e.g., TeX) model (which is the impression I'm getting about LP).
>(Kind of like the difference in operational style between, say, WordPerfect
>on an IBM PC vs Microsoft Word on a Macintosh - am I right about this or
>have I completely (hopefully) misunderstood this crucial aspect (the
>operational model) of LP?)
 
Reflaming the WYSIWYG wars; and ``interactive'' implying multiple
and/or dynamic expositions.  Anyone have dynamic exposition support?
That is, do any of the HTML tools allow presentation creation,
interactively?
 
>My question is this: Are there literate programming environments that
>support such interactive WYSIWYG features as described or are they all
>geared at producing a paper document? If there are, I'd _really_ like
>to get my hands on one! If the answer is no then it seems to me that the
>value of LP is significantly diminished.
...
>Someone please tell me if I've misunderstood LP. (Or have LPers simply reached
>a different conclusion: that it is worth the extra effort and that interactive
>WYSIWYG is not really as important as I've claimed?)
 
Sounds like you just cut out a nice big chunk of work that perhaps you
might like to implement.  I volunteer as a ``Beta'' version user. ;-)
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
-------------------------------------------------------------
Geo. Carlin - "We're gonna learn ya', we're gonna learn ya' good"
 
From koopman@sgi84.ctc.com Thu Nov 18 20:32:46 -0500 1993
Date: Thu, 18 Nov 93 20:32:46 -0500
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, shf@NETCOM.COM
Subject: LP Failure Story (Scoping)
 
Stuart Ferguson wrote:
 
>Limiting scoping blocks to sections seems like a reasonable compromise
>between providing the programmer with a powerful tool and keeping the
>document readable.
 
This gets my vote, although, especially when maintaining older
(``golden'') code - global scoping might be helpful?
 
>There are plenty of ways to lay out the index and cross reference to
>make clear the locality of reference.
 
Adding a chapter mark and id seems a straightforward approach.
 
>| I like all my C files to have the same basic format. Why do I have
>| to rename all the sections in the top-level template when I apply it to 
>| a new module. This is unneeded work and it's error prone.
>
>This ties into one of the ideas I've had which I posted here recently,
>about boilerplate and literate macros.  If your web tool had text
>substitution macros which could be instantiated forward and backwards,
>you would only need to define your template once and could envoke it
>with a different module name for each instance.  This would obviate 
>the need for scoping in this case.
 
I would add support for module name tagging of macros and other web
variable entries to (fully?) obviate scoping.
 
Michael Koopman (mike)    Associate Computer Systems Specialist
Concurrent Technologies Corporation     e-mail: koopman@ctc.com
1450 Scalp Avenue                        phone: +1-814-269-2637
Johnstown, PA  15904-3321  USA         telefax: +1-814-269-2666
 
From lynbech@daimi.aau.dk Thu Nov 18 20:42:52 -0500 1993
Date: Thu, 18 Nov 93 20:42:52 -0500
From: lynbech@daimi.aau.dk (Christian Lynbech)
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.EDU
Subject: Re: Ordering Dependencies and Scoping
 
On the issue on mixed file/global scoping.
 
I believe that noweb does a good enough job here. 
 
As I see it, you cannot mix the two types of scope, without having
some (textual) way to mark something as local and something as
global. And having to do this anyway, why not either prefix all local
scrap names with the file name, thus making them unique to that file,
or if that is too much typing (for instance you need to decide on the
file name, rather than having a fixed and short marker), pipe it
through a small sed/perl/awk script that takes all
this-is-a-local-scrap-marker and substitute the file name.
 
The above scheme can be varied endlessly, but it could be easily
implemented in a makefile.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
				| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From koopman@sgi84.ctc.com Thu Nov 18 20:42:52 -0500 1993
Date: Thu, 18 Nov 93 20:42:52 -0500
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, mcguire@CS.UTEXAS.EDU
Subject: Ordering Dependencies and Scoping
 
Yes, it is a non-problem.
 
From smclewin@ultrix.ramapo.edu Thu Nov 18 20:42:52 -0500 1993
Date: Thu, 18 Nov 93 20:42:52 -0500
From: smclewin@ultrix.ramapo.edu (Scott M McLewin)
Reply-To: LitProg@SHSU.edu, smclewin@ULTRIX.RAMAPO.EDU
To: LitProg@SHSU.EDU
Subject: Anybody using PowerBuilder from PowerSoft? Yes? Questions...
 
My company is looking to re-write a vertical market application using
PowerBuilder.  We presently use C and the Raima Data Manager (RDM) from
Raima Corp for the product.  I know PowerBuilder can sit on the
RDM engine through ODBC, but would like to know what database you would
reccomend to attach to PowerBuilder via ODBC.
 
Our constraints are as follows:                                        
 * We need our application to work both on single user systems and networks.
 * We would preferr a database engine with royalty free distribution
 
Some other questions I would love to have answered:
  * Is PowerBuilder a good development tool?
     - what are its strengths?
     - what are its weaknesses?
  * How is the PowerBuilder documentation?  Have you had questions you
    simply could not answer via the manuals?
  * Is PowerSoft a "good" company?  (I know, a rather vague question...)
     - How is their technical support?
        + responsive/"we'll call you back next month"?
        + well informed?
     - How frequently, if ever, do they make software patchs available?
     - Are they willing to share their known bugs with developers so we
       can avoid getting snagged by them?
  * Would you consider the SQL/database query tool included in the
    database you use to be good?  For exaple, any Raima user who has
    attempted to use db_Query knows it is full of "features" its
    creators never intended.
 
I am truly sorry if this message does not belong in this group.  I
was unable to find a group dedicated to PowerSoft products, so I tried
to place this message in a wide variety of programming groups.  Please
don't waste further bandwidth by flaming me or those silly folks who may 
have already flamed me.  Thanks.
 
In addition to posting your reply, please email me a carbon
copy as I may not have a chance to catch all replies in all groups.
 
Thanks,
 
Scott M McLewin
smclewin@ultrix.ramapo.edu
 
--
 
Scott M McLewin                                 smclewin@ultrix.ramapo.edu
 
From smclewin@ultrix.ramapo.edu Thu Nov 18 20:42:52 -0500 1993
Date: Thu, 18 Nov 93 20:42:52 -0500
From: smclewin@ultrix.ramapo.edu (Scott M McLewin)
Reply-To: LitProg@SHSU.edu, smclewin@ULTRIX.RAMAPO.EDU
To: LitProg@SHSU.EDU
Subject: Anybody using PowerBuilder from PowerSoft? Yes? Questions...
 
My company is looking to re-write a vertical market application using
PowerBuilder.  We presently use C and the Raima Data Manager (RDM) from
Raima Corp for the product.  I know PowerBuilder can sit on the
RDM engine through ODBC, but would like to know what database you would
reccomend to attach to PowerBuilder via ODBC.
 
Our constraints are as follows:                                        
 * We need our application to work both on single user systems and networks.
 * We would preferr a database engine with royalty free distribution
 
Some other questions I would love to have answered:
  * Is PowerBuilder a good development tool?
     - what are its strengths?
     - what are its weaknesses?
  * How is the PowerBuilder documentation?  Have you had questions you
    simply could not answer via the manuals?
  * Is PowerSoft a "good" company?  (I know, a rather vague question...)
     - How is their technical support?
        + responsive/"we'll call you back next month"?
        + well informed?
     - How frequently, if ever, do they make software patchs available?
     - Are they willing to share their known bugs with developers so we
       can avoid getting snagged by them?
  * Would you consider the SQL/database query tool included in the
    database you use to be good?  For exaple, any Raima user who has
    attempted to use db_Query knows it is full of "features" its
    creators never intended.
 
I am truly sorry if this message does not belong in this group.  I
was unable to find a group dedicated to PowerSoft products, so I tried
to place this message in a wide variety of programming groups.  Please
don't waste further bandwidth by flaming me or those silly folks who may 
have already flamed me.  Thanks.
 
In addition to posting your reply, please email me a carbon
copy as I may not have a chance to catch all replies in all groups.
 
Thanks,
 
Scott M McLewin
smclewin@ultrix.ramapo.edu
 
--
 
Scott M McLewin                                 smclewin@ultrix.ramapo.edu
 
From huff@schenectady.ecn.purdue.edu Fri Nov 19 15:12:55 GMT 1993
Date: Fri, 19 Nov 1993 15:12:55 GMT
From: huff@schenectady.ecn.purdue.edu (John E Huff)
Reply-To: LitProg@SHSU.edu, huff@SCHENECTADY.ECN.PURDUE.EDU
To: LitProg@SHSU.EDU
Subject: nuweb for macintosh
 
I have tried to compile nuweb with Think C 5.0 on the macintosh and have
not been able to get it to run.  The program compiles completely but
crashes when it runs.
 
I would appreciate any help or versions ready to go.
 
One caveat, I am just learning to program in C.
 
Thanks,
 
John Huff
huff@ecn.purdue.edu
 
From <PJENSEN@CSI.compuserve.com> Fri Nov 19 15:12:55 GMT 1993
Date: Fri, 19 Nov 1993 15:12:55 GMT
From: <PJENSEN@CSI.compuserve.com>
Reply-To: LitProg@SHSU.edu, PJENSEN@CSI.COMPUSERVE.COM
To: <LitProg@shsu.edu>
Subject: Re: A naive question: Is LP interactive and WYSIWIG?
 
Todd Plessel (plessel@vislab.rtpnc.epa.gov) writes:
 
>  ... all of the benefits of LP (and I'm convinced of its basic premise)
> should be obtainable interactively and in a WYSIWIG mode.  If this is not
> the case and LP simply requires me to do even _more programming_ (e.g.,
> in a TeX-like language) to yield a very nicely formatted paper document,
> then I'd deem the benefits (increased understandability) as not worth the
> cost (substantial additional programming effort).
 
First, I will admit that I'm a rabid hater of graphic interfaces.  My blood
pressure rises when I'm forced to move five of my ten fingers over to a mouse
to do something that should be one keystroke (like PageUp/PageDown).  Also,
as a typographic purist, I admire TeX for enabling high quality work under
precisely-defined rules.  What you see is all you got.
 
But leaving this aside, many of us are used to developing programs in
character-cell mode, with emacs or whatever.  We know what to type to get
the keywords and special symbols of whatever language it is (and with smart
editors, we have the option of binding single keys to set up control structure
templates and so forth).  The fact that with (prettyprinting flavors of) LP
tools we can get listings with boldface, arrows, inequality symbols, angle
brackets, and so on is "gravy".
 
Also, very many of us find great benefit in the chunking of LP, quite apart
from how many times we actually weave and TeX it; some posters have stated
that they almost never make listings.
 
One sees from recent postings that we don't agree entirely on what LP tools
should do; but in batch mode the effort to develop a new tool or modify an
existing one is "finite":  a WYSIWIG tool would be an order of magnitude more
complicated.
 
A nice bonus is that the tools we use are free, and portable (and fast).
 
- Phil
pjensen@csi.compuserve.com
 
From preston@dawn.cs.rice.edu Fri Nov 19 16:39:47 GMT 1993
Date: Fri, 19 Nov 1993 16:39:47 GMT
From: preston@dawn.cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU
To: LitProg@SHSU.EDU
Subject: Re: A naive question: Is LP interactive and WYSIWYG?
 
plessel@oz.rtpnc.epa.gov (Todd Plessel) writes:
>Someone please tell me if I've misunderstood LP. (Or have LPers simply reached
>a different conclusion: that it is worth the extra effort and that interactive
>WYSIWYG is not really as important as I've claimed?)
 
I need to tone down some of the bitterness that some might have leaked
into my previous post.
 
I don't think you've misunderstood LP; however, I don't think anyone's
reached a conclusion either.  Hmmm... I take it back, many of us have
concluded many things, but we haven't reached a consensus as to
exactly what's important, trivial, nice to have, too expensive, etc.
Mostly, we're all still exploring the possibilities.  Simpler systems
are currently fairly popular because we can build them.
 
Preston Briggs
 
From shf@netcom.com Fri Nov 19 17:33:28 GMT 1993
Date: Fri, 19 Nov 1993 17:33:28 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: Reuse of LP code
 
+-- Mark.Probert@nms.otc.com.au (Mark Probert) writes:
| When I code in "straight" C++, for instance, the class definition 
| is in the header and the implementation is in .cc file. But when I
| use an LP tool, both of these are in the same file, as I believe it
| should be. Now, at reuse time, I have either to use the generated
| header, which may be "unreadable" (CWEB), or look at the web, which
| has implementation details that I shouldn't see. 
 
I've been dealing with this two different ways.  The simplest is
just to organize the document for reuse with a chapter on the public
interfaces and how to use them and other chapters on the
implementation.  The idea is to make the document readable by a
client of the package without letting the details get in the way.
In many OO systems it is considered normal for clients to look at
the implementation too, so having it there may be good.
 
Another approach would be to generate two different forms of your
web -- one for the client and one for the maintainer.  You might
use "\if" or some other mechanism to generate a version of the
document with only the public interfaces and no implementation.
This is like the Eiffel short form, and has the advantage that the
long form may contain public interfaces anywhere in the document
which will be collected together for the client to see.
-- 
	Stuart Ferguson		(shf@netcom.com)
			"Just Once or Twice .. is Good for your Soul"
		Ten weeks to Midnight.
 
From fulling@sarastro.math.tamu.edu Fri Nov 19 11:47:08 CST 1993
Date: Fri, 19 Nov 93 11:47:08 CST
From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling)
Reply-To: LitProg@SHSU.edu, fulling@SARASTRO.MATH.TAMU.EDU
To: LitProg@shsu.edu
Subject: Re: A naive question: Is LP interactive and WYSIWIG?
 
Phil (pjensen@csi.compuserve.com) writes:
 
>First, I will admit that I'm a rabid hater of graphic interfaces.
>My blood pressure rises when I'm forced to move five of my ten
>fingers over to a mouse to do something that should be one
>keystroke (like PageUp/PageDown).
 
HEAR!  HEAR!
 
>Also, as a typographic purist, I admire TeX for enabling high
>quality work under precisely-defined rules.  What you see is all
>you got.  [...]   A nice bonus is that the tools we use are free,
>and portable (and fast).
 
Again hear!  I cringe whenever a term like "hypertext" comes up
that threatens to cut back the number of systems on which a tool
could operate.  TeX and *WEB are valuable largely because of their
universality and low cost.  It would be nice to have a more-nearly-
WYSIWYG TeX (and LP) system that maintained source-code
compatibility with more primitive systems; but I think this requires
a new generation of higher-resolution monitors, so that the source
and the TeX output can be displayed side-by-side without loss of
legibility of the latter.
 
				  Steve Fulling
 
From dak@messua.informatik.rwth-aachen.de Fri Nov 19 11:47:08 CST 1993
Date: Fri, 19 Nov 93 11:47:08 CST
From: dak@messua.informatik.rwth-aachen.de (David Kastrup)
Reply-To: LitProg@SHSU.edu, dak@MESSUA.INFORMATIK.RWTH-AACHEN.DE
To: LitProg@SHSU.EDU
Subject: A task nobody thought of, but all will embrace if done...
 
Here comes what we all want:
 
All Weave writers using TeX, allow an option to generate
\special{weblines: file.web 1512}
Into the weave output. For every line.
 
Xdvi patchers, allow xdvi, when encountering such a line, to listen
to a tcp Port (this may be difficult...), and mapping requests
for files and lines by finding and displaying the appropriate
special location.
 
Finally, gdb fans, make it possible to open such a TCP Port
(if present) and send those commands through.
 
It might even be an idea from xdvi to manage several dvi files at
once, but I do not think I insist...
 
What do we get?
 
A debugger stepping through the *document* in the previewer, not through
the ugly WEB source.
-- 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From Lee Fri Nov 19 15:03:32 EST 1993
Date: Fri, 19 Nov 93 15:03:32 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, plessel@oz.rtpnc.epa.gov
Subject: Re: A naive question: Is LP interactive and WYSIWYG?
 
Todd Plessel writes:
 
> I'm new to this newsgroup and not really familiar with literate
> programming. But if the idea is to support writing software that
> maximizes understandability, then I'd certainly like to learn more.
 
> 	[text omitted]
> 
> The point is, these features call for an interactive, WYSIWYG capability
> rather than a programmed (batch-mode) model. By interactive, I'm referring
> to a WIMP operational model as opposed to a batch-mode embedded-command
> (e.g., TeX) model (which is the impression I'm getting about LP).
> (Kind of like the difference in operational style between, say, WordPerfect
> on an IBM PC vs Microsoft Word on a Macintosh - am I right about this or
> have I completely (hopefully) misunderstood this crucial aspect (the
> operational model) of LP?)
 
Whether LP features ``call for an interactive, WYSIWYG capability'' or
not seems to be a major religous issue around here.  To avoid
avoidable friction, I will refrain from commenting on the issue of whether
WYSIWYG is best or not.  It's best to leave it as ``Different strokes
for different folks.''
 
> My question is this: Are there literate programming environments that
> support such interactive WYSIWYG features as described or are they all
> geared at producing a paper document? If there are, I'd _really_ like
> to get my hands on one! If the answer is no then it seems to me that the
> value of LP is significantly diminished.
 
There are 2 WYSIWYG LP environments that I know of.  WinWordWEB is a
collection of Word for Windows macros that support literate
programming in that <<appropriate adjective>> word processor.  A
a FrameMaker-based system was recently announced as well.
 
Happy hunting.
 
		-- Lee
		   leew@pilot.njin.net
 
From norman@bellcore.com Fri Nov 19 17:28:51 -0500 1993
Date: Fri, 19 Nov 93 17:28:51 -0500
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, preston@dawn.cs.rice.edu
Subject: simple systems are popular because...
 
> Simpler systems are currently fairly popular because we can build them.
 
Not, I submit, because we can build them, but because we can
understand them.  Lots of people build complex tools before we got
some of the simpler ones we have now.
 
Norman Ramsey
 
From norman@bellcore.com Fri Nov 19 17:40:08 -0500 1993
Date: Fri, 19 Nov 93 17:40:08 -0500
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, dak@messua.informatik.rwth-aachen.de
Subject: Re: A task nobody thought of, but all will embrace if done...
 
> A debugger stepping through the *document* in the previewer, not through
> the ugly WEB source.
 
Actually this has been thought of a number of times.  I'd consider a
slightly different structure, though.:
 
> \special{weblines: file.web 1512}
 
Remember that source locations aren't just line numbers; they are line
and column, so it might simply be better to have the \special mark a
particular point of known interest (e.g. lcc `defpoints'), give xdvi
the ability to highlight a point, then have something else do the
mapping from source location (or object location) to defpoint.
 
> Xdvi patchers, allow xdvi, when encountering such a line, to listen
> to a tcp Port (this may be difficult...), and mapping requests
> for files and lines by finding and displaying the appropriate
> special location.
 
I'd suggest rather than a tcp port you use the `send' facility of
ousterhout's tk toolkit.  tcl/tk was designed precisely with this sort
of application in mind, and it should be fairly easy to include into
gdb.  adding it to xdvi might be more problematic, but tcl/tk dvi
previewer would be a fine thing.
 
You also might consider separating mappings
 
  object location -> defpoint -> display location
 
having gdb perform the first mapping, some other tool (perhaps some
simple tcl code) perform the 2nd mapping, and just send the display
location to xdvi (e.g. in terms of dvi file, page, and xy coordinate).
(N.B. source locations are essentially uninteresting until you want to
edit, but there is also a defpoint -> source location mapping).
 
Norman
 
From norman@bellcore.com Fri Nov 19 19:19:52 -0500 1993
Date: Fri, 19 Nov 93 19:19:52 -0500
From: norman@bellcore.com
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, kwerling@ISOIT034.BBN.HP.COM
Subject: Re: NOWEB to nroff
 
> I wonder if somebody of you tried to convert the output of the
> markup program, coming with the noweb package, to nroff.
 
I'm not a troff user, but if you send me a sample file giving me some
idea what the troff ought to look like, I'll try.
 
Norman
 
From mcguire@cs.utexas.edu Fri Nov 19 19:19:52 -0500 1993
Date: Fri, 19 Nov 93 19:19:52 -0500
From: mcguire@cs.utexas.edu (Tommy Marcus McGuire)
Reply-To: LitProg@SHSU.edu, mcguire@CS.UTEXAS.EDU
To: LitProg@SHSU.EDU
Subject: Re: Reuse of LP code
 
In article <17625278@mvb.saic.com>,
Mark Probert <Mark.Probert@nms.otc.com.au> wrote:
[...]
>Now, at reuse time, I have either to use the generated
>header, which may be "unreadable" (CWEB), or look at the web, which
>has implementation details that I shouldn't see. 
[...]
>mark.    (probertm@nms.otc.com.au) ph: (02) 339 3953  fax: (02) 339 3688
 
Do you by any chance read the last page of a mystery novel first?  :-)
 
-----
Tommy McGuire
mcguire@cs.utexas.edu
mcguire@austin.ibm.com
 
"...I will append an appropriate disclaimer to outgoing public information,
identifying it as personal and as independent of IBM...."
 
From dak@POOL.Informatik.RWTH-Aachen.DE Sat Nov 20 10:17:39 +0100 1993
Date: Sat, 20 Nov 93 10:17:39 +0100
From: dak@POOL.Informatik.RWTH-Aachen.DE
Reply-To: LitProg@SHSU.edu, dak@POOL.INFORMATIK.RWTH-AACHEN.DE
To: norman@bellcore.com
Subject: Re: A task nobody thought of, but all will embrace if done...
 
The Tcl/Tk interface sounds like a reasonable idea for passing line
numbers from a debugger to some other program, but is it not very
X-specific? I mean, fine for xdvi, but probably for other potential
application a more generally usable source location indicating
interface might be desirable, and the more an extension might be
of use, probably the more it will get used.
 
Another possibility is filtering gdb's output for line number information.
I believe this is the way gdb under emacs works, and is of course
a pretty easy way.
 
All the best,
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
 David Kastrup        dak@pool.informatik.rwth-aachen.de          
 Tel: +49-241-72419 Fax: +49-241-79502
 Goethestr. 20, D-52064 Aachen
 
From <PJENSEN@CSI.compuserve.com> Sat Nov 20 09:06:45 MST 1993
Date: Sat, 20 Nov 1993 09:06:45 MST
From: <PJENSEN@CSI.compuserve.com>
Reply-To: LitProg@SHSU.edu, PJENSEN@CSI.COMPUSERVE.COM
To: <LitProg@shsu.edu>
Subject: Re: Ordering Dependencies and Scoping
 
Stuart Ferguson (shf@netcom.com) writes:
 
> Any good language would allow use before definition, but since C does not,
> I always have to jump through hoops getting valid concepts to run through
> the compiler.
 
Hear, hear!  This comment was apropos of the need to order type definitions
properly, but another instance is that of prototypes.  I am currently using
CWEB, and am sorely tempted to hack on it so that ctangle notices function
definitions and constructs matching prototypes, which would then get emitted
at a designated point in the output.
 
I see this enhancement as analogous to the ways in which Knuth's original
made up for certain deficiencies of standard Pascal.
 
From system@galcon.ersys.edmonton.ab.ca Sat Nov 20 09:06:45 MST 1993
Date: Sat, 20 Nov 1993 09:06:45 MST
From: system@galcon.ersys.edmonton.ab.ca (The Doctor)
Reply-To: LitProg@SHSU.edu, system@GALCON.ERSYS.EDMONTON.AB.CA
To: LitProg@SHSU.EDU
Subject: Re: Anybody using PowerBuilder from PowerSoft? Yes? Questions...
 
smclewin@ultrix.ramapo.edu (Scott M McLewin) writes:
 
> My company is looking to re-write a vertical market application using
> PowerBuilder.  We presently use C and the Raima Data Manager (RDM) from
> Raima Corp for the product.  I know PowerBuilder can sit on the
> RDM engine through ODBC, but would like to know what database you would
> reccomend to attach to PowerBuilder via ODBC.
>  
> Our constraints are as follows:                                        
>  * We need our application to work both on single user systems and networks.
>  * We would preferr a database engine with royalty free distribution
>  
> Some other questions I would love to have answered:
>   * Is PowerBuilder a good development tool?
>      - what are its strengths?
>      - what are its weaknesses?
>   * How is the PowerBuilder documentation?  Have you had questions you
>     simply could not answer via the manuals?
>   * Is PowerSoft a "good" company?  (I know, a rather vague question...)
>      - How is their technical support?
>         + responsive/"we'll call you back next month"?
>         + well informed?
>      - How frequently, if ever, do they make software patchs available?
>      - Are they willing to share their known bugs with developers so we
>        can avoid getting snagged by them?
>   * Would you consider the SQL/database query tool included in the
>     database you use to be good?  For exaple, any Raima user who has
>     attempted to use db_Query knows it is full of "features" its
>     creators never intended.
 
Powerbuilder needs an SQL Server to work with, Gupta SQLBase, Oracle,
XDB, Sybase, HP, otherwise you are OOL.
 
>  
>  
> I am truly sorry if this message does not belong in this group.  I
> was unable to find a group dedicated to PowerSoft products, so I tried
> to place this message in a wide variety of programming groups.  Please
> don't waste further bandwidth by flaming me or those silly folks who may 
> have already flamed me.  Thanks.
>  
> In addition to posting your reply, please email me a carbon
> copy as I may not have a chance to catch all replies in all groups.
>  
> Thanks,
>  
> Scott M McLewin
> smclewin@ultrix.ramapo.edu
>  
> 
> --
> 
> 
> Scott M McLewin                                 smclewin@ultrix.ramapo.edu
> 
-- 
God save the Queen! God bless and save us all!!
Remeber, Jesus saves all souls from eternal damnation!
Save the world! Purge Republicanism and Dictatorship!
A British citizen I was born, A British citizen I will most honourably die!
 
From rryan@panix.com Sat Nov 20 09:06:45 MST 1993
Date: Sat, 20 Nov 1993 09:06:45 MST
From: rryan@panix.com (Rob Ryan)
Reply-To: LitProg@SHSU.edu, rryan@PANIX.COM
To: LitProg@SHSU.EDU
Subject: Re: Anybody using PowerBuilder from PowerSoft? Yes? Questions...
 
In <931120.090645.1K3.rusnews.w165w@galcon.ersys.edmonton.ab.ca> system@galcon.ersys.edmonton.ab.ca (The Doctor) writes:
 
>Powerbuilder needs an SQL Server to work with, Gupta SQLBase, Oracle,
>XDB, Sybase, HP, otherwise you are OOL.
 
PowerBuilder v3.0 comes with its own DBMS, Watcom SQL, doesn't it?
Incidentally, "SQL Server" is a particular DBMS from Microsoft (I
believe that it runs under OS/2 and, more recently, NT), not
necessarily a generic term.
 
From shf@netcom.com Sat Nov 20 21:46:57 GMT 1993
Date: Sat, 20 Nov 1993 21:46:57 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: featurism, complexity, portability, and extensibility (Was: Which
 
mcguire@cs.utexas.edu (Tommy Marcus McGuire) writes:
| Are you sure you really want case insensitivity?  I know I'd wind up with
| <Do some work>, <Do Some Work>, <do some Work>, etc., running all through
| the program.
 
I guess I wasn't clear.  The weaver would pick a single string to
represent the code tag and use that consistently throughout the final
document.  It could pick the first complete reference to a tag as the
canonical form, or the one with the most uppercase characters, or
whatever.
 
The tangler would treat all the above identifiers as the same and
generate code (or errors) appropriately.
 
|  That would tend to make regular expression searches while
| editing the thing useless, not to mention confusing the heck out of 
| anyone reading the final document and wondering why these case distinctions
| keep showing up.
 
The readable document would only contain one form for any identifier.  I
don't know about all editors, but emacs certainly has a switch for case-
folding while searching.
 
My desire to ignore case comes from reading too much of other peoples
code with different variables all in the same routine called `doall,'
`doAll,' `doALL,' etc.  (I'm not making this up.)  If case is
significant, some literate but noncreative programmer will use it.
 
| Personally, I am pretty ambivalent about using the ``...'' completion for
| [chunk|fragment|scrap] names.  I can see where someone else might like 
| it, but I don't use it.
 
These seemed like a can of worms when I first saw them too, but with
sufficiently good error messages I have never found them to be a 
problem.  Completion may even be a good thing since it encourages long
refinement names, and it also encourages puting the most salient info
toward the front of the name.
-- 
	Stuart Ferguson		(shf@netcom.com)
			"Just Once or Twice .. is Good for your Soul"
		Ten weeks to Midnight.
 
From shf@netcom.com Sat Nov 20 22:46:55 GMT 1993
Date: Sat, 20 Nov 1993 22:46:55 GMT
From: shf@netcom.com (Stuart Ferguson)
Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM
To: LitProg@SHSU.EDU
Subject: Re: Ordering Dependencies and Scoping
 
mcguire@cs.utexas.edu (Tommy Marcus McGuire) writes:
| >Stuart Ferguson wrote [Ordering Dependencies]:
| >>One problem that I am noticing is that of final ordering of elements
| >>in the output program text.  Like most one pass compilers, C requires
| >>that objects be declared before they are used.  This lends a decidedly
| >>"bottom-up" quality to raw C code.  I am finding that my literate
| >>programs tend to be more "top-down," with declarations of higher level
| >>objects before the lower level components which they require.  The
| >>problem is that if I use some generic refinement like << Public Data
| >>Types >> to collect up my typedef's, for example, then the objects
| >>are declared in the wrong order for the compiler.
 
| Pardon me for being terribly dense today, but is this a non-problem?
| If type Foo depends on the definition of type Bar, shouldn't there
| be a scrap
|
| <<Public Data Types>>=
|   <Define Type Bar>
|   <Define Type Foo>
 
There seems to be a lot of confusion about what I was trying to say, so
I suppose I should clarify.  Yes, of course you can explicitly put the
declarations in the right order and it will work.  So there is no
"problem" in the sense that work has stopped because something is not
possible.  However, when I do this I get a twinge from my finely tuned
sense of "rightness."  It seems wrong that I have to encode the 
dependency order in this way.
 
Of course, I get this same feeling every time I program in C.  Any good
language would allow use before definition, but since C does not, I 
always have to jump through hoops getting valid concepts to run through
the compiler.  I've long since learned to ignore the mental warnings I
get when programming in C, and it may be that I'm just seeing them anew
when attempting literate C programming.  But I think I can make a case
for the problem being in the literate programming domain and not just
the target language.
 
Most webs allow code chunks with the same identifier, and the code from
all the chunks is collected together to form a single refinement of the
same name.  The code is ordered in the refinement in the same order that
it occurs in the document.  It seems to me that sometimes the order is
conceptually important and sometimes it is not.
 
If the refinement represents some linear process, like a series of steps,
then the order is important.  In this case I would argue that the chunks
with the same name will for very natural reasons be together in the prose
and will be in the right order.
 
	"First we do step 1."
	<<Some process>>=
		Step #1
 
	"Now we do the next step, which is 2."
	<<Some process>>=
		Step #2
 
	"Finally we do the third step."
	<<Some process>>=
		Step #3
 
It would never make sense to cut out step two and paste it into another
section since that would take it out of context.  So we don't generally
have to worry about the steps getting out of order as result of editing
the prose.
 
On the other hand, some refinements which have the same name are just
used to collect things of similar type and are conceptually order
independent.  Code chunks for <<Public Functions>>, <<Local Typedefs>>
and <<Private Include Files>> will be strewn throughout the web source
willy nilly, used whenever a new thing of that type is to be inserted
into the output code.  When the reader encounters a chunk like
 
	<<Include Files>>=
		#include <ectrl.h>
 
he is not concerned with what comes before or after this chunk in the
refinement.  The chunk is stand-alone in that it declares only what type
of code the chunk represents, not its order in any sequence.  If the web
is complex, there may be many sections each with many such chunks, and
each section is semi-independent in that it could very easily be moved
to make the prose read better.
 
The problem is that even though this type of chunk is conceptually order
independent, it is actually order dependent, since the code will be
generated in the order it's found in the web.  So, if A depends on B,
and B comes first in the document, the generated code will compile.  If,
due to a conceptual restructuring of the web, A is moved to before B,
then the generated code will not compile.  Now the person who was just
making the web read better has to write "glue" code to skick B back in
front of A in the code sequence.  And where does this tacky glue stuff
go anyway?  Is it part of the section on A, or the section on B?  What
if a third thing depends on A or B -- now where does the glue belong?
 
I would find it conceptually cleaner to allow code chunks to declare
their dependencies and be truely independent of the order they occur
in the web.  We could have:
 
	<<Typedefs>>=
		typedef {... B C } A;
		<: defines A and depends on B and C :>
 
	<<Typedefs>>=
		typedef {... C } B;
		<: defines B and depends on C :>
 
	<<Typedefs>>=
		typedef {...} C;
		<: defines C :>
 
These three chunks could be anywhere in the document in any order and
if the <<Typedefs>> refinement had the right behavior associated with
it, then the chunks which define it would be shuffled into C B A order,
which will compile.  Even better, if a new type was added it would be
shuffled into the sequence correctly and none of the other parts of the
web would be affected.
 
I hope this is more clear now.  I think this is really a literate 
programming problem since it is about making the description of the code
clear and elegant and not just about hacking something together that
works.
-- 
	Stuart Ferguson		(shf@netcom.com)
			"Just Once or Twice .. is Good for your Soul"
		Ten weeks to Midnight.
 
From j_mcarthur@BIX.com Sun Nov 21 02:25:13 -0500 1993
Date: Sun, 21 Nov 1993 02:25:13 -0500 (EST)
From: j_mcarthur@BIX.com
Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
To: litprog@shsu.edu
Subject: Ordering Dependencies and Scoping
 
Stuart Ferguson writes:
 
>I would find it conceptually cleaner to allow code chunks to declare
>their dependencies and be truely independent of the order they occur
>in the web.  We could have:
>
> <<Typedefs>>=
>  typedef {... B C } A;
>  <: defines A and depends on B and C :>
 
The original Pascal WEB has this feature.  It understands Pascal
and orders the declarations in such a way that simple dependancies
are resolved by tangle.  If the dependancy is circular, it needs
help.
 
All in all, the original Pascal WEB is not that bad of a language
to use.  Far from perfect.  Many of its flaws are do to the nature
of Pascal.
 
----
    Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur
    a.k.a. Jeffrey McArthur          ATLIS Publishing
    phone: (301) 210-6655            12001 Indian Creek Court
    fax:   (301) 210-4999            Beltsville, MD  20705
    email: j_mcarthur@bix.com
 
From Eric Sun Nov 21 23:02 +0000 1993
Date: Sun, 21 Nov 1993 23:02 +0000 (GMT)
From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" <AMMERS@RCL.WAU.NL>
Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL
To: LitProg@SHSU.edu
Subject: Re: A naive question: Is LP interactive and WYSIWYG?
 
Lee Wittenberg writes in reply to "plessel@oz.rtpnc.epa.gov"
 
	[text omitted]
 
=There are 2 WYSIWYG LP environments that I know of.  WinWordWEB is a
=collection of Word for Windows macros that support literate
=programming in that <<appropriate adjective>> word processor.  A
=a FrameMaker-based system was recently announced as well.
 
I would like to add CLiP to this list. It works with any word-processor
(WYSIWYG of conventional). It is designed to work in a hypertext environment
also (but we have no experience here yet).
 
Eric
 
Eric W. van Ammers
Department of Computer Science
Wageningen Agricultural University
Dreijenplein 2				E-mail:	ammers@rcl.wau.nl
6703 HB  Wageningen			voice:	+31 (0)8370 83356/84154
The Netherlands				fax:	+31 (0)8370 84731
 
From Lee Sun Nov 21 23:15:53 EST 1993
Date: Sun, 21 Nov 93 23:15:53 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, AMMERS@rcl.wau.nl
Subject: Re: A naive question: Is LP interactive and WYSIWYG?
 
Eric W. van Ammers writes:
 
> Lee Wittenberg writes in reply to "plessel@oz.rtpnc.epa.gov"
> 
> 	[text omitted]
> 
> =There are 2 WYSIWYG LP environments that I know of.  WinWordWEB is a
> =collection of Word for Windows macros that support literate
> =programming in that <<appropriate adjective>> word processor.  A
> =a FrameMaker-based system was recently announced as well.
> 
> I would like to add CLiP to this list. It works with any word-processor
> (WYSIWYG of conventional). It is designed to work in a hypertext environment
> also (but we have no experience here yet).
 
Mea culpa.  I apologize to Eric.  I do know about CLiP, and while I
don't use it myself, I did know that it is word-processor independent
and should, therefore, belong in the WYSIWYG list.  I just forgot.
 
I guess my only excuse is that I don't tend to think highly of WYSIWYG
web systems (no flames, please:  as the author of WinWordWEB, I'm
allowed to disparage my own product), but I do think rather highly of
CLiP :-).
 
		-- Lee
		   leew@pilot.njin.net
 
From Mark.Probert@nms.otc.com.au Mon Nov 22 8:42:29 GMT 1993
Date: Mon, 22 Nov 93 8:42:29 GMT
From: Mark.Probert@nms.otc.com.au (Mark Probert)
Reply-To: LitProg@SHSU.edu, Mark.Probert@NMS.OTC.COM.AU
To: LitProg@SHSU.edu, mcguire@cs.utexas.edu
Subject: Re: Reuse of LP code
 
Tommy Marcus McGuire...
> 
> Do you by any chance read the last page of a mystery novel first?  :-)
> 
I'm one of those sick individuals that reads from front to back,
with no peeking. Sad, isn't it? :-)
 
-- 
mark.    (probertm@nms.otc.com.au) ph: (02) 339 3953  fax: (02) 339 3688
 
From erawlins@sybase.com Mon Nov 22 15:42:38 GMT 1993
Date: Mon, 22 Nov 1993 15:42:38 GMT
From: erawlins@sybase.com (Eric Rawlins)
Reply-To: LitProg@SHSU.edu, erawlins@SYBASE.COM
To: LitProg@SHSU.EDU
Subject: Re: Anybody using PowerBuilder from PowerSoft? Yes? Questions...
 
In article <2cq1cj$cjn@panix.com> rryan@panix.com (Rob Ryan) writes:
>In <931120.090645.1K3.rusnews.w165w@galcon.ersys.edmonton.ab.ca> system@galcon.ersys.edmonton.ab.ca (The Doctor) writes:
>
>>Powerbuilder needs an SQL Server to work with, Gupta SQLBase, Oracle,
>>XDB, Sybase, HP, otherwise you are OOL.
>
>PowerBuilder v3.0 comes with its own DBMS, Watcom SQL, doesn't it?
>Incidentally, "SQL Server" is a particular DBMS from Microsoft (I
>believe that it runs under OS/2 and, more recently, NT), not
>necessarily a generic term.
 
"SQL Server" is the name of Sybase's RDBMS, which is licensed to Microsoft
for the OS/2 and Windows environments.
-- 
-------------------------------------------------------------------
   Eric Rawlins                          erawlins@sybase.com
   Sybase, Inc.                          510-596-4657
--------------------------------------------------------------------
 
From mauer@mcs.anl.gov Mon Nov 22 16:42:20 GMT 1993
Date: Mon, 22 Nov 1993 16:42:20 GMT
From: mauer@mcs.anl.gov (Andrew Mauer)
Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV
To: LitProg@SHSU.EDU
Subject: Literate Scoping of Scrap Names
 
>>>>> On Thu, 18 Nov 93 20:32:46 -0500, koopman@sgi84.ctc.com (Michael G. Koopman) said:
 
>| I like all my C files to have the same basic format. Why do I have
>| to rename all the sections in the top-level template when I apply it to 
>| a new module. This is unneeded work and it's error prone.
>
>This ties into one of the ideas I've had which I posted here recently,
>about boilerplate and literate macros.  If your web tool had text
>substitution macros which could be instantiated forward and backwards,
>you would only need to define your template once and could envoke it
>with a different module name for each instance.  This would obviate 
>the need for scoping in this case.
 
Michael> I would add support for module name tagging of macros and other web
Michael> variable entries to (fully?) obviate scoping.
 
IMHO, this is an excellent idea. I'm interested in hearing the
advantages/disadvantages of allowing a user to specify a the module by
doing:
	@module << C++Class >>
or maybe
	@scope << C++Class >>	
 
It seems to me that in the spirit of WEB delimiting of text and
program scraps, one would not need to support more than one level of
scoping, and a scope should just go on until the next scope is
encountered. 
 
What is the real-life situation here? Does anybody have a code that
they think needs nested scoping? I agree that it would be more
elegant, but for c/c++ (my area), the program structure does not nest
enough for that to be likely. I gather that in scheme or other
languages which support prodecures-within-procedures this could be
important, but is that good style?!?
 
/Andrew/
--
/Andrew Mauer/
mauer@mcs.anl.gov
 
From c21vc@kocrsv01.delcoelect.com Mon Nov 22 16:57:00 GMT 1993
Date: Mon, 22 Nov 1993 16:57:00 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: WYSIWYG LP environments
 
At this time we (Ron Peithman and I) here at Delco Electronics have (at 
least the beginnings) two LP environments, for devloping Perl literate programs:
 
1. The first uses the '-x' feature of Perl. Very detailed annotations may be
provided at the start of each Perl file without marking these as comments (using
the '#' character). At run time, the '-x' option performs the simple tangle of
processing only the lines following the perl invocation line. Please contact me
if you need more details. (Larry Wall the author of Perl pointed this to me.)
This alone will go a long way (for us) in writing understandable programs.
However, very little 'weave' features will be available.
 
2. The second uses Interleaf to create Perl source programs. Jonathan Starr who
   performs independent consulting in Interleaf provided some code which
   makes tangle possible. There may be other less elegant ways too. Weave is done
   using the effectivity option or the select and copy features.
 
Of the two, clearly the Interleaf method is superior since good formatting of
text can be achieved; table of contents, index etc. can be achieved without
writing a post processor. What I have heard of Interleaf (regarding ease of
learning and ease of use) makes me want to try the Perl way first. It is time to
try writing some understandable programs now. 
 
This in passing: sometimes people ask those who spend time worrying about the
'great unwashed', 'what have the great unwashed done for you lately ?' I cannot
help thinking of this. Recently, I was talking to one of my users (who might be
modifying some of my programs) and saying that the programs he will be getting
will be more understandable. Not really being used to this luxury, he didn't seem
to be expecting much. Also, it is possible that he would almost be disappointed
if his work was made very easy. (I remember reading that some food product did
not sell well because it was ready to eat; there was no place for the housewife
to perform say 5% of the work and claim credit for the whole thing; they had to
make it only 95% readymade). As Cox points out in his book Object Oriented
Programming, unless the extra work done in software towards whatever purposes
(make it more maintainable, etc.) is appreciated, there is little incentive to
do these. None of these take away from my interest and determination to write
understandabel programs employing the book paradigm; but it will be nice to be
appreciated. You may run into the great unwashed taking your work for garnted.
 
Shaker
 
From jacojn@inet.uni-c.dk Mon Nov 22 17:48:40 GMT 1993
Date: Mon, 22 Nov 1993 17:48:40 GMT
From: jacojn@inet.uni-c.dk (Jacob Nielsen)
Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK
To: LitProg@SHSU.EDU
Subject: Literate programming on WWW, where ?
 
Hi,
 
does anyone have the 'URL' of the literate programming page 
at CERN (info.cern.ch). It's not that easy to find :-(
 
Thanx,
 
Jacob
--
Jacob Nielsen
Email:   jacojn@inet.uni-c.dk (my private account)
   or    bc898574@bbar.dth.dk (my account at the university)
 
From rkeel@fnugget.intel.com Mon Nov 22 17:48:40 GMT 1993
Date: Mon, 22 Nov 1993 17:48:40 GMT
From: rkeel@fnugget.intel.com (William R Keel)
Reply-To: LitProg@SHSU.edu, rkeel@FNUGGET.INTEL.COM
To: LitProg@SHSU.EDU
Subject: Re: Anybody using PowerBuilder from PowerSoft? Yes? Questions...
 
rryan@panix.com (Rob Ryan) writes:
 
>In <931120.090645.1K3.rusnews.w165w@galcon.ersys.edmonton.ab.ca> system@galcon.ersys.edmonton.ab.ca (The Doctor) writes:
 
>>Powerbuilder needs an SQL Server to work with, Gupta SQLBase, Oracle,
>>XDB, Sybase, HP, otherwise you are OOL.
 
>PowerBuilder v3.0 comes with its own DBMS, Watcom SQL, doesn't it?
yes.  It's a SQL type DBMS that runs locally on your machine (is it
only in Windows?)
 
>Incidentally, "SQL Server" is a particular DBMS from Microsoft (I
>believe that it runs under OS/2 and, more recently, NT), not
>necessarily a generic term.
SQL Server is one of those combination efforts.  Both Sybase and
Microsoft have put their name to basically the same product.  I don't
know if MS did any work on it or if they just licensed the product
from Sybase.
But true...it's not a generic term (like Kleenex).
 
Reed
+----------------------------+-[mail]-------------------------------------+
| "I didn't do it...nobody   |  unix: rkeel@fnugget.intel.com             |
|  saw me do it...you can't  |    pc: william_r_keel@ccm.hf.intel.com     |
|  prove anything!" - Bart   | Intel Corp. Memory Components - Folsom, CA |
+-[disclaimer]---------------+--------------------------------------------+
|  Intel had absolutely nothing to do with the content of this message.   |
+-------------------------------------------------------------------------+
 
From George Mon Nov 22 14:18:45 CST 1993
Date: Mon, 22 Nov 1993 14:18:45 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: tomas@cae.wisc.edu
Subject: CWEB (3.1) for Amiga on the CTAN
 
On Sun, 21 Nov 93 17:55:14 CST, Tomas Willis <tomas@cae.wisc.edu> posted:
> I have uploaded CWEB 3.1 for Amiga to the incoming area
> in a subdir named AmigaCWEB.
> The files are AmigaCWEB_31.readme, an explanatory text file in Aminet format
> and AmigaCWEB_31.lha, a LHA-compressed archive file, the standard Amiga
> archiver.
 
Thank you for the submission.  I have moved the files into the directory
 /tex-archive/web/c_cpp/AmigaCWEB_31/
on the CTAN hosts at ftp.SHSU.edu and ftp.Uni-Stuttgart.de (I was unable to
get connections to deposit it at ftp.TeX.ac.uk, but feel sure it will be
mirrored there sometime soon).
 
Three comments on this (and, please, if you're going to flame on any of
this, please do so directly to me and not the list/newsgroup).  First, the
web/c_cpp directory is where the C and C++ web-type files are placed; since
"+" can be a tricky file/directory name on more than a few platforms, the
CTAN uses this convention for portability reasons.  Second, I placed this
file outside of web/c_cpp/cweb intentionally as that hierarchy is a mirror
of the authoritative CWEB files at labrea.  Third, and finally (and no
flame at Tomas nor anyone else -- I've yet to mention this publicly),
please consider using lowercase alphanumeric names for files and
(especially!) directories whenever possible (a tertiary-level reason why
this isn't directly in the web/c_cpp/cweb/ directory).  Lowercase
alphanumerics (plus "_" and "-" which seem to be acceptable on every OS for
filename purposes -- at least no one's told me differently so far) are an
awful lot more portable in design (ideally 8+3 filenames, but I won't get
into that as it's secondary or lower in importance to character selection).
 
Regards to all and again my thanks to Tomas,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From marcus@x4u2.desy.de Mon Nov 22 20:59:15 GMT 1993
Date: Mon, 22 Nov 1993 20:59:15 GMT
From: marcus@x4u2.desy.de (Marcus Speh)
Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE
To: LitProg@SHSU.EDU
Subject: Re: Literate programming on WWW, where ?
 
>>>>> "Jacob" == Jacob Nielsen <jacojn@inet.uni-c.dk> writes:
 
Jacob> Hi, does anyone have the 'URL' of the literate programming page
Jacob> at CERN (info.cern.ch). It's not that easy to find :-(
 
"The literate programming page at CERN" is in fact from DESY :-)
URL is  
	http://info.desy.de/user/projects/LitProg.html
 
Due to a server change at DESY, the link from CERN is disabled until
CERN fixes the URL. It is hidden in "Subjects"->"Computing"->"Languages".
 
--
-----------------------------------------------------------------------------
Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany
Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392
Email: <marcus@x4u.desy.de> <na.speh@na-net.ornl.gov> <marcus1@uu-gna.mit.edu>
 
From thompson@sun1.coe.ttu.edu Tue Nov 23 14:21:53 +0000 1993
Date: Tue, 23 Nov 1993 14:21:53 +0000
From: thompson@sun1.coe.ttu.edu
Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu
To: LitProg@SHSU.EDU
Subject: comp.programming.literate FAQ
 
Archive-name: literate-programming-faq
Last-modified: 1993/11/11
Version: 1.0.4
 
Welcome to the Literate Programming Frequently Asked Questions List
-------------------------------------------------------------------
 
This version was created Thursday - November 11, 1993 and should
considered stale after 90 days.  Information contained in this document
is the best available at preparation.
 
Disclaimer: "This FAQ is presented with no warranties or guarantees of
ANY KIND including correctness or fitness for any particular purpose.
The author of this document has attempted to verify correctness of the
data contained herein; however, slip-ups can and do happen.  If you use
this data, you do so at your own risk."
 
Copyright 1993 David B. Thompson.  All rights reserved worldwide.
Permission is granted to copy this document for free distribution so
long as it remains intact and unmodified.
 
* Introduction:
---------------
 
This document is for new and experienced users of literate programming
tools.  The purpose is to explain the concept of literate programming and
to provide a resource for locating files of interest to literate
programmers and those interested in literate programming.
 
The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list
is maintained by Dave Thompson, who can be reached at:
 
    thompson@sun1.coe.ttu.edu     * Preferred mailing address for FAQ
                                    related comments/questions.
    wqdbt@ttacs1.ttu.edu          * Forwarded to my pc.
 
Comment and constructive criticism is welcome.  Direct flames to
/dev/null (or > nul if you're a msdos user! ;-)  If you find an error,
please report it.  I'm particularly interested in establishing the
locations of generally available literate programming tools.  If you are
the author of such a tool and wish to have it included in this list,
please send email.
 
Please note this is a work-in-progress.  It is *not* complete, and
probably will not be complete for some months.  Nevertheless, the
information contained herein may be useful to some.  Use it as it is
intended.
 
- ----------------------------------------------------------------------
 
- Typography:
-------------
 
Major sections of the FAQ are divided by double lines (====).  Minor
sections and other divisions are separated by single lines (----).
Major topics use a "* " as a leader.  Minor topics use a "- " as a
leader.  This should simplify searching for topics.
 
Table of Contents:
------------------
 
* Introduction
    - Typography.
* How to get the FAQ.
    - Literate Programming FAQ.
    - FWEB FAQ.
* The LitProg newsgroup.
* Internet nodes of interest to literate programmers.
* What is literate programming?
* How do I begin literate programming?
* What tools are available and where are they?
    - c2latex
    - CLip
    - CWEB
    - FunnelWeb
    - FWEB
    - noweb
    - NUWEB
    - SchemeWEB
    - Spidery WEB
    - WinWordWEB
* What other resources are available?
    - Virtual Coursework
* Code examples.
    - Examples included with developer's tools
    - Cameron Smith's KR-CWEB
    - Bart Child's examples for FWEB
* Bibliographies.
* How to anonymously ftp.
* Acknowledgements.
* End notes.
 
* How to get the FAQ:
---------------------
 
- Literate Programming FAQ.
---------------------------
 
You have many ways to get a current copy of this FAQ.  One is to use
anonymous ftp (if you don't know how, see a later section in this FAQ)
to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites
or the Literate Programming Archive and retrieve a copy of the file.
(For more information on CTAN and the literate programming archive, see
the section below entitled "Internet Nodes of Interest to Literate
Programmers.")
 
An alternative is to use the fileserver at SHSU.  Send a message to
FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message
 
    SENDME FAQ.LITPROG
 
The file server will forward a copy of the file to you via email.
 
- ----------------------------------------------------------------------
 
- FWEB FAQ:
-----------
 
Marcus Speh <marcus@x4u.desy.de> maintains the FWEB FAQ.  The current
version number is 1.29.  It can be retrieved in the same way as this
FAQ; either by anonymous ftp or through the SHSU file server.  On the
SHSU server, the file name is FAQ.FWEB.  Invoke your ftp software, open
a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory
FAQ, and transfer the file FAQ.FWEB.
 
Alternatively, send a message to the file server, FILESERV@SHSU.EDU
(FILESERV@SHSU.BITNET), and include the following text in a one line
message:
 
    SENDME FAQ.FWEB
 
The file server will send the current version of the file via email.
 
The FWEB FAQ exists in various formats, including HyperText (see other
resources below). In Europe, the complete distribution can also be
obtained from ftp.desy.de [131.169.10.115] in directory
/pub/faq/web/fweb/.  It is also available from the literate programming
archive (LPA) in the directory LPA/documentation/faq/fweb (see the
references to LPA below for more information).
 
* The LitProg Newsgroup:
------------------------
 
One of the most important resources is the literate programming
newsgroup, comp.programming.literate.  You can read this newsgroup using
your standard reader.  Altenatively, the newsgroup is gated to a mailing
list hosted by George Greenwade and Sam Houston State University.  You
can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or
LISTSERV@SHSU.BITNET), and include in the message one line of text:
 
    SUBSCRIBE LITPROG  "your name in quotes"
 
The list is unmoderated; messages sent to litprog@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.programming.literate.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory litprog.
 
* Internet Nodes of Interest to Literate Programmers:
-----------------------------------------------------
 
The principal nodes of interest to literate programmers are the Literate
Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX
Archive Network).
 
The Literate Programming Archive (LPA) is:
 
  Node:       ftp.th-darmstadt.de [130.83.55.75]
  Directory:  pub/programming/literate-programming
  Notes:      Fastest response during off-U.S. [yep] business hours.
 
The CTAN sites are:
 
ftp host             IP            CTAN root    Institution and Sponsor
-------------------------------------------------------------------------
ftp.TeX.ac.UK        134.151.79.32 pub/archive  Aston Univ./UK TeX U.G.
ftp.Uni-Stuttgart.DE 129.69.8.13   soft/tex     Univ. Stuttgart/DANTE e.V
ftp.SHSU.edu         192.92.115.10 tex-archive  Sam Houston State Univ.
 
Other nodes and directories of interest include:
 
  Node:       niord.shsu.edu [192.92.115.8]
  Directory:  various (do some snooping!)
  Notes:      Has a gopher server.
 
  Node:       ftp.desy.de [131.169.10.115]
  Directory:  pub/web. Various documents, samples, and the FWEB FAQ.
  Notes:      Has a www server, http://info.desy.de:80/
 
* What is Literate Programming?
-------------------------------
 
Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings.  In fact,
literate programs should be enjoyable reading, even inviting!  (Sorry
Bob, I couldn't resist!)  In general, literate programs combine source
and documentation in a single file.  Literate programming tools then
parse the file to produce either readable documentation or compilable
source.  The WEB style of literate programming was created by D.E. Knuth
during the development of his TeX typsetting software.
 
All the original work revolves around a particular literate programming
tool called WEB.  Knuth says:
 
     The philosophy behind WEB is that an experienced system
     programmer, who wants to provide the best possible
     documentation of his or her software products, needs two
     things simultaneously: a language like TeX for formatting,
     and a language like C for programming.  Neither type of
     language can provide the best documentation by itself; but
     when both are appropriately combined, we obtain a system
     that is much more useful than either language separately.
 
     The structure of a software program may be thought of as a
     web that is made up of many interconnected pieces.  To
     document such a program we want to explain each individual
     part of the web and how it relates to its neighbours. The
     typographic tools provided by TeX give us an opportunity to
     explain the local structure of each part by making that
     structure visible, and the programming tools provided by
     languages such as C or Fortran make it possible for us to
     specify the algorithms formally and unambigously. By
     combining the two, we can develop a style of programming
     that maximizes our ability to perceive the structure of a
     complex piece of software, and at the same time the
     documented programs can be mechanically translated into a
     working software system that matches the documentation.
 
* How to begin literate programming:
------------------------------------
 
A recommended book is D.E. Knuth's collection of articles (1992)
"Literate Programming," Center for the Study of Language and
Information, Stanford University, ISBN 0-937073-80-6 (pbk).  This book
gives insight into Knuth's thoughts as he developed the web system of
literate programming (and TeX for typesetting).  It does not document
methods for literate programming.
 
A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate
Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk).
This book focuses on using Knuth's web system.
 
Some talk exists in the newsgroup/mailing list for a Usenet University
course in literate programming.  I'm sure discussion of this topic will
be welcomed.  If you are interested, please participate.
 
* What Tools are Available:
---------------------------
 
A significant number of tools for literate programming are available.
Most have been ported from their original systems, so support multiple
computer platforms.  If you are the developer of such a tool, and would
like to make the software freely available, please send me email and
I'll reply with a form (like those below) for you to fill in.  (Or
short-circuit the process and kludge a form from below. :-)
 
- C2LaTeX:
----------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix
 
Software supported:
            Programming language: C.
            Text formatter: LaTeX but it's easy to change the formatter.
 
Availability:
            Anonymous ftp from
                omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex.
 
Readme:
            Absent.  Documentation is in the C source for c2latex.
 
Brief description:
            C2latex provides simple support for literate programming
            in C.  Given a C source file in which the comments have
            been written in LaTeX, c2latex converts the C source file
            into a LaTeX source file.  It can be used to produce
            typeset listings of C programs and/or documentation
            associated with the program.
 
            C2latex produces LaTeX source by implementing a small
            number of rules.  A C comment that starts at the beginning
            of a line is copied unmodified into the LaTeX source
            file.  Otherwise, non-blank lines are surrounded by a pair
            of formatting commands (\begin{flushleft} and
            \end{flushleft}), and the lines are separated by \\*.
            Each non-blank line is formatted using LaTeX's \verb
            command, except comments within the line are formatted in
            an \mbox.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
- ----------------------------------------------------------------------
 
- CLip:
-------
 
Developer:
            E.W. van Ammers and M.R. Kramer
 
Systems supported:
            Vax/VMS and MS-DOS.
 
Software supported:
            An programming language.  Plain TeX and LaTeX text
            formatters.
 
Availability:
            Anonymous ftp from:
              CTAN/web/clip
              LPA/machines/ms-dos
              LPA/machines/vax
              sun01.info.wau.nl/CLIP
 
Readme:
            In distribution.
 
Brief description:
 
Support:
            Unknown.
 
- ----------------------------------------------------------------------
 
- CWEB:
-------
 
Developer:
            Silvio Levy and D.E. Knuth
 
System(s) supported:
            Unix systems (dos and amiga ports available)
 
Software supported:
            Languages supported are C and C++.  Text formatters are
            plain TeX and LaTeX.
 
Availability:
            anonymous ftp from:
              labrea.stanford.edu/pub/cweb
              LPA/c.c++
              CTAN/web/c_cpp/cweb
              DOS version in CTAN/web/c_cpp/cwb30p8c
              DOS version in LPA/machines/ms-dos
              Amiga version to be posted soon (look at CTAN).
              Mac port of CTANGLE in LPA/machines/mac
              LaTeX support in LPA/c.c++
 
Readme:
            bundled with above
 
Brief description:
 
Support:
            bugs to levy@math.berkeley.edu
 
- ----------------------------------------------------------------------
 
- FunnelWeb:
------------
 
Developer:
            Ross N. Williams: ross@guest.adelaide.edu.au
 
Systems supported:
            MSDOS, Mac, VMS, Sun.  Other ports reported.
 
Software supported:
            For printing, TeX.  Otherwise no restrictions.
 
Availability:
            anonymous ftp from:
              CTAN/web/funnelweb
              LPA/independent
              ftp.adelaide.edu.au/pub/funnelweb
 
Readme:
            With bundle above.
 
Brief description:
            FunnelWeb is a production-quality literate-programming tool
            that emphasises simplicity and reliability. Everything about
            FunnelWeb, from the simplicity of its language to the
            comprehensive tutorial in the user's manual, has been
            designed to make this as simple, as practical, and as usable
            a tool as possible.
 
            Features:
               + Provides a simple macro preprocessor facility.
               + Can produce typeset documentation.
               + Runs on Sun, VMS VAX, Macintosh, PC, and others.
               + Portable C source code distributed under GNU licence.
               + Comprehensive user's manual including tutorial.
               + Programming-language independent.
               + Can generate multiple output files.
               + Allows complete control over the output text.
               + Regression test suite with over 200 tests.
               + Fully worked example (in /pub/funnelweb/examples).
               - Requires TeX to produce typeset documentation.
               - Typesets program code using TT font only.
 
Support:
            No formal support available.  Mailing list maintained with
            about 50 subscribers.  Informal assistance available from
            mailing list.
 
- ----------------------------------------------------------------------
 
- FWEB:
-------
 
Developer:
            John A. Krommes
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX.
            Text formatters are plain TeX and LaTeX.
 
Availability:
            anonymous ftp from:
              lyman.pppl.gov/pub/fweb
              CTAN/web/fweb
              LPA/fweb
              DOS version in LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            It also has a well-developed user's manual and its own FAQ
            (see above). It runs on most platforms: VMS, PC, UNIX, and
            pretty much anything that the GNU C compiler (GCC) is
            supported for.
 
Support:
            bug reports to krommes@princeton.edu
 
- ----------------------------------------------------------------------
 
- noweb:
--------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            All programming languages, plain TeX and LaTeX formatters.
 
Availability:
            anonymous ftp from:
              csservices.princeton.edu/pub/noweb.shar.Z
              bellcore.com/pub/norman/noweb.shar.Z
              CTAN/web/independent/noweb
              LPA/independent
 
Readme:
            with bundle above
 
Brief description:
 
            noweb is designed to meet the needs of literate programmers
            while remaining as simple as possible.  Its primary
            advantages are simplicity, extensibility, and
            language-independence.  noweb uses 5 control sequences to
            WEB's 27.  noweb now supports indexing and identifier
            cross-reference.  The simple noweb manual is only 2 pages;
            documenting the full power of noweave and notangle requires
            another 3 pages.  noweb works ``out of the box'' with any
            programming language, and its formatter-dependent part is a
            60-line nawk program. The primary sacrifice relative to WEB
            is the loss of prettyprinting.
 
Support:
            by email to the author
 
- ----------------------------------------------------------------------
 
- NUWEB:
--------
 
Developer:
            Preston Briggs: preston@cs.rice.edu
 
Systems supported:
            Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS.
 
Software supported:
            It's written in C.  It works with any programming language
            (or combination of programming languages) and uses Latex as
            its text formatter.
 
Availability:
            anonymous ftp from:
              Unix: CTAN/web/nuweb
              DOS:  CTAN/web/nuweb-pc
              LPA/independent
 
Readme:
            Send mail to preston@cs.rice.edu
 
Brief description:
 
            A single program that takes a web file written in a
            combination of latex and any programming language(s) and
            produces a latex file that can be pretty printed and a set
            of files containing code for compilation/interpretation by
            the appropriate language processors.
 
            Strengths include speed, simplicity, multiple languages,
            nice indices and cross-references, latex.  Doesn't require
            any special macros or macro files.
 
            Drawbacks: latex-dependent, no code pretty printing, harder
            to make indices than cweb.
 
            More good stuff: nice support for make, doesn't reformat
            source files, so they're easy to debug.  Lots of control
            without too much effort.  That is, it doesn't do too much!
 
            Future directions... Very little change planned, except
            perhaps refinements in the indexing software.
 
Support:
            Hack it yourself or send e-mail to preston@cs.rice.edu
 
- ----------------------------------------------------------------------
 
- SchemeWEB:
------------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Programming language: Any dialect of Lisp.
            Text formatter: LaTeX.
 
Availability:
            The Unix version is in the Scheme Repository and it is
            available via anonymous ftp from:
              nexus.yorku.ca/pub/scheme/utl
              LPA/lisp
 
            The DOS version is part of the PCS/Geneva Scheme system
            which is available via anonymous ftp from:
              cui.unige.ch/pub/pcs.
              LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            SchemeWEB is a Unix or DOS filter that translates
            SchemeWEB source into LaTeX source or Lisp source.
            Lisp code is formatted in typewriter type font and
            the comments are passed to LaTeX unchanged.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
- ----------------------------------------------------------------------
 
- Spidery WEB:
-------------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Most Algol-like languages, including C, Ada, Pascal, Awk,
            and many others.  Plain TeX and latex for text formatters.
 
Availability:
            Anonymous ftp from:
                CTAN
 
Readme:
            In distribution.
 
Brief description:
            A system for building language-dependent WEBs. Spider is
            frozen; no further development is planned.
 
Support:
            Bug reports to author.
 
- ----------------------------------------------------------------------
 
- WinWordWEB:
-------------
 
Developer:
            Lee Wittenberg <leew@pilot.njin.net>
 
Systems supported:
            Needs Microsoft Word for Windows, v.2.x, and, of course,
            MS-Windows 3.x.
 
Software supported:
            Any programming language.  Word for Windows 2.x for text
            formatting and file maintenance.
 
Availability:
            anonymous ftp from:
              bart.kean.edu:pub/leew
            World-Wide Web (WWW)
 
Readme:
            WORDWEB.DOC in the downloadable package describes the
            system.
 
Brief description:
            WinWordWEB is a set of a Word for Windows macros (plus a
            paragraph style) that provide a crude literate programming
            environment.  The ``look and feel'' of the system is based
            on Norman Ramsey's noweb, but can easily be modified to suit
            individual tastes.
 
Support:
            None.  WinWordWEB was written as a prototype to see if a
            WYSIWYG literate programming system was possible.  It is
            intended as a jumping off point for future work by others.
            However, the system is surprisingly usable as it stands, and
            the author is interested in hearing from users (satisfied
            and unsatisfied).
 
            Anyone interested in actively supporting (and improving) the
            product should contact the author via email.
 
* Other resources:
------------------
 
An untapped resource (by me anyway ;-) is the World Wide Web.  Marcus
Speh has expended considerable effort in this regard.  If you're
connected to WWW, then access:
 
  http://info.desy.de/user/projects/LitProg.html
 
If you aren't connected to WWW, telnet to info.cern.ch and explore.
You can reach Marcus' literate programming pages by typing:
 
  go http://info.desy.de/user/projects/LitProg.html
 
Help for people who have only Email and neither WWW nor telnet, can be
obtained by Email from LISTSERV@INFO.CERN.CH by sending a message
containing the command HELP.  Instructions will be returned by email.
For literate programming documents, you can try anonymous ftp to
ftp.desy.de [131.169.10.115] and attach to directory:
 
  /pub/userWWW/projects/Announce
 
Another resource of interest to literate programmers is the info-tex
mailing list.  If you're using (La)TeX as your typsetting system and
have access to internet, then you should investigate this mailing list.
Mail list service is available through the SHSU list-server.  To
subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET),
and include in the message one line of text:
 
    SUBSCRIBE INFO-TEX "your name in quotes"
 
The list is unmoderated; messages sent to info-tex@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.text.tex.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory info-tex.
 
- ----------------------------------------------------------------------
 
- Virtual Coursework:
---------------------
 
Marcus Speh plans an introductory course on Literate Programming on the
Internet, part of the first semester of "Global Network Academy" [GNA],
a non-profit corporation incorporated in the state of Texas, affilated
with the Usenet University project. The texts/sample programs for this
class will be made available via anonymous FTP. A special room on GNA
Virtual Campus will be staffed by a consultant in one to two hour
shifts.  Students with questions can telnet to the virtual campus and
ask questions of the staff there. Tuition: Students should agree to work
for Global Network Academy in some capacity. This may include agreeing
to serve as a consultant next term, donating computing resources which
belong to them, helping with programming, etc. If you are interested in
registering for the course either as a student or as a consultant,
please contact marcus@x4u.desy.de. You will receive a standard reply
message; no further action will be taken until January 94.
 
[Editor's note: Because of workload, Marcus requests that email
inquiries be limited to a statement of interest for either a student or
consultant position until January 1994.]
 
* Code Examples:
----------------
 
Examples of web programs are included with the FWEB, CWEB, and noweb
distributions.
 
Cameron Smith converted the K&R calculator program into a literate
program.   It can be retrieved by anonymous ftp from:
  niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as
    krcwsamp.zip
  or from
    LPA/Documentation
 
Ross Williams has released a funnelweb example.  You can retrieve this
file from node ftp.adelaide.edu.au [129.127.40.3] as
  /pub/funnelweb/examples/except.*
This file should be on CTAN as well.
 
* Bibliographies:
-----------------
 
Nelson Beebe has collected an extensive bibliography treating literate
programming.  His work is available for anonymous ftp from
ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files:
    litprog.bib
    litprog.ltx.
Although I have not verified this, LPA is an alternate source for these
files.  Note that they are updated frequently (Nelson says several times
each week), so be sure to get a fresh copy before extensive use.
Joachim Schrod indicates that these files may be updated daily and can
be retrieved via anonymous ftp at LPA/documentation.
 
* How to anonymously ftp:
-------------------------
 
Pretty much everything mentioned here is available by anonymous FTP.
FAQ lists cross-posted to news.answers and rec.answers can be gotten
from rtfm.mit.edu [18.70.0.209], under /pub/usenet/news.answers or under
/pub/usenet/more.specific.group.name
 
"anonymous FTP" is just a way for files to be stored where anyone
can retrieve them over the Net.    For example, to retrieve the
latest version of the literate programming FAQ, do the following:
 
> ftp rtfm.mit.edu              /* connect to the site; message follows */
> anonymous                     /* type this when it asks for your name */
> <your email address>          /* type your address as the password    */
> cd /pub/usenet                /* go to the directory you want to be   */
> cd comp.programming.literate  /* one level down (no slash).           */
> dir                           /* look at what's there                 */
> get literate-progamming-faq   /* get the file; case-sensitive         */
> quit                          /* stop this mysterious thing           */
 
If your FTP program complains that it doesn't know where the site you
want to use is, type the numerical address instead of the sitename:
 
> ftp 18.70.0.209               /* connect with numerical address */
 
If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu
with the single word "help" in the body of the message.
 
Getting binary files (executables, or any compressed files) is only
slightly more difficult.   You need to set binary mode inside FTP before
you transfer the file.
 
> binary            /* set binary transfer mode  */
> ascii             /* set back to text transfer mode */
 
FAQs and spoiler lists are generally ascii files; everything else is
generally binary files.
 
Some common extensions on binary files in archive sites are:
 
  .Z           Compressed; extract with uncompress
  .tar.Z       Compressed 'tape archive'; uncompress then untar or tar -xvf
  .gz or .z    Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu)
  .sit         (Mac) StufIt archive
  .zip         Extract with Zip or Unzip
  .zoo         Yet another archive/compress program
  .lhe         (Amiga) ?
  .lzh         Lha archive program.
  .arj         (PC) Arj archive program.
  .exe         (PC) Sometimes self-extracting archives-just execute them.
  .uue or .UUE Transfer as text file; use uudecode to convert to binary
  .hqx         (Mac) BinHex format; transfer in text mode
 
Generic help can be found in the FAQs of comp.binaries.<your_system_type>
for how to transfer, extract, and virus-check binary files.  (At
rtfm.mit.edu)
 
If you can't FTP from your site, use one of the following ftp-by-mail
servers:
 
  ftpmail@decwrl.dec.com
  ftpmail@src.doc.ic.ac.uk
  ftpmail@cs.uow.edu.au
  ftpmail@grasp.insa-lyon.fr
 
For complete instructions, send a message reading "help" to the server.
 
If you don't know exactly what you're looking for, or exactly where it
is, there are programs and servers that can help you.  For more info,
send e-mail to mail-server@rtfm.mit.with with the body of the
message reading send usenet/news.answers/finding-sources
 
Thanks to Aliza R. Panitz (the "buglady") for this text.  I copied it
verbatim from her post on faq-maintainers with only minor modifications.
 
* Acknowledgements:
-------------------
 
This document would not have happened without the help of many people.
Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim
Schrod, Piet van Oostrum, and Ross N. Williams.  A special thanks to
Aliza R. Panitz for the text describing how to execute an anonymous ftp
for files of interest.
 
Any omissions from these acknowledgements should be considered an act of
stupidity on my part.  Of course, the authors of literate programming
tools mentioned above all play a vital role in the vitality of literate
programming. Furthermore, participants in the comp.programming.literate
newsgroup (and associated mailing list) all contributed in various
fashions. Thank all of you.
 
* End notes:
------------
 
This document will be evolving over the next few months.  I'm planning
on adding entries for additional literate programming tools and will
expand the sections on examples as more examples become available. Tools
I will include are web (the original pascal version), funnelweb,
spiderweb, and cnoweb for starters. Others will be added as I find and
document them.  Omission of a particular tool should not be considered a
snub in any sense--simply an error or oversight on my part.
 
History:
 
  First release: Fri 10/15/1993 -- Yep, I finally did it!
  Thu 10/21/93 -- Minor change to ftp instructions.
  Fri 10/22/93 -- Minor change to stuttgart ip and fweb.faq version.
                  Made reader-recommended changes, lots of re-
                  organization, and added a few tools.
  Mon 11/01/93 -- Corrected typo in address.
  Thu 11/11/93 -- Minor change to www.
 
From julian@bjalon.demon.co.uk Tue Nov 23 14:21:53 +0000 1993
Date: Tue, 23 Nov 1993 14:21:53 +0000
From: julian@bjalon.demon.co.uk (julian templeman)
Reply-To: LitProg@SHSU.edu, julian@bjalon.demon.co.uk
To: LitProg@SHSU.EDU
Subject: Re: A naive question: Is LP interactive and WYSIWIG?
 
In article <17693446@MVB.SAIC.COM> Phil Jensen writes:
 
> First, I will admit that I'm a rabid hater of graphic interfaces.  My blood
> pressure rises when I'm forced to move five of my ten fingers over to a mouse
> to do something that should be one keystroke (like PageUp/PageDown).
 
Aha! Invitation to a flame war, it sounds like....
 
Interestingly, I also find that I'm occasionally prone to fits of high blood-
pressure, but for the opposite reason. Misfit though I am, I hate TeX... 
that great sprawl of programs and data files, taking up megabytes of my 
precious disk space. All those arcane commands and incomprehensible error 
messages. Ugh. :-)
 
> Also, as a typographic purist, I admire TeX for enabling high quality work 
> under precisely-defined rules.  What you see is all you got.
 
Not too sure what you mean by the last sentence, but... I also admire TeX for 
its typographical ability, but I can't say that I *like* its output very much. 
 
Although I'm an 'informed layman' when it comes to typography, I do know that 
one aspect of good typography is suiting the layout and appearance of the 
text to the material, so that the interest of the reader is maintained, and 
their 'navigation' of the document is facilitated. Most of the examples of 
LP produced by TeX-based systems I find about as easy to digest as the phone 
book.
 
Well, that's responded to the provocation, now for a couple of thoughts :-)
 
As I see it, what you (or I, for that matter) like or dislike doesn't matter
very much. I happen to dislike TeX, but I have to admit that a lot of LP tools
use it, and a lot of people hereabouts like it. I happen to like GUIs, and
programming the things pays my wages, so what I want are tools to enable me
to program that are integrated with the environment in which I usually
work - programming IDEs, WYSIWYG word processors and other visual tools.
TeX, for all its strengths, is alien to my environment.
 
I'm happy to accept the less-than-perfect typography that comes from using
Word for Windows or whatever - heck, what I'm actually doing is finding a
better way of editing my code, not producing something I can frame and hang
on the wall. (But others' mileage may vary on that point). Using WfW with
WordWeb, incomplete though it is, neatly starts to integrate LP into my
company's environment.
 
> One sees from recent postings that we don't agree entirely on what LP tools
> should do; but in batch mode the effort to develop a new tool or modify an
> existing one is "finite":  a WYSIWIG tool would be an order of magnitude more
> complicated.
 
Well, I'll find out when I'm finished....
 
-- 
Julian Templeman                           Baker Jardine & Associates,
julian@bjalon.demon.co.uk                  London, England
bja@compulink.co.uk
 
"Some people don't see the advantages of combining Microsoft applications.
 But then some people didn't see what would come of mixing nitro and
 glycerin" --- Microsoft ad
 
From c21vc@kocrsv01.delcoelect.com Tue Nov 23 15:08:22 GMT 1993
Date: Tue, 23 Nov 1993 15:08:22 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: Perl programs - how to put free form annotations at the top
 
> Hello Shaker,
> 
> Are you making your Perl literate programming environment work
> available to "the great unwashed" out here?
> 
> Thanks,
> 
> Mike
 
Actually, there is not a lot of 'work' really. However, I will document 
the procedure right here.
 
As for "the great unwashed out there (in the usenet land)" (I know you
are introducing a light touch here; however, I do not want the netters to
misunderstand me), I was referring only to maintenance programmers who
use literate programs without acknowledging (for political or
whatever reasons) that these are better than the average programs they
normally get; I was not referring to the people in the newsgroup, who only
contribute positively to my motivation (to write understandable programs).
 
Here is a preview of what I plan to do for Perl programs:
 
 1. Normally Perl annotations have to start with a '#' in column 1.
    It is annoying to have to 'box' comments; usually, the comments
    (number and quality) are restricted because of this. What I plan to 
    do is have a lot of free form text providing a lot of details; this could 
    be several pages; arranged nicely with sections headings etc. .
 
 2. Follow this with the call to the Perl interpreter. So, the whole
    thing will look like:
 
    Detailed annotations
    #!/usr/local/bin/perl -P
    perl code
 
    The restriction is that the annotations cannot contain '#!' (perhaps
    in the whole line or possibly only in column 1). The restriction is 
    probably specified more precisely in the perl book (under the '-x' 
    option). I plan to put only descriptive narrative (book chapter
    like) in the annotations.
 
    Assuming that the above file is called test1, from the command
    line I type:
 
     /usr/local/bin/perl -x test1
 
    The '-x' option causes, Perl to ignore everything above the '#!'
    line. Larry Wall says that the code ('chunk' ?), can be followed
    by an end specification enabling one to put another annotation and so 
    on. ''test1' then should weed out the next annotation, etc,; I don't plan
    to do this (since it will complicate - i.e., make 
    it harder to understand - my application code). In other words, 
    the following is possible, if one is willing to put this kind of 
    tangle_like processing in his application code:
 
    Detailed annotations
    #!/usr/local/bin/perl -P
    perl code
    _END_ (or something like this)
    more annotations
    more perl code
    _END_ (or something like this)
     more annotations
     more perl code
     etc.
 
    If you have any questions, please feel free to contact me.
    Thanks for your question.
 
     Shaker
 
From epasos@sfsuvax1.sfsu.edu Wed Nov 24 08:39:02 GMT 1993
Date: Wed, 24 Nov 1993 08:39:02 GMT
From: epasos@sfsuvax1.sfsu.edu (Enrique Pasos)
Reply-To: LitProg@SHSU.edu, epasos@SFSUVAX1.SFSU.EDU
To: LitProg@SHSU.EDU
Subject: Enfin..
 
I am curious if anyone is using Easel's Enfin product.  I use it at work
but haven't run into anyone else who uses it.
I'm just curious to know what others are doing with it.
---
Henry Pasos 
(epasos@sfsuvax1.sfsu.edu)
 
From Walter Wed Nov 24 09:11:04 GMT 1993
Date: Wed, 24 Nov 1993 09:11:04 GMT
From: Walter Ravenek <ravenek@chem.vu.nl>
Reply-To: LitProg@SHSU.edu, ravenek@CHEM.VU.NL
To: LitProg@SHSU.EDU
Subject: Re: nuweb for macintosh
 
John, and anyone wanting to install nuweb on the Macintosh.
 
Get the latest version of nuweb, currently 0.87.
Then make the following changes:
 
- file main.c
- add after line 1:
#include <console.h>
 
- file main.c
- replace line 6:
  int arg = 1;
- by
  int arg;
  argc = ccommand(&argv);
  arg = 1;
 
- file output.c
- replace lien 10:
      char *temp_name = tempnam(".", 0);
- by
      char *temp_name = tmpnam(NULL);
 
Hope this helps,
 
From pgl@imada.ou.dk Wed Nov 24 12:22:25 GMT 1993
Date: Wed, 24 Nov 1993 12:22:25 GMT
From: pgl@imada.ou.dk (Peter Gorm Larsen)
Reply-To: LitProg@SHSU.edu, pgl@IMADA.OU.DK
To: LitProg@SHSU.EDU
Subject: Context sensitive font-lock in emacs ?
 
We have produced a tool supporting the specification language called
VDM-SL. The tool is called "The IFAD VDM-SL Toolbox" and it has an
interface which is built on top of GNU emacs. this tool uses literate
programming (or specification in this case) because we are considering
VDM-SL specifications as part of LaTeX documents. Thus, we have an
environment (\begin{vdm_al} ... \end{vdm_al}) inside which ASCII VDM-SL
specifications are written, whereas the rest of the document are purely
a LaTeX document. The tools we have produce are then able to perform a
number of different kinds of analysis of the VDM specifications (such
as type-checking and execution). However, we have looked at the
font-lock.el macros for emacs which are used to change fonts for certain
reserved words. We would like to be able to use something like this in a
context sensitive way (such that it would only change font of keyword if
it is inside the VDM environment). A similar kind of desire is connected
to spell-checkking of such documents where one would like to be able to
simply spell-check the text and not the formulae. I wonder whether
anyone else in the literate programming community have solved these
context sensitiveity problems already. If so, please let me know about
it.
 
Thanks in advance
Peter
-------------------------------------------------------------
Peter Gorm Larsen
The Institute of Applied Computer Science (IFAD)
Forskerparken 10, DK-5230 Odense M, Denmark
Phone: +45-65932300, Fax: +45-65-932999, Email: peter@ifad.dk
-------------------------------------------------------------
 
From UPP201@ibm.rhrz.uni-bonn.de Wed Nov 24 16:29:22 MEZ 1993
Date: Wed, 24 Nov 93 16:29:22 MEZ
From: UPP201@ibm.rhrz.uni-bonn.de (Michael Burschik)
Reply-To: LitProg@SHSU.edu, UPP201@IBM.RHRZ.UNI-BONN.DE
To: LitProg@SHSU.EDU
Subject: Re: Embedded documentation
 
In article <17383187@MVB.SAIC.COM>
Christian Lynbech <lynbech@daimi.aau.dk> writes:
 
>Thanks for the info.
>
>> The biggest drawback of LaTeXinfo is that you partly need Emacs. The LaTeX
>> style is their, so printed output is not a problem but generating an
>> info file is: the program was written as an Emacs macro. And no
>> way I am going to use that 'editor'. No wars, please, just MHO.
>
>To me, this is a feature, as you might have guessed from my .sig :-)
>I'll choose tools after how well the work with emacs, not the other
>way around. No way I'm goeing to use any other editor, but I know that
>everybody doesn't subscribe to that view. IMVHO.
>
>
>------------------------------------------------------------------------------
>Christian Lynbech               | Hit the philistines three times over the
>                                | head with the Elisp reference manual.
>email: lynbech@daimi.aau.dk     |        - petonic@hal.com (Michael A. Petonic)
>------------------------------------------------------------------------------
 
If this is the same as TeXinfo, then you can use the standalone info
browser, which is small and neat and does not require emacs.
 
Cheers,
        Mike.
 
From Lee Wed Nov 24 12:35:40 EST 1993
Date: Wed, 24 Nov 93 12:35:40 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu
Subject: [Paul Ceruzzi <NASEM001@sivm.bitnet>: Software Archives Report]
 
The following came in on a ``History of Computing'' discussion group
that I subscribe to.  I think the idea of software archives is
particularly interesting w/r/t literate programs, and all you LP'ers
out there might be interested.
 
		-- Lee
		   leew@pilot.njin.net
 
                ---------------
 
Received: from vtbit.cc.vt.edu by pilot.njin.net (5.59/SMI4.0/RU1.5/3.08) 
	id AA04606; Wed, 24 Nov 93 10:44:15 EST
Message-Id: <9311241544.AA04606@pilot.njin.net>
Received: from UMDD.UMD.EDU by VTBIT.CC.VT.EDU (IBM VM SMTP V2R2)
   with BSMTP id 8306; Wed, 24 Nov 93 10:39:22 EST
Received: from UMDD.UMD.EDU by UMDD.UMD.EDU (Mailer R2.10 ptf000) with BSMTP id
 9382; Wed, 24 Nov 93 10:39:21 EST
Date:         Wed, 24 Nov 1993 09:11:08 -0500
Reply-To: History of Computing Issues <SHOTHC-L@sivm.bitnet>
Sender: History of Computing Issues <SHOTHC-L@sivm.bitnet>
From: Paul Ceruzzi <NASEM001@sivm.bitnet>
Subject:      Software Archives Report
To: Multiple recipients of list SHOTHC-L <SHOTHC-L@sivm.bitnet>
 
This came from David Allison.  He welcomes comments privately, or you may post
your comments on this list.
*** Forwarding note from .       --.        11/23/93 18:42 ***
Return-Path: <@SIVM.SI.EDU:dkallison@AOL.COM>
Received: from SIVM (NJE origin SMTP@SIVM) by SIVM.SI.EDU (LMail V1.1d/1.7f)
          with BSMTP id 9792; Tue, 23 Nov 1993 18:42:26 -0500
Received: from mailgate.prod.aol.net by SIVM.SI.EDU (IBM VM SMTP V2R2) with
TCP;
   Tue, 23 Nov 93 18:42:25 EST
Received: by mailgate.prod.aol.net
        (1.37.109.4/16.2) id AA18334; Tue, 23 Nov 93 18:23:16 -0500
From: dkallison@aol.com
X-Mailer: America Online Mailer
Sender: "dkallison" <dkallison@aol.com>
Errors-To: <dkallison@aol.com>
Reply-To: <dkallison@aol.com>
Message-Id: <9311231823.tn238487@aol.com>
To: nasem001@sivm.si.edu
Date: Tue, 23 Nov 93 18:23:10 EST
Subject: Software Archives Report
 
Following is the report for the meeting of the software archives planning
group.  I'd like to get any comments those of you who participated might
have.
 
Paul Ceruzzi:  I'd also like to get the comments of the people in your
list-serve.  I don't know exactly how to get the report on the system, so I'd
appreciate it if you would put it out for comment.  Thanks for the help.  You
can reach me at this America on-line address or also at mahcis01@sivm.si.edu
_____
 
National Software Archives:  Exploring the Concept
 
Early in 1993, several representatives of major historical and cultural
organizations met with American software companies to discuss the need for a
"National Software Archives."  The discussion began with a simple reflection:
 Software is unquestionably among the most important contributions of recent
generations to the history of mankind.  Yet little thought or effort has been
devoted to how it should be preserved for both short and long-term purposes.
Resolving this issue is important to corporations that create software.
America is the premier producer of software for the global market, and these
corporations need to know how to fulfill their responsibilities to maintain
appropriate records.
Before a nation-wide a
rchives is established, there are many questions to answer.  Among them:
- What fraction o
f software and supporting records should be saved?
- What preservation standards should be adopted?
 
- Should manuals and marketing materials be preserved ?  What about
videotapes or other media?
- Where would the archives reside?
- How will the archives be catalogued?
- How would the archives be used?
On October 15-16, 1993, a second meeting of representatives of major
organizations was held in Seattle to discuss the formal establishment of a
National Software Archives.  Institutions participating included:  The
Smithsonian Institution, the Library of Congress, The Annals of the History
of Computing, Stanford University, Microsoft, Apple Computer, Hewlett
Packard, and Word Perfect.  Other institutions and corporations had
previously expressed strong interest in the project, but were unable to
attend this initial meeting.
Those attending the meeting agreed on  a number of significant points.  Th
ey are: conclusions.  Among them
- A "National Software Archives" should be established.
-
 The Archives should not reside in a single institution, but have elements
housed in many different organizations, including software producing
companies, universities, libraries, cultural organizatio
ns, and museums.
- A National reviewing body would be formed that included representatives of
cultural and historical organizations, universities,  industry associations,
information technology companies, and appropriate small firms or individuals.
 This group would establish standards for the collection, review and select
potential submissions, and review management of existing items in the
collection.  The
 body would meet at least once a year.
- One institution should serve as the coordinating institution for the
project, and at least one full-time staff person should be hired to work on
the project.  This person should be involved in both educating participants
and potential participants on the project and the procedures and standards
necessary for participation.  The person should also be in charge of
cataloging official entries into the collection.  Funding for the position
might come from contributio
ns of participants in the project or from grant funding.
- The first area of focus would b
e microcomputer software from US based corporations.
- The National Software Collection would include only those software
materials deemed to have very long-term or permanent significance to Software
 companies, the Information Technology Industry, or the History of the United
States
- An appealing marking system would be developed for identifying items that
had been accessioned in the national software archive.  This marking, and the
associated product names, would be made suitable for display in corporations
who participated in the project and whose products had been selected for
inclusion in the collection.  The marking would also be put on storage boxes
or other media holding the materials included in the
 collection to distinguish the items from general corporate record materials.
 
- The Collection would begin with core software materials, such as source
code, compilers, make files, and actual products.  However it would also
include supporting materials.  These include (where possible) hardware on
which the software could be run (recognizing that the active life of hardware
will probably be much shorter than that of the software);  contextual
materials, such as rights and contracts, development files and electronic
mail documents, management and administrative information, and  business
plans;  and  collateral materials, such as manuals, support records,
packaging, promotional materials, and oral and vide
o histories with principal participants.
- Setting standards and procedures for catalogi
ng and managing the collection should be a collaborative endeavor.
- The collection should be cataloged in an existing national bibliographic
database, such as RLIN or OCLC, that is readily accessible to both
participants and researchers.  Cataloging conventions should follow current
professional standards where possible (i.e. MARC standards), and new
standards should be developed where required in conjuncti
ons with current national efforts.
- Cataloging in the collection would be on different levels:  collection,
sub-collection, and item levels.  Most entries would be only bibliographic in
nature, but some would include full text of items.  Examples are general
descriptions of the software or major fe
atures, as might appear in press releases or general reports.
- Access to some portions of the archives should be restricted for
proprietary reasons.
Obviously many questions remain to be answered.  The group realized that
resolving even the major issues will take several years.  However all agreed
that a start on the project should be made, and development of procedures and
standards evolved incrementally.  At the conclusion of the Seattle meeting,
the participants agreed on a series of subsequent acti
ons.  They were:
- To open the idea of a National Software Archives for discussion over th
e Internet
- To gather additional comments on the ideas above through circulation of
this report to
 many individuals  and soliciting comment
- To explore details related to staffing the project a
nd cataloging the entries with the appropriate parties
- To ask respected experts to begin compilin
g lists of potential software materials that should be included in the
National Collection
- To plan a Spring Meeting at the Smithsonian Institution in Spring 1994 to
develop the idea further, and to broaden attendance at this meeting to a
larger spectrum of interested parties
- To use the Spring meeting and the period following to develop specific
plans for funding implementing the  National Software Archives, with a
planned start-up date of early 1995
 
From Lee Wed Nov 24 12:38:12 EST 1993
Date: Wed, 24 Nov 93 12:38:12 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, epasos@sfsuvax1.sfsu.edu
Subject: Re: Enfin..
 
Henry Pasos writes:
 
> I am curious if anyone is using Easel's Enfin product.  I use it at work
> but haven't run into anyone else who uses it.
> I'm just curious to know what others are doing with it.
 
Forgive my ignorance, but what is ``Easel's Enfin product?''  Was I
napping when its description came over the net?
 
		-- Lee
		   leew@pilot.njin.net
 
From D.C.Ince@open.ac.uk Wed Nov 24 18:40:06 +0000 1993
Date: Wed, 24 Nov 1993 18:40:06 +0000
From: D.C.Ince@open.ac.uk (Darrel Ince)
Reply-To: LitProg@SHSU.edu, D.C.Ince@OPEN.AC.UK
To: LitProg@SHSU.edu
Subject: Re: Enfin..
 
I have spent the last six months experimenting with literate programming
as a prepreation to writing a book on programming and data types in 
a literate programming style. Could anyone help me with two questions.
 
First, is there an implementation of web and weave for the Macintosh
and where can I find it?
 
Second, does anyone know of any books written or in progress that deal with
programming, algorithms and data types that use the literate programming
idea?
 
Darrel Ince
 
From j_mcarthur@BIX.com Mon Nov 29 00:57:32 -0500 1993
Date: Mon, 29 Nov 1993 00:57:32 -0500 (EST)
From: j_mcarthur@BIX.com
Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM
To: LitProg@SHSU.edu
Subject: Simple Lex Literate ProgramKKK
 
I have just completed a simple little literate program.  The
program takes an quote delimited file, like one exported
from dBase or Paradox, and replaces the quotes with tags
so that it can be processed via TeX.
 
This program is written in the original Pascal Web.  The
output of Tangle is then processed by Albert Graef's
TP Lex program to create a pascal program.
 
Weave generates a reasonable output file.  Since this is
a fairly small program, I am including it in the message.
 
First the WEB file.
-------------------------------- cut here --------------------------------
\let\]=\empty
 
\def\BS{{\tt\char"5C}}
 
\def\Lex{{\bf Lex}}
\def\Yacc{{\bf Yacc}}
 
\def\verb{\futurelet\next\TestVerb}
 
\chardef\other = 12
 
\def\uncatcodespecials{%
   \def\do##1{\catcode`##1 = \other}%
   \dospecials
}%
 
\def\TestVerb{%
    \ifx\next"\let\next=\DoubleQuoteVerb\else%
        \let\next=\SingleQuoteVerb\fi%
    \begingroup\uncatcodespecials\next}
 
\def\DoubleQuoteVerb"#1"{{\tt#1}\endgroup}
\def\SingleQuoteVerb'#1'{{\tt#1}\endgroup}
 
\font\sc=cmcsc10
 
@* Introduction.
This program converts a quote delimited file into a \TeX\ tag delimited
file.  This is done using TP \Lex\ written by Albert Graef.
 
@ The first thing that needs to be defined are the different parts of
a \Lex\ program.  A \Lex\ program has three main parts:  definition,
rules, and supplemental routines.
 
Each section of a \Lex\ is identified by a sequence of characters
at the start of a line.  The character sequences are defined as macros
to make them easier to see and to understand.
 
@d START_DEFINITION==@=%{@>@\
@d END_DEFINITION==@=%}@>@\
@#
@d START_RULES==@=%%@>@\
@d END_RULES==@=%%@>@\
 
@ In addition to defining the macros we need to specify how to
format them.  They are formatted the same as the program statement.
 
@f START_DEFINITION==program
@f END_DEFINITION==program
@#
@f START_RULES==program
@f END_RULES==program
 
@ The definition section of a \Lex\ program contains the program header
and such.  Actually since it contains Pascal code we can code it
up easily.
 
@ Since this is compiled using Borland Pascal one final formatting
command needs to be added.  
@f uses==const
 
@ A \Lex\ program is not that complex.  It is actually very similar
to a conventional Pascal program.  Here is the layout of our \Lex\ program:
 
@p START_DEFINITION@t\2@>
program TagMl;
uses @<Units that are used by the program@>@/
const @<Constants in the outer block@>@/
type @<Types in the outer block@>@/
const @<Typed Constants in the outer block@>@/
var @<Globals in the outer block@>@t\2@>@\@/
END_DEFINITION@t\2@>@/
START_RULES@t\2@>@/
@<Lex production rules go here@>@\@/
END_RULES@t\2@>@/
@<Main body of the program@>@/
 
@ The program uses the LexLib unit.  This provides the utility
functions need by a \Lex\ program.  If any other
units were needed they could be included here.
 
@<Units that are used by the program@>=
LexLib;
 
@ There are eleven fields in the database.  This number
is important.  Each fields is processed in turn.  A
constant is needed so a type can be created to store
the strings.
 
@<Constants in the outer block@>=
    NumberOfFields = 11;
 
@ TagStrArray is the name of the type created to store
the strings used in tagging the data.
 
@<Types in the outer block@>=
    TagStrArray = array [1..NumberOfFields] of string;
 
@ Borland Pascal provides the feature of structured constants.
We take advantage of this feature and define the string arrays.
 
@<Typed Constants in the outer block@>=
    TagStr: TagStrArray = ( 'Salutation',@/
                            'FirstName',@/
                            'MiddleName',@/
                            'LastName',@/
                            'Honorific',@/
                            'AddressA',@/
                            'AddressB',@/
                            'AddressC',@/
                            'City',@/
                            'State',@/
                            'Zip');@/
 
@ As the data is processed, each field must be accessed in turn.
To keep track of the field we need a simple variable.  Here is
the declaration of the field tracking variable.
 
@<Globals in the outer block@>=
    field: integer;
 
@ There are six parts to line from a quote delimited file:  starting quote,
quote-comma-quote, ending quote, the data, and the end of line.
Each section needs to be processed
separately.  Each section will have its own \Lex\ rule.
 
@<Lex production rules go here@>=
@<Match Starting Quote@>@/
@<Match Quote-Comma-Quote@>@/
@<Match Ending Quote@>@/
@<Match Strings@>@/
@<Match End-Of-Line@>
 
@ \Lex\ uses regular expressions to specify the patterns to match.  Below 
is a table showing all the possible expressions.  Tagging an quote delimited
file will only use a few of these.
$$\vbox{\offinterlineskip%
\halign{%
\quad\hfil#\hfil\quad\vrule&
\quad\hfil#\hfil\quad\vrule&
\quad\hfil#\hfil\quad\strut\cr
%\begin{table*}\centering
%   \begin{tabular}{c|c|c}
\noalign{\hrule}
\noalign{\vskip2pt}
\noalign{\hrule}
{\sc Expression}& {\sc Matches}& {\sc Example}\cr
\noalign{\hrule}
$c$& any non-operator character $c$& \verb"a"\cr
\verb"\"$c$& character $c$ literally& \verb"\*"\cr
\verb'"'$s$\verb'"'& string $s$ literally& \verb'"**"'\cr
\verb"."& any character but newline& \verb"a.*b"\cr
\verb"^"& beginning of line& \verb"^abc"\cr
\verb"$"& end of line& \verb"abc$"\cr
\verb"["$s$\verb"]"& any character in $s$& \verb"[abc]"\cr
\verb"[^"$s$\verb"]"& any character not in $s$& \verb"[^abc]"\cr
$r$\verb"*"& zero or more $r$'s& \verb"a*"\cr
$r$\verb"+"& one or more $r$'s& \verb"a+"\cr
$r$\verb"?"& zero or one $r$& \verb"a?"\cr
$r$\verb"{"$m$\verb","$n$\verb"}"& $m$ to $n$ occurrences of $r$
& \verb"a{1,5}"\cr
$r$\verb"{"$m$\verb"}"& $m$ occurrences of $r$& \verb"a{5}"\cr
$r_1r_2$& $r_1$ then $r_2$& \verb"ab"\cr
$r_1$\verb"\char"7C"$r_2$& $r_1$ or $r_2$& \verb"a\char"7Cb"\cr
\verb"("$r$\verb")"& $r$& \verb"(a\char"7Cb)"\cr
$r_1$\verb"/"$r_2$& $r_1$ when followed by $r_2$& \verb"a/b"\cr
\verb"<"$x$\verb">"$r$& $r$ when in start condition $x$& \verb"<x>abc"\cr
\noalign{\hrule}
}}$$
 
@ First we want to process the quote at the start of the line.
The up arrow specifies the start of line.  Quotes are used to
delimit special characters, so a backslash is used to delimit
the quote.  Finally a space or tab follows the regular expression.
This is required for \Lex\ to determine the end of the regular
expression and the start of the Pascal code.  The Pascal code
does two things.  It resets |field| to one, and
outputs the \BS StartRec tag.  One comment about |yyoutput|.
The unit |LexLib| opens two files:  |yyinput| for input
and |yyoutput| for output.  By default both of these files
are the same as |input| and |output|.  \Lex\ programs
are set up to run as filters.  They take the input one line
at a time from the standard input, process it, and write the
output to the standard output.
 
@<Match Starting Quote@>=
@=^\"   @>@t\quad@>begin
                field := 1;
                writeln(yyoutput, '\StartRec');
            end;@/@\
 
@ Between each field is a quote-comma-quote.  This pattern
is used to increments |field.|  The pattern is quote-comma-quote.
However quotes need to be preceded by a backslash and the pattern
must be followed by a tab or space.
 
@<Match Quote-Comma-Quote@>=
@=\",\" @>@t\quad@> inc(field);@/@\
 
@ The dollar sign, \$, is used to specify the end of line in
a regular expression.  The Pascal code outputs the \BS EndRec
tag.
 
@<Match Ending Quote@>=
@=\"$   @>@t\quad@>         write(yyoutput, '\EndRec');@/@\
 
@ Finding the data string is quite easy.  Anything that is not
a quote or an end of line will match.  The Pascal code looks
up the tag and delimites the data.  This does not properly
handle embedded quotes {\tt "} or embedded curly braces
{\tt\char"7B} and {\tt\char"7D}.  This could be done by using
a start state.  But for most data this is process should
work.
 
@<Match Strings@>=
@=[^\"\n]*  @>@t\quad@> writeln(yyoutput, '\', TagStr[field],
 '{', yytext, '}');@/@\
 
@ The end of line is just echoed.  No special processing is
required.  This section could be omitted since the default
action of a \Lex\ program is to echo the output.  |echo|
is a procedure defined in |LexLib|.  It writes the
input string to |yyoutput|.
 
@<Match End-Of-Line@>=
@=\n    @>@t\quad@>         echo;
 
@ Now for the end of the \Lex\ program.  \Lex\ creates
a function |yylex|.  This function can return a wide
variety of values.  The return value of |yylex| is used
by \Yacc.  This program does not require \Yacc\ and so
|yylex| only returns at the end of the file.  One difference
between the Pascal and C version of Lex is the need for
the main body of the program.  In C |LexLib| would include
a function |main| that would call |yylex|.
 
@<Main body of the program@>=
begin
    if yylex = 0 then ;
end.
 
@* Index.
Here is the index of the program.
 
-------------------------------- cut here --------------------------------
 
Now for the TeX file generate by WEAVE (for those who don't have
WEAVE).
 
-------------------------------- cut here --------------------------------
\input webmac
\let\]=\empty
 
\def\BS{{\tt\char"5C}}
 
\def\Lex{{\bf Lex}}
\def\Yacc{{\bf Yacc}}
 
\def\verb{\futurelet\next\TestVerb}
 
\chardef\other = 12
 
\def\uncatcodespecials{%
   \def\do##1{\catcode`##1 = \other}%
   \dospecials
}%
 
\def\TestVerb{\ifx\next"\let\next=\DoubleQuoteVerb\else\let\next=%
\SingleQuoteVerb\fi%
 \begingroup\uncatcodespecials\next}
 
\def\DoubleQuoteVerb"#1"{{\tt#1}\endgroup}
\def\SingleQuoteVerb'#1'{{\tt#1}\endgroup}
 
\font\sc=cmcsc10
 
\N1.  Introduction.
This program converts a quote delimited file into a \TeX\ tag delimited
file.  This is done using TP \Lex\ written by Albert Graef.
 
\fi
 
\M2. The first thing that needs to be defined are the different parts of
a \Lex\ program.  A \Lex\ program has three main parts:  definition,
rules, and supplemental routines.
 
Each section of a \Lex\ is identified by a sequence of characters
at the start of a line.  The character sequences are defined as macros
to make them easier to see and to understand.
 
\Y\P\D \37$\\{START\_DEFINITION}\S\={\%\{}\]$\par
\P\D \37$\\{END\_DEFINITION}\S\={\%\}}\]$\Y\par
\P\D \37$\\{START\_RULES}\S\={\%\%}\]$\par
\P\D \37$\\{END\_RULES}\S\={\%\%}\]$\par
\fi
 
\M3. In addition to defining the macros we need to specify how to
format them.  They are formatted the same as the program statement.
 
\Y\P\F \37$\\{START\_DEFINITION}\S\\{program}$\par
\P\F \37$\\{END\_DEFINITION}\S\\{program}$\Y\par
\P\F \37$\\{START\_RULES}\S\\{program}$\par
\P\F \37$\\{END\_RULES}\S\\{program}$\par
\fi
 
\M4. The definition section of a \Lex\ program contains the program header
and such.  Actually since it contains Pascal code we can code it
up easily.
 
\fi
 
\M5. Since this is compiled using Borland Pascal one final formatting
command needs to be added.
\Y\P\F \37$\\{uses}\S\\{const}$\par
\fi
 
\M6. A \Lex\ program is not that complex.  It is actually very similar
to a conventional Pascal program.  Here is the layout of our \Lex\ program:
 
\Y\P\4\&{START\_DEFINITION} \1\  \hbox{\2} \6
\4\&{program}\1\  \37\\{TagMl};\6
\4\&{uses} \37\X7:Units that are used by the program\X\6
\4\&{const} \37\X8:Constants in the outer block\X\6
\4\&{type} \37\X9:Types in the outer block\X\6
\4\&{const} \37\X10:Typed Constants in the outer block\X\6
\4\&{var} \37\X11:Globals in the outer block\X\hbox{\2}\]\6
\4\&{END\_DEFINITION}\1\  \37\hbox{\2}\6
\4\&{START\_RULES}\1\  \37\hbox{\2}\6
\X12:Lex production rules go here\X\]\6
\4\&{END\_RULES}\1\  \37\hbox{\2}\6
\X19:Main body of the program\X\par
\fi
 
\M7. The program uses the LexLib unit.  This provides the utility
functions need by a \Lex\ program.  If any other
units were needed they could be included here.
 
\Y\P$\4\X7:Units that are used by the program\X\S$\6
\\{LexLib};\par
\U6.\fi
 
\M8. There are eleven fields in the database.  This number
is important.  Each fields is processed in turn.  A
constant is needed so a type can be created to store
the strings.
 
\Y\P$\4\X8:Constants in the outer block\X\S$\6
$\\{NumberOfFields}=11$;\par
\U6.\fi
 
\M9. TagStrArray is the name of the type created to store
the strings used in tagging the data.
 
\Y\P$\4\X9:Types in the outer block\X\S$\6
$\\{TagStrArray}=$\1\5
\&{array} $[1\to\\{NumberOfFields}]$ \1\&{of}\5
\\{string};\2\2\par
\U6.\fi
 
\M10. Borland Pascal provides the feature of structured constants.
We take advantage of this feature and define the string arrays.
 
\Y\P$\4\X10:Typed Constants in the outer block\X\S$\6
\4\\{TagStr}: \37$\\{TagStrArray}=($$\.{\'Salutation\'},\39$\6
$\.{\'FirstName\'},\39$\6
$\.{\'MiddleName\'},\39$\6
$\.{\'LastName\'},\39$\6
$\.{\'Honorific\'},\39$\6
$\.{\'AddressA\'},\39$\6
$\.{\'AddressB\'},\39$\6
$\.{\'AddressC\'},\39$\6
$\.{\'City\'},\39$\6
$\.{\'State\'},\39$\6
\.{\'Zip\'}$)$;\par
\U6.\fi
 
\M11. As the data is processed, each field must be accessed in turn.
To keep track of the field we need a simple variable.  Here is
the declaration of the field tracking variable.
 
\Y\P$\4\X11:Globals in the outer block\X\S$\6
\4\\{field}: \37\\{integer};\par
\U6.\fi
 
\M12. There are six parts to line from a quote delimited file:  starting quote,
quote-comma-quote, ending quote, the data, and the end of line.
Each section needs to be processed
separately.  Each section will have its own \Lex\ rule.
 
\Y\P$\4\X12:Lex production rules go here\X\S$\6
\X14:Match Starting Quote\X\6
\X15:Match Quote-Comma-Quote\X\6
\X16:Match Ending Quote\X\6
\X17:Match Strings\X\6
\X18:Match End-Of-Line\X\par
\U6.\fi
 
\M13. \Lex\ uses regular expressions to specify the patterns to match.  Below
is a table
showing all the possible expressions.  Tagging an quote delimited file will
only
use a few of these.
$$\vbox{\offinterlineskip%
\halign{\quad\hfil#\hfil\quad\vrule&\quad\hfil#\hfil\quad\vrule&\quad\hfil#%
\hfil\quad\strut\cr
%\begin{table*}\centering
%   \begin{tabular}{c\|cc}
\noalign{\hrule}
\noalign{\vskip2pt}
\noalign{\hrule}
{\sc Expression}& {\sc Matches}& {\sc Example}\cr
\noalign{\hrule}
$c$& any non-operator character $c$& \verb"a"\cr
\verb"\"$c$& character $c$ literally& \verb"\*"\cr
\verb'"'$s$\verb'"'& string $s$ literally& \verb'"**"'\cr
\verb"."& any character but newline& \verb"a.*b"\cr
\verb"^"& beginning of line& \verb"^abc"\cr
\verb"$"& end of line& \verb"abc$"\cr
\verb"["$s$\verb"]"& any character in $s$& \verb"[abc]"\cr
\verb"[^"$s$\verb"]"& any character not in $s$& \verb"[^abc]"\cr
$r$\verb"*"& zero or more $r$'s& \verb"a*"\cr
$r$\verb"+"& one or more $r$'s& \verb"a+"\cr
$r$\verb"?"& zero or one $r$& \verb"a?"\cr
$r$\verb"{"$m$\verb","$n$\verb"}"& $m$ to $n$ occurrences of $r$& \verb"a{1,5}"%
\cr
$r$\verb"{"$m$\verb"}"& $m$ occurrences of $r$& \verb"a{5}"\cr
$r_1r_2$& $r_1$ then $r_2$& \verb"ab"\cr
$r_1$\verb"\char"7C"$r_2$& $r_1$ or $r_2$& \verb"a\char"7Cb"\cr
\verb"("$r$\verb")"& $r$& \verb"(a\char"7Cb)"\cr
$r_1$\verb"/"$r_2$& $r_1$ when followed by $r_2$& \verb"a/b"\cr
\verb"<"$x$\verb">"$r$& $r$ when in start condition $x$& \verb"<x>abc"\cr
\noalign{\hrule}
}}$$
 
\fi
 
\M14. First we want to process the quote at the start of the line.
The up arrow specifies the start of line.  Quotes are used to
delimit special characters, so a backslash is used to delimit
the quote.  Finally a space or tab follows the regular expression.
This is required for \Lex\ to determine the end of the regular
expression and the start of the Pascal code.  The Pascal code
does two things.  It resets \\{field} to one, and
outputs the \BS StartRec tag.  One comment about \\{yyoutput}.
The unit \\{LexLib} opens two files:  \\{yyinput} for input
and \\{yyoutput} for output.  By default both of these files
are the same as \\{input} and \\{output}.  \Lex\ programs
are set up to run as filters.  They take the input one line
at a time from the standard input, process it, and write the
output to the standard output.
 
\Y\P$\4\X14:Match Starting Quote\X\S$\6
\={\^\\"\ }\hbox{\quad} \6
\&{begin} \37$\\{field}\K1$;\5
$\\{writeln}(\\{yyoutput},\39\.{\'\\StartRec\'})$;\6
\&{end};\6
\]\par
\U12.\fi
 
\M15. Between each field is a quote-comma-quote.  This pattern
is used to increments \\{field}.  The pattern is quote-comma-quote.
However quotes need to be preceded by a backslash and the pattern
must be followed by a tab or space.
 
\Y\P$\4\X15:Match Quote-Comma-Quote\X\S$\6
$\={\\",\\"\ }\hbox{\quad}\\{inc}(\\{field})$;\6
\]\par
\U12.\fi
 
\M16. The dollar sign, \$, is used to specify the end of line in
a regular expression.  The Pascal code outputs the \BS EndRec
tag.
 
\Y\P$\4\X16:Match Ending Quote\X\S$\6
$\={\\"\$\ }\hbox{\quad}\\{write}(\\{yyoutput},\39\.{\'\\EndRec\'})$;\6
\]\par
\U12.\fi
 
\M17. Finding the data string is quite easy.  Anything that is not
a quote or an end of line will match.  The Pascal code looks
up the tag and delimites the data.  This does not properly
handle embedded quotes {\tt "} or embedded curly braces
{\tt\char"7B} and {\tt\char"7D}.  This could be done by using
a start state.  But for most data this is process should
work.
 
\Y\P$\4\X17:Match Strings\X\S$\6
$\={[\^\\"\\n]*\ }\hbox{\quad}\\{writeln}(\\{yyoutput},\39\.{\'\\\'},\39%
\\{TagStr}[\\{field}],\39\.{\'\{\'},\39\\{yytext},\39\.{\'\}\'})$;\6
\]\par
\U12.\fi
 
\M18. The end of line is just echoed.  No special processing is
required.  This section could be omitted since the default
action of a \Lex\ program is to echo the output.  \\{echo}
is a procedure defined in \\{LexLib}.  It writes the
input string to \\{yyoutput}.
 
\Y\P$\4\X18:Match End-Of-Line\X\S$\6
\={\\n\ }\hbox{\quad}\\{echo};\par
\U12.\fi
 
\M19. Now for the end of the \Lex\ program.  \Lex\ creates
a function \\{yylex}.  This function can return a wide
variety of values.  The return value of \\{yylex} is used
by \Yacc.  This program does not require \Yacc\ and so
\\{yylex} only returns at the end of the file.  One difference
between the Pascal and C version of Lex is the need for
the main body of the program.  In C \\{LexLib} would include
a function \\{main} that would call \\{yylex}.
 
\Y\P$\4\X19:Main body of the program\X\S$\6
\&{begin} \37\&{if} $\\{yylex}=0$ \1\&{then}\5
;\2\6
\&{end}.\par
\U6.\fi
 
\N20.  Index.
Here is the index of the program.
\fi
 
\inx
\:\&{const}, 5.
\:\\{echo}, 18.
\:\&{END\_DEFINITION}, \[2], \[3].
\:\&{END\_RULES}, \[2], \[3].
\:\\{field}, 11, 14, 15, 17.
\:\\{inc}, 15.
\:\\{input}, 14.
\:\\{integer}, 11.
\:\\{LexLib}, 7, 14, 18, 19.
\:\\{main}, 19.
\:\\{NumberOfFields}, 8, 9.
\:\\{output}, 14.
\:\&{program}, 3, \[6].
\:\&{START\_DEFINITION}, \[2], \[3].
\:\&{START\_RULES}, \[2], \[3], \[6].
\:\\{string}, 9.
\:\\{TagMl}, \[6].
\:\\{TagStr}, 10, 17.
\:\\{TagStrArray}, 9, 10.
\:\&{uses}, \[5].
\:\\{write}, 16.
\:\\{writeln}, 14, 17.
\:\\{yyinput}, 14.
\:\\{yylex}, 19.
\:\\{yyoutput}, 14, 16, 17, 18.
\:\\{yytext}, 17.
\fin
\:\X8:Constants in the outer block\X
\U6.
\:\X11:Globals in the outer block\X
\U6.
\:\X12:Lex production rules go here\X
\U6.
\:\X19:Main body of the program\X
\U6.
\:\X18:Match End-Of-Line\X
\U12.
\:\X16:Match Ending Quote\X
\U12.
\:\X15:Match Quote-Comma-Quote\X
\U12.
\:\X14:Match Starting Quote\X
\U12.
\:\X17:Match Strings\X
\U12.
\:\X10:Typed Constants in the outer block\X
\U6.
\:\X9:Types in the outer block\X
\U6.
\:\X7:Units that are used by the program\X
\U6.
\con
-------------------------------- cut here --------------------------------
 
It would be interresting to see what a convensional Lex program looked
like if it where processed via CWeb, FWeb, etc.
 
----
    Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur
    a.k.a. Jeffrey McArthur          ATLIS Publishing
    phone: (301) 210-6655            12001 Indian Creek Court
    fax:   (301) 210-4999            Beltsville, MD  20705
    email: j_mcarthur@bix.com
 
From Nico Mon Nov 29 00:57:32 -0500 1993
Date: Mon, 29 Nov 1993 00:57:32 -0500 (EST)
From: Nico MACK <nico.mack@crpht.lu>
Reply-To: LitProg@SHSU.edu, nico.mack@CRPHT.LU
To: LitProg@SHSU.EDU
Subject: 6303 Cross Assembler for MPW
 
Hello world...
 
I'm looking for a cross-assembler running under MPW for the 6303,
respectively the 6801 micro-controller. Who knows where I may find 
this tool ?
																																	Many thanks
																																												Nico
 
From lynbech@daimi.aau.dk Mon Nov 29 00:57:32 -0500 1993
Date: Mon, 29 Nov 1993 00:57:32 -0500 (EST)
From: lynbech@daimi.aau.dk (Christian Lynbech)
Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK
To: LitProg@SHSU.EDU
Subject: Re: Embedded documentation
 
Thus spake UPP201@ibm.rhrz.uni-bonn.de (Michael Burschik):
 
>If this is the same as TeXinfo, then you can use the standalone info
>browser, which is small and neat and does not require emacs.
> 
 
The LaTeXinfo package generates ordinary info files. The info format
is an ascii format that can be browsed by a number of tools, including
emacs and the above mentioned standalone reader (part of the GNU
TeXinfo distribution).
 
In fact (La)TeXinfo is not necessary as source. Any program could
generate information in the info format and have the tools work on it.
But one would of course loose the hardcopy option.
 
------------------------------------------------------------------------------
Christian Lynbech               | Hit the philistines three times over the 
				| head with the Elisp reference manual.
email: lynbech@daimi.aau.dk	|        - petonic@hal.com (Michael A. Petonic)
------------------------------------------------------------------------------
 
From schrod@iti.informatik.th-darmstadt.de Mon Nov 29 15:57:24 GMT 1993
Date: Mon, 29 Nov 1993 15:57:24 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Enfin..
 
In article <17848173@MVB.SAIC.COM>, D.C.Ince@open.ac.uk (Darrel Ince) writes:
> 
> Second, does anyone know of any books written or in progress that deal with
> programming, algorithms and data types that use the literate programming
> idea?
 
Knuth's new book about the Stanford Graph Base (basically a preprint
of a Vol. 4 part).
 
	Joachim
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From crabb@tucson.Princeton.EDU Mon Nov 29 15:57:24 GMT 1993
Date: Mon, 29 Nov 1993 15:57:24 GMT
From: crabb@tucson.Princeton.EDU (David W Crabb)
Reply-To: LitProg@SHSU.edu, crabb@TUCSON.PRINCETON.EDU
To: LitProg@SHSU.EDU
Subject: Re: Perl programs - how to put free form annotations at the top
 
#!perl
 
>>PROLOGUE;
 
	Free-form discussion comes here.
        ...
 
PROLOGUE
 
# Code follows:     
 
__END__
 
   Regards, 
 
        David
 
-- 
David Crabb
crabb@phoenix.princeton.edu
 
From domi@grenoble.hp.com Mon Nov 29 15:57:24 GMT 1993
Date: Mon, 29 Nov 1993 15:57:24 GMT
From: domi@grenoble.hp.com (Dominique Dumont)
Reply-To: LitProg@SHSU.edu, domi@GRENOBLE.HP.COM
To: LitProg@SHSU.EDU
Subject: compiling a tangled file ?
 
Hello
 
When I compile a perl script tangled with noweb, I often have syntax errors
(well more often than I like to admit :-) ), and the (little) problem I have
is that the compiler gives me the line number of the tangled file, not the
line number of the web file where the error was actually made.
 
Does anyone have a practical way around this problem ?
 
Do you have the same problem with others webs or compiler ?
 
Thanks
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 14 88
-----------------------------------------------------------------------------
 
From crabb@tucson.Princeton.EDU Mon Nov 29 15:57:31 GMT 1993
Date: Mon, 29 Nov 1993 15:57:31 GMT
From: crabb@tucson.Princeton.EDU (David W Crabb)
Reply-To: LitProg@SHSU.edu, crabb@TUCSON.PRINCETON.EDU
To: LitProg@SHSU.EDU
Subject: Re: Perl programs - CORRECTION
 
In the message I just posted, the syntax for the "here document" should be << .
 
#!perl
 
<<PROLOGUE;
 
	Free-form discussion.
 
   etc.
 
-- 
David Crabb
crabb@phoenix.princeton.edu
 
From Zdenek Thu Dec 02 14:20:19 MET 1993
Date: Thu, 02 Dec 93 14:20:19 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, domi@GRENOBLE.HP.COM
Subject: Re: compiling a tangled file ?
 
On 2 Dec 1993 08:25:48 GMT <domi@grenoble.hp.com> said:
>Hello
>
>When I compile a perl script tangled with noweb, I often have syntax errors
>(well more often than I like to admit :-) ), and the (little) problem I have
>is that the compiler gives me the line number of the tangled file, not the
>line number of the web file where the error was actually made.
>
>Does anyone have a practical way around this problem ?
>
>Do you have the same problem with others webs or compiler ?
>
>Thanks
>
>
>-----------------------------------------------------------------------------
>                Name:          Dominique Dumont
>    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
>   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
>  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
>   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
>                Telex,Fax:     980 124 - (33) 76 62 14 88
>-----------------------------------------------------------------------------
 
I use CWEB and Borland C++ 3.0. When I have a syntax error, the compiler
usually shows the place in the web files. However, there are situations
where the error is mistakenly indicated after the end of the tangled file.
If this is the case, I change my makefile and invoke a small program which
commants out the #line directive. Then the compiler indicates the error in the
tangled file and by commented #line directives I manually trace it back to
the web source. It's not nice but better than nothing. This kind of trouble
is not in various webs but in the compilers :-(.
 
Regards
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete and will soon cease to exist!
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From Lee Thu Dec 2 10:35:54 EST 1993
Date: Thu, 2 Dec 93 10:35:54 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, domi@grenoble.hp.com
Subject: Re: compiling a tangled file ?
 
Dominique Dumont writes:
 
> When I compile a perl script tangled with noweb, I often have syntax errors
> (well more often than I like to admit :-) ), and the (little) problem I have
> is that the compiler gives me the line number of the tangled file, not the
> line number of the web file where the error was actually made.
> 
> Does anyone have a practical way around this problem ?
> 
> Do you have the same problem with others webs or compiler ?
 
noweb provides a facility to insert #line-like directives in the
tangled code (I'm not sure what the option is, but it should be easy
to find on the notangle manual page).  This works beautifully, for C &
C++, but I don't know if perl supports any such directive.
 
An alternative (one I frequently  use in PAL webs) is to use this
option to insert the appropriate line numbers as comments in the
tangled code.  Then you can find the line in the tangled version and
back up to the closest line number comment to find the line in the
original web.  It's not perfect, but it's better than nothing.
 
Maybe we LP'ers should start insisting that all new programming
languages have a #line-like facility, and that all old languages
should be retrofitted with one!  Or am I just cranky this morning? :-)
 
		-- Lee
		   leew@pilot.njin.net
 
From domi@grenoble.hp.com Thu Dec 2 10:35:54 EST 1993
Date: Thu, 2 Dec 93 10:35:54 EST
From: domi@grenoble.hp.com (Dominique Dumont)
Reply-To: LitProg@SHSU.edu, domi@GRENOBLE.HP.COM
To: LitProg@SHSU.EDU
Subject: Re: compiling a tangled file ?
 
Thanks for your responses.
 
As usual I think I'll have to hack something. Like a Perl script to help me
compile perl scripts (May be I'm heading in a recursive loop :-( ).
 
-----------------------------------------------------------------------------
                Name:          Dominique Dumont 
    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
                Telex,Fax:     980 124 - (33) 76 62 14 88
-----------------------------------------------------------------------------
 
From Zdenek Fri Dec 03 15:12:17 MET 1993
Date: Fri, 03 Dec 93 15:12:17 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, domi@GRENOBLE.HP.COM
Subject: Re: compiling a tangled file ?
 
On 3 Dec 1993 08:43:50 GMT <domi@grenoble.hp.com> said:
>Thanks for your responses.
>
>As usual I think I'll have to hack something. Like a Perl script to help me
>compile perl scripts (May be I'm heading in a recursive loop :-( ).
>
>
>-----------------------------------------------------------------------------
>                Name:          Dominique Dumont
>    ^^^^^^      Email:         Dominique_Dumont@grenoble.hp.com
>   / O  O \     HP Desk:       Dominique DUMONT / HP6300/UM
>  ( \____/ )    Address :      HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE
>   \______/     Tel,Telnet:    (33) 76 62 57 24 - 7 779 5724
>                Telex,Fax:     980 124 - (33) 76 62 14 88
>-----------------------------------------------------------------------------
 
The recursion may be surprisingly short. I have a small C++ program which
helps me to translate tangled C++ programs produced by CWEB. It's small and
easy and it works (I wrote it within a few minutes in raw C++).
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete and will soon cease to exist!
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From <PJENSEN@CSI.compuserve.com> Fri Dec 03 15:12:17 MET 1993
Date: Fri, 03 Dec 93 15:12:17 MET
From: <PJENSEN@CSI.compuserve.com>
Reply-To: LitProg@SHSU.edu, PJENSEN@CSI.COMPUSERVE.COM
To: <LitProg@shsu.edu>
Subject: CWEB thoughts
 
I just got _The Stanford GraphBase_, and I'm terrifically impressed, as with
everything else DEK has written.  Some thoughts on CWEB, and one or two
questions for anyone who has looked at the sources (I don't have the time
right now).
 
I have considerable distaste for C.  Among the things I wish had been done
differently are: the meaning of = and ==; declaration and typename syntax;
open-ended control constructs (vs. Modula's if...end, while...end etc.);
use of int for Boolean; line-oriented preprocessor; absence of |var|
parameters; treatment of arrays as pointers...
 
But as I read The SGB, I'm thinking - this is okay, I can live happily with
this.  Just as I believe that LP is far more significant than OO, I also
believe it is more important than details of language syntax.  (Semantics
are different - I still want RAISE, TRY..EXCEPT, TRY..FINALLY, and LOCK..DO.)
 
I'm also using CWEB, and am evolving some guidelines:
  - Use a semicolon after every fragment reference occurring in a
	statement-like context;
  - Enclose the body of every statement-like fragment in {...} except
	when it looks silly, as for things like "case N: stmts";
  - Always use {...} after an |if| which is followed by an |else| (and
	never put an |if| and a matching |else| in different fragments!);
  - Otherwise, don't use {...} with control constructs which govern a single
	statement or single fragment reference, EXCEPT
  - Do use {...} if the enclosed fragment has multiple defining occurrences
	(usually things like @<Initialize...@> and @<Handle cases...@>.)
 
[ Disclaimer - all this, like indentation, has elements of religious
  preference - I just post these guidelines for general interest. ]
 
A couple questions, if anyone knows, vis-a-vis CTANGLE:
 
  Knuth gets |struct foobar| with both words in boldface, but I get the
	tag in italic---why?
 
  Knuth seems to get no line break between { and a declaration,
	but I do---why?
 
Thanks and happy LitProgging.
 
Phil Jensen : pjensen@csi.compuserve.com
 
From Lee Sun Dec 5 13:29:36 EST 1993
Date: Sun, 5 Dec 93 13:29:36 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, PJENSEN@csi.compuserve.com
Subject: Re: CWEB thoughts
 
Phil Jensen writes:
 
> I just got _The Stanford GraphBase_, and I'm terrifically impressed, as with
> everything else DEK has written.  Some thoughts on CWEB, and one or two
> questions for anyone who has looked at the sources (I don't have the time
> right now).
> 
>	[text omitted]
> 
> I'm also using CWEB, and am evolving some guidelines:
>   - Use a semicolon after every fragment reference occurring in a
> 	statement-like context;
>   - Enclose the body of every statement-like fragment in {...} except
> 	when it looks silly, as for things like "case N: stmts";
>***- Always use {...} after an |if| which is followed by an |else| (and
> 	never put an |if| and a matching |else| in different fragments!);
>   - Otherwise, don't use {...} with control constructs which govern a single
> 	statement or single fragment reference, EXCEPT
>   - Do use {...} if the enclosed fragment has multiple defining occurrences
> 	(usually things like @<Initialize...@> and @<Handle cases...@>.)
 
I pretty much agree with all of these, and follow them in my own
programs.  I would go further with the one I've marked ***, though.  I
always make sure that each control construct is in a single fragment
(with possible sub-fragments, of course, for nested statements).  The
only exception is in case-like statements:  the "case N:" labels and
their corresponding statements are almost always in the
sub-fragments.
 
> A couple questions, if anyone knows, vis-a-vis CTANGLE:
> 
>   Knuth gets |struct foobar| with both words in boldface, but I get the
> 	tag in italic---why?
 
Either the definition of `struct foobar' is in a C chunk that occurs earlier
in the web than the text containing `|struct foobar|, or Knuth has
snuck an `@s foobar int' into the web somewhere (`@s' is a silent `@f').
 
>   Knuth seems to get no line break between { and a declaration,
> 	but I do---why?
 
He probably puts an `@+'  (or a bizarre @t sequence) into the web
immediately after the {.
 
		-- Lee
		   leew@pilot.njin.net
 
From Norman Sun Dec 05 14:40:14 -0500 1993
Date: Sun, 05 Dec 1993 14:40:14 -0500
From: Norman Ramsey <norman@bellcore.com>
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, leew@pilot.njin.net
Subject: Re: CWEB thoughts
 
> > A couple questions, if anyone knows, vis-a-vis CTANGLE:
> > 
> >   Knuth gets |struct foobar| with both words in boldface, but I get the
> > 	tag in italic---why?
> 
> Either the definition of `struct foobar' is in a C chunk that occurs earlier
> in the web than the text containing `|struct foobar|, or Knuth has
> snuck an `@s foobar int' into the web somewhere (`@s' is a silent `@f').
>  
> >   Knuth seems to get no line break between { and a declaration,
> > 	but I do---why?
> 
> He probably puts an `@+'  (or a bizarre @t sequence) into the web
> immediately after the {.
 
And people wonder why I dislike prettyprinting :-) :-) :-) :-)
 
Norman
 
From bart@cs.tamu.edu Mon Dec 6 06:05:21 GMT 1993
Date: Mon, 6 Dec 1993 06:05:21 GMT
From: bart@cs.tamu.edu (Bart Childs)
Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU
To: LitProg@SHSU.EDU
Subject: CWEB thoughts and more
 
Phil Jensen posed some CWEB questions after reading some of
Knuth's Stanford GraphBase.  The answer to one question is that
Knuth inserted `@+' in many places to supress a line break.
 
The first question is probably that Knuth inserted a format statement
like
 
@f foobar struct
which says use the same typesetting formatting for foobar that is used
for struct.
 
Phil's guidelines were quite good and remind me of the Strunk and White
type rules.  Some of the same kinds are imbedded in the FWEB
documentation from John Krommes.
 
The sources of GraphBase are available for anonymous ftp from
labrea.stanford.edu   directory  /pub/sgb
 
Krommes FWEB 1.40 has been interesting to test.  It has a LaTeX
style and a verbatim language.  The latter gives formatting similar
to NoWEB and NuWEB in that the HLL code is not messed up.
 
HOWEVER, I don't like it.  The section numbers disappear and show up
as part of the section names
 
<Some section name 4.5>=
 
I am stating my strong preference for the section numbers appearing
at the beginning of the section.  If a variable is referenced in
the documentation part, you have to find a code part to be able
to find the bounds of the section.  This is particularly troublesome
if you have sections that are documentation only.
 
Still, I am grateful for the contributions of John, Norman Ramsey,
Preston Briggs, ...
 
Bart Childs
 
From greyham@research.canon.oz.au Mon Dec 6 06:05:21 GMT 1993
Date: Mon, 6 Dec 1993 06:05:21 GMT
From: greyham@research.canon.oz.au (Graham Stoney)
Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU
To: LitProg@SHSU.EDU
Subject: Announcing the c2man mailing list.
 
For anyone that is not familiar with it, c2man is an automatic documentation
tool that extracts comments from C source code to generate functional
interface documentation in the same format as sections 2 & 3 of the Unix
Programmer's Manual.  It requires minimal effort from the programmer by
looking for comments in the usual places near the objects they document,
rather than imposing a rigid function-comment syntax or requiring that the
programmer learn and use a typesetting language.  Acceptable documentation
can often be generated from existing code with no modifications.
 
There is now a mailing list specifically for c2man users.  Topics for
discussion could range from anything from where exactly Mullumbimby is, to why
looking at Web input files tends to evoke spontaneous convulsions in the
user[1].  This is the preferred place to ask questions about the program and
discuss modifications and additions with the author and other users.  Any
existing users or other interested people are encouraged to join by sending
mail with no Subject: line to <listserv@research.canon.oz.au> containing:
	SUBSCRIBE c2man Your name
Where `Your name' should be replaced with your real name.
 
C2man itself is available from:
how to get:	ftp usenet/comp.sources.reviewed/volume03/c2man* 
		from ftp.wustl.edu
    Europe:	ftp /pub/archive/comp.sources/reviewed/c2man* 
		from ftp.informatik.uni-stuttgart.de
    Patches:	ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se
 
Regards,
Graham
 
Footnote:
1. Actually, that's probably better kept for comp.programming.literate.
-- 
Graham Stoney, Hardware/Software Engineer
Canon Information Systems Research Australia
Ph: + 61 2 805 2909	Fax: + 61 2 805 2929
 
From Zdenek Mon Dec 06 10:44:14 MET 1993
Date: Mon, 06 Dec 93 10:44:14 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <LitProg@SHSU.edu>, norman@BELLCORE.COM
Subject: Re: CWEB thoughts
 
On Sun, 05 Dec 1993 14:40:14 -0500 Norman Ramsey said:
>> > A couple questions, if anyone knows, vis-a-vis CTANGLE:
>> >
>> >   Knuth gets |struct foobar| with both words in boldface, but I get the
>> >     tag in italic---why?
>>
>> Either the definition of `struct foobar' is in a C chunk that occurs earlier
>> in the web than the text containing `|struct foobar|, or Knuth has
>> snuck an `@s foobar int' into the web somewhere (`@s' is a silent `@f').
>>
>> >   Knuth seems to get no line break between { and a declaration,
>> >     but I do---why?
>>
>> He probably puts an `@+'  (or a bizarre @t sequence) into the web
>> immediately after the {.
>
>And people wonder why I dislike prettyprinting :-) :-) :-) :-)
>
>Norman
 
I still insist on prettyprinting. If I look at my program a year later, I know
that the boldface objects are either C++ keywords or my classes/structures.
Since |foo| is not a C++ keyword, it defined somewhere as class/structure.
Thus I can see more things at the first glance :-)
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete and will soon cease to exist!
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From George Mon Dec 06 12:46:27 CST 1993
Date: Mon, 06 Dec 1993 12:46:27 CST
From: "George D. Greenwade" <bed_gdg@SHSU.edu>
Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU
To: info-tex@SHSU.edu, pol-econ@SHSU.edu, ctan@SHSU.edu, TUGBD-L%IRLEARN.BITNET@HEARN.nic.SURFnet.nl, VMSGopher-L@trln.lib.unc.edu, tex-cd@SHSU.edu, litprog@SHSU.edu
Subject: Your patience, please........
 
My apologies for the wide broadcast of this note to a few lists where I
have a "presence" (i.e., I manage or co-manage them, have something to do
with their archives, etc.).
 
If you have sent me any e-mail within the past week or so and have not
heard back, or have attempted to unsubscribe from a list and are awaiting
manual removal for some reason, or have noticed that manual maintenance
aspects of our archives haven't taken place, or have sent me a personal
note and think I'm ignoring you, please bear with me.  I will make every
effort to get to your post as soon as possible.  I intend to get to the
unsubs first, any problems on the lists second, any problems with the
archives third, then personal items (based on subject lines, anyway). 
Given that I have to focus at least a modicum of attention to finals this
week and next, it may take me a brief time to get caught up with the 1,200
or so messages already awaiting me.  If you have a message for me which is
truly urgent, please include the word "urgent" in your subject line and I
will get to it as soon as I see it before plowing through all the rest.
 
Last week I managed to get myself hospitalized for an impacted lower
intestinal tract (so those of you who thought I was full of sh*t were
obviously right 8-)).  You don't even want to hear what was like nor what
done to me -- suffice it to say that it was less than pleasant in both
instances, and that recuperation hasn't been all that much joy either. 
However, I will get better and I will get caught up (not necessarily in
that order).
 
Regards and thanks in advance for your patience,   George
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
George D. Greenwade, Ph.D.                            Bitnet:  BED_GDG@SHSU
Department of Economics and Business Analysis         THEnet: SHSU::BED_GDG
College of Business Administration                    Voice: (409) 294-1266
P. O. Box 2118                                        FAX:   (409) 294-3612
Sam Houston State University              Internet:        bed_gdg@SHSU.edu
Huntsville, TX 77341                      bed_gdg%SHSU.decnet@relay.the.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
From c21vc@kocrsv01.delcoelect.com Tue Dec 7 21:44:00 GMT 1993
Date: Tue, 7 Dec 1993 21:44:00 GMT
From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar)
Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
To: LitProg@SHSU.EDU
Subject: command names
 
What is written here does not have anything directly to do with literate 
programming. However, people interested in literate programming may have 
good insight on the subject and hence I am posting here.
 
In one of our systems, we have a menu of commands. The system has been in use for
about a year. The name of one of the commands is misleading. In other words,
from its name, I anticipate it to do something somewhat different than 
what it actually does. There is on-line help and other documentation. 
 
A couple of us here are debating the pros and cons of changing the name. We
seem to get into this kind of debate periodically. For one of us, the
perturbation caused by changing the name is the bigger evil compared to 
leaving the somewhat imprecise name alone; his point is that users can (and 
after a while certainly will) learn to work with the imprecise name. These kind 
of changes add trivial value (they don't add functionality).
 
For theother, changing the name is well worth it; the point is, why should every
user fall into this little trap and learn only after necessarily making mistakes ?
Also, these kind of changes do add more than trivial value (even though they do
not add functionality). 
 
A related argument: are more descriptive command names better or briefer ones
better ? Even with several words in the command name, there is still some
imprecision - does it mean the thing to do is to give up the battle and go for a
brief one word tag for each command ? With briefer command names, (for most
systems), the entire menu can be fitted on to one screen. However, users have to 
'live with' brief command names, for the entire life of the system. 
 
Shaker
 
From koopman@sgi84.ctc.com Tue Dec 7 20:41:53 -0500 1993
Date: Tue, 7 Dec 93 20:41:53 -0500
From: koopman@sgi84.ctc.com (Michael G. Koopman)
Reply-To: LitProg@SHSU.edu, koopman@ctc.com
To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
Subject: command names
 
Shaker <c21vc@KOCRSV01.DELCOELECT.COM> wrote:
 
>What is written here does not have anything directly to do with literate 
>programming. However, people interested in literate programming may have 
>good insight on the subject and hence I am posting here.
 
I disagree, the labeling of menus is a part of the literate aspects of
a program, IMHO.  The label should be based on the logical principles
applied globally within a web and should therefore be changed.  I
expect that a forewarned user should readily accommodate such a
logical name change and, as you asserted, new users should learn the
menu system quicker and with greater comprehension.
 
>A related argument: are more descriptive command names better or briefer ones
>better ?
 
This has the making of a religious war of great proportions.  I see it
as akin to questioning the utility of scrap psuedonyms within a web.
A program which provides both curt and verbose menu descriptions, at
the user's discretion, may be the best choice.
 
Michael Koopman (mike)                e-mail:  koopman@ctc.com
Concurrent Technologies Corporation    phone: +1-814-269-2637
1450 Scalp Avenue                    telefax: +1-814-269-2666
Johnstown, PA  15904-3321  USA          ICBM:  40-15'N-78-50'W
-------------------------------------------------------------
That's all from `Dear Gabby' for this week.
 
From thompson@sun1.coe.ttu.edu Wed Dec 8 09:52:46 CST 1993
Date: Wed, 8 Dec 93 09:52:46 CST
From: thompson@sun1.coe.ttu.edu (Dave Thompson (3/1/93))
Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU
To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM
Subject: Re:  command names
 
> A related argument: are more descriptive command names better or briefer ones
> better ? Even with several words in the command name, there is still some
> imprecision - does it mean the thing to do is to give up the battle and go 
> for a brief one word tag for each command ? With briefer command names, 
> (for most systems), the entire menu can be fitted on to one screen. 
 
I'm not an expert in human interface design, but have an opinion (and like 
most noses, it probably smells ;-).  The interface should be designed with 
more than one user type in mind.  You need sufficient detail (even if it
requires more steps) to guide new users through the software.  This might be
your multiple screens, or long command names, or what-have-you.  You need
a second set of commands, probably greatly abbreviated, for your expert users,
those who have significant experience with the system (sometimes these are
called power users).  Even if you use the same displays as for your neophyte
users, you should provide "short-cuts" or speed keys.  You might allow the
user to toggle the menu screens off and work simply with the keyboard (with
some help available for infrequently used commands).  A third level of user 
interface might be included in between the first two, for experienced users 
but not power users.
 
As an example, my text editor is the SemWare Editor.  It is a plain text
editor that is the descendent of QEdit for PC boxes.  It has two user
interfaces installed.  One is a pull-down menu system (user-configurable)
that seems to be the ui of choice these days.  It even works with a mouse
and is very easy to use.  New users (and infrequent editors) can work with
the program without learning a lot of keyboard commands.  The second user
interface is keyboard command driven.  It is also user-configurable and I
have reprogrammed my keyboard to emulate (mostly) Wordstar.  (Now, stop
laughing!)  Like most of the people who hang around here, I'm a touch typist
and hate taking my fingers from the keyboard (hence mice are anathema to
me).  This user interface works very well for me, and I'm probably a power
user of this program.
 
The point is, both user interfaces are necessary to meet the needs of the
target audience.  Yes, users will learn to use whatever command set you
provide.  But, the best way is to meet the needs of the user, make things
intuitive if possible, and provide multiple ways to achieve the same goal.
 
-=d
 
David B. Thompson               internet: thompson@sun1.coe.ttu.edu 
Civil Engineering Dept.         internet: dthompson@coe2.coe.ttu.edu
Texas Tech University           internet: wqdbt@ttacs1.ttu.edu 
P.O. Box 41023
Lubbock, Texas 79409-1023       "Get a haircut and get a *real* job."
 
From krommes@theory.pppl.gov Wed Dec 8 09:52:46 CST 1993
Date: Wed, 8 Dec 93 09:52:46 CST
From: krommes@theory.pppl.gov (John Krommes)
Reply-To: LitProg@SHSU.edu, Krommes@Princeton.EDU
To: LitProg@SHSU.EDU
Subject: Re: CWEB thoughts and more
 
Bart Childs writes with regard to FWEB 1.40:
 
> Krommes' FWEB 1.40 has been interesting to test.  It has a LaTeX
> style and a verbatim language.  The latter gives formatting similar
> to NoWEB and NuWEB in that the HLL code is not messed up.
 
> HOWEVER, I don't like it.  The section numbers disappear and show up
> as part of the section names
 
> <Some section name 4.5>=
 
> I am stating my strong preference for the section numbers appearing
> at the beginning of the section.  If a variable is referenced in
> the documentation part, you have to find a code part to be able
> to find the bounds of the section.  This is particularly troublesome
> if you have sections that are documentation only.
 
  That section numbers do not appear at the beginning of the section in FWEB
1.40 is only a default.  It is very simple to make them reappear:  just put
 
	\numberTeXtrue
 
in the limbo section.  For most programming purposes, I agree with Bart; I
like the section numbering to be explicit, for precisely the reason he
mentions about sections that are documentation only.  However, perusing my
request queue, for every user who agrees with Bart, there's one who
passionately wants the documentation to look more ``book-like.''  FWEB 1.40
(which is still highly experimental) attempts to let the user choose.
 
  FWEB 1.40 was announced to the FWEB mailing list but not here because I
don't want people, and especially large programming projects, dependent on
a stable FWEB to convert just yet.  However, I do need patient volunteers
to experiment.  It's available via anonymous ftp from
 
	ftp.pppl.gov:/pub/fweb
 
--
--- John                      (Mail to krommes@princeton.edu is forwarded to
                              krommes@lyman.pppl.gov == 198.35.4.70.  
krommes@princeton.edu         Ftp files to/from ftp.pppl.gov, NOT princeton.edu
   (609) 243--2606            or lyman.pppl.gov.)
 
From Eric Fri Dec 10 14:25:50 TZ 1993
Date: Fri, 10 Dec 93 14:25:50 TZ
From: Eric Landes <ericla@microsoft.com>
Reply-To: LitProg@SHSU.edu, ericla@MICROSOFT.COM
To: litprog@shsu.edu
Subject: Compiling FWEB 1.40 on Windows NT
 
It's amazingly easy.  I did this with Visual C++ 1.0 for NT on an NTFS
partition.  I also used the 'touch' utility from the Toolbuster CD-ROM.
 
Pretend you are building an ANSI Unix version.  Copy defaults.mk and
custom.h from \fweb1.40\boot\unix\ansi into \fweb1.40\web.
 
Make the following changes:
 
defaults.mk
 
1  Change the CC and COMPILER macros from 'gcc' to 'cl'.
2. Change the CFLAGS macro to the options you desire (I used -O2).
3. Change the O macro from 'o' to 'obj'.
4. Change the LDFLAGS and LIBS macros to the options you desire (I 
didn't use any).
5. Remove the '-o' from the LINK macro.
6. Change the MAKE macro from 'make' to 'nmake'.
7. Change the HWEB macro from 'hweb' to 'hwe'. (optional.  Use if you 
aren't always
   going to be using NTFS partitions.)
 
makefile
1. Change all '/' to '\'.
2. Uncomment the 'include' directive on line 62 to reflect the 
Microsoft/Borland
   format.  Comment out the directive on the line above.
3. For the 'touch' command on line 131, change the last two '\' 
characters back to
   '/'. (this is for the version of touch I used.  Your mileage may vary.)
 
custom.h
1. Change the definition of NULL_FILE_NAME from '/dev/null' to 'NUL'
2. Change the C++ extension on line 89 from 'C++' to 'cpp'.
3. Uncomment the inclusion of malloc.h on line 149.
4. Change the definition of FEWB_INI from '.fweb' to 'fweb.ini'. 
(optional. I did
   this for compatibility with the DOS version.)
 
(warning: hack)
ftangle.c
1. Around line 3225, MV is defined.  Change this definition to refect 
what you would
   get if ibmpc was defined.  You don't want to define ibmpc for the NT 
version.
 
After you make these changes, simply type 'nmake bootstrap' and after a 
couple minutes,
you will have FTANGLE.EXE and FWEAVE.EXE.
 
I've got diffs available for these changes if people would like them.
 
If you have any questions/problems, please let me know.  I'll be doing 
this soon for
FWEB 1.30a.
 
Eric Landes
ericla@microsoft.com
 
From thompson@sun1.coe.ttu.edu Fri Dec 10 14:25:50 TZ 1993
Date: Fri, 10 Dec 93 14:25:50 TZ
From: thompson@sun1.coe.ttu.edu
Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu
To: LitProg@SHSU.EDU
Subject: comp.programming.literate FAQ
 
Archive-name: literate-programming-faq
Last-modified: 1993/11/11
Version: 1.0.4
 
Welcome to the Literate Programming Frequently Asked Questions List
-------------------------------------------------------------------
 
This version was created Thursday - November 11, 1993 and should
considered stale after 90 days.  Information contained in this document
is the best available at preparation.
 
Disclaimer: "This FAQ is presented with no warranties or guarantees of
ANY KIND including correctness or fitness for any particular purpose.
The author of this document has attempted to verify correctness of the
data contained herein; however, slip-ups can and do happen.  If you use
this data, you do so at your own risk."
 
Copyright 1993 David B. Thompson.  All rights reserved worldwide.
Permission is granted to copy this document for free distribution so
long as it remains intact and unmodified.
 
* Introduction:
---------------
 
This document is for new and experienced users of literate programming
tools.  The purpose is to explain the concept of literate programming and
to provide a resource for locating files of interest to literate
programmers and those interested in literate programming.
 
The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list
is maintained by Dave Thompson, who can be reached at:
 
    thompson@sun1.coe.ttu.edu     * Preferred mailing address for FAQ
                                    related comments/questions.
    wqdbt@ttacs1.ttu.edu          * Forwarded to my pc.
 
Comment and constructive criticism is welcome.  Direct flames to
/dev/null (or > nul if you're a msdos user! ;-)  If you find an error,
please report it.  I'm particularly interested in establishing the
locations of generally available literate programming tools.  If you are
the author of such a tool and wish to have it included in this list,
please send email.
 
Please note this is a work-in-progress.  It is *not* complete, and
probably will not be complete for some months.  Nevertheless, the
information contained herein may be useful to some.  Use it as it is
intended.
 
- ----------------------------------------------------------------------
 
- Typography:
-------------
 
Major sections of the FAQ are divided by double lines (====).  Minor
sections and other divisions are separated by single lines (----).
Major topics use a "* " as a leader.  Minor topics use a "- " as a
leader.  This should simplify searching for topics.
 
Table of Contents:
------------------
 
* Introduction
    - Typography.
* How to get the FAQ.
    - Literate Programming FAQ.
    - FWEB FAQ.
* The LitProg newsgroup.
* Internet nodes of interest to literate programmers.
* What is literate programming?
* How do I begin literate programming?
* What tools are available and where are they?
    - c2latex
    - CLip
    - CWEB
    - FunnelWeb
    - FWEB
    - noweb
    - NUWEB
    - SchemeWEB
    - Spidery WEB
    - WinWordWEB
* What other resources are available?
    - Virtual Coursework
* Code examples.
    - Examples included with developer's tools
    - Cameron Smith's KR-CWEB
    - Bart Child's examples for FWEB
* Bibliographies.
* How to anonymously ftp.
* Acknowledgements.
* End notes.
 
* How to get the FAQ:
---------------------
 
- Literate Programming FAQ.
---------------------------
 
You have many ways to get a current copy of this FAQ.  One is to use
anonymous ftp (if you don't know how, see a later section in this FAQ)
to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites
or the Literate Programming Archive and retrieve a copy of the file.
(For more information on CTAN and the literate programming archive, see
the section below entitled "Internet Nodes of Interest to Literate
Programmers.")
 
An alternative is to use the fileserver at SHSU.  Send a message to
FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message
 
    SENDME FAQ.LITPROG
 
The file server will forward a copy of the file to you via email.
 
- ----------------------------------------------------------------------
 
- FWEB FAQ:
-----------
 
Marcus Speh <marcus@x4u.desy.de> maintains the FWEB FAQ.  The current
version number is 1.29.  It can be retrieved in the same way as this
FAQ; either by anonymous ftp or through the SHSU file server.  On the
SHSU server, the file name is FAQ.FWEB.  Invoke your ftp software, open
a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory
FAQ, and transfer the file FAQ.FWEB.
 
Alternatively, send a message to the file server, FILESERV@SHSU.EDU
(FILESERV@SHSU.BITNET), and include the following text in a one line
message:
 
    SENDME FAQ.FWEB
 
The file server will send the current version of the file via email.
 
The FWEB FAQ exists in various formats, including HyperText (see other
resources below). In Europe, the complete distribution can also be
obtained from ftp.desy.de [131.169.10.115] in directory
/pub/faq/web/fweb/.  It is also available from the literate programming
archive (LPA) in the directory LPA/documentation/faq/fweb (see the
references to LPA below for more information).
 
* The LitProg Newsgroup:
------------------------
 
One of the most important resources is the literate programming
newsgroup, comp.programming.literate.  You can read this newsgroup using
your standard reader.  Altenatively, the newsgroup is gated to a mailing
list hosted by George Greenwade and Sam Houston State University.  You
can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or
LISTSERV@SHSU.BITNET), and include in the message one line of text:
 
    SUBSCRIBE LITPROG  "your name in quotes"
 
The list is unmoderated; messages sent to litprog@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.programming.literate.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory litprog.
 
* Internet Nodes of Interest to Literate Programmers:
-----------------------------------------------------
 
The principal nodes of interest to literate programmers are the Literate
Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX
Archive Network).
 
The Literate Programming Archive (LPA) is:
 
  Node:       ftp.th-darmstadt.de [130.83.55.75]
  Directory:  pub/programming/literate-programming
  Notes:      Fastest response during off-U.S. [yep] business hours.
 
The CTAN sites are:
 
ftp host             IP            CTAN root    Institution and Sponsor
-------------------------------------------------------------------------
ftp.TeX.ac.UK        134.151.79.32 pub/archive  Aston Univ./UK TeX U.G.
ftp.Uni-Stuttgart.DE 129.69.8.13   soft/tex     Univ. Stuttgart/DANTE e.V
ftp.SHSU.edu         192.92.115.10 tex-archive  Sam Houston State Univ.
 
Other nodes and directories of interest include:
 
  Node:       niord.shsu.edu [192.92.115.8]
  Directory:  various (do some snooping!)
  Notes:      Has a gopher server.
 
  Node:       ftp.desy.de [131.169.10.115]
  Directory:  pub/web. Various documents, samples, and the FWEB FAQ.
  Notes:      Has a www server, http://info.desy.de:80/
 
* What is Literate Programming?
-------------------------------
 
Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings.  In fact,
literate programs should be enjoyable reading, even inviting!  (Sorry
Bob, I couldn't resist!)  In general, literate programs combine source
and documentation in a single file.  Literate programming tools then
parse the file to produce either readable documentation or compilable
source.  The WEB style of literate programming was created by D.E. Knuth
during the development of his TeX typsetting software.
 
All the original work revolves around a particular literate programming
tool called WEB.  Knuth says:
 
     The philosophy behind WEB is that an experienced system
     programmer, who wants to provide the best possible
     documentation of his or her software products, needs two
     things simultaneously: a language like TeX for formatting,
     and a language like C for programming.  Neither type of
     language can provide the best documentation by itself; but
     when both are appropriately combined, we obtain a system
     that is much more useful than either language separately.
 
     The structure of a software program may be thought of as a
     web that is made up of many interconnected pieces.  To
     document such a program we want to explain each individual
     part of the web and how it relates to its neighbours. The
     typographic tools provided by TeX give us an opportunity to
     explain the local structure of each part by making that
     structure visible, and the programming tools provided by
     languages such as C or Fortran make it possible for us to
     specify the algorithms formally and unambigously. By
     combining the two, we can develop a style of programming
     that maximizes our ability to perceive the structure of a
     complex piece of software, and at the same time the
     documented programs can be mechanically translated into a
     working software system that matches the documentation.
 
* How to begin literate programming:
------------------------------------
 
A recommended book is D.E. Knuth's collection of articles (1992)
"Literate Programming," Center for the Study of Language and
Information, Stanford University, ISBN 0-937073-80-6 (pbk).  This book
gives insight into Knuth's thoughts as he developed the web system of
literate programming (and TeX for typesetting).  It does not document
methods for literate programming.
 
A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate
Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk).
This book focuses on using Knuth's web system.
 
Some talk exists in the newsgroup/mailing list for a Usenet University
course in literate programming.  I'm sure discussion of this topic will
be welcomed.  If you are interested, please participate.
 
* What Tools are Available:
---------------------------
 
A significant number of tools for literate programming are available.
Most have been ported from their original systems, so support multiple
computer platforms.  If you are the developer of such a tool, and would
like to make the software freely available, please send me email and
I'll reply with a form (like those below) for you to fill in.  (Or
short-circuit the process and kludge a form from below. :-)
 
- C2LaTeX:
----------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix
 
Software supported:
            Programming language: C.
            Text formatter: LaTeX but it's easy to change the formatter.
 
Availability:
            Anonymous ftp from
                omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex.
 
Readme:
            Absent.  Documentation is in the C source for c2latex.
 
Brief description:
            C2latex provides simple support for literate programming
            in C.  Given a C source file in which the comments have
            been written in LaTeX, c2latex converts the C source file
            into a LaTeX source file.  It can be used to produce
            typeset listings of C programs and/or documentation
            associated with the program.
 
            C2latex produces LaTeX source by implementing a small
            number of rules.  A C comment that starts at the beginning
            of a line is copied unmodified into the LaTeX source
            file.  Otherwise, non-blank lines are surrounded by a pair
            of formatting commands (\begin{flushleft} and
            \end{flushleft}), and the lines are separated by \\*.
            Each non-blank line is formatted using LaTeX's \verb
            command, except comments within the line are formatted in
            an \mbox.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
- ----------------------------------------------------------------------
 
- CLip:
-------
 
Developer:
            E.W. van Ammers and M.R. Kramer
 
Systems supported:
            Vax/VMS and MS-DOS.
 
Software supported:
            An programming language.  Plain TeX and LaTeX text
            formatters.
 
Availability:
            Anonymous ftp from:
              CTAN/web/clip
              LPA/machines/ms-dos
              LPA/machines/vax
              sun01.info.wau.nl/CLIP
 
Readme:
            In distribution.
 
Brief description:
 
Support:
            Unknown.
 
- ----------------------------------------------------------------------
 
- CWEB:
-------
 
Developer:
            Silvio Levy and D.E. Knuth
 
System(s) supported:
            Unix systems (dos and amiga ports available)
 
Software supported:
            Languages supported are C and C++.  Text formatters are
            plain TeX and LaTeX.
 
Availability:
            anonymous ftp from:
              labrea.stanford.edu/pub/cweb
              LPA/c.c++
              CTAN/web/c_cpp/cweb
              DOS version in CTAN/web/c_cpp/cwb30p8c
              DOS version in LPA/machines/ms-dos
              Amiga version to be posted soon (look at CTAN).
              Mac port of CTANGLE in LPA/machines/mac
              LaTeX support in LPA/c.c++
 
Readme:
            bundled with above
 
Brief description:
 
Support:
            bugs to levy@math.berkeley.edu
 
- ----------------------------------------------------------------------
 
- FunnelWeb:
------------
 
Developer:
            Ross N. Williams: ross@guest.adelaide.edu.au
 
Systems supported:
            MSDOS, Mac, VMS, Sun.  Other ports reported.
 
Software supported:
            For printing, TeX.  Otherwise no restrictions.
 
Availability:
            anonymous ftp from:
              CTAN/web/funnelweb
              LPA/independent
              ftp.adelaide.edu.au/pub/funnelweb
 
Readme:
            With bundle above.
 
Brief description:
            FunnelWeb is a production-quality literate-programming tool
            that emphasises simplicity and reliability. Everything about
            FunnelWeb, from the simplicity of its language to the
            comprehensive tutorial in the user's manual, has been
            designed to make this as simple, as practical, and as usable
            a tool as possible.
 
            Features:
               + Provides a simple macro preprocessor facility.
               + Can produce typeset documentation.
               + Runs on Sun, VMS VAX, Macintosh, PC, and others.
               + Portable C source code distributed under GNU licence.
               + Comprehensive user's manual including tutorial.
               + Programming-language independent.
               + Can generate multiple output files.
               + Allows complete control over the output text.
               + Regression test suite with over 200 tests.
               + Fully worked example (in /pub/funnelweb/examples).
               - Requires TeX to produce typeset documentation.
               - Typesets program code using TT font only.
 
Support:
            No formal support available.  Mailing list maintained with
            about 50 subscribers.  Informal assistance available from
            mailing list.
 
- ----------------------------------------------------------------------
 
- FWEB:
-------
 
Developer:
            John A. Krommes
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX.
            Text formatters are plain TeX and LaTeX.
 
Availability:
            anonymous ftp from:
              lyman.pppl.gov/pub/fweb
              CTAN/web/fweb
              LPA/fweb
              DOS version in LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            It also has a well-developed user's manual and its own FAQ
            (see above). It runs on most platforms: VMS, PC, UNIX, and
            pretty much anything that the GNU C compiler (GCC) is
            supported for.
 
Support:
            bug reports to krommes@princeton.edu
 
- ----------------------------------------------------------------------
 
- noweb:
--------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            All programming languages, plain TeX and LaTeX formatters.
 
Availability:
            anonymous ftp from:
              csservices.princeton.edu/pub/noweb.shar.Z
              bellcore.com/pub/norman/noweb.shar.Z
              CTAN/web/independent/noweb
              LPA/independent
 
Readme:
            with bundle above
 
Brief description:
 
            noweb is designed to meet the needs of literate programmers
            while remaining as simple as possible.  Its primary
            advantages are simplicity, extensibility, and
            language-independence.  noweb uses 5 control sequences to
            WEB's 27.  noweb now supports indexing and identifier
            cross-reference.  The simple noweb manual is only 2 pages;
            documenting the full power of noweave and notangle requires
            another 3 pages.  noweb works ``out of the box'' with any
            programming language, and its formatter-dependent part is a
            60-line nawk program. The primary sacrifice relative to WEB
            is the loss of prettyprinting.
 
Support:
            by email to the author
 
- ----------------------------------------------------------------------
 
- NUWEB:
--------
 
Developer:
            Preston Briggs: preston@cs.rice.edu
 
Systems supported:
            Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS.
 
Software supported:
            It's written in C.  It works with any programming language
            (or combination of programming languages) and uses Latex as
            its text formatter.
 
Availability:
            anonymous ftp from:
              Unix: CTAN/web/nuweb
              DOS:  CTAN/web/nuweb-pc
              LPA/independent
 
Readme:
            Send mail to preston@cs.rice.edu
 
Brief description:
 
            A single program that takes a web file written in a
            combination of latex and any programming language(s) and
            produces a latex file that can be pretty printed and a set
            of files containing code for compilation/interpretation by
            the appropriate language processors.
 
            Strengths include speed, simplicity, multiple languages,
            nice indices and cross-references, latex.  Doesn't require
            any special macros or macro files.
 
            Drawbacks: latex-dependent, no code pretty printing, harder
            to make indices than cweb.
 
            More good stuff: nice support for make, doesn't reformat
            source files, so they're easy to debug.  Lots of control
            without too much effort.  That is, it doesn't do too much!
 
            Future directions... Very little change planned, except
            perhaps refinements in the indexing software.
 
Support:
            Hack it yourself or send e-mail to preston@cs.rice.edu
 
- ----------------------------------------------------------------------
 
- SchemeWEB:
------------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Programming language: Any dialect of Lisp.
            Text formatter: LaTeX.
 
Availability:
            The Unix version is in the Scheme Repository and it is
            available via anonymous ftp from:
              nexus.yorku.ca/pub/scheme/utl
              LPA/lisp
 
            The DOS version is part of the PCS/Geneva Scheme system
            which is available via anonymous ftp from:
              cui.unige.ch/pub/pcs.
              LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            SchemeWEB is a Unix or DOS filter that translates
            SchemeWEB source into LaTeX source or Lisp source.
            Lisp code is formatted in typewriter type font and
            the comments are passed to LaTeX unchanged.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
- ----------------------------------------------------------------------
 
- Spidery WEB:
-------------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Most Algol-like languages, including C, Ada, Pascal, Awk,
            and many others.  Plain TeX and latex for text formatters.
 
Availability:
            Anonymous ftp from:
                CTAN
 
Readme:
            In distribution.
 
Brief description:
            A system for building language-dependent WEBs. Spider is
            frozen; no further development is planned.
 
Support:
            Bug reports to author.
 
- ----------------------------------------------------------------------
 
- WinWordWEB:
-------------
 
Developer:
            Lee Wittenberg <leew@pilot.njin.net>
 
Systems supported:
            Needs Microsoft Word for Windows, v.2.x, and, of course,
            MS-Windows 3.x.
 
Software supported:
            Any programming language.  Word for Windows 2.x for text
            formatting and file maintenance.
 
Availability:
            anonymous ftp from:
              bart.kean.edu:pub/leew
            World-Wide Web (WWW)
 
Readme:
            WORDWEB.DOC in the downloadable package describes the
            system.
 
Brief description:
            WinWordWEB is a set of a Word for Windows macros (plus a
            paragraph style) that provide a crude literate programming
            environment.  The ``look and feel'' of the system is based
            on Norman Ramsey's noweb, but can easily be modified to suit
            individual tastes.
 
Support:
            None.  WinWordWEB was written as a prototype to see if a
            WYSIWYG literate programming system was possible.  It is
            intended as a jumping off point for future work by others.
            However, the system is surprisingly usable as it stands, and
            the author is interested in hearing from users (satisfied
            and unsatisfied).
 
            Anyone interested in actively supporting (and improving) the
            product should contact the author via email.
 
* Other resources:
------------------
 
An untapped resource (by me anyway ;-) is the World Wide Web.  Marcus
Speh has expended considerable effort in this regard.  If you're
connected to WWW, then access:
 
  http://info.desy.de/user/projects/LitProg.html
 
If you aren't connected to WWW, telnet to info.cern.ch and explore.
You can reach Marcus' literate programming pages by typing:
 
  go http://info.desy.de/user/projects/LitProg.html
 
Help for people who have only Email and neither WWW nor telnet, can be
obtained by Email from LISTSERV@INFO.CERN.CH by sending a message
containing the command HELP.  Instructions will be returned by email.
For literate programming documents, you can try anonymous ftp to
ftp.desy.de [131.169.10.115] and attach to directory:
 
  /pub/userWWW/projects/Announce
 
Another resource of interest to literate programmers is the info-tex
mailing list.  If you're using (La)TeX as your typsetting system and
have access to internet, then you should investigate this mailing list.
Mail list service is available through the SHSU list-server.  To
subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET),
and include in the message one line of text:
 
    SUBSCRIBE INFO-TEX "your name in quotes"
 
The list is unmoderated; messages sent to info-tex@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.text.tex.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory info-tex.
 
- ----------------------------------------------------------------------
 
- Virtual Coursework:
---------------------
 
Marcus Speh plans an introductory course on Literate Programming on the
Internet, part of the first semester of "Global Network Academy" [GNA],
a non-profit corporation incorporated in the state of Texas, affilated
with the Usenet University project. The texts/sample programs for this
class will be made available via anonymous FTP. A special room on GNA
Virtual Campus will be staffed by a consultant in one to two hour
shifts.  Students with questions can telnet to the virtual campus and
ask questions of the staff there. Tuition: Students should agree to work
for Global Network Academy in some capacity. This may include agreeing
to serve as a consultant next term, donating computing resources which
belong to them, helping with programming, etc. If you are interested in
registering for the course either as a student or as a consultant,
please contact marcus@x4u.desy.de. You will receive a standard reply
message; no further action will be taken until January 94.
 
[Editor's note: Because of workload, Marcus requests that email
inquiries be limited to a statement of interest for either a student or
consultant position until January 1994.]
 
* Code Examples:
----------------
 
Examples of web programs are included with the FWEB, CWEB, and noweb
distributions.
 
Cameron Smith converted the K&R calculator program into a literate
program.   It can be retrieved by anonymous ftp from:
  niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as
    krcwsamp.zip
  or from
    LPA/Documentation
 
Ross Williams has released a funnelweb example.  You can retrieve this
file from node ftp.adelaide.edu.au [129.127.40.3] as
  /pub/funnelweb/examples/except.*
This file should be on CTAN as well.
 
* Bibliographies:
-----------------
 
Nelson Beebe has collected an extensive bibliography treating literate
programming.  His work is available for anonymous ftp from
ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files:
    litprog.bib
    litprog.ltx.
Although I have not verified this, LPA is an alternate source for these
files.  Note that they are updated frequently (Nelson says several times
each week), so be sure to get a fresh copy before extensive use.
Joachim Schrod indicates that these files may be updated daily and can
be retrieved via anonymous ftp at LPA/documentation.
 
* How to anonymously ftp:
-------------------------
 
Pretty much everything mentioned here is available by anonymous FTP.
FAQ lists cross-posted to news.answers and rec.answers can be gotten
from rtfm.mit.edu [18.70.0.209], under /pub/usenet/news.answers or under
/pub/usenet/more.specific.group.name
 
"anonymous FTP" is just a way for files to be stored where anyone
can retrieve them over the Net.    For example, to retrieve the
latest version of the literate programming FAQ, do the following:
 
> ftp rtfm.mit.edu              /* connect to the site; message follows */
> anonymous                     /* type this when it asks for your name */
> <your email address>          /* type your address as the password    */
> cd /pub/usenet                /* go to the directory you want to be   */
> cd comp.programming.literate  /* one level down (no slash).           */
> dir                           /* look at what's there                 */
> get literate-progamming-faq   /* get the file; case-sensitive         */
> quit                          /* stop this mysterious thing           */
 
If your FTP program complains that it doesn't know where the site you
want to use is, type the numerical address instead of the sitename:
 
> ftp 18.70.0.209               /* connect with numerical address */
 
If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu
with the single word "help" in the body of the message.
 
Getting binary files (executables, or any compressed files) is only
slightly more difficult.   You need to set binary mode inside FTP before
you transfer the file.
 
> binary            /* set binary transfer mode  */
> ascii             /* set back to text transfer mode */
 
FAQs and spoiler lists are generally ascii files; everything else is
generally binary files.
 
Some common extensions on binary files in archive sites are:
 
  .Z           Compressed; extract with uncompress
  .tar.Z       Compressed 'tape archive'; uncompress then untar or tar -xvf
  .gz or .z    Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu)
  .sit         (Mac) StufIt archive
  .zip         Extract with Zip or Unzip
  .zoo         Yet another archive/compress program
  .lhe         (Amiga) ?
  .lzh         Lha archive program.
  .arj         (PC) Arj archive program.
  .exe         (PC) Sometimes self-extracting archives-just execute them.
  .uue or .UUE Transfer as text file; use uudecode to convert to binary
  .hqx         (Mac) BinHex format; transfer in text mode
 
Generic help can be found in the FAQs of comp.binaries.<your_system_type>
for how to transfer, extract, and virus-check binary files.  (At
rtfm.mit.edu)
 
If you can't FTP from your site, use one of the following ftp-by-mail
servers:
 
  ftpmail@decwrl.dec.com
  ftpmail@src.doc.ic.ac.uk
  ftpmail@cs.uow.edu.au
  ftpmail@grasp.insa-lyon.fr
 
For complete instructions, send a message reading "help" to the server.
 
If you don't know exactly what you're looking for, or exactly where it
is, there are programs and servers that can help you.  For more info,
send e-mail to mail-server@rtfm.mit.with with the body of the
message reading send usenet/news.answers/finding-sources
 
Thanks to Aliza R. Panitz (the "buglady") for this text.  I copied it
verbatim from her post on faq-maintainers with only minor modifications.
 
* Acknowledgements:
-------------------
 
This document would not have happened without the help of many people.
Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim
Schrod, Piet van Oostrum, and Ross N. Williams.  A special thanks to
Aliza R. Panitz for the text describing how to execute an anonymous ftp
for files of interest.
 
Any omissions from these acknowledgements should be considered an act of
stupidity on my part.  Of course, the authors of literate programming
tools mentioned above all play a vital role in the vitality of literate
programming. Furthermore, participants in the comp.programming.literate
newsgroup (and associated mailing list) all contributed in various
fashions. Thank all of you.
 
* End notes:
------------
 
This document will be evolving over the next few months.  I'm planning
on adding entries for additional literate programming tools and will
expand the sections on examples as more examples become available. Tools
I will include are web (the original pascal version), funnelweb,
spiderweb, and cnoweb for starters. Others will be added as I find and
document them.  Omission of a particular tool should not be considered a
snub in any sense--simply an error or oversight on my part.
 
History:
 
  First release: Fri 10/15/1993 -- Yep, I finally did it!
  Thu 10/21/93 -- Minor change to ftp instructions.
  Fri 10/22/93 -- Minor change to stuttgart ip and fweb.faq version.
                  Made reader-recommended changes, lots of re-
                  organization, and added a few tools.
  Mon 11/01/93 -- Corrected typo in address.
  Thu 11/11/93 -- Minor change to www.
 
From dpapp@amisk.cs.ualberta.ca Sun Dec 12 03:10:41 GMT 1993
Date: Sun, 12 Dec 1993 03:10:41 GMT
From: dpapp@amisk.cs.ualberta.ca (Denis R. Papp)
Reply-To: LitProg@SHSU.edu, dpapp@amisk.cs.ualberta.ca
To: LitProg@SHSU.EDU
Subject: Watcom C++
 
Does anyone know if you can do anything if DOS4GW 1.9+ dont work
on your system?
 
Either it returns me to the prompt or hangs, or gives some weird
interrupt error (usually Interrupt 0D something like that)
I have been informed that it is probably incompatibility with
my motherboard...
 
There must be something that can be done
 
Please email me, as I would otherwise miss your reply
 
Thanks
 
-- 
 
Denis Papp					   dpapp@cs.ualberta.ca
						   dpapp@amisk.cs.ualberta.ca
"Oh."				-- Albert Einstein
 
From ses@tipper.oit.unc.edu Sun Dec 12 03:10:41 GMT 1993
Date: Sun, 12 Dec 1993 03:10:41 GMT
From: ses@tipper.oit.unc.edu (Simon E Spero)
Reply-To: LitProg@SHSU.edu, ses@TIPPER.OIT.UNC.EDU
To: LitProg@SHSU.EDU
Subject: emacs hack for cweb users
 
Here's a little hack to do completion on cweb module names in emacs lisp.
I find working with abbreviated module names much more confusing than when
the names are given in full. This hack keeps the amount of typing the same
Simon
 
-- 
Hackers Local 42- National Union of Computer Operatives, Chapel Hill section
------------------------------------------------------------------------------
Tar Heel Information Services - Nothing but net!   | WAIS/Z39.50 spoken here
North Carolina - First in Usenet	| DoD #612 | Tel: +1-919-962-9107
 
From cfwas@ux1.cts.eiu.edu Tue Dec 14 21:53:02 GMT 1993
Date: Tue, 14 Dec 1993 21:53:02 GMT
From: cfwas@ux1.cts.eiu.edu (William Slough)
Reply-To: LitProg@SHSU.edu, cfwas@UX1.CTS.EIU.EDU
To: LitProg@SHSU.EDU
Subject: Stanford GraphBase on PC's?
 
Is there anyone in this group who has had direct experience with 
the Stanford GraphBase on a PC with MS-DOS?  I have Knuth's book
which describes these programs; there is a clear slant toward
Unix systems.
 
I am potentially interested in dabbling with these programs, but
would prefer not to "reinvent the wheel" regarding makefiles, compiler
switches, etc.
 
I have noticed that there is a CWEB tailored to the PC environment;
how about the Stanford GraphBase? 
 
Any comments are most welcome.  Thanks.
 
+----------------------------------------------------------+
|  William Slough                  e-mail:  cfwas@eiu.edu  |    
|  Department of Mathematics       phone : (217)-581-6275  |
|  Eastern Illinois University     office:   Old Main 320  |
|  Charleston, IL  61920                                   |
+----------------------------------------------------------+
 
From perlman@cis.ohio-state.edu Tue Dec 14 21:53:02 GMT 1993
Date: Tue, 14 Dec 1993 21:53:02 GMT
From: perlman@cis.ohio-state.edu (Gary Perlman)
Reply-To: LitProg@SHSU.edu, perlman@CIS.OHIO-STATE.EDU
To: LitProg@SHSU.EDU
Subject: Re: command names
 
In article <1993Dec7.214400.14556@kocrsv01.delcoelect.com> c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) writes:
>In one of our systems, we have a menu of commands. The system has been in use for
>about a year. The name of one of the commands is misleading. In other words,
>from its name, I anticipate it to do something somewhat different than 
>what it actually does. There is on-line help and other documentation. 
>
>A couple of us here are debating the pros and cons of changing the name. 
 
It's a tradeoff.  See the discussion of Experiment 3 in:
 
%A Gary Perlman
%D 1984
%T Natural Artificial Languages: Low Level Processes
%P 373-419
%O Reviewed in Computing Reviews, 1984, 529
%X An artificial language is one created for concise and precise
communication within a limited domain such as mathematics.  A
natural artificial language is one that people find easy to learn
and use.  I discuss low level properties of natural artificial
languages, especially those in which names are chosen for concepts,
and symbols are chosen for names, a class of artificial languages
I call linguistically mediated artificial languages.  These
properties include choosing mnemonic symbols for names, and
suggestive names for concepts, and using both internally and
externally consistent syntax.  I outline a model of processing
linguistically mediated artificial language and present results
from experiments in support of the model.  The results of the
experiments are applied to the design of a user interface to a
programming system, demonstrating their practicality along with
their theoretical interest.  The research shows the trade-offs in
designing natural artificial languages: naturalness in a specific
domain is gained at the cost of generality for other domains.
%J International Journal of Man-Machine Studies
%V 20
%K user interfaces, cognitive psychology, human factors, systems development
%Y 
Introduction to Basic Concepts
	An Example of An Artificial Language
	Descriptions of Important Terms
	Properties of Natural Artificial Languages
	A Model of Artificial Language Processing
Experimental Evidence
	Symbols <==> Names
	Experiment 1: Symbols ==> Names
	Experiment 2: Names ==> Symbols
	General Discussion of Symbol <==> Name Experiments
	Names <==> Concepts
	Experiment 3: Names ==> Concepts
Practical Applications
	MENUNIX: A Menu-Based Interface to a Programming System
	Application 1: Symbols <==> Names
	Application 2: Names <==> Concepts
Conclusions
	Future Work
	Applicability of Cognitive Psychology to Design
	Relation to Learning Mathematics
References
 
>A related argument: are more descriptive command names better or briefer ones
>better ? Even with several words in the command name, there is still some
>imprecision - does it mean the thing to do is to give up the battle and go for a
>brief one word tag for each command ? With briefer command names, (for most
>systems), the entire menu can be fitted on to one screen. However, users have to 
>'live with' brief command names, for the entire life of the system. 
 
I think research recoomends to start people with long names and then
provide well-chosen abbreviations for them (as opposed to letting them
each try to devise their own).
 
%T Command Names
%S II. User Interface Design
%A Phil J. Barnard
%A Jonathan Grudin
%B Handbook of Human-Computer Interaction
%E Martin Helander
%D 1988
%N 11
%P 237-255
%C New York, NY
%I North-Holland
%K DESIGN Dialogue
%* (c) Copyright 1988 Elsevier Science Publishing Company
%Y Introduction
Designing Namesets
	What Designers Need to Keep in Mind
	What People Do When They Create Names
	What Designers Do When They Create Names
Experimental Contributions
	Interpreting Experiments
	Differing Designs of Command Namesets Used in Research
	Differing Characteristics of Participants in the Experiments
	Differing Task Domains of Research Experiments
	Differing Measures of User Performance
	Summary
	Natural Names versus System-Oriented or Arbitrary Names
	Attributes of Names: Specificity, Frequency and Concreteness
	Abbreviation
	Effects of Nameset on Individual Names
	Effects of Task Structure on the Use of Names
Using Research Knowledge in Design: Guidelines, Tools and Models
	Guidelines
	Background: Choosing and Structuring a Command Language
	Naming to Facilitate the Name-Operation Mapping
	Naming to Anticipate User Variability and Permit Customization
	Context of Command Name Use: Layout, Prompts, Help
	Designing the System for User Error
	Tools and Models
Design Problems, Approaches, and Unexplored Topics
Acknowledgements
References
-- 
Gary Perlman, Computer & Information Science, Ohio State University
228 Bolz Hall, 2036 Neil Avenue, Columbus, OH 43210-1277  USA
perlman@cis.ohio-state.edu   Voice: +01-614-292-2566   Fax: +01-614-292-2911
 
From M.van.Leeuwen@cwi.nl Thu Dec 16 14:35:28 GMT 1993
Date: Thu, 16 Dec 1993 14:35:28 GMT
From: M.van.Leeuwen@cwi.nl (Marc van Leeuwen)
Reply-To: LitProg@SHSU.edu, M.van.Leeuwen@CWI.NL
To: LitProg@SHSU.EDU
Subject: Release of another version of CWEB
 
Announcement of CWEB 3.x, a new and modified version of CWEB
 
A new version of CWEB, called version 3.x, has been developed and is now
officially being released. It is available by anonymous ftp from ftp.cwi.nl,
in the directory pub/cweb. The version was developed from the original CWEB
of Levy/Knuth, version 2.1, via an intermediate version called auc-cweb by
Frank Jensen of Aalborg University. The following list gives the differences
with respect to the original CWEB version; these are minor but useful ones,
of which the more significant ones were deemed necessary in order to allow
existing moderately large C programs to be gradually adapted to a literate
style without requiring major organisational changes.
 
- The programs are fully adapted to ANSI C: they support literate programs
  in that language and are themselves written in ANSI C.
 
- The CWEB system deals explicitly with #include preprocessor directives,
  just like #define directives were already handled. There are two important
  reasons for this: firstly the programmer is given control over the
  relative order of #include and #define directives in the output of
  CTANGLE, so that the situation that macro definitions disrupt the reading
  of (system) header files can be avoided, and secondly it allows CWEAVE to
  be aware of typedef declarations that are hidden in header files, so that
  their identifiers can be treated properly.
 
- Typedef declarations are found during the first pass of CWEAVE, along with
  all other |ilk| assingments. This implies that code containing typedef
  identifiers will be formatted correctly, whether it precedes the typedef
  declaration or follows it; this conforms to the WEB philosophy of giving
  the programmer maximal freedom in ordering the material, and also avoids
  awkward problems when discussing a typedef declaration in its own
  commentary (apart from the move to ANSI C, this is the change that required
  the most significant change of the program sources).
 
- A mechanism is provided to explicitly refer to the number of specific
  sections from within the commentary text, by means of symbolic labels.
 
- Module names are treated syntactically as statements by default, rather
  than as expressions (although means are provided to treat them as
  declarations or as expressions). This is really removing a property that
  was unjustly retained from (Pascal) WEB, since in C statements and
  expressions have completely separate places in the syntax, and module
  names almost never stand for expressions; the practical consequence is that
  it removes the need of putting an invisible semicolon (@;) after almost
  every module name (or even worse a real semicolon).
 
- A few (further) control codes have been added for the following purposes:
  to introduce a new section without risking a page break before it (useful
  between modules that are closely related but have to be separate because
  they are CTANGLEd to different places); to use the `|' (bitwise or)
  operator within `|...|'; and to remove one level of indentation from a line
  (useful for module names that stand for cases in a switch statement).
 
- Arbitrary 8-bit characters may be used in source files. The programs are
  completely robust against the use of such characters, but using them in
  program fragments outside strings and comments causes an error.
 
- Several styles of layout can be selected by command line options. The
  default style aligns all matching braces vertically (unlike other versions
  of CWEB) without consuming extra space.
 
- CWEAVE can be told to report irreducible scrap sequences (which cause bad
  layout) by a command line option, i.e., without changing the source file.
 
- The command line syntax has been changed so that with standard naming
  conventions only a single file name argument is needed, whether or not a
  change file is being used.
 
- Breaking of long expressions across lines, if necessary, is done in an
  intelligent way, favouring a break at operators of lowest priority, except
  when enclosed in parentheses or square brackets. (This is really only a
  change of the cwebmac format used by TeX.)
 
- A completely new manual has been written (25 pages) providing a (hopefully)
  more didactical introduction to literate programming and the use of CWEB;
  it contains a simple but complete sample program illustrating all basic
  aspects of CWEB, and also a one-page table of all control codes.
 
Furthermore significant changes have been made to the program sources;
although these are of little concern to ordinary users, they should make it
easier to maintain the programs or to modify them to handle different but
similar tasks (e.g., handle a different programming language); indeed they
were intended to make the programs more ``literate''. Although the basic
structure of the programs has not been greatly altered, almost every part of
the source files has undergone rewriting; many minor errors were removed in
this process. Some particularly noteworthy points:
 
- All trivial system dependencies have been removed, so that generally no
  change file is necessary to compile CWEB itself (this mainly means that
  the referral to "/dev/null" has been eliminated); the only explicit system
  dependencies are the assumption of the ASCII character set and the assumed
  interpretation of the value returned from |main|.
 
- The parser of CWEAVE operates by interpretation of a set of grammar rules
  that are explicitly stored in a (statically initialised linear) table.
  The formatting rules are given by easily interpreted format strings.
  Altogether there is a clean separation between parser and grammar (somewhat
  along the lines of the SPIDER system), making it relatively easy to alter
  the set of rules; in fact a system for dynamically selecting rules
  according to command line arguments is present that could easily be
  extended to support more variants. 
 
- The programs use a header file read in by #include to share common
  declarations between different compilation units (as is normal practice in
  multi-file C programs), instead of using the CWEB inclusion facility (@i)
  for this, which would lead to the text being replicated into all CWEB
  documents. In doing so, the programs also set a good example of how the
  multiple output file facility can be effectively used, since the header
  file is produced by CTANGLE from the same source file (common.w) that
  contains the definitions of the objects that the declarations in the header
  file refer to.
 
- The style of the programs has been altered to a more C-like one on
  numerous points where there were complications that could only be
  explained by the Pascal origins of the programs. For instance, since the
  program usually manipulates pointers into arrays rather than the indices
  of the elements, it is more natural to use NULL to indicate an exceptional
  value (e.g., the end of a list) than the value of a pointer to a specially
  reserved element. 
 
- In programs and documentation a systematic distinction is made between
  sections, which are numbered pieces of the CWEB document that may or may
  not contain a program fragment, and modules, which are named pieces of C
  code that are defined in one or more sections; thus a source of confusion
  is removed.
 
As I recently found out, there is now an updated version of the original
Levy/Knuth CWEB, called version 3.1. Therefore the version announced here
introduces a forking in the development history of CWEB, which is of course
regrettable, and which explains the strange version number of this version,
that would otherwise have been called CWEB 3.0. Apparently the main change
in version 3.1 is the support for C++ and therefore a fortiori for ANSI C;
further small changes have been made in direction different from those for
version 3.x, such as handling 8-bit characters in identifiers. Since it is
my intention to serve the literate programming community, not to divide it,
I will make an attempt at some future time to merge the two branches by
incorporating those additions if version 3.1 that are still relevant to 3.x,
most importantly to extend the support for C++ (currently the support is
limited to what was present in version 2.1, which is not likely to be
sufficient in view of the evolutionary nature of C++). Meanwhile I deemed it
wise not to hold up the release of the current version until such changes
have been made.
 
In other respects as well, I plan to provide active support for CWEB 3.x.
For one thing, it will be used to convert the computer algebra program LiE,
which is moderately large (currently about 600Kb source code in some 65
files), to a literate program; this should provide a good test for the
practical usability. Therefore all bug reports, comments and suggested can
be sent to the address below.
 
Marc van Leeuwen
CWI, Amsterdam, The Netherlands
e-mail: M.van.Leeuwen@cwi.nl
 
From Zdenek Mon Dec 20 10:19:23 MET 1993
Date: Mon, 20 Dec 93 10:19:23 MET
From: Zdenek Wagner <WAGNER%CSEARN.BITNET@SHSU.edu>
Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU
To: Literate Progaramming list <litprog@SHSU.edu>
Subject: nuweb for 286
 
Hello,
 
I am partially busy and partially lazy to study nuweb code so I have the
following question: did anybody managed to compile nuweb for 286 processor?
I just compiled it with my Borland C++ and when trying to run, it reboots the
computer.
 
Any help will be appreciated.
 Merry Christmas
 
,~~~/        /`               /     /|      /~~~
   /        /           |_/  /__/  ' |     /
  /     /~~/ /~~/ /~~/ /~~/ /\       | /| / /~~/ /~~/ /~~/ /~~/ /~~~
 /   , /  / /~~~ /  / /~~~ /  \      |/ |/ /  /_/  / /  / /~~~ /
 ~~~~  ~~~  ~~~ '  '  ~~~ '    `     '  '  ~~~  ~~/ '  '  ~~~ '
                              Zdenek Wagner______/
 
Some gateway between me and you may garble backslash. It will appear
on your screen as <pi> due to problems with EBCDIC <--> ASCII conversion.
It has already been corrected on SOME gateways.
 
The address <wagner@earn.cvut.cs> is obsolete and will soon cease to exist!
Valid addresses are:     <wagner@csearn.bitnet>
                         <wagner@earn.cvut.cz>
                                           ^^
 
From Thorbjoern Mon Dec 20 10:58:26 +0100 1993
Date: Mon, 20 Dec 1993 10:58:26 +0100 (MET)
From: Thorbjoern Ravn Andersen <ravn@imada.ou.dk>
Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
To: LitProg@SHSU.edu
Subject: Re: nuweb for 286
 
Zdenek Wagner
 
| I am partially busy and partially lazy to study nuweb code so I have the
| following question: did anybody managed to compile nuweb for 286 processor?
| I just compiled it with my Borland C++ and when trying to run, it reboots the
| computer.
 
I have nuweb 0.87 running on my 486 system (and I think I compiled it
for the 8086 processor), and it works like a charm.
 
I have, however, incorporated my patches for AUC-TeX (plus some Borland
Pascal support and Dominique de Waleffes comment patch) so the resulting
TeX output requires a relatively new LaTeX (like emTeX) to run.
 
If there is anybody who wants a copy, I will make it available for ftp.
 
(I am not probing into protected mode or anything like it, but if some
wizard wants to do it, I can bundle the source with the binary.)
 
Regards,
-- 
Thorbjo/rn Andersen
ravn@imada.ou.dk
 
From ddw2@sunbim.be Mon Dec 20 12:08:17 +0100 1993
Date: Mon, 20 Dec 93 12:08:17 +0100
From: ddw2@sunbim.be (Dominique de Waleffe)
Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE
To: LitProg@SHSU.edu, ravn@IMADA.OU.DK
Subject: Re: nuweb for 286
 
Thorbjoern> I have nuweb 0.87 running on my 486 system (and I think I
Thorbjoern> compiled it for the 8086 processor), and it works like a
Thorbjoern> charm.
 
Thorbjoern> I have, however, incorporated my patches for AUC-TeX
Thorbjoern> (plus some Borland Pascal support and Dominique de
Thorbjoern> Waleffes comment patch) so the resulting TeX output
Thorbjoern> requires a relatively new LaTeX (like emTeX) to run.
 
Thorbjoern> If there is anybody who wants a copy, I will make it
Thorbjoern> available for ftp.
 
I've been meaning to integrate your patches and mine into the latest
0.87 but haven't got any time to do it in months. I'd appreciate
being able to get a patched copy of 0.87... SO if you could put it up
for ftp... If you don't for any reason, could you send me the patched
nuweb? Or a diff, that will do.
 
Dominique
 
Merry Christmas and a Happy and Successful 1994    /\            	     
                                             *    /  \   *    *        
	    				   *     /o/\ \          	     
Dominique de Waleffe  ddw@sunbim.be           * / /  o \    *          
BIM sa			                       / /o   \ \      * 	     
Chee de Louvain, 510  Tel: +32 2 719 26 14    / o-------o\       	  
B-1930 Zaventem	      Fax: +32 2 725 47 83   ------o------- *    	  
Belgium					    _______||___________    
       	       	       	       	       	   ______________________	  
 
From jacojn@inet.uni-c.dk Mon Dec 20 12:23:23 GMT 1993
Date: Mon, 20 Dec 1993 12:23:23 GMT
From: jacojn@inet.uni-c.dk (Jacob Nielsen)
Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK
To: LitProg@SHSU.EDU
Subject: Re: nuweb for 286
 
>I am partially busy and partially lazy to study nuweb code so I have the
>following question: did anybody managed to compile nuweb for 286 processor?
>I just compiled it with my Borland C++ and when trying to run, it reboots the
>computer.
 
The only problem I've ever had with nuweb, is the use of 'tempnam' to
generate tempoary files. I have never quite got it working, but then I
work on UN*X :-), so I can allways think of some long file name, that
I'm quite sure wont colide with other file names.
 
You could consider altering the call of 'tempnam' - it's easy to find -
to produce something like tmmssxx.tmp, where 'mm' is minuts, 'ss' is seconds
and xx is the number of the processed file. Asuming you don't have files
named like that, all will work as a charm. PS: nuweb removes its temporary
files after use.
 
Merry christmas,
 
Jacob
--
Jacob Nielsen
Email:  jacojn@inet.uni-c.dk (my private account)
   or   bc898574@bbar.dth.dk (my account at the university)
 
From pgjtasse@atlas.cs.upei.ca Mon Dec 20 13:59:28 03d-7 1993
Date: Mon, 20 Dec 1993 13:59:28 03d-7 ((null))
From: pgjtasse@atlas.cs.upei.ca (Judy Tassell)
Reply-To: LitProg@SHSU.edu, pgjtasse@ATLAS.CS.UPEI.CA
To: LitProg@SHSU.EDU
Subject: An Encryption Decrypter
 
  Hiya.  I was wondering if anyone new of a way to derive the algorithm of
an encryption meathod with a list of the encoded words and their decoded
values.  I red in a book, _The Fools Run_ (fiction), that someone had
developed a program to do something liek this, and I was wondering if their
were any in existance.  Preferably written in (Turbo) Pascal, (Turbo)
C(+,++), or IBM (Turbo) Assembly.  Any input would be appretiated.
-Charles Tassell
 
From tomas@cae.wisc.edu Mon Dec 20 13:33:08 CST 1993
Date: Mon, 20 Dec 93 13:33:08 CST
From: tomas@cae.wisc.edu
Reply-To: LitProg@SHSU.edu, tomas@CAE.WISC.EDU
To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK
Subject: Re: nuweb for 286
 
> The only problem I've ever had with nuweb, is the use of 'tempnam' to
> generate tempoary files. I have never quite got it working, but then I
> work on UN*X :-), so I can allways think of some long file name, that
> I'm quite sure wont colide with other file names.
 
That's odd.  I thought |tempnam| _was_ a UNIXism.  I hacked |tempnam|
to the ANSI |tmpnam| and then diddled with that to get it to work on my Amigas.
(I had to make sure the temporary file went to the same directory as the code
so |rename| would work.)
 
>
> You could consider altering the call of 'tempnam' - it's easy to find -
> to produce something like tmmssxx.tmp, where 'mm' is minuts, 'ss' is seconds
> and xx is the number of the processed file. Asuming you don't have files
> named like that, all will work as a charm. PS: nuweb removes its temporary
> files after use.
>
> Merry christmas,
>
> Jacob
> --
> Jacob Nielsen
> Email:  jacojn@inet.uni-c.dk (my private account)
>    or   bc898574@bbar.dth.dk (my account at the university)
>
I have found nuweb to be terrifically useful.  The ability to make many output
files from one web makes it pleasant to write wrapper code to test certain
functions one at a time.  I was quite pleased with CWEB until I started
hacking about with nuweb.
Good work Preston!
--
Ciao!
                 Tomas Willis  (tomas@cae.wisc.edu)
     @<standard disclaimer@>               @<standard pithy remark@>
 --------------------------------------------------------------------------
| There is a bright side to being the first and only intelligent beings in |
| our galaxy - we will have the chance to found the Galactic Empire!       |
|      --- some astronomy student ---                                      |
 --------------------------------------------------------------------------
 
From mauer@mcs.anl.gov Tue Dec 21 00:29:10 GMT 1993
Date: Tue, 21 Dec 1993 00:29:10 GMT
From: mauer@mcs.anl.gov (Andrew Mauer)
Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV
To: LitProg@SHSU.EDU
Subject: Using noweb with Underscores
 
I would like to use 'noweb', and have written several pieces of code
with it. 
 
Recently, I decided to convert all of by bastardized nuweb/noweb code
to plain noweb, and I came across a rather ugly "feature" of noweb
which seems to be the fault of LaTeX (??).
 
I use "indexing" mainly to get numbered chunks. I like to have
descriptive file names, and this frequently means *underscores*. I
like to call the root node for a file by it's name, so I have a file
"Expression_List.h" and I want a scrap <<Expression_List.h>>. 
Unfortunately, this causes latex (specifically amslatex, but I don't
think that matters) to barf when trying to tex...
 
I would not mind enclosing the filename in [[ ... ]] , or preferably
the shorthand verb |...|, but this causes the notangle -R<OUTPUT_FILENAME>
method of generating your code to fail badly. 
 
It seems to me that the fix should be to allow -RExpression_List.h to
extract the node <<[[Expression_List.h]]>>. 
 
Let me know what you think.
 
/Andrew/
 
P.S. Let me know if you want the patches, too.
--
/Andrew Mauer/
mauer@mcs.anl.gov
 
From Norman Tue Dec 21 00:42:15 -0500 1993
Date: Tue, 21 Dec 1993 00:42:15 -0500
From: Norman Ramsey <norman@bellcore.com>
Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM
To: LitProg@SHSU.edu, mauer@mcs.anl.gov
Subject: Re: Using noweb with Underscores
 
> I like to have
> descriptive file names, and this frequently means *underscores*. I
> like to call the root node for a file by it's name, so I have a file
> "Expression_List.h" and I want a scrap <<Expression_List.h>>. 
> Unfortunately, this causes latex (specifically amslatex, but I don't
> think that matters) to barf when trying to tex...
> 
> I would not mind enclosing the filename in [[ ... ]] , or preferably
> the shorthand verb |...|, but this causes the notangle -R<OUTPUT_FILENAME>
> method of generating your code to fail badly. 
 
Interesting.  I tend to avoid underscores in file names (I prefer a
hyphen), so I have never faced this issue. What's wrong with
	notangle -R'[[Expression_List.h]]'
?
Do you just find it ugly or am I missing some deeper issue?
 
There are various other games you could play.  If you're not using
much math, you might find something like
	\catcode`\_=13
profitable; this would eliminate _ as a special character.  That's
probably what I would do.  (I might be wrong about 13; you should
check the TeXbook for the catcode of `other').
 
> It seems to me that the fix should be to allow -RExpression_List.h to
> extract the node <<[[Expression_List.h]]>>. 
 
I'm unenthusiastic about this idea, but the world won't end if you do it.
 
Norman
 
From Klaus Tue Dec 21 08:05:40 +0100 1993
Date: Tue, 21 Dec 1993 08:05:40 +0100 (MEZ)
From: Klaus Guntermann <gunterma@iti.informatik.th-darmstadt.de>
Reply-To: LitProg@SHSU.edu, gunterma@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@shsu.edu
Subject: cweave 3.1 optimization
 
Dear cweb users,
 
since the Stanford GraphBase was published we had an increasing need
to use cweb to create formatted and printed program listings. But
doing so I ran into an incredible time penalty for using cweave.
After some investigation I found out, that problems with the NFS
implementation on our workstations were heavily exercised by cweave
in the second phase. The reason is that in section 78 (definition of
|flush_buffer|) the macro |c_line_write| contains a call to |fflush|.
This seems to be absolutely unnecessary. At least I cannot see why
the file buffers should be flushed here.
 
When I removed this call the timings for cweave in phase 2 improved
dramatically for us. But also for other machines I noticed a
considerable speed up in system time for larger cweave jobs (eg.
cweaving cweave) without the |fflush|. Thus I would recommend to
remove this. To make sure that not any negative effects are 
introduced by this - although I cannot imagine how that should 
happen - I include a change file for this optimization. Before that
change is included in one of the next releases, everybody can test it
and report problems to me. Silvio Levy is willing to include that
change in the next official release, if no problems are reported.
 
I would also like to hear of any dramatic improvements (by mail,
please). To make sure that we did not introduce our NFS performance
problem by choosing bad parameters, I would like to hear in detail
about the behaviour of this change in different releases of AIX 3 on
IBM RS/6000s (we are on 3.2.4).
Thank you in advance.
 
Including seasonal greetings from Darmstadt,
 
	Klaus Guntermann	<guntermann@iti.informatik.th-darmstadt.de>
	TH Darmstadt		(Technical University)
	FB Informatik		(Computer Science Department)
	Alexanderstr. 10, D-64283 Darmstadt, FR Germany
 
8<------------------------------------------------------------cweave.ch
There are some performance penalties when using fflush too heavily,
mainly when the file system is accessed via NFS.
 
As there is no need to flush the file buffers so often, we can omit
that from cweave.
 
Klaus Guntermann 	<guntermann@iti.informatik.th-darmstadt.de>
 
-----
First update all parts which refer to version numbering, and add a
trailing tag.
 
@x
% Version 3.1 --- November 1993
@y
% Version 3.1 --- November 1993
% Update  3.1-1	--- remove fflush on files, December 1993
%	by Klaus Guntermann	<guntermann@iti.informatik.th-darmstadt.de>
@z
 
@x
\def\title{CWEAVE (Version 3.1)}
\def\topofcontents{\null\vfill
  \centerline{\titlefont The {\ttitlefont CWEAVE} processor}
  \vskip 15pt
  \centerline{(Version 3.1)}
  \vfill}
@y
\def\title{CWEAVE (Version 3.1-1)}
\def\topofcontents{\null\vfill
  \centerline{\titlefont The {\ttitlefont CWEAVE} processor}
  \vskip 15pt
  \centerline{(Version 3.1-1)}
  \vfill}
@z
 
@x
@d banner "This is CWEAVE (Version 3.1)\n"
@y
@d banner "This is CWEAVE (Version 3.1-1)\n"
@z
 
-----
And here the real change takes place. Do not 'fflush(active_file)'
 
@x
@d c_line_write(c) fflush(active_file),fwrite(out_buf+1,sizeof(char),c,active_file)
@y
@d c_line_write(c) fwrite(out_buf+1,sizeof(char),c,active_file)
@z
8<------------------------------------------------------------
 
From Andrew Tue Dec 21 09:44:36 CST 1993
Date: Tue, 21 Dec 93 09:44:36 CST
From: Andrew Mauer <mauer@mcs.anl.gov>
Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV
To: Norman Ramsey <norman@bellcore.com>
Subject: Re: Using noweb with Underscores
 
Andrew Mauer said
> I like to have
> descriptive file names, and this frequently means *underscores*. I
> like to call the root node for a file by it's name, so I have a file
> "Expression_List.h" and I want a scrap <<Expression_List.h>>. 
> Unfortunately, this causes latex (specifically amslatex, but I don't
> think that matters) to barf when trying to tex...
> 
> I would not mind enclosing the filename in [[ ... ]] , or preferably
> the shorthand verb |...|, but this causes the notangle -R<OUTPUT_FILENAME>
> method of generating your code to fail badly. 
 
Norman Ramsey said:
> Interesting.  I tend to avoid underscores in file names (I prefer a
> hyphen), so I have never faced this issue. What's wrong with
> 	notangle -R'[[Expression_List.h]]'
> ?
> Do you just find it ugly or am I missing some deeper issue?
 
The problem I have is with automatic extraction a la:
 
%.cc: %.nw
	$(TANGLE) $(TANGLE_FLAGS) -R$@ $(web-files) > $@
 
or some variant thereof. This would force me to name EVERY root chunk
in the [[filename]] style. This isn't aesthetically pleasing, and it
would mean fixing up quite a bit of existing code :-( .
 
> There are various other games you could play.  If you're not using
> much math, you might find something like
> 	\catcode`\_=13
> profitable; this would eliminate _ as a special character.  That's
> probably what I would do.  (I might be wrong about 13; you should
> check the TeXbook for the catcode of `other').
[The catcode for "other" is 12.]
 
There must be some \catcode resetting going on in the support code;
I perform this in the text immediately before the problem area:
 
\catcode`\_=\other
<<Expression_List.h>>= [...]
 
But when TeX reads the <<Expression_List.h>> line, it still thinks 
that _ (underscore) is a subscript (catcode 8). (I can't figure out
why, and I believe I looked at all the macros that get executed... ?)
 
There is another problem with this. Even if you catcode an underscore
to \letter or \other, it does not *print* as an underscore. It comes
out as a little raised dot. This is obviously a Tex problem, but I'm
not an expert. I would appreciate any TeX expert advice. (There is
presumably an easy solution...)
 
/Andrew/
 
From fuellen@athena.mit.edu Tue Dec 21 09:44:36 CST 1993
Date: Tue, 21 Dec 93 09:44:36 CST
From: fuellen@athena.mit.edu (Georg Fuellen)
Reply-To: LitProg@SHSU.edu, fuellen@ATHENA.MIT.EDU
To: LitProg@SHSU.EDU
Subject: Re: An Encryption Decrypter
 
In article <2f5b96$ast@atlas.cs.upei.ca>, pgjtasse@atlas.cs.upei.ca (Judy Tassell) writes:
|>   Hiya.  I was wondering if anyone new of a way to derive the algorithm of
|> an encryption meathod with a list of the encoded words and their decoded
|> values.  I red in a book, _The Fools Run_ (fiction), that someone had
|> developed a program to do something liek this, and I was wondering if their
|> were any in existance.  Preferably written in (Turbo) Pascal, (Turbo)
|> C(+,++), or IBM (Turbo) Assembly.  Any input would be appretiated.
|> -Charles Tassell
 
In general, there is no way to derive the algorithm, 
and any known plaintext/ciphertext technique (you are hinting at this)
does presumably not enable decryption of new messages EVEN IF THE ALGORITHM 
IS KNOWN TO BE RSA ENCRYPTION (for instance), but the key is kept secret.
 
There is a nice faq in sci.crypt, to which follow-ups are redirected.
 
Regards,
  georg
fuellen@mit.edu
The convex hull of all disclaimers made on usenet last year applies to this mess
 
From paul@opal.com.au Tue Dec 21 21:55:43 GMT 1993
Date: Tue, 21 Dec 1993 21:55:43 GMT
From: paul@opal.com.au (Paul Bandler)
Reply-To: LitProg@SHSU.edu, paul@OPAL.COM.AU
To: LitProg@SHSU.EDU
Subject: cweb for C++ API Extractor? - Request for Information
 
I am new to reading this group so appologies for what is I'm sure a very
basic question.
 
We're at the begining for a C++ development and establishing coding /
documentation practises for the project.  We would like to be able to 
build a high quality (i.e. to be distributed as part of a software product) 
programmer's reference manual derived from the C++ source files.
 
In investigating this I have been lead to this news group and understand
that there is a program called cweb which may be of assistance to us.
 
Could someone advise:-
 
1.	Whether cweb is a tool suitable to my purpose?
2.	Is cweb available in the public domain at an archive site?  If so,
	where?
3.	Would someone be willing to send me an example cweb input and output
	so that I can get an idea of what is involved?
4.	Would it be possible to integrate cweb with Framemaker?
5.	There is some resistance here to the effect of needing to instrument
	ones source code extensively in order to be able to create product
	quality end-user documentation from it.  Can anyone comment as the
	feasibility/desirability of this approach or indicate whether this
	has been achieved successfully in practice somewhere?
 
I would appreciate any respondants copying me directly by email in order to
ensure timely delivery.
 
Thanks in anticipation,
 
Paul Bandler
Project Manager
Opal Communications Systems
Melbourne, VIC, Australia
paul@opal.com.au
 
From mwj@cnve.rz.uni-jena.de Tue Dec 21 21:55:43 GMT 1993
Date: Tue, 21 Dec 1993 21:55:43 GMT
From: mwj@cnve.rz.uni-jena.de (Johannes Waldmann)
Reply-To: LitProg@SHSU.edu, mwj@CNVE.RZ.UNI-JENA.DE
To: LitProg@SHSU.EDU
Subject: DEK's `Stanford Graph Base' book existing / available?
 
Some time ago a new book by Knuth `The Stanford Graph Base'
was announced in some newsgroup. Is it available, meanwhile?
 
Is it something like his TeX/MF books, or rather like Art Of Computer
Programming? (I read it should become Vol 4 of this series.)
 
Johannes - mwj@rz.uni-jena.de
 
From schrod@iti.informatik.th-darmstadt.de Tue Dec 21 21:55:43 GMT 1993
Date: Tue, 21 Dec 1993 21:55:43 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: nuweb for 286
 
In article <18678804@MVB.SAIC.COM>, tomas@cae.wisc.edu writes:
> > The only problem I've ever had with nuweb, is the use of 'tempnam' to
> > generate tempoary files. I have never quite got it working, but then I
> > work on UN*X :-), so I can allways think of some long file name, that
> > I'm quite sure wont colide with other file names.
> 
> That's odd.  I thought |tempnam| _was_ a UNIXism.
 
Yes, it is. Originally it's from SVID2, and it's listed both in XPG2
and XPG3. 'Though I don't know if BSD 4.2 has it (but mktemp() is
there), at least SunOS 4.1 does support it.
 
Cheers,
        Joachim
 
PS: For the Non-Unix folks:
        SVID: System V Interface Definition
        XPG: X/Open Portability Guide
    Open definitions of the API for Unix systems.
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod                  Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From schrod@iti.informatik.th-darmstadt.de Tue Dec 21 21:55:43 GMT 1993
Date: Tue, 21 Dec 1993 21:55:43 GMT
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Re: Using noweb with Underscores
 
In article <18696317@MVB.SAIC.COM>, Norman Ramsey <norman@bellcore.com> writes:
> 
> There are various other games you could play.  If you're not using
> much math, you might find something like
> 	\catcode`\_=13
> profitable; this would eliminate _ as a special character.  That's
> probably what I would do.  (I might be wrong about 13; you should
> check the TeXbook for the catcode of `other').
 
It's 12.
 
In fact, you can use
 
    \catcode`\_=\active
    \def_{\ifmmode \sb \else \_\fi}
 
and get an underscore in text and a subscript in math mode, as long
as you don't use _ as the first char in a table entry. (And, of
course, as long as you put these lines in a macro file; don't stick
them at the head of your document.)
 
(This holds for both LaTeX and plain TeX.)
 
Cheers,
	Joachim
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Computer Science Department
Technical University of Darmstadt, Germany
 
From d.love@dl.ac.uk Tue Dec 21 21:55:43 GMT 1993
Date: Tue, 21 Dec 1993 21:55:43 GMT
From: d.love@dl.ac.uk (Dave Love)
Reply-To: LitProg@SHSU.edu, d.love@DL.AC.UK
To: LitProg@SHSU.EDU
Subject: Re: Using noweb with Underscores
 
>>>>> "Andrew" == Andrew Mauer <mauer@mcs.anl.gov> writes:
 
 Andrew> There must be some \catcode resetting going on in the support code;
 
There is -- the catcodes are not saved and reset from the values they
have when the code which sets the scrap is invoked, just flipped to
the canonical values.
 
[...]
 
 Andrew> There is another problem with this. Even if you catcode an underscore
 Andrew> to \letter or \other, it does not *print* as an underscore. It comes
 Andrew> out as a little raised dot. This is obviously a Tex problem, but I'm
 Andrew> not an expert. I would appreciate any TeX expert advice. (There is
 Andrew> presumably an easy solution...)
 
The Computer Modern text fonts (for instance) don't contain an
underscore.  If you want _ to print as underscore I think you want, in
general, just:
  \catcode`\_=\active  % so `_' \equiv `\_'
If you then want to use subscripts, you have either to use an
\everymath to reset the catcode of _ or to use \sb.
 
I support Norman's recommendation of dashes rather than underscores if
your OS allows and caution against catcode hacking unless you're
prepared for surprises.  Some macros written by TeX gurus that expect
filenames as arguments will barf on names containing underscores and
other special characters anyhow.
 
Incidentally, it is likely that the noweb macros will need some
alteration for use with the recently-surfaced LaTeX 2e (the new
standard version of LaTeX when it gets out of test).  I will attend to
this in the new year if no one else does.
 
From preston@cs.rice.edu Wed Dec 22 17:58:05 GMT 1993
Date: Wed, 22 Dec 1993 17:58:05 GMT
From: preston@cs.rice.edu (Preston Briggs)
Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU
To: LitProg@SHSU.EDU
Subject: Re: DEK's `Stanford Graph Base' book existing / available?
 
mwj@cnve.rz.uni-jena.de (Johannes Waldmann) writes:
>Some time ago a new book by Knuth `The Stanford Graph Base'
>was announced in some newsgroup. Is it available, meanwhile?
 
I recently got a flyer from the ACM Press saying that it's here, order
now.
 
US$ 40.75 for ACM members, $45.25 for nonmembers.
 
ACM order number 704931
 
ACM
Church Street Station
PO Box 12114
New York, NY  10257
 
(800) 342-6626 or (212) 626-0500
ACMPUBS@acm.org
 
In Europe,
 
ACM European Service Center
Avenue Marcel Thiry 204
1200 Brussels, Belgium
 
Phone 32 2 774 9602
ACM_EUROPE@acm.org
 
>Is it something like his TeX/MF books, or rather like Art Of Computer
>Programming? (I read it should become Vol 4 of this series.)
 
It's not Volume 4; instead, it's supposed to represent his final
preparation.  Nor do I imagine it's like the TeX/MF books.  They were
each a single large program.  This is supposed to be a collection of
30 essays, where each essay is is a small program.
 
Preston Briggs
 
From bos@mdd.comm.mot.com Wed Dec 22 12:54:57 PST 1993
Date: Wed, 22 Dec 93 12:54:57 PST
From: bos@mdd.comm.mot.com (Mary Bos)
Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM
To: LitProg@SHSU.edu, preston@CS.RICE.EDU
Subject: Re: DEK's `Stanford Graph Base' book existing / available?
 
I bought Knuth's new book "The Stanford GraphBase" at the
University BookStore (University of Washington) in Seattle, WA USA,
for $42.00 US about a month ago.  I have seen the book around in
other bookstore's computer science areas (Tower Books - a chain
in the US).
 
The blurb on the back says
 
"The Stanford GraphBase: A Platform for Combinatoral Computing represents
  the first fruits of Donald E. Knuth's preparations for Volume 4 of 
  The Art of Computer Programming. The book's first goal is to demonstrate,
  through 30 examples, the art of literate programming....The book's second
  goal is to provide a useful means for comparing combinatorial algorithms
  and evaluating methods of combinatorial computing...."
 
 I have introduced a few others in my workplace to this book and seem
 to be getting others to consider literate programming as a standard.
 We'll see.
 
  mary bos                                        bos@mdd.comm.mot.com
  Motorola Wireless Data Group                   (206) 487 5851
  19807 NorthCreek Parkway North        
  Bothell WA  98011
 
From bill@majipoor.cygnus.com Wed Dec 22 12:54:57 PST 1993
Date: Wed, 22 Dec 93 12:54:57 PST
From: bill@majipoor.cygnus.com (Bill Cox)
Reply-To: LitProg@SHSU.edu, bill@MAJIPOOR.CYGNUS.COM
To: LitProg@SHSU.EDU
Subject: Re: DEK's `Stanford Graph Base' book
 
I bought a copy about 2 weeks ago.  It's about a set of
tools that Knuth built to help him work on combinatorial
problems for Volume 4.
 
He spoke about Volume 4 at the bookstore where I bought the
book.  Volume 4 will be about *2000* pages, in three bindings.
He expects to be done by the year 2003.  John Hennesey is
helping him to design a RISC-like assembly language to
replace MIX.  Apparently, most of the Volume 4 algorithms
will be written in cweb, as the GraphBase is, but the RISC
MIX will see some use.
 
Volume 4 will be published as a series of 'fascicles' of
about 128 pages, starting in the middle of 1994.  I believe
he said that the RISC MIX will be one of the first fascicles,
so people will have time to build simulators.
 
The GraphBase software is available free by anonymous FTP from
labrea.stanford.edu.
 
It was truly a treat to hear him speak in person.  DEK's a
entertaining speaker!
--
bill@cygnus.com                     Your CHILL compiler supplier
(415)903-1436 (voice)                        (415)903-0122 (FAX)
 
From Lee Thu Dec 23 17:51:09 EST 1993
Date: Thu, 23 Dec 93 17:51:09 EST
From: Lee Wittenberg <leew@pilot.njin.net>
Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET
To: LitProg@shsu.edu, paul@opal.com.au
Subject: Re: cweb for C++ API Extractor? - Request for Information
 
Paul Bandler writes:
 
> I am new to reading this group so appologies for what is I'm sure a very
> basic question.
 
No apologies necessary.  That's what the group is for (IMHO).
 
> We're at the begining for a C++ development and establishing coding /
> documentation practises for the project.  We would like to be able to 
> build a high quality (i.e. to be distributed as part of a software product) 
> programmer's reference manual derived from the C++ source files.
> 
> In investigating this I have been lead to this news group and understand
> that there is a program called cweb which may be of assistance to us.
> 
> Could someone advise:-
> 
> 1.	Whether cweb is a tool suitable to my purpose?
 
Yes.  CWEB 3.0 (and thus the current version 3.1, as well) is designed
to work with C++.  I have used it for some C++ work myself.
 
> 2.	Is cweb available in the public domain at an archive site?  If so,
> 	where?
 
The official site is labrea.stanford.edu.  I believe it is in the
~/pub/cweb directory.
 
> 3.	Would someone be willing to send me an example cweb input and output
> 	so that I can get an idea of what is involved?
 
CWEB itself is just such an example, but if you'd like something
simpler, I have a few sample webs available in the
~/pub/leew/samples.LP directory of bart.kean.edu.
 
> 4.	Would it be possible to integrate cweb with Framemaker?
 
It ~may~ be possible, if you're willing to do the rewriting, but CWEB
is set up (designed?) to work with TeX.
 
> 5.	There is some resistance here to the effect of needing to instrument
> 	ones source code extensively in order to be able to create product
> 	quality end-user documentation from it.  Can anyone comment as the
> 	feasibility/desirability of this approach or indicate whether this
> 	has been achieved successfully in practice somewhere?
 
LP doesn't really work well for end-user documentation (IMHO).  What
it ~does~ do is to turn the program itself into a high-quality
programmer's reference (which is what you asked about in the first
place).
 
> I would appreciate any respondants copying me directly by email in order to
> ensure timely delivery.
 
Hope this helps.
 
		-- Lee
		   leew@pilot.njin.net
 
From thompson@sun1.coe.ttu.edu Thu Dec 23 17:51:09 EST 1993
Date: Thu, 23 Dec 93 17:51:09 EST
From: thompson@sun1.coe.ttu.edu
Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu
To: LitProg@SHSU.EDU
Subject: comp.programming.literate FAQ
 
Archive-name: literate-programming-faq
Last-modified: 1993/11/11
Version: 1.0.4
 
Welcome to the Literate Programming Frequently Asked Questions List
-------------------------------------------------------------------
 
This version was created Thursday - November 11, 1993 and should
considered stale after 90 days.  Information contained in this document
is the best available at preparation.
 
Disclaimer: "This FAQ is presented with no warranties or guarantees of
ANY KIND including correctness or fitness for any particular purpose.
The author of this document has attempted to verify correctness of the
data contained herein; however, slip-ups can and do happen.  If you use
this data, you do so at your own risk."
 
Copyright 1993 David B. Thompson.  All rights reserved worldwide.
Permission is granted to copy this document for free distribution so
long as it remains intact and unmodified.
 
* Introduction:
---------------
 
This document is for new and experienced users of literate programming
tools.  The purpose is to explain the concept of literate programming and
to provide a resource for locating files of interest to literate
programmers and those interested in literate programming.
 
The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list
is maintained by Dave Thompson, who can be reached at:
 
    thompson@sun1.coe.ttu.edu     * Preferred mailing address for FAQ
                                    related comments/questions.
    wqdbt@ttacs1.ttu.edu          * Forwarded to my pc.
 
Comment and constructive criticism is welcome.  Direct flames to
/dev/null (or > nul if you're a msdos user! ;-)  If you find an error,
please report it.  I'm particularly interested in establishing the
locations of generally available literate programming tools.  If you are
the author of such a tool and wish to have it included in this list,
please send email.
 
Please note this is a work-in-progress.  It is *not* complete, and
probably will not be complete for some months.  Nevertheless, the
information contained herein may be useful to some.  Use it as it is
intended.
 
- ----------------------------------------------------------------------
 
- Typography:
-------------
 
Major sections of the FAQ are divided by double lines (====).  Minor
sections and other divisions are separated by single lines (----).
Major topics use a "* " as a leader.  Minor topics use a "- " as a
leader.  This should simplify searching for topics.
 
Table of Contents:
------------------
 
* Introduction
    - Typography.
* How to get the FAQ.
    - Literate Programming FAQ.
    - FWEB FAQ.
* The LitProg newsgroup.
* Internet nodes of interest to literate programmers.
* What is literate programming?
* How do I begin literate programming?
* What tools are available and where are they?
    - c2latex
    - CLip
    - CWEB
    - FunnelWeb
    - FWEB
    - noweb
    - NUWEB
    - SchemeWEB
    - Spidery WEB
    - WinWordWEB
* What other resources are available?
    - Virtual Coursework
* Code examples.
    - Examples included with developer's tools
    - Cameron Smith's KR-CWEB
    - Bart Child's examples for FWEB
* Bibliographies.
* How to anonymously ftp.
* Acknowledgements.
* End notes.
 
* How to get the FAQ:
---------------------
 
- Literate Programming FAQ.
---------------------------
 
You have many ways to get a current copy of this FAQ.  One is to use
anonymous ftp (if you don't know how, see a later section in this FAQ)
to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites
or the Literate Programming Archive and retrieve a copy of the file.
(For more information on CTAN and the literate programming archive, see
the section below entitled "Internet Nodes of Interest to Literate
Programmers.")
 
An alternative is to use the fileserver at SHSU.  Send a message to
FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message
 
    SENDME FAQ.LITPROG
 
The file server will forward a copy of the file to you via email.
 
- ----------------------------------------------------------------------
 
- FWEB FAQ:
-----------
 
Marcus Speh <marcus@x4u.desy.de> maintains the FWEB FAQ.  The current
version number is 1.29.  It can be retrieved in the same way as this
FAQ; either by anonymous ftp or through the SHSU file server.  On the
SHSU server, the file name is FAQ.FWEB.  Invoke your ftp software, open
a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory
FAQ, and transfer the file FAQ.FWEB.
 
Alternatively, send a message to the file server, FILESERV@SHSU.EDU
(FILESERV@SHSU.BITNET), and include the following text in a one line
message:
 
    SENDME FAQ.FWEB
 
The file server will send the current version of the file via email.
 
The FWEB FAQ exists in various formats, including HyperText (see other
resources below). In Europe, the complete distribution can also be
obtained from ftp.desy.de [131.169.10.115] in directory
/pub/faq/web/fweb/.  It is also available from the literate programming
archive (LPA) in the directory LPA/documentation/faq/fweb (see the
references to LPA below for more information).
 
* The LitProg Newsgroup:
------------------------
 
One of the most important resources is the literate programming
newsgroup, comp.programming.literate.  You can read this newsgroup using
your standard reader.  Altenatively, the newsgroup is gated to a mailing
list hosted by George Greenwade and Sam Houston State University.  You
can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or
LISTSERV@SHSU.BITNET), and include in the message one line of text:
 
    SUBSCRIBE LITPROG  "your name in quotes"
 
The list is unmoderated; messages sent to litprog@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.programming.literate.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory litprog.
 
* Internet Nodes of Interest to Literate Programmers:
-----------------------------------------------------
 
The principal nodes of interest to literate programmers are the Literate
Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX
Archive Network).
 
The Literate Programming Archive (LPA) is:
 
  Node:       ftp.th-darmstadt.de [130.83.55.75]
  Directory:  pub/programming/literate-programming
  Notes:      Fastest response during off-U.S. [yep] business hours.
 
The CTAN sites are:
 
ftp host             IP            CTAN root    Institution and Sponsor
-------------------------------------------------------------------------
ftp.TeX.ac.UK        134.151.79.32 pub/archive  Aston Univ./UK TeX U.G.
ftp.Uni-Stuttgart.DE 129.69.8.13   soft/tex     Univ. Stuttgart/DANTE e.V
ftp.SHSU.edu         192.92.115.10 tex-archive  Sam Houston State Univ.
 
Other nodes and directories of interest include:
 
  Node:       niord.shsu.edu [192.92.115.8]
  Directory:  various (do some snooping!)
  Notes:      Has a gopher server.
 
  Node:       ftp.desy.de [131.169.10.115]
  Directory:  pub/web. Various documents, samples, and the FWEB FAQ.
  Notes:      Has a www server, http://info.desy.de:80/
 
* What is Literate Programming?
-------------------------------
 
Literate programming is the combination of documentation and source
together in a fashion suited for reading by human beings.  In fact,
literate programs should be enjoyable reading, even inviting!  (Sorry
Bob, I couldn't resist!)  In general, literate programs combine source
and documentation in a single file.  Literate programming tools then
parse the file to produce either readable documentation or compilable
source.  The WEB style of literate programming was created by D.E. Knuth
during the development of his TeX typsetting software.
 
All the original work revolves around a particular literate programming
tool called WEB.  Knuth says:
 
     The philosophy behind WEB is that an experienced system
     programmer, who wants to provide the best possible
     documentation of his or her software products, needs two
     things simultaneously: a language like TeX for formatting,
     and a language like C for programming.  Neither type of
     language can provide the best documentation by itself; but
     when both are appropriately combined, we obtain a system
     that is much more useful than either language separately.
 
     The structure of a software program may be thought of as a
     web that is made up of many interconnected pieces.  To
     document such a program we want to explain each individual
     part of the web and how it relates to its neighbours. The
     typographic tools provided by TeX give us an opportunity to
     explain the local structure of each part by making that
     structure visible, and the programming tools provided by
     languages such as C or Fortran make it possible for us to
     specify the algorithms formally and unambigously. By
     combining the two, we can develop a style of programming
     that maximizes our ability to perceive the structure of a
     complex piece of software, and at the same time the
     documented programs can be mechanically translated into a
     working software system that matches the documentation.
 
* How to begin literate programming:
------------------------------------
 
A recommended book is D.E. Knuth's collection of articles (1992)
"Literate Programming," Center for the Study of Language and
Information, Stanford University, ISBN 0-937073-80-6 (pbk).  This book
gives insight into Knuth's thoughts as he developed the web system of
literate programming (and TeX for typesetting).  It does not document
methods for literate programming.
 
A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate
Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk).
This book focuses on using Knuth's web system.
 
Some talk exists in the newsgroup/mailing list for a Usenet University
course in literate programming.  I'm sure discussion of this topic will
be welcomed.  If you are interested, please participate.
 
* What Tools are Available:
---------------------------
 
A significant number of tools for literate programming are available.
Most have been ported from their original systems, so support multiple
computer platforms.  If you are the developer of such a tool, and would
like to make the software freely available, please send me email and
I'll reply with a form (like those below) for you to fill in.  (Or
short-circuit the process and kludge a form from below. :-)
 
- C2LaTeX:
----------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix
 
Software supported:
            Programming language: C.
            Text formatter: LaTeX but it's easy to change the formatter.
 
Availability:
            Anonymous ftp from
                omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex.
 
Readme:
            Absent.  Documentation is in the C source for c2latex.
 
Brief description:
            C2latex provides simple support for literate programming
            in C.  Given a C source file in which the comments have
            been written in LaTeX, c2latex converts the C source file
            into a LaTeX source file.  It can be used to produce
            typeset listings of C programs and/or documentation
            associated with the program.
 
            C2latex produces LaTeX source by implementing a small
            number of rules.  A C comment that starts at the beginning
            of a line is copied unmodified into the LaTeX source
            file.  Otherwise, non-blank lines are surrounded by a pair
            of formatting commands (\begin{flushleft} and
            \end{flushleft}), and the lines are separated by \\*.
            Each non-blank line is formatted using LaTeX's \verb
            command, except comments within the line are formatted in
            an \mbox.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
- ----------------------------------------------------------------------
 
- CLip:
-------
 
Developer:
            E.W. van Ammers and M.R. Kramer
 
Systems supported:
            Vax/VMS and MS-DOS.
 
Software supported:
            An programming language.  Plain TeX and LaTeX text
            formatters.
 
Availability:
            Anonymous ftp from:
              CTAN/web/clip
              LPA/machines/ms-dos
              LPA/machines/vax
              sun01.info.wau.nl/CLIP
 
Readme:
            In distribution.
 
Brief description:
 
Support:
            Unknown.
 
- ----------------------------------------------------------------------
 
- CWEB:
-------
 
Developer:
            Silvio Levy and D.E. Knuth
 
System(s) supported:
            Unix systems (dos and amiga ports available)
 
Software supported:
            Languages supported are C and C++.  Text formatters are
            plain TeX and LaTeX.
 
Availability:
            anonymous ftp from:
              labrea.stanford.edu/pub/cweb
              LPA/c.c++
              CTAN/web/c_cpp/cweb
              DOS version in CTAN/web/c_cpp/cwb30p8c
              DOS version in LPA/machines/ms-dos
              Amiga version to be posted soon (look at CTAN).
              Mac port of CTANGLE in LPA/machines/mac
              LaTeX support in LPA/c.c++
 
Readme:
            bundled with above
 
Brief description:
 
Support:
            bugs to levy@math.berkeley.edu
 
- ----------------------------------------------------------------------
 
- FunnelWeb:
------------
 
Developer:
            Ross N. Williams: ross@guest.adelaide.edu.au
 
Systems supported:
            MSDOS, Mac, VMS, Sun.  Other ports reported.
 
Software supported:
            For printing, TeX.  Otherwise no restrictions.
 
Availability:
            anonymous ftp from:
              CTAN/web/funnelweb
              LPA/independent
              ftp.adelaide.edu.au/pub/funnelweb
 
Readme:
            With bundle above.
 
Brief description:
            FunnelWeb is a production-quality literate-programming tool
            that emphasises simplicity and reliability. Everything about
            FunnelWeb, from the simplicity of its language to the
            comprehensive tutorial in the user's manual, has been
            designed to make this as simple, as practical, and as usable
            a tool as possible.
 
            Features:
               + Provides a simple macro preprocessor facility.
               + Can produce typeset documentation.
               + Runs on Sun, VMS VAX, Macintosh, PC, and others.
               + Portable C source code distributed under GNU licence.
               + Comprehensive user's manual including tutorial.
               + Programming-language independent.
               + Can generate multiple output files.
               + Allows complete control over the output text.
               + Regression test suite with over 200 tests.
               + Fully worked example (in /pub/funnelweb/examples).
               - Requires TeX to produce typeset documentation.
               - Typesets program code using TT font only.
 
Support:
            No formal support available.  Mailing list maintained with
            about 50 subscribers.  Informal assistance available from
            mailing list.
 
- ----------------------------------------------------------------------
 
- FWEB:
-------
 
Developer:
            John A. Krommes
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX.
            Text formatters are plain TeX and LaTeX.
 
Availability:
            anonymous ftp from:
              lyman.pppl.gov/pub/fweb
              CTAN/web/fweb
              LPA/fweb
              DOS version in LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            It also has a well-developed user's manual and its own FAQ
            (see above). It runs on most platforms: VMS, PC, UNIX, and
            pretty much anything that the GNU C compiler (GCC) is
            supported for.
 
Support:
            bug reports to krommes@princeton.edu
 
- ----------------------------------------------------------------------
 
- noweb:
--------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            All programming languages, plain TeX and LaTeX formatters.
 
Availability:
            anonymous ftp from:
              csservices.princeton.edu/pub/noweb.shar.Z
              bellcore.com/pub/norman/noweb.shar.Z
              CTAN/web/independent/noweb
              LPA/independent
 
Readme:
            with bundle above
 
Brief description:
 
            noweb is designed to meet the needs of literate programmers
            while remaining as simple as possible.  Its primary
            advantages are simplicity, extensibility, and
            language-independence.  noweb uses 5 control sequences to
            WEB's 27.  noweb now supports indexing and identifier
            cross-reference.  The simple noweb manual is only 2 pages;
            documenting the full power of noweave and notangle requires
            another 3 pages.  noweb works ``out of the box'' with any
            programming language, and its formatter-dependent part is a
            60-line nawk program. The primary sacrifice relative to WEB
            is the loss of prettyprinting.
 
Support:
            by email to the author
 
- ----------------------------------------------------------------------
 
- NUWEB:
--------
 
Developer:
            Preston Briggs: preston@cs.rice.edu
 
Systems supported:
            Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS.
 
Software supported:
            It's written in C.  It works with any programming language
            (or combination of programming languages) and uses Latex as
            its text formatter.
 
Availability:
            anonymous ftp from:
              Unix: CTAN/web/nuweb
              DOS:  CTAN/web/nuweb-pc
              LPA/independent
 
Readme:
            Send mail to preston@cs.rice.edu
 
Brief description:
 
            A single program that takes a web file written in a
            combination of latex and any programming language(s) and
            produces a latex file that can be pretty printed and a set
            of files containing code for compilation/interpretation by
            the appropriate language processors.
 
            Strengths include speed, simplicity, multiple languages,
            nice indices and cross-references, latex.  Doesn't require
            any special macros or macro files.
 
            Drawbacks: latex-dependent, no code pretty printing, harder
            to make indices than cweb.
 
            More good stuff: nice support for make, doesn't reformat
            source files, so they're easy to debug.  Lots of control
            without too much effort.  That is, it doesn't do too much!
 
            Future directions... Very little change planned, except
            perhaps refinements in the indexing software.
 
Support:
            Hack it yourself or send e-mail to preston@cs.rice.edu
 
- ----------------------------------------------------------------------
 
- SchemeWEB:
------------
 
Developer:
            John D. Ramsdell
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Programming language: Any dialect of Lisp.
            Text formatter: LaTeX.
 
Availability:
            The Unix version is in the Scheme Repository and it is
            available via anonymous ftp from:
              nexus.yorku.ca/pub/scheme/utl
              LPA/lisp
 
            The DOS version is part of the PCS/Geneva Scheme system
            which is available via anonymous ftp from:
              cui.unige.ch/pub/pcs.
              LPA/machines/ms-dos
 
Readme:
            In bundle with above.
 
Brief description:
            SchemeWEB is a Unix or DOS filter that translates
            SchemeWEB source into LaTeX source or Lisp source.
            Lisp code is formatted in typewriter type font and
            the comments are passed to LaTeX unchanged.
 
Support:
            Send bug reports to ramsdell@mitre.org.
 
- ----------------------------------------------------------------------
 
- Spidery WEB:
-------------
 
Developer:
            Norman Ramsey <norman@bellcore.com>
 
System(s) supported:
            Unix and DOS platforms
 
Software supported:
            Most Algol-like languages, including C, Ada, Pascal, Awk,
            and many others.  Plain TeX and latex for text formatters.
 
Availability:
            Anonymous ftp from:
                CTAN
 
Readme:
            In distribution.
 
Brief description:
            A system for building language-dependent WEBs. Spider is
            frozen; no further development is planned.
 
Support:
            Bug reports to author.
 
- ----------------------------------------------------------------------
 
- WinWordWEB:
-------------
 
Developer:
            Lee Wittenberg <leew@pilot.njin.net>
 
Systems supported:
            Needs Microsoft Word for Windows, v.2.x, and, of course,
            MS-Windows 3.x.
 
Software supported:
            Any programming language.  Word for Windows 2.x for text
            formatting and file maintenance.
 
Availability:
            anonymous ftp from:
              bart.kean.edu:pub/leew
            World-Wide Web (WWW)
 
Readme:
            WORDWEB.DOC in the downloadable package describes the
            system.
 
Brief description:
            WinWordWEB is a set of a Word for Windows macros (plus a
            paragraph style) that provide a crude literate programming
            environment.  The ``look and feel'' of the system is based
            on Norman Ramsey's noweb, but can easily be modified to suit
            individual tastes.
 
Support:
            None.  WinWordWEB was written as a prototype to see if a
            WYSIWYG literate programming system was possible.  It is
            intended as a jumping off point for future work by others.
            However, the system is surprisingly usable as it stands, and
            the author is interested in hearing from users (satisfied
            and unsatisfied).
 
            Anyone interested in actively supporting (and improving) the
            product should contact the author via email.
 
* Other resources:
------------------
 
An untapped resource (by me anyway ;-) is the World Wide Web.  Marcus
Speh has expended considerable effort in this regard.  If you're
connected to WWW, then access:
 
  http://info.desy.de/user/projects/LitProg.html
 
If you aren't connected to WWW, telnet to info.cern.ch and explore.
You can reach Marcus' literate programming pages by typing:
 
  go http://info.desy.de/user/projects/LitProg.html
 
Help for people who have only Email and neither WWW nor telnet, can be
obtained by Email from LISTSERV@INFO.CERN.CH by sending a message
containing the command HELP.  Instructions will be returned by email.
For literate programming documents, you can try anonymous ftp to
ftp.desy.de [131.169.10.115] and attach to directory:
 
  /pub/userWWW/projects/Announce
 
Another resource of interest to literate programmers is the info-tex
mailing list.  If you're using (La)TeX as your typsetting system and
have access to internet, then you should investigate this mailing list.
Mail list service is available through the SHSU list-server.  To
subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET),
and include in the message one line of text:
 
    SUBSCRIBE INFO-TEX "your name in quotes"
 
The list is unmoderated; messages sent to info-tex@shsu.edu are
automatically distributed to all subscribers and cross-posted to
comp.text.tex.
 
Archives of the mailing list and newsgroup are maintained on
niord.shsu.edu [192.92.115.8] in the directory info-tex.
 
- ----------------------------------------------------------------------
 
- Virtual Coursework:
---------------------
 
Marcus Speh plans an introductory course on Literate Programming on the
Internet, part of the first semester of "Global Network Academy" [GNA],
a non-profit corporation incorporated in the state of Texas, affilated
with the Usenet University project. The texts/sample programs for this
class will be made available via anonymous FTP. A special room on GNA
Virtual Campus will be staffed by a consultant in one to two hour
shifts.  Students with questions can telnet to the virtual campus and
ask questions of the staff there. Tuition: Students should agree to work
for Global Network Academy in some capacity. This may include agreeing
to serve as a consultant next term, donating computing resources which
belong to them, helping with programming, etc. If you are interested in
registering for the course either as a student or as a consultant,
please contact marcus@x4u.desy.de. You will receive a standard reply
message; no further action will be taken until January 94.
 
[Editor's note: Because of workload, Marcus requests that email
inquiries be limited to a statement of interest for either a student or
consultant position until January 1994.]
 
* Code Examples:
----------------
 
Examples of web programs are included with the FWEB, CWEB, and noweb
distributions.
 
Cameron Smith converted the K&R calculator program into a literate
program.   It can be retrieved by anonymous ftp from:
  niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as
    krcwsamp.zip
  or from
    LPA/Documentation
 
Ross Williams has released a funnelweb example.  You can retrieve this
file from node ftp.adelaide.edu.au [129.127.40.3] as
  /pub/funnelweb/examples/except.*
This file should be on CTAN as well.
 
* Bibliographies:
-----------------
 
Nelson Beebe has collected an extensive bibliography treating literate
programming.  His work is available for anonymous ftp from
ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files:
    litprog.bib
    litprog.ltx.
Although I have not verified this, LPA is an alternate source for these
files.  Note that they are updated frequently (Nelson says several times
each week), so be sure to get a fresh copy before extensive use.
Joachim Schrod indicates that these files may be updated daily and can
be retrieved via anonymous ftp at LPA/documentation.
 
* How to anonymously ftp:
-------------------------
 
Pretty much everything mentioned here is available by anonymous FTP.
FAQ lists cross-posted to news.answers and rec.answers can be gotten
from rtfm.mit.edu [18.70.0.209], under /pub/usenet/news.answers or under
/pub/usenet/more.specific.group.name
 
"anonymous FTP" is just a way for files to be stored where anyone
can retrieve them over the Net.    For example, to retrieve the
latest version of the literate programming FAQ, do the following:
 
> ftp rtfm.mit.edu              /* connect to the site; message follows */
> anonymous                     /* type this when it asks for your name */
> <your email address>          /* type your address as the password    */
> cd /pub/usenet                /* go to the directory you want to be   */
> cd comp.programming.literate  /* one level down (no slash).           */
> dir                           /* look at what's there                 */
> get literate-progamming-faq   /* get the file; case-sensitive         */
> quit                          /* stop this mysterious thing           */
 
If your FTP program complains that it doesn't know where the site you
want to use is, type the numerical address instead of the sitename:
 
> ftp 18.70.0.209               /* connect with numerical address */
 
If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu
with the single word "help" in the body of the message.
 
Getting binary files (executables, or any compressed files) is only
slightly more difficult.   You need to set binary mode inside FTP before
you transfer the file.
 
> binary            /* set binary transfer mode  */
> ascii             /* set back to text transfer mode */
 
FAQs and spoiler lists are generally ascii files; everything else is
generally binary files.
 
Some common extensions on binary files in archive sites are:
 
  .Z           Compressed; extract with uncompress
  .tar.Z       Compressed 'tape archive'; uncompress then untar or tar -xvf
  .gz or .z    Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu)
  .sit         (Mac) StufIt archive
  .zip         Extract with Zip or Unzip
  .zoo         Yet another archive/compress program
  .lhe         (Amiga) ?
  .lzh         Lha archive program.
  .arj         (PC) Arj archive program.
  .exe         (PC) Sometimes self-extracting archives-just execute them.
  .uue or .UUE Transfer as text file; use uudecode to convert to binary
  .hqx         (Mac) BinHex format; transfer in text mode
 
Generic help can be found in the FAQs of comp.binaries.<your_system_type>
for how to transfer, extract, and virus-check binary files.  (At
rtfm.mit.edu)
 
If you can't FTP from your site, use one of the following ftp-by-mail
servers:
 
  ftpmail@decwrl.dec.com
  ftpmail@src.doc.ic.ac.uk
  ftpmail@cs.uow.edu.au
  ftpmail@grasp.insa-lyon.fr
 
For complete instructions, send a message reading "help" to the server.
 
If you don't know exactly what you're looking for, or exactly where it
is, there are programs and servers that can help you.  For more info,
send e-mail to mail-server@rtfm.mit.with with the body of the
message reading send usenet/news.answers/finding-sources
 
Thanks to Aliza R. Panitz (the "buglady") for this text.  I copied it
verbatim from her post on faq-maintainers with only minor modifications.
 
* Acknowledgements:
-------------------
 
This document would not have happened without the help of many people.
Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim
Schrod, Piet van Oostrum, and Ross N. Williams.  A special thanks to
Aliza R. Panitz for the text describing how to execute an anonymous ftp
for files of interest.
 
Any omissions from these acknowledgements should be considered an act of
stupidity on my part.  Of course, the authors of literate programming
tools mentioned above all play a vital role in the vitality of literate
programming. Furthermore, participants in the comp.programming.literate
newsgroup (and associated mailing list) all contributed in various
fashions. Thank all of you.
 
* End notes:
------------
 
This document will be evolving over the next few months.  I'm planning
on adding entries for additional literate programming tools and will
expand the sections on examples as more examples become available. Tools
I will include are web (the original pascal version), funnelweb,
spiderweb, and cnoweb for starters. Others will be added as I find and
document them.  Omission of a particular tool should not be considered a
snub in any sense--simply an error or oversight on my part.
 
History:
 
  First release: Fri 10/15/1993 -- Yep, I finally did it!
  Thu 10/21/93 -- Minor change to ftp instructions.
  Fri 10/22/93 -- Minor change to stuttgart ip and fweb.faq version.
                  Made reader-recommended changes, lots of re-
                  organization, and added a few tools.
  Mon 11/01/93 -- Corrected typo in address.
  Thu 11/11/93 -- Minor change to www.
 
From schrod@iti.informatik.th-darmstadt.de Thu Dec 23 17:51:09 EST 1993
Date: Thu, 23 Dec 93 17:51:09 EST
From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod)
Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE
To: LitProg@SHSU.EDU
Subject: Contents of the LitProg Archive (monthly posting)
 
# literate-programming/Contents			20 Dec 93  -*- Indented-Text -*-
#------------------------------------------------------------
 
The material available from the Literate Programming Archive is
categorized, each category is put in a directory tree. While this
structure (which is described in the README files) supports browsing,
the need for quick access to a specific Literate Programming tool
remains.
 
This file shall assist you in this need. It presents the *WEB systems
and tools available, in an alphabetic order, and names the directory
where you can find it.
    In addition to the systems mentioned below, the LitProg Archive
features texts in the directory Documentation: FAQs, papers, and an
extensive bibliography in BibTeX format.
 
Since this file is updated manually, I cannot guarantee that it's up
to date. Send reports about inconsistencies of description and reality
to Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>.
 
SYSTEM		    DIRECTORY			REMARK
------		    ---------			------
APLWEB		    apl				w/o source, but under the GPL!
					[this was an error by the author]
AWEB		    ada/aweb			not supported any more
cfa		    Tools			Change File Analyzer
CLiP						any language, any formatter, any
 -- for DOS	    machines/ms-dos		    wordprocessor. Hypertext
 -- for VMS	    machines/vms		    integration possible
cnoweb		    c.c++
CWEB (Levy/Knuth)				C++, ANSI C, K&R C
 -- source	    c.c++
 -- DOS port	    machines/ms-dos
 -- Mac port	    machines/mac/cweb		only CTANGLE
cweb style	    c.c++			CWEB programs as LaTeX documents
CWEB (van Leeuwen)  c.c++			CWEB for ANSI C, in ANSI C
CWEB (Schrod)	    <not available>		not supported any more
						send me mail if you have
						historic interests :-)
Funnelweb	    independent
FWEB						multi-lingual WEB
 -- source	    fweb
 -- DOS port	    machines/ms-dos
Knit		    pascal			not supported any more
lit2x		    independent			[????] from Glasgow
LPW		    machines/mac		Literate Programming Workshop
						CAVEAT: Shareware!
MapleWEB	    maple			[SpiderWEB?]
MWEB (Schrod/Detig) modula-2			not supported any more
MWEB (Sewell)	    modula-2			not supported any more
noweb		    				uses the UNIX toolbox paradigm
 -- source	    independent
 -- DOS port	    machines/ms-dos
ProTex		    independent			WEB system based on TeX
RWEB		    reduce			[SpiderWEB?]
SpiderWEB					WEB generator, in awk
 -- source	    spiderweb
 -- DOS port	    machines/ms-dos
 -- OS/2 port	    machines/os2
 -- Mac port	    machines/mac
TIE		    Tools			Change File Merger
WEB		    				The basis, it started with it...
 -- source	    pascal
 -- DOS port	    machines/ms-dos
WEB mode	    Tools			for GNU Emacs
WinWordWEB	    machines/ms-dos		WEB with Word for Windows
 
Systems without support of refinements
--------------------------------------
 
MAKEPROG	    independent			is here for my own convenience
						:-)
SchemeWEB	    lisp
 
--
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Joachim Schrod			Email: schrod@iti.informatik.th-darmstadt.de
Literate Programming Archive, maintainer
Technical University of Darmstadt, Germany
 
From Kayvan Fri Dec 31 18:10 PST 1993
Date: Fri, 31 Dec 93 18:10 PST
From: Kayvan Sylvan <kayvan@satyr.Sylvan.COM>
Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM
To: LitProg@SHSU.EDU
Subject: Whew... I'm back.
 
I've just read about 5 megabytes of litprog mail.
 
It's taken me a while to get back to LitProg, since work and family
matters got in the way.
 
With the perspective gained from reading 4 months of archives in a
couple of days, I have some thoughts to share. :-)
 
1. There's still too little sharing of real-world literate programs
   and techniques.
 
   I want to see more code being posted and more peer review going on.
   I don't really know whether the literate Perl, Prolog, C, C++, or
   Lisp code I write is good literate programming, because I haven't
   gotten too many comments other than "Wow. Cool. Looks nice." I
   suspect there are other literate programmers who are hungry for
   constructive criticism of their publications and I think that the
   LitProg mailinglist/newsgroup can be a forum for this.
 
2. Along the same lines as #1, I want to see a document that is a set
   of style guidelines or useful suggestions for literate programming.
   There has been talk along this line at various times, but no one
   has stepped forward to coordinate this.
 
   This document would answer general literate programming questions
   like "How do I structure my C++ WEB to make the interface obvious
   for users of the contained classes but still document the
   implementation in a sensible way?" I'd be willing to collect bits
   of advice and/or guidelines and compile it into a LitProg
   suggestions document in my copious spare time.
 
It's good to be "back" (I never really went anywhere, but it feels
like I'm returning).
 
Happy New Year to all!!!
 
			---Kayvan
 
| Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407  |
| Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems  |
| "Think Globally, Act Locally." "Only you can make your dreams come true."  |
| Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |
