summaryrefslogtreecommitdiff
path: root/web/funnelAC/fwACsrc/README.ABC
blob: a52953930460d6eb9dc239bf6659aa5b6c221c94 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
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 (`<P>') 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 `<P>' 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 `<P>' 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 `@<line@>' whenever a line
     directive was needed (an appropriate definition of @<line@> 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 = <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 = <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@<main.c>==@{...@}' to `@O@<main.c@,C@>==@{...@}'.  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@<main.c@,C@>==@{int main(void) { return 0; }@}

     @$@<TAB@>==@{@^D(009)@} @! ASCII TAB character is decimal 9.
     @O@<Makefile@>==@{@-
     main.exe: main.c
     @<TAB@>$(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 @<line@> 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
  `@<line@>' wherever needed.  The version of `@<line@>' 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 = <num>' 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 = <num>' controls *which* line number and file name
  are actually printed by @<#line@> and @<#file@>.  Taking
  `ccline.fwi' as an example, this file defines a @<line@> macro in
  which @<#line@> and @<#file@> are then called.  My first naive
  version of @<line@> [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
  @<line@> was invoked, not where @<#line@> and @<#file@> were
  actually invoked inside @<line@>.  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 = <num>' 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.