OS/2 Shareware BBS: 22 gnu/22-gnu.zip/fweb153.zip/READ_ME-1.5x

Text File | 1996-02-27 | 25KB | 605 lines

                             FWEB version 1.5x
                             September 22, 1995

  (See the BUGS list at the end of this file.)

  FWEB v1.5x (where 'x' is a number like '3') is available via
anonymous ftp from

        ftp.pppl.gov:/pub/fweb/fweb-1.5x.tar.Z

This release has three principal purposes:

        (1) It now supports LaTeX2e in native mode.

        (2) It adds support for templates and exceptions in C++.  It also
incorporates some miscellaneous and usually obscure bug fixes.  A few
convenience features have been added.

        (3) It provides executables for the IBM-PC that run in extended memory.


  To unpack the release,

        uncompress fweb-1.5x.tar
        tar -xvf fweb-1.5x.tar

This creates the directory fweb-1.5x with the four subdirectories boot,
demos, manual, and web:

        boot   --- Presently almost entirely useless; ignore it.
        demos  --- Presently empty.
        manual --- Documentation, style files, etc.
        web    --- *.c and *.h files for installation; source code.

  Major points to note with this release are:

        * For detailed installation instructions, see the READ_ME.FWEB file
in the top-level directory of the release.

        * Version 1.5x has been developed and tested only using the gcc
compiler on a Sun SPARCstation.  The extensive testing on other platforms
that was done with previous releases has not yet been done because of lack
of time.  Hence, this release is primarily intended for people with a
standard Unix environment and an ANSI-compliant C compiler.  You must use
`./configure' to create the make files; see READ_ME.FWEB.  As time permits,
executable binaries for various personal computers may be provided, but
this will not be for (at least) several months.  In particular, ports to
OS/2 and MS-DOS are in the works.  I presently do not have the resources to
develop on the Mac.

        * Further FWEB development will be done with LaTeX---LaTeX2e in
particular.  Although basic TeX pretty-printing may still be possible, some
features may not work, and no bugs relating to Plain TeX will be
addressed.

        * Hence, the default processor that works in conjunction with
fweave is now LaTeX (`-PL' option), not TeX (`-PT').

        * The experimental macro package fwebmacL.sty used for LaTeX
support with v1.40 is now the default, hence called fwebmac.sty.  Eliminate
any reference to fwebmacL.sty in your .fweb file, scripts, etc.

        * Only the texinfo version of the manual is supplied.  You should
install this online; however, a postscript version of the manual is also
supplied.

        * No demos are provided with this release, since they have not yet
been tested for this version and also need to be updated.


                     RELATIVELY MINOR CHANGES (v1.53)

V1.53 fixes a relatively small number of obscure bugs in v1.52--beta; for a
discussion, see the BUGS list at the end of this file.  A few enhancements
were also made.  They include:

* Sections can be numbered by consecutive integers rather than LaTeX's
default Dewey-decimal form by saying

        LaTeX.package = "fwebnum"

* The `-H' option (experimental and incomplete) was added.  For C and C++,
this option tells fweave to scan `#include' files for `typedef' and/or
`class' definitions.

* The `-k' option was added.  This tells Fortran and Ratfor to understand
the lower-case forms of I/O keywords such as `iostat' (with the exception
of `read', `write', and `end').

* The `-n:' option was added.  This tells Fortran to place statement labels
on a separate line, which is useful when the labels are relatively long.
(By default, Fortran labels are placed on the same line as the thing they
are labeling, which looks good for short labels.)

* The preprocessor command `@#line' was added.  For C code, this adds an
explicit `#line' command to the tangled output file.  This helps to keep
the line numbers between debugger and source file in sync when an FWEB
preprocessor statement expands to several lines.

  An implicit `@#line' command is added after each `@%' that begins a line
(this keeps line numbering correct).  To override this, use the option `-T#'.

* `-p' (style-file) options on the command line are now processed AFTER the
local style file.

