[gtk/ebassi/rst-man: 1/2] Switch man pages to reStructuredFormat

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/rst-man: 1/2] Switch man pages to reStructuredFormat
Date: Fri, 24 Sep 2021 17:01:20 +0000 (UTC)

commit 2c810c747d5c21161dd5a786101d2017f330c548
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Sep 24 17:54:41 2021 +0100

    Switch man pages to reStructuredFormat
    
    It's easier to write than DocBook, and rst2man is faster than xsltproc.

 docs/reference/gtk/gtk4-broadwayd.rst           | 57 +++++++++++++++++
 docs/reference/gtk/gtk4-builder-tool.rst        | 85 +++++++++++++++++++++++++
 docs/reference/gtk/gtk4-demo-application.rst    | 22 +++++++
 docs/reference/gtk/gtk4-demo.rst                | 48 ++++++++++++++
 docs/reference/gtk/gtk4-encode-symbolic-svg.rst | 40 ++++++++++++
 docs/reference/gtk/gtk4-icon-browser.rst        | 28 ++++++++
 docs/reference/gtk/gtk4-launch.rst              | 50 +++++++++++++++
 docs/reference/gtk/gtk4-query-settings.rst      | 21 ++++++
 docs/reference/gtk/gtk4-update-icon-cache.rst   | 65 +++++++++++++++++++
 docs/reference/gtk/gtk4-widget-factory.rst      | 34 ++++++++++
 docs/reference/gtk/meson.build                  | 49 +++++++-------
 11 files changed, 472 insertions(+), 27 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-broadwayd.rst b/docs/reference/gtk/gtk4-broadwayd.rst
