*** empty log message ***

util/ack/ack.1.X

@@ -1,4 +1,14 @@
 .\" $Header$
+.de SB
+.\" SuBheader
+.sp 1
+.nr Sf \\n(.f
+.ft B
+.PP
+\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+.ft \\n(Sf
+.sp 1
+..
 .TH ACK I
 .ad
 .SH NAME
@@ -10,6 +20,8 @@ ack \- Amsterdam Compiler Kit
 .br
 \fBapc\fP arguments
 .br
+\fBabc\fP arguments
+.br
 \fImachine\fP arguments
 .SH DESCRIPTION
 This program transforms sources in several
@@ -35,13 +47,16 @@ in time and depends on the installation.
 .PP
 The actions of \fIack\fP are to repeatedly transform files with a
 particular suffix into files with another suffix,
-finally combining the results into a load file.
+finally combining the results into a single file.
 .PP
-\fIAck\fP recognizes the following suffixes:
+Different machines can use different suffices,
+but the following are recognized by most machines:
 .IP .p
 Pascal program.
 .IP .c
 C module.
+.IP .b
+Basic program.
 .IP .e
 EM assembly module in human readable form.
 .IP .k
@@ -54,54 +69,53 @@ Machine assembly language code.
 Object file.
 .PP
 \fIAck\fP accepts the following flags:
+.SB machine used
 .IP \-m\fImachine\fP
 This flag tells \fIack\fP to generate a load file for \fImachine\fP.
 \fIMachine\fP can also be used as the program call
 name, instead of \fIack\fP.
-e.g. \fIack \-m8086 file.p\fP is equivalent to \fI8086
+e.g. \fIack \-mi86 file.p\fP is equivalent to \fIi86
 file.p\fP.
+.SB output files
 .IP \-o
-The the next argument as the name of the resulting load file,
+Use the next argument as the name of the resulting file.
-instead of the default \fIa.out\fP or \fIe.out\fP.
+\fIAck\fP produces \fIa.out\fP or \fIe.out\fP by default.
-.IP \-O
+This flag can always be used when \fIack\fP produces a single output file,
-Use the EM peephole optimizer,
+as in
-this flag is superfluous when an machine code is generated.
+.br
-.IP \-LIB
+.ti +5
-This flag tells the peephole optimizer
+\fBack -c.s main.c -o new.s\fP.
-.RF em_opt VI
+.br
-to add information about the visibility of the names used
+The output is produced on \fInew.s\fP instead of \fImain.s\fP.
-to each output module.
+.IP \-c\fI.suffix\fP
-This is needed by most
+.IP \-c
-assembler/linkers when these modules are to be inserted
+\fIAck\fP tries to transform each source into a file with the \fIsuffix\fP.
-in libraries.
+When no \fIsuffix\fP is specified \fIack\fP stops just
-.IP \-l\fIname\fP
+before the phase where it combines all arguments into a load file,
-Tells \fIack\fP to insert a library module at this point.
+thereby transforming the sources into \fI.k\fP, \fI.s\fP,
-For example: the library \fImon\fP contains the
+\&\fI.o\fP or \fI.m\fP files.
-routines for systems calls needed by both C and Pascal.
+One extra \fIsuffix\fP is recognized here, \fI.i\fP,
-.IP \-r.\fIsuffix\fP
+this tells \fIack\fP to only preprocess all human readable sources,
-Most frontends and backends use one or
+producing files with \fIsuffix\fP \fI.i\fP.
-more run-time libraries.
+.br
-These flags tell \fIack\fP to include the libraries needed when
+Note: \fIack\fP refuses to overwrite argument \fI.e\fP files.
-a file with \fIsuffix\fP would be included in the arguments.
+.IP \-t
-.IP \-L
+Preserve all intermediate files.
-Disable the generation of code by the front ends to
+If two \fB\-t\fP are used,
-record line number and source file name at run-time.
+\fIack\fP also preserves core dumps and output of failed transformations.
-.IP \-p
+.SB messages
-This flag tells both the Pascal and C front ends to include
-code enabling the user to do some monitoring/debugging.
-Each time a routine is entered the routine \fBprocentry\fP
-is called and just before each return \fBprocexit\fP is called.
-These routines are supplied with one parameter, a pointer
-to a string containing the name of the routine.
 .IP \-w
 Suppress all warning messages.
+.IP \-E
+Produce a complete listing of each Pascal source program.
+Normally for each error, one message,
+including the source line number, is given.
+.IP \-e
+List only the erroneous lines of each Pascal source program.
 .IP \-v
 Verbose.
 Print information while juggling with files.
-.IP \-g
+.SB preprocessing
-Try to run the resulting load file.
-No arguments can be passed this way,
-so it is only useful in simple cases.
 .IP \-I\fIdir\fP
 \&\`#include\' files whose names do not begin with \`/\' are
 always sought first in the directory of the \fIfile\fP argument,
@@ -115,33 +129,50 @@ If no definition is given the \fIname\fP is defined as 1.
 .IP \-U\fIname\fP
 Remove any initial definition of \fIname\fP, before
 preprocessing.
-.IP \-c\fI.suffix\fP
+.SB debugging
-.IP \-c
+.IP \-p
-\fIAck\fP tries to transform each source into a file with the \fIsuffix\fP.
+This flag tells both the Pascal and C front ends to include
-When no \fIsuffix\fP is specified \fIack\fP stops just
+code enabling the user to do some monitoring/debugging.
-before the phase where it combines all arguments into a load file,
+Each time a routine is entered the routine \fBprocentry\fP
-thereby transforming the sources into \fI.k\fP, \fI.s\fP,
+is called and just before each return \fBprocexit\fP is called.
-\&\fI.o\fP or \fI.m\fP files.
+These routines are supplied with one parameter, a pointer
-One extra \fIsuffix\fP is recognized here, \fI.i\fP,
+to a string containing the name of the routine.
-this tells \fIack\fP to only preprocess all human readable sources,
+.SB optimizing
-producing files with \fIsuffix\fP \fI.i\fP.
+.IP \-O
-Note: \fIack\fP refuses to overwrite argument \fI.e\fP files.
+Use as many optimizers as possible.
-.IP \-t
+\fIAck\fP can almost always use the EM peephole optimizer.
-Preserve all intermediate files.
+Sometimes the global optimizer or machine-dependent
-.IP \-k
+optimizers can be used.
-Do not stop when an error occurs, but try to transform all
+.IP \-L
-other arguments as far as possible.
+Disable the generation of code by the front ends to
-.IP \-R\fIprogram=xxx\fP
+record line number and source file name at run-time.
-Replace the \fIprogram\fP by the pathname \fIxxx\fP.
+.SB libraries
-The program names referred to later in this manual are allowed here.
+.IP \-l\fIname\fP
-.IP \-R\fIprogram\-xxx\fP
+Tells \fIack\fP to insert a library module at this point.
-The flag argument \fI\-xxx\fP is given to \fIprogram\fP.
+For example: the library \fImon\fP contains the
-.IP \-E
+routines for systems calls needed by both C and Pascal.
-Produce a complete listing of each Pascal source program.
+.IP \-.\fIsuffix\fP
-Normally for each error, one message,
+When linking multiple \fI.o\fP or \fI.m\fP files created by
-including the source line number, is given.
+separate calls of \fIack\fP together, \fIack\fP cannot deduce
-.IP \-e
+the run-time system needed,
-List only the erroneous lines of each Pascal source program.
+unless called as \fIapc\fP or \fIacc\fP.
+This flag serves to tell \fIack\fP which runtime system is
+needed in such a case.
+For example: "ack \-c x.c ; ack \-.c x.o".
+.IP \-r.\fIsuffix\fP
+Most frontends and backends use one or
+more run-time libraries.
+These flags tell \fIack\fP to include the libraries needed when
+a file with \fIsuffix\fP would be included in the arguments.
+.IP \-LIB
+This flag tells the peephole optimizer
+.RF em_opt VI
+to add information about the visibility of the names used
+to each output module.
+This is needed by most
+assembler/linkers when these modules are to be inserted
+in libraries.
+.SB interpreter
 .IP \-{xxx}
 The string starting after \`{\' and terminated by a \`}\' is passed
 as an option string to the Pascal compiler and supersedes corresponding
@@ -169,14 +200,24 @@ the defaults per program.
 The changed options are recorded in the "e.out" header.
 These flags \-\- and \-+ are passed to the assembler for this purpose.
 So, \-\-t and \-+pfce invert the defaults.
-.IP \-.\fIsuffix\fP
+.SB general
-When linking multiple \fI.o\fP or \fI.m\fP files created by
+.IP \-R\fIprogram=xxx\fP
-separate calls of \fIack\fP together, \fIack\fP cannot deduce
+Replace the \fIprogram\fP by the pathname \fIxxx\fP.
-the run-time system needed,
+The program names referred to later in this manual are allowed here.
-unless called as \fIapc\fP or \fIacc\fP.
+.IP \-R\fIprogram\-xxx\fP
-This flag serves to tell \fIack\fP which runtime system is
+The flag argument \fI\-xxx\fP is given to \fIprogram\fP.
-needed in such a case.
+.IP \-R\fIprogram:n\fP
-For example: "ack \-c x.c ; ack \-.c x.o".
+Set the priority of the indicated transformation to \fIn\fP.
+The default priority is 0, setting it to -1 makes it highly
+inlikely the the phase will be used, setting it to 1 makes
+it very likely that the phase will be used.
+.IP \-k
+Do not stop when an error occurs, but try to transform all
+other arguments as far as possible.
+.IP \-g
+Try to run the resulting load file.
+No arguments can be passed this way,
+so it is only useful in simple cases.
 .PP
 All arguments without a suffix or with an unrecognized suffix
 are passed to the loaders, as for flags.
@@ -191,7 +232,7 @@ preprocessor.
 These macro\'s contain the word- and pointer-size and the sizes
 of some basic types used by the Pascal and/or C compiler.
 All sizes are in bytes.
-.PP
+.sp 1
 .TS
 tab(:);
 l l l l.
@@ -199,9 +240,12 @@ EM_WSIZE:wordsize:EM_PSIZE:pointer size
 EM_SSIZE:size of shorts (C):EM_LSIZE:size of longs (C+Pascal)
 EM_FSIZE:size of floats (C):EM_DSIZE:size of doubles (C+Pascal)
 .TE
-.PP
+.sp 1
 The name of the \fImachine\fP or something like it when
 the machine name is numeric is also defined (as 1).
+.PP
+The default directories searched for include files differ for each machine.
+Some machines do not even use \fI/usr/include\fP.
 .SH PROGRAMS
 \fIAck\fP uses one or more programs in each phase of the
 transformation.
@@ -211,12 +255,15 @@ Internally \fIack\fP maintains a mapping of these names to pathnames
 for load files.
 The table specifies which type of files are accepted by each
 program as input and the file type produced as output.
+.sp 1
+.in +2
 .TS
 tab(:);
 l l l l.
 input:name:output:description
 \&.c:cem:.k:C front end [4,5,6]
 \&.p:pc:.k:Pascal front end [2,3,6]
+\&.b:abc:.k:Basic front end [6,8]
 \&.e:encode:.k:Compactify EM assembly language [1]
 \&.k:opt:.m:EM peephole optimizer
 \&.k .m:decode:.e:Produce human readable EM assembly
@@ -226,16 +273,17 @@ input:name:output:description
 \&.s:as:.o:Assembler
 \&.o:ld:a.out:Linker producing machine code
 .TE
+.in -2
 .SH "SEE ALSO"
 .PD 0
 em_opt(VI), em_ass(VI), em_cg(VI)
 .IP [1]
 A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
-Stevenson "Description of a machine architecture for use with
+Stevenson \fIDescription of a machine architecture for use with
-block structured languages" Informatica report IR-81.
+block structured languages\fP Informatica report IR-81.
 .IP [2]
 K. Jensen and N. Wirth
-"PASCAL, User manual and report" Springer Verlag.
+\fIPASCAL, User manual and report\fP Springer Verlag.
 .IP [3]
 The ISO Pascal standard proposal ISO/TC97/SC5-N462.
 .IP [4]
@@ -244,7 +292,11 @@ language\fP, Prentice-Hall, 1978
 .IP [5]
 D.M. Ritchie, \fI C Reference Manual\fP
 .IP [6]
-E.G. Keizer, Amsterdam Compiler Kit, reference manuals and UNIX manual pages.
+Amsterdam Compiler Kit, reference manuals and UNIX manual pages.
+.IP [7]
+E.G. Keizer, Ack description file reference manual.
+.IP [8]
+M.L. Kersten, \fIThe ABC compiler\fP.
 .PD
 .SH DIAGNOSTICS
 .PD