From patchwork Wed Nov 30 21:39:49 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Iain Buclaw X-Patchwork-Id: 61282 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 618A63858281 for ; Wed, 30 Nov 2022 21:40:29 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 618A63858281 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1669844429; bh=m0tBt9LiF6Y73hqxxKkvG48KcMUvhe1wavKCVi9W6zM=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=cH+lRzrTnOEtwXP9jcQXm5KOxA9/5F0YgBn3DcZORiXx6sItqoU/SdIPaHCdlp5Rg BZlI3z/AXAg4MVRVfdbmE8OokRtJwN+MamvIZspm194kuo+1/Nq129yd//Q7iukX/E 7n//JyOKM67GIddhUmtIYdu6mntjy/RiQG4DQsWY= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [IPv6:2001:67c:2050:0:465::101]) by sourceware.org (Postfix) with ESMTPS id AFA943858D37 for ; Wed, 30 Nov 2022 21:39:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org AFA943858D37 Received: from smtp2.mailbox.org (smtp2.mailbox.org [IPv6:2001:67c:2050:b231:465::2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4NMt0C1kR6z9sV0; Wed, 30 Nov 2022 22:39:55 +0100 (CET) To: gcc-patches@gcc.gnu.org Cc: Iain Buclaw Subject: [committed] d: Separate documentation indices into options and keywords. Date: Wed, 30 Nov 2022 22:39:49 +0100 Message-Id: <20221130213949.547614-1-ibuclaw@gdcproject.org> MIME-Version: 1.0 X-Rspamd-Queue-Id: 4NMt0C1kR6z9sV0 X-Spam-Status: No, score=-13.5 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Iain Buclaw via Gcc-patches From: Iain Buclaw Reply-To: Iain Buclaw Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" Hi, This patch separates indexes at the end of the gdc documentation into an Options index and Keyword index, as per documentation manuals in other front-ends. Tested by building and checking pdf/info/man/html pages, and committed to mainline. Regards, Iain. --- gcc/d/ChangeLog: * gdc.texi: Separate indices into options and keywords. --- gcc/d/gdc.texi | 225 ++++++++++++++++++++++++++----------------------- 1 file changed, 118 insertions(+), 107 deletions(-) diff --git a/gcc/d/gdc.texi b/gcc/d/gdc.texi index 6ceb2cc67aa..45dc544e83f 100644 --- a/gcc/d/gdc.texi +++ b/gcc/d/gdc.texi @@ -2,6 +2,8 @@ @setfilename gdc.info @settitle The GNU D Compiler +@c Create a separate index for command line options +@defcodeindex op @c Merge the standard indexes into a single one. @syncodeindex fn cp @syncodeindex vr cp @@ -69,19 +71,14 @@ language in general, including language specifications and standard package documentation, see @uref{https://dlang.org/}. @menu +* Invoking gdc:: How to run gdc. * Copying:: The GNU General Public License. * GNU Free Documentation License:: How you can share and copy this manual. -* Invoking gdc:: How to run gdc. -* Index:: Index. +* Option Index:: Index of command line options. +* Keyword Index:: Index of concepts. @end menu - -@include gpl_v3.texi - -@include fdl.texi - - @node Invoking gdc @chapter Invoking gdc @@ -173,21 +170,21 @@ These options affect the runtime behavior of programs compiled with @table @gcctabopt @item -fall-instantiations -@cindex @option{-fall-instantiations} -@cindex @option{-fno-all-instantiations} +@opindex fall-instantiations +@opindex fno-all-instantiations Generate code for all template instantiations. The default template emission strategy is to not generate code for declarations that were either instantiated speculatively, such as from @code{__traits(compiles, ...)}, or that come from an imported module not being compiled. @item -fno-assert -@cindex @option{-fassert} -@cindex @option{-fno-assert} +@opindex fassert +@opindex fno-assert Turn off code generation for @code{assert} contracts. @item -fno-bounds-check -@cindex @option{-fbounds-check} -@cindex @option{-fno-bounds-check} +@opindex fbounds-check +@opindex fno-bounds-check Turns off array bounds checking for all functions, which can improve performance for code that uses arrays extensively. Note that this can result in unpredictable behavior if the code in question actually @@ -195,7 +192,7 @@ does violate array bounds constraints. It is safe to use this option if you are sure that your code never throws a @code{RangeError}. @item -fbounds-check=@var{value} -@cindex @option{-fbounds-check=} +@opindex fbounds-check= An alternative to @option{-fbounds-check} that allows more control as to where bounds checking is turned on or off. The following values are supported: @@ -210,14 +207,14 @@ Turns off array bounds checking completely. @end table @item -fno-builtin -@cindex @option{-fbuiltin} -@cindex @option{-fno-builtin} +@opindex fbuiltin +@opindex fno-builtin Don't recognize built-in functions unless they begin with the prefix @samp{__builtin_}. By default, the compiler will recognize when a function in the @code{core.stdc} package is a built-in function. @item -fcheckaction=@var{value} -@cindex @option{-fcheckaction} +@opindex fcheckaction This option controls what code is generated on an assertion, bounds check, or final switch failure. The following values are supported: @@ -232,8 +229,8 @@ Throw an @code{AssertError} (the default). @item -fdebug @item -fdebug=@var{value} -@cindex @option{-fdebug} -@cindex @option{-fno-debug} +@opindex fdebug +@opindex fno-debug Turn on compilation of conditional @code{debug} code into the program. The @option{-fdebug} option itself sets the debug level to @code{1}, while @option{-fdebug=} enables @code{debug} code that are identified @@ -245,8 +242,8 @@ Turns on compilation of any @code{debug} code identified by @var{ident}. @end table @item -fno-druntime -@cindex @option{-fdruntime} -@cindex @option{-fno-druntime} +@opindex fdruntime +@opindex fno-druntime Implements @uref{https://dlang.org/spec/betterc.html}. Assumes that compilation targets an environment without a D runtime library. @@ -257,7 +254,7 @@ gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti @end example @item -fextern-std=@var{standard} -@cindex @option{-fextern-std} +@opindex fextern-std Sets the C++ name mangling compatibility to the version identified by @var{standard}. The following values are supported: @@ -277,20 +274,20 @@ Sets @code{__traits(getTargetInfo, "cppStd")} to @code{202002}. @end table @item -fno-invariants -@cindex @option{-finvariants} -@cindex @option{-fno-invariants} +@opindex finvariants +@opindex fno-invariants Turns off code generation for class @code{invariant} contracts. @item -fmain -@cindex @option{-fmain} +@opindex fmain Generates a default @code{main()} function when compiling. This is useful when unittesting a library, as it enables running the unittests in a library without having to manually define an entry-point function. This option does nothing when @code{main} is already defined in user code. @item -fno-moduleinfo -@cindex @option{-fmoduleinfo} -@cindex @option{-fno-moduleinfo} +@opindex fmoduleinfo +@opindex 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 are not be generated @@ -299,23 +296,23 @@ include module constructors and destructors (@code{static this} and functions for dynamically linked code. @item -fonly=@var{filename} -@cindex @option{-fonly} +@opindex fonly Tells the compiler to parse and run semantic analysis on all modules on the command line, but only generate code for the module specified by @var{filename}. @item -fno-postconditions -@cindex @option{-fpostconditions} -@cindex @option{-fno-postconditions} +@opindex fpostconditions +@opindex fno-postconditions Turns off code generation for postcondition @code{out} contracts. @item -fno-preconditions -@cindex @option{-fpreconditions} -@cindex @option{-fno-preconditions} +@opindex fpreconditions +@opindex fno-preconditions Turns off code generation for precondition @code{in} contracts. @item -fpreview=@var{id} -@cindex @option{-fpreview} +@opindex fpreview Turns on an upcoming D language change identified by @var{id}. The following values are supported: @@ -361,8 +358,8 @@ Disables access to variables marked @code{@@system} from @code{@@safe} code. @end table @item -frelease -@cindex @option{-frelease} -@cindex @option{-fno-release} +@opindex frelease +@opindex 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 @@ -376,7 +373,7 @@ gdc -fno-assert -fbounds-check=safe -fno-invariants \ @end example @item -frevert= -@cindex @option{-frevert} +@opindex frevert Turns off a D language feature identified by @var{id}. The following values are supported: @@ -397,28 +394,28 @@ expressions. @end table @item -fno-rtti -@cindex @option{-frtti} -@cindex @option{-fno-rtti} +@opindex frtti +@opindex fno-rtti Turns off generation of run-time type information for all user defined types. Any code that uses features of the language that require access to this information will result in an error. @item -fno-switch-errors -@cindex @option{-fswitch-errors} -@cindex @option{-fno-switch-errors} +@opindex fswitch-errors +@opindex fno-switch-errors This option controls what code is generated when no case is matched in a @code{final switch} statement. The default run time behavior is to throw a @code{SwitchError}. Turning off @option{-fswitch-errors} means that instead the execution of the program is immediately halted. @item -funittest -@cindex @option{-funittest} -@cindex @option{-fno-unittest} +@opindex funittest +@opindex fno-unittest Turns on compilation of @code{unittest} code, and turns on the @code{version(unittest)} identifier. This implies @option{-fassert}. @item -fversion=@var{value} -@cindex @option{-fversion} +@opindex fversion Turns on compilation of conditional @code{version} code into the program identified by any of the following values: @@ -428,8 +425,8 @@ Turns on compilation of @code{version} code identified by @var{ident}. @end table @item -fno-weak-templates -@cindex @option{-fweak-templates} -@cindex @option{-fno-weak-templates} +@opindex fweak-templates +@opindex fno-weak-templates Turns off emission of declarations that can be defined in multiple objects as weak symbols. The default is to emit all public symbols as weak, unless the target lacks support for weak symbols. Disabling this option means that common @@ -449,29 +446,29 @@ other parts of the compiler: @table @gcctabopt @item -I@var{dir} -@cindex @option{-I} +@opindex I Specify a directory to use when searching for imported modules at compile time. Multiple @option{-I} options can be used, and the paths are searched in the same order. @item -J@var{dir} -@cindex @option{-J} +@opindex 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. @item -L@var{dir} -@cindex @option{-L} +@opindex L When linking, specify a library search directory, as with @command{gcc}. @item -B@var{dir} -@cindex @option{-B} +@opindex B This option specifies where to find the executables, libraries, source files, and data files of the compiler itself, as with @command{gcc}. @item -fmodule-file=@var{module}=@var{spec} -@cindex @option{-fmodule-file} +@opindex 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. @@ -494,18 +491,18 @@ import A.B.C; // No match, searches for A/B/C.d @end example @item -imultilib @var{dir} -@cindex @option{-imultilib} +@opindex imultilib Use @var{dir} as a subdirectory of the gcc directory containing target-specific D sources and interfaces. @item -iprefix @var{prefix} -@cindex @option{-iprefix} +@opindex 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{'/'}. @item -nostdinc -@cindex @option{-nostdinc} +@opindex 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. @@ -522,106 +519,106 @@ In addition to the many @command{gcc} options controlling code generation, @table @gcctabopt @item -H -@cindex @option{-H} +@opindex H Generates D interface files for all modules being compiled. The compiler determines the output file based on the name of the input file, removes any directory components and suffix, and applies the @file{.di} suffix. @item -Hd @var{dir} -@cindex @option{-Hd} +@opindex Hd Same as @option{-H}, but writes interface files to directory @var{dir}. This option can be used with @option{-Hf @var{file}} to independently set the output file and directory path. @item -Hf @var{file} -@cindex @option{-Hf} +@opindex Hf Same as @option{-H} but writes interface files to @var{file}. This option can be used with @option{-Hd @var{dir}} to independently set the output file and directory path. @item -M -@cindex @option{-M} +@opindex M Output the module dependencies of all source files being compiled in a format suitable for @command{make}. The compiler outputs one @command{make} rule containing the object file name for that source file, a colon, and the names of all imported files. @item -MM -@cindex @option{-MM} +@opindex MM Like @option{-M} but does not mention imported modules from the D standard library package directories. @item -MF @var{file} -@cindex @option{-MF} +@opindex MF When used with @option{-M} or @option{-MM}, specifies a @var{file} to write the dependencies to. When used with the driver options @option{-MD} or @option{-MMD}, @option{-MF} overrides the default dependency output file. @item -MG -@cindex @option{-MG} +@opindex MG This option is for compatibility with @command{gcc}, and is ignored by the compiler. @item -MP -@cindex @option{-MP} +@opindex MP Outputs a phony target for each dependency other than the modules being compiled, causing each to depend on nothing. @item -MT @var{target} -@cindex @option{-MT} +@opindex MT Change the @var{target} of the rule emitted by dependency generation to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to @option{-MT}, or use multiple @option{-MT} options. @item -MQ @var{target} -@cindex @option{-MQ} +@opindex MQ Same as @option{-MT}, but it quotes any characters which are special to @command{make}. @item -MD -@cindex @option{-MD} +@opindex MD This option is equivalent to @option{-M -MF @var{file}}. The driver determines @var{file} by removing any directory components and suffix from the input file, and then adding a @file{.deps} suffix. @item -MMD -@cindex @option{-MMD} +@opindex MMD Like @option{-MD} but does not mention imported modules from the D standard library package directories. @item -X -@cindex @option{-X} +@opindex X Output information describing the contents of all source files being compiled in JSON format to a file. The driver determines @var{file} by removing any directory components and suffix from the input file, and then adding a @file{.json} suffix. @item -Xf @var{file} -@cindex @option{-Xf} +@opindex Xf Same as @option{-X}, but writes all JSON contents to the specified @var{file}. @item -fdoc -@cindex @option{-fdoc} +@opindex fdoc Generates @code{Ddoc} documentation and writes it to a file. The compiler determines @var{file} by removing any directory components and suffix from the input file, and then adding a @file{.html} suffix. @item -fdoc-dir=@var{dir} -@cindex @option{-fdoc-dir} +@opindex fdoc-dir Same as @option{-fdoc}, but writes documentation to directory @var{dir}. This option can be used with @option{-fdoc-file=@var{file}} to independently set the output file and directory path. @item -fdoc-file=@var{file} -@cindex @option{-fdoc-file} +@opindex fdoc-file Same as @option{-fdoc}, but writes documentation to @var{file}. This option can be used with @option{-fdoc-dir=@var{dir}} to independently set the output file and directory path. @item -fdoc-inc=@var{file} -@cindex @option{-fdoc-inc} +@opindex fdoc-inc Specify @var{file} as a @var{Ddoc} macro file to be read. Multiple @option{-fdoc-inc} options can be used, and files are read and processed in the same order. @@ -634,7 +631,7 @@ In conjunction with @option{-fdump-c++-spec=} above, add comments for ignored declarations in the generated C++ header. @item -fsave-mixins=@var{file} -@cindex @option{-fsave-mixins} +@opindex fsave-mixins Generates code expanded from D @code{mixin} statements and writes the processed sources to @var{file}. This is useful to debug errors in compilation and provides source for debuggers to show when requested. @@ -658,19 +655,19 @@ specified, they do not prevent compilation of the program. @table @gcctabopt @item -Wall -@cindex @option{-Wall} -@cindex @option{-Wno-all} +@opindex Wall +@opindex 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 valid code. @item -Walloca -@cindex @option{-Walloca} +@opindex Walloca This option warns on all uses of "alloca" in the source. @item -Walloca-larger-than=@var{n} -@cindex @option{-Walloca-larger-than} -@cindex @option{-Wno-alloca-larger-than} +@opindex Walloca-larger-than +@opindex Wno-alloca-larger-than Warn on unbounded uses of alloca, and on bounded uses of alloca whose bound can be larger than @var{n} bytes. @option{-Wno-alloca-larger-than} disables @@ -678,72 +675,72 @@ whose bound can be larger than @var{n} bytes. @option{-Walloca-larger-than=@var{SIZE_MAX}} or larger. @item -Wno-builtin-declaration-mismatch -@cindex @option{-Wno-builtin-declaration-mismatch} -@cindex @option{-Wbuiltin-declaration-mismatch} +@opindex Wno-builtin-declaration-mismatch +@opindex Wbuiltin-declaration-mismatch Warn if a built-in function is declared with an incompatible signature. @item -Wcast-result -@cindex @option{-Wcast-result} -@cindex @option{-Wno-cast-result} +@opindex Wcast-result +@opindex Wno-cast-result Warn about casts that will produce a null or zero result. Currently this is only done for casting between an imaginary and non-imaginary data type, or casting between a D and C++ class. @item -Wno-deprecated -@cindex @option{-Wdeprecated} -@cindex @option{-Wno-deprecated} +@opindex Wdeprecated +@opindex Wno-deprecated Do not warn about usage of deprecated features and symbols with @code{deprecated} attributes. @item -Werror -@cindex @option{-Werror} -@cindex @option{-Wno-error} +@opindex Werror +@opindex Wno-error Turns all warnings into errors. @item -Wspeculative -@cindex @option{-Wspeculative} -@cindex @option{-Wno-speculative} +@opindex Wspeculative +@opindex Wno-speculative List 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. @item -Wunknown-pragmas -@cindex @option{-Wunknown-pragmas} -@cindex @option{-Wno-unknown-pragmas} +@opindex Wunknown-pragmas +@opindex 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, won't get reported. @item -Wno-varargs -@cindex Wvarargs -@cindex Wno-varargs +@opindex Wvarargs +@opindex Wno-varargs Do not warn upon questionable usage of the macros used to handle variable arguments like @code{va_start}. @item -fignore-unknown-pragmas -@cindex @option{-fignore-unknown-pragmas} -@cindex @option{-fno-ignore-unknown-pragmas} +@opindex fignore-unknown-pragmas +@opindex fno-ignore-unknown-pragmas Turns off errors for unsupported pragmas. @item -fmax-errors=@var{n} -@cindex @option{-fmax-errors} +@opindex fmax-errors Limits the maximum number of error messages to @var{n}, at which point @command{gdc} bails out rather than attempting to continue processing the source code. If @var{n} is 0 (the default), there is no limit on the number of error messages produced. @item -fsyntax-only -@cindex @option{-fsyntax-only} -@cindex @option{-fno-syntax-only} +@opindex fsyntax-only +@opindex fno-syntax-only Check the code for syntax errors, but do not actually compile it. This can be used in conjunction with @option{-fdoc} or @option{-H} to generate files for each module present on the command-line, but no other output file. @item -ftransition=@var{id} -@cindex @option{-ftransition} +@opindex ftransition Report additional information about D language changes identified by @var{id}. The following values are supported: @@ -778,34 +775,34 @@ a link step. @table @gcctabopt @item -defaultlib=@var{libname} -@cindex @option{-defaultlib=} +@opindex defaultlib= Specify the library to use instead of libphobos when linking. Options specifying the linkage of libphobos, such as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored. @item -debuglib=@var{libname} -@cindex @option{-debuglib=} +@opindex debuglib= Specify the debug library to use instead of libphobos when linking. This option has no effect unless the @option{-g} option was also given on the command line. Options specifying the linkage of libphobos, such as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored. @item -nophoboslib -@cindex @option{-nophoboslib} +@opindex nophoboslib Do not use the Phobos or D runtime library when linking. Options specifying the linkage of libphobos, such as @option{-static-libphobos} or @option{-shared-libphobos}, are ignored. The standard system libraries are used normally, unless @option{-nostdlib} or @option{-nodefaultlibs} is used. @item -shared-libphobos -@cindex @option{-shared-libphobos} +@opindex shared-libphobos On systems that provide @file{libgphobos} and @file{libgdruntime} as a shared and a static library, this option forces the use of the shared version. If no shared version was built when the compiler was configured, this option has no effect. @item -static-libphobos -@cindex @option{-static-libphobos} +@opindex static-libphobos On systems that provide @file{libgphobos} and @file{libgdruntime} as a shared and a static library, this option forces the use of the static version. If no static version was built when the compiler was configured, @@ -825,12 +822,12 @@ interest to developers or language tooling. @table @gcctabopt @item -fdump-d-original -@cindex @option{-fdump-d-original} +@opindex fdump-d-original Output the internal front-end AST after the @code{semantic3} stage. This option is only useful for debugging the GNU D compiler itself. @item -v -@cindex @option{-v} +@opindex v Dump information about the compiler language processing stages as the source program is being compiled. This includes listing all modules that are processed through the @code{parse}, @code{semantic}, @code{semantic2}, and @@ -841,8 +838,22 @@ and all @code{function} bodies that are being compiled. @c man end -@node Index -@unnumbered Index +@include gpl_v3.texi +@include fdl.texi + +@node Option Index +@unnumbered Option Index + +@command{gdc}'s command line options are indexed here without any initial +@samp{-} or @samp{--}. Where an option has both positive and negative forms +(such as @option{-f@var{option}} and @option{-fno-@var{option}}), relevant +entries in the manual are indexed under the most appropriate form; it may +sometimes be useful to look up both forms. + +@printindex op + +@node Keyword Index +@unnumbered Keyword Index @printindex cp