Rewrapped and alphabetized the Gnome module.

docs/markdown/Gnome-module.md

@@ -1,68 +1,121 @@
 # GNOME module
 
-This module provides helper tools for build operations needed when building Gnome/GLib programs.
+This module provides helper tools for build operations needed when
+building Gnome/GLib programs.
 
-**Note**: the compilation commands here might not work properly when you change the source files. This is a bug in the respective compilers which do not expose the required dependency information. This has been reported upstream in [this bug]. Until this is fixed you need to be careful when changing your source files.
+**Note**: the compilation commands here might not work properly when
+  you change the source files. This is a bug in the respective
+  compilers which do not expose the required dependency
+  information. This has been reported upstream in [this bug]. Until
+  this is fixed you need to be careful when changing your source
+  files.
 
   [this bug]: https://bugzilla.gnome.org/show_bug.cgi?id=745754
 
 ## Usage
 
-To use this module, just do: **`gnome = import('gnome')`**. The following functions will then be available as methods on the object with the name `gnome`. You can, of course, replace the name `gnome` with anything else.
+To use this module, just do: **`gnome = import('gnome')`**. The
+following functions will then be available as methods on the object
+with the name `gnome`. You can, of course, replace the name `gnome`
+with anything else.
 
 ### gnome.compile_resources()
 
-This function compiles resources specified in an XML file into code that can be embedded inside the main binary. Similar a build target it takes two positional arguments. The first one is the name of the resource and the second is the XML file containing the resource definitions. If the name is `foobar`, Meson will generate a header file called `foobar.h`, which you can then include in your sources.
+This function compiles resources specified in an XML file into code
+that can be embedded inside the main binary. Similar a build target it
+takes two positional arguments. The first one is the name of the
+resource and the second is the XML file containing the resource
+definitions. If the name is `foobar`, Meson will generate a header
+file called `foobar.h`, which you can then include in your sources.
+
+* `c_name`: passed to the resource compiler as an argument after
+  `--c-name`
 
-* `source_dir`: a list of subdirectories where the resource compiler should look up the files, relative to the location of the XML file
-* `c_name`: passed to the resource compiler as an argument after `--c-name`
 * `dependencies`: extra targets to depend upon for building
-* `export`: (*Added 0.37.0*) if true, export the symbols of the generated sources
+
-* `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource` file instead of source
+* `export`: (*Added 0.37.0*) if true, export the symbols of the
-* `install_header`: (*Added 0.37.0*) if true, install the header file
+  generated sources
+
+* `extra_args`: extra command line arguments to pass to the resource
+
+* `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource`
+  file instead of source
+
 * `install`: (*Added 0.37.0*) if true, install the gresource file
-* `install_dir`: (*Added 0.37.0*) location to install the header or bundle depending on previous options
-* `extra_args`: extra command line arguments to pass to the resource compiler
 
-Returns an array containing: `[c_source, header_file]` or `[gresource_bundle]`
+* `install_dir`: (*Added 0.37.0*) location to install the header or
+  bundle depending on previous options
+
+* `install_header`: (*Added 0.37.0*) if true, install the header file
+
+* `source_dir`: a list of subdirectories where the resource compiler
+  should look up the files, relative to the location of the XML file
+
+  compiler
+
+Returns an array containing: `[c_source, header_file]` or
+`[gresource_bundle]`
 
 ### gnome.generate_gir()
 
-Generates GObject introspection data. Takes one positional argument, the build target you want to build gir data for. There are several keyword arguments. Many of these map directly to the `g-ir-scanner` tool so see its documentation for more information.
+Generates GObject introspection data. Takes one positional argument,
+the build target you want to build gir data for. There are several
+keyword arguments. Many of these map directly to the `g-ir-scanner`
+tool so see its documentation for more information.
+
+* `dependencies`: deps to use during introspection scanning
+
+* `extra_args`: command line arguments to pass to gir compiler
+
+* `export_packages`: extra packages the gir file exports
 
 * `sources`: the list of sources to be scanned for gir data
+
 * `nsversion`: namespace version
