Similar to the --enable-g-ir-doc option I just added on autotools. Also
separate this option from gtk-doc as it is unrelated (not everything
under devel-docs is related to gtk-doc!).
Based on the proposed process proposed by Akkana Peck. Thanks Akk!
For now, it's only in the meson build, which is fairly terrible to use
as soon as we do custom build rules. Here are the list of issues:
- meson does not allow building in subdir (issue 2320 on meson tracker).
Sure I could make several subdirs with meson in them. But here the
future goal would be to be able to generate docs for other
introspected languages, and maybe also other output formats (epub or
whatnot). For this, since these are basically the same commands which
are used, the best practice would be to have loops generating one
target per language/format combination, reusing code rather than ugly
copy-pasting in subdirectories' meson files).
- custom_target() requires the output parameter to be the complete list
of generated files. But we have more than a thousand of them. It's not
practical. Maybe we could try to find a way to generate the list from
the contents of the .def files which are already exhaustive and exact.
- Install also requires the output list to be complete.
- I temporarily have these docs not generated by default (because the
gtk-doc option is already crazy slow as it is, making meson near
unusable for development if it's enabled). If you want to generate the
docs, the commands are as following (yeah I don't understand what the
target names are for since meson does not actually create targets with
these names, so we have to use fake output names instead):
> ninja devel-docs/g-ir-docs/Gimp-python-html
> ninja devel-docs/g-ir-docs/GimpUi-python-html
Let's start up some porting guide for plug-in developers. One of the
first things to do is to get rid of any deprecated functions from 2.10
or older versions. In the current stable, these would "just" output
warnings, but in the dev version, all deprecated functions got removed
and the build would fail.
This list may not be complete. I mostly created it by some grep on
deprecated functions from libgimp 2.10.
Plug-ins that work from different bindings probably want to use their
own list-type to specify arguments, rather than working with a more
cumbersome `GimpValueArray`.
This new API should make it less verbose. For example:
```
args = Gimp.ValueArray.new(5)
args.insert(0, GObject.Value(Gimp.RunMode, Gimp.RunMode.NONINTERACTIVE))
args.insert(1, GObject.Value(Gimp.Image, image))
args.insert(2, GObject.Value(Gimp.Drawable, mask))
args.insert(3, GObject.Value(GObject.TYPE_INT, int(time.time())))
args.insert(4, GObject.Value(GObject.TYPE_DOUBLE, turbulence))
Gimp.get_pdb().run_procedure('plug-in-plasma', args)
```
becomes
```
Gimp.get_pdb().run_procedure('plug-in-plasma', [
GObject.Value(Gimp.RunMode, Gimp.RunMode.NONINTERACTIVE),
GObject.Value(Gimp.Image, image),
GObject.Value(Gimp.Drawable, mask),
GObject.Value(GObject.TYPE_INT, int(time.time())),
GObject.Value(GObject.TYPE_DOUBLE, turbulence),
])
```
The `info line` in particular was given by Ell and will make trace
handling a lot easier as it means we may not have to ask for traces with
debug symbols or gdb with Flatpak. We can indeed get these infos back
ourselves since we are guaranted to use the exact same binaries.
This together with the change in verbose version output I did 2 weeks
ago (commit bc5f6371e9), allowing us to check the exact Flatpak hash
commit used by a reporter, Flatpak debugging should be a lot easier with
just the simpler stack trace format.
Flatpak repositories can store successive builds (up to 20 in the
Flathub repository in particular), even though by default it installs
only the last build.
I added in `debugging-tips.txt` the commands to search for and
explicitly install an older build of our official GIMP build. This can
be useful to compare some behaviorial changes as reported by users,
without having to re-compile old commits just for a quick test.
`gimp_unit_store_get_value()` clashes with the `get_value()` method of
its parent class GtkTreeStore. This means trouble for bindings, as seen
here in some pseudocode:
```vala
var unit_store = new Gimp.UnitStore();
// Which function are we referencing here, the one from GtkTreeStore or
// the one from GimpUnitStore? Worse, they both have different arguments
unit_store.get_value( ... )
```
The GIR parser is giving warnings because both e.g. a signal, a
corresponding vfunc and a method emitting it are named
"channel_changed", which can and will give issues in some bindings.
The easiest option is to follow the general convention of starting the
signal emitters with `emit_`, which also makes clear the intention of
the method.
* Don't generate our own marshallers if they are available in GLib
already
* Don't set the c_marshaller parameter in `g_signal_new()` if it's a
default marshaller provided by GLib. See commit message of commit
39e4aa3c57 on why this is the case.
Found via `codespell -q 3 -S ./ChangeLog*,*.po -L als,ang,ba,chello,daa,doubleclick,foto,hist,iff,inport,klass,mut,nd,ower,paeth,params,pard,pevent,sinc,thru,tim,uint`
Though the description of the POINTER type clearly tells of the new type
size, it was still refered as 32-bit only in this introductory text.
Let's fix this.
Though it may have started as an unofficial document, it is clearly now
an official one (which should be obvious since it is in our source
repository, but apparently some people get misled by the historical
"Status" text to think this to be somehow unofficial).
So first of all, change the s/official/unofficial/ mention.
Secondly, add a small paragraph explicitly telling that the document is
complete (and meant to be), to the best of our knowledge. This document
is a detailed, full and exhaustive written "specification" of the XCF
format up to GIMP 2.10.x (even though the normative spec is still the
code itself). Now we are humans, we may have missed something, and if
so, this is just to be considered as any other bug, and reported to us
nicely to be fixed.
