Import Upstream version 2.72.4

.clang-format

@@ -0,0 +1,11 @@
+# See https://wiki.apertis.org/Guidelines/Coding_conventions#Code_formatting
+BasedOnStyle: GNU
+AlwaysBreakAfterDefinitionReturnType: All
+BreakBeforeBinaryOperators: None
+BinPackParameters: false
+SpaceAfterCStyleCast: true
+# Our column limit is actually 80, but setting that results in clang-format
+# making a lot of dubious hanging-indent choices; disable it and assume the
+# developer will line wrap appropriately. clang-format will still check
+# existing hanging indents.
+ColumnLimit: 0

.dir-locals.el

@@ -0,0 +1 @@
+((c-mode . ((indent-tabs-mode . nil)))))

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+
+[*.[ch]]
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+# For the legacy tabs which still exist in the code:
+tab_width = 8
+
+[meson.build]
+indent_size = 2
+indent_style = space
+

AUTHORS

@@ -0,0 +1,40 @@
+Below are just a few of the people who have contributed
+to GLib. Please don't mail these people about problems you
+have with GLib; see the README.md file for information about
+filing bugs and submitting changes.
+
+GLib-2.0 Team
+-------------
+Hans Breuer        <hans@breuer.org>
+Matthias Clasen    <mclasen@redhat.com>
+Tor Lillqvist      <tml@iki.fi>
+Tim Janik          <timj@gtk.org>
+Havoc Pennington   <hp@redhat.com> 
+Ron Steinke        <rsteinke@w-link.net>
+Owen Taylor        <otaylor@redhat.com>
+Sebastian Wilhelmi <seppi@seppi.de>
+
+GLib-1.2 Team
+-------------
+Shawn T. Amundson  <amundson@gimp.org>
+Jeff Garzik        <jgarzik@pobox.com>
+Raja R Harinath    <harinath@cs.umn.edu>
+Tim Janik          <timj@gtk.org>
+Elliot Lee         <sopwith@redhat.com>
+Tor Lillqvist      <tml@iki.fi>
+Paolo Molaro       <lupus@debian.org>
+Havoc Pennington   <hp@pobox.com>
+Manish Singh       <yosh@gimp.org>
+Owen Taylor        <otaylor@gtk.org>
+Sebastian Wilhelmi <wilhelmi@ira.uka.de>
+
+The random number generator "Mersenne Twister", which is used by GLib,
+was developed and originally coded by:
+Makoto Matsumoto   <matumoto@math.keio.ac.jp>
+Takuji Nishimura   <nisimura@math.keio.ac.jp>
+
+Original Authors
+----------------
+Peter Mattis       <petm@xcf.berkeley.edu>
+Spencer Kimball    <spencer@xcf.berkeley.edu>
+Josh MacDonald     <jmacd@xcf.berkeley.edu>

CONTRIBUTING.md

@@ -0,0 +1,274 @@
+# Contribution guidelines
+
+Thank you for considering contributing to the GLib project!
+
+These guidelines are meant for new contributors, regardless of their level
+of proficiency; following them allows the core developers of the GLib project to
+more effectively evaluate your contribution, and provide prompt feedback to
+you. Additionally, by following these guidelines you clearly communicate
+that you respect the time and effort that the people developing GLib put into
+managing the project.
+
+GLib is a complex free software utility library, and it would not exist without
+contributions from the free and open source software community. There are
+many things that we value:
+
+ - bug reporting and fixing
+ - documentation and examples
+ - tests
+ - testing and support for other platforms
+ - new features
+
+Please, do not use the issue tracker for support questions. If you have
+questions on how to use GLib effectively, you can use:
+
+ - the `#gtk` IRC channel on irc.gnome.org
+ - the [`glib` tag on GNOME's Discourse](https://discourse.gnome.org/tags/glib)
+
+You can also look at the [`glib` tag on Stack
+Overflow](https://stackoverflow.com/questions/tagged/glib).
+
+The issue tracker is meant to be used for actionable issues only.
+
+## How to report bugs
+
+### Security issues
+
+You should not open a new issue for security related questions.
+
+When in doubt, send an email to the [security](mailto:security@gnome.org)
+mailing list.
+
+### Bug reports
+
+If you’re reporting a bug make sure to list:
+
+ 0. which version of GLib are you using?
+ 0. which operating system are you using?
+ 0. the necessary steps to reproduce the issue
+ 0. the expected outcome
+ 0. a description of the behavior
+ 0. a small, self-contained example exhibiting the behavior
+
+If the issue includes a crash, you should also include:
+
+ 0. the eventual warnings printed on the terminal
+ 0. a backtrace, obtained with tools such as GDB or LLDB
+
+If the issue includes a memory leak, you should also include:
+
+ 0. a log of definite leaks from a tool such as [valgrind’s
+    memcheck](http://valgrind.org/docs/manual/mc-manual.html)
+
+For small issues, such as:
+
+ - spelling/grammar fixes in the documentation,
+ - typo correction,
+ - comment clean ups,
+ - changes to metadata files (CI, `.gitignore`),
+ - build system changes, or
+ - source tree clean ups and reorganizations;
+
+or for self-contained bug fixes where you have implemented and tested a solution
+already, you should directly open a merge request instead of filing a new issue.
+
+### Features and enhancements
+
+Feature discussion can be open ended and require high bandwidth channels; if
+you are proposing a new feature on the issue tracker, make sure to make
+an actionable proposal, and list:
+
+ 0. what you’re trying to achieve and the problem it solves
+ 0. three (or more) existing pieces of software which would benefit from the
+    new feature
+ 0. how the feature is implementable on platforms other than Linux
+
+New APIs, in particular, should follow the ‘rule of three’, where there should
+be three (or more) pieces of software which are ready to use the new APIs. This
+allows us to check that the new APIs are usable in real-life code, and fit well
+with related APIs. This reduces the chances of awkward or unusable APIs becoming
+stable in GLib and having to be supported forever.
+
+A common way to introduce new APIs or data types to GLib is to prototype them in
+another code base for a while, to gain real-life experience with them before
+they are imported into GLib and marked as stable.
+
+Each feature should also come fully documented, and with tests which approach
+full branch coverage of the new code. GLib’s CI system generates code coverage
+reports which are viewable for each merge request.
+
+If proposing a large feature or change, it’s better to discuss it (on the
+`#gtk` IRC channel or on [Discourse](https://discourse.gnome.org) before
+putting time into writing an actionable issue — and certainly before putting
+time into writing a merge request.
+
+## Your first contribution
+
+### Prerequisites
+
+If you want to contribute to the GLib project, you will need to have the
+development tools appropriate for your operating system, including:
+
+ - Python 3.x
+ - Meson
+ - Ninja
+ - Gettext (19.7 or newer)
+ - a [C99 compatible compiler](https://wiki.gnome.org/Projects/GLib/CompilerRequirements)
+
+Up-to-date instructions about developing GNOME applications and libraries
+can be found on [the GNOME Developer Center](https://developer.gnome.org).
+
+The [GLib project uses GitLab](https://gitlab.gnome.org/GNOME/glib/) for code
+hosting and for tracking issues. More information about using GitLab can be
+found [on the GNOME wiki](https://wiki.gnome.org/GitLab).
+
+### Getting started
+
+You should start by forking the GLib repository from the GitLab web UI, and
+cloning from your fork:
+
+```sh
+$ git clone https://gitlab.gnome.org/yourusername/glib.git
+$ cd glib
+```
+
+**Note**: if you plan to push changes to back to the main repository and
+have a GNOME account, you can skip the fork, and use the following instead:
+
+```sh
+$ git clone git@gitlab.gnome.org:GNOME/glib.git
+$ cd glib
+```
+
+To compile the Git version of GLib on your system, you will need to
+configure your build using Meson:
+
+```sh
+$ meson _builddir .
+$ cd _builddir
+$ ninja
+```
+
+Typically, you should work on your own branch:
+
+```sh
+$ git checkout -b your-branch
+```
+
+Once you’ve finished working on the bug fix or feature, push the branch
+to the Git repository and open a new merge request, to let the GLib
+core developers review your contribution.
+
+### Code reviews
+
+Each contribution is reviewed by the core developers of the GLib project.
+
+The [CODEOWNERS](./docs/CODEOWNERS) document contains the list of core
+contributors to GLib and the areas for which they are responsible; you
+should ensure to receive their review and signoff on your changes.
+
+It is our intention that every commit to GLib is reviewed by at least one other
+person, including commits from core developers. We all make mistakes and can
+always learn from each other, and code review allows that. It also reduces
+[bus factor](https://en.wikipedia.org/wiki/Bus_factor) by spreading knowledge
+of each commit between at least two people.
+
+With each code review, we intend to:
+
+ 0. Identify if this is a desirable change or new feature. Ideally for larger
+    features this will have been discussed (in an issue, on IRC, or on Discourse)
+    already, so that effort isn’t wasted on putting together merge requests
+    which will be rejected.
+ 0. Check the design of any new API.
+ 0. Provide realistic estimates of how long a review might take, if it can’t
+    happen immediately.
+ 0. Ensure that all significant contributions of new code, or bug fixes, are
+    adequately tested, either through requiring tests to be submitted at the
+    same time, or as a follow-up.
+ 0. Ensure that all new APIs are documented and have [introspection
+    annotations](https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations).
+ 0. Check that the contribution is split into logically separate commits, each
+    with a good commit message.
+ 0. Encourage further high quality contributions.
+ 0. Ensure code style and quality is upheld.
+
+If a code review is stalled (due to not receiving comments for two or more
+weeks; or due to a technical disagreement), please ping another GLib core
+developer on the merge request, or on IRC, to ask for a second opinion.
+
+### Commit messages
+
+The expected format for git commit messages is as follows:
+
+```plain
+Short explanation of the commit
+
+Longer explanation explaining exactly what’s changed, whether any
+external or private interfaces changed, what bugs were fixed (with bug
+tracker reference if applicable) and so forth. Be concise but not too
+brief.
+
+Closes #1234
+```
+
+ - Always add a brief description of the commit to the _first_ line of
+ the commit and terminate by two newlines (it will work without the
+ second newline, but that is not nice for the interfaces).
+
+ - First line (the brief description) must only be one sentence and
+ should start with a capital letter unless it starts with a lowercase
+ symbol or identifier. Don’t use a trailing period either. Don’t exceed
+ 72 characters.
+
+ - The main description (the body) is normal prose and should use normal
+ punctuation and capital letters where appropriate. Consider the commit
+ message as an email sent to the developers (or yourself, six months
+ down the line) detailing **why** you changed something. There’s no need
+ to specify the **how**: the changes can be inlined.
+
+ - When committing code on behalf of others use the `--author` option, e.g.
+ `git commit -a --author "Joe Coder <joe@coder.org>"` and `--signoff`.
+
+ - If your commit is addressing an issue, use the
+ [GitLab syntax](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html)
+ to automatically close the issue when merging the commit with the upstream
+ repository:
+
+```plain
+Closes #1234
+Fixes #1234
+Closes: https://gitlab.gnome.org/GNOME/glib/issues/1234
+```
+
+ - If you have a merge request with multiple commits and none of them
+ completely fixes an issue, you should add a reference to the issue in
+ the commit message, e.g. `Bug: #1234`, and use the automatic issue
+ closing syntax in the description of the merge request.
+
+### Merge access to the GLib repository
+
+GLib is part of the GNOME infrastructure. At the current time, any
+person with write access to the GNOME repository can merge merge requests to
+GLib. This is a good thing, in that it allows maintainership to be delegated
+and shared as needed. However, GLib is a fairly large and complicated package
+that many other things depend on, and which has platform specific behavior — so
+to avoid unnecessary breakage, and to take advantage of the knowledge about GLib
+that has been built up over the years, we’d like to ask people contributing to
+GLib to follow a few rules:
+
+0. Never push to the `main` branch, or any stable branches, directly; you
+   should always go through a merge request, to ensure that the code is
+   tested on the CI infrastructure at the very least. A merge request is
+   also the proper place to get a comprehensive code review from the core
+   developers of GLib.
+
+0. Always get a code review, even for seemingly trivial changes.
+
+0. Pay attention to the CI results. Merge requests cannot be merged until the
+   CI passes. If they consistently fail, either something is wrong with the
+   change, or the CI tests need fixing — in either case, please bring this to
+   the attention of a core developer rather than overriding the CI.
+
+If you have been contributing to GLib for a while and you don’t have commit
+access to the repository, you may ask to obtain it following the [GNOME account
+process](https://wiki.gnome.org/AccountsTeam/NewAccounts).

COPYING

@@ -0,0 +1,502 @@
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!

HACKING

@@ -0,0 +1,17 @@
+If you want to hack on the GLib project, you'll need to have the
+following packages installed:
+
+        - Meson 0.48.0
+        - GNU gettext 0.10.40
+        - pkg-config 0.16
+        - gtk-doc
+        - libffi 3.0.0
+
+To compile a Git version of glib on your system, you will need to take
+several steps to setup the tree for compilation.  You can do all these
+steps at once by running:
+
+        checkout/glib# meson _build
+
+For information about submitting patches see the CONTRIBUTING.md file. For
+information about major design decisions, see the README.rationale file.

INSTALL.in

@@ -0,0 +1,125 @@
+Simple install procedure
+========================
+
+  % tar xf glib-@GLIB_VERSION@.tar.gz       # unpack the sources
+  % cd glib-@GLIB_VERSION@                  # change to the toplevel directory
+  % meson _build                            # configure the build
+  % ninja -C _build                         # build GLib
+
+  [ Become root if necessary ]
+  % ninja -C _build install                 # install GLib
+
+Requirements
+============
+
+GLib requires a C90-compliant (but not necessarily C99-compliant) C
+compiler and libc. On UNIX-like systems, it also assumes compliance
+with at least the original 1990 version of POSIX.
+
+GLib-2.0 requires pkg-config, which is tool for tracking the
+compilation flags needed for libraries. (For each library, a small .pc
+text file is installed in a standard location that contains the
+compilation flags needed for that library along with version number
+information.) Information about pkg-config can be found at:
+
+  http://www.freedesktop.org/software/pkgconfig/
+
+Meson (http://mesonbuild.com/) is also required.
+
+In order to implement conversions between character sets,
+GLib requires an implementation of the standard iconv() routine.
+Most modern systems will have a suitable implementation, however
+many older systems lack an iconv() implementation. On such systems,
+you must install the libiconv library. This can be found at:
+
+ http://www.gnu.org/software/libiconv/
+
+If your system has an iconv implementation but you want to use
+libiconv instead, you can pass the --with-libiconv option to
+configure. This forces libiconv to be used.
+
+Note that if you have libiconv installed in your default include
+search path (for instance, in /usr/local/), but don't enable
+it, you will get an error while compiling GLib because the
+iconv.h that libiconv installs hides the system iconv.
+
+If you are using the native iconv implementation on Solaris
+instead of libiconv, you'll need to make sure that you have
+the converters between locale encodings and UTF-8 installed.
+At a minimum you'll need the SUNWuiu8 package. You probably
+should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
+SUNWkiu8 packages.
+
+The native iconv on Compaq Tru64 doesn't contain support for
+UTF-8, so you'll need to use GNU libiconv instead. (When
+using GNU libiconv for GLib, you'll need to use GNU libiconv
+for GNU gettext as well.) This probably applies to related
+operating systems as well.
+
+Finally, for message catalog handling, GLib requires an implementation
+of gettext(). If your system doesn't provide this functionality,
+you should use the libintl library from the GNU gettext package,
+available from:
+
+ http://www.gnu.org/software/gettext/
+
+Support for extended attributes and SELinux in GIO requires
+libattr and libselinux.
+
+Some of the mimetype-related functionality in GIO requires the
+update-mime-database and update-desktop-database utilities, which
+are part of shared-mime-info and desktop-file-utils, respectively.
+
+GObject uses libffi to implement generic marshalling functionality.
+
+The Nitty-Gritty
+================
+
+Complete information about installing GLib can be found
+in the file:
+
+ docs/reference/glib/html/glib-building.html
+
+Or online at:
+
+ https://developer.gnome.org/glib/stable/glib-building.html
+
+
+Installation directories
+========================
+
+The location of the installed files is determined by the --prefix
+and --exec-prefix options given to configure. There are also more
+detailed flags to control individual directories. However, the
+use of these flags is not tested.
+
+One particular detail to note, is that the architecture-dependent
+include file glibconfig.h is installed in:
+
+  $libdir/glib-2.0/include/
+
+.pc files for the various libraries are installed in
+$libdir/pkgconfig to provide information when compiling
+other packages that depend on GLib. If you set PKG_CONFIG_PATH
+so that it points to this directory, then you can get the
+correct include flags and library flags for compiling a GLib
+application with:
+
+ pkg-config --cflags glib-2.0
+ pkg-config --libs glib-2.0
+
+This is the only supported way of determining the include and library flags
+for building against GLib.
+
+
+Cross-compiling GLib
+====================
+
+Information about cross-compilation of GLib can be found
+in the file:
+
+ docs/reference/glib/html/glib-cross-compiling.html
+
+Or online at:
+
+ https://developer.gnome.org/glib/stable/glib-cross-compiling.html

NEWS.pre-1-3

@@ -0,0 +1,211 @@
+Overview of Changes in GLib 1.2.1:
+
+* g_realloc() fix for SunOS (please report further problems).
+* Continued the never ending fix vendetta regarding getpwuid(),
+  this time AIX has been the culprit.
+* Upgrade to libtool 1.2f
+* Miscellaneous other buglets fixed.
+
+What's new in GLib 1.2.0 (since GLib 1.0.x):
+
+* GLib is distributed seperatedly from Gtk+
+* Win32 Portability
+* Threading support
+* GModule mechanism (implemented in an extra library) which wraps dynamic
+  object code loading facilities in a portable manner
+* GIOChannel structure to encapsulate the IPC mechanism
+* GQuarks and datasets
+* GRelations for n-way mapping of certain data
+* An n-way tree implementation
+* GDate functionality for calendar date manipulations
+* GAllocator type and associated functions
+* Added generic callback maintenance functions (ghook)
+* Generic functions for TAB completions
+* Endian defines (G_*_ENDIAN)
+* g_log() mechanism for logging of messages at different log levels
+* Generic main-loop mechanism
+* New glib-config helper script
+* Many more API extensions
+
+Overview of Changes in GLib 1.1.16:
+
+* Allocate smaller pools of memory for glists, gslists, gnodes
+* Bug Fixes
+
+Overview of Changes in GLib 1.1.15:
+
+* HPUX 11 thread system detection should now work
+* Release the main loop lock around calls to prepare() and
+  check() so it is not held over user code
+* A few Win32 fixups
+
+Overview of Changes in GLib 1.1.14:
+
+* Check for dlsym() in system libraries and -dl
+* FreeBSD portability fixes
+* Random bug fixes and autoconf/automake changes
+
+Overview of Changes in GLib 1.1.13:
+
+* Removed alloca() based function and macro variants again.
+* Improved thread related configure tests.
+* GSource destruction fixups.
+* Fixed up idle function removal based on user_data pointer.
+* Advanced Win32 portability.
+* Enforced GSource's check(), prepare() and dispatch() constrains,
+  loop recursions may only happen from dispatch(), and check() as well
+  as prepare() are called while the main_loop lock is being held.
+* GLib development now requires GNU autoconf 2.13, GNU automake 1.4
+  and GNU libtool 1.2d.
+* Lots of random portability and bug fixes.
+
+Overview of Changes in GLib 1.1.12:
+
+* Added alloca functions/macros: g_strdup_a, g_strconcat3_a, g_alloca,
+  g_new_a, g_new0_a
+* New tests structure.  Type 'make check' on your system to run them.
+* Avoid unnecessary extra hook referencing in g_hook_list_marshal
+
+Overview of Changes in GLib 1.1.11:
+
+* provide defaults for POLL sysdefs
+* g_main_is_running: new function to check whether a main loop has been quitted
+* a few other enhancement/fixes
+
+Overview of Changes in GLib 1.1.9:
+
+* Check for pthread_attr_init in all cases, Digital Unix 4 requires this
+* For G_LOCK_DECLARE_*, if !G_THREADS_ENABLED, eat trailing semicolon better
+* Changed g_main_poll_(add|remove) to g_main_(add|remove)_poll
+
+Overview of Changes in GLib 1.1.8:
+
+* Added threading support
+  - The ability to specify a set of functions to be used for
+    locking at runtime.
+  - Default implementations of locking functions for pthreads,
+    Solaris threads, and (experimentally) NSPR.
+  - All static variables should now properly locked.
+  - Enhancements to the generic main-loop mechanism to be thread-safe.
+    (It is used for the main-loop in GTK+ as of GTK+-1.1.8)
+* Portability fixes.
+
+Overview of Changes in GLib 1.1.7:
+
+* Removed multiple define from glibconfig.h
+
+Overview of Changes in GLib 1.1.6:
+
+* New GDate functionality for calendar date manipulations (g_date_*)
+* New GAllocator type and associated functions
+* New functions g_slist_copy and g_list_copy to duplicate a list with all
+  its data pointers.
+* New function g_array_insert_vals and new macro g_array_insert_val to
+  insert elements at an arbitrary index
+* GAllocators used for glist, gslist, gnode node allocations
+* Incremental freezing in ghash
+* New function g_hook_list_marshal_check to eventually destroy hooks after
+  they got marshalled
+* Revised GIOChannel to provide generic virtual-function based interface
+* Added generic main-loop abstraction
+* Removed GListAllocator type and its g_*_allocator_*() function variants
+* Bug fixes
+
+Overview of Changes in GLib 1.1.5:
+
+* Win32 portability
+* GIOChannel structure to encapsulate the IPC mechanism 
+* Reimplemented endian stuff, using inline asm for x86
+* New functions:
+  - g_strescape: escapes backslashes
+  - g_path_is_absolute and g_path_skip_root
+  - g_getenv: expands environment variables that contain references 
+    to other environment variables
+  - g_scanner_sync_file_offset: rewind the filedescriptor to the current
+    buffer position and blow the file read ahead buffer
+  - g_array_remove_index: remove an entry, preserving the order
+  - g_array_remove_index_fast: remove an entry, order might be distorted
+  - g_ptr_array_remove: remove an entry, preserving the order 
+  - g_ptr_array_remove_fast: remove an entry, order might be distorted
+  - g_byte_array_remove_index: wrapper for g_array_remove_index
+  - g_byte_array_remove_index_fast: wrapper for g_array_remove_index_fast
+  - g_strncasecmp: modeled closely after g_strcasecmp
+  - g_list_sort, g_slist_sort: to merge sort GLists and GSLists
+* New macros:
+  - G_DIR_SEPARATOR, G_DIR_SEPARATOR_S: platform-dependant file name
+    syntax elements
+  - G_SEARCHPATH_SEPARATOR, G_SEARCHPATH_SEPARATOR_S: platform-dependant
+    search path syntax conventions
+  - G_STRUCT_OFFSET, G_STRUCT_MEMBER_P, G_STRUCT_MEMBER: for handling
+    structure fields through their offsets
+* Removed G_ENUM, G_FLAGS, G_NV, and G_SV macros
+* Bug fixes
+
+Overview of Changes in GLib 1.1.4:
+
+* Added generic callback maintenance functions (ghook)
+* New endian defines (G_*_ENDIAN)
+* New string join/split/free routines 
+* Fixes
+
+Overview of Changes in GLib 1.1.3:
+
+* New GModule mechanism (implemented in an extra library) which wraps dynamic
+  object code loading facilities in a portable manner.
+* glib-config features extra "glib" (old behaviour remains) and "gmodule"
+  (add libgmodule.so to the --libs output) arguments now. this can also
+  be specified as fourth argument to the AM_PATH_GLIB() macro.
+* Overhaul of the `inline' autoconfiguration stuff, so inlining should be
+  sufficiently supported on all systems that allow inlining now.
+* New g_log() mechanism for logging of messages at different log levels,
+  associated with certain log domains (define -DG_LOG_DOMAIN for your library).
+* New inline functions for bit masks tests.
+* GNode macros (and functions) now return the newly allocated node.
+* New macro G_VA_COPY() to work around va_list copying oddities on some
+  platforms. the non-static g_vsprintf() function vanished in favour of
+  a publically exported g_strdup_vprintf().
+  People that used the former g_vsprintf() would definitely want to read the
+  associated ChangeLog entries (grep for printf).
+* New utility functions:
+  g_strndup(), g_on_error_query(), g_on_error_stack_trace(), g_strdup_printf(),
+  g_strdup_vprintf(), g_printf_string_upper_bound(), g_spaced_primes_closest(),
+  g_strnfill(), g_memdup(). 
+* Overhaul of the array implementations, this contains some source incompatible
+  changes. Again, the ChangeLog is much more informative (grep for garray.c).
+* The internals of the g_dataset mechanism are now exported through the
+  new g_datalist_* API (this is also the underlying implementation for the
+  keyed data of GtkObjects).
+* New function g_atexit(), use of the ATEXIT() macro is discouraged.
+* Better configure checks for ansi compliance.
+* Libtool update to version 1.2b.
+* Lotsa bug fixes and cleanups as always ;)
+
+Overview of Changes in GLib 1.1.2:
+
+* Fixed packaging mistake which occured in 1.1.1
+* fix 64-bitness in g_prints in glibtest
+
+What is new in GLib 1.1.1:
+
+* An n-way tree implementation is provided now, based on the GNode structure.
+* Bugfix for pointer arrays.
+
+What is new in GLib 1.1.0:
+
+* GLib is distributed seperatedly from Gtk+ now and uses a sophisticated
+  shared library versioning scheme to deal with interface and binary
+  incompatibilities.
+* There is a glib-config helper script installed now.
+* Fixups all over the place.
+* gboolean is now a gint, not a gchar anymore.
+* API extensions for GList and GSList.
+* New g_str*() functions for simple string handling.
+* GScanner extensions for scope, warning and error handling.
+* Minor performance improvements for GMemChunks.
+* Implementations of GQuarks and datasets (similar to GtkObjects data
+  mechansim, but works for generic memory locations).
+* More convenience macros for GNU C function arguments.
+* Const correction all over the place, including a new pointer type
+  gconstpointer.
+* Generic functions for TAB completions.
+* GRelations for n-way mapping of certain data.

README

@@ -0,0 +1 @@
+See README.md

README.md

@@ -0,0 +1,93 @@
+# GLib
+
+GLib is the low-level core library that forms the basis for projects such
+as GTK and GNOME. It provides data structure handling for C, portability
+wrappers, and interfaces for such runtime functionality as an event loop,
+threads, dynamic loading, and an object system.
+
+The official download locations are:
+  <https://download.gnome.org/sources/glib>
+
+The official web site is:
+  <https://www.gtk.org/>
+
+## Installation
+
+See the file '[INSTALL.in](INSTALL.in)'
+
+## Supported versions
+
+Only the most recent unstable and stable release series are supported. All
+older versions are not supported upstream and may contain bugs, some of
+which may be exploitable security vulnerabilities.
+
+See [SECURITY.md](SECURITY.md) for more details.
+
+## Documentation
+
+API documentation is available online for GLib for the:
+ * [GLib](https://docs.gtk.org/glib/)
+ * [GObject](https://docs.gtk.org/gobject/)
+ * [GModule](https://docs.gtk.org/gmodule/)
+ * [GIO](https://docs.gtk.org/gio/)
+
+## Discussion
+
+If you have a question about how to use GLib, seek help on [GNOME’s Discourse
+instance](https://discourse.gnome.org/tags/glib). Alternatively, ask a question
+on [StackOverflow and tag it `glib`](https://stackoverflow.com/questions/tagged/glib).
+
+## Reporting bugs
+
+Bugs should be [reported to the GNOME issue tracking system](https://gitlab.gnome.org/GNOME/glib/issues/new).
+You will need to create an account for yourself. You may also submit bugs by
+e-mail (without an account) by e-mailing <incoming+gnome-glib-658-issue-@gitlab.gnome.org>,
+but this will give you a degraded experience.
+
+Bugs are for reporting problems in GLib itself, not for asking questions about
+how to use it. To ask questions, use one of our [discussion forums](#discussion).
+
+In bug reports please include:
+
+* Information about your system. For instance:
+  * What operating system and version
+  * For Linux, what version of the C library
+  * And anything else you think is relevant.
+* How to reproduce the bug.
+  * If you can reproduce it with one of the test programs that are built
+  in the `tests/` subdirectory, that will be most convenient.  Otherwise,
+  please include a short test program that exhibits the behavior.
+  As a last resort, you can also provide a pointer to a larger piece
+  of software that can be downloaded.
+* If the bug was a crash, the exact text that was printed out
+  when the crash occurred.
+* Further information such as stack traces may be useful, but
+  is not necessary.
+
+## Contributing to GLib
+
+Please follow the [contribution guide](./CONTRIBUTING.md) to know how to
+start contributing to GLib.
+
+Patches should be [submitted as merge requests](https://gitlab.gnome.org/GNOME/glib/-/merge_requests/new)
+to gitlab.gnome.org. If the patch fixes an existing issue, please refer to the
+issue in your commit message with the following notation (for issue 123):
+```
+Closes: #123
+```
+
+Otherwise, create a new merge request that introduces the change. Filing a
+separate issue is not required.
+
+## Default branch renamed to `main`
+
+The default development branch of GLib has been renamed to `main`. To update
+your local checkout, use:
+```sh
+git checkout master
+git branch -m master main
+git fetch
+git branch --unset-upstream
+git branch -u origin/main
+git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
+```

README.rationale

@@ -0,0 +1,16 @@
+This file documents various major decisions which affect GLib development,
+giving a brief rationale of each decision, plus a link to further discussion.
+
+
+ * Compiler attributes: https://bugzilla.gnome.org/show_bug.cgi?id=113075#c46
+
+   GLib uses GIR annotations instead of compiler attributes. They are tidier,
+   already supported by GLib and GNOME tools, and accomplish the same task as
+   compiler attributes. GLib does not provide macros for attributes like
+   nonnull because it would not use them.
+
+ * Main loop API:
+
+   The ID-based mainloop APIs (g_idle_add, g_timeout_add, etc) are considered
+   legacy, and new features (such as g_source_set_static_name) will only be
+   added to the explicit GSource APIs.

README.win32

@@ -0,0 +1 @@
+See README.win32.md

README.win32.md

@@ -0,0 +1,169 @@
+Chun-wei Fan `<fanc999@yahoo.com.tw>`
+Philip Withnall `<withnall@endlessm.com>`
+Nirbheek Chauhan `<nirbheek@centricular.com>`
+
+This document was last updated in 2019. You're reading this in the future, and
+lots of information might be misleading or outdated in your age. You have been
+warned.
+
+# General
+
+For prebuilt binaries (DLLs and EXEs) and developer packages (headers,
+import libraries) of GLib, Pango, GTK+ etc for Windows, go to
+https://www.gtk.org/download/windows.php . They are for "native"
+Windows meaning they use the Win32 API and Microsoft C runtime library
+only. No POSIX (Unix) emulation layer like Cygwin is involved.
+
+To build GLib on Win32, you can use either GCC ("MinGW") or the Microsoft
+Visual Studio toolchain. For the latter, Visual Studio 2015 and later are
+recommended. For older Visual Studio versions, see below.
+
+You can also cross-compile GLib for Windows from Linux using the
+cross-compiling mingw packages for your distro.
+
+Note that to just *use* GLib on Windows, there is no need to build it
+yourself.
+
+On Windows setting up a correct build environment is very similar to typing
+`meson; ninja` like on Linux.
+
+The following preprocessor macros are to be used for conditional
+compilation related to Win32 in GLib-using code:
+
+- `G_OS_WIN32` is defined when compiling for native Win32, without
+  any POSIX emulation, other than to the extent provided by the
+  bundled Microsoft C library.
+
+- `G_WITH_CYGWIN` is defined if compiling for the Cygwin
+  environment. Note that `G_OS_WIN32` is *not* defined in that case, as
+  Cygwin is supposed to behave like Unix. `G_OS_UNIX` *is* defined by a GLib
+  for Cygwin.
+
+- `G_PLATFORM_WIN32` is defined when either `G_OS_WIN32` or `G_WITH_CYGWIN`
+  is defined.
+
+These macros are defined in `glibconfig.h`, and are thus available in
+all source files that include `<glib.h>`.
+
+Additionally, there are the compiler-specific macros:
+- `__GNUC__` is defined when using GCC or Clang
+- `__clang__` is defined when using Clang or Clang-CL
+- `_MSC_VER` is defined when using MSVC or Clang-CL
+
+`G_OS_WIN32` implies using the Microsoft C runtime, which used to be
+`msvcrt.dll` and is now the [Universal CRT](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=vs-2015)
+when building with Visual Studio. When using the MinGW-GCC toolchain, the CRT
+in use depends on the settings used while the toolchain was built. We highly
+recommend [using the Universal CRT when building with
+MinGW](https://mingwpy.github.io/ucrt.html) too.
+
+GLib is not actively tested with the static versions of the UCRT, but if you
+need to use those, patches are welcome.
+
+# Building software that use GLib or GTK+
+
+Building software that just *uses* GLib or GTK+ also require to have
+the right compiler set up the right way. If you intend to use MinGW-GCC,
+follow the relevant instructions below in that case, too.
+
+You should link to GLib using the `-mms-bitfields` GCC flag. This flag means
+that the struct layout rules are identical to those used by MSVC. This is
+essential if the same DLLs are to be usable both from gcc- and MSVC-compiled
+code.
+
+## Cross-CRT issues
+
+You should take care that the DLLs that your code links to are using the same
+C runtime library. Not doing so can and likely will lead to panics and crashes
+**unless** you're very careful while passing objects allocated by a library
+linked with one CRT to a library linked to another CRT, or (more commonly) not
+doing that at all.
+
+If you *do* pass CRT objects across CRT boundaries, do not file any issues
+about whatever happens next.
+
+To give an example, opening a `FILE` handle created by one CRT cannot be
+understood by any other CRT, and will lead to an access violation. You also
+cannot allocate memory in one CRT and free it using another.
+
+There are [many other cases where you must not allow objects to cross CRT boundaries](https://docs.microsoft.com/en-us/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries?view=vs-2019),
+but in theory if you're **very very** careful, you can make things work. Again,
+please do not come to us for help if you choose to do this.
+
+# Building GLib
+
+You can build GLib with MinGW-GCC, MSVC, or (experimentally) with Clang-CL.
+
+For all compilers, you will need the following:
+
+- Install Python 3.6.x or newer, either 32-bit or 64-bit. We recommend enabling
+  the option to add it to your `PATH`.
+- [Install Meson](https://mesonbuild.com/Getting-meson.html)
+- Install the [Ninja build tool](https://github.com/ninja-build/ninja/releases), which can also be
+  installed with `pip3`. You can skip this step if you want to generate Visual
+  Studio project files.
+- [git for Windows](https://gitforwindows.org/) is required, since Meson makes
+  use of git to download dependencies using subprojects.
+
+## Building with MinGW-GCC
+
+Open your MSYS or [MSYS2](https://www.msys2.org/) shell where you have the
+MinGW-GCC toolchain installed, and build GLib [like any other Meson
+project](https://mesonbuild.com/Quick-guide.html#compiling-a-meson-project).
+
+## Building with Visual Studio 2015 or newer
+
+Meson is now the only supported method of building GLib using Visual Studio.
+
+To do a build using Meson, do the following:
+
+- Open a Visual Studio (or SDK) command prompt that matches the Visual Studio
+  version and build platform (Win32/x86, x64, etc.) that will be used in all
+  the following steps.
+
+- Create an empty directory/folder for the build inside your GLib sources
+  directory, say, `_builddir`, and `cd` into it.
+
+- Set up the build using Meson:
+
+```cmd
+> meson .. --buildtype=<release|debug|debugoptimized> --prefix=<path> [--backend=vs]
+```
+
+ Please see [the Meson docs](https://mesonbuild.com/Builtin-options.html#core-options)
+ for an explanation for `--buildtype`.
+
+ The path passed for `--prefix` need not to be on the same drive as where the
+ build is carried out, but it is recommended to use forward slashes for this
+ path.  The `--backend=vs` option can be used if the Visual Studio project
+ generator is preferred over using Ninja.
+
+- Build, test and install the build:
+  Run `ninja` to build, `meson test` to test and `meson install` to install the
+  build. If you used `--backend=vs`, instead of running `ninja`, you need to
+  use `msbuild` or you can open the generated solution in Visual Studio.
+
+## Building with old versions of Visual Studio
+
+The steps are the same as above, with the following notes about issues that you might face.
+
+### C4819 build errors
+
+If you are building GLib-based libraries or applications, or GLib itself
+and you see a `C4819` error (or warning, before `C4819` is treated as an error
+in `msvc_recommended_pragmas.h`), please be advised that this error/warning should
+not be disregarded, as this likely means portions of the build are not being
+done correctly, as this is an issue of Visual Studio running on CJK (East Asian)
+locales.  This is an issue that also affects builds of other projects, such as
+QT, Firefox, LibreOffice/OpenOffice, Pango and GTK, along with many other projects.
+
+To overcome this problem, please set your system's locale setting for non-Unicode to
+English (United States), reboot, and restart the build, and the code should build
+normally.
+
+### Support for pre-2012 Visual Studio
+
+This release of GLib requires at least the Windows 8 SDK in order to be built
+successfully using Visual Studio, which means that it is no longer supported to
+build GLib with Visual Studio 2008 nor 2010.  People that still need to use
+Visual Studio 2008 or 2010 should continue to use glib-2.66.x.

SECURITY.md

@@ -0,0 +1,78 @@
+# Security policy for GLib
+
+ * [Supported Versions](#Supported-Versions)
+ * [Reporting a Vulnerability](#Reporting-a-Vulnerability)
+ * [Security Announcements](#Security-Announcements)
+ * [Acknowledgements](#Acknowledgements)
+
+## Supported Versions
+
+Upstream GLib only supports the most recent stable release series, and the
+current development release series. Any older stable release series are no
+longer supported, although they may still receive backported security updates
+in long-term support distributions. Such support is up to the distributions,
+though.
+
+Under GLib’s versioning scheme, stable release series have an *even* minor
+component (for example, 2.66.0, 2.66.1, 2.68.3), and development release series
+have an *odd* minor component (2.67.1, 2.69.0).
+
+## Signed Releases
+
+The git tags for all releases ≥2.58.0 are signed by a maintainer using
+[git-evtag](https://github.com/cgwalters/git-evtag). The maintainer will use
+their personal GPG key; there is currently not necessarily a formal chain of
+trust for these keys. Please [create an issue](https://gitlab.gnome.org/GNOME/glib/-/issues/new)
+if you would like to work on improving this.
+
+Unsigned releases ≥2.58.0 should not be trusted. Releases prior to 2.58.0 were
+not signed.
+
+## Reporting a Vulnerability
+
+If you think you've identified a security issue in GLib, GObject or GIO, please
+**do not** report the issue publicly via a mailing list, IRC, a public issue on
+the GitLab issue tracker, a merge request, or any other public venue.
+
+Instead, report a
+[*confidential* issue in the GitLab issue tracker](https://gitlab.gnome.org/GNOME/glib/-/issues/new?issue[confidential]=1),
+with the “This issue is confidential” box checked. Please include as many
+details as possible, including a minimal reproducible example of the issue, and
+an idea of how exploitable/severe you think it is.
+
+**Do not** provide a merge request to fix the issue, as there is currently no
+way to make confidential merge requests on gitlab.gnome.org. If you have patches
+which fix the security issue, please attach them to your confidential issue as
+patch files.
+
+Confidential issues are only visible to the reporter and the GLib maintainers.
+
+As per the [GNOME security policy](https://security.gnome.org/), the next steps
+are then:
+ * The report is triaged.
+ * Code is audited to find any potential similar problems.
+ * If it is determined, in consultation with the submitter, that a CVE is
+   required, the submitter obtains one via [cveform.mitre.org](https://cveform.mitre.org/).
+ * The fix is prepared for the development branch, and for the most recent
+   stable branch.
+ * The fix is submitted to the public repository.
+ * On the day the issue and fix are made public, an announcement is made on the
+   [public channels listed below](#Security-Announcements).
+ * A new release containing the fix is issued.
+
+## Security Announcements
+
+Security announcements are made publicly via the
+[`distributor` tag on discourse.gnome.org](https://discourse.gnome.org/tag/distributor)
+and cross-posted to the
+[distributor-list](https://mail.gnome.org/mailman/listinfo/distributor-list).
+
+Announcements for security issues with wide applicability or high impact may
+additionally be made via
+[oss-security@lists.openwall.com](https://www.openwall.com/lists/oss-security/).
+
+## Acknowledgements
+
+This text was partially based on the
+[github.com/containers security policy](https://github.com/containers/common/blob/HEAD/SECURITY.md),
+and partially based on the [flatpak security policy](https://github.com/flatpak/flatpak/blob/HEAD/SECURITY.md).

check-abis.sh

@@ -0,0 +1,23 @@
+#!/bin/sh -e
+
+list_leaked_symbols () {
+	nm -D "$1" | grep ' T ' | cut -f 3 -d ' ' | grep -E -v "$2"
+}
+
+check_symbols () {
+	if [ "$(list_leaked_symbols "$1" "$2" | wc -l)" -ne 0 ]; then
+		echo File "$1" possibly leaking symbols:
+		list_leaked_symbols "$1" "$2"
+		exit 1
+	fi
+}
+
+allowed="^_init$|^_fini$|^_ftext$|^g_"
+allowed_in_libglib="${allowed}|^glib__private__$|^glib_gettext$|^glib_pgettext$|^glib_check_version$"
+allowed_in_libgthread='^_init$|^_fini$|^_ftext$|^g_thread_init$|^g_thread_init_with_errorcheck_mutexes$'
+
+check_symbols glib/.libs/libglib-2.0.so "$allowed_in_libglib"
+check_symbols gthread/.libs/libgthread-2.0.so "$allowed_in_libgthread"
+for file in gmodule/.libs/libgmodule-2.0.so gobject/.libs/libgobject-2.0.so gio/.libs/libgio-2.0.so; do
+	check_symbols "$file" "$allowed"
+done

clang-format-diff.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+#
+# === clang-format-diff.py - ClangFormat Diff Reformatter ---*- python -*-=== #
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# ===---------------------------------------------------------------------=== #
+
+"""
+This script reads input from a unified diff and reformats all the changed
+lines. This is useful to reformat all the lines touched by a specific patch.
+Example usage for git/svn users:
+
+  git diff -U0 --no-color HEAD^ | clang-format-diff.py -p1 -i
+  svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i
+
+"""
+from __future__ import absolute_import, division, print_function
+
+import argparse
+import difflib
+import re
+import subprocess
+import sys
+
+if sys.version_info.major >= 3:
+    from io import StringIO
+else:
+    from io import BytesIO as StringIO
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        "-i",
+        action="store_true",
+        default=False,
+        help="apply edits to files instead of displaying a " "diff",
+    )
+    parser.add_argument(
+        "-p",
+        metavar="NUM",
+        default=0,
+        help="strip the smallest prefix containing P slashes",
+    )
+    parser.add_argument(
+        "-regex",
+        metavar="PATTERN",
+        default=None,
+        help="custom pattern selecting file paths to reformat "
+        "(case sensitive, overrides -iregex)",
+    )
+    parser.add_argument(
+        "-iregex",
+        metavar="PATTERN",
+        default=r".*\.(cpp|cc|c\+\+|cxx|c|cl|h|hh|hpp|m|mm|inc"
+        r"|js|ts|proto|protodevel|java|cs)",
+        help="custom pattern selecting file paths to reformat "
+        "(case insensitive, overridden by -regex)",
+    )
+    parser.add_argument(
+        "-sort-includes",
+        action="store_true",
+        default=False,
+        help="let clang-format sort include blocks",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="be more verbose, ineffective without -i",
+    )
+    parser.add_argument(
+        "-style",
+        help="formatting style to apply (LLVM, Google, " "Chromium, Mozilla, WebKit)",
+    )
+    parser.add_argument(
+        "-binary",
+        default="clang-format",
+        help="location of binary to use for clang-format",
+    )
+    args = parser.parse_args()
+
+    # Extract changed lines for each file.
+    filename = None
+    lines_by_file = {}
+    for line in sys.stdin:
+        match = re.search(r"^\+\+\+\ (.*?/){%s}(\S*)" % args.p, line)
+        if match:
+            filename = match.group(2)
+        if filename is None:
+            continue
+
+        if args.regex is not None:
+            if not re.match("^%s$" % args.regex, filename):
+                continue
+        else:
+            if not re.match("^%s$" % args.iregex, filename, re.IGNORECASE):
+                continue
+
+        match = re.search(r"^@@.*\+(\d+)(,(\d+))?", line)
+        if match:
+            start_line = int(match.group(1))
+            line_count = 1
+            if match.group(3):
+                line_count = int(match.group(3))
+            if line_count == 0:
+                continue
+            end_line = start_line + line_count - 1
+            lines_by_file.setdefault(filename, []).extend(
+                ["-lines", str(start_line) + ":" + str(end_line)]
+            )
+
+    # Reformat files containing changes in place.
+    # We need to count amount of bytes generated in the output of
+    # clang-format-diff. If clang-format-diff doesn't generate any bytes it
+    # means there is nothing to format.
+    format_line_counter = 0
+    for filename, lines in lines_by_file.items():
+        if args.i and args.verbose:
+            print("Formatting {}".format(filename))
+        command = [args.binary, filename]
+        if args.i:
+            command.append("-i")
+        if args.sort_includes:
+            command.append("-sort-includes")
+        command.extend(lines)
+        if args.style:
+            command.extend(["-style", args.style])
+        p = subprocess.Popen(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=None,
+            stdin=subprocess.PIPE,
+            universal_newlines=True,
+        )
+        stdout, _ = p.communicate()
+        if p.returncode != 0:
+            sys.exit(p.returncode)
+
+        if not args.i:
+            with open(filename) as f:
+                code = f.readlines()
+            formatted_code = StringIO(stdout).readlines()
+            diff = difflib.unified_diff(
+                code,
+                formatted_code,
+                filename,
+                filename,
+                "(before formatting)",
+                "(after formatting)",
+            )
+            diff_string = "".join(diff)
+            if diff_string:
+                format_line_counter += sys.stdout.write(diff_string)
+
+    if format_line_counter > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

docs/CODEOWNERS

@@ -0,0 +1,83 @@
+# These are the people responsible for subsystems in GLib; if you're opening
+# a merge request for files listed here, please add the following people to
+# the list of reviewers
+
+# The syntax of this file is defined by GitLab:
+#   https://docs.gitlab.com/ee/user/project/code_owners.html
+# Which, in turn, is similar to the .gitignore and .gitattributes files:
+#
+#  - comments start with `#`
+#  - the first column contains paths and globs
+#  - the second column contains GitLab user names or email addresses,
+#    separated by spaces
+#
+# The last matching glob (rather than the union of *all* matching globs) gives
+# the owners of a piece of code.
+#
+# If you want to be responsible for code reviews in specific sections of
+# the GLib code base, add yourself here.
+
+# Overall maintainers
+*	@pwithnall @ebassi
+
+# Build system
+meson.build		@xclaesse @nirbheek @pwithnall
+meson_options.txt	@xclaesse @nirbheek @pwithnall
+subprojects/		@xclaesse @nirbheek @pwithnall
+
+# CI integration
+.gitlab-ci*	@pwithnall @xclaesse @creiter
+
+# macOS support
+*osx*	@jralls @pwithnall @sdroege
+*.m	@jralls @pwithnall @sdroege
+
+# Windows support
+*win32*	@lrn @creiter @fanc999 @pwithnall @sdroege @nirbheek
+
+# Windows support (MSVC-specific)
+*msvc*	@fanc999 @creiter @pwithnall @sdroege @nirbheek
+
+# Windows support (UWP-specific)
+*uwp*   @nirbheek
+
+# Android support
+*android*	@xclaesse @pwithnall @sdroege
+
+# BSD support
+*bsd*		@jmatthew @ajacoutot @lantw @pwithnall
+*kqueue*	@jmatthew @ajacoutot @lantw @pwithnall
+
+# flatpak portals
+gio/*portal*	@matthiasc @alexl @pwithnall
+
+# Networking
+gio/g*{tcp,udp,tls,socket,resolver,proxy,network,inet,datagram}*	@mcatanzaro @pgriffis @pwithnall @sdroege
+
+# D-Bus
+gio/g*bus*	@smcv @pwithnall
+
+# I/O
+gio/g*{file,vfs,mount,drive,volume}*	@oholy @alexl @pwithnall @sdroege
+gio/g*stream*				@alexl @pwithnall @sdroege
+gio/gio-tool*				@oholy @alexl @pwithnall
+
+# Generic bits of GLib
+glib/	@ebassi @pwithnall @sdroege
+
+# GObject type system
+gobject/	@ebassi @pwithnall @sdroege
+
+# GVariant
+glib/gvariant*	@pwithnall @sdroege
+
+# grefcount, GRcBox and GRefString
+glib/gref{count,string}.[ch]	@ebassi @pwithnall @sdroege
+glib/grc*.[ch]			@ebassi @pwithnall @sdroege
+glib/garc*.[ch]			@ebassi @pwithnall @sdroege
+
+# Logging
+glib/gmessages.[ch]	@pwithnall @sdroege
+
+# Google clusterfuzz support
+fuzzing/	@pwithnall

docs/debugging.txt

@@ -0,0 +1,38 @@
+
+Traps (G_BREAKPOINT) and traces for the debugging
+=================================================
+
+Some code portions contain trap variables that can be set during
+debugging time if G_ENABLE_DEBUG has been defined upon compilation
+(use the --buildtype=debug option to configure for this, macros.txt
+covers more details).
+Such traps lead to immediate code halts to examine the current
+program state and backtrace.
+Currently, the following trap variables exist:
+
+static volatile gulong g_trap_free_size;
+static volatile gulong g_trap_realloc_size;
+static volatile gulong g_trap_malloc_size;
+	If set to a size > 0, g_free(), g_realloc() and g_malloc()
+	respectively, will be intercepted if the size matches the
+	size of the corresponding memory block to free/reallocate/allocate.
+	This will only work with g_mem_set_vtable (glib_mem_profiler_table)
+	upon startup though, because memory profiling is required to match
+	on the memory block sizes.
+static volatile GObject *g_trap_object_ref;
+	If set to a valid object pointer, ref/unref will be intercepted
+	with G_BREAKPOINT ();
+static volatile gpointer *g_trap_instance_signals;
+static volatile gpointer *g_trace_instance_signals;
+       If set to a valid instance pointer, debugging messages
+       will be spewed about emissions of signals on this instance.
+       For g_trap_instance_signals matches, the emissions will
+       also be intercepted with G_BREAKPOINT ();
+
+Environment variables for debugging
+===================================
+When G_ENABLE_DEBUG was defined upon compilation, the GObject library 
+supports an environment variable GOBJECT_DEBUG that can be set to a
+combination of the flags passed in to g_type_init() (currently
+"objects" and "signals") to trigger debugging messages about
+object bookkeeping and signal emissions during runtime.

docs/macros.txt

@@ -0,0 +1,58 @@
+GLib's configure options and corresponding macros
+=================================================
+
+--buildtype={plain,release,minsize,custom}
+	none
+--buildtype={debug,debugoptimized}	[debugoptimized is the default]
+	-DG_ENABLE_DEBUG -g
+-Dglib_debug=disabled
+	Omits G_ENABLE_DEBUG when implied by --buildtype/-Ddebug
+-Dglib_debug=enabled
+	Defines G_ENABLE_DEBUG regardless of --buildtype/-Ddebug
+-Dglib_asserts=false
+	-DG_DISABLE_ASSERT
+-Dglib_checks=false
+	-DG_DISABLE_CHECKS
+
+Besides these, there are some local feature specific options, but my main
+focus here is to concentrate on macros that affect overall GLib behaviour
+and/or third party code.
+
+
+Notes on GLib's internal and global macros
+==========================================
+
+G_DISABLE_ASSERT
+	The g_assert() and g_assert_not_reached() become non-functional
+	with this define. The motivation is to speed up end-user apps by
+	avoiding expensive checks.
+	This macro can affect third-party code. Defining it when building GLib
+	will only disable the assertion macros for GLib itself, but third-party code
+	that passes -DG_DISABLE_ASSERT to the compiler upon its own build
+	will end up with the non-functional variants after including glib.h
+	as well.
+	NOTE: Code inside the assertion macros should not have side effects
+	that affect the operation of the program.
+G_DISABLE_CHECKS
+	This macro is similar to G_DISABLE_ASSERT, it affects third-party
+	code as mentioned above and the NOTE about G_DISABLE_ASSERT applies
+	too. The macros that become non-functional here are
+	g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+	g_return_val_if_reached().
+	Additionally the glib_mem_profiler_table and g_mem_profile() from
+	gmem.h become non-functional if this macro is supplied.
+	This macro also switches off certain checks in the GSignal code.
+G_ENABLE_DEBUG
+	Quite a bit of additional debugging code is compiled into GLib for this
+	macro, and since it is a globally visible define, third-party code may
+	be affected by it similar to G_DISABLE_ASSERT.
+	The additional code executed/compiled for this macro currently involve:
+	- extra validity checks for GDate
+	- memory profiling traps in gmem.c (consult debugging.txt for details)
+	- BREAKPOINT abortion for fatal log levels in gmessage.c instead of
+	  plain abort() to allow debuggers trapping and overriding them
+	- added verbosity of gscanner.c to catch deprecated code paths
+	- added verbosity of gutils.c to catch deprecated code paths
+	- object ref/unref traps (consult debugging.txt) and object bookkeeping
+	  in gobject.c
+	- extra validity checks in gsignal.c

docs/reference/.gitignore

@@ -0,0 +1,16 @@
+*-decl-list.txt
+*-decl.txt
+*-unused.txt
+*-undocumented.txt
+*-undeclared.txt
+*.args
+*.hierarchy
+*.interfaces
+*.prerequisites
+*.signals
+*.stamp
+html
+xml
+*.bak
+version.xml
+*.1

docs/reference/AUTHORS

@@ -0,0 +1,7 @@
+Damon Chaplin <damon@karuna.freeserve.co.uk> and others.
+
+See:
+
+ http://www.gtk.org/rdp/status.html
+
+for a complete list.

docs/reference/COPYING

@@ -0,0 +1,30 @@
+This work may be reproduced and distributed in whole or in part, in
+any medium, physical or electronic, so as long as this copyright
+notice remains intact and unchanged on all copies.  Commercial
+redistribution is permitted and encouraged, but you may not
+redistribute, in whole or in part, under terms more restrictive than
+those under which you received it. If you redistribute a modified or
+translated version of this work, you must also make the source code to
+the modified or translated version available in electronic form
+without charge.  However, mere aggregation as part of a larger work
+shall not count as a modification for this purpose.
+
+All code examples in this work are placed into the public domain,
+and may be used, modified and redistributed without restriction.
+
+BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY REPAIR OR CORRECTION.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE 
+POSSIBILITY OF SUCH DAMAGES.

docs/reference/gio/.gitignore

@@ -0,0 +1,3 @@
+*.1
+gio-overrides.txt
+tmpl

docs/reference/gio/concat-files-helper.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# Copyright (C) 2018 Collabora Inc.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General
+# Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
+#
+# Author: Xavier Claessens <xavier.claessens@collabora.com>
+
+import os
+import sys
+
+if len(sys.argv) < 3:
+    print(
+        "Usage: {} <output file> <input file 1> ...".format(
+            os.path.basename(sys.argv[0])
+        )
+    )
+    sys.exit(1)
+
+with open(sys.argv[1], "w") as outfile:
+    for fname in sys.argv[2:]:
+        with open(fname) as infile:
+            for line in infile:
+                outfile.write(line)

docs/reference/gio/gapplication.xml

@@ -0,0 +1,352 @@
+<refentry id="gapplication-tool" lang="en">
+  <refentryinfo>
+    <title>gapplication</title>
+    <productname>GIO</productname>
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Ryan</firstname>
+        <surname>Lortie</surname>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>gapplication</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>gapplication</refname>
+    <refpurpose>D-Bus application launcher</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">help</arg>
+      <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">version</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">list-apps</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">launch</arg>
+      <arg choice="plain"><replaceable>APPID</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">launch</arg>
+      <arg choice="plain"><replaceable>APPID</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">list-actions</arg>
+      <arg choice="plain"><replaceable>APPID</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gapplication</command>
+      <arg choice="plain">action</arg>
+      <arg choice="plain"><replaceable>APPID</replaceable></arg>
+      <arg choice="plain"><replaceable>ACTION</replaceable></arg>
+      <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      <command>gapplication</command> is a commandline implementation of the client-side of the
+      <interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
+      Desktop Entry Specification.
+    </para>
+
+    <para>
+      <command>gapplication</command> can be used to start applications that have
+      <varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
+      files and can be used to send messages to already-running instances of other applications.
+    </para>
+
+    <para>
+      It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
+      line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
+      with implementations that do not directly support <varname>DBusActivatable</varname>.
+    </para>
+
+    <para>
+      <command>gapplication</command> ships as part of <application>GLib</application>.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Commands</title>
+
+    <refsect2>
+      <title>Global commands</title>
+
+      <variablelist>
+        <varlistentry>
+          <term>
+            <command>help</command>
+            <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+          </term>
+          <listitem>
+            <para>
+              Displays a short synopsis of the available commands or provides detailed help on a specific
+              command.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <command>version</command>
+          </term>
+          <listitem>
+            <para>
+              Prints the GLib version whence <command>gapplication</command> came.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <command>list-apps</command>
+          </term>
+          <listitem>
+            <para>
+              Prints a list of all application IDs that are known to support D-Bus activation.  This list is
+              generated by scanning <filename class='extension'>.desktop</filename> files as per the current
+              <envar>XDG_DATA_DIRS</envar>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <command>launch</command>
+            <arg choice="plain"><replaceable>APPID</replaceable></arg>
+            <arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
+          </term>
+          <listitem>
+            <para>
+              Launches an application.
+            </para>
+            <para> 
+              The first parameter is the application ID in the familiar "reverse DNS" style (eg:
+              '<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
+              suffix.
+            </para>
+            <para>
+              Optionally, if additional parameters are given, they are treated as the names of files to open and
+              may be filenames or URIs.  If no files are given then the application is simply activated.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <command>list-actions</command>
+            <arg choice="plain"><replaceable>APPID</replaceable></arg>
+          </term>
+          <listitem>
+            <para>
+              List the actions declared in the application's <filename class='extension'>.desktop</filename>
+              file.  The parameter is the application ID, as above.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <command>action</command>
+            <arg choice="plain"><replaceable>APPID</replaceable></arg>
+            <arg choice="plain"><replaceable>ACTION</replaceable></arg>
+            <arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
+          </term>
+          <listitem>
+            <para>
+              Invokes the named action (in the same way as would occur when activating an action specified in
+              the <filename class='extension'>.desktop</filename> file).
+            </para>
+            <para>
+              The application ID (as above) is the first parameter.  The action name follows.
+            </para>
+            <para>
+              Optionally, following the action name can be one parameter, in GVariant format, given as a single
+              argument.  Make sure to use sufficient quoting.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <refsect2>
+      <title>From the commandline</title>
+
+      <para>
+        Launching an application:
+      </para>
+
+      <programlisting>
+        gapplication launch org.example.fooview
+      </programlisting>
+
+      <para>
+        Opening a file with an application:
+      </para>
+
+      <programlisting>
+        gapplication launch org.example.fooview ~/file.foo
+      </programlisting>
+
+      <para>
+        Opening many files with an application:
+      </para>
+
+      <programlisting>
+        gapplication launch org.example.fooview ~/foos/*.foo
+      </programlisting>
+
+      <para>
+        Invoking an action on an application:
+      </para>
+
+      <programlisting>
+        gapplication action org.example.fooview create
+      </programlisting>
+
+      <para>
+        Invoking an action on an application, with an action:
+      </para>
+
+      <programlisting>
+        gapplication action org.example.fooview show-item '"item_id_828739"'
+      </programlisting>
+    </refsect2>
+
+    <refsect2>
+      <title>
+        From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
+      </title>
+
+      <para>
+        The commandline interface of <command>gapplication</command> was designed so that it could be used
+        directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
+        file.
+      </para>
+
+      <para>
+        You might want to do this to allow for backwards compatibility with implementations of the specification
+        that do not understand how to do D-Bus activation, without having to install a separate utility program.
+      </para>
+
+      <para>
+        Consider the following example:
+      </para>
+
+      <programlisting>
+        [Desktop Entry]
+        Version=1.1
+        Type=Application
+        Name=Foo Viewer
+        DBusActivatable=true
+        MimeType=image/x-foo;
+        Exec=gapplication launch org.example.fooview %F
+        Actions=gallery;create;
+
+        [Desktop Action gallery]
+        Name=Browse Gallery
+        Exec=gapplication action org.example.fooview gallery
+
+        [Desktop Action create]
+        Name=Create a new Foo!
+        Exec=gapplication action org.example.fooview create
+      </programlisting>
+    </refsect2>
+
+    <refsect2>
+      <title>From a script</title>
+
+      <para>
+        If installing an application that supports D-Bus activation you may still want to put a file in
+        <filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
+      </para>
+
+      <para>
+        It is possible for this file to be a shell script.  The script can handle arguments such as --help and
+        --version directly.  It can also parse other command line arguments and convert them to uses of
+        <command>gapplication</command> to activate the application, open files, or invoke actions.
+      </para>
+
+      <para>
+        Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
+      </para>
+
+      <programlisting>
+        #!/bin/sh
+
+        case "$1" in
+          --help)
+            echo "see 'man fooview' for more information"
+            ;;
+
+          --version)
+            echo "fooview 1.2"
+            ;;
+
+          --gallery)
+            gapplication action org.example.fooview gallery
+            ;;
+
+          --create)
+            gapplication action org.example.fooview create
+            ;;
+
+          -*)
+            echo "unrecognised commandline argument"
+            exit 1
+            ;;
+
+          *)
+            gapplication launch org.example.fooview "$@"
+            ;;
+        esac
+      </programlisting>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+    <para>
+      <ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
+      <citerefentry>
+        <refentrytitle>gdbus</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>xdg-open</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>desktop-file-validate</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>

docs/reference/gio/gdbus-object-manager-example/.gitignore

@@ -0,0 +1 @@
+gdbus-object-manager-example-overrides.txt

docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-docs.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <part>
+    <title>GDBus ObjctManager Example</title>
+    <chapter>
+      <title>Interfaces</title>
+      <xi:include href="xml/ExampleAnimal.xml"/>
+      <xi:include href="xml/ExampleCat.xml"/>
+      <xi:include href="xml/ExampleObject.xml"/>
+      <xi:include href="xml/ExampleObjectManagerClient.xml"/>
+    </chapter>
+  </part>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>

docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-sections.txt

@@ -0,0 +1,161 @@
+<SECTION>
+<FILE>ExampleAnimal</FILE>
+<TITLE>ExampleAnimal</TITLE>
+ExampleAnimal
+ExampleAnimalIface
+example_animal_interface_info
+example_animal_override_properties
+example_animal_call_poke
+example_animal_call_poke_finish
+example_animal_call_poke_sync
+example_animal_complete_poke
+example_animal_emit_jumped
+example_animal_get_mood
+example_animal_get_foo
+example_animal_get_bar
+example_animal_dup_mood
+example_animal_dup_foo
+example_animal_dup_bar
+example_animal_set_mood
+example_animal_set_foo
+example_animal_set_bar
+ExampleAnimalProxy
+ExampleAnimalProxyClass
+example_animal_proxy_new
+example_animal_proxy_new_finish
+example_animal_proxy_new_sync
+example_animal_proxy_new_for_bus
+example_animal_proxy_new_for_bus_finish
+example_animal_proxy_new_for_bus_sync
+ExampleAnimalSkeleton
+ExampleAnimalSkeletonClass
+example_animal_skeleton_new
+<SUBSECTION Standard>
+example_animal_get_type
+example_animal_proxy_get_type
+example_animal_skeleton_get_type
+ExampleAnimalSkeletonPrivate
+ExampleAnimalProxyPrivate
+EXAMPLE_TYPE_ANIMAL
+EXAMPLE_TYPE_ANIMAL_PROXY
+EXAMPLE_TYPE_ANIMAL_SKELETON
+EXAMPLE_ANIMAL
+EXAMPLE_ANIMAL_GET_IFACE
+EXAMPLE_ANIMAL_PROXY
+EXAMPLE_ANIMAL_PROXY_CLASS
+EXAMPLE_ANIMAL_PROXY_GET_CLASS
+EXAMPLE_ANIMAL_SKELETON
+EXAMPLE_ANIMAL_SKELETON_CLASS
+EXAMPLE_ANIMAL_SKELETON_GET_CLASS
+EXAMPLE_IS_ANIMAL
+EXAMPLE_IS_ANIMAL_PROXY
+EXAMPLE_IS_ANIMAL_PROXY_CLASS
+EXAMPLE_IS_ANIMAL_SKELETON
+EXAMPLE_IS_ANIMAL_SKELETON_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>ExampleCat</FILE>
+<TITLE>ExampleCat</TITLE>
+ExampleCat
+ExampleCatIface
+example_cat_interface_info
+example_cat_override_properties
+ExampleCatProxy
+ExampleCatProxyClass
+example_cat_proxy_new
+example_cat_proxy_new_finish
+example_cat_proxy_new_sync
+example_cat_proxy_new_for_bus
+example_cat_proxy_new_for_bus_finish
+example_cat_proxy_new_for_bus_sync
+ExampleCatSkeleton
+ExampleCatSkeletonClass
+example_cat_skeleton_new
+<SUBSECTION Standard>
+example_cat_get_type
+example_cat_proxy_get_type
+example_cat_skeleton_get_type
+ExampleCatProxyPrivate
+ExampleCatSkeletonPrivate
+EXAMPLE_TYPE_CAT
+EXAMPLE_TYPE_CAT_PROXY
+EXAMPLE_TYPE_CAT_SKELETON
+EXAMPLE_CAT
+EXAMPLE_CAT_GET_IFACE
+EXAMPLE_CAT_PROXY
+EXAMPLE_CAT_PROXY_CLASS
+EXAMPLE_CAT_PROXY_GET_CLASS
+EXAMPLE_CAT_SKELETON
+EXAMPLE_CAT_SKELETON_CLASS
+EXAMPLE_CAT_SKELETON_GET_CLASS
+EXAMPLE_IS_CAT
+EXAMPLE_IS_CAT_PROXY
+EXAMPLE_IS_CAT_PROXY_CLASS
+EXAMPLE_IS_CAT_SKELETON
+EXAMPLE_IS_CAT_SKELETON_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>ExampleObject</FILE>
+<TITLE>ExampleObject</TITLE>
+ExampleObject
+ExampleObjectIface
+example_object_get_animal
+example_object_get_cat
+example_object_peek_animal
+example_object_peek_cat
+ExampleObjectProxy
+ExampleObjectProxyClass
+example_object_proxy_new
+ExampleObjectSkeleton
+ExampleObjectSkeletonClass
+example_object_skeleton_new
+example_object_skeleton_set_animal
+example_object_skeleton_set_cat
+<SUBSECTION Standard>
+example_object_get_type
+example_object_proxy_get_type
+example_object_skeleton_get_type
+ExampleObjectProxyPrivate
+ExampleObjectSkeletonPrivate
+EXAMPLE_IS_OBJECT
+EXAMPLE_IS_OBJECT_PROXY
+EXAMPLE_IS_OBJECT_PROXY_CLASS
+EXAMPLE_IS_OBJECT_SKELETON
+EXAMPLE_IS_OBJECT_SKELETON_CLASS
+EXAMPLE_OBJECT
+EXAMPLE_OBJECT_GET_IFACE
+EXAMPLE_OBJECT_PROXY
+EXAMPLE_OBJECT_PROXY_CLASS
+EXAMPLE_OBJECT_PROXY_GET_CLASS
+EXAMPLE_OBJECT_SKELETON
+EXAMPLE_OBJECT_SKELETON_CLASS
+EXAMPLE_OBJECT_SKELETON_GET_CLASS
+EXAMPLE_TYPE_OBJECT
+EXAMPLE_TYPE_OBJECT_PROXY
+EXAMPLE_TYPE_OBJECT_SKELETON
+</SECTION>
+
+<SECTION>
+<FILE>ExampleObjectManagerClient</FILE>
+<TITLE>ExampleObjectManagerClient</TITLE>
+ExampleObjectManagerClient
+ExampleObjectManagerClientClass
+example_object_manager_client_get_proxy_type
+example_object_manager_client_new
+example_object_manager_client_new_finish
+example_object_manager_client_new_sync
+example_object_manager_client_new_for_bus
+example_object_manager_client_new_for_bus_finish
+example_object_manager_client_new_for_bus_sync
+<SUBSECTION Standard>
+example_object_manager_client_get_type
+EXAMPLE_IS_OBJECT_MANAGER_CLIENT
+EXAMPLE_IS_OBJECT_MANAGER_CLIENT_CLASS
+EXAMPLE_OBJECT_MANAGER_CLIENT
+EXAMPLE_OBJECT_MANAGER_CLIENT_CLASS
+EXAMPLE_OBJECT_MANAGER_CLIENT_GET_CLASS
+EXAMPLE_TYPE_OBJECT_MANAGER_CLIENT
+ExampleObjectManagerClientPrivate
+</SECTION>

docs/reference/gio/gdbus-object-manager-example/meson.build

@@ -0,0 +1,11 @@
+gdbus_object_manager_example_doc = gnome.gtkdoc('gdbus-object-manager-example',
+  main_xml : 'gdbus-object-manager-example-docs.xml',
+  namespace : 'example',
+  dependencies : [libgdbus_example_objectmanager_dep],
+  src_dir : 'gio/tests/gdbus-object-manager-example',
+  scan_args : gtkdoc_common_scan_args + [
+    '--rebuild-types',
+  ],
+  install : false,
+)
+

docs/reference/gio/gdbus.xml

@@ -0,0 +1,429 @@
+<refentry id="gdbus" lang="en">
+
+<refentryinfo>
+  <title>gdbus</title>
+  <productname>GIO</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>David</firstname>
+      <surname>Zeuthen</surname>
+      <email>zeuthen@gmail.com</email>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>gdbus</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>gdbus</refname>
+  <refpurpose>Tool for working with D-Bus objects</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">introspect</arg>
+    <group>
+      <arg choice="plain">--system</arg>
+      <arg choice="plain">--session</arg>
+      <arg choice="plain">--address <replaceable>address</replaceable></arg>
+    </group>
+    <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
+    <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+    <group>
+      <arg choice="plain">--xml</arg>
+    </group>
+    <group>
+      <arg choice="plain">--recurse</arg>
+    </group>
+    <group>
+      <arg choice="plain">--only-properties</arg>
+    </group>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">monitor</arg>
+    <group>
+      <arg choice="plain">--system</arg>
+      <arg choice="plain">--session</arg>
+      <arg choice="plain">--address <replaceable>address</replaceable></arg>
+    </group>
+    <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
+    <group>
+      <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+    </group>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">call</arg>
+    <group>
+      <arg choice="plain">--system</arg>
+      <arg choice="plain">--session</arg>
+      <arg choice="plain">--address <replaceable>address</replaceable></arg>
+    </group>
+    <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
+    <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+    <arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
+    <group>
+      <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
+      <arg choice="plain">--interactive</arg>
+    </group>
+    <arg choice="plain">ARG1</arg>
+    <arg choice="plain" rep="repeat">ARG2</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">emit</arg>
+    <group>
+      <arg choice="plain">--system</arg>
+      <arg choice="plain">--session</arg>
+      <arg choice="plain">--address <replaceable>address</replaceable></arg>
+    </group>
+    <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
+    <arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
+    <group>
+      <arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
+    </group>
+    <arg choice="plain">ARG1</arg>
+    <arg choice="plain" rep="repeat">ARG2</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">wait</arg>
+    <group>
+      <arg choice="plain">--system</arg>
+      <arg choice="plain">--session</arg>
+      <arg choice="plain">--address <replaceable>address</replaceable></arg>
+    </group>
+    <arg choice="plain">--activate <replaceable>bus_name</replaceable></arg>
+    <group>
+      <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
+    </group>
+    <arg choice="plain"><replaceable>bus_name</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gdbus</command>
+    <arg choice="plain">help</arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+  <title>Description</title>
+  <para>
+    <command>gdbus</command> is a simple tool for working with D-Bus objects.
+  </para>
+</refsect1>
+<refsect1>
+    <title>Commands</title>
+    <variablelist>
+      <varlistentry>
+        <term><option>introspect</option></term>
+        <listitem><para>
+          Prints out interfaces and property values for a remote object.
+          For this to work, the owner of the object needs to implement the
+          <literal>org.freedesktop.DBus.Introspectable</literal> interface.
+          If the <option>--xml</option> option is used, the returned
+          introspection XML is printed, otherwise a parsed pretty
+          representation is printed.
+          The <option>--recurse</option> option can be used to
+          introspect children (and their children and so on) and the
+          <option>--only-properties</option> option can be used to
+          only print the interfaces with properties.
+          </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>monitor</option></term>
+        <listitem><para>
+          Monitors one or all objects owned by the owner of
+          <replaceable>bus_name</replaceable>.
+        </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>call</option></term>
+        <listitem><para>
+          Invokes a method on a remote object.  Each argument to pass to the
+          method must be specified as a serialized
+          <link linkend="GVariant"><type>GVariant</type></link> except that strings do
+          not need explicit quotes. The return values are printed out as
+          serialized <link linkend="GVariant"><type>GVariant</type></link>
+          values.
+        </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>emit</option></term>
+        <listitem><para>
+          Emits a signal. Each argument to include in the signal must be specified as a serialized
+          <link linkend="GVariant"><type>GVariant</type></link> except that strings do
+          not need explicit quotes.
+        </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>wait</option></term>
+        <listitem><para>
+          Waits until <replaceable>bus_name</replaceable> is owned by some
+          process on the bus. If the <option>--activate</option> is specified,
+          that bus name will be auto-started first. It may be the same as the
+          bus name being waited for, or different.
+        </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>help</option></term>
+        <listitem><para>
+          Prints help and exit.
+        </para></listitem>
+      </varlistentry>
+    </variablelist>
+</refsect1>
+
+<refsect1>
+  <title>Bash Completion</title>
+  <para>
+    <command>gdbus</command> ships with a bash completion script to
+    complete commands, destinations, bus names, object paths and
+    interface/method names.
+  </para>
+</refsect1>
+
+<refsect1>
+  <title>Examples</title>
+  This shows how to introspect an object - note that the value of each
+  property is displayed:
+<programlisting>
+$ gdbus introspect --system \
+        --dest org.freedesktop.NetworkManager \
+        --object-path /org/freedesktop/NetworkManager/Devices/0
+node /org/freedesktop/NetworkManager/Devices/0 {
+  interface org.freedesktop.DBus.Introspectable {
+    methods:
+      Introspect(out s data);
+  };
+  interface org.freedesktop.DBus.Properties {
+    methods:
+      Get(in  s interface,
+          in  s propname,
+          out v value);
+      Set(in  s interface,
+          in  s propname,
+          in  v value);
+      GetAll(in  s interface,
+             out a{sv} props);
+  };
+  interface org.freedesktop.NetworkManager.Device.Wired {
+    signals:
+      PropertiesChanged(a{sv} arg_0);
+    properties:
+      readonly b Carrier = false;
+      readonly u Speed = 0;
+      readonly s HwAddress = '00:1D:72:88:BE:97';
+  };
+  interface org.freedesktop.NetworkManager.Device {
+    methods:
+      Disconnect();
+    signals:
+      StateChanged(u arg_0,
+                   u arg_1,
+                   u arg_2);
+    properties:
+      readonly u DeviceType = 1;
+      readonly b Managed = true;
+      readwrite o Ip6Config = '/';
+      readwrite o Dhcp4Config = '/';
+      readwrite o Ip4Config = '/';
+      readonly u State = 2;
+      readwrite u Ip4Address = 0;
+      readonly u Capabilities = 3;
+      readonly s Driver = 'e1000e';
+      readwrite s Interface = 'eth0';
+      readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
+  };
+};
+</programlisting>
+<para>
+  The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
+</para>
+<programlisting>
+$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse  --only-properties 
+node / {
+  node /org {
+    node /org/freedesktop {
+      node /org/freedesktop/UPower {
+        interface org.freedesktop.UPower {
+          properties:
+            readonly b IsDocked = true;
+            readonly b LidForceSleep = false;
+            readonly b LidIsPresent = false;
+            readonly b LidIsClosed = false;
+            readonly b OnLowBattery = false;
+            readonly b OnBattery = false;
+            readonly b CanHibernate = true;
+            readonly b CanSuspend = true;
+            readonly s DaemonVersion = '0.9.10';
+        };
+        node /org/freedesktop/UPower/Policy {
+        };
+        node /org/freedesktop/UPower/Wakeups {
+          interface org.freedesktop.UPower.Wakeups {
+            properties:
+              readonly b HasCapability = true;
+          };
+        };
+      };
+    };
+  };
+};
+</programlisting>
+<para>
+  In a similar fashion, the <option>introspect</option> command can be
+  used to learn details about the <literal>Notify</literal> method:
+</para>
+<programlisting>
+[...]
+  interface org.freedesktop.Notifications {
+    methods:
+      GetServerInformation(out s return_name,
+                           out s return_vendor,
+                           out s return_version,
+                           out s return_spec_version);
+      GetCapabilities(out as return_caps);
+      CloseNotification(in  u id);
+      Notify(in  s app_name,
+             in  u id,
+             in  s icon,
+             in  s summary,
+             in  s body,
+             in  as actions,
+             in  a{sv} hints,
+             in  i timeout,
+             out u return_id);
+  };
+[...]
+</programlisting>
+<para>
+  With this information, it's easy to use the <option>call</option>
+  command to display a notification
+</para>
+<programlisting>
+$ gdbus call --session \
+             --dest org.freedesktop.Notifications \
+             --object-path /org/freedesktop/Notifications \
+             --method org.freedesktop.Notifications.Notify \
+             my_app_name \
+             42 \
+             gtk-dialog-info \
+             "The Summary" \
+             "Here's the body of the notification" \
+             [] \
+             {} \
+             5000
+(uint32 12,)
+</programlisting>
+<para>
+  Call a method with file handle argument:
+</para>
+<programlisting>
+$ gdbus call --session \
+             --dest org.example.foo \
+             --object-path /org/example/foo \
+             --method SendFDs \
+             1 \
+             10 \
+             10&lt;file.foo
+</programlisting>
+<para>
+  Monitoring all objects on a service:
+</para>
+<programlisting>
+$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
+Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
+The name org.freedesktop.ConsoleKit is owned by :1.15
+/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
+/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
+/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
+/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
+</programlisting>
+<para>
+  Monitoring a single object on a service:
+</para>
+<programlisting>
+$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
+Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
+The name org.freedesktop.NetworkManager is owned by :1.5
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5c&gt;},)
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
+/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
+</programlisting>
+
+<para>
+  Emitting a signal:
+</para>
+<programlisting>
+$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
+</programlisting>
+
+<para>
+  Emitting a signal to a specific process:
+</para>
+<programlisting>
+$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
+</programlisting>
+
+<para>
+  Waiting for a well-known name to be owned on the bus; this will
+  <emphasis>not</emphasis> auto-start the service:
+</para>
+<programlisting>
+$ gdbus wait --session org.bar.SomeName
+</programlisting>
+
+<para>
+  Auto-starting then waiting for a well-known name to be owned on the bus:
+</para>
+<programlisting>
+$ gdbus wait --session --activate org.bar.SomeName
+</programlisting>
+
+<para>
+  Auto-starting a different service, then waiting for a well-known name to be
+  owned on the bus. This is useful in situations where
+  <replaceable>SomeName</replaceable> is not directly activatable:
+</para>
+<programlisting>
+$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
+</programlisting>
+
+<para>
+  Waiting for a well-known name and giving up after 30 seconds. By default,
+  the timeout is disabled; or set <option>--timeout</option> to 0 to disable it:
+</para>
+<programlisting>
+$ gdbus wait --session --timeout 30 org.bar.SomeName
+</programlisting>
+
+</refsect1>
+
+<refsect1>
+  <title>Bugs</title>
+  <para>
+    Please send bug reports to either the distribution bug tracker
+    or the upstream bug tracker at
+    <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>.
+  </para>
+</refsect1>
+
+<refsect1>
+  <title>See Also</title>
+  <para>
+    <citerefentry>
+      <refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
+    </citerefentry>
+  </para>
+</refsect1>
+
+</refentry>
+

docs/reference/gio/gio-docs-unix.xml

@@ -0,0 +1,3 @@
+<chapter id='unix-support'>
+<!--FIXME: fill this with unix APIs that cannot build on Windows -->
+</chapter>

docs/reference/gio/gio-docs-win32.xml

@@ -0,0 +1,6 @@
+<chapter id='win32-support'>
+    <title>Win32 support</title>
+    <xi:include href="xml/gwin32registrykey.xml"/>
+    <xi:include href="xml/gwin32inputstream.xml"/>
+    <xi:include href="xml/gwin32outputstream.xml"/>
+</chapter>

docs/reference/gio/gio-docs.xml

@@ -0,0 +1,406 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
+                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book lang="en" id="gio" xmlns:xi="http://www.w3.org/2003/XInclude">
+<title>GIO Reference Manual</title>
+  <bookinfo>
+    <title>GIO Reference Manual</title>
+    <releaseinfo>
+      for GIO &version;
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="https://developer.gnome.org/gio/unstable/">https://developer.gnome.org/gio/unstable/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <xi:include href="xml/overview.xml"/>
+
+  <part>
+  <title>API Reference</title>
+    <chapter id="file_ops">
+        <title>File Operations</title>
+        <xi:include href="xml/gfile.xml"/>
+        <xi:include href="xml/gfileattribute.xml"/>
+        <xi:include href="xml/gfileinfo.xml"/>
+        <xi:include href="xml/gfileenumerator.xml"/>
+        <xi:include href="xml/gioerror.xml"/>
+        <xi:include href="xml/gmountoperation.xml"/>
+    </chapter>
+    <chapter id="file_mon">
+        <title>File System Monitoring</title>
+        <xi:include href="xml/gfilemonitor.xml"/>
+    </chapter>
+    <chapter id="utils">
+        <title>File-related Utilities</title>
+        <xi:include href="xml/gfilenamecompleter.xml"/>
+    </chapter>
+    <chapter id="async">
+        <title>Asynchronous I/O</title>
+        <xi:include href="xml/gcancellable.xml"/>
+        <xi:include href="xml/gasyncresult.xml"/>
+        <xi:include href="xml/gtask.xml"/>
+        <xi:include href="xml/gioscheduler.xml"/>
+        <xi:include href="xml/gsimpleasyncresult.xml"/>
+    </chapter>
+    <chapter id="conversion">
+        <title>Data conversion</title>
+        <xi:include href="xml/gconverter.xml"/>
+        <xi:include href="xml/gcharsetconverter.xml"/>
+        <xi:include href="xml/gzlibcompressor.xml"/>
+        <xi:include href="xml/gzlibdecompressor.xml"/>
+    </chapter>
+    <chapter id="streaming">
+        <title>Streaming I/O</title>
+        <xi:include href="xml/gseekable.xml"/>
+        <xi:include href="xml/ginputstream.xml"/>
+        <xi:include href="xml/goutputstream.xml"/>
+        <xi:include href="xml/giostream.xml"/>
+        <xi:include href="xml/gsimpleiostream.xml"/>
+        <xi:include href="xml/gfileinputstream.xml"/>
+        <xi:include href="xml/gfileoutputstream.xml"/>
+        <xi:include href="xml/gfileiostream.xml"/>
+        <xi:include href="xml/gfiledescriptorbased.xml"/>
+        <xi:include href="xml/gfilterinputstream.xml"/>
+        <xi:include href="xml/gfilteroutputstream.xml"/>
+        <xi:include href="xml/gmemoryinputstream.xml"/>
+        <xi:include href="xml/gmemoryoutputstream.xml"/>
+        <xi:include href="xml/gbufferedinputstream.xml"/>
+        <xi:include href="xml/gbufferedoutputstream.xml"/>
+        <xi:include href="xml/gdatainputstream.xml"/>
+        <xi:include href="xml/gdataoutputstream.xml"/>
+        <xi:include href="xml/gunixinputstream.xml"/>
+        <xi:include href="xml/gunixoutputstream.xml"/>
+        <xi:include href="xml/gconverterinputstream.xml"/>
+        <xi:include href="xml/gconverteroutputstream.xml"/>
+        <xi:include href="xml/gpollableinputstream.xml"/>
+        <xi:include href="xml/gpollableoutputstream.xml"/>
+        <xi:include href="xml/gpollableutils.xml"/>
+    </chapter>
+    <chapter id="types">
+        <title>File types and applications</title>
+        <xi:include href="xml/gcontenttype.xml"/>
+        <xi:include href="xml/gappinfo.xml"/>
+        <xi:include href="xml/gappinfomonitor.xml"/>
+        <xi:include href="xml/gdesktopappinfo.xml"/>
+    </chapter>
+    <chapter id="volume_mon">
+        <title>Volumes and Drives</title>
+        <xi:include href="xml/gvolumemonitor.xml"/>
+        <xi:include href="xml/gvolume.xml"/>
+        <xi:include href="xml/gmount.xml"/>
+        <xi:include href="xml/gdrive.xml"/>
+        <xi:include href="xml/gunixmounts.xml"/>
+    </chapter>
+    <chapter id="icons">
+        <title>Icons</title>
+        <xi:include href="xml/gicon.xml"/>
+        <xi:include href="xml/gfileicon.xml"/>
+        <xi:include href="xml/gbytesicon.xml"/>
+        <xi:include href="xml/gloadableicon.xml"/>
+        <xi:include href="xml/gthemedicon.xml"/>
+        <xi:include href="xml/gemblemedicon.xml"/>
+        <xi:include href="xml/gemblem.xml"/>
+    </chapter>
+    <chapter id="failable_initialization">
+        <title>Failable Initialization</title>
+        <xi:include href="xml/ginitable.xml"/>
+        <xi:include href="xml/gasyncinitable.xml"/>
+    </chapter>
+    <chapter id="subprocesses">
+      <title>Subprocesses</title>
+      <xi:include href="xml/gsubprocess.xml"/>
+      <xi:include href="xml/gsubprocesslauncher.xml"/>
+    </chapter>
+    <chapter id="networking">
+      <title>Low-level network support</title>
+      <xi:include href="xml/gsocket.xml"/>
+      <xi:include href="xml/gdatagrambased.xml"/>
+      <xi:include href="xml/ginetaddress.xml"/>
+      <xi:include href="xml/ginetaddressmask.xml"/>
+      <xi:include href="xml/gsocketaddress.xml"/>
+      <xi:include href="xml/ginetsocketaddress.xml"/>
+      <xi:include href="xml/gunixsocketaddress.xml"/>
+      <xi:include href="xml/gnativesocketaddress.xml"/>
+      <xi:include href="xml/gsocketcontrolmessage.xml"/>
+      <xi:include href="xml/gunixfdlist.xml"/>
+      <xi:include href="xml/gunixfdmessage.xml"/>
+      <xi:include href="xml/gcredentials.xml"/>
+      <xi:include href="xml/gunixcredentialsmessage.xml"/>
+      <xi:include href="xml/gproxy.xml"/>
+      <xi:include href="xml/gproxyaddress.xml"/>
+      <xi:include href="xml/gnetworking.xml"/>
+    </chapter>
+    <chapter id="highlevel-socket">
+      <title>High-level network functionality</title>
+      <xi:include href="xml/gsocketclient.xml"/>
+      <xi:include href="xml/gsocketconnection.xml"/>
+      <xi:include href="xml/gunixconnection.xml"/>
+      <xi:include href="xml/gtcpconnection.xml"/>
+      <xi:include href="xml/gtcpwrapperconnection.xml"/>
+      <xi:include href="xml/gsocketlistener.xml"/>
+      <xi:include href="xml/gsocketservice.xml"/>
+      <xi:include href="xml/gthreadedsocketservice.xml"/>
+      <xi:include href="xml/gnetworkmonitor.xml"/>
+    </chapter>
+    <chapter id="tls">
+      <title>TLS (SSL) support</title>
+      <xi:include href="xml/gtls.xml"/>
+      <xi:include href="xml/gtlscertificate.xml"/>
+      <xi:include href="xml/gtlsconnection.xml"/>
+      <xi:include href="xml/gtlsclientconnection.xml"/>
+      <xi:include href="xml/gtlsserverconnection.xml"/>
+      <xi:include href="xml/gdtlsconnection.xml"/>
+      <xi:include href="xml/gdtlsclientconnection.xml"/>
+      <xi:include href="xml/gdtlsserverconnection.xml"/>
+      <xi:include href="xml/gtlsbackend.xml"/>
+      <xi:include href="xml/gtlsdatabase.xml"/>
+      <xi:include href="xml/gtlsfiledatabase.xml"/>
+      <xi:include href="xml/gtlsinteraction.xml"/>
+      <xi:include href="xml/gtlspassword.xml"/>
+    </chapter>
+    <chapter id="resolver">
+      <title>DNS resolution</title>
+      <xi:include href="xml/gresolver.xml"/>
+      <xi:include href="xml/gproxyresolver.xml"/>
+      <xi:include href="xml/gsimpleproxyresolver.xml"/>
+      <xi:include href="xml/gsocketconnectable.xml"/>
+      <xi:include href="xml/gsocketaddressenumerator.xml"/>
+      <xi:include href="xml/gproxyaddressenumerator.xml"/>
+      <xi:include href="xml/gnetworkaddress.xml"/>
+      <xi:include href="xml/gnetworkservice.xml"/>
+      <xi:include href="xml/gsrvtarget.xml"/>
+    </chapter>
+    <chapter id="gdbus-lowlevel">
+      <title>Low-level D-Bus Support</title>
+      <xi:include href="xml/gdbusutils.xml"/>
+      <xi:include href="xml/gdbusaddress.xml"/>
+      <xi:include href="xml/gdbusintrospection.xml"/>
+      <xi:include href="xml/gdbuserror.xml"/>
+      <xi:include href="xml/gdbusmessage.xml"/>
+      <xi:include href="xml/gdbusconnection.xml"/>
+      <xi:include href="xml/gdbusmethodinvocation.xml"/>
+      <xi:include href="xml/gdbusserver.xml"/>
+      <xi:include href="xml/gdbusauthobserver.xml"/>
+    </chapter>
+    <chapter id="gdbus-convenience">
+      <title>High-level D-Bus Support</title>
+      <xi:include href="xml/gdbusnameowning.xml"/>
+      <xi:include href="xml/gdbusnamewatching.xml"/>
+      <xi:include href="xml/gdbusinterface.xml"/>
+      <xi:include href="xml/gdbusinterfaceskeleton.xml"/>
+      <xi:include href="xml/gdbusproxy.xml"/>
+      <xi:include href="xml/gdbusobject.xml"/>
+      <xi:include href="xml/gdbusobjectskeleton.xml"/>
+      <xi:include href="xml/gdbusobjectproxy.xml"/>
+      <xi:include href="xml/gdbusobjectmanager.xml"/>
+      <xi:include href="xml/gdbusobjectmanagerserver.xml"/>
+      <xi:include href="xml/gdbusobjectmanagerclient.xml"/>
+    </chapter>
+    <chapter id="settings">
+        <title>Settings</title>
+        <xi:include href="xml/gsettings.xml"/>
+        <xi:include href="xml/gsettingsbackend.xml"/>
+        <xi:include href="xml/gsettingsschema.xml"/>
+    </chapter>
+    <chapter id="resources">
+        <title>Resources</title>
+        <xi:include href="xml/gresource.xml"/>
+    </chapter>
+    <chapter id='permissions'>
+        <title>Permissions</title>
+        <xi:include href="xml/gpermission.xml"/>
+        <xi:include href="xml/gsimplepermission.xml"/>
+    </chapter>
+    <chapter id='data-models'>
+        <title>Data Models</title>
+        <xi:include href="xml/glistmodel.xml"/>
+        <xi:include href="xml/gliststore.xml"/>
+    </chapter>
+
+    <chapter id="application">
+        <title>Application support</title>
+        <xi:include href="xml/gapplication.xml"/>
+        <xi:include href="xml/gapplicationcommandline.xml"/>
+        <xi:include href="xml/gactiongroup.xml"/>
+        <xi:include href="xml/gactionmap.xml"/>
+        <xi:include href="xml/gsimpleactiongroup.xml"/>
+        <xi:include href="xml/gaction.xml"/>
+        <xi:include href="xml/gsimpleaction.xml"/>
+        <xi:include href="xml/gpropertyaction.xml"/>
+        <xi:include href="xml/gremoteactiongroup.xml"/>
+        <xi:include href="xml/gactiongroupexporter.xml"/>
+        <xi:include href="xml/gdbusactiongroup.xml"/>
+        <xi:include href="xml/gdebugcontroller.xml"/>
+        <xi:include href="xml/gdebugcontrollerdbus.xml"/>
+        <xi:include href="xml/gmemorymonitor.xml"/>
+        <xi:include href="xml/gmenumodel.xml"/>
+        <xi:include href="xml/gmenu.xml"/>
+        <xi:include href="xml/gmenuexporter.xml"/>
+        <xi:include href="xml/gdbusmenumodel.xml"/>
+        <xi:include href="xml/gnotification.xml"/>
+        <xi:include href="xml/gpowerprofilemonitor.xml"/>
+    </chapter>
+    <chapter id="extending">
+        <title>Extending GIO</title>
+        <xi:include href="xml/gvfs.xml"/>
+        <xi:include href="xml/giomodule.xml"/>
+        <xi:include href="xml/extensionpoints.xml"/>
+    </chapter>
+    <chapter id="tools">
+        <title>GIO Tools</title>
+        <xi:include href="gio-querymodules.xml"/>
+        <xi:include href="gsettings.xml"/>
+        <xi:include href="glib-compile-schemas.xml"/>
+        <xi:include href="glib-compile-resources.xml"/>
+        <xi:include href="gdbus.xml"/>
+        <xi:include href="xml/gdbus-codegen.xml"/>
+        <xi:include href="gresource.xml"/>
+        <xi:include href="gapplication.xml"/>
+        <xi:include href="gio.xml"/>
+    </chapter>
+    <chapter id="testing">
+        <title>GIO Testing</title>
+        <xi:include href="xml/gtestdbus.xml"/>
+    </chapter>
+    <xi:include href="gio-docs-platform.xml"/>
+  </part>
+
+  <part id="migrating">
+    <title>Migrating to GIO</title>
+    <xi:include href="xml/migrating-posix.xml"/>
+    <xi:include href="xml/migrating-gnome-vfs.xml"/>
+    <xi:include href="xml/migrating-gconf.xml"/>
+    <xi:include href="xml/migrating-gdbus.xml"/>
+  </part>
+
+  <chapter id="gio-hierarchy">
+    <title>Object Hierarchy</title>
+      <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  
+  <index id="api-index-full">
+    <title id="index-all">Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-18" role="2.18">
+    <title>Index of new symbols in 2.18</title>
+    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-20" role="2.20">
+    <title>Index of new symbols in 2.20</title>
+    <xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-22" role="2.22">
+    <title>Index of new symbols in 2.22</title>
+    <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-24" role="2.24">
+    <title>Index of new symbols in 2.24</title>
+    <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-26" role="2.26">
+    <title>Index of new symbols in 2.26</title>
+    <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-28" role="2.28">
+    <title>Index of new symbols in 2.28</title>
+    <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-30" role="2.30">
+    <title>Index of new symbols in 2.30</title>
+    <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-32" role="2.32">
+    <title>Index of new symbols in 2.32</title>
+    <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-34" role="2.34">
+    <title>Index of new symbols in 2.34</title>
+    <xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-36" role="2.36">
+    <title>Index of new symbols in 2.36</title>
+    <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-38" role="2.38">
+    <title>Index of new symbols in 2.38</title>
+    <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-40" role="2.40">
+    <title>Index of new symbols in 2.40</title>
+    <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-42" role="2.42">
+    <title>Index of new symbols in 2.42</title>
+    <xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-44" role="2.44">
+    <title>Index of new symbols in 2.44</title>
+    <xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-46" role="2.46">
+    <title>Index of new symbols in 2.46</title>
+    <xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-48" role="2.48">
+    <title>Index of new symbols in 2.48</title>
+    <xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-50" role="2.50">
+    <title>Index of new symbols in 2.50</title>
+    <xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-52" role="2.52">
+    <title>Index of new symbols in 2.52</title>
+    <xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-54" role="2.54">
+    <title>Index of new symbols in 2.54</title>
+    <xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-56" role="2.56">
+    <title>Index of new symbols in 2.56</title>
+    <xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-58" role="2.58">
+    <title>Index of new symbols in 2.58</title>
+    <xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-60" role="2.60">
+    <title>Index of new symbols in 2.60</title>
+    <xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-62" role="2.62">
+    <title>Index of new symbols in 2.62</title>
+    <xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-64" role="2.64">
+    <title>Index of new symbols in 2.64</title>
+    <xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-66" role="2.66">
+    <title>Index of new symbols in 2.66</title>
+    <xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-68" role="2.68">
+    <title>Index of new symbols in 2.68</title>
+    <xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-70" role="2.70">
+    <title>Index of new symbols in 2.70</title>
+    <xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-72" role="2.72">
+    <title>Index of new symbols in 2.72</title>
+    <xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+
+</book>

docs/reference/gio/gio-querymodules.xml

@@ -0,0 +1,45 @@
+<refentry id="gio-querymodules" lang="en">
+
+<refentryinfo>
+  <title>glib-compile-schemas</title>
+  <productname>GIO</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Alexander</firstname>
+      <surname>Larsson</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>gio-querymodules</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>gio-querymodules</refname>
+  <refpurpose>GIO module cache creation</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>gio-querymodules</command>
+    <arg choice="req" rep="repeat">DIRECTORY</arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gio-querymodules</command> creates a
+<filename>giomodule.cache</filename> file in the listed directories.
+This file lists the implemented extension points for each module
+that has been found. It is used by GIO at runtime to avoid opening
+all modules just to find out which extension points they are implementing.
+</para>
+<para>
+GIO modules are usually installed in the <filename>gio/modules</filename>
+subdirectory of libdir.
+</para>
+</refsect1>
+</refentry>

docs/reference/gio/gio-sections-win32.txt

@@ -0,0 +1,112 @@
+<SECTION>
+<FILE>gwin32inputstream</FILE>
+<TITLE>GWin32InputStream</TITLE>
+GWin32InputStream
+g_win32_input_stream_new
+g_win32_input_stream_set_close_handle
+g_win32_input_stream_get_close_handle
+g_win32_input_stream_get_handle
+<SUBSECTION Standard>
+GWin32InputStreamClass
+G_WIN32_INPUT_STREAM
+G_IS_WIN32_INPUT_STREAM
+G_TYPE_WIN32_INPUT_STREAM
+G_WIN32_INPUT_STREAM_CLASS
+G_IS_WIN32_INPUT_STREAM_CLASS
+G_WIN32_INPUT_STREAM_GET_CLASS
+<SUBSECTION Private>
+g_win32_input_stream_get_type
+GWin32InputStreamPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gwin32outputstream</FILE>
+<TITLE>GWin32OutputStream</TITLE>
+GWin32OutputStream
+g_win32_output_stream_new
+g_win32_output_stream_set_close_handle
+g_win32_output_stream_get_close_handle
+g_win32_output_stream_get_handle
+<SUBSECTION Standard>
+GWin32OutputStreamClass
+G_WIN32_OUTPUT_STREAM
+G_IS_WIN32_OUTPUT_STREAM
+G_TYPE_WIN32_OUTPUT_STREAM
+G_WIN32_OUTPUT_STREAM_CLASS
+G_IS_WIN32_OUTPUT_STREAM_CLASS
+G_WIN32_OUTPUT_STREAM_GET_CLASS
+<SUBSECTION Private>
+g_win32_output_stream_get_type
+GWin32OutputStreamPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gwin32registrykey</FILE>
+
+<SUBSECTION>
+GWin32RegistrySubkeyIter
+g_win32_registry_subkey_iter_copy
+g_win32_registry_subkey_iter_free
+g_win32_registry_subkey_iter_assign
+
+<SUBSECTION>
+GWin32RegistryValueIter
+g_win32_registry_value_iter_copy
+g_win32_registry_value_iter_free
+g_win32_registry_value_iter_assign
+
+<SUBSECTION>
+GWin32RegistryKey
+g_win32_registry_key_new
+g_win32_registry_key_new_w
+g_win32_registry_key_get_child
+g_win32_registry_key_get_child_w
+
+<SUBSECTION>
+g_win32_registry_subkey_iter_init
+g_win32_registry_subkey_iter_clear
+g_win32_registry_subkey_iter_n_subkeys
+g_win32_registry_subkey_iter_next
+g_win32_registry_subkey_iter_get_name
+g_win32_registry_subkey_iter_get_name_w
+
+<SUBSECTION>
+g_win32_registry_value_iter_init
+g_win32_registry_value_iter_clear
+g_win32_registry_value_iter_n_values
+g_win32_registry_value_iter_next
+GWin32RegistryValueType
+g_win32_registry_value_iter_get_value_type
+g_win32_registry_value_iter_get_name
+g_win32_registry_value_iter_get_name_w
+g_win32_registry_value_iter_get_data
+g_win32_registry_value_iter_get_data_w
+
+<SUBSECTION>
+g_win32_registry_key_get_value
+g_win32_registry_key_get_value_w
+g_win32_registry_key_get_path
+g_win32_registry_key_get_path_w
+GWin32RegistryKeyWatchCallbackFunc
+GWin32RegistryKeyWatcherFlags
+g_win32_registry_key_watch
+g_win32_registry_key_has_changed
+g_win32_registry_key_erase_change_indicator
+
+<SUBSECTION Standard>
+GWin32RegistryKeyClass
+
+<SUBSECTION Private>
+GWin32RegistryKeyPrivate
+g_win32_registry_key_get_type
+g_win32_registry_subkey_iter_get_type
+g_win32_registry_value_iter_get_type
+G_TYPE_WIN32_REGISTRY_KEY
+G_WIN32_REGISTRY_KEY
+G_WIN32_REGISTRY_KEY_CLASS
+G_IS_WIN32_REGISTRY_KEY
+G_IS_WIN32_REGISTRY_KEY_CLASS
+G_WIN32_REGISTRY_KEY_GET_CLASS
+G_TYPE_WIN32_REGISTRY_SUBKEY_ITER
+G_TYPE_WIN32_REGISTRY_VALUE_ITER
+</SECTION>

docs/reference/gio/gio.xml

@@ -0,0 +1,805 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<refentry id="gio">
+  <refentryinfo>
+    <title>gio</title>
+    <productname>GIO</productname>
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Matthias</firstname>
+        <surname>Clasen</surname>
+        <email>mclasen@redhat.com</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>gio</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>gio</refname>
+    <refpurpose>GIO commandline tool</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">help</arg>
+      <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">version</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">cat</arg>
+      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">copy</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
+      <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">info</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">launch</arg>
+      <arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">list</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">mime</arg>
+      <arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
+      <arg choice="opt"><replaceable>HANDLER</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">mkdir</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">monitor</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">mount</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">move</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
+      <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">open</arg>
+      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">rename</arg>
+      <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
+      <arg choice="plain"><replaceable>NAME</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">remove</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">save</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">set</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
+      <arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">trash</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>gio</command>
+      <arg choice="plain">tree</arg>
+      <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+      <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para><command>gio</command> is a utility that makes many of the GIO
+      features available from the commandline. In doing so, it provides
+      commands that are similar to traditional utilities, but let you
+      use GIO locations instead of local files: for example you can use
+      something like <filename>smb://server/resource/file.txt</filename>
+      as a location.</para>
+    <para>Plain filenames which contain a colon will be interpreted as URIs
+      with an unknown protocol. To avoid this, prefix them with a path such as
+      <filename>./</filename>, or with the <literal>file:</literal> protocol.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Commands</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>
+          <command>help</command>
+          <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Displays a short synopsis of the available commands or provides
+            detailed help on a specific command.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>version</command>
+        </term>
+        <listitem>
+          <para>Prints the GLib version to which <command>gio</command>
+            belongs.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>cat</command>
+          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Concatenates the given files and prints them to the standard
+            output.</para>
+          <para>The <command>cat</command> command works just like the traditional <command>cat</command> utility.</para>
+          <para>Note: just pipe through <command>cat</command> if you need its formatting options
+            like <option>-n</option>, <option>-T</option> or other.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>copy</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
+          <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Copies one or more files from <replaceable>SOURCE</replaceable>
+            to <replaceable>DESTINATION</replaceable>. If more than one source
+            is specified, the destination must be a directory.</para>
+          <para>The <command>copy</command> command is similar to the traditional <command>cp</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-T</option>, <option>--no-target-directory</option></term>
+                <listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-p</option>, <option>--progress</option></term>
+                <listitem><para>Show progress.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-i</option>, <option>--interactive</option></term>
+                <listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--preserve</option></term>
+                <listitem><para>Preserve all attributes of copied files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-b</option>, <option>--backup</option></term>
+                <listitem><para>Create backups of existing destination files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-P</option>, <option>--no-dereference</option></term>
+                <listitem><para>Never follow symbolic links.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--default-permissions</option></term>
+                <listitem><para>Use the default permissions of the current process for the destination file, rather than copying the permissions of the source file.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <command>info</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Shows information about the given locations.</para>
+          <para>The <command>info</command> command is similar to the traditional <command>ls</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-w</option>, <option>--query-writable</option></term>
+                <listitem><para>List writable attributes.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-f</option>, <option>--filesystem</option></term>
+                <listitem><para>Show information about the filesystem that the given
+                locations reside on.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
+                <listitem><para>The attributes to get.</para>
+                  <para>Attributes can be specified with their GIO name, e.g.
+                    <literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
+                    which matches all attributes. Several attributes or groups
+                    of attributes can be specified, separated by comma.</para>
+                  <para>By default, all attributes are listed.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-n</option>, <option>--nofollow-symlinks</option></term>
+                <listitem><para>Don’t follow symbolic links.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>launch</command>
+          <arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
+          <arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Launch a desktop file from any location given.</para>
+          <para>The <command>launch</command> command extends the behavior of the <command>open</command> command by allowing
+            any desktop file to be launched, not only those registered as file handlers.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>list</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Lists the contents of the given locations. If no location is
+            given, the contents of the current directory are shown.</para>
+          <para>The <command>list</command> command is similar to the traditional <command>ls</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
+                <listitem><para>The attributes to get.</para>
+                  <para>Attributes can be specified with their GIO name, e.g.
+                    <literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
+                    which matches all attributes. Several attributes or groups
+                    of attributes can be specified, separated by comma.</para>
+                  <para>By default, all attributes are listed.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-h</option>, <option>--hidden</option></term>
+                <listitem><para>Show hidden files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-l</option>, <option>--long</option></term>
+                <listitem><para>Use a long listing format.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-n</option>, <option>--nofollow-symlinks</option></term>
+                <listitem><para>Don’t follow symbolic links.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-d</option>, <option>--print-display-names</option></term>
+                <listitem><para>Print display names.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-u</option>, <option>--print-uris</option></term>
+                <listitem><para>Print full URIs.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>mime</command>
+          <arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
+          <arg choice="opt"><replaceable>HANDLER</replaceable></arg>
+        </term>
+        <listitem>
+          <para>If no handler is given, the <command>mime</command> command lists the
+            registered and recommended applications for the mimetype.
+            If a handler is given, it is set as the default handler for
+            the mimetype.</para>
+          <para>Handlers must be specified by their desktop file name,
+            including the extension. Example: <literal>org.gnome.gedit.desktop</literal>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>mkdir</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Creates directories.</para>
+          <para>The <command>mkdir</command> command is similar to the traditional <command>mkdir</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-p</option>, <option>--parent</option></term>
+                <listitem><para>Create parent directories when necessary.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>monitor</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Monitors files or directories for changes, such as creation
+            deletion, content and attribute changes, and mount and unmount
+            operations affecting the monitored locations.</para>
+          <para>The <command>monitor</command> command uses the GIO file monitoring APIs to do
+            its job. GIO has different implementations for different platforms.
+            The most common implementation on Linux uses inotify.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-d</option>, <option>--dir=<replaceable>LOCATION</replaceable></option></term>
+                <listitem><para>Monitor the given location as a directory. Normally,
+                  the file type is used to determine whether to monitor a file or directory.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-f</option>, <option>--file=<replaceable>LOCATION</replaceable></option></term>
+                <listitem><para>Monitor the given location as a file. Normally,
+                  the file type is used to determine whether to monitor a file or directory.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-D</option>, <option>--direct=<replaceable>LOCATION</replaceable></option></term>
+                <listitem><para>Monitor the file directly. This allows changes made via hardlinks to be captured.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-s</option>, <option>--silent=<replaceable>LOCATION</replaceable></option></term>
+                <listitem><para>Monitor the file directly, but don’t report changes.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-n</option>, <option>--no-moves</option></term>
+                <listitem><para>Report moves and renames as simple deleted/created events.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-m</option>, <option>--mounts</option></term>
+                <listitem><para>Watch for mount events.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>mount</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Provides commandline access to various aspects of GIO’s mounting
+            functionality.</para>
+          <para>Mounting refers to the traditional concept of arranging multiple
+            file systems and devices in a single tree, rooted at <filename>/</filename>. Classical
+            mounting happens in the kernel and is controlled by the mount utility.
+            GIO expands this concept by introducing mount daemons that can make
+            file systems available to GIO applications without kernel
+            involvement.</para>
+          <para>GIO mounts can require authentication, and the <command>mount</command> command
+            may ask for user IDs, passwords, and so on, when required.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-m</option>, <option>--mountable</option></term>
+                <listitem><para>Mount as mountable.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-d</option>, <option>--device=<replaceable>ID</replaceable></option></term>
+                <listitem><para>Mount volume with device file, or other identifier.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-u</option>, <option>--unmount</option></term>
+                <listitem><para>Unmount the location.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-e</option>, <option>--eject</option></term>
+                <listitem><para>Eject the location.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-t</option>, <option>--stop=<replaceable>DEVICE</replaceable></option></term>
+                <listitem><para>Stop drive with device file.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-s</option>, <option>--unmount-scheme=<replaceable>SCHEME</replaceable></option></term>
+                <listitem><para>Unmount all mounts with the given scheme.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-f</option>, <option>--force</option></term>
+                <listitem><para>Ignore outstanding file operations when unmounting or ejecting.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-a</option>, <option>--anonymous</option></term>
+                <listitem><para>Use an anonymous user when authenticating.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-l</option>, <option>--list</option></term>
+                <listitem><para>List all GIO mounts.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-o</option>, <option>--monitor</option></term>
+                <listitem><para>Monitor mount-related events.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-i</option>, <option>--detail</option></term>
+                <listitem><para>Show extra information.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--tcrypt-pim</option></term>
+                <listitem><para>The numeric PIM when unlocking a VeraCrypt volume.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--tcrypt-hidden</option></term>
+                <listitem><para>Mount a TCRYPT hidden volume.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--tcrypt-system</option></term>
+                <listitem><para>Mount a TCRYPT system volume.</para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>move</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
+          <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Moves one or more files from <replaceable>SOURCE</replaceable>
+            to <replaceable>DESTINATION</replaceable>. If more than one source
+            is specified, the destination must be a directory.</para>
+          <para>The <command>move</command> command is similar to the traditional <command>mv</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-T</option>, <option>--no-target-directory</option></term>
+                <listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-p</option>, <option>--progress</option></term>
+                <listitem><para>Show progress.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-i</option>, <option>--interactive</option></term>
+                <listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-b</option>, <option>--backup</option></term>
+                <listitem><para>Create backups of existing destination files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-C</option>, <option>--no-copy-fallback</option></term>
+                <listitem><para>Don’t use copy and delete fallback.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>open</command>
+          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Opens files with the default application that is registered
+            to handle files of this type.</para>
+          <para>GIO obtains this information from the shared-mime-info
+            database, with per-user overrides stored in
+            <filename><envar>$XDG_DATA_HOME</envar>/applications/mimeapps.list</filename>.</para>
+          <para>The <command>mime</command> command can be used to change the default handler for
+            a mimetype.</para>
+          <para>Environment variables will not be set on the application, as it
+            may be an existing process which is activated to handle the new file.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>rename</command>
+          <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
+          <arg choice="plain"><replaceable>NAME</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Renames a file.</para>
+          <para>The <command>rename</command> command is similar to the traditional <command>rename</command> utility.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>remove</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Deletes each given file.</para>
+          <para>This command removes files irreversibly. If you want a reversible
+            way to remove files, see the <command>trash</command> command.</para>
+          <para>Note that not all URI schemes that are supported by GIO may
+            allow deletion of files.</para>
+          <para>The <command>remove</command> command is similar to the traditional <command>rm</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-f</option>, <option>--force</option></term>
+                <listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>save</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Reads from standard input and saves the data to the given
+            location.</para>
+          <para>This is similar to just redirecting output to a file using
+            traditional shell syntax, but the <command>save</command> command allows saving to
+            location that GIO can write to.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-b</option>, <option>--backup</option></term>
+                <listitem><para>Back up existing destination files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-c</option>, <option>--create</option></term>
+                <listitem><para>Only create the destination if it doesn’t exist yet.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-a</option>, <option>--append</option></term>
+                <listitem><para>Append to the end of the file.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-p</option>, <option>--private</option></term>
+                <listitem><para>When creating, restrict access to the current user.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-u</option>, <option>--unlink</option></term>
+                <listitem><para>When replacing, replace as if the destination did not exist.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-v</option>, <option>--print-etag</option></term>
+                <listitem><para>Print the new ETag in the end.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-e</option>, <option>--etag=<replaceable>ETAG</replaceable></option></term>
+                <listitem><para>The ETag of the file that is overwritten.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>set</command>
+          <arg choice="plain"><replaceable>LOCATION</replaceable></arg>
+          <arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
+          <arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Sets a file attribute on a file.</para>
+          <para>File attributes can be specified with their GIO name, e.g
+            <literal>standard::icon</literal>. Note that not all GIO file attributes are writable.
+            Use the <option>--query-writable</option> option of the <command>info</command> command to list
+            writable file attributes.</para>
+          <para>If the <replaceable>TYPE</replaceable> is unset,
+            <replaceable>VALUE</replaceable> does not have to be specified.
+            If the <replaceable>TYPE</replaceable> is <literal>stringv</literal>, multiple values can be given.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-t</option>, <option>--type=<replaceable>TYPE</replaceable></option></term>
+                <listitem><para>Specifies the type of the attribute. Supported
+                  types are <literal>string</literal>, <literal>stringv</literal>,
+                  <literal>bytestring</literal>, <literal>boolean</literal>,
+                  <literal>uint32</literal>, <literal>int32</literal>,
+                  <literal>uint64</literal>, <literal>int64</literal> and <literal>unset</literal>.</para>
+                  <para>If the type is not specified, <literal>string</literal> is assumed.</para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-n</option>, <option>--nofollow-symlinks</option></term>
+                <listitem><para>Don’t follow symbolic links.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>trash</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Sends files or directories to the ‘Trashcan’ or restore them from
+            ‘Trashcan’. This can be a different folder depending on where the file
+            is located, and not all file systems support this concept. In the common
+            case that the file lives inside a user’s home directory, the trash folder is
+            <filename><envar>$XDG_DATA_HOME</envar>/Trash</filename>.</para>
+          <para>Note that moving files to the trash does not free up space on
+            the file system until the ‘Trashcan’ is emptied. If you are interested
+            in deleting a file irreversibly, see the <command>remove</command> command.</para>
+          <para>Inspecting and emptying the ‘Trashcan’ is normally supported by
+            graphical file managers such as Nautilus, but you can also see the
+            trash with the command: <command>gio trash --list</command> or
+            <command>gio list trash://</command>.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-f</option>, <option>--force</option></term>
+                <listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--empty</option></term>
+                <listitem><para>Empty the trash.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--list</option></term>
+                <listitem><para>List files in the trash with their original locations</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>--restore</option></term>
+                <listitem><para>Restore a file from trash to its original location. A URI beginning
+                                with <literal>trash://</literal> is expected here. If the original
+                                directory doesn't exist, it will be recreated.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <command>tree</command>
+          <arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
+          <arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
+        </term>
+        <listitem>
+          <para>Lists the contents of the given locations recursively, in a
+            tree-like format. If no location is given, it defaults to the current
+            directory.</para>
+          <para>The <command>tree</command> command is similar to the traditional <command>tree</command> utility.</para>
+          <refsect3>
+            <title>Options</title>
+            <variablelist>
+              <varlistentry>
+                <term><option>-h</option>, <option>--hidden</option></term>
+                <listitem><para>Show hidden files.</para></listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><option>-l</option>, <option>--follow-symlinks</option></term>
+                <listitem><para>Follow symbolic links.</para></listitem>
+              </varlistentry>
+            </variablelist>
+          </refsect3>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit status</title>
+    <para>On success 0 is returned, a non-zero failure code otherwise.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>cat</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>cp</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>ls</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>mkdir</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>mv</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>rm</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>tree</refentrytitle>
+        <manvolnum>1</manvolnum>
+      </citerefentry>.
+    </para>
+  </refsect1>
+</refentry>

docs/reference/gio/glib-compile-resources.xml

@@ -0,0 +1,254 @@
+<refentry id="glib-compile-resources" lang="en">
+
+<refentryinfo>
+  <title>glib-compile-schemas</title>
+  <productname>GIO</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Alexander</firstname>
+      <surname>Larsson</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>glib-compile-resources</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>glib-compile-resources</refname>
+  <refpurpose>GLib resource compiler</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>glib-compile-resources</command>
+    <arg choice="opt" rep="repeat">OPTION</arg>
+    <arg choice="req">FILE</arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>glib-compile-resources</command> reads the resource description from
+<replaceable>FILE</replaceable> and the files that it references
+and creates a binary resource bundle that is suitable for use with the
+<link linkend="GResource"><type>GResource</type></link> API.
+The resulting bundle is then written out as-is, or as C source for linking into
+an application.
+</para>
+<para>
+The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
+For a detailed description of the XML file format, see the
+<link linkend="GResource"><type>GResource</type></link> documentation.
+</para>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--version</option></term>
+<listitem><para>
+Print program version and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--target=<replaceable>TARGET</replaceable></option></term>
+<listitem><para>
+Store the compiled resources in the file <replaceable>TARGET</replaceable>.
+If not specified a filename based on the <replaceable>FILE</replaceable>
+basename is used.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--sourcedir=<replaceable>DIRECTORY</replaceable></option></term>
+<listitem><para>
+The files referenced in <replaceable>FILE</replaceable> are loaded from
+this directory. If not specified, the current directory is used.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate</option></term>
+<listitem><para>
+Write the output file in the format selected for by its filename extension:
+<variablelist>
+<varlistentry>
+<term><literal>.c</literal></term>
+<listitem><para>C source</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>.h</literal></term>
+<listitem><para>C header</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>.gresource</literal></term>
+<listitem><para>resource bundle</para></listitem>
+</varlistentry>
+</variablelist>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate-source</option></term>
+<listitem><para>
+Instead of a writing the resource bundle in binary form create a C source file
+that contains the resource bundle. This can then be compiled into an
+application for easy access.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate-header</option></term>
+<listitem><para>
+Generate a header file for use with C code generated by
+<option>--generate-source</option>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate-dependencies</option></term>
+<listitem><para>
+Prints the list of files that the resource bundle references to standard output.
+This can be used to track dependencies in the build system. For example, the
+following make rule would mark <replaceable>test.gresource</replaceable> as
+depending on all the files that <replaceable>test.gresource.xml</replaceable>
+includes, so that is is automatically rebuilt if any of them change:
+<programlisting>
+test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
+</programlisting>
+Note that this may or may not be portable to non-GNU <command>make</command>.
+</para>
+<para>
+Also see <option>--dependency-file</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--c-name</option></term>
+<listitem><para>
+Specify the prefix used for the C identifiers in the code generated by
+<option>--generate-source</option> and <option>--generate-header</option>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--manual-register</option></term>
+<listitem><para>
+By default code generated by <option>--generate-source</option> uses automatic
+initialization of the resource. This works on most systems by using the
+compiler support for constructors. However, some (uncommon) compilers may not
+support this, you can then specify <option>--manual-register</option>,
+which will generate custom register and unregister functions that your code
+can manually call at initialization and uninitialization time.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--internal</option></term>
+<listitem><para>
+By default code generated by <option>--generate-source</option> declares all
+initialization functions as <type>extern</type>.  So they are exported
+unless this is prevented by a link script or other means.  Since libraries
+usually want to use the functions only internally it can be more useful to
+declare them as
+<link linkend="G-GNUC-INTERNAL:CAPS"><literal>G_GNUC_INTERNAL</literal></link>
+which is what <option>--internal</option> does.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--external-data</option></term>
+<listitem><para>
+By default code generated by <option>--generate-source</option> embeds the
+resource data as a string literal. When <option>--external-data</option>
+is given, the data is only declared in the generated C file, and the data
+has to be linked externally.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--dependency-file=<replaceable>FILE</replaceable></option></term>
+<listitem><para>
+Write dependencies in the same style as gcc -M -MF to the given file.
+If <option>FILE</option> is -, the dependencies are written to the standard
+output. Unlike <option>--generate-dependencies</option>, this option can be
+combined with other <option>--generate</option> options to generate dependencies
+as a side-effect of generating sources.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--generate-phony-targets</option></term>
+<listitem><para>
+When creating a dependency file with <option>--dependency-file</option>
+include phony targets in the same style as gcc -MP. This would typically
+be used with <literal>make</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--compiler=<replaceable>NAME</replaceable></option></term>
+<listitem><para>
+Generate code that is going to target the given compiler <replaceable>NAME</replaceable>.
+The current two compiler modes are "gcc", for all GCC-compatible toolchains; and "msvc",
+for the Microsoft Visual C Compiler. If this option isn't set, then the default will be
+taken from the <envar>CC</envar> environment variable.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1><title>Environment</title>
+<variablelist>
+
+<varlistentry>
+<term><envar>XMLLINT</envar></term>
+<listitem><para>
+The full path to the <command>xmllint</command> executable. This is used to
+preprocess resources with the <literal>xml-stripblanks</literal> preprocessing
+option. If this environment variable is not set, <command>xmllint</command> is
+searched for in the <envar>PATH</envar>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><envar>GDK_PIXBUF_PIXDATA</envar></term>
+<listitem><para>
+Deprecated since gdk-pixbuf 2.32, as <type>GResource</type> supports embedding
+modern image formats without conversion.
+</para><para>
+The full path to the <command>gdk-pixbuf-pixdata</command> executable. This is
+used to preprocess resources with the <literal>to-pixdata</literal> preprocessing
+option. If this environment variable is not set, <command>gdk-pixbuf-pixdata</command>
+is searched for in the <envar>PATH</envar>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><envar>JSON_GLIB_FORMAT</envar></term>
+<listitem><para>
+The full path to the <command>json-glib-format</command> executable. This is used
+to preprocess resources with the <literal>json-stripblanks</literal> preprocessing
+option. If this environment variable is not set, <command>json-glib-format</command>
+is searched for in the <envar>PATH</envar>.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+</refentry>

docs/reference/gio/glib-compile-schemas.xml

@@ -0,0 +1,118 @@
+<refentry id="glib-compile-schemas" lang="en">
+
+<refentryinfo>
+  <title>glib-compile-schemas</title>
+  <productname>GIO</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Ryan</firstname>
+      <surname>Lortie</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>glib-compile-schemas</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>glib-compile-schemas</refname>
+  <refpurpose>GSettings schema compiler</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>glib-compile-schemas</command>
+    <arg choice="opt" rep="repeat">OPTION</arg>
+    <arg choice="req">DIRECTORY</arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>glib-compile-schemas</command> compiles all the GSettings XML
+schema files in <replaceable>DIRECTORY</replaceable> into a binary file
+with the name <filename>gschemas.compiled</filename> that can be used
+by <link linkend="GSettings"><type>GSettings</type></link>. The XML schema
+files must have the filename extension <filename>.gschema.xml</filename>.
+For a detailed description of the XML file format, see the
+<link linkend="GSettings"><type>GSettings</type></link> documentation.
+</para>
+<para>
+At runtime, GSettings looks for schemas in the
+<filename>glib-2.0/schemas</filename> subdirectories of all directories
+specified in the <envar>XDG_DATA_DIRS</envar> environment variable. The
+usual location to install schema files is
+<filename>/usr/share/glib-2.0/schemas</filename>.
+</para>
+<para>
+In addition to schema files, glib-compile-schemas reads 'vendor override'
+files, which are key files that can override default values for keys in
+the schemas. The group names in the key files are the schema id, and the
+values are written in serialized GVariant form.
+Vendor override files must have the filename extension
+<filename>.gschema.override</filename>.
+</para>
+<para>
+By convention, vendor override files begin with <filename>nn_</filename>
+where <filename>nn</filename> is a number from 00 to 99.  Higher
+numbered files have higher priority (eg: if the same override is made in
+a file numbered 10 and then again in a file numbered 20, the override
+from 20 will take precedence).
+</para>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--version</option></term>
+<listitem><para>
+Print program version and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--targetdir=<replaceable>TARGET</replaceable></option></term>
+<listitem><para>
+Store <filename>gschemas.compiled</filename> in the <replaceable>TARGET</replaceable> directory instead of <replaceable>DIRECTORY</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--strict</option></term>
+<listitem><para>
+Abort on any errors in schemas. Without this option, faulty schema files are
+simply omitted from the resulting compiled schema.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--dry-run</option></term>
+<listitem><para>
+Don't write <filename>gschemas.compiled</filename>. This option can be used
+to check <filename>.gschema.xml</filename> sources for errors.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--allow-any-name</option></term>
+<listitem><para>
+Do not enforce restrictions on key names. Note that this option is purely
+to facility the transition from GConf, and will be removed at some time
+in the future.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+</refentry>

docs/reference/gio/gresource.xml

@@ -0,0 +1,127 @@
+<refentry id="gresource-tool" lang="en">
+
+<refentryinfo>
+  <title>gresource</title>
+  <productname>GIO</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Matthias</firstname>
+      <surname>Clasen</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>gresource</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>gresource</refname>
+  <refpurpose>GResource tool</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>gresource</command>
+    <arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
+    <arg choice="plain">list</arg>
+    <arg choice="plain"><replaceable>FILE</replaceable></arg>
+    <arg choice="opt"><replaceable>PATH</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gresource</command>
+    <arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
+    <arg choice="plain">details</arg>
+    <arg choice="plain"><replaceable>FILE</replaceable></arg>
+    <arg choice="opt"><replaceable>PATH</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gresource</command>
+    <arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
+    <arg choice="plain">extract</arg>
+    <arg choice="plain"><replaceable>FILE</replaceable></arg>
+    <arg choice="plain"><replaceable>PATH</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gresource</command>
+    <arg choice="plain">sections</arg>
+    <arg choice="plain"><replaceable>FILE</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gresource</command>
+    <arg choice="plain">help</arg>
+    <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gresource</command> offers a simple commandline
+interface to <link linkend="GResource"><type>GResource</type></link>.
+It lets you list and extract resources that have been compiled
+into a resource file or included in an elf file (a binary or a
+shared library).
+</para>
+<para>
+The file to operate on is specified by the <replaceable>FILE</replaceable>
+argument.
+</para>
+<para>
+If an elf file includes multiple sections with resources, it is
+possible to select which one to operate on with the
+<arg choice="plain">--section</arg> option. Use the
+<arg choice="plain">sections</arg> command to find available sections.
+</para>
+</refsect1>
+
+<refsect1><title>Commands</title>
+<variablelist>
+
+<varlistentry>
+<term><option>list</option></term>
+<listitem><para>
+Lists resources. If <replaceable>SECTION</replaceable> is given, only
+list resources in this section. If <replaceable>PATH</replaceable> is
+given, only list matching resources.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>details</option></term>
+<listitem><para>
+Lists resources with details. If <replaceable>SECTION</replaceable>
+is given, only list resources in this section. If
+<replaceable>PATH</replaceable> is given, only list matching resources.
+Details include the section, size and compression of each resource.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>extract</option></term>
+<listitem><para>
+Extracts the resource named by <replaceable>PATH</replaceable> to stdout.
+Note that resources may contain binary data.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>sections</option></term>
+<listitem><para>
+Lists sections containing resources. This is only interesting if
+<replaceable>FILE</replaceable> is an elf file.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>help</option></term>
+<listitem><para>
+Prints help and exits.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</refsect1>
+</refentry>

docs/reference/gio/gsettings.xml

@@ -0,0 +1,248 @@
+<refentry id="gsettings-tool" lang="en">
+
+<refentryinfo>
+  <title>gsettings</title>
+  <productname>GIO</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Ryan</firstname>
+      <surname>Lortie</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>gsettings</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>gsettings</refname>
+  <refpurpose>GSettings configuration tool</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">get</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">monitor</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="opt"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">writable</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">range</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">describe</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">set</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+    <arg choice="plain"><replaceable>VALUE</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">reset</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+    <arg choice="plain"><replaceable>KEY</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">reset-recursively</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-schemas</arg>
+    <arg choice="opt">--print-paths</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-relocatable-schemas</arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-keys</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-children</arg>
+    <arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">list-recursively</arg>
+    <arg choice="opt"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>gsettings</command>
+    <arg choice="plain">help</arg>
+    <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gsettings</command> offers a simple commandline
+interface to <link linkend="GSettings"><type>GSettings</type></link>.
+It lets you get, set or monitor an individual key for changes.
+</para>
+<para>
+The <replaceable>SCHEMA</replaceable> and <replaceable>KEY</replaceable>
+arguments are required for most commands to specify the schema id and the
+name of the key to operate on. The schema id may optionally have a
+:<replaceable>PATH</replaceable> suffix. Specifying the path is only needed
+if the schema does not have a fixed path.
+</para>
+<para>
+When setting a key, you also need specify a <replaceable>VALUE</replaceable>
+The format for the value is that of a serialized
+<link linkend="GVariant"><type>GVariant</type></link>,
+so e.g. a string
+must include explicit quotes: "'foo'". This format is also used when printing
+out values.
+</para>
+<para>
+Note that gsettings needs a D-Bus session bus connection to write changes to
+the dconf database.
+</para>
+</refsect1>
+
+<refsect1><title>Commands</title>
+<variablelist>
+
+<varlistentry>
+<term><option>get</option></term>
+<listitem><para>
+Gets the value of <replaceable>KEY</replaceable>.
+The value is printed out as a serialized
+<link linkend="GVariant"><type>GVariant</type></link>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>monitor</option></term>
+<listitem><para>
+Monitors <replaceable>KEY</replaceable> for changes and prints the changed
+values. If no <replaceable>KEY</replaceable> is specified, all keys in the
+schema are monitored. Monitoring will continue until the process is terminated.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>writable</option></term>
+<listitem><para>
+Finds out whether <replaceable>KEY</replaceable> is writable.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>range</option></term>
+<listitem><para>
+Queries the range of valid values for <replaceable>KEY</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>describe</option></term>
+<listitem><para>
+Queries the description of valid values for <replaceable>KEY</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>set</option></term>
+<listitem><para>
+Sets the value of <replaceable>KEY</replaceable> to
+<replaceable>VALUE</replaceable>. The value is specified as a serialized
+<link linkend="GVariant"><type>GVariant</type></link>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>reset</option></term>
+<listitem><para>
+Resets <replaceable>KEY</replaceable> to its default value.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>reset-recursively</option></term>
+<listitem><para>
+Reset all keys under the given <replaceable>SCHEMA</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-schemas</option></term>
+<listitem><para>
+Lists the installed, non-relocatable schemas.
+See <option>list-relocatable-schemas</option> if you are interested in
+relocatable schemas. If <optional><option>--print-paths</option></optional>
+is given, the path where each schema is mapped is also printed.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-relocatable-schemas</option></term>
+<listitem><para>
+Lists the installed, relocatable schemas.
+See <option>list-schemas</option> if you are interested in
+non-relocatable schemas.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-keys</option></term>
+<listitem><para>
+Lists the keys in <replaceable>SCHEMA</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-children</option></term>
+<listitem><para>
+Lists the children of <replaceable>SCHEMA</replaceable>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>list-recursively</option></term>
+<listitem><para>
+Lists keys and values, recursively. If no <replaceable>SCHEMA</replaceable>
+is given, list keys in all schemas.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>help</option></term>
+<listitem><para>
+Prints help and exits.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</refsect1>
+</refentry>

docs/reference/gio/meson.build

@@ -0,0 +1,242 @@
+if get_option('gtk_doc')
+  subdir('gdbus-object-manager-example')
+  subdir('xml')
+
+  ignore_headers = [
+    'fam',
+    'fen',
+    'gdbus-2.0',
+    'gvdb',
+    'inotify',
+    'kqueue',
+    'libasyncns',
+    'tests',
+    'win32',
+    'xdgmime',
+    'gappinfoprivate.h',
+    'gapplicationimpl.h',
+    'gasynchelper.h',
+    'gcontenttypeprivate.h',
+    'gcontextspecificgroup.h',
+    'gcredentialsprivate.h',
+    'gdbus-daemon-generated.h',
+    'gdbusactiongroup-private.h',
+    'gdbusauth.h',
+    'gdbusauthmechanismanon.h',
+    'gdbusauthmechanismexternal.h',
+    'gdbusauthmechanism.h',
+    'gdbusauthmechanismsha1.h',
+    'gdbusdaemon.h',
+    'gdbusprivate.h',
+    'gdelayedsettingsbackend.h',
+    'gdocumentportal.h',
+    'gdummyfile.h',
+    'gdummyproxyresolver.h',
+    'gdummytlsbackend.h',
+    'gfileattribute-priv.h',
+    'gfileinfo-priv.h',
+    'ghttpproxy.h',
+    'giomodule-priv.h',
+    'gioprivate.h',
+    'giowin32-afunix.h',
+    'giowin32-priv.h',
+    'gio_probes.h',
+    'gio_trace.h',
+    'gio-tool.h',
+    'glocaldirectorymonitor.h',
+    'glocalfileenumerator.h',
+    'glocalfile.h',
+    'glocalfileinfo.h',
+    'glocalfileinputstream.h',
+    'glocalfileiostream.h',
+    'glocalfilemonitor.h',
+    'glocalfileoutputstream.h',
+    'glocalvfs.h',
+    'gmemorymonitordbus.h',
+    'gmemorymonitorportal.h',
+    'gmountprivate.h',
+    'gnativevolumemonitor.h',
+    'gnetworkingprivate.h',
+    'gnetworkmonitorbase.h',
+    'gnetworkmonitornetlink.h',
+    'gnetworkmonitornm.h',
+    'gnetworkmonitorportal.h',
+    'gnotificationbackend.h',
+    'gnotification-private.h',
+    'gopenuriportal.h',
+    'gpollfilemonitor.h',
+    'gportalsupport.h',
+    'gpowerprofilemonitordbus.h',
+    'gpowerprofilemonitorportal.h',
+    'gproxyresolverportal.h',
+    'gregistrysettingsbackend.h',
+    'gresourcefile.h',
+    'gsettingsbackendinternal.h',
+    'gsettings-mapping.h',
+    'gsettingsschema-internal.h',
+    'gsocketinputstream.h',
+    'gsocketoutputstream.h',
+    'gsocks4aproxy.h',
+    'gsocks4proxy.h',
+    'gsocks5proxy.h',
+    'gsubprocesslauncher-private.h',
+    'gthreadedresolver.h',
+    'gtrashportal.h',
+    'gunionvolumemonitor.h',
+    'gunixmount.h',
+    'gunixresolver.h',
+    'gunixvolume.h',
+    'gunixvolumemonitor.h',
+    'gwin32networkmonitor.h',
+    'gwin32api-application-activation-manager.h',
+    'gwin32api-iterator.h',
+    'gwin32api-misc.h',
+    'gwin32api-package.h',
+    'gwin32api-storage.h',
+    'gwin32appinfo.h',
+    'gwin32file-sync-stream.h',
+    'gwin32mount.h',
+    'gwin32packageparser.h',
+    'gwin32resolver.h',
+    'gwin32volumemonitor.h',
+    'thumbnail-verify.h',
+    'xdp-dbus.h',
+  ]
+
+  sections_files = files('gio-sections-common.txt')
+
+  if host_system == 'windows'
+    ignore_headers += [
+      'gfiledescriptorbased.h',
+      'gunixmounts.h',
+      'gunixfdlist.h',
+      'gunixfdmessage.h',
+      'gunixinputstream.h',
+      'gunixoutputstream.h',
+      'gdesktopappinfo.h',
+      'gosxappinfo.h',
+    ]
+    sections_files += files('gio-sections-win32.txt')
+    platform_file = files('gio-docs-win32.xml')
+  else
+    if glib_have_cocoa
+      ignore_headers += ['gdesktopappinfo.h']
+    else
+      ignore_headers += ['gosxappinfo.h']
+    endif
+
+    ignore_headers += [
+      'gwin32inputstream.h',
+      'gwin32outputstream.h',
+      'gwin32registrykey.h',
+    ]
+    platform_file = files('gio-docs-unix.xml')
+  endif
+
+  ignore_sources = [
+    'kqueue',
+    'tests',
+    'gdbus-daemon-generated.c',
+    'xdp-dbus.c',
+  ]
+
+  docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
+  version_conf = configuration_data()
+  version_conf.set('VERSION', meson.project_version())
+  configure_file(
+    input: 'version.xml.in',
+    output: 'version.xml',
+    configuration: version_conf
+  )
+
+  # FIXME: configure_file() does not support more than one file in input
+  # argument. If input argument is omitted then meson checks that all items in
+  # the command array are strings. But if we have an input then extra files
+  # can be passed in command array.
+  # See https://github.com/mesonbuild/meson/issues/5893
+  concat_files_helper = find_program('concat-files-helper.py')
+  configure_file(
+    output : 'gio-sections.txt',
+    input : sections_files[0],
+    command : [concat_files_helper, '@OUTPUT@'] + sections_files,
+  )
+
+  configure_file(
+    output : 'gio-docs-platform.xml',
+    input : platform_file,
+    copy : true,
+  )
+
+  content_files = [
+    'overview.xml',
+    'migrating-posix.xml',
+    'migrating-gnome-vfs.xml',
+    'migrating-gconf.xml',
+    'migrating-gdbus.xml',
+    'gio-querymodules.xml',
+    'glib-compile-schemas.xml',
+    'glib-compile-resources.xml',
+    'gapplication.xml',
+    'gsettings.xml',
+    'gresource.xml',
+    'gdbus.xml',
+    'gdbus-codegen.xml',
+  ]
+
+  content_files += [
+    gdbus_example_objectmanager_xml,
+    gdbus_example_objectmanager_sources,
+    gdbus_object_manager_example_doc
+  ]
+
+  gnome.gtkdoc('gio',
+    main_xml : 'gio-docs.xml',
+    namespace : 'g',
+    mode : 'none',
+    dependencies : [libgio_dep, libgobject_dep, libglib_dep],
+    src_dir : 'gio',
+    scan_args : gtkdoc_common_scan_args + [
+      '--rebuild-types',
+      '--ignore-headers=' + ' '.join(ignore_headers),
+    ],
+    mkdb_args : [
+      '--ignore-files=' + ' '.join(ignore_sources),
+    ],
+    content_files : content_files,
+    expand_content_files : [
+      'overview.xml',
+      'migrating-posix.xml',
+      'migrating-gnome-vfs.xml',
+      'migrating-gconf.xml',
+      'migrating-gdbus.xml',
+      'gdbus-codegen.xml',
+    ],
+    html_assets : [
+      'gvfs-overview.png',
+      'menu-example.png',
+      'menu-model.png',
+    ],
+    fixxref_args: [
+      '--html-dir=' + docpath,
+      '--extra-dir=' + join_paths('gio', '..', 'glib', 'html'),
+      '--extra-dir=' + join_paths('gio', '..', 'gobject', 'html'),
+    ],
+    install: true,
+    check: true,
+  )
+endif
+
+
+if get_option('man')
+  manpages = ['gapplication', 'gio-querymodules', 'glib-compile-schemas',
+              'glib-compile-resources', 'gsettings', 'gresource', 'gdbus',
+              'gio', 'gdbus-codegen']
+  foreach page : manpages
+    custom_target(page + '-man',
+      input: page + '.xml',
+      output: page + '.1',
+      command: xsltproc_command,
+      install: true,
+      install_dir: man1_dir)
+  endforeach
+endif

docs/reference/gio/migrating-gconf.xml

@@ -0,0 +1,515 @@
+  <chapter>
+    <title>Migrating from GConf to GSettings</title>
+
+    <section>
+      <title>Before you start</title>
+
+      <para>
+        Converting individual applications and their settings from GConf to
+        GSettings can be done at will. But desktop-wide settings like font or
+        theme settings often have consumers in multiple modules. Therefore,
+        some consideration has to go into making sure that all users of a setting
+        are converted to GSettings at the same time or that the program
+        responsible for configuring that setting continues to update the value in
+        both places.
+      </para>
+      <para>
+        It is always a good idea to have a look at how others have handled
+        similar problems before.
+      </para>
+    </section>
+
+    <section>
+      <title>Conceptual differences</title>
+
+      <para>
+        Conceptually, GConf and GSettings are fairly similar. Both
+        have a concept of pluggable backends. Both keep information
+        about keys and their types in schemas. Both have a concept of
+        mandatory values, which lets you implement lock-down.
+      </para>
+      <para>
+        There are some differences in the approach to schemas. GConf
+        installs the schemas into the database and has API to handle
+        schema information (gconf_client_get_default_from_schema(),
+        gconf_value_get_schema(), etc). GSettings on the other hand
+        assumes that an application knows its own schemas, and does
+        not provide API to handle schema information at runtime.
+        GSettings is also more strict about requiring a schema whenever
+        you want to read or write a key. To deal with more free-form
+        information that would appear in schema-less entries in GConf,
+        GSettings allows for schemas to be 'relocatable'.
+      </para>
+      <para>
+        One difference in the way applications interact with their
+        settings is that with GConf you interact with a tree of
+        settings (ie the keys you pass to functions when reading
+        or writing values are actually paths with the actual name
+        of the key as the last element. With GSettings, you create
+        a GSettings object which has an implicit prefix that determines
+        where the settings get stored in the global tree of settings,
+        but the keys you pass when reading or writing values are just
+        the key names, not the full path.
+      </para>
+    </section>
+
+    <section>
+      <title>GConfClient (and GConfBridge) API conversion</title>
+
+      <para>
+        Most people use GConf via the high-level #GConfClient API.
+        The corresponding API is the #GSettings object. While not
+        every GConfClient function has a direct GSettings equivalent,
+        many do:
+        <table id="gconf-client-vs-gsettings">
+          <tgroup cols="2">
+            <thead>
+              <row><entry>GConfClient</entry><entry>GSettings</entry></row>
+            </thead>
+            <tbody>
+              <row><entry>gconf_client_get_default()</entry><entry>no direct equivalent,
+                                                                   instead you call g_settings_new() for the schemas you use</entry></row>
+              <row><entry>gconf_client_set()</entry><entry>g_settings_set()</entry></row>
+              <row><entry>gconf_client_get()</entry><entry>g_settings_get()</entry></row>
+              <row><entry>gconf_client_get_bool()</entry><entry>g_settings_get_boolean()</entry></row>
+              <row><entry>gconf_client_set_bool()</entry><entry>g_settings_set_boolean()</entry></row>
+              <row><entry>gconf_client_get_int()</entry><entry>g_settings_get_int()</entry></row>
+              <row><entry>gconf_client_set_int()</entry><entry>g_settings_set_int()</entry></row>
+              <row><entry>gconf_client_get_float()</entry><entry>g_settings_get_double()</entry></row>
+              <row><entry>gconf_client_set_float()</entry><entry>g_settings_set_double()</entry></row>
+              <row><entry>gconf_client_get_string()</entry><entry>g_settings_get_string()</entry></row>
+              <row><entry>gconf_client_set_string()</entry><entry>g_settings_set_string()</entry></row>
+              <row><entry>gconf_client_get_list()</entry><entry>for string lists, see g_settings_get_strv(), else see g_settings_get_value() and #GVariant API</entry></row>
+              <row><entry>gconf_client_set_list()</entry><entry>for string lists, see g_settings_set_strv(), else see g_settings_set_value() and #GVariant API</entry></row>
+              <row><entry>gconf_entry_get_is_writable()</entry><entry>g_settings_is_writable()</entry></row>
+              <row><entry>gconf_client_notify_add()</entry><entry>not required, the #GSettings::changed signal is emitted automatically</entry></row>
+              <row><entry>gconf_client_add_dir()</entry><entry>not required, each GSettings instance automatically watches all keys in its path</entry></row>
+              <row><entry>#GConfChangeSet</entry><entry>g_settings_delay(), g_settings_apply()</entry></row>
+              <row><entry>gconf_client_get_default_from_schema()</entry><entry>no equivalent, applications are expected to know their schema</entry></row>
+              <row><entry>gconf_client_all_entries()</entry><entry>no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries</entry></row>
+              <row><entry>gconf_client_get_without_default()</entry><entry>no equivalent</entry></row>
+              <row><entry>gconf_bridge_bind_property()</entry><entry>g_settings_bind()</entry></row>
+              <row><entry>gconf_bridge_bind_property_full()</entry><entry>g_settings_bind_with_mapping()</entry></row>
+            </tbody>
+          </tgroup>
+        </table>
+      </para>
+      <para>
+        GConfBridge was a third-party library that used GConf to bind an object property
+        to a particular configuration key. GSettings offers this service itself.
+      </para>
+      <para>
+        There is a pattern that is sometimes used for GConf, where a setting can have
+        explicit 'value A', explicit 'value B' or 'use the system default'. With GConf,
+        'use the system default' is sometimes implemented by unsetting the user value.
+      </para>
+      <para>
+        This is not possible in GSettings, since it does not have API to determine if a value
+        is the default and does not let you unset values. The recommended way (and much
+        clearer) way in which this can be implemented in GSettings is to have a separate
+        'use-system-default' boolean setting.
+      </para>
+    </section>
+
+    <section>
+      <title>Change notification</title>
+
+      <para>
+        GConf requires you to call gconf_client_add_dir() and
+        gconf_client_notify_add() to get change notification. With
+        GSettings, this is not necessary; signals get emitted automatically
+        for every change.
+      </para>
+      <para>
+        The #GSettings::changed signal is emitted for each changed key.
+        There is also a #GSettings::change-event signal that you can handle
+        if you need to see groups of keys that get changed at the same time.
+      </para>
+      <para>
+        GSettings also notifies you about changes in writability of keys,
+        with the #GSettings::writable-changed signal (and the
+        #GSettings::writable-change-event signal).
+      </para>
+    </section>
+
+    <section><title>Change sets</title>
+      <para>
+        GConf has a concept of a set of changes which can be applied or reverted
+        at once: #GConfChangeSet (GConf doesn't actually apply changes atomically,
+        which is one of its shortcomings).
+      </para>
+      <para>
+        Instead of a separate object to represent a change set, GSettings has a
+        'delayed-apply' mode, which can be turned on for a GSettings object by
+        calling g_settings_delay(). In this mode, changes done to the GSettings
+        object are not applied - they are still visible when calling g_settings_get()
+        <emphasis>on the same object</emphasis>, but not to other GSettings instances
+        or even other processes.
+      </para>
+      <para>
+        To apply the pending changes all at once (GSettings <emphasis>does</emphasis>
+        atomicity here), call g_settings_apply(). To revert the pending changes,
+        call g_settings_revert() or just drop the reference to the #GSettings object.
+      </para>
+    </section>
+
+    <section>
+      <title>Schema conversion</title>
+
+      <para>
+        If you are porting your application from GConf, most likely you already
+        have a GConf schema. GConf comes with a commandline tool
+        gsettings-schema-convert that can help with the task of converting
+        a GConf schema into an equivalent GSettings schema. The tool is not
+        perfect and may need assistance in some cases.
+      </para>
+      <example><title>An example for using gsettings-schema-convert</title>
+        <para>Running <userinput>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</userinput> on the following <filename>desktop_gnome_font_rendering.schemas</filename> file:
+        <programlisting>
+<![CDATA[
+<?xml version="1.0"?>
+<gconfschemafile>
+    <schemalist>
+        <schema>
+            <key>/schemas/desktop/gnome/font_rendering/dpi</key>
+            <applyto>/desktop/gnome/font_rendering/dpi</applyto>
+            <owner>gnome</owner>
+            <type>int</type>
+            <default>96</default>
+            <locale name="C">
+                <short>DPI</short>
+                <long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
+            </locale>
+        </schema>
+    </schemalist>
+</gconfschemafile>
+]]>
+</programlisting>
+produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with the following content:
+<programlisting>
+<![CDATA[
+<schemalist>
+  <schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
+    <key name="dpi" type="i">
+      <default>96</default>
+      <summary>DPI</summary>
+      <description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
+    </key>
+  </schema>
+</schemalist>
+]]>
+</programlisting>
+</para>
+      </example>
+
+      <para>
+       GSettings schemas are identified at runtime by their id (as specified
+       in the XML source file). It is recommended to use a dotted name as schema
+       id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
+       In cases where the settings are general and not specific to one application,
+       the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
+       The filename used for the XML schema source is immaterial, but
+       schema compiler expects the files to have the extension
+       <filename>.gschema.xml</filename>. It is recommended to simply
+       use the schema id as the filename, followed by this extension,
+       e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
+      </para>
+
+      <para>
+        The XML source file for your GSettings schema needs to get installed
+        into <filename>$datadir/glib-2.0/schemas</filename>, and needs to be
+        compiled into a binary form. At runtime, GSettings looks for compiled
+        schemas in the <filename>glib-2.0/schemas</filename> subdirectories
+        of all <envar>XDG_DATA_DIRS</envar> directories, so if you install
+        your schema in a different location, you need to set the
+        <envar>XDG_DATA_DIRS</envar> environment variable appropriately.
+      </para>
+      <para>
+        Schemas are compiled into binary form by the
+        <link linkend="glib-compile-schemas">glib-compile-schemas</link> utility.
+        GIO provides a <literal>glib_compile_schemas</literal>
+        variable for the schema compiler.
+      </para>
+      <para>
+        You can ignore all of this by using the provided m4 macros.  To
+        do this, add to your <filename>configure.ac</filename>:
+<programlisting>
+GLIB_GSETTINGS
+</programlisting>
+        The corresponding <filename>Makefile.am</filename> fragment looks like
+        this:
+<programlisting>
+# gsettings_SCHEMAS is a list of all the schemas you want to install
+gsettings_SCHEMAS = my.app.gschema.xml
+
+# include the appropriate makefile rules for schema handling
+@GSETTINGS_RULES@
+</programlisting>
+      </para>
+
+      <para>
+        This is not sufficient on its own.  You need to mention what the source
+        of the <filename>my.app.gschema.xml</filename> file is.  If the schema
+        file is distributed directly with your project's tarball then a mention
+        in <varname>EXTRA_DIST</varname> is appropriate.  If the schema file is
+        generated from another source then you will need the appropriate rule
+        for that, plus probably an item in <varname>EXTRA_DIST</varname> for the
+        source files used by that rule.
+      </para>
+
+      <para>
+        One possible pitfall in doing schema conversion is that the default
+        values in GSettings schemas are parsed by the #GVariant parser.
+        This means that strings need to include quotes in the XML.  Also note
+        that the types are now specified as #GVariant type strings.
+        <programlisting>
+<![CDATA[
+<type>string</type>
+<default>rgb</default>
+]]>
+        </programlisting>
+        becomes
+        <programlisting>
+<![CDATA[
+<key name="rgba-order" type="s">
+  <default>'rgb'</default> <!-- note quotes -->
+</key>
+]]>
+        </programlisting>
+      </para>
+      <para>
+        Another possible complication is that GConf specifies full paths
+        for each key, while a GSettings schema has a 'path' attribute that
+        contains the prefix for all the keys in the schema, and individual
+        keys just have a simple name. So
+        <programlisting>
+<![CDATA[
+<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
+]]>
+        </programlisting>
+        becomes
+        <programlisting>
+<![CDATA[
+<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
+  <key name="antialiasing" type="s">
+]]>
+        </programlisting>
+      </para>
+      <para>
+        Default values can be localized in both GConf and GSettings schemas,
+        but GSettings uses gettext for the localization. You can specify
+        the gettext domain to use in the <tag class="attribute">gettext-domain</tag>
+        attribute. Therefore, when converting localized defaults in GConf,
+        <programlisting>
+<![CDATA[
+<key>/schemas/apps/my_app/font_size</key>
+  <locale name="C">
+    <default>18</default>
+  </locale>
+  <locale name="be">
+    <default>24</default>
+  </locale>
+</key>
+]]>
+        </programlisting>
+        becomes
+        <programlisting>
+<![CDATA[
+<schema id="..." gettext-domain="your-domain">
+ ...
+<key name="font-size" type="i">
+  <default l10n="messages" context="font_size">18</default>
+</key>
+]]>
+        </programlisting>
+      </para>
+      <para>
+        GSettings uses gettext for translation of default values.
+        The string that is translated is exactly the string that appears
+        inside of the <tag class='starttag'>default</tag> element.  This
+        includes the quotation marks that appear around strings.
+        Default values must be marked with the <varname>l10n</varname>
+        attribute in the <tag class='starttag'>default</tag> tag, which
+        should be set as equal to <literal>'messages'</literal> or
+        <literal>'time'</literal> depending on the desired category.  An
+        optional translation context can also be specified with the
+        <varname>context</varname> attribute, as in the example.  This
+        is usually recommended, since the string "<literal>18</literal>"
+        is not particularly easy to translate without context.  The
+        translated version of the default value should be stored in the
+        specified <varname>gettext-domain</varname>.  Care must be taken
+        during translation to ensure that all translated values remain
+        syntactically valid; mistakes here will cause runtime errors.
+      </para>
+      <para>
+        GSettings schemas have optional <tag class="starttag">summary</tag> and
+        <tag class="starttag">description</tag> elements for each key which
+        correspond to the <tag class="starttag">short</tag> and
+        <tag class="starttag">long</tag> elements in the GConf schema and
+        will be used in similar ways by a future gsettings-editor, so you
+        should use the same conventions for them: The summary is just a short
+        label with no punctuation, the description can be one or more complete
+        sentences. If multiple paragraphs are desired for the description, the
+        paragraphs should be separated by a completely empty line.
+      </para>
+      <para>
+        Translations for these strings will also be handled
+        via gettext, so you should arrange for these strings to be
+        extracted into your gettext catalog. One way to do that is to use
+        intltool. Since intltool 0.50.1, schema files are
+        supported, so all you have to do is to add your .gschema.xml
+        files to <filename>POTFILES.in</filename> with a line like
+        <programlisting>
+        [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
+        </programlisting>
+      </para>
+      <para>
+        GSettings is a bit more restrictive about key names than GConf. Key
+        names in GSettings can be at most 32 characters long, and must only
+        consist of lowercase characters, numbers and dashes, with no
+        consecutive dashes. The first character must not be a number or dash,
+        and the last character cannot be '-'.
+      </para>
+      <para>
+        If you are using the GConf backend for GSettings during the
+        transition, you may want to keep your key names the same they
+        were in GConf, so that existing settings in the users GConf
+        database are preserved. You can achieve this by using the
+        <option>--allow-any-name</option> with the
+        <link linkend="glib-compile-schemas">glib-compile-schemas</link> schema
+        compiler. Note that this option is only meant
+        to ease the process of porting your application, allowing parts
+        of your application to continue to access GConf and parts to use
+        GSettings. By the time you have finished porting your application
+        you must ensure that all key names are valid.
+      </para>
+    </section>
+
+    <section><title>Data conversion</title>
+      <para>
+        GConf comes with a GSettings backend that can be used to
+        facility the transition to the GSettings API until you are
+        ready to make the jump to a different backend (most likely
+        dconf). To use it, you need to set the <envar>GSETTINGS_BACKEND</envar>
+        to 'gconf', e.g. by using
+<programlisting>
+  g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
+</programlisting>
+        early on in your program. Note that this backend is meant purely
+        as a transition tool, and should not be used in production.
+      </para>
+      <para>
+        GConf also comes with a utility called
+        <command>gsettings-data-convert</command>, which is designed to help
+        with the task of migrating user settings from GConf into another
+        GSettings backend. It can be run manually, but it is designed to be
+        executed automatically, every time a user logs in. It keeps track of
+        the data migrations that it has already done, and it is harmless to
+        run it more than once.
+      </para>
+      <para>
+        To make use of this utility, you must install a keyfile in the
+        directory <filename>/usr/share/GConf/gsettings</filename> which
+        lists the GSettings keys and GConf paths to map to each other, for
+        each schema that you want to migrate user data for.
+      </para>
+      <para>
+        Here is an example:
+        <programlisting>
+<![CDATA[
+[org.gnome.fonts]
+antialiasing = /desktop/gnome/font_rendering/antialiasing
+dpi = /desktop/gnome/font_rendering/dpi
+hinting = /desktop/gnome/font_rendering/hinting
+rgba-order = /desktop/gnome/font_rendering/rgba_order
+
+[apps.myapp:/path/to/myapps/]
+some-odd-key1 = /apps/myapp/some_ODD-key1
+]]>
+        </programlisting>
+        The last key demonstrates that it may be necessary to modify the key
+        name to comply with stricter GSettings key name rules. Of course,
+        that means your application must use the new key names when looking
+        up settings in GSettings.
+      </para>
+      <para>
+        The last group in the example also shows how to handle the case
+        of 'relocatable' schemas, which don't have a fixed path. You can
+        specify the path to use in the group name, separated by a colon.
+      </para>
+      <para>
+        There are some limitations: <command>gsettings-data-convert</command>
+        does not do any transformation of the values. And it does not handle
+        complex GConf types other than lists of strings or integers.
+      </para>
+      <para>
+        Don't forget to require GConf 2.31.1 or newer in your configure
+        script if you are making use of the GConf backend or the conversion
+        utility.
+      </para>
+
+      <para>
+        If, as an application developer, you are interested in manually
+        ensuring that <command>gsettings-data-convert</command> has been
+        invoked (for example, to deal with the case where the user is
+        logged in during a distribution upgrade or for non-XDG desktop
+        environments which do not run the command as an autostart) you
+        may invoke it manually during your program initialisation.  This
+        is not recommended for all application authors -- it is your
+        choice if this use case concerns you enough.
+      </para>
+      <para>
+        Internally, <command>gsettings-data-convert</command> uses a
+        keyfile to track which settings have been migrated.  The
+        following code fragment will check that keyfile to see if your
+        data conversion script has been run yet and, if not, will
+        attempt to invoke the tool to run it.  You should adapt it to
+        your application as you see fit.
+      </para>
+      <para>
+        <programlisting>
+<![CDATA[
+static void
+ensure_migrated (const gchar *name)
+{
+  gboolean needed = TRUE;
+  GKeyFile *kf;
+  gchar **list;
+  gsize i, n;
+
+  kf = g_key_file_new ();
+
+  g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
+                                  NULL, G_KEY_FILE_NONE, NULL);
+  list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
+
+  if (list)
+    {
+      for (i = 0; i < n; i++)
+        if (strcmp (list[i], name) == 0)
+          {
+            needed = FALSE;
+            break;
+          }
+
+      g_strfreev (list);
+    }
+
+  g_key_file_free (kf);
+
+  if (needed)
+    g_spawn_command_line_sync ("gsettings-data-convert",
+                               NULL, NULL, NULL, NULL);
+}
+
+]]>
+        </programlisting>
+      </para>
+      <para>
+        Although there is the possibility that the
+        <command>gsettings-data-convert</command> script will end up
+        running multiple times concurrently with this approach, it is
+        believed that this is safe.
+      </para>
+    </section>
+  </chapter>

docs/reference/gio/migrating-gdbus.xml

@@ -0,0 +1,310 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+                  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<chapter>
+  <title>Migrating to GDBus</title>
+
+  <section>
+    <title>Conceptual differences</title>
+
+    <para>
+      The central concepts of D-Bus are modelled in a very similar way
+      in dbus-glib and GDBus. Both have objects representing connections,
+      proxies and method invocations. But there are some important
+      differences:
+      <itemizedlist>
+        <listitem><para>
+          dbus-glib uses the <ulink
+          url="http://www.freedesktop.org/wiki/Software/dbus#ReferenceImplementation.28dbus-daemonandlibdbus.29">libdbus
+          reference implementation</ulink>, GDBus doesn't. Instead, it
+          relies on GIO streams as transport layer, and has its own
+          implementation for the D-Bus connection setup and
+          authentication. Apart from using streams as transport,
+          avoiding libdbus also lets GDBus avoid some thorny
+          multithreading issues.
+        </para></listitem>
+        <listitem><para>
+          dbus-glib uses the GObject type system for method arguments and
+          return values, including a homegrown container specialization
+          mechanism. GDBus relies on the #GVariant type system which is
+          explicitly designed to match D-Bus types.
+        </para></listitem>
+        <listitem><para>
+          dbus-glib models only D-Bus interfaces and does not provide
+          any types for objects. GDBus models both D-Bus interfaces
+          (via the #GDBusInterface, #GDBusProxy and
+          #GDBusInterfaceSkeleton types) and objects (via the
+          #GDBusObject, #GDBusObjectSkeleton and #GDBusObjectProxy types).
+        </para></listitem>
+        <listitem><para>
+          GDBus includes native support for the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> (via the #GDBusProxy type) and <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> D-Bus interfaces, dbus-glib doesn't.
+        </para></listitem>
+        <listitem><para>
+          The typical way to export an object in dbus-glib involves
+          generating glue code from XML introspection data using
+          <command>dbus-binding-tool</command>. GDBus provides a
+          similar tool called <command><link
+          linkend="gdbus-codegen">gdbus-codegen</link></command> that
+          can also generate Docbook D-Bus interface documentation.
+        </para></listitem>
+        <listitem><para>
+          dbus-glib doesn't provide any convenience API for owning and
+          watching bus names, GDBus provides the g_bus_own_name() and
+          g_bus_watch_name() family of convenience functions.
+        </para></listitem>
+        <listitem><para>
+          GDBus provides API to parse, generate and work with <link
+          linkend="gio-D-Bus-Introspection-Data">Introspection
+          XML</link>, dbus-glib doesn't.
+        </para></listitem>
+        <listitem><para>
+          GTestDBus provides API to create isolated unit tests <link
+          linkend="gio-D-Bus-Test-Scaffolding">GDBus Test Scaffolding</link>.
+        </para></listitem>
+      </itemizedlist>
+    </para>
+  </section>
+
+  <section>
+    <title>API comparison</title>
+
+    <table id="dbus-glib-vs-gdbus">
+      <title>dbus-glib APIs and their GDBus counterparts</title>
+      <tgroup cols="2">
+        <thead>
+           <row><entry>dbus-glib</entry><entry>GDBus</entry></row>
+        </thead>
+        <tbody>
+          <row><entry>#DBusGConnection</entry><entry>#GDBusConnection</entry></row>
+          <row><entry>#DBusGProxy</entry><entry>#GDBusProxy, #GDBusInterface - also see #GDBusObjectProxy</entry></row>
+          <row><entry>#DBusGObject</entry><entry>#GDBusInterfaceSkeleton, #GDBusInterface - also see #GDBusObjectSkeleton</entry></row>
+          <row><entry>#DBusGMethodInvocation</entry><entry>#GDBusMethodInvocation</entry></row>
+          <row><entry>dbus_g_bus_get()</entry><entry>g_bus_get_sync(), also see
+               g_bus_get()</entry></row>
+          <row><entry>dbus_g_proxy_new_for_name()</entry><entry>g_dbus_proxy_new_sync() and
+               g_dbus_proxy_new_for_bus_sync(), also see g_dbus_proxy_new()</entry></row>
+          <row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
+          <row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
+          <row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object() - also see g_dbus_object_manager_server_export()</entry></row>
+          <row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object() - also see g_dbus_object_manager_server_unexport()</entry></row>
+          <row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
+               an object, see g_dbus_connection_register_object()</entry></row>
+          <row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_call()</entry></row>
+          <row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_call_finish()</entry></row>
+          <row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_call_sync()</entry></row>
+          <row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
+          <row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
+          <row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
+          <row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
+          <row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
+        </tbody>
+      </tgroup>
+    </table>
+  </section>
+
+  <section>
+    <title>Owning bus names</title>
+    <para>
+      Using dbus-glib, you typically call RequestName manually
+      to own a name, like in the following excerpt:
+      <informalexample><programlisting><![CDATA[
+  error = NULL;
+  res = dbus_g_proxy_call (system_bus_proxy,
+                           "RequestName",
+                           &error,
+                           G_TYPE_STRING, NAME_TO_CLAIM,
+                           G_TYPE_UINT,   DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
+                           G_TYPE_INVALID,
+                           G_TYPE_UINT,   &result,
+                           G_TYPE_INVALID);
+  if (!res)
+    {
+      if (error != NULL)
+        {
+          g_warning ("Failed to acquire %s: %s",
+                     NAME_TO_CLAIM, error->message);
+          g_error_free (error);
+        }
+      else
+        {
+          g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
+        }
+      goto out;
+    }
+
+  if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
+    {
+      if (error != NULL)
+        {
+          g_warning ("Failed to acquire %s: %s",
+                     NAME_TO_CLAIM, error->message);
+          g_error_free (error);
+        }
+      else
+        {
+          g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
+        }
+      exit (1);
+    }
+
+  dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
+                           G_TYPE_STRING, G_TYPE_INVALID);
+  dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
+                               G_CALLBACK (on_name_lost), NULL, NULL);
+
+  /* further setup ... */
+]]>
+      </programlisting></informalexample>
+    </para>
+    <para>
+    While you can do things this way with GDBus too, using
+    g_dbus_proxy_call_sync(), it is much nicer to use the high-level API
+    for this:
+    <informalexample><programlisting><![CDATA[
+static void
+on_name_acquired (GDBusConnection *connection,
+                  const gchar     *name,
+                  gpointer         user_data)
+{
+  /* further setup ... */
+}
+
+/* ... */
+
+  owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
+                             NAME_TO_CLAIM,
+                             G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
+                             on_bus_acquired,
+                             on_name_acquired,
+                             on_name_lost,
+                             NULL,
+                             NULL);
+
+  g_main_loop_run (loop);
+
+  g_bus_unown_name (owner_id);
+]]>
+    </programlisting></informalexample>
+    Note that g_bus_own_name() works asynchronously and requires
+    you to enter your mainloop to await the on_name_aquired()
+    callback. Also note that in order to avoid race conditions (e.g.
+    when your service is activated by a method call), you have to export
+    your manager object <emphasis>before</emphasis> acquiring the
+    name. The on_bus_acquired() callback is the right place to do
+    such preparations.
+    </para>
+  </section>
+
+  <section>
+    <title>Creating proxies for well-known names</title>
+    <para>
+      dbus-glib lets you create proxy objects for well-known names, like the
+      following example:
+      <informalexample><programlisting><![CDATA[
+  proxy = dbus_g_proxy_new_for_name (system_bus_connection,
+                                     "org.freedesktop.Accounts",
+                                     "/org/freedesktop/Accounts",
+                                     "org.freedesktop.Accounts");
+      ]]>
+      </programlisting></informalexample>
+      For a #DBusGProxy constructed like this, method calls will be sent to
+      the current owner of the name, and that owner can change over time.
+    </para>
+    <para>
+      The same can be achieved with #GDBusProxy:
+      <informalexample><programlisting><![CDATA[
+  error = NULL;
+  proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SYSTEM,
+                                         G_DBUS_PROXY_FLAGS_NONE,
+                                         NULL, /* GDBusInterfaceInfo */
+                                         "org.freedesktop.Accounts",
+                                         "/org/freedesktop/Accounts",
+                                         "org.freedesktop.Accounts",
+                                         NULL, /* GCancellable */
+                                         &error);
+      ]]>
+      </programlisting></informalexample>
+      For an added layer of safety, you can specify what D-Bus
+      interface the proxy is expected to conform to by using the
+      #GDBusInterfaceInfo type.  Additionally, #GDBusProxy loads,
+      caches and tracks changes to the D-Bus properties on the remote
+      object. It also sets up match rules so D-Bus signals from the
+      remote object are delivered locally.
+    </para>
+    <para>
+      The #GDBusProxy type normally isn't used directly - instead
+      proxies subclassing #GDBusProxy generated by <command><link
+      linkend="gdbus-codegen">gdbus-codegen</link></command> is used, see <xref linkend="gdbus-example-gdbus-codegen"/>
+    </para>
+  </section>
+
+  <section>
+    <title>Generating code and docs</title>
+
+  <section id="gdbus-example-gdbus-codegen">
+    <title>Using gdbus-codegen</title>
+
+    <para>
+      dbus-glib comes with <command>dbus-binding-tool</command>, which
+      can produce somewhat nice client- and server-side wrappers for a D-Bus interface.
+      With GDBus, <command><link
+      linkend="gdbus-codegen">gdbus-codegen</link></command> is used and like
+      its counterpart, it also takes D-Bus Introspection XML as input:
+    </para>
+    <example id="gdbus-example-codegen-input"><title>Example D-Bus Introspection XML</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-object-manager-example/gdbus-example-objectmanager.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager.xml</xi:fallback></xi:include></programlisting></example>
+    <para>
+      If this XML is processed like this
+<informalexample><programlisting><![CDATA[
+gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
+              --generate-c-code generated-code	                      \
+              --c-namespace Example 				      \
+              --c-generate-object-manager			      \
+              --generate-docbook generated-docs                       \
+              gdbus-example-objectmanager.xml
+]]></programlisting></informalexample>
+      then two files <filename>generated-code.h</filename> and
+      <filename>generated-code.c</filename> are
+      generated. Additionally, two XML files
+      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename> and
+      <filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat</filename>
+      with Docbook XML are generated. For an example of what the docs look
+      like see <link
+      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Animal">the Animal D-Bus interface documentation</link>.
+      and
+      <link
+      linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Cat">the Cat D-Bus interface documentation</link>.
+    </para>
+    <para>
+      While the contents of <filename>generated-code.h</filename> and
+      <filename>generated-code.c</filename> are best described by the
+      <command><link
+      linkend="gdbus-codegen">gdbus-codegen</link></command> manual
+      page, brief examples of how this generated code can be used can be found in
+      <xref linkend="gdbus-example-codegen-server"/>
+      and <xref
+      linkend="gdbus-example-codegen-client"/>. Additionally, since
+      the generated code has 100% gtk-doc coverage, see
+      #ExampleAnimal, #ExampleCat, #ExampleObject and
+      #ExampleObjectManagerClient pages for documentation.
+    </para>
+
+    <example id="gdbus-example-codegen-server"><title>Server-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-objectmanager-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager-server.c</xi:fallback></xi:include></programlisting></example>
+
+    <example id="gdbus-example-codegen-client"><title>Client-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-objectmanager-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager-client.c</xi:fallback></xi:include></programlisting></example>
+
+  </section>
+
+  <!-- All XInclude paths are relative to the html/ directory under the build root directory -->
+  <xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml</xi:fallback></xi:include>
+  <xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml</xi:fallback></xi:include>
+  <xi:include href="../gdbus-object-manager-example/xml/ExampleAnimal.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleAnimal.xml</xi:fallback></xi:include>
+  <xi:include href="../gdbus-object-manager-example/xml/ExampleCat.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleCat.xml</xi:fallback></xi:include>
+  <xi:include href="../gdbus-object-manager-example/xml/ExampleObject.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleObject.xml</xi:fallback></xi:include>
+  <xi:include href="../gdbus-object-manager-example/xml/ExampleObjectManagerClient.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleObjectManagerClient.xml</xi:fallback></xi:include>
+
+  </section>
+
+</chapter>

docs/reference/gio/migrating-gnome-vfs.xml

@@ -0,0 +1,133 @@
+  <chapter>
+    <title>Migrating from GnomeVFS to GIO</title>
+
+    <table id="gnome-vfs-vs-gio">
+      <title>Comparison of GnomeVFS and GIO concepts</title>
+      <tgroup cols="2">
+        <thead>
+          <row><entry>GnomeVFS</entry><entry>GIO</entry></row>
+        </thead>
+        <tbody>
+          <row><entry>GnomeVFSURI</entry><entry>GFile</entry></row>
+          <row><entry>GnomeVFSFileInfo</entry><entry>GFileInfo</entry></row>
+          <row><entry>GnomeVFSResult</entry><entry>GError, with G_IO_ERROR values</entry></row>
+          <row><entry>GnomeVFSHandle &amp; GnomeVFSAsyncHandle</entry><entry>GInputStream or GOutputStream</entry></row>
+          <row><entry>GnomeVFSDirectoryHandle</entry><entry>GFileEnumerator</entry></row>
+          <row><entry>mime type</entry><entry>content type</entry></row>
+          <row><entry>GnomeVFSMonitor</entry><entry>GFileMonitor</entry></row>
+          <row><entry>GnomeVFSVolumeMonitor</entry><entry>GVolumeMonitor</entry></row>
+          <row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
+          <row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
+          <row><entry>-</entry><entry>GDrive</entry></row>
+          <row><entry>GnomeVFSContext</entry><entry>GCancellable</entry></row>
+          <row><entry>gnome_vfs_async_cancel</entry><entry>g_cancellable_cancel</entry></row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <section>
+      <title>Trash handling</title>
+
+      <para>
+        The handling of trashed files has been changed in GIO, compared
+        to gnome-vfs. gnome-vfs has a home-grown trash implementation that 
+        predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
+        that is implemented in GIO. The location for storing trashed files 
+        has changed from <filename>$HOME/.Trash</filename> to 
+        <filename>$HOME/.local/share/Trash</filename> (or more correctly
+        <filename>$XDG_DATA_HOME/Trash</filename>), which means that 
+        there is a need for migrating files that have been trashed by 
+        gnome-vfs to the new location.
+      </para>
+      <para>
+        In gnome-vfs, the <filename>trash://</filename> scheme offering a 
+        merged view of all trash directories was implemented in nautilus,
+        and trash-handling applications had to find and monitor all trash 
+        directories themselves. With GIO, the <filename>trash://</filename>
+        implementation has been moved to gvfs and applications can simply
+        monitor that location:
+      </para>
+<informalexample><programlisting>
+static void
+file_changed (GFileMonitor      *file_monitor,
+              GFile             *child,
+              GFile             *other_file,
+              GFileMonitorEvent  event_type,
+              gpointer           user_data)
+{
+  switch (event_type)
+  {
+  case G_FILE_MONITOR_EVENT_DELETED:
+    g_print ("'%s' removed from trash\n", g_file_get_basename (child));
+    break;
+  case G_FILE_MONITOR_EVENT_CREATED:
+    g_print ("'%s' added to trash\n", g_file_get_basename (child));
+    break;
+  default: ;
+  }
+}
+
+static void
+start_monitoring_trash (void)
+{
+  GFile *file;
+  GFileMonitor *monitor;
+
+  file = g_file_new_for_uri ("trash://");
+  monitor = g_file_monitor_directory (file, 0, NULL, NULL);
+  g_object_unref (file);
+
+  g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
+
+  /* ... */
+
+}       
+</programlisting></informalexample> 
+      <para>
+        GIO exposes some useful metadata about trashed files. There are
+        trash::orig-path and trash::deletion-date attributes. The 
+        standard::icon attribute of the <filename>trash://</filename> 
+        itself provides a suitable icon for displaying the trash can on 
+        the desktop. If you are using this icon, make sure to monitor
+        this attribute for changes, since the icon may be updated to
+        reflect that state of the trash can.
+      </para>
+      <para>
+        Moving a file to the trash is much simpler with GIO. Instead of
+        using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH 
+        to find out where to move the trashed file, just use the g_file_trash()
+        function.
+      </para>
+    </section>
+
+    <section>
+      <title>Operations on multiple files</title>
+
+      <para>
+        gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
+        has tons of options and offers the equivalent of cp, mv, ln, mkdir
+        and rm at the same time. 
+      </para>
+      <para>
+        GIO offers a much simpler I/O scheduler functionality instead, that
+        lets you schedule a function to be called in a separate thread, or
+        if threads are not available, as an idle in the mainloop.
+        See g_io_scheduler_push_job(). 
+      </para>
+
+    </section>
+
+    <section>
+      <title>Mime monitoring</title>
+
+      <para>
+        gnome-vfs offered a way to monitor the association between mime types
+        and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
+        GIO does not offer a replacement for this functionality at this time,
+        since we have not found a compelling use case where
+        #GnomeVFSMIMEMonitor was used. If you think you have such a use
+        case, please report it at
+        <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
+      </para>
+    </section>
+  </chapter>

docs/reference/gio/migrating-posix.xml

@@ -0,0 +1,27 @@
+<part id="migrating">
+  <title>Migrating to GIO</title>
+
+  <chapter>
+    <title>Migrating from POSIX to GIO</title>
+  
+    <table id="posix-vs-gio">
+      <title>Comparison of POSIX and GIO concepts</title>
+      <tgroup cols="2">
+        <thead>
+          <row><entry>POSIX</entry><entry>GIO</entry></row>
+        </thead>
+        <tbody>
+          <row><entry>char *path</entry><entry>GFile *file</entry></row>
+          <row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
+          <row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
+          <row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
+          <row><entry>GOutputStream *out</entry></row>
+          <row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
+          <row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
+          <row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
+        </tbody>
+      </tgroup>
+    </table>  
+
+  </chapter>
+</part>

docs/reference/gio/overview.xml

@@ -0,0 +1,745 @@
+<part>
+  <title>GIO Overview</title>
+
+  <chapter>
+    <title>Introduction</title>
+
+  <para>
+    GIO is striving to provide a modern, easy-to-use VFS API that sits
+    at the right level in the library stack, as well as other generally
+    useful APIs for desktop applications (such as networking and
+    D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
+    and provide an API that is so good that developers prefer it over raw
+    POSIX calls. Among other things that means using GObject. It also means
+    not cloning the POSIX API, but providing higher-level, document-centric
+    interfaces.
+  </para>
+
+  <para>
+    The abstract file system model of GIO consists of a number of
+    interfaces and base classes for I/O and files:
+    <variablelist>
+       <varlistentry>
+         <term>GFile</term>
+         <listitem><para>reference to a file</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GFileInfo</term>
+         <listitem><para>information about a file or filesystem</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GFileEnumerator</term>
+         <listitem><para>list files in directories</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GDrive</term>
+         <listitem><para>represents a drive</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GVolume</term>
+         <listitem><para>represents a file system in an abstract way</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GMount</term>
+         <listitem><para>represents a mounted file system</para></listitem>
+       </varlistentry>
+    </variablelist>
+    Then there is a number of stream classes, similar to the input and
+    output stream hierarchies that can be found in frameworks like Java:
+    <variablelist>
+       <varlistentry>
+         <term>GInputStream</term>
+         <listitem><para>read data</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GOutputStream</term>
+         <listitem><para>write data</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GIOStream</term>
+         <listitem><para>read and write data</para></listitem>
+       </varlistentry>
+       <varlistentry>
+         <term>GSeekable</term>
+         <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
+       </varlistentry>
+    </variablelist>
+    There are interfaces related to applications and the types
+    of files they handle:
+    <variablelist>
+       <varlistentry>
+          <term>GAppInfo</term>
+          <listitem><para>information about an installed application</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GIcon</term>
+          <listitem><para>abstract type for file and application icons</para></listitem>
+       </varlistentry>
+    </variablelist>
+    There is a framework for storing and retrieving application settings:
+    <variablelist>
+       <varlistentry>
+          <term>GSettings</term>
+          <listitem><para>stores and retrieves application settings</para></listitem>
+       </varlistentry>
+    </variablelist>
+    There is support for network programming, including connectivity monitoring,
+    name resolution, lowlevel socket APIs and highlevel client and server
+    helper classes:
+    <variablelist>
+       <varlistentry>
+          <term>GSocket</term>
+          <listitem><para>lowlevel platform independent socket object</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GResolver</term>
+          <listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GSocketClient</term>
+          <listitem><para>high-level network client helper</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GSocketService</term>
+          <listitem><para>high-level network server helper</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GSocketConnection</term>
+          <listitem><para>network connection stream</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GNetworkMonitor</term>
+          <listitem><para>network connectivity monitoring</para></listitem>
+       </varlistentry>
+    </variablelist>
+    There is support for connecting to <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
+    sending and receiving messages, owning and watching bus names,
+    and making objects available on the bus:
+    <variablelist>
+       <varlistentry>
+          <term>GDBusConnection</term>
+          <listitem><para>a D-Bus connection</para></listitem>
+       </varlistentry>
+
+       <varlistentry>
+          <term>GDBusMethodInvocation</term>
+          <listitem><para>for handling remote calls</para></listitem>
+       </varlistentry>
+
+       <varlistentry>
+          <term>GDBusServer</term>
+          <listitem><para>helper for accepting connections</para></listitem>
+       </varlistentry>
+
+       <varlistentry>
+          <term>GDBusProxy</term>
+          <listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
+       </varlistentry>
+
+    </variablelist>
+    Beyond these, GIO provides facilities for file monitoring,
+    asynchronous I/O and filename completion. In addition to the
+    interfaces, GIO provides implementations for the local case.
+    Implementations for various network file systems are provided
+    by the GVFS package as loadable modules.
+  </para>
+
+  <para>
+    Other design choices which consciously break with the GnomeVFS
+    design are to move backends out-of-process, which minimizes the
+    dependency bloat and makes the whole system more robust. The backends
+    are not included in GIO, but in the separate GVFS package. The GVFS
+    package also contains the GVFS daemon, which spawn further mount
+    daemons for each individual connection.
+  </para>
+
+  <figure id="gvfs-overview">
+    <title>GIO in the GTK+ library stack</title>
+    <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
+  </figure>
+
+  <para>
+    The GIO model of I/O is stateful: if an application establishes e.g.
+    a SFTP connection to a server, it becomes available to all applications
+    in the session; the user does not have to enter their password over
+    and over again.
+  </para>
+  <para>
+    One of the big advantages of putting the VFS in the GLib layer
+    is that GTK+ can directly use it, e.g. in the filechooser.
+  </para>
+  </chapter>
+
+  <chapter>
+    <title>Writing GIO applications</title>
+
+    <para>
+      The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
+      applications is generally applicable when writing GIO applications.
+    </para>
+
+    <simplesect><title>Threads</title>
+
+    <para>
+       GDBus has its own private worker thread, so applications using
+       GDBus have at least 3 threads. GIO makes heavy use of the concept
+       of a <link linkend="g-main-context-push-thread-default">thread-default
+       main context</link> to execute callbacks of asynchronous
+       methods in the same context in which the operation was started.
+    </para>
+
+    </simplesect>
+
+    <simplesect id="async-programming"><title>Asynchronous Programming</title>
+
+    <para>
+      Many GIO functions come in two versions: synchronous and asynchronous,
+      denoted by an <code>_async</code> suffix. It is important to use these
+      appropriately: synchronous calls should not be used from
+      within a main loop which is shared with other code, such as one in the
+      application’s main thread. Synchronous calls block until they complete,
+      and I/O operations can take noticeable amounts of time (even on ‘fast’
+      SSDs). Blocking a main loop iteration while waiting for I/O means that
+      other sources in the main loop will not be dispatched, such as input and
+      redraw handlers for the application’s UI. This can cause the application
+      to ‘freeze’ until I/O completes.
+    </para>
+
+    <para>
+      A few self-contained groups of functions, such as code generated by
+      <link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
+      use a different convention: functions are asynchronous default, and it is
+      the <emphasis>synchronous</emphasis> version which has a
+      <code>_sync</code>
+      suffix. Aside from naming differences, they should be treated the same
+      way as functions following the normal convention above.
+    </para>
+
+    <para>
+      The asynchronous (<code>_async</code>) versions of functions return
+      control to the caller immediately, after scheduling the I/O in the kernel
+      and adding a callback for it to the main loop. This callback will be
+      invoked when the operation has completed. From the callback, the paired
+      <code>_finish</code> function should be called to retrieve the return
+      value of the I/O operation, and any errors which occurred. For more
+      information on using and implementing asynchronous functions, see
+      <link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
+      and <link linkend="GTask.description"><type>GTask</type></link>.
+    </para>
+
+    <para>
+      By starting multiple asynchronous operations in succession, they will be
+      executed in parallel (up to an arbitrary limit imposed by GIO’s internal
+      worker thread pool).
+    </para>
+
+    <para>
+      The synchronous versions of functions can be used early in application
+      startup when there is no main loop to block, for example to load initial
+      configuration files. They can also be used for I/O on files which are
+      guaranteed to be small and on the local disk. Note that the user’s home
+      directory is not guaranteed to be on the local disk.
+    </para>
+    </simplesect>
+
+    <simplesect><title>Security</title>
+
+<para>
+When your program needs to carry out some privileged operation (say,
+create a new user account), there are various ways in which you can go
+about this:
+<itemizedlist>
+<listitem><para>
+Implement a daemon that offers the privileged operation. A convenient
+way to do this is as a D-Bus system-bus service. The daemon will probably
+need ways to check the identity and authorization of the caller before
+executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
+</para></listitem>
+<listitem><para>
+Use a small helper that is executed with elevated privileges via
+pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.
+</para></listitem>
+<listitem><para>
+Use a small helper that is executed with elevated privileges by
+being suid root.
+</para></listitem>
+</itemizedlist>
+None of these approaches is the clear winner, they all have their
+advantages and disadvantages.
+</para>
+
+<para>
+When writing code that runs with elevated privileges, it is important
+to follow some basic rules of secure programming. David Wheeler has an
+excellent book on this topic,
+<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
+</para>
+
+<para>
+When using GIO in code that runs with elevated privileges, you have to
+be careful. GIO has extension points whose implementations get loaded
+from modules (executable code in shared objects), which could allow
+an attacker to sneak their own code into your application by tricking it
+into loading the code as a module. However, GIO will never load modules
+from your home directory except when explicitly asked to do so via an
+environment variable.
+</para>
+
+<para>
+In most cases, your helper program should be so small that you don't
+need GIO, whose APIs are largely designed to support full-blown desktop
+applications. If you can't resist the convenience of these APIs, here
+are some steps you should take:
+<itemizedlist>
+<listitem><para>
+Clear the environment, e.g. using the <function>clearenv()</function>
+function.
+David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is
+important to sanitize the environment.
+See <xref linkend="running-gio-apps"/>
+for a list of all environment variables affecting GIO. In particular,
+<envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.
+</para></listitem>
+<listitem><para>
+Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
+The reason to avoid GVfs in security-sensitive programs is that it uses
+many libraries which have not necessarily been audited for security problems.
+Gvfs is also heavily distributed and relies on a session bus to be present.
+</para></listitem>
+</itemizedlist>
+</para>
+
+    </simplesect>
+
+  </chapter>
+
+  <chapter>
+    <title>Compiling GIO applications</title>
+
+    <para>
+      GIO comes with a <filename>gio-2.0.pc</filename> file that you
+      should use together with <literal>pkg-config</literal> to obtain
+      the necessary information about header files and libraries. See
+      the <literal>pkg-config</literal> man page or the GLib documentation
+      for more information on how to use <literal>pkg-config</literal>
+      to compile your application.
+    </para>
+
+    <para>
+      If you are using GIO on UNIX-like systems, you may want to use
+      UNIX-specific GIO interfaces such as #GUnixInputStream,
+      #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
+      To do so, use the <filename>gio-unix-2.0.pc</filename> file
+      instead of <filename>gio-2.0.pc</filename>
+    </para>
+  </chapter>
+
+  <chapter id="running-gio-apps">
+    <title>Running GIO applications</title>
+
+    <para>
+      GIO inspects a few environment variables in addition to the
+      ones used by GLib.
+    </para>
+
+    <formalpara>
+      <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
+
+      <para>
+        GIO uses these environment variables to locate MIME information.
+        For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
+        and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GVFS_DISABLE_FUSE</envar></title>
+
+      <para>
+        This variable can be set to keep #Gvfs from starting the fuse backend,
+        which may be unwanted or unnecessary in certain situations.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GIO_USE_VFS</envar></title>
+
+      <para>
+        This environment variable can be set to the name of a #GVfs
+        implementation to override the default for debugging purposes.
+        The #GVfs implementation for local files that is included in GIO
+        has the name "local", the implementation in the gvfs module has
+        the name "gvfs".  Most commonly, system software will set this to "local"
+        to avoid having `GFile` APIs perform unnecessary D-Bus calls.
+      </para><para>
+        The special value <literal>help</literal> can be used to print a list of
+        available implementations to standard output.
+      </para>
+    </formalpara>
+
+    <para>
+      The following environment variables are only useful for debugging
+      GIO itself or modules that it loads. They should not be set in a
+      production environment.
+    </para>
+
+    <formalpara>
+      <title><envar>GIO_USE_FILE_MONITOR</envar></title>
+
+      <para>
+        This variable can be set to the name of a #GFileMonitor
+        implementation to override the default for debugging purposes.
+        The #GFileMonitor implementation for local files that is included
+        in GIO on Linux has the name <literal>inotify</literal>, others that are built
+        are built as modules (depending on the platform) are called
+        <literal>fam</literal> and <literal>fen</literal>.
+      </para><para>
+        The special value <literal>help</literal> can be used to print a list of
+        available implementations to standard output.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
+
+      <para>
+        This variable can be set to the name of a #GVolumeMonitor
+        implementation to override the default for debugging purposes.
+        The #GVolumeMonitor implementation for local files that is included
+        in GIO has the name "unix", the udisks2-based implementation in the
+        gvfs module has the name "udisks2".
+      </para><para>
+        The special value <literal>help</literal> can be used to print a list of
+        available implementations to standard output.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GIO_USE_TLS</envar></title>
+
+      <para>
+        This variable can be set to the name of a #GTlsBackend
+        implementation to override the default for debugging purposes.
+        GIO does not include a #GTlsBackend implementation, the gnutls-based
+        implementation in the glib-networking module has the name "gnutls".
+      </para><para>
+        The special value <literal>help</literal> can be used to print a list of
+        available implementations to standard output.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GIO_MODULE_DIR</envar></title>
+
+      <para>
+        When this environment variable is set to a path, GIO will load
+	modules from this alternate directory instead of the directory
+	built into GIO. This is useful when running tests, for example.
+      </para>
+      <para>
+        This environment variable is ignored when running in a setuid program.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GIO_EXTRA_MODULES</envar></title>
+
+      <para>
+        When this environment variable is set to a path, or a set of
+        paths separated by a colon, GIO will attempt to load
+        additional modules from within the path.
+      </para>
+      <para>
+        This environment variable is ignored when running in a setuid program.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GSETTINGS_BACKEND</envar></title>
+
+      <para>
+        This variable can be set to the name of a #GSettingsBackend
+        implementation to override the default for debugging purposes.
+        The memory-based implementation that is included in GIO has
+        the name "memory", the one in dconf has the name "dconf".
+      </para><para>
+        The special value <literal>help</literal> can be used to print a list of
+        available implementations to standard output.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
+
+      <para>
+        This variable can be set to the names of directories to consider when looking for compiled schemas for #GSettings,
+        in addition to the <filename>glib-2.0/schemas</filename>
+        subdirectories of the XDG system data dirs. To specify multiple directories, use <constant>G_SEARCHPATH_SEPARATOR_S</constant> as a separator.
+      </para>
+    </formalpara>
+
+   <formalpara>
+      <title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
+
+      <para>
+        This variable is consulted to find the address of the D-Bus system
+        bus. For the format of D-Bus addresses, see the D-Bus
+        <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
+      </para>
+      <para>
+        Setting this variable overrides platform-specific ways of determining
+        the system bus address.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
+
+      <para>
+        This variable is consulted to find the address of the D-Bus session bus.
+      </para>
+      <para>
+        Setting this variable overrides platform-specific ways of determining
+        the session bus address.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
+
+      <para>
+        This variable is consulted to find out the 'starter' bus for an
+        application that has been started via D-Bus activation. The possible
+        values are 'system' or 'session'.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title><envar>G_DBUS_DEBUG</envar></title>
+
+      <para>
+         This variable can be set to a list of debug options, which
+         cause GLib to print out different types of debugging
+         information when using the D-Bus routines.
+         <variablelist>
+           <varlistentry>
+             <term>transport</term>
+             <listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>message</term>
+             <listitem><para>Show all sent and received D-Bus messages</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>payload</term>
+             <listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>call</term>
+             <listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>signal</term>
+             <listitem><para>Show when a D-Bus signal is received</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>incoming</term>
+             <listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>return</term>
+             <listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>emission</term>
+             <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>authentication</term>
+             <listitem><para>Show information about connection authentication</para></listitem>
+           </varlistentry>
+           <varlistentry>
+             <term>address</term>
+             <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
+           </varlistentry>
+         </variablelist>
+         The special value <literal>all</literal> can be used to turn
+         on all debug options. The special value
+         <literal>help</literal> can be used to print a list of
+         supported options to standard output.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
+
+      <para>
+        Can be used to override the directory used to store the
+        keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
+        authentication mechanism. Normally the directory used is
+        <filename>.dbus-keyrings</filename> in the user's home
+        directory.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
+
+      <para>
+        If set, the permissions of the directory used to store the
+        keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
+        authentication mechanism won't be checked. Normally the
+        directory must be readable only by the user.
+      </para>
+   </formalpara>
+  </chapter>
+
+  <chapter id="extending-gio">
+    <title>Extending GIO</title>
+
+    <para>
+      A lot of the functionality that is accessible through GIO
+      is implemented in loadable modules, and modules provide a convenient
+      way to extend GIO. In addition to the #GIOModule API which supports
+      writing such modules, GIO has a mechanism to define extension points,
+      and register implementations thereof, see #GIOExtensionPoint.
+    </para>
+    <para>
+      The following extension points are currently defined by GIO:
+    </para>
+
+    <formalpara>
+       <title>G_VFS_EXTENSION_POINT_NAME</title>
+
+       <para>
+          Allows to override the functionality of the #GVfs class.
+          Implementations of this extension point must be derived from #GVfs.
+          GIO uses the implementation with the highest priority that is active,
+          see g_vfs_is_active().
+       </para>
+       <para>
+          GIO implements this extension point for local files, gvfs contains
+          an implementation that supports all the backends in gvfs.
+       </para>
+   </formalpara>
+
+   <formalpara>
+      <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
+
+      <para>
+         Allows to add more volume monitors.
+         Implementations of this extension point must be derived from
+         #GVolumeMonitor. GIO uses all registered extensions.
+      </para>
+      <para>
+        gvfs contains an implementation that works together with the #GVfs
+        implementation in gvfs.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
+
+      <para>
+         Allows to override the 'native' volume monitor.
+         Implementations of this extension point must be derived from
+         #GNativeVolumeMonitor. GIO uses the implementation with
+         the highest priority that is supported, as determined by the
+         is_supported() vfunc in #GVolumeMonitorClass.
+      </para>
+      <para>
+         GIO implements this extension point for local mounts,
+         gvfs contains a udisks2-based implementation.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
+
+      <para>
+        Allows to override the file monitor implementation for
+        local files. Implementations of this extension point must
+        be derived from #GLocalFileMonitor. GIO uses the implementation
+        with the highest priority that is supported, as determined by the
+        is_supported() vfunc in #GLocalFileMonitorClass.
+      </para>
+      <para>
+        GIO uses this extension point internally, to switch between
+        its fam-based and inotify-based file monitoring implementations.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
+
+      <para>
+        Unix-only. Allows to provide a way to associate default handlers
+        with URI schemes. Implementations of this extension point must
+        implement the #GDesktopAppInfoLookup interface. GIO uses the
+        implementation with the highest priority.
+      </para>
+      <para>
+        This extension point has been discontinued in GLib 2.28. It is
+        still available to keep API and ABI stability, but GIO is no
+        longer using it for default handlers. Instead, the mime handler
+        mechanism is used, together with x-scheme-handler pseudo-mimetypes.
+      </para>
+   </formalpara>
+
+   <formalpara>
+      <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
+
+      <para>
+        Allows to provide an alternative storage for #GSettings.
+        Implementations of this extension point must derive from the
+        #GSettingsBackend type. GIO contains a keyfile-based
+        implementation of this extension point, another one is provided
+        by dconf.
+      </para>
+   </formalpara>
+
+   <formalpara>
+     <title>G_PROXY_EXTENSION_POINT_NAME</title>
+
+     <para>
+       Allows to provide implementations for network proxying.
+       Implementations of this extension point must provide the
+       #GProxy interface, and must be named after the network
+       protocol they are proxying.
+     </para>
+     <para>
+       glib-networking contains an implementation of this extension
+       point based on libproxy.
+     </para>
+   </formalpara>
+   <formalpara>
+     <title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
+
+     <para>
+       Allows to provide implementations for TLS support.
+       Implementations of this extension point must implement
+       the #GTlsBackend interface.
+     </para>
+     <para>
+       glib-networking contains an implementation of this extension
+       point.
+     </para>
+   </formalpara>
+
+   <formalpara>
+     <title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
+
+     <para>
+       Allows to provide implementations for network connectivity
+       monitoring.
+       Implementations of this extension point must implement
+       the #GNetworkMonitorInterface interface.
+     </para>
+     <para>
+       GIO contains an implementation of this extension point
+       that is using the netlink interface of the Linux kernel.
+     </para>
+   </formalpara>
+  </chapter>
+</part>
+

docs/reference/gio/version.xml.in

@@ -0,0 +1 @@
+@VERSION@

docs/reference/gio/xml/gtkdocentities.ent.in

@@ -0,0 +1,8 @@
+<!ENTITY package "@PACKAGE@">
+<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
+<!ENTITY package_name "@PACKAGE_NAME@">
+<!ENTITY package_string "@PACKAGE_STRING@">
+<!ENTITY package_tarname "@PACKAGE_TARNAME@">
+<!ENTITY package_url "@PACKAGE_URL@">
+<!ENTITY package_version "@PACKAGE_VERSION@">
+<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

docs/reference/gio/xml/meson.build

@@ -0,0 +1,14 @@
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'glib')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/glib/issues/new')
+ent_conf.set('PACKAGE_NAME', 'glib')
+ent_conf.set('PACKAGE_STRING', 'glib')
+ent_conf.set('PACKAGE_TARNAME', 'glib')
+ent_conf.set('PACKAGE_URL', 'FIXME')
+ent_conf.set('PACKAGE_VERSION', glib_version)
+ent_conf.set('PACKAGE_API_VERSION', glib_api_version)
+configure_file(
+  input: 'gtkdocentities.ent.in',
+  output: 'gtkdocentities.ent',
+  configuration: ent_conf
+)

docs/reference/glib/Sorted_binary_tree_breadth-first_traversal.svg

@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 16.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="266px" height="212px" viewBox="0 0 266 212" enable-background="new 0 0 266 212" xml:space="preserve">
+<g>
+	<g>
+		<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="27.23" y1="23.192" x2="29.23" y2="23.192"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9562,3.9562" x1="33.187" y1="23.192" x2="236.932" y2="23.192"/>
+		<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,23.192 240.91,23.192 
+			238.97,23.677 		"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="24.646" x2="27.971" y2="76.427"/>
+		<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,76.912 24.095,77.396 
+			26.095,77.396 		"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="77.396" x2="236.902" y2="77.396"/>
+		<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,77.396 240.91,77.396 
+			238.97,77.881 		"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="78.85" x2="27.971" y2="130.631"/>
+		<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,131.114 24.095,131.6 
+			26.095,131.6 		"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="131.6" x2="236.902" y2="131.6"/>
+		<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,131.6 240.91,131.6 
+			238.97,132.085 		"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="133.053" x2="27.971" y2="184.835"/>
+		<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,185.318 24.095,185.804 
+			26.095,185.804 		"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0086,4.0086" x1="30.104" y1="185.804" x2="228.53" y2="185.804"/>
+		
+			<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="230.534" y1="185.804" x2="232.534" y2="185.804"/>
+		<g>
+			<rect x="24.095" y="19.892" width="6.602" height="6.602"/>
+		</g>
+		<g>
+			<path d="M238.569,185.804c-2.84,1.054-6.363,2.852-8.548,4.756l1.721-4.756l-1.721-4.755
+				C232.206,182.953,235.729,184.751,238.569,185.804z"/>
+		</g>
+	</g>
+</g>
+<g id="graph0">
+	<title>sorted_binary_tree</title>
+	<g id="node1">
+		<title>C</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="185.804" rx="18.067" ry="18.067"/>
+		<text transform="matrix(1 0 0 1 55.5435 190.8223)" font-family="'Times-Roman'" font-size="14.0528">C</text>
+	</g>
+	<g id="node2">
+		<title>E</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="185.804" rx="18.067" ry="18.067"/>
+		<text transform="matrix(1 0 0 1 128.21 190.8223)" font-family="'Times-Roman'" font-size="14.0528">E</text>
+	</g>
+	<g id="node3">
+		<title>H</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="185.804" rx="17.064" ry="18.067"/>
+		<text transform="matrix(1 0 0 1 199.6992 190.8223)" font-family="'Times-Roman'" font-size="14.0528">H</text>
+	</g>
+	<g id="node4">
+		<title>A</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="24.094" cy="131.6" rx="17.064" ry="18.068"/>
+		<text transform="matrix(1 0 0 1 19.02 136.6191)" font-family="'Times-Roman'" font-size="14.0528">A</text>
+	</g>
+	<g id="node5">
+		<title>D</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="96.366" cy="131.6" rx="17.064" ry="18.068"/>
+		<text transform="matrix(1 0 0 1 91.292 136.6191)" font-family="'Times-Roman'" font-size="14.0528">D</text>
+	</g>
+	<g id="edge6">
+		<title>D-&gt;C</title>
+		<path fill="none" stroke="#000000" d="M86.328,147.66c-3.011,4.016-7.026,9.034-10.038,14.053"/>
+		<polygon stroke="#000000" points="78.298,164.725 70.268,170.747 73.279,160.709 		"/>
+	</g>
+	<g id="edge8">
+		<title>D-&gt;E</title>
+		<path fill="none" stroke="#000000" d="M106.404,147.66c3.011,4.016,7.026,9.034,10.038,14.053"/>
+		<polygon stroke="#000000" points="119.453,160.709 122.464,170.747 114.434,164.725 		"/>
+	</g>
+	<g id="node6">
+		<title>I</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="240.909" cy="131.6" rx="18.068" ry="18.068"/>
+		<text transform="matrix(1 0 0 1 238.5693 136.6191)" font-family="'Times-Roman'" font-size="14.0528">I</text>
+	</g>
+	<g id="edge12">
+		<title>I-&gt;H</title>
+		<path fill="none" stroke="#000000" d="M230.871,146.656c-3.011,5.02-6.021,10.038-10.037,15.057"/>
+		<polygon stroke="#000000" points="223.846,163.721 214.812,169.743 217.822,159.705 		"/>
+	</g>
+	<g id="node7">
+		<title>B</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="77.396" rx="18.068" ry="18.068"/>
+		<text transform="matrix(1 0 0 1 55.5435 82.415)" font-family="'Times-Roman'" font-size="14.0528">B</text>
+	</g>
+	<g id="edge3">
+		<title>B-&gt;A</title>
+		<path fill="none" stroke="#000000" d="M50.192,92.453c-3.011,5.019-6.022,10.038-10.038,15.057"/>
+		<polygon stroke="#000000" points="43.166,109.518 34.132,115.539 37.144,105.502 		"/>
+	</g>
+	<g id="edge5">
+		<title>B-&gt;D</title>
+		<path fill="none" stroke="#000000" d="M70.268,92.453c3.011,5.019,6.022,10.038,10.038,15.057"/>
+		<polygon stroke="#000000" points="83.317,105.502 86.328,115.539 77.294,109.518 		"/>
+	</g>
+	<g id="node8">
+		<title>G</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="77.396" rx="17.064" ry="18.068"/>
+		<text transform="matrix(1 0 0 1 199.6992 82.415)" font-family="'Times-Roman'" font-size="14.0528">G</text>
+	</g>
+	<g id="edge11">
+		<title>G-&gt;I</title>
+		<path fill="none" stroke="#000000" d="M214.812,93.457c3.011,4.015,7.026,9.034,10.038,14.053"/>
+		<polygon stroke="#000000" points="227.86,106.506 230.871,116.543 222.842,110.521 		"/>
+	</g>
+	<g id="node9">
+		<title>F</title>
+		<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="23.192" rx="18.068" ry="18.068"/>
+		<text transform="matrix(1 0 0 1 128.5942 28.2109)" font-family="'Times-Roman'" font-size="14.0528">F</text>
+	</g>
+	<g id="edge2">
+		<title>F-&gt;B</title>
+		<path fill="none" stroke="#000000" d="M117.445,34.234c-11.042,8.03-23.087,17.064-34.128,26.098"/>
+		<polygon stroke="#000000" points="85.325,63.343 75.287,66.354 81.31,57.321 		"/>
+	</g>
+	<g id="edge10">
+		<title>F-&gt;G</title>
+		<path fill="none" stroke="#000000" d="M147.559,34.234c11.041,8.03,23.087,17.064,34.129,26.098"/>
+		<polygon stroke="#000000" points="183.694,57.321 189.717,66.354 179.68,63.343 		"/>
+	</g>
+</g>
+</svg>

docs/reference/glib/building.xml

@@ -0,0 +1,365 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-building">
+  <refmeta>
+    <refentrytitle>Compiling the GLib package</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>GLib Library</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>Compiling the GLib Package</refname>
+    <refpurpose>How to compile GLib itself</refpurpose>
+  </refnamediv>
+
+  <refsect1 id="building">
+    <title>Building the Library on UNIX</title>
+    <para>
+      On UNIX, GLib uses the standard <application>Meson</application> build
+      system. The normal sequence for compiling and installing the GLib library
+      is thus:
+
+      <literallayout>
+        <userinput>meson _build</userinput>
+        <userinput>ninja -C _build</userinput>
+        <userinput>ninja -C _build install</userinput>
+      </literallayout>
+
+      On FreeBSD:
+      <literallayout>
+        <userinput>env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" meson -Dxattr=false -Dinstalled_tests=true -Diconv=external -Db_lundef=false _build</userinput>
+        <userinput>ninja -C _build</userinput>
+      </literallayout>
+    </para>
+
+    <para>
+      The standard options provided by <application>Meson</application> may be
+      passed to the <command>meson</command> command.  Please see the
+      <application>Meson</application> documentation or run
+      <command>meson configure --help</command> for information about
+      the standard options.
+    </para>
+    <para>
+      GLib is compiled with
+      <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
+      disabled. It is strongly recommended that this is not re-enabled by
+      overriding the compiler flags, as GLib has not been tested with strict
+      aliasing and cannot be guaranteed to work.
+    </para>
+    <para>
+      The GTK+ documentation contains
+      <ulink url="https://developer.gnome.org/gtk3/stable/gtk-building.html">further details</ulink>
+      about the build process and ways to influence it.
+    </para>
+  </refsect1>
+  <refsect1 id="dependencies">
+    <title>Dependencies</title>
+    <para>
+      Before you can compile the GLib library, you need to have
+      various other tools and libraries installed on your system.
+      If you are building from a release archive, you will need
+      <ulink url="https://wiki.gnome.org/Projects/GLib/CompilerRequirements">a compliant C toolchain</ulink>,
+      <application>Meson</application>, and <application>pkg-config</application>;
+      the requirements are the same when building from a Git repository clone
+      of GLib.
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
+          is a tool for tracking the compilation flags needed for
+          libraries that are used by the GLib library. (For each
+          library, a small <literal>.pc</literal> text file is
+          installed in a standard location that contains the compilation
+          flags needed for that library along with version number
+          information).
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      A UNIX build of GLib requires that the system implements at
+      least the original 1990 version of POSIX. Beyond this, it
+      depends on a number of other libraries.
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          The <ulink url="http://www.gnu.org/software/libiconv/">GNU
+          libiconv library</ulink> is needed to build GLib if your
+          system doesn't have the <function>iconv()</function>
+          function for doing conversion between character
+          encodings. Most modern systems should have
+          <function>iconv()</function>, however many older systems lack
+          an <function>iconv()</function> implementation. On such systems,
+          you must install the libiconv library. This can be found at:
+          <ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
+        </para>
+        <para>
+          If your system has an <function>iconv()</function> implementation but
+          you want to use libiconv instead, you can pass the
+          <option>-Diconv=gnu</option> option to <command>meson</command>. This
+          forces libiconv to be used.
+        </para>
+        <para>
+          Note that if you have libiconv installed in your default include
+          search path (for instance, in <filename>/usr/local/</filename>), but
+          don't enable it, you will get an error while compiling GLib because
+          the <filename>iconv.h</filename> that libiconv installs hides the
+          system iconv.
+        </para>
+        <para>
+          If you are using the native iconv implementation on Solaris
+          instead of libiconv, you'll need to make sure that you have
+          the converters between locale encodings and UTF-8 installed.
+          At a minimum you'll need the SUNWuiu8 package. You probably
+          should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
+          SUNWkiu8 packages.
+        </para>
+        <para>
+          The native iconv on Compaq Tru64 doesn't contain support for
+          UTF-8, so you'll need to use GNU libiconv instead. (When
+          using GNU libiconv for GLib, you'll need to use GNU libiconv
+          for GNU gettext as well.) This probably applies to related
+          operating systems as well.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Python 3.5 or newer is required. Your system Python must
+          conform to <ulink
+          url="https://www.python.org/dev/peps/pep-0394/">PEP 394
+          </ulink>
+          For FreeBSD, this means that the
+          <literal>lang/python3</literal> port must be installed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The libintl library from the <ulink
+          url="http://www.gnu.org/software/gettext">GNU gettext
+          package</ulink> is needed if your system doesn't have the
+          <function>gettext()</function> functionality for handling
+          message translation databases.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          A thread implementation is needed. The thread support in GLib
+          can be based upon POSIX threads or win32 threads.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
+          for regular expression matching. The system version of PCRE is used,
+          unless not available (which is the case on Android), in which case a
+          fallback subproject is used.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The optional extended attribute support in GIO requires the
+          <function>getxattr()</function> family of functions that may be
+          provided by the C library or by the standalone libattr library. To
+          build GLib without extended attribute support, use the
+          <option>-Dxattr=false</option> option.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The optional SELinux support in GIO requires libselinux.
+          To build GLib without SELinux support, use the
+          <option>-Dselinux=disabled</option> option.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The optional support for DTrace requires the
+          <filename>sys/sdt.h</filename> header, which is provided
+          by SystemTap on Linux. To build GLib without DTrace, use
+          the <option>-Ddtrace=false</option> option.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The optional support for
+          <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
+          can be disabled with the <option>-Dsystemtap=false</option>
+          option. Additionally, you can control the location
+          where GLib installs the SystemTap probes, using the
+          <option>-Dtapset_install_dir=DIR</option> option.
+        </para>
+      </listitem>
+    </itemizedlist>
+
+  </refsect1>
+  <refsect1 id="extra-configuration-options">
+    <title>Extra Configuration Options</title>
+
+    <para>
+      In addition to the normal options, these additional ones are supported
+      when configuring the GLib library:
+    </para>
+
+    <formalpara>
+      <title><option>--buildtype</option></title>
+
+      <para>
+        This is a standard <application>Meson</application> option which
+        specifies how much debugging and optimization to enable. If the build
+        type starts with <literal>debug</literal>,
+        <literal>G_ENABLE_DEBUG</literal> will be defined and GLib will be built
+        with additional debug code enabled.
+      </para>
+      <para>
+        If the build type is <literal>plain</literal>, GLib will not enable any
+        optimization or debug options by default, and will leave it entirely to
+        the user to choose their options. To build with the options recommended
+        by GLib developers, choose <literal>release</literal>.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dforce_posix_threads=true</option></title>
+
+      <para>
+        Normally, <application>Meson</application> should be able to work out
+        the correct thread implementation to use. This option forces POSIX
+        threads to be used even if the platform provides another threading API
+        (for example, on Windows).
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dbsymbolic_functions=false</option> and
+        <option>-Dbsymbolic_functions=true</option></title>
+
+      <para>
+        By default, GLib uses the <option>-Bsymbolic-functions</option>
+        linker flag to avoid intra-library PLT jumps. A side-effect
+        of this is that it is no longer possible to override
+        internal uses of GLib functions with
+        <envar>LD_PRELOAD</envar>. Therefore, it may make
+        sense to turn this feature off in some situations.
+        The <option>-Dbsymbolic_functions=false</option> option allows
+        to do that.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dgtk_doc=false</option> and
+        <option>-Dgtk_doc=true</option></title>
+
+      <para>
+        By default, GLib will detect whether the
+        <application>gtk-doc</application> package is installed.
+        If it is, then it will use it to extract and build the
+        documentation for the GLib library. These options
+        can be used to explicitly control whether
+        <application>gtk-doc</application> should be
+        used or not. If it is not used, the distributed,
+        pre-generated HTML files will be installed instead of
+        building them on your machine.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dman=false</option> and
+        <option>-Dman=true</option></title>
+
+      <para>
+        By default, GLib will detect whether <application>xsltproc</application>
+        and the necessary DocBook stylesheets are installed.
+        If they are, then it will use them to rebuild the included
+        man pages from the XML sources. These options can be used
+        to explicitly control whether man pages should be rebuilt
+        used or not. The distribution includes pre-generated man
+        pages.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dxattr=false</option> and
+        <option>-Dxattr=true</option></title>
+
+      <para>
+        By default, GLib will detect whether the
+        <function>getxattr()</function>
+        family of functions is available. If it is, then extended
+        attribute support will be included in GIO. These options can
+        be used to explicitly control whether extended attribute
+        support should be included or not. <function>getxattr()</function>
+        and friends can be provided by glibc or by the standalone
+        libattr library.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dselinux=auto</option>,
+        <option>-Dselinux=enabled</option> or
+        <option>-Dselinux=disabled</option></title>
+
+      <para>
+        By default, GLib will detect if libselinux is available and
+        include SELinux support in GIO if it is. These options can be
+        used to explicitly control whether SELinux support should
+        be included.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Ddtrace=false</option> and
+        <option>-Ddtrace=true</option></title>
+
+      <para>
+        By default, GLib will detect if DTrace support is available, and use it.
+        These options can be used to explicitly control whether DTrace support
+        is compiled into GLib.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Dsystemtap=false</option> and
+        <option>-Dsystemtap=true</option></title>
+
+      <para>
+        This option requires DTrace support. If it is available, then
+        GLib will also check for the presence of SystemTap.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Db_coverage=true</option> and
+        <option>-Db_coverage=false</option></title>
+
+      <para>
+        Enable the generation of coverage reports for the GLib tests.
+        This requires the lcov frontend to gcov from the
+        <ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
+        To generate a coverage report, use
+        <command>ninja coverage-html</command>. The report is placed in the
+        <filename>meson-logs</filename> directory.
+      </para>
+    </formalpara>
+
+    <formalpara>
+      <title><option>-Druntime_libdir=RELPATH</option></title>
+
+      <para>
+        Allows specifying a relative path to where to install the runtime
+        libraries (meaning library files used for running, not developing,
+        GLib applications). This can be used in operating system setups where
+        programs using GLib needs to run before e.g. <filename>/usr</filename>
+        is mounted.
+        For example, if <varname>LIBDIR</varname> is <filename>/usr/lib</filename> and
+        <filename>../../lib</filename> is passed to
+        <option>-Druntime_libdir</option> then the
+        runtime libraries are installed into <filename>/lib</filename> rather
+        than <filename>/usr/lib</filename>.
+      </para>
+    </formalpara>
+  </refsect1>
+
+</refentry>

docs/reference/glib/changes.xml

@@ -0,0 +1,174 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-changes" revision="17 Jan 2002">
+<refmeta>
+<refentrytitle>Changes to GLib</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Changes to GLib</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Changes to GLib</refname>
+<refpurpose>
+Incompatible changes made between successive versions of GLib
+</refpurpose>
+</refnamediv>
+
+
+<refsect1>
+<title>Incompatible changes from 2.0 to 2.2</title>
+
+<itemizedlist>
+
+<listitem>
+<para>
+GLib changed the seeding algorithm for the pseudo-random number
+generator Mersenne Twister, as used by <structname>GRand</structname>
+and <structname>GRandom</structname>. This was necessary, because some
+seeds would yield very bad pseudo-random streams. Also the
+pseudo-random integers generated by
+<function>g_rand*_int_range()</function> will have a
+slightly better equal distribution with the new version of GLib.
+</para>
+
+<para>
+Further information can be found at the website of the Mersenne
+Twister random number generator at <ulink
+url="http://www.math.keio.ac.jp/~matumoto/emt.html">http://www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
+</para> 
+
+<para>
+The original seeding and generation algorithms, as found in GLib
+2.0.x, can be used instead of the new ones by setting the environment
+variable <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use
+the GLib-2.0 algorithms only if you have sequences of numbers generated
+with Glib-2.0 that you need to reproduce exactly.  
+</para> 
+
+</listitem>
+
+</itemizedlist>
+
+</refsect1>
+
+<refsect1>
+<title>Incompatible changes from 1.2 to 2.0</title>
+
+<itemizedlist>
+
+<listitem>
+<para>
+The event loop functionality <structname>GMain</structname> has extensively 
+been revised to support multiple separate main loops in separate threads. 
+All sources (timeouts, idle functions, etc.) are associated with a 
+<structname>GMainContext</structname>.
+</para>
+
+<para>
+Compatibility functions exist so that most application code dealing with
+the main loop will continue to work. However, code that creates new custom 
+types of sources will require modification.
+</para>
+
+<para>
+The main changes here are:
+
+  <itemizedlist>
+
+  <listitem>
+  <para>
+   Sources are now exposed as <type>GSource *</type>, rather than simply as 
+   numeric ids.
+  </para>
+  </listitem>
+  
+  <listitem>
+  <para>
+   New types of sources are created by structure "derivation" from 
+   <structname>GSource</structname>, so the <literal>source_data</literal> 
+   parameter to the <structname>GSource</structname> virtual functions has been
+   replaced with a <type>GSource *</type>.
+  </para>
+  </listitem>
+  
+  <listitem>
+  <para>
+   Sources are first created, then later added to a specific 
+   <structname>GMainContext</structname>. 
+  </para>
+  </listitem>
+  
+  <listitem>
+  <para>
+   Dispatching has been modified so both the callback and data are passed
+   in to the <function>dispatch()</function> virtual function.
+  </para>
+  </listitem>
+
+  </itemizedlist>
+  To go along with this change, the vtable for 
+  <structname>GIOChannel</structname> has changed and
+  <function>add_watch()</function> has been replaced by 
+  <function>create_watch()</function>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+<function>g_list_foreach()</function> and 
+<function>g_slist_foreach()</function> have been changed so they
+are now safe against removal of the current item, not the next item.
+</para>
+
+<para>
+It's not recommended to mutate the list in the callback to these
+functions in any case.
+</para>
+</listitem>
+
+<listitem>
+<para>
+<structname>GDate</structname> now works in UTF-8, not in the current locale. 
+If you want to use it with the encoding of the locale, you need to convert 
+strings using <function>g_locale_to_utf8()</function> first.
+</para>
+</listitem>
+
+<listitem>
+<para>
+<function>g_strsplit()</function> has been fixed to:
+
+  <itemizedlist>
+  <listitem>
+  <para>
+   include trailing empty tokens, rather than stripping them
+  </para>
+  </listitem>
+  <listitem>
+  <para>
+   split into a maximum of <literal>max_tokens</literal> tokens, rather 
+   than <literal>max_tokens + 1</literal>
+  </para>
+  </listitem>
+  </itemizedlist>
+
+  Code depending on either of these bugs will need to be fixed.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Deprecated functions that got removed:
+<function>g_set_error_handler()</function>, 
+<function>g_set_warning_handler()</function>,
+<function>g_set_message_handler()</function>, use 
+<function>g_log_set_handler()</function> instead.
+</para>
+</listitem>
+</itemizedlist>
+
+</refsect1>
+
+</refentry>

docs/reference/glib/compiling.xml

@@ -0,0 +1,125 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-compiling" revision="17 Jan 2002">
+<refmeta>
+<refentrytitle>Compiling GLib Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GLib Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Compiling GLib Applications</refname>
+<refpurpose>
+How to compile your GLib application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Compiling GLib Applications on UNIX</title>
+
+<para>
+To compile a GLib application, you need to tell the compiler where to
+find the GLib header files and libraries. This is done with the
+<application>pkg-config</application> utility.
+</para>
+<para>
+The following interactive shell session demonstrates how
+<application>pkg-config</application> is used (the actual output on
+your system may be different):
+<programlisting>
+$ pkg-config --cflags glib-2.0
+ -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
+$ pkg-config --libs glib-2.0
+ -L/usr/lib -lm -lglib-2.0
+</programlisting>
+</para>
+<para>
+See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
+for more information about <application>pkg-config</application>.
+</para>
+<para>
+If your application uses or <structname>GObject</structname>
+features, it must be compiled and linked with the options returned
+by the following <application>pkg-config</application> invocation:
+<programlisting>
+$ pkg-config --cflags --libs gobject-2.0
+</programlisting>
+</para>
+<para>
+If your application uses modules, it must be compiled and linked
+with the options returned by one of the following
+<application>pkg-config</application> invocations:
+<programlisting>
+$ pkg-config --cflags --libs gmodule-no-export-2.0
+$ pkg-config --cflags --libs gmodule-2.0
+</programlisting>
+The difference between the two is that gmodule-2.0 adds
+<option>--export-dynamic</option> to the linker flags,
+which is often not needed.
+</para>
+<para>
+The simplest way to compile a program is to use command substitution
+feature of a shell. A command written in the format
+<literal>$(command)</literal> gets substituted into the command line
+before execution. So to compile a GLib Hello, World, you would type
+the following:
+<programlisting>
+$ cc hello.c $(pkg-config --cflags --libs glib-2.0) -o hello
+</programlisting>
+</para>
+<note><para>
+Note that the name of the file must come before the other options
+(such as <emphasis>pkg-config</emphasis>), or else you may get an
+error from the linker.
+</para></note>
+
+<para>
+Deprecated GLib functions are annotated to make the compiler
+emit warnings when they are used (e.g. with gcc, you need to use
+the -Wdeprecated-declarations option). If these warnings are
+problematic, they can be turned off by defining the preprocessor
+symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline
+option <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
+</para>
+
+<para>
+GLib deprecation annotations are versioned; by defining the
+macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED,
+you can specify the range of GLib versions whose API you want
+to use. APIs that were deprecated before or introduced after
+this range will trigger compiler warnings.
+</para>
+
+<para>
+Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
+entirely from the compiler by using the preprocessor symbol
+<literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
+are now handled using the above mechanism.
+</para>
+
+<para>
+The recommended way of using GLib has always been to only include the
+toplevel headers <filename>glib.h</filename>,
+<filename>glib-object.h</filename>, <filename>gio.h</filename>.
+Starting with 2.32, GLib enforces this by generating an error
+when individual headers are directly included.
+</para>
+
+<para>
+Still, there are some exceptions; these headers have to be included
+separately:
+<filename>gmodule.h</filename>,
+<filename>glib-unix.h</filename>,
+<filename>glib/gi18n-lib.h</filename> or
+<filename>glib/gi18n.h</filename> (see
+the <link linkend="glib-I18N">Internationalization section</link>),
+<filename>glib/gprintf.h</filename> and
+<filename>glib/gstdio.h</filename>
+(we don't want to pull in all of stdio).
+</para>
+
+</refsect1>
+
+</refentry>

docs/reference/glib/cross.xml

@@ -0,0 +1,147 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-cross-compiling" revision="7 Aug 2018">
+<refmeta>
+<refentrytitle>Cross-compiling the GLib package</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GLib Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Cross-compiling the GLib Package</refname>
+<refpurpose>
+How to cross-compile GLib
+</refpurpose>
+</refnamediv>
+
+    <refsect1 id="cross">
+      <title>Building the Library for a different architecture</title>
+      <para>
+        Cross-compilation is the process of compiling a program or
+        library on a different architecture or operating system then
+        it will be run upon. GLib is slightly more difficult to 
+        cross-compile than many packages because much of GLib is
+        about hiding differences between different systems. 
+      </para>
+      <para>
+        These notes cover things specific to cross-compiling GLib;
+        for general information about cross-compilation, see the
+        <ulink url="http://mesonbuild.com/Cross-compilation.html">meson</ulink>
+        info pages.
+      </para>
+      <para>
+        GLib tries to detect as much information as possible about
+        the target system by compiling and linking programs without
+        actually running anything; however, some information GLib
+        needs is not available this way. This information needs
+        to be provided to meson via a ‘cross file’.
+      </para>
+      <para>
+        As an example of using a cross file, to cross compile for
+        the ‘MingW32’ Win64 runtime environment on a Linux system,
+        create a file <filename>cross_file.txt</filename> with the following
+        contents:
+      </para>
+      <programlisting> 
+[host_machine]
+system = 'windows'
+cpu_family = 'x86_64'
+cpu = 'x86_64'
+endian = 'little'
+
+[properties]
+c_args = []
+c_link_args = []
+
+[binaries]
+c = 'x86_64-w64-mingw32-gcc'
+cpp = 'x86_64-w64-mingw32-g++'
+ar = 'x86_64-w64-mingw32-ar'
+ld = 'x86_64-w64-mingw32-ld'
+objcopy = 'x86_64-w64-mingw32-objcopy'
+strip = 'x86_64-w64-mingw32-strip'
+pkgconfig = 'x86_64-w64-mingw32-pkg-config'
+windres = 'x86_64-w64-mingw32-windres'
+      </programlisting>
+      <para>
+        Then execute the following commands:
+      </para>
+      <programlisting>
+meson --cross-file cross_file.txt builddir
+      </programlisting>
+      <para>
+        The complete list of cross properties follows. Most
+         of these won't need to be set in most cases.
+      </para>
+    </refsect1>
+    <refsect1 id="cross-properties">
+      <title>Cross properties</title>
+      <formalpara>
+        <title>have_[function]</title>
+
+        <para>
+           When meson checks if a function is supported, the test can be
+           overridden by setting the
+           <literal>have_<replaceable>function</replaceable></literal> property
+           to <constant>true</constant> or <constant>false</constant>.
+           For example <programlisting>Checking for function "fsync" : YES</programlisting>
+           can be overridden by setting <programlisting>have_fsync = false</programlisting>
+        </para>
+      </formalpara>
+      <formalpara>
+        <title>growing_stack=[true/false]</title>
+
+        <para>
+           Whether the stack grows up or down. Most places will want
+           <constant>false</constant>.
+           A few architectures, such as PA-RISC need <constant>true</constant>.
+        </para>
+      </formalpara>
+      <formalpara>
+         <title>have_strlcpy=[true/false]</title>
+
+         <para>
+            Whether you have <function>strlcpy()</function> that matches 
+            OpenBSD. Defaults to <constant>false</constant>, which is safe,
+            since GLib uses a built-in version in that case.
+	</para>
+      </formalpara>
+      <formalpara>
+         <title>va_val_copy=[true/false]</title>
+
+         <para>
+            Whether <type>va_list</type> can be copied as a pointer. If set 
+            to <constant>false</constant>, then <function>memcopy()</function>
+            will be used. Only matters if you don't have
+            <function>va_copy()</function> or <function>__va_copy()</function>.
+            (So, doesn't matter for GCC.)
+            Defaults to <constant>true</constant> which is slightly more common
+            than <constant>false</constant>.
+        </para>
+      </formalpara>
+      <formalpara>
+         <title>have_c99_vsnprintf=[true/false]</title>
+
+         <para>
+            Whether you have a <function>vsnprintf()</function> with C99 
+            semantics. (C99 semantics means returning the number of bytes 
+            that would have been written had the output buffer had enough 
+            space.) Defaults to <constant>false</constant>.
+         </para>
+      </formalpara>
+      <formalpara>
+         <title>have_c99_snprintf=[true/false]</title>
+
+         <para>
+            Whether you have a <function>snprintf()</function> with C99 
+            semantics. (C99 semantics means returning the number of bytes 
+            that would have been written had the output buffer had enough 
+            space.) Defaults to <constant>false</constant>.
+         </para>
+      </formalpara>
+
+    </refsect1>
+
+</refentry>

docs/reference/glib/glib-docs.xml

@@ -0,0 +1,302 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
+                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>GLib Reference Manual</title>
+    <releaseinfo>
+      for GLib &version;
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="https://developer.gnome.org/glib/unstable/">https://developer.gnome.org/glib/unstable/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter id="glib">
+    <title>GLib Overview</title>
+    <para>
+      GLib is a general-purpose utility library, which provides many useful
+      data types, macros, type conversions, string utilities, file utilities,
+      a mainloop abstraction, and so on. It works on many UNIX-like platforms,
+      as well as Windows and OS X. GLib is released under the GNU Lesser
+      General Public License (GNU LGPL).
+    </para>
+
+    <xi:include href="building.xml" />
+    <xi:include href="cross.xml" />
+    <xi:include href="programming.xml" />
+    <xi:include href="xml/compiling.xml" />
+    <xi:include href="running.xml" />
+    <xi:include href="changes.xml" />
+    <xi:include href="resources.xml" />
+
+  </chapter>
+
+  <chapter id="glib-fundamentals">
+    <title>GLib Fundamentals</title>
+    <xi:include href="xml/version.xml" />
+    <xi:include href="xml/types.xml" />
+    <xi:include href="xml/macros.xml" />
+    <xi:include href="xml/type_conversion.xml" />
+    <xi:include href="xml/byte_order.xml" />
+    <xi:include href="xml/checkedmath.xml" />
+    <xi:include href="xml/numerical.xml" />
+    <xi:include href="xml/macros_misc.xml" />
+    <xi:include href="xml/atomic_operations.xml" />
+  </chapter>
+
+  <chapter id="glib-core">
+    <title>GLib Core Application Support</title>
+    <xi:include href="xml/main.xml" />
+    <xi:include href="xml/threads.xml" />
+    <xi:include href="xml/thread_pools.xml" />
+    <xi:include href="xml/async_queues.xml" />
+    <xi:include href="xml/modules.xml" />
+    <xi:include href="xml/memory.xml" />
+    <xi:include href="xml/memory_slices.xml" />
+    <xi:include href="xml/iochannels.xml" />
+    <xi:include href="xml/error_reporting.xml" />
+    <xi:include href="xml/warnings.xml" />
+    <xi:include href="xml/messages.xml" />
+  </chapter>
+
+  <chapter id="glib-utilities">
+    <title>GLib Utilities</title>
+    <xi:include href="xml/string_utils.xml" />
+    <xi:include href="xml/conversions.xml" />
+    <xi:include href="xml/unicode.xml" />
+    <xi:include href="xml/base64.xml" />
+    <xi:include href="xml/checksum.xml" />
+    <xi:include href="xml/hmac.xml" />
+    <xi:include href="xml/i18n.xml" />
+    <xi:include href="xml/date.xml" />
+    <xi:include href="xml/timezone.xml" />
+    <xi:include href="xml/date-time.xml" />
+    <xi:include href="xml/random_numbers.xml" />
+    <xi:include href="xml/hooks.xml" />
+    <xi:include href="xml/misc_utils.xml" />
+    <xi:include href="xml/scanner.xml" />
+    <xi:include href="xml/timers.xml" />
+    <xi:include href="xml/spawn.xml" />
+    <xi:include href="xml/fileutils.xml" />
+    <xi:include href="xml/guri.xml" />
+    <xi:include href="xml/ghostutils.xml" />
+    <xi:include href="xml/shell.xml" />
+    <xi:include href="xml/option.xml" />
+    <xi:include href="xml/patterns.xml" />
+    <xi:include href="xml/gregex.xml" />
+    <xi:include href="regex-syntax.xml" />
+    <xi:include href="xml/markup.xml" />
+    <xi:include href="xml/keyfile.xml" />
+    <xi:include href="xml/bookmarkfile.xml" />
+    <xi:include href="xml/testing.xml" />
+    <xi:include href="xml/gunix.xml" />
+    <xi:include href="xml/windows.xml" />
+    <xi:include href="xml/uuid.xml" />
+  </chapter>
+
+  <chapter id="glib-data-types">
+    <title>GLib Data Types</title>
+    <xi:include href="xml/linked_lists_double.xml" />
+    <xi:include href="xml/linked_lists_single.xml" />
+    <xi:include href="xml/queue.xml" />
+    <xi:include href="xml/sequence.xml" />
+    <xi:include href="xml/trash_stack.xml" />
+    <xi:include href="xml/hash_tables.xml" />
+    <xi:include href="xml/strings.xml" />
+    <xi:include href="xml/string_chunks.xml" />
+    <xi:include href="xml/arrays.xml" />
+    <xi:include href="xml/arrays_pointer.xml" />
+    <xi:include href="xml/arrays_byte.xml" />
+    <xi:include href="xml/trees-binary.xml" />
+    <xi:include href="xml/trees-nary.xml" />
+    <xi:include href="xml/quarks.xml" />
+    <xi:include href="xml/datalist.xml" />
+    <xi:include href="xml/datasets.xml" />
+    <xi:include href="xml/gvarianttype.xml"/>
+    <xi:include href="xml/gvariant.xml"/>
+    <xi:include href="gvariant-varargs.xml"/>
+    <xi:include href="gvariant-text.xml"/>
+    <xi:include href="xml/refcount.xml"/>
+    <xi:include href="xml/rcbox.xml"/>
+    <xi:include href="xml/arcbox.xml"/>
+    <xi:include href="xml/refstring.xml"/>
+  </chapter>
+
+  <chapter id="deprecated">
+    <title>Deprecated APIs</title>
+    <xi:include href="xml/threads-deprecated.xml"/>
+    <xi:include href="xml/caches.xml" />
+    <xi:include href="xml/relations.xml" />
+    <xi:include href="xml/completion.xml" />
+  </chapter>
+
+  <chapter id="tools">
+    <title>GLib Tools</title>
+    <xi:include href="glib-gettextize.xml" />
+  </chapter>
+
+  <chapter id="deprecated-tools">
+    <title>Deprecated Tools</title>
+    <xi:include href="gtester.xml" />
+    <xi:include href="gtester-report.xml" />
+  </chapter>
+
+  <index id="api-index-full">
+    <title>Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-2" role="2.2">
+    <title>Index of new symbols in 2.2</title>
+    <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-4" role="2.4">
+    <title>Index of new symbols in 2.4</title>
+    <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-6" role="2.6">
+    <title>Index of new symbols in 2.6</title>
+    <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-8" role="2.8">
+    <title>Index of new symbols in 2.8</title>
+    <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-10" role="2.10">
+    <title>Index of new symbols in 2.10</title>
+    <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-12" role="2.12">
+    <title>Index of new symbols in 2.12</title>
+    <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-14" role="2.14">
+    <title>Index of new symbols in 2.14</title>
+    <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-16" role="2.16">
+    <title>Index of new symbols in 2.16</title>
+    <xi:include href="xml/api-index-2.16.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-18" role="2.18">
+    <title>Index of new symbols in 2.18</title>
+    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-20" role="2.20">
+    <title>Index of new symbols in 2.20</title>
+    <xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-22" role="2.22">
+    <title>Index of new symbols in 2.22</title>
+    <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-24" role="2.24">
+    <title>Index of new symbols in 2.24</title>
+    <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-26" role="2.26">
+    <title>Index of new symbols in 2.26</title>
+    <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-28" role="2.28">
+    <title>Index of new symbols in 2.28</title>
+    <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-30" role="2.30">
+    <title>Index of new symbols in 2.30</title>
+    <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-32" role="2.32">
+    <title>Index of new symbols in 2.32</title>
+    <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-34" role="2.34">
+    <title>Index of new symbols in 2.34</title>
+    <xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-36" role="2.36">
+    <title>Index of new symbols in 2.36</title>
+    <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-38" role="2.38">
+    <title>Index of new symbols in 2.38</title>
+    <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-40" role="2.40">
+    <title>Index of new symbols in 2.40</title>
+    <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-42" role="2.42">
+    <title>Index of new symbols in 2.42</title>
+    <xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-44" role="2.44">
+    <title>Index of new symbols in 2.44</title>
+    <xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-46" role="2.46">
+    <title>Index of new symbols in 2.46</title>
+    <xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-48" role="2.48">
+    <title>Index of new symbols in 2.48</title>
+    <xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-50" role="2.50">
+    <title>Index of new symbols in 2.50</title>
+    <xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-52" role="2.52">
+    <title>Index of new symbols in 2.52</title>
+    <xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-54" role="2.54">
+    <title>Index of new symbols in 2.54</title>
+    <xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-56" role="2.56">
+    <title>Index of new symbols in 2.56</title>
+    <xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-58" role="2.58">
+    <title>Index of new symbols in 2.58</title>
+    <xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-60" role="2.60">
+    <title>Index of new symbols in 2.60</title>
+    <xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-62" role="2.62">
+    <title>Index of new symbols in 2.62</title>
+    <xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-64" role="2.64">
+    <title>Index of new symbols in 2.64</title>
+    <xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-66" role="2.66">
+    <title>Index of new symbols in 2.66</title>
+    <xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-68" role="2.68">
+    <title>Index of new symbols in 2.68</title>
+    <xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-70" role="2.70">
+    <title>Index of new symbols in 2.70</title>
+    <xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-72" role="2.72">
+    <title>Index of new symbols in 2.72</title>
+    <xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+
+</book>

docs/reference/glib/glib-gettextize.xml

@@ -0,0 +1,88 @@
+<refentry id="glib-gettextize" lang="en">
+
+<refentryinfo>
+<title>glib-gettextize</title>
+<productname>GLib</productname>
+<authorgroup>
+<author>
+<contrib>Developer</contrib>
+<firstname>Owen</firstname>
+<surname>Taylor</surname>
+</author>
+</authorgroup>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle>glib-gettextize</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>glib-gettextize</refname>
+<refpurpose>gettext internationalization utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>glib-gettextize</command>
+<arg choice="opt" rep="repeat">OPTION</arg>
+<arg choice="opt">DIRECTORY</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>glib-gettextize</command> helps to prepare a source package for being
+internationalized through <application>gettext</application>. 
+It is a variant of the <command>gettextize</command> that ships with
+<application>gettext</application>. 
+</para>
+
+<para><command>glib-gettextize</command> differs
+from <command>gettextize</command> in that it doesn't create an
+<filename>intl/</filename> subdirectory and doesn't modify
+<filename>po/ChangeLog</filename> (note that newer versions of 
+<command>gettextize</command> behave like this when called with the
+<option>--no-changelog</option> option).
+</para>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>--help</option></term>
+<listitem><para>
+print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--version</option></term>
+<listitem><para>
+print version information and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-c</option>, <option>--copy</option></term>
+<listitem><para>
+copy files instead of making symlinks
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-f</option>, <option>--force</option></term>
+<listitem><para>
+force writing of new files even if old ones exist
+</para></listitem>
+</varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1><title>See also</title>
+<para>
+<citerefentry><refentrytitle>gettextize</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+</para>
+</refsect1>
+</refentry>

docs/reference/glib/glib-overrides.txt

@@ -0,0 +1,294 @@
+# This file makes most of the thread related macros look like
+# functions, which they really were, if possible easy.
+
+<MACRO>
+<NAME>GLIB_DISABLE_DEPRECATION_WARNINGS</NAME>
+#ifdef GLIB_DISABLE_DEPRECATION_WARNINGS
+</MACRO>
+
+<MACRO>
+<NAME>G_ATOMIC_LOCK_FREE</NAME>
+#define G_ATOMIC_LOCK_FREE
+</MACRO>
+
+# default thread implementation
+
+<MACRO>
+<NAME>G_THREADS_IMPL_POSIX</NAME>
+#define G_THREADS_IMPL_POSIX
+</MACRO>
+
+<MACRO>
+<NAME>G_THREADS_IMPL_WIN32</NAME>
+#define G_THREADS_IMPL_NONE
+</MACRO>
+
+# threads supported?
+
+<FUNCTION>
+<NAME>g_thread_supported</NAME>
+<RETURNS>gboolean</RETURNS>
+</FUNCTION>
+
+# GMutex
+
+<FUNCTION>
+<NAME>g_mutex_new</NAME>
+<RETURNS>GMutex *</RETURNS>
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_mutex_lock</NAME>
+<RETURNS>void</RETURNS>
+GMutex *mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_mutex_trylock</NAME>
+<RETURNS>gboolean</RETURNS>
+GMutex *mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_mutex_unlock</NAME>
+<RETURNS>void</RETURNS>
+GMutex *mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_mutex_free</NAME>
+<RETURNS>void</RETURNS>
+GMutex *mutex
+</FUNCTION>
+
+# GStaticMutex
+
+<STRUCT>
+<NAME>GStaticMutex</NAME>
+</STRUCT>
+
+<MACRO>
+<NAME>G_STATIC_MUTEX_INIT</NAME>
+#define G_STATIC_MUTEX_INIT
+</MACRO>
+
+<FUNCTION>
+<NAME>g_static_mutex_lock</NAME>
+<RETURNS>void</RETURNS>
+GStaticMutex* mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_static_mutex_trylock</NAME>
+<RETURNS>gboolean</RETURNS>
+GStaticMutex* mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_static_mutex_unlock</NAME>
+<RETURNS>void</RETURNS>
+GStaticMutex* mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_static_mutex_get_mutex</NAME>
+<RETURNS>GMutex *</RETURNS>
+GStaticMutex* mutex
+</FUNCTION>
+
+# GThread
+
+<FUNCTION>
+<NAME>g_thread_yield</NAME>
+<RETURNS>void</RETURNS>
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_thread_create</NAME>
+<RETURNS>GThread *</RETURNS>
+GThreadFunc func
+gpointer data,
+gboolean joinable,
+GError **error
+</FUNCTION>
+
+# G_LOCK_* macros
+
+<MACRO>
+<NAME>G_LOCK_DEFINE</NAME>
+#define G_LOCK_DEFINE(name)    
+</MACRO>
+
+<MACRO>
+<NAME>G_LOCK_DEFINE_STATIC</NAME>
+#define G_LOCK_DEFINE_STATIC(name)
+</MACRO>
+
+<MACRO>
+<NAME>G_LOCK_EXTERN</NAME>
+#define G_LOCK_EXTERN(name)    
+</MACRO>
+
+<MACRO>
+<NAME>G_LOCK</NAME>
+#define G_LOCK(name)
+</MACRO>
+
+<MACRO>
+<NAME>G_UNLOCK</NAME>
+#define G_UNLOCK(name)
+</MACRO>
+
+<MACRO>
+<NAME>G_TRYLOCK</NAME>
+#define G_TRYLOCK(name)
+</MACRO>
+
+# GCond
+
+<FUNCTION>
+<NAME>g_cond_new</NAME>
+<RETURNS>GCond*</RETURNS>
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_cond_signal</NAME>
+<RETURNS>void</RETURNS>
+GCond *cond
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_cond_broadcast</NAME>
+<RETURNS>void</RETURNS>
+GCond *cond
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_cond_wait</NAME>
+<RETURNS>void</RETURNS>
+GCond *cond, GMutex *mutex
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_cond_timed_wait</NAME>
+<RETURNS>gboolean</RETURNS>
+GCond *cond, GMutex *mutex, GTimeVal *abs_time
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_cond_free</NAME>
+<RETURNS>void</RETURNS>
+GCond *cond
+</FUNCTION>
+
+# GPrivate
+<MACRO>
+<NAME>G_PRIVATE_INIT</NAME>
+#define G_PRIVATE_INIT(notify)
+</MACRO>
+
+# GStaticPrivate
+
+<MACRO>
+<NAME>G_STATIC_PRIVATE_INIT</NAME>
+#define G_STATIC_PRIVATE_INIT 
+</MACRO>
+
+# Definitions for different operating systems
+
+<MACRO>
+<NAME>G_OS_UNIX</NAME>
+#define G_OS_UNIX
+</MACRO>
+
+<MACRO>
+<NAME>G_OS_WIN32</NAME>
+#define G_OS_WIN32
+</MACRO>
+
+# g_ascii_isxxx
+
+<FUNCTION>
+<NAME>g_ascii_isalnum</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isalpha</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_iscntrl</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isdigit</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isgraph</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_islower</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isprint</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_ispunct</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isspace</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isupper</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_ascii_isxdigit</NAME>
+<RETURNS>gboolean</RETURNS>
+gchar c
+</FUNCTION>
+
+# g_atomic
+
+<FUNCTION>
+<NAME>g_atomic_int_inc</NAME>
+<RETURNS>void</RETURNS>
+gint *atomic
+</FUNCTION>
+
+<FUNCTION>
+<NAME>g_atomic_int_dec_and_test</NAME>
+<RETURNS>gboolean</RETURNS>
+gint *atomic
+</FUNCTION>
+
+<MACRO>
+<NAME>G_VA_COPY</NAME>
+#define G_VA_COPY(ap1,ap2)    
+</MACRO>

docs/reference/glib/gtester-report.xml

@@ -0,0 +1,78 @@
+<refentry id="gtester-report">
+
+<refentryinfo>
+<title>gtester-report</title>
+<productname>GLib</productname>
+<authorgroup>
+<author>
+<contrib>Developer</contrib>
+<firstname>Tim</firstname>
+<surname>Janik</surname>
+</author>
+</authorgroup>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle>gtester-report</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>gtester-report</refname>
+<refpurpose>test report formatting utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gtester-report</command>
+<arg choice="opt" rep="repeat">option</arg>
+<arg>gtester-log</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gtester-report</command> is a script which converts
+the XML output generated by gtester into HTML.
+</para>
+<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
+TAP for reporting test results instead, and feed it to the test harness provided
+by your build system.</para>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+print version information and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-s</option>, <option>--subunit</option></term>
+<listitem><para>
+Output subunit. Needs python-subunit.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1><title>See also</title>
+<para>
+<citerefentry>
+<refentrytitle>gtester</refentrytitle>
+<manvolnum>1</manvolnum>
+</citerefentry>
+</para>
+</refsect1>
+</refentry>

docs/reference/glib/gtester.xml

@@ -0,0 +1,192 @@
+<refentry id="gtester">
+
+<refentryinfo>
+<title>gtester</title>
+<productname>GLib</productname>
+<authorgroup>
+<author>
+<contrib>Developer</contrib>
+<firstname>Tim</firstname>
+<surname>Janik</surname>
+</author>
+<author>
+<contrib>Developer</contrib>
+<firstname>Sven</firstname>
+<surname>Herzberg</surname>
+</author>
+</authorgroup>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle>gtester</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>gtester</refname>
+<refpurpose>test running utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gtester</command>
+<arg choice="opt" rep="repeat">OPTION</arg>
+<arg>testprogram</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gtester</command> is a utility to run unit tests that have
+been written using the GLib test framework.
+</para>
+<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
+TAP for reporting test results instead, and feed it to the test harness provided
+by your build system.</para>
+<para>
+When called with the <option>-o</option> option, <command>gtester</command>
+writes an XML report of the test results, which can be converted
+into HTML using the <command>gtester-report</command> utility.
+</para>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+print version information and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--g-fatal-warnings</option></term>
+<listitem><para>
+make warnings fatal
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-k</option>, <option>--keep-going</option></term>
+<listitem><para>
+continue running after tests failed
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-l</option></term>
+<listitem><para>
+list paths of available test cases
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-m=<replaceable>MODE</replaceable></option></term>
+<listitem><para>
+    run test cases in <replaceable>MODE</replaceable>, which can be one of:
+
+    <variablelist>
+      <varlistentry>
+      <term><option>perf</option></term>
+      <listitem><para>
+          run performance tests
+      </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term><option>slow</option>, <option>thorough</option></term>
+      <listitem><para>
+          run slow tests, or repeat non-deterministic tests more often
+      </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term><option>quick</option></term>
+      <listitem><para>
+          do not run slow or performance tests, or do extra repeats
+          of non-deterministic tests (default)
+      </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term><option>undefined</option></term>
+      <listitem><para>
+          run test cases that deliberately provoke checks or assertion
+          failures, if implemented (default)
+      </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+      <term><option>no-undefined</option></term>
+      <listitem><para>
+          do not run test cases that deliberately provoke checks or
+          assertion failures
+      </para></listitem>
+      </varlistentry>
+    </variablelist>
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-p=<replaceable>TESTPATH</replaceable></option></term>
+<listitem><para>
+only run test cases matching <replaceable>TESTPATH</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-s=<replaceable>TESTPATH</replaceable></option></term>
+<listitem><para>
+skip test cases matching <replaceable>TESTPATH</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--seed=<replaceable>SEEDSTRING</replaceable></option></term>
+<listitem><para>
+run all test cases with random number seed <replaceable>SEEDSTRING</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-o=<replaceable>LOGFILE</replaceable></option></term>
+<listitem><para>
+write the test log to <replaceable>LOGFILE</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-q</option>, <option>--quiet</option></term>
+<listitem><para>
+suppress per test binary output
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--verbose</option></term>
+<listitem><para>
+report success per testcase
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1><title>See also</title>
+<para>
+<citerefentry>
+<refentrytitle>gtester-report</refentrytitle>
+<manvolnum>1</manvolnum>
+</citerefentry>
+</para>
+</refsect1>
+</refentry>

docs/reference/glib/gvariant-text.xml

@@ -0,0 +1,622 @@
+<?xml version='1.0' encoding='utf-8'?>
+
+<refentry id='gvariant-text'>
+ <refmeta>
+  <refentrytitle>GVariant Text Format</refentrytitle>
+ </refmeta>
+ <refnamediv>
+  <refname>GVariant Text Format</refname>
+  <refpurpose>textual representation of GVariants</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+  <title>GVariant Text Format</title>
+
+  <para>
+   This page attempts to document the GVariant text format as produced by
+   <link linkend='g-variant-print'><function>g_variant_print()</function></link> and parsed by the
+   <link linkend='g-variant-parse'><function>g_variant_parse()</function></link> family of functions.  In most
+   cases the style closely resembles the formatting of literals in Python but there are some additions and
+   exceptions.
+  </para>
+
+  <para>
+   The functions that deal with GVariant text format absolutely always deal in utf-8.  Conceptually, GVariant
+   text format is a string of Unicode characters -- not bytes.  Non-ASCII but otherwise printable Unicode
+   characters are not treated any differently from normal ASCII characters.
+  </para>
+
+  <para>
+   The parser makes two passes.  The purpose of the first pass is to determine the type of the value being
+   parsed.  The second pass does the actual parsing.  Based on the fact that all elements in an array have to
+   have the same type, GVariant is able to make some deductions that would not otherwise be possible.  As an
+   example:
+
+   <informalexample><programlisting>[[1, 2, 3], [4, 5, 6]]</programlisting></informalexample>
+
+   is parsed as an array of arrays of integers (type '<literal>aai</literal>'), but
+
+   <informalexample><programlisting>[[1, 2, 3], [4, 5, 6.0]]</programlisting></informalexample>
+
+   is parsed as an array of arrays of doubles (type '<literal>aad</literal>').
+  </para>
+
+  <para>
+   As another example, GVariant is able to determine that
+
+   <informalexample><programlisting>["hello", nothing]</programlisting></informalexample>
+
+   is an array of maybe strings (type '<literal>ams</literal>').
+  </para>
+
+  <para>
+   What the parser accepts as valid input is dependent on context.  The API permits for out-of-band type
+   information to be supplied to the parser (which will change its behaviour).  This can be seen in the
+   GSettings and GDBus command line utilities where the type information is available from the schema or the
+   remote introspection information.  The additional information can cause parses to succeed when they would not
+   otherwise have been able to (by resolving ambiguous type information) or can cause them to fail (due to
+   conflicting type information).  Unless stated otherwise, the examples given in this section assume that no
+   out-of-band type data has been given to the parser.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Syntax Summary</title>
+
+  <para>
+   The following table describes the rough meaning of symbols that may appear inside GVariant text format.
+   Each symbol is described in detail in its own section, including usage examples.
+  </para>
+
+  <informaltable>
+   <tgroup cols='2'>
+    <colspec colname='col_0'/>
+    <colspec colname='col_1'/>
+    <tbody>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'>Symbol</emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+         <emphasis role='strong'>Meaning</emphasis>
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>true</literal></emphasis>,
+        <emphasis role='strong'><literal>false</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+         <link linkend='gvariant-text-booleans'>Booleans</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>""</literal></emphasis>,
+        <emphasis role='strong'><literal>''</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+         String literal.  See <link linkend='gvariant-text-strings'>Strings</link> below.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        numbers
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        See <link linkend='gvariant-text-numbers'>Numbers</link> below.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>()</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-tuples'>Tuples</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>[]</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-arrays'>Arrays</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>{}</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-dictionaries'>Dictionaries and Dictionary Entries</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>&lt;&gt;</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-variants'>Variants</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>just</literal></emphasis>,
+        <emphasis role='strong'><literal>nothing</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-maybe-types'>Maybe Types</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>@</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        type keywords
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <literal>boolean</literal>,
+        <literal>byte</literal>,
+        <literal>int16</literal>,
+        <literal>uint16</literal>,
+        <literal>int32</literal>,
+        <literal>uint32</literal>,
+        <literal>handle</literal>,
+        <literal>int64</literal>,
+        <literal>uint64</literal>,
+        <literal>double</literal>,
+        <literal>string</literal>,
+        <literal>objectpath</literal>,
+        <literal>signature</literal>
+       </para>
+       <para>
+        See <link linkend='gvariant-text-type-annotations'>Type Annotations</link> below.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>b""</literal></emphasis>,
+        <emphasis role='strong'><literal>b''</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-bytestrings'>Bytestrings</link>.
+       </para>
+      </entry>
+     </row>
+
+     <row rowsep='1'>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <emphasis role='strong'><literal>%</literal></emphasis>
+       </para>
+      </entry>
+      <entry colsep='1' rowsep='1'>
+       <para>
+        <link linkend='gvariant-text-positional'>Positional Parameters</link>.
+       </para>
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+
+  <refsect2 id='gvariant-text-booleans'>
+   <title>Booleans</title>
+   <para>
+    The strings <literal>true</literal> and <literal>false</literal> are parsed as booleans.  This is the only
+    way to specify a boolean value.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-strings'>
+   <title>Strings</title>
+   <para>
+    Strings literals must be quoted using <literal>""</literal> or <literal>''</literal>.  The two are
+    completely equivalent (except for the fact that each one is unable to contain itself unescaped).
+   </para>
+   <para>
+    Strings are Unicode strings with no particular encoding.  For example, to specify the character
+    <literal>é</literal>, you just write <literal>'é'</literal>.  You could also give the Unicode codepoint of
+    that character (U+E9) as the escape sequence <literal>'\u00e9'</literal>.  Since the strings are pure
+    Unicode, you should not attempt to encode the utf-8 byte sequence corresponding to the string using escapes;
+    it won't work and you'll end up with the individual characters corresponding to each byte.
+   </para>
+   <para>
+    Unicode escapes of the form <literal>\uxxxx</literal> and <literal>\Uxxxxxxxx</literal> are supported, in
+    hexadecimal.  The usual control sequence escapes <literal>\a</literal>, <literal>\b</literal>,
+    <literal>\f</literal>, <literal>\n</literal>, <literal>\r</literal>, <literal>\t</literal> and
+    <literal>\v</literal> are supported.  Additionally, a <literal>\</literal> before a newline character causes
+    the newline to be ignored.  Finally, any other character following <literal>\</literal> is copied literally
+    (for example, <literal>\"</literal> or <literal>\\</literal>) but for forwards compatibility with future
+    additions you should only use this feature when necessary for escaping backslashes or quotes.
+   </para>
+   <para>
+    The usual octal and hexadecimal escapes <literal>\0nnn</literal> and <literal>\xnn</literal> are not
+    supported here.  Those escapes are used to encode byte values and GVariant strings are Unicode.
+   </para>
+   <para>
+    Single-character strings are not interpreted as bytes.  Bytes must be specified by their numerical value.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-numbers'>
+   <title>Numbers</title>
+   <para>
+    Numbers are given by default as decimal values.  Octal and hex values can be given in the usual way (by
+    prefixing with <literal>0</literal> or <literal>0x</literal>).  Note that GVariant considers bytes to be
+    unsigned integers and will print them as a two digit hexadecimal number by default.
+   </para>
+   <para>
+    Floating point numbers can also be given in the usual ways, including scientific and hexadecimal notations.
+   </para>
+   <para>
+    For lack of additional information, integers will be parsed as int32 values by default.  If the number has a
+    point or an 'e' in it, then it will be parsed as a double precision floating point number by default.  If
+    type information is available (either explicitly or inferred) then that type will be used instead.
+   </para>
+   <para>
+    Some examples:
+   </para>
+   <para>
+    <literal>5</literal> parses as the int32 value five.
+   </para>
+   <para>
+    <literal>37.5</literal> parses as a floating point value.
+   </para>
+   <para>
+    <literal>3.75e1</literal> parses the same as the value above.
+   </para>
+   <para>
+    <literal>uint64 7</literal> parses seven as a uint64.
+    See <link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-tuples'>
+   <title>Tuples</title>
+   <para>
+    Tuples are formed using the same syntax as Python.  Here are some examples:
+   </para>
+   <para>
+    <literal>()</literal> parses as the empty tuple.
+   </para>
+   <para>
+    <literal>(5,)</literal> is a tuple containing a single value.
+   </para>
+   <para>
+    <literal>("hello", 42)</literal> is a pair.  Note that values of different types are permitted.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-arrays'>
+   <title>Arrays</title>
+   <para>
+    Arrays are formed using the same syntax as Python uses for lists (which is arguably the term that GVariant
+    should have used).  Note that, unlike Python lists, GVariant arrays are statically typed.  This has two
+    implications.
+   </para>
+   <para>
+    First, all items in the array must have the same type.  Second, the type of the array must be known, even in
+    the case that it is empty.  This means that (unless there is some other way to infer it) type information
+    will need to be given explicitly for empty arrays.
+   </para>
+   <para>
+    The parser is able to infer some types based on the fact that all items in an array must have the same type.
+    See the examples below:
+   </para>
+   <para>
+    <literal>[1]</literal> parses (without additional type information) as a one-item array of signed integers.
+   </para>
+   <para>
+    <literal>[1, 2, 3]</literal> parses (similarly) as a three-item array.
+   </para>
+   <para>
+    <literal>[1, 2, 3.0]</literal> parses as an array of doubles.  This is the most simple case of the type
+    inferencing in action.
+   </para>
+   <para>
+    <literal>[(1, 2), (3, 4.0)]</literal> causes the 2 to also be parsed as a double (but the 1 and 3 are still
+    integers).
+   </para>
+   <para>
+    <literal>["", nothing]</literal> parses as an array of maybe strings.  The presence of
+    "<literal>nothing</literal>" clearly implies that the array elements are nullable.
+   </para>
+   <para>
+    <literal>[[], [""]]</literal> will parse properly because the type of the first (empty) array can be
+    inferred to be equal to the type of the second array (both are arrays of strings).
+   </para>
+   <para>
+    <literal>[b'hello', []]</literal> looks odd but will parse properly.
+    See <link linkend='gvariant-text-bytestrings'>Bytestrings</link>
+   </para>
+   <para>
+    And some examples of errors:
+   </para>
+   <para>
+    <literal>["hello", 42]</literal> fails to parse due to conflicting types.
+   </para>
+   <para>
+    <literal>[]</literal> will fail to parse without additional type information.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-dictionaries'>
+   <title>Dictionaries and Dictionary Entries</title>
+   <para>
+    Dictionaries and dictionary entries are both specified using the <literal>{}</literal> characters.
+   </para>
+   <para>
+    The dictionary syntax is more commonly used.  This is what the printer elects to use in the normal case of
+    dictionary entries appearing in an array (aka "a dictionary").  The separate syntax for dictionary entries
+    is typically only used for when the entries appear on their own, outside of an array (which is valid but
+    unusual).  Of course, you are free to use the dictionary entry syntax within arrays but there is no good
+    reason to do so (and the printer itself will never do so).  Note that, as with arrays, the type of empty
+    dictionaries must be established (either explicitly or through inference).
+   </para>
+   <para>
+    The dictionary syntax is the same as Python's syntax for dictionaries.  Some examples:
+   </para>
+   <para>
+    <literal>@a{sv} {}</literal> parses as the empty dictionary of everyone's favourite type.
+   </para>
+   <para>
+    <literal>@a{sv} []</literal> is the same as above (owing to the fact that dictionaries are really arrays).
+   </para>
+   <para>
+    <literal>{1: "one", 2: "two", 3: "three"}</literal> parses as a dictionary mapping integers to strings.
+   </para>
+   <para>
+    The dictionary entry syntax looks just like a pair (2-tuple) that uses braces instead of parens.  The
+    presence of a comma immediately following the key differentiates it from the dictionary syntax (which
+    features a colon after the first key).  Some examples:
+   </para>
+   <para>
+    <literal>{1, "one"}</literal> is a free-standing dictionary entry that can be parsed on its own or as part
+    of another container value.
+   </para>
+   <para>
+    <literal>[{1, "one"}, {2, "two"}, {3, "three"}]</literal> is exactly equivalent to the dictionary example
+    given above.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-variants'>
+   <title>Variants</title>
+   <para>
+    Variants are denoted using angle brackets (aka "XML brackets"), <literal>&lt;&gt;</literal>.  They may not
+    be omitted.
+   </para>
+   <para>
+    Using <literal>&lt;&gt;</literal> effectively disrupts the type inferencing that occurs between array
+    elements.  This can have positive and negative effects.
+   </para>
+   <para>
+    <literal>[&lt;"hello"&gt;, &lt;42&gt;]</literal> will parse whereas <literal>["hello", 42]</literal> would
+    not.
+   </para>
+   <para>
+    <literal>[&lt;['']&gt;, &lt;[]&gt;]</literal> will fail to parse even though <literal>[[''], []]</literal>
+    parses successfully.  You would need to specify <literal>[&lt;['']&gt;, &lt;@as []&gt;]</literal>.
+   </para>
+   <para>
+    <literal>{"title": &lt;"frobit"&gt;, "enabled": &lt;true&gt;, "width": &lt;800&gt;}</literal> is an example of
+    perhaps the most pervasive use of both dictionaries and variants.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-maybe-types'>
+   <title>Maybe Types</title>
+   <para>
+    The syntax for specifying maybe types is inspired by Haskell.
+   </para>
+   <para>
+    The null case is specified using the keyword <literal>nothing</literal> and the non-null case is explicitly
+    specified using the keyword <literal>just</literal>.  GVariant allows <literal>just</literal> to be omitted
+    in every case that it is able to unambiguously determine the intention of the writer.  There are two cases
+    where it must be specified:
+   </para>
+   <itemizedlist>
+    <listitem>
+     <para>when using nested maybes, in order to specify the <literal>just nothing</literal> case</para>
+    </listitem>
+    <listitem>
+     <para>
+      to establish the nullability of the type of a value without explicitly specifying its full type
+     </para>
+    </listitem>
+   </itemizedlist>
+   <para>
+    Some examples:
+   </para>
+   <para>
+    <literal>just 'hello'</literal> parses as a non-null nullable string.
+   </para>
+   <para>
+    <literal>@ms 'hello'</literal> is the same (demonstrating how <literal>just</literal> can be dropped if the type is already
+    known).
+   </para>
+   <para>
+    <literal>nothing</literal> will not parse wtihout extra type information.
+   </para>
+   <para>
+    <literal>@ms nothing</literal> parses as a null nullable string.
+   </para>
+   <para>
+    <literal>[just 3, nothing]</literal> is an array of nullable integers
+   </para>
+   <para>
+    <literal>[3, nothing]</literal> is the same as the above (demonstrating another place were
+    <literal>just</literal> can be dropped).
+   </para>
+   <para>
+    <literal>[3, just nothing]</literal> parses as an array of maybe maybe integers (type
+    <literal>'ammi'</literal>).
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-type-annotations'>
+   <title>Type Annotations</title>
+   <para>
+    Type annotations allow additional type information to be given to the parser.  Depending on the context,
+    this type information can change the output of the parser, cause an error when parsing would otherwise have
+    succeeded or resolve an error when parsing would have otherwise failed.
+   </para>
+   <para>
+    Type annotations come in two forms: type codes and type keywords.
+   </para>
+   <para>
+    Type keywords can be seen as more verbose (and more legible) versions of a common subset of the type codes.
+    The type keywords <literal>boolean</literal>, <literal>byte</literal>, <literal>int16</literal>,
+    <literal>uint16</literal>, <literal>int32</literal>, <literal>uint32</literal>, <literal>handle</literal>,
+    <literal>int64</literal>, <literal>uint64</literal>, <literal>double</literal>, <literal>string</literal>,
+    <literal>objectpath</literal> and literal <literal>signature</literal> are each exactly equivalent to their
+    corresponding type code.
+   </para>
+   <para>
+    Type codes are an <literal>@</literal> ("at" sign) followed by a definite GVariant type string.  Some
+    examples:
+   </para>
+   <para>
+    <literal>uint32 5</literal> causes the number to be parsed unsigned instead of signed (the default).
+   </para>
+   <para>
+    <literal>@u 5</literal> is the same
+   </para>
+   <para>
+    <literal>objectpath "/org/gnome/xyz"</literal> creates an object path instead of a normal string
+   </para>
+   <para>
+    <literal>@au []</literal> specifies the type of the empty array (which would not parse otherwise)
+   </para>
+   <para>
+    <literal>@ms ""</literal> indicates that a string value is meant to have a maybe type
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-bytestrings'>
+   <title>Bytestrings</title>
+   <para>
+    The bytestring syntax is a piece of syntactic sugar meant to complement the bytestring APIs in GVariant.  It
+    constructs arrays of non-nul bytes (type '<literal>ay</literal>') with a nul terminator at the end. These are
+    normal C strings with no particular encoding enforced, so the bytes may not be valid UTF-8.
+    Bytestrings are a special case of byte arrays; byte arrays (also type '<literal>ay</literal>'), in the general
+    case, can contain nul at any position, and need not end with nul.
+   </para>
+   <para>
+    Bytestrings are specified with either <literal>b""</literal> or <literal>b''</literal>.  As with strings,
+    there is no fundamental difference between the two different types of quotes.
+   </para>
+   <para>
+    Bytestrings support the full range of escapes that you would expect (ie: those supported by
+    <link linkend='g-strcompress'><function>g_strcompress()</function></link>.  This includes the normal control
+    sequence escapes (as mentioned in the section on strings) as well as octal and hexadecimal escapes of the
+    forms <literal>\0nnn</literal> and <literal>\xnn</literal>.
+   </para>
+   <para>
+    <literal>b'abc'</literal> is equivalent to <literal>[byte 0x61, 0x62, 0x63, 0]</literal>.
+   </para>
+   <para>
+    When formatting arrays of bytes, the printer will choose to display the array as a bytestring if it contains
+    a nul character at the end and no other nul bytes within.  Otherwise, it is formatted as a normal array.
+   </para>
+  </refsect2>
+
+  <refsect2 id='gvariant-text-positional'>
+   <title>Positional Parameters</title>
+   <para>
+    Positional parameters are not a part of the normal GVariant text format, but they are mentioned here because
+    they can be used with <link linkend='g-variant-new-parsed'><function>g_variant_new_parsed()</function></link>.
+   </para>
+   <para>
+    A positional parameter is indicated with a <literal>%</literal> followed by any valid
+    <link linkend='gvariant-format-strings'>GVariant Format String</link>.  Variable arguments are collected as
+    specified by the format string and the resulting value is inserted at the current position.
+   </para>
+   <para>
+    This feature is best explained by example:
+   </para>
+   <informalexample><programlisting><![CDATA[char *t = "xyz";
+gboolean en = false;
+GVariant *value;
+
+value = g_variant_new_parsed ("{'title': <%s>, 'enabled': <%b>}", t, en);]]></programlisting></informalexample>
+   <para>
+    This constructs a dictionary mapping strings to variants (type '<literal>a{sv}</literal>') with two items in
+    it.  The key names are parsed from the string and the values for those keys are taken as variable arguments
+    parameters.
+   </para>
+   <para>
+    The arguments are always collected in the order that they appear in the string to be parsed.  Format strings
+    that collect multiple arguments are permitted, so you may require more varargs parameters than the number of
+    <literal>%</literal> signs that appear.  You can also give format strings that collect no arguments, but
+    there's no good reason to do so.
+   </para>
+  </refsect2>
+ </refsect1>
+</refentry>

docs/reference/glib/mainloop-states.eps

@@ -0,0 +1,306 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: mainloop-stages.eps
+%%Creator: fig2dev Version 3.2 Patchlevel 3c
+%%CreationDate: Wed Nov 29 12:23:52 2000
+%%For: otaylor@fresnel.labs.redhat.com (Owen Taylor)
+%%BoundingBox: 0 0 503 291
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 291 moveto 0 0 lineto 503 0 lineto 503 291 lineto closepath clip newpath
+-106.0 402.0 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+%%Page: 1 1
+10 setmiterlimit
+ 0.06000 0.06000 sc
+%
+% Fig objects follow
+%
+/Times-Roman ff 270.00 scf sf
+9300 6225 m
+gs 1 -1 sc (Initial[n+1]) dup sw pop 2 div neg 0 rm  col0 sh gr
+/Times-Roman ff 270.00 scf sf
+9300 6540 m
+gs 1 -1 sc (\(Recursion\)) dup sw pop 2 div neg 0 rm  col0 sh gr
+% Polyline
+15.000 slw
+ [60] 0 sd
+n 1905 6000 m 1800 6000 1800 6420 105 arcto 4 {pop} repeat
+  1800 6525 3120 6525 105 arcto 4 {pop} repeat
+  3225 6525 3225 6105 105 arcto 4 {pop} repeat
+  3225 6000 1905 6000 105 arcto 4 {pop} repeat
+ cp gs col0 s gr  [] 0 sd
+% Polyline
+ [60] 0 sd
+gs  clippath
+3865 5498 m 3806 5431 l 3688 5535 l 3808 5490 l 3747 5602 l cp
+3184 5976 m 3243 6043 l 3361 5939 l 3242 5985 l 3302 5872 l cp
+eoclip
+n 3225 6000 m
+ 3825 5475 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 3302 5872 m 3242 5985 l 3361 5939 l 3302 5872 l  cp gs 0.00 setgray ef gr  col0 s
+% arrowhead
+n 3747 5602 m 3808 5490 l 3688 5535 l 3747 5602 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+n 4980 5775 m 4875 5775 4875 6270 105 arcto 4 {pop} repeat
+  4875 6375 6870 6375 105 arcto 4 {pop} repeat
+  6975 6375 6975 5880 105 arcto 4 {pop} repeat
+  6975 5775 4980 5775 105 arcto 4 {pop} repeat
+ cp gs col0 s gr 
+% Polyline
+ [60] 0 sd
+gs  clippath
+8457 5969 m 8515 5900 l 8394 5799 l 8458 5911 l 8337 5868 l cp
+8042 5505 m 7984 5574 l 8105 5675 l 8042 5564 l 8162 5606 l cp
+eoclip
+n 8025 5550 m
+ 8475 5925 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 8162 5606 m 8042 5564 l 8105 5675 l 8162 5606 l  cp gs 0.00 setgray ef gr  col0 s
+% arrowhead
+n 8337 5868 m 8458 5911 l 8394 5799 l 8337 5868 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+ [60] 0 sd
+n 8580 5850 m 8475 5850 8475 6570 105 arcto 4 {pop} repeat
+  8475 6675 10020 6675 105 arcto 4 {pop} repeat
+  10125 6675 10125 5955 105 arcto 4 {pop} repeat
+  10125 5850 8580 5850 105 arcto 4 {pop} repeat
+ cp gs col0 s gr  [] 0 sd
+% Polyline
+n 7155 3825 m 7050 3825 7050 4320 105 arcto 4 {pop} repeat
+  7050 4425 9045 4425 105 arcto 4 {pop} repeat
+  9150 4425 9150 3930 105 arcto 4 {pop} repeat
+  9150 3825 7155 3825 105 arcto 4 {pop} repeat
+ cp gs col0 s gr 
+% Polyline
+n 5055 2100 m 4950 2100 4950 2595 105 arcto 4 {pop} repeat
+  4950 2700 6945 2700 105 arcto 4 {pop} repeat
+  7050 2700 7050 2205 105 arcto 4 {pop} repeat
+  7050 2100 5055 2100 105 arcto 4 {pop} repeat
+ cp gs col0 s gr 
+% Polyline
+n 2730 3900 m 2625 3900 2625 4395 105 arcto 4 {pop} repeat
+  2625 4500 4620 4500 105 arcto 4 {pop} repeat
+  4725 4500 4725 4005 105 arcto 4 {pop} repeat
+  4725 3900 2730 3900 105 arcto 4 {pop} repeat
+ cp gs col0 s gr 
+% Polyline
+ [60] 0 sd
+n 8580 1875 m 8475 1875 8475 2295 105 arcto 4 {pop} repeat
+  8475 2400 9645 2400 105 arcto 4 {pop} repeat
+  9750 2400 9750 1980 105 arcto 4 {pop} repeat
+  9750 1875 8580 1875 105 arcto 4 {pop} repeat
+ cp gs col0 s gr  [] 0 sd
+% Polyline
+ [60] 0 sd
+gs  clippath
+8518 2419 m 8451 2358 l 8345 2474 l 8460 2416 l 8412 2534 l cp
+8003 2848 m 8070 2909 l 8176 2793 l 8062 2852 l 8109 2733 l cp
+eoclip
+n 8047 2868 m
+ 8475 2400 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 8109 2733 m 8062 2852 l 8176 2793 l 8109 2733 l  cp gs 0.00 setgray ef gr  col0 s
+% arrowhead
+n 8412 2534 m 8460 2416 l 8345 2474 l 8412 2534 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+2 slj
+gs  clippath
+3340 4475 m 3252 4494 l 3286 4648 l 3305 4522 l 3374 4629 l cp
+eoclip
+n 4875 6075 m 4874 6075 l 4872 6074 l 4868 6073 l 4861 6072 l 4852 6070 l
+ 4839 6067 l 4824 6064 l 4805 6059 l 4783 6054 l 4759 6048 l
+ 4731 6041 l 4701 6033 l 4669 6025 l 4635 6015 l 4600 6004 l
+ 4563 5993 l 4526 5981 l 4487 5967 l 4448 5953 l 4408 5937 l
+ 4367 5920 l 4326 5901 l 4284 5881 l 4241 5859 l 4198 5835 l
+ 4154 5809 l 4109 5781 l 4063 5749 l 4016 5715 l 3968 5678 l
+ 3920 5638 l 3872 5595 l 3825 5550 l 3780 5503 l 3737 5455 l
+ 3697 5407 l 3660 5359 l 3626 5312 l 3594 5266 l 3566 5221 l
+ 3540 5177 l 3516 5134 l 3494 5091 l 3474 5049 l 3455 5008 l
+ 3438 4967 l 3422 4927 l 3408 4888 l 3394 4849 l 3382 4812 l
+ 3371 4775 l 3360 4740 l 3350 4706 l 3342 4674 l 3334 4644 l
+ 3327 4616 l 3321 4592 l 3316 4570 l 3311 4551 l 3308 4536 l
+ 3305 4523 l 3303 4514 l
+ 3300 4500 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 3374 4629 m 3305 4522 l 3286 4648 l 3374 4629 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+2 slj
+gs  clippath
+6943 6114 m 6978 6197 l 7123 6135 l 6995 6141 l 7087 6052 l cp
+eoclip
+n 8475 4500 m 8475 4501 l 8475 4503 l 8475 4508 l 8475 4515 l 8474 4525 l
+ 8474 4538 l 8473 4553 l 8472 4573 l 8470 4594 l 8468 4619 l
+ 8465 4646 l 8462 4675 l 8457 4706 l 8452 4739 l 8445 4773 l
+ 8437 4808 l 8427 4845 l 8416 4882 l 8403 4921 l 8388 4961 l
+ 8370 5002 l 8350 5045 l 8326 5090 l 8299 5137 l 8268 5186 l
+ 8232 5237 l 8192 5290 l 8148 5345 l 8100 5400 l 8057 5445 l
+ 8013 5490 l 7968 5533 l 7923 5573 l 7878 5612 l 7833 5649 l
+ 7789 5684 l 7745 5717 l 7701 5749 l 7658 5779 l 7615 5807 l
+ 7573 5834 l 7531 5861 l 7489 5886 l 7447 5910 l 7407 5933 l
+ 7366 5955 l 7327 5977 l 7288 5997 l 7250 6017 l 7214 6035 l
+ 7180 6052 l 7147 6068 l 7117 6083 l 7090 6096 l 7065 6108 l
+ 7043 6118 l 7025 6127 l 7010 6134 l 6998 6140 l 6989 6144 l
+
+ 6975 6150 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 7087 6052 m 6995 6141 l 7123 6135 l 7087 6052 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+2 slj
+gs  clippath
+8433 3848 m 8521 3831 l 8493 3676 l 8471 3803 l 8404 3693 l cp
+eoclip
+n 7050 2400 m 7051 2400 l 7054 2401 l 7058 2401 l 7066 2403 l 7076 2404 l
+ 7090 2407 l 7107 2410 l 7127 2414 l 7150 2418 l 7177 2424 l
+ 7206 2430 l 7238 2437 l 7271 2445 l 7306 2454 l 7343 2463 l
+ 7381 2474 l 7419 2486 l 7458 2499 l 7498 2513 l 7538 2528 l
+ 7579 2545 l 7621 2564 l 7663 2585 l 7706 2608 l 7750 2634 l
+ 7795 2662 l 7841 2694 l 7887 2728 l 7933 2766 l 7980 2807 l
+ 8025 2850 l 8068 2895 l 8109 2942 l 8147 2988 l 8181 3034 l
+ 8213 3080 l 8241 3125 l 8267 3169 l 8290 3212 l 8311 3254 l
+ 8330 3296 l 8347 3337 l 8362 3377 l 8376 3417 l 8389 3456 l
+ 8401 3494 l 8412 3532 l 8421 3569 l 8430 3604 l 8438 3637 l
+ 8445 3669 l 8451 3698 l 8457 3725 l 8461 3748 l 8465 3768 l
+ 8468 3785 l 8471 3799 l 8472 3809 l
+ 8475 3825 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 8404 3693 m 8471 3803 l 8493 3676 l 8404 3693 l  cp gs 0.00 setgray ef gr  col0 s
+% Polyline
+2 slj
+gs  clippath
+4970 2442 m 4959 2353 l 4803 2372 l 4928 2403 l 4814 2461 l cp
+eoclip
+n 3375 3900 m 3375 3899 l 3376 3897 l 3377 3892 l 3378 3886 l 3380 3876 l
+ 3383 3863 l 3386 3848 l 3391 3828 l 3396 3806 l 3402 3781 l
+ 3409 3753 l 3417 3722 l 3425 3689 l 3435 3655 l 3446 3619 l
+ 3457 3581 l 3469 3543 l 3483 3504 l 3497 3464 l 3513 3423 l
+ 3530 3383 l 3549 3341 l 3569 3299 l 3591 3257 l 3615 3214 l
+ 3641 3170 l 3669 3125 l 3701 3080 l 3735 3034 l 3772 2988 l
+ 3812 2941 l 3855 2895 l 3900 2850 l 3950 2804 l 4001 2762 l
+ 4052 2723 l 4102 2687 l 4152 2655 l 4201 2625 l 4248 2599 l
+ 4295 2576 l 4340 2555 l 4385 2536 l 4429 2519 l 4472 2504 l
+ 4515 2490 l 4557 2477 l 4598 2466 l 4638 2456 l 4677 2447 l
+ 4715 2439 l 4751 2432 l 4784 2426 l 4815 2420 l 4843 2415 l
+ 4868 2411 l 4890 2408 l 4908 2406 l 4922 2404 l 4933 2402 l
+
+ 4950 2400 l gs col0 s gr gr
+
+% arrowhead
+0 slj
+n 4814 2461 m 4928 2403 l 4803 2372 l 4814 2461 l  cp gs 0.00 setgray ef gr  col0 s
+/Times-Roman ff 360.00 scf sf
+5925 6225 m
+gs 1 -1 sc (Initial[n]) dup sw pop 2 div neg 0 rm  col0 sh gr
+/Times-Roman ff 360.00 scf sf
+8100 4275 m
+gs 1 -1 sc (Dispatching) dup sw pop 2 div neg 0 rm  col0 sh gr
+/Times-Roman ff 360.00 scf sf
+3675 4350 m
+gs 1 -1 sc (Prepared) dup sw pop 2 div neg 0 rm  col0 sh gr
+/Times-Roman ff 360.00 scf sf
+5925 2550 m
+gs 1 -1 sc (Polling) dup sw pop 2 div neg 0 rm  col0 sh gr
+/Times-Roman ff 270.00 scf sf
+4050 3300 m
+gs 1 -1 sc (query\(\)) col0 sh gr
+/Times-Roman ff 270.00 scf sf
+7800 3225 m
+gs 1 -1 sc (check\(\)) dup sw pop neg 0 rm  col0 sh gr
+/Times-Roman ff 270.00 scf sf
+2475 6375 m
+gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm  col0 sh gr
+/Times-Roman ff 270.00 scf sf
+3900 5400 m
+gs 1 -1 sc (prepare\(\)) col0 sh gr
+/Times-Roman ff 270.00 scf sf
+8025 5325 m
+gs 1 -1 sc (dispatch\(\)) dup sw pop neg 0 rm  col0 sh gr
+/Times-Roman ff 270.00 scf sf
+9150 2250 m
+gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm  col0 sh gr
+$F2psEnd
+rs

docs/reference/glib/mainloop-states.fig

@@ -0,0 +1,65 @@
+#FIG 3.2
+Landscape
+Center
+Inches
+Letter  
+100.00
+Single
+-2
+1200 2
+6 8625 6000 9975 6600
+4 1 0 50 0 0 18 0.0000 4 240 1290 9300 6225 Initial[n+1]\001
+4 1 0 50 0 0 18 0.0000 4 255 1335 9300 6540 (Recursion)\001
+-6
+2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
+	 3225 6525 3225 6000 1800 6000 1800 6525 3225 6525
+2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
+	1 1 2.00 90.00 120.00
+	1 1 2.00 90.00 120.00
+	 3225 6000 3825 5475
+2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 6975 6375 6975 5775 4875 5775 4875 6375 6975 6375
+2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
+	1 1 2.00 90.00 120.00
+	1 1 2.00 90.00 120.00
+	 8025 5550 8475 5925
+2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
+	 10125 6675 10125 5850 8475 5850 8475 6675 10125 6675
+2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 9150 4425 9150 3825 7050 3825 7050 4425 9150 4425
+2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 7050 2700 7050 2100 4950 2100 4950 2700 7050 2700
+2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
+	 4725 4500 4725 3900 2625 3900 2625 4500 4725 4500
+2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
+	 9750 2400 9750 1875 8475 1875 8475 2400 9750 2400
+2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
+	1 1 2.00 90.00 120.00
+	1 1 2.00 90.00 120.00
+	 8047 2868 8475 2400
+3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
+	1 1 2.00 90.00 120.00
+	 4875 6075 3825 5550 3300 4500
+	 0.000 -1.000 0.000
+3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
+	1 1 2.00 90.00 120.00
+	 8475 4500 8100 5400 6975 6150
+	 0.000 -1.000 0.000
+3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
+	1 1 2.00 90.00 120.00
+	 7050 2400 8025 2850 8475 3825
+	 0.000 -1.000 0.000
+3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
+	1 1 2.00 90.00 120.00
+	 3375 3900 3900 2850 4950 2400
+	 0.000 -1.000 0.000
+4 1 0 50 0 0 24 0.0000 4 315 1290 5925 6225 Initial[n]\001
+4 1 0 50 0 0 24 0.0000 4 330 1770 8100 4275 Dispatching\001
+4 1 0 50 0 0 24 0.0000 4 330 1320 3675 4350 Prepared\001
+4 1 0 50 0 0 24 0.0000 4 330 1050 5925 2550 Polling\001
+4 0 0 50 0 0 18 0.0000 4 255 825 4050 3300 query()\001
+4 2 0 50 0 0 18 0.0000 4 255 855 7800 3225 check()\001
+4 1 0 50 0 0 18 0.0000 4 255 990 2475 6375 Working\001
+4 0 0 50 0 0 18 0.0000 4 255 1050 3900 5400 prepare()\001
+4 2 0 50 0 0 18 0.0000 4 255 1140 8025 5325 dispatch()\001
+4 1 0 50 0 0 18 0.0000 4 255 990 9150 2250 Working\001

docs/reference/glib/meson.build

@@ -0,0 +1,104 @@
+if get_option('gtk_doc')
+  subdir('xml')
+
+  ignore_headers = [
+    'gallocator.h',
+    'gdatasetprivate.h',
+    'glibintl.h',
+    'gbsearcharray.h',
+    'glib-private.h',
+    'gmoduleconf.h',
+    'grcboxprivate.h',
+    'gstdioprivate.h',
+    'gthreadprivate.h',
+    'gunibreak.h',
+    'gunicomp.h',
+    'gunidecomp.h',
+    'gunichartables.h',
+    'glib_probes.h',
+    'glib_trace.h',
+    'libcharset.h',
+    'gdebug.h',
+    'gprintfint.h',
+    'gmirroringtable.h',
+    'gscripttable.h',
+    'gtrace-private.h',
+    'glib-mirroring-tab',
+    'gnulib',
+    'gbytesprivate.h',
+    'gvariant-internal.h',
+    'gvariant-serialiser.h',
+    'gvariant-core.h',
+    'gvarianttypeinfo.h',
+    'gwakeup.h',
+    'gtranslit-data.h',
+    'glib-init.h',
+    'gconstructor.h',
+    'valgrind.h',
+    'gutilsprivate.h',
+    'gvalgrind.h',
+    'dirent.h',
+  ]
+
+  docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
+  version_conf = configuration_data()
+  version_conf.set('GLIB_VERSION', meson.project_version())
+  configure_file(
+    input: 'version.xml.in',
+    output: 'version.xml',
+    configuration: version_conf
+  )
+
+  gnome.gtkdoc('glib',
+               main_xml : 'glib-docs.xml',
+               namespace : 'g',
+               mode : 'none',
+               src_dir : [ 'glib', 'gmodule' ],
+               dependencies : libglib_dep,
+               scan_args : gtkdoc_common_scan_args + [
+                 '--ignore-headers=' + ' '.join(ignore_headers),
+               ],
+               content_files : [
+                 'cross.xml',
+                 'running.xml',
+                 'building.xml',
+                 'changes.xml',
+                 'compiling.xml',
+                 'programming.xml',
+                 'resources.xml',
+                 'regex-syntax.xml',
+                 'glib-gettextize.xml',
+                 'gtester.xml',
+                 'gtester-report.xml',
+                 'gvariant-varargs.xml',
+                 'gvariant-text.xml',
+               ],
+               expand_content_files : [
+                 'compiling.xml',
+               ],
+               html_assets : [
+                 'file-name-encodings.png',
+                 'mainloop-states.gif',
+                 'Sorted_binary_tree_breadth-first_traversal.svg',
+                 'Sorted_binary_tree_inorder.svg',
+                 'Sorted_binary_tree_postorder.svg',
+                 'Sorted_binary_tree_preorder.svg',
+               ],
+               fixxref_args: [
+                 '--html-dir=' + docpath,
+               ],
+               install: true,
+               check: true)
+endif
+
+if get_option('man')
+  manpages = ['glib-gettextize', 'gtester', 'gtester-report']
+  foreach page : manpages
+    custom_target(page + '-man',
+      input: page + '.xml',
+      output: page + '.1',
+      command: xsltproc_command,
+      install: true,
+      install_dir: man1_dir)
+  endforeach
+endif

docs/reference/glib/programming.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-programming">
+<refmeta>
+<refentrytitle>Writing GLib Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GLib Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Writing GLib Applications</refname>
+<refpurpose>
+General considerations when programming with GLib
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Writing GLib Applications</title>
+
+<refsect2>
+<title>Threads</title>
+
+<para>
+The general policy of GLib is that all functions are invisibly threadsafe
+with the exception of data structure manipulation functions, where, if
+you have two threads manipulating the <emphasis>same</emphasis> data
+structure, they must use a lock to synchronize their operation.
+</para>
+
+<para>
+GLib creates a worker thread for its own purposes so GLib applications
+will always have at least 2 threads.
+</para>
+
+<para>
+See the sections on <link linkend="glib-Threads">threads</link> and
+<link linkend="glib-Thread-Pools">threadpools</link> for GLib APIs that
+support multithreaded applications.
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Security</title>
+
+<para>
+When writing code that runs with elevated privileges, it is important
+to follow some basic rules of secure programming. David Wheeler has an
+excellent book on this topic,
+<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
+</para>
+
+<para>
+When it comes to GLib and its associated libraries, GLib and
+GObject are generally fine to use in code that runs with elevated
+privileges; they don't load modules (executable code in shared objects)
+or run other programs 'behind your back'. GIO has to be used
+carefully in privileged programs, see the <ulink url="http://developer.gnome.org/gio/stable/ch02.html">GIO documentation</ulink> for details.
+</para>
+
+</refsect2>
+
+</refsect1>
+
+</refentry>

docs/reference/glib/resources.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-resources" revision="17 Jan 2002">
+<refmeta>
+<refentrytitle>Mailing lists and bug reports</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Mailing lists and bug reports</refname>
+<refpurpose>
+Getting help with GLib
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Filing a bug report or feature request</title>
+
+<para>
+If you encounter a bug, misfeature, or missing feature in GLib, please
+file a bug report on the issue tracker at
+<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
+We'd also appreciate reports of incomplete or misleading information in 
+the GLib documentation; file those with the ‘Documentation’ label.
+</para>
+
+<para>
+Don't hesitate to file a bug report, even if you think we may know
+about it already, or aren't sure of the details. Just give us as much
+information as you have, and if it's already fixed or has already been
+discussed, we'll add a note to that effect in the report.
+</para>
+
+<para>
+The issue tracker should definitely be used for feature requests, it's
+not only for bugs. We track all GLib development in GitLab, so it's
+the way to be sure the GLib developers won't forget about an issue.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Code Contributions</title>
+
+<para>
+If you develop a bugfix or enhancement for GLib, please open a merge request
+for that in GitLab as well. All branches must be offered under the terms of
+the GNU LGPL license, so be sure you  are authorized to give us the branch
+under those terms.
+</para>
+
+<para>
+If you want to discuss your branch before or after developing it, open a
+topic on <ulink url="https://discourse.gnome.org/tags/glib">Discourse</ulink>.
+But be sure to create the GitLab merge request as well; if the branch is only
+on the list and not in GitLab, it's likely to slip through the cracks.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>Discussions and user questions</title>
+
+<para>
+The <ulink url="https://gitlab.gnome.org/GNOME/glib/issues">GLib issue tracker</ulink>
+is meant for discussions with actionable topics. If you want to ask a question
+about using GLib, or discuss new features, you should use
+<ulink url="https://discourse.gnome.org/tags/glib">the glib tag on Discourse</ulink>.
+</para>
+
+</refsect1>
+
+
+</refentry>

docs/reference/glib/running.xml

@@ -0,0 +1,414 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<refentry id="glib-running">
+<refmeta>
+<refentrytitle>Running GLib Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GLib Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Running GLib Applications</refname>
+<refpurpose>
+How to run and debug your GLib application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Running and debugging GLib Applications</title>
+
+<refsect2>
+<title>Environment variables</title>
+
+<para>
+  The runtime behaviour of GLib applications can be influenced by a
+  number of environment variables.
+</para>
+
+<formalpara>
+  <title>Standard variables</title>
+
+  <para>
+    GLib reads standard environment variables like <envar>LANG</envar>,
+    <envar>PATH</envar>, <envar>HOME</envar>, <envar>TMPDIR</envar>,
+    <envar>TZ</envar> and <envar>LOGNAME</envar>.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title>XDG directories</title>
+
+  <para>
+    GLib consults the environment variables <envar>XDG_DATA_HOME</envar>,
+    <envar>XDG_DATA_DIRS</envar>, <envar>XDG_CONFIG_HOME</envar>,
+    <envar>XDG_CONFIG_DIRS</envar>, <envar>XDG_CACHE_HOME</envar> and
+    <envar>XDG_RUNTIME_DIR</envar> for the various XDG directories.
+    For more information, see the <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG basedir spec</ulink>.
+  </para>
+</formalpara>
+
+<formalpara id="G_FILENAME_ENCODING">
+  <title><envar>G_FILENAME_ENCODING</envar></title>
+
+  <para>
+    This environment variable can be set to a comma-separated list of character
+    set names. GLib assumes that filenames are encoded in the first character
+    set from that list rather than in UTF-8. The special token "@locale" can be
+    used to specify the character set for the current locale.
+  </para>
+</formalpara>
+
+<formalpara id="G_BROKEN_FILENAMES">
+  <title><envar>G_BROKEN_FILENAMES</envar></title>
+
+  <para>
+    If this environment variable is set, GLib assumes that filenames are in
+    the locale encoding rather than in UTF-8. G_FILENAME_ENCODING takes
+    priority over G_BROKEN_FILENAMES.
+  </para>
+</formalpara>
+
+<formalpara id="G_MESSAGES_PREFIXED">
+  <title><envar>G_MESSAGES_PREFIXED</envar></title>
+
+  <para>
+    A list of log levels for which messages should be prefixed by the
+    program name and PID of the application. The default is to prefix
+    everything except <literal>G_LOG_LEVEL_MESSAGE</literal> and
+    <literal>G_LOG_LEVEL_INFO</literal>.
+    The possible values are
+    <literal>error</literal>,
+    <literal>warning</literal>,
+    <literal>critical</literal>,
+    <literal>message</literal>,
+    <literal>info</literal> and
+    <literal>debug</literal>.
+    You can also use the special values
+    <literal>all</literal> and
+    <literal>help</literal>.
+  </para>
+  <para>
+    This environment variable only affects the default log handler,
+    g_log_default_handler().
+  </para>
+</formalpara>
+
+<formalpara id="G_MESSAGES_DEBUG">
+  <title><envar>G_MESSAGES_DEBUG</envar></title>
+
+  <para>
+    A space-separated list of log domains for which informational
+    and debug messages should be printed. By default, these
+    messages are not printed.
+  </para>
+  <para>
+    You can also use the special value <literal>all</literal>.
+  </para>
+  <para>
+    This environment variable only affects the default log handler,
+    g_log_default_handler().
+  </para>
+</formalpara>
+
+<formalpara id="G-DEBUG:CAPS">
+  <title><envar>G_DEBUG</envar></title>
+
+  <para>
+    This environment variable can be set to a list of debug options,
+    which cause GLib to print out different types of debugging information.
+    <variablelist>
+      <varlistentry>
+        <term>fatal-warnings</term>
+        <listitem><para>Causes GLib to abort the program at the first call
+           to g_warning() or g_critical().  Use of this flag is not
+           recommended except when debugging.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>fatal-criticals</term>
+        <listitem><para>Causes GLib to abort the program at the first call
+           to g_critical().  This flag can be useful during debugging and
+           testing.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>gc-friendly</term>
+        <listitem><para>Newly allocated memory that isn't directly initialized,
+          as well as memory being freed will be reset to 0. The point here is
+          to allow memory checkers and similar programs that use Boehm GC alike
+          algorithms to produce more accurate results.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>resident-modules</term>
+        <listitem><para>All modules loaded by GModule will be made resident.
+          This can be useful for tracking memory leaks in modules which are
+          later unloaded; but it can also hide bugs where code is accessed
+          after the module would have normally been unloaded.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>bind-now-modules</term>
+        <listitem><para>All modules loaded by GModule will bind their symbols
+          at load time, even when the code uses %G_MODULE_BIND_LAZY.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    The special value <literal>all</literal> can be used to turn on all debug options.
+    The special value <literal>help</literal> can be used to print all available options.
+  </para>
+</formalpara>
+
+<formalpara id="G_SLICE">
+  <title><envar>G_SLICE</envar></title>
+
+  <para>
+    This environment variable allows reconfiguration of the GSlice
+    memory allocator.
+    <variablelist>
+      <varlistentry>
+        <term>always-malloc</term>
+        <listitem><para>This will cause all slices allocated through
+          g_slice_alloc() and released by g_slice_free1() to be actually
+          allocated via direct calls to g_malloc() and g_free().
+          This is most useful for memory checkers and similar programs that
+          use Boehm GC alike algorithms to produce more accurate results.
+          It can also be in conjunction with debugging features of the system's
+          malloc() implementation such as glibc's MALLOC_CHECK_=2 to debug
+          erroneous slice allocation code, although
+          <literal>debug-blocks</literal> is usually a better suited debugging
+          tool.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>debug-blocks</term>
+        <listitem><para>Using this option (present since GLib 2.13) engages
+          extra code which performs sanity checks on the released memory
+          slices. Invalid slice addresses or slice sizes will be reported and
+          lead to a program halt. This option is for debugging scenarios.
+          In particular, client packages sporting their own test suite should
+          <emphasis>always enable this option when running tests</emphasis>.
+          Global slice validation is ensured by storing size and address
+          information for each allocated chunk, and maintaining a global
+          hash table of that data. That way, multi-thread scalability is
+          given up, and memory consumption is increased. However, the
+          resulting code usually performs acceptably well, possibly better
+          than with comparable memory checking carried out using external
+          tools.</para>
+          <para>An example of a memory corruption scenario that cannot be
+          reproduced with <literal>G_SLICE=always-malloc</literal>, but will
+          be caught by <literal>G_SLICE=debug-blocks</literal> is as follows:
+          <programlisting>
+            /* void* gives up type-safety */
+            void *slist = g_slist_alloc ();
+
+            /* corruption: sizeof (GSList) != sizeof (GList) */
+            g_list_free (slist);
+          </programlisting></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    The special value <literal>all</literal> can be used to turn on all options.
+    The special value <literal>help</literal> can be used to print all available options.
+  </para>
+</formalpara>
+
+<formalpara id="G_RANDOM_VERSION">
+  <title><envar>G_RANDOM_VERSION</envar></title>
+
+  <para>
+    If this environment variable is set to '2.0', the outdated
+    pseudo-random number seeding and generation algorithms from
+    GLib 2.0 are used instead of the newer, better ones. You should
+    only set this variable if you have sequences of numbers that were
+    generated with Glib 2.0 that you need to reproduce exactly.
+  </para>
+</formalpara>
+
+<formalpara id="LIBCHARSET_ALIAS_DIR">
+  <title><envar>LIBCHARSET_ALIAS_DIR</envar></title>
+
+  <para>
+    Allows to specify a nonstandard location for the
+    <filename>charset.aliases</filename> file that is used by the
+    character set conversion routines. The default location is the
+    <replaceable>libdir</replaceable> specified at compilation time.
+  </para>
+</formalpara>
+
+<formalpara id="TZDIR">
+  <title><envar>TZDIR</envar></title>
+
+  <para>
+    Allows to specify a nonstandard location for the timezone data files
+    that are used by the #GDateTime API. The default location is under
+    <filename>/usr/share/zoneinfo</filename>. For more information,
+    also look at the <command>tzset</command> manual page.
+  </para>
+</formalpara>
+
+<formalpara id="G_ENABLE_DIAGNOSTIC">
+  <title><envar>G_ENABLE_DIAGNOSTIC</envar></title>
+
+  <para>
+    If set to a non-zero value, this environment variable enables
+    diagnostic messages, like deprecation messages for GObject properties
+    and signals.
+  </para>
+</formalpara>
+
+<formalpara id="G_DEBUGGER">
+  <title><envar>G_DEBUGGER</envar></title>
+
+  <para>
+    When running on Windows, if set to a non-empty string, GLib will
+    try to interpret the contents of this environment variable as
+    a command line to a debugger, and run it if the process crashes.
+    The debugger command line should contain <literal>%p</literal> and <literal>%e</literal> substitution
+    tokens, which GLib will replace with the process ID of the crashing
+    process and a handle to an event that the debugger should signal
+    to let GLib know that the debugger successfully attached to the
+    process. If <literal>%e</literal> is absent, or if the debugger is not able to
+    signal events, GLib will resume execution after 60 seconds.
+    If <literal>%p</literal> is absent, the debugger won't know which process to attach to,
+    and GLib will also resume execution after 60 seconds.
+  </para>
+  <para>
+    Additionally, even if <envar>G_DEBUGGER</envar> is not set, GLib would still
+    try to print basic exception information (code and address) into
+    stderr.
+  </para>
+  <para>
+    By default the debugger gets a new console allocated for it.
+    Set the <envar>G_DEBUGGER_OLD_CONSOLE</envar> environment variable to any
+    non-empty string to make the debugger inherit the console of
+    the crashing process. Normally this is only used by the GLib
+    testsuite.
+  </para>
+  <para>
+    The exception handler is written with the aim of making it as
+    simple as possible, to minimize the risk of it invoking
+    buggy functions or running buggy code, which would result
+    in exceptions being raised recursively. Because of that
+    it lacks most of the amenities that one would expect of GLib.
+    Namely, it does not support Unicode, so it is highly advisable
+    to only use ASCII characters in <envar>G_DEBUGGER</envar>.
+  </para>
+  <para>
+    See also <link linkend="G_VEH_CATCH"><envar>G_VEH_CATCH</envar></link>.
+  </para>
+</formalpara>
+
+<formalpara id="G_VEH_CATCH">
+  <title><envar>G_VEH_CATCH</envar></title>
+
+  <para>
+    Catching some exceptions can break the program, since Windows
+    will sometimes use exceptions for execution flow control and
+    other purposes other than signalling a crash.
+  </para>
+  <para>
+    The <envar>G_VEH_CATCH</envar> environment variable augments
+    <ulink url="https://docs.microsoft.com/en-us/windows/desktop/debug/vectored-exception-handling">Vectored Exception Handling</ulink>
+    on Windows (see <link linkend="G_DEBUGGER"><envar>G_DEBUGGER</envar></link>), allowing GLib to catch more
+    exceptions. Set this variable to a comma-separated list of
+    hexadecimal exception codes that should additionally be caught.
+  </para>
+  <para>
+    By default GLib will only catch Access Violation, Stack Overflow and
+    Illegal Instruction <ulink url="https://docs.microsoft.com/en-us/windows/desktop/api/winnt/ns-winnt-_exception_record">exceptions</ulink>.
+  </para>
+</formalpara>
+
+</refsect2>
+
+<refsect2 id="setlocale">
+<title>Locale</title>
+
+<para>
+A number of interfaces in GLib depend on the current locale in which
+an application is running. Therefore, most GLib-using applications should
+call <function>setlocale (LC_ALL, "")</function> to set up the current
+locale.
+</para>
+
+<para>
+On Windows, in a C program there are several locale concepts
+that not necessarily are synchronized. On one hand, there is the
+system default ANSI code-page, which determines what encoding is used
+for file names handled by the C library's functions and the Win32
+API. (We are talking about the "narrow" functions here that take
+character pointers, not the "wide" ones.)
+</para>
+
+<para>
+On the other hand, there is the C library's current locale. The
+character set (code-page) used by that is not necessarily the same as
+the system default ANSI code-page. Strings in this character set are
+returned by functions like <function>strftime()</function>.
+</para>
+
+</refsect2>
+
+<para>
+GLib ships with a set of Python macros for the GDB debugger. These includes pretty
+printers for lists, hashtables and GObject types. It also has a backtrace filter
+that makes backtraces with signal emissions easier to read.
+</para>
+
+<para>
+To use this you need a version of GDB that supports Python scripting; anything
+from 7.0 should be fine. You then need to install GLib in the same prefix as
+GDB so that the Python GDB autoloaded files get installed in the right place
+for GDB to pick up.
+</para>
+
+<para>
+General pretty printing should just happen without having to do anything special.
+To get the signal emission filtered backtrace you must use the "new-backtrace" command
+instead of the standard one.
+</para>
+
+<para>
+There is also a new command called gforeach that can be used to apply a command
+on each item in a list. E.g. you can do
+<programlisting>
+gforeach i in some_list_variable: print *(GtkWidget *)l
+</programlisting>
+Which would print the contents of each widget in a list of widgets.
+</para>
+
+<refsect2>
+<title>SystemTap</title>
+
+<para>
+<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> is a dynamic whole-system
+analysis toolkit.  GLib ships with a file <filename>libglib-2.0.so.*.stp</filename> which defines a
+set of probe points, which you can hook into with custom SystemTap scripts.
+See the files <filename>libglib-2.0.so.*.stp</filename>, <filename>libgobject-2.0.so.*.stp</filename>
+and <filename>libgio-2.0.so.*.stp</filename> which
+are in your shared SystemTap scripts directory.
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Memory statistics</title>
+
+<para>
+g_mem_profile() will output a summary g_malloc() memory usage, if memory
+profiling has been enabled by calling
+<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup.
+</para>
+
+<para>
+If GLib has been configured with <option>--enable-debug=yes</option>,
+then g_slice_debug_tree_statistics() can be called in a debugger to
+output details about the memory usage of the slice allocator.
+</para>
+
+</refsect2>
+</refsect1>
+</refentry>

docs/reference/glib/version.xml.in

@@ -0,0 +1 @@
+@GLIB_VERSION@

docs/reference/glib/xml/gtkdocentities.ent.in

@@ -0,0 +1,8 @@
+<!ENTITY package "@PACKAGE@">
+<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
+<!ENTITY package_name "@PACKAGE_NAME@">
+<!ENTITY package_string "@PACKAGE_STRING@">
+<!ENTITY package_tarname "@PACKAGE_TARNAME@">
+<!ENTITY package_url "@PACKAGE_URL@">
+<!ENTITY package_version "@PACKAGE_VERSION@">
+<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

docs/reference/glib/xml/meson.build

@@ -0,0 +1,14 @@
+ent_conf = configuration_data()
+ent_conf.set('PACKAGE', 'glib')
+ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/glib/issues/new')
+ent_conf.set('PACKAGE_NAME', 'glib')
+ent_conf.set('PACKAGE_STRING', 'glib')
+ent_conf.set('PACKAGE_TARNAME', 'glib')
+ent_conf.set('PACKAGE_URL', 'FIXME')
+ent_conf.set('PACKAGE_VERSION', glib_version)
+ent_conf.set('PACKAGE_API_VERSION', glib_api_version)
+configure_file(
+  input: 'gtkdocentities.ent.in',
+  output: 'gtkdocentities.ent',
+  configuration: ent_conf
+)

docs/reference/gobject/glib-genmarshal.xml

@@ -0,0 +1,579 @@
+<refentry id="glib-genmarshal" lang="en">
+
+<refentryinfo>
+  <title>glib-genmarshal</title>
+  <productname>GObject</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Emmanuele</firstname>
+      <surname>Bassi</surname>
+    </author>
+    <author>
+      <contrib>Original developer</contrib>
+      <firstname>Tim</firstname>
+      <surname>Janik</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle>glib-genmarshal</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>glib-genmarshal</refname>
+<refpurpose>C code marshaller generation utility for GLib closures</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>glib-genmarshal</command>
+<arg choice="opt" rep="repeat">OPTION</arg>
+<arg choice="opt" rep="repeat">FILE</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>glib-genmarshal</command> is a small utility that generates C code
+marshallers for callback functions of the GClosure mechanism in the GObject
+sublibrary of GLib. The marshaller functions have a standard signature,
+they get passed in the invoking closure, an array of value structures holding
+the callback function parameters and a value structure for the return value
+of the callback. The marshaller is then responsible to call the respective C
+code function of the closure with all the parameters on the stack and to
+collect its return value.
+</para>
+
+<para><command>glib-genmarshal</command> takes a list of marshallers to generate as
+input. The marshaller list is either read from files passed as additional arguments
+on the command line; or from standard input, by using <literal>-</literal> as the
+input file.
+</para>
+
+<refsect2><title>Marshaller list format</title>
+<para>
+The marshaller lists are processed line by line, a line can contain a
+comment in the form of
+<informalexample><programlisting>
+# this is a comment
+</programlisting></informalexample>
+or a marshaller specification of the form
+<programlisting>
+<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>
+<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
+<replaceable>RTYPE</replaceable>:<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>,<replaceable>PTYPE</replaceable>
+</programlisting>
+</para>
+<para>
+The <replaceable>RTYPE</replaceable> part specifies the callback's return
+type and the <replaceable>PTYPE</replaceable>s right to the colon specify
+the callback's parameter list, except for the first and the last arguments
+which are always pointers.
+</para>
+</refsect2>
+<refsect2><title>Parameter types</title>
+<para>
+Currently, the following types are supported:
+<variablelist>
+<varlistentry>
+<term><replaceable>VOID</replaceable></term>
+<listitem><para>
+indicates no return type, or no extra parameters.
+If <replaceable>VOID</replaceable> is used as the parameter list, no
+additional parameters may be present.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>BOOLEAN</replaceable></term>
+<listitem><para>
+for boolean types (gboolean)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>CHAR</replaceable></term>
+<listitem><para>
+for signed char types (gchar)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>UCHAR</replaceable></term>
+<listitem><para>
+for unsigned char types (guchar)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>INT</replaceable></term>
+<listitem><para>
+for signed integer types (gint)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>UINT</replaceable></term>
+<listitem><para>
+for unsigned integer types (guint)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>LONG</replaceable></term>
+<listitem><para>
+for signed long integer types (glong)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>ULONG</replaceable></term>
+<listitem><para>
+for unsigned long integer types (gulong)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>INT64</replaceable></term>
+<listitem><para>
+for signed 64bit integer types (gint64)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>UINT64</replaceable></term>
+<listitem><para>
+for unsigned 64bit integer types (guint64)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>ENUM</replaceable></term>
+<listitem><para>
+for enumeration types (gint)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>FLAGS</replaceable></term>
+<listitem><para>
+for flag enumeration types (guint)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>FLOAT</replaceable></term>
+<listitem><para>
+for single-precision float types (gfloat)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>DOUBLE</replaceable></term>
+<listitem><para>
+for double-precision float types (gdouble)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>STRING</replaceable></term>
+<listitem><para>
+for string types (gchar*)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>BOXED</replaceable></term>
+<listitem><para>
+for boxed (anonymous but reference counted) types (GBoxed*)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>PARAM</replaceable></term>
+<listitem><para>
+for GParamSpec or derived types (GParamSpec*)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>POINTER</replaceable></term>
+<listitem><para>
+for anonymous pointer types (gpointer)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>OBJECT</replaceable></term>
+<listitem><para>
+for GObject or derived types (GObject*)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>VARIANT</replaceable></term>
+<listitem><para>
+for GVariant types (GVariant*)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>NONE</replaceable></term>
+<listitem><para>
+deprecated alias for <replaceable>VOID</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><replaceable>BOOL</replaceable></term>
+<listitem><para>
+deprecated alias for <replaceable>BOOLEAN</replaceable>
+</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</refsect2>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>--header</option></term>
+<listitem><para>
+Generate header file contents of the marshallers. This option is mutually
+exclusive with the <option>--body</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--body</option></term>
+<listitem><para>
+Generate C code file contents of the marshallers. This option is mutually
+exclusive with the <option>--header</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--prefix=<replaceable>PREFIX</replaceable></option></term>
+<listitem><para>
+Specify marshaller prefix. The default prefix is <literal>`g_cclosure_user_marshal'</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--skip-source</option></term>
+<listitem><para>
+Skip source location remarks in generated comments.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--stdinc</option></term>
+<listitem><para>
+Use the standard marshallers of the GObject library, and include
+<filename>glib-object.h</filename> in generated header files. This
+option is mutually exclusive with the <option>--nostdinc</option>
+option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--nostdinc</option></term>
+<listitem><para>
+Do not use the standard marshallers of the GObject library, and skip
+<filename>glib-object.h</filename> include directive in generated header files.
+This option is mutually exclusive with the <option>--stdinc</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--internal</option></term>
+<listitem><para>
+Mark generated functions as internal, using <literal>G_GNUC_INTERNAL</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--valist-marshallers</option></term>
+<listitem><para>
+Generate valist marshallers, for use with <function>g_signal_set_va_marshaller()</function>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+Print version information.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--g-fatal-warnings</option></term>
+<listitem><para>
+Make warnings fatal, that is, exit immediately once a warning occurs.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Print brief help and exit.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+Print version and exit.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--output=FILE</option></term>
+<listitem><para>
+Write output to <replaceable>FILE</replaceable> instead of the standard output.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--prototypes</option></term>
+<listitem><para>
+Generate function prototypes before the function definition in the C source
+file, in order to avoid a <literal>missing-prototypes</literal> compiler
+warning. This option is only useful when using the <option>--body</option>
+option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--pragma-once</option></term>
+<listitem><para>
+Use the <literal>once</literal> pragma instead of an old style header guard
+when generating the C header file. This option is only useful when using the
+<option>--header</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--include-header=<replaceable>HEADER</replaceable></option></term>
+<listitem><para>
+Adds a <literal>#include</literal> directive for the given file in the C
+source file. This option is only useful when using the <option>--body</option>
+option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-D <replaceable>SYMBOL[=VALUE]</replaceable></option></term>
+<listitem><para>
+Adds a <literal>#define</literal> C pre-processor directive for
+<replaceable>SYMBOL</replaceable> and its given <replaceable>VALUE</replaceable>,
+or "1" if the value is unset. You can use this option multiple times; if you do,
+all the symbols will be defined in the same order given on the command line, before
+the symbols undefined using the <option>-U</option> option. This option is only
+useful when using the <option>--body</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-U <replaceable>SYMBOL</replaceable></option></term>
+<listitem><para>
+Adds a <literal>#undef</literal> C pre-processor directive to undefine the
+given <replaceable>SYMBOL</replaceable>. You can use this option multiple times;
+if you do, all the symbols will be undefined in the same order given on the
+command line, after the symbols defined using the <option>-D</option> option.
+This option is only useful when using the <option>--body</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--quiet</option></term>
+<listitem><para>
+Minimizes the output of <command>glib-genmarshal</command>, by printing only
+warnings and errors. This option is mutually exclusive with the
+<option>--verbose</option> option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--verbose</option></term>
+<listitem><para>
+Increases the verbosity of <command>glib-genmarshal</command>, by printing
+debugging information. This option is mutually exclusive with the
+<option>--quiet</option> option.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1><title>Using <command>glib-genmarshal</command> with Meson</title>
+<para>
+Meson supports generating closure marshallers using <command>glib-genmarshal</command>
+out of the box in its "gnome" module.
+</para>
+
+<para>
+In your <filename>meson.build</filename> file you will typically call the
+<literal>gnome.genmarshal()</literal> method with the source list of marshallers
+to generate:
+</para>
+<informalexample><programlisting>
+gnome = import('gnome')
+marshal_files = gnome.genmarshal('marshal',
+  sources: 'marshal.list',
+  internal: true,
+)
+</programlisting></informalexample>
+<para>
+The <literal>marshal_files</literal> variable will contain an array of two elements
+in the following order:
+</para>
+<itemizedlist>
+  <listitem><para>a build target for the source file</para></listitem>
+  <listitem><para>a build target for the header file</para></listitem>
+</itemizedlist>
+<para>
+You should use the returned objects to provide a dependency on every other
+build target that references the source or header file; for instance, if you
+are using the source to build a library:
+</para>
+<informalexample><programlisting>
+mainlib = library('project',
+  sources: project_sources + marshal_files,
+  ...
+)
+</programlisting></informalexample>
+<para>
+Additionally, if you are including the generated header file inside a build
+target that depends on the library you just built, you must ensure that the
+internal dependency includes the generated header as a required source file:
+</para>
+<informalexample><programlisting>
+mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)
+</programlisting></informalexample>
+<para>
+You should not include the generated source file as well, otherwise it will
+be built separately for every target that depends on it, causing build
+failures. To know more about why all this is required, please refer to the
+<ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
+corresponding Meson FAQ entry</ulink>.
+</para>
+<para>
+For more information on how to use the method, see the
+<ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
+documentation for <literal>gnome.genmarshal()</literal></ulink>.
+</para>
+</refsect1>
+
+<refsect1><title>Using <command>glib-genmarshal</command> with Autotools</title>
+<para>
+In order to use <command>glib-genmarshal</command> in your project when using
+Autotools as the build system, you will first need to modify your
+<filename>configure.ac</filename> file to ensure you find the appropriate
+command using <command>pkg-config</command>, similarly as to how you discover
+the compiler and linker flags for GLib.
+</para>
+<informalexample><programlisting>
+PKG_PROG_PKG_CONFIG([0.28])
+
+PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])
+</programlisting></informalexample>
+<para>
+In your <filename>Makefile.am</filename> file you will typically need very
+simple rules to generate the C files needed for the build.
+</para>
+<informalexample><programlisting>
+marshal.h: marshal.list
+        $(AM_V_GEN)$(GLIB_GENMARSHAL) \
+                --header \
+                --output=$@ \
+                $&lt;
+
+marshal.c: marshal.list marshal.h
+        $(AM_V_GEN)$(GLIB_GENMARSHAL) \
+                --include-header=marshal.h \
+                --body \
+                --output=$@ \
+                $&lt;
+
+BUILT_SOURCES += marshal.h marshal.c
+CLEANFILES += marshal.h marshal.c
+EXTRA_DIST += marshal.list
+</programlisting></informalexample>
+<para>
+In the example above, the first rule generates the header file and depends on
+a <filename>marshal.list</filename> file in order to regenerate the result in
+case the marshallers list is updated. The second rule generates the source file
+for the same <filename>marshal.list</filename>, and includes the file generated
+by the header rule.
+</para>
+</refsect1>
+
+<refsect1><title>Example</title>
+<para>
+To generate marshallers for the following callback functions:
+</para>
+<informalexample><programlisting>
+void   foo (gpointer data1,
+            gpointer data2);
+void   bar (gpointer data1,
+            gint     param1,
+            gpointer data2);
+gfloat baz (gpointer data1,
+            gboolean param1,
+            guchar   param2,
+            gpointer data2);
+</programlisting></informalexample>
+<para>
+The <filename>marshaller.list</filename> file has to look like this:
+</para>
+<programlisting>
+VOID:VOID
+VOID:INT
+FLOAT:BOOLEAN,UCHAR
+</programlisting>
+<para>
+and you call glib-genmarshal like this:
+</para>
+<programlisting>
+glib-genmarshal --header marshaller.list > marshaller.h
+glib-genmarshal --body marshaller.list > marshaller.c
+</programlisting>
+<para>
+The generated marshallers have the arguments encoded in their function name.
+For this particular list, they are
+</para>
+<programlisting>
+g_cclosure_user_marshal_VOID__VOID(...),
+g_cclosure_user_marshal_VOID__INT(...),
+g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).
+</programlisting>
+<para>
+They can be used directly for GClosures or be passed in as the
+GSignalCMarshaller c_marshaller; argument upon creation of signals:
+</para>
+<informalexample><programlisting>
+GClosure *cc_foo, *cc_bar, *cc_baz;
+
+cc_foo = g_cclosure_new (NULL, foo, NULL);
+g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
+cc_bar = g_cclosure_new (NULL, bar, NULL);
+g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
+cc_baz = g_cclosure_new (NULL, baz, NULL);
+g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);
+</programlisting></informalexample>
+</refsect1>
+<refsect1><title>See also</title>
+<para>
+<citerefentry>
+<refentrytitle>glib-mkenums</refentrytitle>
+<manvolnum>1</manvolnum>
+</citerefentry>
+</para>
+</refsect1>
+</refentry>

docs/reference/gobject/glib-mkenums.xml

@@ -0,0 +1,653 @@
+<refentry id="glib-mkenums" lang="en">
+
+<refentryinfo>
+  <title>gdbus</title>
+  <productname>GObject</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Owen</firstname>
+      <surname>Taylor</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle>glib-mkenums</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>glib-mkenums</refname>
+<refpurpose>C language enum description generation utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>glib-mkenums</command>
+<arg choice="opt" rep="repeat">OPTION</arg>
+<arg choice="opt" rep="repeat">FILE</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>glib-mkenums</command> is a small utility that parses C code to
+extract enum definitions and produces enum descriptions based on text templates
+specified by the user. Typically, you can use this tool to generate enumeration
+types for the GType type system, for GObject properties and signal marshalling;
+additionally, you can use it to generate enumeration values of GSettings schemas.
+</para>
+
+<para><command>glib-mkenums</command> takes a list of valid C code files as
+input. The options specified control the text that generated, substituting various
+keywords enclosed in <literal>@</literal> characters in the templates.
+</para>
+
+<refsect2><title>Production text substitutions</title>
+<para>
+Certain keywords enclosed in <literal>@</literal> characters will be substituted in the
+emitted text. For the substitution examples of the keywords below,
+the following example enum definition is assumed:
+</para>
+<informalexample><programlisting>
+typedef enum
+{
+  PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
+  PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
+} PrefixTheXEnum;
+</programlisting></informalexample>
+<variablelist>
+<varlistentry>
+<term><literal>@EnumName@</literal>></term>
+<listitem><para>
+The name of the enum currently being processed, enum names are assumed to be
+properly namespaced and to use mixed capitalization to separate
+words (e.g. <literal>PrefixTheXEnum</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@enum_name@</literal></term>
+<listitem><para>
+The enum name with words lowercase and word-separated by underscores
+(e.g. <literal>prefix_the_xenum</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@ENUMNAME@</literal></term>
+<listitem><para>
+The enum name with words uppercase and word-separated by underscores
+(e.g. <literal>PREFIX_THE_XENUM</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@ENUMSHORT@</literal></term>
+<listitem><para>
+The enum name with words uppercase and word-separated by underscores,
+prefix stripped (e.g. <literal>THE_XENUM</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@ENUMPREFIX@</literal></term>
+<listitem><para>
+The prefix of the enum name (e.g. <literal>PREFIX</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@VALUENAME@</literal></term>
+<listitem><para>
+The enum value name currently being processed with words uppercase and
+word-separated by underscores,
+this is the assumed literal notation of enum values in the C sources
+(e.g. <literal>PREFIX_THE_XVALUE</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@valuenick@</literal></term>
+<listitem><para>
+A nick name for the enum value currently being processed, this is usually
+generated by stripping common prefix words of all the enum values of the
+current enum, the words are lowercase and underscores are substituted by a
+minus (e.g. <literal>the-xvalue</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@valuenum@</literal></term>
+<listitem><para>
+The integer value for the enum value currently being processed. If the
+evaluation fails then <command>glib-mkenums</command> will exit with an
+error status, but this only happens if <literal>@valuenum@</literal>
+appears in your value production template. (Since: 2.26)
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@type@</literal></term>
+<listitem><para>
+This is substituted either by "enum" or "flags", depending on whether the
+enum value definitions contained bit-shift operators or not (e.g. <literal>flags</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@Type@</literal></term>
+<listitem><para>
+The same as <literal>@type@</literal> with the first letter capitalized (e.g. <literal>Flags</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@TYPE@</literal></term>
+<listitem><para>
+The same as <literal>@type@</literal> with all letters uppercased (e.g. <literal>FLAGS</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@filename@</literal></term>
+<listitem><para>
+The full path of the input file currently being processed (e.g. <literal>/build/environment/project/src/foo.h</literal>).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><literal>@basename@</literal></term>
+<listitem><para>
+The base name of the input file currently being processed (e.g. <literal>foo.h</literal>).
+Typically you want to use <literal>@basename@</literal> in place of <literal>@filename@</literal>
+in your templates, to improve the reproducibility of the build. (Since: 2.22)
+</para></listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+<refsect2><title>Trigraph extensions</title>
+<para>
+Some C comments are treated specially in the parsed enum definitions,
+such comments start out with the trigraph sequence <literal>/*&lt;</literal>
+and end with the trigraph sequence <literal>&gt;*/</literal>.
+</para>
+
+<para>The following options can be specified per enum definition:</para>
+<variablelist>
+<varlistentry>
+<term><literal>skip</literal></term>
+<listitem><para>
+Indicates this enum definition should  be skipped.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>flags</literal></term>
+<listitem><para>
+Indicates this enum should be treated as a flags definition.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>underscore_name</literal></term>
+<listitem><para>
+Specifies the word separation used in the <function>*_get_type()</function>
+function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>since</literal></term>
+<listitem><para>
+Specifies the version tag that will be used to substitute the <literal>@enumsince@</literal>
+keyword in the template, useful when documenting methods generated from the enums
+(e.g. <literal>Since: @enumsince@</literal>). (Since: 2.66)
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>The following options can be specified per value definition:</para>
+<variablelist>
+<varlistentry>
+<term><literal>skip</literal></term>
+<listitem><para>
+Indicates the value should be skipped.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>nick</literal></term>
+<listitem><para>
+Specifies the otherwise auto-generated nickname.
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>Examples:</para>
+<informalexample><programlisting>
+typedef enum /*&lt; skip &gt;*/
+{
+  PREFIX_FOO
+} PrefixThisEnumWillBeSkipped;
+typedef enum /*&lt; flags,prefix=PREFIX,since=1.0 &gt;*/
+{
+  PREFIX_THE_ZEROTH_VALUE,	/*&lt; skip &gt;*/
+  PREFIX_THE_FIRST_VALUE,
+  PREFIX_THE_SECOND_VALUE,
+  PREFIX_THE_THIRD_VALUE,	/*&lt; nick=the-last-value &gt;*/
+} PrefixTheFlagsEnum;
+</programlisting></informalexample>
+</refsect2>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>--fhead</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> prior to processing input files.
+</para>
+<para>
+You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
+will be concatenated.
+</para>
+<para>
+When used along with a template file, <replaceable>TEXT</replaceable>
+will be prepended to the template's <literal>file-header</literal> section.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--fprod</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> every time a new input file
+is being processed.
+</para>
+<para>
+You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
+will be concatenated.
+</para>
+<para>
+When used along with a template file, <replaceable>TEXT</replaceable>
+will be appended to the template's <literal>file-production</literal> section.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--ftail</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> after all input files have been
+processed.
+</para>
+<para>
+You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
+will be concatenated.
+</para>
+<para>
+When used along with a template file, <replaceable>TEXT</replaceable>
+will be appended to the template's <literal>file-tail</literal> section.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--eprod</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> every time an enum is encountered
+in the input files.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--vhead</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> before iterating over the set of
+values of an enum.
+</para>
+<para>
+You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
+will be concatenated.
+</para>
+<para>
+When used along with a template file, <replaceable>TEXT</replaceable>
+will be prepended to the template's <literal>value-header</literal> section.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--vprod</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> for every value of an enum.
+</para>
+<para>
+You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
+will be concatenated.
+</para>
+<para>
+When used along with a template file, <replaceable>TEXT</replaceable>
+will be appended to the template's <literal>value-production</literal> section.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--vtail</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Emits <replaceable>TEXT</replaceable> after iterating over all values
+of an enum.
+</para>
+<para>
+You can specify this option multiple times, and the <replaceable>TEXT</replaceable>
+will be concatenated.
+</para>
+<para>
+When used along with a template file, <replaceable>TEXT</replaceable>
+will be appended to the template's <literal>value-tail</literal> section.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--comments</option> <replaceable>TEXT</replaceable></term>
+<listitem><para>
+Template for auto-generated comments, the default (for C code generations) is
+<literal>"/* @comment@ */"</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--template</option> <replaceable>FILE</replaceable></term>
+<listitem><para>
+Read templates from the given file. The templates are enclosed in
+specially-formatted C comments:
+</para>
+<informalexample><programlisting>
+/*** BEGIN section ***/
+/*** END section ***/
+</programlisting></informalexample>
+<para>
+<replaceable>section</replaceable> may be <literal>file-header</literal>,
+<literal>file-production</literal>, <literal>file-tail</literal>,
+<literal>enumeration-production</literal>, <literal>value-header</literal>,
+<literal>value-production</literal>, <literal>value-tail</literal> or
+<literal>comment</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--identifier-prefix</option> <replaceable>PREFIX</replaceable></term>
+<listitem><para>
+Indicates what portion of the enum name should be interpreted as the
+prefix (eg, the "<literal>Gtk</literal>" in
+"<literal>GtkDirectionType</literal>"). Normally this will be figured
+out automatically, but you may need to override the default if your
+namespace is capitalized oddly.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--symbol-prefix</option> <replaceable>PREFIX</replaceable></term>
+<listitem><para>
+Indicates what prefix should be used to correspond to the identifier
+prefix in related C function names (eg, the "<literal>gtk</literal>"
+in "<literal>gtk_direction_type_get_type</literal>". Equivalently,
+this is the lowercase version of the prefix component of the enum
+value names (eg, the "<literal>GTK</literal>" in
+"<literal>GTK_DIR_UP</literal>". The default value is the identifier
+prefix, converted to lowercase.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--help</option></term>
+<listitem><para>
+Print brief help and exit.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--version</option></term>
+<listitem><para>
+Print version and exit.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--output=FILE</option></term>
+<listitem><para>
+Write output to FILE instead of stdout.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>@RSPFILE</option></term>
+<listitem><para>
+When passed as the sole argument, read and parse the actual arguments from
+<literal>RSPFILE</literal>. Useful on systems with a low command-line length
+limit. For example, Windows has a limit of 8191 characters.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1><title>Using templates</title>
+<para>
+Instead of passing the various sections of the generated file to the command
+line of <command>glib-mkenums</command>, it's strongly recommended to use a
+template file, especially for generating C sources.
+</para>
+
+<para>
+A C header template file will typically look like this:
+</para>
+<informalexample><programlisting>
+/*** BEGIN file-header ***/
+#pragma once
+
+/* Include the main project header */
+#include "project.h"
+
+G_BEGIN_DECLS
+/*** END file-header ***/
+
+/*** BEGIN file-production ***/
+
+/* enumerations from "@basename@" */
+/*** END file-production ***/
+
+/*** BEGIN value-header ***/
+GType @enum_name@_get_type (void) G_GNUC_CONST;
+#define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
+/*** END value-header ***/
+
+/*** BEGIN file-tail ***/
+G_END_DECLS
+/*** END file-tail ***/
+</programlisting></informalexample>
+
+<para>
+A C source template file will typically look like this:
+</para>
+<informalexample><programlisting>
+/*** BEGIN file-header ***/
+#include "config.h"
+#include "enum-types.h"
+
+/*** END file-header ***/
+
+/*** BEGIN file-production ***/
+/* enumerations from "@basename@" */
+/*** END file-production ***/
+
+/*** BEGIN value-header ***/
+GType
+@enum_name@_get_type (void)
+{
+  static gsize static_g_@type@_type_id;
+
+  if (g_once_init_enter (&amp;static_g_@type@_type_id))
+    {
+      static const G@Type@Value values[] = {
+/*** END value-header ***/
+
+/*** BEGIN value-production ***/
+            { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
+/*** END value-production ***/
+
+/*** BEGIN value-tail ***/
+            { 0, NULL, NULL }
+      };
+
+      GType g_@type@_type_id =
+        g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
+
+      g_once_init_leave (&amp;static_g_@type@_type_id, g_@type@_type_id);
+    }
+  return static_g_@type@_type_id;
+}
+
+/*** END value-tail ***/
+</programlisting></informalexample>
+
+<para>
+Template files are easier to modify and update, and can be used
+to generate various types of outputs using the same command line
+or tools during the build.
+</para>
+</refsect1>
+
+<refsect1><title>Using glib-mkenums with Meson</title>
+<para>
+Meson supports generating enumeration types using <command>glib-mkenums</command>
+out of the box in its "gnome" module.
+</para>
+
+<para>
+In your <filename>meson.build</filename> file you will typically call the
+<literal>gnome.mkenums_simple()</literal> method to generate idiomatic enumeration
+types from a list of headers to inspect:
+</para>
+<informalexample><programlisting>
+project_headers = [
+  'project-foo.h',
+  'project-bar.h',
+  'project-baz.h',
+]
+
+gnome = import('gnome')
+enum_files = gnome.mkenums_simple('enum-types',
+  sources: project_headers,
+)
+</programlisting></informalexample>
+
+<para>
+The <literal>enum_files</literal> variable will contain an array of two elements
+in the following order:
+</para>
+<itemizedlist>
+  <listitem><para>a build target for the source file</para></listitem>
+  <listitem><para>a build target for the header file</para></listitem>
+</itemizedlist>
+<para>
+You should use the returned objects to provide a dependency on every other
+build target that references the source or header file; for instance, if you
+are using the source to build a library:
+</para>
+<informalexample><programlisting>
+mainlib = library('project',
+  sources: project_sources + enum_files,
+  ...
+)
+</programlisting></informalexample>
+<para>
+Additionally, if you are including the generated header file inside a build
+target that depends on the library you just built, you must ensure that the
+internal dependency includes the generated header as a required source file:
+</para>
+<informalexample><programlisting>
+mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib)
+</programlisting></informalexample>
+<para>
+You should not include the generated source file as well, otherwise it will
+be built separately for every target that depends on it, causing build
+failures. To know more about why all this is required, please refer to the
+<ulink url="https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers">
+corresponding Meson FAQ entry</ulink>.
+</para>
+
+<para>
+If you are generating C header and source files that require special
+templates, you can use <literal>gnome.mkenums()</literal> to provide those
+headers, for instance:
+</para>
+<informalexample><programlisting>
+enum_files = gnome.mkenums('enum-types',
+  sources: project_headers,
+  h_template: 'enum-types.h.in',
+  c_template: 'enum-types.c.in',
+  install_header: true,
+)
+</programlisting></informalexample>
+<para>
+For more information, see the <ulink url="https://mesonbuild.com/Gnome-module.html#gnomegenmarshal">Meson
+documentation for <literal>gnome.mkenums()</literal></ulink>.
+</para>
+</refsect1>
+
+<refsect1><title>Using glib-mkenums with Autotools</title>
+<para>
+In order to use <command>glib-mkenums</command> in your project when using
+Autotools as the build system, you will first need to modify your
+<filename>configure.ac</filename> file to ensure you find the appropriate
+command using <command>pkg-config</command>, similarly as to how you discover
+the compiler and linker flags for GLib.
+</para>
+<informalexample><programlisting>
+PKG_PROG_PKG_CONFIG([0.28])
+
+PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])
+</programlisting></informalexample>
+<para>
+In your <filename>Makefile.am</filename> file you will typically use rules
+like these:
+</para>
+<informalexample><programlisting>
+# A list of headers to inspect
+project_headers = \
+        project-foo.h \
+        project-bar.h \
+        project-baz.h
+
+enum-types.h: $(project_headers) enum-types.h.in
+        $(AM_V_GEN)$(GLIB_MKENUMS) \
+                --template=enum-types.h.in \
+                --output=$@ \
+                $(project_headers)
+
+enum-types.c: $(project_headers) enum-types.c.in enum-types.h
+        $(AM_V_GEN)$(GLIB_MKENUMS) \
+                --template=enum-types.c.in \
+                --output=$@ \
+                $(project_headers)
+
+# Build the enum types files before every other target
+BUILT_SOURCES += enum-types.h enum-types.c
+CLEANFILES += enum-types.h enum-types.c
+EXTRA_DIST += enum-types.h.in enum-types.c.in
+</programlisting></informalexample>
+<para>
+In the example above, we have a variable called <literal>project_headers</literal>
+where we reference all header files we want to inspect for generating enumeration
+GTypes. In the <filename>enum-types.h</filename> rule we use <command>glib-mkenums</command>
+with a template called <filename>enum-types.h.in</filename> in order to generate the
+header file; similarly, in the <filename>enum-types.c</filename> rule we use a
+template called <filename>enum-types.c.in</filename>.
+</para>
+</refsect1>
+
+<refsect1><title>See also</title>
+<para>
+<citerefentry>
+<refentrytitle>glib-genmarshal</refentrytitle>
+<manvolnum>1</manvolnum>
+</citerefentry>
+</para>
+</refsect1>
+</refentry>

docs/reference/gobject/gobject-docs.xml

@@ -0,0 +1,224 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
+                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
+
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>GObject Reference Manual</title>
+    <releaseinfo>
+      for GObject &version;
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="https://developer.gnome.org/gobject/unstable/">https://developer.gnome.org/gobject/unstable/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <preface>
+    <title>Introduction</title>
+      <para>
+			Most modern programming languages come with their own native object
+			systems and additional fundamental algorithmic language constructs.
+			Just as GLib serves as an implementation of such fundamental
+			types and algorithms (linked lists, hash tables and so forth), the
+			GLib Object System provides the required implementations of a
+			flexible, extensible, and intentionally easy to map (into other
+			languages) object-oriented framework for C.
+			The substantial elements that are provided can be summarized as:
+			<itemizedlist>
+				<listitem><para>
+					 A generic type system to register arbitrary single-inherited
+						flat and deep derived types as well as interfaces for
+						structured types.
+						It takes care of creation, initialization and memory management
+						of the assorted object and class structures, maintains
+						parent/child relationships and deals with dynamic implementations
+						of such types. That is, their type specific implementations are
+						relocatable/unloadable during runtime.
+				</para></listitem>
+				<listitem><para>
+						A collection of fundamental type implementations, such as integers,
+						doubles, enums and structured types, to name a few.
+				</para></listitem>
+				<listitem><para>
+						A sample fundamental type implementation to base object hierarchies
+						upon - the GObject fundamental type.
+				</para></listitem>
+				<listitem><para>
+						A signal system that allows very flexible user customization of
+						virtual/overridable object methods and can serve as a powerful
+						notification mechanism.
+				</para></listitem>
+				<listitem><para>
+						An extensible parameter/value system, supporting all the provided
+						fundamental types that can be used to generically handle object
+						properties or otherwise parameterized types.
+				</para></listitem>
+			</itemizedlist>
+		</para>
+  </preface>
+
+  <part label="I">
+    <title>Concepts</title>
+
+    <xi:include href="tut_intro.xml" />
+    <xi:include href="tut_gtype.xml" />
+    <xi:include href="tut_gobject.xml" />
+    <xi:include href="tut_gsignal.xml" />
+  </part>
+  <reference label="II">
+    <title>API Reference</title>
+
+      <xi:include href="xml/gtype.xml" />
+      <xi:include href="xml/gtypeplugin.xml" />
+      <xi:include href="xml/gtypemodule.xml" />
+      <xi:include href="xml/objects.xml" />
+      <xi:include href="xml/enumerations_flags.xml" />
+      <xi:include href="xml/gboxed.xml" />
+      <xi:include href="xml/generic_values.xml" />
+      <xi:include href="xml/param_value_types.xml" />
+      <xi:include href="xml/gparamspec.xml" />
+      <xi:include href="xml/value_collection.xml" />
+      <xi:include href="xml/signals.xml" />
+      <xi:include href="xml/gsignalgroup.xml" />
+      <xi:include href="xml/gclosure.xml" />
+      <xi:include href="xml/value_arrays.xml" />
+      <xi:include href="xml/gbinding.xml" />
+      <xi:include href="xml/gbindinggroup.xml" />
+  </reference>
+  <reference label="III">
+    <title>Tools Reference</title>
+
+    <xi:include href="glib-mkenums.xml" />
+    <xi:include href="glib-genmarshal.xml" />
+    <xi:include href="gobject-query.xml" />
+  </reference>
+
+  <xi:include href="tut_howto.xml" />
+  <xi:include href="tut_tools.xml" />
+
+  <index id="api-index-full">
+    <title>Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-2" role="2.2">
+    <title>Index of new symbols in 2.2</title>
+    <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-4" role="2.4">
+    <title>Index of new symbols in 2.4</title>
+    <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-6" role="2.6">
+    <title>Index of new symbols in 2.6</title>
+    <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-8" role="2.8">
+    <title>Index of new symbols in 2.8</title>
+    <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-10" role="2.10">
+    <title>Index of new symbols in 2.10</title>
+    <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-12" role="2.12">
+    <title>Index of new symbols in 2.12</title>
+    <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-14" role="2.14">
+    <title>Index of new symbols in 2.14</title>
+    <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-18" role="2.18">
+    <title>Index of new symbols in 2.18</title>
+    <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-22" role="2.22">
+    <title>Index of new symbols in 2.22</title>
+    <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-24" role="2.24">
+    <title>Index of new symbols in 2.24</title>
+    <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-26" role="2.26">
+    <title>Index of new symbols in 2.26</title>
+    <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-28" role="2.28">
+    <title>Index of new symbols in 2.28</title>
+    <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-30" role="2.30">
+    <title>Index of new symbols in 2.30</title>
+    <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-32" role="2.32">
+    <title>Index of new symbols in 2.32</title>
+    <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-34" role="2.34">
+    <title>Index of new symbols in 2.34</title>
+    <xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-36" role="2.36">
+    <title>Index of new symbols in 2.36</title>
+    <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-38" role="2.38">
+    <title>Index of new symbols in 2.38</title>
+    <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-40" role="2.40">
+    <title>Index of new symbols in 2.40</title>
+    <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-42" role="2.42">
+    <title>Index of new symbols in 2.42</title>
+    <xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-44" role="2.44">
+    <title>Index of new symbols in 2.44</title>
+    <xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-46" role="2.46">
+    <title>Index of new symbols in 2.46</title>
+    <xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-54" role="2.54">
+    <title>Index of new symbols in 2.54</title>
+    <xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-56" role="2.56">
+    <title>Index of new symbols in 2.56</title>
+    <xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-62" role="2.62">
+    <title>Index of new symbols in 2.62</title>
+    <xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-66" role="2.66">
+    <title>Index of new symbols in 2.66</title>
+    <xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-68" role="2.68">
+    <title>Index of new symbols in 2.68</title>
+    <xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-70" role="2.70">
+    <title>Index of new symbols in 2.70</title>
+    <xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-2-72" role="2.72">
+    <title>Index of new symbols in 2.72</title>
+    <xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+
+</book>

docs/reference/gobject/gobject-query.xml

@@ -0,0 +1,123 @@
+<refentry id="gobject-query" lang="en">
+
+<refentryinfo>
+  <title>gobject-query</title>
+  <productname>GObject</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Tim</firstname>
+      <surname>Janik</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle>gobject-query</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>gobject-query</refname>
+<refpurpose>display a tree of types</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gobject-query</command>
+<arg choice="plain">froots</arg>
+<arg choice="opt" rep="repeat">OPTION</arg>
+</cmdsynopsis>
+<cmdsynopsis>
+<command>gobject-query</command>
+<arg choice="plain">tree</arg>
+<arg choice="opt" rep="repeat">OPTION</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>
+<command>gobject-query</command> is a small utility that draws a tree of
+types.
+</para>
+
+<para>
+<command>gobject-query</command> takes a mandatory argument that specifies
+whether it should iterate over the fundamental types or print a type tree.
+</para>
+</refsect1>
+
+<refsect1><title>Commands</title>
+<variablelist>
+<varlistentry>
+<term><option>froots</option></term>
+<listitem><para>
+iterate over fundamental roots
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><option>tree</option></term>
+<listitem><para>
+print type tree
+</para></listitem>
+</varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-r</option> <replaceable>TYPE</replaceable></term>
+<listitem><para>
+specify the root type
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-n</option></term>
+<listitem><para>
+don't descend type tree
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-b</option> <replaceable>STRING</replaceable></term>
+<listitem><para>
+specify indent string
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-i</option> <replaceable>STRING</replaceable></term>
+<listitem><para>
+specify incremental indent string
+</para></listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><option>-s</option> <replaceable>NUMBER</replaceable></term>
+<listitem><para>
+specify line spacing
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Print brief help and exit.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+Print version and exit.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+</refentry>

docs/reference/gobject/meson.build

@@ -0,0 +1,68 @@
+if get_option('gtk_doc')
+  subdir('xml')
+
+  ignore_headers = [
+    'tests',
+    'gatomicarray.h',
+    'gobject_probes.h',
+    'gobject_trace.h',
+    'gtype-private.h',
+    'glib-enumtypes.h',
+  ]
+
+  docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
+  version_conf = configuration_data()
+  version_conf.set('GLIB_VERSION', meson.project_version())
+  configure_file(
+    input: 'version.xml.in',
+    output: 'version.xml',
+    configuration: version_conf
+  )
+
+  gtkdocincl = include_directories('.')
+
+  gnome.gtkdoc('gobject',
+    main_xml : 'gobject-docs.xml',
+    namespace : 'g',
+    mode : 'none',
+    dependencies : [libgobject_dep, libglib_dep],
+    include_directories : [gtkdocincl],
+    src_dir : 'gobject',
+    scan_args : gtkdoc_common_scan_args + [
+      '--rebuild-types',
+      '--ignore-headers=' + ' '.join(ignore_headers),
+    ],
+    content_files : [
+      'glib-mkenums.xml',
+      'glib-genmarshal.xml',
+      'gobject-query.xml',
+      'tut_gobject.xml',
+      'tut_gsignal.xml',
+      'tut_gtype.xml',
+      'tut_howto.xml',
+      'tut_intro.xml',
+      'tut_tools.xml'
+    ],
+    html_assets : [
+      'images/glue.png'
+    ],
+    fixxref_args: [
+      '--html-dir=' + docpath,
+      '--extra-dir=' + join_paths('gobject', '..', 'glib', 'html'),
+    ],
+    install: true,
+    check: true,
+  )
+endif
+
+if get_option('man')
+  manpages = ['glib-mkenums', 'glib-genmarshal', 'gobject-query']
+  foreach page : manpages
+    custom_target(page + '-man',
+      input: page + '.xml',
+      output: page + '.1',
+      command: xsltproc_command,
+      install: true,
+      install_dir: man1_dir)
+  endforeach
+endif

docs/reference/gobject/tut_gobject.xml

@@ -0,0 +1,728 @@
+<?xml version='1.0' encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter id="chapter-gobject">
+  <title>The GObject base class</title>
+
+  <para>
+    The previous chapter discussed the details of GLib's Dynamic Type System.
+    The GObject library also contains an implementation for a base fundamental
+    type named <link linkend="GObject"><type>GObject</type></link>.
+  </para>
+
+  <para>
+    <link linkend="GObject"><type>GObject</type></link> is a fundamental classed instantiatable type. It implements:
+    <itemizedlist>
+      <listitem><para>Memory management with reference counting</para></listitem>
+      <listitem><para>Construction/Destruction of instances</para></listitem>
+      <listitem><para>Generic per-object properties with set/get function pairs</para></listitem>
+      <listitem><para>Easy use of signals</para></listitem>
+    </itemizedlist>
+    All the GNOME libraries which use the GLib type system (like GTK+ and GStreamer)
+    inherit from <link linkend="GObject"><type>GObject</type></link> which is why it is important to understand
+    the details of how it works.
+  </para>
+
+  <sect1 id="gobject-instantiation">
+    <title>Object instantiation</title>
+
+    <para>
+      The <function><link linkend="g-object-new">g_object_new</link></function>
+      family of functions can be used to instantiate any GType which inherits
+      from the GObject base type. All these functions make sure the class and
+      instance structures have been correctly initialized by GLib's type system
+      and then invoke at one point or another the constructor class method
+      which is used to:
+      <itemizedlist>
+        <listitem><para>
+            Allocate and clear memory through <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>,
+          </para></listitem>
+        <listitem><para>
+            Initialize the object's instance with the construction properties.
+          </para></listitem>
+      </itemizedlist>
+     Although one can expect all class and instance members (except the fields
+     pointing to the parents) to be set to zero, some consider it good practice
+     to explicitly set them.
+    </para>
+
+    <para>
+      Once all construction operations have been completed and constructor
+      properties set, the constructed class method is called.
+    </para>
+
+    <para>
+      Objects which inherit from GObject are allowed to override this
+      constructed class method.
+      The example below shows how <type>ViewerFile</type> overrides the parent's construction process:
+<informalexample><programlisting>
+#define VIEWER_TYPE_FILE viewer_file_get_type ()
+G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
+
+struct _ViewerFile
+{
+  GObject parent_instance;
+
+  /* instance members */
+  gchar *filename;
+  guint zoom_level;
+};
+
+/* will create viewer_file_get_type and set viewer_file_parent_class */
+G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)
+
+static void
+viewer_file_constructed (GObject *obj)
+{
+  /* update the object state depending on constructor properties */
+
+  /* Always chain up to the parent constructed function to complete object
+   * initialisation. */
+  G_OBJECT_CLASS (viewer_file_parent_class)-&gt;constructed (obj);
+}
+
+static void
+viewer_file_finalize (GObject *obj)
+{
+  ViewerFile *self = VIEWER_FILE (obj);
+
+  g_free (self->filename);
+
+  /* Always chain up to the parent finalize function to complete object
+   * destruction. */
+  G_OBJECT_CLASS (viewer_file_parent_class)-&gt;finalize (obj);
+}
+
+static void
+viewer_file_class_init (ViewerFileClass *klass)
+{
+  GObjectClass *object_class = G_OBJECT_CLASS (klass);
+
+  object_class-&gt;constructed = viewer_file_constructed;
+  object_class-&gt;finalize = viewer_file_finalize;
+}
+
+static void
+viewer_file_init (ViewerFile *self)
+{
+  /* initialize the object */
+}
+
+</programlisting></informalexample>
+      If the user instantiates an object <type>ViewerFile</type> with:
+<informalexample><programlisting>
+ViewerFile *file = g_object_new (VIEWER_TYPE_FILE, NULL);
+</programlisting></informalexample>        
+      If this is the first instantiation of such an object, the
+      <function>viewer_file_class_init</function> function will be invoked
+      after any <function>viewer_file_base_class_init</function> function.
+      This will make sure the class structure of this new object is
+      correctly initialized. Here, <function>viewer_file_class_init</function>
+      is expected to override the object's class methods and setup the
+      class' own methods. In the example above, the <literal>constructed</literal>
+      method is the only overridden method: it is set to
+      <function>viewer_file_constructed</function>.
+    </para>
+
+    <para>
+      Once <function><link linkend="g-object-new">g_object_new</link></function> has obtained a reference to an initialized
+      class structure, it invokes its constructor method to create an instance of the new 
+      object, if the constructor has been overridden in <function>viewer_file_class_init</function>.
+      Overridden constructors must chain up to their parent’s constructor. In
+      order to find the parent class and chain up to the parent class
+      constructor, we can use the <literal>viewer_file_parent_class</literal>
+      pointer that has been set up for us by the
+      <link linkend="G-DEFINE-TYPE:CAPS"><literal>G_DEFINE_TYPE</literal></link>
+      macro.
+    </para>
+
+    <para>
+      Finally, at one point or another, <function>g_object_constructor</function> is invoked
+      by the last constructor in the chain. This function allocates the object's instance buffer
+      through <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
+      which means that the <function>instance_init</function> function is invoked at this point if one
+      was registered. After <function>instance_init</function> returns, the object is fully initialized and should be 
+      ready to have its methods called by the user. When
+      <function><link linkend="g-type-create-instance">g_type_create_instance</link></function>
+      returns, <function>g_object_constructor</function> sets the construction properties
+      (i.e. the properties which were given to <function><link linkend="g-object-new">g_object_new</link></function>) and returns
+      to the user's constructor.
+    </para>
+
+    <para>
+      The process described above might seem a bit complicated, but it can be
+      summarized easily by the table below which lists the functions invoked
+      by <function><link linkend="g-object-new">g_object_new</link></function>
+      and their order of invocation:
+    </para>
+
+    <para>
+      <table id="gobject-construction-table">
+        <title><function><link linkend="g-object-new">g_object_new</link></function></title>
+        <tgroup cols="3">
+          <colspec colwidth="*" colnum="1" align="left"/>
+          <colspec colwidth="*" colnum="2" align="left"/>
+          <colspec colwidth="8*" colnum="3" align="left"/>
+
+          <thead>
+            <row>
+              <entry>Invocation time</entry>
+              <entry>Function invoked</entry>
+              <entry>Function's parameters</entry>
+              <entry>Remark</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry morerows="3">First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+              <entry>target type's <function>base_init</function> function</entry>
+              <entry>On the inheritance tree of classes from fundamental type to target type. 
+                <function>base_init</function> is invoked once for each class structure.</entry>
+              <entry>Never used in practice. Unlikely you will need it.</entry>
+            </row>
+            <row>
+              <!--entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
+              <entry>target type's <function>class_init</function> function</entry>
+              <entry>On target type's class structure</entry>
+              <entry>
+                Here, you should make sure to initialize or override class methods (that is,
+                assign to each class' method its function pointer) and create the signals and
+                the properties associated to your object.
+              </entry>
+            </row>
+            <row>
+              <!--entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
+              <entry>interface's <function>base_init</function> function</entry>
+              <entry>On interface's vtable</entry>
+              <entry></entry>
+            </row>
+            <row>
+              <!--entry>First call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
+              <entry>interface's <function>interface_init</function> function</entry>
+              <entry>On interface's vtable</entry>
+              <entry></entry>
+            </row>
+            <row>
+              <entry morerows="2">Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry>
+              <entry>target type's class <function>constructor</function> method: <function>GObjectClass->constructor</function></entry>
+              <entry>On object's instance</entry>
+              <entry>
+                If you need to handle construct properties in a custom way, or implement a singleton class, override the constructor
+                method and make sure to chain up to the object's
+                parent class before doing your own initialization.
+                In doubt, do not override the constructor method.
+              </entry>
+            </row>
+            <row>
+              <!--entry>Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
+              <entry>type's <function>instance_init</function> function</entry>
+              <entry>On the inheritance tree of classes from fundamental type to target type. 
+              the <function>instance_init</function> provided for each type is invoked once for each instance 
+              structure.</entry>
+              <entry>
+                Provide an <function>instance_init</function> function to initialize your object before its construction
+                properties are set. This is the preferred way to initialize a GObject instance.
+                This function is equivalent to C++ constructors.
+              </entry>
+            </row>
+            <row>
+              <!--entry>Each call to <function><link linkend="g-object-new">g_object_new</link></function> for target type</entry-->
+              <entry>target type's class <function>constructed</function> method: <function>GObjectClass->constructed</function></entry>
+              <entry>On object's instance</entry>
+              <entry>
+                If you need to perform object initialization steps after all construct properties have been set.
+                This is the final step in the object initialization process, and is only called if the <function>constructor</function>
+                method returned a new object instance (rather than, for example, an existing singleton).
+              </entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </para>
+
+    <para>
+      Readers should feel concerned about one little twist in the order in
+      which functions are invoked: while, technically, the class' constructor
+      method is called <emphasis>before</emphasis> the GType's <function>instance_init</function>
+      function (since <function><link linkend="g-type-create-instance">g_type_create_instance</link></function> which calls <function>instance_init</function> is called by
+      <function>g_object_constructor</function> which is the top-level class 
+      constructor method and to which users are expected to chain to), the
+      user's code which runs in a user-provided constructor will always
+      run <emphasis>after</emphasis> GType's <function>instance_init</function> function since the
+      user-provided constructor <emphasis>must</emphasis> (you've been warned)
+      chain up <emphasis>before</emphasis> doing anything useful.
+    </para>
+  </sect1>
+
+  <sect1 id="gobject-memory">
+    <title>Object memory management</title>
+
+    <para>
+      The memory-management API for GObjects is a bit complicated but the idea behind it
+      is pretty simple: the goal is to provide a flexible model based on reference counting
+      which can be integrated in applications which use or require different memory management
+      models (such as garbage collection). The methods which are used to
+      manipulate this reference count are described below.
+    </para>
+
+    <sect2 id="gobject-memory-refcount">
+      <title>Reference count</title>
+
+      <para>
+        The functions <function><link linkend="g-object-ref">g_object_ref</link></function>/<function><link linkend="g-object-unref">g_object_unref</link></function> respectively 
+        increase and decrease the reference count. These functions are
+        thread-safe.
+        <function><link linkend="g-clear-object">g_clear_object</link></function>
+        is a convenience wrapper around <function>g_object_unref</function>
+        which also clears the pointer passed to it.
+      </para>
+      <para>
+        The reference count is initialized to one by 
+        <function><link linkend="g-object-new">g_object_new</link></function> which means that the caller
+        is currently the sole owner of the newly-created reference. (If the object is derived from <link linkend="GInitiallyUnowned"><type>GInitiallyUnowned</type></link>, this reference count is <link linkend="floating-ref">floating</link>.)
+        When the reference count reaches zero, that is, 
+        when <function><link linkend="g-object-unref">g_object_unref</link></function> is called by the last client holding
+        a reference to the object, the <emphasis>dispose</emphasis> and the 
+        <emphasis>finalize</emphasis> class methods are invoked.
+      </para>
+      <para>
+        Finally, after <emphasis>finalize</emphasis> is invoked, 
+        <function><link linkend="g-type-free-instance">g_type_free_instance</link></function> is called to free the object instance.
+        Depending on the memory allocation policy decided when the type was registered (through
+        one of the <function>g_type_register_*</function> functions), the object's instance 
+        memory will be freed or returned to the object pool for this type.
+        Once the object has been freed, if it was the last instance of the type, the type's class
+        will be destroyed as described in <xref linkend="gtype-instantiatable-classed"/> and
+          <xref linkend="gtype-non-instantiatable-classed"/>.
+      </para>
+
+      <para>
+        The table below summarizes the destruction process of a GObject:
+        <table id="gobject-destruction-table">
+          <title><function><link linkend="g-object-unref">g_object_unref</link></function></title>
+          <tgroup cols="3">
+            <colspec colwidth="*" colnum="1" align="left"/>
+            <colspec colwidth="*" colnum="2" align="left"/>
+            <colspec colwidth="8*" colnum="3" align="left"/>
+
+            <thead>
+              <row>
+                <entry>Invocation time</entry>
+                <entry>Function invoked</entry>
+                <entry>Function's parameters</entry>
+                <entry>Remark</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry morerows="1">Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
+                  of target type
+                 </entry>
+                <entry>target type's dispose class function</entry>
+                <entry>GObject instance</entry>
+                <entry>
+                  When dispose ends, the object should not hold any reference to any other
+                  member object. The object is also expected to be able to answer client
+                  method invocations (with possibly an error code but no memory violation)
+                  until finalize is executed. dispose can be executed more than once.
+                dispose should chain up to its parent implementation just before returning
+                to the caller.
+                </entry>
+              </row>
+              <row>
+                <!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for an instance
+                  of target type
+                </entry-->
+                <entry>target type's finalize class function</entry>
+                <entry>GObject instance</entry>
+                <entry>
+                  Finalize is expected to complete the destruction process initiated by
+                  dispose. It should complete the object's destruction. finalize will be
+                  executed only once.
+                finalize should chain up to its parent implementation just before returning
+                to the caller.
+                  The reason why the destruction process is split is two different phases is
+                  explained in <xref linkend="gobject-memory-cycles"/>.
+                </entry>
+              </row>
+              <row>
+                <entry morerows="3">Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for the last
+                  instance of target type
+                 </entry>
+                <entry>interface's <function>interface_finalize</function> function</entry>
+                <entry>On interface's vtable</entry>
+                <entry>Never used in practice. Unlikely you will need it.</entry>
+              </row>
+              <row>
+                <!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function>for the last
+                  instance of target type
+                 </entry-->
+                <entry>interface's <function>base_finalize</function> function</entry>
+                <entry>On interface's vtable</entry>
+                <entry>Never used in practice. Unlikely you will need it.</entry>
+              </row>
+              <row>
+                <!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for the last
+                  instance of target type
+                 </entry-->
+                <entry>target type's <function>class_finalize</function> function</entry>
+                <entry>On target type's class structure</entry>
+                <entry>Never used in practice. Unlikely you will need it.</entry>
+              </row>
+              <row>
+                <!--entry>Last call to <function><link linkend="g-object-unref">g_object_unref</link></function> for the last
+                  instance of target type
+                 </entry-->
+                <entry>type's <function>base_finalize</function> function</entry>
+                <entry>On the inheritance tree of classes from fundamental type to target type.
+                  <function>base_init</function> is invoked once for each class structure.</entry>
+                <entry>Never used in practice. Unlikely you will need it.</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>                
+      </para>
+
+    </sect2>
+
+    <sect2 id="gobject-memory-weakref">
+      <title>Weak References</title>
+    
+      <para>
+      Weak references are used to monitor object finalization:
+      <function><link linkend="g-object-weak-ref">g_object_weak_ref</link></function> adds a monitoring callback which does
+      not hold a reference to the object but which is invoked when the object runs 
+      its dispose method. As such, each weak ref can be invoked more than once upon
+      object finalization (since dispose can run more than once during object 
+      finalization).
+      </para>
+
+      <para>
+        <function><link linkend="g-object-weak-unref">g_object_weak_unref</link></function> can be used to remove a monitoring
+        callback from the object. 
+      </para>
+  
+      <para>
+        Weak references are also used to implement <function><link linkend="g-object-add-weak-pointer">g_object_add_weak_pointer</link></function>
+        and <function><link linkend="g-object-remove-weak-pointer">g_object_remove_weak_pointer</link></function>. These functions add a weak reference
+        to the object they are applied to which makes sure to nullify the pointer given by the user
+        when object is finalized.
+      </para>
+
+      <para>
+        Similarly, <link linkend="GWeakRef"><type>GWeakRef</type></link> can be
+        used to implement weak references if thread safety is required.
+      </para>
+    </sect2>
+  
+    <sect2 id="gobject-memory-cycles">
+      <title>Reference counts and cycles</title>
+
+      <para>
+        GObject's memory management model was designed to be easily integrated in existing code
+        using garbage collection. This is why the destruction process is split in two phases:
+        the first phase, executed in the dispose handler is supposed to release all references
+        to other member objects. The second phase, executed by the finalize handler is supposed
+        to complete the object's destruction process. Object methods should be able to run
+        without program error in-between the two phases.
+      </para>
+  
+      <para>
+        This two-step destruction process is very useful to break reference counting cycles.
+        While the detection of the cycles is up to the external code, once the cycles have been
+        detected, the external code can invoke <function><link linkend="g-object-run-dispose">g_object_run_dispose</link></function> which 
+        will indeed break any existing cycles since it will run the dispose handler associated
+        to the object and thus release all references to other objects.
+      </para>
+  
+      <para>
+        This explains one of the rules about the dispose handler stated earlier:
+        the dispose handler can be invoked multiple times. Let's say we
+        have a reference count cycle: object A references B which itself references object A.
+        Let's say we have detected the cycle and we want to destroy the two objects. One way to 
+        do this would be to invoke <function><link linkend="g-object-run-dispose">g_object_run_dispose</link></function> on one of the 
+        objects.
+      </para>
+  
+      <para>
+        If object A releases all its references to all objects, this means it releases its
+        reference to object B. If object B was not owned by anyone else, this is its last
+        reference count which means this last unref runs B's dispose handler which, in turn,
+        releases B's reference on object A. If this is A's last reference count, this last 
+        unref runs A's dispose handler which is running for the second time before
+        A's finalize handler is invoked !
+      </para>
+  
+      <para>
+        The above example, which might seem a bit contrived, can really happen if
+        GObjects are being handled by language bindings — hence the rules for
+        object destruction should be closely followed.
+      </para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="gobject-properties">
+    <title>Object properties</title>
+  
+    <para>
+      One of GObject's nice features is its generic get/set mechanism for object
+      properties. When an object
+      is instantiated, the object's <function>class_init</function> handler should be used to register
+      the object's properties with <function><link linkend="g-object-class-install-properties">g_object_class_install_properties</link></function>.
+    </para>
+  
+    <para>
+      The best way to understand how object properties work is by looking at a real example
+      of how it is used:
+<informalexample><programlisting>
+/************************************************/
+/* Implementation                               */
+/************************************************/
+
+typedef enum
+{
+  PROP_FILENAME = 1,
+  PROP_ZOOM_LEVEL,
+  N_PROPERTIES
+} ViewerFileProperty;
+
+static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
+
+static void
+viewer_file_set_property (GObject      *object,
+                          guint         property_id,
+                          const GValue *value,
+                          GParamSpec   *pspec)
+{
+  ViewerFile *self = VIEWER_FILE (object);
+
+  switch ((ViewerFileProperty) property_id)
+    {
+    case PROP_FILENAME:
+      g_free (self-&gt;filename);
+      self-&gt;filename = g_value_dup_string (value);
+      g_print ("filename: %s\n", self-&gt;filename);
+      break;
+
+    case PROP_ZOOM_LEVEL:
+      self-&gt;zoom_level = g_value_get_uint (value);
+      g_print ("zoom level: &percnt;u\n", self-&gt;zoom_level);
+      break;
+
+    default:
+      /* We don't have any other property... */
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+      break;
+    }
+}
+
+static void
+viewer_file_get_property (GObject    *object,
+                          guint       property_id,
+                          GValue     *value,
+                          GParamSpec *pspec)
+{
+  ViewerFile *self = VIEWER_FILE (object);
+
+  switch ((ViewerFileProperty) property_id)
+    {
+    case PROP_FILENAME:
+      g_value_set_string (value, self-&gt;filename);
+      break;
+
+    case PROP_ZOOM_LEVEL:
+      g_value_set_uint (value, self-&gt;zoom_level);
+      break;
+
+    default:
+      /* We don't have any other property... */
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+      break;
+    }
+}
+
+static void
+viewer_file_class_init (ViewerFileClass *klass)
+{
+  GObjectClass *object_class = G_OBJECT_CLASS (klass);
+
+  object_class-&gt;set_property = viewer_file_set_property;
+  object_class-&gt;get_property = viewer_file_get_property;
+
+  obj_properties[PROP_FILENAME] =
+    g_param_spec_string ("filename",
+                         "Filename",
+                         "Name of the file to load and display from.",
+                         NULL  /* default value */,
+                         G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
+
+  obj_properties[PROP_ZOOM_LEVEL] =
+    g_param_spec_uint ("zoom-level",
+                       "Zoom level",
+                       "Zoom level to view the file at.",
+                       0  /* minimum value */,
+                       10 /* maximum value */,
+                       2  /* default value */,
+                       G_PARAM_READWRITE);
+
+  g_object_class_install_properties (object_class,
+                                     N_PROPERTIES,
+                                     obj_properties);
+}
+
+/************************************************/
+/* Use                                          */
+/************************************************/
+
+ViewerFile *file;
+GValue val = G_VALUE_INIT;
+
+file = g_object_new (VIEWER_TYPE_FILE, NULL);
+
+g_value_init (&amp;val, G_TYPE_UINT);
+g_value_set_char (&amp;val, 11);
+
+g_object_set_property (G_OBJECT (file), "zoom-level", &amp;val);
+
+g_value_unset (&amp;val);
+</programlisting></informalexample>
+      The client code above looks simple but a lot of things happen under the hood:
+    </para>
+  
+    <para>
+      <function><link linkend="g-object-set-property">g_object_set_property</link></function> first ensures a property
+      with this name was registered in <emphasis>file</emphasis>'s <function>class_init</function> handler. If so it walks the class hierarchy,
+      from bottom-most most-derived type, to top-most fundamental type to find the class
+      which registered that property. It then tries to convert the user-provided
+      <link linkend="GValue"><type>GValue</type></link>
+      into a <type>GValue</type> whose type is that of the associated property.
+    </para>
+
+    <para>
+      If the user provides a <type>signed char</type> <type>GValue</type>, as is shown
+      here, and if the object's property was registered as an <type>unsigned int</type>,
+      <function><link linkend="g-value-transform">g_value_transform</link></function> will try to transform the input signed char into
+      an unsigned int. Of course, the success of the transformation depends on the availability
+      of the required transform function. In practice, there will almost always be a transformation
+      <footnote>
+        <para>Its behaviour might not be what you expect but it is up to you to actually avoid
+          relying on these transformations.
+        </para>
+      </footnote>
+      which matches and conversion will be carried out if needed.
+    </para>
+  
+    <para>
+      After transformation, the <link linkend="GValue"><type>GValue</type></link> is validated by 
+      <function><link linkend="g-param-value-validate">g_param_value_validate</link></function> which makes sure the user's
+      data stored in the <link linkend="GValue"><type>GValue</type></link> matches the characteristics specified by
+      the property's <link linkend="GParamSpec"><type>GParamSpec</type></link>.
+      Here, the <link linkend="GParamSpec"><type>GParamSpec</type></link> we 
+      provided in <function>class_init</function> has a validation function which makes sure that the GValue
+      contains a value which respects the minimum and maximum bounds of the 
+      <link linkend="GParamSpec"><type>GParamSpec</type></link>. In the example above, the client's GValue does not
+      respect these constraints (it is set to 11, while the maximum is 10). As such, the
+      <function><link linkend="g-object-set-property">g_object_set_property</link></function> function will return with an error.
+    </para>
+  
+    <para>
+      If the user's GValue had been set to a valid value, <function><link linkend="g-object-set-property">g_object_set_property</link></function>
+      would have proceeded with calling the object's
+      <function>set_property</function> class method. Here, since our
+      implementation of <type>ViewerFile</type> did override this method, execution would jump to
+      <function>viewer_file_set_property</function> after having retrieved from the 
+      <link linkend="GParamSpec"><type>GParamSpec</type></link> the <emphasis>param_id</emphasis>
+      <footnote>
+        <para>
+          It should be noted that the param_id used here need only to uniquely identify each 
+          <link linkend="GParamSpec"><type>GParamSpec</type></link> within the <type>ViewerFileClass</type> such that the switch
+          used in the set and get methods actually works. Of course, this locally-unique 
+          integer is purely an optimization: it would have been possible to use a set of 
+          <emphasis>if (strcmp (a, b) == 0) {} else if (strcmp (a, b) == 0) {}</emphasis> statements.
+        </para>
+      </footnote>
+      which had been stored by
+      <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
+    </para>
+  
+    <para>
+      Once the property has been set by the object's
+      <function>set_property</function> class method, execution
+      returns to <function><link linkend="g-object-set-property">g_object_set_property</link></function> which makes sure that
+      the "notify" signal is emitted on the object's instance with the changed property as
+      parameter unless notifications were frozen by <function><link linkend="g-object-freeze-notify">g_object_freeze_notify</link></function>.
+    </para>
+  
+    <para>
+      <function><link linkend="g-object-thaw-notify">g_object_thaw_notify</link></function> can be used to re-enable notification of 
+      property modifications through the
+      <link linkend="GObject-notify"><type>“notify”</type></link> signal. It is important to remember that
+      even if properties are changed while property change notification is frozen, the "notify"
+      signal will be emitted once for each of these changed properties as soon as the property
+      change notification is thawed: no property change is lost for the "notify"
+      signal, although multiple notifications for a single property are
+      compressed. Signals can only be delayed by the notification freezing
+      mechanism.
+    </para>
+    
+    <para>
+      It sounds like a tedious task to set up GValues every time when one wants to modify a property.
+      In practice one will rarely do this. The functions <function><link linkend="g-object-set-property">g_object_set_property</link></function>
+      and <function><link linkend="g-object-get-property">g_object_get_property</link></function>
+      are meant to be used by language bindings. For application there is an easier way and
+      that is described next.
+    </para>
+
+    <sect2 id="gobject-multi-properties">
+      <title>Accessing multiple properties at once</title>
+  
+      <para>
+        It is interesting to note that the <function><link linkend="g-object-set">g_object_set</link></function> and 
+        <function><link linkend="g-object-set-valist">g_object_set_valist</link></function> (variadic version) functions can be used to set
+        multiple properties at once. The client code shown above can then be re-written as:
+<informalexample><programlisting>
+ViewerFile *file;
+file = /* */;
+g_object_set (G_OBJECT (file),
+              "zoom-level", 6, 
+              "filename", "~/some-file.txt", 
+              NULL);
+</programlisting></informalexample>
+        This saves us from managing the GValues that we were needing to handle when using
+        <function><link linkend="g-object-set-property">g_object_set_property</link></function>.
+        The code above will trigger one notify signal emission for each property modified.
+      </para>
+    
+      <para>
+        Equivalent <function>_get</function> versions are also available:
+        <function><link linkend="g-object-get">g_object_get</link></function>
+        and <function><link linkend="g-object-get-valist">g_object_get_valist</link></function> (variadic version) can be used to get numerous
+        properties at once.
+      </para>
+      
+      <para>
+        These high level functions have one drawback — they don't provide a return value.
+        One should pay attention to the argument types and ranges when using them.
+        A known source of errors is to pass a different type from what the
+        property expects; for instance, passing an integer when the property
+        expects a floating point value and thus shifting all subsequent parameters
+        by some number of bytes. Also forgetting the terminating
+        <literal>NULL</literal> will lead to undefined behaviour.
+      </para>
+    
+      <para>
+        This explains how <function><link linkend="g-object-new">g_object_new</link></function>,
+        <function><link linkend="g-object-newv">g_object_newv</link></function> and <function><link linkend="g-object-new-valist">g_object_new_valist</link></function> 
+        work: they parse the user-provided variable number of parameters and invoke
+        <function><link linkend="g-object-set">g_object_set</link></function> on the parameters only after the object has been successfully constructed.
+        The "notify" signal will be emitted for each property set.
+      </para>
+    
+    </sect2>
+
+<!-- @todo tell here about how to pass use handle properties in derived classes -->
+
+  </sect1>
+
+</chapter>

docs/reference/gobject/tut_gsignal.xml

@@ -0,0 +1,495 @@
+<?xml version='1.0' encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter id="chapter-signal">
+  <title>The GObject messaging system</title>
+
+  <sect1 id="closure">
+    <title>Closures</title>
+
+    <para>
+      Closures are central to the concept of asynchronous signal delivery
+      which is widely used throughout GTK+ and GNOME applications. A closure is an 
+      abstraction, a generic representation of a callback. It is a small structure
+      which contains three objects:
+      <itemizedlist>
+        <listitem><para>a function pointer (the callback itself) whose prototype looks like:
+<informalexample><programlisting>
+return_type function_callback (… , gpointer user_data);
+</programlisting></informalexample>
+        </para></listitem>
+        <listitem><para>
+           the <parameter>user_data</parameter> pointer which is passed to the callback upon invocation of the closure
+          </para></listitem>
+        <listitem><para>
+           a function pointer which represents the destructor of the closure: whenever the
+           closure's refcount reaches zero, this function will be called before the closure
+           structure is freed.
+          </para></listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      The <link linkend="GClosure"><type>GClosure</type></link> structure represents the common functionality of all
+      closure implementations: there exists a different closure implementation for
+      each separate runtime which wants to use the GObject type system.
+      <footnote><para>
+        In practice, closures sit at the boundary of language runtimes: if you are
+        writing Python code and one of your Python callbacks receives a signal from
+        a GTK+ widget, the C code in GTK+ needs to execute your Python
+        code. The closure invoked by the GTK+ object invokes the Python callback:
+        it behaves as a normal C object for GTK+ and as a normal Python object for
+        Python code.
+      </para></footnote>
+      The GObject library provides a simple <link linkend="GCClosure"><type>GCClosure</type></link> type which
+      is a specific implementation of closures to be used with C/C++ callbacks.
+    </para>
+    <para>
+      A <link linkend="GClosure"><type>GClosure</type></link> provides simple services:
+      <itemizedlist>
+        <listitem><para>
+          Invocation (<function><link linkend="g-closure-invoke">g_closure_invoke</link></function>): this is what closures 
+          were created for: they hide the details of callback invocation from the
+          callback invoker.</para>
+        </listitem>
+        <listitem><para>
+          Notification: the closure notifies listeners of certain events such as
+          closure invocation, closure invalidation and closure finalization. Listeners
+          can be registered with <function><link linkend="g-closure-add-finalize-notifier">g_closure_add_finalize_notifier</link></function>
+          (finalization notification), <function><link linkend="g-closure-add-invalidate-notifier">g_closure_add_invalidate_notifier</link></function> 
+          (invalidation notification) and 
+          <function><link linkend="g-closure-add-marshal-guards">g_closure_add_marshal_guards</link></function> (invocation notification).
+          There exist symmetric deregistration functions for finalization and invalidation
+          events (<function><link linkend="g-closure-remove-finalize-notifier">g_closure_remove_finalize_notifier</link></function> and
+          <function><link linkend="g-closure-remove-invalidate-notifier">g_closure_remove_invalidate_notifier</link></function>) but not for the invocation 
+          process.
+          <footnote><para>
+            Closures are reference counted and notify listeners of their destruction in a two-stage
+            process: the invalidation notifiers are invoked before the finalization notifiers.
+          </para></footnote></para>
+        </listitem>
+      </itemizedlist>
+    </para>
+
+    <sect2>
+      <title>C Closures</title>
+
+      <para>
+        If you are using C or C++
+        to connect a callback to a given event, you will either use simple <link linkend="GCClosure"><type>GCClosure</type></link>s
+        which have a pretty minimal API or the even simpler <function><link linkend="g-signal-connect">g_signal_connect</link></function> 
+        functions (which will be presented a bit later).
+      </para>
+
+      <para>
+        <function><link linkend="g-cclosure-new">g_cclosure_new</link></function> will create a new closure which can invoke the
+        user-provided callback_func with the user-provided
+        <parameter>user_data</parameter> as its last parameter. When the closure
+        is finalized (second stage of the destruction process), it will invoke
+        the <parameter>destroy_data</parameter> function if the user has
+        supplied one.
+      </para>
+  
+      <para>
+        <function><link linkend="g-cclosure-new-swap">g_cclosure_new_swap</link></function> will create a new closure which can invoke the
+        user-provided <parameter>callback_func</parameter> with the
+        user-provided <parameter>user_data</parameter> as its first parameter
+        (instead of being the 
+        last parameter as with <function><link linkend="g-cclosure-new">g_cclosure_new</link></function>). When the closure
+        is finalized (second stage of the destruction process), it will invoke
+        the <parameter>destroy_data</parameter> function if the user has
+        supplied one.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Non-C closures (for the fearless)</title>
+
+      <para>
+        As was explained above, closures hide the details of callback invocation. In C,
+        callback invocation is just like function invocation: it is a matter of creating
+        the correct stack frame for the called function and executing a <emphasis>call</emphasis>
+        assembly instruction.
+      </para>
+  
+      <para>
+        C closure marshallers transform the array of GValues which represent 
+        the parameters to the target function into a C-style function parameter list, invoke
+        the user-supplied C function with this new parameter list, get the return value of the
+        function, transform it into a GValue and return this GValue to the marshaller caller.
+      </para>
+
+      <para>
+        A generic C closure marshaller is available as
+        <link linkend="g-cclosure-marshal-generic"><function>g_cclosure_marshal_generic</function></link>
+        which implements marshalling for all function types using libffi. Custom
+        marshallers for different types are not needed apart from performance
+        critical code where the libffi-based marshaller may be too slow.
+      </para>
+
+      <para>
+        An example of a custom marshaller is given below, illustrating how
+        <type>GValue</type>s can be converted to a C function call. The
+        marshaller is for a C function which takes an integer as its first
+        parameter and returns void.
+<informalexample><programlisting>
+g_cclosure_marshal_VOID__INT (GClosure     *closure,
+                              GValue       *return_value,
+                              guint         n_param_values,
+                              const GValue *param_values,
+                              gpointer      invocation_hint,
+                              gpointer      marshal_data)
+{
+  typedef void (*GMarshalFunc_VOID__INT) (gpointer     data1,
+                                          gint         arg_1,
+                                          gpointer     data2);
+  register GMarshalFunc_VOID__INT callback;
+  register GCClosure *cc = (GCClosure*) closure;
+  register gpointer data1, data2;
+
+  g_return_if_fail (n_param_values == 2);
+
+  data1 = g_value_peek_pointer (param_values + 0);
+  data2 = closure->data;
+
+  callback = (GMarshalFunc_VOID__INT) (marshal_data ? marshal_data : cc->callback);
+
+  callback (data1,
+            g_marshal_value_peek_int (param_values + 1),
+            data2);
+}
+</programlisting></informalexample>
+      </para>
+  
+      <para>
+        There exist other kinds of marshallers, for example there is a generic
+        Python marshaller which is used by all Python closures (a Python closure
+        is used to invoke a callback written in Python). This Python marshaller
+        transforms the input GValue list representing the function parameters
+        into a Python tuple which is the equivalent structure in Python.
+      </para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="signal">
+    <title>Signals</title>
+
+    <para>
+      GObject's signals have nothing to do with standard UNIX signals: they connect 
+      arbitrary application-specific events with any number of listeners.
+      For example, in GTK+, every user event (keystroke or mouse move) is received
+      from the windowing system and generates a GTK+ event in the form of a signal emission
+      on the widget object instance.
+    </para>
+
+    <para>
+      Each signal is registered in the type system together with the type on which
+      it can be emitted: users of the type are said to <emphasis>connect</emphasis>
+      to the signal on a given type instance when they register a closure to be  
+      invoked upon the signal emission. The closure will be called synchronously on emission.
+      Users can also emit the signal by themselves or stop the emission of the signal from
+      within one of the closures connected to the signal.
+    </para>
+
+    <para>
+      When a signal is emitted on a given type instance, all the closures
+      connected to this signal on this type instance will be invoked. All the closures
+      connected to such a signal represent callbacks whose signature looks like:
+<informalexample><programlisting>
+return_type function_callback (gpointer instance, …, gpointer user_data);
+</programlisting></informalexample>
+    </para>
+
+    <sect2 id="signal-registration">
+      <title>Signal registration</title>
+
+	  <para>
+		To register a new signal on an existing type, we can use any of <function><link linkend="g-signal-newv">g_signal_newv</link></function>,
+		<function><link linkend="g-signal-new-valist">g_signal_new_valist</link></function> or <function><link linkend="g-signal-new">g_signal_new</link></function> functions:
+<informalexample><programlisting>
+guint g_signal_newv (const gchar        *signal_name,
+                     GType               itype,
+                     GSignalFlags        signal_flags,
+                     GClosure           *class_closure,
+                     GSignalAccumulator  accumulator,
+                     gpointer            accu_data,
+                     GSignalCMarshaller  c_marshaller,
+                     GType               return_type,
+                     guint               n_params,
+                     GType              *param_types);
+</programlisting></informalexample>
+		The number of parameters to these functions is a bit intimidating but they are relatively
+		simple:
+		<itemizedlist>
+		  <listitem><para>
+			  <parameter>signal_name</parameter>: is a string which can be used to uniquely identify a given signal.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>itype</parameter>: is the instance type on which this signal can be emitted.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>signal_flags</parameter>: partly defines the order in which closures which were connected to the
+			  signal are invoked.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>class_closure</parameter>: this is the default closure for the signal: if it is not NULL upon
+			  the signal emission, it will be invoked upon this emission of the signal. The 
+			  moment where this closure is invoked compared to other closures connected to that 
+			  signal depends partly on the signal_flags.
+			</para></listitem>
+			<listitem><para>
+			  <parameter>accumulator</parameter>: this is a function pointer which is invoked after each closure
+			  has been invoked. If it returns FALSE, signal emission is stopped. If it returns
+			  TRUE, signal emission proceeds normally. It is also used to compute the return
+			  value of the signal based on the return value of all the invoked closures.
+			  For example, an accumulator could ignore
+			  <literal>NULL</literal> returns from closures; or it
+			  could build a list of the values returned by the
+			  closures.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>accu_data</parameter>: this pointer will be passed down to each invocation of the
+			  accumulator during emission.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>c_marshaller</parameter>: this is the default C marshaller for any closure which is connected to
+			this signal.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>return_type</parameter>: this is the type of the return value of the signal.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>n_params</parameter>: this is the number of parameters this signal takes.
+			</para></listitem>
+		  <listitem><para>
+			  <parameter>param_types</parameter>: this is an array of GTypes which indicate the type of each parameter
+			  of the signal. The length of this array is indicated by n_params.
+			</para></listitem>
+		</itemizedlist>
+      </para>
+
+	  <para>
+		As you can see from the above definition, a signal is basically a description
+		of the closures which can be connected to this signal and a description of the
+		order in which the closures connected to this signal will be invoked.
+	  </para>
+
+	</sect2>
+
+	<sect2 id="signal-connection">
+	  <title>Signal connection</title>
+
+	  <para>
+		If you want to connect to a signal with a closure, you have three possibilities:
+		<itemizedlist>
+		  <listitem><para>
+		  You can register a class closure at signal registration: this is a
+		  system-wide operation. i.e.: the class closure will be invoked during each emission
+		  of a given signal on <emphasis>any</emphasis> of the instances of the type which supports that signal.
+			</para></listitem>
+		  <listitem><para>
+		  You can use <function><link linkend="g-signal-override-class-closure">g_signal_override_class_closure</link></function> which
+		  overrides the class closure of a given type. It is possible to call this function
+		  only on a derived type of the type on which the signal was registered.
+		  This function is of use only to language bindings.
+			</para></listitem>
+		  <listitem><para>
+		  You can register a closure with the <function><link linkend="g-signal-connect">g_signal_connect</link></function>
+		  family of functions. This is an instance-specific operation: the closure
+		  will be invoked only during emission of a given signal on a given instance.
+			</para></listitem>
+		</itemizedlist>
+		It is also possible to connect a different kind of callback on a given signal: 
+		emission hooks are invoked whenever a given signal is emitted whatever the instance on 
+		which it is emitted. Emission hooks are used for example to get all mouse_clicked
+		emissions in an application to be able to emit the small mouse click sound.
+		Emission hooks are connected with <function><link linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link></function>
+		and removed with <function><link linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link></function>.
+	  </para>
+
+	</sect2>
+
+	<sect2 id="signal-emission">
+	  <title>Signal emission</title>
+
+	  <para>
+		Signal emission is done through the use of the <function><link linkend="g-signal-emit">g_signal_emit</link></function> family 
+		of functions.
+<informalexample><programlisting>
+void g_signal_emitv (const GValue *instance_and_params,
+                     guint         signal_id,
+                     GQuark        detail,
+                     GValue       *return_value);
+</programlisting></informalexample>
+		<itemizedlist>
+		  <listitem><para>
+			The <parameter>instance_and_params</parameter> array of GValues contains the list of input
+			parameters to the signal. The first element of the array is the 
+			instance pointer on which to invoke the signal. The following elements of
+			the array contain the list of parameters to the signal.
+			</para></listitem>
+		  <listitem><para>
+			<parameter>signal_id</parameter> identifies the signal to invoke.
+			</para></listitem>
+		  <listitem><para>
+			<parameter>detail</parameter> identifies the specific detail of the signal to invoke. A detail is a kind of 
+			magic token/argument which is passed around during signal emission and which is used
+			by closures connected to the signal to filter out unwanted signal emissions. In most 
+			cases, you can safely set this value to zero. See <xref linkend="signal-detail"/> for
+			more details about this parameter.
+			</para></listitem>
+		  <listitem><para>
+			<parameter>return_value</parameter> holds the return value of the last closure invoked during emission if
+			no accumulator was specified. If an accumulator was specified during signal creation,
+			this accumulator is used to calculate the return value as a function of the return
+			values of all the closures invoked during emission. 
+			If no closure is invoked during
+			emission, the <parameter>return_value</parameter> is nonetheless initialized to zero/null.
+			</para></listitem>
+		  </itemizedlist>
+		</para>
+
+	  <para>
+		Signal emission is done synchronously and can be decomposed in 5 steps:
+		<orderedlist>
+		  <listitem><para>
+			<literal>RUN_FIRST</literal>: if the
+			<link linkend="G-SIGNAL-RUN-FIRST:CAPS"><literal>G_SIGNAL_RUN_FIRST</literal></link> flag was used
+			during signal registration and if there exists a class closure for this signal,
+			the class closure is invoked.
+			</para></listitem>
+		  <listitem><para>
+			<literal>EMISSION_HOOK</literal>: if any emission hook was added to
+			the signal, they are invoked from first to last added. Accumulate return values.
+			</para></listitem>
+		  <listitem><para>
+			<literal>HANDLER_RUN_FIRST</literal>: if any closure were connected
+			with the <function><link linkend="g-signal-connect">g_signal_connect</link></function> family of 
+			functions, and if they are not blocked (with the <function><link linkend="g-signal-handler-block">g_signal_handler_block</link></function>
+			family of functions) they are run here, from first to last connected.
+			</para></listitem>
+		  <listitem><para>
+			<literal>RUN_LAST</literal>: if the <literal>G_SIGNAL_RUN_LAST</literal>
+			flag was set during registration and if a class closure
+			was set, it is invoked here.
+			</para></listitem>
+		  <listitem><para>
+			<literal>HANDLER_RUN_LAST</literal>: if any closure were connected
+			with the <function>g_signal_connect_after</function> family of 
+			functions, if they were not invoked during <literal>HANDLER_RUN_FIRST</literal> and if they 
+			are not blocked, they are run here, from first to last connected.
+			</para></listitem>
+		  <listitem><para>
+			<literal>RUN_CLEANUP</literal>: if the <literal>G_SIGNAL_RUN_CLEANUP</literal> flag
+			was set during registration and if a class closure was set,
+			it is invoked here. Signal emission is completed here.
+			</para></listitem>
+		</orderedlist>
+	  </para>
+  
+	  <para>
+		If, at any point during emission (except in <literal>RUN_CLEANUP</literal> or
+		<literal>EMISSION_HOOK</literal> state), one of the closures stops the signal emission with
+		<function><link linkend="g-signal-stop-emission">g_signal_stop_emission</link></function>,
+		emission jumps to <literal>RUN_CLEANUP</literal> state.
+	  </para>
+  
+	  <para>
+		If, at any point during emission, one of the closures or emission hook 
+		emits the same signal on the same instance, emission is restarted from
+		the <literal>RUN_FIRST</literal> state.
+	  </para>
+  
+	  <para>
+		The accumulator function is invoked in all states, after invocation
+		of each closure (except in <literal>RUN_EMISSION_HOOK</literal> and
+		<literal>RUN_CLEANUP</literal>). It accumulates
+		the closure return value into the signal return value and returns TRUE or
+		FALSE. If, at any point, it does not return TRUE, emission jumps
+		to <literal>RUN_CLEANUP</literal> state.
+	  </para>
+
+	  <para>
+		If no accumulator function was provided, the value returned by the last handler
+		run will be returned by <function><link linkend="g-signal-emit">g_signal_emit</link></function>.
+	  </para>
+
+	</sect2>
+
+
+	<sect2 id="signal-detail">
+	  <title>The <emphasis>detail</emphasis> argument</title>
+
+	  <para>All the functions related to signal emission or signal connection have a parameter
+		named the <emphasis>detail</emphasis>. Sometimes, this parameter is hidden by the API
+		but it is always there, in one form or another. 
+	  </para>
+
+	  <para>
+	    Of the three main connection functions,
+		only one has an explicit detail parameter as a <link linkend="GQuark"><type>GQuark</type></link>:
+		<link linkend="g-signal-connect-closure-by-id"><function>g_signal_connect_closure_by_id</function></link>.
+		<footnote>
+		  <para>A GQuark is an integer which uniquely represents a string. It is possible to transform
+		   back and forth between the integer and string representations with the functions 
+		   <function><link linkend="g-quark-from-string">g_quark_from_string</link></function> and <function><link linkend="g-quark-to-string">g_quark_to_string</link></function>.
+		  </para>
+		</footnote>
+	  </para>
+	  <para>
+	    The two other functions,
+	    <link linkend="g-signal-connect-closure"><function>g_signal_connect_closure</function></link> and
+	    <link linkend="g-signal-connect-data"><function>g_signal_connect_data</function></link>
+	    hide the detail parameter in the signal name identification.
+		Their <parameter>detailed_signal</parameter> parameter is a
+		string which identifies the name of the signal to connect to.
+		The format of this string should match
+		<emphasis>signal_name::detail_name</emphasis>. For example,
+		connecting to the signal named
+		<emphasis>notify::cursor_position</emphasis> will actually
+		connect to the signal named <emphasis>notify</emphasis> with the
+		<emphasis>cursor_position</emphasis> detail.
+		Internally, the detail string is transformed to a GQuark if it is present.
+	  </para>
+
+	  <para>
+	    Of the four main signal emission functions, one hides it in its
+	    signal name parameter:
+	    <link linkend="g-signal-connect"><function>g_signal_connect</function></link>.
+	    The other three have an explicit detail parameter as a
+	    <link linkend="GQuark"><type>GQuark</type></link> again:
+	    <link linkend="g-signal-emit"><function>g_signal_emit</function></link>,
+	    <link linkend="g-signal-emitv"><function>g_signal_emitv</function></link> and
+	    <link linkend="g-signal-emit-valist"><function>g_signal_emit_valist</function></link>.
+	  </para>
+
+	  <para>
+        If a detail is provided by the user to the emission function, it is used during emission to match
+        against the closures which also provide a detail.
+        If a closure's detail does not match the detail provided by the user, it
+        will not be invoked (even though it is connected to a signal which is
+        being emitted).
+	  </para>
+
+	  <para>
+		This completely optional filtering mechanism is mainly used as an optimization for signals
+		which are often emitted for many different reasons: the clients can filter out which events they are
+		interested in before the closure's marshalling code runs. For example, this is used extensively
+		by the <link linkend="GObject-notify"><structfield>notify</structfield></link> signal of GObject: whenever a property is modified on a GObject,
+		instead of just emitting the <emphasis>notify</emphasis> signal, GObject associates as a detail to this
+		signal emission the name of the property modified. This allows clients who wish to be notified of changes
+		to only one property to filter most events before receiving them.
+	  </para>
+
+	  <para>
+		As a simple rule, users can and should set the detail parameter to zero: this will disable completely
+        this optional filtering for that signal.
+	  </para>
+
+	</sect2>
+
+  </sect1>
+</chapter>
+