Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Switch man pages to reStructuredFormat

Browse Source 
It's easier to write than DocBook, and rst2man is faster than xsltproc.
This commit is contained in:
Emmanuele Bassi
2021-09-24 17:54:41 +01:00
parent a74d90891a
commit 2c810c747d
11 changed files with 472 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
docs/reference/gtk/gtk4-broadwayd.rst Normal file
View File

@@ -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.

85
docs/reference/gtk/gtk4-builder-tool.rst Normal file
View File

@@ -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.

22
docs/reference/gtk/gtk4-demo-application.rst Normal file
View File

@@ -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.

48
docs/reference/gtk/gtk4-demo.rst Normal file
View File

@@ -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.

40
docs/reference/gtk/gtk4-encode-symbolic-svg.rst Normal file
View File

@@ -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.

28
docs/reference/gtk/gtk4-icon-browser.rst Normal file
View File

@@ -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.

50
docs/reference/gtk/gtk4-launch.rst Normal file
View File

@@ -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.

21
docs/reference/gtk/gtk4-query-settings.rst Normal file
View File

@@ -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``.

65
docs/reference/gtk/gtk4-update-icon-cache.rst Normal file
View File

@@ -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.

34
docs/reference/gtk/gtk4-widget-factory.rst Normal file
View File

@@ -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.

49
docs/reference/gtk/meson.build
View File

@@ -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