new file mode 100644
index 0000000000..88bd224a5d
--- /dev/null
+++ b/docs/reference/gtk/gtk4-broadwayd.rst
@@ -0,0 +1,57 @@
+.. _gtk4-broadwayd(1):
+
+==============
+gtk4-broadwayd
+==============
+
+---------------------------
+The Broadway display server
+---------------------------
+
+SYNOPSIS
+--------
+|   **gtk4-broadwayd** [OPTIONS...] <DISPLAY>
+|   **gtk4-broadwayd** --port=PORT --address=ADDRESS <DISPLAY>
+|   **gtk4-broadwayd** --unixaddress=ADDRESS <DISPLAY>
+
+
+DESCRIPTION
+-----------
+
+``gtk4-broadwayd`` is a display server for the Broadway GDK backend. It allows
+multiple GTK applications to display their windows in the same web browser, by
+connecting to gtk4-broadwayd.
+
+When using gtk4-broadwayd, specify the display number to use, prefixed with a
+colon, similar to X. The default display number is 0.
+
+::
+
+   gtk4-broadwayd :5
+
+
+Then point your web browser at ``http://127.0.0.1:8085``.
+
+Start your applications like this:
+
+::
+
+   GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo
+
+
+OPTIONS
+-------
+
+``--port PORT``
+
+  Use the given ``PORT`` for the HTTP connection, instead of the default ``8080 + (DISPLAY - 1)``.
+
+``--address ADDRESS``
+
+  Use the given ``address`` for the HTTP connection, instead of the default ``http://127.0.0.1``.
+
+``--unixsocket ADDRESS``
+
+  Use the given ``address`` as the unix domain socket address. This option
+  overrides ``--address`` and ``--port``, and it is available only on Unix-like
+  systems.
diff --git a/docs/reference/gtk/gtk4-builder-tool.rst b/docs/reference/gtk/gtk4-builder-tool.rst
new file mode 100644
index 0000000000..80998a9d96
--- /dev/null
+++ b/docs/reference/gtk/gtk4-builder-tool.rst
@@ -0,0 +1,85 @@
+.. _gtk4-builder-tool(1):
+
+=================
+gtk4-builder-tool
+=================
+
+-----------------------
+GtkBuilder File Utility
+-----------------------
+
+SYNOPSIS
+--------
+|   **gtk4-builder-tool** <COMMAND> [OPTIONS...] <FILE>
+|
+|   **gtk4-builder-tool** validate <FILE>
+|   **gtk4-builder-tool** enumerate <FILE>
+|   **gtk4-builder-tool** simplify [OPTIONS...] <FILE>
+|   **gtk4-builder-tool** preview [OPTIONS...] <FILE>
+
+DESCRIPTION
+-----------
+
+``gtk4-builder-tool`` can perform various operations on GtkBuilder UI definition
+files.
+
+COMMANDS
+--------
+
+Validation
+^^^^^^^^^^
+
+The ``validate`` command validates the given UI definition file and reports
+errors to ``stderr``.
+
+Enumeration
+^^^^^^^^^^^
+
+The ``enumerate`` command lists all the named objects that are present in the UI
+definition file.
+
+Preview
+^^^^^^^
+
+The ``preview`` command displays the UI dfinition file.
+
+This command accepts options to specify the ID of the toplevel object and a CSS
+file to use.
+
+``--id=ID``
+
+  The ID of the object to preview. If not specified, gtk4-builder-tool will
+  choose a suitable object on its own.
+
+``--css=FILE``
+
+  Load style information from the given CSS file.
+
+Simplification
+^^^^^^^^^^^^^^
+
+The ``simplify`` command simplifies the UI definition file by removing
+properties that are set to their default values and writes the resulting XML to
+the standard output, or back to the input file.
+
+When the ``--3to4`` option is specified, the ``simplify`` command interprets the
+input as a GTK 3 UI definuition file and attempts to convert it to GTK 4
+equivalents. It performs various conversions, such as renaming properties,
+translating child properties to layout properties, rewriting the setup for
+GtkNotebook, GtkStack, GtkAssistant  or changing toolbars into boxes.
+
+You should always test the modified UI definition files produced by
+gtk4-builder-tool before using them in production.
+
+Note in particular that the conversion done with ``--3to4`` is meant as a
+starting point for a port from GTK 3 to GTK 4. It is expected that you will have
+to do manual fixups  after the initial conversion.
+
+``--replace``
+
+  Write the content back to the UI definition file instead of using the standard
+  output.
+
+``--3to4``
+
+  Transform a GTK 3 UI definition file to the equivalent GTK 4 definitions.
diff --git a/docs/reference/gtk/gtk4-demo-application.rst b/docs/reference/gtk/gtk4-demo-application.rst
new file mode 100644
index 0000000000..0eb12ee404
--- /dev/null
+++ b/docs/reference/gtk/gtk4-demo-application.rst
@@ -0,0 +1,22 @@
+.. _gtk4-demo-application(1):
+
+=====================
+gtk4-demo-application
+=====================
+
+--------------------------
+Demonstrate GtkApplication
+--------------------------
+
+
+SYNOPSIS
+--------
+|   **gtk4-demo-application**
+
+
+DESCRIPTION
+-----------
+
+``gtk4-demo-application`` is an example application used by ``gtk4-demo``.
+
+There is no need to call it manually.
diff --git a/docs/reference/gtk/gtk4-demo.rst b/docs/reference/gtk/gtk4-demo.rst
new file mode 100644
index 0000000000..e917900988
--- /dev/null
+++ b/docs/reference/gtk/gtk4-demo.rst
@@ -0,0 +1,48 @@
+.. _gtk4-demo(1):
+
+=========
+gtk4-demo
+=========
+
+-----------------------
+Demonstrate GTK widgets
+-----------------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-demo** [OPTIONS...]
+
+DESCRIPTION
+-----------
+
+``gtk4-demo`` is a collection of examples.
+
+Its purpose is to demonstrate many GTK widgets in a form that is useful to
+application developers.
+
+The application shows the source code for each example, as well as other used
+resources, such as UI description files and image assets.
+
+OPTIONS
+-------
+
+``-h, --help``
+
+  Show help options.
+
+``--version``
+
+  Show program version.
+
+``--list``
+
+  List available examples.
+
+``--run EXAMPLE``
+
+  Run the named example. Use ``--list`` to see the available examples.
+
+``--autoquit``
+
+  Quit after a short timeout. This is intended for use with ``--run``, e.g. when profiling.
diff --git a/docs/reference/gtk/gtk4-encode-symbolic-svg.rst b/docs/reference/gtk/gtk4-encode-symbolic-svg.rst
new file mode 100644
index 0000000000..6aedcbede6
--- /dev/null
+++ b/docs/reference/gtk/gtk4-encode-symbolic-svg.rst
@@ -0,0 +1,40 @@
+.. _gtk4-encode-symbolic-svg(1):
+
+========================
+gtk4-encode-symbolic-svg
+========================
+
+--------------------------------
+Symbolic icon conversion utility
+--------------------------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-encode-symbolic-svg** [OPTIONS...] <PATH> <WIDTH>x<HEIGHT>
+
+DESCRIPTION
+-----------
+
+``gtk4-encode-symbolic-svg`` converts symbolic SVG icons into specially prepared
+PNG files. GTK can load and recolor these PNGs, just like original SVGs, but
+loading them is much faster.
+
+``PATH`` is the name of a symbolic SVG file, ``WIDTH`` x ``HEIGHT`` are the
+desired dimensions for the generated PNG file.
+
+To distinguish them from ordinary PNGs, the generated files have the extension
+``.symbolic.png``.
+
+OPTIONS
+-------
+
+``-o, --output DIRECTORY``
+
+  Write png files to ``DIRECTORY`` instead of the current working directory.
+
+``--debug``
+
+  Generate PNG files of the various channels during the conversion. If these
+  files are not monochrome green, they are often helpful in pinpointing the
+  problematic parts of the source SVG.
diff --git a/docs/reference/gtk/gtk4-icon-browser.rst b/docs/reference/gtk/gtk4-icon-browser.rst
new file mode 100644
index 0000000000..683b3f3054
--- /dev/null
+++ b/docs/reference/gtk/gtk4-icon-browser.rst
@@ -0,0 +1,28 @@
+.. _gtk4-icon-browser(1):
+
+=================
+gtk4-icon-browser
+=================
+
+-----------------
+List themed icons
+-----------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-icon-browser** [OPTIONS...]
+
+DESCRIPTION
+-----------
+
+``gtk4-icon-browser`` is a utility to explore the icons in the current icon
+theme. It shows icons in various sizes, their symbolic variants where available,
+as well as a description of the icon and its context.
+
+OPTIONS
+-------
+
+``-h, --help``
+
+  Show the application help.
diff --git a/docs/reference/gtk/gtk4-launch.rst b/docs/reference/gtk/gtk4-launch.rst
new file mode 100644
index 0000000000..526df727b4
--- /dev/null
+++ b/docs/reference/gtk/gtk4-launch.rst
@@ -0,0 +1,50 @@
+.. _gtk4-launch(1):
+
+===========
+gtk4-launch
+===========
+
+---------------------
+Launch an application
+---------------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-launch** [OPTIONS...] <APPLICATION> [URI...]
+
+DESCRIPTION
+-----------
+
+``gtk4-launch`` launches an application using the given name. The application is
+started with proper startup notification on a default display, unless specified
+otherwise.
+
+``gtk4-launch`` takes at least one argument, the name of the application to
+launch. The name should match application desktop file name, as residing in the
+applications subdirectories of the XDG data directories, with or without the
+``.desktop`` suffix.
+
+If called with more than one argument, the rest of them besides the application
+name are considered URI locations and are passed as arguments to the launched
+application.
+
+OPTIONS
+-------
+
+``-?, -h, --help``
+
+  Print the command's help and exit.
+
+``--version``
+
+  Print the command's version and exit.
+
+ENVIRONMENT
+-----------
+
+Some environment variables affect the behavior of ``gtk4-launch``:
+
+``XDG_DATA_HOME, XDG_DATA_DIRS``
+
+  The environment variables specifying the XDG data directories.
diff --git a/docs/reference/gtk/gtk4-query-settings.rst b/docs/reference/gtk/gtk4-query-settings.rst
new file mode 100644
index 0000000000..3e16b3a758
--- /dev/null
+++ b/docs/reference/gtk/gtk4-query-settings.rst
@@ -0,0 +1,21 @@
+.. _gtk4-query-settings(1):
+
+===================
+gtk4-query-settings
+===================
+
+------------------------------------
+Print name and value of GTK settings
+------------------------------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-query-settings** [PATTERN]
+
+DESCRIPTION
+-----------
+
+``gtk4-query-settings`` prints both name and value of all properties available
+in the ``GtkSettings`` class. Optionally, you can filter which properties to
+list by specifying a ``PATTERN``.
diff --git a/docs/reference/gtk/gtk4-update-icon-cache.rst b/docs/reference/gtk/gtk4-update-icon-cache.rst
new file mode 100644
index 0000000000..2ee1f14a06
--- /dev/null
+++ b/docs/reference/gtk/gtk4-update-icon-cache.rst
@@ -0,0 +1,65 @@
+.. _gtk4-update-icon-cache(1):
+
+======================
+gtk4-update-icon-cache
+======================
+
+--------------------------
+Icon theme caching utility
+--------------------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-update-icon-cache** [OPTIONS...] <PATH>
+
+DESCRIPTION
+-----------
+
+``gtk4-update-icon-cache`` creates ``mmap(2)``-able cache files for icon themes.
+
+It expects to be given the ``PATH`` to an icon theme directory containing an
+``index.theme``, e.g. ``/usr/share/icons/hicolor``, and writes a
+``icon-theme.cache`` containing cached information about the icons in the
+directory tree below the given directory.
+
+GTK can use the cache files created by ``gtk4-update-icon-cache`` to avoid a lot
+of system call and disk seek overhead when the application starts. Since the
+format of the cache files allows them to be shared across multiple processes,
+for instance using the POSIX ``mmap(2)`` system call, the overall memory
+consumption is reduced as well.
+
+OPTIONS
+-------
+
+``-f, --force``
+
+  Overwrite an existing cache file even if it appears to be up-to-date.
+
+``-t, --ignore-theme-index``
+
+  Don't check for the existence of ``index.theme`` in the icon theme directory.
+  Without this option, ``gtk4-update-icon-cache`` refuses to create an icon
+  cache in a directory which does not appear to be the toplevel directory of an
+  icon theme.
+
+``-i, --index-only``
+
+  Don't include image data in the cache.
+
+``--include-image-data``
+
+  Include image data in the cache.
+
+``-c, --source <NAME>``
+
+  Output a C header file declaring a constant ``NAME`` with the contents of the
+  icon cache.
+
+``-q, --quiet``
+
+  Turn off verbose output.
+
+``-v, --validate``
+
+  Validate existing icon cache.
diff --git a/docs/reference/gtk/gtk4-widget-factory.rst b/docs/reference/gtk/gtk4-widget-factory.rst
new file mode 100644
index 0000000000..a8d23139ec
--- /dev/null
+++ b/docs/reference/gtk/gtk4-widget-factory.rst
@@ -0,0 +1,34 @@
+.. _gtk4-widget-factory(1):
+
+===================
+gtk4-widget-factory
+===================
+
+-------------------------------
+Showcase GTK widgets and styles
+-------------------------------
+
+SYNOPSIS
+--------
+
+|   **gtk4-widget-factory** [OPTIONS...]
+
+DESCRIPTION
+-----------
+
+``gtk4-widget-factory`` is a collection of examples.
+
+Its purpose is to demonstrate many GTK widgets in a form that is useful to GTK theme developers.
+
+The application shows widgets in different, typical combinations and states.
+
+OPTIONS
+-------
+
+``-h, --help``
+
+  Show the application help.
+
+``--version``
+
+  Show the application version.
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index 65873e5202..7ae01f0451 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -59,24 +59,15 @@ if get_option('gtk_doc')
   )
 endif
 
