| From: | Frank Pappas |
| Date: | 24 Feb 1993 |
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 am 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 am 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 am 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.
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 would 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.
| From: | Joachim Schrod |
| Date: | 25 Feb 1993 |
Is this system freely distributable? May you point us to a location where to get it from?
Hmm, there is already an AWEB, written by U. Schweigert. I am posting retrieval info RSN.
| From: | Frank Pappas |
| Date: | 26 Feb 1993 |
Joachim Schrod writes: 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 am 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.
Hmm, there is already an AWEB, written by U. Schweigert. I am posting retrieval info
RSN.
Yes, I am 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 am 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.