https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634
--- Comment #10 from Eric Botcazou <ebotcazou at gcc dot gnu.org> --- > About the number of files. Yes, that's the biggest change when it comes to > Sphinx and I see it also as a drawback. However, it's the only valid file > naming scheme supported by Sphinx and there are projects with non-trivial > docs where the average size of a file matches to what we have: The granularity is IMO problematic and will very likely not coax people into updating the documentation (to say the least), which is counter-productive. Why do we need to recursively split sections into sub-sections like this? │ ├── extensions-to-the-c-language-family │ │ ├── 128-bit-integers.rst │ │ ├── additional-floating-types.rst │ │ ├── alternate-keywords.rst │ │ ├── an-inline-function-is-as-fast-as-a-macro.rst │ │ ├── arithmetic-on-void-and-function-pointers.rst │ │ ├── arrays-of-length-zero.rst │ │ ├── arrays-of-variable-length.rst │ │ ├── attribute-syntax.rst │ │ ├── binary-constants-using-the-0b-prefix.rst │ │ ├── built-in-functions-for-memory-model-aware-atomic-operations.rst │ │ ├── built-in-functions-to-perform-arithmetic-with-overflow-checking.rst │ │ ├── c++-style-comments.rst │ │ ├── case-ranges.rst │ │ ├── cast-to-a-union-type.rst │ │ ├── complex-numbers.rst │ │ ├── compound-literals.rst │ │ ├── conditionals-with-omitted-operands.rst │ │ ├── constructing-function-calls.rst │ │ ├── decimal-floating-types.rst │ │ ├── declaring-attributes-of-functions │ │ │ ├── aarch64-function-attributes.rst │ │ │ ├── amd-gcn-function-attributes.rst │ │ │ ├── arc-function-attributes.rst │ │ │ ├── arm-function-attributes.rst │ │ │ ├── avr-function-attributes.rst │ │ │ ├── blackfin-function-attributes.rst │ │ │ ├── bpf-function-attributes.rst │ │ │ ├── c-sky-function-attributes.rst │ │ │ ├── common-function-attributes.rst │ │ │ ├── epiphany-function-attributes.rst │ │ │ ├── h8-300-function-attributes.rst │ │ │ ├── ia-64-function-attributes.rst │ │ │ ├── m32c-function-attributes.rst │ │ │ ├── m32r-d-function-attributes.rst │ │ │ ├── m68k-function-attributes.rst │ │ │ ├── mcore-function-attributes.rst │ │ │ ├── mep-function-attributes.rst │ │ │ ├── microblaze-function-attributes.rst │ │ │ ├── microsoft-windows-function-attributes.rst │ │ │ ├── mips-function-attributes.rst │ │ │ ├── msp430-function-attributes.rst │ │ │ ├── nds32-function-attributes.rst │ │ │ ├── nios-ii-function-attributes.rst │ │ │ ├── nvidia-ptx-function-attributes.rst │ │ │ ├── powerpc-function-attributes.rst │ │ │ ├── risc-v-function-attributes.rst │ │ │ ├── rl78-function-attributes.rst │ │ │ ├── rx-function-attributes.rst │ │ │ ├── s-390-function-attributes.rst │ │ │ ├── sh-function-attributes.rst │ │ │ ├── symbian-os-function-attributes.rst │ │ │ ├── v850-function-attributes.rst │ │ │ ├── visium-function-attributes.rst │ │ │ ├── x86-function-attributes.rst │ │ │ └── xstormy16-function-attributes.rst │ │ ├── declaring-attributes-of-functions.rst │ │ ├── designated-initializers.rst │ │ ├── determining-the-alignment-of-functions-types-or-variables.rst │ │ ├── dollar-signs-in-identifier-names.rst │ │ ├── double-word-integers.rst │ │ ├── enumerator-attributes.rst │ │ ├── fixed-point-types.rst │ │ ├── format-checks-specific-to-particular-target-machines.rst │ │ ├── function-names-as-strings.rst │ │ ├── getting-the-return-or-frame-address-of-a-function.rst │ │ ├── half-precision-floating-point.rst │ │ ├── hex-floats.rst │ │ ├── how-to-use-inline-assembly-language-in-c-code.rst │ │ ├── incomplete-enum-types.rst │ │ ├── label-attributes.rst │ │ ├── labels-as-values.rst │ │ ├── legacy-sync-built-in-functions-for-atomic-memory-access.rst │ │ ├── locally-declared-labels.rst │ │ ├── macros-with-a-variable-number-of-arguments.rst │ │ ├── mixed-declarations-labels-and-code.rst │ │ ├── named-address-spaces.rst │ │ ├── nested-functions.rst │ │ ├── non-constant-initializers.rst │ │ ├── non-lvalue-arrays-may-have-subscripts.rst │ │ ├── nonlocal-gotos.rst │ │ ├── object-size-checking-built-in-functions.rst │ │ ├── other-built-in-functions-provided-by-gcc.rst │ │ ├── pointer-arguments-in-variadic-functions.rst │ │ ├── pointers-to-arrays-with-qualifiers-work-as-expected.rst │ │ ├── pragmas-accepted-by-gcc.rst │ │ ├── prototypes-and-old-style-function-definitions.rst │ │ ├── referring-to-a-type-with-typeof.rst │ │ ├── slightly-looser-rules-for-escaped-newlines.rst │ │ ├── specifying-attributes-of-types.rst │ │ ├── specifying-attributes-of-variables.rst │ │ ├── statement-attributes.rst │ │ ├── statements-and-declarations-in-expressions.rst │ │ ├── structures-with-no-members.rst │ │ ├── support-for-offsetof.rst │ │ ├── target-builtins │ │ │ ├── aarch64-built-in-functions.rst │ │ │ ├── alpha-built-in-functions.rst │ │ │ ├── altera-nios-ii-built-in-functions.rst │ │ │ ├── arc-built-in-functions.rst │ │ │ ├── arc-simd-built-in-functions.rst │ │ │ ├── arm-armv8-m-security-extensions.rst │ │ │ ├── arm-c-language-extensions-acle.rst │ │ │ ├── arm-floating-point-status-and-control-intrinsics.rst │ │ │ ├── arm-iwmmxt-built-in-functions.rst │ │ │ ├── avr-built-in-functions.rst │ │ │ ├── basic-powerpc-built-in-functions.rst │ │ │ ├── blackfin-built-in-functions.rst │ │ │ ├── bpf-built-in-functions.rst │ │ │ ├── fr-v-built-in-functions.rst │ │ │ ├── mips-dsp-built-in-functions.rst │ │ │ ├── mips-loongson-built-in-functions.rst │ │ │ ├── mips-paired-single-support.rst │ │ │ ├── mips-simd-architecture-msa-support.rst │ │ │ ├── msp430-built-in-functions.rst │ │ │ ├── nds32-built-in-functions.rst │ │ │ ├── other-mips-built-in-functions.rst │ │ │ ├── picochip-built-in-functions.rst │ │ │ ├── powerpc-altivec-vsx-built-in-functions.rst │ │ │ ├── powerpc-atomic-memory-operation-functions.rst │ │ │ ├── powerpc-hardware-transactional-memory-built-in-functions.rst │ │ │ ├── powerpc-matrix-multiply-assist-built-in-functions.rst │ │ │ ├── pru-built-in-functions.rst │ │ │ ├── risc-v-built-in-functions.rst │ │ │ ├── rx-built-in-functions.rst │ │ │ ├── s-390-system-z-built-in-functions.rst │ │ │ ├── sh-built-in-functions.rst │ │ │ ├── sparc-vis-built-in-functions.rst │ │ │ ├── ti-c6x-built-in-functions.rst │ │ │ ├── x86-built-in-functions.rst │ │ │ ├── x86-control-flow-protection-intrinsics.rst │ │ │ └── x86-transactional-memory-intrinsics.rst │ │ ├── target-builtins.rst │ │ ├── the-character-esc-in-constants.rst │ │ ├── thread-local-storage.rst │ │ ├── unnamed-structure-and-union-fields.rst │ │ ├── using-vector-instructions-through-built-in-functions.rst │ │ ├── when-is-a-volatile-object-accessed.rst │ │ └── x86-specific-memory-model-extensions-for-transactional-memory.rst > That's a reduction of ~50 files. To be honest, the split is mandatory thing > and there's not much I can do about it. Not sufficient IMO, we would need to slash the number of files by an order of magnitude, 70-80 files would be acceptable I think. > Just a note for the old .texi files: we used to have files > (./gcc/doc/invoke.texi ./gcc/doc/extend.texi, ./gcc/fortran/intrinsic.texi) > that tend to have 1000s of lines which is not ideal either. Ideal for what? The point of a documentation processor should be to separate the final layout from the sources as much as possible. If Sphinx does really put such questionable constraints on the sources to produce the final layout, then it's a clear step backwards from Texinfo.
