I'll pretend to be a doc reviewer...
Iain Buclaw <ibuc...@gdcproject.org> writes:
> +@page
> +@vskip 0pt plus 1filll
> +Published by the Free Software Foundation @*
> +51 Franklin Street, Fifth Floor@*
> +Boston, MA 02110-1301, USA@*
Would be good to copy the expanded GNU Press stuff from gcc.texi.
> +The @command{gdc} command is a frontend to @command{gcc} and supports many
> +of the same options.
A bit pedantic, but I think this should be something like:
The @command{gdc} command is the GNU compiler for the D language and
supports many of the same options as @command{gcc}.
> +@menu
> +* Input and Output files:: Controlling the kind of output:
> + an executable, object files, assembler files,
> +* Runtime Options:: Options controlling runtime behaviour
"behavior"
> +* Directory Options:: Where to find module files
> +* Code Generation:: Options controlling the output of gdc
> +* Warnings:: Options controlling warnings specific to gdc
> +* Linking:: Options influceing the linking step
"influencing"
> +* Developer Options:: Options you won't use
Don't know if this came from an earlier version of the main GCC manual,
but it seems a bit off-message for the FSF. Something boring like:
Options useful for developers of gdc
might be better.
> +For any given input file, the file name suffix determines what kind of
> +compilation is done. The following kinds of input file names are supported:
> +
> +@table @gcctabopt
> +@item @var{file}.d
> +D source files.
> +@item @var{file}.dd
> +Ddoc source files.
> +@item @var{file}.di
> +D interface files.
> +@end table
> +
> +You can specify more than one input file on the @command{gdc} command line,
> +in which case they will all be compiled. If you specify a
The documentation convention is to avoid the future tense for things
like this. s/will all be/are all/ doesn't read very naturally so it
might need to be reworded.
> +@code{-o @var{file}} option, all the input files will be compiled together,
Same here.
> +@item -fno-bounds-check
> +@cindex @option{-fbounds-check}
> +@cindex @option{-fno-bounds-check}
> +Turns off array bounds checking for all functions, which can improve
> +performance for code that uses array extensively. Note that this
"uses arrays extensively"? Or maybe some markup is missing from "array".
> +can result in unpredictable behavior if the code in question actually
> +does violate array bounds constraints. It is safe to use this option
> +if you are sure that your code will never throw a @code{RangeError}.
s/will never throw/never throws/
> +@item -fno-builtin
> +@cindex @option{-fbuiltin}
> +@cindex @option{-fno-builtin}
> +Don't recognize built-in functions that do not begin with
> +@samp{__builtin_} as prefix. By default, the compiler will recognize
> +when a function in the @code{core.stdc} package is a built-in function.
maybe "unless they begin with the prefix @samp{__builtin_}"?
s/will recognize/recognizes/
> +@table @samp
> +@item level
> +@cindex @option{-fdebug=level}
> +Sets the debug level to @var{level}, any @code{debug} code <= @var{level}
> +is compiled into the program.
> +@item ident
> +@cindex @option{-fdebug=ident}
> +Turns on compilation of any @code{debug} code identified by @var{ident}.
> +@end table
Should be @var rather than @samp in the @table. Also @var{...} in
the @option{...}s.
> +@item -fno-moduleinfo
> +@cindex @option{-fmoduleinfo}
> +@cindex @option{-fno-moduleinfo}
> +Turns off generation of the @code{ModuleInfo} and related functions
> +that would become unreferenced without it, which may allow linking
> +to programs not written in D. Functions that will not be generated
s/will not be/are not/
> +include module constructor and destructors (@code{static this} and
s/constructor/constructors/? Or is there only one of each, in which
case maybe "the module constructor and destructor".
> +@item -frelease
> +@cindex @option{-frelease}
> +@cindex @option{-fno-release}
> +Turns on compiling in release mode, which means not emitting runtime
> +checks for contracts and asserts. Array bounds checking is not done
> +for @code{@@system} and @code{@@trusted} functions, and assertion
> +failures are undefined behaviour.
"behavior"
> +This is equivalent to compiling with the following options:
> +
> +@example
> +gdc -fno-assert -fbounds-check=safe -fno-invariants \
> + -fno-postconditions -fno-preconditions -fno-switch-errors
> +@end example
> +
> +@item -fno-switch-errors
> +@cindex @option{-fswitch-errors}
> +@cindex @option{-fno-switch-errors}
> +This option controls what code should be generated when no case is
s/should be/is/
> +matched in a @code{final switch} statement. The default run time
> +behavior is that a @code{SwitchError} will be thrown. Turning off
"is to throw a @code{SwitchError}"
> +@item -fversion=@var{value}
> +@cindex @option{-fversion}
> +Turns on compilation of conditional @code{version} code into the program
> +identified by any of the following values:
> +
> +@table @samp
> +@item level
> +@cindex @option{-fversion=level}
> +Sets the version level to @var{level}, any @code{version} code >= @var{level}
> +is compiled into the program.
> +@item ident
> +@cindex @option{-fversion=ident}
> +Turns on compilation of @code{version} code identified by @var{ident}.
> +@end table
Same comments as above about @var{}.
> +
> +@item -fno-weak
> +@cindex @option{-fweak}
> +@cindex @option{-fno-weak}
> +Turns off emission of instantiated declarations that can be defined in
> multiple
> +objects as weak or one-only symbols. The default is to emit all public
> symbols
> +as weak, unless there lacks target support. Disabling this options means
> that
> +common symbols are instead put in COMDAT or become private.
Maybe "unless the target lacks support for weak symbols"?
> +@item -J@var{dir}
> +@cindex @option{-J}
> +Specify a directory to use when searching for files in string imports
> +at compile time. This switch is required in order to use
> +@code{import(file)} expressions. Multiple @option{-J} options can be
> +used, and the paths are searched in the same order.
Should this be @var{file}?
> +@item -fmodule-file=@var{module}=@var{spec}
> +@cindex @option{-fmodule-file}
> +This option manipulates file paths of imported modules, such that if an
> +imported module matches all or the leftmost part of @var{module}, the file
> +path in @var{spec} is used as the location to search for D sources.
> +This is used when the source file path and names are not the same as the
> +package and module hierachy. Consider the following examples:
"hierarchy"
> +@item -imultilib @var{dir}
> +@cindex @option{-imultilib}
> +Use @var{dir} as a subdirectory of the gcc directory containing
> +target-specific D sources and interfaces.
Which gcc directory does this mean?
> +@item -iprefix @var{prefix}
> +@cindex @option{-iprefix}
> +Specify @var{prefix} as the prefix for the gcc directory containing
> +target-specific D sources and interfaces. If the @var{prefix} represents
> +a directory, you should include the final @code{'/'}.
Same here. What does a prefix without the "/" mean here? It doesn't
seem from the docs that it acts with a -iwithprefix option.
> +@item -nostdinc
> +@cindex @option{-nostdinc}
> +Do not search the standard system directories for D source and interface
> +files. Only the directories that have been specified with @option{-I}
> options
> +(and the directory of the current file, if appropriate) are searched.
When's that appropriate for D?
> +@item -H
> +@cindex @option{-H}
> +Generates D interface files for all modules being compiled. The compiler
> +determines the output @var{file} based on the name of the input file,
> +removes any directory components and suffix, and applies the @file{.di}
> +suffix.
Marking up @var{file} looks odd here, since nothing else refers to it.
> +@item -Hd @var{dir}
> +@cindex @option{-Hd}
> +Same as @option{-H}, but writes interface files to @var{dir} directory.
"directory @var{dir}"?
> +@item -MD
> +@cindex @option{-MD}
> +This option is equivalent to @option{-M -MF @var{file}}. The driver
> +determines @var{file} based on the name of the input file, removes any
> +directory components and suffix, and applies a @file{.deps} suffix.
This sounded at first like the driver removes the components after
determining @var{file}, whereas I'm guessing that's how it determines
@var{file}. Maybe something like:
determines @var{file} by removing any directory components and suffix
from the input file and then adding a @file{.deps} suffix.
if so?
> +@item -X
> +@cindex @option{-X}
> +Output information describing the contents of all source files being
> +compiled in JSON format to a file. The driver determines @var{file} based
> +on the name of the input file, removes any directory components and suffix,
> +and applies a @file{.json} suffix.
Same sort of thing here.
> +@item -fdoc
> +@cindex @option{-fdoc}
> +Generates @code{Ddoc} documentation and writes to a file. The compiler
> +determines @var{file} based on the name of the input file, removes any
> +directory components and suffix, and applies a @file{.html} suffix.
Here too. "writes it"?
> +@item -fdoc-dir=@var{dir}
> +@cindex @option{-fdoc-dir}
> +Same as @option{-fdoc}, but writes documentation to @var{dir} directory.
"directory @var{dir}"?
> +@item -Wall
> +@cindex @option{-Wall}
> +@cindex @option{-Wno-all}
> +Turns on all warnings messages. Warnings are not a defined part of
> +the D language, and all constructs for which this may generate a
> +warning message are legal code.
"valid code". But I assume this is "all" in the same way that it's
"all" for C and C++? Might be better to use something like the
invoke.texi entry, which says:
This enables all the warnings about constructions that some users
consider questionable, and that are easy to avoid (or modify to
prevent the warning), even in conjunction with macros.
> +@item -Wspeculative
> +@cindex @option{-Wspeculative}
> +@cindex @option{-Wno-speculative}
> +Report on all error messages from speculative compiles, such as
> +@code{__traits(compiles, ...)}. This option does not report
> +messages as warnings, and these messages therefore never become
> +errors when the @option{-Werror} option is also used.
"Report on all error messages" sounds a bit odd.
> +@item -Wunknown-pragmas
> +@cindex @option{-Wunknown-pragmas}
> +@cindex @option{-Wno-unknown-pragmas}
> +Warn when a @code{pragma()} is encountered that is not understood by
> +@command{gdc}. This differs from @option{-fignore-unknown-pragmas}
> +where a pragma that is part of the D language, but not implemented by
> +the compiler, will not get reported.
Future tense.
> +@item -fsyntax-only
> +@cindex @option{-fsyntax-only}
> +@cindex @option{-fno-syntax-only}
> +Check the code for syntax errors, but do not actually compile it. This
> +only suppresses the generation of the object code, and can be used in
> +conjunction with @option{-fdoc} or @option{-H} options.
"object code" might be confusing since I assume we wouldn't generate
assembly code either.
> +These options come into play when the compiler links object files into an
> +executable output file. They are meaningless if the compiler is not doing
> +a link step.
Two spaces before "They".
> +@item -fdump-d-original
> +@cindex @option{-fdump-d-original}
> +Dump the front-end AST after after parsing and running semantic on
> +the source program. Only really useful for debugging the compiler
> +itself.
"after running semantic" sounds odd. Based on -v, maybe "after the
@code{semantic} stage", if that's what it means?
Looks OK otherwise.
Thanks,
Richard
