GApplication: fix bogus testcase

We had a GApplication testcase that handled both open and commandline.
This only way that this worked was by implementing the commandline
handler without actually setting the HANDLES_COMMAND_LINE flag.

This behaviour is now invalid, so just rip out the offending part of the
test.

https://bugzilla.gnome.org/show_bug.cgi?id=711099

appinfo: Add some testcases for searching

https://bugzilla.gnome.org/show_bug.cgi?id=711557

Add g_desktop_app_info_search()

The first time this function is called we load all of the keyfiles in
the directory, ignoring the 'Hidden' ones and build an index out of the
interesting fields using g_str_tokenize_and_fold().

We do prefix matching on the tokens to find relevent desktop files.

Right now this is implemented as a hashtable that we iterate over,
checking prefixes on each token.  This could possibly be sped up by
creating an array, but it's already pretty fast...

https://bugzilla.gnome.org/show_bug.cgi?id=711557

gio/Makefile: make sure to dist gappinfoprivate.h

gio: Add gappinfoprivate.h to Makefile.am

In addition to e55d33edc1336ddc6d5cdfa0e3003a69a5812d26

Updated Greek translation

configure: test(1) uses = to test for string equality

https://bugzilla.gnome.org/show_bug.cgi?id=711600

codegen.py: Rearrange GLib Version Check

...so that the generated code will build on all platforms, as compilers
like Visual C++ does not like #ifdef checks during a definition/use of
a macro.

https://bugzilla.gnome.org/show_bug.cgi?id=711049

Add GAppInfoMonitor

This is a simple object that emits a "change" signal when the installed
applications may have changed in some way.

https://bugzilla.gnome.org/show_bug.cgi?id=711556

gdesktopappinfo: keep a list of files in the dirs

In each DesktopFileDir, store a list of desktop files for that
directory.  This speeds up opening desktop files by name because we can
skip statting in directories that we know don't have the file and also
speeds up _get_all() because we can avoid enumeration.

This also improves our support for dealing with names like
'kde4/kate.desktop' (equivalent to kde4-kate.desktop) since we find out
about all of these files are the start and don't need to guess about
which '-' to change to a '/'.  It also means that we can easily deal
with more than one level of such prefixes.

We use a file monitor to watch for changes, invalidating our lists when
we notice them.

https://bugzilla.gnome.org/show_bug.cgi?id=711520

signals: Fix memory leaks in signals unit tests

https://bugzilla.gnome.org/show_bug.cgi?id=627423

qdata: Fix leak in qdata unit tests

https://bugzilla.gnome.org/show_bug.cgi?id=627423

gerror: Don't leak when warning about overwriting an error

While not strictly necessary, this fixes a false positive
leak in the tests.

https://bugzilla.gnome.org/show_bug.cgi?id=627423

tests: fix leak in mainloop test

Properly unref a pair of GSources in the unix-fd mainloop test.

valgrind was reporting these as 'still reachable' before (possibly due
to some residual pointers somewhere in memory), but when running with
G_DEBUG=cleanup they were properly reported as leaked.

grand: restructure a bit

Instead of having lots of 'if NULL then allocate' code segments for the
global GRand instance, move it to a single getter function that everyone
calls.

gslice: don't misuse g_mutex_init()

We were using g_mutex_init() to initialise a pair of mutexes in static
storage, but we should only do that for mutexes that are part of
allocated structures.

garray: Note lack of bounds checking in g_ptr_array_index() documentation

gio/tests: Clean up inclusion of unistd.h

Include unistd.h only on *NIX and define items as necessary on Windows,
also replace instances of ssize_t with the GLib-equivilant gssize so to fix
the build on platforms that do not have ssize_t, such as Visual C++.

https://bugzilla.gnome.org/show_bug.cgi?id=711047

glib/tests: Clean up inclusion of unistd.h

Include unistd.h only when G_OS_UNIX is defined (or when G_OS_WIN32 is not
defined).  This will avoid including unistd.h unconditionally and/or
unecessarily, which may cause problems in certain scenarios, such as when
building the tests on Visual C++, which does not come with a unistd.h and
MinGW, where unistd.h is essentially a wrapper for io.h and process.h.

https://bugzilla.gnome.org/show_bug.cgi?id=711047

glib/tests/fileutils.c: Include unistd.h on *NIX only

