In case you are using emacs, this is a -*- text -*- file.
Documentation for FunnelWeb 3.05AC
10th October, 1995.
Anthony B. Coates
Department of Physics
The University of Queensland
QLD 4072
Australia
coates@physics.uq.edu.au
This document lists the features which I [ABC] have added to Ross
Williams' FunnelWeb v3.0 in developing FunnelWeb 3.05AC. Although
Ross does not want bogus copies of FunnelWeb to be distributed, for
the very good reason that existing FunnelWeb code should not break
because someone unknowingly installs an improperly modified version of
the program, he has allowed me to distribute FunnelWeb 3.05AC freely.
However, note that while the features of FunnelWeb 3.05AC may appear
in the next official release of FunnelWeb, there is no guarantee that
they will, as this will be up to Ross Williams to decide.
Note too that when my version of FunnelWeb is run, it automatically
prints out a message pointing out that it is not FunnelWeb v3.0.
Please do not remove or change this message without my express
permission [ABC].
****ATTENTION****
FunnelWeb is currently written using K&R C. This means that it can be
compiled by both old-style K&R C compilers and new-style ANSI/ISO C
compilers, but not (as C++) by C++ compilers, as C++ uses the ANSI/ISO
syntax. In future releases, FunnelWeb AC may change from K&R to
ANSI/ISO syntax. This is because the number of people who wish to
compile FunnelWeb using a C++ compiler will probably outnumber those
who wish to use a K&R C compiler. However, if you have a strong
opinion as to whether FunnelWeb should be written in K&R or ANSI/ISO
C, send an email message to coates@physics.uq.edu.au, so that users'
opinions can be gauged.
****ATTENTION****
To avoid problems with existing FunnelWeb code breaking when processed
with FunnelWeb 3.05AC, new features are only enabled by the explicit
setting of pragmas. As such, this version of FunnelWeb should process
all existing sources without problems, and all product files,
including the documentation, should be exactly the same as produced by
FunnelWeb v3.0. The one exception to this is if the FunnelWeb
document contains macro names that begin with the hash character '#'.
This will be discussed later in this document.
Differences from FunnelWeb 3.0AC:
1. Fixed a serious bug in the HTML code generation
(the characters '<' and '>' should have been escaped in the
generated HTML documentation, but were not).
2. Added the concept of source code types. Currently, this is used
only to allow line directives to be generated in some product
files but not others.
3. Added the internal macro #timestamp to allow timestamping of
product files.
4. Added PC32 machine type for 32-bit DOS code (no 64K boundary
restrictions).
5. Added +Qb command line switch for true batch mode
(no interaction with the user is attempted if FunnelWeb
has to abort).
6. Mapping of files into memory changed to try and avoid problems
of differing EOL conventions when taking FunnelWeb sources from
one type of system to another (e.g. DOS to Unix).
Modifications:
1. Addition of OSF64, OS2, and LINUX machine types to environ.h,
machin.h, and machin.c. The OSF64 machine type is for a 64-bit
processor running the OSF/1.3 version of UNIX, such as a DEC
AXP (Alpha). The OS2 machine type is for a PC386/486 running OS/2
2.1. The code now checks for `PATH_MAX' before `FILENAME_MAX'
as the constant giving the maximum fully qualified filename
length for an operating system. This is to accomodate
Unix System V. The PC32 machine type has also been added for
32-bit DOS code.
2. Additions to `typesetter' pragma:
FunnelWeb v.3.0 supports the `@p typesetter = tex' pragma, which
allows (La)TeX expressions to be imbedded in the documentation
text without being escaped. Without this pragma, FunnelWeb
treats all documentation text as literal ASCII.
My version [ABC] of FunnelWeb also supports the additional
typesetter choices `@p typesetter = hypertext' and
`@p typesetter = html'. The `hypertext' option causes FunnelWeb
to output an HTML hypertext file rather than a TeX file. This
HTML file can be viewed using `Mosaic', and indeed `Mosaic' is
the only HTML viewer with which the HTML code produced by this
FunnelWeb 3.05AC has been tested. In `hypertext' mode, the
standard FunnelWeb typesetting commands are converted to
hypertext equivalents, so an existing FunnelWeb file which does
NOT contain a `@p typesetter = tex' pragma should be able to be
used for hypertext by simply adding `@p typesetter = hypertext'
as the first line. The resulting hypertext output is not be
formatted exactly the same as the TeX version (in particular,
vertical skips are currently ignored for hypertext), but the
formatting should nonetheless be reasonable for a hypertext
document, and includes appropriate hypertext links for macro
invocations and the table of contents. The
`@p typesetter = html' option allows HTML expressions to be
included in the documentation without being escaped, and so is
the HTML equivalent of the `@p typesetter = tex' option.
3. no_doc_header pragma:
`@p no_doc_header' is used to suppress the TeX (or HTML)
header definitions that FunnelWeb normally includes in the output
file. It is mainly intended for users who use
`@p typesetter = tex' so that they can write their documentation
using LaTeX. The file `fw-latex.sty' contains all of the
standard FunnelWeb header definitions, and can be included as an
optional style file for the LaTeX `\documentstyle' command. Note
that it is not necessary to do this for LaTeX files, as the
FunnelWeb TeX definitions work perfectly well under LaTeX;
however, by separating the definitions into a single style file,
the same definitions are not repeated in every documentation
file, which can offer a useful saving in disk space. Leaving the
TeX header intact *and* using the FunnelWeb style file as well
will lead to a LaTeX error, so you must choose one or the other
if you are writing your documentation this way. Using
`@p no_doc_header' also suppresses the automatic inclusion of a
TeX `\bye' command at the end of the documentation file. For
LaTeX, the `\end{document}' command makes `\bye' unnecessary.
4. raw_macro_and_section_names pragma:
Normally, FunnelWeb escapes all TeX (or HTML) expressions that
occur in section names (if you use the FunnelWeb sectioning
commands) or in macro names. The
`@p raw_macro_and_section_names' pragma inhibits this escaping of
expressions in section and macro names, unless the macro is
attached to a file (TeX or HTML in file names almost certainly
have no practical value, and would more likely be unintentional,
particularly with file systems that use `\' as the directory
separator).
4. ignore_text_after_special_minus pragma:
Normally, it is an error to have any text on a line after a
FunnelWeb `@-' command, which suppresses the return at the end of
a line. However, in some cases it may be useful to allow the
text appearing after a `@-' command on a line to be treated as a
comment which does not appear in the final documentation (in
particular, this style of comment allows the automatic setting of
emacs buffer modes for editing code scraps when using certain
emacs WEB modes). The `@p ignore_text_after_special_minus'
allows the use of such trailing comments after `@-' (assuming
that `@' is the special character as per usual; the use of `@' as
the special is not at all necessary for this pragma to work).
5. no_paragraph_markups pragma:
For the hypertext settings `@p typesetter = hypertext' and
`@p typesetter = html', HTML paragraph markups (`') are
inserted in the documentation text wherever one or more blank
lines occur in a row. However, particularly for users writing
HTML documentation directly and using `@p typesetter = html', it
may be undesirable to have these `
' markups automatically
inserted, since they may already exist as desired in the
documentation text. The `@p no_paragraph_markups' pragma
suppresses the automatic insertion of `
' markups in HTML
documentation (but has no effect on TeX documentation).
6. automatic_line_directive_macro pragma:
This pragma allows the *automatic* insertion of line directives
into the product files, similarly to the manner supported by
`noweb'. For example, `@p automatic_line_directive_macro = line'
would make FunnelWeb call the macro `@' whenever a line
directive was needed (an appropriate definition of @ for
C/C++ is given in `autoccln.fwi'. The fact that this macro is
user defined means that the user can support any type of line
directive convention, or just add comments to show where a
section of a product file came from in the original FunnelWeb
source. New line directive types can be defined using
`@<#line@>' and `@<#file@>', which are described in the next
section.
There are some caveats that go with using automatic line
directive insertion. The same macro is used for all the line
directives, which means that a single FunnelWeb source cannot
support multiple language/file types unless the line directive
style happens to be the same for all of them. Also, when adding
line directives, there is the need to insert carriage returns
into the product files before and after macro invocations. So
your code may break unless macros are only used where adding
newlines before or after the macro invocations does not affect
the meaning of the product code. For many languages, such as
C/C++ or Pascal, this is generally the case; it isn't for
Fortran, though. Using a macro in the middle of a string
definition would probably also do the wrong thing, breaking
the string up across multiple lines.
7. allow_source_code_typing and declare_source_code_type pragmas:
As originally implemented, the `automatic_line_directive_macro'
pragma added the same line directives to every product file
(except the documentation file). This is O.K. when all of the
files are, say, C files, but if you also generate the makefile
from the FunnelWeb file, you would then have to remove the #line
directives from the makefile, or use two separate FunnelWeb
files. The `allow_source_code_typing' macro tells FunnelWeb that
you wish apply the insertion of line directives selectively to
the product files. This pragma is required so that the new
features remain inactive unless explicitly asked for, to protect
existing FunnelWeb code.
Continuing the example of a FunnelWeb file from which is produced
a C file and a makefile, the product makefile should not have any
line directives. Since the FunnelWeb default is no line
directives, the makefile can be produced with the default source
code type. Then `@p declare_source_code_type "C"' can be used to
declare a source code type for the C file. You can declare as
many source code types as are required. Do not create a special
source code type for files without line directives, though, since
the default already provides this.
With source code types, the `automatic_line_directive_macro'
pragma can have two forms. The first form is
`@p automatic_line_directive_macro = ', which sets the
automatic line directive macro for the default source type. If
you are using source code typing, you probably will have some
files to generate without line directives, and so you will not
want to set a line directive type for the default source code
type. Having defined a "C" source code type, you set the
automatic line directive macro for C files by
`@p automatic_line_directive_macro = "C"', i.e. you add
the source code type name to the end of the line.
There is only one more thing to do. Source code types apply only
to macros which are attached to files. So when you generate your
C file `main.c', you change its definition from
`@O@==@{...@}' to `@O@==@{...@}'. Note the
special use of `@,' here, and also that in the file macro
definition the source code type name is not surrounded by double
quotes as it is in the pragmas.
If you have followed all of this, you should be able to
understand the following sample FunnelWeb file which uses these
pragmas.
-----------sample FunnelWeb file----------------
@p allow_source_code_typing
@p declare_source_code_type "C"
@p automatic_line_directive_macro = "line" "C"
@i autoccln.fwi
@O@==@{int main(void) { return 0; }@}
@$@==@{@^D(009)@} @! ASCII TAB character is decimal 9.
@O@==@{@-
main.exe: main.c
@$(CC) -o $@@ main.c
@}
-----------end of sample FunnelWeb file----------
8. A command switch `+Qb' has been added. The `b' stands for
`batch', and this switch stops FunnelWeb from asking the user
for confirmation if it has to abort. This means that FunnelWeb
will run as a completely batch-mode program, which apparently is
important for users who want to integrate it into the Borland
C/C++ IDE (development environment).
9. The way FunnelWeb AC maps files into memory has been modified in
order to avoid problems with Unix systems choking on the CR/LF
pair used to terminate lines in DOS files. While the new system
has been checked under OS/2, OSF/1(Unix), and DOS, I would
appreciate knowing if this system works for Macintoshes as I
believe it should.
In principle this change could make FunnelWeb 3.05AC act
differently to FunnelWeb 3.0 for some files, but only files
so perverse as to be unreasonable in any case. If this is not
the case, report it to the author immediately.
Special Internal Macros:
Some special `internal' macros have been added to FunnelWeb 3.05AC
to support imbedding of references to the original FunnelWeb
source(s) in the product files. In particular, the FunnelWeb
include file `ccline.fwi' defines a macro called @ which can
be used to insert a C/C++ #line directive into a product file (for
manual line directive insertion, i.e. where the user types
`@' wherever needed. The version of `@' to be used
for automatic line directive insertion is to be found in
`autoccln.fwi'). These internal macros, of which only three
currently exist (@<#line@>, @<#file@>, and @<#timestamp@>), have
names which start with the hash character '#'.
This is the one place where existing FunnelWeb code might be
expected to break when processed by this experimental version of
FunnelWeb, if the name of an internal macro also used for a
user-defined macro. As such, it is strongly recommended that the
user avoid macro names which start with the '#' character.
The @<#line@> macro causes a FunnelWeb source line number to
be inserted into the product file, while the @<#file@> macro inserts
a FunnelWeb source file name. See `ccline.fwi' for an example.
There are two pragmas related to this pair of internal macros.
`@p #line_offset = ' is used to set a value which is added to
the actual FunnelWeb source file line on which @<#line@> is invoked
before the line number is printed in the product file. This is
necessary for C/C++ #line directives because the directive much
specify the source line number of the line *after* the directive,
not the source line number of the directive itself. Thus, the
offset value needs to be 1 for C/C++ (and is defined to be in
`ccline.fwi').
`@p #line_depth = ' controls *which* line number and file name
are actually printed by @<#line@> and @<#file@>. Taking
`ccline.fwi' as an example, this file defines a @ macro in
which @<#line@> and @<#file@> are then called. My first naive
version of @ [ABC] ended up printing the line number and file
name for `ccline.fwi' (which is then the same for every case)!!!
What I [ABC] wanted was the line number and file name for where
@ was invoked, not where @<#line@> and @<#file@> were
actually invoked inside @. This means that it is necessary
to climb up the current stack of macro invocations until you arrive
at the one you want. `@p #line_depth = ' allows the user to
define how far up the macro invocation stack you must go in order to
get the desired line number and file name. The appropriate value
for C/C++ #line directives is set in `ccline.fwi'.
The @<#timestamp@> macro is converted in the product files
(but not in the documentation file)to a date/time string in the form
`yyyy/mm/dd/hh/mm/ss'. Although most file systems will date the
product files anyway, timestamping may be useful for having the
program itself print a message saying when FunnelWeb was last used
to generate the product files. The actually date and time used for
the timestamp are only checked once, the first time that
@<#timestamp@> is processed by FunnelWeb. Thus, all product files
produced by the same run of FunnelWeb will contain the same
timestamp. This seems more reasonable than having slightly
different times in each of the product files. If you have more
complicated timestamp or version control requirements, try using GNU
RCS (revision control system), which has been found to work well
with FunnelWeb. *WARNING*: if you use @<#timestamp@> in a product
file, the FunnelWeb `+D' command line flag will not affect that
file, since the timestamp in the file will be different every time
FunnelWeb is run. Hence, if you use makefiles, and do not want to
recompile/regenerate everything every time, be careful about using
@<#timestamp@>.
Other changes:
Ross Williams once posted a message to the FunnelWeb mailing list
stating that FunnelWeb allocated a maximally-sized string to every
macro name, and that this was a waste of space. In my version,
this has been modified so that only the amount of string space
necessary is allocated. How much is saved will depend greatly on
the nature of the FunnelWeb source. I [ABC] did manage in one case
to save 100k on the memory that needed to be allocated, but this was
on a project where FunnelWeb allocated itself just over 11M while
running; thus the saving is not necessarily significant.
Compiling the code:
I have included some example makefiles, but the standard FunnelWeb
creed of `just compile it all together at once' should work fine. I
[ABC] tend not to do this because my compiler is not lightning fast.
Because of the modifications, when you run the FunnelWeb tests, you
will not get the same errors as with FunnelWeb v.3.0. The number of
errors and differences that you should get is to be found in the
file `err.status'.
This is the end of this documentation file.