* The functionality of the `-D' command was enhanced to include optional
arguments that limit the information that will be listed.


                     RELATIVELY MINOR CHANGES (v1.52)

* fwebmac.sty was enhanced to warn to run LaTeX again when the section
numbering hasn't yet been brought up to date.  I'm not sure I've covered
all the bases, but before it didn't complain at all.

* C++ classes are now formatted (identified as reserved words) on the first
pass, so forward references such as

        @ The class |C|...
        @a
        class C
          {}

will now work.  Note that |typedef| has done this for a while, although
there are still a few glitches.

* For two years, the documentation has described two control codes as
follows:

        @~ --- inhibit line break.
        @+ --- force an index entry.

Apparently the code had these definitions inverted; it has now been brought
up to date with the documentation.  Fortunately these commands are
evidently not heavily used, since no one complained.

* fwebmac.sty was further reworked to interact properly with the user
package multicol.sty.  If in fweb.sty you say `LaTeX.package "multicol"',
then the two-column index is done with multicol; this gives various
improvements over the \twocolumn that was previously used.  Furthermore, it's
possible to use multicol to do your entire document in two-column format.
This turned out to be relatively simple, but one needs to get the commands
in the proper order.  See the Info documentation, menu item `Index', for
more details.  Two-column format substantially cuts down the white space; I
saved about 50% on a 200-page code.

  One known glitch with FWEB/multicol is that if one selects page-number
cross-references instead of LaTeX section numbers, page references such
as 98c don't get the 'c' correct.  Presumably not a big deal.  At this
point, assume that the use of multicol is highly experimental.

* Further bugs in the C and C++ production rules were fixed.


                         RELATIVELY MINOR CHANGES (v1.50)

* People justifiably complained about one aspect of the section numbering
scheme for the new LaTeX look.  Namely, if any section had a maximum depth
of, say, 3 (e.g., it contained a command `@*2'), then under v1.40 the
unnamed code within any major section was numbered like `4.0.0.1' even if
section 4 had a depth of just 1.  This has now been changed; one now gets
`4.1' instead of `4.0.0.1'.

  The fwebmac.sty code that accomplishes this is both very new and very
tedious.  If it doesn't work, all is not lost; one can turn it off by
saying `\stripzerosfalse'.

* The syntax for entries in the initialization file .fweb has been modified
(in a way that is as backward-compatible as possible).  Previously, '+'
meant process the option before the command-line options, '-' meant process
it after.  This convention was somewhat hard to remember, given the
statement that any command-line option could be put into .fweb;
furthermore, just about everything in .fweb should, in fact, be processed
before the command-line options.  So now both '+' and '-' mean the same
thing, namely process before (and the '+' notation should fade away as time
goes on).  If you explicitly want something to be processed after all
command-line options for some tricky reason, begin it with '&'.  I.e., scan
your .fweb file for any line beginning with '-' and replace that with '&'.

* The LaTeX processor (`-PL' option) is now the default, rather than `-PT'
for Plain TeX.

* The experimental fwebmacL.sty macro package released with v1.40 has been
substantially reworked and is now the default, fwebmac.sty.

* Support for LaTeX2e was added to fwebmac.sty.  Essentially, this means
that the \documentclass and \usepackage commands are used instead of
\documentstyle.  The following fweb style-file options were added to
support those commands:

        LaTeX.class.options
        LaTeX.class
        LaTeX.package.options
        LaTeX.package
        doc.preamble

The beginning of the file output by fweave looks like the following, where
<parameter> means the contents of the style-file string called `parameter':

        \input fwebmac.sty
        \Wbegin{many obscure arguments}
        <limbo.begin> % <limbo> also works.
        Optional TeX commands copied from user's limbo section
        <limbo.end>

The \Wbegin command essentially does the following:

        \documentclass[<LaTeX.class.options>]{<LaTeX.class>}
        \usepackage[<LaTeX.package.options>]{<LaTeX.package>}
        <doc.preamble>
        \begin{document}

For precise information about how \Wbegin works, see fwebmac.web.  If you
feel that macro absolutely needs to be changed, please inform the
developer.

* The style-file parameter `index.name' was added.  This is the
section name to be given to the index, which should be the last major
(starred) section.  It becomes the contents of the macro `\INDEX'.
Therefore, one can end one's source file by saying

        @* \INDEX.

* The `$IF...' class of built-in functions was reworked.  They should now
be more robust, recursive, and intuitive.  Simple uses of these functions
should work as before.  However, complicated uses that depended on tricky
things about the order of expansion of arguments may require revision.
Carefully compare the descriptions of these functions in the documentation
with your usage of them in any pre-existing code.  In some cases, if a
previous constructions using $IF no longer works, it might work if you say

        @m $IF(a,b,c) $$IF(a,b,c)

and then use `$$IF' in your code.  (This forces an extra level of macro
expansion.)  The same remark goes for `$DEFINE'.

The old forms `_IF' etc. no longer work; convert to `$IF'.