...and fix the test on non-English Windows, as gettext on Windows does
not honor LC_ALL = "C" (the default CRT behavior) but requires using
SetThreadLocale() to set the locale as it picks up the user's environment
and the thread's locale.  Without doing so the g_format_size_for_display()
et al will display the translated message if the gettext translations have
been installed before, causing the test_format_size_for_display tests to
fail.

https://bugzilla.gnome.org/show_bug.cgi?id=711047

tests/libmoduletestplugins*.c: Update Prototypes

Visual C++ does not like function declarations being different from
their prototypes, so make the prototypes match the declarations by
decorating them with G_MODULE_EXPORT.

https://bugzilla.gnome.org/show_bug.cgi?id=711047

gio/test/resources.c: Fix for Windows

We need to use g_content_type_get_mime_type() to look up the mime type of
the file from the registry on the content type that was acquired on
Windows, as g_file_info_get_content_type() does not acquire the
file mime type (unlike on *NIX).

g_content_type_get_mime_type() on *NIX is more or less an no-op as it
simply returns the g_strdup()-ed version of the passed-in content type.

This will enable the resources test to pass on Windows.

https://bugzilla.gnome.org/show_bug.cgi?id=711047

gmain: make g_source_add_child_source() thread safe

g_source_add_child_source() releases the context lock before attaching
child_source to context. And this causes trouble if parent source is
blocked and g_main_dispatch() manages to lock the context mutex and call
unblock_source() before child_source gets attached to context.
To fix this we call g_source_attach_unlocked() before releasing the
context mutex.

https://bugzilla.gnome.org/show_bug.cgi?id=711064

gio: Don't allow skipping past the end of GLocalFileInputStream

The overridden implementation of the skip method for
GLocalFileInputStream allows skipping past the end of the file which is
inconsistent with the documentation.  Prevent this by first seeking to
the end of the file and then seeking backwards from there as much as
is necessary.

https://bugzilla.gnome.org/show_bug.cgi?id=711048

gmacros.h: fix C99 check

G_STRFUNC was checking __STDC_VERSION__ against the wrong value
(though it didn't actually matter, since __STDC_VERSION__ wasn't
defined in C90, so the check still only matched C99 and above anyway).

Updated Galician translations

Updated Galician translations

Updated Spanish translation

docs: GDataTime: *_add_*(): Mention that you can subtract.

Because this was not obvious to at least one person on irc.

gio: Clean up trashinfo file if trashing fails

https://bugzilla.gnome.org/show_bug.cgi?id=687202

Tests: It is useless to unset "DBUS_SESSION_BUS_ADDRESS" manually

If the goal is to make sure we don't have a dbus connection, it has
to call g_test_dbus_unset() instead which is much more complete.

In this case, g_test_dbus_unset() is called already, so it should be
fine.

https://bugzilla.gnome.org/show_bug.cgi?id=697348

GTestDBus: Make sure only DBUS_SESSION_BUS_ADDRESS is set by default

g_test_dbus_unset() now also unset DBUS_STARTER_ADDRESS and
DBUS_STARTER_BUS_TYPE.

https://bugzilla.gnome.org/show_bug.cgi?id=697348

Tests: add session_bus_run() and use it where possible

This is to avoid having again the subtil bug in dbus-appinfo.c:
session_bus_down() was called before g_test_run() so the test was
running on the user's dbus session.

https://bugzilla.gnome.org/show_bug.cgi?id=697348

tests/gdbus-introspection: Add a less trivial test case for _IGNORE_QUALIFIED

This is distilled from PackageKit which currently aborts on startup.

https://bugzilla.gnome.org/show_bug.cgi?id=665634

GMarkup: clear attributes on ignorned tags

Make sure that if we ignore a tag then we also clear the attributes that
we already collected so that they don't end up on the next unignored tag
opening.

Also add some extra brackets for clarity (it doesn't make any difference
-- I just think it reads nicer this way).

https://bugzilla.gnome.org/show_bug.cgi?id=665634

gtk-notification-backend: remove unused variable

A reference to the session bus is now stored in GNotificationBackend.
Remove the extraneous one in the gtk backend and stop using it in
withdraw_notification.

https://bugzilla.gnome.org/show_bug.cgi?id=711051

gio: Clear error properly to prevent crash

