[babl] docs: improve the generated reference
- From: Øyvind "pippin" Kolås <ok src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [babl] docs: improve the generated reference
- Date: Mon, 22 Jul 2019 13:50:35 +0000 (UTC)
commit 51ff8e26f48c294ea2fdd486bbbd504290fb064b
Author: Øyvind Kolås <pippin gimp org>
Date: Mon Jul 22 14:39:52 2019 +0200
docs: improve the generated reference
babl/babl-class.h | 1 +
babl/babl-core.c | 1 +
babl/babl-format.c | 19 ++++++---
babl/babl-internal.c | 14 +++++++
babl/babl-internal.h | 5 +++
babl/babl-model.c | 12 ++++--
babl/babl-space.h | 2 +
babl/babl-type.c | 11 ++++-
babl/base/type-float.c | 1 +
babl/base/type-half.c | 1 +
babl/base/type-u8.c | 3 ++
docs/babl.css | 8 +++-
tools/babl-html-dump.c | 111 ++++++++++++++++++++++++++-----------------------
13 files changed, 126 insertions(+), 63 deletions(-)
---
diff --git a/babl/babl-class.h b/babl/babl-class.h
index a1efa9d..ceada22 100644
--- a/babl/babl-class.h
+++ b/babl/babl-class.h
@@ -50,6 +50,7 @@ typedef struct
ones */
void *creator;
char *name; /*< the name this type exists under */
+ const char *doc; /*< the name this type exists under */
} BablInstance;
diff --git a/babl/babl-core.c b/babl/babl-core.c
index c551cb9..d78b5e5 100644
--- a/babl/babl-core.c
+++ b/babl/babl-core.c
@@ -93,6 +93,7 @@ babl_core_init (void)
"double",
"id", BABL_DOUBLE,
"bits", 64,
+ "doc", "IEEE 754 double precision.",
NULL);
babl_component_new (
diff --git a/babl/babl-format.c b/babl/babl-format.c
index accc15a..20617d2 100644
--- a/babl/babl-format.c
+++ b/babl/babl-format.c
@@ -52,7 +52,8 @@ format_new (const char *name,
const Babl *space,
BablComponent **component,
BablSampling **sampling,
- const BablType **type)
+ const BablType **type,
+ const char *doc)
{
Babl *babl;
@@ -128,7 +129,7 @@ format_new (const char *name,
babl->format.space = (void*)space;
babl->format.encoding = NULL;
-
+ babl->instance.doc = doc;
return babl;
}
@@ -149,7 +150,7 @@ format_new_from_format_with_space (const Babl *format,
format->format.planar, format->format.components,
(void*)babl_remodel_with_space (BABL(format->format.model), space),
space,
- format->format.component, format->format.sampling, (void*)format->format.type);
+ format->format.component, format->format.sampling, (void*)format->format.type, NULL);
ret->format.encoding = babl_get_name(format);
babl_db_insert (db, (void*)ret);
@@ -285,7 +286,7 @@ babl_format_n (const Babl *btype,
id,
planar, components, model,
babl_space("sRGB"),
- component, sampling, type);
+ component, sampling, type, NULL);
babl_format_set_is_format_n (babl);
@@ -343,7 +344,8 @@ babl_format_new (const void *first_arg,
int planar = 0;
int components = 0;
BablModel *model = NULL;
- const Babl * space = babl_space ("sRGB");
+ const Babl *space = babl_space ("sRGB");
+ const char *doc = NULL;
BablComponent *component [BABL_MAX_COMPONENTS];
BablSampling *sampling [BABL_MAX_COMPONENTS];
const BablType*type [BABL_MAX_COMPONENTS];
@@ -368,6 +370,11 @@ babl_format_new (const void *first_arg,
name = babl_strdup (va_arg (varg, char *));
}
+ else if (!strcmp (arg, "doc"))
+ {
+ doc = babl_strdup (va_arg (varg, const char *));
+ }
+
else if (!strcmp (arg, "packed"))
{
planar = 0;
@@ -506,7 +513,7 @@ babl_format_new (const void *first_arg,
babl = format_new ((void*)name,
id,
planar, components, model, space,
- component, sampling, type);
+ component, sampling, type, doc);
babl_db_insert (db, babl);
babl_free (name);
diff --git a/babl/babl-internal.c b/babl/babl-internal.c
index 5609720..b0c1831 100644
--- a/babl/babl-internal.c
+++ b/babl/babl-internal.c
@@ -113,3 +113,17 @@ babl_get_name (const Babl *babl)
babl_assert (BABL_IS_BABL (babl));
return babl->instance.name;
}
+
+const char *
+babl_get_doc (const Babl *babl)
+{
+ babl_assert (BABL_IS_BABL (babl));
+ return babl->instance.doc;
+}
+
+void babl_doc (const Babl *babl,
+ const char *doc)
+{
+ babl_assert (BABL_IS_BABL (babl));
+ ((Babl*)babl)->instance.doc = doc;
+}
diff --git a/babl/babl-internal.h b/babl/babl-internal.h
index 95ca661..c476827 100644
--- a/babl/babl-internal.h
+++ b/babl/babl-internal.h
@@ -100,6 +100,11 @@ double babl_model_is_symmetric (const Babl *babl);
void babl_die (void);
int babl_sanity (void);
+void babl_doc (const Babl *babl,
+ const char *doc);
+
+const char * babl_get_doc (const Babl *babl);
+
void babl_core_init (void);
const Babl *babl_format_with_model_as_type (const Babl *model,
const Babl *type);
diff --git a/babl/babl-model.c b/babl/babl-model.c
index 142734c..727e6d6 100644
--- a/babl/babl-model.c
+++ b/babl/babl-model.c
@@ -57,7 +57,8 @@ model_new (const char *name,
int id,
int components,
BablComponent **component,
- BablModelFlag flags)
+ BablModelFlag flags,
+ const char *doc)
{
Babl *babl;
@@ -70,6 +71,7 @@ model_new (const char *name,
babl->class_type = BABL_MODEL;
babl->instance.id = id;
+ babl->instance.doc = doc;
babl->model.components = components;
babl->model.space = space;
babl->model.data = NULL;
@@ -117,6 +119,7 @@ babl_model_new (void *first_argument,
const char *arg = first_argument;
const char *assigned_name = NULL;
char *name = NULL;
+ const char *doc = NULL;
const Babl *space = babl_space ("sRGB");
BablComponent *component [BABL_MAX_COMPONENTS];
BablModelFlag flags = 0;
@@ -130,7 +133,10 @@ babl_model_new (void *first_argument,
{
id = va_arg (varg, int);
}
-
+ else if (!strcmp (arg, "doc"))
+ {
+ doc = va_arg (varg, const char *);
+ }
else if (!strcmp (arg, "name"))
{
assigned_name = va_arg (varg, char *);
@@ -257,7 +263,7 @@ babl_model_new (void *first_argument,
if (! babl)
{
- babl = model_new (name, space, id, components, component, flags);
+ babl = model_new (name, space, id, components, component, flags, doc);
babl_db_insert (db, babl);
construct_double_format (babl);
}
diff --git a/babl/babl-space.h b/babl/babl-space.h
index 4c97cdb..7a905e2 100644
--- a/babl/babl-space.h
+++ b/babl/babl-space.h
@@ -41,6 +41,7 @@ typedef struct
#endif
} BablCMYK;
+#if 0 // draft datastructures for spectral spaces
typedef struct _BablSpectrumType BablSpectrumType;
struct _BablSpectrumType {
@@ -86,6 +87,7 @@ typedef struct
float stochastic_diffusion0;
float stochastic_diffusion1;
} BablProcessSpace;
+#endif
typedef struct
{
diff --git a/babl/babl-type.c b/babl/babl-type.c
index 12a3e02..c079828 100644
--- a/babl/babl-type.c
+++ b/babl/babl-type.c
@@ -38,7 +38,8 @@ babl_type_destroy (void *data)
static Babl *
type_new (const char *name,
int id,
- int bits)
+ int bits,
+ const char *doc)
{
Babl *babl;
@@ -50,6 +51,7 @@ type_new (const char *name,
babl->instance.name = (void *) ((char *) babl + sizeof (BablType));
babl->class_type = BABL_TYPE;
babl->instance.id = id;
+ babl->instance.doc = doc;
strcpy (babl->instance.name, name);
babl->type.bits = bits;
babl->type.from_list = NULL;
@@ -77,6 +79,7 @@ babl_type_new (void *first_arg,
int bits = 0;
const char *name = first_arg;
const char *arg;
+ const char *doc = NULL;
va_start (varg, first_arg);
@@ -104,6 +107,10 @@ babl_type_new (void *first_arg,
{
(void) va_arg (varg, long);
}
+ else if (!strcmp (arg, "doc"))
+ {
+ doc = va_arg (varg, const char*);
+ }
else if (!strcmp (arg, "max"))
{
(void) va_arg (varg, long);
@@ -150,7 +157,7 @@ babl_type_new (void *first_arg,
return babl;
}
- babl = type_new (name, id, bits);
+ babl = type_new (name, id, bits, 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/type-float.c b/babl/base/type-float.c
index ee05c37..5b03b3f 100644
--- a/babl/base/type-float.c
+++ b/babl/base/type-float.c
@@ -89,6 +89,7 @@ babl_base_type_float (void)
"float",
"id", BABL_FLOAT,
"bits", 32,
+ "doc", "IEEE 754 single precision",
NULL);
babl_conversion_new (
diff --git a/babl/base/type-half.c b/babl/base/type-half.c
index edb0390..862d662 100644
--- a/babl/base/type-half.c
+++ b/babl/base/type-half.c
@@ -401,6 +401,7 @@ babl_base_type_half (void)
"half",
"id", BABL_HALF,
"bits", 16,
+ "doc", "IEEE 754 half precision.",
NULL);
babl_conversion_new (
diff --git a/babl/base/type-u8.c b/babl/base/type-u8.c
index 5e55e4d..d41d5e0 100644
--- a/babl/base/type-u8.c
+++ b/babl/base/type-u8.c
@@ -208,12 +208,14 @@ babl_base_type_u8 (void)
"u8",
"id", BABL_U8,
"bits", 8,
+ "doc", "uint8_t, 8 bit unsigned integer, values from 0-255",
NULL);
babl_type_new (
"u8-luma",
"id", BABL_U8_LUMA,
"bits", 8,
+ "doc", "8 bit unsigned integer, values from 16-235",
NULL
);
@@ -227,6 +229,7 @@ babl_base_type_u8 (void)
"max", (long) 240,
"min_val", -0.5,
"max_val", 0.5,
+ "doc", "8 bit unsigned integer -0.5 to 0.5 maps to 16-240",
NULL
);
babl_conversion_new (
diff --git a/docs/babl.css b/docs/babl.css
index 79e62ec..c63b7f3 100644
--- a/docs/babl.css
+++ b/docs/babl.css
@@ -60,7 +60,6 @@
}
div.expander_content {
margin-left: 3em;
- display: none;
padding-bottom: 1em;
}
div.expander_content dl{
@@ -314,3 +313,10 @@
display: none;
}
}
+
+.item_title { font-weight: bold; margin-top: 1.5em; margin-bottom: 0.6em;
+}
+
+
+.item_body {
+}
diff --git a/tools/babl-html-dump.c b/tools/babl-html-dump.c
index 079b2d7..0f294a0 100644
--- a/tools/babl-html-dump.c
+++ b/tools/babl-html-dump.c
@@ -16,7 +16,7 @@
* <https://www.gnu.org/licenses/>.
*
*/
-
+
#include "config.h"
#include "babl-internal.h" /* needed for babl_log */
@@ -29,6 +29,9 @@ type_html (Babl *babl);
static void
format_html (Babl *babl);
+static void
+space_html (Babl *babl);
+
static void
conversion_html (Babl *babl);
@@ -36,36 +39,11 @@ static int
each_item (Babl *babl,
void *user_data);
-static int
-show_item (Babl *babl,
- void *user_data);
-
-static int
-hide_item (Babl *babl,
- void *user_data);
-
-
int
main (void)
{
babl_init ();
- printf ("<br/><a href='javascript:");
- printf ("show(\"x_types\");show(\"x_models\");show(\"x_formats\");show(\"x_conversions\");");
- babl_type_class_for_each (show_item, NULL);
- babl_model_class_for_each (show_item, NULL);
- babl_format_class_for_each (show_item, NULL);
-/* babl_conversion_each (show_item, NULL);*/
- printf ("'>+</a>");
-
- printf ("<a href='javascript:");
- printf ("hide(\"x_types\");hide(\"x_models\");hide(\"x_formats\");hide(\"x_conversions\");");
- babl_type_class_for_each (hide_item, NULL);
- babl_model_class_for_each (hide_item, NULL);
- babl_format_class_for_each (hide_item, NULL);
- /*babl_conversion_each (hide_item, NULL);*/
- printf ("'>-</a>");
-
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");
babl_type_class_for_each (each_item, NULL);
@@ -114,6 +92,9 @@ normalize (const char *str)
(*s >= '0' && *s <= '9'))
{
}
+ else if (*s == '~')
+ {
+ }
else
{
*s = '_';
@@ -124,32 +105,15 @@ normalize (const char *str)
}
-static int
-show_item (Babl *babl,
- void *user_data)
-{
- printf ("show(\"x_%s\");", normalize (babl->instance.name));
- return 0;
-}
-
-
-static int
-hide_item (Babl *babl,
- void *user_data)
-{
- printf ("hide(\"x_%s\");", normalize (babl->instance.name));
- return 0;
-}
-
static int
each_item (Babl *babl,
void *user_data)
{
- printf ("<div class='expander'>");
- printf ("<div class='expander_title'><a href='javascript:toggle_visible(\"x_%s\")'>%s</a></div>\n",
- normalize (babl->instance.name), babl->instance.name);
- printf ("<div class='expander_content' id='x_%s'>\n",
- normalize (babl->instance.name));
+ printf ("<div><div class='item_title'><a href='#%s', name='%s'>%s</a></div>\n",
+ normalize (babl->instance.name),
+ normalize (babl->instance.name),
+ babl->instance.name);
+ printf ("<div class='item_body'>");
switch (babl->class_type)
@@ -166,6 +130,10 @@ each_item (Babl *babl,
format_html (babl);
break;
+ case BABL_SPACE:
+ space_html (babl);
+ break;
+
case BABL_CONVERSION:
case BABL_CONVERSION_LINEAR:
case BABL_CONVERSION_PLANE:
@@ -182,10 +150,24 @@ each_item (Babl *babl,
return 0;
}
+static void
+model_doc (const Babl *babl)
+{
+ if (babl->instance.doc)
+ printf ("%s", babl->instance.doc);
+ else
+ {
+ }
+}
+
+
static void
model_html (Babl *babl)
{
int i;
+ printf ("<p>");
+ model_doc (babl);
+ printf ("</p>");
printf ("<dl>");
printf ("<dt>components</dt><dd><table class='nopad'>");
@@ -201,6 +183,9 @@ model_html (Babl *babl)
static void
type_html (Babl *babl)
{
+ if (babl->instance.doc)
+ printf ("<p>%s</p>", babl->instance.doc);
+
printf ("<dl><dt>bits</dt><dd>%i</dd>", babl->type.bits);
printf ("<dt>bytes</dt><dd>%i</dd></dl>", babl->type.bits / 8);
}
@@ -209,22 +194,46 @@ type_html (Babl *babl)
static void
conversion_html (Babl *babl)
{
- printf ("\n");
+ printf ("%s<br/>\n", babl->instance.name);
+}
+
+static void
+space_html (Babl *babl)
+{
+ printf ("%s<br/>\n", babl->instance.name);
}
static void
format_html (Babl *babl)
{
int i;
+ const Babl *model = BABL (babl->format.model);
+
+ printf ("<p>");
+ if (babl->instance.doc)
+ printf ("%s", babl->instance.doc);
+ else
+ {
+ 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);
+ }
+ printf ("</p>");
printf ("<dl>");
printf ("<dt>bytes/pixel</dt><dd>%i</dd>", babl->format.bytes_per_pixel);
- printf ("<dt>model</dt><dd>%s</dd>", BABL (babl->format.model)->instance.name);
+ printf ("<dt>model</dt><dd><a href='#%s'>%s</a></dd>",
+ normalize( BABL (babl->format.model)->instance.name),
+ BABL (babl->format.model)->instance.name);
printf ("<dt>components</dt><dd><table class='nopad'>");
for (i = 0; i < babl->format.components; i++)
{
- printf ("<tr><td class='type'>%s</td><td class='component'>%s</td></tr>",
+ printf ("<tr><td class='type'><a href='#%s' style='color:white''>%s</a></td><td
class='component'>%s</td></tr>",
+ normalize(BABL (babl->format.type[i])->instance.name),
BABL (babl->format.type[i])->instance.name,
BABL (babl->format.component[i])->instance.name);
}
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]