-* `namespace`: the namespace for this gir object which determines output files
+
-* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`
+* `namespace`: the namespace for this gir object which determines
-* `identifier_prefix`: the identifier prefix for the gir object, e.g. `Gtk`
+  output files
-* `export_packages`: extra packages the gir file exports
+
+* `identifier_prefix`: the identifier prefix for the gir object,
+  e.g. `Gtk`
+
 * `includes`: list of gir names to be included, can also be a GirTarget
-* `dependencies`: deps to use during introspection scanning
+
-* `link_with`: list of libraries to link with
 * `include_directories`: extra include paths to look for gir files
+
 * `install`: if true, install the generated files
-* `install_dir_gir`: (*Added 0.35.0*) which directory to install the gir file into
-* `install_dir_typelib`: (*Added 0.35.0*) which directory to install the typelib file into
-* `extra_args`: command line arguments to pass to gir compiler
 
-Returns an array of two elements which are: `[gir_target, typelib_target]`
+* `install_dir_gir`: (*Added 0.35.0*) which directory to install the
+  gir file into
+
+* `install_dir_typelib`: (*Added 0.35.0*) which directory to install
+  the typelib file into
+
+* `link_with`: list of libraries to link with
+
+* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`
+
+Returns an array of two elements which are: `[gir_target,
+typelib_target]`
 
 ### gnome.genmarshal()
 
-Generates a marshal file using the `glib-genmarshal` tool. The first argument is the basename of
+Generates a marshal file using the `glib-genmarshal` tool. The first
-the output files.
+argument is the basename of the output files.
 
-* `sources`: the list of sources to use as inputs
+* `extra_args`: (*Added 0.42.0*) additional command line arguments to
-* `prefix`: the prefix to use for symbols
+  pass
 * `install_header`: if true, install the generated header
 * `install_dir`: directory to install header to
-* `stdinc`: if true, include the standard marshallers from glib
+* `nostdinc`: if true, don't include the standard marshallers from
-* `nostdinc`: if true, don't include the standard marshallers from glib
+  glib
-* `internal`: if true, mark generated sources as internal
+* `internal`: if true, mark generated sources as internal to
+  `glib-genmarshal` (*Requires GLib 2.54*)
+* `prefix`: the prefix to use for symbols
 * `skip_source`: if true, skip source location comments
+* `stdinc`: if true, include the standard marshallers from glib
+* `sources`: the list of sources to use as inputs
 * `valist_marshallers`: if true, generate va_list marshallers
-* `extra_args`: (*Added 0.42.0*) additional command line arguments to pass
-  to `glib-genmarshal` (*Requires GLib 2.54*)
 
 *Added 0.35.0*
 
@@ -70,23 +123,31 @@ Returns an array of two elements which are: `[c_source, header_file]`
 
 ### gnome.mkenums()
 
-Generates enum files for GObject using the `glib-mkenums` tool. The first argument is the base name of the output files.
+Generates enum files for GObject using the `glib-mkenums` tool. The
+first argument is the base name of the output files.
 
-This method is essentially a wrapper around the `glib-mkenums` tool's command line API. It is the most featureful method for enum creation.
+This method is essentially a wrapper around the `glib-mkenums` tool's
+command line API. It is the most featureful method for enum creation.
 
-Typically you either provide template files or you specify the various template sections manually as strings.
+Typically you either provide template files or you specify the various
+template sections manually as strings.
 
-Most libraries and applications will be using the same standard template with only minor tweaks, in which case the `gnome.mkenums_simple()` convenience method can be used instead.
+Most libraries and applications will be using the same standard
+template with only minor tweaks, in which case the
+`gnome.mkenums_simple()` convenience method can be used instead.
 
-Note that if you `#include` the generated header in any of the sources for a build target, you must add the generated header to the build target's list of sources to codify the dependency. This is true for all generated sources, not just `mkenums`.
+Note that if you `#include` the generated header in any of the sources
+for a build target, you must add the generated header to the build
+target's list of sources to codify the dependency. This is true for
+all generated sources, not just `mkenums`.
 
