diff options
author | Emmanuele Bassi <ebassi@gnome.org> | 2021-09-24 17:54:41 +0100 |
---|---|---|
committer | Emmanuele Bassi <ebassi@gnome.org> | 2021-09-24 18:01:00 +0100 |
commit | 2c810c747d5c21161dd5a786101d2017f330c548 (patch) | |
tree | 71b46fd7ba0089dc94c354f2e810fcce47f3b97f | |
parent | a74d90891a0bddd8e4f46ce689aab0505d1662e8 (diff) | |
download | gtk+-2c810c747d5c21161dd5a786101d2017f330c548.tar.gz |
Switch man pages to reStructuredFormat
It's easier to write than DocBook, and rst2man is faster than xsltproc.
-rw-r--r-- | docs/reference/gtk/gtk4-broadwayd.rst | 57 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-builder-tool.rst | 85 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-demo-application.rst | 22 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-demo.rst | 48 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-encode-symbolic-svg.rst | 40 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-icon-browser.rst | 28 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-launch.rst | 50 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-query-settings.rst | 21 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-update-icon-cache.rst | 65 | ||||
-rw-r--r-- | docs/reference/gtk/gtk4-widget-factory.rst | 34 | ||||
-rw-r--r-- | 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 |