https://bugzilla.gnome.org/show_bug.cgi?id=711070

GCancellable: drop lock for callback during connect()

Don't hold the lock when calling the user's callback during
g_cancellable_connect() for the case that the cancellable has already
fired.

Taken from a patch by Alex Larsson.

Doc updates from Colin Walters.

https://bugzilla.gnome.org/show_bug.cgi?id=705395

gio/gsubprocess.c: Use g_snprintf()

snprintf() is unfortunately still not universally available, so use
g_snprintf() to ensure the build works on all platforms.

https://bugzilla.gnome.org/show_bug.cgi?id=711049

gobject/gvaluetransform.c: Cleanup #ifndef _MSC_VER

The two casts that were unsupported with Visual Studio is now properly
supported, so build this code like how the other compilers build the code.

GSettingsSchemaSource: fix parameter name in header

list_schemas() had the parameters called 'recursive' and 'non-recursive'
in the header instead of 'relocatable'.  Fix that.

exporter: give error on Describe of missing action

If someone calls org.gtk.Actions.Describe on a non-existent action then
return an exception instead of a trivial description (disabled, no
state, etc.).

https://bugzilla.gnome.org/show_bug.cgi?id=687185

exporter: give error on Describe of missing action

If someone calls org.gtk.Actions.Describe on a non-existent action then
return an exception instead of a trivial description (disabled, no
state, etc.).

https://bugzilla.gnome.org/show_bug.cgi?id=687185

GSimpleAction: don't allow changing state type

g_object_set() allowed us to bypass the usual checks that the state
doesn't change type and also leaked.

Fix that up by turning the state into a construct property (so that it
always gets set once during construction, even if only to NULL) and
then route the further sets through the C API so that they are subject
to the same checks.

https://bugzilla.gnome.org/show_bug.cgi?id=696424

glib-compile-schemas: ignore qualified tags/attrs

Ignore qualified (in the XML namespace sense) tags and attributes when
compiling GSettings schemas.

This will allow people to add custom tags and attributes to their schemas
without tripping up the compiler.

https://bugzilla.gnome.org/show_bug.cgi?id=635641

GDBus: ignore qualified XML tags and attributes

Ignore qualified (in the XML namespace sense) tags and attributes when
parsing D-Bus introspection XML.

This will allow people to add custom tags and attributes to their D-Bus
interfaces without tripping up GDBus.

https://bugzilla.gnome.org/show_bug.cgi?id=665634

tests: add a ignore-qualified markup-collect case

Add a case to markup-collect that exercises the new IGNORE_QUALIFIED
flag.

https://bugzilla.gnome.org/show_bug.cgi?id=665634

GMarkup: add G_MARKUP_IGNORE_QUALIFIED

Add a flag to GMarkupParserFlags to ignore qualified tags (along with
their contents) and attributes.

This will provide a nice way for some of our parsers (GDBus
introspection, GSettings schema, etc) to ignore additional tags that
users have added to their files, under a different namespace.

https://bugzilla.gnome.org/show_bug.cgi?id=665634

GMarkup: share some common code for closing tags

The code for dealing with </foo> and the second half of <foo/> was
largely duplicated.  We can share a lot of it by using a common
function.

This slightly changes the behaviour of the parser under error
circumstances: previously the parser would deal with '<foo/}' by first
issuing the end_element callback and then flagging the error due to the
unexpected character.  Now we will flag the unexpected character error
first, skipping the callback.

This behaviour change required modifying the testsuite.

https://bugzilla.gnome.org/show_bug.cgi?id=665634

test: g_debug messages shouldn't affect g_assert_expected_messages

Debug messages are meant to give insight into how a process is
proceeding, and are unpredictable in nature. They also often have
line numbers in them.

This patch ignores debug messages in g_test_assert_expected_messages().

https://bugzilla.gnome.org/show_bug.cgi?id=710991

GSettings: fix for loop in 'extends' functionality

