Retitle gi-* man pages and update content

gi-compile-repository --module and gi-decompile-typelib --shlib are
intentionally undocumented here: they will be removed in !3926.

Signed-off-by: Simon McVittie <smcv@collabora.com>

docs/reference/girepository/gi-compile-repository.rst

@@ -7,6 +7,7 @@
    :copyright: Copyright 2018 Tomasz Miąsko
    :copyright: Copyright 2018 Christoph Reiter
    :copyright: Copyright 2020 Jan Tojnar
+   :copyright: Copyright 2024 Collabora Ltd.
    :license: LGPL-2.1-or-later
 ..
    This has to be duplicated from above to make it machine-readable by `reuse`:
@@ -17,11 +18,12 @@
    SPDX-FileCopyrightText: 2018 Tomasz Miąsko
    SPDX-FileCopyrightText: 2018 Christoph Reiter
    SPDX-FileCopyrightText: 2020 Jan Tojnar
+   SPDX-FileCopyrightText: 2024 Collabora Ltd.
    SPDX-License-Identifier: LGPL-2.1-or-later
 
-=============
+=====================
-g-ir-compiler
+gi-compile-repository
-=============
+=====================
 
 ----------------
 Typelib compiler
@@ -33,51 +35,53 @@ Typelib compiler
 SYNOPSIS
 ========
 
-**g-ir-compiler** [OPTION...] GIRFILE
+**gi-compile-repository** [*OPTION*…] *GIRFILE*
 
 
 DESCRIPTION
 ===========
 
-g-ir-compiler converts one or more GIR files into one or more typelib. The
+gi-compile-repository converts one or more GIR files into one or more typelibs.
-output will be written to standard output unless the ``--output`` is
+The output will be written to standard output unless the ``--output`` is
 specified.
 
 
 OPTIONS
 =======
 
---help
+``--help``
-    Show help options
+    Show help options.
 
---output=FILENAME
+``--output`` *FILENAME*, ``-o`` *FILENAME*
-    Save the resulting output in FILENAME.
+    Save the resulting output in *FILENAME*.
 
---verbose
+``--verbose``
-    Show verbose messages
+    Show verbose messages.
 
---debug
+``--debug``
-    Show debug messages
+    Show debug messages.
 
---includedir=DIRECTORY
+``--includedir`` *DIRECTORY*
-    Adds a directory which will be used to find includes inside the GIR format.
+    Add *DIRECTORY* to the search path for GIR XML.
+    This option can be used more than once.
+    The first *DIRECTORY* on the command-line will be searched first
+    (highest precedence).
 
---module=MODULE
+``--shared-library`` *FILENAME*, ``-l`` *FILENAME*
-    FIXME
-
---shared-library=FILENAME
     Specifies the shared library where the symbols in the typelib can be
     found. The name of the library should not contain the ending shared
     library suffix.
+    This option can be used more than once, for typelibs that describe
+    more than one shared library.
 
---version
+``--version``
-    Show program's version number and exit
+    Show program’s version number and exit.
 
 
 BUGS
 ====
 
-Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues
+Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
 
 
 HOMEPAGE and CONTACT

docs/reference/girepository/gi-decompile-typelib.rst

@@ -6,6 +6,7 @@
    :copyright: Copyright 2018 Tomasz Miąsko
    :copyright: Copyright 2018 Christoph Reiter
    :copyright: Copyright 2020 Jan Tojnar
+   :copyright: Copyright 2024 Collabora Ltd.
    :license: LGPL-2.1-or-later
 ..
    This has to be duplicated from above to make it machine-readable by `reuse`:
@@ -15,15 +16,16 @@
    SPDX-FileCopyrightText: 2018 Tomasz Miąsko
    SPDX-FileCopyrightText: 2018 Christoph Reiter
    SPDX-FileCopyrightText: 2020 Jan Tojnar
+   SPDX-FileCopyrightText: 2024 Collabora Ltd.
    SPDX-License-Identifier: LGPL-2.1-or-later
 
-=============
+====================
-g-ir-generate
+gi-decompile-typelib
-=============
+====================
 
------------------
+------------------
-Typelib generator
+Typelib decompiler
------------------
+------------------
 
 :Manual section: 1
 
@@ -31,37 +33,52 @@ Typelib generator
 SYNOPSIS
 ========
 
-**g-ir-generate** [OPTION...] FILES...
+**gi-decompile-typelib** [*OPTION*…] *TYPELIB* [*TYPELIB*\ …]
 
 
 DESCRIPTION
 ===========
 
-g-ir-generate is an GIR generator, using the repository API. It generates GIR
+gi-decompile-typelib is a GIR decompiler, using the repository API.
-files from a raw typelib or in a shared library (``--shlib``). The output will
+It generates GIR XML files from the compiled binary typelib format.
-be written to standard output unless the ``--output`` is specified.
+The output will be written to standard output unless the ``--output``
+is specified.
+
+The binary typelib format stores a subset of the information available
+in GIR XML, so not all typelibs can be decompiled in this way, and the
+resulting GIR XML might be incomplete.
+
+Normally, GIR XML should be generated from source code, headers and
+shared libraries using `g-ir-scanner(1) <man:g-ir-scanner(1)>`_
+instead of using this tool.
 
 
 OPTIONS
 =======
 
---help
+``--help``
-    Show help options
+    Show help options.
 
---shlib=FILENAME
+``--output`` *FILENAME*, ``-o`` *FILENAME*
-    The shared library to read the symbols from.
+    Save the resulting output in *FILENAME*.
 
---output=FILENAME
+``--includedir`` *DIRECTORY*
-    Save the resulting output in FILENAME.
+    Add *DIRECTORY* to the search path for typelibs.
+    This option can be used more than once.
+    The first *DIRECTORY* on the command-line will be searched first
+    (highest precedence).
 
---version
+``--all``
-    Show program's version number and exit
+    Show all available information.
+
+``--version``
+    Show program’s version number and exit.
 
 
 BUGS
 ====
 
-Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues
+Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
 
 
 HOMEPAGE and CONTACT