[babl] docs: improve generated reference

[Øyvind "pippin" Kolås <ok src gnome org>]

commit 615096b610b74bb24cab855866e3add42c48bac0
Author: Øyvind Kolås <pippin gimp org>
Date:   Mon Jul 22 17:10:08 2019 +0200

    docs: improve generated reference
    
    When registering types, models, formats and components one can now
    specify override "doc" strings that end up in this reference.

 babl/babl-component.c   | 11 ++++++--
 babl/base/model-ycbcr.c |  2 ++
 docs/babl.css           |  4 ++-
 extensions/CIE.c        | 14 ++++++----
 tools/babl-html-dump.c  | 74 ++++++++++++++++++++++++++++++++++++++-----------
 5 files changed, 81 insertions(+), 24 deletions(-)
---
diff --git a/babl/babl-component.c b/babl/babl-component.c
index 2993e81..514ad26 100644
--- a/babl/babl-component.c
+++ b/babl/babl-component.c
@@ -29,7 +29,8 @@ component_new (const char *name,
                int         id,
                int         luma,
                int         chroma,
-               int         alpha)
+               int         alpha,
+               const char *doc)
 {
   Babl *babl;
 
@@ -39,6 +40,7 @@ component_new (const char *name,
 
   babl->class_type       = BABL_COMPONENT;
   babl->instance.id      = id;
+  babl->instance.doc     = doc;
   babl->component.luma   = luma;
   babl->component.chroma = chroma;
   babl->component.alpha  = alpha;
@@ -73,6 +75,7 @@ babl_component_new (void *first_arg,
   int         alpha  = 0;
   const char *name   = first_arg;
   const char *arg;
+  const char *doc = NULL;
 
   va_start (varg, first_arg);
 
@@ -87,6 +90,10 @@ babl_component_new (void *first_arg,
         {
           id = va_arg (varg, int);
         }
+      else if (!strcmp (arg, "doc"))
+        {
+          doc = va_arg (varg, const char *);
+        }
 
       else if (!strcmp (arg, "luma"))
         {
@@ -136,7 +143,7 @@ babl_component_new (void *first_arg,
       return babl;
     }
 
-  babl = component_new (name, id, luma, chroma, alpha);
+  babl = component_new (name, id, luma, chroma, alpha, doc);
 
   /* Since there is not an already registered instance by the required
    * id/name, inserting newly created class into database.
diff --git a/babl/base/model-ycbcr.c b/babl/base/model-ycbcr.c
index 21353e6..64db6a2 100644
--- a/babl/base/model-ycbcr.c
+++ b/babl/base/model-ycbcr.c
@@ -63,6 +63,7 @@ models (void)
 {
   babl_model_new (
     "id", BABL_YCBCR,
+    "doc", "Y'CbCr video format model, NB! math is tuned to sRGB space",
     babl_component_from_id (BABL_GRAY_NONLINEAR),
     babl_component_from_id (BABL_CB),
     babl_component_from_id (BABL_CR),
@@ -70,6 +71,7 @@ models (void)
 
   babl_model_new (
     "id", BABL_YCBCR_ALPHA,
+    "doc", "Y'CbCr video format model, separate alpha NB! math is tuned to sRGB space",
     babl_component_from_id (BABL_GRAY_NONLINEAR),
     babl_component_from_id (BABL_CB),
     babl_component_from_id (BABL_CR),
diff --git a/docs/babl.css b/docs/babl.css
index c63b7f3..ecfe47e 100644
--- a/docs/babl.css
+++ b/docs/babl.css
@@ -2,6 +2,7 @@
       body {
         margin: 0;
         padding: 0;
+        font-size: 14pt;
       }
       div.paper {
         background-color: #fff;
@@ -149,6 +150,7 @@
       span.NULL {
         color: #555;
       }
+      tt { font-size: 110%; }
       pre.authors {
         font-size: 100%;
         font-family: FreeSans, Verdana, sans-serif;
@@ -314,7 +316,7 @@
         }
       }
 
-.item_title {  font-weight: bold; margin-top: 1.5em; margin-bottom: 0.6em;
+.item_title {  font-weight: bold; margin-top: 2.5em; margin-bottom: 0.6em;
 }
 
 
diff --git a/extensions/CIE.c b/extensions/CIE.c
index 9bfb41b..4b41894 100644
--- a/extensions/CIE.c
+++ b/extensions/CIE.c
@@ -85,11 +85,11 @@ init (void)
 static void
 components (void)
 {
-  babl_component_new ("CIE L", NULL);
-  babl_component_new ("CIE a", "chroma", NULL);
-  babl_component_new ("CIE b", "chroma", NULL);
-  babl_component_new ("CIE C(ab)", "chroma", NULL);
-  babl_component_new ("CIE H(ab)", "chroma", NULL);
+  babl_component_new ("CIE L", "doc", "Luminance, range 0.0-100.0 in float", NULL);
+  babl_component_new ("CIE a", "chroma", "doc", "chroma component 0.0 is no saturation", NULL);
+  babl_component_new ("CIE b", "chroma", "doc", "chroma component 0.0 is no saturation", NULL);
+  babl_component_new ("CIE C(ab)", "chroma", "doc", "chrominance/saturation", NULL);
+  babl_component_new ("CIE H(ab)", "chroma", "doc", "hue value range 0.0-360.0", NULL);
   babl_component_new ("CIE X", NULL);
   babl_component_new ("CIE Y", NULL);
   babl_component_new ("CIE Z", NULL);
@@ -106,6 +106,7 @@ models (void)
 {
   babl_model_new (
     "name", "CIE Lab",
+    "doc", "CIE Lab color model, a perceptually uniform space, euclidian distance in this space represents 
delta E.",
     babl_component ("CIE L"),
     babl_component ("CIE a"),
     babl_component ("CIE b"),
@@ -114,6 +115,7 @@ models (void)
 
   babl_model_new (
     "name", "CIE Lab alpha",
+    "doc", "CIE Lab color model, with separate alpha",
     babl_component ("CIE L"),
     babl_component ("CIE a"),
     babl_component ("CIE b"),
@@ -124,6 +126,7 @@ models (void)
 
   babl_model_new (
     "name", "CIE LCH(ab)",
+    "doc", "CIE LCH color model, using cylindrical coordinates",
     babl_component ("CIE L"),
     babl_component ("CIE C(ab)"),
     babl_component ("CIE H(ab)"),
@@ -132,6 +135,7 @@ models (void)
 
   babl_model_new (
     "name", "CIE LCH(ab) alpha",
+    "doc", "CIE LCH color model, using cylindrical coordinates, with separate alpha",
     babl_component ("CIE L"),
     babl_component ("CIE C(ab)"),
     babl_component ("CIE H(ab)"),
diff --git a/tools/babl-html-dump.c b/tools/babl-html-dump.c
index 0f294a0..08db1cd 100644
--- a/tools/babl-html-dump.c
+++ b/tools/babl-html-dump.c
@@ -44,24 +44,21 @@ main (void)
 {
   babl_init ();
 
-  printf ("<div class='expander'>");
-  printf ("<div class='expander_title'><a style='font-size:110%%' name='Data-types' 
href='javascript:toggle_visible(\"x_types\")'>Data types</a></div><div class='expander_content' 
id='x_types'>\n");
+  printf ("<div>");
+  printf ("<h3>Types</h3>");
   babl_type_class_for_each (each_item, NULL);
   printf ("</div>\n");
-  printf ("</div>\n");
 
-  printf ("<div class='expander'>");
-  printf ("<div class='expander_title'><a style='font-size:110%%' name='Color-models' 
href='javascript:toggle_visible(\"x_models\")'>Color models</a></div><div class='expander_content' 
id='x_models'>\n");
+  printf ("<div>");
+  printf ("<h3>Models</h3>");
   babl_model_class_for_each (each_item, NULL);
   printf ("</div>\n");
-  printf ("</div>\n");
 
 
-  printf ("<div class='expander'>");
-  printf ("<div class='expander_title'><a style='font-size:110%%' name='Pixel-formats' 
href='javascript:toggle_visible(\"x_formats\")'>Pixel formats</a></div><div class='expander_content' 
id='x_formats'>\n");
+  printf ("<div>");
+  printf ("<h3>Pixelformats</h3>");
   babl_format_class_for_each (each_item, NULL);
   printf ("</div>\n");
-  printf ("</div>\n");
 
 /*
    printf ("<div class='expander'>");
@@ -109,10 +106,23 @@ static int
 each_item (Babl *babl,
            void *user_data)
 {
-  printf ("<div><div class='item_title'><a href='#%s', name='%s'>%s</a></div>\n",
+  const char *fun_pre = "babl_type";
+  const char *fun_post = ")";
+
+  switch (babl->class_type)
+  {
+    case BABL_MODEL: fun_pre = "babl_model"; break;
+    case BABL_FORMAT: fun_pre = "babl_format_with_space";
+                      fun_post = ", space|NULL)";
+    break;
+  }
+
+  printf ("<div><div class='item_title'><a href='#%s', name='%s'><tt>%s (\"%s\"%s</tt></a></div>\n",
           normalize (babl->instance.name),
           normalize (babl->instance.name),
-          babl->instance.name);
+          fun_pre,
+          babl->instance.name,
+          fun_post);
   printf ("<div class='item_body'>");
 
 
@@ -157,6 +167,38 @@ model_doc (const Babl *babl)
     printf ("%s", babl->instance.doc);
   else
     {
+      BablModelFlag flags = babl_get_model_flags (babl);
+      if (flags & BABL_MODEL_FLAG_RGB)
+        printf ("RGB");
+      else if (flags & BABL_MODEL_FLAG_GRAY)
+        printf ("Grayscale");
+      else if (flags & BABL_MODEL_FLAG_CMYK)
+      {
+        if (flags & BABL_MODEL_FLAG_INVERTED)
+          printf ("CMYK with inverted color components (0.0=full coverage), for additive compositing");
+        else
+          printf ("CMYK");
+      }
+
+      if (flags & BABL_MODEL_FLAG_LINEAR)
+        printf (" linear");
+      if (flags & BABL_MODEL_FLAG_NONLINEAR)
+        printf (" with TRC from space");
+      if (flags & BABL_MODEL_FLAG_PERCEPTUAL)
+        printf (" with perceptual (sRGB) TRC");
+
+      if (flags & BABL_MODEL_FLAG_ALPHA)
+      {
+        if (flags & BABL_MODEL_FLAG_ASSOCIATED)
+        {
+          printf (", associated alpha");
+        }
+        else
+        {
+          printf (", separate alpha");
+        }
+      }
+
     }
 }
 
@@ -214,12 +256,12 @@ format_html (Babl *babl)
     printf ("%s", babl->instance.doc);
   else
     {
-      const Babl *type = BABL (babl->format.type[0]);
+      //const Babl *type = BABL (babl->format.type[0]);
       model_doc (model);
-      if (type->instance.doc)
-        printf (" %s", type->instance.doc);
-      else
-        printf (" %s", type->instance.name);
+      //if (type->instance.doc)
+      //  printf (" %s", type->instance.doc);
+      //else
+      //  printf (" %s", type->instance.name);
     }
   printf ("</p>");