Obvious mistake :(

gsettings(1): stop using deprecated APIs

Stop using the recently-deprecated GSettings APIs.

Use the GSettingsSchema-based APIs instead.

This fixes a number of bugs and also a net reduction of code. In
particular, list-schemas will now work in context of a given --schemadir
argument.

https://bugzilla.gnome.org/show_bug.cgi?id=695558

gsettings(1): use global variables

The number of arguments passed to each function is about to increase, so
just use global variables instead.

This is a commandline tool, after all...

https://bugzilla.gnome.org/show_bug.cgi?id=695558

GSettingsSchemaKey: add introspection APIs

Add g_settings_schema_has_key() and _get_range(), _range_check(),
_get_value_type(), _get_default_value() methods on GSettingsSchemaKey.

Deprecate the equivalent APIs on GSettings.

https://bugzilla.gnome.org/show_bug.cgi?id=683017

bump version

dconf needs the new version with read_user_value() on the backend API.

GSettings: add getters for user/default value

Add two new APIs: g_settings_get_user_value() and
g_settings_get_default_value().   Together, these should allow the
inspection of all interesting cases of "is this key set?" and "what
would happen if I reset this key?"

https://bugzilla.gnome.org/show_bug.cgi?id=668233

GSettings: small internal refactor

Add two boolean parameters to our internal getter utility function in
anticipation of the coming addition of g_settings_get_user_value() and
g_settings_get_default_value() APIs.

https://bugzilla.gnome.org/show_bug.cgi?id=668233

GSettingsBackend: add read_user_value() API

This will get the 'user' value from the database (ie: the one that the user has
control over).

Provide a default implementation that chains to ->read().  That will work for
all of our internal backends which don't have a concept of layering or
lockdown.

The delayed backend implments "user value" by returning anything that's
in the changeset (incuding an explicit NULL) or chaining up otherwise.

We will use this for g_settings_get_user_value().

https://bugzilla.gnome.org/show_bug.cgi?id=668233

gio: Remove an unused variable from Makefile.am

RESOLVER_LIBADD was not defined anywhere (its functionality has
migrated to NETWORK_LIBS instead).

docs: Mention that generated code should not be kept

Code generated by gdbus-codegen should neither be checked in into
revision control, nor should be distributed.

https://bugzilla.gnome.org/show_bug.cgi?id=710133

gdbus-codegen maintains ABI for type structures

Make it explicit, to avoid changes that could potentially lead to
breakage in user code.

https://bugzilla.gnome.org/show_bug.cgi?id=710133

gdbus-codegen: Take into consideration MAX_ALLOWED for private data

The G_ADD_PRIVATE() macro, and the auto-generated get_instance_private()
internal function, should be used conditionally depending on the maximum
allowed version of GLib, as defined by the GLIB_VERSION_MAX_ALLOWED
pre-processor symbol.

This allows generating code that can be compiled in projects that wish
to use an older API version of GLib through the use of the
GLIB_VERSION_MAX_ALLOWED symbol.

https://bugzilla.gnome.org/show_bug.cgi?id=710133

g_settings_schema_list: some fixes

Prevent a crash in the case that gvdb_table_list() returns NULL (ie:
because a schema has no keys).

Stop a memory leak caused by pointlessly stealing keys from a hashtable
(after we quarked them already).

Stop allocating an extra entry at the end of an array for a terminator
(that we never wrote anyway) when all functions using this API refer to
the out-parameter length array.

https://bugzilla.gnome.org/show_bug.cgi?id=711016

Fix handling of icons in GNotification

The fdo backend was sending a uri where a file path
was expected.

Add a request_certificate virtual method to GTlsInteraction

This allows GTlsConnection implementations to request a certificate
from the user.

Fix ups by Dan Winship <danw@gnome.org>

https://bugzilla.gnome.org/show_bug.cgi?id=637257

GKeyFileSettingsBackend: ignore file deletions

Ignore the keyfile being deleted (ie: by the user) instead of reporting
it to the application as all values being reverted back to their
originals.

https://bugzilla.gnome.org/show_bug.cgi?id=637956

Add test for extended schemas

The test checks that the keys of the base schema are all present in
the extended schema.

https://bugzilla.gnome.org/show_bug.cgi?id=645453

GSettings: properly support 'extends'

Support the 'extends' attribute that has been supported by the compiler
for a long time by doing three things:

 - when creating a schema that extends another schema, lookup that other
   schema

 - when looking up keys and we can't find them in the schema, check
   (recursively) in the 'extends' schema

 - when listing all keys in a schema, also visit the extends schemas,
   but take care to avoid duplicates caused by overrides

Extend the testsuite to verify that it works.

https://bugzilla.gnome.org/show_bug.cgi?id=645453

gio: Fix typo in documentation

https://bugzilla.gnome.org/show_bug.cgi?id=710859

Add g_settings_schema_source_list_schemas()

g_settings_list_schemas() and g_settings_list_relocatable_schemas() are
now deprecated.

This will allow listing off schemas on non-default sources and is a
better fit with the new direction the API is going.

https://bugzilla.gnome.org/show_bug.cgi?id=680838

gsubprocess: Add documentation about default input directions

gsubprocess: Fall back to plain F_DUPFD+fcntl for OS X <= Snow Lion

Since it apparently doesn't have F_DUPFD_CLOEXEC.

https://bugzilla.gnome.org/show_bug.cgi?id=710962

Add a testcase for summary/description

https://bugzilla.gnome.org/show_bug.cgi?id=668232

Add g_settings_schema_key_get_summary/description

Add an API to read the summary and description from the .xml schema
files.

This will be used by dconf-editor and gnome-tweak-tool.

This API is a bit heavy -- it parses the XML and builds a table.  It
also loads gettext domains for translation.  It only does these things
if it is used, however, so it will not impact normal applications.

We store the summary/description in a pair of hash tables on the schema
source (which we have a backref to as of a few commits ago).  We can't
use a global table because people might want to request summary and
description from non-default sources.  We don't want to use per-schema
tables because we'd have to reparse the directory every time (since we
cannot guess which file a schema may have been in).