-xsltproc = find_program('xsltproc', required: false)
-if get_option('man-pages') and not xsltproc.found()
-  error('No xsltproc found, but man pages were explicitly enabled')
+rst2man = find_program('rst2man', required: false)
+if get_option('man-pages') and not rst2man.found()
+  error('No rst2man found, but man pages were explicitly enabled')
 endif
 
-if get_option('man-pages') and xsltproc.found()
-  xlstproc_flags = [
-    '--nonet',
-    '--stringparam', 'man.output.quietly', '1',
-    '--stringparam', 'funcsynopsis.style', 'ansi',
-    '--stringparam', 'man.th.extra1.suppress', '1',
-    '--stringparam', 'man.authors.section.enabled', '0',
-    '--stringparam', 'man.copyright.section.enabled', '0',
-  ]
-
-  man_files = [
-    [ 'gtk4-broadwayd', '1', ],
-    [ 'gtk4-builder-tool', '1', ],
+if get_option('man-pages') and rst2man.found()
+  rst_files = [
+    [ 'gtk4-broadwayd', '1' ],
+    [ 'gtk4-builder-tool', '1' ],
     [ 'gtk4-encode-symbolic-svg', '1', ],
     [ 'gtk4-launch', '1', ],
     [ 'gtk4-query-settings', '1', ],
@@ -84,7 +75,7 @@ if get_option('man-pages') and xsltproc.found()
   ]
 
   if get_option('demos')
-    man_files += [
+    rst_files += [
       [ 'gtk4-demo', '1', ],
       [ 'gtk4-demo-application', '1', ],
       [ 'gtk4-widget-factory', '1', ],
@@ -92,21 +83,25 @@ if get_option('man-pages') and xsltproc.found()
     ]
   endif
 
-  foreach man: man_files
-    man_name = man.get(0)
-    man_section = man.get(1, '1')
-    custom_target('@0@.@1@'.format(man_name, man_section),
-      input: '@0@.xml'.format(man_name),
+  rst2man_flags = [
+    '--syntax-highlight=none',
+  ]
+
+  foreach rst: rst_files
+    man_name = rst[0]
+    man_section = rst.get(1, '1')
+
+    custom_target('man-@0@'.format(man_name),
+      input: '@0@.rst'.format(man_name),
       output: '@0@.@1@'.format(man_name, man_section),
       command: [
-        xsltproc,
-        xlstproc_flags,
-        '-o', '@OUTPUT@',
-        'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
+        rst2man,
+        rst2man_flags,
         '@INPUT@',
       ],
+      capture: true,
       install: true,
-      install_dir: join_paths(get_option('mandir'), 'man@0@'.format(man_section)),
+      install_dir: get_option('mandir') / 'man@0@'.format(man_section),
     )
   endforeach
 endif
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]