[Bug other/107634] New: Very long filenames and URLs for sphinx-based docs

[Bug other/107634] New: Very long filenames and URLs for sphinx-based docs

[dmalcolm at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

            Bug ID: 107634
           Summary: Very long filenames and URLs for sphinx-based docs
           Product: gcc
           Version: 13.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: normal
          Priority: P3
         Component: other
          Assignee: unassigned at gcc dot gnu.org
          Reporter: dmalcolm at gcc dot gnu.org
                CC: marxin at gcc dot gnu.org
  Target Milestone: ---

Although mostly I'm very happy with how our docs look after migration to
sphinx, the new filenames (and thus URLs) for the sphinx-based docs seem overly
long.

I just added a new option to -fanalyzer.  Previously I had to edit:
  gcc/doc/invoke.texi
and the generated HTML would be in:
  https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Static-Analyzer-Options.html

Now I have to edit:
  gcc/doc/gcc/gcc-command-options/options-that-control-static-analysis.rst
and the generated HTML is in:
 
https://gcc.gnu.org/onlinedocs/gcc/gcc-command-options/options-that-control-static-analysis.html

which repeats "gcc" and "options".  Some of them are:
  options-that-*
and others are:
  options-for-*
and:
  options-to-*
and:
  options-controlling-*

Perhaps this is just unfamiliarity with the new system, but it seems like the
filenames could be much shorter, so e.g. rather than:
  gcc/doc/gcc/gcc-command-options/options-that-control-static-analysis.rst
we could have:  
  gcc/doc/gcc/options/analyzer.rst
or somesuch.

Similar, we have:
  gcc/doc/gcc/gcc-command-options/machine-dependent-options/aarch64-options.rst
 
https://gcc.gnu.org/onlinedocs/gcc/gcc-command-options/machine-dependent-options/aarch64-options.html
which has "options" 3 times; perhaps it could be:
  gcc/doc/gcc/options/target/aarch64.rst
or somesuch.

...and yet another set of redirects for the HTML, I guess :-/

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[rguenth at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #1 from Richard Biener <rguenth at gcc dot gnu.org> ---
Finding the relevant sources to edit is indeed cumbersome (for those who
remember the previous file names).  I've also used the texi sources themselves
as documentation - that's now nearly impossible due to the hugely fragmented
source base :(

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #2 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Hmm, I thought at one point we were producing also one big HTML for the manual
but maybe that was just binutils.

Also sphinx does not produce postscript? Just PDFs? Seems a downgrade.

And yes I used to go into invoke.texi and do a search for the options too.
Splitting it up into different files is a HUGE downgrade.

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[ebotcazou at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

Eric Botcazou <ebotcazou at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
     Ever confirmed|0                           |1
   Last reconfirmed|                            |2022-11-11
                 CC|                            |ebotcazou at gcc dot gnu.org
             Status|UNCONFIRMED                 |NEW

--- Comment #3 from Eric Botcazou <ebotcazou at gcc dot gnu.org> ---
Indeed, there are now 746 files under doc/ with ridiculously long names for a
bunch of them.  I don't think that's even remotely manageable.

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[ebotcazou at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

Eric Botcazou <ebotcazou at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Severity|normal                      |critical

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #4 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
I came across a related issue here:
Take:
https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gccint/C_002b_002b-ABI.html
The original section name was just C++-ABI but had a heading of C++ ABI
parameters

Now post sphinx, it is just C++ ABI parameters for both the section name and
the heading:
https://gcc.gnu.org/onlinedocs/gccint/target-macros/c%2B%2B-abi-parameters.html
The file name definitely could just be C++-abi here since we are in the target
macro section.

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #5 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
One of the biggest drawbacks of not having one file is when you need to add a
new section, you have to add a new file/directory rather than edditing one
file.
I also noticed the splitting up sections of the post sphinx conversion is
"random". Some sections are split up now while others are not. for an example
the documentation for inline-asm is no longer split up (PR 107653). Does anyone
understand the heurstic used for when sections were split up?

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[ebotcazou at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #6 from Eric Botcazou <ebotcazou at gcc dot gnu.org> ---
> One of the biggest drawbacks of not having one file is when you need to add
> a new section, you have to add a new file/directory rather than edditing one
> file.

Right, that's clearly not manageable.  GNAT went through the same transition a
couple of years ago and ada/doc now contains 45 files, which is already quite a
bit but nowhere near the 700 now present in doc/.

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #7 from Martin Liška <marxin at gcc dot gnu.org> ---
So first to the original issue reported by David. Yes, the filenames were
selected based on chapter's caption and thus some of them are very long. For
gcc documentation, I'm suggesting following name scheme where the entire path
since base folder (gcc/doc/gcc) should be at maximum 50 characters w/o .rst
extension:

./binary-compatibility.rst
./c++-implementation-defined-behavior.rst
c-behavior/architecture.rst
c-behavior/arrays-and-pointers.rst
c-behavior/characters.rst
c-behavior/declarators.rst
c-behavior/environment.rst
c-behavior/floating-point.rst
c-behavior/hints.rst
c-behavior/identifiers.rst
c-behavior/integers.rst
c-behavior/library-functions.rst
c-behavior/locale-specific-behavior.rst
c-behavior/preprocessing-directives.rst
c-behavior/qualifiers.rst
c-behavior/statements.rst
c-behavior/compount-types.rst
c-behavior/translation.rst
./c-behavior.rst
./conditionally-supported-behavior.rst
./contributing.rst
./contributors.rst
./copyright.rst
./exception-handling.rst
c++-extensions/backwards-compatibility.rst
c++-extensions/c++-concepts.rst
c++-extensions/interface-and-impl-pragmas.rst
c++-extensions/var-and-type-attrs.rst
c++-extensions/deprecated-features.rst
c++-extensions/function-pointer.rst
c++-extensions/function-multiversioning.rst
c++-extensions/restricting-pointer-aliasing.rst
c++-extensions/type-traits.rst
c++-extensions/vague-linkage.rst
c++-extensions/volatile.rst
c++-extensions/wheres-the-template.rst
./c++-extensions.rst
c-extensions/128-bit-integers.rst
c-extensions/additional-floating-types.rst
c-extensions/alternate-keywords.rst
c-extensions/inline-function.rst
c-extensions/void-fns-arithmetic.rst
c-extensions/arrays-of-length-zero.rst
c-extensions/arrays-of-variable-length.rst
c-extensions/attribute-syntax.rst
c-extensions/0b-prefix-arithmetic.rst
c-extensions/memory-model-builtins.rst
c-extensions/arithmetic-overflow-builtins.rst
c-extensions/c++-style-comments.rst
c-extensions/case-ranges.rst
c-extensions/cast-to-a-union-type.rst
c-extensions/complex-numbers.rst
c-extensions/compound-literals.rst
c-extensions/omitted-operands-conditionals.rst
c-extensions/constructing-fn-calls.rst
c-extensions/decimal-floating-types.rst
c-extensions/function-attrs/aarch64.rst
c-extensions/function-attrs/amd-gcn.rst
c-extensions/function-attrs/arc.rst
c-extensions/function-attrs/arm.rst
c-extensions/function-attrs/avr.rst
c-extensions/function-attrs/blackfin.rst
c-extensions/function-attrs/bpf.rst
c-extensions/function-attrs/c-sky.rst
c-extensions/function-attrs/common.rst
c-extensions/function-attrs/epiphany.rst
c-extensions/function-attrs/h8-300.rst
c-extensions/function-attrs/ia-64.rst
c-extensions/function-attrs/m32c.rst
c-extensions/function-attrs/m32r-d.rst
c-extensions/function-attrs/m68k.rst
c-extensions/function-attrs/mcore.rst
c-extensions/function-attrs/mep.rst
c-extensions/function-attrs/microblaze.rst
c-extensions/function-attrs/microsoft-windows.rst
c-extensions/function-attrs/mips.rst
c-extensions/function-attrs/msp430.rst
c-extensions/function-attrs/nds32.rst
c-extensions/function-attrs/nios-ii.rst
c-extensions/function-attrs/nvidia-ptx.rst
c-extensions/function-attrs/powerpc.rst
c-extensions/function-attrs/risc-v.rst
c-extensions/function-attrs/rl78.rst
c-extensions/function-attrs/rx.rst
c-extensions/function-attrs/s-390.rst
c-extensions/function-attrs/sh.rst
c-extensions/function-attrs/symbian-os.rst
c-extensions/function-attrs/v850.rst
c-extensions/function-attrs/visium.rst
c-extensions/function-attrs/x86.rst
c-extensions/function-attrs/xstormy16.rst
c-extensions/function-attrs.rst
c-extensions/designated-initializers.rst
c-extensions/fn-and-var-alignment.rst
c-extensions/dollar-signs.rst
c-extensions/double-word-integers.rst
c-extensions/enumerator-attributes.rst
c-extensions/fixed-point-types.rst
c-extensions/target-format-checks.rst
c-extensions/function-names-as-strings.rst
c-extensions/fn-frame-address.rst
c-extensions/half-precision-floating-point.rst
c-extensions/hex-floats.rst
c-extensions/inline-assembly.rst
c-extensions/incomplete-enum-types.rst
c-extensions/label-attributes.rst
c-extensions/labels-as-values.rst
c-extensions/legacy-memory-atomics.rst
c-extensions/locally-declared-labels.rst
c-extensions/variadic-macros.rst
c-extensions/mixed-declarations-labels.rst
c-extensions/named-address-spaces.rst
c-extensions/nested-functions.rst
c-extensions/non-constant-initializers.rst
c-extensions/non-lvalue-arrays.rst
c-extensions/nonlocal-gotos.rst
c-extensions/object-size-builtins.rst
c-extensions/other-fn-builtins.rst
c-extensions/pointer-arg-in-var-fns.rst
c-extensions/qualified-array-pointers.rst
c-extensions/pragmas-accepted-by-gcc.rst
c-extensions/prototypes-and-old-style-fns.rst
c-extensions/typeof-reference.rst
c-extensions/escaped-newlines-rules.rst
c-extensions/type-attrs.rst
c-extensions/var-attrs.rst
c-extensions/statement-attributes.rst
c-extensions/statements-decls-in-exprs.rst
c-extensions/structures-with-no-members.rst
c-extensions/support-for-offsetof.rst
c-extensions/target-builtins/aarch64.rst
c-extensions/target-builtins/alpha.rst
c-extensions/target-builtins/altera-nios-ii.rst
c-extensions/target-builtins/arc.rst
c-extensions/target-builtins/arc-simd.rst
c-extensions/target-builtins/arm-armv8-m-sec.rst
c-extensions/target-builtins/arm-acle.rst
c-extensions/target-builtins/arm-fp-and-control.rst
c-extensions/target-builtins/arm-iwmmxt.rst
c-extensions/target-builtins/avr.rst
c-extensions/target-builtins/basic-powerpc.rst
c-extensions/target-builtins/blackfin.rst
c-extensions/target-builtins/bpf.rst
c-extensions/target-builtins/fr-v.rst
c-extensions/target-builtins/mips-dsp.rst
c-extensions/target-builtins/mips-loongson.rst
c-extensions/target-builtins/mips-paired-single.rst
c-extensions/target-builtins/mips-msa.rst
c-extensions/target-builtins/msp430.rst
c-extensions/target-builtins/nds32.rst
c-extensions/target-builtins/other-mips.rst
c-extensions/target-builtins/picochip.rst
c-extensions/target-builtins/powerpc-altivec-vsx.rst
c-extensions/target-builtins/powerpc-atomics.rst
c-extensions/target-builtins/powerpc-hardware-tm.rst
c-extensions/target-builtins/powerpc-matrix.rst
c-extensions/target-builtins/pru.rst
c-extensions/target-builtins/risc-v.rst
c-extensions/target-builtins/rx.rst
c-extensions/target-builtins/s-390-system-z.rst
c-extensions/target-builtins/sh.rst
c-extensions/target-builtins/sparc-vis.rst
c-extensions/target-builtins/ti-c6x.rst
c-extensions/target-builtins/x86.rst
c-extensions/target-builtins/x86-cfp.rst
c-extensions/target-builtins/x86-tm.rst
c-extensions/target-builtins.rst
c-extensions/esc-in-constants.rst
c-extensions/thread-local-storage.rst
c-extensions/unnamed-fields.rst
c-extensions/vector-builtins.rst
c-extensions/volative-access.rst
c-extensions/x86-tm-extensions.rst
./c-extensions.rst
./funding.rst
options/c++-modules.rst
options/compiling-c++-programs.rst
options/description.rst
options/env.rst
options/gcc-developer-options.rst
options/machine/aarch64.rst
options/machine/adapteva-epiphany.rst
options/machine/amd-gcn.rst
options/machine/arc.rst
options/machine/arm.rst
options/machine/avr-mmcu.rst
options/machine/avr.rst
options/machine/blackfin.rst
options/machine/c-sky.rst
options/machine/c6x.rst
options/machine/cris.rst
options/machine/darwin.rst
options/machine/dec-alpha.rst
options/machine/ebpf.rst
options/machine/fr30.rst
options/machine/frv.rst
options/machine/ft32.rst
options/machine/gnu-linux.rst
options/machine/h8-300.rst
options/machine/hppa.rst
options/machine/ia-64.rst
options/machine/ibm-rs-6000.rst
options/machine/lm32.rst
options/machine/loongarch.rst
options/machine/m32c.rst
options/machine/m32r-d.rst
options/machine/m680x0.rst
options/machine/mcore.rst
options/machine/mep.rst
options/machine/microblaze.rst
options/machine/mips.rst
options/machine/mmix.rst
options/machine/mn10300.rst
options/machine/moxie.rst
options/machine/msp430.rst
options/machine/nds32.rst
options/machine/nios-ii.rst
options/machine/nvidia-ptx.rst
options/machine/openrisc.rst
options/machine/options-for-system-v.rst
options/machine/pdp-11.rst
options/machine/picochip.rst
options/machine/powerpc.rst
options/machine/pru.rst
options/machine/risc-v.rst
options/machine/rl78.rst
options/machine/rx.rst
options/machine/s-390-and-zseries.rst
options/machine/score.rst
options/machine/sh.rst
options/machine/solaris-2.rst
options/machine/sparc.rst
options/machine/v850.rst
options/machine/vax.rst
options/machine/visium.rst
options/machine/vms.rst
options/machine/vxworks.rst
options/machine/x86.rst
options/machine/x86-windows.rst
options/machine/xstormy16.rst
options/machine/xtensa.rst
options/machine/zseries.rst
options/machine.rst
options/summary.rst
options/c++.rst
options/c.rst
options/c-c++.rst
options/output.rst
options/preprocessor.rst
options/code-generation.rst
options/debugging.rst
options/directory-search.rst
options/linking.rst
options/optimizations.rst
options/analyzer.rst
options/messages-formatting.rst
options/warnings.rst
options/assembler.rst
options/pgo.rst
options/subprocesses.rst
options/precompiled-headers.rst
./options.rst
./gcc.rst
gcov/gcov-data-format.rst
gcov/cross-profiling.rst
gcov/introduction.rst
gcov/invoking.rst
gcov/freestanding-environments.rst
gcov/optimization.rst
./gcov-dump.rst
./gcov-tool.rst
./gcov.rst
./general-public-license-3.rst
./gnu-free-documentation-license.rst
objc-features/compatibilityalias.rst
objc-features/constant-string-objects.rst
objc-features/exceptions.rst
objc-features/fast-enumeration.rst
objc-features/garbage-collection.rst
objc-features/runtime-api.rst
objc-features/code-before-main.rst
objc-features/messaging-with-runtime.rst
objc-features/synchronization.rst
objc-features/type-encoding.rst
./objc-features.rst
./gnu.rst
./found-bug.rst
./bug-reporting.rst
./get-help.rst
./index.rst
./indices-and-tables.rst
known-trouble/bugs.rst
known-trouble/certain-changes.rst
known-trouble/gnuc-misunderstandings.rst
known-trouble/disappointments.rst
known-trouble/fixed-header-files.rst
known-trouble/incompatibilities.rst
known-trouble/interoperation.rst
known-trouble/standard-libraries.rst
known-trouble/warnings-errors.rst
./known-trouble.rst
standards/c++.rst
standards/c.rst
standards/d.rst
standards/go.rst
standards/objc-objc++.rst
standards/other.rst
./standards.rst
./lto-dump.rst
./supported-languages.rst
./reporting-bugs.rst

Thoughs?

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #8 from Martin Liška <marxin 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:

gcc manual:

TOTAL files: 312
Total LOC: 68643
Average LOC: 220
Median LOC: 104

linux kernel:

TOTAL files: 3198
Total LOC: 649105
Average LOC: 202
Median LOC: 485

godot game engine:

=== TOTAL files: 1262
Total LOC: 308497
Average LOC: 244
Median LOC: 325

coreboot:

=== TOTAL files: 354
Total LOC: 36916
Average LOC: 104
Median LOC: 139

Note the GCC manual contains many target-specific sections and I don't believe
they should be presented at a single HTML page:

extensions-to-the-c-language-family/declaring-attributes-of-functions/ - 35
files
extensions-to-the-c-language-family/target-builtins/ - 36 files
gcc-command-options/machine-dependent-options/ - 62 files

Where I can imagine merging the files are following sub-folders:

extensions-to-the-c++-language/backwards-compatibility.rst [27]
extensions-to-the-c++-language/c++-concepts.rst [44]
extensions-to-the-c++-language/c++-interface-and-implementation-pragmas.rst
[97]
extensions-to-the-c++-language/c++-specific-variable-function-and-type-attributes.rst
[95]
extensions-to-the-c++-language/deprecated-features.rst [43]
extensions-to-the-c++-language/extracting-the-function-pointer-from-a-bound-pointer-to-member-function.rst
[48]
extensions-to-the-c++-language/function-multiversioning.rst [65]
extensions-to-the-c++-language/restricting-pointer-aliasing.rst [52]
extensions-to-the-c++-language/type-traits.rst [165]
extensions-to-the-c++-language/vague-linkage.rst [80]
extensions-to-the-c++-language/when-is-a-volatile-c++-object-accessed.rst [58]
extensions-to-the-c++-language/wheres-the-template.rst [131]
./extensions-to-the-c++-language.rst [34]

c-implementation-defined-behavior/architecture.rst [47]
c-implementation-defined-behavior/arrays-and-pointers.rst [46]
c-implementation-defined-behavior/characters.rst [93]
c-implementation-defined-behavior/declarators.rst [14]
c-implementation-defined-behavior/environment.rst [18]
c-implementation-defined-behavior/floating-point.rst [88]
c-implementation-defined-behavior/hints.rst [35]
c-implementation-defined-behavior/identifiers.rst [28]
c-implementation-defined-behavior/integers.rst [66]
c-implementation-defined-behavior/library-functions.rst [19]
c-implementation-defined-behavior/locale-specific-behavior.rst [12]
c-implementation-defined-behavior/preprocessing-directives.rst [54]
c-implementation-defined-behavior/qualifiers.rst [53]
c-implementation-defined-behavior/statements.rst [14]
c-implementation-defined-behavior/structures-unions-enumerations-and-bit-fields.rst
[78]
c-implementation-defined-behavior/translation.rst [20]
./c-implementation-defined-behavior.rst [46]

gnu-objective-c-features/compatibilityalias.rst [26]
gnu-objective-c-features/constant-string-objects.rst [64]
gnu-objective-c-features/exceptions.rst [79]
gnu-objective-c-features/fast-enumeration.rst [221]
gnu-objective-c-features/garbage-collection.rst [81]
gnu-objective-c-features/gnu-objective-c-runtime-api.rst [98]
gnu-objective-c-features/load-executing-code-before-main.rst [141]
gnu-objective-c-features/messaging-with-the-gnu-objective-c-runtime.rst [145]
gnu-objective-c-features/synchronization.rst [36]
gnu-objective-c-features/type-encoding.rst [280]

known-causes-of-trouble-with-gcc/actual-bugs-we-havent-fixed-yet.rst [14]
known-causes-of-trouble-with-gcc/certain-changes-we-dont-want-to-make.rst [236]
known-causes-of-trouble-with-gcc/common-misunderstandings-with-gnu-c.rst [296]
known-causes-of-trouble-with-gcc/disappointments-and-misunderstandings.rst
[102]
known-causes-of-trouble-with-gcc/fixed-header-files.rst [39]
known-causes-of-trouble-with-gcc/incompatibilities-of-gcc.rst [233]
known-causes-of-trouble-with-gcc/interoperation.rst [153]
known-causes-of-trouble-with-gcc/standard-libraries.rst [33]
known-causes-of-trouble-with-gcc/warning-messages-and-error-messages.rst [46]

language-standards-supported-by-gcc/c++-language.rst [71]
language-standards-supported-by-gcc/c-language.rst [139]
language-standards-supported-by-gcc/d-language.rst [11]
language-standards-supported-by-gcc/go-language.rst [10]
language-standards-supported-by-gcc/objective-c-and-objective-c++-languages.rst
[62]
language-standards-supported-by-gcc/references-for-other-languages.rst [13]

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.

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.

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

--- Comment #9 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
(In reply to Martin Liška from comment #7)


> c-behavior/architecture.rst
> c-behavior/arrays-and-pointers.rst
> c-behavior/characters.rst
> c-behavior/declarators.rst
> c-behavior/environment.rst
> c-behavior/floating-point.rst
> c-behavior/hints.rst
> c-behavior/identifiers.rst
> c-behavior/integers.rst
> c-behavior/library-functions.rst
> c-behavior/locale-specific-behavior.rst
> c-behavior/preprocessing-directives.rst
> c-behavior/qualifiers.rst
> c-behavior/statements.rst
> c-behavior/compount-types.rst
> c-behavior/translation.rst

Is there a way to get C implementation defined behavior in one source file
which gets split up is better? That would make it easier to modify and no need
for the longer file names there.


> ./c++-implementation-defined-behavior.rst
> ./conditionally-supported-behavior.rst
> ./exception-handling.rst

Likewise for the C++ implementation defined behavior which right now you have
listed as on the toplevel when it is not.


> c++-extensions/backwards-compatibility.rst

Just Why not ext instead of extensions (at least remove the s).

> c++-extensions/c++-concepts.rst
concepts

> c++-extensions/interface-and-impl-pragmas.rst

template-pragmas

> c++-extensions/var-and-type-attrs.rst
> c++-extensions/deprecated-features.rst

Just deprecated.

> c++-extensions/function-pointer.rst

func-ptr

> c++-extensions/function-multiversioning.rst

multiversioning

> c++-extensions/restricting-pointer-aliasing.rst

restrict

> c++-extensions/type-traits.rst
> c++-extensions/vague-linkage.rst
> c++-extensions/volatile.rst
> c++-extensions/wheres-the-template.rst
> ./c++-extensions.rst


> c-extensions/128-bit-integers.rst
again c-ext

128bit-int

> c-extensions/additional-floating-types.rst

float-types

> c-extensions/alternate-keywords.rst
> c-extensions/inline-function.rst

inline

> c-extensions/void-fns-arithmetic.rst
void-funcs-addition

> c-extensions/arrays-of-length-zero.rst

zero length arrays

> c-extensions/arrays-of-variable-length.rst
variable length array

> c-extensions/attribute-syntax.rst

attributes

> c-extensions/0b-prefix-arithmetic.rst

0b literals

> c-extensions/memory-model-builtins.rst

atomics

> c-extensions/arithmetic-overflow-builtins.rst
just overflow

> c-extensions/c++-style-comments.rst

line comments

> c-extensions/case-ranges.rst
> c-extensions/cast-to-a-union-type.rst

union-cast

> c-extensions/complex-numbers.rst

complex

> c-extensions/compound-literals.rst
> c-extensions/omitted-operands-conditionals.rst
> c-extensions/constructing-fn-calls.rst
> c-extensions/decimal-floating-types.rst

dfp

> c-extensions/function-attrs/aarch64.rst
> c-extensions/function-attrs/amd-gcn.rst
> c-extensions/function-attrs/arc.rst
> c-extensions/function-attrs/arm.rst
> c-extensions/function-attrs/avr.rst
> c-extensions/function-attrs/blackfin.rst
> c-extensions/function-attrs/bpf.rst
> c-extensions/function-attrs/c-sky.rst
> c-extensions/function-attrs/common.rst
> c-extensions/function-attrs/epiphany.rst
> c-extensions/function-attrs/h8-300.rst
> c-extensions/function-attrs/ia-64.rst
> c-extensions/function-attrs/m32c.rst
> c-extensions/function-attrs/m32r-d.rst
> c-extensions/function-attrs/m68k.rst
> c-extensions/function-attrs/mcore.rst
> c-extensions/function-attrs/mep.rst
> c-extensions/function-attrs/microblaze.rst
> c-extensions/function-attrs/microsoft-windows.rst
> c-extensions/function-attrs/mips.rst
> c-extensions/function-attrs/msp430.rst
> c-extensions/function-attrs/nds32.rst
> c-extensions/function-attrs/nios-ii.rst
> c-extensions/function-attrs/nvidia-ptx.rst
> c-extensions/function-attrs/powerpc.rst
> c-extensions/function-attrs/risc-v.rst
> c-extensions/function-attrs/rl78.rst
> c-extensions/function-attrs/rx.rst
> c-extensions/function-attrs/s-390.rst
> c-extensions/function-attrs/sh.rst
> c-extensions/function-attrs/symbian-os.rst
> c-extensions/function-attrs/v850.rst
> c-extensions/function-attrs/visium.rst
> c-extensions/function-attrs/x86.rst
> c-extensions/function-attrs/xstormy16.rst

target-attr

> c-extensions/function-attrs.rst
> c-extensions/designated-initializers.rst
> c-extensions/fn-and-var-alignment.rst
> c-extensions/dollar-signs.rst
> c-extensions/double-word-integers.rst
> c-extensions/enumerator-attributes.rst
> c-extensions/fixed-point-types.rst
> c-extensions/target-format-checks.rst
> c-extensions/function-names-as-strings.rst
> c-extensions/fn-frame-address.rst
> c-extensions/half-precision-floating-point.rst
> c-extensions/hex-floats.rst
> c-extensions/inline-assembly.rst
> c-extensions/incomplete-enum-types.rst
> c-extensions/label-attributes.rst
> c-extensions/labels-as-values.rst
> c-extensions/legacy-memory-atomics.rst
legacy-sync-atomics

> c-extensions/locally-declared-labels.rst
> c-extensions/variadic-macros.rst
> c-extensions/mixed-declarations-labels.rst
> c-extensions/named-address-spaces.rst
> c-extensions/nested-functions.rst
> c-extensions/non-constant-initializers.rst
> c-extensions/non-lvalue-arrays.rst
> c-extensions/nonlocal-gotos.rst
> c-extensions/object-size-builtins.rst
> c-extensions/other-fn-builtins.rst
> c-extensions/pointer-arg-in-var-fns.rst
> c-extensions/qualified-array-pointers.rst
> c-extensions/pragmas-accepted-by-gcc.rst
> c-extensions/prototypes-and-old-style-fns.rst
> c-extensions/typeof-reference.rst
> c-extensions/escaped-newlines-rules.rst
> c-extensions/type-attrs.rst
> c-extensions/var-attrs.rst
> c-extensions/statement-attributes.rst
> c-extensions/statements-decls-in-exprs.rst
> c-extensions/structures-with-no-members.rst
> c-extensions/support-for-offsetof.rst
> c-extensions/target-builtins/aarch64.rst
> c-extensions/target-builtins/alpha.rst
> c-extensions/target-builtins/altera-nios-ii.rst
> c-extensions/target-builtins/arc.rst
> c-extensions/target-builtins/arc-simd.rst
> c-extensions/target-builtins/arm-armv8-m-sec.rst
> c-extensions/target-builtins/arm-acle.rst
> c-extensions/target-builtins/arm-fp-and-control.rst
> c-extensions/target-builtins/arm-iwmmxt.rst
> c-extensions/target-builtins/avr.rst
> c-extensions/target-builtins/basic-powerpc.rst
> c-extensions/target-builtins/blackfin.rst
> c-extensions/target-builtins/bpf.rst
> c-extensions/target-builtins/fr-v.rst
> c-extensions/target-builtins/mips-dsp.rst
> c-extensions/target-builtins/mips-loongson.rst
> c-extensions/target-builtins/mips-paired-single.rst
> c-extensions/target-builtins/mips-msa.rst
> c-extensions/target-builtins/msp430.rst
> c-extensions/target-builtins/nds32.rst
> c-extensions/target-builtins/other-mips.rst
> c-extensions/target-builtins/picochip.rst
> c-extensions/target-builtins/powerpc-altivec-vsx.rst
> c-extensions/target-builtins/powerpc-atomics.rst
> c-extensions/target-builtins/powerpc-hardware-tm.rst
> c-extensions/target-builtins/powerpc-matrix.rst
> c-extensions/target-builtins/pru.rst
> c-extensions/target-builtins/risc-v.rst
> c-extensions/target-builtins/rx.rst
> c-extensions/target-builtins/s-390-system-z.rst
> c-extensions/target-builtins/sh.rst
> c-extensions/target-builtins/sparc-vis.rst
> c-extensions/target-builtins/ti-c6x.rst
> c-extensions/target-builtins/x86.rst
> c-extensions/target-builtins/x86-cfp.rst
> c-extensions/target-builtins/x86-tm.rst
> c-extensions/target-builtins.rst
> c-extensions/esc-in-constants.rst
> c-extensions/thread-local-storage.rst
> c-extensions/unnamed-fields.rst
> c-extensions/vector-builtins.rst
vector since it has more than the builtins these days

> c-extensions/volative-access.rst
> c-extensions/x86-tm-extensions.rst
> ./c-extensions.rst
> ./funding.rst

> options/c++-modules.rst
> options/compiling-c++-programs.rst
> options/description.rst
> options/env.rst
> options/gcc-developer-options.rst
> options/machine/aarch64.rst
> options/machine/adapteva-epiphany.rst
> options/machine/amd-gcn.rst
> options/machine/arc.rst
> options/machine/arm.rst
> options/machine/avr-mmcu.rst
> options/machine/avr.rst
> options/machine/blackfin.rst
> options/machine/c-sky.rst
> options/machine/c6x.rst
> options/machine/cris.rst
> options/machine/darwin.rst
> options/machine/dec-alpha.rst
> options/machine/ebpf.rst
> options/machine/fr30.rst
> options/machine/frv.rst
> options/machine/ft32.rst
> options/machine/gnu-linux.rst
> options/machine/h8-300.rst
> options/machine/hppa.rst
> options/machine/ia-64.rst
> options/machine/ibm-rs-6000.rst
> options/machine/lm32.rst
> options/machine/loongarch.rst
> options/machine/m32c.rst
> options/machine/m32r-d.rst
> options/machine/m680x0.rst
> options/machine/mcore.rst
> options/machine/mep.rst
> options/machine/microblaze.rst
> options/machine/mips.rst
> options/machine/mmix.rst
> options/machine/mn10300.rst
> options/machine/moxie.rst
> options/machine/msp430.rst
> options/machine/nds32.rst
> options/machine/nios-ii.rst
> options/machine/nvidia-ptx.rst
> options/machine/openrisc.rst
> options/machine/options-for-system-v.rst
> options/machine/pdp-11.rst
> options/machine/picochip.rst
> options/machine/powerpc.rst
> options/machine/pru.rst
> options/machine/risc-v.rst
> options/machine/rl78.rst
> options/machine/rx.rst
> options/machine/s-390-and-zseries.rst
> options/machine/score.rst
> options/machine/sh.rst
> options/machine/solaris-2.rst
> options/machine/sparc.rst
> options/machine/v850.rst
> options/machine/vax.rst
> options/machine/visium.rst
> options/machine/vms.rst
> options/machine/vxworks.rst
> options/machine/x86.rst
> options/machine/x86-windows.rst
> options/machine/xstormy16.rst
> options/machine/xtensa.rst
> options/machine/zseries.rst
target rather than machine (we should figure out some consistency here because
some places uses machine and other uses target).

> options/machine.rst
> options/summary.rst
> options/c++.rst
> options/c.rst
> options/c-c++.rst
> options/output.rst
> options/preprocessor.rst
> options/code-generation.rst
> options/debugging.rst
> options/directory-search.rst
> options/linking.rst
> options/optimizations.rst
> options/analyzer.rst
> options/messages-formatting.rst
> options/warnings.rst
> options/assembler.rst
> options/pgo.rst
> options/subprocesses.rst
> options/precompiled-headers.rst
> ./options.rst
> ./gcc.rst
> gcov/gcov-data-format.rst
> gcov/cross-profiling.rst
> gcov/introduction.rst
> gcov/invoking.rst
> gcov/freestanding-environments.rst
> gcov/optimization.rst
> ./gcov-dump.rst
> ./gcov-tool.rst
> ./gcov.rst
> ./general-public-license-3.rst
> ./gnu-free-documentation-license.rst
> objc-features/compatibilityalias.rst
> objc-features/constant-string-objects.rst
> objc-features/exceptions.rst
> objc-features/fast-enumeration.rst
> objc-features/garbage-collection.rst
> objc-features/runtime-api.rst
> objc-features/code-before-main.rst
> objc-features/messaging-with-runtime.rst
> objc-features/synchronization.rst
> objc-features/type-encoding.rst

Just objc

> ./objc-features.rst
> ./gnu.rst
> ./found-bug.rst
> ./bug-reporting.rst
> ./get-help.rst
> ./index.rst
> ./indices-and-tables.rst
> known-trouble/bugs.rst
> known-trouble/certain-changes.rst
> known-trouble/gnuc-misunderstandings.rst
> known-trouble/disappointments.rst
> known-trouble/fixed-header-files.rst
> known-trouble/incompatibilities.rst
> known-trouble/interoperation.rst
> known-trouble/standard-libraries.rst
> known-trouble/warnings-errors.rst
> ./known-trouble.rst
> standards/c++.rst
> standards/c.rst
> standards/d.rst
> standards/go.rst
> standards/objc-objc++.rst
> standards/other.rst
> ./standards.rst
> ./lto-dump.rst
> ./supported-languages.rst
> ./reporting-bugs.rst
> 
> Thoughs?

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[ebotcazou at gcc dot gnu.org]

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.

[Bug other/107634] Very long filenames and URLs for sphinx-based docs

[marxin at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107634

Martin Liška <marxin at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|---                         |WONTFIX

--- Comment #11 from Martin Liška <marxin at gcc dot gnu.org> ---
The Sphinx documentation has been reverted:
https://gcc.gnu.org/pipermail/gcc/2022-November/239983.html

Thus, I'm closing this as won't fix.