https://bugzilla.gnome.org/show_bug.cgi?id=668232

Make GSettingsSchemaKey public

Take this private API and make it public along with a boxed type and
ref/unref functions.

Future commits will add accessors with new functionality and some that
allow us to deprecate functions on GSettings itself (such as
g_settings_get_range).

https://bugzilla.gnome.org/show_bug.cgi?id=668232

GSettingsSchema: store a backref to the source

Record in each GSettingsSchema object the source from which it came.

This will be useful in future commits.

https://bugzilla.gnome.org/show_bug.cgi?id=668232

Clean up GSettingsSchema logic

The way we created the global schema list predates
g_settings_schema_source_new_from_directory() and therefore doesn't use
it.

Update it to use that function, removing some code.

https://bugzilla.gnome.org/show_bug.cgi?id=668232

tests: test g_hash_table_get_keys_as_array()

https://bugzilla.gnome.org/show_bug.cgi?id=710964

Add g_hash_table_get_keys_as_array()

Returns a %NULL-terminated array of the keys of a hashtable.

In the case that the hash table has strings for keys, this is actually a
gchar**.

https://bugzilla.gnome.org/show_bug.cgi?id=710964

gapplication: don't emit warnings for DBus calls

If a broken (or malicious) remote client calls Open or CommandLine
on a GApplication that does not implement those, return a DBus
error instead of going through and then emitting a warning.

https://bugzilla.gnome.org/show_bug.cgi?id=710885

gapplication: fix memory leak

g_variant_get_child_value() returns a new GVariant, which we must
free.

https://bugzilla.gnome.org/show_bug.cgi?id=710885

win32: use real random data for seed on win32

We can get cryptographically secure data from rand_s().

https://bugzilla.gnome.org/show_bug.cgi?id=710738

Assamese translation updated

GLib 2.39.0

docs: dist manpage gapplication.xml

tests: Add tests for the thumbnail verification code in GIO

This code was added for use by the G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID
file attribute, but may end up being used elsewhere (e.g. in GVfs) as well.
As it’s dealing with untrusted external files, and the non-trivial PNG file
format, this commit adds several test cases to cover valid and invalid PNG
files.

The security model for the thumbnail verification code is that the user’s
cache directory is untrusted, and potentially any PNG file which is passed
to the verifier has been manipulated arbitrarily by an attacker.

This is a follow-up to commit fe7069749fe39a006985ec266260a3c02ee8c855.

https://bugzilla.gnome.org/show_bug.cgi?id=709898

Revert "Use g_return_val_if_fail() for developer-only messages"

This reverts commit 00f0795a84d23f2e2654a86f8bd3a233c8af3771.

https://bugzilla.gnome.org/show_bug.cgi?id=569017

gsettings-tool: Add --version into general usage

https://bugzilla.gnome.org/show_bug.cgi?id=707002

GSettings: verify path validity on constructors