* The option `-j' was added.  This inhibits multiple inclusions via @i of
the same include file.

* One now has the ability to change the comment character that begins
ftangle's line command.  In the style file, say, e.g.,

        line_char.N '#'

to change the default `*line' output by ftangle in Fortran mode to `#line'.
This could be useful if one runs the C preprocessor on the tangled Fortran
output.

* fweave's processing of |typedef| statements in C and C++ was improved.

* FWEB should now be able to process C++ templates and exception handling,
at least in simple situations.  The typesetting of C++ references (e.g.,
`int&') was also improved. Please report any difficulties.

* There were various miscellaneous obscure bug fixes.


                          MAJOR FEATURES (v1.40)

* Beginning with v1.40, documentation is now written in texinfo format.
Only this documentation will be supplied in the future.  For a summary of
the features new with versions 1.40 and 1.50, see the info menu item `New
features'.

* Versions of FWEB prior to 1.40 did not work entirely gracefully with LaTeX, i
n
that LaTeX's \output routine was usurped by FWEB.  That is no longer the
case; LaTeX's \output routine is now used, as are its sectioning and
table-of-contents commands.  Things like footnotes should now work.

When using LaTeX, the appearance of FWEAVE's output will be noticably
different from the Plain TeX output from v1.30 and before.  In particular,
it is supposed to look more `book-like' in appearance.  Sections are no
longer numbered at the beginning of the TeX part, but rather when the code
part (if any) begins.  Section numbering will be LaTeX's---e.g., 13.1.5,
and this will be reflected in the index and other cross-reference
information.

  There are several difficulties with the LaTeX support:

        (1) After an editing change LaTeX may not warn that section
numbering is out of date.  If in doubt, or if question marks appear in
place of section numbers, or if the table of contents is incomplete, rerun
LaTex.  It may initially require three passes to get everything consistent.

        (2) See the discussion of \INDEX under the remarks for v1.50.

* Version 1.40 featured the beginnings of some work on language
independence.  In principle, it is now possible to weave and tangle
sections of code literally (verbatim) instead of using FWEAVE's
pretty-printing and FTANGLE's blank suppression.  One is supposed to be
able to do this both for compiler languages like Fortran or C that FWEAVE
can pretty-print, as well as for any other language (makefiles, etc.) whose
syntax FWEB does not understand.  It is certain that these features have
not yet been fully or entirely correctly implemented, although v1.50
incorporates some bug fixes.  The general mechanism is complex, as it must
interact smoothly with FTANGLE's macro preprocessor and other such
features.  I STRONGLY RECOMMEND THAT NOBODY BEGIN A LARGE-SCALE PROGRAMMING
PROJECT USING THESE NEW LANGUAGE-INDEPENDENT FEATURES.  That said, I hope
people will try it out so problems can be identified and fixed.

  There are two ways of obtaining language independence: a
language-independent `mode' (the `N mode') that can be used even for
languages such as Fortran, and a `verbatim language'.  The verbatim
language is the stronger of the two; it turns on the language-independent
mode.  The two concepts are closely related, and in some applications they
will function identically.

  If you are, say, a Fortran programmer but merely want to turn off
pretty-printing, you should use the N mode.  This is done by using the
command-line option `-N'.  (Case is significant; `-n' means something
entirely different.)  FWEAVE will just print your source in a verbatim
environment, and will continue to do indexing as usual; FTANGLE will copy
the source literally to the output file, say test.f.

  If you are using FWEB to document a language different than the supported
ones of C, C++, Fortran, Ratfor, and TeX, then you should select the
verbatim language by means of the language command `@Lv' (replacing
something like `@c', `@n', or `@Lx').  FWEAVE will again print your source
in a verbatim environment, and FTANGLE will copy it to the output file
test.mk.  (The `.mk' extension can be changed in the style file.)

  The N mode and the verbatim language are supposed to obey the usual
