add a section on compilation modes. only half done, though

tools/qfcc/doc/man/qfcc.1

@@ -28,6 +28,9 @@
 .\" .sp <n>    insert n+1 empty lines
 .\" for manpage-specific macros, see man(7)
 .\"
+.ds qfcc \fBqfcc\fP
+.ds cpp \fBcpp\fP
+.ds progs.src \fIprogs.src\fP
 .TH QFCC 1 "28 April, 2004" QuakeForge "QuakeForge Developer's Manual"
 .\" Please update the above date whenever this man page is modified.
 .SH NAME
@@ -37,10 +40,10 @@ qfcc \- The QuakeForge Code Compiler
 .RI [ options ]
 .RI [ files ]
 .SH DESCRIPTION
-\fBqfcc\fP compiles Ruamoko source into a form that the QuakeForge engine can
+\*[qfcc] compiles Ruamoko source into a form that the QuakeForge engine can
 understand.
 .SH OPTIONS
-\fBqfcc\fP takes the following arguments:
+\*[qfcc] takes the following arguments:
 .TP
 .B \-\-advanced
 Use advanced Ruamoko features.
@@ -55,7 +58,7 @@ Compile only, do not link.
 Can be used in either \fBprogs.src\fP or separate compilation modes.
 .TP
 .B \-\-cpp CPPSPEC
-\fBcpp\fP execution command line.
+\*[cpp] execution command line.
 See \fBCPP NAME\fP for details.
 .TP
 .B \-D, \-\-define SYMBOL[=VAL]
@@ -82,19 +85,19 @@ for include files.
 .TP
 .B \-\-include FILE
 Process FILE as if \fB#include "FILE"\fP appeared as the first line of the
-primary source file. See the \fBcpp\fP man page (\fB\-include\fP) for details.
+primary source file. See the \*[cpp] man page (\fB\-include\fP) for details.
 .TP
 .B \-L DIR
 Add DIR to the search path used for finding libraries specified with \fB-l\fP.
 .TP
 .B \-l LIB
 Add libLIB.a to the list of libraries to be used for resolving undefined
-symbols. \fBqfcc\fP expects libraries to be \fBpak\fP files of \fBqfcc\fP
+symbols. \*[qfcc] expects libraries to be \fBpak\fP files of \*[qfcc]
 object files built using the \fBpak\fP utility. (\fBFIXME\fP: add sections
 on object files and library files)
 .TP
 .B \-M, \-MD, \-MMD
-Generate dependency info. Dependent on \fBcpp\fP version, so check \fBcpp\fP's
+Generate dependency info. Dependent on \*[cpp] version, so check \*[cpp]'s
 documentation.
 .TP
 .B \-N, \-\-notice OPTION,...
@@ -102,19 +105,24 @@ Set notice options. See \fBNOTICE OPTIONS\fP for details.
 .TP
 .B \-o, \-\-output\-file FILE
 Specify output file name.
+In \fBprogs.src\fP mode, this overides the output file in \*[progs.src].
 .TP
 .B \-P, \-\-progs\-src FILE
-File to use instead of \fIprogs.src\fP.
+File to use instead of \*[progs.src].
+No effect in separate compilation mode.
 .TP
 .B \-p, \-\-strip\-path NUM
-Strip NUM leading path elements from file names. eg. -p 3 will strip the
+Strip NUM leading path elements from file names.
+eg. -p 3 will strip the
 .I ../../../
 from
 .I ../../../src/foo.r
 when embedding the source file name in the output code.
 .TP
 .B \-q, \-\-quiet
-Inhibit some of \fBqfcc\fP's normal output.
+Inhibit some of \*[qfcc]'s normal output.
+Specifying this option multiple times further inhibits \*[qfcc]'s output.
+Counteracts the effects of \fB-v\fP.
 .TP
 .B \-r, \-\-relocatable
 Incremental linking.
@@ -125,7 +133,7 @@ Generate a larger object file from other object files and libraries.
 Do not delete temporary files.
 .TP
 .B \-s, \-\-source DIR