Don't allow constructing GSettings objects with invalid paths.

https://bugzilla.gnome.org/show_bug.cgi?id=704802

gthemedicon: Fallback to non-symbolic icons

When doing fallback for symbolic icons, we first shorten the name at dashes
while preserving the -symbolic suffix. But after exhausting that, we should also
try stripping the suffix.

See https://bugzilla.gnome.org/show_bug.cgi?id=708163

Signed-off-by: Olivier Brunel <jjk@jjacky.com>
https://bugzilla.gnome.org/show_bug.cgi?id=710254

grand: Document this is not for cryptographic purposes

While this is obvious to seasoned experts upon inspection, it is
really worth documenting explicitly.

https://bugzilla.gnome.org/show_bug.cgi?id=710736

gdbus: Ensure message matching always succeeds against path_namespace='/'

This copies the fix from upstream D-Bus bug
https://bugs.freedesktop.org/show_bug.cgi?id=70799 to the GDBusDaemon
implementation, ensuring that matching against path_namespace='/' succeeds
for all keys (i.e. it’s a no-op).

https://bugzilla.gnome.org/show_bug.cgi?id=710726

gtester: only remove source if not already dead

Don't attempt to g_source_remove() a source for which we already returned FALSE
from the handler.

https://bugzilla.gnome.org/show_bug.cgi?id=710724

tests: expect critical on failure to remove source

We've added a g_critical() on failure to remove sources, so make sure we
expect to see that (instead of failing the test due to the unexpected
message).

https://bugzilla.gnome.org/show_bug.cgi?id=710724

gmain: test g_source_remove() with invalid ID

Make sure we get the proper critical displayed.

https://bugzilla.gnome.org/show_bug.cgi?id=710724

gmain: Warn when g_source_remove() fails

Trying to remove a non-existent source should really be
a programming error, as the programmer could be trying to
use the wrong function to remove a callback, as seen when
GtkScrolledWindow tried to remove ID from another function
using g_source_remove().

See https://bugzilla.gnome.org/show_bug.cgi?id=710666#c12

https://bugzilla.gnome.org/show_bug.cgi?id=710724

file-info: Add a G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID attribute

This indicates whether the thumbnail (given by G_FILE_ATTRIBUTE_THUMBNAIL_PATH)
is valid — i.e. to represent the file in its current state. If
G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID is FALSE (for a normal _or_ failed
thumbnail) it means the file has changed since the thumbnail was generated, and
the thumbnail is out of date.

Part of checking thumbnail validity (by the spec) involves parsing
headers out of the thumbnail .png so we include some (small) code to do
that in a separate file.  We will likely want to copy this code to gvfs
to do the same for GVfsFile.

Heavily based on a patch from Philip Withnall <philip.withnall@collabora.co.uk>
who suggested the feature and designed the API.

https://bugzilla.gnome.org/show_bug.cgi?id=709898

GMemoryOutputStream: docs and whitespace fixes

Document the difference between resizable and fixed-sized streams,
particularly with regards to sizing and seeking.

https://bugzilla.gnome.org/show_bug.cgi?id=684842

GMemoryOutputStream: improve seek tests

Improve test coverage for testing seeking on fixed vs. resizable
GMemoryOutputStream.

https://bugzilla.gnome.org/show_bug.cgi?id=684842

Change semantics of seek on memory output stream

It is our intention that memory output streams should operate in two
distinct modes, depending on if a realloc function was provided or not.

In the case that we have a realloc function (resizable mode), we want
the stream to behave as if it were a file that started out empty.  In
the case that we don't have a realloc function (fixed-sized mode), we
want the stream to behave as a block device would.

To this end, we introduce two changes in functionality:

 - seeking to SEEK_END on a resizable stream will now seek to the end of
   the valid data region, not to the end of the allocated memory (which
   is really just an implementation detail)

 - seeks past the end of the allocated memory size are now permitted,
   but only on resizable streams.  The next write will grow the buffer
   (inserting zeros between).

Some tweaks to testcases were required in order not to break the build,
which indicates that this is an API break, but it seems unlikely that
anyone will be effected by these changes 'in the real world'.

Updates to documentation and further testcases are in following commits.

Based on a patch from Maciej Piechotka <uzytkownik2@gmail.com>.

https://bugzilla.gnome.org/show_bug.cgi?id=684842