scoping and inheritance rules (modules inherit the features of their
ancestors), so that mixed-language programming still works correctly.
There are probably some difficulties here, however.

  Cross-referencing is turned off under `@Lv'.  However, FWEAVE still
recognizes identifiers according to FWEB's rules.  This does not always
make sense, and in the future a mechanism should be provided for modifying
those rules.  (This is tricky because of built-in functions, WEB macros,
etc.)  In any event, an index entry for FWEB's current understanding of an
identifier can be forced by means of the `@+' command.

  Sharp-eyed users will note that prior to v1.40 `@+' used to mean something
else---namely, it prevented a line break, as in `x; @+ y;'.  That role is
now played by `@~' (which, if you think of TeX, should be easier to
remember).  I regret making this change, but the new usage is now symmetric
with the `@-' command, which means delete an index entry.  Incidently,
another change that was made in the last version, namely replacing the
compiler directive command `@!' by `@?', now becomes more crucial since
`@!' is now used to suppress expansion of a WEB macro or built-in function.
(This is sometimes particular necessary in the language-independent modes.)
In summary, five important control codes in versions beginning with 1.40 are

        @? --- compiler directive
        @~ --- suppress line break
        @! --- suppress macro expansion of next identifier
        @- --- suppress index entry for next identifier
        @+ --- force index entry for next identifier

It is expected that these control codes will remain stable.


                         RELATIVELY MINOR CHANGES (v1.40)

* Beginning with v1.40, built-in functions such as $PI now begin with '$',
not '_'.  For example, you should say `$EVAL(1+2)', not `_EVAL(1+2)'.  The
underscore convention was a poor design decision that introduced conflicts
with ANSI C in certain cases.  Existing codes will still work, as FWEB
currently understands both conventions.  One can therefore say things like
`@#undef _EVAL' (retaining the functionality of $EVAL).  However, THE
UNDERSCORE CONVENTION WILL GO AWAY IN A FUTURE RELEASE.  Please eliminate
any calls to built-in functions beginning with underscores in present
codes.

* When the `-F' option is used, FTANGLE will write its output to temporary
files and compare the results to the last version in the directory, if any.
The file is updated only if a difference is found.  This prevents make
files from recompiling source if only the documentation was changed.  This
feature was not entirely trivial to make portable, so please report any
difficulties.

* A new flag `-n)' (reverse Fortran indices) has been added.  This may be
very useful for advanced Fortran programming; see fweb.info for its
description.

* The ./configure automatic configuration script has been improved, and should
lead to easy installation on many systems.  Please report any difficulties
you have with using this script.


                                   BUGS
                               Version 1.53

* (October 19, 1995):  For FTANGLE's macro processor, when a stringize
operation begins a line, as in

-------------------------------------------------------------------------------
@m A(name)
        #name
-------------------------------------------------------------------------------

it does not expand the `#name'.  A kludge is to put the pseudo-expression
`@e' before the `#name', as in

-------------------------------------------------------------------------------
@m A(name)
        @e#name
-------------------------------------------------------------------------------
=

Of course, in this simple example, it would be more sensible to just put
everything on one line:  `@m A(name) #name'.

* (October 16, 1995):  In C++, the construction `operator ^' creates bad
LaTeX code in the Index.  To fix, apply the following change files:

-------------------------------------------------------------------------------
--- fweave-1.53.ch ---

Changes \^ to \Caret.  (See also fwebmac-1.53.ch.)
JAK 10/16/95

@x
 INIT_OP(@'^',"CARET",ALL_LANGUAGES,"\\^",binop); // `|x^y|'
@y
 INIT_OP(@'^',"CARET",ALL_LANGUAGES,"\\Caret",binop); // `|x^y|'
@z

-------------------------------------------------------------------------------
--- fwebmac-1.53.ch ---

Adds \Caret.  (See also fweave-1.53.ch.)
JAK 10/16/95

@x
\def\AT!{@@}% Knuth's abbreviation for the at sign for control text: '\AT!'
@y
\let\Caret\^
\def\AT!{@@}% Knuth's abbreviation for the at sign for control text: '\AT!'
@z
-------------------------------------------------------------------------------

* (October 2, 1995):  With FWEAVE, template constructions of the form

-------------------------------------------------------------------------------
@c++

@

@% @f c0 int
@% @f c1 int

@a
class A
{
static c0<c1, A*> test;
}
-------------------------------------------------------------------------------

generate an infinite production loop---the infamous ``rule 591''.  This can
be avoided by uncommenting the @f statements in the above, although the
result may not format optimally.

* (October 2, 1995):  There's some weird behavior with installing FWEB on
the RS-6000.  See a message in /pub/fweb/archive/fweb-installers.archive.

* (October 2, 1995):  Tangling the Fortran file

-------------------------------------------------------------------------------
@n/

@
@a
        x // BUG
 /* Test */
        y
-------------------------------------------------------------------------------