-* `sources`: the list of sources to make enums with
 * `c_template`: template to use for generating the source
+* `comments`: comment passed to the command
 * `h_template`: template to use for generating the header
+* `identifier_prefix`: prefix to use for the identifiers
 * `install_header`: if true, install the generated header
 * `install_dir`: directory to install the header
-* `comments`: comment passed to the command
+* `sources`: the list of sources to make enums with
-* `identifier_prefix`: prefix to use for the identifiers
 * `symbol_prefix`: prefix to use for the symbols
 * `eprod`: enum text
 * `fhead`: file header
@@ -101,24 +162,31 @@ Returns an array of two elements which are: `[c_source, header_file]`
 
 ### gnome.mkenums_simple()
 
-Generates enum `.c` and `.h` files for GObject using the `glib-mkenums` tool
+Generates enum `.c` and `.h` files for GObject using the
-with the standard template used by most GObject-based C libraries. The first
+`glib-mkenums` tool with the standard template used by most
-argument is the base name of the output files.
+GObject-based C libraries. The first argument is the base name of the
-
+output files.
-Note that if you `#include` the generated header in any of the sources for a
+
-build target, you must add the generated header to the build target's list of
+Note that if you `#include` the generated header in any of the sources
-sources to codify the dependency. This is true for all generated sources, not
+for a build target, you must add the generated header to the build
-just `mkenums_simple`.
+target's list of sources to codify the dependency. This is true for
-
+all generated sources, not just `mkenums_simple`.
-* `sources`: the list of sources to make enums with
+
+* `body_prefix`: additional prefix at the top of the body file,
+  e.g. for extra includes
+* `decorator`: optional decorator for the function declarations,
+  e.g. `GTK_AVAILABLE` or `GST_EXPORT`
+* `function_prefix`: additional prefix for function names, e.g. in
+  case you want to add a leading underscore to functions used only
+  internally
+* `header_prefix`: additional prefix at the top of the header file,
+  e.g. for extra includes (which may be needed if you specify a
+  decorator for the function declarations)
 * `install_header`: if true, install the generated header
 * `install_dir`: directory to install the header
 * `identifier_prefix`: prefix to use for the identifiers
+* `sources`: the list of sources to make enums with
 * `symbol_prefix`: prefix to use for the symbols
-* `header_prefix`: additional prefix at the top of the header file, e.g. for extra includes (which may be needed if you specify a decorator for the function declarations)
-* `decorator`: optional decorator for the function declarations, e.g. `GTK_AVAILABLE` or `GST_EXPORT`
-* `function_prefix`: additional prefix for function names, e.g. in case you want to add a leading underscore to functions used only internally
-* `body_prefix`: additional prefix at the top of the body file, e.g. for extra includes
 
 Example:
 
@@ -144,68 +212,87 @@ Returns an array of two elements which are: `[c_source, header_file]`
 
 ### gnome.compile_schemas()
 
-When called, this method will compile the gschemas in the current directory. Note that this is not
+When called, this method will compile the gschemas in the current
-for installing schemas and is only useful when running the application locally for example during tests.
+directory. Note that this is not for installing schemas and is only
+useful when running the application locally for example during tests.
 
 ### gnome.gdbus_codegen()
 
-Compiles the given XML schema into gdbus source code. Takes two positional arguments, the first one specifies the name of the source files and the second specifies the XML file name. There are three keyword arguments. `interface_prefix` and `namespace` map to corresponding features of the compiler while `object_manager` (since 0.40.0), when set to true, generates object manager code.
+Compiles the given XML schema into gdbus source code. Takes two
+positional arguments, the first one specifies the name of the source
+files and the second specifies the XML file name. There are three
+keyword arguments. `interface_prefix` and `namespace` map to
+corresponding features of the compiler while `object_manager` (since
+0.40.0), when set to true, generates object manager code.
 
-Returns an opaque object containing the source files. Add it to a top level target's source list.
+Returns an opaque object containing the source files. Add it to a top
+level target's source list.
 
 ### gnome.generate_vapi()
 
