[gimp] Bug 709048 - improvement of gimp-layer-add-mask procedure's doc.

[Jehan Pagès <jehanp src gnome org>]

commit cca6772714178b5017c28c3ecbcb3fd367b631ab
Author: Jehan <jehan girinstud io>
Date:   Mon Sep 30 22:20:49 2013 +1300

    Bug 709048 - improvement of gimp-layer-add-mask procedure's doc.
    
    The documentation was missing information about GIMP_ADD_CHANNEL_MASK
    mask type, also about possible failure cases, and had an unclosed
    bracket typo.
    Also make nicer output and list formatting with the new pdb paragraph
    feature.

 app/pdb/layer-cmds.c       |   13 ++++++++++++-
 libgimp/gimplayer_pdb.c    |   30 ++++++++++++++++++++----------
 tools/pdbgen/pdb/layer.pdb |   37 ++++++++++++++++++++++++++++---------
 3 files changed, 60 insertions(+), 20 deletions(-)
---
diff --git a/app/pdb/layer-cmds.c b/app/pdb/layer-cmds.c
index 31a083f..da8dcaf 100644
--- a/app/pdb/layer-cmds.c
+++ b/app/pdb/layer-cmds.c
@@ -1636,7 +1636,18 @@ register_layer_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-layer-create-mask",
                                      "Create a layer mask for the specified layer.",
-                                     "This procedure creates a layer mask for the specified layer. Layer 
masks serve as an additional alpha channel for a layer. A number of different types of masks are allowed for 
initialisation: completely white masks (which will leave the layer fully visible), completely black masks 
(which will give the layer complete transparency, the layer's already existing alpha channel (which will 
leave the layer fully visible, but which may be more useful than a white mask), the current selection or a 
grayscale copy of the layer. The layer mask still needs to be added to the layer. This can be done with a 
call to 'gimp-layer-add-mask'.",
+                                     "This procedure creates a layer mask for the specified layer.\n"
+                                     "Layer masks serve as an additional alpha channel for a layer. 
Different types of masks are allowed for initialisation:\n"
+                                     "- white mask (leaves the layer fully visible);\n"
+                                     "- black mask (gives the layer complete transparency);\n"
+                                     "- the layer's alpha channel (either a copy, or a transfer, which 
leaves the layer fully visible, but which may be more useful than a white mask);\n"
+                                     "- the current selection;\n"
+                                     "- a grayscale copy of the layer;\n"
+                                     "- or a copy of the active channel.\n"
+                                     "\n"
+                                     "The layer mask still needs to be added to the layer. This can be done 
with a call to 'gimp-layer-add-mask'.\n"
+                                     "\n"
+                                     "'gimp-layer-create-mask' will fail if there are no active channels on 
the image, when called with 'ADD-CHANNEL-MASK'. It will return a black mask when called with 'ADD-ALPHA-MASK' 
or 'ADD-ALPHA-TRANSFER-MASK' on a layer with no alpha channels, or with 'ADD-SELECTION-MASK' when there is no 
selection on the image.",
                                      "Spencer Kimball & Peter Mattis",
                                      "Spencer Kimball & Peter Mattis",
                                      "1995-1996",
diff --git a/libgimp/gimplayer_pdb.c b/libgimp/gimplayer_pdb.c
index 47b1fc0..8bcfd47 100644
--- a/libgimp/gimplayer_pdb.c
+++ b/libgimp/gimplayer_pdb.c
@@ -548,16 +548,26 @@ gimp_layer_set_offsets (gint32 layer_ID,
  *
  * Create a layer mask for the specified layer.
  *
- * This procedure creates a layer mask for the specified layer. Layer
- * masks serve as an additional alpha channel for a layer. A number of
- * different types of masks are allowed for initialisation: completely
- * white masks (which will leave the layer fully visible), completely
- * black masks (which will give the layer complete transparency, the
- * layer's already existing alpha channel (which will leave the layer
- * fully visible, but which may be more useful than a white mask), the
- * current selection or a grayscale copy of the layer. The layer mask
- * still needs to be added to the layer. This can be done with a call
- * to gimp_layer_add_mask().
+ * This procedure creates a layer mask for the specified layer.
+ * Layer masks serve as an additional alpha channel for a layer.
+ * Different types of masks are allowed for initialisation:
+ * - white mask (leaves the layer fully visible);
+ * - black mask (gives the layer complete transparency);
+ * - the layer's alpha channel (either a copy, or a transfer, which
+ * leaves the layer fully visible, but which may be more useful than a
+ * white mask);
+ * - the current selection;
+ * - a grayscale copy of the layer;
+ * - or a copy of the active channel.
+ * 
+ * The layer mask still needs to be added to the layer. This can be
+ * done with a call to gimp_layer_add_mask().
+ * 
+ * gimp_layer_create_mask() will fail if there are no active channels
+ * on the image, when called with 'ADD-CHANNEL-MASK'. It will return a
+ * black mask when called with 'ADD-ALPHA-MASK' or
+ * 'ADD-ALPHA-TRANSFER-MASK' on a layer with no alpha channels, or with
+ * 'ADD-SELECTION-MASK' when there is no selection on the image.
  *
  * Returns: The newly created mask.
  **/
diff --git a/tools/pdbgen/pdb/layer.pdb b/tools/pdbgen/pdb/layer.pdb
index 806ea10..415f23c 100644
--- a/tools/pdbgen/pdb/layer.pdb
+++ b/tools/pdbgen/pdb/layer.pdb
@@ -285,15 +285,34 @@ sub layer_create_mask {
     $blurb = 'Create a layer mask for the specified layer.';
 
     $help = <<'HELP';
-This procedure creates a layer mask for the specified layer. Layer masks serve
-as an additional alpha channel for a layer. A number of different types of
-masks are allowed for initialisation: completely white masks (which will
-leave the layer fully visible), completely black masks (which will give the
-layer complete transparency, the layer's already existing alpha channel
-(which will leave the layer fully visible, but which may be more useful than
-a white mask), the current selection or a grayscale copy of the layer. The
-layer mask still needs to be added to the layer. This can be done with a call
-to gimp_layer_add_mask().
+This procedure creates a layer mask for the specified layer.
+
+Layer masks serve as an additional alpha channel for a layer. Different
+types of masks are allowed for initialisation:
+
+- white mask (leaves the layer fully visible);
+
+- black mask (gives the layer complete transparency);
+
+- the layer's alpha channel (either a copy, or a transfer, which leaves
+the layer fully visible, but which may be more useful than a white mask);
+
+- the current selection;
+
+- a grayscale copy of the layer;
+
+- or a copy of the active channel.
+
+
+The layer mask still needs to be added to the layer. This can be done
+with a call to gimp_layer_add_mask().
+
+
+gimp_layer_create_mask() will fail if there are no active channels on
+the image, when called with 'ADD-CHANNEL-MASK'. It will return a black
+mask when called with 'ADD-ALPHA-MASK' or 'ADD-ALPHA-TRANSFER-MASK' on
+a layer with no alpha channels, or with 'ADD-SELECTION-MASK' when there
+is no selection on the image.
 HELP
 
     &std_pdb_misc();