doesn't put the `y' on a separate line.  It works OK if one uses the long
form of the comment---i.e., `/* NOBUG */'.

* (September 29, 1995):  The behavior of the `-D' option doesn't quite
match the documentation.  For example, if you say `-c -Dexit', it doesn't
report that `exit' is an intrinsic function.  It will do so if you say
`-c -D[i]exit'.

        (FIXED for v1.54.)

                                   BUGS
                               Version 1.52

* (September 8, 1995):  When the `-v' option is not used, the tangled
output for a short comment (// ...) included an extra newline.  (FIXED for
v1.53.)

* (September 7, 1995):  When the @% command (invisible comment) is used,
the subsequent line numbering produced by FTANGLE was incorrect.  (FIXED
for v1.53.)

* (September 6, 1995):  FTANGLE didn't recognize `-i!'.  (FIXED for v1.53.)

* (August 10, 1995):  For multiple-language programming, section-number
comments were sometimes output to the wrong file.  A workaround is to use
the -# option.  (v1.52-beta; FIXED for v1.53.)

* (July 27, 1995):  For fweave, if an @I command is encountered in the
limbo section, the -i option does not work properly (it spuriously
suppresses important output).  A workaround is to put at least one section
before the @I, as in

-----------------
@c
@* INTRODUCTION.
@I test.hweb
-----------------

* (July 1, 1995): An egregious error in fweave may clobber the heap on some
systems, particularly personal computers.  Apply the following change file
(incorporated into v1.53):

-------------------------------------------------------------------------------
common.ch
July 1, 1995
To use:
        ftangle -A -# --v --F common common
        make fweave

@x
SRTN mfree(VOID)
{
if(!mod_names) return; // For errors happening during the command line.

for(--next_mod_name; next_mod_name >= mod_names; next_mod_name--)
        FREE(*next_mod_name);
}
@y
SRTN mfree(VOID)
{
if(!mod_names) return; // For errors happening during the command line.

while(next_mod_name > mod_names)
        FREE(*(--next_mod_name));
}
@z
-------------------------------------------------------------------------------

* (July 1, 1995):  The web/Makefile should, but does not, install
fweb.info-6.  (v1.52-beta; FIXED for v1.53.)

* (June 13, 1995):  In fweb-1.52/manual/fwebmac.web,

change
        \global\let\*=\lapstar
to
        \global\let\*=\W@@lapstar
then
        ftangle -# -v fwebmac

(FIXED for v1.53.)

* Effectively, only LaTeX2e is now supported with FWEAVE.  Most codes
should still work with TeX or LaTeX 2.09, but some advanced features are
known to not work with the latter two, and in general testing of
fwebmac.sty is now done only with LaTeX2e.  For example,

        - Code mode (stuff between vertical bars) may be used in the names
of starred sections for LaTeX2e, but possibly not for TeX or LaTeX.

* The command `@N' is not yet entirely robust; try not to use it.  @Lv is
more robust, but don't use that either unless you really must.

        - Do not use @N in limbo; use @Lv instead.

        - If you must use @N to locally inhibit pretty-printing, use it
immediately before the @a or module name beginning the code part.  If you
use it elsewhere in the TeX part and there are embedded shifts into code
mode (|...|), FWEAVE will not deal with those correctly.

        - Ratfor (@r) doesn't yet coexist with @N.

        -  ASCII characters whose values are > 127 do not presently coexist
with @N or @Lv.

        - I'm strongly tempted to remove the @N command.

* -W[ sometimes can't process subscripts that consist of complicated/lengthy
expressions.

* FWEAVE will not typeset various Fortran--90 constructions correctly; the
rules have been little tested.  Also, various features of Fortran--90 were
deduced from a DRAFT of the ANSI design; as it turns out, some things, such
as the token /= instead of <> for .NE., were changed in the final version.
Please report difficulties by submitting (very short) examples.

* The parsing algorithm used for C and C++ (inherited from the original
CWEB) is really not up to the job.  Its virtue is that it's fast, but
something more recursive is really called for.  The present one sometimes
can't distinguish similar-looking constructions that are syntactically
quite different.  The changes required are fundamental; not minor tweaking.
So they won't happen soon; perhaps never.

* In C, the statement `|typedef int A, B;|' doesn't format |B| on the first
pass, so forward references to |B| won't format correctly.

* The built-in function $P doesn't format well.

* The core FWEB header file `typedefs.web' can't be woven satisfactorily.
(Problems with the verbatim mode.)  Nevertheless, this file demonstrates
some useful techniques.