-look for \fIprogs.src\fP in DIR instead of the current directory.
+Look for \*[progs.src] in \fBDIR\fP instead of the current directory.
 .TP
 .B \-\-traditional
 Use traditional QuakeC syntax, semantics and \*(lqbugs\*(rq.
@@ -138,10 +146,12 @@ This is the default when using \fBprogs.src\fP mode.
 Undefine a preprocessor symbol, if the preprocessor is in use.
 .TP
 .B \-V, \-\-version
-Show the version of \fBqfcc\fP.
+Show the version of \*[qfcc].
 .TP
 .B \-v, \-\-verbose
 Display more output than usual.
+Specifying this option multiple times further increases \*[qfcc]'s output.
+Counteracts the effects of \fB-q\fP.
 .TP
 .B \-W, \-\-warn OPTION,...
 Set warning options.
@@ -151,31 +161,31 @@ See \fBWARNING OPTIONS\fP for details.
 Compress object files when writing them.
 This is especially useful when creating libraries, especially if using the
 object oriented features, but can be quite slow.
-This has no effect when writing \fBprogs.dat\fP.
+This has no effect when creating \fBprogs.dat\fP.
 .SH "CODE GENERATION OPTIONS"
 Code generation options are processed in the order of their appearance on the
 command line.
 Unsupported options are ignored.
-The following options are supported by \fBqfcc\fP's \fB\-\-code\fP argument:
+The following options are supported by \*[qfcc]'s \fB\-\-code\fP argument:
 .TP
 .B cow
 Allow assignment to initialized globals.
 In Quake-C and Ruamoko, a global that has been initialized to a value is not
 a variable, but a named constant.
 However, \fBqcc\fP never really enforced this.
-The \fBcow\fP option allows \fBqfcc\fP to gracefully cope with QuakeC source
+The \fBcow\fP option allows \*[qfcc] to gracefully cope with QuakeC source
 that assigns values to initialized globals in this manner.
 (also known as \*(lqcopy on write\*(rq\(emnever mind the bovine connotations)
 .TP
 .B cpp
-Preprocess all input files with \fBcpp\fP.
-This includes the \fIprogs.src\fP file when used.
+Preprocess all input files with \*[cpp].
+This includes the \*[progs.src] file when used.
 .TP
 .B debug
 Generate debug code for QuakeForge engines.
 The QuakeForge engine has the ability to load line number and other debugging
 information for use in diagnosing progs crashes.
-This option tells \fBqfcc\fP to generate this information.
+This option tells \*[qfcc] to generate this information.
 It is written to a secondary file with the extension \*(lqsym\*(rq\(emif your
 output file is \*(lqprogs.dat\*(rq, the symbol file will be
 \*(lqprogs.sym\*(rq.
@@ -183,7 +193,8 @@ output file is \*(lqprogs.dat\*(rq, the symbol file will be
 .B fast\-float
 Use float values directly in \*(lqif\*(rq statements.
 Defaults to on.
-This option is always enabled when using version 6 progs.
+This option is always enabled when using version 6 progs (\fBv6only\fP is in
+effect).
 .TP
 .B local-merging
 Clump the local variables from all functions into one block of data the size
@@ -192,6 +203,8 @@ space.
 When off, each function's local variable block is separate from the others,
 preserving the behaviour of traditional \fBqcc\fP, but using much more global
 data.
+This can be a problem because instructions can access addresses up to 32767 in
+older servers or 65535 in most modern servers.
 Defaults to off for traditional mode, and on for advanced mode.
 .TP
 .B short\-circuit
@@ -203,19 +216,21 @@ be true and the code for \fBB\fP will not be executed.
 Defaults to off for traditional mode, and on for advanced mode.
 .TP
 .B single-cpp
-In \fBprogs.src\fP mode, when \fBcpp\fP is used, produce an intermediate file
+In \fBprogs.src\fP mode, when \*[cpp] is used, produce an intermediate file
 that is a series of \fB#include\fP directives, one for each source file.
-This file is then passed to \fBcpp\fP and the resulting output is compiled in
+This file is then passed to \*[cpp] and the resulting output is compiled in
 one go.
 This results in preprocessor directives in early files affecting later files,
 as would be expected in \fBprogs.src\fP mode.
 Without this option, each source file is independent with respect to the
 preprocessor.
+Has no effect in separate compilation mode.
 Defaults to on.
 .TP
 .B vector\-calls
-Where a function is called with just a vector, this causes the function call to
-store three floats instead of one vector.
+When a function is passed a constant vector, this causes the vector to be
+passed using three float copy instructions instead of one vector copy
+instruction.
 This can save a good number of pr_globals where those vectors contain many
 duplicate coordinates but do not match entirely.
 However, this will generate slower code for such calls.
@@ -225,14 +240,14 @@ Restrict the compiler to only version 6 progs (original Quake/QuakeWorld)
 features.
 This means that the compiled data file should be able to run on older servers,
 as long as you have not used any QuakeForge-specific built-in functions.
-Also disables some of the compiler's features (like integers and string
-manipulation support).
+Also disables compiler features (such as integers and string manipulation
+support) that require extensions.
 Defaults to on for traditional mode and off for advanced mode.
 .SH "WARNING OPTIONS"
 Warning options are processed in the order of their appearance on the command
 line.
 Unsupported options are ignored.
-The following options are supported by \fBqfcc\fP's \fB\-\-warn\fP argument:
+The following options are supported by \*[qfcc]'s \fB\-\-warn\fP argument:
 .TP
 .B cow
 Emit a warning when the source assigns a value to a named constant.
@@ -304,11 +319,11 @@ Promote notices to warnings.
 If warnings are being treated as errors, so will notices.
 Disabling warnings has no effect on this option.
 .SH "CPP NAME"
-When preprocessing source files, \fBqfcc\fP calls \fBcpp\fP (the C
+When preprocessing source files, \*[qfcc] calls \*[cpp] (the C
 preprocessor) with a configurable command line.
 This is useful when you wish to use an alternative preprocessor (though it
-must be command line compatible with \fBcpp\fP) or when \fBqfcc\fP has been
-misconfigured to call \fBcpp\fP incorrectly for your operating system.
+must be command line compatible with \*[cpp]) or when \*[qfcc] has been
+misconfigured to call \*[cpp] incorrectly for your operating system.
 If the latter is the case, please report the details (operating system,
 detection methods, correct execution specification).
 The base default execution spec (on most Linux systems) is
@@ -320,16 +335,59 @@ Available substitutions:
 .TP
 .B %d
 Mainly for defines (\-D, \-U and \-I) but \fB%d\fP will be replaced by all
-\fBcpp\fP options that \fBqfcc\fP passes to \fBcpp\fP
+\*[cpp] options that \*[qfcc] passes to \*[cpp]
 .TP
 .B %o
 This will be replaced by the output file path.
-Could be either absolute or relative, depending on whether \fBqfcc\fP is
+Could be either absolute or relative, depending on whether \*[qfcc] is
 deleting temporary files or not.
 .TP
 .B %i
 This will be replaced by the input file path.
-Generally as given to \fBqfcc\fP.
+Generally as given to \*[qfcc].
+.SH "COMPILATION MODES"
+\*[qfcc] has two, mutually exclusive, modes of operation: \fBprogs.src\fP
+mode and \*(lqseparate compilation\*(rq mode.
+.SS "progs.src mode"
+This is the traditional method of compiling QuakeC programs.
+It is selected when no file arguments are given to \*[qfcc].
+Note that the \fB-lLIB\fP option is considered to be a file argument.
+.P
+In this mode, the file \[progs.src] is used to specify the output file name and
+the input source files.
+While it is customary to write each file name on a separate line, file names
+are really just white-space separated strings (use double quotes around files
+with spaces, though using files with spaces is a gibbing offence).
+\fB//\fP is used to denote a comment.
+The comment extends to the end of the current line.
+The first file name in the file specified the output file name.
+This may be overridden using the \fB-o\fP option.
+All subsequent file names specify QuakeC source files.
+.P
+The source files are cumulatively compiled in the order they are listed in
+\[progs.src].
+Cumulatively compiled means that all symbols other than frame macros defined in
+earlier source files are visible in later source files.
+Once the all source files have been compiled, the finished program is written
+to the output file as a normal \fIprogs.dat\fP file.
+.P
+If the \fB-c\fP option is given, instead of a \fIprogs.dat\fP file, an object
+file is written. This object file can then be linked against other object files
+to produce the \fIprogs.dat\fP file. This is useful when mod extensions are in
+library form and converting the main mod from \fBprogs.src\fP style to
+separate compilation is undesirable.
+.P
+\fBprogs.src\fP mode implies \fB--traditional\fP.
+.P
+When \[cpp] has not been disabled, \[progs.src] is first passed through \[cpp].
+The result is then parsed as above, but unless the \fBno-single-cpp\fP code
+option has been given, rather than compiling each source file, an intermediate
+file is generated containing a series of frame macro reset and \fB#include\fP
+directives, one for each file.
+This intermediate file is then passed to \[cpp] and the resulting single file
+containing all of the pre-processed source code is then compiled.
+.SS "\*(lqseparate compilation\*(rq mode"
+much like C. \fBFIXME\fP I'm tired, I'm going to bed.
 .SH "FAQ"
 .TP
 .B Where did the name Ruamoko come from?
@@ -339,16 +397,16 @@ Ruamoko is the god of volcanoes and earthquakes \fB(Quake, get it?)\fP.
 For more information, see the Web site at <\fBhttp://maori.com/kmst1.htm\fP>.
 .TP
 .B qfcc hangs
-This is almost always caused by qfcc incorrectly invoking \fBcpp\fP.
+This is almost always caused by qfcc incorrectly invoking \*[cpp].
 Using the \fB--cpp\fP option (refer to the \fBCPP NAME\fP section above), the
-correct method for invoking \fBcpp\fP can be specified.
-Once you have found this, please send the correct \fBcpp\fP command line,
+correct method for invoking \*[cpp] can be specified.
+Once you have found this, please send the correct \*[cpp] command line,
 preferably along with the output of \fBconfig.guess\fP, to the team.
 .TP
 .B qfcc is singing a bad 80s rap song to me. What's going on?
 \*(lqice ice baby\*(rq is QuakeForge-speak for \*(lqInternal Compiler
 Error\*(rq.
-It usually means there's a bug in \fBqfcc\fP, so please report it to the team.
+It usually means there's a bug in \*[qfcc], so please report it to the team.
 .TP
 .B qfcc is mooing at me. What's wrong with you people?
 The compiler doesn't like being treated like a slab of beef.