[PATCH+wwwdocs,0/8] A small Texinfo refinement

  Evening,

This patchset includes the requisite changes to gcc-wwwdocs and gcc in
order to produce hopefully more accessible and readable documentation.
For optimal results, please install Texinfo from master (there's
currently no release that includes the few patches I made, the changes
in which this patchset exploit).

This patchset consists of changes that are mostly mechanical, and came
down to reordering @item and @XYZindex commands appropriately.  Attached
to a few commits are pieces of automation that helped the process.

Note that some manuals were not consistent with the rest, specifically
the Ada ones, and so the methods I used weren't applicable to them
without producing massive amounts of unrelated changes.  For the same
reasons as the following paragraph, I have decided to defer those.

I also started doing less mechanical changes, like the @defbuiltin
stuff, but after going over extend.texi I've noticed many sections
that'd need many kinds of slightly different rework, and likely would
require inventing some new convention (for instance, the
instruction-generating built-ins come to mind, there's currently
precedent of documenting them as @example blocks that list them, but
this skips indexing, breaks the flow on text on narrow screens, and is
generally inconsistent with other builtins).  I've decided to halt this
effort for the current release cycle, based on how much time I'll have
until the release.

I am curious about why texinfo.tex was left out of date for so long.  If
there's some reason, please let me know, and I'll see what I can do to
remedy the problem.  From a quick look I presumed there's none and
updated to the latest version.  In the process, I also got rid of the
@gol macro, that was used for conditionally terminating lines, as this
appears to be working around a now-nonexistent bug (and it caused a
build issue on the new texinfo version).

Note, however, that I did not thoroughly test update_web_docs_git
script, as it seems to make a lot of assumptions about the environment
it's invoked in, and so, I couldn't replicate it.  Instead, I tested the
following:

  #!/bin/sh
  set -xe
  MANUALS="cpp
    cppinternals
    fastjar
    gcc
    gccgo
    gccint
    gcj
    gdc
    gfortran
    gfc-internals
    gnat_ugn
    gnat-style
    gnat_rm
    libgomp
    libitm
    libquadmath
    libiberty
    porting"
  
  for file in $MANUALS; do
      rm -rf "${file}.html"
      mkdir "${file}.html"
      texi="$(find /home/arsen/gcc/gcc -name "$file.texi" | head -n 1)"
      [ "$texi" ] || continue
      includes="-I /home/arsen/gcc/gcc/gcc/doc/include"
      includes="$includes -I /home/arsen/gcc/outstuff/include"
      if [ "$file" = gnat_ugn ]; then
          includes="$includes -I /home/arsen/gcc/gcc/gcc/ada"
          includes="$includes -I /home/arsen/gcc/gcc/gcc/ada/doc/gnat_ugn"
      fi
      makeinfo --html -o "${file}.html" $includes \
               --css-ref="/~arsen/final/texinfo-manuals.css" \
               -c TOP_NODE_UP_URL="/~arsen/final/" \
               "$texi"
      makeinfo --pdf -o "${file}.pdf" $includes "$texi"
      makeinfo --dvi -o "${file}.dvi" $includes "$texi"
      makeinfo --info -o "${file}.info" $includes "$texi"
  done

This appeared to produce decent results when I was searching for various
parts I touched.

The output of the script above is visible online:
https://www.aarsen.me/~arsen/final/

This was built against the a8306872ffc91e8d9572a3feedaa125be3c5c1d0
commit in Texinfo.

Thanks in advance, have a lovely night.

=== gcc.git ===

Arsen Arsenović (7):
  docs: Create Indices appendix
  docs: Reorder @opindex to be before corresponding options
  **/*.texi: Reorder index entries
  docs: Mechanically reorder item/index combos in extend.texi
  doc: Add @defbuiltin family of helpers, set documentlanguage
  Update texinfo.tex, remove the @gol macro/alias
  update_web_docs_git: Update CSS reference to new manual CSS

 gcc/d/gdc.texi                         |  144 +-
 gcc/d/implement-d.texi                 |   66 +-
 gcc/doc/cfg.texi                       |   12 +-
 gcc/doc/cpp.texi                       |   12 +-
 gcc/doc/cppdiropts.texi                |   24 +-
 gcc/doc/cppenv.texi                    |    4 +-
 gcc/doc/cppopts.texi                   |   94 +-
 gcc/doc/cppwarnopts.texi               |   14 +-
 gcc/doc/extend.texi                    | 2564 ++++----
 gcc/doc/gcc.texi                       |   36 +-
 gcc/doc/generic.texi                   |    2 +-
 gcc/doc/implement-c.texi               |    2 +-
 gcc/doc/include/gcc-common.texi        |   26 +-
 gcc/doc/include/texinfo.tex            | 7599 +++++++++++++--------
 gcc/doc/install.texi                   |    6 +-
 gcc/doc/invoke.texi                    | 8420 ++++++++++++------------
 gcc/doc/lto.texi                       |    8 +-
 gcc/doc/md.texi                        |   25 +-
 gcc/doc/rtl.texi                       |    8 +-
 gcc/doc/sourcebuild.texi               |    4 -
 gcc/doc/tm.texi                        |    4 +-
 gcc/doc/trouble.texi                   |    8 +-
 gcc/fortran/intrinsic.texi             |  722 +-
 gcc/fortran/invoke.texi                |  394 +-
 gcc/go/gccgo.texi                      |   34 +-
 maintainer-scripts/update_web_docs_git |    2 +-
 26 files changed, 11004 insertions(+), 9230 deletions(-)

=== gcc-wwwdocs.git ===

Arsen Arsenović (1):
  Add revised Texinfo manual CSS

 htdocs/texinfo-manuals.css | 129 +++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 htdocs/texinfo-manuals.css
  

Morning,

Some patches from this patchset appear to have been dropped due to size
limits.  I neglected to compress them last night.  Here they are again:
Alternatively, they're visible on the public-inbox, and can be fetched
from my clone on git.sr.ht:

https://git.sr.ht/~arsen/gcc/log/texinfo_improvements
https://git.sr.ht/~arsen/gcc/commit/7ff7376a83cedfc43ba042ebf82cae106f516e11
https://git.sr.ht/~arsen/gcc/commit/76d9d48fb924f0a575bc46290bf8b3a9329afd28

Apologies for the inconvenience.
  

On Fri, 27 Jan 2023, Arsen Arsenović via Gcc-patches wrote:
> Some patches from this patchset appear to have been dropped due to size
> limits.  I neglected to compress them last night.  Here they are again:

I pushed 2/8 after spot checking the huge patch.

Just 2 out of 970 hunks FAILED (for gcc/doc/invoke.texi). Do you want to 
re-run your script and see what new may have popped up or is missing?

Thanks,
Gerald