Put a real man page in for cpp(1)... it needs to be converted to the mandoc

macros,  but it's good enough for now.
Obtained from: gcc 2.6.0 gnu distribution

gnu/usr.bin/cc/cpp/cpp.1

@@ -1 +1,674 @@
-.so man1/cccp.1
+.\" Copyright (c) 1991, 1992, 1993 Free Software Foundation       \-*-Text-*-
+.\" See section COPYING for conditions for redistribution
+.TH cpp 1 "30, April 1993" "FreeBSD" "GNU Tools"
+.SH NAME
+cpp \- Compiler Preprocessor.
+.SH SYNOPSIS
+.hy 0
+.na
+.TP
+.B cpp
+.RB "[\|" \-$ "\|]"
+.RB "[\|" \-A \c
+.I predicate\c
+.RB [ (\c
+.I value\c
+.BR ) ]\|]
+.RB "[\|" \-C "\|]" 
+.RB "[\|" \-D \c
+.I name\c
+.RB [ =\c
+.I definition\c
+\&]\|]
+.RB "[\|" \-dD "\|]"
+.RB "[\|" \-dM "\|]"
+.RB "[\|" "\-I\ "\c
+.I directory\c
+\&\|]
+.RB "[\|" \-H "\|]"
+.RB "[\|" \-I\- "\|]" 
+.RB "[\|" "\-imacros\ "\c
+.I file\c
+\&\|]
+.RB "[\|" "\-include\ "\c
+.I file\c
+\&\|]
+.RB "[\|" "\-idirafter\ "\c
+.I dir\c
+\&\|]
+.RB "[\|" "\-iprefix\ "\c
+.I prefix\c
+\&\|]
+.RB "[\|" "\-iwithprefix\ "\c
+.I dir\c
+\&\|]
+.RB "[\|" \-lang\-c "\|]"
+.RB "[\|" \-lang\-c++ "\|]"
+.RB "[\|" \-lang\-objc "\|]"
+.RB "[\|" \-lang\-objc++ "\|]"
+.RB "[\|" \-lint "\|]"
+.RB "[\|" \-M\  [ \-MG "\|]]"
+.RB "[\|" \-MM\  [ \-MG "\|]]"
+.RB "[\|" \-MD\  \c
+.I file\ \c
+\&\|]
+.RB "[\|" \-MMD\  \c
+.I file\ \c
+\&\|]
+.RB "[\|" \-nostdinc "\|]" 
+.RB "[\|" \-nostdinc++ "\|]" 
+.RB "[\|" \-P "\|]" 
+.RB "[\|" \-pedantic "\|]"
+.RB "[\|" \-pedantic\-errors "\|]"
+.RB "[\|" \-traditional "\|]" 
+.RB "[\|" \-trigraphs "\|]" 
+.RB "[\|" \-U \c
+.I name\c
+\&\|]
+.RB "[\|" \-undef "\|]"
+.RB "[\|" \-Wtrigraphs "\|]"
+.RB "[\|" \-Wcomment "\|]"
+.RB "[\|" \-Wall "\|]"
+.RB "[\|" \-Wtraditional "\|]"
+.br
+.RB "[\|" \c
+.I infile\c
+.RB | \- "\|]" 
+.RB "[\|" \c
+.I outfile\c
+.RB | \- "\|]"  
+.ad b
+.hy 1
+.SH DESCRIPTION
+The C preprocessor is a \c
+.I macro processor\c
+\& that is used automatically by
+the C compiler to transform your program before actual compilation.  It is
+called a macro processor because it allows you to define \c
+.I macros\c
+\&,
+which are brief abbreviations for longer constructs.
+
+The C preprocessor provides four separate facilities that you can use as
+you see fit:
+.TP
+\(bu
+Inclusion of header files.  These are files of declarations that can be
+substituted into your program.
+.TP
+\(bu
+Macro expansion.  You can define \c
+.I macros\c
+\&, which are abbreviations
+for arbitrary fragments of C code, and then the C preprocessor will
+replace the macros with their definitions throughout the program.
+.TP
+\(bu
+Conditional compilation.  Using special preprocessor commands, you
+can include or exclude parts of the program according to various
+conditions.
+.TP
+\(bu
+Line control.  If you use a program to combine or rearrange source files into
+an intermediate file which is then compiled, you can use line control
+to inform the compiler of where each source line originally came from.
+.PP
+C preprocessors vary in some details.  For a full explanation of the
+GNU C preprocessor, see the
+.B info
+file `\|\c
+.B cpp.info\c
+\&\|', or the manual
+.I The C Preprocessor\c
+\&.  Both of these are built from the same documentation source file, `\|\c
+.B cpp.texinfo\c
+\&\|'.  The GNU C
+preprocessor provides a superset of the features of ANSI Standard C.
+
+ANSI Standard C requires the rejection of many harmless constructs commonly
+used by today's C programs.  Such incompatibility would be inconvenient for
+users, so the GNU C preprocessor is configured to accept these constructs
+by default.  Strictly speaking, to get ANSI Standard C, you must use the
+options `\|\c
+.B \-trigraphs\c
+\&\|', `\|\c
+.B \-undef\c
+\&\|' and `\|\c
+.B \-pedantic\c
+\&\|', but in
+practice the consequences of having strict ANSI Standard C make it
+undesirable to do this.  
+
+Most often when you use the C preprocessor you will not have to invoke it
+explicitly: the C compiler will do so automatically.  However, the
+preprocessor is sometimes useful individually.
+
+The C preprocessor expects two file names as arguments, \c
+.I infile\c
+\& and
+\c
+.I outfile\c
+\&.  The preprocessor reads \c
+.I infile\c
+\& together with any other
+files it specifies with `\|\c
+.B #include\c
+\&\|'.  All the output generated by the
+combined input files is written in \c
+.I outfile\c
+\&.
+
+Either \c
+.I infile\c
+\& or \c
+.I outfile\c
+\& may be `\|\c
+.B \-\c
+\&\|', which as \c
+.I infile\c
+\&
+means to read from standard input and as \c
+.I outfile\c
+\& means to write to
+standard output.  Also, if \c
+.I outfile\c
+\& or both file names are omitted,
+the standard output and standard input are used for the omitted file names.
+.SH OPTIONS
+Here is a table of command options accepted by the C preprocessor.  
+These options can also be given when compiling a C program; they are
+passed along automatically to the preprocessor when it is invoked by
+the compiler. 
+.TP
+.B \-P
+Inhibit generation of `\|\c
+.B #\c
+\&\|'-lines with line-number information in
+the output from the preprocessor.  This might be
+useful when running the preprocessor on something that is not C code
+and will be sent to a program which might be confused by the
+`\|\c
+.B #\c
+\&\|'-lines.
+.TP
+.B \-C
+Do not discard comments: pass them through to the output file.
+Comments appearing in arguments of a macro call will be copied to the
+output before the expansion of the macro call.
+.TP
+.B \-traditional
+Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
+.TP
+.B \-trigraphs
+Process ANSI standard trigraph sequences.  These are three-character
+sequences, all starting with `\|\c
+.B ??\c
+\&\|', that are defined by ANSI C to
+stand for single characters.  For example, `\|\c
+.B ??/\c
+\&\|' stands for
+`\|\c
+.BR "\e" "\|',"
+so `\|\c
+.B '??/n'\c
+\&\|' is a character constant for a newline.
+Strictly speaking, the GNU C preprocessor does not support all
+programs in ANSI Standard C unless `\|\c
+.B \-trigraphs\c
+\&\|' is used, but if
+you ever notice the difference it will be with relief.
+
+You don't want to know any more about trigraphs.
+.TP
+.B \-pedantic
+Issue warnings required by the ANSI C standard in certain cases such
+as when text other than a comment follows `\|\c
+.B #else\c
+\&\|' or `\|\c
+.B #endif\c
+\&\|'.
+.TP
+.B \-pedantic\-errors
+Like `\|\c
+.B \-pedantic\c
+\&\|', except that errors are produced rather than
+warnings.
+.TP
+.B \-Wtrigraphs
+Warn if any trigraphs are encountered (assuming they are enabled).
+.TP
+.B \-Wcomment
+.TP
+.B \-Wcomments
+Warn whenever a comment-start sequence `\|\c
+.B /*\c
+\&\|' appears in a comment.
+(Both forms have the same effect).
+.TP
+.B \-Wall
+Requests both `\|\c
+.B \-Wtrigraphs\c
+\&\|' and `\|\c
+.B \-Wcomment\c
+\&\|' (but not
+`\|\c
+.B \-Wtraditional\c
+\&\|'). 
+.TP
+.B \-Wtraditional
+Warn about certain constructs that behave differently in traditional and
+ANSI C.
+.TP
+.BI "\-I " directory\c
+\&
+Add the directory \c
+.I directory\c
+\& to the end of the list of
+directories to be searched for header files.
+This can be used to override a system header file, substituting your
+own version, since these directories are searched before the system
+header file directories.  If you use more than one `\|\c
+.B \-I\c
+\&\|' option,
+the directories are scanned in left-to-right order; the standard
+system directories come after.
+.TP
+.B \-I\-
+Any directories specified with `\|\c
+.B \-I\c
+\&\|' options before the `\|\c
+.B \-I\-\c
+\&\|'
+option are searched only for the case of `\|\c
+.B #include "\c
+.I file\c
+\&"\c
+\&\|';
+they are not searched for `\|\c
+.B #include <\c
+.I file\c
+\&>\c
+\&\|'.
+
+If additional directories are specified with `\|\c
+.B \-I\c
+\&\|' options after
+the `\|\c
+.B \-I\-\c
+\&\|', these directories are searched for all `\|\c
+.B #include\c
+\&\|'
+directives.
+
+In addition, the `\|\c
+.B \-I\-\c
+\&\|' option inhibits the use of the current
+directory as the first search directory for `\|\c
+.B #include "\c
+.I file\c
+\&"\c
+\&\|'.
+Therefore, the current directory is searched only if it is requested
+explicitly with `\|\c
+.B \-I.\c
+\&\|'.  Specifying both `\|\c
+.B \-I\-\c
+\&\|' and `\|\c
+.B \-I.\c
+\&\|'
+allows you to control precisely which directories are searched before
+the current one and which are searched after.
+.TP
+.B \-nostdinc
+Do not search the standard system directories for header files.
+Only the directories you have specified with `\|\c
+.B \-I\c
+\&\|' options
+(and the current directory, if appropriate) are searched.
+.TP
+.B \-nostdinc++
+Do not search for header files in the C++ specific standard
+directories, but do still search the other standard directories.
+(This option is used when building libg++.)
+.TP
+.BI "\-D " "name"\c
+\&
+Predefine \c
+.I name\c
+\& as a macro, with definition `\|\c
+.B 1\c
+\&\|'.
+.TP
+.BI "\-D " "name" = definition
+\&
+Predefine \c
+.I name\c
+\& as a macro, with definition \c
+.I definition\c
+\&.
+There are no restrictions on the contents of \c
+.I definition\c
+\&, but if
+you are invoking the preprocessor from a shell or shell-like program
+you may need to use the shell's quoting syntax to protect characters
+such as spaces that have a meaning in the shell syntax.  If you use more than
+one `\|\c
+.B \-D\c
+\&\|' for the same
+.I name\c
+\&, the rightmost definition takes effect.
+.TP
+.BI "\-U " "name"\c
+\&
+Do not predefine \c
+.I name\c
+\&.  If both `\|\c
+.B \-U\c
+\&\|' and `\|\c
+.B \-D\c
+\&\|' are
+specified for one name, the `\|\c
+.B \-U\c
+\&\|' beats the `\|\c
+.B \-D\c
+\&\|' and the name
+is not predefined.
+.TP
+.B \-undef
+Do not predefine any nonstandard macros.
+.TP
+.BI "\-A " "name(" value )
+Assert (in the same way as the \c
+.B #assert\c
+\& command)
+the predicate \c
+.I name\c
+\& with tokenlist \c
+.I value\c
+\&.  Remember to escape or quote the parentheses on
+shell command lines.
+
+You can use `\|\c
+.B \-A-\c
+\&\|' to disable all predefined assertions; it also
+undefines all predefined macros.
+.TP
+.B \-dM
+Instead of outputting the result of preprocessing, output a list of
+`\|\c
+.B #define\c
+\&\|' commands for all the macros defined during the
+execution of the preprocessor, including predefined macros.  This gives
+you a way of finding out what is predefined in your version of the
+preprocessor; assuming you have no file `\|\c
+.B foo.h\c
+\&\|', the command
+.sp
+.br
+touch\ foo.h;\ cpp\ \-dM\ foo.h
+.br
+.sp
+will show the values of any predefined macros.
+.TP
+.B \-dD
+Like `\|\c
+.B \-dM\c
+\&\|' except in two respects: it does \c
+.I not\c
+\& include the
+predefined macros, and it outputs \c
+.I both\c
+\& the `\|\c
+.B #define\c
+\&\|'
+commands and the result of preprocessing.  Both kinds of output go to
+the standard output file.
+.PP
+.TP
+.BR \-M\  [ \-MG ]
+Instead of outputting the result of preprocessing, output a rule
+suitable for \c
+.B make\c
+\& describing the dependencies of the main
+source file.  The preprocessor outputs one \c
+.B make\c
+\& rule containing
+the object file name for that source file, a colon, and the names of
+all the included files.  If there are many included files then the
+rule is split into several lines using `\|\c
+.B \\\\\c
+\&\|'-newline.
+
+`\|\c
+.B \-MG\c
+\&\|' says to treat missing header files as generated files and assume \c
+they live in the same directory as the source file.  It must be specified \c
+in addition to `\|\c
+.B \-M\c
+\&\|'.
+
+This feature is used in automatic updating of makefiles.
+.TP
+.BR \-MM\  [ \-MG ]
+Like `\|\c
+.B \-M\c
+\&\|' but mention only the files included with `\|\c
+.B #include
+"\c
+.I file\c
+\&"\c
+\&\|'.  System header files included with `\|\c
+.B #include
+<\c
+.I file\c
+\&>\c
+\&\|' are omitted.
+.TP
+.BI \-MD\  file
+Like `\|\c
+.B \-M\c
+\&\|' but the dependency information is written to `\|\c
+.I file\c
+\&\|'.  This is in addition to compiling the file as
+specified\(em\&`\|\c
+.B \-MD\c
+\&\|' does not inhibit ordinary compilation the way
+`\|\c
+.B \-M\c
+\&\|' does.
+
+When invoking gcc, do not specify the `\|\c
+.I file\c
+\&\|' argument.  Gcc will create file names made by replacing `\|\c
+.B .c\c
+\&\|' with `\|\c
+.B .d\c
+\&\|' at the end of the input file names.
+
+In Mach, you can use the utility \c
+.B md\c
+\& to merge multiple files
+into a single dependency file suitable for using with the `\|\c
+.B make\c
+\&\|'
+command.
+.TP
+.BI \-MMD\  file
+Like `\|\c
+.B \-MD\c
+\&\|' except mention only user header files, not system
+header files.
+.TP
+.B \-H
+Print the name of each header file used, in addition to other normal
+activities.
+.TP
+.BI "\-imacros " "file"\c
+\&
+Process \c
+.I file\c
+\& as input, discarding the resulting output, before
+processing the regular input file.  Because the output generated from
+\c
+.I file\c
+\& is discarded, the only effect of `\|\c
+.B \-imacros \c
+.I file\c
+\&\c
+\&\|' is to
+make the macros defined in \c
+.I file\c
+\& available for use in the main
+input.  The preprocessor evaluates any `\|\c
+.B \-D\c
+\&\|' and `\|\c
+.B \-U\c
+\&\|' options
+on the command line before processing `\|\c
+.B \-imacros \c
+.I file\c
+\&\|' \c
+\&.
+.TP
+.BI "\-include " "file"
+Process 
+.I file
+as input, and include all the resulting output,
+before processing the regular input file.  
+.TP
+.BI "-idirafter " "dir"\c
+\&
+Add the directory \c
+.I dir\c
+\& to the second include path.  The directories
+on the second include path are searched when a header file is not found
+in any of the directories in the main include path (the one that
+`\|\c
+.B \-I\c
+\&\|' adds to).
+.TP
+.BI "-iprefix " "prefix"\c
+\&
+Specify \c
+.I prefix\c
+\& as the prefix for subsequent `\|\c
+.B \-iwithprefix\c
+\&\|'
+options.
+.TP
+.BI "-iwithprefix " "dir"\c
+\&
+Add a directory to the second include path.  The directory's name is
+made by concatenating \c
+.I prefix\c
+\& and \c
+.I dir\c
+\&, where \c
+.I prefix\c
+\&
+was specified previously with `\|\c
+.B \-iprefix\c
+\&\|'.
+.TP
+.B \-lang-c
+.TP
+.B \-lang-c++
+.TP
+.B \-lang-objc
+.TP
+.B \-lang-objc++
+Specify the source language.  `\|\c
+.B \-lang-c++\c
+\&\|' makes the preprocessor
+handle C++ comment syntax, and includes extra default include
+directories for C++, and `\|\c
+.B \-lang-objc\c
+\&\|' enables the Objective C
+`\|\c
+.B #import\c
+\&\|' directive.  `\|\c
+.B \-lang-c\c
+\&\|' explicitly turns off both of
+these extensions, and `\|\c
+.B \-lang-objc++\c
+\&\|' enables both.
+
+These options are generated by the compiler driver \c
+.B gcc\c
+\&, but not
+passed from the `\|\c
+.B gcc\c
+\&\|' command line.
+.TP
+.B \-lint
+Look for commands to the program checker \c
+.B lint\c
+\& embedded in
+comments, and emit them preceded by `\|\c
+.B #pragma lint\c
+\&\|'.  For example,
+the comment `\|\c
+.B /* NOTREACHED */\c
+\&\|' becomes `\|\c
+.B #pragma lint
+NOTREACHED\c
+\&\|'.
+
+This option is available only when you call \c
+.B cpp\c
+\& directly;
+\c
+.B gcc\c
+\& will not pass it from its command line.
+.TP
+.B \-$
+Forbid the use of `\|\c
+.B $\c
+\&\|' in identifiers.  This is required for ANSI
+conformance.  \c
+.B gcc\c
+\& automatically supplies this option to the
+preprocessor if you specify `\|\c
+.B \-ansi\c
+\&\|', but \c
+.B gcc\c
+\& doesn't
+recognize the `\|\c
+.B \-$\c
+\&\|' option itself\(em\&to use it without the other
+effects of `\|\c
+.B \-ansi\c
+\&\|', you must call the preprocessor directly.
+.SH "SEE ALSO"
+.RB "`\|" Cpp "\|'"
+entry in
+.B info\c
+\&;
+.I The C Preprocessor\c
+, Richard M. Stallman.
+.br
+.BR gcc "(" 1 ");"
+.RB "`\|" Gcc "\|'"
+entry in 
+.B info\c
+\&;
+.I 
+Using and Porting GNU CC (for version 2.0)\c
+, Richard M. Stallman.
+.SH COPYING
+Copyright (c) 1991, 1992, 1993 Free Software Foundation, Inc.
+.PP
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+.PP
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be included in
+translations approved by the Free Software Foundation instead of in
+the original English.