-Creates a VAPI file from gir. The first argument is the name of the library.
+Creates a VAPI file from gir. The first argument is the name of the
+library.
 
-* `sources`: the gir source to generate the VAPI from
-* `packages`: VAPI packages that are depended upon
-* `metadata_dirs`: extra directories to include for metadata files
 * `gir_dirs`: extra directories to include for gir files
-* `vapi_dirs`: extra directories to include for VAPI files
 * `install`: if true, install the VAPI file
 * `install_dir`: location to install the VAPI file (defaults to datadir/vala/vapi)
+* `metadata_dirs`: extra directories to include for metadata files
+* `packages`: VAPI packages that are depended upon
+* `sources`: the gir source to generate the VAPI from
+* `vapi_dirs`: extra directories to include for VAPI files
 
-Returns a custom dependency that can be included when building other VAPI or Vala binaries.
+Returns a custom dependency that can be included when building other
+VAPI or Vala binaries.
 
 *Added 0.36.0*
 
 ### gnome.yelp()
 
-Installs help documentation using Yelp. The first argument is the project id.
+Installs help documentation using Yelp. The first argument is the
+project id.
 
-This also creates two targets for translations `help-$project-update-po` and `help-$project-pot`.
+This also creates two targets for translations
+`help-$project-update-po` and `help-$project-pot`.
 
-* `sources`: list of pages
+* `languages`: list of languages for translations
 * `media`: list of media such as images
+* `sources`: list of pages
 * `symlink_media`: if media should be symlinked not copied (defaults to `true` since 0.42.0)
-* `languages`: list of languages for translations
 
-Note that very old versions of yelp may not support symlinked media; At least 3.10 should work.
+Note that very old versions of yelp may not support symlinked media;
+At least 3.10 should work.
 
 *Added 0.36.0*
 
 ### gnome.gtkdoc()
 
-Compiles and installs gtkdoc documentation into `prefix/share/gtk-doc/html`. Takes one positional argument: The name of the module.
+Compiles and installs gtkdoc documentation into
+`prefix/share/gtk-doc/html`. Takes one positional argument: The name
+of the module.
 
-* `main_xml`: specifies the main XML file
+* `content_files`: a list of content files
-* `main_sgml`: equal to `main_xml`
-* `src_dir`: include_directories to include
 * `dependencies`: a list of dependencies
-* `install`: if true, installs the generated docs
-* `install_dir`: the directory to install the generated docs relative to the gtk-doc html dir or an absolute path (default: module name)
-* `scan_args`: a list of arguments to pass to `gtkdoc-scan`
-* `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
-* `gobject_typesfile`: a list of type files
 * `fixxref_args`: a list of arguments to pass to `gtkdoc-fixxref`
-* `html_args` a list of arguments to pass to `gtkdoc-mkhtml`
+* `gobject_typesfile`: a list of type files
+* `ignore_headers`: a list of header files to ignore
 * `html_assets`: a list of assets for the HTML pages
-* `content_files`: a list of content files
+* `html_args` a list of arguments to pass to `gtkdoc-mkhtml`
+* `install`: if true, installs the generated docs
+* `install_dir`: the directory to install the generated docs relative
+  to the gtk-doc html dir or an absolute path (default: module name)
+* `main_xml`: specifies the main XML file
+* `main_sgml`: equal to `main_xml`
 * `mkdb_args`: a list of arguments to pass to `gtkdoc-mkdb`
-* `ignore_headers`: a list of header files to ignore
+* `scan_args`: a list of arguments to pass to `gtkdoc-scan`
+* `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
+* `src_dir`: include_directories to include
 
-This creates a `$module-doc` target that can be ran to build docs and normally these are only built on install.
+This creates a `$module-doc` target that can be ran to build docs and
+normally these are only built on install.
 
 ### gnome.gtkdoc_html_dir()
 
-Takes as argument a module name and returns the path where that module's HTML files will be installed. Usually used with `install_data` to install extra files, such as images, to the output directory.
+Takes as argument a module name and returns the path where that
+module's HTML files will be installed. Usually used with
+`install_data` to install extra files, such as images, to the output
+directory.