Merge branch 'wip/smcv/gir-man-pages' into 'main'

Add man pages for gi-* tools

Closes #3260 and gobject-introspection#55

See merge request GNOME/glib!3924

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

@@ -0,0 +1,103 @@
+.. _gi-compile-repository(1):
+.. meta::
+   :copyright: Copyright 2010 Johan Dahlin
+   :copyright: Copyright 2015 Ben Boeckel
+   :copyright: Copyright 2013, 2015 Dieter Verfaillie
+   :copyright: Copyright 2018 Emmanuele Bassi
+   :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`:
+   SPDX-FileCopyrightText: 2010 Johan Dahlin
+   SPDX-FileCopyrightText: 2015 Ben Boeckel
+   SPDX-FileCopyrightText: 2013, 2015 Dieter Verfaillie
+   SPDX-FileCopyrightText: 2018 Emmanuele Bassi
+   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
+
+=====================
+gi-compile-repository
+=====================
+
+----------------
+Typelib compiler
+----------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**gi-compile-repository** [*OPTION*…] *GIRFILE*
+
+
+DESCRIPTION
+===========
+
+gi-compile-repository converts one or more GIR files into one or more typelibs.
+The output will be written to standard output unless the ``--output`` is
+specified.
+
+
+OPTIONS
+=======
+
+``--help``
+    Show help options.
+
+``--output`` *FILENAME*, ``-o`` *FILENAME*
+    Save the resulting output in *FILENAME*.
+
+``--verbose``
+    Show verbose messages.
+
+``--debug``
+    Show debug messages.
+
+``--includedir`` *DIRECTORY*
+    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).
+
+``--shared-library`` *FILENAME*, ``-l`` *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``
+    Show program’s version number and exit.
+
+
+EXAMPLE
+=======
+
+::
+    $ gi-compile-repository -o Gio-2.0.typelib /usr/share/gir-1.0/Gio-2.0.gir
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+https://gi.readthedocs.io/
+
+
+AUTHORS
+=======
+
+Matthias Clasen

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

@@ -0,0 +1,107 @@
+.. _gi-decompile-typelib(1):
+.. meta::
+   :copyright: Copyright 2008, 2010 Johan Dahlin
+   :copyright: Copyright 2014 Robert Roth
+   :copyright: Copyright 2015 Dieter Verfaillie
+   :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`:
+   SPDX-FileCopyrightText: 2008, 2010 Johan Dahlin
+   SPDX-FileCopyrightText: 2014 Robert Roth
+   SPDX-FileCopyrightText: 2015 Dieter Verfaillie
+   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
+
+====================
+gi-decompile-typelib
+====================
+
+------------------
+Typelib decompiler
+------------------
+
+:Manual section: 1
+
+
+SYNOPSIS
+========
+
+**gi-decompile-typelib** [*OPTION*…] *TYPELIB* [*TYPELIB*\ …]
+
+
+DESCRIPTION
+===========
+
+gi-decompile-typelib is a GIR decompiler, using the repository API.
+It generates GIR XML files from the compiled binary typelib format.
+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``
+    Show help options.
+
+``--output`` *FILENAME*, ``-o`` *FILENAME*
+    Save the resulting output in *FILENAME*.
+
+``--includedir`` *DIRECTORY*
+    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).
+
+``--all``
+    Show all available information.
+
+``--version``
+    Show program’s version number and exit.
+
+
+EXAMPLE
+=======
+
+::
+    $ libdir=/usr/lib/x86_64-linux-gnu     # or /usr/lib64 or similar
+    $ gi-decompile-typelib -o Gio-2.0.gir \
+      $libdir/girepository-1.0/Gio-2.0.typelib
+
+    $ diff -u /usr/share/gir-1.0/Gio-2.0.gir Gio-2.0.gir
+
+You will see that the original GIR XML contains much more information
+than the decompiled typelib.
+
+
+BUGS
+====
+
+Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
+
+
+HOMEPAGE and CONTACT
+====================
+
+https://gi.readthedocs.io/
+
+
+AUTHORS
+=======
+
+Matthias Clasen

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

@@ -0,0 +1,58 @@
+.. _gio(1):
+.. meta::
+   :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`:
+   SPDX-FileCopyrightText: 2024 Collabora Ltd.
+   SPDX-License-Identifier: LGPL-2.1-or-later
+
+==================
+gi-inspect-typelib
+==================
+
+-----------------------
+Typelib inspection tool
+-----------------------
+
+SYNOPSIS
+--------
+
+| **gi-inspect-typelib** [*OPTION*\ …] **--print-shlibs** *NAMESPACE*
+| **gi-inspect-typelib** [*OPTION*\ …] **--print-typelibs** *NAMESPACE*
+
+DESCRIPTION
+-----------
+
+**gi-inspect-typelib** displays information about GObject-Introspection
+binary typelib files.
+
+OPTIONS
+-------
+
+``--print-shlibs``
+    Show the shared libraries that implement the *NAMESPACE*.
+
+``--print-typelibs``
+    Show the other typelibs that the *NAMESPACE* depends on.
+
+``--typelib-version``
+    The version of each *NAMESPACE* to inspect.
+    For example, the version of ``Gio-2.0.typelib`` is ``2.0``.
+    If not specified, use the newest available version if there is more
+    than one installed.
+
+EXAMPLE
+-------
+
+On Linux, the ``Gio-2.0`` typelib is implemented by ``libgio-2.0.so.0``::
+
+    $ gi-inspect-typelib --typelib-version 2.0 --print-shlibs Gio
+    shlib: libgio-2.0.so.0
+
+and it depends on GObject-2.0, GLib-2.0 and GModule-2.0::
+
+    $ gi-inspect-typelib --typelib-version 2.0 --print-typelibs Gio
+    typelib: GObject-2.0
+    typelib: GLib-2.0
+    typelib: GModule-2.0

docs/reference/girepository/meson.build

@@ -1,3 +1,26 @@
+if get_option('man-pages').enabled()
+  manpages = [
+    'gi-compile-repository',
+    'gi-decompile-typelib',
+    'gi-inspect-typelib',
+  ]
+  foreach page : manpages
+    custom_target(page + '-man',
+      input: page + '.rst',
+      output: page + '.1',
+      command: [
+        rst2man,
+        rst2man_flags,
+        '@INPUT@',
+      ],
+      capture: true,
+      install: true,
+      install_dir: man1_dir,
+      install_tag: 'doc',
+    )
+  endforeach
+endif
+
 if get_option('documentation') and enable_gir
   expand_content_files = [
     'migrating-gi.md',