* Create a dark-mode variant of each traversal diagram, with the
traversal path colorized `--primary` blue, instead of the original
black.
* Apply the same colorizations to the light-mode diagrams, but
using the light-theme `--primary` blue.
* Add SPDX license/copyright comments to all eight SVG files.
* Add new files to documentation configs in `glib.toml.in`.
* Update documentation comment in `gnode.c` to embed both color
variants via picture tags, instead of markdown image embeds.
* Add alt text to all four images.
* Add additional blank lines to documentation comment, so that
a. First item in bulleted list does not get folded into
preceding intro paragraph
b. Intro paragraph and diagrams are not part of first paragraph
in documentation. (This also gets them out of the top-level
table-of-contents/index list, where they previously appeared
in full.)
* (Accidental change I didn't realize I was making): Convert line
endings in breadth-first diagram from CRLF to LF.
Commit d0e03f09 introduced GTYPE_TO_POINTER/GPOINTER_TO_TYPE, on which
work started before the move of conversion macros to Markdown. It did
get merged after that move, but the macros never made it into the docs.
Let's do so now.
There is no need to use double backticks. Also, insert extra newlines
between header and item, which paragraphs the item [1, 2], increading
readability by giving a little more "breathing" room between items. This
is also done in `macros.md`. Also, indentation of the definition block
should technically be 4 if extra paragraphs are needed, but it's better
to use 4 indentation always to prevent future problems after edits.
[1] https://python-markdown.github.io/extensions/definition_lists/
[2] https://michelf.ca/projects/php-markdown/extra/#def-list
- Do not refer to people’s expectation, they can wildly differ.
- Do not link to `strcompress`, that confusingly does not support `\a`. Link Wikipedia instead.
- Reiterate the C escape sequences from string section, they are not that many.
- Mention escaping newline and other characters (also copied from string section).
- Mention Unicode escapes not being supported to contrast with strings.
548ec9f186d373c4e55528a04d78450f6f2fceef accidentally moved the GVariant
spec to the toplevel /usr/share/doc directory, which is surely not
right. Let's move it back into the glib-2.0 subdirectory.
It's debatable whether this is the best place to install the GVariant
specification, since it's not part of the gi-docgen docs, but surely
it's much better than not putting it in any subdirectory.
Fixes#3351
The `gi-docgen` tool is not designed to be used like that. In
particular, when nesting documentation directories, the generated
`*.devhelp2` files (needed by Devhelp to show the documentation) are
nested one directory level too deep for Devhelp to find them, and hence
are useless, and the documentation doesn’t show up in this common
documentation viewer.
So, change the installed documentation directory hierarchy:
* `${PREFIX}/share/doc/glib-2.0/gio` → `${PREFIX}/share/doc/gio-2.0`
* `${PREFIX}/share/doc/glib-2.0/glib-unix` →
`${PREFIX}/share/doc/glib-unix-2.0`
* `${PREFIX}/share/doc/glib-2.0/gobject` →
`${PREFIX}/share/doc/gobject-2.0`
* etc.
* `${PREFIX}/share/doc/glib-2.0/glib` → `${PREFIX}/share/doc/glib-2.0`
This is going to seem like pointless churn (the contents of the
documentation have not changed), and packagers may mourn the split of
content in `/usr/share/doc` from `/usr/share/doc/${package_name}` to
`/usr/share/doc/${pkg_config_id}` instead, but that seems to be the best
approach to fix this issue in GLib. gi-docgen’s behaviour does feel
fairly consistent and correct with the rest of how it works (single
output directory).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Fixes: #3287
So now introspection users will have to call `GLibUnix.open_pipe()`
rather than `GLibUnix.unix_open_pipe()` — or
`GLibWin32.check_windows_version()` rather than
`GLibWin32.win32_check_windows_version()`.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
This creates `GioUnix`, `GioWin32`, `GLibUnix` and `GLibWin32`. These
bodies of documentation are in addition to the main, platform agnostic,
documentation for both libraries.
This commit necessarily includes various mechanical changes to update
the repository namespace used in various existing documentation links to
platform specific APIs.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Seems no point in keeping them separate. It doesn’t seem to matter if
they contain entries which are unused for a particular docs build.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This might help increase visibility of Philip's useful GMainContext
tutorial. Although the GMainContext documentation is fairly good, it's
also pretty intimidating. The tutorial is very useful and provides
guidance that we can't fit directly into the documentation, so reference
it.
Now that the reference documentation uses gi-docgen, it's more
troublesome to generate in less standard build scenarios like
cross-compiling.
In distributions like Debian, reference documentation is generally
packaged separately (in libglib2.0-doc in Debian's case), but man pages
are generally packaged alongside the executables themselves (in the
libglib2.0-bin and libglib2.0-dev-bin packages, in Debian's case). We
can exclude the reference documentation when cross-compiling, but ideally
we would like the man pages to still be built, so that a cross-compiled
libglib2.0-bin or libglib2.0-dev-bin package has the same content as a
native build.
Signed-off-by: Simon McVittie <smcv@debian.org>
They are now installed to (e.g.)
`${prefix}/share/doc/glib-2.0/{glib,gmodule,gobject,gio}/index.html`.
We might want to drop one level of nesting out of that, but for the
moment I thought I’d keep it in so we can disambiguate by installed
major version.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
So they are consistent with the way we’re building man pages in other
projects, and because some people are allergic to XML.
This changes the build-time dependencies from `xsltproc` to `rst2man`,
and also takes the opportunity to change the `-Dman` Meson option from a
boolean to a feature (so you should use `-Dman-pages={enabled,disabled}`
now, rather than `-Dman={true,false}`).
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Because the documentation is no longer built using gtk-doc.
Keep the old option around, but deprecated.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
Point people to the official PCRE documentation instead, which is going
to be more up to date. This saves us periodically having to copy in and
reformat the PCRE documentation.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
We haven’t made any backwards-incompatible changes since GLib 2.2 in
2002. It’s probably not very useful to tell people about those any more.
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3037
