I just realized that the way we have been using "Deprecated:" tag was
wrong. It has a version first, then further descriptive text.
Fixes display "Deprecated since: Unknown" in gi-docgen documentation.
Yet they still are generated libgimp functions' arguments.
For instance gimp_context_get_line_dash_pattern() still has a num_dashes
integer argument and a dashes C array, but when calling the PDB
procedure "gimp-context-get-line-dash-pattern", we only set the
GimpArray.
This will allow simpler direct PDB calls too, included in script-fu,
where the size argument is really redundant.
The previous PDB generation was losing pre-formatting inside
triple-backticked blocks. In particular we were losing indentation
(which was already ugly in C, but even syntactically wrong when
displaying Python code samples). And it was also making us add
double-newlines between every code lines, which was annoying.
This updated code now leaves triple-backticked sections as-is.
Unfortunately I was completely unable to do this by modifying the
existing functions, which were modifying the input arg in-place. So I
made them into functions returning the result. But then there is another
part of code (niceargs()) where changing array contents doesn't work
properly, and worse it seems to corrupt the array somehow (because I
have generation breakage in completely-different pieces of the PDB
generation code). I believe there is some passing-by reference/value
concepts in perl which I don't quite get (they use `&`, `\` and other
symbols and even searching for these, I don't quite understand how to
use them the right way) but I've spent already too much time on this. So
since I've got something working now by having duplicate functions, I'll
let someone else from the future, who knows better perl, re-merge these
functions if they know how.
The get() API are sometimes nicer in C code because it's just simpler to
loop through C arrays, but they end up with similar API to the list()
variants for binding, or with a useless size return value (since most
higher level languages have length-aware array types, which is what
GList are transformed into).
So let's use the list() variants as the main ones and skip the get()
variants. I hesitated to rename the list() variants to get() with
`(rename-to)` annotations but since I am unsure if the get() bindings
are absolutely useless, I don't think it's the best idea. Maybe on some
other language usable as GI binding, the get() variant might be
different again and nicer to use. So if we shadowed these by renaming
list() ones, the day we change our mind, we'd have to rename get() ones
too (which would be very confusing), or else break bindings' API. To
avoid this, I just skip the get() ones altogether in bindings but leave
their name available in the bindings.
They only contain private functions and don't need to be installed or
included by gimp_pdb_headers.h.
The PDB generation part is done by adding a "lib_private" variable
that can be set on PDB groups which should not be public API; the rest
is manual Makefile fiddling.
It never belonged inside "tools". Also rename its "pdb" subdirectory
to "groups". This had to happen before 2.10 so cherry-picking between
branches doesn't become a nightmare in the future.
