sphinx: copy files from texi2rst-generated repository

ChangeLog:

	* doc/Makefile: New file.
	* doc/_static/custom.css: New file.
	* doc/baseconf.py: New file.
	* doc/bsd.rst: New file.
	* doc/contrib.rst: New file.
	* doc/contribute.rst: New file.
	* doc/cppdiropts.rst: New file.
	* doc/cppenv.rst: New file.
	* doc/cppopts.rst: New file.
	* doc/cppwarnopts.rst: New file.
	* doc/favicon.ico: New file.
	* doc/funding.rst: New file.
	* doc/gcc_sphinx.py: New file.
	* doc/gnu.rst: New file.
	* doc/gnu_free_documentation_license.rst: New file.
	* doc/gpl-3.0.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/lgpl-2.1.rst: New file.
	* doc/logo.pdf: New file.
	* doc/logo.svg: New file.
	* doc/md.rst: New file.
	* doc/requirements.txt: New file.

gcc/d/ChangeLog:

	* doc/conf.py: New file.
	* doc/copyright.rst: New file.
	* doc/general-public-license-3.rst: New file.
	* doc/gnu-free-documentation-license.rst: New file.
	* doc/index.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/invoking-gdc.rst: New file.
	* doc/invoking-gdc/code-generation.rst: New file.
	* doc/invoking-gdc/developer-options.rst: New file.
	* doc/invoking-gdc/input-and-output-files.rst: New file.
	* doc/invoking-gdc/options-for-directory-search.rst: New file.
	* doc/invoking-gdc/options-for-linking.rst: New file.
	* doc/invoking-gdc/runtime-options.rst: New file.
	* doc/invoking-gdc/warnings.rst: New file.

gcc/ChangeLog:

	* doc/cpp/character-sets.rst: New file.
	* doc/cpp/conditional-syntax.rst: New file.
	* doc/cpp/conditional-uses.rst: New file.
	* doc/cpp/conditionals.rst: New file.
	* doc/cpp/conf.py: New file.
	* doc/cpp/copyright.rst: New file.
	* doc/cpp/deleted-code.rst: New file.
	* doc/cpp/diagnostics.rst: New file.
	* doc/cpp/environment-variables.rst: New file.
	* doc/cpp/gnu-free-documentation-license.rst: New file.
	* doc/cpp/header-files.rst: New file.
	* doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst: New file.
	* doc/cpp/header-files/computed-includes.rst: New file.
	* doc/cpp/header-files/include-operation.rst: New file.
	* doc/cpp/header-files/include-syntax.rst: New file.
	* doc/cpp/header-files/once-only-headers.rst: New file.
	* doc/cpp/header-files/search-path.rst: New file.
	* doc/cpp/header-files/system-headers.rst: New file.
	* doc/cpp/header-files/wrapper-headers.rst: New file.
	* doc/cpp/implementation-defined-behavior.rst: New file.
	* doc/cpp/implementation-details.rst: New file.
	* doc/cpp/implementation-limits.rst: New file.
	* doc/cpp/index.rst: New file.
	* doc/cpp/indices-and-tables.rst: New file.
	* doc/cpp/initial-processing.rst: New file.
	* doc/cpp/invocation.rst: New file.
	* doc/cpp/line-control.rst: New file.
	* doc/cpp/macros.rst: New file.
	* doc/cpp/macros/concatenation.rst: New file.
	* doc/cpp/macros/directives-within-macro-arguments.rst: New file.
	* doc/cpp/macros/function-like-macros.rst: New file.
	* doc/cpp/macros/macro-arguments.rst: New file.
	* doc/cpp/macros/macro-pitfalls.rst: New file.
	* doc/cpp/macros/object-like-macros.rst: New file.
	* doc/cpp/macros/predefined-macros.rst: New file.
	* doc/cpp/macros/stringizing.rst: New file.
	* doc/cpp/macros/undefining-and-redefining-macros.rst: New file.
	* doc/cpp/macros/variadic-macros.rst: New file.
	* doc/cpp/obsolete-features.rst: New file.
	* doc/cpp/other-directives.rst: New file.
	* doc/cpp/overview.rst: New file.
	* doc/cpp/pragmas.rst: New file.
	* doc/cpp/preprocessor-output.rst: New file.
	* doc/cpp/the-preprocessing-language.rst: New file.
	* doc/cpp/tokenization.rst: New file.
	* doc/cpp/traditional-lexical-analysis.rst: New file.
	* doc/cpp/traditional-macros.rst: New file.
	* doc/cpp/traditional-miscellany.rst: New file.
	* doc/cpp/traditional-mode.rst: New file.
	* doc/cpp/traditional-warnings.rst: New file.
	* doc/cppinternals/conf.py: New file.
	* doc/cppinternals/copyright.rst: New file.
	* doc/cppinternals/cppinternals.rst: New file.
	* doc/cppinternals/cpplib.rst: New file.
	* doc/cppinternals/files.rst: New file.
	* doc/cppinternals/index.rst: New file.
	* doc/cppinternals/indices-and-tables.rst: New file.
	* doc/cppinternals/internal-representation-of-macros.rst: New file.
	* doc/cppinternals/just-which-line-number-anyway.rst: New file.
	* doc/cppinternals/lexing-a-line.rst: New file.
	* doc/cppinternals/lexing-a-token.rst: New file.
	* doc/cppinternals/looking-for-a-function-like-macros-opening-parenthesis.rst: New file.
	* doc/cppinternals/macro-expansion-overview.rst: New file.
	* doc/cppinternals/marking-tokens-ineligible-for-future-expansion.rst: New file.
	* doc/cppinternals/multiple-include-optimization.rst: New file.
	* doc/cppinternals/overview.rst: New file.
	* doc/cppinternals/representation-of-line-numbers.rst: New file.
	* doc/cppinternals/scanning-the-replacement-list-for-macros-to-expand.rst: New file.
	* doc/gcc/binary-compatibility.rst: New file.
	* doc/gcc/c++-implementation-defined-behavior.rst: New file.
	* doc/gcc/c-implementation-defined-behavior.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/architecture.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/arrays-and-pointers.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/characters.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/declarators.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/environment.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/floating-point.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/hints.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/identifiers.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/integers.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/library-functions.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/locale-specific-behavior.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/preprocessing-directives.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/qualifiers.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/statements.rst: New file.
	* doc/gcc/c-implementation-defined-behavior/structures-unions-enumerations-and-bit-fields.rst:
	New file.
	* doc/gcc/c-implementation-defined-behavior/translation.rst: New file.
	* doc/gcc/conditionally-supported-behavior.rst: New file.
	* doc/gcc/conf.py: New file.
	* doc/gcc/contributing-to-gcc-development.rst: New file.
	* doc/gcc/contributors-to-gcc.rst: New file.
	* doc/gcc/copyright.rst: New file.
	* doc/gcc/exception-handling.rst: New file.
	* doc/gcc/extensions-to-the-c++-language.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/backwards-compatibility.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/c++-concepts.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/c++-interface-and-implementation-pragmas.rst:
	New file.
	* doc/gcc/extensions-to-the-c++-language/c++-specific-variable-function-and-type-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c++-language/deprecated-features.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/extracting-the-function-pointer-from-a-bound-pointer-to-member-function.rst:
	New file.
	* doc/gcc/extensions-to-the-c++-language/function-multiversioning.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/restricting-pointer-aliasing.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/type-traits.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/vague-linkage.rst: New file.
	* doc/gcc/extensions-to-the-c++-language/when-is-a-volatile-c++-object-accessed.rst:
	New file.
	* doc/gcc/extensions-to-the-c++-language/wheres-the-template.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/128-bit-integers.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/additional-floating-types.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/alternate-keywords.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/an-inline-function-is-as-fast-as-a-macro.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/arithmetic-on-void-and-function-pointers.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/arrays-of-length-zero.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/arrays-of-variable-length.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/attribute-syntax.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/binary-constants-using-the-0b-prefix.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/built-in-functions-for-memory-model-aware-atomic-operations.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/built-in-functions-to-perform-arithmetic-with-overflow-checking.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/c++-style-comments.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/case-ranges.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/cast-to-a-union-type.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/complex-numbers.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/compound-literals.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/conditionals-with-omitted-operands.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/constructing-function-calls.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/decimal-floating-types.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/aarch64-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/amd-gcn-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/arc-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/arm-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/avr-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/blackfin-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/bpf-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/c-sky-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/common-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/epiphany-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/h8-300-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/ia-64-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m32c-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m32r-d-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/m68k-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mcore-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mep-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microblaze-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microsoft-windows-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/mips-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/msp430-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nds32-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nios-ii-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/nvidia-ptx-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/powerpc-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/risc-v-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/rl78-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/rx-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/s-390-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/sh-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/symbian-os-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/v850-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/visium-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/x86-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/xstormy16-function-attributes.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/designated-initializers.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/determining-the-alignment-of-functions-types-or-variables.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/dollar-signs-in-identifier-names.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/double-word-integers.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/enumerator-attributes.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/fixed-point-types.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/format-checks-specific-to-particular-target-machines.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/function-names-as-strings.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/getting-the-return-or-frame-address-of-a-function.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/half-precision-floating-point.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/hex-floats.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/how-to-use-inline-assembly-language-in-c-code.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/incomplete-enum-types.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/label-attributes.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/labels-as-values.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/legacy-sync-built-in-functions-for-atomic-memory-access.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/locally-declared-labels.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/macros-with-a-variable-number-of-arguments.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/mixed-declarations-labels-and-code.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/named-address-spaces.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/nested-functions.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/non-constant-initializers.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/non-lvalue-arrays-may-have-subscripts.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/nonlocal-gotos.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/object-size-checking-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/other-built-in-functions-provided-by-gcc.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/pointer-arguments-in-variadic-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/pointers-to-arrays-with-qualifiers-work-as-expected.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/pragmas-accepted-by-gcc.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/prototypes-and-old-style-function-definitions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/referring-to-a-type-with-typeof.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/slightly-looser-rules-for-escaped-newlines.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/specifying-attributes-of-types.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/specifying-attributes-of-variables.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/statement-attributes.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/statements-and-declarations-in-expressions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/structures-with-no-members.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/support-for-offsetof.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/aarch64-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/alpha-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/altera-nios-ii-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/arc-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/arc-simd-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-armv8-m-security-extensions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-c-language-extensions-acle.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-floating-point-status-and-control-intrinsics.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/arm-iwmmxt-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/avr-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/basic-powerpc-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/blackfin-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/bpf-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/fr-v-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-dsp-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-loongson-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-paired-single-support.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/mips-simd-architecture-msa-support.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/msp430-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/nds32-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/other-mips-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/picochip-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-altivec-vsx-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-atomic-memory-operation-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-hardware-transactional-memory-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/powerpc-matrix-multiply-assist-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/pru-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/risc-v-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/rx-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/s-390-system-z-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/sh-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/sparc-vis-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/ti-c6x-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-control-flow-protection-intrinsics.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/target-builtins/x86-transactional-memory-intrinsics.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/the-character-esc-in-constants.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/thread-local-storage.rst: New file.
	* doc/gcc/extensions-to-the-c-language-family/unnamed-structure-and-union-fields.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/using-vector-instructions-through-built-in-functions.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/when-is-a-volatile-object-accessed.rst:
	New file.
	* doc/gcc/extensions-to-the-c-language-family/x86-specific-memory-model-extensions-for-transactional-memory.rst:
	New file.
	* doc/gcc/funding.rst: New file.
	* doc/gcc/gcc-command-options.rst: New file.
	* doc/gcc/gcc-command-options/c++-modules.rst: New file.
	* doc/gcc/gcc-command-options/compiling-c++-programs.rst: New file.
	* doc/gcc/gcc-command-options/description.rst: New file.
	* doc/gcc/gcc-command-options/environment-variables-affecting-gcc.rst: New file.
	* doc/gcc/gcc-command-options/gcc-developer-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/aarch64-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/adapteva-epiphany-options.rst:
	New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/amd-gcn-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/arc-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/arm-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/avr-mmcu.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/avr-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/blackfin-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/c-sky-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/c6x-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/cris-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/darwin-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/dec-alpha-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/ebpf-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/fr30-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/frv-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/ft32-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/gnu-linux-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/h8-300-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/hppa-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/ia-64-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/ibm-rs-6000-and-powerpc-options.rst:
	New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/lm32-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/loongarch-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/m32c-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/m32r-d-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/m680x0-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/mcore-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/mep-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/microblaze-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/mips-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/mmix-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/mn10300-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/moxie-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/msp430-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/nds32-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/nios-ii-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/nvidia-ptx-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/openrisc-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/options-for-system-v.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/pdp-11-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/picochip-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/powerpc-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/pru-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/risc-v-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/rl78-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/rx-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/s-390-and-zseries-options.rst:
	New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/score-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/sh-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/solaris-2-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/sparc-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/v850-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/vax-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/visium-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/vms-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/vxworks-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/x86-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/x86-windows-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/xstormy16-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/xtensa-options.rst: New file.
	* doc/gcc/gcc-command-options/machine-dependent-options/zseries-options.rst: New file.
	* doc/gcc/gcc-command-options/option-summary.rst: New file.
	* doc/gcc/gcc-command-options/options-controlling-c++-dialect.rst: New file.
	* doc/gcc/gcc-command-options/options-controlling-c-dialect.rst: New file.
	* doc/gcc/gcc-command-options/options-controlling-objective-c-and-objective-c++-dialects.rst:
	New file.
	* doc/gcc/gcc-command-options/options-controlling-the-kind-of-output.rst: New file.
	* doc/gcc/gcc-command-options/options-controlling-the-preprocessor.rst: New file.
	* doc/gcc/gcc-command-options/options-for-code-generation-conventions.rst: New file.
	* doc/gcc/gcc-command-options/options-for-debugging-your-program.rst: New file.
	* doc/gcc/gcc-command-options/options-for-directory-search.rst: New file.
	* doc/gcc/gcc-command-options/options-for-linking.rst: New file.
	* doc/gcc/gcc-command-options/options-that-control-optimization.rst: New file.
	* doc/gcc/gcc-command-options/options-that-control-static-analysis.rst: New file.
	* doc/gcc/gcc-command-options/options-to-control-diagnostic-messages-formatting.rst:
	New file.
	* doc/gcc/gcc-command-options/options-to-request-or-suppress-warnings.rst: New file.
	* doc/gcc/gcc-command-options/passing-options-to-the-assembler.rst: New file.
	* doc/gcc/gcc-command-options/program-instrumentation-options.rst: New file.
	* doc/gcc/gcc-command-options/specifying-subprocesses-and-the-switches-to-pass-to-them.rst:
	New file.
	* doc/gcc/gcc-command-options/using-precompiled-headers.rst: New file.
	* doc/gcc/gcc.rst: New file.
	* doc/gcc/gcov-dump.rst: New file.
	* doc/gcc/gcov-tool.rst: New file.
	* doc/gcc/gcov.rst: New file.
	* doc/gcc/gcov/brief-description-of-gcov-data-files.rst: New file.
	* doc/gcc/gcov/data-file-relocation-to-support-cross-profiling.rst: New file.
	* doc/gcc/gcov/introduction-to-gcov.rst: New file.
	* doc/gcc/gcov/invoking-gcov.rst: New file.
	* doc/gcc/gcov/profiling-and-test-coverage-in-freestanding-environments.rst: New file.
	* doc/gcc/gcov/using-gcov-with-gcc-optimization.rst: New file.
	* doc/gcc/general-public-license-3.rst: New file.
	* doc/gcc/gnu-free-documentation-license.rst: New file.
	* doc/gcc/gnu-objective-c-features.rst: New file.
	* doc/gcc/gnu-objective-c-features/compatibilityalias.rst: New file.
	* doc/gcc/gnu-objective-c-features/constant-string-objects.rst: New file.
	* doc/gcc/gnu-objective-c-features/exceptions.rst: New file.
	* doc/gcc/gnu-objective-c-features/fast-enumeration.rst: New file.
	* doc/gcc/gnu-objective-c-features/garbage-collection.rst: New file.
	* doc/gcc/gnu-objective-c-features/gnu-objective-c-runtime-api.rst: New file.
	* doc/gcc/gnu-objective-c-features/load-executing-code-before-main.rst: New file.
	* doc/gcc/gnu-objective-c-features/messaging-with-the-gnu-objective-c-runtime.rst: New file.
	* doc/gcc/gnu-objective-c-features/synchronization.rst: New file.
	* doc/gcc/gnu-objective-c-features/type-encoding.rst: New file.
	* doc/gcc/gnu.rst: New file.
	* doc/gcc/have-you-found-a-bug.rst: New file.
	* doc/gcc/how-and-where-to-report-bugs.rst: New file.
	* doc/gcc/how-to-get-help-with-gcc.rst: New file.
	* doc/gcc/index.rst: New file.
	* doc/gcc/indices-and-tables.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/actual-bugs-we-havent-fixed-yet.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/certain-changes-we-dont-want-to-make.rst:
	New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/common-misunderstandings-with-gnu-c.rst:
	New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/disappointments-and-misunderstandings.rst:
	New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/fixed-header-files.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/incompatibilities-of-gcc.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/interoperation.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/standard-libraries.rst: New file.
	* doc/gcc/known-causes-of-trouble-with-gcc/warning-messages-and-error-messages.rst:
	New file.
	* doc/gcc/language-standards-supported-by-gcc.rst: New file.
	* doc/gcc/language-standards-supported-by-gcc/c++-language.rst: New file.
	* doc/gcc/language-standards-supported-by-gcc/c-language.rst: New file.
	* doc/gcc/language-standards-supported-by-gcc/d-language.rst: New file.
	* doc/gcc/language-standards-supported-by-gcc/go-language.rst: New file.
	* doc/gcc/language-standards-supported-by-gcc/objective-c-and-objective-c++-languages.rst:
	New file.
	* doc/gcc/language-standards-supported-by-gcc/references-for-other-languages.rst: New file.
	* doc/gcc/lto-dump.rst: New file.
	* doc/gcc/programming-languages-supported-by-gcc.rst: New file.
	* doc/gcc/reporting-bugs.rst: New file.
	* doc/gccint/analysis-and-optimization-of-gimple-tuples.rst: New file.
	* doc/gccint/analysis-and-optimization-of-gimple-tuples/alias-analysis.rst: New file.
	* doc/gccint/analysis-and-optimization-of-gimple-tuples/annotations.rst: New file.
	* doc/gccint/analysis-and-optimization-of-gimple-tuples/memory-model.rst: New file.
	* doc/gccint/analysis-and-optimization-of-gimple-tuples/ssa-operands.rst: New file.
	* doc/gccint/analysis-and-optimization-of-gimple-tuples/static-single-assignment.rst:
	New file.
	* doc/gccint/analysis-and-representation-of-loops.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/data-dependency-analysis.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/iv-analysis-on-rtl.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/loop-closed-ssa-form.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/loop-manipulation.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/loop-querying.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/loop-representation.rst: New file.
	* doc/gccint/analysis-and-representation-of-loops/number-of-iterations-analysis.rst:
	New file.
	* doc/gccint/analysis-and-representation-of-loops/scalar-evolutions.rst: New file.
	* doc/gccint/analyzer-internals.rst: New file.
	* doc/gccint/collect2.rst: New file.
	* doc/gccint/conf.py: New file.
	* doc/gccint/contributing-to-gcc-development.rst: New file.
	* doc/gccint/contributors-to-gcc.rst: New file.
	* doc/gccint/control-flow-graph.rst: New file.
	* doc/gccint/control-flow-graph/basic-blocks.rst: New file.
	* doc/gccint/control-flow-graph/edges.rst: New file.
	* doc/gccint/control-flow-graph/liveness-information.rst: New file.
	* doc/gccint/control-flow-graph/maintaining-the-cfg.rst: New file.
	* doc/gccint/control-flow-graph/profile-information.rst: New file.
	* doc/gccint/copyright.rst: New file.
	* doc/gccint/debugging-the-analyzer.rst: New file.
	* doc/gccint/funding.rst: New file.
	* doc/gccint/gcc-and-portability.rst: New file.
	* doc/gccint/general-public-license-3.rst: New file.
	* doc/gccint/generic.rst: New file.
	* doc/gccint/generic/attributes-in-trees.rst: New file.
	* doc/gccint/generic/c-and-c++-trees.rst: New file.
	* doc/gccint/generic/declarations.rst: New file.
	* doc/gccint/generic/deficiencies.rst: New file.
	* doc/gccint/generic/expressions.rst: New file.
	* doc/gccint/generic/functions.rst: New file.
	* doc/gccint/generic/language-dependent-trees.rst: New file.
	* doc/gccint/generic/overview.rst: New file.
	* doc/gccint/generic/statements.rst: New file.
	* doc/gccint/generic/types.rst: New file.
	* doc/gccint/gimple-api.rst: New file.
	* doc/gccint/gimple.rst: New file.
	* doc/gccint/gimple/adding-a-new-gimple-statement-code.rst: New file.
	* doc/gccint/gimple/class-hierarchy-of-gimple-statements.rst: New file.
	* doc/gccint/gimple/exception-handling.rst: New file.
	* doc/gccint/gimple/gimple-instruction-set.rst: New file.
	* doc/gccint/gimple/gimple-sequences.rst: New file.
	* doc/gccint/gimple/manipulating-gimple-statements.rst: New file.
	* doc/gccint/gimple/operands.rst: New file.
	* doc/gccint/gimple/sequence-iterators.rst: New file.
	* doc/gccint/gimple/statement-and-operand-traversals.rst: New file.
	* doc/gccint/gimple/temporaries.rst: New file.
	* doc/gccint/gimple/tuple-representation.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleasm.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleassign.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplebind.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplecall.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplecatch.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplecond.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpledebug.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleehfilter.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplegoto.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplelabel.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplenop.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompatomicload.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompatomicstore.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompcontinue.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompcritical.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompfor.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompmaster.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompordered.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompparallel.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompreturn.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompsection.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompsections.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleompsingle.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplephi.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleresx.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplereturn.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpleswitch.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimpletry.rst: New file.
	* doc/gccint/gimple/tuple-specific-accessors/gimplewithcleanupexpr.rst: New file.
	* doc/gccint/gnu-free-documentation-license.rst: New file.
	* doc/gccint/guidelines-for-diagnostics.rst: New file.
	* doc/gccint/guidelines-for-options.rst: New file.
	* doc/gccint/host-common.rst: New file.
	* doc/gccint/host-configuration.rst: New file.
	* doc/gccint/host-filesystem.rst: New file.
	* doc/gccint/host-makefile-fragments.rst: New file.
	* doc/gccint/host-misc.rst: New file.
	* doc/gccint/index.rst: New file.
	* doc/gccint/indices-and-tables.rst: New file.
	* doc/gccint/interfacing-to-gcc-output.rst: New file.
	* doc/gccint/introduction.rst: New file.
	* doc/gccint/language-front-ends-in-gcc.rst: New file.
	* doc/gccint/link-time-optimization.rst: New file.
	* doc/gccint/link-time-optimization/design-overview.rst: New file.
	* doc/gccint/link-time-optimization/internal-flags-controlling-lto1.rst: New file.
	* doc/gccint/link-time-optimization/lto-file-sections.rst: New file.
	* doc/gccint/link-time-optimization/using-summary-information-in-ipa-passes.rst: New file.
	* doc/gccint/link-time-optimization/whole-program-assumptions-linker-plugin-and-symbol-visibilities.rst:
	New file.
	* doc/gccint/machine-descriptions.rst: New file.
	* doc/gccint/machine-descriptions/c-statements-for-assembler-output.rst: New file.
	* doc/gccint/machine-descriptions/canonicalization-of-instructions.rst: New file.
	* doc/gccint/machine-descriptions/conditional-execution.rst: New file.
	* doc/gccint/machine-descriptions/constant-definitions.rst: New file.
	* doc/gccint/machine-descriptions/defining-how-to-split-instructions.rst: New file.
	* doc/gccint/machine-descriptions/defining-jump-instruction-patterns.rst: New file.
	* doc/gccint/machine-descriptions/defining-looping-instruction-patterns.rst: New file.
	* doc/gccint/machine-descriptions/defining-rtl-sequences-for-code-generation.rst: New file.
	* doc/gccint/machine-descriptions/everything-about-instruction-patterns.rst: New file.
	* doc/gccint/machine-descriptions/example-of-defineinsn.rst: New file.
	* doc/gccint/machine-descriptions/including-patterns-in-machine-descriptions.rst: New file.
	* doc/gccint/machine-descriptions/instruction-attributes.rst: New file.
	* doc/gccint/machine-descriptions/interdependence-of-patterns.rst: New file.
	* doc/gccint/machine-descriptions/iterators.rst: New file.
	* doc/gccint/machine-descriptions/machine-specific-peephole-optimizers.rst: New file.
	* doc/gccint/machine-descriptions/operand-constraints.rst: New file.
	* doc/gccint/machine-descriptions/output-templates-and-operand-substitution.rst: New file.
	* doc/gccint/machine-descriptions/overview-of-how-the-machine-description-is-used.rst:
	New file.
	* doc/gccint/machine-descriptions/predicates.rst: New file.
	* doc/gccint/machine-descriptions/rtl-template.rst: New file.
	* doc/gccint/machine-descriptions/rtl-templates-transformations.rst: New file.
	* doc/gccint/machine-descriptions/standard-pattern-names-for-generation.rst: New file.
	* doc/gccint/machine-descriptions/when-the-order-of-patterns-matters.rst: New file.
	* doc/gccint/makefile-fragments.rst: New file.
	* doc/gccint/match-and-simplify.rst: New file.
	* doc/gccint/memory-management-and-type-information.rst: New file.
	* doc/gccint/memory-management-and-type-information/how-to-invoke-the-garbage-collector.rst:
	New file.
	* doc/gccint/memory-management-and-type-information/marking-roots-for-the-garbage-collector.rst:
	New file.
	* doc/gccint/memory-management-and-type-information/source-files-containing-type-information.rst:
	New file.
	* doc/gccint/memory-management-and-type-information/support-for-inheritance.rst: New file.
	* doc/gccint/memory-management-and-type-information/support-for-user-provided-gc-marking-routines.rst:
	New file.
	* doc/gccint/memory-management-and-type-information/the-inside-of-a-gty.rst: New file.
	* doc/gccint/memory-management-and-type-information/troubleshooting-the-garbage-collector.rst:
	New file.
	* doc/gccint/option-file-format.rst: New file.
	* doc/gccint/option-properties.rst: New file.
	* doc/gccint/option-specification-files.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler/gimplification-pass.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler/inter-procedural-optimization-passes.rst:
	New file.
	* doc/gccint/passes-and-files-of-the-compiler/optimization-info.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler/parsing-pass.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler/pass-manager.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler/rtl-passes.rst: New file.
	* doc/gccint/passes-and-files-of-the-compiler/tree-ssa-passes.rst: New file.
	* doc/gccint/plugins.rst: New file.
	* doc/gccint/plugins/building-gcc-plugins.rst: New file.
	* doc/gccint/plugins/controlling-which-passes-are-being-run.rst: New file.
	* doc/gccint/plugins/giving-information-about-a-plugin.rst: New file.
	* doc/gccint/plugins/interacting-with-the-gcc-garbage-collector.rst: New file.
	* doc/gccint/plugins/interacting-with-the-pass-manager.rst: New file.
	* doc/gccint/plugins/keeping-track-of-available-passes.rst: New file.
	* doc/gccint/plugins/loading-plugins.rst: New file.
	* doc/gccint/plugins/plugin-api.rst: New file.
	* doc/gccint/plugins/recording-information-about-pass-execution.rst: New file.
	* doc/gccint/plugins/registering-custom-attributes-or-pragmas.rst: New file.
	* doc/gccint/rtl-representation.rst: New file.
	* doc/gccint/rtl-representation/access-to-operands.rst: New file.
	* doc/gccint/rtl-representation/access-to-special-operands.rst: New file.
	* doc/gccint/rtl-representation/assembler-instructions-as-expressions.rst: New file.
	* doc/gccint/rtl-representation/bit-fields.rst: New file.
	* doc/gccint/rtl-representation/comparison-operations.rst: New file.
	* doc/gccint/rtl-representation/constant-expression-types.rst: New file.
	* doc/gccint/rtl-representation/conversions.rst: New file.
	* doc/gccint/rtl-representation/declarations.rst: New file.
	* doc/gccint/rtl-representation/embedded-side-effects-on-addresses.rst: New file.
	* doc/gccint/rtl-representation/flags-in-an-rtl-expression.rst: New file.
	* doc/gccint/rtl-representation/insns.rst: New file.
	* doc/gccint/rtl-representation/machine-modes.rst: New file.
	* doc/gccint/rtl-representation/on-the-side-ssa-form-for-rtl.rst: New file.
	* doc/gccint/rtl-representation/reading-rtl.rst: New file.
	* doc/gccint/rtl-representation/registers-and-memory.rst: New file.
	* doc/gccint/rtl-representation/rtl-classes-and-formats.rst: New file.
	* doc/gccint/rtl-representation/rtl-expressions-for-arithmetic.rst: New file.
	* doc/gccint/rtl-representation/rtl-object-types.rst: New file.
	* doc/gccint/rtl-representation/rtl-representation-of-function-call-insns.rst: New file.
	* doc/gccint/rtl-representation/side-effect-expressions.rst: New file.
	* doc/gccint/rtl-representation/structure-sharing-assumptions.rst: New file.
	* doc/gccint/rtl-representation/variable-location-debug-information-in-rtl.rst: New file.
	* doc/gccint/rtl-representation/vector-operations.rst: New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants.rst: New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/alignment-of-polyints.rst: New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/arithmetic-on-polyints.rst: New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/comparisons-involving-polyint.rst:
	New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/computing-bounds-on-polyints.rst:
	New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/consequences-of-using-polyint.rst:
	New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/converting-polyints.rst: New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/guidelines-for-using-polyint.rst:
	New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/miscellaneous-polyint-routines.rst:
	New file.
	* doc/gccint/sizes-and-offsets-as-runtime-invariants/overview-of-polyint.rst: New file.
	* doc/gccint/source-tree-structure-and-build-system.rst: New file.
	* doc/gccint/source-tree-structure-and-build-system/configure-terms-and-history.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory.rst: New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/anatomy-of-a-language-front-end.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/anatomy-of-a-target-back-end.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/build-system-in-the-gcc-directory.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/building-documentation.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/configuration-in-the-gcc-directory.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/headers-installed-by-gcc.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/library-source-files-and-headers-under-the-gcc-directory.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/makefile-targets.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/the-gcc-subdirectory/subdirectories-of-gcc.rst:
	New file.
	* doc/gccint/source-tree-structure-and-build-system/top-level-source-directory.rst:
	New file.
	* doc/gccint/standard-header-file-directories.rst: New file.
	* doc/gccint/static-analyzer.rst: New file.
	* doc/gccint/target-macros.rst: New file.
	* doc/gccint/target-macros/adding-support-for-named-address-spaces.rst: New file.
	* doc/gccint/target-macros/addressing-modes.rst: New file.
	* doc/gccint/target-macros/adjusting-the-instruction-scheduler.rst: New file.
	* doc/gccint/target-macros/anchored-addresses.rst: New file.
	* doc/gccint/target-macros/c++-abi-parameters.rst: New file.
	* doc/gccint/target-macros/condition-code-status.rst: New file.
	* doc/gccint/target-macros/controlling-debugging-information-format.rst: New file.
	* doc/gccint/target-macros/controlling-the-compilation-driver-gcc.rst: New file.
	* doc/gccint/target-macros/cross-compilation-and-floating-point.rst: New file.
	* doc/gccint/target-macros/d-abi-parameters.rst: New file.
	* doc/gccint/target-macros/defining-coprocessor-specifics-for-mips-targets.rst: New file.
	* doc/gccint/target-macros/defining-data-structures-for-per-function-information.rst:
	New file.
	* doc/gccint/target-macros/defining-target-specific-uses-of-attribute.rst: New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language.rst: New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-alignment.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/assembler-commands-for-exception-regions.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/how-initialization-functions-are-handled.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/macros-controlling-initialization-routines.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/output-and-generation-of-labels.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-assembler-instructions.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-data.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-dispatch-tables.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/output-of-uninitialized-variables.rst:
	New file.
	* doc/gccint/target-macros/defining-the-output-assembler-language/the-overall-framework-of-an-assembler-file.rst:
	New file.
	* doc/gccint/target-macros/describing-relative-costs-of-operations.rst: New file.
	* doc/gccint/target-macros/dividing-the-output-into-sections-texts-data.rst: New file.
	* doc/gccint/target-macros/emulating-tls.rst: New file.
	* doc/gccint/target-macros/implementing-the-varargs-macros.rst: New file.
	* doc/gccint/target-macros/implicit-calls-to-library-routines.rst: New file.
	* doc/gccint/target-macros/layout-of-source-language-data-types.rst: New file.
	* doc/gccint/target-macros/miscellaneous-parameters.rst: New file.
	* doc/gccint/target-macros/mode-switching-instructions.rst: New file.
	* doc/gccint/target-macros/parameters-for-precompiled-header-validity-checking.rst:
	New file.
	* doc/gccint/target-macros/position-independent-code.rst: New file.
	* doc/gccint/target-macros/register-classes.rst: New file.
	* doc/gccint/target-macros/register-usage.rst: New file.
	* doc/gccint/target-macros/run-time-target-specification.rst: New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions.rst: New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/basic-stack-layout.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/caller-saves-register-allocation.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/eliminating-frame-pointer-and-arg-pointer.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/exception-handling-support.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/function-entry-and-exit.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/generating-code-for-profiling.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/how-large-values-are-returned.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/how-scalar-function-values-are-returned.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/miscellaneous-register-hooks.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/passing-arguments-in-registers.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/passing-function-arguments-on-the-stack.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/permitting-tail-calls.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/registers-that-address-the-stack-frame.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/shrink-wrapping-separate-components.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/specifying-how-stack-checking-is-done.rst:
	New file.
	* doc/gccint/target-macros/stack-layout-and-calling-conventions/stack-smashing-protection.rst:
	New file.
	* doc/gccint/target-macros/storage-layout.rst: New file.
	* doc/gccint/target-macros/support-for-nested-functions.rst: New file.
	* doc/gccint/target-macros/the-global-targetm-variable.rst: New file.
	* doc/gccint/target-makefile-fragments.rst: New file.
	* doc/gccint/testsuites.rst: New test.
	* doc/gccint/testsuites/ada-language-testsuites.rst: New test.
	* doc/gccint/testsuites/c-language-testsuites.rst: New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests.rst: New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests/commands-for-use-in-dg-final.rst:
	New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests/features-for-dg-add-options.rst:
	New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests/keywords-describing-target-attributes.rst:
	New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests/selecting-targets-to-which-a-test-applies.rst:
	New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests/syntax-and-descriptions-of-test-directives.rst:
	New test.
	* doc/gccint/testsuites/directives-used-within-dejagnu-tests/variants-of-dg-require-support.rst:
	New test.
	* doc/gccint/testsuites/idioms-used-in-testsuite-code.rst: New test.
	* doc/gccint/testsuites/support-for-testing-binary-compatibility.rst: New test.
	* doc/gccint/testsuites/support-for-testing-gcov.rst: New test.
	* doc/gccint/testsuites/support-for-testing-gimple-passes.rst: New test.
	* doc/gccint/testsuites/support-for-testing-link-time-optimizations.rst: New test.
	* doc/gccint/testsuites/support-for-testing-profile-directed-optimizations.rst: New test.
	* doc/gccint/testsuites/support-for-testing-rtl-passes.rst: New test.
	* doc/gccint/testsuites/support-for-torture-testing-using-multiple-options.rst: New test.
	* doc/gccint/the-gcc-low-level-runtime-library.rst: New file.
	* doc/gccint/the-gcc-low-level-runtime-library/language-independent-routines-for-exception-handling.rst:
	New file.
	* doc/gccint/the-gcc-low-level-runtime-library/miscellaneous-runtime-library-routines.rst:
	New file.
	* doc/gccint/the-gcc-low-level-runtime-library/routines-for-decimal-floating-point-emulation.rst:
	New file.
	* doc/gccint/the-gcc-low-level-runtime-library/routines-for-fixed-point-fractional-emulation.rst:
	New file.
	* doc/gccint/the-gcc-low-level-runtime-library/routines-for-floating-point-emulation.rst:
	New file.
	* doc/gccint/the-gcc-low-level-runtime-library/routines-for-integer-arithmetic.rst:
	New file.
	* doc/gccint/the-language.rst: New file.
	* doc/gccint/user-experience-guidelines.rst: New file.
	* doc/install/binaries.rst: New file.
	* doc/install/building.rst: New file.
	* doc/install/building/building-a-cross-compiler.rst: New file.
	* doc/install/building/building-a-native-compiler.rst: New file.
	* doc/install/building/building-in-parallel.rst: New file.
	* doc/install/building/building-the-ada-compiler.rst: New file.
	* doc/install/building/building-the-d-compiler.rst: New file.
	* doc/install/building/building-with-profile-feedback.rst: New file.
	* doc/install/conf.py: New file.
	* doc/install/configuration.rst: New file.
	* doc/install/copyright.rst: New file.
	* doc/install/downloading-gcc.rst: New file.
	* doc/install/final-installation.rst: New file.
	* doc/install/gnu-free-documentation-license.rst: New file.
	* doc/install/host-target-specific-installation-notes-for-gcc.rst: New file.
	* doc/install/how-can-you-run-the-testsuite-on-selected-tests.rst: New test.
	* doc/install/how-to-interpret-test-results.rst: New file.
	* doc/install/index.rst: New file.
	* doc/install/indices-and-tables.rst: New file.
	* doc/install/installing-gcc.rst: New file.
	* doc/install/passing-options-and-running-multiple-testsuites.rst: New test.
	* doc/install/prerequisites.rst: New file.
	* doc/install/submitting-test-results.rst: New file.
	* doc/install/testing.rst: New file.

gcc/fortran/ChangeLog:

	* doc/gfc-internals/code-that-interacts-with-the-user.rst: New file.
	* doc/gfc-internals/command-line-options.rst: New file.
	* doc/gfc-internals/conf.py: New file.
	* doc/gfc-internals/copyright.rst: New file.
	* doc/gfc-internals/error-handling.rst: New file.
	* doc/gfc-internals/frontend-data-structures.rst: New file.
	* doc/gfc-internals/generating-the-intermediate-language-for-later-stages.rst: New file.
	* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/accessing-declarations.rst:
	New file.
	* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/basic-data-structures.rst:
	New file.
	* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/converting-expressions-to-tree.rst:
	New file.
	* doc/gfc-internals/generating-the-intermediate-language-for-later-stages/translating-statements.rst:
	New file.
	* doc/gfc-internals/gfccode.rst: New file.
	* doc/gfc-internals/gfcexpr.rst: New file.
	* doc/gfc-internals/gnu-free-documentation-license.rst: New file.
	* doc/gfc-internals/index.rst: New file.
	* doc/gfc-internals/indices-and-tables.rst: New file.
	* doc/gfc-internals/internals-of-fortran-2003-oop-features.rst: New file.
	* doc/gfc-internals/introduction.rst: New file.
	* doc/gfc-internals/symbol-versioning.rst: New file.
	* doc/gfc-internals/the-libgfortran-runtime-library.rst: New file.
	* doc/gfc-internals/type-bound-operators.rst: New file.
	* doc/gfc-internals/type-bound-procedures.rst: New file.
	* doc/gfortran/about-gnu-fortran.rst: New file.
	* doc/gfortran/coarray-programming.rst: New file.
	* doc/gfortran/compiler-characteristics.rst: New file.
	* doc/gfortran/compiler-characteristics/asynchronous-i-o.rst: New file.
	* doc/gfortran/compiler-characteristics/data-consistency-and-durability.rst: New file.
	* doc/gfortran/compiler-characteristics/evaluation-of-logical-expressions.rst: New file.
	* doc/gfortran/compiler-characteristics/file-format-of-unformatted-sequential-files.rst:
	New file.
	* doc/gfortran/compiler-characteristics/file-operations-on-symbolic-links.rst: New file.
	* doc/gfortran/compiler-characteristics/files-opened-without-an-explicit-action=-specifier.rst:
	New file.
	* doc/gfortran/compiler-characteristics/internal-representation-of-logical-variables.rst:
	New file.
	* doc/gfortran/compiler-characteristics/kind-type-parameters.rst: New file.
	* doc/gfortran/compiler-characteristics/max-and-min-intrinsics-with-real-nan-arguments.rst:
	New file.
	* doc/gfortran/compiler-characteristics/thread-safety-of-the-runtime-library.rst: New file.
	* doc/gfortran/conf.py: New file.
	* doc/gfortran/contributing.rst: New file.
	* doc/gfortran/contributors-to-gnu-fortran.rst: New file.
	* doc/gfortran/copyright.rst: New file.
	* doc/gfortran/extensions-implemented-in-gnu-fortran.rst: New file.
	* doc/gfortran/extensions-not-implemented-in-gnu-fortran.rst: New file.
	* doc/gfortran/extensions.rst: New file.
	* doc/gfortran/function-abi-documentation.rst: New file.
	* doc/gfortran/funding.rst: New file.
	* doc/gfortran/general-public-license-3.rst: New file.
	* doc/gfortran/gnu-fortran-and-gcc.rst: New file.
	* doc/gfortran/gnu-fortran-command-options.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/description.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/enable-and-customize-preprocessing.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/environment-variables-affecting-gfortran.rst:
	New file.
	* doc/gfortran/gnu-fortran-command-options/influencing-runtime-behavior.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/influencing-the-linking-step.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/option-summary.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/options-controlling-fortran-dialect.rst:
	New file.
	* doc/gfortran/gnu-fortran-command-options/options-for-code-generation-conventions.rst:
	New file.
	* doc/gfortran/gnu-fortran-command-options/options-for-debugging-your-program-or-gnu-fortran.rst:
	New file.
	* doc/gfortran/gnu-fortran-command-options/options-for-directory-search.rst: New file.
	* doc/gfortran/gnu-fortran-command-options/options-for-interoperability-with-other-languages.rst:
	New file.
	* doc/gfortran/gnu-fortran-command-options/options-to-request-or-suppress-errors-and-warnings.rst:
	New file.
	* doc/gfortran/gnu-fortran-compiler-directives.rst: New file.
	* doc/gfortran/gnu-free-documentation-license.rst: New file.
	* doc/gfortran/index.rst: New file.
	* doc/gfortran/indices-and-tables.rst: New file.
	* doc/gfortran/interoperability-with-c.rst: New file.
	* doc/gfortran/intrinsic-modules.rst: New file.
	* doc/gfortran/intrinsic-modules/ieee-modules-ieeeexceptions-ieeearithmetic-and-ieeefeatures.rst:
	New file.
	* doc/gfortran/intrinsic-modules/isocbinding.rst: New file.
	* doc/gfortran/intrinsic-modules/isofortranenv.rst: New file.
	* doc/gfortran/intrinsic-modules/openacc-module-openacc.rst: New file.
	* doc/gfortran/intrinsic-modules/openmp-modules-omplib-and-omplibkinds.rst: New file.
	* doc/gfortran/intrinsic-procedures.rst: New file.
	* doc/gfortran/intrinsic-procedures/abort.rst: New file.
	* doc/gfortran/intrinsic-procedures/abs.rst: New file.
	* doc/gfortran/intrinsic-procedures/access.rst: New file.
	* doc/gfortran/intrinsic-procedures/achar.rst: New file.
	* doc/gfortran/intrinsic-procedures/acos.rst: New file.
	* doc/gfortran/intrinsic-procedures/acosd.rst: New file.
	* doc/gfortran/intrinsic-procedures/acosh.rst: New file.
	* doc/gfortran/intrinsic-procedures/adjustl.rst: New file.
	* doc/gfortran/intrinsic-procedures/adjustr.rst: New file.
	* doc/gfortran/intrinsic-procedures/aimag.rst: New file.
	* doc/gfortran/intrinsic-procedures/aint.rst: New file.
	* doc/gfortran/intrinsic-procedures/alarm.rst: New file.
	* doc/gfortran/intrinsic-procedures/all.rst: New file.
	* doc/gfortran/intrinsic-procedures/allocated.rst: New file.
	* doc/gfortran/intrinsic-procedures/and.rst: New file.
	* doc/gfortran/intrinsic-procedures/anint.rst: New file.
	* doc/gfortran/intrinsic-procedures/any.rst: New file.
	* doc/gfortran/intrinsic-procedures/asin.rst: New file.
	* doc/gfortran/intrinsic-procedures/asind.rst: New file.
	* doc/gfortran/intrinsic-procedures/asinh.rst: New file.
	* doc/gfortran/intrinsic-procedures/associated.rst: New file.
	* doc/gfortran/intrinsic-procedures/atan.rst: New file.
	* doc/gfortran/intrinsic-procedures/atan2.rst: New file.
	* doc/gfortran/intrinsic-procedures/atan2d.rst: New file.
	* doc/gfortran/intrinsic-procedures/atand.rst: New file.
	* doc/gfortran/intrinsic-procedures/atanh.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicadd.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicand.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomiccas.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicdefine.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicfetchadd.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicfetchand.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicfetchor.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicfetchxor.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicor.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicref.rst: New file.
	* doc/gfortran/intrinsic-procedures/atomicxor.rst: New file.
	* doc/gfortran/intrinsic-procedures/backtrace.rst: New file.
	* doc/gfortran/intrinsic-procedures/besselj0.rst: New file.
	* doc/gfortran/intrinsic-procedures/besselj1.rst: New file.
	* doc/gfortran/intrinsic-procedures/besseljn.rst: New file.
	* doc/gfortran/intrinsic-procedures/bessely0.rst: New file.
	* doc/gfortran/intrinsic-procedures/bessely1.rst: New file.
	* doc/gfortran/intrinsic-procedures/besselyn.rst: New file.
	* doc/gfortran/intrinsic-procedures/bge.rst: New file.
	* doc/gfortran/intrinsic-procedures/bgt.rst: New file.
	* doc/gfortran/intrinsic-procedures/bitsize.rst: New file.
	* doc/gfortran/intrinsic-procedures/ble.rst: New file.
	* doc/gfortran/intrinsic-procedures/blt.rst: New file.
	* doc/gfortran/intrinsic-procedures/btest.rst: New file.
	* doc/gfortran/intrinsic-procedures/cassociated.rst: New file.
	* doc/gfortran/intrinsic-procedures/ceiling.rst: New file.
	* doc/gfortran/intrinsic-procedures/cfpointer.rst: New file.
	* doc/gfortran/intrinsic-procedures/cfprocpointer.rst: New file.
	* doc/gfortran/intrinsic-procedures/cfunloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/char.rst: New file.
	* doc/gfortran/intrinsic-procedures/chdir.rst: New file.
	* doc/gfortran/intrinsic-procedures/chmod.rst: New file.
	* doc/gfortran/intrinsic-procedures/cloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/cmplx.rst: New file.
	* doc/gfortran/intrinsic-procedures/cobroadcast.rst: New file.
	* doc/gfortran/intrinsic-procedures/comax.rst: New file.
	* doc/gfortran/intrinsic-procedures/comin.rst: New file.
	* doc/gfortran/intrinsic-procedures/commandargumentcount.rst: New file.
	* doc/gfortran/intrinsic-procedures/compileroptions.rst: New file.
	* doc/gfortran/intrinsic-procedures/compilerversion.rst: New file.
	* doc/gfortran/intrinsic-procedures/complex.rst: New file.
	* doc/gfortran/intrinsic-procedures/conjg.rst: New file.
	* doc/gfortran/intrinsic-procedures/coreduce.rst: New file.
	* doc/gfortran/intrinsic-procedures/cos.rst: New file.
	* doc/gfortran/intrinsic-procedures/cosd.rst: New file.
	* doc/gfortran/intrinsic-procedures/cosh.rst: New file.
	* doc/gfortran/intrinsic-procedures/cosum.rst: New file.
	* doc/gfortran/intrinsic-procedures/cotan.rst: New file.
	* doc/gfortran/intrinsic-procedures/cotand.rst: New file.
	* doc/gfortran/intrinsic-procedures/count.rst: New file.
	* doc/gfortran/intrinsic-procedures/cputime.rst: New file.
	* doc/gfortran/intrinsic-procedures/cshift.rst: New file.
	* doc/gfortran/intrinsic-procedures/csizeof.rst: New file.
	* doc/gfortran/intrinsic-procedures/ctime.rst: New file.
	* doc/gfortran/intrinsic-procedures/dateandtime.rst: New file.
	* doc/gfortran/intrinsic-procedures/dble.rst: New file.
	* doc/gfortran/intrinsic-procedures/dcmplx.rst: New file.
	* doc/gfortran/intrinsic-procedures/digits.rst: New file.
	* doc/gfortran/intrinsic-procedures/dim.rst: New file.
	* doc/gfortran/intrinsic-procedures/dotproduct.rst: New file.
	* doc/gfortran/intrinsic-procedures/dprod.rst: New file.
	* doc/gfortran/intrinsic-procedures/dreal.rst: New file.
	* doc/gfortran/intrinsic-procedures/dshiftl.rst: New file.
	* doc/gfortran/intrinsic-procedures/dshiftr.rst: New file.
	* doc/gfortran/intrinsic-procedures/dtime.rst: New file.
	* doc/gfortran/intrinsic-procedures/eoshift.rst: New file.
	* doc/gfortran/intrinsic-procedures/epsilon.rst: New file.
	* doc/gfortran/intrinsic-procedures/erf.rst: New file.
	* doc/gfortran/intrinsic-procedures/erfc.rst: New file.
	* doc/gfortran/intrinsic-procedures/erfcscaled.rst: New file.
	* doc/gfortran/intrinsic-procedures/etime.rst: New file.
	* doc/gfortran/intrinsic-procedures/eventquery.rst: New file.
	* doc/gfortran/intrinsic-procedures/executecommandline.rst: New file.
	* doc/gfortran/intrinsic-procedures/exit.rst: New file.
	* doc/gfortran/intrinsic-procedures/exp.rst: New file.
	* doc/gfortran/intrinsic-procedures/exponent.rst: New file.
	* doc/gfortran/intrinsic-procedures/extendstypeof.rst: New file.
	* doc/gfortran/intrinsic-procedures/fdate.rst: New file.
	* doc/gfortran/intrinsic-procedures/fget.rst: New file.
	* doc/gfortran/intrinsic-procedures/fgetc.rst: New file.
	* doc/gfortran/intrinsic-procedures/findloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/floor.rst: New file.
	* doc/gfortran/intrinsic-procedures/flush.rst: New file.
	* doc/gfortran/intrinsic-procedures/fnum.rst: New file.
	* doc/gfortran/intrinsic-procedures/fput.rst: New file.
	* doc/gfortran/intrinsic-procedures/fputc.rst: New file.
	* doc/gfortran/intrinsic-procedures/fraction.rst: New file.
	* doc/gfortran/intrinsic-procedures/free.rst: New file.
	* doc/gfortran/intrinsic-procedures/fseek.rst: New file.
	* doc/gfortran/intrinsic-procedures/fstat.rst: New file.
	* doc/gfortran/intrinsic-procedures/ftell.rst: New file.
	* doc/gfortran/intrinsic-procedures/gamma.rst: New file.
	* doc/gfortran/intrinsic-procedures/gerror.rst: New file.
	* doc/gfortran/intrinsic-procedures/getarg.rst: New file.
	* doc/gfortran/intrinsic-procedures/getcommand.rst: New file.
	* doc/gfortran/intrinsic-procedures/getcommandargument.rst: New file.
	* doc/gfortran/intrinsic-procedures/getcwd.rst: New file.
	* doc/gfortran/intrinsic-procedures/getenv.rst: New file.
	* doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst: New file.
	* doc/gfortran/intrinsic-procedures/getgid.rst: New file.
	* doc/gfortran/intrinsic-procedures/getlog.rst: New file.
	* doc/gfortran/intrinsic-procedures/getpid.rst: New file.
	* doc/gfortran/intrinsic-procedures/getuid.rst: New file.
	* doc/gfortran/intrinsic-procedures/gmtime.rst: New file.
	* doc/gfortran/intrinsic-procedures/hostnm.rst: New file.
	* doc/gfortran/intrinsic-procedures/huge.rst: New file.
	* doc/gfortran/intrinsic-procedures/hypot.rst: New file.
	* doc/gfortran/intrinsic-procedures/iachar.rst: New file.
	* doc/gfortran/intrinsic-procedures/iall.rst: New file.
	* doc/gfortran/intrinsic-procedures/iand.rst: New file.
	* doc/gfortran/intrinsic-procedures/iany.rst: New file.
	* doc/gfortran/intrinsic-procedures/iargc.rst: New file.
	* doc/gfortran/intrinsic-procedures/ibclr.rst: New file.
	* doc/gfortran/intrinsic-procedures/ibits.rst: New file.
	* doc/gfortran/intrinsic-procedures/ibset.rst: New file.
	* doc/gfortran/intrinsic-procedures/ichar.rst: New file.
	* doc/gfortran/intrinsic-procedures/idate.rst: New file.
	* doc/gfortran/intrinsic-procedures/ieor.rst: New file.
	* doc/gfortran/intrinsic-procedures/ierrno.rst: New file.
	* doc/gfortran/intrinsic-procedures/imageindex.rst: New file.
	* doc/gfortran/intrinsic-procedures/index.rst: New file.
	* doc/gfortran/intrinsic-procedures/int.rst: New file.
	* doc/gfortran/intrinsic-procedures/int2.rst: New file.
	* doc/gfortran/intrinsic-procedures/int8.rst: New file.
	* doc/gfortran/intrinsic-procedures/introduction-to-intrinsic-procedures.rst: New file.
	* doc/gfortran/intrinsic-procedures/ior.rst: New file.
	* doc/gfortran/intrinsic-procedures/iparity.rst: New file.
	* doc/gfortran/intrinsic-procedures/irand.rst: New file.
	* doc/gfortran/intrinsic-procedures/isatty.rst: New file.
	* doc/gfortran/intrinsic-procedures/iscontiguous.rst: New file.
	* doc/gfortran/intrinsic-procedures/ishft.rst: New file.
	* doc/gfortran/intrinsic-procedures/ishftc.rst: New file.
	* doc/gfortran/intrinsic-procedures/isiostatend.rst: New file.
	* doc/gfortran/intrinsic-procedures/isiostateor.rst: New file.
	* doc/gfortran/intrinsic-procedures/isnan.rst: New file.
	* doc/gfortran/intrinsic-procedures/itime.rst: New file.
	* doc/gfortran/intrinsic-procedures/kill.rst: New file.
	* doc/gfortran/intrinsic-procedures/kind.rst: New file.
	* doc/gfortran/intrinsic-procedures/lbound.rst: New file.
	* doc/gfortran/intrinsic-procedures/lcobound.rst: New file.
	* doc/gfortran/intrinsic-procedures/leadz.rst: New file.
	* doc/gfortran/intrinsic-procedures/len.rst: New file.
	* doc/gfortran/intrinsic-procedures/lentrim.rst: New file.
	* doc/gfortran/intrinsic-procedures/lge.rst: New file.
	* doc/gfortran/intrinsic-procedures/lgt.rst: New file.
	* doc/gfortran/intrinsic-procedures/link.rst: New file.
	* doc/gfortran/intrinsic-procedures/lle.rst: New file.
	* doc/gfortran/intrinsic-procedures/llt.rst: New file.
	* doc/gfortran/intrinsic-procedures/lnblnk.rst: New file.
	* doc/gfortran/intrinsic-procedures/loc.rst: New file.
	* doc/gfortran/intrinsic-procedures/log.rst: New file.
	* doc/gfortran/intrinsic-procedures/log10.rst: New file.
	* doc/gfortran/intrinsic-procedures/loggamma.rst: New file.
	* doc/gfortran/intrinsic-procedures/logical.rst: New file.
	* doc/gfortran/intrinsic-procedures/lshift.rst: New file.
	* doc/gfortran/intrinsic-procedures/lstat.rst: New file.
	* doc/gfortran/intrinsic-procedures/ltime.rst: New file.
	* doc/gfortran/intrinsic-procedures/malloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/maskl.rst: New file.
	* doc/gfortran/intrinsic-procedures/maskr.rst: New file.
	* doc/gfortran/intrinsic-procedures/matmul.rst: New file.
	* doc/gfortran/intrinsic-procedures/max.rst: New file.
	* doc/gfortran/intrinsic-procedures/maxexponent.rst: New file.
	* doc/gfortran/intrinsic-procedures/maxloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/maxval.rst: New file.
	* doc/gfortran/intrinsic-procedures/mclock.rst: New file.
	* doc/gfortran/intrinsic-procedures/mclock8.rst: New file.
	* doc/gfortran/intrinsic-procedures/merge.rst: New file.
	* doc/gfortran/intrinsic-procedures/mergebits.rst: New file.
	* doc/gfortran/intrinsic-procedures/min.rst: New file.
	* doc/gfortran/intrinsic-procedures/minexponent.rst: New file.
	* doc/gfortran/intrinsic-procedures/minloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/minval.rst: New file.
	* doc/gfortran/intrinsic-procedures/mod.rst: New file.
	* doc/gfortran/intrinsic-procedures/modulo.rst: New file.
	* doc/gfortran/intrinsic-procedures/movealloc.rst: New file.
	* doc/gfortran/intrinsic-procedures/mvbits.rst: New file.
	* doc/gfortran/intrinsic-procedures/nearest.rst: New file.
	* doc/gfortran/intrinsic-procedures/newline.rst: New file.
	* doc/gfortran/intrinsic-procedures/nint.rst: New file.
	* doc/gfortran/intrinsic-procedures/norm2.rst: New file.
	* doc/gfortran/intrinsic-procedures/not.rst: New file.
	* doc/gfortran/intrinsic-procedures/null.rst: New file.
	* doc/gfortran/intrinsic-procedures/numimages.rst: New file.
	* doc/gfortran/intrinsic-procedures/or.rst: New file.
	* doc/gfortran/intrinsic-procedures/pack.rst: New file.
	* doc/gfortran/intrinsic-procedures/parity.rst: New file.
	* doc/gfortran/intrinsic-procedures/perror.rst: New file.
	* doc/gfortran/intrinsic-procedures/popcnt.rst: New file.
	* doc/gfortran/intrinsic-procedures/poppar.rst: New file.
	* doc/gfortran/intrinsic-procedures/precision.rst: New file.
	* doc/gfortran/intrinsic-procedures/present.rst: New file.
	* doc/gfortran/intrinsic-procedures/product.rst: New file.
	* doc/gfortran/intrinsic-procedures/radix.rst: New file.
	* doc/gfortran/intrinsic-procedures/ran.rst: New file.
	* doc/gfortran/intrinsic-procedures/rand.rst: New file.
	* doc/gfortran/intrinsic-procedures/randominit.rst: New file.
	* doc/gfortran/intrinsic-procedures/randomnumber.rst: New file.
	* doc/gfortran/intrinsic-procedures/randomseed.rst: New file.
	* doc/gfortran/intrinsic-procedures/range.rst: New file.
	* doc/gfortran/intrinsic-procedures/rank.rst: New file.
	* doc/gfortran/intrinsic-procedures/real.rst: New file.
	* doc/gfortran/intrinsic-procedures/rename.rst: New file.
	* doc/gfortran/intrinsic-procedures/repeat.rst: New file.
	* doc/gfortran/intrinsic-procedures/reshape.rst: New file.
	* doc/gfortran/intrinsic-procedures/rrspacing.rst: New file.
	* doc/gfortran/intrinsic-procedures/rshift.rst: New file.
	* doc/gfortran/intrinsic-procedures/sametypeas.rst: New file.
	* doc/gfortran/intrinsic-procedures/scale.rst: New file.
	* doc/gfortran/intrinsic-procedures/scan.rst: New file.
	* doc/gfortran/intrinsic-procedures/secnds.rst: New file.
	* doc/gfortran/intrinsic-procedures/second.rst: New file.
	* doc/gfortran/intrinsic-procedures/selectedcharkind.rst: New file.
	* doc/gfortran/intrinsic-procedures/selectedintkind.rst: New file.
	* doc/gfortran/intrinsic-procedures/selectedrealkind.rst: New file.
	* doc/gfortran/intrinsic-procedures/setexponent.rst: New file.
	* doc/gfortran/intrinsic-procedures/shape.rst: New file.
	* doc/gfortran/intrinsic-procedures/shifta.rst: New file.
	* doc/gfortran/intrinsic-procedures/shiftl.rst: New file.
	* doc/gfortran/intrinsic-procedures/shiftr.rst: New file.
	* doc/gfortran/intrinsic-procedures/sign.rst: New file.
	* doc/gfortran/intrinsic-procedures/signal.rst: New file.
	* doc/gfortran/intrinsic-procedures/sin.rst: New file.
	* doc/gfortran/intrinsic-procedures/sind.rst: New file.
	* doc/gfortran/intrinsic-procedures/sinh.rst: New file.
	* doc/gfortran/intrinsic-procedures/size.rst: New file.
	* doc/gfortran/intrinsic-procedures/sizeof.rst: New file.
	* doc/gfortran/intrinsic-procedures/sleep.rst: New file.
	* doc/gfortran/intrinsic-procedures/spacing.rst: New file.
	* doc/gfortran/intrinsic-procedures/spread.rst: New file.
	* doc/gfortran/intrinsic-procedures/sqrt.rst: New file.
	* doc/gfortran/intrinsic-procedures/srand.rst: New file.
	* doc/gfortran/intrinsic-procedures/stat.rst: New file.
	* doc/gfortran/intrinsic-procedures/storagesize.rst: New file.
	* doc/gfortran/intrinsic-procedures/sum.rst: New file.
	* doc/gfortran/intrinsic-procedures/symlnk.rst: New file.
	* doc/gfortran/intrinsic-procedures/system.rst: New file.
	* doc/gfortran/intrinsic-procedures/systemclock.rst: New file.
	* doc/gfortran/intrinsic-procedures/tan.rst: New file.
	* doc/gfortran/intrinsic-procedures/tand.rst: New file.
	* doc/gfortran/intrinsic-procedures/tanh.rst: New file.
	* doc/gfortran/intrinsic-procedures/thisimage.rst: New file.
	* doc/gfortran/intrinsic-procedures/time.rst: New file.
	* doc/gfortran/intrinsic-procedures/time8.rst: New file.
	* doc/gfortran/intrinsic-procedures/tiny.rst: New file.
	* doc/gfortran/intrinsic-procedures/trailz.rst: New file.
	* doc/gfortran/intrinsic-procedures/transfer.rst: New file.
	* doc/gfortran/intrinsic-procedures/transpose.rst: New file.
	* doc/gfortran/intrinsic-procedures/trim.rst: New file.
	* doc/gfortran/intrinsic-procedures/ttynam.rst: New file.
	* doc/gfortran/intrinsic-procedures/ubound.rst: New file.
	* doc/gfortran/intrinsic-procedures/ucobound.rst: New file.
	* doc/gfortran/intrinsic-procedures/umask.rst: New file.
	* doc/gfortran/intrinsic-procedures/unlink.rst: New file.
	* doc/gfortran/intrinsic-procedures/unpack.rst: New file.
	* doc/gfortran/intrinsic-procedures/verify.rst: New file.
	* doc/gfortran/intrinsic-procedures/xor.rst: New file.
	* doc/gfortran/introduction.rst: New file.
	* doc/gfortran/mixed-language-programming.rst: New file.
	* doc/gfortran/naming-and-argument-passing-conventions.rst: New file.
	* doc/gfortran/non-fortran-main-program.rst: New file.
	* doc/gfortran/projects.rst: New file.
	* doc/gfortran/runtime.rst: New file.
	* doc/gfortran/runtime/gfortranconvertunit.rst: New file.
	* doc/gfortran/runtime/gfortranerrorbacktrace.rst: New file.
	* doc/gfortran/runtime/gfortranformattedbuffersize.rst: New file.
	* doc/gfortran/runtime/gfortranlistseparator.rst: New file.
	* doc/gfortran/runtime/gfortranoptionalplus.rst: New file.
	* doc/gfortran/runtime/gfortranshowlocus.rst: New file.
	* doc/gfortran/runtime/gfortranstderrunit.rst: New file.
	* doc/gfortran/runtime/gfortranstdinunit.rst: New file.
	* doc/gfortran/runtime/gfortranstdoutunit.rst: New file.
	* doc/gfortran/runtime/gfortranunbufferedall.rst: New file.
	* doc/gfortran/runtime/gfortranunbufferedpreconnected.rst: New file.
	* doc/gfortran/runtime/gfortranunformattedbuffersize.rst: New file.
	* doc/gfortran/runtime/tmpdir.rst: New file.
	* doc/gfortran/standards.rst: New file.
	* doc/gfortran/type-and-enum-abi-documentation.rst: New file.

gcc/go/ChangeLog:

	* doc/c-interoperability.rst: New file.
	* doc/c-type-interoperability.rst: New file.
	* doc/compiler-directives.rst: New file.
	* doc/conf.py: New file.
	* doc/copyright.rst: New file.
	* doc/function-names.rst: New file.
	* doc/general-public-license-3.rst: New file.
	* doc/gnu-free-documentation-license.rst: New file.
	* doc/import-and-export.rst: New file.
	* doc/index.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/introduction.rst: New file.
	* doc/invoking-gccgo.rst: New file.

libgomp/ChangeLog:

	* doc/amd-radeon-gcn.rst: New file.
	* doc/conf.py: New file.
	* doc/copyright.rst: New file.
	* doc/cuda-streams-usage.rst: New file.
	* doc/enabling-openacc.rst: New file.
	* doc/enabling-openmp.rst: New file.
	* doc/first-invocation-nvidia-cublas-library-api.rst: New file.
	* doc/first-invocation-openacc-library-api.rst: New file.
	* doc/funding.rst: New file.
	* doc/general-public-license-3.rst: New file.
	* doc/gnu-free-documentation-license.rst: New file.
	* doc/implementation-status-and-implementation-defined-behavior.rst: New file.
	* doc/index.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/introduction.rst: New file.
	* doc/memory-allocation-with-libmemkind.rst: New file.
	* doc/nvptx.rst: New file.
	* doc/offload-target-specifics.rst: New file.
	* doc/openacc-environment-variables.rst: New file.
	* doc/openacc-environment-variables/accdevicenum.rst: New file.
	* doc/openacc-environment-variables/accdevicetype.rst: New file.
	* doc/openacc-environment-variables/accproflib.rst: New file.
	* doc/openacc-environment-variables/gccaccnotify.rst: New file.
	* doc/openacc-introduction.rst: New file.
	* doc/openacc-library-and-environment-variables.rst: New file.
	* doc/openacc-library-interoperability.rst: New file.
	* doc/openacc-profiling-interface.rst: New file.
	* doc/openacc-runtime-library-routines.rst: New file.
	* doc/openacc-runtime-library-routines/accasynctest.rst: New file.
	* doc/openacc-runtime-library-routines/accasynctestall.rst: New file.
	* doc/openacc-runtime-library-routines/accattach.rst: New file.
	* doc/openacc-runtime-library-routines/acccopyin.rst: New file.
	* doc/openacc-runtime-library-routines/acccopyout.rst: New file.
	* doc/openacc-runtime-library-routines/acccreate.rst: New file.
	* doc/openacc-runtime-library-routines/accdelete.rst: New file.
	* doc/openacc-runtime-library-routines/accdetach.rst: New file.
	* doc/openacc-runtime-library-routines/accdeviceptr.rst: New file.
	* doc/openacc-runtime-library-routines/accfree.rst: New file.
	* doc/openacc-runtime-library-routines/accgetcudastream.rst: New file.
	* doc/openacc-runtime-library-routines/accgetcurrentcudacontext.rst: New file.
	* doc/openacc-runtime-library-routines/accgetcurrentcudadevice.rst: New file.
	* doc/openacc-runtime-library-routines/accgetdevicenum.rst: New file.
	* doc/openacc-runtime-library-routines/accgetdevicetype.rst: New file.
	* doc/openacc-runtime-library-routines/accgetnumdevices.rst: New file.
	* doc/openacc-runtime-library-routines/accgetproperty.rst: New file.
	* doc/openacc-runtime-library-routines/acchostptr.rst: New file.
	* doc/openacc-runtime-library-routines/accinit.rst: New file.
	* doc/openacc-runtime-library-routines/accispresent.rst: New file.
	* doc/openacc-runtime-library-routines/accmalloc.rst: New file.
	* doc/openacc-runtime-library-routines/accmapdata.rst: New file.
	* doc/openacc-runtime-library-routines/accmemcpyfromdevice.rst: New file.
	* doc/openacc-runtime-library-routines/accmemcpytodevice.rst: New file.
	* doc/openacc-runtime-library-routines/accondevice.rst: New file.
	* doc/openacc-runtime-library-routines/accpresentorcopyin.rst: New file.
	* doc/openacc-runtime-library-routines/accpresentorcreate.rst: New file.
	* doc/openacc-runtime-library-routines/accproflookup.rst: New file.
	* doc/openacc-runtime-library-routines/accprofregister.rst: New file.
	* doc/openacc-runtime-library-routines/accprofunregister.rst: New file.
	* doc/openacc-runtime-library-routines/accregisterlibrary.rst: New file.
	* doc/openacc-runtime-library-routines/accsetcudastream.rst: New file.
	* doc/openacc-runtime-library-routines/accsetdevicenum.rst: New file.
	* doc/openacc-runtime-library-routines/accsetdevicetype.rst: New file.
	* doc/openacc-runtime-library-routines/accshutdown.rst: New file.
	* doc/openacc-runtime-library-routines/accunmapdata.rst: New file.
	* doc/openacc-runtime-library-routines/accupdatedevice.rst: New file.
	* doc/openacc-runtime-library-routines/accupdateself.rst: New file.
	* doc/openacc-runtime-library-routines/accwait.rst: New file.
	* doc/openacc-runtime-library-routines/accwaitall.rst: New file.
	* doc/openacc-runtime-library-routines/accwaitallasync.rst: New file.
	* doc/openacc-runtime-library-routines/accwaitasync.rst: New file.
	* doc/openmp-context-selectors.rst: New file.
	* doc/openmp-environment-variables.rst: New file.
	* doc/openmp-environment-variables/gompcpuaffinity.rst: New file.
	* doc/openmp-environment-variables/gompdebug.rst: New file.
	* doc/openmp-environment-variables/gomprtemsthreadpools.rst: New file.
	* doc/openmp-environment-variables/gompspincount.rst: New file.
	* doc/openmp-environment-variables/gompstacksize.rst: New file.
	* doc/openmp-environment-variables/ompcancellation.rst: New file.
	* doc/openmp-environment-variables/ompdefaultdevice.rst: New file.
	* doc/openmp-environment-variables/ompdisplayenv.rst: New file.
	* doc/openmp-environment-variables/ompdynamic.rst: New file.
	* doc/openmp-environment-variables/ompmaxactivelevels.rst: New file.
	* doc/openmp-environment-variables/ompmaxtaskpriority.rst: New file.
	* doc/openmp-environment-variables/ompnested.rst: New file.
	* doc/openmp-environment-variables/ompnumteams.rst: New file.
	* doc/openmp-environment-variables/ompnumthreads.rst: New file.
	* doc/openmp-environment-variables/ompplaces.rst: New file.
	* doc/openmp-environment-variables/ompprocbind.rst: New file.
	* doc/openmp-environment-variables/ompschedule.rst: New file.
	* doc/openmp-environment-variables/ompstacksize.rst: New file.
	* doc/openmp-environment-variables/omptargetoffload.rst: New file.
	* doc/openmp-environment-variables/ompteamsthreadlimit.rst: New file.
	* doc/openmp-environment-variables/ompthreadlimit.rst: New file.
	* doc/openmp-environment-variables/ompwaitpolicy.rst: New file.
	* doc/openmp-implementation-specifics.rst: New file.
	* doc/openmp-implementation-status.rst: New file.
	* doc/openmp-implementation-status/openmp-45.rst: New file.
	* doc/openmp-implementation-status/openmp-50.rst: New file.
	* doc/openmp-implementation-status/openmp-51.rst: New file.
	* doc/openmp-implementation-status/openmp-52.rst: New file.
	* doc/openmp-runtime-library-routines.rst: New file.
	* doc/openmp-runtime-library-routines/ompdestroylock.rst: New file.
	* doc/openmp-runtime-library-routines/ompdestroynestlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompfulfillevent.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetactivelevel.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetancestorthreadnum.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetcancellation.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetdefaultdevice.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetdevicenum.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetdynamic.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetinitialdevice.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetlevel.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetmaxactivelevels.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetmaxtaskpriority.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetmaxteams.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetmaxthreads.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetnested.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetnumdevices.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetnumprocs.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetnumteams.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetnumthreads.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetprocbind.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetschedule.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetsupportedactivelevels.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetteamnum.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetteamsize.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetteamsthreadlimit.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetthreadlimit.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetthreadnum.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetwtick.rst: New file.
	* doc/openmp-runtime-library-routines/ompgetwtime.rst: New file.
	* doc/openmp-runtime-library-routines/ompinfinal.rst: New file.
	* doc/openmp-runtime-library-routines/ompinitlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompinitnestlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompinparallel.rst: New file.
	* doc/openmp-runtime-library-routines/ompisinitialdevice.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetdefaultdevice.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetdynamic.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetmaxactivelevels.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetnested.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetnestlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetnumteams.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetnumthreads.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetschedule.rst: New file.
	* doc/openmp-runtime-library-routines/ompsetteamsthreadlimit.rst: New file.
	* doc/openmp-runtime-library-routines/omptestlock.rst: New file.
	* doc/openmp-runtime-library-routines/omptestnestlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompunsetlock.rst: New file.
	* doc/openmp-runtime-library-routines/ompunsetnestlock.rst: New file.
	* doc/reporting-bugs.rst: New file.
	* doc/the-libgomp-abi.rst: New file.
	* doc/the-libgomp-abi/implementing-atomic-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-barrier-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-critical-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-firstprivate-lastprivate-copyin-and-copyprivate-clauses.rst:
	New file.
	* doc/the-libgomp-abi/implementing-flush-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-for-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-master-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-openaccs-parallel-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-ordered-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-parallel-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-private-clause.rst: New file.
	* doc/the-libgomp-abi/implementing-reduction-clause.rst: New file.
	* doc/the-libgomp-abi/implementing-sections-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-single-construct.rst: New file.
	* doc/the-libgomp-abi/implementing-threadprivate-construct.rst: New file.

libiberty/ChangeLog:

	* doc/bsd.rst: New file.
	* doc/conf.py: New file.
	* doc/copyright.rst: New file.
	* doc/extensions.rst: New file.
	* doc/function-variable-and-macro-listing.rst: New file.
	* doc/index.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/introduction.rst: New file.
	* doc/lesser-general-public-license-2.1.rst: New file.
	* doc/overview.rst: New file.
	* doc/replacement-functions.rst: New file.
	* doc/supplemental-functions.rst: New file.
	* doc/using.rst: New file.

libitm/ChangeLog:

	* doc/c-c++-language-constructs-for-tm.rst: New file.
	* doc/conf.py: New file.
	* doc/copyright.rst: New file.
	* doc/enabling-libitm.rst: New file.
	* doc/gnu-free-documentation-license.rst: New file.
	* doc/index.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/internals.rst: New file.
	* doc/locking-conventions.rst: New file.
	* doc/nesting-flat-vs-closed.rst: New file.
	* doc/the-libitm-abi.rst: New file.
	* doc/the-libitm-abi/function-list.rst: New file.
	* doc/the-libitm-abi/future-enhancements-to-the-abi.rst: New file.
	* doc/the-libitm-abi/library-design-principles.rst: New file.
	* doc/the-libitm-abi/memory-model.rst: New file.
	* doc/the-libitm-abi/non-objectives.rst: New file.
	* doc/the-libitm-abi/objectives.rst: New file.
	* doc/the-libitm-abi/sample-code.rst: New file.
	* doc/the-libitm-abi/types-and-macros-list.rst: New file.
	* doc/tm-methods-and-method-groups.rst: New file.

libquadmath/ChangeLog:

	* doc/conf.py: New file.
	* doc/copyright.rst: New file.
	* doc/gnu-free-documentation-license.rst: New file.
	* doc/i-o-library-routines.rst: New file.
	* doc/index.rst: New file.
	* doc/indices-and-tables.rst: New file.
	* doc/introduction.rst: New file.
	* doc/math-library-routines.rst: New file.
	* doc/quadmathsnprintf.rst: New file.
	* doc/reporting-bugs.rst: New file.
	* doc/strtoflt128.rst: New file.
	* doc/typedef-and-constants.rst: New file.

doc/Makefile

@@ -0,0 +1,97 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS   ?= -j auto -q
+SPHINXBUILD  ?= sphinx-build
+PAPER        ?=
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_elements.papersize=a4paper
+PAPEROPT_letter = -D latex_elements.papersize=letterpaper
+# $(O) is meant as a shortcut for $(SPHINXOPTS)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR)
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) $(SOURCEDIR)
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html        to make standalone HTML files"
+	@echo "  dirhtml     to make HTML files named index.html in directories"
+	@echo "  singlehtml  to make a single large HTML file"
+	@echo "  pickle      to make pickle files"
+	@echo "  json        to make JSON files"
+	@echo "  htmlhelp    to make HTML files and an HTML help project"
+	@echo "  qthelp      to make HTML files and a qthelp project"
+	@echo "  applehelp   to make an Apple Help Book"
+	@echo "  devhelp     to make HTML files and a Devhelp project"
+	@echo "  epub        to make an epub"
+	@echo "  latex       to make LaTeX files (you can set PAPER=a4 or PAPER=letter)"
+	@echo "  latexpdf    to make LaTeX files and then PDFs out of them"
+	@echo "  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  lualatexpdf to make LaTeX files and run them through lualatex"
+	@echo "  xelatexpdf  to make LaTeX files and run them through xelatex"
+	@echo "  text        to make text files"
+	@echo "  man         to make manual pages"
+	@echo "  texinfo     to make Texinfo files"
+	@echo "  info        to make Texinfo files and run them through makeinfo"
+	@echo "  gettext     to make PO message catalogs"
+	@echo "  changes     to make an overview of all changed/added/deprecated items"
+	@echo "  xml         to make Docutils-native XML files"
+	@echo "  pseudoxml   to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck   to check all external links for integrity"
+	@echo "  doctest     to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage    to run coverage check of the documentation (if enabled)"
+	@echo "  dummy       to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) LATEXMKOPTS="-interaction=nonstopmode -f" -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: lualatexpdf
+lualatexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through lualatex..."
+	$(MAKE) PDFLATEX=lualatex -C $(BUILDDIR)/latex all-pdf
+	@echo "lualatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: xelatexpdf
+xelatexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through xelatex..."
+	$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf
+	@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+
+# Catch-all target: route all unknown targets to Sphinx
+.PHONY: Makefile
+%: Makefile
+	$(SPHINXBUILD) -b "$@" $(ALLSPHINXOPTS) "$(BUILDDIR)/$@"
+

doc/_static/custom.css

@@ -0,0 +1,11 @@
+.sidebar-brand-text {
+  font-size: 13pt;
+}
+
+.literal {
+  white-space: nowrap !important;
+}
+
+.wy-nav-content {
+  max-width: initial;
+}

doc/baseconf.py

@@ -0,0 +1,230 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import subprocess
+import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# gccint needs a deeper stack limit
+sys.setrecursionlimit(2000)
+
+# -- Project information -----------------------------------------------------
+
+# The full version, including alpha/beta/rc tags
+
+# FIXME
+folder = os.path.dirname(os.path.realpath(__file__))
+gcc_srcdir = os.path.join(folder, './objdir')
+
+
+def __read_file(name):
+    path = os.path.join(gcc_srcdir, name)
+    if os.path.exists(path):
+        return open(path).read().strip()
+    else:
+        return ''
+
+
+def __get_git_revision():
+    try:
+        r = subprocess.check_output('git rev-parse --short HEAD', shell=True, encoding='utf8',
+                                    stderr=subprocess.DEVNULL)
+        return r.strip()
+    except subprocess.CalledProcessError:
+        return None
+
+
+def __get_builder_name():
+    if '-b' in sys.argv:
+        return sys.argv[sys.argv.index('-b') + 1]
+    else:
+        return None
+
+
+gcc_BASEVER = __read_file('BASE-VER')
+gcc_DEVPHASE = __read_file('DEV-PHASE')
+gcc_DATESTAMP = __read_file('DATESTAMP')
+gcc_REVISION = __read_file('REVISION')
+
+VERSION_PACKAGE = os.getenv('VERSION_PACKAGE', '(GCC)')
+BUGURL = os.getenv('BUGURL', 'https://gcc.gnu.org/bugs/')
+MONOCHROMATIC = os.getenv('MONOCHROMATIC')
+
+# The short X.Y version.
+version = gcc_BASEVER
+
+# The full version, including alpha/beta/rc tags.
+release = ('%s (%s %s%s)'
+           % (gcc_BASEVER, gcc_DEVPHASE, gcc_DATESTAMP,
+              (' %s' % gcc_REVISION) if gcc_REVISION else ''))
+
+rst_prolog = r'''
+.. |gol| raw:: latex
+
+               \\
+.. |nbsp| unicode:: 0xA0
+  :trim:
+'''
+
+needs_sphinx = '5.3'
+
+rst_epilog = '''
+.. |gcc_version| replace:: %s
+.. |package_version| replace:: %s
+.. |bugurl| replace:: %s
+.. |needs_sphinx| replace:: %s
+''' % (gcc_BASEVER, VERSION_PACKAGE, BUGURL, needs_sphinx)
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'gcc_sphinx',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.todo',
+]
+
+if __get_builder_name() == 'html':
+    extensions.append('sphinx_copybutton')
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build']
+
+# Do not highlight by default
+highlight_language = 'none'
+
+# Select C++ as a primary domain
+primary_domain = 'cpp'
+
+cpp_id_attributes = ['HOST_WIDE_INT', '__memx']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'furo'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    'navigation_with_keys': True,
+}
+
+html_logo = '../logo.svg'
+
+html_favicon = '../favicon.ico'
+
+html_last_updated_fmt = ''
+
+html_context = {
+    'commit': __get_git_revision()
+}
+
+html_static_path = [
+    '../_static'
+]
+
+html_css_files = [
+    'custom.css'
+]
+
+# By default, do not generate any manual pages
+man_pages = []
+
+# FIXME: handle WARNINGs: unknown option issues and cross refs
+suppress_warnings = [
+    'ref.option',
+]
+
+# Use xelatex by default
+latex_engine = 'xelatex'
+
+latex_logo = '../logo.pdf'
+
+latex_elements = {
+    'pointsize': '11pt',
+    'fontpkg': r'''
+\setmonofont[Scale=0.8]{DejaVu Sans Mono}
+''',
+    'preamble': r'''
+\fvset{formatcom=\let\textbf\relax}
+\protected\def\sphinxcrossref#1{#1}
+''',
+}
+
+if MONOCHROMATIC:
+    latex_elements['sphinxsetup'] = r'''
+TitleColor={black},
+InnerLinkColor={rgb}{0.0, 0.2, 0.6},
+OuterLinkColor={rgb}{0.0, 0.2, 0.6},
+'''
+
+latex_table_style = ['colorrows']
+
+texinfo_cross_references = False
+
+texinfo_elements = {'preamble': """
+@definfoenclose strong,*,*
+@definfoenclose emph,','
+"""
+}
+
+# Use default as RTD theme uses default as well
+pygments_style = 'bw' if MONOCHROMATIC else 'default'
+
+option_emphasise_placeholders = True
+
+# Ignore GitHub domain for link checking:
+# https://github.com/sphinx-doc/sphinx/issues/9016
+linkcheck_ignore = [
+    'https://github.com/.*#.*'
+]
+
+USER_LEVEL_DOCS = ('install', 'gcc', 'gfortran', 'cpp', 'gnat_rm', 'gnat_ugn',
+                   'gccgo', 'libgomp', 'libquadmath', 'libgccjit')
+INTERNAL_DOCS = ('gccint', 'cppinternals', 'gfc-internals', 'gnat-style')
+
+# Cross manual reference mapping
+intersphinx_mapping = {}
+for manual in USER_LEVEL_DOCS + INTERNAL_DOCS:
+    intersphinx_mapping[manual] = (f'https://splichal.eu/scripts/sphinx/{manual}/_build/html/', None)
+
+# Custom references
+extlinks = {
+    'P': ('https://wg21.link/p%s', 'P%s'),
+    'PR': ('https://gcc.gnu.org/PR%s', 'PR%s'),
+    'openmp': ('https://openmp.org/specifications/#%s', 'OpenMP specification v%s'),
+    'openacc': ('https://openacc.org/specification#%s', 'OpenACC specification v%s'),
+}
+
+extlinks_detect_hardcoded_links = True
+
+# Set common settings where we need NAME of the documentation
+def set_common(name, module):
+    module['tags'].add(name)
+    if gcc_DEVPHASE == 'experimental':
+        module['todo_include_todos'] = True
+        module['tags'].add('development')
+
+    html_theme_options['source_edit_link'] = f'https://splichal.eu/scripts/sphinx/{name}' \
+                                               '/_build/html/_sources/{filename}.txt'

doc/bsd.rst

@@ -0,0 +1,39 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+BSD
+===
+
+Copyright (C) 1990 Regents of the University of California.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+#. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+#. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+#. [rescinded 22 July 1999]
+
+#. Neither the name of the University nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS 'AS IS' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

doc/contribute.rst

@@ -0,0 +1,21 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _contributing:
+
+Contributing to GCC Development
+-------------------------------
+
+If you would like to help pretest GCC releases to assure they work well,
+current development sources are available via Git (see
+https://gcc.gnu.org/git.html).  Source and binary snapshots are
+also available for FTP; see https://gcc.gnu.org/snapshots.html.
+
+If you would like to work on improvements to GCC, please read the
+advice at these URLs: https://gcc.gnu.org/contribute.html, https://gcc.gnu.org/contributewhy.html.
+
+for information on how to make useful contributions and avoid
+duplication of effort.  Suggested projects are listed at
+https://gcc.gnu.org/projects/.

doc/cppdiropts.rst

@@ -0,0 +1,217 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. option:: -I {dir}, -iquote {dir}, -isystem {dir}, -idirafter {dir}
+
+  Add the directory :samp:`{dir}` to the list of directories to be searched
+  for header files during preprocessing.
+
+  .. only:: cpp
+
+    See :ref:`search-path`.
+
+  If :samp:`{dir}` begins with :samp:`=` or ``$SYSROOT``, then the :samp:`=`
+  or ``$SYSROOT`` is replaced by the sysroot prefix; see
+  :option:`--sysroot` and :option:`-isysroot`.
+
+  Directories specified with :option:`-iquote` apply only to the quote
+  form of the directive, ``#include "file"``.
+  Directories specified with :option:`-I`, :option:`-isystem`,
+  or :option:`-idirafter` apply to lookup for both the
+  ``#include "file"`` and
+  ``#include <file>`` directives.
+
+  You can specify any number or combination of these options on the
+  command line to search for header files in several directories.
+  The lookup order is as follows:
+
+  * For the quote form of the include directive, the directory of the current
+    file is searched first.
+
+  * For the quote form of the include directive, the directories specified
+    by :option:`-iquote` options are searched in left-to-right order,
+    as they appear on the command line.
+
+  * Directories specified with :option:`-I` options are scanned in
+    left-to-right order.
+
+  * Directories specified with :option:`-isystem` options are scanned in
+    left-to-right order.
+
+  * Standard system directories are scanned.
+
+  * Directories specified with :option:`-idirafter` options are scanned in
+    left-to-right order.
+
+  You can use :option:`-I` to override a system header
+  file, substituting your own version, since these directories are
+  searched before the standard system header file directories.
+  However, you should
+  not use this option to add directories that contain vendor-supplied
+  system header files; use :option:`-isystem` for that.
+
+  The :option:`-isystem` and :option:`-idirafter` options also mark the directory
+  as a system directory, so that it gets the same special treatment that
+  is applied to the standard system directories.
+
+  .. only:: cpp
+
+    See :ref:`system-headers`.
+
+
+  If a standard system include directory, or a directory specified with
+  :option:`-isystem`, is also specified with :option:`-I`, the :option:`-I`
+  option is ignored.  The directory is still searched but as a
+  system directory at its normal position in the system include chain.
+  This is to ensure that GCC's procedure to fix buggy system headers and
+  the ordering for the ``#include_next`` directive are not inadvertently
+  changed.
+  If you really need to change the search order for system directories,
+  use the :option:`-nostdinc` and/or :option:`-isystem` options.
+
+  .. only:: cpp
+
+    See :ref:`system-headers`.
+
+
+.. option:: -I-
+
+  Split the include path.
+  This option has been deprecated.  Please use :option:`-iquote` instead for
+  :option:`-I` directories before the :option:`-I-` and remove the :option:`-I-`
+  option.
+
+  Any directories specified with :option:`-I`
+  options before :option:`-I-` are searched only for headers requested with
+  ``#include "file"`` ; they are not searched for
+  ``#include <file>``.  If additional directories are
+  specified with :option:`-I` options after the :option:`-I-`, those
+  directories are searched for all :samp:`#include` directives.
+
+  In addition, :option:`-I-` inhibits the use of the directory of the current
+  file directory as the first search directory for ``#include
+  "file"``.  There is no way to override this effect of :option:`-I-`.
+
+  .. only:: cpp
+
+    See :ref:`search-path`.
+
+
+.. option:: -iprefix {prefix}
+
+  Specify :samp:`{prefix}` as the prefix for subsequent :option:`-iwithprefix`
+  options.  If the prefix represents a directory, you should include the
+  final :samp:`/`.
+
+.. option:: -iwithprefix {dir}, -iwithprefixbefore {dir}
+
+  Append :samp:`{dir}` to the prefix specified previously with
+  :option:`-iprefix`, and add the resulting directory to the include search
+  path.  :option:`-iwithprefixbefore` puts it in the same place :option:`-I`
+  would; :option:`-iwithprefix` puts it where :option:`-idirafter` would.
+
+.. option:: -isysroot {dir}
+
+  This option is like the :option:`--sysroot` option, but applies only to
+  header files (except for Darwin targets, where it applies to both header
+  files and libraries).  See the :option:`--sysroot` option for more
+  information.
+
+.. option:: -imultilib {dir}
+
+  Use :samp:`{dir}` as a subdirectory of the directory containing
+  target-specific C++ headers.
+
+.. option:: -nostdinc
+
+  Do not search the standard system directories for header files.
+  Only the directories explicitly specified with :option:`-I`,
+  :option:`-iquote`, :option:`-isystem`, and/or :option:`-idirafter`
+  options (and the directory of the current file, if appropriate)
+  are searched.
+
+.. option:: -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 the C++ library.)
+
+.. option:: -Wcomment, -Wcomments
+
+  Warn whenever a comment-start sequence :samp:`/*` appears in a :samp:`/*`
+  comment, or whenever a backslash-newline appears in a :samp:`//` comment.
+  This warning is enabled by :option:`-Wall`.
+
+.. option:: -Wtrigraphs
+
+.. _wtrigraphs:
+
+  Warn if any trigraphs are encountered that might change the meaning of
+  the program.  Trigraphs within comments are not warned about,
+  except those that would form escaped newlines.
+
+  This option is implied by :option:`-Wall`.  If :option:`-Wall` is not
+  given, this option is still enabled unless trigraphs are enabled.  To
+  get trigraph conversion without warnings, but get the other
+  :option:`-Wall` warnings, use :samp:`-trigraphs -Wall -Wno-trigraphs`.
+
+.. option:: -Wundef
+
+  Warn if an undefined identifier is evaluated in an ``#if`` directive.
+  Such identifiers are replaced with zero.
+
+.. option:: -Wno-undef
+
+  Default setting; overrides :option:`-Wundef`.
+
+.. option:: -Wexpansion-to-defined
+
+  Warn whenever :samp:`defined` is encountered in the expansion of a macro
+  (including the case where the macro is expanded by an :samp:`#if` directive).
+  Such usage is not portable.
+  This warning is also enabled by :option:`-Wpedantic` and :option:`-Wextra`.
+
+.. option:: -Wunused-macros
+
+  Warn about macros defined in the main file that are unused.  A macro
+  is :dfn:`used` if it is expanded or tested for existence at least once.
+  The preprocessor also warns if the macro has not been used at the
+  time it is redefined or undefined.
+
+  Built-in macros, macros defined on the command line, and macros
+  defined in include files are not warned about.
+
+  .. note::
+
+    If a macro is actually used, but only used in skipped
+    conditional blocks, then the preprocessor reports it as unused.  To avoid the
+    warning in such a case, you might improve the scope of the macro's
+    definition by, for example, moving it into the first skipped block.
+    Alternatively, you could provide a dummy use with something like:
+
+  .. code-block:: c++
+
+    #if defined the_macro_causing_the_warning
+    #endif
+
+.. option:: -Wno-endif-labels
+
+  Do not warn whenever an ``#else`` or an ``#endif`` are followed by text.
+  This sometimes happens in older programs with code of the form
+
+  .. code-block:: c++
+
+    #if FOO
+    ...
+    #else FOO
+    ...
+    #endif FOO
+
+  The second and third ``FOO`` should be in comments.
+  This warning is on by default.
+
+.. option:: -Wendif-labels
+
+  Default setting; overrides :option:`-Wno-endif-labels`.

doc/cppenv.rst

@@ -0,0 +1,97 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. envvar:: CPATH, C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH
+
+  .. Commented out until ObjC++ is part of GCC:
+     @itemx OBJCPLUS_INCLUDE_PATH
+
+  Each variable's value is a list of directories separated by a special
+  character, much like :envvar:`PATH`, in which to look for header files.
+  The special character, ``PATH_SEPARATOR``, is target-dependent and
+  determined at GCC build time.  For Microsoft Windows-based targets it is a
+  semicolon, and for almost all other targets it is a colon.
+
+  :envvar:`CPATH` specifies a list of directories to be searched as if
+  specified with :option:`-I`, but after any paths given with :option:`-I`
+  options on the command line.  This environment variable is used
+  regardless of which language is being preprocessed.
+
+  The remaining environment variables apply only when preprocessing the
+  particular language indicated.  Each specifies a list of directories
+  to be searched as if specified with :option:`-isystem`, but after any
+  paths given with :option:`-isystem` options on the command line.
+
+  In all these variables, an empty element instructs the compiler to
+  search its current working directory.  Empty elements can appear at the
+  beginning or end of a path.  For instance, if the value of
+  :envvar:`CPATH` is ``:/special/include``, that has the same
+  effect as :samp:`-I. -I/special/include`.
+
+  .. only:: cpp
+
+    See also :ref:`search-path`.
+
+.. index:: dependencies for make as output
+
+.. envvar:: DEPENDENCIES_OUTPUT
+
+  If this variable is set, its value specifies how to output
+  dependencies for Make based on the non-system header files processed
+  by the compiler.  System header files are ignored in the dependency
+  output.
+
+  The value of :envvar:`DEPENDENCIES_OUTPUT` can be just a file name, in
+  which case the Make rules are written to that file, guessing the target
+  name from the source file name.  Or the value can have the form
+  :samp:`{file}{target}`, in which case the rules are written to
+  file :samp:`{file}` using :samp:`{target}` as the target name.
+
+  In other words, this environment variable is equivalent to combining
+  the options :option:`-MM` and :option:`-MF`
+
+  .. only:: cpp
+
+    (see :ref:`invocation`),
+
+  .. only:: not cpp
+
+    (see :ref:`preprocessor-options`),
+
+  with an optional :option:`-MT` switch too.
+
+.. index:: dependencies for make as output
+
+.. envvar:: SUNPRO_DEPENDENCIES
+
+  This variable is the same as :envvar:`DEPENDENCIES_OUTPUT` (see above),
+  except that system header files are not ignored, so it implies
+  :option:`-M` rather than :option:`-MM`.  However, the dependence on the
+  main input file is omitted.
+
+  .. only:: cpp
+
+    See :ref:`invocation`.
+
+  .. only:: not cpp
+
+    See :ref:`preprocessor-options`.
+
+.. envvar:: SOURCE_DATE_EPOCH
+
+  If this variable is set, its value specifies a UNIX timestamp to be
+  used in replacement of the current date and time in the ``__DATE__``
+  and ``__TIME__`` macros, so that the embedded timestamps become
+  reproducible.
+
+  The value of :envvar:`SOURCE_DATE_EPOCH` must be a UNIX timestamp,
+  defined as the number of seconds (excluding leap seconds) since
+  01 Jan 1970 00:00:00 represented in ASCII; identical to the output of
+  ``date +%s`` on GNU/Linux and other systems that support the
+  ``%s`` extension in the ``date`` command.
+
+  The value should be a known timestamp such as the last modification
+  time of the source or package and it should be set by the build
+  process.

doc/cppopts.rst

@@ -0,0 +1,556 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. option:: -D {name}
+
+  Predefine :samp:`{name}` as a macro, with definition ``1``.
+
+.. option:: -D name=definition
+
+  The contents of :samp:`{definition}` are tokenized and processed as if
+  they appeared during translation phase three in a :samp:`#define`
+  directive.  In particular, the definition is truncated by
+  embedded newline characters.
+
+  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 wish to define a function-like macro on the command line, write
+  its argument list with surrounding parentheses before the equals sign
+  (if any).  Parentheses are meaningful to most shells, so you should
+  quote the option.  With :command:`sh` and :command:`csh`,
+  :option:`-D'name(args...)=definition'` works.
+
+  :option:`-D` and :option:`-U` options are processed in the order they
+  are given on the command line.  All :option:`-imacros file` and
+  :option:`-include file` options are processed after all
+  :option:`-D` and :option:`-U` options.
+
+.. option:: -U {name}
+
+  Cancel any previous definition of :samp:`{name}`, either built in or
+  provided with a :option:`-D` option.
+
+.. option:: -include {file}
+
+  Process :samp:`{file}` as if ``#include "file"`` appeared as the first
+  line of the primary source file.  However, the first directory searched
+  for :samp:`{file}` is the preprocessor's working directory *instead of*
+  the directory containing the main source file.  If not found there, it
+  is searched for in the remainder of the ``#include "..."`` search
+  chain as normal.
+
+  If multiple :option:`-include` options are given, the files are included
+  in the order they appear on the command line.
+
+.. option:: -imacros {file}
+
+  Exactly like :option:`-include`, except that any output produced by
+  scanning :samp:`{file}` is thrown away.  Macros it defines remain defined.
+  This allows you to acquire all the macros from a header without also
+  processing its declarations.
+
+  All files specified by :option:`-imacros` are processed before all files
+  specified by :option:`-include`.
+
+.. option:: -undef
+
+  Do not predefine any system-specific or GCC-specific macros.  The
+  standard predefined macros remain defined.
+
+  .. only:: cpp
+
+    See :ref:`standard-predefined-macros`.
+
+.. option:: -pthread
+
+  Define additional macros required for using the POSIX threads library.
+  You should use this option consistently for both compilation and linking.
+  This option is supported on GNU/Linux targets, most other Unix derivatives,
+  and also on x86 Cygwin and MinGW targets.
+
+.. index:: make, dependencies, make
+
+.. option:: -M
+
+  Instead of outputting the result of preprocessing, output a rule
+  suitable for :command:`make` describing the dependencies of the main
+  source file.  The preprocessor outputs one :command:`make` rule containing
+  the object file name for that source file, a colon, and the names of all
+  the included files, including those coming from :option:`-include` or
+  :option:`-imacros` command-line options.
+
+  Unless specified explicitly (with :option:`-MT` or :option:`-MQ`), the
+  object file name consists of the name of the source file with any
+  suffix replaced with object file suffix and with any leading directory
+  parts removed.  If there are many included files then the rule is
+  split into several lines using :samp:`\\` -newline.  The rule has no
+  commands.
+
+  This option does not suppress the preprocessor's debug output, such as
+  :option:`-dM`.  To avoid mixing such debug output with the dependency
+  rules you should explicitly specify the dependency output file with
+  :option:`-MF`, or use an environment variable like
+  :envvar:`DEPENDENCIES_OUTPUT` (see :ref:`environment-variables`).  Debug output
+  is still sent to the regular output stream as normal.
+
+  Passing :option:`-M` to the driver implies :option:`-E`, and suppresses
+  warnings with an implicit :option:`-w`.
+
+.. option:: -MM
+
+  Like :option:`-M` but do not mention header files that are found in
+  system header directories, nor header files that are included,
+  directly or indirectly, from such a header.
+
+  This implies that the choice of angle brackets or double quotes in an
+  :samp:`#include` directive does not in itself determine whether that
+  header appears in :option:`-MM` dependency output.
+
+.. option:: -MF {file}
+
+  When used with :option:`-M` or :option:`-MM`, specifies a
+  file to write the dependencies to.  If no :option:`-MF` switch is given
+  the preprocessor sends the rules to the same place it would send
+  preprocessed output.
+
+  When used with the driver options :option:`-MD` or :option:`-MMD`,
+  :option:`-MF` overrides the default dependency output file.
+
+  If :samp:`{file}` is :samp:`-`, then the dependencies are written to :samp:`stdout`.
+
+.. option:: -MG
+
+  In conjunction with an option such as :option:`-M` requesting
+  dependency generation, :option:`-MG` assumes missing header files are
+  generated files and adds them to the dependency list without raising
+  an error.  The dependency filename is taken directly from the
+  ``#include`` directive without prepending any path.  :option:`-MG`
+  also suppresses preprocessed output, as a missing header file renders
+  this useless.
+
+  This feature is used in automatic updating of makefiles.
+
+.. option:: -Mno-modules
+
+  Disable dependency generation for compiled module interfaces.
+
+.. option:: -MP
+
+  This option instructs CPP to add a phony target for each dependency
+  other than the main file, causing each to depend on nothing.  These
+  dummy rules work around errors :command:`make` gives if you remove header
+  files without updating the :samp:`Makefile` to match.
+
+  This is typical output:
+
+  .. code-block:: c++
+
+    test.o: test.c test.h
+
+    test.h:
+
+.. option:: -MT {target}
+
+  Change the target of the rule emitted by dependency generation.  By
+  default CPP takes the name of the main input file, deletes any
+  directory components and any file suffix such as :samp:`.c`, and
+  appends the platform's usual object suffix.  The result is the target.
+
+  An :option:`-MT` option sets the target 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.
+
+  For example, ``-MT '$(objpfx)foo.o'`` might give
+
+  .. code-block:: c++
+
+    $(objpfx)foo.o: foo.c
+
+.. option:: -MQ {target}
+
+  Same as :option:`-MT`, but it quotes any characters which are special to
+  Make. ``-MQ '$(objpfx)foo.o'`` gives
+
+  .. code-block:: c++
+
+    $$(objpfx)foo.o: foo.c
+
+  The default target is automatically quoted, as if it were given with
+  :option:`-MQ`.
+
+.. option:: -MD
+
+  :option:`-MD` is equivalent to :option:`-M -MF file`, except that
+  :option:`-E` is not implied.  The driver determines :samp:`{file}` based on
+  whether an :option:`-o` option is given.  If it is, the driver uses its
+  argument but with a suffix of :samp:`.d`, otherwise it takes the name
+  of the input file, removes any directory components and suffix, and
+  applies a :samp:`.d` suffix.
+
+  If :option:`-MD` is used in conjunction with :option:`-E`, any
+  :option:`-o` switch is understood to specify the dependency output file
+  (see :option:`-MF`), but if used without :option:`-E`, each :option:`-o`
+  is understood to specify a target object file.
+
+  Since :option:`-E` is not implied, :option:`-MD` can be used to generate
+  a dependency output file as a side effect of the compilation process.
+
+.. option:: -MMD
+
+  Like :option:`-MD` except mention only user header files, not system
+  header files.
+
+.. option:: -fpreprocessed
+
+  Indicate to the preprocessor that the input file has already been
+  preprocessed.  This suppresses things like macro expansion, trigraph
+  conversion, escaped newline splicing, and processing of most directives.
+  The preprocessor still recognizes and removes comments, so that you can
+  pass a file preprocessed with :option:`-C` to the compiler without
+  problems.  In this mode the integrated preprocessor is little more than
+  a tokenizer for the front ends.
+
+  :option:`-fpreprocessed` is implicit if the input file has one of the
+  extensions :samp:`.i`, :samp:`.ii` or :samp:`.mi`.  These are the
+  extensions that GCC uses for preprocessed files created by
+  :option:`-save-temps`.
+
+.. option:: -fdirectives-only
+
+  When preprocessing, handle directives, but do not expand macros.
+
+  The option's behavior depends on the :option:`-E` and :option:`-fpreprocessed`
+  options.
+
+  With :option:`-E`, preprocessing is limited to the handling of directives
+  such as ``#define``, ``#ifdef``, and ``#error``.  Other
+  preprocessor operations, such as macro expansion and trigraph
+  conversion are not performed.  In addition, the :option:`-dD` option is
+  implicitly enabled.
+
+  With :option:`-fpreprocessed`, predefinition of command line and most
+  builtin macros is disabled.  Macros such as ``__LINE__``, which are
+  contextually dependent, are handled normally.  This enables compilation of
+  files previously preprocessed with ``-E -fdirectives-only``.
+
+  With both :option:`-E` and :option:`-fpreprocessed`, the rules for
+  :option:`-fpreprocessed` take precedence.  This enables full preprocessing of
+  files previously preprocessed with ``-E -fdirectives-only``.
+
+.. option:: -fdollars-in-identifiers
+
+  Accept :samp:`$` in identifiers.
+
+  .. only:: cpp
+
+    See :ref:`identifier-characters`.
+
+.. option:: -fextended-identifiers
+
+  Accept universal character names and extended characters in
+  identifiers.  This option is enabled by default for C99 (and later C
+  standard versions) and C++.
+
+.. option:: -fno-canonical-system-headers
+
+  When preprocessing, do not shorten system header paths with canonicalization.
+
+.. option:: -fmax-include-depth={depth}
+
+  Set the maximum depth of the nested #include. The default is 200.
+
+.. option:: -ftabstop={width}
+
+  Set the distance between tab stops.  This helps the preprocessor report
+  correct column numbers in warnings or errors, even if tabs appear on the
+  line.  If the value is less than 1 or greater than 100, the option is
+  ignored.  The default is 8.
+
+.. option:: -ftrack-macro-expansion[={level}]
+
+  Track locations of tokens across macro expansions. This allows the
+  compiler to emit diagnostic about the current macro expansion stack
+  when a compilation error occurs in a macro expansion. Using this
+  option makes the preprocessor and the compiler consume more
+  memory. The :samp:`{level}` parameter can be used to choose the level of
+  precision of token location tracking thus decreasing the memory
+  consumption if necessary. Value :samp:`0` of :samp:`{level}` de-activates
+  this option. Value :samp:`1` tracks tokens locations in a
+  degraded mode for the sake of minimal memory overhead. In this mode
+  all tokens resulting from the expansion of an argument of a
+  function-like macro have the same location. Value :samp:`2` tracks
+  tokens locations completely. This value is the most memory hungry.
+  When this option is given no argument, the default parameter value is
+  :samp:`2`.
+
+  Note that ``-ftrack-macro-expansion=2`` is activated by default.
+
+.. option:: -fmacro-prefix-map={old}={new}
+
+  When preprocessing files residing in directory :samp:`{old}`,
+  expand the ``__FILE__`` and ``__BASE_FILE__`` macros as if the
+  files resided in directory :samp:`{new}` instead.  This can be used
+  to change an absolute path to a relative path by using :samp:`.` for
+  :samp:`{new}` which can result in more reproducible builds that are
+  location independent.  This option also affects
+  ``__builtin_FILE()`` during compilation.  See also
+  :option:`-ffile-prefix-map`.
+
+.. index:: character set, execution
+
+.. option:: -fexec-charset={charset}
+
+  Set the execution character set, used for string and character
+  constants.  The default is UTF-8.  :samp:`{charset}` can be any encoding
+  supported by the system's ``iconv`` library routine.
+
+.. index:: character set, wide execution
+
+.. option:: -fwide-exec-charset={charset}
+
+  Set the wide execution character set, used for wide string and
+  character constants.  The default is one of UTF-32BE, UTF-32LE, UTF-16BE,
+  or UTF-16LE, whichever corresponds to the width of ``wchar_t`` and the
+  big-endian or little-endian byte order being used for code generation.  As
+  with :option:`-fexec-charset`, :samp:`{charset}` can be any encoding supported
+  by the system's ``iconv`` library routine; however, you will have
+  problems with encodings that do not fit exactly in ``wchar_t``.
+
+.. index:: character set, input
+
+.. option:: -finput-charset={charset}
+
+  Set the input character set, used for translation from the character
+  set of the input file to the source character set used by GCC.  If the
+  locale does not specify, or GCC cannot get this information from the
+  locale, the default is UTF-8.  This can be overridden by either the locale
+  or this command-line option.  Currently the command-line option takes
+  precedence if there's a conflict.  :samp:`{charset}` can be any encoding
+  supported by the system's ``iconv`` library routine.
+
+.. only:: not cpp
+
+  .. option:: -fpch-deps
+
+    When using precompiled headers (see :ref:`precompiled-headers`), this flag
+    causes the dependency-output flags to also list the files from the
+    precompiled header's dependencies.  If not specified, only the
+    precompiled header are listed and not the files that were used to
+    create it, because those files are not consulted when a precompiled
+    header is used.
+
+  .. option:: -fpch-preprocess
+
+    This option allows use of a precompiled header (see :ref:`precompiled-headers`) together with :option:`-E`.  It inserts a special ``#pragma``,
+    ``#pragma GCC pch_preprocess "filename"`` in the output to mark
+    the place where the precompiled header was found, and its :samp:`{filename}`.
+    When :option:`-fpreprocessed` is in use, GCC recognizes this ``#pragma``
+    and loads the PCH.
+
+    This option is off by default, because the resulting preprocessed output
+    is only really suitable as input to GCC.  It is switched on by
+    :option:`-save-temps`.
+
+    You should not write this ``#pragma`` in your own code, but it is
+    safe to edit the filename if the PCH file is available in a different
+    location.  The filename may be absolute or it may be relative to GCC's
+    current directory.
+
+.. option:: -fworking-directory
+
+  Enable generation of linemarkers in the preprocessor output that
+  let the compiler know the current working directory at the time of
+  preprocessing.  When this option is enabled, the preprocessor
+  emits, after the initial linemarker, a second linemarker with the
+  current working directory followed by two slashes.  GCC uses this
+  directory, when it's present in the preprocessed input, as the
+  directory emitted as the current working directory in some debugging
+  information formats.  This option is implicitly enabled if debugging
+  information is enabled, but this can be inhibited with the negated
+  form :option:`-fno-working-directory`.  If the :option:`-P` flag is
+  present in the command line, this option has no effect, since no
+  ``#line`` directives are emitted whatsoever.
+
+.. option:: -fno-working-directory
+
+  Default setting; overrides :option:`-fworking-directory`.
+
+.. option:: -A {predicate}={answer}
+
+  Make an assertion with the predicate :samp:`{predicate}` and answer
+  :samp:`{answer}`.  This form is preferred to the older form :option:`-A
+  predicate(answer)`, which is still supported, because
+  it does not use shell special characters.
+
+  .. only:: cpp
+
+    See :ref:`obsolete-features`.
+
+.. option:: -A -predicate=answer
+
+  Cancel an assertion with the predicate :samp:`{predicate}` and answer
+  :samp:`{answer}`.
+
+.. option:: -C
+
+  Do not discard comments.  All comments are passed through to the output
+  file, except for comments in processed directives, which are deleted
+  along with the directive.
+
+  You should be prepared for side effects when using :option:`-C` ; it
+  causes the preprocessor to treat comments as tokens in their own right.
+  For example, comments appearing at the start of what would be a
+  directive line have the effect of turning that line into an ordinary
+  source line, since the first token on the line is no longer a :samp:`#`.
+
+.. option:: -CC
+
+  Do not discard comments, including during macro expansion.  This is
+  like :option:`-C`, except that comments contained within macros are
+  also passed through to the output file where the macro is expanded.
+
+  In addition to the side effects of the :option:`-C` option, the
+  :option:`-CC` option causes all C++-style comments inside a macro
+  to be converted to C-style comments.  This is to prevent later use
+  of that macro from inadvertently commenting out the remainder of
+  the source line.
+
+  The :option:`-CC` option is generally used to support lint comments.
+
+.. option:: -P
+
+  Inhibit generation of linemarkers 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
+  linemarkers.
+
+  .. only:: cpp
+
+    See :ref:`preprocessor-output`.
+
+  .. index:: traditional C language, C language, traditional
+
+.. option:: -traditional, -traditional-cpp
+
+  Try to imitate the behavior of pre-standard C preprocessors, as
+  opposed to ISO C preprocessors.
+
+  .. only:: cpp
+
+    See :ref:`traditional-mode`.
+
+  .. only:: not cpp
+
+    See the GNU CPP manual for details.
+
+  Note that GCC does not otherwise attempt to emulate a pre-standard
+  C compiler, and these options are only supported with the :option:`-E`
+  switch, or when invoking CPP explicitly.
+
+.. option:: -trigraphs
+
+  Support ISO C trigraphs.
+  These are three-character sequences, all starting with :samp:`??`, that
+  are defined by ISO C to stand for single characters.  For example,
+  :samp:`??/` stands for :samp:`\\`, so :samp:`??/n` is a character
+  constant for a newline.
+
+  .. only:: cpp
+
+    See :ref:`initial-processing`.
+
+  .. only:: not cpp
+
+    The nine trigraphs and their replacements are
+
+    .. code-block::
+
+      Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
+      Replacement:      [    ]    {    }    #    \    ^    |    ~
+
+  By default, GCC ignores trigraphs, but in
+  standard-conforming modes it converts them.  See the :option:`-std` and
+  :option:`-ansi` options.
+
+.. option:: -remap
+
+  Enable special code to work around file systems which only permit very
+  short file names, such as MS-DOS.
+
+.. option:: -H
+
+  Print the name of each header file used, in addition to other normal
+  activities.  Each name is indented to show how deep in the
+  :samp:`#include` stack it is.  Precompiled header files are also
+  printed, even if they are found to be invalid; an invalid precompiled
+  header file is printed with :samp:`...x` and a valid one with :samp:`...!` .
+
+.. option:: -dletters
+
+  Says to make debugging dumps during compilation as specified by
+  :samp:`{letters}`.  The flags documented here are those relevant to the
+  preprocessor.  Other :samp:`{letters}` are interpreted
+  by the compiler proper, or reserved for future versions of GCC, and so
+  are silently ignored.  If you specify :samp:`{letters}` whose behavior
+  conflicts, the result is undefined.
+
+  .. only:: not cpp
+
+    See :ref:`developer-options`, for more information.
+
+  .. option:: -dM
+
+    Instead of the normal output, generate a list of :samp:`#define`
+    directives 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 :samp:`foo.h`, the command
+
+    .. code-block:: c++
+
+      touch foo.h; cpp -dM foo.h
+
+    shows all the predefined macros.
+
+    .. only:: cpp
+
+      If you use :option:`-dM` without the :option:`-E` option, :option:`-dM` is
+      interpreted as a synonym for :option:`-fdump-rtl-mach`.
+      See :ref:`developer-options`.
+
+  .. option:: -dD
+
+    Like :option:`-dM` except in two respects: it does *not* include the
+    predefined macros, and it outputs *both* the :samp:`#define`
+    directives and the result of preprocessing.  Both kinds of output go to
+    the standard output file.
+
+  .. option:: -dN
+
+    Like :option:`-dD`, but emit only the macro names, not their expansions.
+
+  .. option:: -dI
+
+    Output :samp:`#include` directives in addition to the result of
+    preprocessing.
+
+  .. option:: -dU
+
+    Like :option:`-dD` except that only macros that are expanded, or whose
+    definedness is tested in preprocessor directives, are output; the
+    output is delayed until the use or test of the macro; and
+    :samp:`#undef` directives are also output for macros tested but
+    undefined at the time.
+
+.. option:: -fdebug-cpp
+
+  This option is only useful for debugging GCC.  When used from CPP or with
+  :option:`-E`, it dumps debugging information about location maps.  Every
+  token in the output is preceded by the dump of the map its location
+  belongs to.
+
+  When used from GCC without :option:`-E`, this option has no effect.

doc/cppwarnopts.rst

@@ -0,0 +1,4 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.

doc/funding.rst

@@ -0,0 +1,47 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Funding Free Software
+=====================
+
+If you want to have more free software a few years from now, it makes
+sense for you to help encourage people to contribute funds for its
+development.  The most effective approach known is to encourage
+commercial redistributors to donate.
+
+Users of free software systems can boost the pace of development by
+encouraging for-a-fee distributors to donate part of their selling price
+to free software developers-the Free Software Foundation, and others.
+
+The way to convince distributors to do this is to demand it and expect
+it from them.  So when you compare distributors, judge them partly by
+how much they give to free software development.  Show distributors
+they must compete to be the one who gives the most.
+
+To make this approach work, you must insist on numbers that you can
+compare, such as, 'We will donate ten dollars to the Frobnitz project
+for each disk sold.'  Don't be satisfied with a vague promise, such as
+'A portion of the profits are donated,' since it doesn't give a basis
+for comparison.
+
+Even a precise fraction 'of the profits from this disk' is not very
+meaningful, since creative accounting and unrelated business decisions
+can greatly alter what fraction of the sales price counts as profit.
+If the price you pay is $50, ten percent of the profit is probably
+less than a dollar; it might be a few cents, or nothing at all.
+
+Some redistributors do development work themselves.  This is useful too;
+but to keep everyone honest, you need to inquire how much they do, and
+what kind.  Some kinds of development make much more long-term
+difference than others.  For example, maintaining a separate version of
+a program contributes very little; maintaining the standard version of a
+program for the whole community contributes much.  Easy new ports
+contribute little, since someone else would surely do them; difficult
+ports such as adding a new CPU to the GNU Compiler Collection contribute more;
+major new features or packages contribute the most.
+
+By establishing the idea that supporting further development is 'the
+proper thing to do' when distributing free software for a fee, we can
+assure a steady flow of resources into making more free software.

doc/gcc_sphinx.py

@@ -0,0 +1,44 @@
+# GCC Sphinx customization
+
+__version__ = '1.0'
+
+
+def setup(app):
+    app.add_object_type('gcc-attr', 'gcc-attr', objname='GCC attribute',
+                        indextemplate='pair: %s; attribute')
+    app.add_object_type('fn-attr', 'fn-attr', objname='function attribute',
+                        indextemplate='pair: %s; function attribute')
+    app.add_object_type('var-attr', 'var-attr', objname='variable attribute',
+                        indextemplate='pair: %s; variable attribute')
+    app.add_object_type('type-attr', 'type-attr', objname='type attribute',
+                        indextemplate='pair: %s; variable attribute')
+    app.add_object_type('enum-attr', 'enum-attr', objname='Enumerator attribute',
+                        indextemplate='pair: %s; enumerator attribute')
+    app.add_object_type('label-attr', 'label-attr', objname='Label attribute',
+                        indextemplate='pair: %s; label attribute')
+    app.add_object_type('gcc-param', 'gcc-param', objname='GCC parameter',
+                        indextemplate='pair: %s; parameter')
+
+    targets = (('AArch64 ', 'aarch64'), ('AMD GCN ', 'amd-gcn'), ('ARC ', 'arc'), ('ARM ', 'arm'), ('AVR ', 'avr'),
+               ('Blackfin ', 'blackfin'), ('BPF ', 'bpf'), ('C-SKY ', 'c-sky'),
+               ('Epiphany ', 'epiphany'), ('H8/300 ', 'h8-300'), ('IA-64 ', 'ia-64'), ('LoongArch', 'loongarch'), ('M32C ', 'm32c'),
+               ('M32R/D ', 'm32r-d'), ('m68k ', 'm68k'), ('MCORE ', 'mcore'), ('MeP ', 'mep'),
+               ('MicroBlaze ', 'microblaze'), ('Microsoft Windows ', 'microsoft-windows'), ('MIPS ', 'mips'),
+               ('MSP430 ', 'msp430'), ('NDS32 ', 'nds32'), ('Nios II ', 'nios-ii'), ('Nvidia PTX ', 'nvidia-ptx'),
+               ('PowerPC ', 'powerpc'), ('RISC-V ', 'risc-v'), ('RL78 ', 'rl78'), ('RX ', 'rx'), ('S/390 ', 's-390'),
+               ('SH ', 'sh'), ('Symbian OS ', 'symbian-os'), ('V850 ', 'v850'), ('Visium ', 'visium'), ('x86 ', 'x86'),
+               ('Xstormy16 ', 'xstormy16'))
+
+    for target_name, target in targets:
+        app.add_object_type(f'{target}-fn-attr', f'{target}-fn-attr', objname=f'{target_name} function attribute',
+                            indextemplate=f'pair: %s; {target_name} function attribute')
+        app.add_object_type(f'{target}-var-attr', f'{target}-var-attr', objname=f'{target_name} variable attribute',
+                            indextemplate=f'pair: %s; {target_name} variable attribute')
+        app.add_object_type(f'{target}-type-attr', f'{target}-type-attr', objname=f'{target_name} type attribute',
+                            indextemplate=f'pair: %s; {target_name} type attribute')
+
+    return dict(
+        version=__version__,
+        parallel_read_safe=True,
+        parallel_write_safe=True
+    )

doc/gnu.rst

@@ -0,0 +1,19 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _gnu-project:
+
+The GNU Project and GNU/Linux
+=============================
+
+The GNU Project was launched in 1984 to develop a complete Unix-like
+operating system which is free software: the GNU system.  (GNU is a
+recursive acronym for 'GNU's Not Unix'; it is pronounced
+'guh-NEW'.)  Variants of the GNU operating system, which use the
+kernel Linux, are now widely used; though these systems are often
+referred to as 'Linux', they are more accurately called GNU/Linux
+systems.
+
+For more information, see: https://www.gnu.org/ and https://www.gnu.org/gnu/linux-and-gnu.html.

doc/gnu_free_documentation_license.rst

@@ -0,0 +1,476 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _gnu_fdl:
+
+******************************
+GNU Free Documentation License
+******************************
+
+Version 1.3, 3 November 2008
+
+Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
+https://fsf.org/
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Preamble
+~~~~~~~~
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+1. APPLICABILITY AND DEFINITIONS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The **Document**, below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as "**you**".  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A "**Modified Version**" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "**Secondary Section**" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject.  (Thus, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "**Invariant Sections**" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The "**Cover Texts**" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A "**Transparent**" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not "Transparent" is called **Opaque**.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification.  Examples of
+transparent image formats include PNG, XCF and JPG.  Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The "**Title Page**" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The "**publisher**" means any person or entity that distributes
+copies of the Document to the public.
+
+A section "**Entitled XYZ**" means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as "**Acknowledgements**",
+"**Dedications**", "**Endorsements**", or "**History**".)
+To "**Preserve the Title**"
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+2. VERBATIM COPYING
+~~~~~~~~~~~~~~~~~~~
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+3. COPYING IN QUANTITY
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+4. MODIFICATIONS
+~~~~~~~~~~~~~~~~
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+   from that of the Document, and from those of previous versions
+   (which should, if there were any, be listed in the History section
+   of the Document).  You may use the same title as a previous version
+   if the original publisher of that version gives permission.
+
+B. List on the Title Page, as authors, one or more persons or entities
+   responsible for authorship of the modifications in the Modified
+   Version, together with at least five of the principal authors of the
+   Document (all of its principal authors, if it has fewer than five),
+   unless they release you from this requirement.
+
+C. State on the Title page the name of the publisher of the
+   Modified Version, as the publisher.
+
+D. Preserve all the copyright notices of the Document.
+
+E. Add an appropriate copyright notice for your modifications
+   adjacent to the other copyright notices.
+
+F. Include, immediately after the copyright notices, a license notice
+   giving the public permission to use the Modified Version under the
+   terms of this License, in the form shown in the Addendum below.
+
+G. Preserve in that license notice the full lists of Invariant Sections
+   and required Cover Texts given in the Document's license notice.
+H. Include an unaltered copy of this License.
+
+I. Preserve the section Entitled "History", Preserve its Title, and add
+   to it an item stating at least the title, year, new authors, and
+   publisher of the Modified Version as given on the Title Page.  If
+   there is no section Entitled "History" in the Document, create one
+   stating the title, year, authors, and publisher of the Document as
+   given on its Title Page, then add an item describing the Modified
+   Version as stated in the previous sentence.
+
+J. Preserve the network location, if any, given in the Document for
+   public access to a Transparent copy of the Document, and likewise
+   the network locations given in the Document for previous versions
+   it was based on.  These may be placed in the "History" section.
+   You may omit a network location for a work that was published at
+   least four years before the Document itself, or if the original
+   publisher of the version it refers to gives permission.
+
+K. For any section Entitled "Acknowledgements" or "Dedications",
+   Preserve the Title of the section, and preserve in the section all
+   the substance and tone of each of the contributor acknowledgements
+   and/or dedications given therein.
+
+L. Preserve all the Invariant Sections of the Document,
+   unaltered in their text and in their titles.  Section numbers
+   or the equivalent are not considered part of the section titles.
+
+M. Delete any section Entitled "Endorsements".  Such a section
+   may not be included in the Modified Version.
+
+N. Do not retitle any existing section to be Entitled "Endorsements"
+   or to conflict in title with any Invariant Section.
+
+O. Preserve any Warranty Disclaimers.
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+5. COMBINING DOCUMENTS
+~~~~~~~~~~~~~~~~~~~~~~
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications".  You must delete all sections
+Entitled "Endorsements".
+
+6. COLLECTIONS OF DOCUMENTS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+8. TRANSLATION
+~~~~~~~~~~~~~~
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+9. TERMINATION
+~~~~~~~~~~~~~~
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+10. FUTURE REVISIONS OF THIS LICENSE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+https://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+11. RELICENSING
+~~~~~~~~~~~~~~~
+
+"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+"Massive Multiauthor Collaboration" (or "MMC") contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+"Incorporate" means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is "eligible for relicensing" if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+    Copyright © YEAR  YOUR NAME.
+    Permission is granted to copy, distribute and/or modify this document
+    under the terms of the GNU Free Documentation License, Version 1.3
+    or any later version published by the Free Software Foundation;
+    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+    A copy of the license is included in the section entitled "GNU
+    Free Documentation License".
+
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with ... Texts." line with this:
+
+    with the Invariant Sections being LIST THEIR TITLES, with the
+    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.

doc/gpl-3.0.rst

@@ -0,0 +1,707 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+GNU GENERAL PUBLIC LICENSE
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. https://fsf.org/
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Preamble
+########
+
+The GNU General Public License is a free, copyleft license for software
+and other kinds of works.
+
+The licenses for most software and other practical works are designed to
+take away your freedom to share and change the works. By contrast, the
+GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users. We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors. You can apply it to
+your programs, too.
+
+When we speak of free software, we are referring to freedom, not price.
+Our General Public Licenses are designed to make sure that you have the
+freedom to distribute copies of free software (and charge for them if
+you wish), that you receive source code or can get it if you want it,
+that you can change the software or use pieces of it in new free
+programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these
+rights or asking you to surrender the rights. Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis
+or for a fee, you must pass on to the recipients the same freedoms that
+you received. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1)
+assert copyright on the software, and (2) offer you this License giving
+you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so. This is fundamentally incompatible with the aim of protecting
+users' freedom to change the software. The systematic pattern of such
+abuse occurs in the area of products for individuals to use, which is
+precisely where it is most unacceptable. Therefore, we have designed
+this version of the GPL to prohibit the practice for those products. If
+such problems arise substantially in other domains, we stand ready to
+extend this provision to those domains in future versions of the GPL, as
+needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary. To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+TERMS AND CONDITIONS
+####################
+
+0. Definitions.
+^^^^^^^^^^^^^^^
+
+"This License" refers to version 3 of the GNU General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based on
+the Program.
+
+To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to
+the extent that it includes a convenient and prominently visible feature
+that (1) displays an appropriate copyright notice, and (2) tells the
+user that there is no warranty for the work (except to the extent that
+warranties are provided), that licensees may convey the work under this
+License, and how to view a copy of this License. If the interface
+presents a list of user commands or options, such as a menu, a prominent
+item in the list meets this criterion.
+
+1. Source Code.
+^^^^^^^^^^^^^^^
+
+The "source code" for a work means the preferred form of the work for
+making modifications to it. "Object code" means any non-source form of a
+work.
+
+A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that is
+widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that Major
+Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A "Major
+Component", in this context, means a major essential component (kernel,
+window system, and so on) of the specific operating system (if any) on
+which the executable work runs, or a compiler used to produce the work,
+or an object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all the
+source code needed to generate, install, and (for an executable work)
+run the object code and to modify the work, including scripts to control
+those activities. However, it does not include the work's System
+Libraries, or general-purpose tools or generally available free programs
+which are used unmodified in performing those activities but which are
+not part of the work. For example, Corresponding Source includes
+interface definition files associated with source files for the work,
+and the source code for shared libraries and dynamically linked
+subprograms that the work is specifically designed to require, such as
+by intimate data communication or control flow between those subprograms
+and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+2. Basic Permissions.
+^^^^^^^^^^^^^^^^^^^^^
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright. Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below. Sublicensing is not allowed; section 10 makes
+it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article 11
+of the WIPO copyright treaty adopted on 20 December 1996, or similar
+laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to the
+covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+4. Conveying Verbatim Copies.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice; keep
+intact all notices stating that this License and any non-permissive
+terms added in accord with section 7 apply to the code; keep intact all
+notices of the absence of any warranty; and give all recipients a copy
+of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and
+you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the terms
+of section 4, provided that you also meet all of these conditions:
+
+a) The work must carry prominent notices stating that you modified
+   it, and giving a relevant date.
+
+b) The work must carry prominent notices stating that it is released
+   under this License and any conditions added under section 7. This
+   requirement modifies the requirement in section 4 to "keep intact
+   all notices".
+
+c) You must license the entire work, as a whole, under this License
+   to anyone who comes into possession of a copy. This License will
+   therefore apply, along with any applicable section 7 additional
+   terms, to the whole of the work, and all its parts, regardless of
+   how they are packaged. This License gives no permission to license
+   the work in any other way, but it does not invalidate such
+   permission if you have separately received it.
+
+d) If the work has interactive user interfaces, each must display
+   Appropriate Legal Notices; however, if the Program has interactive
+   interfaces that do not display Appropriate Legal Notices, your
+   work need not make them do so.
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work, and
+which are not combined with it such as to form a larger program, in or
+on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not used
+to limit the access or legal rights of the compilation's users beyond
+what the individual works permit. Inclusion of a covered work in an
+aggregate does not cause this License to apply to the other parts of the
+aggregate.
+
+6. Conveying Non-Source Forms.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+a) Convey the object code in, or embodied in, a physical product
+   (including a physical distribution medium), accompanied by the
+   Corresponding Source fixed on a durable physical medium
+   customarily used for software interchange.
+
+b) Convey the object code in, or embodied in, a physical product
+   (including a physical distribution medium), accompanied by a
+   written offer, valid for at least three years and valid for as
+   long as you offer spare parts or customer support for that product
+   model, to give anyone who possesses the object code either (1) a
+   copy of the Corresponding Source for all the software in the
+   product that is covered by this License, on a durable physical
+   medium customarily used for software interchange, for a price no
+   more than your reasonable cost of physically performing this
+   conveying of source, or (2) access to copy the Corresponding
+   Source from a network server at no charge.
+
+c) Convey individual copies of the object code with a copy of the
+   written offer to provide the Corresponding Source. This
+   alternative is allowed only occasionally and noncommercially, and
+   only if you received the object code with such an offer, in accord
+   with subsection 6b.
+
+d) Convey the object code by offering access from a designated place
+   (gratis or for a charge), and offer equivalent access to the
+   Corresponding Source in the same way through the same place at no
+   further charge. You need not require recipients to copy the
+   Corresponding Source along with the object code. If the place to
+   copy the object code is a network server, the Corresponding Source
+   may be on a different server (operated by you or a third party)
+   that supports equivalent copying facilities, provided you maintain
+   clear directions next to the object code saying where to find the
+   Corresponding Source. Regardless of what server hosts the
+   Corresponding Source, you remain obligated to ensure that it is
+   available for as long as needed to satisfy these requirements.
+
+e) Convey the object code using peer-to-peer transmission, provided
+   you inform other peers where the object code and Corresponding
+   Source of the work are being offered to the general public at no
+   charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be included
+in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling. In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of coverage.
+For a particular product received by a particular user, "normally used"
+refers to a typical or common use of that class of product, regardless
+of the status of the particular user or of the way in which the
+particular user actually uses, or expects or is expected to use, the
+product. A product is a consumer product regardless of whether the
+product has substantial commercial, industrial or non-consumer uses,
+unless such uses represent the only significant mode of use of the
+product.
+
+"Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product
+from a modified version of its Corresponding Source. The information
+must suffice to ensure that the continued functioning of the modified
+object code is in no case prevented or interfered with solely because
+modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied by
+the Installation Information. But this requirement does not apply if
+neither you nor any third party retains the ability to install modified
+object code on the User Product (for example, the work has been
+installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in
+accord with this section must be in a format that is publicly documented
+(and with an implementation available to the public in source code
+form), and must require no special password or key for unpacking,
+reading or copying.
+
+7. Additional Terms.
+^^^^^^^^^^^^^^^^^^^^
+
+"Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by this
+License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove
+any additional permissions from that copy, or from any part of it.
+(Additional permissions may be written to require their own removal in
+certain cases when you modify the work.) You may place additional
+permissions on material, added by you to a covered work, for which you
+have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders
+of that material) supplement the terms of this License with terms:
+
+a) Disclaiming warranty or limiting liability differently from the
+   terms of sections 15 and 16 of this License; or
+
+b) Requiring preservation of specified reasonable legal notices or
+   author attributions in that material or in the Appropriate Legal
+   Notices displayed by works containing it; or
+
+c) Prohibiting misrepresentation of the origin of that material, or
+   requiring that modified versions of such material be marked in
+   reasonable ways as different from the original version; or
+
+d) Limiting the use for publicity purposes of names of licensors or
+   authors of the material; or
+
+e) Declining to grant rights under trademark law for use of some
+   trade names, trademarks, or service marks; or
+
+f) Requiring indemnification of licensors and authors of that
+   material by anyone who conveys the material (or modified versions
+   of it) with contractual assumptions of liability to the recipient,
+   for any liability that these contractual assumptions directly
+   impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains a
+further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms of
+that license document, provided that the further restriction does not
+survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must
+place, in the relevant source files, a statement of the additional terms
+that apply to those files, or a notice indicating where to find the
+applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the above
+requirements apply either way.
+
+8. Termination.
+^^^^^^^^^^^^^^^
+
+You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally terminates
+your license, and (b) permanently, if the copyright holder fails to
+notify you of the violation by some reasonable means prior to 60 days
+after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated
+permanently if the copyright holder notifies you of the violation by
+some reasonable means, this is the first time you have received notice
+of violation of this License (for any work) from that copyright holder,
+and you cure the violation prior to 30 days after your receipt of the
+notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You are not required to accept this License in order to receive or run a
+copy of the Program. Ancillary propagation of a covered work occurring
+solely as a consequence of using peer-to-peer transmission to receive a
+copy likewise does not require acceptance. However, nothing other than
+this License grants you permission to propagate or modify any covered
+work. These actions infringe copyright if you do not accept this
+License. Therefore, by modifying or propagating a covered work, you
+indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered work
+results from an entity transaction, each party to that transaction who
+receives a copy of the work also receives whatever licenses to the work
+the party's predecessor in interest had or could give under the previous
+paragraph, plus a right to possession of the Corresponding Source of the
+work from the predecessor in interest, if the predecessor has it or can
+get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may not
+impose a license fee, royalty, or other charge for exercise of rights
+granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that any
+patent claim is infringed by making, using, selling, offering for sale,
+or importing the Program or any portion of it.
+
+11. Patents.
+^^^^^^^^^^^^
+
+A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The work
+thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned or
+controlled by the contributor, whether already acquired or hereafter
+acquired, that would be infringed by some manner, permitted by this
+License, of making, using, or selling its contributor version, but do
+not include claims that would be infringed only as a consequence of
+further modification of the contributor version. For purposes of this
+definition, "control" includes the right to grant patent sublicenses in
+a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to make,
+use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and
+the Corresponding Source of the work is not available for anyone to
+copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify or
+convey a specific copy of the covered work, then the patent license you
+grant is automatically extended to all recipients of the covered work
+and works based on it.
+
+A patent license is "discriminatory" if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License. You may not convey a covered work if you are
+a party to an arrangement with a third party that is in the business of
+distributing software, under which you make payment to the third party
+based on the extent of your activity of conveying the work, and under
+which the third party grants, to any of the parties who would receive
+the covered work from you, a discriminatory patent license (a) in
+connection with copies of the covered work conveyed by you (or copies
+made from those copies), or (b) primarily for and in connection with
+specific products or compilations that contain the covered work, unless
+you entered into that arrangement, or that patent license was granted,
+prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any
+implied license or other defenses to infringement that may otherwise be
+available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not convey it at all. For example, if you agree to terms that
+obligate you to collect a royalty for further conveying from those to
+whom you convey the Program, the only way you could satisfy both those
+terms and this License would be to refrain entirely from conveying the
+Program.
+
+13. Use with the GNU Affero General Public License.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Notwithstanding any other provision of this License, you have permission
+to link or combine any covered work with a work licensed under version 3
+of the GNU Affero General Public License into a single combined work,
+and to convey the resulting work. The terms of this License will
+continue to apply to the part which is the covered work, but the special
+requirements of the GNU Affero General Public License, section 13,
+concerning interaction through a network will apply to the combination
+as such.
+
+14. Revised Versions of this License.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies that a certain numbered version of the GNU General Public
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that numbered version or of
+any later version published by the Free Software Foundation. If the
+Program does not specify a version number of the GNU General Public
+License, you may choose any version ever published by the Free Software
+Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU General Public License can be used, that proxy's public
+statement of acceptance of a version permanently authorizes you to
+choose that version for the Program.
+
+Later license versions may give you additional or different permissions.
+However, no additional obligations are imposed on any author or
+copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
+THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
+SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
+WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the disclaimer of warranty and limitation of liability provided above
+cannot be given local legal effect according to their terms, reviewing
+courts shall apply local law that most closely approximates an absolute
+waiver of all civil liability in connection with the Program, unless a
+warranty or assumption of liability accompanies a copy of the Program in
+return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+#############################################
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program. It is safest to
+attach them to the start of each source file to most effectively state
+the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+::
+
+        <one line to give the program's name and a brief idea of what it does.>
+        Copyright (C) <year>  <name of author>
+
+        This program is free software: you can redistribute it and/or modify
+        it under the terms of the GNU General Public License as published by
+        the Free Software Foundation, either version 3 of the License, or
+        (at your option) any later version.
+
+        This program is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        GNU General Public License for more details.
+
+        You should have received a copy of the GNU General Public License
+        along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice
+like this when it starts in an interactive mode:
+
+::
+
+        <program>  Copyright (C) <year>  <name of author>
+        This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+        This is free software, and you are welcome to redistribute it
+        under certain conditions; type `show c' for details.
+
+The hypothetical commands \`show w' and \`show c' should show the
+appropriate parts of the General Public License. Of course, your
+program's commands might be different; for a GUI interface, you would
+use an "about box".
+
+You should also get your employer (if you work as a programmer) or
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. For more information on this, and how to apply and follow the
+GNU GPL, see https://www.gnu.org/licenses/.
+
+The GNU General Public License does not permit incorporating your
+program into proprietary programs. If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library. If this is what you want to do, use the
+GNU Lesser General Public License instead of this License. But first,
+please read https://www.gnu.org/licenses/why-not-lgpl.html.

doc/indices-and-tables.rst

@@ -0,0 +1,13 @@
+.. only:: html
+
+  Indexes and tables
+  ==================
+
+  :ref:`genindex`
+
+  .. only:: development
+
+    TODO
+    ----
+
+    .. todolist::

doc/lgpl-2.1.rst

@@ -0,0 +1,514 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+GNU LESSER GENERAL PUBLIC LICENSE
+---------------------------------
+
+.. index:: LGPL, Lesser General Public License
+
+Version 2.1, February 1999
+
+Copyright (C) 1991-2022 Free Software Foundation, Inc.
+51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+as the successor of the GNU Library Public License, version 2, hence the
+version number 2.1.]
+
+Preamble
+^^^^^^^^
+
+The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software---to make sure the software is free for all its users.
+
+This license, the Lesser General Public License, applies to some
+specially designated software---typically libraries---of the Free
+Software Foundation and other authors who decide to use it.  You can use
+it too, but we suggest you first think carefully about whether this
+license or the ordinary General Public License is the better strategy to
+use in any particular case, based on the explanations below.
+
+When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of it
+in new free programs; and that you are informed that you can do these
+things.
+
+To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+We call this license the :dfn:`Lesser` General Public License because it
+does *Less* to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+'work based on the library' and a 'work that uses the library'.  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+#. This License Agreement applies to any software library or other program
+    which contains a notice placed by the copyright holder or other
+    authorized party saying it may be distributed under the terms of this
+    Lesser General Public License (also called 'this License').  Each
+    licensee is addressed as 'you'.
+
+    A 'library' means a collection of software functions and/or data
+    prepared so as to be conveniently linked with application programs
+    (which use some of those functions and data) to form executables.
+
+    The 'Library', below, refers to any such software library or work
+    which has been distributed under these terms.  A 'work based on the
+    Library' means either the Library or any derivative work under
+    copyright law: that is to say, a work containing the Library or a
+    portion of it, either verbatim or with modifications and/or translated
+    straightforwardly into another language.  (Hereinafter, translation is
+    included without limitation in the term 'modification'.)
+
+    'Source code' for a work means the preferred form of the work for
+    making modifications to it.  For a library, complete source code means
+    all the source code for all modules it contains, plus any associated
+    interface definition files, plus the scripts used to control compilation
+    and installation of the library.
+
+    Activities other than copying, distribution and modification are not
+    covered by this License; they are outside its scope.  The act of
+    running a program using the Library is not restricted, and output from
+    such a program is covered only if its contents constitute a work based
+    on the Library (independent of the use of the Library in a tool for
+    writing it).  Whether that is true depends on what the Library does
+    and what the program that uses the Library does.
+
+#. You may copy and distribute verbatim copies of the Library's
+    complete source code as you receive it, in any medium, provided that
+    you conspicuously and appropriately publish on each copy an
+    appropriate copyright notice and disclaimer of warranty; keep intact
+    all the notices that refer to this License and to the absence of any
+    warranty; and distribute a copy of this License along with the
+    Library.
+
+    You may charge a fee for the physical act of transferring a copy,
+    and you may at your option offer warranty protection in exchange for a
+    fee.
+
+#. You may modify your copy or copies of the Library or any portion
+    of it, thus forming a work based on the Library, and copy and
+    distribute such modifications or work under the terms of Section 1
+    above, provided that you also meet all of these conditions:
+
+    a* The modified work must itself be a software library.
+
+    * You must cause the files modified to carry prominent notices
+      stating that you changed the files and the date of any change.
+
+    * You must cause the whole of the work to be licensed at no
+      charge to all third parties under the terms of this License.
+
+    * If a facility in the modified Library refers to a function or a
+      table of data to be supplied by an application program that uses
+      the facility, other than as an argument passed when the facility
+      is invoked, then you must make a good faith effort to ensure that,
+      in the event an application does not supply such function or
+      table, the facility still operates, and performs whatever part of
+      its purpose remains meaningful.
+
+      (For example, a function in a library to compute square roots has
+      a purpose that is entirely well-defined independent of the
+      application.  Therefore, Subsection 2d requires that any
+      application-supplied function or table used by this function must
+      be optional: if the application does not supply it, the square
+      root function must still compute square roots.)
+
+    These requirements apply to the modified work as a whole.  If
+    identifiable sections of that work are not derived from the Library,
+    and can be reasonably considered independent and separate works in
+    themselves, then this License, and its terms, do not apply to those
+    sections when you distribute them as separate works.  But when you
+    distribute the same sections as part of a whole which is a work based
+    on the Library, the distribution of the whole must be on the terms of
+    this License, whose permissions for other licensees extend to the
+    entire whole, and thus to each and every part regardless of who wrote
+    it.
+
+    Thus, it is not the intent of this section to claim rights or contest
+    your rights to work written entirely by you; rather, the intent is to
+    exercise the right to control the distribution of derivative or
+    collective works based on the Library.
+
+    In addition, mere aggregation of another work not based on the Library
+    with the Library (or with a work based on the Library) on a volume of
+    a storage or distribution medium does not bring the other work under
+    the scope of this License.
+
+#. You may opt to apply the terms of the ordinary GNU General Public
+    License instead of this License to a given copy of the Library.  To do
+    this, you must alter all the notices that refer to this License, so
+    that they refer to the ordinary GNU General Public License, version 2,
+    instead of to this License.  (If a newer version than version 2 of the
+    ordinary GNU General Public License has appeared, then you can specify
+    that version instead if you wish.)  Do not make any other change in
+    these notices.
+
+    Once this change is made in a given copy, it is irreversible for
+    that copy, so the ordinary GNU General Public License applies to all
+    subsequent copies and derivative works made from that copy.
+
+    This option is useful when you wish to copy part of the code of
+    the Library into a program that is not a library.
+
+#. You may copy and distribute the Library (or a portion or
+    derivative of it, under Section 2) in object code or executable form
+    under the terms of Sections 1 and 2 above provided that you accompany
+    it with the complete corresponding machine-readable source code, which
+    must be distributed under the terms of Sections 1 and 2 above on a
+    medium customarily used for software interchange.
+
+    If distribution of object code is made by offering access to copy
+    from a designated place, then offering equivalent access to copy the
+    source code from the same place satisfies the requirement to
+    distribute the source code, even though third parties are not
+    compelled to copy the source along with the object code.
+
+#. A program that contains no derivative of any portion of the
+    Library, but is designed to work with the Library by being compiled or
+    linked with it, is called a 'work that uses the Library'.  Such a
+    work, in isolation, is not a derivative work of the Library, and
+    therefore falls outside the scope of this License.
+
+    However, linking a 'work that uses the Library' with the Library
+    creates an executable that is a derivative of the Library (because it
+    contains portions of the Library), rather than a 'work that uses the
+    library'.  The executable is therefore covered by this License.
+    Section 6 states terms for distribution of such executables.
+
+    When a 'work that uses the Library' uses material from a header file
+    that is part of the Library, the object code for the work may be a
+    derivative work of the Library even though the source code is not.
+    Whether this is true is especially significant if the work can be
+    linked without the Library, or if the work is itself a library.  The
+    threshold for this to be true is not precisely defined by law.
+
+    If such an object file uses only numerical parameters, data
+    structure layouts and accessors, and small macros and small inline
+    functions (ten lines or less in length), then the use of the object
+    file is unrestricted, regardless of whether it is legally a derivative
+    work.  (Executables containing this object code plus portions of the
+    Library will still fall under Section 6.)
+
+    Otherwise, if the work is a derivative of the Library, you may
+    distribute the object code for the work under the terms of Section 6.
+    Any executables containing that work also fall under Section 6,
+    whether or not they are linked directly with the Library itself.
+
+#. As an exception to the Sections above, you may also combine or
+    link a 'work that uses the Library' with the Library to produce a
+    work containing portions of the Library, and distribute that work
+    under terms of your choice, provided that the terms permit
+    modification of the work for the customer's own use and reverse
+    engineering for debugging such modifications.
+
+    You must give prominent notice with each copy of the work that the
+    Library is used in it and that the Library and its use are covered by
+    this License.  You must supply a copy of this License.  If the work
+    during execution displays copyright notices, you must include the
+    copyright notice for the Library among them, as well as a reference
+    directing the user to the copy of this License.  Also, you must do one
+    of these things:
+
+    a* Accompany the work with the complete corresponding
+      machine-readable source code for the Library including whatever
+      changes were used in the work (which must be distributed under
+      Sections 1 and 2 above); and, if the work is an executable linked
+      with the Library, with the complete machine-readable 'work that
+      uses the Library', as object code and/or source code, so that the
+      user can modify the Library and then relink to produce a modified
+      executable containing the modified Library.  (It is understood
+      that the user who changes the contents of definitions files in the
+      Library will not necessarily be able to recompile the application
+      to use the modified definitions.)
+
+    * Use a suitable shared library mechanism for linking with the Library.  A
+      suitable mechanism is one that (1) uses at run time a copy of the
+      library already present on the user's computer system, rather than
+      copying library functions into the executable, and (2) will operate
+      properly with a modified version of the library, if the user installs
+      one, as long as the modified version is interface-compatible with the
+      version that the work was made with.
+
+    * Accompany the work with a written offer, valid for at
+      least three years, to give the same user the materials
+      specified in Subsection 6a, above, for a charge no more
+      than the cost of performing this distribution.
+
+    * If distribution of the work is made by offering access to copy
+      from a designated place, offer equivalent access to copy the above
+      specified materials from the same place.
+
+    * Verify that the user has already received a copy of these
+      materials or that you have already sent this user a copy.
+
+    For an executable, the required form of the 'work that uses the
+    Library' must include any data and utility programs needed for
+    reproducing the executable from it.  However, as a special exception,
+    the materials to be distributed need not include anything that is
+    normally distributed (in either source or binary form) with the major
+    components (compiler, kernel, and so on) of the operating system on
+    which the executable runs, unless that component itself accompanies the
+    executable.
+
+    It may happen that this requirement contradicts the license
+    restrictions of other proprietary libraries that do not normally
+    accompany the operating system.  Such a contradiction means you cannot
+    use both them and the Library together in an executable that you
+    distribute.
+
+#. You may place library facilities that are a work based on the
+    Library side-by-side in a single library together with other library
+    facilities not covered by this License, and distribute such a combined
+    library, provided that the separate distribution of the work based on
+    the Library and of the other library facilities is otherwise
+    permitted, and provided that you do these two things:
+
+    a* Accompany the combined library with a copy of the same work
+      based on the Library, uncombined with any other library
+      facilities.  This must be distributed under the terms of the
+      Sections above.
+
+    * Give prominent notice with the combined library of the fact
+      that part of it is a work based on the Library, and explaining
+      where to find the accompanying uncombined form of the same work.
+
+#. You may not copy, modify, sublicense, link with, or distribute
+    the Library except as expressly provided under this License.  Any
+    attempt otherwise to copy, modify, sublicense, link with, or
+    distribute the Library is void, and will automatically terminate your
+    rights under this License.  However, parties who have received copies,
+    or rights, from you under this License will not have their licenses
+    terminated so long as such parties remain in full compliance.
+
+#. You are not required to accept this License, since you have not
+    signed it.  However, nothing else grants you permission to modify or
+    distribute the Library or its derivative works.  These actions are
+    prohibited by law if you do not accept this License.  Therefore, by
+    modifying or distributing the Library (or any work based on the
+    Library), you indicate your acceptance of this License to do so, and
+    all its terms and conditions for copying, distributing or modifying
+    the Library or works based on it.
+
+#. Each time you redistribute the Library (or any work based on the
+    Library), the recipient automatically receives a license from the
+    original licensor to copy, distribute, link with or modify the Library
+    subject to these terms and conditions.  You may not impose any further
+    restrictions on the recipients' exercise of the rights granted herein.
+    You are not responsible for enforcing compliance by third parties with
+    this License.
+
+#. If, as a consequence of a court judgment or allegation of patent
+    infringement or for any other reason (not limited to patent issues),
+    conditions are imposed on you (whether by court order, agreement or
+    otherwise) that contradict the conditions of this License, they do not
+    excuse you from the conditions of this License.  If you cannot
+    distribute so as to satisfy simultaneously your obligations under this
+    License and any other pertinent obligations, then as a consequence you
+    may not distribute the Library at all.  For example, if a patent
+    license would not permit royalty-free redistribution of the Library by
+    all those who receive copies directly or indirectly through you, then
+    the only way you could satisfy both it and this License would be to
+    refrain entirely from distribution of the Library.
+
+    If any portion of this section is held invalid or unenforceable under any
+    particular circumstance, the balance of the section is intended to apply,
+    and the section as a whole is intended to apply in other circumstances.
+
+    It is not the purpose of this section to induce you to infringe any
+    patents or other property right claims or to contest validity of any
+    such claims; this section has the sole purpose of protecting the
+    integrity of the free software distribution system which is
+    implemented by public license practices.  Many people have made
+    generous contributions to the wide range of software distributed
+    through that system in reliance on consistent application of that
+    system; it is up to the author/donor to decide if he or she is willing
+    to distribute software through any other system and a licensee cannot
+    impose that choice.
+
+    This section is intended to make thoroughly clear what is believed to
+    be a consequence of the rest of this License.
+
+#. If the distribution and/or use of the Library is restricted in
+    certain countries either by patents or by copyrighted interfaces, the
+    original copyright holder who places the Library under this License may add
+    an explicit geographical distribution limitation excluding those countries,
+    so that distribution is permitted only in or among countries not thus
+    excluded.  In such case, this License incorporates the limitation as if
+    written in the body of this License.
+
+#. The Free Software Foundation may publish revised and/or new
+    versions of the Lesser General Public License from time to time.
+    Such new versions will be similar in spirit to the present version,
+    but may differ in detail to address new problems or concerns.
+
+    Each version is given a distinguishing version number.  If the Library
+    specifies a version number of this License which applies to it and
+    'any later version', you have the option of following the terms and
+    conditions either of that version or of any later version published by
+    the Free Software Foundation.  If the Library does not specify a
+    license version number, you may choose any version ever published by
+    the Free Software Foundation.
+
+#. If you wish to incorporate parts of the Library into other free
+    programs whose distribution conditions are incompatible with these,
+    write to the author to ask for permission.  For software which is
+    copyrighted by the Free Software Foundation, write to the Free
+    Software Foundation; we sometimes make exceptions for this.  Our
+    decision will be guided by the two goals of preserving the free status
+    of all derivatives of our free software and of promoting the sharing
+    and reuse of software generally.
+
+    NO WARRANTY
+
+#. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+    WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+    EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+    OTHER PARTIES PROVIDE THE LIBRARY 'AS IS' WITHOUT WARRANTY OF ANY
+    KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+    PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+    LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+    THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+#. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+    WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+    AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+    FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+    LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+    FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+    DAMAGES.
+
+How to Apply These Terms to Your New Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+'copyright' line and a pointer to where the full notice is found.
+
+.. code-block::
+
+    one line to give the library's name and an idea of what it does.
+    Copyright (C) year  name of author
+
+    This library is free software; you can redistribute it and/or modify it
+    under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation; either version 2.1 of the License, or (at
+    your option) any later version.
+
+    This library is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+    USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a 'copyright disclaimer' for the library, if
+necessary.  Here is a sample; alter the names:
+
+.. code-block::
+
+    Yoyodyne, Inc., hereby disclaims all copyright interest in the library
+    `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+    signature of Ty Coon, 1 April 1990
+    Ty Coon, President of Vice
+
+That's all there is to it!

doc/requirements.txt

@@ -0,0 +1,3 @@
+Sphinx>=5.3
+furo
+sphinx_copybutton

gcc/d/doc/conf.py

@@ -0,0 +1,30 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sys
+sys.path.append('../../..//doc')
+
+from baseconf import *
+
+name = 'gdc'
+project = 'The GNU D Compiler'
+copyright = '2006-2022 Free Software Foundation, Inc.'
+authors = 'David Friedman, Iain Buclaw'
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+latex_documents = [
+  ('index', f'{name}.tex', project, authors, 'manual'),
+]
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('invoking-gdc', name, project, [authors], 1),
+]
+
+texinfo_documents = [
+  ('index', name, project, authors, None, None, None, True)
+]
+
+set_common(name, globals())

gcc/d/doc/copyright.rst

@@ -0,0 +1,13 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the GPL license file
+
+Copyright
+^^^^^^^^^
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is in the :ref:`gnu_fdl`.

gcc/d/doc/general-public-license-3.rst

@@ -0,0 +1,6 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. include:: ../../../doc/gpl-3.0.rst

gcc/d/doc/gnu-free-documentation-license.rst

@@ -0,0 +1,6 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. include:: ../../../doc/gnu_free_documentation_license.rst

gcc/d/doc/index.rst

@@ -0,0 +1,22 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+The GNU D Compiler
+==================
+
+This manual describes how to use :command:`gdc`, the GNU compiler for
+the D programming language.  This manual is specifically about
+:command:`gdc`.  For more information about the D programming
+language in general, including language specifications and standard
+package documentation, see https://dlang.org/.
+
+.. toctree::
+
+  copyright
+  invoking-gdc
+  general-public-license-3
+  gnu-free-documentation-license
+
+  indices-and-tables

gcc/d/doc/indices-and-tables.rst

@@ -0,0 +1 @@
+.. include:: ../../../doc/indices-and-tables.rst

gcc/d/doc/invoking-gdc.rst

@@ -0,0 +1,48 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _invoking-gdc:
+
+Invoking gdc
+------------
+
+.. only:: man
+
+  Synopsis
+  ^^^^^^^^
+
+  gdc [ :option:`-c` | :option:`-S` ] [ :option:`-g` ] [ :option:`-pg` ]
+      [ :option:`-O`:samp:`{level}` ] [ :option:`-W`:samp:`{warn}`...]
+      [ :option:`-I`:samp:`{dir}`...] [ :option:`-L`:samp:`{dir}`...]
+      [ :option:`-f`:samp:`{option}`...] [ :option:`-m`:samp:`{machine-option}`...]
+      [ :option:`-o` :samp:`{outfile}` ] [@ :samp:`{file}` ] :samp:`{infile}`...
+
+  Only the most useful options are listed here; see below for the
+  remainder.
+
+Description
+^^^^^^^^^^^
+
+The :command:`gdc` command is the GNU compiler for the D language and
+supports many of the same options as :command:`gcc`.  See :ref:`gcc:option-summary`.
+This manual only documents the options specific to :command:`gdc`.
+
+Options
+^^^^^^^
+
+.. toctree::
+  :maxdepth: 2
+
+  invoking-gdc/input-and-output-files
+  invoking-gdc/runtime-options
+  invoking-gdc/options-for-directory-search
+  invoking-gdc/code-generation
+  invoking-gdc/warnings
+  invoking-gdc/options-for-linking
+  invoking-gdc/developer-options
+
+.. only:: man
+
+  .. include:: copyright.rst

gcc/d/doc/invoking-gdc/code-generation.rst

@@ -0,0 +1,170 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: options, code generation
+
+.. _code-generation:
+
+Code Generation
+***************
+
+In addition to the many :command:`gcc` options controlling code generation,
+:command:`gdc` has several options specific to itself.
+
+.. option:: -H
+
+  .. index:: -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 :samp:`.di` suffix.
+
+.. option:: -Hd dir
+
+  .. index:: -Hd
+
+  Same as :option:`-H`, but writes interface files to directory :samp:`{dir}`.
+  This option can be used with :option:`-Hf file` to independently set the
+  output file and directory path.
+
+.. option:: -Hf file
+
+  .. index:: -Hf
+
+  Same as :option:`-H` but writes interface files to :samp:`{file}`.  This option can
+  be used with :option:`-Hd dir` to independently set the output file and
+  directory path.
+
+.. option:: -M
+
+  .. index:: -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.
+
+.. option:: -MM
+
+  .. index:: -MM
+
+  Like :option:`-M` but does not mention imported modules from the D standard
+  library package directories.
+
+.. option:: -MF file
+
+  .. index:: -MF
+
+  When used with :option:`-M` or :option:`-MM`, specifies a :samp:`{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.
+
+.. option:: -MG
+
+  .. index:: -MG
+
+  This option is for compatibility with :command:`gcc`, and is ignored by the
+  compiler.
+
+.. option:: -MP
+
+  .. index:: -MP
+
+  Outputs a phony target for each dependency other than the modules being
+  compiled, causing each to depend on nothing.
+
+.. option:: -MT target
+
+  .. index:: -MT
+
+  Change the :samp:`{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.
+
+.. option:: -MQ target
+
+  .. index:: -MQ
+
+  Same as :option:`-MT`, but it quotes any characters which are special to
+  :command:`make`.
+
+.. option:: -MD
+
+  .. index:: -MD
+
+  This option is equivalent to :option:`-M -MF file`.  The driver
+  determines :samp:`{file}` by removing any directory components and suffix
+  from the input file, and then adding a :samp:`.deps` suffix.
+
+.. option:: -MMD
+
+  .. index:: -MMD
+
+  Like :option:`-MD` but does not mention imported modules from the D standard
+  library package directories.
+
+.. option:: -X
+
+  .. index:: -X
+
+  Output information describing the contents of all source files being
+  compiled in JSON format to a file.  The driver determines :samp:`{file}` by
+  removing any directory components and suffix from the input file, and then
+  adding a :samp:`.json` suffix.
+
+.. option:: -Xf file
+
+  .. index:: -Xf
+
+  Same as :option:`-X`, but writes all JSON contents to the specified
+  :samp:`{file}`.
+
+.. option:: -fdoc
+
+  .. index:: -fdoc
+
+  Generates ``Ddoc`` documentation and writes it to a file.  The compiler
+  determines :samp:`{file}` by removing any directory components and suffix
+  from the input file, and then adding a :samp:`.html` suffix.
+
+.. option:: -fdoc-dir=dir
+
+  .. index:: -fdoc-dir
+
+  Same as :option:`-fdoc`, but writes documentation to directory :samp:`{dir}`.
+  This option can be used with :option:`-fdoc-file=file` to
+  independently set the output file and directory path.
+
+.. option:: -fdoc-file=file
+
+  .. index:: -fdoc-file
+
+  Same as :option:`-fdoc`, but writes documentation to :samp:`{file}`.  This
+  option can be used with :option:`-fdoc-dir=dir` to independently
+  set the output file and directory path.
+
+.. option:: -fdoc-inc=file
+
+  .. index:: -fdoc-inc
+
+  Specify :samp:`{file}` as a :samp:`{Ddoc}` macro file to be read.  Multiple
+  :option:`-fdoc-inc` options can be used, and files are read and processed
+  in the same order.
+
+.. option::  -fdump-c++-spec={file}
+
+  For D source files, generate corresponding C++ declarations in :samp:`{file}`.
+
+.. option:: -fdump-c++-spec-verbose
+
+  In conjunction with :option:`-fdump-c++-spec=` above, add comments for ignored
+  declarations in the generated C++ header.
+
+.. option:: -fsave-mixins={file}
+
+  Generates code expanded from D ``mixin`` statements and writes the
+  processed sources to :samp:`{file}`.  This is useful to debug errors in compilation
+  and provides source for debuggers to show when requested.

gcc/d/doc/invoking-gdc/developer-options.rst

@@ -0,0 +1,31 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: developer options, debug dump options, dump options
+
+.. _developer-options:
+
+Developer Options
+*****************
+
+This section describes command-line options that are primarily of
+interest to developers or language tooling.
+
+.. option:: -fdump-d-original
+
+  .. index:: -fdump-d-original
+
+  Output the internal front-end AST after the ``semantic3`` stage.
+  This option is only useful for debugging the GNU D compiler itself.
+
+.. option:: -v
+
+  .. index:: -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 ``parse``, ``semantic``, ``semantic2``, and
+  ``semantic3`` stages; all ``import`` modules and their file paths;
+  and all ``function`` bodies that are being compiled.

gcc/d/doc/invoking-gdc/input-and-output-files.rst

@@ -0,0 +1,45 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: suffixes for D source, D source file suffixes
+
+.. _input-and-output-files:
+
+Input and Output files
+**********************
+
+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:
+
+:samp:`{file}.d`
+  D source files.
+
+:samp:`{file}.dd`
+  Ddoc source files.
+
+:samp:`{file}.di`
+  D interface files.
+
+You can specify more than one input file on the :command:`gdc` command line,
+each being compiled separately in the compilation process.  If you specify a
+``-o file`` option, all the input files are compiled together,
+producing a single output file, named :samp:`{file}`.  This is allowed even
+when using ``-S`` or ``-c``.
+
+.. index:: D interface files.
+
+A D interface file contains only what an import of the module needs,
+rather than the whole implementation of that module.  They can be created
+by :command:`gdc` from a D source file by using the ``-H`` option.
+When the compiler resolves an import declaration, it searches for matching
+:samp:`.di` files first, then for :samp:`.d`.
+
+.. index:: Ddoc source files.
+
+A Ddoc source file contains code in the D macro processor language.  It is
+primarily designed for use in producing user documentation from embedded
+comments, with a slight affinity towards HTML generation.  If a :samp:`.d`
+source file starts with the string ``Ddoc`` then it is treated as general
+purpose documentation, not as a D source file.

gcc/d/doc/invoking-gdc/options-for-directory-search.rst

@@ -0,0 +1,92 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: directory options, options, directory search, search path
+
+.. _directory-options:
+
+Options for Directory Search
+****************************
+
+These options specify directories to search for files, libraries, and
+other parts of the compiler:
+
+.. option:: -Idir
+
+  .. index:: -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.
+
+.. option:: -Jdir
+
+  .. index:: -J
+
+  Specify a directory to use when searching for files in string imports
+  at compile time.  This switch is required in order to use
+  ``import(file)`` expressions.  Multiple :option:`-J` options can be
+  used, and the paths are searched in the same order.
+
+.. option:: -Ldir
+
+  .. index:: -L
+
+  When linking, specify a library search directory, as with :command:`gcc`.
+
+.. option:: -Bdir
+
+  .. index:: -B
+
+  This option specifies where to find the executables, libraries,
+  source files, and data files of the compiler itself, as with :command:`gcc`.
+
+.. option:: -fmodule-file=module=spec
+
+  .. index:: -fmodule-file
+
+  This option manipulates file paths of imported modules, such that if an
+  imported module matches all or the leftmost part of :samp:`{module}`, the file
+  path in :samp:`{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 hierarchy.  Consider the following examples:
+
+  .. code-block:: c++
+
+    gdc test.d -fmodule-file=A.B=foo.d -fmodule-file=C=bar
+
+  This will tell the compiler to search in all import paths for the source
+  file :samp:`{foo.d}` when importing :samp:`{A.B}`, and the directory :samp:`{bar/}`
+  when importing :samp:`{C}`, as annotated in the following D code:
+
+  .. code-block:: c++
+
+    module test;
+    import A.B;     // Matches A.B, searches for foo.d
+    import C.D.E;   // Matches C, searches for bar/D/E.d
+    import A.B.C;   // No match, searches for A/B/C.d
+
+.. option:: -imultilib dir
+
+  .. index:: -imultilib
+
+  Use :samp:`{dir}` as a subdirectory of the gcc directory containing
+  target-specific D sources and interfaces.
+
+.. option:: -iprefix prefix
+
+  .. index:: -iprefix
+
+  Specify :samp:`{prefix}` as the prefix for the gcc directory containing
+  target-specific D sources and interfaces.  If the :samp:`{prefix}` represents
+  a directory, you should include the final ``'/'``.
+
+.. option:: -nostdinc
+
+  .. index:: -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.

gcc/d/doc/invoking-gdc/options-for-linking.rst

@@ -0,0 +1,59 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: options, linking, linking, static
+
+.. _linking:
+
+Options for Linking
+*******************
+
+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.
+
+.. option:: -defaultlib=libname
+
+  .. index:: -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.
+
+.. option:: -debuglib=libname
+
+  .. index:: -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.
+
+.. option:: -nophoboslib
+
+  .. index:: -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.
+
+.. option:: -shared-libphobos
+
+  .. index:: -shared-libphobos
+
+  On systems that provide :samp:`libgphobos` and :samp:`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.
+
+.. option:: -static-libphobos
+
+  .. index:: -static-libphobos
+
+  On systems that provide :samp:`libgphobos` and :samp:`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,
+  this option has no effect.

gcc/d/doc/invoking-gdc/runtime-options.rst

@@ -0,0 +1,314 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: options, runtime
+
+.. _runtime-options:
+
+Runtime Options
+***************
+
+These options affect the runtime behavior of programs compiled with
+:command:`gdc`.
+
+.. option:: -fall-instantiations
+
+  .. index:: -fall-instantiations, -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 ``__traits(compiles, ...)``, or
+  that come from an imported module not being compiled.
+
+.. option:: -fno-assert
+
+  .. index:: -fassert, -fno-assert
+
+  Turn off code generation for ``assert`` contracts.
+
+.. option:: -fno-bounds-check
+
+  .. index:: -fbounds-check, -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
+  does violate array bounds constraints.  It is safe to use this option
+  if you are sure that your code never throws a ``RangeError``.
+
+.. option:: -fbounds-check=value
+
+  .. index:: -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:
+
+  :samp:`on`
+    Turns on array bounds checking for all functions.
+
+  :samp:`safeonly`
+    Turns on array bounds checking only for ``@safe`` functions.
+
+  :samp:`off`
+    Turns off array bounds checking completely.
+
+.. option:: -fno-builtin
+
+  .. index:: -fbuiltin, -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 ``core.stdc`` package is a built-in function.
+
+.. option:: -fcheckaction
+
+  This option controls what code is generated on an assertion, bounds check, or
+  final switch failure.  The following values are supported:
+
+  :samp:`context`
+    Throw an ``AssertError`` with extra context information.
+
+  :samp:`halt`
+    Halt the program execution.
+
+  :samp:`throw`
+    Throw an ``AssertError`` (the default).
+
+.. option:: -fdebug=value
+
+  .. index:: -fno-debug
+
+  Turn on compilation of conditional ``debug`` code into the program.
+  The :option:`-fdebug` option itself sets the debug level to ``1``,
+  while :option:`-fdebug=` enables ``debug`` code that are identified
+  by any of the following values:
+
+  :samp:`level`
+    Sets the debug level to :samp:`{level}`, any ``debug`` code <= :samp:`{level}`
+    is compiled into the program.
+
+  :samp:`ident`
+    Turns on compilation of any ``debug`` code identified by :samp:`{ident}`.
+
+.. option:: -fno-druntime
+
+  .. index:: -fdruntime, -fno-druntime
+
+  Implements https://dlang.org/spec/betterc.html.  Assumes that
+  compilation targets an environment without a D runtime library.
+
+  This is equivalent to compiling with the following options:
+
+  .. code-block:: c++
+
+    gdc -nophoboslib -fno-exceptions -fno-moduleinfo -fno-rtti
+
+.. option:: -fextern-std=standard
+
+  Sets the C++ name mangling compatibility to the version identified by
+  :samp:`{standard}`.  The following values are supported:
+
+  :samp:`c++98`, :samp:`c++03`
+    Sets ``__traits(getTargetInfo, "cppStd")`` to ``199711``.
+
+  :samp:`c++11`
+    Sets ``__traits(getTargetInfo, "cppStd")`` to ``201103``.
+
+  :samp:`c++14`
+    Sets ``__traits(getTargetInfo, "cppStd")`` to ``201402``.
+
+  :samp:`c++17`
+    Sets ``__traits(getTargetInfo, "cppStd")`` to ``201703``.
+    This is the default.
+
+  :samp:`c++20`
+    Sets ``__traits(getTargetInfo, "cppStd")`` to ``202002``.
+
+.. option:: -fno-invariants
+
+  .. index:: -finvariants, -fno-invariants
+
+  Turns off code generation for class ``invariant`` contracts.
+
+.. option:: -fmain
+
+  Generates a default ``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 ``main`` is already defined in user code.
+
+.. option:: -fno-moduleinfo
+
+  Turns off generation of the ``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
+  include module constructors and destructors (``static this`` and
+  ``static ~this``), ``unittest`` code, and ``DSO`` registry
+  functions for dynamically linked code.
+
+.. option:: -fonly=filename
+
+  .. index:: -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 :samp:`{filename}`.
+
+.. option:: -fno-postconditions
+
+  .. index:: -fpostconditions, -fno-postconditions
+
+  Turns off code generation for postcondition ``out`` contracts.
+
+.. option:: -fno-preconditions
+
+  .. index:: -fpreconditions, -fno-preconditions
+
+  Turns off code generation for precondition ``in`` contracts.
+
+.. option:: -fpreview=id
+
+  .. index:: -fpreview
+
+  Turns on an upcoming D language change identified by :samp:`{id}`.  The following
+  values are supported:
+
+  :samp:`all`
+    Turns on all upcoming D language features.
+
+  :samp:`dip1000`
+    Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md
+    (Scoped pointers).
+
+  :samp:`dip1008`
+    Implements https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md
+    (Allow exceptions in ``@nogc`` code).
+
+  :samp:`dip1021`
+    Implements https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md
+    (Mutable function arguments).
+
+  :samp:`dip25`
+    Implements https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md
+    (Sealed references).
+
+  :samp:`dtorfields`
+    Turns on generation for destructing fields of partially constructed objects.
+
+  :samp:`fieldwise`
+    Turns on generation of struct equality to use field-wise comparisons.
+
+  :samp:`fixaliasthis`
+    Implements new lookup rules that check the current scope for ``alias this``
+    before searching in upper scopes.
+
+  :samp:`fiximmutableconv`
+    Disallows unsound immutable conversions that were formerly incorrectly
+    permitted.
+
+  :samp:`in`
+    Implements ``in`` parameters to mean ``scope const [ref]`` and accepts
+    rvalues.
+
+  :samp:`inclusiveincontracts`
+    Implements ``in`` contracts of overridden methods to be a superset of parent
+    contract.
+
+  :samp:`intpromote`
+    Implements C-style integral promotion for unary ``+``, ``-`` and ``~``
+    expressions.
+
+  :samp:`nosharedaccess`
+    Turns off and disallows all access to shared memory objects.
+
+  :samp:`rvaluerefparam`
+    Implements rvalue arguments to ``ref`` parameters.
+
+  :samp:`systemvariables`
+    Disables access to variables marked ``@system`` from ``@safe`` code.
+
+.. option:: -frelease
+
+  .. index:: -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 ``@system`` and ``@trusted`` functions, and assertion
+  failures are undefined behavior.
+
+  This is equivalent to compiling with the following options:
+
+  .. code-block:: c++
+
+    gdc -fno-assert -fbounds-check=safe -fno-invariants \
+        -fno-postconditions -fno-preconditions -fno-switch-errors
+
+.. option:: -frevert=
+
+  .. index:: -frevert
+
+  Turns off a D language feature identified by :samp:`{id}`.  The following values
+  are supported:
+
+  :samp:`all`
+    Turns off all revertable D language features.
+
+  :samp:`dip25`
+    Reverts https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md
+    (Sealed references).
+
+  :samp:`dtorfields`
+    Turns off generation for destructing fields of partially constructed objects.
+
+  :samp:`markdown`
+    Turns off Markdown replacements in Ddoc comments.
+
+.. option:: -fno-rtti
+
+  .. index:: -frtti, -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.
+
+.. option:: -fno-switch-errors
+
+  .. index:: -fswitch-errors, -fno-switch-errors
+
+  This option controls what code is generated when no case is matched
+  in a ``final switch`` statement.  The default run time behavior
+  is to throw a ``SwitchError``.  Turning off :option:`-fswitch-errors`
+  means that instead the execution of the program is immediately halted.
+
+.. option:: -funittest
+
+  .. index:: -funittest, -fno-unittest
+
+  Turns on compilation of ``unittest`` code, and turns on the
+  ``version(unittest)`` identifier.  This implies :option:`-fassert`.
+
+.. option:: -fversion=value
+
+  .. index:: -fversion
+
+  Turns on compilation of conditional ``version`` code into the program
+  identified by any of the following values:
+
+  :samp:`level`
+    Sets the version level to :samp:`{level}`, any ``version`` code >= :samp:`{level}`
+    is compiled into the program.
+
+  :samp:`ident`
+    Turns on compilation of ``version`` code identified by :samp:`{ident}`.
+
+.. option:: -fno-weak-templates
+
+  .. index:: -fweak-templates, -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
+  symbols are instead put in COMDAT or become private.

gcc/d/doc/invoking-gdc/warnings.rst

@@ -0,0 +1,148 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: options to control warnings, warning messages, messages, warning, suppressing warnings
+
+.. _warnings:
+
+Warnings
+********
+
+Warnings are diagnostic messages that report constructions that
+are not inherently erroneous but that are risky or suggest there
+is likely to be a bug in the program.  Unless :option:`-Werror` is
+specified, they do not prevent compilation of the program.
+
+.. option:: -Wall
+
+  .. index:: -Wall, -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.
+
+.. option:: -Walloca
+
+  .. index:: -Walloca
+
+  This option warns on all uses of "alloca" in the source.
+
+.. option:: -Walloca-larger-than=n
+
+  .. index:: -Walloca-larger-than, -Wno-alloca-larger-than
+
+  Warn on unbounded uses of alloca, and on bounded uses of alloca
+  whose bound can be larger than :samp:`{n}` bytes.
+  :option:`-Wno-alloca-larger-than` disables
+  :option:`-Walloca-larger-than` warning and is equivalent to
+  :option:`-Walloca-larger-than=SIZE_MAX` or larger.
+
+.. option:: -Wcast-result
+
+  .. index:: -Wcast-result, -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.
+
+.. option:: -Wno-deprecated
+
+  .. index:: -Wdeprecated, -Wno-deprecated
+
+  Do not warn about usage of deprecated features and symbols with
+  ``deprecated`` attributes.
+
+.. option:: -Werror
+
+  .. index:: -Werror, -Wno-error
+
+  Turns all warnings into errors.
+
+.. option:: -Wspeculative
+
+  .. index:: -Wspeculative, -Wno-speculative
+
+  List all error messages from speculative compiles, such as
+  ``__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.
+
+.. option:: -Wtemplates
+
+  .. index:: -Wtemplates, -Wno-templates
+
+  Warn when a template instantiation is encountered.  Some coding
+  rules disallow templates, and this may be used to enforce that rule.
+
+.. option:: -Wunknown-pragmas
+
+  .. index:: -Wunknown-pragmas, -Wno-unknown-pragmas
+
+  Warn when a ``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.
+
+.. option:: -Wno-varargs
+
+  .. index:: Wvarargs, Wno-varargs
+
+  Do not warn upon questionable usage of the macros used to handle variable
+  arguments like ``va_start``.
+
+.. option:: -fignore-unknown-pragmas
+
+  .. index:: -fignore-unknown-pragmas, -fno-ignore-unknown-pragmas
+
+  Turns off errors for unsupported pragmas.
+
+.. option:: -fmax-errors=n
+
+  .. index:: -fmax-errors
+
+  Limits the maximum number of error messages to :samp:`{n}`, at which point
+  :command:`gdc` bails out rather than attempting to continue processing the
+  source code.  If :samp:`{n}` is 0 (the default), there is no limit on the
+  number of error messages produced.
+
+.. option:: -fsyntax-only
+
+  .. index:: -fsyntax-only, -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.
+
+.. option:: -ftransition=id
+
+  .. index:: -ftransition
+
+  Report additional information about D language changes identified by
+  :samp:`{id}`.  The following values are supported:
+
+  :samp:`all`
+    List information on all D language transitions.
+
+  :samp:`complex`
+    List all usages of complex or imaginary types.
+
+  :samp:`field`
+    List all non-mutable fields which occupy an object instance.
+
+  :samp:`in`
+    List all usages of ``in`` on parameter.
+
+  :samp:`nogc`
+    List all hidden GC allocations.
+
+  :samp:`templates`
+    List statistics on template instantiations.
+
+  :samp:`tls`
+    List all variables going into thread local storage.
+
+  :samp:`vmarkdown`
+    List instances of Markdown replacements in Ddoc.

gcc/doc/cpp/character-sets.rst

@@ -0,0 +1,56 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _character-sets:
+
+Character sets
+**************
+
+Source code character set processing in C and related languages is
+rather complicated.  The C standard discusses two character sets, but
+there are really at least four.
+
+The files input to CPP might be in any character set at all.  CPP's
+very first action, before it even looks for line boundaries, is to
+convert the file into the character set it uses for internal
+processing.  That set is what the C standard calls the :dfn:`source`
+character set.  It must be isomorphic with ISO 10646, also known as
+Unicode.  CPP uses the UTF-8 encoding of Unicode.
+
+The character sets of the input files are specified using the
+:option:`-finput-charset=` option.
+
+All preprocessing work (the subject of the rest of this manual) is
+carried out in the source character set.  If you request textual
+output from the preprocessor with the :option:`-E` option, it will be
+in UTF-8.
+
+After preprocessing is complete, string and character constants are
+converted again, into the :dfn:`execution` character set.  This
+character set is under control of the user; the default is UTF-8,
+matching the source character set.  Wide string and character
+constants have their own character set, which is not called out
+specifically in the standard.  Again, it is under control of the user.
+The default is UTF-16 or UTF-32, whichever fits in the target's
+``wchar_t`` type, in the target machine's byte
+order [#f1]_.
+
+Octal and hexadecimal escape sequences do not undergo
+conversion; ``'\x12'`` has the value 0x12 regardless of the currently
+selected execution character set.  All other escapes are replaced by
+the character in the source character set that they represent, then
+converted to the execution character set, just like unescaped
+characters.
+
+In identifiers, characters outside the ASCII range can be specified
+with the :samp:`\\u` and :samp:`\\U` escapes or used directly in the input
+encoding.  If strict ISO C90 conformance is specified with an option
+such as :option:`-std=c90`, or :option:`-fno-extended-identifiers` is
+used, then those constructs are not permitted in identifiers.
+
+.. [#f1] UTF-16 does not meet the requirements of the C
+  standard for a wide character set, but the choice of 16-bit
+  ``wchar_t`` is enshrined in some system ABIs so we cannot fix
+  this.

gcc/doc/cpp/conditional-syntax.rst

@@ -0,0 +1,411 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: #if
+
+.. _conditional-syntax:
+
+Conditional Syntax
+******************
+
+A conditional in the C preprocessor begins with a :dfn:`conditional
+directive`: :samp:`#if`, :samp:`#ifdef` or :samp:`#ifndef`.
+
+.. toctree::
+  :maxdepth: 2
+
+
+.. index:: #ifdef, #endif
+
+.. _ifdef:
+
+Ifdef
+^^^^^
+
+The simplest sort of conditional is
+
+.. code-block:: c++
+
+  #ifdef MACRO
+
+  controlled text
+
+  #endif /* MACRO */
+
+.. index:: conditional group
+
+This block is called a :dfn:`conditional group`.  :samp:`{controlled text}`
+will be included in the output of the preprocessor if and only if
+:samp:`{MACRO}` is defined.  We say that the conditional :dfn:`succeeds` if
+:samp:`{MACRO}` is defined, :dfn:`fails` if it is not.
+
+The :samp:`{controlled text}` inside of a conditional can include
+preprocessing directives.  They are executed only if the conditional
+succeeds.  You can nest conditional groups inside other conditional
+groups, but they must be completely nested.  In other words,
+:samp:`#endif` always matches the nearest :samp:`#ifdef` (or
+:samp:`#ifndef`, or :samp:`#if`).  Also, you cannot start a conditional
+group in one file and end it in another.
+
+Even if a conditional fails, the :samp:`{controlled text}` inside it is
+still run through initial transformations and tokenization.  Therefore,
+it must all be lexically valid C.  Normally the only way this matters is
+that all comments and string literals inside a failing conditional group
+must still be properly ended.
+
+The comment following the :samp:`#endif` is not required, but it is a
+good practice if there is a lot of :samp:`{controlled text}`, because it
+helps people match the :samp:`#endif` to the corresponding :samp:`#ifdef`.
+Older programs sometimes put :samp:`{MACRO}` directly after the
+:samp:`#endif` without enclosing it in a comment.  This is invalid code
+according to the C standard.  CPP accepts it with a warning.  It
+never affects which :samp:`#ifndef` the :samp:`#endif` matches.
+
+.. index:: #ifndef
+
+Sometimes you wish to use some code if a macro is *not* defined.
+You can do this by writing :samp:`#ifndef` instead of :samp:`#ifdef`.
+One common use of :samp:`#ifndef` is to include code only the first
+time a header file is included.  See :ref:`once-only-headers`.
+
+Macro definitions can vary between compilations for several reasons.
+Here are some samples.
+
+* Some macros are predefined on each kind of machine
+  (see :ref:`system-specific-predefined-macros`).  This allows you to provide
+  code specially tuned for a particular machine.
+
+* System header files define more macros, associated with the features
+  they implement.  You can test these macros with conditionals to avoid
+  using a system feature on a machine where it is not implemented.
+
+* Macros can be defined or undefined with the :option:`-D` and :option:`-U`
+  command-line options when you compile the program.  You can arrange to
+  compile the same source file into two different programs by choosing a
+  macro name to specify which program you want, writing conditionals to
+  test whether or how this macro is defined, and then controlling the
+  state of the macro with command-line options, perhaps set in the
+  Makefile.  See :ref:`invocation`.
+
+* Your program might have a special header file (often called
+  :samp:`config.h`) that is adjusted when the program is compiled.  It can
+  define or not define macros depending on the features of the system and
+  the desired capabilities of the program.  The adjustment can be
+  automated by a tool such as :command:`autoconf`, or done by hand.
+
+.. _if:
+
+If
+^^
+
+The :samp:`#if` directive allows you to test the value of an arithmetic
+expression, rather than the mere existence of one macro.  Its syntax is
+
+.. code-block:: c++
+
+  #if expression
+
+  controlled text
+
+  #endif /* expression */
+
+:samp:`{expression}` is a C expression of integer type, subject to stringent
+restrictions.  It may contain
+
+* Integer constants.
+
+* Character constants, which are interpreted as they would be in normal
+  code.
+
+* Arithmetic operators for addition, subtraction, multiplication,
+  division, bitwise operations, shifts, comparisons, and logical
+  operations (``&&`` and ``||``).  The latter two obey the usual
+  short-circuiting rules of standard C.
+
+* Macros.  All macros in the expression are expanded before actual
+  computation of the expression's value begins.
+
+* Uses of the ``defined`` operator, which lets you check whether macros
+  are defined in the middle of an :samp:`#if`.
+
+* Identifiers that are not macros, which are all considered to be the
+  number zero.  This allows you to write ``#if MACRO`` instead of
+  ``#ifdef MACRO``, if you know that MACRO, when defined, will
+  always have a nonzero value.  Function-like macros used without their
+  function call parentheses are also treated as zero.
+
+  In some contexts this shortcut is undesirable.  The :option:`-Wundef`
+  option causes GCC to warn whenever it encounters an identifier which is
+  not a macro in an :samp:`#if`.
+
+The preprocessor does not know anything about types in the language.
+Therefore, ``sizeof`` operators are not recognized in :samp:`#if`, and
+neither are ``enum`` constants.  They will be taken as identifiers
+which are not macros, and replaced by zero.  In the case of
+``sizeof``, this is likely to cause the expression to be invalid.
+
+The preprocessor calculates the value of :samp:`{expression}`.  It carries
+out all calculations in the widest integer type known to the compiler;
+on most machines supported by GCC this is 64 bits.  This is not the same
+rule as the compiler uses to calculate the value of a constant
+expression, and may give different results in some cases.  If the value
+comes out to be nonzero, the :samp:`#if` succeeds and the :samp:`{controlled
+text}` is included; otherwise it is skipped.
+
+.. index:: defined
+
+.. _defined:
+
+Defined
+^^^^^^^
+
+The special operator ``defined`` is used in :samp:`#if` and
+:samp:`#elif` expressions to test whether a certain name is defined as a
+macro.  ``defined name`` and ``defined (name)`` are
+both expressions whose value is 1 if :samp:`{name}` is defined as a macro at
+the current point in the program, and 0 otherwise.  Thus,  ``#if
+defined MACRO`` is precisely equivalent to ``#ifdef MACRO``.
+
+``defined`` is useful when you wish to test more than one macro for
+existence at once.  For example,
+
+.. code-block:: c++
+
+  #if defined (__vax__) || defined (__ns16000__)
+
+would succeed if either of the names ``__vax__`` or
+``__ns16000__`` is defined as a macro.
+
+Conditionals written like this:
+
+.. code-block:: c++
+
+  #if defined BUFSIZE && BUFSIZE >= 1024
+
+can generally be simplified to just ``#if BUFSIZE >= 1024``,
+since if ``BUFSIZE`` is not defined, it will be interpreted as having
+the value zero.
+
+If the ``defined`` operator appears as a result of a macro expansion,
+the C standard says the behavior is undefined.  GNU cpp treats it as a
+genuine ``defined`` operator and evaluates it normally.  It will warn
+wherever your code uses this feature if you use the command-line option
+:option:`-Wpedantic`, since other compilers may handle it differently.  The
+warning is also enabled by :option:`-Wextra`, and can also be enabled
+individually with :option:`-Wexpansion-to-defined`.
+
+.. index:: #else
+
+.. _else:
+
+Else
+^^^^
+
+The :samp:`#else` directive can be added to a conditional to provide
+alternative text to be used if the condition fails.  This is what it
+looks like:
+
+.. code-block:: c++
+
+  #if expression
+  text-if-true
+  #else /* Not expression */
+  text-if-false
+  #endif /* Not expression */
+
+If :samp:`{expression}` is nonzero, the :samp:`{text-if-true}` is included and
+the :samp:`{text-if-false}` is skipped.  If :samp:`{expression}` is zero, the
+opposite happens.
+
+You can use :samp:`#else` with :samp:`#ifdef` and :samp:`#ifndef`, too.
+
+.. index:: #elif
+
+.. _elif:
+
+Elif
+^^^^
+
+One common case of nested conditionals is used to check for more than two
+possible alternatives.  For example, you might have
+
+.. code-block:: c++
+
+  #if X == 1
+  ...
+  #else /* X != 1 */
+  #if X == 2
+  ...
+  #else /* X != 2 */
+  ...
+  #endif /* X != 2 */
+  #endif /* X != 1 */
+
+Another conditional directive, :samp:`#elif`, allows this to be
+abbreviated as follows:
+
+.. code-block:: c++
+
+  #if X == 1
+  ...
+  #elif X == 2
+  ...
+  #else /* X != 2 and X != 1*/
+  ...
+  #endif /* X != 2 and X != 1*/
+
+:samp:`#elif` stands for 'else if'.  Like :samp:`#else`, it goes in the
+middle of a conditional group and subdivides it; it does not require a
+matching :samp:`#endif` of its own.  Like :samp:`#if`, the :samp:`#elif`
+directive includes an expression to be tested.  The text following the
+:samp:`#elif` is processed only if the original :samp:`#if`-condition
+failed and the :samp:`#elif` condition succeeds.
+
+More than one :samp:`#elif` can go in the same conditional group.  Then
+the text after each :samp:`#elif` is processed only if the :samp:`#elif`
+condition succeeds after the original :samp:`#if` and all previous
+:samp:`#elif` directives within it have failed.
+
+:samp:`#else` is allowed after any number of :samp:`#elif` directives, but
+:samp:`#elif` may not follow :samp:`#else`.
+
+.. index:: __has_attribute
+
+__has_attribute
+^^^^^^^^^^^^^^^
+
+The special operator ``__has_attribute (operand)`` may be used
+in :samp:`#if` and :samp:`#elif` expressions to test whether the attribute
+referenced by its :samp:`{operand}` is recognized by GCC.  Using the operator
+in other contexts is not valid.  In C code, if compiling for strict
+conformance to standards before C2x, :samp:`{operand}` must be
+a valid identifier.  Otherwise, :samp:`{operand}` may be optionally
+introduced by the ``attribute-scope::`` prefix.
+The :samp:`{attribute-scope}` prefix identifies the 'namespace' within
+which the attribute is recognized.  The scope of GCC attributes is
+:samp:`gnu` or :samp:`__gnu__`.  The ``__has_attribute`` operator by
+itself, without any :samp:`{operand}` or parentheses, acts as a predefined
+macro so that support for it can be tested in portable code.  Thus,
+the recommended use of the operator is as follows:
+
+.. code-block:: c++
+
+  #if defined __has_attribute
+  #  if __has_attribute (nonnull)
+  #    define ATTR_NONNULL __attribute__ ((nonnull))
+  #  endif
+  #endif
+
+The first :samp:`#if` test succeeds only when the operator is supported
+by the version of GCC (or another compiler) being used.  Only when that
+test succeeds is it valid to use ``__has_attribute`` as a preprocessor
+operator.  As a result, combining the two tests into a single expression as
+shown below would only be valid with a compiler that supports the operator
+but not with others that don't.
+
+.. code-block:: c++
+
+  #if defined __has_attribute && __has_attribute (nonnull)   /* not portable */
+  ...
+  #endif
+
+.. index:: __has_cpp_attribute
+
+__has_cpp_attribute
+^^^^^^^^^^^^^^^^^^^
+
+The special operator ``__has_cpp_attribute (operand)`` may be used
+in :samp:`#if` and :samp:`#elif` expressions in C++ code to test whether
+the attribute referenced by its :samp:`{operand}` is recognized by GCC.
+``__has_cpp_attribute (operand)`` is equivalent to
+``__has_attribute (operand)`` except that when :samp:`{operand}`
+designates a supported standard attribute it evaluates to an integer
+constant of the form ``YYYYMM`` indicating the year and month when
+the attribute was first introduced into the C++ standard.  For additional
+information including the dates of the introduction of current standard
+attributes, see `SD-6: SG10 Feature Test Recommendations <https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/>`_.
+
+.. index:: __has_c_attribute
+
+__has_c_attribute
+^^^^^^^^^^^^^^^^^
+
+The special operator ``__has_c_attribute (operand)`` may be
+used in :samp:`#if` and :samp:`#elif` expressions in C code to test
+whether the attribute referenced by its :samp:`{operand}` is recognized by
+GCC in attributes using the :samp:`[[]]` syntax.  GNU attributes must
+be specified with the scope :samp:`gnu` or :samp:`__gnu__` with
+``__has_c_attribute``.  When :samp:`{operand}` designates a supported
+standard attribute it evaluates to an integer constant of the form
+``YYYYMM`` indicating the year and month when the attribute was
+first introduced into the C standard, or when the syntax of operands
+to the attribute was extended in the C standard.
+
+.. index:: __has_builtin
+
+__has_builtin
+^^^^^^^^^^^^^
+
+The special operator ``__has_builtin (operand)`` may be used in
+constant integer contexts and in preprocessor :samp:`#if` and :samp:`#elif`
+expressions to test whether the symbol named by its :samp:`{operand}` is
+recognized as a built-in function by GCC in the current language and
+conformance mode.  It evaluates to a constant integer with a nonzero
+value if the argument refers to such a function, and to zero otherwise.
+The operator may also be used in preprocessor :samp:`#if` and :samp:`#elif`
+expressions.  The ``__has_builtin`` operator by itself, without any
+:samp:`{operand}` or parentheses, acts as a predefined macro so that support
+for it can be tested in portable code.  Thus, the recommended use of
+the operator is as follows:
+
+.. code-block:: c++
+
+  #if defined __has_builtin
+  #  if __has_builtin (__builtin_object_size)
+  #    define builtin_object_size(ptr) __builtin_object_size (ptr, 2)
+  #  endif
+  #endif
+  #ifndef builtin_object_size
+  #  define builtin_object_size(ptr)   ((size_t)-1)
+  #endif
+
+.. index:: __has_include
+
+__has_include
+^^^^^^^^^^^^^
+
+The special operator ``__has_include (operand)`` may be used in
+:samp:`#if` and :samp:`#elif` expressions to test whether the header referenced
+by its :samp:`{operand}` can be included using the :samp:`#include` directive.  Using
+the operator in other contexts is not valid.  The :samp:`{operand}` takes
+the same form as the file in the :samp:`#include` directive (see :ref:`include-syntax`) and evaluates to a nonzero value if the header can be included and
+to zero otherwise.  Note that that the ability to include a header doesn't
+imply that the header doesn't contain invalid constructs or :samp:`#error`
+directives that would cause the preprocessor to fail.
+
+The ``__has_include`` operator by itself, without any :samp:`{operand}` or
+parentheses, acts as a predefined macro so that support for it can be tested
+in portable code.  Thus, the recommended use of the operator is as follows:
+
+.. code-block:: c++
+
+  #if defined __has_include
+  #  if __has_include (<stdatomic.h>)
+  #    include <stdatomic.h>
+  #  endif
+  #endif
+
+The first :samp:`#if` test succeeds only when the operator is supported
+by the version of GCC (or another compiler) being used.  Only when that
+test succeeds is it valid to use ``__has_include`` as a preprocessor
+operator.  As a result, combining the two tests into a single expression
+as shown below would only be valid with a compiler that supports the operator
+but not with others that don't.
+
+.. code-block:: c++
+
+  #if defined __has_include && __has_include ("header.h")   /* not portable */
+  ...
+  #endif

gcc/doc/cpp/conditional-uses.rst

@@ -0,0 +1,32 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _conditional-uses:
+
+Conditional Uses
+****************
+
+There are three general reasons to use a conditional.
+
+* A program may need to use different code depending on the machine or
+  operating system it is to run on.  In some cases the code for one
+  operating system may be erroneous on another operating system; for
+  example, it might refer to data types or constants that do not exist on
+  the other system.  When this happens, it is not enough to avoid
+  executing the invalid code.  Its mere presence will cause the compiler
+  to reject the program.  With a preprocessing conditional, the offending
+  code can be effectively excised from the program when it is not valid.
+
+* You may want to be able to compile the same source file into two
+  different programs.  One version might make frequent time-consuming
+  consistency checks on its intermediate data, or print the values of
+  those data for debugging, and the other not.
+
+* A conditional whose condition is always false is one way to exclude code
+  from the program but keep it as a sort of comment for future reference.
+
+Simple programs that do not need system-specific logic or complex
+debugging hooks generally will not need to use preprocessing
+conditionals.

gcc/doc/cpp/conditionals.rst

@@ -0,0 +1,44 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: conditionals
+
+.. _conditionals:
+
+Conditionals
+------------
+
+A :dfn:`conditional` is a directive that instructs the preprocessor to
+select whether or not to include a chunk of code in the final token
+stream passed to the compiler.  Preprocessor conditionals can test
+arithmetic expressions, or whether a name is defined as a macro, or both
+simultaneously using the special ``defined`` operator.
+
+A conditional in the C preprocessor resembles in some ways an ``if``
+statement in C, but it is important to understand the difference between
+them.  The condition in an ``if`` statement is tested during the
+execution of your program.  Its purpose is to allow your program to
+behave differently from run to run, depending on the data it is
+operating on.  The condition in a preprocessing conditional directive is
+tested when your program is compiled.  Its purpose is to allow different
+code to be included in the program depending on the situation at the
+time of compilation.
+
+However, the distinction is becoming less clear.  Modern compilers often
+do test ``if`` statements when a program is compiled, if their
+conditions are known not to vary at run time, and eliminate code which
+can never be executed.  If you can count on your compiler to do this,
+you may find that your program is more readable if you use ``if``
+statements with constant conditions (perhaps determined by macros).  Of
+course, you can only use this to exclude code, not type definitions or
+other preprocessing directives, and you can only do it if the code
+remains syntactically valid when it is not to be used.
+
+.. toctree::
+  :maxdepth: 2
+
+  conditional-uses
+  conditional-syntax
+  deleted-code

gcc/doc/cpp/conf.py

@@ -0,0 +1,30 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sys
+sys.path.append('../../..//doc')
+
+from baseconf import *
+
+name = 'cpp'
+project = 'The C Preprocessor'
+copyright = '1987-2022 Free Software Foundation, Inc.'
+authors = 'Richard M. Stallman, Zachary Weinberg'
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+latex_documents = [
+  ('index', f'{name}.tex', project, authors, 'manual'),
+]
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('invocation', name, project, [authors], 1),
+]
+
+texinfo_documents = [
+  ('index', name, project, authors, None, None, None, True)
+]
+
+set_common(name, globals())

gcc/doc/cpp/copyright.rst

@@ -0,0 +1,24 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the GPL license file
+
+Copyright
+^^^^^^^^^
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, the Front-Cover Texts being (a) (see below), and
+with the Back-Cover Texts being (b) (see below).
+A copy of the license is included in the :ref:`gnu_fdl`.
+
+(a) The FSF's Front-Cover Text is:
+
+     A GNU Manual
+
+(b) The FSF's Back-Cover Text is:
+
+     You have freedom to copy and modify this GNU Manual, like GNU
+     software.  Copies published by the Free Software Foundation raise
+     funds for GNU development.

gcc/doc/cpp/deleted-code.rst

@@ -0,0 +1,34 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: commenting out code
+
+.. _deleted-code:
+
+Deleted Code
+************
+
+If you replace or delete a part of the program but want to keep the old
+code around for future reference, you often cannot simply comment it
+out.  Block comments do not nest, so the first comment inside the old
+code will end the commenting-out.  The probable result is a flood of
+syntax errors.
+
+One way to avoid this problem is to use an always-false conditional
+instead.  For instance, put ``#if 0`` before the deleted code and
+``#endif`` after it.  This works even if the code being turned
+off contains conditionals, but they must be entire conditionals
+(balanced :samp:`#if` and :samp:`#endif`).
+
+Some people use ``#ifdef notdef`` instead.  This is risky, because
+``notdef`` might be accidentally defined as a macro, and then the
+conditional would succeed.  ``#if 0`` can be counted on to fail.
+
+Do not use ``#if 0`` for comments which are not C code.  Use a real
+comment, instead.  The interior of ``#if 0`` must consist of complete
+tokens; in particular, single-quote characters must balance.  Comments
+often contain unbalanced single-quote characters (known in English as
+apostrophes).  These confuse ``#if 0``.  They don't confuse
+:samp:`/*`.

gcc/doc/cpp/diagnostics.rst

@@ -0,0 +1,51 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: diagnostic, reporting errors, reporting warnings, #error
+
+.. _diagnostics:
+
+Diagnostics
+-----------
+
+The directive :samp:`#error` causes the preprocessor to report a fatal
+error.  The tokens forming the rest of the line following :samp:`#error`
+are used as the error message.
+
+You would use :samp:`#error` inside of a conditional that detects a
+combination of parameters which you know the program does not properly
+support.  For example, if you know that the program will not run
+properly on a VAX, you might write
+
+.. code-block:: c++
+
+  #ifdef __vax__
+  #error "Won't work on VAXen.  See comments at get_last_object."
+  #endif
+
+If you have several configuration parameters that must be set up by
+the installation in a consistent way, you can use conditionals to detect
+an inconsistency and report it with :samp:`#error`.  For example,
+
+.. code-block:: c++
+
+  #if !defined(FOO) && defined(BAR)
+  #error "BAR requires FOO."
+  #endif
+
+.. index:: #warning
+
+The directive :samp:`#warning` is like :samp:`#error`, but causes the
+preprocessor to issue a warning and continue preprocessing.  The tokens
+following :samp:`#warning` are used as the warning message.
+
+You might use :samp:`#warning` in obsolete header files, with a message
+directing the user to the header file which should be used instead.
+
+Neither :samp:`#error` nor :samp:`#warning` macro-expands its argument.
+Internal whitespace sequences are each replaced with a single space.
+The line must consist of complete tokens.  It is wisest to make the
+argument of these directives be a single string constant; this avoids
+problems with apostrophes and the like.

gcc/doc/cpp/environment-variables.rst

@@ -0,0 +1,23 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: environment variables
+
+.. _environment-variables:
+
+Environment Variables
+---------------------
+
+This section describes the environment variables that affect how CPP
+operates.  You can use them to specify directories or prefixes to use
+when searching for include files, or to control dependency output.
+
+Note that you can also specify places to search using options such as
+:option:`-I`, and control dependency output with options like
+:option:`-M` (see :ref:`invocation`).  These take precedence over
+environment variables, which in turn take precedence over the
+configuration of GCC.
+
+.. include:: ../../../doc/cppenv.rst

gcc/doc/cpp/gnu-free-documentation-license.rst

@@ -0,0 +1,6 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. include:: ../../../doc/gnu_free_documentation_license.rst

gcc/doc/cpp/header-files.rst

@@ -0,0 +1,56 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: header file
+
+.. _header-files:
+
+Header Files
+------------
+
+A header file is a file containing C declarations and macro definitions
+(see :ref:`macros`) to be shared between several source files.  You request
+the use of a header file in your program by :dfn:`including` it, with the
+C preprocessing directive :samp:`#include`.
+
+Header files serve two purposes.
+
+.. index:: system header files
+
+* System header files declare the interfaces to parts of the operating
+  system.  You include them in your program to supply the definitions and
+  declarations you need to invoke system calls and libraries.
+
+* Your own header files contain declarations for interfaces between the
+  source files of your program.  Each time you have a group of related
+  declarations and macro definitions all or most of which are needed in
+  several different source files, it is a good idea to create a header
+  file for them.
+
+Including a header file produces the same results as copying the header
+file into each source file that needs it.  Such copying would be
+time-consuming and error-prone.  With a header file, the related
+declarations appear in only one place.  If they need to be changed, they
+can be changed in one place, and programs that include the header file
+will automatically use the new version when next recompiled.  The header
+file eliminates the labor of finding and changing all the copies as well
+as the risk that a failure to find one copy will result in
+inconsistencies within a program.
+
+In C, the usual convention is to give header files names that end with
+:samp:`.h`.  It is most portable to use only letters, digits, dashes, and
+underscores in header file names, and at most one dot.
+
+.. toctree::
+  :maxdepth: 2
+
+  header-files/include-syntax
+  header-files/include-operation
+  header-files/search-path
+  header-files/once-only-headers
+  header-files/alternatives-to-wrapper-ifndef
+  header-files/computed-includes
+  header-files/wrapper-headers
+  header-files/system-headers

gcc/doc/cpp/header-files/alternatives-to-wrapper-ifndef.rst

@@ -0,0 +1,40 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _alternatives-to-wrapper-ifndef:
+
+Alternatives to Wrapper #ifndef
+*******************************
+
+CPP supports two more ways of indicating that a header file should be
+read only once.  Neither one is as portable as a wrapper :samp:`#ifndef`
+and we recommend you do not use them in new programs, with the caveat
+that :samp:`#import` is standard practice in Objective-C.
+
+.. index:: #import
+
+CPP supports a variant of :samp:`#include` called :samp:`#import` which
+includes a file, but does so at most once.  If you use :samp:`#import`
+instead of :samp:`#include`, then you don't need the conditionals
+inside the header file to prevent multiple inclusion of the contents.
+:samp:`#import` is standard in Objective-C, but is considered a
+deprecated extension in C and C++.
+
+:samp:`#import` is not a well designed feature.  It requires the users of
+a header file to know that it should only be included once.  It is much
+better for the header file's implementor to write the file so that users
+don't need to know this.  Using a wrapper :samp:`#ifndef` accomplishes
+this goal.
+
+In the present implementation, a single use of :samp:`#import` will
+prevent the file from ever being read again, by either :samp:`#import` or
+:samp:`#include`.  You should not rely on this; do not use both
+:samp:`#import` and :samp:`#include` to refer to the same header file.
+
+Another way to prevent a header file from being included more than once
+is with the :samp:`#pragma once` directive (see :ref:`pragmas`).
+:samp:`#pragma once` does not have the problems that :samp:`#import` does,
+but it is not recognized by all preprocessors, so you cannot rely on it
+in a portable program.

gcc/doc/cpp/header-files/computed-includes.rst

@@ -0,0 +1,86 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: computed includes, macros in include
+
+.. _computed-includes:
+
+Computed Includes
+*****************
+
+Sometimes it is necessary to select one of several different header
+files to be included into your program.  They might specify
+configuration parameters to be used on different sorts of operating
+systems, for instance.  You could do this with a series of conditionals,
+
+.. code-block:: c++
+
+  #if SYSTEM_1
+  # include "system_1.h"
+  #elif SYSTEM_2
+  # include "system_2.h"
+  #elif SYSTEM_3
+  ...
+  #endif
+
+That rapidly becomes tedious.  Instead, the preprocessor offers the
+ability to use a macro for the header name.  This is called a
+:dfn:`computed include`.  Instead of writing a header name as the direct
+argument of :samp:`#include`, you simply put a macro name there instead:
+
+.. code-block:: c++
+
+  #define SYSTEM_H "system_1.h"
+  ...
+  #include SYSTEM_H
+
+``SYSTEM_H`` will be expanded, and the preprocessor will look for
+:samp:`system_1.h` as if the :samp:`#include` had been written that way
+originally.  ``SYSTEM_H`` could be defined by your Makefile with a
+:option:`-D` option.
+
+You must be careful when you define the macro.  :samp:`#define` saves
+tokens, not text.  The preprocessor has no way of knowing that the macro
+will be used as the argument of :samp:`#include`, so it generates
+ordinary tokens, not a header name.  This is unlikely to cause problems
+if you use double-quote includes, which are close enough to string
+constants.  If you use angle brackets, however, you may have trouble.
+
+The syntax of a computed include is actually a bit more general than the
+above.  If the first non-whitespace character after :samp:`#include` is
+not :samp:`"` or :samp:`<`, then the entire line is macro-expanded
+like running text would be.
+
+If the line expands to a single string constant, the contents of that
+string constant are the file to be included.  CPP does not re-examine the
+string for embedded quotes, but neither does it process backslash
+escapes in the string.  Therefore
+
+.. code-block:: c++
+
+  #define HEADER "a\"b"
+  #include HEADER
+
+looks for a file named :samp:`a\\"b`.  CPP searches for the file according
+to the rules for double-quoted includes.
+
+If the line expands to a token stream beginning with a :samp:`<` token
+and including a :samp:`>` token, then the tokens between the :samp:`<` and
+the first :samp:`>` are combined to form the filename to be included.
+Any whitespace between tokens is reduced to a single space; then any
+space after the initial :samp:`<` is retained, but a trailing space
+before the closing :samp:`>` is ignored.  CPP searches for the file
+according to the rules for angle-bracket includes.
+
+In either case, if there are any tokens on the line after the file name,
+an error occurs and the directive is not processed.  It is also an error
+if the result of expansion does not match either of the two expected
+forms.
+
+These rules are implementation-defined behavior according to the C
+standard.  To minimize the risk of different compilers interpreting your
+computed includes differently, we recommend you use only a single
+object-like macro which expands to a string constant.  This will also
+minimize confusion for people reading your program.

gcc/doc/cpp/header-files/include-operation.rst

@@ -0,0 +1,67 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _include-operation:
+
+Include Operation
+*****************
+
+The :samp:`#include` directive works by directing the C preprocessor to
+scan the specified file as input before continuing with the rest of the
+current file.  The output from the preprocessor contains the output
+already generated, followed by the output resulting from the included
+file, followed by the output that comes from the text after the
+:samp:`#include` directive.  For example, if you have a header file
+:samp:`header.h` as follows,
+
+.. code-block:: c++
+
+  char *test (void);
+
+and a main program called :samp:`program.c` that uses the header file,
+like this,
+
+.. code-block:: c++
+
+  int x;
+  #include "header.h"
+
+  int
+  main (void)
+  {
+    puts (test ());
+  }
+
+the compiler will see the same token stream as it would if
+:samp:`program.c` read
+
+.. code-block:: c++
+
+  int x;
+  char *test (void);
+
+  int
+  main (void)
+  {
+    puts (test ());
+  }
+
+Included files are not limited to declarations and macro definitions;
+those are merely the typical uses.  Any fragment of a C program can be
+included from another file.  The include file could even contain the
+beginning of a statement that is concluded in the containing file, or
+the end of a statement that was started in the including file.  However,
+an included file must consist of complete tokens.  Comments and string
+literals which have not been closed by the end of an included file are
+invalid.  For error recovery, they are considered to end at the end of
+the file.
+
+To avoid confusion, it is best if header files contain only complete
+syntactic units---function declarations or definitions, type
+declarations, etc.
+
+The line following the :samp:`#include` directive is always treated as a
+separate line by the C preprocessor, even if the included file lacks a
+final newline.

gcc/doc/cpp/header-files/include-syntax.rst

@@ -0,0 +1,42 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: #include
+
+.. _include-syntax:
+
+Include Syntax
+**************
+
+Both user and system header files are included using the preprocessing
+directive :samp:`#include`.  It has two variants:
+
+:samp:`#include <{file}>`
+  This variant is used for system header files.  It searches for a file
+  named :samp:`{file}` in a standard list of system directories.  You can prepend
+  directories to this list with the :option:`-I` option (see :ref:`invocation`).
+
+:samp:`#include "{file}"`
+  This variant is used for header files of your own program.  It
+  searches for a file named :samp:`{file}` first in the directory containing
+  the current file, then in the quote directories and then the same
+  directories used for ``<file>``.  You can prepend directories
+  to the list of quote directories with the :option:`-iquote` option.
+
+The argument of :samp:`#include`, whether delimited with quote marks or
+angle brackets, behaves like a string constant in that comments are not
+recognized, and macro names are not expanded.  Thus, ``#include
+<x/*y>`` specifies inclusion of a system header file named :samp:`x/*y`.
+
+However, if backslashes occur within :samp:`{file}`, they are considered
+ordinary text characters, not escape characters.  None of the character
+escape sequences appropriate to string constants in C are processed.
+Thus, ``#include "x\n\\y"`` specifies a filename containing three
+backslashes.  (Some systems interpret :samp:`\\` as a pathname separator.
+All of these also interpret :samp:`/` the same way.  It is most portable
+to use only :samp:`/`.)
+
+It is an error if there is anything (other than comments) on the line
+after the file name.

gcc/doc/cpp/header-files/once-only-headers.rst

@@ -0,0 +1,52 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: repeated inclusion, including just once, wrapper #ifndef
+
+.. _once-only-headers:
+
+Once-Only Headers
+*****************
+
+If a header file happens to be included twice, the compiler will process
+its contents twice.  This is very likely to cause an error, e.g. when the
+compiler sees the same structure definition twice.  Even if it does not,
+it will certainly waste time.
+
+The standard way to prevent this is to enclose the entire real contents
+of the file in a conditional, like this:
+
+.. code-block:: c++
+
+  /* File foo.  */
+  #ifndef FILE_FOO_SEEN
+  #define FILE_FOO_SEEN
+
+  the entire file
+
+  #endif /* !FILE_FOO_SEEN */
+
+This construct is commonly known as a :dfn:`wrapper #ifndef`.
+When the header is included again, the conditional will be false,
+because ``FILE_FOO_SEEN`` is defined.  The preprocessor will skip
+over the entire contents of the file, and the compiler will not see it
+twice.
+
+CPP optimizes even further.  It remembers when a header file has a
+wrapper :samp:`#ifndef`.  If a subsequent :samp:`#include` specifies that
+header, and the macro in the :samp:`#ifndef` is still defined, it does
+not bother to rescan the file at all.
+
+You can put comments outside the wrapper.  They will not interfere with
+this optimization.
+
+.. index:: controlling macro, guard macro
+
+The macro ``FILE_FOO_SEEN`` is called the :dfn:`controlling macro` or
+:dfn:`guard macro`.  In a user header file, the macro name should not
+begin with :samp:`_`.  In a system header file, it should begin with
+:samp:`__` to avoid conflicts with user programs.  In any kind of header
+file, the macro name should contain the name of the file and some
+additional text, to avoid conflicts with other header files.

gcc/doc/cpp/header-files/search-path.rst

@@ -0,0 +1,53 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _search-path:
+
+Search Path
+***********
+
+By default, the preprocessor looks for header files included by the quote
+form of the directive ``#include "file"`` first relative to
+the directory of the current file, and then in a preconfigured list
+of standard system directories.
+For example, if :samp:`/usr/include/sys/stat.h` contains
+``#include "types.h"``, GCC looks for :samp:`types.h` first in
+:samp:`/usr/include/sys`, then in its usual search path.
+
+For the angle-bracket form ``#include <file>``, the
+preprocessor's default behavior is to look only in the standard system
+directories.  The exact search directory list depends on the target
+system, how GCC is configured, and where it is installed.  You can
+find the default search directory list for your version of CPP by
+invoking it with the :option:`-v` option.  For example,
+
+.. code-block:: c++
+
+  cpp -v /dev/null -o /dev/null
+
+There are a number of command-line options you can use to add
+additional directories to the search path.
+The most commonly-used option is :option:`-Idir`, which causes
+:samp:`{dir}` to be searched after the current directory (for the quote
+form of the directive) and ahead of the standard system directories.
+You can specify multiple :option:`-I` options on the command line,
+in which case the directories are searched in left-to-right order.
+
+If you need separate control over the search paths for the quote and
+angle-bracket forms of the :samp:`#include` directive, you can use the
+:option:`-iquote` and/or :option:`-isystem` options instead of :option:`-I`.
+See :ref:`invocation`, for a detailed description of these options, as
+well as others that are less generally useful.
+
+If you specify other options on the command line, such as :option:`-I`,
+that affect where the preprocessor searches for header files, the
+directory list printed by the :option:`-v` option reflects the actual
+search path used by the preprocessor.
+
+Note that you can also prevent the preprocessor from searching any of
+the default system header directories with the :option:`-nostdinc`
+option.  This is useful when you are compiling an operating system
+kernel or some other program that does not use the standard C library
+facilities, or the standard C library itself.

gcc/doc/cpp/header-files/system-headers.rst

@@ -0,0 +1,41 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: system header files
+
+.. _system-headers:
+
+System Headers
+**************
+
+The header files declaring interfaces to the operating system and
+runtime libraries often cannot be written in strictly conforming C.
+Therefore, GCC gives code found in :dfn:`system headers` special
+treatment.  All warnings, other than those generated by :samp:`#warning`
+(see :ref:`diagnostics`), are suppressed while GCC is processing a system
+header.  Macros defined in a system header are immune to a few warnings
+wherever they are expanded.  This immunity is granted on an ad-hoc
+basis, when we find that a warning generates lots of false positives
+because of code in macros defined in system headers.
+
+Normally, only the headers found in specific directories are considered
+system headers.  These directories are determined when GCC is compiled.
+There are, however, two ways to make normal headers into system headers:
+
+* Header files found in directories added to the search path with the
+  :option:`-isystem` and :option:`-idirafter` command-line options are
+  treated as system headers for the purposes of diagnostics.
+
+*
+  .. index:: #pragma GCC system_header
+
+  There is also a directive, ``#pragma GCC system_header``, which
+  tells GCC to consider the rest of the current include file a system
+  header, no matter where it was found.  Code that comes before the
+  :samp:`#pragma` in the file is not affected.  ``#pragma GCC
+  system_header`` has no effect in the primary source file.
+
+On some targets, such as RS/6000 AIX, GCC implicitly surrounds all
+system headers with an :samp:`extern "C"` block when compiling as C++.

gcc/doc/cpp/header-files/wrapper-headers.rst

@@ -0,0 +1,58 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: wrapper headers, overriding a header file, #include_next
+
+.. _wrapper-headers:
+
+Wrapper Headers
+***************
+
+Sometimes it is necessary to adjust the contents of a system-provided
+header file without editing it directly.  GCC's :command:`fixincludes`
+operation does this, for example.  One way to do that would be to create
+a new header file with the same name and insert it in the search path
+before the original header.  That works fine as long as you're willing
+to replace the old header entirely.  But what if you want to refer to
+the old header from the new one?
+
+You cannot simply include the old header with :samp:`#include`.  That
+will start from the beginning, and find your new header again.  If your
+header is not protected from multiple inclusion (see :ref:`once-only-headers`), it will recurse infinitely and cause a fatal error.
+
+You could include the old header with an absolute pathname:
+
+.. code-block:: c++
+
+  #include "/usr/include/old-header.h"
+
+This works, but is not clean; should the system headers ever move, you
+would have to edit the new headers to match.
+
+There is no way to solve this problem within the C standard, but you can
+use the GNU extension :samp:`#include_next`.  It means, 'Include the
+*next* file with this name'.  This directive works like
+:samp:`#include` except in searching for the specified file: it starts
+searching the list of header file directories *after* the directory
+in which the current file was found.
+
+Suppose you specify :option:`-I /usr/local/include`, and the list of
+directories to search also includes :samp:`/usr/include`; and suppose
+both directories contain :samp:`signal.h`.  Ordinary ``#include
+<signal.h>`` finds the file under :samp:`/usr/local/include`.  If that
+file contains ``#include_next <signal.h>``, it starts searching
+after that directory, and finds the file in :samp:`/usr/include`.
+
+:samp:`#include_next` does not distinguish between ``<file>``
+and ``"file"`` inclusion, nor does it check that the file you
+specify has the same name as the current file.  It simply looks for the
+file named, starting with the directory in the search path after the one
+where the current file was found.
+
+The use of :samp:`#include_next` can lead to great confusion.  We
+recommend it be used only when there is no other alternative.  In
+particular, it should not be used in the headers belonging to a specific
+program; it should be used only to make global corrections along the
+lines of :command:`fixincludes`.

gcc/doc/cpp/implementation-defined-behavior.rst

@@ -0,0 +1,97 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _implementation-defined-behavior:
+
+.. _identifier-characters:
+
+Implementation-defined behavior
+*******************************
+
+This is how CPP behaves in all the cases which the C standard
+describes as :dfn:`implementation-defined`.  This term means that the
+implementation is free to do what it likes, but must document its choice
+and stick to it.
+
+.. todo:: Check the C++ standard for more implementation-defined stuff.
+
+* The mapping of physical source file multi-byte characters to the
+  execution character set.
+
+  The input character set can be specified using the
+  :option:`-finput-charset` option, while the execution character set may
+  be controlled using the :option:`-fexec-charset` and
+  :option:`-fwide-exec-charset` options.
+
+* Identifier characters.
+
+  The C and C++ standards allow identifiers to be composed of :samp:`_`
+  and the alphanumeric characters.  C++ also allows universal character
+  names.  C99 and later C standards permit both universal character
+  names and implementation-defined characters.  In both C and C++ modes,
+  GCC accepts in identifiers exactly those extended characters that
+  correspond to universal character names permitted by the chosen
+  standard.
+
+  GCC allows the :samp:`$` character in identifiers as an extension for
+  most targets.  This is true regardless of the std= switch,
+  since this extension cannot conflict with standards-conforming
+  programs.  When preprocessing assembler, however, dollars are not
+  identifier characters by default.
+
+  Currently the targets that by default do not permit :samp:`$` are AVR,
+  IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX
+  operating system.
+
+  You can override the default with :option:`-fdollars-in-identifiers` or
+  :option:`-fno-dollars-in-identifiers`.  See :option:`-fdollars-in-identifiers`.
+
+* Non-empty sequences of whitespace characters.
+
+  In textual output, each whitespace sequence is collapsed to a single
+  space.  For aesthetic reasons, the first token on each non-directive
+  line of output is preceded with sufficient spaces that it appears in the
+  same column as it did in the original source file.
+
+* The numeric value of character constants in preprocessor expressions.
+
+  The preprocessor and compiler interpret character constants in the
+  same way; i.e. escape sequences such as :samp:`\\a` are given the
+  values they would have on the target machine.
+
+  The compiler evaluates a multi-character character constant a character
+  at a time, shifting the previous value left by the number of bits per
+  target character, and then or-ing in the bit-pattern of the new
+  character truncated to the width of a target character.  The final
+  bit-pattern is given type ``int``, and is therefore signed,
+  regardless of whether single characters are signed or not.
+  If there are more
+  characters in the constant than would fit in the target ``int`` the
+  compiler issues a warning, and the excess leading characters are
+  ignored.
+
+  For example, ``'ab'`` for a target with an 8-bit ``char`` would be
+  interpreted as :samp:`(int) ((unsigned char) 'a' * 256 + (unsigned char)
+  'b')`, and ``'\234a'`` as :samp:`(int) ((unsigned char) '\\234' *
+  256 + (unsigned char) 'a')`.
+
+* Source file inclusion.
+
+  For a discussion on how the preprocessor locates header files,
+  :ref:`include-operation`.
+
+* Interpretation of the filename resulting from a macro-expanded
+  :samp:`#include` directive.
+
+  See :ref:`computed-includes`.
+
+* Treatment of a :samp:`#pragma` directive that after macro-expansion
+  results in a standard pragma.
+
+  No macro expansion occurs on any :samp:`#pragma` directive line, so the
+  question does not arise.
+
+  Note that GCC does not yet implement any of the standard
+  pragmas.

gcc/doc/cpp/implementation-details.rst

@@ -0,0 +1,23 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _implementation-details:
+
+Implementation Details
+----------------------
+
+Here we document details of how the preprocessor's implementation
+affects its user-visible behavior.  You should try to avoid undue
+reliance on behavior described here, as it is possible that it will
+change subtly in future implementations.
+
+Also documented here are obsolete features still supported by CPP.
+
+.. toctree::
+  :maxdepth: 2
+
+  implementation-defined-behavior
+  implementation-limits
+  obsolete-features

gcc/doc/cpp/implementation-limits.rst

@@ -0,0 +1,68 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: implementation limits
+
+.. _implementation-limits:
+
+Implementation limits
+*********************
+
+CPP has a small number of internal limits.  This section lists the
+limits which the C standard requires to be no lower than some minimum,
+and all the others known.  It is intended that there should be as few limits
+as possible.  If you encounter an undocumented or inconvenient limit,
+please report that as a bug.  See :ref:`gcc:bugs`.
+
+Where we say something is limited :dfn:`only by available memory`, that
+means that internal data structures impose no intrinsic limit, and space
+is allocated with ``malloc`` or equivalent.  The actual limit will
+therefore depend on many things, such as the size of other things
+allocated by the compiler at the same time, the amount of memory
+consumed by other processes on the same computer, etc.
+
+* Nesting levels of :samp:`#include` files.
+
+  We impose an arbitrary limit of 200 levels, to avoid runaway recursion.
+  The standard requires at least 15 levels.
+
+* Nesting levels of conditional inclusion.
+
+  The C standard mandates this be at least 63.  CPP is limited only by
+  available memory.
+
+* Levels of parenthesized expressions within a full expression.
+
+  The C standard requires this to be at least 63.  In preprocessor
+  conditional expressions, it is limited only by available memory.
+
+* Significant initial characters in an identifier or macro name.
+
+  The preprocessor treats all characters as significant.  The C standard
+  requires only that the first 63 be significant.
+
+* Number of macros simultaneously defined in a single translation unit.
+
+  The standard requires at least 4095 be possible.  CPP is limited only
+  by available memory.
+
+* Number of parameters in a macro definition and arguments in a macro call.
+
+  We allow ``USHRT_MAX``, which is no smaller than 65,535.  The minimum
+  required by the standard is 127.
+
+* Number of characters on a logical source line.
+
+  The C standard requires a minimum of 4096 be permitted.  CPP places
+  no limits on this, but you may get incorrect column numbers reported in
+  diagnostics for lines longer than 65,535 characters.
+
+* Maximum size of a source file.
+
+  The standard does not specify any lower limit on the maximum size of a
+  source file.  GNU cpp maps files into memory, so it is limited by the
+  available address space.  This is generally at least two gigabytes.
+  Depending on the operating system, the size of physical memory may or
+  may not be a limitation.

gcc/doc/cpp/index.rst

@@ -0,0 +1,35 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+The C Preprocessor
+==================
+
+The C preprocessor implements the macro language used to transform C,
+C++, and Objective-C programs before they are compiled.  It can also be
+useful on its own.
+
+.. only:: html
+
+  Contents:
+
+.. toctree::
+
+  copyright
+  overview
+  header-files
+  macros
+  conditionals
+  diagnostics
+  line-control
+  pragmas
+  other-directives
+  preprocessor-output
+  traditional-mode
+  implementation-details
+  invocation
+  environment-variables
+  gnu-free-documentation-license
+
+  indices-and-tables

gcc/doc/cpp/indices-and-tables.rst

@@ -0,0 +1 @@
+.. include:: ../../../doc/indices-and-tables.rst

gcc/doc/cpp/initial-processing.rst

@@ -0,0 +1,164 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _initial-processing:
+
+Initial processing
+******************
+
+The preprocessor performs a series of textual transformations on its
+input.  These happen before all other processing.  Conceptually, they
+happen in a rigid order, and the entire file is run through each
+transformation before the next one begins.  CPP actually does them
+all at once, for performance reasons.  These transformations correspond
+roughly to the first three 'phases of translation' described in the C
+standard.
+
+.. index:: line endings
+
+* The input file is read into memory and broken into lines.
+
+  Different systems use different conventions to indicate the end of a
+  line.  GCC accepts the ASCII control sequences LF, CR
+  LF and CR as end-of-line markers.  These are the canonical
+  sequences used by Unix, DOS and VMS, and the classic Mac OS (before
+  OSX) respectively.  You may therefore safely copy source code written
+  on any of those systems to a different one and use it without
+  conversion.  (GCC may lose track of the current line number if a file
+  doesn't consistently use one convention, as sometimes happens when it
+  is edited on computers with different conventions that share a network
+  file system.)
+
+  If the last line of any input file lacks an end-of-line marker, the end
+  of the file is considered to implicitly supply one.  The C standard says
+  that this condition provokes undefined behavior, so GCC will emit a
+  warning message.
+
+.. index:: trigraphs
+
+.. _trigraphs:
+
+* If trigraphs are enabled, they are replaced by their
+  corresponding single characters.  By default GCC ignores trigraphs,
+  but if you request a strictly conforming mode with the :option:`-std`
+  option, or you specify the :option:`-trigraphs` option, then it
+  converts them.
+
+  These are nine three-character sequences, all starting with :samp:`??`,
+  that are defined by ISO C to stand for single characters.  They permit
+  obsolete systems that lack some of C's punctuation to use C.  For
+  example, :samp:`??/` stands for :samp:`\\`, so ``'??/n'`` is a character
+  constant for a newline.
+
+  Trigraphs are not popular and many compilers implement them
+  incorrectly.  Portable code should not rely on trigraphs being either
+  converted or ignored.  With :option:`-Wtrigraphs` GCC will warn you
+  when a trigraph may change the meaning of your program if it were
+  converted.  See :ref:`wtrigraphs`.
+
+  In a string constant, you can prevent a sequence of question marks
+  from being confused with a trigraph by inserting a backslash between
+  the question marks, or by separating the string literal at the
+  trigraph and making use of string literal concatenation.  ``"(??\?)"``
+  is the string :samp:`(???)`, not :samp:`(?]`.  Traditional C compilers
+  do not recognize these idioms.
+
+  The nine trigraphs and their replacements are
+
+  .. code-block::
+
+    Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
+    Replacement:      [    ]    {    }    #    \    ^    |    ~
+
+.. index:: continued lines, backslash-newline
+
+* Continued lines are merged into one long line.
+
+  A continued line is a line which ends with a backslash, :samp:`\\`.  The
+  backslash is removed and the following line is joined with the current
+  one.  No space is inserted, so you may split a line anywhere, even in
+  the middle of a word.  (It is generally more readable to split lines
+  only at white space.)
+
+  The trailing backslash on a continued line is commonly referred to as a
+  :dfn:`backslash-newline`.
+
+  If there is white space between a backslash and the end of a line, that
+  is still a continued line.  However, as this is usually the result of an
+  editing mistake, and many compilers will not accept it as a continued
+  line, GCC will warn you about it.
+
+.. index:: comments, line comments, block comments
+
+* All comments are replaced with single spaces.
+
+  There are two kinds of comments.  :dfn:`Block comments` begin with
+  :samp:`/*` and continue until the next :samp:`*/`.  Block comments do not
+  nest:
+
+  .. code-block:: c++
+
+    /* this is /* one comment */ text outside comment
+
+  :dfn:`Line comments` begin with :samp:`//` and continue to the end of the
+  current line.  Line comments do not nest either, but it does not matter,
+  because they would end in the same place anyway.
+
+  .. code-block:: c++
+
+    // this is // one comment
+    text outside comment
+
+It is safe to put line comments inside block comments, or vice versa.
+
+.. code-block:: c++
+
+  /* block comment
+     // contains line comment
+     yet more comment
+   */ outside comment
+
+  // line comment /* contains block comment */
+
+But beware of commenting out one end of a block comment with a line
+comment.
+
+.. code-block::
+
+   // l.c.  /* block comment begins
+      oops! this isn't a comment anymore */
+
+Comments are not recognized within string literals.
+``"/* blah */"`` is the string constant :samp:`/\* blah \*/`, not
+an empty string.
+
+Line comments are not in the 1989 edition of the C standard, but they
+are recognized by GCC as an extension.  In C++ and in the 1999 edition
+of the C standard, they are an official part of the language.
+
+Since these transformations happen before all other processing, you can
+split a line mechanically with backslash-newline anywhere.  You can
+comment out the end of a line.  You can continue a line comment onto the
+next line with backslash-newline.  You can even split :samp:`/*`,
+:samp:`*/`, and :samp:`//` onto multiple lines with backslash-newline.
+For example:
+
+.. code-block::
+
+  /\
+  *
+  */ # /*
+  */ defi\
+  ne FO\
+  O 10\
+  20
+
+is equivalent to ``#define FOO 1020``.  All these tricks are
+extremely confusing and should not be used in code intended to be
+readable.
+
+There is no way to prevent a backslash at the end of a line from being
+interpreted as a backslash-newline.  This cannot affect any correct
+program, however.

gcc/doc/cpp/invocation.rst

@@ -0,0 +1,81 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: invocation, command line
+
+.. _invocation:
+
+Invocation
+----------
+
+Most often when you use the C preprocessor you do not have to invoke it
+explicitly: the C compiler does so automatically.  However, the
+preprocessor is sometimes useful on its own.  You can invoke the
+preprocessor either with the :command:`cpp` command, or via :command:`gcc -E`.
+In GCC, the preprocessor is actually integrated with the compiler
+rather than a separate program, and both of these commands invoke
+GCC and tell it to stop after the preprocessing phase.
+
+The :command:`cpp` options listed here are also accepted by
+:command:`gcc` and have the same meaning.  Likewise the :command:`cpp`
+command accepts all the usual :command:`gcc` driver options, although those
+pertaining to compilation phases after preprocessing are ignored.
+
+Only options specific to preprocessing behavior are documented here.
+Refer to the GCC manual for full documentation of other driver options.
+
+.. only:: man
+
+  Synopsis
+  ^^^^^^^^
+
+  cpp [ :option:`-D`:samp:`{macro}` [= :samp:`{defn}` ]...] [ :option:`-U`:samp:`{macro}` ]
+      [ :option:`-I`:samp:`{dir}`...] [ :option:`-iquote`:samp:`{dir}`...]
+      [ :option:`-M` | :option:`-MM` ] [ :option:`-MG` ] [ :option:`-MF` :samp:`{filename}` ]
+      [ :option:`-MP` ] [ :option:`-MQ` :samp:`{target}`...]
+      [ :option:`-MT` :samp:`{target}`...]
+      :samp:`{infile}` [[ :option:`-o` ] :samp:`{outfile}` ]
+
+  Only the most useful options are given above; see below for a more
+  complete list of preprocessor-specific options.
+  In addition, :command:`cpp` accepts most :command:`gcc` driver options, which
+  are not listed here.  Refer to the GCC documentation for details.
+
+Options
+^^^^^^^
+
+The :command:`cpp` command expects two file names as arguments, :samp:`{infile}` and
+:samp:`{outfile}`.  The preprocessor reads :samp:`{infile}` together with any
+other files it specifies with :samp:`#include`.  All the output generated
+by the combined input files is written in :samp:`{outfile}`.
+
+Either :samp:`{infile}` or :samp:`{outfile}` may be :option:`-`, which as
+:samp:`{infile}` means to read from standard input and as :samp:`{outfile}`
+means to write to standard output.  If either file is omitted, it
+means the same as if :option:`-` had been specified for that file.
+You can also use the :option:`-o outfile` option to specify the
+output file.
+
+Unless otherwise noted, or the option ends in :samp:`=`, all options
+which take an argument may have that argument appear either immediately
+after the option, or with a space between option and argument:
+:option:`-Ifoo` and :option:`-I foo` have the same effect.
+
+.. index:: grouping options, options, grouping
+
+Many options have multi-letter names; therefore multiple single-letter
+options may *not* be grouped: :option:`-dM` is very different from
+:samp:`-d -M`.
+
+.. index:: options
+
+.. include:: ../../../doc/cppopts.rst
+
+
+.. include:: ../../../doc/cppdiropts.rst
+
+.. only:: man
+
+  .. include:: copyright.rst

gcc/doc/cpp/line-control.rst

@@ -0,0 +1,55 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: line control
+
+.. _line-control:
+
+Line Control
+------------
+
+The C preprocessor informs the C compiler of the location in your source
+code where each token came from.  Presently, this is just the file name
+and line number.  All the tokens resulting from macro expansion are
+reported as having appeared on the line of the source file where the
+outermost macro was used.  We intend to be more accurate in the future.
+
+If you write a program which generates source code, such as the
+:command:`bison` parser generator, you may want to adjust the preprocessor's
+notion of the current file name and line number by hand.  Parts of the
+output from :command:`bison` are generated from scratch, other parts come
+from a standard parser file.  The rest are copied verbatim from
+:command:`bison`'s input.  You would like compiler error messages and
+symbolic debuggers to be able to refer to ``bison`` 's input file.
+
+.. index:: #line
+
+:command:`bison` or any such program can arrange this by writing
+:samp:`#line` directives into the output file.  :samp:`#line` is a
+directive that specifies the original line number and source file name
+for subsequent input in the current preprocessor input file.
+:samp:`#line` has three variants:
+
+:samp:`#line {linenum}`
+  :samp:`{linenum}` is a non-negative decimal integer constant.  It specifies
+  the line number which should be reported for the following line of
+  input.  Subsequent lines are counted from :samp:`{linenum}`.
+
+:samp:`#line {linenum}{filename}`
+  :samp:`{linenum}` is the same as for the first form, and has the same
+  effect.  In addition, :samp:`{filename}` is a string constant.  The
+  following line and all subsequent lines are reported to come from the
+  file it specifies, until something else happens to change that.
+  :samp:`{filename}` is interpreted according to the normal rules for a string
+  constant: backslash escapes are interpreted.  This is different from
+  :samp:`#include`.
+
+:samp:`#line {anything else}`
+  :samp:`{anything else}` is checked for macro calls, which are expanded.
+  The result should match one of the above two forms.
+
+:samp:`#line` directives alter the results of the ``__FILE__`` and
+``__LINE__`` predefined macros from that point on.  See :ref:`standard-predefined-macros`.  They do not have any effect on :samp:`#include`'s
+idea of the directory containing the current file.

gcc/doc/cpp/macros.rst

@@ -0,0 +1,37 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _macros:
+
+Macros
+------
+
+A :dfn:`macro` is a fragment of code which has been given a name.
+Whenever the name is used, it is replaced by the contents of the macro.
+There are two kinds of macros.  They differ mostly in what they look
+like when they are used.  :dfn:`Object-like` macros resemble data objects
+when used, :dfn:`function-like` macros resemble function calls.
+
+You may define any valid identifier as a macro, even if it is a C
+keyword.  The preprocessor does not know anything about keywords.  This
+can be useful if you wish to hide a keyword such as ``const`` from an
+older compiler that does not understand it.  However, the preprocessor
+operator ``defined`` (see :ref:`defined`) can never be defined as a
+macro, and C++'s named operators (see :ref:`c++-named-operators`) cannot be
+macros when you are compiling C++.
+
+.. toctree::
+  :maxdepth: 2
+
+  macros/object-like-macros
+  macros/function-like-macros
+  macros/macro-arguments
+  macros/stringizing
+  macros/concatenation
+  macros/variadic-macros
+  macros/predefined-macros
+  macros/undefining-and-redefining-macros
+  macros/directives-within-macro-arguments
+  macros/macro-pitfalls

gcc/doc/cpp/macros/concatenation.rst

@@ -0,0 +1,85 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: concatenation, token pasting, token concatenation, ## operator
+
+.. _concatenation:
+
+Concatenation
+*************
+
+It is often useful to merge two tokens into one while expanding macros.
+This is called :dfn:`token pasting` or :dfn:`token concatenation`.  The
+:samp:`##` preprocessing operator performs token pasting.  When a macro
+is expanded, the two tokens on either side of each :samp:`##` operator
+are combined into a single token, which then replaces the :samp:`##` and
+the two original tokens in the macro expansion.  Usually both will be
+identifiers, or one will be an identifier and the other a preprocessing
+number.  When pasted, they make a longer identifier.  This isn't the
+only valid case.  It is also possible to concatenate two numbers (or a
+number and a name, such as ``1.5`` and ``e3``) into a number.
+Also, multi-character operators such as ``+=`` can be formed by
+token pasting.
+
+However, two tokens that don't together form a valid token cannot be
+pasted together.  For example, you cannot concatenate ``x`` with
+``+`` in either order.  If you try, the preprocessor issues a warning
+and emits the two tokens.  Whether it puts white space between the
+tokens is undefined.  It is common to find unnecessary uses of :samp:`##`
+in complex macros.  If you get this warning, it is likely that you can
+simply remove the :samp:`##`.
+
+Both the tokens combined by :samp:`##` could come from the macro body,
+but you could just as well write them as one token in the first place.
+Token pasting is most useful when one or both of the tokens comes from a
+macro argument.  If either of the tokens next to an :samp:`##` is a
+parameter name, it is replaced by its actual argument before :samp:`##`
+executes.  As with stringizing, the actual argument is not
+macro-expanded first.  If the argument is empty, that :samp:`##` has no
+effect.
+
+Keep in mind that the C preprocessor converts comments to whitespace
+before macros are even considered.  Therefore, you cannot create a
+comment by concatenating :samp:`/` and :samp:`*`.  You can put as much
+whitespace between :samp:`##` and its operands as you like, including
+comments, and you can put comments in arguments that will be
+concatenated.  However, it is an error if :samp:`##` appears at either
+end of a macro body.
+
+Consider a C program that interprets named commands.  There probably
+needs to be a table of commands, perhaps an array of structures declared
+as follows:
+
+.. code-block:: c++
+
+  struct command
+  {
+    char *name;
+    void (*function) (void);
+  };
+
+  struct command commands[] =
+  {
+    { "quit", quit_command },
+    { "help", help_command },
+    ...
+  };
+
+It would be cleaner not to have to give each command name twice, once in
+the string constant and once in the function name.  A macro which takes the
+name of a command as an argument can make this unnecessary.  The string
+constant can be created with stringizing, and the function name by
+concatenating the argument with :samp:`_command`.  Here is how it is done:
+
+.. code-block:: c++
+
+  #define COMMAND(NAME)  { #NAME, NAME ## _command }
+
+  struct command commands[] =
+  {
+    COMMAND (quit),
+    COMMAND (help),
+    ...
+  };

gcc/doc/cpp/macros/directives-within-macro-arguments.rst

@@ -0,0 +1,39 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: macro arguments and directives
+
+.. _directives-within-macro-arguments:
+
+Directives Within Macro Arguments
+*********************************
+
+Occasionally it is convenient to use preprocessor directives within
+the arguments of a macro.  The C and C++ standards declare that
+behavior in these cases is undefined.  GNU CPP
+processes arbitrary directives within macro arguments in
+exactly the same way as it would have processed the directive were the
+function-like macro invocation not present.
+
+If, within a macro invocation, that macro is redefined, then the new
+definition takes effect in time for argument pre-expansion, but the
+original definition is still used for argument replacement.  Here is a
+pathological example:
+
+.. code-block:: c++
+
+  #define f(x) x x
+  f (1
+  #undef f
+  #define f 2
+  f)
+
+which expands to
+
+.. code-block:: c++
+
+  1 2 1 2
+
+with the semantics described above.

gcc/doc/cpp/macros/function-like-macros.rst

@@ -0,0 +1,55 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: function-like macros
+
+.. _function-like-macros:
+
+Function-like Macros
+********************
+
+You can also define macros whose use looks like a function call.  These
+are called :dfn:`function-like macros`.  To define a function-like macro,
+you use the same :samp:`#define` directive, but you put a pair of
+parentheses immediately after the macro name.  For example,
+
+.. code-block::
+
+  #define lang_init()  c_init()
+  lang_init()
+       → c_init()
+
+A function-like macro is only expanded if its name appears with a pair
+of parentheses after it.  If you write just the name, it is left alone.
+This can be useful when you have a function and a macro of the same
+name, and you wish to use the function sometimes.
+
+.. code-block::
+
+  extern void foo(void);
+  #define foo() /* optimized inline version */
+  ...
+    foo();
+    funcptr = foo;
+
+Here the call to ``foo()`` will use the macro, but the function
+pointer will get the address of the real function.  If the macro were to
+be expanded, it would cause a syntax error.
+
+If you put spaces between the macro name and the parentheses in the
+macro definition, that does not define a function-like macro, it defines
+an object-like macro whose expansion happens to begin with a pair of
+parentheses.
+
+.. code-block::
+
+  #define lang_init ()    c_init()
+  lang_init()
+       → () c_init()()
+
+The first two pairs of parentheses in this expansion come from the
+macro.  The third is the pair that was originally after the macro
+invocation.  Since ``lang_init`` is an object-like macro, it does not
+consume those parentheses.

gcc/doc/cpp/macros/macro-arguments.rst

@@ -0,0 +1,112 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: arguments, macros with arguments, arguments in macro definitions
+
+.. _macro-arguments:
+
+Macro Arguments
+***************
+
+Function-like macros can take :dfn:`arguments`, just like true functions.
+To define a macro that uses arguments, you insert :dfn:`parameters`
+between the pair of parentheses in the macro definition that make the
+macro function-like.  The parameters must be valid C identifiers,
+separated by commas and optionally whitespace.
+
+To invoke a macro that takes arguments, you write the name of the macro
+followed by a list of :dfn:`actual arguments` in parentheses, separated
+by commas.  The invocation of the macro need not be restricted to a
+single logical line---it can cross as many lines in the source file as
+you wish.  The number of arguments you give must match the number of
+parameters in the macro definition.  When the macro is expanded, each
+use of a parameter in its body is replaced by the tokens of the
+corresponding argument.  (You need not use all of the parameters in the
+macro body.)
+
+As an example, here is a macro that computes the minimum of two numeric
+values, as it is defined in many C programs, and some uses.
+
+.. code-block::
+
+  #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+    x = min(a, b);          →  x = ((a) < (b) ? (a) : (b));
+    y = min(1, 2);          →  y = ((1) < (2) ? (1) : (2));
+    z = min(a + 28, *p);    →  z = ((a + 28) < (*p) ? (a + 28) : (*p));
+
+(In this small example you can already see several of the dangers of
+macro arguments.  See :ref:`macro-pitfalls`, for detailed explanations.)
+
+Leading and trailing whitespace in each argument is dropped, and all
+whitespace between the tokens of an argument is reduced to a single
+space.  Parentheses within each argument must balance; a comma within
+such parentheses does not end the argument.  However, there is no
+requirement for square brackets or braces to balance, and they do not
+prevent a comma from separating arguments.  Thus,
+
+.. code-block:: c++
+
+  macro (array[x = y, x + 1])
+
+passes two arguments to ``macro`` : ``array[x = y`` and ``x +
+1]``.  If you want to supply ``array[x = y, x + 1]`` as an argument,
+you can write it as ``array[(x = y, x + 1)]``, which is equivalent C
+code.
+
+All arguments to a macro are completely macro-expanded before they are
+substituted into the macro body.  After substitution, the complete text
+is scanned again for macros to expand, including the arguments.  This rule
+may seem strange, but it is carefully designed so you need not worry
+about whether any function call is actually a macro invocation.  You can
+run into trouble if you try to be too clever, though.  See :ref:`argument-prescan`, for detailed discussion.
+
+For example, ``min (min (a, b), c)`` is first expanded to
+
+.. code-block:: c++
+
+    min (((a) < (b) ? (a) : (b)), (c))
+
+and then to
+
+.. code-block:: c++
+
+  ((((a) < (b) ? (a) : (b))) < (c)
+   ? (((a) < (b) ? (a) : (b)))
+   : (c))
+
+(Line breaks shown here for clarity would not actually be generated.)
+
+.. index:: empty macro arguments
+
+You can leave macro arguments empty; this is not an error to the
+preprocessor (but many macros will then expand to invalid code).
+You cannot leave out arguments entirely; if a macro takes two arguments,
+there must be exactly one comma at the top level of its argument list.
+Here are some silly examples using ``min`` :
+
+.. code-block::
+
+  min(, b)        → ((   ) < (b) ? (   ) : (b))
+  min(a, )        → ((a  ) < ( ) ? (a  ) : ( ))
+  min(,)          → ((   ) < ( ) ? (   ) : ( ))
+  min((,),)       → (((,)) < ( ) ? ((,)) : ( ))
+
+  min()      error macro "min" requires 2 arguments, but only 1 given
+  min(,,)    error macro "min" passed 3 arguments, but takes just 2
+
+Whitespace is not a preprocessing token, so if a macro ``foo`` takes
+one argument, ``foo ()`` and ``foo ( )`` both supply it an
+empty argument.  Previous GNU preprocessor implementations and
+documentation were incorrect on this point, insisting that a
+function-like macro that takes a single argument be passed a space if an
+empty argument was required.
+
+Macro parameters appearing inside string literals are not replaced by
+their corresponding actual arguments.
+
+.. code-block::
+
+  #define foo(x) x, "x"
+  foo(bar)        → bar, "x"

gcc/doc/cpp/macros/macro-pitfalls.rst

@@ -0,0 +1,449 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: problems with macros, pitfalls of macros
+
+.. _macro-pitfalls:
+
+Macro Pitfalls
+**************
+
+In this section we describe some special rules that apply to macros and
+macro expansion, and point out certain cases in which the rules have
+counter-intuitive consequences that you must watch out for.
+
+.. toctree::
+  :maxdepth: 2
+
+
+.. _misnesting:
+
+Misnesting
+^^^^^^^^^^
+
+When a macro is called with arguments, the arguments are substituted
+into the macro body and the result is checked, together with the rest of
+the input file, for more macro calls.  It is possible to piece together
+a macro call coming partially from the macro body and partially from the
+arguments.  For example,
+
+.. code-block::
+
+  #define twice(x) (2*(x))
+  #define call_with_1(x) x(1)
+  call_with_1 (twice)
+       → twice(1)
+       → (2*(1))
+
+Macro definitions do not have to have balanced parentheses.  By writing
+an unbalanced open parenthesis in a macro body, it is possible to create
+a macro call that begins inside the macro body but ends outside of it.
+For example,
+
+.. code-block::
+
+  #define strange(file) fprintf (file, "%s %d",
+  ...
+  strange(stderr) p, 35)
+       → fprintf (stderr, "%s %d", p, 35)
+
+The ability to piece together a macro call can be useful, but the use of
+unbalanced open parentheses in a macro body is just confusing, and
+should be avoided.
+
+.. index:: parentheses in macro bodies
+
+.. _operator-precedence-problems:
+
+Operator Precedence Problems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may have noticed that in most of the macro definition examples shown
+above, each occurrence of a macro argument name had parentheses around
+it.  In addition, another pair of parentheses usually surround the
+entire macro definition.  Here is why it is best to write macros that
+way.
+
+Suppose you define a macro as follows,
+
+.. code-block:: c++
+
+  #define ceil_div(x, y) (x + y - 1) / y
+
+whose purpose is to divide, rounding up.  (One use for this operation is
+to compute how many ``int`` objects are needed to hold a certain
+number of ``char`` objects.)  Then suppose it is used as follows:
+
+.. code-block::
+
+  a = ceil_div (b & c, sizeof (int));
+       → a = (b & c + sizeof (int) - 1) / sizeof (int);
+
+This does not do what is intended.  The operator-precedence rules of
+C make it equivalent to this:
+
+.. code-block:: c++
+
+  a = (b & (c + sizeof (int) - 1)) / sizeof (int);
+
+What we want is this:
+
+.. code-block:: c++
+
+  a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
+
+Defining the macro as
+
+.. code-block:: c++
+
+  #define ceil_div(x, y) ((x) + (y) - 1) / (y)
+
+provides the desired result.
+
+Unintended grouping can result in another way.  Consider ``sizeof
+ceil_div(1, 2)``.  That has the appearance of a C expression that would
+compute the size of the type of ``ceil_div (1, 2)``, but in fact it
+means something very different.  Here is what it expands to:
+
+.. code-block:: c++
+
+  sizeof ((1) + (2) - 1) / (2)
+
+This would take the size of an integer and divide it by two.  The
+precedence rules have put the division outside the ``sizeof`` when it
+was intended to be inside.
+
+Parentheses around the entire macro definition prevent such problems.
+Here, then, is the recommended way to define ``ceil_div`` :
+
+.. code-block:: c++
+
+  #define ceil_div(x, y) (((x) + (y) - 1) / (y))
+
+.. index:: semicolons (after macro calls)
+
+.. _swallowing-the-semicolon:
+
+Swallowing the Semicolon
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Often it is desirable to define a macro that expands into a compound
+statement.  Consider, for example, the following macro, that advances a
+pointer (the argument ``p`` says where to find it) across whitespace
+characters:
+
+.. code-block:: c++
+
+  #define SKIP_SPACES(p, limit)  \
+  { char *lim = (limit);         \
+    while (p < lim) {            \
+      if (*p++ != ' ') {         \
+        p--; break; }}}
+
+Here backslash-newline is used to split the macro definition, which must
+be a single logical line, so that it resembles the way such code would
+be laid out if not part of a macro definition.
+
+A call to this macro might be ``SKIP_SPACES (p, lim)``.  Strictly
+speaking, the call expands to a compound statement, which is a complete
+statement with no need for a semicolon to end it.  However, since it
+looks like a function call, it minimizes confusion if you can use it
+like a function call, writing a semicolon afterward, as in
+``SKIP_SPACES (p, lim);``
+
+This can cause trouble before ``else`` statements, because the
+semicolon is actually a null statement.  Suppose you write
+
+.. code-block:: c++
+
+  if (*p != 0)
+    SKIP_SPACES (p, lim);
+  else ...
+
+The presence of two statements---the compound statement and a null
+statement---in between the ``if`` condition and the ``else``
+makes invalid C code.
+
+The definition of the macro ``SKIP_SPACES`` can be altered to solve
+this problem, using a ``do ... while`` statement.  Here is how:
+
+.. code-block:: c++
+
+  #define SKIP_SPACES(p, limit)     \
+  do { char *lim = (limit);         \
+       while (p < lim) {            \
+         if (*p++ != ' ') {         \
+           p--; break; }}}          \
+  while (0)
+
+Now ``SKIP_SPACES (p, lim);`` expands into
+
+.. code-block:: c++
+
+  do {...} while (0);
+
+which is one statement.  The loop executes exactly once; most compilers
+generate no extra code for it.
+
+.. index:: side effects (in macro arguments), unsafe macros
+
+.. _duplication-of-side-effects:
+
+Duplication of Side Effects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many C programs define a macro ``min``, for 'minimum', like this:
+
+.. code-block:: c++
+
+  #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+
+When you use this macro with an argument containing a side effect,
+as shown here,
+
+.. code-block:: c++
+
+  next = min (x + y, foo (z));
+
+it expands as follows:
+
+.. code-block:: c++
+
+  next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
+
+where ``x + y`` has been substituted for ``X`` and ``foo (z)``
+for ``Y``.
+
+The function ``foo`` is used only once in the statement as it appears
+in the program, but the expression ``foo (z)`` has been substituted
+twice into the macro expansion.  As a result, ``foo`` might be called
+two times when the statement is executed.  If it has side effects or if
+it takes a long time to compute, the results might not be what you
+intended.  We say that ``min`` is an :dfn:`unsafe` macro.
+
+The best solution to this problem is to define ``min`` in a way that
+computes the value of ``foo (z)`` only once.  The C language offers
+no standard way to do this, but it can be done with GNU extensions as
+follows:
+
+.. code-block:: c++
+
+  #define min(X, Y)                \
+  ({ typeof (X) x_ = (X);          \
+     typeof (Y) y_ = (Y);          \
+     (x_ < y_) ? x_ : y_; })
+
+The :samp:`({ ... })` notation produces a compound statement that
+acts as an expression.  Its value is the value of its last statement.
+This permits us to define local variables and assign each argument to
+one.  The local variables have underscores after their names to reduce
+the risk of conflict with an identifier of wider scope (it is impossible
+to avoid this entirely).  Now each argument is evaluated exactly once.
+
+If you do not wish to use GNU C extensions, the only solution is to be
+careful when *using* the macro ``min``.  For example, you can
+calculate the value of ``foo (z)``, save it in a variable, and use
+that variable in ``min`` :
+
+.. code-block:: c++
+
+  #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+  ...
+  {
+    int tem = foo (z);
+    next = min (x + y, tem);
+  }
+
+(where we assume that ``foo`` returns type ``int``).
+
+.. index:: self-reference
+
+.. _self-referential-macros:
+
+Self-Referential Macros
+^^^^^^^^^^^^^^^^^^^^^^^
+
+A :dfn:`self-referential` macro is one whose name appears in its
+definition.  Recall that all macro definitions are rescanned for more
+macros to replace.  If the self-reference were considered a use of the
+macro, it would produce an infinitely large expansion.  To prevent this,
+the self-reference is not considered a macro call.  It is passed into
+the preprocessor output unchanged.  Consider an example:
+
+.. code-block:: c++
+
+  #define foo (4 + foo)
+
+where ``foo`` is also a variable in your program.
+
+Following the ordinary rules, each reference to ``foo`` will expand
+into ``(4 + foo)`` ; then this will be rescanned and will expand into
+``(4 + (4 + foo))`` ; and so on until the computer runs out of memory.
+
+The self-reference rule cuts this process short after one step, at
+``(4 + foo)``.  Therefore, this macro definition has the possibly
+useful effect of causing the program to add 4 to the value of ``foo``
+wherever ``foo`` is referred to.
+
+In most cases, it is a bad idea to take advantage of this feature.  A
+person reading the program who sees that ``foo`` is a variable will
+not expect that it is a macro as well.  The reader will come across the
+identifier ``foo`` in the program and think its value should be that
+of the variable ``foo``, whereas in fact the value is four greater.
+
+One common, useful use of self-reference is to create a macro which
+expands to itself.  If you write
+
+.. code-block:: c++
+
+  #define EPERM EPERM
+
+then the macro ``EPERM`` expands to ``EPERM``.  Effectively, it is
+left alone by the preprocessor whenever it's used in running text.  You
+can tell that it's a macro with :samp:`#ifdef`.  You might do this if you
+want to define numeric constants with an ``enum``, but have
+:samp:`#ifdef` be true for each constant.
+
+If a macro ``x`` expands to use a macro ``y``, and the expansion of
+``y`` refers to the macro ``x``, that is an :dfn:`indirect
+self-reference` of ``x``.  ``x`` is not expanded in this case
+either.  Thus, if we have
+
+.. code-block:: c++
+
+  #define x (4 + y)
+  #define y (2 * x)
+
+then ``x`` and ``y`` expand as follows:
+
+.. code-block::
+
+  x    → (4 + y)
+       → (4 + (2 * x))
+
+  y    → (2 * x)
+       → (2 * (4 + y))
+
+Each macro is expanded when it appears in the definition of the other
+macro, but not when it indirectly appears in its own definition.
+
+.. index:: expansion of arguments, macro argument expansion, prescan of macro arguments
+
+.. _argument-prescan:
+
+Argument Prescan
+^^^^^^^^^^^^^^^^
+
+Macro arguments are completely macro-expanded before they are
+substituted into a macro body, unless they are stringized or pasted
+with other tokens.  After substitution, the entire macro body, including
+the substituted arguments, is scanned again for macros to be expanded.
+The result is that the arguments are scanned *twice* to expand
+macro calls in them.
+
+Most of the time, this has no effect.  If the argument contained any
+macro calls, they are expanded during the first scan.  The result
+therefore contains no macro calls, so the second scan does not change
+it.  If the argument were substituted as given, with no prescan, the
+single remaining scan would find the same macro calls and produce the
+same results.
+
+You might expect the double scan to change the results when a
+self-referential macro is used in an argument of another macro
+(see :ref:`self-referential-macros`): the self-referential macro would be
+expanded once in the first scan, and a second time in the second scan.
+However, this is not what happens.  The self-references that do not
+expand in the first scan are marked so that they will not expand in the
+second scan either.
+
+You might wonder, 'Why mention the prescan, if it makes no difference?
+And why not skip it and make the preprocessor faster?'  The answer is
+that the prescan does make a difference in three special cases:
+
+* Nested calls to a macro.
+
+  We say that :dfn:`nested` calls to a macro occur when a macro's argument
+  contains a call to that very macro.  For example, if ``f`` is a macro
+  that expects one argument, ``f (f (1))`` is a nested pair of calls to
+  ``f``.  The desired expansion is made by expanding ``f (1)`` and
+  substituting that into the definition of ``f``.  The prescan causes
+  the expected result to happen.  Without the prescan, ``f (1)`` itself
+  would be substituted as an argument, and the inner use of ``f`` would
+  appear during the main scan as an indirect self-reference and would not
+  be expanded.
+
+* Macros that call other macros that stringize or concatenate.
+
+  If an argument is stringized or concatenated, the prescan does not
+  occur.  If you *want* to expand a macro, then stringize or
+  concatenate its expansion, you can do that by causing one macro to call
+  another macro that does the stringizing or concatenation.  For
+  instance, if you have
+
+  .. code-block:: c++
+
+    #define AFTERX(x) X_ ## x
+    #define XAFTERX(x) AFTERX(x)
+    #define TABLESIZE 1024
+    #define BUFSIZE TABLESIZE
+
+  then ``AFTERX(BUFSIZE)`` expands to ``X_BUFSIZE``, and
+  ``XAFTERX(BUFSIZE)`` expands to ``X_1024``.  (Not to
+  ``X_TABLESIZE``.  Prescan always does a complete expansion.)
+
+* Macros used in arguments, whose expansions contain unshielded commas.
+
+  This can cause a macro expanded on the second scan to be called with the
+  wrong number of arguments.  Here is an example:
+
+  .. code-block:: c++
+
+    #define foo  a,b
+    #define bar(x) lose(x)
+    #define lose(x) (1 + (x))
+
+  We would like ``bar(foo)`` to turn into ``(1 + (foo))``, which
+  would then turn into ``(1 + (a,b))``.  Instead, ``bar(foo)``
+  expands into ``lose(a,b)``, and you get an error because ``lose``
+  requires a single argument.  In this case, the problem is easily solved
+  by the same parentheses that ought to be used to prevent misnesting of
+  arithmetic operations:
+
+  .. code-block::
+
+    #define foo (a,b)
+    or#define bar(x) lose((x))
+
+  The extra pair of parentheses prevents the comma in ``foo`` 's
+  definition from being interpreted as an argument separator.
+
+.. index:: newlines in macro arguments
+
+.. _newlines-in-arguments:
+
+Newlines in Arguments
+^^^^^^^^^^^^^^^^^^^^^
+
+The invocation of a function-like macro can extend over many logical
+lines.  However, in the present implementation, the entire expansion
+comes out on one line.  Thus line numbers emitted by the compiler or
+debugger refer to the line the invocation started on, which might be
+different to the line containing the argument causing the problem.
+
+Here is an example illustrating this:
+
+.. code-block:: c++
+
+  #define ignore_second_arg(a,b,c) a; c
+
+  ignore_second_arg (foo (),
+                     ignored (),
+                     syntax error);
+
+The syntax error triggered by the tokens ``syntax error`` results in
+an error message citing line three---the line of ignore_second_arg---
+even though the problematic code comes from line five.
+
+We consider this a bug, and intend to fix it in the near future.

gcc/doc/cpp/macros/object-like-macros.rst

@@ -0,0 +1,126 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: object-like macro, symbolic constants, manifest constants
+
+.. _object-like-macros:
+
+Object-like Macros
+******************
+
+An :dfn:`object-like macro` is a simple identifier which will be replaced
+by a code fragment.  It is called object-like because it looks like a
+data object in code that uses it.  They are most commonly used to give
+symbolic names to numeric constants.
+
+.. index:: #define
+
+You create macros with the :samp:`#define` directive.  :samp:`#define` is
+followed by the name of the macro and then the token sequence it should
+be an abbreviation for, which is variously referred to as the macro's
+:dfn:`body`, :dfn:`expansion` or :dfn:`replacement list`.  For example,
+
+.. code-block:: c++
+
+  #define BUFFER_SIZE 1024
+
+defines a macro named ``BUFFER_SIZE`` as an abbreviation for the
+token ``1024``.  If somewhere after this :samp:`#define` directive
+there comes a C statement of the form
+
+.. code-block:: c++
+
+  foo = (char *) malloc (BUFFER_SIZE);
+
+then the C preprocessor will recognize and :dfn:`expand` the macro
+``BUFFER_SIZE``.  The C compiler will see the same tokens as it would
+if you had written
+
+.. code-block:: c++
+
+  foo = (char *) malloc (1024);
+
+By convention, macro names are written in uppercase.  Programs are
+easier to read when it is possible to tell at a glance which names are
+macros.
+
+The macro's body ends at the end of the :samp:`#define` line.  You may
+continue the definition onto multiple lines, if necessary, using
+backslash-newline.  When the macro is expanded, however, it will all
+come out on one line.  For example,
+
+.. code-block::
+
+  #define NUMBERS 1, \
+                  2, \
+                  3
+  int x[] = { NUMBERS };
+       → int x[] = { 1, 2, 3 };
+
+The most common visible consequence of this is surprising line numbers
+in error messages.
+
+There is no restriction on what can go in a macro body provided it
+decomposes into valid preprocessing tokens.  Parentheses need not
+balance, and the body need not resemble valid C code.  (If it does not,
+you may get error messages from the C compiler when you use the macro.)
+
+The C preprocessor scans your program sequentially.  Macro definitions
+take effect at the place you write them.  Therefore, the following input
+to the C preprocessor
+
+.. code-block:: c++
+
+  foo = X;
+  #define X 4
+  bar = X;
+
+produces
+
+.. code-block:: c++
+
+  foo = X;
+  bar = 4;
+
+When the preprocessor expands a macro name, the macro's expansion
+replaces the macro invocation, then the expansion is examined for more
+macros to expand.  For example,
+
+.. code-block::
+
+  #define TABLESIZE BUFSIZE
+  #define BUFSIZE 1024
+  TABLESIZE
+       → BUFSIZE
+       → 1024
+
+``TABLESIZE`` is expanded first to produce ``BUFSIZE``, then that
+macro is expanded to produce the final result, ``1024``.
+
+Notice that ``BUFSIZE`` was not defined when ``TABLESIZE`` was
+defined.  The :samp:`#define` for ``TABLESIZE`` uses exactly the
+expansion you specify---in this case, ``BUFSIZE`` ---and does not
+check to see whether it too contains macro names.  Only when you
+*use* ``TABLESIZE`` is the result of its expansion scanned for
+more macro names.
+
+This makes a difference if you change the definition of ``BUFSIZE``
+at some point in the source file.  ``TABLESIZE``, defined as shown,
+will always expand using the definition of ``BUFSIZE`` that is
+currently in effect:
+
+.. code-block:: c++
+
+  #define BUFSIZE 1020
+  #define TABLESIZE BUFSIZE
+  #undef BUFSIZE
+  #define BUFSIZE 37
+
+Now ``TABLESIZE`` expands (in two stages) to ``37``.
+
+If the expansion of a macro contains its own name, either directly or
+via intermediate macros, it is not expanded again when the expansion is
+examined for more macros.  This prevents infinite recursion.
+See :ref:`self-referential-macros`, for the precise details.

gcc/doc/cpp/macros/predefined-macros.rst

@@ -0,0 +1,874 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: predefined macros
+
+.. _predefined-macros:
+
+Predefined Macros
+*****************
+
+Several object-like macros are predefined; you use them without
+supplying their definitions.  They fall into three classes: standard,
+common, and system-specific.
+
+In C++, there is a fourth category, the named operators.  They act like
+predefined macros, but you cannot undefine them.
+
+.. toctree::
+  :maxdepth: 2
+
+
+.. index:: standard predefined macros.
+
+.. _standard-predefined-macros:
+
+Standard Predefined Macros
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The standard predefined macros are specified by the relevant
+language standards, so they are available with all compilers that
+implement those standards.  Older compilers may not provide all of
+them.  Their names all start with double underscores.
+
+.. c:macro:: __FILE__
+
+  This macro expands to the name of the current input file, in the form of
+  a C string constant.  This is the path by which the preprocessor opened
+  the file, not the short name specified in :samp:`#include` or as the
+  input file name argument.  For example,
+  ``"/usr/local/include/myheader.h"`` is a possible expansion of this
+  macro.
+
+.. c:macro:: __LINE__
+
+  This macro expands to the current input line number, in the form of a
+  decimal integer constant.  While we call it a predefined macro, it's
+  a pretty strange macro, since its 'definition' changes with each
+  new line of source code.
+
+  ``__FILE__`` and ``__LINE__`` are useful in generating an error
+  message to report an inconsistency detected by the program; the message
+  can state the source line at which the inconsistency was detected.  For
+  example,
+
+.. code-block:: c++
+
+  fprintf (stderr, "Internal error: "
+                   "negative string length "
+                   "%d at %s, line %d.",
+           length, __FILE__, __LINE__);
+
+An :samp:`#include` directive changes the expansions of ``__FILE__``
+and ``__LINE__`` to correspond to the included file.  At the end of
+that file, when processing resumes on the input file that contained
+the :samp:`#include` directive, the expansions of ``__FILE__`` and
+``__LINE__`` revert to the values they had before the
+:samp:`#include` (but ``__LINE__`` is then incremented by one as
+processing moves to the line after the :samp:`#include`).
+
+A :samp:`#line` directive changes ``__LINE__``, and may change
+``__FILE__`` as well.  See :ref:`line-control`.
+
+C99 introduced ``__func__``, and GCC has provided ``__FUNCTION__``
+for a long time.  Both of these are strings containing the name of the
+current function (there are slight semantic differences; see the GCC
+manual).  Neither of them is a macro; the preprocessor does not know the
+name of the current function.  They tend to be useful in conjunction
+with ``__FILE__`` and ``__LINE__``, though.
+
+.. c:macro:: __DATE__
+
+  This macro expands to a string constant that describes the date on which
+  the preprocessor is being run.  The string constant contains eleven
+  characters and looks like ``"Feb 12 1996"``.  If the day of the
+  month is less than 10, it is padded with a space on the left.
+
+  If GCC cannot determine the current date, it will emit a warning message
+  (once per compilation) and ``__DATE__`` will expand to
+  ``"??? ?? ????"``.
+
+.. c:macro:: __TIME__
+
+  This macro expands to a string constant that describes the time at
+  which the preprocessor is being run.  The string constant contains
+  eight characters and looks like ``"23:59:01"``.
+
+  If GCC cannot determine the current time, it will emit a warning message
+  (once per compilation) and ``__TIME__`` will expand to
+  ``"??:??:??"``.
+
+.. c:macro:: __STDC__
+
+  In normal operation, this macro expands to the constant 1, to signify
+  that this compiler conforms to ISO Standard C.  If GNU CPP is used with
+  a compiler other than GCC, this is not necessarily true; however, the
+  preprocessor always conforms to the standard unless the
+  :option:`-traditional-cpp` option is used.
+
+  This macro is not defined if the :option:`-traditional-cpp` option is used.
+
+  On some hosts, the system compiler uses a different convention, where
+  ``__STDC__`` is normally 0, but is 1 if the user specifies strict
+  conformance to the C Standard.  CPP follows the host convention when
+  processing system header files, but when processing user files
+  ``__STDC__`` is always 1.  This has been reported to cause problems;
+  for instance, some versions of Solaris provide X Windows headers that
+  expect ``__STDC__`` to be either undefined or 1.  See :ref:`invocation`.
+
+.. c:macro:: __STDC_VERSION__
+
+  This macro expands to the C Standard's version number, a long integer
+  constant of the form ``yyyymmL`` where :samp:`{yyyy}` and
+  :samp:`{mm}` are the year and month of the Standard version.  This signifies
+  which version of the C Standard the compiler conforms to.  Like
+  ``__STDC__``, this is not necessarily accurate for the entire
+  implementation, unless GNU CPP is being used with GCC.
+
+  The value ``199409L`` signifies the 1989 C standard as amended in
+  1994, which is the current default; the value ``199901L`` signifies
+  the 1999 revision of the C standard; the value ``201112L``
+  signifies the 2011 revision of the C standard; the value
+  ``201710L`` signifies the 2017 revision of the C standard (which is
+  otherwise identical to the 2011 version apart from correction of
+  defects).  An unspecified value larger than ``201710L`` is used for
+  the experimental :option:`-std=c2x` and :option:`-std=gnu2x` modes.
+
+  This macro is not defined if the :option:`-traditional-cpp` option is
+  used, nor when compiling C++ or Objective-C.
+
+.. c:macro:: __STDC_HOSTED__
+
+  This macro is defined, with value 1, if the compiler's target is a
+  :dfn:`hosted environment`.  A hosted environment has the complete
+  facilities of the standard C library available.
+
+.. c:macro:: __cplusplus
+
+  This macro is defined when the C++ compiler is in use.  You can use
+  ``__cplusplus`` to test whether a header is compiled by a C compiler
+  or a C++ compiler.  This macro is similar to ``__STDC_VERSION__``, in
+  that it expands to a version number.  Depending on the language standard
+  selected, the value of the macro is
+  ``199711L`` for the 1998 C++ standard,
+  ``201103L`` for the 2011 C++ standard,
+  ``201402L`` for the 2014 C++ standard,
+  ``201703L`` for the 2017 C++ standard,
+  ``202002L`` for the 2020 C++ standard,
+  or an unspecified value strictly larger than ``202002L`` for the
+  experimental languages enabled by :option:`-std=c++23` and
+  :option:`-std=gnu++23`.
+
+.. c:macro:: __OBJC__
+
+  This macro is defined, with value 1, when the Objective-C compiler is in
+  use.  You can use ``__OBJC__`` to test whether a header is compiled
+  by a C compiler or an Objective-C compiler.
+
+.. c:macro:: __ASSEMBLER__
+
+  This macro is defined with value 1 when preprocessing assembly
+  language.
+
+.. index:: common predefined macros
+
+.. _common-predefined-macros:
+
+Common Predefined Macros
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The common predefined macros are GNU C extensions.  They are available
+with the same meanings regardless of the machine or operating system on
+which you are using GNU C or GNU Fortran.  Their names all start with
+double underscores.
+
+.. c:macro:: __COUNTER__
+
+  This macro expands to sequential integral values starting from 0.  In
+  conjunction with the ``##`` operator, this provides a convenient means to
+  generate unique identifiers.  Care must be taken to ensure that
+  ``__COUNTER__`` is not expanded prior to inclusion of precompiled headers
+  which use it.  Otherwise, the precompiled headers will not be used.
+
+.. c:macro:: __GFORTRAN__
+
+  The GNU Fortran compiler defines this.
+
+.. c:macro:: __GNUC__
+             __GNUC_MINOR__
+             __GNUC_PATCHLEVEL__
+
+  These macros are defined by all GNU compilers that use the C
+  preprocessor: C, C++, Objective-C and Fortran.  Their values are the major
+  version, minor version, and patch level of the compiler, as integer
+  constants.  For example, GCC version :samp:`{x}`. :samp:`{y}`. :samp:`{z}`
+  defines ``__GNUC__`` to :samp:`{x}`, ``__GNUC_MINOR__`` to :samp:`{y}`,
+  and ``__GNUC_PATCHLEVEL__`` to :samp:`{z}`.  These
+  macros are also defined if you invoke the preprocessor directly.
+
+  If all you need to know is whether or not your program is being compiled
+  by GCC, or a non-GCC compiler that claims to accept the GNU C dialects,
+  you can simply test ``__GNUC__``.  If you need to write code
+  which depends on a specific version, you must be more careful.  Each
+  time the minor version is increased, the patch level is reset to zero;
+  each time the major version is increased, the
+  minor version and patch level are reset.  If you wish to use the
+  predefined macros directly in the conditional, you will need to write it
+  like this:
+
+  .. code-block:: c++
+
+    /* Test for GCC > 3.2.0 */
+    #if __GNUC__ > 3 || \
+        (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
+                           (__GNUC_MINOR__ == 2 && \
+                            __GNUC_PATCHLEVEL__ > 0))
+
+  Another approach is to use the predefined macros to
+  calculate a single number, then compare that against a threshold:
+
+  .. code-block:: c++
+
+    #define GCC_VERSION (__GNUC__ * 10000 \
+                         + __GNUC_MINOR__ * 100 \
+                         + __GNUC_PATCHLEVEL__)
+    ...
+    /* Test for GCC > 3.2.0 */
+    #if GCC_VERSION > 30200
+
+  Many people find this form easier to understand.
+
+.. c:macro:: __GNUG__
+
+  The GNU C++ compiler defines this.  Testing it is equivalent to
+  testing ``(__GNUC__ && __cplusplus)``.
+
+.. c:macro:: __STRICT_ANSI__
+
+  GCC defines this macro if and only if the :option:`-ansi` switch, or a
+  :option:`-std` switch specifying strict conformance to some version of ISO C
+  or ISO C++, was specified when GCC was invoked.  It is defined to :samp:`1`.
+  This macro exists primarily to direct GNU libc's header files to use only
+  definitions found in standard C.
+
+.. c:macro:: __BASE_FILE__
+
+  This macro expands to the name of the main input file, in the form
+  of a C string constant.  This is the source file that was specified
+  on the command line of the preprocessor or C compiler.
+
+.. c:macro:: __FILE_NAME__
+
+  This macro expands to the basename of the current input file, in the
+  form of a C string constant.  This is the last path component by which
+  the preprocessor opened the file.  For example, processing
+  ``"/usr/local/include/myheader.h"`` would set this
+  macro to ``"myheader.h"``.
+
+.. c:macro:: __INCLUDE_LEVEL__
+
+  This macro expands to a decimal integer constant that represents the
+  depth of nesting in include files.  The value of this macro is
+  incremented on every :samp:`#include` directive and decremented at the
+  end of every included file.  It starts out at 0, its value within the
+  base file specified on the command line.
+
+.. c:macro:: __ELF__
+
+  This macro is defined if the target uses the ELF object format.
+
+.. c:macro:: __VERSION__
+
+  This macro expands to a string constant which describes the version of
+  the compiler in use.  You should not rely on its contents having any
+  particular form, but it can be counted on to contain at least the
+  release number.
+
+.. c:macro:: __OPTIMIZE__
+             __OPTIMIZE_SIZE__
+             __NO_INLINE__
+
+  These macros describe the compilation mode.  ``__OPTIMIZE__`` is
+  defined in all optimizing compilations.  ``__OPTIMIZE_SIZE__`` is
+  defined if the compiler is optimizing for size, not speed.
+  ``__NO_INLINE__`` is defined if no functions will be inlined into
+  their callers (when not optimizing, or when inlining has been
+  specifically disabled by :option:`-fno-inline`).
+
+  These macros cause certain GNU header files to provide optimized
+  definitions, using macros or inline functions, of system library
+  functions.  You should not use these macros in any way unless you make
+  sure that programs will execute with the same effect whether or not they
+  are defined.  If they are defined, their value is 1.
+
+.. c:macro:: __GNUC_GNU_INLINE__
+
+  GCC defines this macro if functions declared ``inline`` will be
+  handled in GCC's traditional gnu90 mode.  Object files will contain
+  externally visible definitions of all functions declared ``inline``
+  without ``extern`` or ``static``.  They will not contain any
+  definitions of any functions declared ``extern inline``.
+
+.. c:macro:: __GNUC_STDC_INLINE__
+
+  GCC defines this macro if functions declared ``inline`` will be
+  handled according to the ISO C99 or later standards.  Object files will contain
+  externally visible definitions of all functions declared ``extern
+  inline``.  They will not contain definitions of any functions declared
+  ``inline`` without ``extern``.
+
+  If this macro is defined, GCC supports the ``gnu_inline`` function
+  attribute as a way to always get the gnu90 behavior.
+
+.. c:macro:: __CHAR_UNSIGNED__
+
+  GCC defines this macro if and only if the data type ``char`` is
+  unsigned on the target machine.  It exists to cause the standard header
+  file :samp:`limits.h` to work correctly.  You should not use this macro
+  yourself; instead, refer to the standard macros defined in :samp:`limits.h`.
+
+.. c:macro:: __WCHAR_UNSIGNED__
+
+  Like ``__CHAR_UNSIGNED__``, this macro is defined if and only if the
+  data type ``wchar_t`` is unsigned and the front-end is in C++ mode.
+
+.. c:macro:: __REGISTER_PREFIX__
+
+  This macro expands to a single token (not a string constant) which is
+  the prefix applied to CPU register names in assembly language for this
+  target.  You can use it to write assembly that is usable in multiple
+  environments.  For example, in the ``m68k-aout`` environment it
+  expands to nothing, but in the ``m68k-coff`` environment it expands
+  to a single :samp:`%`.
+
+.. c:macro:: __USER_LABEL_PREFIX__
+
+  This macro expands to a single token which is the prefix applied to
+  user labels (symbols visible to C code) in assembly.  For example, in
+  the ``m68k-aout`` environment it expands to an :samp:`_`, but in the
+  ``m68k-coff`` environment it expands to nothing.
+
+  This macro will have the correct definition even if
+  :option:`-f(no-)underscores` is in use, but it will not be correct if
+  target-specific options that adjust this prefix are used (e.g. the
+  OSF/rose :option:`-mno-underscores` option).
+
+.. c:macro:: __SIZE_TYPE__
+             __PTRDIFF_TYPE__
+             __WCHAR_TYPE__
+             __WINT_TYPE__
+             __INTMAX_TYPE__
+             __UINTMAX_TYPE__
+             __SIG_ATOMIC_TYPE__
+             __INT8_TYPE__
+             __INT16_TYPE__
+             __INT32_TYPE__
+             __INT64_TYPE__
+             __UINT8_TYPE__
+             __UINT16_TYPE__
+             __UINT32_TYPE__
+             __UINT64_TYPE__
+             __INT_LEAST8_TYPE__
+             __INT_LEAST16_TYPE__
+             __INT_LEAST32_TYPE__
+             __INT_LEAST64_TYPE__
+             __UINT_LEAST8_TYPE__
+             __UINT_LEAST16_TYPE__
+             __UINT_LEAST32_TYPE__
+             __UINT_LEAST64_TYPE__
+             __INT_FAST8_TYPE__
+             __INT_FAST16_TYPE__
+             __INT_FAST32_TYPE__
+             __INT_FAST64_TYPE__
+             __UINT_FAST8_TYPE__
+             __UINT_FAST16_TYPE__
+             __UINT_FAST32_TYPE__
+             __UINT_FAST64_TYPE__
+             __INTPTR_TYPE__
+             __UINTPTR_TYPE__
+
+  These macros are defined to the correct underlying types for the
+  ``size_t``, ``ptrdiff_t``, ``wchar_t``, ``wint_t``,
+  ``intmax_t``, ``uintmax_t``, ``sig_atomic_t``, ``int8_t``,
+  ``int16_t``, ``int32_t``, ``int64_t``, ``uint8_t``,
+  ``uint16_t``, ``uint32_t``, ``uint64_t``,
+  ``int_least8_t``, ``int_least16_t``, ``int_least32_t``,
+  ``int_least64_t``, ``uint_least8_t``, ``uint_least16_t``,
+  ``uint_least32_t``, ``uint_least64_t``, ``int_fast8_t``,
+  ``int_fast16_t``, ``int_fast32_t``, ``int_fast64_t``,
+  ``uint_fast8_t``, ``uint_fast16_t``, ``uint_fast32_t``,
+  ``uint_fast64_t``, ``intptr_t``, and ``uintptr_t`` typedefs,
+  respectively.  They exist to make the standard header files
+  :samp:`stddef.h`, :samp:`stdint.h`, and :samp:`wchar.h` work correctly.
+  You should not use these macros directly; instead, include the
+  appropriate headers and use the typedefs.  Some of these macros may
+  not be defined on particular systems if GCC does not provide a
+  :samp:`stdint.h` header on those systems.
+
+.. c:macro:: __CHAR_BIT__
+
+  Defined to the number of bits used in the representation of the
+  ``char`` data type.  It exists to make the standard header given
+  numerical limits work correctly.  You should not use
+  this macro directly; instead, include the appropriate headers.
+
+.. c:macro:: __SCHAR_MAX__
+             __WCHAR_MAX__
+             __SHRT_MAX__
+             __INT_MAX__
+             __LONG_MAX__
+             __LONG_LONG_MAX__
+             __WINT_MAX__
+             __SIZE_MAX__
+             __PTRDIFF_MAX__
+             __INTMAX_MAX__
+             __UINTMAX_MAX__
+             __SIG_ATOMIC_MAX__
+             __INT8_MAX__
+             __INT16_MAX__
+             __INT32_MAX__
+             __INT64_MAX__
+             __UINT8_MAX__
+             __UINT16_MAX__
+             __UINT32_MAX__
+             __UINT64_MAX__
+             __INT_LEAST8_MAX__
+             __INT_LEAST16_MAX__
+             __INT_LEAST32_MAX__
+             __INT_LEAST64_MAX__
+             __UINT_LEAST8_MAX__
+             __UINT_LEAST16_MAX__
+             __UINT_LEAST32_MAX__
+             __UINT_LEAST64_MAX__
+             __INT_FAST8_MAX__
+             __INT_FAST16_MAX__
+             __INT_FAST32_MAX__
+             __INT_FAST64_MAX__
+             __UINT_FAST8_MAX__
+             __UINT_FAST16_MAX__
+             __UINT_FAST32_MAX__
+             __UINT_FAST64_MAX__
+             __INTPTR_MAX__
+             __UINTPTR_MAX__
+             __WCHAR_MIN__
+             __WINT_MIN__
+             __SIG_ATOMIC_MIN__
+
+  Defined to the maximum value of the ``signed char``, ``wchar_t``,
+  ``signed short``,
+  ``signed int``, ``signed long``, ``signed long long``,
+  ``wint_t``, ``size_t``, ``ptrdiff_t``,
+  ``intmax_t``, ``uintmax_t``, ``sig_atomic_t``, ``int8_t``,
+  ``int16_t``, ``int32_t``, ``int64_t``, ``uint8_t``,
+  ``uint16_t``, ``uint32_t``, ``uint64_t``,
+  ``int_least8_t``, ``int_least16_t``, ``int_least32_t``,
+  ``int_least64_t``, ``uint_least8_t``, ``uint_least16_t``,
+  ``uint_least32_t``, ``uint_least64_t``, ``int_fast8_t``,
+  ``int_fast16_t``, ``int_fast32_t``, ``int_fast64_t``,
+  ``uint_fast8_t``, ``uint_fast16_t``, ``uint_fast32_t``,
+  ``uint_fast64_t``, ``intptr_t``, and ``uintptr_t`` types and
+  to the minimum value of the ``wchar_t``, ``wint_t``, and
+  ``sig_atomic_t`` types respectively.  They exist to make the
+  standard header given numerical limits work correctly.  You should not
+  use these macros directly; instead, include the appropriate headers.
+  Some of these macros may not be defined on particular systems if GCC
+  does not provide a :samp:`stdint.h` header on those systems.
+
+.. c:macro:: __INT8_C
+             __INT16_C
+             __INT32_C
+             __INT64_C
+             __UINT8_C
+             __UINT16_C
+             __UINT32_C
+             __UINT64_C
+             __INTMAX_C
+             __UINTMAX_C
+
+  Defined to implementations of the standard :samp:`stdint.h` macros with
+  the same names without the leading ``__``.  They exist the make the
+  implementation of that header work correctly.  You should not use
+  these macros directly; instead, include the appropriate headers.  Some
+  of these macros may not be defined on particular systems if GCC does
+  not provide a :samp:`stdint.h` header on those systems.
+
+.. c:macro:: __SCHAR_WIDTH__
+             __SHRT_WIDTH__
+             __INT_WIDTH__
+             __LONG_WIDTH__
+             __LONG_LONG_WIDTH__
+             __PTRDIFF_WIDTH__
+             __SIG_ATOMIC_WIDTH__
+             __SIZE_WIDTH__
+             __WCHAR_WIDTH__
+             __WINT_WIDTH__
+             __INT_LEAST8_WIDTH__
+             __INT_LEAST16_WIDTH__
+             __INT_LEAST32_WIDTH__
+             __INT_LEAST64_WIDTH__
+             __INT_FAST8_WIDTH__
+             __INT_FAST16_WIDTH__
+             __INT_FAST32_WIDTH__
+             __INT_FAST64_WIDTH__
+             __INTPTR_WIDTH__
+             __INTMAX_WIDTH__
+
+  Defined to the bit widths of the corresponding types.  They exist to
+  make the implementations of :samp:`limits.h` and :samp:`stdint.h` behave
+  correctly.  You should not use these macros directly; instead, include
+  the appropriate headers.  Some of these macros may not be defined on
+  particular systems if GCC does not provide a :samp:`stdint.h` header on
+  those systems.
+
+.. c:macro:: __SIZEOF_INT__
+             __SIZEOF_LONG__
+             __SIZEOF_LONG_LONG__
+             __SIZEOF_SHORT__
+             __SIZEOF_POINTER__
+             __SIZEOF_FLOAT__
+             __SIZEOF_DOUBLE__
+             __SIZEOF_LONG_DOUBLE__
+             __SIZEOF_SIZE_T__
+             __SIZEOF_WCHAR_T__
+             __SIZEOF_WINT_T__
+             __SIZEOF_PTRDIFF_T__
+
+  Defined to the number of bytes of the C standard data types: ``int``,
+  ``long``, ``long long``, ``short``, ``void *``, ``float``,
+  ``double``, ``long double``, ``size_t``, ``wchar_t``, ``wint_t``
+  and ``ptrdiff_t``.
+
+.. c:macro:: __BYTE_ORDER__
+             __ORDER_LITTLE_ENDIAN__
+             __ORDER_BIG_ENDIAN__
+             __ORDER_PDP_ENDIAN__
+
+  ``__BYTE_ORDER__`` is defined to one of the values
+  ``__ORDER_LITTLE_ENDIAN__``, ``__ORDER_BIG_ENDIAN__``, or
+  ``__ORDER_PDP_ENDIAN__`` to reflect the layout of multi-byte and
+  multi-word quantities in memory.  If ``__BYTE_ORDER__`` is equal to
+  ``__ORDER_LITTLE_ENDIAN__`` or ``__ORDER_BIG_ENDIAN__``, then
+  multi-byte and multi-word quantities are laid out identically: the
+  byte (word) at the lowest address is the least significant or most
+  significant byte (word) of the quantity, respectively.  If
+  ``__BYTE_ORDER__`` is equal to ``__ORDER_PDP_ENDIAN__``, then
+  bytes in 16-bit words are laid out in a little-endian fashion, whereas
+  the 16-bit subwords of a 32-bit quantity are laid out in big-endian
+  fashion.
+
+  You should use these macros for testing like this:
+
+  .. code-block:: c++
+
+    /* Test for a little-endian machine */
+    #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+
+.. c:macro:: __FLOAT_WORD_ORDER__
+
+  ``__FLOAT_WORD_ORDER__`` is defined to one of the values
+  ``__ORDER_LITTLE_ENDIAN__`` or ``__ORDER_BIG_ENDIAN__`` to reflect
+  the layout of the words of multi-word floating-point quantities.
+
+.. c:macro:: __DEPRECATED
+
+  This macro is defined, with value 1, when compiling a C++ source file
+  with warnings about deprecated constructs enabled.  These warnings are
+  enabled by default, but can be disabled with :option:`-Wno-deprecated`.
+
+.. c:macro:: __EXCEPTIONS
+
+  This macro is defined, with value 1, when compiling a C++ source file
+  with exceptions enabled.  If :option:`-fno-exceptions` is used when
+  compiling the file, then this macro is not defined.
+
+.. c:macro:: __GXX_RTTI
+
+  This macro is defined, with value 1, when compiling a C++ source file
+  with runtime type identification enabled.  If :option:`-fno-rtti` is
+  used when compiling the file, then this macro is not defined.
+
+.. c:macro:: __USING_SJLJ_EXCEPTIONS__
+
+  This macro is defined, with value 1, if the compiler uses the old
+  mechanism based on ``setjmp`` and ``longjmp`` for exception
+  handling.
+
+.. c:macro:: __GXX_EXPERIMENTAL_CXX0X__
+
+  This macro is defined when compiling a C++ source file with C++11 features
+  enabled, i.e., for all C++ language dialects except :option:`-std=c++98`
+  and :option:`-std=gnu++98`. This macro is obsolete, but can be used to
+  detect experimental C++0x features in very old versions of GCC. Since
+  GCC 4.7.0 the ``__cplusplus`` macro is defined correctly, so most
+  code should test ``__cplusplus >= 201103L`` instead of using this
+  macro.
+
+.. c:macro:: __GXX_WEAK__
+
+  This macro is defined when compiling a C++ source file.  It has the
+  value 1 if the compiler will use weak symbols, COMDAT sections, or
+  other similar techniques to collapse symbols with 'vague linkage'
+  that are defined in multiple translation units.  If the compiler will
+  not collapse such symbols, this macro is defined with value 0.  In
+  general, user code should not need to make use of this macro; the
+  purpose of this macro is to ease implementation of the C++ runtime
+  library provided with G++.
+
+.. c:macro:: __NEXT_RUNTIME__
+
+  This macro is defined, with value 1, if (and only if) the NeXT runtime
+  (as in :option:`-fnext-runtime`) is in use for Objective-C.  If the GNU
+  runtime is used, this macro is not defined, so that you can use this
+  macro to determine which runtime (NeXT or GNU) is being used.
+
+.. c:macro:: __LP64__
+             _LP64
+
+  These macros are defined, with value 1, if (and only if) the compilation
+  is for a target where ``long int`` and pointer both use 64-bits and
+  ``int`` uses 32-bit.
+
+.. c:macro:: __SSP__
+
+  This macro is defined, with value 1, when :option:`-fstack-protector` is in
+  use.
+
+.. c:macro:: __SSP_ALL__
+
+  This macro is defined, with value 2, when :option:`-fstack-protector-all` is
+  in use.
+
+.. c:macro:: __SSP_STRONG__
+
+  This macro is defined, with value 3, when :option:`-fstack-protector-strong` is
+  in use.
+
+.. c:macro:: __SSP_EXPLICIT__
+
+  This macro is defined, with value 4, when :option:`-fstack-protector-explicit` is
+  in use.
+
+``__SANITIZE_ADDRESS__``
+  This macro is defined, with value 1, when :option:`-fsanitize=address`
+  or :option:`-fsanitize=kernel-address` are in use.
+
+``__SANITIZE_THREAD__``
+  This macro is defined, with value 1, when :option:`-fsanitize=thread` is in use.
+
+.. c:macro:: __TIMESTAMP__
+
+  This macro expands to a string constant that describes the date and time
+  of the last modification of the current source file. The string constant
+  contains abbreviated day of the week, month, day of the month, time in
+  hh:mm:ss form, year and looks like ``"Sun Sep 16 01:03:52 1973"``.
+  If the day of the month is less than 10, it is padded with a space on the left.
+
+  If GCC cannot determine the current date, it will emit a warning message
+  (once per compilation) and ``__TIMESTAMP__`` will expand to
+  ``"??? ??? ?? ??:??:?? ????"``.
+
+.. c:macro:: __GCC_HAVE_SYNC_COMPARE_AND_SWAP_1
+             __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2
+             __GCC_HAVE_SYNC_COMPARE_AND_SWAP_4
+             __GCC_HAVE_SYNC_COMPARE_AND_SWAP_8
+             __GCC_HAVE_SYNC_COMPARE_AND_SWAP_16
+
+  These macros are defined when the target processor supports atomic compare
+  and swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively.
+
+.. c:macro:: __HAVE_SPECULATION_SAFE_VALUE
+
+  This macro is defined with the value 1 to show that this version of GCC
+  supports ``__builtin_speculation_safe_value``.
+
+.. c:macro:: __GCC_HAVE_DWARF2_CFI_ASM
+
+  This macro is defined when the compiler is emitting DWARF CFI directives
+  to the assembler.  When this is defined, it is possible to emit those same
+  directives in inline assembly.
+
+.. c:macro:: __FP_FAST_FMA
+             __FP_FAST_FMAF
+             __FP_FAST_FMAL
+
+  These macros are defined with value 1 if the backend supports the
+  ``fma``, ``fmaf``, and ``fmal`` builtin functions, so that
+  the include file :samp:`math.h` can define the macros
+  ``FP_FAST_FMA``, ``FP_FAST_FMAF``, and ``FP_FAST_FMAL``
+  for compatibility with the 1999 C standard.
+
+.. c:macro:: __FP_FAST_FMAF16
+             __FP_FAST_FMAF32
+             __FP_FAST_FMAF64
+             __FP_FAST_FMAF128
+             __FP_FAST_FMAF32X
+             __FP_FAST_FMAF64X
+             __FP_FAST_FMAF128X
+
+  These macros are defined with the value 1 if the backend supports the
+  ``fma`` functions using the additional ``_Floatn`` and
+  ``_Floatnx`` types that are defined in ISO/IEC TS
+  18661-3:2015.  The include file :samp:`math.h` can define the
+  ``FP_FAST_FMAFn`` and ``FP_FAST_FMAFnx`` macros if
+  the user defined ``__STDC_WANT_IEC_60559_TYPES_EXT__`` before
+  including :samp:`math.h`.
+
+.. c:macro:: __GCC_IEC_559
+
+  This macro is defined to indicate the intended level of support for
+  IEEE 754 (IEC 60559) floating-point arithmetic.  It expands to a
+  nonnegative integer value.  If 0, it indicates that the combination of
+  the compiler configuration and the command-line options is not
+  intended to support IEEE 754 arithmetic for ``float`` and
+  ``double`` as defined in C99 and C11 Annex F (for example, that the
+  standard rounding modes and exceptions are not supported, or that
+  optimizations are enabled that conflict with IEEE 754 semantics).  If
+  1, it indicates that IEEE 754 arithmetic is intended to be supported;
+  this does not mean that all relevant language features are supported
+  by GCC.  If 2 or more, it additionally indicates support for IEEE
+  754-2008 (in particular, that the binary encodings for quiet and
+  signaling NaNs are as specified in IEEE 754-2008).
+
+  This macro does not indicate the default state of command-line options
+  that control optimizations that C99 and C11 permit to be controlled by
+  standard pragmas, where those standards do not require a particular
+  default state.  It does not indicate whether optimizations respect
+  signaling NaN semantics (the macro for that is
+  ``__SUPPORT_SNAN__``).  It does not indicate support for decimal
+  floating point or the IEEE 754 binary16 and binary128 types.
+
+.. c:macro:: __GCC_IEC_559_COMPLEX
+
+  This macro is defined to indicate the intended level of support for
+  IEEE 754 (IEC 60559) floating-point arithmetic for complex numbers, as
+  defined in C99 and C11 Annex G.  It expands to a nonnegative integer
+  value.  If 0, it indicates that the combination of the compiler
+  configuration and the command-line options is not intended to support
+  Annex G requirements (for example, because :option:`-fcx-limited-range`
+  was used).  If 1 or more, it indicates that it is intended to support
+  those requirements; this does not mean that all relevant language
+  features are supported by GCC.
+
+.. c:macro:: __NO_MATH_ERRNO__
+
+  This macro is defined if :option:`-fno-math-errno` is used, or enabled
+  by another option such as :option:`-ffast-math` or by default.
+
+.. c:macro:: __RECIPROCAL_MATH__
+
+  This macro is defined if :option:`-freciprocal-math` is used, or enabled
+  by another option such as :option:`-ffast-math` or by default.
+
+.. c:macro:: __NO_SIGNED_ZEROS__
+
+  This macro is defined if :option:`-fno-signed-zeros` is used, or enabled
+  by another option such as :option:`-ffast-math` or by default.
+
+.. c:macro:: __NO_TRAPPING_MATH__
+
+  This macro is defined if :option:`-fno-trapping-math` is used.
+
+.. c:macro:: __ASSOCIATIVE_MATH__
+
+  This macro is defined if :option:`-fassociative-math` is used, or enabled
+  by another option such as :option:`-ffast-math` or by default.
+
+.. c:macro:: __ROUNDING_MATH__
+
+  This macro is defined if :option:`-frounding-math` is used.
+
+.. c:macro:: __GNUC_EXECUTION_CHARSET_NAME
+             __GNUC_WIDE_EXECUTION_CHARSET_NAME
+
+  These macros are defined to expand to a narrow string literal of
+  the name of the narrow and wide compile-time execution character
+  set used.  It directly reflects the name passed to the options
+  :option:`-fexec-charset` and :option:`-fwide-exec-charset`, or the defaults
+  documented for those options (that is, it can expand to something like
+  ``"UTF-8"``).  See :ref:`invocation`.
+
+.. index:: system-specific predefined macros, predefined macros, system-specific, reserved namespace
+
+.. _system-specific-predefined-macros:
+
+System-specific Predefined Macros
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The C preprocessor normally predefines several macros that indicate what
+type of system and machine is in use.  They are obviously different on
+each target supported by GCC.  This manual, being for all systems and
+machines, cannot tell you what their names are, but you can use
+:command:`cpp -dM` to see them all.  See :ref:`invocation`.  All system-specific
+predefined macros expand to a constant value, so you can test them with
+either :samp:`#ifdef` or :samp:`#if`.
+
+The C standard requires that all system-specific macros be part of the
+:dfn:`reserved namespace`.  All names which begin with two underscores,
+or an underscore and a capital letter, are reserved for the compiler and
+library to use as they wish.  However, historically system-specific
+macros have had names with no special prefix; for instance, it is common
+to find ``unix`` defined on Unix systems.  For all such macros, GCC
+provides a parallel macro with two underscores added at the beginning
+and the end.  If ``unix`` is defined, ``__unix__`` will be defined
+too.  There will never be more than two underscores; the parallel of
+``_mips`` is ``__mips__``.
+
+When the :option:`-ansi` option, or any :option:`-std` option that
+requests strict conformance, is given to the compiler, all the
+system-specific predefined macros outside the reserved namespace are
+suppressed.  The parallel macros, inside the reserved namespace, remain
+defined.
+
+We are slowly phasing out all predefined macros which are outside the
+reserved namespace.  You should never use them in new programs, and we
+encourage you to correct older code to use the parallel macros whenever
+you find it.  We don't recommend you use the system-specific macros that
+are in the reserved namespace, either.  It is better in the long run to
+check specifically for features you need, using a tool such as
+:command:`autoconf`.
+
+.. index:: named operators, C++ named operators, iso646.h
+
+.. _c++-named-operators:
+
+C++ Named Operators
+^^^^^^^^^^^^^^^^^^^
+
+In C++, there are eleven keywords which are simply alternate spellings
+of operators normally written with punctuation.  These keywords are
+treated as such even in the preprocessor.  They function as operators in
+:samp:`#if`, and they cannot be defined as macros or poisoned.  In C, you
+can request that those keywords take their C++ meaning by including
+:samp:`iso646.h`.  That header defines each one as a normal object-like
+macro expanding to the appropriate punctuator.
+
+These are the named operators and their corresponding punctuators:
+
+.. list-table::
+
+   * - Named Operator
+     - Punctuator
+   * - ``and``
+     - ``&&``
+   * - ``and_eq``
+     - ``&=``
+   * - ``bitand``
+     - ``&``
+   * - ``bitor``
+     - ``|``
+   * - ``compl``
+     - ``~``
+   * - ``not``
+     - ``!``
+   * - ``not_eq``
+     - ``!=``
+   * - ``or``
+     - ``||``
+   * - ``or_eq``
+     - ``|=``
+   * - ``xor``
+     - ``^``
+   * - ``xor_eq``
+     - ``^=``

gcc/doc/cpp/macros/stringizing.rst

@@ -0,0 +1,86 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: stringizing, # operator
+
+.. _stringizing:
+
+Stringizing
+***********
+
+Sometimes you may want to convert a macro argument into a string
+constant.  Parameters are not replaced inside string constants, but you
+can use the :samp:`#` preprocessing operator instead.  When a macro
+parameter is used with a leading :samp:`#`, the preprocessor replaces it
+with the literal text of the actual argument, converted to a string
+constant.  Unlike normal parameter replacement, the argument is not
+macro-expanded first.  This is called :dfn:`stringizing`.
+
+There is no way to combine an argument with surrounding text and
+stringize it all together.  Instead, you can write a series of adjacent
+string constants and stringized arguments.  The preprocessor
+replaces the stringized arguments with string constants.  The C
+compiler then combines all the adjacent string constants into one
+long string.
+
+Here is an example of a macro definition that uses stringizing:
+
+.. code-block::
+
+  #define WARN_IF(EXP) \
+  do { if (EXP) \
+          fprintf (stderr, "Warning: " #EXP "\n"); } \
+  while (0)
+  WARN_IF (x == 0);
+       → do { if (x == 0)
+             fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0);
+
+The argument for ``EXP`` is substituted once, as-is, into the
+``if`` statement, and once, stringized, into the argument to
+``fprintf``.  If ``x`` were a macro, it would be expanded in the
+``if`` statement, but not in the string.
+
+The ``do`` and ``while (0)`` are a kludge to make it possible to
+write ``WARN_IF (arg);``, which the resemblance of
+``WARN_IF`` to a function would make C programmers want to do; see
+:ref:`swallowing-the-semicolon`.
+
+Stringizing in C involves more than putting double-quote characters
+around the fragment.  The preprocessor backslash-escapes the quotes
+surrounding embedded string constants, and all backslashes within string and
+character constants, in order to get a valid C string constant with the
+proper contents.  Thus, stringizing ``p = "foo\n";`` results in
+``"p = \"foo\\n\";"``.  However, backslashes that are not inside string
+or character constants are not duplicated: :samp:`\\n` by itself
+stringizes to ``"\n"``.
+
+All leading and trailing whitespace in text being stringized is
+ignored.  Any sequence of whitespace in the middle of the text is
+converted to a single space in the stringized result.  Comments are
+replaced by whitespace long before stringizing happens, so they
+never appear in stringized text.
+
+There is no way to convert a macro argument into a character constant.
+
+If you want to stringize the result of expansion of a macro argument,
+you have to use two levels of macros.
+
+.. code-block::
+
+  #define xstr(s) str(s)
+  #define str(s) #s
+  #define foo 4
+  str (foo)
+       → "foo"
+  xstr (foo)
+       → xstr (4)
+       → str (4)
+       → "4"
+
+``s`` is stringized when it is used in ``str``, so it is not
+macro-expanded first.  But ``s`` is an ordinary argument to
+``xstr``, so it is completely macro-expanded before ``xstr``
+itself is expanded (see :ref:`argument-prescan`).  Therefore, by the time
+``str`` gets to its argument, it has already been macro-expanded.

gcc/doc/cpp/macros/undefining-and-redefining-macros.rst

@@ -0,0 +1,67 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: undefining macros, redefining macros, #undef
+
+.. _undefining-and-redefining-macros:
+
+Undefining and Redefining Macros
+********************************
+
+If a macro ceases to be useful, it may be :dfn:`undefined` with the
+:samp:`#undef` directive.  :samp:`#undef` takes a single argument, the
+name of the macro to undefine.  You use the bare macro name, even if the
+macro is function-like.  It is an error if anything appears on the line
+after the macro name.  :samp:`#undef` has no effect if the name is not a
+macro.
+
+.. code-block::
+
+  #define FOO 4
+  x = FOO;        → x = 4;
+  #undef FOO
+  x = FOO;        → x = FOO;
+
+Once a macro has been undefined, that identifier may be :dfn:`redefined`
+as a macro by a subsequent :samp:`#define` directive.  The new definition
+need not have any resemblance to the old definition.
+
+However, if an identifier which is currently a macro is redefined, then
+the new definition must be :dfn:`effectively the same` as the old one.
+Two macro definitions are effectively the same if:
+
+* Both are the same type of macro (object- or function-like).
+
+* All the tokens of the replacement list are the same.
+
+* If there are any parameters, they are the same.
+
+* Whitespace appears in the same places in both.  It need not be
+  exactly the same amount of whitespace, though.  Remember that comments
+  count as whitespace.
+
+These definitions are effectively the same:
+
+.. code-block:: c++
+
+  #define FOUR (2 + 2)
+  #define FOUR         (2    +    2)
+  #define FOUR (2 /* two */ + 2)
+
+but these are not:
+
+.. code-block:: c++
+
+  #define FOUR (2 + 2)
+  #define FOUR ( 2+2 )
+  #define FOUR (2 * 2)
+  #define FOUR(score,and,seven,years,ago) (2 + 2)
+
+If a macro is redefined with a definition that is not effectively the
+same as the old one, the preprocessor issues a warning and changes the
+macro to use the new definition.  If the new definition is effectively
+the same, the redefinition is silently ignored.  This allows, for
+instance, two different headers to define a common macro.  The
+preprocessor will only complain if the definitions do not match.

gcc/doc/cpp/macros/variadic-macros.rst

@@ -0,0 +1,141 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: variable number of arguments, macros with variable arguments, variadic macros
+
+.. _variadic-macros:
+
+Variadic Macros
+***************
+
+A macro can be declared to accept a variable number of arguments much as
+a function can.  The syntax for defining the macro is similar to that of
+a function.  Here is an example:
+
+.. code-block:: c++
+
+  #define eprintf(...) fprintf (stderr, __VA_ARGS__)
+
+This kind of macro is called :dfn:`variadic`.  When the macro is invoked,
+all the tokens in its argument list after the last named argument (this
+macro has none), including any commas, become the :dfn:`variable
+argument`.  This sequence of tokens replaces the identifier
+``__VA_ARGS__`` in the macro body wherever it appears.  Thus, we
+have this expansion:
+
+.. code-block::
+
+  eprintf ("%s:%d: ", input_file, lineno)
+       →  fprintf (stderr, "%s:%d: ", input_file, lineno)
+
+The variable argument is completely macro-expanded before it is inserted
+into the macro expansion, just like an ordinary argument.  You may use
+the :samp:`#` and :samp:`##` operators to stringize the variable argument
+or to paste its leading or trailing token with another token.  (But see
+below for an important special case for :samp:`##`.)
+
+If your macro is complicated, you may want a more descriptive name for
+the variable argument than ``__VA_ARGS__``.  CPP permits
+this, as an extension.  You may write an argument name immediately
+before the :samp:`...`; that name is used for the variable argument.
+The ``eprintf`` macro above could be written
+
+.. code-block:: c++
+
+  #define eprintf(args...) fprintf (stderr, args)
+
+using this extension.  You cannot use ``__VA_ARGS__`` and this
+extension in the same macro.
+
+You can have named arguments as well as variable arguments in a variadic
+macro.  We could define ``eprintf`` like this, instead:
+
+.. code-block:: c++
+
+  #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
+
+This formulation looks more descriptive, but historically it was less
+flexible: you had to supply at least one argument after the format
+string.  In standard C, you could not omit the comma separating the
+named argument from the variable arguments.  (Note that this
+restriction has been lifted in C++20, and never existed in GNU C; see
+below.)
+
+Furthermore, if you left the variable argument empty, you would have
+gotten a syntax error, because there would have been an extra comma
+after the format string.
+
+.. code-block::
+
+  eprintf("success!\n", );
+       → fprintf(stderr, "success!\n", );
+
+This has been fixed in C++20, and GNU CPP also has a pair of
+extensions which deal with this problem.
+
+First, in GNU CPP, and in C++ beginning in C++20, you are allowed to
+leave the variable argument out entirely:
+
+.. code-block::
+
+  eprintf ("success!\n")
+       → fprintf(stderr, "success!\n", );
+
+Second, C++20 introduces the ``__VA_OPT__`` function macro.
+This macro may only appear in the definition of a variadic macro.  If
+the variable argument has any tokens, then a ``__VA_OPT__``
+invocation expands to its argument; but if the variable argument does
+not have any tokens, the ``__VA_OPT__`` expands to nothing:
+
+.. code-block:: c++
+
+  #define eprintf(format, ...) \
+    fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__)
+
+``__VA_OPT__`` is also available in GNU C and GNU C++.
+
+Historically, GNU CPP has also had another extension to handle the
+trailing comma: the :samp:`##` token paste operator has a special
+meaning when placed between a comma and a variable argument.  Despite
+the introduction of ``__VA_OPT__``, this extension remains
+supported in GNU CPP, for backward compatibility.  If you write
+
+.. code-block:: c++
+
+  #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
+
+and the variable argument is left out when the ``eprintf`` macro is
+used, then the comma before the :samp:`##` will be deleted.  This does
+*not* happen if you pass an empty argument, nor does it happen if
+the token preceding :samp:`##` is anything other than a comma.
+
+.. code-block::
+
+  eprintf ("success!\n")
+       → fprintf(stderr, "success!\n");
+
+The above explanation is ambiguous about the case where the only macro
+parameter is a variable arguments parameter, as it is meaningless to
+try to distinguish whether no argument at all is an empty argument or
+a missing argument.
+CPP retains the comma when conforming to a specific C
+standard.  Otherwise the comma is dropped as an extension to the standard.
+
+The C standard
+mandates that the only place the identifier ``__VA_ARGS__``
+can appear is in the replacement list of a variadic macro.  It may not
+be used as a macro name, macro argument name, or within a different type
+of macro.  It may also be forbidden in open text; the standard is
+ambiguous.  We recommend you avoid using it except for its defined
+purpose.
+
+Likewise, C++ forbids ``__VA_OPT__`` anywhere outside the
+replacement list of a variadic macro.
+
+Variadic macros became a standard part of the C language with C99.
+GNU CPP previously supported them
+with a named variable argument
+(:samp:`args...`, not :samp:`...` and ``__VA_ARGS__``), which
+is still supported for backward compatibility.

gcc/doc/cpp/obsolete-features.rst

@@ -0,0 +1,98 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _obsolete-features:
+
+Obsolete Features
+*****************
+
+CPP has some features which are present mainly for compatibility with
+older programs.  We discourage their use in new code.  In some cases,
+we plan to remove the feature in a future version of GCC.
+
+.. index:: assertions
+
+Assertions
+^^^^^^^^^^
+
+:dfn:`Assertions` are a deprecated alternative to macros in writing
+conditionals to test what sort of computer or system the compiled
+program will run on.  Assertions are usually predefined, but you can
+define them with preprocessing directives or command-line options.
+
+Assertions were intended to provide a more systematic way to describe
+the compiler's target system and we added them for compatibility with
+existing compilers.  In practice they are just as unpredictable as the
+system-specific predefined macros.  In addition, they are not part of
+any standard, and only a few compilers support them.
+Therefore, the use of assertions is **less** portable than the use
+of system-specific predefined macros.  We recommend you do not use them at
+all.
+
+.. index:: predicates
+
+An assertion looks like this:
+
+.. code-block:: c++
+
+  #predicate (answer)
+
+:samp:`{predicate}` must be a single identifier.  :samp:`{answer}` can be any
+sequence of tokens; all characters are significant except for leading
+and trailing whitespace, and differences in internal whitespace
+sequences are ignored.  (This is similar to the rules governing macro
+redefinition.)  Thus, ``(x + y)`` is different from ``(x+y)`` but
+equivalent to ``( x + y )``.  Parentheses do not nest inside an
+answer.
+
+.. index:: testing predicates
+
+To test an assertion, you write it in an :samp:`#if`.  For example, this
+conditional succeeds if either ``vax`` or ``ns16000`` has been
+asserted as an answer for ``machine``.
+
+.. code-block:: c++
+
+  #if #machine (vax) || #machine (ns16000)
+
+You can test whether *any* answer is asserted for a predicate by
+omitting the answer in the conditional:
+
+.. code-block:: c++
+
+  #if #machine
+
+.. index:: #assert
+
+Assertions are made with the :samp:`#assert` directive.  Its sole
+argument is the assertion to make, without the leading :samp:`#` that
+identifies assertions in conditionals.
+
+.. code-block:: c++
+
+  #assert predicate (answer)
+
+You may make several assertions with the same predicate and different
+answers.  Subsequent assertions do not override previous ones for the
+same predicate.  All the answers for any given predicate are
+simultaneously true.
+
+.. index:: assertions, canceling, #unassert
+
+Assertions can be canceled with the :samp:`#unassert` directive.  It
+has the same syntax as :samp:`#assert`.  In that form it cancels only the
+answer which was specified on the :samp:`#unassert` line; other answers
+for that predicate remain true.  You can cancel an entire predicate by
+leaving out the answer:
+
+.. code-block:: c++
+
+  #unassert predicate
+
+In either form, if no such assertion has been made, :samp:`#unassert` has
+no effect.
+
+You can also make or cancel assertions using command-line options.
+See :ref:`invocation`.

gcc/doc/cpp/other-directives.rst

@@ -0,0 +1,30 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: #ident, #sccs
+
+.. _other-directives:
+
+Other Directives
+----------------
+
+The :samp:`#ident` directive takes one argument, a string constant.  On
+some systems, that string constant is copied into a special segment of
+the object file.  On other systems, the directive is ignored.  The
+:samp:`#sccs` directive is a synonym for :samp:`#ident`.
+
+These directives are not part of the C standard, but they are not
+official GNU extensions either.  What historical information we have
+been able to find, suggests they originated with System V.
+
+.. index:: null directive
+
+The :dfn:`null directive` consists of a :samp:`#` followed by a newline,
+with only whitespace (including comments) in between.  A null directive
+is understood as a preprocessing directive but has no effect on the
+preprocessor output.  The primary significance of the existence of the
+null directive is that an input line consisting of just a :samp:`#` will
+produce no output, rather than a line of output containing just a
+:samp:`#`.  Supposedly some old C programs contain such lines.

gcc/doc/cpp/overview.rst

@@ -0,0 +1,67 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _top:
+
+.. _overview:
+
+Overview
+--------
+
+The C preprocessor, often known as :dfn:`cpp`, is a :dfn:`macro processor`
+that is used automatically by the C compiler to transform your program
+before compilation.  It is called a macro processor because it allows
+you to define :dfn:`macros`, which are brief abbreviations for longer
+constructs.
+
+The C preprocessor is intended to be used only with C, C++, and
+Objective-C source code.  In the past, it has been abused as a general
+text processor.  It will choke on input which does not obey C's lexical
+rules.  For example, apostrophes will be interpreted as the beginning of
+character constants, and cause errors.  Also, you cannot rely on it
+preserving characteristics of the input which are not significant to
+C-family languages.  If a Makefile is preprocessed, all the hard tabs
+will be removed, and the Makefile will not work.
+
+Having said that, you can often get away with using cpp on things which
+are not C.  Other Algol-ish programming languages are often safe
+(Ada, etc.) So is assembly, with caution.  :option:`-traditional-cpp`
+mode preserves more white space, and is otherwise more permissive.  Many
+of the problems can be avoided by writing C or C++ style comments
+instead of native language comments, and keeping macros simple.
+
+Wherever possible, you should use a preprocessor geared to the language
+you are writing in.  Modern versions of the GNU assembler have macro
+facilities.  Most high level programming languages have their own
+conditional compilation and inclusion mechanism.  If all else fails,
+try a true general text processor, such as GNU M4.
+
+C preprocessors vary in some details.  This manual discusses the GNU C
+preprocessor, which provides a small superset of the features of ISO
+Standard C.  In its default mode, the GNU C preprocessor does not do a
+few things required by the standard.  These are features which are
+rarely, if ever, used, and may cause surprising changes to the meaning
+of a program which does not expect them.  To get strict ISO Standard C,
+you should use the :option:`-std=c90`, :option:`-std=c99`,
+:option:`-std=c11` or :option:`-std=c17` options, depending
+on which version of the standard you want.  To get all the mandatory
+diagnostics, you must also use :option:`-pedantic`.  See :ref:`invocation`.
+
+This manual describes the behavior of the ISO preprocessor.  To
+minimize gratuitous differences, where the ISO preprocessor's
+behavior does not conflict with traditional semantics, the
+traditional preprocessor should behave the same way.  The various
+differences that do exist are detailed in the section :ref:`traditional-mode`.
+
+For clarity, unless noted otherwise, references to :samp:`CPP` in this
+manual refer to GNU CPP.
+
+.. toctree::
+  :maxdepth: 2
+
+  character-sets
+  initial-processing
+  tokenization
+  the-preprocessing-language

gcc/doc/cpp/pragmas.rst

@@ -0,0 +1,121 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: pragma directive
+
+.. _pragmas:
+
+Pragmas
+-------
+
+The :samp:`#pragma` directive is the method specified by the C standard
+for providing additional information to the compiler, beyond what is
+conveyed in the language itself.  The forms of this directive
+(commonly known as :dfn:`pragmas`) specified by C standard are prefixed with
+``STDC``.  A C compiler is free to attach any meaning it likes to other
+pragmas.  Most GNU-defined, supported pragmas have been given a
+``GCC`` prefix.
+
+.. index:: _Pragma
+
+C99 introduced the ``_Pragma`` operator.  This feature addresses a
+major problem with :samp:`#pragma`: being a directive, it cannot be
+produced as the result of macro expansion.  ``_Pragma`` is an
+operator, much like ``sizeof`` or ``defined``, and can be embedded
+in a macro.
+
+Its syntax is ``_Pragma (string-literal)``, where
+:samp:`{string-literal}` can be either a normal or wide-character string
+literal.  It is destringized, by replacing all :samp:`\\\\` with a single
+:samp:`\\` and all :samp:`\\"` with a :samp:`"`.  The result is then
+processed as if it had appeared as the right hand side of a
+:samp:`#pragma` directive.  For example,
+
+.. code-block:: c++
+
+  _Pragma ("GCC dependency \"parse.y\"")
+
+has the same effect as ``#pragma GCC dependency "parse.y"``.  The
+same effect could be achieved using macros, for example
+
+.. code-block:: c++
+
+  #define DO_PRAGMA(x) _Pragma (#x)
+  DO_PRAGMA (GCC dependency "parse.y")
+
+The standard is unclear on where a ``_Pragma`` operator can appear.
+The preprocessor does not accept it within a preprocessing conditional
+directive like :samp:`#if`.  To be safe, you are probably best keeping it
+out of directives other than :samp:`#define`, and putting it on a line of
+its own.
+
+This manual documents the pragmas which are meaningful to the
+preprocessor itself.  Other pragmas are meaningful to the C or C++
+compilers.  They are documented in the GCC manual.
+
+GCC plugins may provide their own pragmas.
+
+``#pragma GCC dependency``
+  ``#pragma GCC dependency`` allows you to check the relative dates of
+  the current file and another file.  If the other file is more recent than
+  the current file, a warning is issued.  This is useful if the current
+  file is derived from the other file, and should be regenerated.  The
+  other file is searched for using the normal include search path.
+  Optional trailing text can be used to give more information in the
+  warning message.
+
+  .. code-block:: c++
+
+    #pragma GCC dependency "parse.y"
+    #pragma GCC dependency "/usr/include/time.h" rerun fixincludes
+
+``#pragma GCC poison``
+  Sometimes, there is an identifier that you want to remove completely
+  from your program, and make sure that it never creeps back in.  To
+  enforce this, you can :dfn:`poison` the identifier with this pragma.
+  ``#pragma GCC poison`` is followed by a list of identifiers to
+  poison.  If any of those identifiers appears anywhere in the source
+  after the directive, it is a hard error.  For example,
+
+  .. code-block:: c++
+
+    #pragma GCC poison printf sprintf fprintf
+    sprintf(some_string, "hello");
+
+  will produce an error.
+
+  If a poisoned identifier appears as part of the expansion of a macro
+  which was defined before the identifier was poisoned, it will *not*
+  cause an error.  This lets you poison an identifier without worrying
+  about system headers defining macros that use it.
+
+  For example,
+
+  .. code-block:: c++
+
+    #define strrchr rindex
+    #pragma GCC poison rindex
+    strrchr(some_string, 'h');
+
+  will not produce an error.
+
+``#pragma GCC system_header``
+  This pragma takes no arguments.  It causes the rest of the code in the
+  current file to be treated as if it came from a system header.
+  See :ref:`system-headers`.
+
+``#pragma GCC warning``, ``#pragma GCC error``
+  ``#pragma GCC warning "message"`` causes the preprocessor to issue
+  a warning diagnostic with the text :samp:`message`.  The message
+  contained in the pragma must be a single string literal.  Similarly,
+  ``#pragma GCC error "message"`` issues an error message.  Unlike
+  the :samp:`#warning` and :samp:`#error` directives, these pragmas can be
+  embedded in preprocessor macros using :samp:`_Pragma`.
+
+``#pragma once``
+  If ``#pragma once`` is seen when scanning a header file, that
+  file will never be read again, no matter what.  It is a less-portable
+  alternative to using :samp:`#ifndef` to guard the contents of header files
+  against multiple inclusions.

gcc/doc/cpp/preprocessor-output.rst

@@ -0,0 +1,86 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _preprocessor-output:
+
+Preprocessor Output
+-------------------
+
+When the C preprocessor is used with the C, C++, or Objective-C
+compilers, it is integrated into the compiler and communicates a stream
+of binary tokens directly to the compiler's parser.  However, it can
+also be used in the more conventional standalone mode, where it produces
+textual output.
+
+.. todo:: Document the library interface.
+
+.. index:: output format
+
+The output from the C preprocessor looks much like the input, except
+that all preprocessing directive lines have been replaced with blank
+lines and all comments with spaces.  Long runs of blank lines are
+discarded.
+
+The ISO standard specifies that it is implementation defined whether a
+preprocessor preserves whitespace between tokens, or replaces it with
+e.g. a single space.  In GNU CPP, whitespace between tokens is collapsed
+to become a single space, with the exception that the first token on a
+non-directive line is preceded with sufficient spaces that it appears in
+the same column in the preprocessed output that it appeared in the
+original source file.  This is so the output is easy to read.
+CPP does not insert any
+whitespace where there was none in the original source, except where
+necessary to prevent an accidental token paste.
+
+.. index:: linemarkers
+
+Source file name and line number information is conveyed by lines
+of the form
+
+.. code-block:: c++
+
+  # linenum filename flags
+
+These are called :dfn:`linemarkers`.  They are inserted as needed into
+the output (but never within a string or character constant).  They mean
+that the following line originated in file :samp:`{filename}` at line
+:samp:`{linenum}`.  :samp:`{filename}` will never contain any non-printing
+characters; they are replaced with octal escape sequences.
+
+After the file name comes zero or more flags, which are :samp:`1`,
+:samp:`2`, :samp:`3`, or :samp:`4`.  If there are multiple flags, spaces
+separate them.  Here is what the flags mean:
+
+:samp:`1`
+  This indicates the start of a new file.
+
+:samp:`2`
+  This indicates returning to a file (after having included another file).
+
+:samp:`3`
+  This indicates that the following text comes from a system header file,
+  so certain warnings should be suppressed.
+
+:samp:`4`
+  This indicates that the following text should be treated as being
+  wrapped in an implicit ``extern "C"`` block.
+
+  .. maybe cross reference SYSTEM_IMPLICIT_EXTERN_C
+
+As an extension, the preprocessor accepts linemarkers in non-assembler
+input files.  They are treated like the corresponding :samp:`#line`
+directive, (see :ref:`line-control`), except that trailing flags are
+permitted, and are interpreted with the meanings described above.  If
+multiple flags are given, they must be in ascending order.
+
+Some directives may be duplicated in the output of the preprocessor.
+These are :samp:`#ident` (always), :samp:`#pragma` (only if the
+preprocessor does not handle the pragma itself), and :samp:`#define` and
+:samp:`#undef` (with certain debugging options).  If this happens, the
+:samp:`#` of the directive will always be in the first column, and there
+will be no space between the :samp:`#` and the directive name.  If macro
+expansion happens to generate tokens which might be mistaken for a
+duplicated directive, a space will be inserted between the :samp:`#` and
+the directive name.

gcc/doc/cpp/the-preprocessing-language.rst

@@ -0,0 +1,69 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: directives, preprocessing directives, directive line, directive name
+
+.. _the-preprocessing-language:
+
+The preprocessing language
+**************************
+
+After tokenization, the stream of tokens may simply be passed straight
+to the compiler's parser.  However, if it contains any operations in the
+:dfn:`preprocessing language`, it will be transformed first.  This stage
+corresponds roughly to the standard's 'translation phase 4' and is
+what most people think of as the preprocessor's job.
+
+The preprocessing language consists of :dfn:`directives` to be executed
+and :dfn:`macros` to be expanded.  Its primary capabilities are:
+
+* Inclusion of header files.  These are files of declarations that can be
+  substituted into your program.
+
+* Macro expansion.  You can define :dfn:`macros`, which are abbreviations
+  for arbitrary fragments of C code.  The preprocessor will replace the
+  macros with their definitions throughout the program.  Some macros are
+  automatically defined for you.
+
+* Conditional compilation.  You can include or exclude parts of the
+  program according to various conditions.
+
+* 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 where each source line originally came
+  from.
+
+* Diagnostics.  You can detect problems at compile time and issue errors
+  or warnings.
+
+There are a few more, less useful, features.
+
+Except for expansion of predefined macros, all these operations are
+triggered with :dfn:`preprocessing directives`.  Preprocessing directives
+are lines in your program that start with :samp:`#`.  Whitespace is
+allowed before and after the :samp:`#`.  The :samp:`#` is followed by an
+identifier, the :dfn:`directive name`.  It specifies the operation to
+perform.  Directives are commonly referred to as :samp:`#{name}`
+where :samp:`{name}` is the directive name.  For example, :samp:`#define` is
+the directive that defines a macro.
+
+The :samp:`#` which begins a directive cannot come from a macro
+expansion.  Also, the directive name is not macro expanded.  Thus, if
+``foo`` is defined as a macro expanding to ``define``, that does
+not make :samp:`#foo` a valid preprocessing directive.
+
+The set of valid directive names is fixed.  Programs cannot define new
+preprocessing directives.
+
+Some directives require arguments; these make up the rest of the
+directive line and must be separated from the directive name by
+whitespace.  For example, :samp:`#define` must be followed by a macro
+name and the intended expansion of the macro.
+
+A preprocessing directive cannot cover more than one line.  The line
+may, however, be continued with backslash-newline, or by a block comment
+which extends past the end of the line.  In either case, when the
+directive is processed, the continuations have already been merged with
+the first line to make one long line.

gcc/doc/cpp/tokenization.rst

@@ -0,0 +1,168 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: tokens, preprocessing tokens
+
+.. _tokenization:
+
+Tokenization
+************
+
+After the textual transformations are finished, the input file is
+converted into a sequence of :dfn:`preprocessing tokens`.  These mostly
+correspond to the syntactic tokens used by the C compiler, but there are
+a few differences.  White space separates tokens; it is not itself a
+token of any kind.  Tokens do not have to be separated by white space,
+but it is often necessary to avoid ambiguities.
+
+When faced with a sequence of characters that has more than one possible
+tokenization, the preprocessor is greedy.  It always makes each token,
+starting from the left, as big as possible before moving on to the next
+token.  For instance, ``a+++++b`` is interpreted as
+``a ++ ++ + b``, not as ``a ++ + ++ b``, even though the
+latter tokenization could be part of a valid C program and the former
+could not.
+
+Once the input file is broken into tokens, the token boundaries never
+change, except when the :samp:`##` preprocessing operator is used to paste
+tokens together.  See :ref:`concatenation`.  For example,
+
+.. code-block::
+
+  #define foo() bar
+  foo()baz
+       → bar baz
+  not
+       → barbaz
+
+The compiler does not re-tokenize the preprocessor's output.  Each
+preprocessing token becomes one compiler token.
+
+.. index:: identifiers
+
+Preprocessing tokens fall into five broad classes: identifiers,
+preprocessing numbers, string literals, punctuators, and other.  An
+:dfn:`identifier` is the same as an identifier in C: any sequence of
+letters, digits, or underscores, which begins with a letter or
+underscore.  Keywords of C have no significance to the preprocessor;
+they are ordinary identifiers.  You can define a macro whose name is a
+keyword, for instance.  The only identifier which can be considered a
+preprocessing keyword is ``defined``.  See :ref:`defined`.
+
+This is mostly true of other languages which use the C preprocessor.
+However, a few of the keywords of C++ are significant even in the
+preprocessor.  See :ref:`c++-named-operators`.
+
+In the 1999 C standard, identifiers may contain letters which are not
+part of the 'basic source character set', at the implementation's
+discretion (such as accented Latin letters, Greek letters, or Chinese
+ideograms).  This may be done with an extended character set, or the
+:samp:`\\u` and :samp:`\\U` escape sequences.
+
+As an extension, GCC treats :samp:`$` as a letter.  This is for
+compatibility with some systems, such as VMS, where :samp:`$` is commonly
+used in system-defined function and object names.  :samp:`$` is not a
+letter in strictly conforming mode, or if you specify the :option:`-$`
+option.  See :ref:`invocation`.
+
+.. index:: numbers, preprocessing numbers
+
+A :dfn:`preprocessing number` has a rather bizarre definition.  The
+category includes all the normal integer and floating point constants
+one expects of C, but also a number of other things one might not
+initially recognize as a number.  Formally, preprocessing numbers begin
+with an optional period, a required decimal digit, and then continue
+with any sequence of letters, digits, underscores, periods, and
+exponents.  Exponents are the two-character sequences :samp:`e+`,
+:samp:`e-`, :samp:`E+`, :samp:`E-`, :samp:`p+`, :samp:`p-`, :samp:`P+`, and
+:samp:`P-`.  (The exponents that begin with :samp:`p` or :samp:`P` are
+used for hexadecimal floating-point constants.)
+
+The purpose of this unusual definition is to isolate the preprocessor
+from the full complexity of numeric constants.  It does not have to
+distinguish between lexically valid and invalid floating-point numbers,
+which is complicated.  The definition also permits you to split an
+identifier at any position and get exactly two tokens, which can then be
+pasted back together with the :samp:`##` operator.
+
+It's possible for preprocessing numbers to cause programs to be
+misinterpreted.  For example, ``0xE+12`` is a preprocessing number
+which does not translate to any valid numeric constant, therefore a
+syntax error.  It does not mean ``0xE + 12``, which is what you
+might have intended.
+
+.. index:: string literals, string constants, character constants, header file names
+
+.. the @: prevents makeinfo from turning '' into ".
+
+:dfn:`String literals` are string constants, character constants, and
+header file names (the argument of :samp:`#include`) [#f1]_.
+
+String constants and character
+constants are straightforward: ``"..."`` or ``'...'``.  In
+either case embedded quotes should be escaped with a backslash:
+``'\''`` is the character constant for :samp:`'`.  There is no limit on
+the length of a character constant, but the value of a character
+constant that contains more than one character is
+implementation-defined.  See :ref:`implementation-details`.
+
+Header file names either look like string constants, ``"..."``, or are
+written with angle brackets instead, ``<...>``.  In either case,
+backslash is an ordinary character.  There is no way to escape the
+closing quote or angle bracket.  The preprocessor looks for the header
+file in different places depending on which form you use.  See :ref:`include-operation`.
+
+No string literal may extend past the end of a line.  You may use continued
+lines instead, or string constant concatenation.
+
+.. index:: punctuators, digraphs, alternative tokens
+
+:dfn:`Punctuators` are all the usual bits of punctuation which are
+meaningful to C and C++.  All but three of the punctuation characters in
+ASCII are C punctuators.  The exceptions are :samp:`@`, :samp:`$`, and
+:samp:`\``.  In addition, all the two- and three-character operators are
+punctuators.  There are also six :dfn:`digraphs`, which the C++ standard
+calls :dfn:`alternative tokens`, which are merely alternate ways to spell
+other punctuators.  This is a second attempt to work around missing
+punctuation in obsolete systems.  It has no negative side effects,
+unlike trigraphs, but does not cover as much ground.  The digraphs and
+their corresponding normal punctuators are:
+
+.. code-block::
+
+  Digraph:        <%  %>  <:  :>  %:  %:%:
+  Punctuator:      {   }   [   ]   #    ##
+
+.. index:: other tokens
+
+Any other single byte is considered 'other' and passed on to the
+preprocessor's output unchanged.  The C compiler will almost certainly
+reject source code containing 'other' tokens.  In ASCII, the only
+'other' characters are :samp:`@`, :samp:`$`, :samp:`\``, and control
+characters other than NUL (all bits zero).  (Note that :samp:`$` is
+normally considered a letter.)  All bytes with the high bit set
+(numeric range 0x7F--0xFF) that were not succesfully interpreted as
+part of an extended character in the input encoding are also 'other'
+in the present implementation.
+
+NUL is a special case because of the high probability that its
+appearance is accidental, and because it may be invisible to the user
+(many terminals do not display NUL at all).  Within comments, NULs are
+silently ignored, just as any other character would be.  In running
+text, NUL is considered white space.  For example, these two directives
+have the same meaning.
+
+.. code-block:: c++
+
+  #define X^@1
+  #define X 1
+
+(where :samp:`^@` is ASCII NUL).  Within string or character constants,
+NULs are preserved.  In the latter two cases the preprocessor emits a
+warning message.
+
+.. [#f1] The C
+  standard uses the term :dfn:`string literal` to refer only to what we are
+  calling :dfn:`string constants`.

gcc/doc/cpp/traditional-lexical-analysis.rst

@@ -0,0 +1,74 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _traditional-lexical-analysis:
+
+Traditional lexical analysis
+****************************
+
+The traditional preprocessor does not decompose its input into tokens
+the same way a standards-conforming preprocessor does.  The input is
+simply treated as a stream of text with minimal internal form.
+
+This implementation does not treat trigraphs (see :ref:`trigraphs`)
+specially since they were an invention of the standards committee.  It
+handles arbitrarily-positioned escaped newlines properly and splices
+the lines as you would expect; many traditional preprocessors did not
+do this.
+
+The form of horizontal whitespace in the input file is preserved in
+the output.  In particular, hard tabs remain hard tabs.  This can be
+useful if, for example, you are preprocessing a Makefile.
+
+Traditional CPP only recognizes C-style block comments, and treats the
+:samp:`/*` sequence as introducing a comment only if it lies outside
+quoted text.  Quoted text is introduced by the usual single and double
+quotes, and also by an initial :samp:`<` in a ``#include``
+directive.
+
+Traditionally, comments are completely removed and are not replaced
+with a space.  Since a traditional compiler does its own tokenization
+of the output of the preprocessor, this means that comments can
+effectively be used as token paste operators.  However, comments
+behave like separators for text handled by the preprocessor itself,
+since it doesn't re-lex its input.  For example, in
+
+.. code-block:: c++
+
+  #if foo/**/bar
+
+:samp:`foo` and :samp:`bar` are distinct identifiers and expanded
+separately if they happen to be macros.  In other words, this
+directive is equivalent to
+
+.. code-block:: c++
+
+  #if foo bar
+
+rather than
+
+.. code-block:: c++
+
+  #if foobar
+
+Generally speaking, in traditional mode an opening quote need not have
+a matching closing quote.  In particular, a macro may be defined with
+replacement text that contains an unmatched quote.  Of course, if you
+attempt to compile preprocessed output containing an unmatched quote
+you will get a syntax error.
+
+However, all preprocessing directives other than ``#define``
+require matching quotes.  For example:
+
+.. code-block:: c++
+
+  #define m This macro's fine and has an unmatched quote
+  "/* This is not a comment.  */
+  /* This is a comment.  The following #include directive
+     is ill-formed.  */
+  #include <stdio.h
+
+Just as for the ISO preprocessor, what would be a closing quote can be
+escaped with a backslash to prevent the quoted text from closing.

gcc/doc/cpp/traditional-macros.rst

@@ -0,0 +1,99 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _traditional-macros:
+
+Traditional macros
+******************
+
+The major difference between traditional and ISO macros is that the
+former expand to text rather than to a token sequence.  CPP removes
+all leading and trailing horizontal whitespace from a macro's
+replacement text before storing it, but preserves the form of internal
+whitespace.
+
+One consequence is that it is legitimate for the replacement text to
+contain an unmatched quote (see :ref:`traditional-lexical-analysis`).  An
+unclosed string or character constant continues into the text
+following the macro call.  Similarly, the text at the end of a macro's
+expansion can run together with the text after the macro invocation to
+produce a single token.
+
+Normally comments are removed from the replacement text after the
+macro is expanded, but if the :option:`-CC` option is passed on the
+command-line comments are preserved.  (In fact, the current
+implementation removes comments even before saving the macro
+replacement text, but it careful to do it in such a way that the
+observed effect is identical even in the function-like macro case.)
+
+The ISO stringizing operator :samp:`#` and token paste operator
+:samp:`##` have no special meaning.  As explained later, an effect
+similar to these operators can be obtained in a different way.  Macro
+names that are embedded in quotes, either from the main file or after
+macro replacement, do not expand.
+
+CPP replaces an unquoted object-like macro name with its replacement
+text, and then rescans it for further macros to replace.  Unlike
+standard macro expansion, traditional macro expansion has no provision
+to prevent recursion.  If an object-like macro appears unquoted in its
+replacement text, it will be replaced again during the rescan pass,
+and so on *ad infinitum*.  GCC detects when it is expanding
+recursive macros, emits an error message, and continues after the
+offending macro invocation.
+
+.. code-block::
+
+  #define PLUS +
+  #define INC(x) PLUS+x
+  INC(foo);
+       → ++foo;
+
+Function-like macros are similar in form but quite different in
+behavior to their ISO counterparts.  Their arguments are contained
+within parentheses, are comma-separated, and can cross physical lines.
+Commas within nested parentheses are not treated as argument
+separators.  Similarly, a quote in an argument cannot be left
+unclosed; a following comma or parenthesis that comes before the
+closing quote is treated like any other character.  There is no
+facility for handling variadic macros.
+
+This implementation removes all comments from macro arguments, unless
+the :option:`-C` option is given.  The form of all other horizontal
+whitespace in arguments is preserved, including leading and trailing
+whitespace.  In particular
+
+.. code-block:: c++
+
+  f( )
+
+is treated as an invocation of the macro :samp:`f` with a single
+argument consisting of a single space.  If you want to invoke a
+function-like macro that takes no arguments, you must not leave any
+whitespace between the parentheses.
+
+If a macro argument crosses a new line, the new line is replaced with
+a space when forming the argument.  If the previous line contained an
+unterminated quote, the following line inherits the quoted state.
+
+Traditional preprocessors replace parameters in the replacement text
+with their arguments regardless of whether the parameters are within
+quotes or not.  This provides a way to stringize arguments.  For
+example
+
+.. code-block::
+
+  #define str(x) "x"
+  str(/* A comment */some text )
+       → "some text "
+
+Note that the comment is removed, but that the trailing space is
+preserved.  Here is an example of using a comment to effect token
+pasting.
+
+.. code-block::
+
+  #define suffix(x) foo_/**/x
+  suffix(bar)
+       → foo_bar

gcc/doc/cpp/traditional-miscellany.rst

@@ -0,0 +1,30 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _traditional-miscellany:
+
+Traditional miscellany
+**********************
+
+Here are some things to be aware of when using the traditional
+preprocessor.
+
+* Preprocessing directives are recognized only when their leading
+  :samp:`#` appears in the first column.  There can be no whitespace
+  between the beginning of the line and the :samp:`#`, but whitespace can
+  follow the :samp:`#`.
+
+* A true traditional C preprocessor does not recognize :samp:`#error` or
+  :samp:`#pragma`, and may not recognize :samp:`#elif`.  CPP supports all
+  the directives in traditional mode that it supports in ISO mode,
+  including extensions, with the exception that the effects of
+  :samp:`#pragma GCC poison` are undefined.
+
+* __STDC__ is not defined.
+
+* If you use digraphs the behavior is undefined.
+
+* If a line that looks like a directive appears within macro arguments,
+  the behavior is undefined.

gcc/doc/cpp/traditional-mode.rst

@@ -0,0 +1,35 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _traditional-mode:
+
+Traditional Mode
+----------------
+
+Traditional (pre-standard) C preprocessing is rather different from
+the preprocessing specified by the standard.  When the preprocessor
+is invoked with the
+:option:`-traditional-cpp` option, it attempts to emulate a traditional
+preprocessor.
+
+This mode is not useful for compiling C code with GCC,
+but is intended for use with non-C preprocessing applications.  Thus
+traditional mode semantics are supported only when invoking
+the preprocessor explicitly, and not in the compiler front ends.
+
+The implementation does not correspond precisely to the behavior of
+early pre-standard versions of GCC, nor to any true traditional preprocessor.
+After all, inconsistencies among traditional implementations were a
+major motivation for C standardization.  However, we intend that it
+should be compatible with true traditional preprocessors in all ways
+that actually matter.
+
+.. toctree::
+  :maxdepth: 2
+
+  traditional-lexical-analysis
+  traditional-macros
+  traditional-miscellany
+  traditional-warnings

gcc/doc/cpp/traditional-warnings.rst

@@ -0,0 +1,49 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. _traditional-warnings:
+
+Traditional warnings
+********************
+
+You can request warnings about features that did not exist, or worked
+differently, in traditional C with the :option:`-Wtraditional` option.
+GCC does not warn about features of ISO C which you must use when you
+are using a conforming compiler, such as the :samp:`#` and :samp:`##`
+operators.
+
+Presently :option:`-Wtraditional` warns about:
+
+* Macro parameters that appear within string literals in the macro body.
+  In traditional C macro replacement takes place within string literals,
+  but does not in ISO C.
+
+* In traditional C, some preprocessor directives did not exist.
+  Traditional preprocessors would only consider a line to be a directive
+  if the :samp:`#` appeared in column 1 on the line.  Therefore
+  :option:`-Wtraditional` warns about directives that traditional C
+  understands but would ignore because the :samp:`#` does not appear as the
+  first character on the line.  It also suggests you hide directives like
+  :samp:`#pragma` not understood by traditional C by indenting them.  Some
+  traditional implementations would not recognize :samp:`#elif`, so it
+  suggests avoiding it altogether.
+
+* A function-like macro that appears without an argument list.  In some
+  traditional preprocessors this was an error.  In ISO C it merely means
+  that the macro is not expanded.
+
+* The unary plus operator.  This did not exist in traditional C.
+
+* The :samp:`U` and :samp:`LL` integer constant suffixes, which were not
+  available in traditional C.  (Traditional C does support the :samp:`L`
+  suffix for simple long integer constants.)  You are not warned about
+  uses of these suffixes in macros defined in system headers.  For
+  instance, ``UINT_MAX`` may well be defined as ``4294967295U``, but
+  you will not be warned if you use ``UINT_MAX``.
+
+  You can usually avoid the warning, and the related warning about
+  constants which are so large that they are unsigned, by writing the
+  integer constant in question in hexadecimal, with no U suffix.  Take
+  care, though, because this gives the wrong result in exotic cases.

gcc/doc/cppinternals/conf.py

@@ -0,0 +1,24 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sys
+sys.path.append('../../..//doc')
+
+from baseconf import *
+
+name = 'cppinternals'
+project = 'Cpplib Internals'
+copyright = '2000-2022 Free Software Foundation, Inc.'
+authors = 'Neil Booth'
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+latex_documents = [
+  ('index', f'{name}.tex', project, authors, 'manual'),
+]
+
+texinfo_documents = [
+  ('index', name, project, authors, None, None, None, True)
+]
+
+set_common(name, globals())

gcc/doc/cppinternals/copyright.rst

@@ -0,0 +1,19 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the GPL license file
+
+Copyright
+^^^^^^^^^
+
+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.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.

gcc/doc/cppinternals/cppinternals.rst

@@ -0,0 +1,284 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. @smallbook
+   @cropmarks
+   @finalout
+
+.. index:: interface, header files
+
+.. _conventions:
+
+Conventions
+===========
+
+cpplib has two interfaces---one is exposed internally only, and the
+other is for both internal and external use.
+
+The convention is that functions and types that are exposed to multiple
+files internally are prefixed with :samp:`_cpp_`, and are to be found in
+the file :samp:`internal.h`.  Functions and types exposed to external
+clients are in :samp:`cpplib.h`, and prefixed with :samp:`cpp_`.  For
+historical reasons this is no longer quite true, but we should strive to
+stick to it.
+
+We are striving to reduce the information exposed in :samp:`cpplib.h` to the
+bare minimum necessary, and then to keep it there.  This makes clear
+exactly what external clients are entitled to assume, and allows us to
+change internals in the future without worrying whether library clients
+are perhaps relying on some kind of undocumented implementation-specific
+behavior.
+
+.. index:: lexer, newlines, escaped newlines
+
+.. _lexer:
+
+The Lexer
+=========
+
+.. toctree::
+  :maxdepth: 2
+
+  overview
+  lexing-a-token
+  lexing-a-line
+
+.. index:: hash table, identifiers, macros, assertions, named operators
+
+.. _hash-nodes:
+
+Hash Nodes
+==========
+
+When cpplib encounters an 'identifier', it generates a hash code for
+it and stores it in the hash table.  By 'identifier' we mean tokens
+with type ``CPP_NAME`` ; this includes identifiers in the usual C
+sense, as well as keywords, directive names, macro names and so on.  For
+example, all of ``pragma``, ``int``, ``foo`` and
+``__GNUC__`` are identifiers and hashed when lexed.
+
+Each node in the hash table contain various information about the
+identifier it represents.  For example, its length and type.  At any one
+time, each identifier falls into exactly one of three categories:
+
+* Macros
+
+  These have been declared to be macros, either on the command line or
+  with ``#define``.  A few, such as ``__TIME__`` are built-ins
+  entered in the hash table during initialization.  The hash node for a
+  normal macro points to a structure with more information about the
+  macro, such as whether it is function-like, how many arguments it takes,
+  and its expansion.  Built-in macros are flagged as special, and instead
+  contain an enum indicating which of the various built-in macros it is.
+
+* Assertions
+
+  Assertions are in a separate namespace to macros.  To enforce this, cpp
+  actually prepends a ``#`` character before hashing and entering it in
+  the hash table.  An assertion's node points to a chain of answers to
+  that assertion.
+
+* Void
+
+  Everything else falls into this category---an identifier that is not
+  currently a macro, or a macro that has since been undefined with
+  ``#undef``.
+
+  When preprocessing C++, this category also includes the named operators,
+  such as ``xor``.  In expressions these behave like the operators they
+  represent, but in contexts where the spelling of a token matters they
+  are spelt differently.  This spelling distinction is relevant when they
+  are operands of the stringizing and pasting macro operators ``#`` and
+  ``##``.  Named operator hash nodes are flagged, both to catch the
+  spelling distinction and to prevent them from being defined as macros.
+
+The same identifiers share the same hash node.  Since each identifier
+token, after lexing, contains a pointer to its hash node, this is used
+to provide rapid lookup of various information.  For example, when
+parsing a ``#define`` statement, CPP flags each argument's identifier
+hash node with the index of that argument.  This makes duplicated
+argument checking an O(1) operation for each argument.  Similarly, for
+each identifier in the macro's expansion, lookup to see if it is an
+argument, and which argument it is, is also an O(1) operation.  Further,
+each directive name, such as ``endif``, has an associated directive
+enum stored in its hash node, so that directive lookup is also O(1).
+
+.. index:: macro expansion
+
+.. _macro-expansion:
+
+Macro Expansion Algorithm
+=========================
+
+Macro expansion is a tricky operation, fraught with nasty corner cases
+and situations that render what you thought was a nifty way to
+optimize the preprocessor's expansion algorithm wrong in quite subtle
+ways.
+
+I strongly recommend you have a good grasp of how the C and C++
+standards require macros to be expanded before diving into this
+section, let alone the code!.  If you don't have a clear mental
+picture of how things like nested macro expansion, stringizing and
+token pasting are supposed to work, damage to your sanity can quickly
+result.
+
+.. toctree::
+  :maxdepth: 2
+
+  internal-representation-of-macros
+  macro-expansion-overview
+  scanning-the-replacement-list-for-macros-to-expand
+  looking-for-a-function-like-macros-opening-parenthesis
+  marking-tokens-ineligible-for-future-expansion
+
+.. index:: paste avoidance, spacing, token spacing
+
+.. _token-spacing:
+
+Token Spacing
+=============
+
+First, consider an issue that only concerns the stand-alone
+preprocessor: there needs to be a guarantee that re-reading its preprocessed
+output results in an identical token stream.  Without taking special
+measures, this might not be the case because of macro substitution.
+For example:
+
+.. code-block::
+
+  #define PLUS +
+  #define EMPTY
+  #define f(x) =x=
+  +PLUS -EMPTY- PLUS+ f(=)
+          → + + - - + + = = =
+  not
+          → ++ -- ++ ===
+
+One solution would be to simply insert a space between all adjacent
+tokens.  However, we would like to keep space insertion to a minimum,
+both for aesthetic reasons and because it causes problems for people who
+still try to abuse the preprocessor for things like Fortran source and
+Makefiles.
+
+For now, just notice that when tokens are added (or removed, as shown by
+the ``EMPTY`` example) from the original lexed token stream, we need
+to check for accidental token pasting.  We call this :dfn:`paste
+avoidance`.  Token addition and removal can only occur because of macro
+expansion, but accidental pasting can occur in many places: both before
+and after each macro replacement, each argument replacement, and
+additionally each token created by the :samp:`#` and :samp:`##` operators.
+
+Look at how the preprocessor gets whitespace output correct
+normally.  The ``cpp_token`` structure contains a flags byte, and one
+of those flags is ``PREV_WHITE``.  This is flagged by the lexer, and
+indicates that the token was preceded by whitespace of some form other
+than a new line.  The stand-alone preprocessor can use this flag to
+decide whether to insert a space between tokens in the output.
+
+Now consider the result of the following macro expansion:
+
+.. code-block::
+
+  #define add(x, y, z) x + y +z;
+  sum = add (1,2, 3);
+          → sum = 1 + 2 +3;
+
+The interesting thing here is that the tokens :samp:`1` and :samp:`2` are
+output with a preceding space, and :samp:`3` is output without a
+preceding space, but when lexed none of these tokens had that property.
+Careful consideration reveals that :samp:`1` gets its preceding
+whitespace from the space preceding :samp:`add` in the macro invocation,
+*not* replacement list.  :samp:`2` gets its whitespace from the
+space preceding the parameter :samp:`y` in the macro replacement list,
+and :samp:`3` has no preceding space because parameter :samp:`z` has none
+in the replacement list.
+
+Once lexed, tokens are effectively fixed and cannot be altered, since
+pointers to them might be held in many places, in particular by
+in-progress macro expansions.  So instead of modifying the two tokens
+above, the preprocessor inserts a special token, which I call a
+:dfn:`padding token`, into the token stream to indicate that spacing of
+the subsequent token is special.  The preprocessor inserts padding
+tokens in front of every macro expansion and expanded macro argument.
+These point to a :dfn:`source token` from which the subsequent real token
+should inherit its spacing.  In the above example, the source tokens are
+:samp:`add` in the macro invocation, and :samp:`y` and :samp:`z` in the
+macro replacement list, respectively.
+
+It is quite easy to get multiple padding tokens in a row, for example if
+a macro's first replacement token expands straight into another macro.
+
+.. code-block::
+
+  #define foo bar
+  #define bar baz
+  [foo]
+          → [baz]
+
+Here, two padding tokens are generated with sources the :samp:`foo` token
+between the brackets, and the :samp:`bar` token from foo's replacement
+list, respectively.  Clearly the first padding token is the one to
+use, so the output code should contain a rule that the first
+padding token in a sequence is the one that matters.
+
+But what if a macro expansion is left?  Adjusting the above
+example slightly:
+
+.. code-block::
+
+  #define foo bar
+  #define bar EMPTY baz
+  #define EMPTY
+  [foo] EMPTY;
+          → [ baz] ;
+
+As shown, now there should be a space before :samp:`baz` and the
+semicolon in the output.
+
+The rules we decided above fail for :samp:`baz`: we generate three
+padding tokens, one per macro invocation, before the token :samp:`baz`.
+We would then have it take its spacing from the first of these, which
+carries source token :samp:`foo` with no leading space.
+
+It is vital that cpplib get spacing correct in these examples since any
+of these macro expansions could be stringized, where spacing matters.
+
+So, this demonstrates that not just entering macro and argument
+expansions, but leaving them requires special handling too.  I made
+cpplib insert a padding token with a ``NULL`` source token when
+leaving macro expansions, as well as after each replaced argument in a
+macro's replacement list.  It also inserts appropriate padding tokens on
+either side of tokens created by the :samp:`#` and :samp:`##` operators.
+I expanded the rule so that, if we see a padding token with a
+``NULL`` source token, *and* that source token has no leading
+space, then we behave as if we have seen no padding tokens at all.  A
+quick check shows this rule will then get the above example correct as
+well.
+
+Now a relationship with paste avoidance is apparent: we have to be
+careful about paste avoidance in exactly the same locations we have
+padding tokens in order to get white space correct.  This makes
+implementation of paste avoidance easy: wherever the stand-alone
+preprocessor is fixing up spacing because of padding tokens, and it
+turns out that no space is needed, it has to take the extra step to
+check that a space is not needed after all to avoid an accidental paste.
+The function ``cpp_avoid_paste`` advises whether a space is required
+between two consecutive tokens.  To avoid excessive spacing, it tries
+hard to only require a space if one is likely to be necessary, but for
+reasons of efficiency it is slightly conservative and might recommend a
+space where one is not strictly needed.
+
+.. index:: line numbers
+
+.. _line-numbering:
+
+Line numbering
+==============
+
+.. toctree::
+  :maxdepth: 2
+
+  just-which-line-number-anyway
+  representation-of-line-numbers

gcc/doc/cppinternals/cpplib.rst

@@ -0,0 +1,29 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Cpplib---the GNU C Preprocessor
+-------------------------------
+
+The GNU C preprocessor is
+implemented as a library, :dfn:`cpplib`, so it can be easily shared between
+a stand-alone preprocessor, and a preprocessor integrated with the C,
+C++ and Objective-C front ends.  It is also available for use by other
+programs, though this is not recommended as its exposed interface has
+not yet reached a point of reasonable stability.
+
+The library has been written to be re-entrant, so that it can be used
+to preprocess many files simultaneously if necessary.  It has also been
+written with the preprocessing token as the fundamental unit; the
+preprocessor in previous versions of GCC would operate on text strings
+as the fundamental unit.
+
+This brief manual documents the internals of cpplib, and explains some
+of the tricky issues.  It is intended that, along with the comments in
+the source code, a reasonably competent C programmer should be able to
+figure out what the code is doing, and why things have been implemented
+the way they have.
+
+.. toctree::
+  :maxdepth: 2

gcc/doc/cppinternals/files.rst

@@ -0,0 +1,70 @@
+.. _files:
+
+File Handling
+=============
+
+.. index:: files
+
+Fairly obviously, the file handling code of cpplib resides in the file
+:samp:`files.c`.  It takes care of the details of file searching,
+opening, reading and caching, for both the main source file and all the
+headers it recursively includes.
+
+The basic strategy is to minimize the number of system calls.  On many
+systems, the basic ``open ()`` and ``fstat ()`` system calls can
+be quite expensive.  For every ``#include`` -d file, we need to try
+all the directories in the search path until we find a match.  Some
+projects, such as glibc, pass twenty or thirty include paths on the
+command line, so this can rapidly become time consuming.
+
+For a header file we have not encountered before we have little choice
+but to do this.  However, it is often the case that the same headers are
+repeatedly included, and in these cases we try to avoid repeating the
+filesystem queries whilst searching for the correct file.
+
+For each file we try to open, we store the constructed path in a splay
+tree.  This path first undergoes simplification by the function
+``_cpp_simplify_pathname``.  For example,
+:samp:`/usr/include/bits/../foo.h` is simplified to
+:samp:`/usr/include/foo.h` before we enter it in the splay tree and try
+to ``open ()`` the file.  CPP will then find subsequent uses of
+:samp:`foo.h`, even as :samp:`/usr/include/foo.h`, in the splay tree and
+save system calls.
+
+Further, it is likely the file contents have also been cached, saving a
+``read ()`` system call.  We don't bother caching the contents of
+header files that are re-inclusion protected, and whose re-inclusion
+macro is defined when we leave the header file for the first time.  If
+the host supports it, we try to map suitably large files into memory,
+rather than reading them in directly.
+
+The include paths are internally stored on a null-terminated
+singly-linked list, starting with the ``"header.h"`` directory search
+chain, which then links into the ``<header.h>`` directory chain.
+
+Files included with the ``<foo.h>`` syntax start the lookup directly
+in the second half of this chain.  However, files included with the
+``"foo.h"`` syntax start at the beginning of the chain, but with one
+extra directory prepended.  This is the directory of the current file;
+the one containing the ``#include`` directive.  Prepending this
+directory on a per-file basis is handled by the function
+``search_from``.
+
+Note that a header included with a directory component, such as
+``#include "mydir/foo.h"`` and opened as
+:samp:`/usr/local/include/mydir/foo.h`, will have the complete path minus
+the basename :samp:`foo.h` as the current directory.
+
+Enough information is stored in the splay tree that CPP can immediately
+tell whether it can skip the header file because of the multiple include
+optimization, whether the file didn't exist or couldn't be opened for
+some reason, or whether the header was flagged not to be re-used, as it
+is with the obsolete ``#import`` directive.
+
+For the benefit of MS-DOS filesystems with an 8.3 filename limitation,
+CPP offers the ability to treat various include file names as aliases
+for the real header files with shorter names.  The map from one to the
+other is found in a special file called :samp:`header.gcc`, stored in the
+command line (or system) include directories to which the mapping
+applies.  This may be higher up the directory tree than the full path to
+the file minus the base name.

gcc/doc/cppinternals/index.rst

@@ -0,0 +1,21 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+The GNU C Preprocessor Internals
+================================
+
+.. only:: html
+
+  Contents:
+
+.. toctree::
+
+  copyright
+  cpplib
+  cppinternals
+  multiple-include-optimization
+  files
+
+  indices-and-tables

gcc/doc/cppinternals/indices-and-tables.rst

@@ -0,0 +1 @@
+.. include:: ../../../doc/indices-and-tables.rst

gcc/doc/cppinternals/internal-representation-of-macros.rst

@@ -0,0 +1,27 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: macro representation (internal)
+
+Internal representation of macros
+*********************************
+
+The preprocessor stores macro expansions in tokenized form.  This
+saves repeated lexing passes during expansion, at the cost of a small
+increase in memory consumption on average.  The tokens are stored
+contiguously in memory, so a pointer to the first one and a token
+count is all you need to get the replacement list of a macro.
+
+If the macro is a function-like macro the preprocessor also stores its
+parameters, in the form of an ordered list of pointers to the hash
+table entry of each parameter's identifier.  Further, in the macro's
+stored expansion each occurrence of a parameter is replaced with a
+special token of type ``CPP_MACRO_ARG``.  Each such token holds the
+index of the parameter it represents in the parameter list, which
+allows rapid replacement of parameters with their arguments during
+expansion.  Despite this optimization it is still necessary to store
+the original parameters to the macro, both for dumping with e.g.,
+:option:`-dD`, and to warn about non-trivial macro redefinitions when
+the parameter names have changed.

gcc/doc/cppinternals/just-which-line-number-anyway.rst

@@ -0,0 +1,62 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Just which line number anyway?
+******************************
+
+There are three reasonable requirements a cpplib client might have for
+the line number of a token passed to it:
+
+* The source line it was lexed on.
+
+* The line it is output on.  This can be different to the line it was
+  lexed on if, for example, there are intervening escaped newlines or
+  C-style comments.  For example:
+
+  .. code-block::
+
+    foo /* A long
+    comment */ bar \
+    baz
+    ⇒
+    foo bar baz
+
+* If the token results from a macro expansion, the line of the macro name,
+  or possibly the line of the closing parenthesis in the case of
+  function-like macro expansion.
+
+The ``cpp_token`` structure contains ``line`` and ``col``
+members.  The lexer fills these in with the line and column of the first
+character of the token.  Consequently, but maybe unexpectedly, a token
+from the replacement list of a macro expansion carries the location of
+the token within the ``#define`` directive, because cpplib expands a
+macro by returning pointers to the tokens in its replacement list.  The
+current implementation of cpplib assigns tokens created from built-in
+macros and the :samp:`#` and :samp:`##` operators the location of the most
+recently lexed token.  This is a because they are allocated from the
+lexer's token runs, and because of the way the diagnostic routines infer
+the appropriate location to report.
+
+The diagnostic routines in cpplib display the location of the most
+recently *lexed* token, unless they are passed a specific line and
+column to report.  For diagnostics regarding tokens that arise from
+macro expansions, it might also be helpful for the user to see the
+original location in the macro definition that the token came from.
+Since that is exactly the information each token carries, such an
+enhancement could be made relatively easily in future.
+
+The stand-alone preprocessor faces a similar problem when determining
+the correct line to output the token on: the position attached to a
+token is fairly useless if the token came from a macro expansion.  All
+tokens on a logical line should be output on its first physical line, so
+the token's reported location is also wrong if it is part of a physical
+line other than the first.
+
+To solve these issues, cpplib provides a callback that is generated
+whenever it lexes a preprocessing token that starts a new logical line
+other than a directive.  It passes this token (which may be a
+``CPP_EOF`` token indicating the end of the translation unit) to the
+callback routine, which can then use the line and column of this token
+to produce correct output.

gcc/doc/cppinternals/lexing-a-line.rst

@@ -0,0 +1,91 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+.. index:: token run
+
+.. _lexing-a-line:
+
+Lexing a line
+*************
+
+When the preprocessor was changed to return pointers to tokens, one
+feature I wanted was some sort of guarantee regarding how long a
+returned pointer remains valid.  This is important to the stand-alone
+preprocessor, the future direction of the C family front ends, and even
+to cpplib itself internally.
+
+Occasionally the preprocessor wants to be able to peek ahead in the
+token stream.  For example, after the name of a function-like macro, it
+wants to check the next token to see if it is an opening parenthesis.
+Another example is that, after reading the first few tokens of a
+``#pragma`` directive and not recognizing it as a registered pragma,
+it wants to backtrack and allow the user-defined handler for unknown
+pragmas to access the full ``#pragma`` token stream.  The stand-alone
+preprocessor wants to be able to test the current token with the
+previous one to see if a space needs to be inserted to preserve their
+separate tokenization upon re-lexing (paste avoidance), so it needs to
+be sure the pointer to the previous token is still valid.  The
+recursive-descent C++ parser wants to be able to perform tentative
+parsing arbitrarily far ahead in the token stream, and then to be able
+to jump back to a prior position in that stream if necessary.
+
+The rule I chose, which is fairly natural, is to arrange that the
+preprocessor lex all tokens on a line consecutively into a token buffer,
+which I call a :dfn:`token run`, and when meeting an unescaped new line
+(newlines within comments do not count either), to start lexing back at
+the beginning of the run.  Note that we do *not* lex a line of
+tokens at once; if we did that ``parse_identifier`` would not have
+state flags available to warn about invalid identifiers (see :ref:`Invalid identifiers <invalid-identifiers>`).
+
+In other words, accessing tokens that appeared earlier in the current
+line is valid, but since each logical line overwrites the tokens of the
+previous line, tokens from prior lines are unavailable.  In particular,
+since a directive only occupies a single logical line, this means that
+the directive handlers like the ``#pragma`` handler can jump around
+in the directive's tokens if necessary.
+
+Two issues remain: what about tokens that arise from macro expansions,
+and what happens when we have a long line that overflows the token run?
+
+Since we promise clients that we preserve the validity of pointers that
+we have already returned for tokens that appeared earlier in the line,
+we cannot reallocate the run.  Instead, on overflow it is expanded by
+chaining a new token run on to the end of the existing one.
+
+The tokens forming a macro's replacement list are collected by the
+``#define`` handler, and placed in storage that is only freed by
+``cpp_destroy``.  So if a macro is expanded in the line of tokens,
+the pointers to the tokens of its expansion that are returned will always
+remain valid.  However, macros are a little trickier than that, since
+they give rise to three sources of fresh tokens.  They are the built-in
+macros like ``__LINE__``, and the :samp:`#` and :samp:`##` operators
+for stringizing and token pasting.  I handled this by allocating
+space for these tokens from the lexer's token run chain.  This means
+they automatically receive the same lifetime guarantees as lexed tokens,
+and we don't need to concern ourselves with freeing them.
+
+Lexing into a line of tokens solves some of the token memory management
+issues, but not all.  The opening parenthesis after a function-like
+macro name might lie on a different line, and the front ends definitely
+want the ability to look ahead past the end of the current line.  So
+cpplib only moves back to the start of the token run at the end of a
+line if the variable ``keep_tokens`` is zero.  Line-buffering is
+quite natural for the preprocessor, and as a result the only time cpplib
+needs to increment this variable is whilst looking for the opening
+parenthesis to, and reading the arguments of, a function-like macro.  In
+the near future cpplib will export an interface to increment and
+decrement this variable, so that clients can share full control over the
+lifetime of token pointers too.
+
+The routine ``_cpp_lex_token`` handles moving to new token runs,
+calling ``_cpp_lex_direct`` to lex new tokens, or returning
+previously-lexed tokens if we stepped back in the token stream.  It also
+checks each token for the ``BOL`` flag, which might indicate a
+directive that needs to be handled, or require a start-of-line call-back
+to be made.  ``_cpp_lex_token`` also handles skipping over tokens in
+failed conditional blocks, and invalidates the control macro of the
+multiple-include optimization if a token was successfully lexed outside
+a directive.  In other words, its callers do not need to concern
+themselves with such issues.

gcc/doc/cppinternals/lexing-a-token.rst

@@ -0,0 +1,177 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Lexing a token
+**************
+
+Lexing of an individual token is handled by ``_cpp_lex_direct`` and
+its subroutines.  In its current form the code is quite complicated,
+with read ahead characters and such-like, since it strives to not step
+back in the character stream in preparation for handling non-ASCII file
+encodings.  The current plan is to convert any such files to UTF-8
+before processing them.  This complexity is therefore unnecessary and
+will be removed, so I'll not discuss it further here.
+
+The job of ``_cpp_lex_direct`` is simply to lex a token.  It is not
+responsible for issues like directive handling, returning lookahead
+tokens directly, multiple-include optimization, or conditional block
+skipping.  It necessarily has a minor rôle to play in memory
+management of lexed lines.  I discuss these issues in a separate section
+(see :ref:`lexing-a-line`).
+
+The lexer places the token it lexes into storage pointed to by the
+variable ``cur_token``, and then increments it.  This variable is
+important for correct diagnostic positioning.  Unless a specific line
+and column are passed to the diagnostic routines, they will examine the
+``line`` and ``col`` values of the token just before the location
+that ``cur_token`` points to, and use that location to report the
+diagnostic.
+
+The lexer does not consider whitespace to be a token in its own right.
+If whitespace (other than a new line) precedes a token, it sets the
+``PREV_WHITE`` bit in the token's flags.  Each token has its
+``line`` and ``col`` variables set to the line and column of the
+first character of the token.  This line number is the line number in
+the translation unit, and can be converted to a source (file, line) pair
+using the line map code.
+
+The first token on a logical, i.e. unescaped, line has the flag
+``BOL`` set for beginning-of-line.  This flag is intended for
+internal use, both to distinguish a :samp:`#` that begins a directive
+from one that doesn't, and to generate a call-back to clients that want
+to be notified about the start of every non-directive line with tokens
+on it.  Clients cannot reliably determine this for themselves: the first
+token might be a macro, and the tokens of a macro expansion do not have
+the ``BOL`` flag set.  The macro expansion may even be empty, and the
+next token on the line certainly won't have the ``BOL`` flag set.
+
+New lines are treated specially; exactly how the lexer handles them is
+context-dependent.  The C standard mandates that directives are
+terminated by the first unescaped newline character, even if it appears
+in the middle of a macro expansion.  Therefore, if the state variable
+``in_directive`` is set, the lexer returns a ``CPP_EOF`` token,
+which is normally used to indicate end-of-file, to indicate
+end-of-directive.  In a directive a ``CPP_EOF`` token never means
+end-of-file.  Conveniently, if the caller was ``collect_args``, it
+already handles ``CPP_EOF`` as if it were end-of-file, and reports an
+error about an unterminated macro argument list.
+
+The C standard also specifies that a new line in the middle of the
+arguments to a macro is treated as whitespace.  This white space is
+important in case the macro argument is stringized.  The state variable
+``parsing_args`` is nonzero when the preprocessor is collecting the
+arguments to a macro call.  It is set to 1 when looking for the opening
+parenthesis to a function-like macro, and 2 when collecting the actual
+arguments up to the closing parenthesis, since these two cases need to
+be distinguished sometimes.  One such time is here: the lexer sets the
+``PREV_WHITE`` flag of a token if it meets a new line when
+``parsing_args`` is set to 2.  It doesn't set it if it meets a new
+line when ``parsing_args`` is 1, since then code like
+
+.. code-block:: c++
+
+  #define foo() bar
+  foo
+  baz
+
+would be output with an erroneous space before :samp:`baz`:
+
+.. code-block:: c++
+
+  foo
+   baz
+
+This is a good example of the subtlety of getting token spacing correct
+in the preprocessor; there are plenty of tests in the testsuite for
+corner cases like this.
+
+The lexer is written to treat each of :samp:`\\r`, :samp:`\\n`, :samp:`\\r\\n`
+and :samp:`\\n\\r` as a single new line indicator.  This allows it to
+transparently preprocess MS-DOS, Macintosh and Unix files without their
+needing to pass through a special filter beforehand.
+
+We also decided to treat a backslash, either ``\`` or the trigraph
+``??/``, separated from one of the above newline indicators by
+non-comment whitespace only, as intending to escape the newline.  It
+tends to be a typing mistake, and cannot reasonably be mistaken for
+anything else in any of the C-family grammars.  Since handling it this
+way is not strictly conforming to the ISO standard, the library issues a
+warning wherever it encounters it.
+
+Handling newlines like this is made simpler by doing it in one place
+only.  The function ``handle_newline`` takes care of all newline
+characters, and ``skip_escaped_newlines`` takes care of arbitrarily
+long sequences of escaped newlines, deferring to ``handle_newline``
+to handle the newlines themselves.
+
+The most painful aspect of lexing ISO-standard C and C++ is handling
+trigraphs and backlash-escaped newlines.  Trigraphs are processed before
+any interpretation of the meaning of a character is made, and unfortunately
+there is a trigraph representation for a backslash, so it is possible for
+the trigraph ``??/`` to introduce an escaped newline.
+
+Escaped newlines are tedious because theoretically they can occur
+anywhere---between the :samp:`+` and :samp:`=` of the :samp:`+=` token,
+within the characters of an identifier, and even between the :samp:`*`
+and :samp:`/` that terminates a comment.  Moreover, you cannot be sure
+there is just one---there might be an arbitrarily long sequence of them.
+
+So, for example, the routine that lexes a number, ``parse_number``,
+cannot assume that it can scan forwards until the first non-number
+character and be done with it, because this could be the :samp:`\\`
+introducing an escaped newline, or the :samp:`?` introducing the trigraph
+sequence that represents the :samp:`\\` of an escaped newline.  If it
+encounters a :samp:`?` or :samp:`\\`, it calls ``skip_escaped_newlines``
+to skip over any potential escaped newlines before checking whether the
+number has been finished.
+
+Similarly code in the main body of ``_cpp_lex_direct`` cannot simply
+check for a :samp:`=` after a :samp:`+` character to determine whether it
+has a :samp:`+=` token; it needs to be prepared for an escaped newline of
+some sort.  Such cases use the function ``get_effective_char``, which
+returns the first character after any intervening escaped newlines.
+
+The lexer needs to keep track of the correct column position, including
+counting tabs as specified by the :option:`-ftabstop=` option.  This
+should be done even within C-style comments; they can appear in the
+middle of a line, and we want to report diagnostics in the correct
+position for text appearing after the end of the comment.
+
+.. _invalid-identifiers:
+
+Some identifiers, such as ``__VA_ARGS__`` and poisoned identifiers,
+may be invalid and require a diagnostic.  However, if they appear in a
+macro expansion we don't want to complain with each use of the macro.
+It is therefore best to catch them during the lexing stage, in
+``parse_identifier``.  In both cases, whether a diagnostic is needed
+or not is dependent upon the lexer's state.  For example, we don't want
+to issue a diagnostic for re-poisoning a poisoned identifier, or for
+using ``__VA_ARGS__`` in the expansion of a variable-argument macro.
+Therefore ``parse_identifier`` makes use of state flags to determine
+whether a diagnostic is appropriate.  Since we change state on a
+per-token basis, and don't lex whole lines at a time, this is not a
+problem.
+
+Another place where state flags are used to change behavior is whilst
+lexing header names.  Normally, a :samp:`<` would be lexed as a single
+token.  After a ``#include`` directive, though, it should be lexed as
+a single token as far as the nearest :samp:`>` character.  Note that we
+don't allow the terminators of header names to be escaped; the first
+:samp:`"` or :samp:`>` terminates the header name.
+
+Interpretation of some character sequences depends upon whether we are
+lexing C, C++ or Objective-C, and on the revision of the standard in
+force.  For example, :samp:`::` is a single token in C++, but in C it is
+two separate :samp:`:` tokens and almost certainly a syntax error.  Such
+cases are handled by ``_cpp_lex_direct`` based upon command-line
+flags stored in the ``cpp_options`` structure.
+
+Once a token has been lexed, it leads an independent existence.  The
+spelling of numbers, identifiers and strings is copied to permanent
+storage from the original input buffer, so a token remains valid and
+correct even if its source buffer is freed with ``_cpp_pop_buffer``.
+The storage holding the spellings of such tokens remains until the
+client program calls cpp_destroy, probably at the end of the translation
+unit.

gcc/doc/cppinternals/looking-for-a-function-like-macros-opening-parenthesis.rst

@@ -0,0 +1,24 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Looking for a function-like macro's opening parenthesis
+*******************************************************
+
+Function-like macros only expand when immediately followed by a
+parenthesis.  To do this cpplib needs to temporarily disable macros
+and read the next token.  Unfortunately, because of spacing issues
+(see :ref:`token-spacing`), there can be fake padding tokens in-between,
+and if the next real token is not a parenthesis cpplib needs to be
+able to back up that one token as well as retain the information in
+any intervening padding tokens.
+
+Backing up more than one token when macros are involved is not
+permitted by cpplib, because in general it might involve issues like
+restoring popped contexts onto the context stack, which are too hard.
+Instead, searching for the parenthesis is handled by a special
+function, ``funlike_invocation_p``, which remembers padding
+information as it reads tokens.  If the next real token is not an
+opening parenthesis, it backs up that one token, and then pushes an
+extra context just containing the padding information if necessary.

gcc/doc/cppinternals/macro-expansion-overview.rst

@@ -0,0 +1,51 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Macro expansion overview
+************************
+
+The preprocessor maintains a :dfn:`context stack`, implemented as a
+linked list of ``cpp_context`` structures, which together represent
+the macro expansion state at any one time.  The ``struct
+cpp_reader`` member variable ``context`` points to the current top
+of this stack.  The top normally holds the unexpanded replacement list
+of the innermost macro under expansion, except when cpplib is about to
+pre-expand an argument, in which case it holds that argument's
+unexpanded tokens.
+
+When there are no macros under expansion, cpplib is in :dfn:`base
+context`.  All contexts other than the base context contain a
+contiguous list of tokens delimited by a starting and ending token.
+When not in base context, cpplib obtains the next token from the list
+of the top context.  If there are no tokens left in the list, it pops
+that context off the stack, and subsequent ones if necessary, until an
+unexhausted context is found or it returns to base context.  In base
+context, cpplib reads tokens directly from the lexer.
+
+If it encounters an identifier that is both a macro and enabled for
+expansion, cpplib prepares to push a new context for that macro on the
+stack by calling the routine ``enter_macro_context``.  When this
+routine returns, the new context will contain the unexpanded tokens of
+the replacement list of that macro.  In the case of function-like
+macros, ``enter_macro_context`` also replaces any parameters in the
+replacement list, stored as ``CPP_MACRO_ARG`` tokens, with the
+appropriate macro argument.  If the standard requires that the
+parameter be replaced with its expanded argument, the argument will
+have been fully macro expanded first.
+
+``enter_macro_context`` also handles special macros like
+``__LINE__``.  Although these macros expand to a single token which
+cannot contain any further macros, for reasons of token spacing
+(see :ref:`token-spacing`) and simplicity of implementation, cpplib
+handles these special macros by pushing a context containing just that
+one token.
+
+The final thing that ``enter_macro_context`` does before returning
+is to mark the macro disabled for expansion (except for special macros
+like ``__TIME__``).  The macro is re-enabled when its context is
+later popped from the context stack, as described above.  This strict
+ordering ensures that a macro is disabled whilst its expansion is
+being scanned, but that it is *not* disabled whilst any arguments
+to it are being expanded.

gcc/doc/cppinternals/marking-tokens-ineligible-for-future-expansion.rst

@@ -0,0 +1,24 @@
+..
+  Copyright 1988-2022 Free Software Foundation, Inc.
+  This is part of the GCC manual.
+  For copying conditions, see the copyright.rst file.
+
+Marking tokens ineligible for future expansion
+**********************************************
+
+As discussed above, cpplib needs a way of marking tokens as
+unexpandable.  Since the tokens cpplib handles are read-only once they
+have been lexed, it instead makes a copy of the token and adds the
+flag ``NO_EXPAND`` to the copy.
+
+For efficiency and to simplify memory management by avoiding having to
+remember to free these tokens, they are allocated as temporary tokens
+from the lexer's current token run (see :ref:`lexing-a-line`) using the
+function ``_cpp_temp_token``.  The tokens are then re-used once the
+current line of tokens has been read in.
+
+This might sound unsafe.  However, tokens runs are not re-used at the
+end of a line if it happens to be in the middle of a macro argument
+list, and cpplib only wants to back-up more than one lexer token in
+situations where no macro expansion is involved, so the optimization
+is safe.