From 82c607d4a860a2c19d5cca9e3ce442dd233148ea Mon Sep 17 00:00:00 2001 From: Jehan Date: Tue, 27 Aug 2024 11:39:31 +0200 Subject: [PATCH] app, libgimp, pdb: support triple-backticks unformatted desc sections. 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. --- app/pdb/item-cmds.c | 8 ++++-- libgimp/gimpitem_pdb.c | 8 ++++-- pdb/groups/item.pdb | 8 +----- pdb/pdbgen.pl | 62 ++++++++++++++++++++++++++++++++++++++---- 4 files changed, 70 insertions(+), 16 deletions(-) diff --git a/app/pdb/item-cmds.c b/app/pdb/item-cmds.c index 8108f09351..a869f9089f 100644 --- a/app/pdb/item-cmds.c +++ b/app/pdb/item-cmds.c @@ -1134,15 +1134,19 @@ register_item_procs (GimpPDB *pdb) "This procedure returns %TRUE if the specified item ID is a layer.\n" "\n" "*Note*: in most use cases, you should not use this function. If the goal is to verify the accurate type for a [class@Gimp.Item], you should either use [method@Gimp.Item.is_layer] or the specific type-checking methods for the used language.\n" + "\n" "For instance, in C:\n" + "\n" "```C\n" "if (GIMP_IS_LAYER (item))\n" - "do_something ();\n" + " do_something ();\n" "```\n" + "\n" "Or in the Python binding, you could run:\n" + "\n" "```py3\n" "if isinstance(item, Gimp.Layer):\n" - "do_something()\n" + " do_something()\n" "```", NULL); gimp_procedure_set_static_attribution (procedure, diff --git a/libgimp/gimpitem_pdb.c b/libgimp/gimpitem_pdb.c index 8ae4b7d92f..1426630652 100644 --- a/libgimp/gimpitem_pdb.c +++ b/libgimp/gimpitem_pdb.c @@ -128,15 +128,19 @@ gimp_item_id_is_drawable (gint item_id) * goal is to verify the accurate type for a [class@Gimp.Item], you * should either use [method@Gimp.Item.is_layer] or the specific * type-checking methods for the used language. + * * For instance, in C: + * * ```C * if (GIMP_IS_LAYER (item)) - * do_something (); + * do_something (); * ``` + * * Or in the Python binding, you could run: + * * ```py3 * if isinstance(item, Gimp.Layer): - * do_something() + * do_something() * ``` * * Returns: TRUE if the item is a layer, FALSE otherwise. diff --git a/pdb/groups/item.pdb b/pdb/groups/item.pdb index 5f9df3d7cd..03d4ff4628 100644 --- a/pdb/groups/item.pdb +++ b/pdb/groups/item.pdb @@ -101,26 +101,20 @@ is to verify the accurate type for a [class@Gimp.Item], you should either use [method@Gimp.Item.is_layer] or the specific type-checking methods for the used language. + For instance, in C: ```C - if (GIMP_IS_LAYER (item)) - do_something (); - ``` Or in the Python binding, you could run: ```py3 - if isinstance(item, Gimp.Layer): - do_something() - ``` - HELP &std_pdb_misc; diff --git a/pdb/pdbgen.pl b/pdb/pdbgen.pl index 15c55229c5..17da88802a 100755 --- a/pdb/pdbgen.pl +++ b/pdb/pdbgen.pl @@ -158,6 +158,58 @@ sub nicelist { foreach (@$list) { &trimspace(\$_) } } +# trimspace2 and nicetext2 are basically copies of the non-2 versions, +# except that they return the value. I was unable to make the original +# version (directly modifying the argument) work with the split() call. +# Inversely, I could not have the niceargs() function use the +# return-version nicetext2(). Something is wrong and that's very likely +# my limited knowledge of how perl works. So I just keep both versions +# around for now, because what I needed anyway was to special-case the +# triple-backticked (blockquotes) in the 'help' section. Anyone, be my +# guest to merge these back into one and remove code duplication, if you +# know how! +sub trimspace2 { + my $text = shift; + my $trimmed = ''; + my $in_triple_ticks = 0; + + foreach $subtext (split /```/, $text) { + if ($in_triple_ticks) { + # Don't touch formatting inside triple-backticked + # blockquotes. + $subtext =~ s/\s+$//; + $subtext = "\n```" . $subtext . "\n```\n"; + $in_triple_ticks = 0; + } + else { + # Removing single newlines. + $subtext =~ s/(\S)[\ \t\r\f]*\n[\ \t\r\f]*(\S)/$1 $2/g; + # All multi-space are transformed in single space. + $subtext =~ s/[\ \t\r\f]+/ /gs; + # Remove one newline per groups of newlines. + $subtext =~ s/\n(([\ \t\r\f]*\n)+)/$1/g; + $subtext =~ s/[\ \t\r\f]*\n[\ \t\r\f]/\n/g; + $in_triple_ticks = 1; + } + $trimmed .= $subtext; + } + $text = $trimmed; + + # Remove leading and trailing whitespaces. + $text =~ s/^\s+//; + $text =~ s/\s+$//; + return $text; +} + +sub nicetext2 { + my $val = shift; + if (defined $val) { + $val = trimspace2($val); + $val =~ s/"/\\"/g; + } + return $val; +} + # Add args for array lengths sub arrayexpand { @@ -200,11 +252,11 @@ sub canonicalargs { # Post-process each pdb entry while ((undef, $entry) = each %pdb) { - &nicetext(\$entry->{blurb}); - &nicetext(\$entry->{help}); - &nicetext(\$entry->{author}); - &nicetext(\$entry->{copyright}); - &nicetext(\$entry->{date}); + $entry->{blurb} = nicetext2($entry->{blurb}); + $entry->{help} = nicetext2($entry->{help}); + $entry->{author} = nicetext2($entry->{author}); + $entry->{copyright} = nicetext2($entry->{copyright}); + $entry->{date} = nicetext2($entry->{date}); foreach (qw(in out)) { my $args = $_ . 'args';