From 7fcb67653dc29f7449baa7f069c3d4bb2ecdd7e9 Mon Sep 17 00:00:00 2001 From: Jim Evins Date: Sun, 3 Apr 2005 00:47:07 +0000 Subject: [PATCH] * docs/libglabels/libglabels-sections.txt: * docs/libglabels/libglabels-undocumented.txt: * docs/libglabels/tmpl/enums.sgml: * docs/libglabels/tmpl/paper.sgml: * docs/libglabels/tmpl/xml-paper.sgml: * docs/libglabels/tmpl/xml-template.sgml: * libglabels/enums.h: * libglabels/paper.c: (gl_paper_dup): * libglabels/paper.h: * libglabels/xml-paper.c: * libglabels/xml-template.c: More documentation updates for libglabels. git-svn-id: https://glabels.svn.sourceforge.net/svnroot/glabels/trunk@511 f5e0f49d-192f-0410-a22d-a8d8700d0965 --- glabels2/ChangeLog | 15 ++ .../docs/libglabels/libglabels-sections.txt | 13 +- .../libglabels/libglabels-undocumented.txt | 31 +-- glabels2/docs/libglabels/tmpl/enums.sgml | 12 +- glabels2/docs/libglabels/tmpl/paper.sgml | 7 +- glabels2/docs/libglabels/tmpl/xml-paper.sgml | 7 +- .../docs/libglabels/tmpl/xml-template.sgml | 8 +- glabels2/libglabels/enums.h | 10 +- glabels2/libglabels/paper.c | 192 +++++++++++++----- glabels2/libglabels/paper.h | 8 +- glabels2/libglabels/xml-paper.c | 40 +++- glabels2/libglabels/xml-template.c | 74 +++++-- 12 files changed, 287 insertions(+), 130 deletions(-) diff --git a/glabels2/ChangeLog b/glabels2/ChangeLog index 9d05536a..9e6139a2 100644 --- a/glabels2/ChangeLog +++ b/glabels2/ChangeLog @@ -1,3 +1,18 @@ +2005-04-02 Jim Evins + + * docs/libglabels/libglabels-sections.txt: + * docs/libglabels/libglabels-undocumented.txt: + * docs/libglabels/tmpl/enums.sgml: + * docs/libglabels/tmpl/paper.sgml: + * docs/libglabels/tmpl/xml-paper.sgml: + * docs/libglabels/tmpl/xml-template.sgml: + * libglabels/enums.h: + * libglabels/paper.c: (gl_paper_dup): + * libglabels/paper.h: + * libglabels/xml-paper.c: + * libglabels/xml-template.c: + More documentation updates for libglabels. + 2005-03-23 Jim Evins * INSTALL: diff --git a/glabels2/docs/libglabels/libglabels-sections.txt b/glabels2/docs/libglabels/libglabels-sections.txt index 89aacf18..279c4178 100644 --- a/glabels2/docs/libglabels/libglabels-sections.txt +++ b/glabels2/docs/libglabels/libglabels-sections.txt @@ -1,14 +1,17 @@
-enums -glUnitsType +libglabels +libglabels/libglabels.h
-libglabels +enums +libglabels/enums.h +glUnitsType
paper +libglabels/paper.h glPaper gl_paper_init gl_paper_new @@ -29,6 +32,7 @@ gl_paper_print_known_papers
template +libglabels/template.h glTemplate glTemplateLabelType glTemplateLayout @@ -72,6 +76,7 @@ gl_template_print_aliases
xml-paper +libglabels/xml-paper.h gl_xml_paper_read_papers_from_file gl_xml_paper_parse_papers_doc gl_xml_paper_parse_paper_node @@ -79,6 +84,7 @@ gl_xml_paper_parse_paper_node
xml-template +libglabels/xml-templates.h gl_xml_template_read_templates_from_file gl_xml_template_parse_templates_doc gl_xml_template_parse_template_node @@ -90,6 +96,7 @@ gl_xml_template_create_template_node
xml +libglabels/xml.h gl_xml_get_prop_double gl_xml_get_prop_boolean gl_xml_get_prop_int diff --git a/glabels2/docs/libglabels/libglabels-undocumented.txt b/glabels2/docs/libglabels/libglabels-undocumented.txt index 06b68d13..7ebb69e5 100644 --- a/glabels2/docs/libglabels/libglabels-undocumented.txt +++ b/glabels2/docs/libglabels/libglabels-undocumented.txt @@ -1,6 +1,6 @@ -14% symbol docs coverage. -11 symbols documented. -66 not documented. +47% symbol docs coverage. +36 symbols documented. +41 not documented. glPaper @@ -11,22 +11,6 @@ glTemplateLayout glTemplateMarkup glTemplateMarkupType glTemplateOrigin -glUnitsType -gl_paper_dup -gl_paper_free -gl_paper_free_id_list -gl_paper_free_name_list -gl_paper_from_id -gl_paper_from_name -gl_paper_get_id_list -gl_paper_get_name_list -gl_paper_init -gl_paper_is_id_known -gl_paper_is_id_other -gl_paper_lookup_id_from_name -gl_paper_lookup_name_from_id -gl_paper_new -gl_paper_print_known_papers gl_template_add_alias gl_template_add_label_type gl_template_add_layout @@ -59,14 +43,5 @@ gl_template_print_known_templates gl_template_rect_label_type_new gl_template_register gl_template_round_label_type_new -gl_xml_paper_parse_paper_node -gl_xml_paper_parse_papers_doc -gl_xml_paper_read_papers_from_file -gl_xml_template_create_template_node gl_xml_template_create_templates_doc -gl_xml_template_parse_template_node -gl_xml_template_parse_templates_doc -gl_xml_template_read_templates_from_file -gl_xml_template_write_template_to_file -gl_xml_template_write_templates_to_file diff --git a/glabels2/docs/libglabels/tmpl/enums.sgml b/glabels2/docs/libglabels/tmpl/enums.sgml index 0db82871..132a74e9 100644 --- a/glabels2/docs/libglabels/tmpl/enums.sgml +++ b/glabels2/docs/libglabels/tmpl/enums.sgml @@ -1,12 +1,12 @@ -enums +Basic Enumerations - +Common enumerations used by libglabels - +This section defines enumerations used to interact with libglabels. @@ -16,7 +16,11 @@ enums - +Enumerations for the units of length supported by libglabels. Internally +all lengths are in points. Externally libglabels supports points ("pt"), +inches ("in"), millimeters ("mm"), centimeters ("cm"), and picas ("pc"). +These units are identical to the absolute length units supported in +the CSS2 Specification (Section 4.3.2). @GL_UNITS_POINT: diff --git a/glabels2/docs/libglabels/tmpl/paper.sgml b/glabels2/docs/libglabels/tmpl/paper.sgml index ed1ff977..95a9ab22 100644 --- a/glabels2/docs/libglabels/tmpl/paper.sgml +++ b/glabels2/docs/libglabels/tmpl/paper.sgml @@ -1,12 +1,13 @@ -paper +Paper Definitions - +Paper size definitions - +This section describes a structure for representing a paper size definition +and related functions. diff --git a/glabels2/docs/libglabels/tmpl/xml-paper.sgml b/glabels2/docs/libglabels/tmpl/xml-paper.sgml index a96393ae..5c7b2316 100644 --- a/glabels2/docs/libglabels/tmpl/xml-paper.sgml +++ b/glabels2/docs/libglabels/tmpl/xml-paper.sgml @@ -1,12 +1,13 @@ -xml-paper +XML Paper Functions - +Functions to parse glabels XML paper definition files - +This section describes a number of functions for parsing glabels +XML paper definition files. diff --git a/glabels2/docs/libglabels/tmpl/xml-template.sgml b/glabels2/docs/libglabels/tmpl/xml-template.sgml index e774e6cd..e652c7cd 100644 --- a/glabels2/docs/libglabels/tmpl/xml-template.sgml +++ b/glabels2/docs/libglabels/tmpl/xml-template.sgml @@ -1,12 +1,14 @@ -xml-template +XML Template Functions - +Functions to create and parse glabels XML template nodes and files - +This section describes a number of functions for creating and parsing +glabels XML template nodes and files. Template nodes are used in both +template files and document files. diff --git a/glabels2/libglabels/enums.h b/glabels2/libglabels/enums.h index bc80a06f..59ec7049 100644 --- a/glabels2/libglabels/enums.h +++ b/glabels2/libglabels/enums.h @@ -32,11 +32,11 @@ G_BEGIN_DECLS /* Units of distance */ typedef enum { - GL_UNITS_POINT, - GL_UNITS_INCH, - GL_UNITS_MM, - GL_UNITS_CM, - GL_UNITS_PICA, + GL_UNITS_POINT, /* encoded as "pt" */ + GL_UNITS_INCH, /* encoded as "in" */ + GL_UNITS_MM, /* encoded as "mm" */ + GL_UNITS_CM, /* encoded as "cm" */ + GL_UNITS_PICA, /* encoded as "pc" */ GL_UNITS_FIRST = GL_UNITS_POINT, GL_UNITS_LAST = GL_UNITS_PICA, diff --git a/glabels2/libglabels/paper.c b/glabels2/libglabels/paper.c index 31cc1081..fd005d54 100644 --- a/glabels2/libglabels/paper.c +++ b/glabels2/libglabels/paper.c @@ -50,10 +50,12 @@ static GList *read_papers (void); static GList *read_paper_files_from_dir (GList *papers, const gchar *dirname); - -/*****************************************************************************/ -/* Initialize module. */ -/*****************************************************************************/ +/** + * gl_paper_init: + * + * Initialize libglabels paper module by reading all paper definition + * files located in system and user template directories. + */ void gl_paper_init (void) { @@ -70,9 +72,20 @@ gl_paper_init (void) papers = g_list_append (papers, other); } -/*****************************************************************************/ -/* Create a new paper structure. */ -/*****************************************************************************/ + +/** + * gl_paper_new: + * @id: Id of paper definition. (E.g. US-Letter, A4, etc.) Should be + * unique. + * @name: Localized name of paper. + * @width: Width of paper in points. + * @height: Height of paper in points. + * + * Allocates and constructs a new #glPaper structure. + * + * Returns: a pointer to a newly allocated #glPaper structure. + * + */ glPaper * gl_paper_new (gchar *id, gchar *name, @@ -90,10 +103,17 @@ gl_paper_new (gchar *id, return paper; } -/*****************************************************************************/ -/* Copy a paper. */ -/*****************************************************************************/ -glPaper *gl_paper_dup (const glPaper *orig_paper) + +/** + * gl_paper_dup: + * @orig: #glPaper structure to be duplicated. + * + * Duplicates an existing #glPaper structure. + * + * Returns: a pointer to a newly allocated #glPaper structure. + * + */ +glPaper *gl_paper_dup (const glPaper *orig) { glPaper *paper; @@ -109,9 +129,14 @@ glPaper *gl_paper_dup (const glPaper *orig_paper) return paper; } -/*****************************************************************************/ -/* Free up a paper. */ -/*****************************************************************************/ + +/** + * gl_paper_free: + * @paper: pointer to #glPaper structure to be freed. + * + * Free all memory associated with an existing #glPaper structure. + * + */ void gl_paper_free (glPaper *paper) { @@ -128,9 +153,15 @@ void gl_paper_free (glPaper *paper) } -/*****************************************************************************/ -/* Get a list of known page size ids */ -/*****************************************************************************/ + +/** + * gl_paper_get_id_list: + * + * Get a list of all paper ids known to libglabels. + * + * Returns: a list of paper ids. + * + */ GList * gl_paper_get_id_list (void) { @@ -150,9 +181,14 @@ gl_paper_get_id_list (void) return ids; } -/*****************************************************************************/ -/* Free a list of page size ids. */ -/*****************************************************************************/ +/** + * gl_paper_free_id_list: + * @ids: List of id strings to be freed. + * + * Free up all storage associated with an id list obtained with + * gl_paper_get_id_list(). + * + */ void gl_paper_free_id_list (GList *ids) { @@ -166,9 +202,15 @@ gl_paper_free_id_list (GList *ids) g_list_free (ids); } -/*****************************************************************************/ -/* Get a list of known page size names */ -/*****************************************************************************/ + +/** + * gl_paper_get_name_list: + * + * Get a list of all localized paper names known to libglabels. + * + * Returns: a list of localized paper names. + * + */ GList * gl_paper_get_name_list (void) { @@ -188,9 +230,15 @@ gl_paper_get_name_list (void) return names; } -/*****************************************************************************/ -/* Free a list of page size names. */ -/*****************************************************************************/ + +/** + * gl_paper_free_name_list: + * @names: List of localized paper name strings to be freed. + * + * Free up all storage associated with a name list obtained with + * gl_paper_get_name_list(). + * + */ void gl_paper_free_name_list (GList *names) { @@ -204,9 +252,16 @@ gl_paper_free_name_list (GList *names) g_list_free (names); } -/*****************************************************************************/ -/* Is page size id known? */ -/*****************************************************************************/ + +/** + * gl_paper_is_id_known: + * @id: paper id to test + * + * Determine if given paper id is known to libglabels. + * + * Returns: TRUE if id is known, otherwise FALSE. + * + */ gboolean gl_paper_is_id_known (const gchar *id) { @@ -231,9 +286,16 @@ gl_paper_is_id_known (const gchar *id) return FALSE; } -/*****************************************************************************/ -/* Is page size id "Other?" */ -/*****************************************************************************/ + +/** + * gl_paper_is_id_other: + * @id: paper id to test + * + * Determine if given paper id is the special id "Other." + * + * Returns: TRUE if id is "Other", otherwise FALSE. + * + */ gboolean gl_paper_is_id_other (const gchar *id) { @@ -244,9 +306,16 @@ gl_paper_is_id_other (const gchar *id) return (g_strcasecmp (id, "Other") == 0); } -/*****************************************************************************/ -/* Return a paper structure from id. */ -/*****************************************************************************/ + +/** + * gl_paper_from_id: + * @id: paper id string + * + * Lookup paper definition from id string. + * + * Returns: pointer to a newly allocated #glPaper structure. + * + */ glPaper * gl_paper_from_id (const gchar *id) { @@ -272,9 +341,16 @@ gl_paper_from_id (const gchar *id) return NULL; } -/*****************************************************************************/ -/* Return a paper structure from name. */ -/*****************************************************************************/ + +/** + * gl_paper_from_name: + * @name: localized paper name string + * + * Lookup paper definition from localized paper name string. + * + * Returns: pointer to a newly allocated #glPaper structure. + * + */ glPaper * gl_paper_from_name (const gchar *name) { @@ -300,9 +376,16 @@ gl_paper_from_name (const gchar *name) return NULL; } -/*****************************************************************************/ -/* Lookup paper id from name. */ -/*****************************************************************************/ + +/** + * gl_paper_lookup_id_from_name: + * @name: localized paper name stringp + * + * Lookup paper name string from localized paper name string. + * + * Returns: pointer to a newly allocated id string. + * + */ gchar * gl_paper_lookup_id_from_name (const gchar *name) { @@ -321,9 +404,15 @@ gl_paper_lookup_id_from_name (const gchar *name) return id; } -/*****************************************************************************/ -/* Lookup paper name from id. */ -/*****************************************************************************/ +/** + * gl_paper_lookup_name_from_id: + * @id: paper id string + * + * Lookup localized paper name string from paper id string. + * + * Returns: pointer to a newly allocated localized paper name string. + * + */ gchar * gl_paper_lookup_name_from_id (const gchar *id) { @@ -343,7 +432,7 @@ gl_paper_lookup_name_from_id (const gchar *id) } /*--------------------------------------------------------------------------*/ -/* PRIVATE. Read papers from various files. */ +/* PRIVATE. Read papers from various files. */ /*--------------------------------------------------------------------------*/ static GList * read_papers (void) @@ -367,7 +456,7 @@ read_papers (void) } /*--------------------------------------------------------------------------*/ -/* PRIVATE. Read all paper files from given directory. Append to list. */ +/* PRIVATE. Read all paper files from given directory. Append to list. */ /*--------------------------------------------------------------------------*/ static GList * read_paper_files_from_dir (GList *papers, @@ -422,9 +511,14 @@ read_paper_files_from_dir (GList *papers, return papers; } -/*****************************************************************************/ -/* Print known papers (for debugging purposes) */ -/*****************************************************************************/ + +/** + * gl_paper_print_known_papers: + * + * For debugging purposes: print a list of all paper definitions known to + * libglabels. + * + */ void gl_paper_print_known_papers (void) { diff --git a/glabels2/libglabels/paper.h b/glabels2/libglabels/paper.h index aeb1bce4..9cf99915 100644 --- a/glabels2/libglabels/paper.h +++ b/glabels2/libglabels/paper.h @@ -37,10 +37,10 @@ G_BEGIN_DECLS typedef struct _glPaper glPaper; struct _glPaper { - gchar *id; - gchar *name; - gdouble width; - gdouble height; + gchar *id; /* Unique ID of paper definition */ + gchar *name; /* Localized name of paper */ + gdouble width; /* Width (in points) */ + gdouble height; /* Height (in points) */ }; diff --git a/glabels2/libglabels/xml-paper.c b/glabels2/libglabels/xml-paper.c index 7afd0512..54eaadd2 100644 --- a/glabels2/libglabels/xml-paper.c +++ b/glabels2/libglabels/xml-paper.c @@ -45,10 +45,16 @@ /* Local function prototypes */ /*===========================================*/ - -/*****************************************************************************/ -/* Read papers from paper file. */ -/*****************************************************************************/ + +/** + * gl_xml_paper_read_papers_from_file: + * @utf8_filename: Filename of papers file (name encoded as UTF-8) + * + * Read paper definitions from a file. + * + * Returns: a list of #glPaper structures. + * + */ GList * gl_xml_paper_read_papers_from_file (gchar *utf8_filename) { @@ -79,9 +85,16 @@ gl_xml_paper_read_papers_from_file (gchar *utf8_filename) return papers; } -/*****************************************************************************/ -/* Read papers from paper xml doc tree. */ -/*****************************************************************************/ + +/** + * gl_xml_paper_parse_papers_doc: + * @papers_doc: libxml #xmlDocPtr tree, representing a papers definition file. + * + * Read paper definitions from a libxml #xmlDocPtr tree. + * + * Returns: a list of #glPaper structures. + * + */ GList * gl_xml_paper_parse_papers_doc (xmlDocPtr papers_doc) { @@ -122,9 +135,16 @@ gl_xml_paper_parse_papers_doc (xmlDocPtr papers_doc) return papers; } -/*****************************************************************************/ -/* Parse XML paper Node. */ -/*****************************************************************************/ + +/** + * gl_xml_paper_parse_paper_node: + * @paper_node: libxml #xmlNodePtr paper node from a #xmlDocPtr tree. + * + * Read a single paper definition from a libxml #xmlNodePtr node. + * + * Returns: a pointer to a newly created #glPaper structure. + * + */ glPaper * gl_xml_paper_parse_paper_node (xmlNodePtr paper_node) { diff --git a/glabels2/libglabels/xml-template.c b/glabels2/libglabels/xml-template.c index fb4365eb..25f2ad84 100644 --- a/glabels2/libglabels/xml-template.c +++ b/glabels2/libglabels/xml-template.c @@ -82,9 +82,15 @@ static void xml_create_alias_node (const gchar *name, const xmlNsPtr ns); -/*****************************************************************************/ -/* Read templates from template file. */ -/*****************************************************************************/ +/** + * gl_xml_template_read_templates_from_file: + * @utf8_filename: Filename of papers file (name encoded as UTF-8) + * + * Read glabels templates from template file. + * + * Returns: a list of #glTemplate structures. + * + */ GList * gl_xml_template_read_templates_from_file (const gchar *utf8_filename) { @@ -115,9 +121,16 @@ gl_xml_template_read_templates_from_file (const gchar *utf8_filename) return templates; } -/*****************************************************************************/ -/* Read templates from templates xml doc tree. */ -/*****************************************************************************/ + +/** + * gl_xml_template_parse_templates_doc: + * @templates_doc: libxml #xmlDocPtr tree, representing template file. + * + * Read glabels templates from a libxml #xmlDocPtr tree. + * + * Returns: a list of #glTemplate structures. + * + */ GList * gl_xml_template_parse_templates_doc (const xmlDocPtr templates_doc) { @@ -157,9 +170,16 @@ gl_xml_template_parse_templates_doc (const xmlDocPtr templates_doc) return templates; } -/*****************************************************************************/ -/* Parse XML template Node. */ -/*****************************************************************************/ + +/** + * gl_xml_template_parse_template_node: + * @template_node: libxml #xmlNodePtr template node from a #xmlDocPtr tree. + * + * Read a single glabels template from a libxml #xmlNodePtr node. + * + * Returns: a pointer to a newly created #glTemplate structure. + * + */ glTemplate * gl_xml_template_parse_template_node (const xmlNodePtr template_node) { @@ -507,9 +527,14 @@ xml_parse_alias_node (xmlNodePtr alias_node, g_free (name); } -/****************************************************************************/ -/* Write a list of templates to XML file. */ -/****************************************************************************/ +/** + * gl_xml_template_write_templates_to_file: + * @templates: List of #glTemplate structures + * @utf8_filename: Filename of templates file (name encoded as UTF-8) + * + * Write a list of #glTemplate structures to a glabels XML template file. + * + */ void gl_xml_template_write_templates_to_file (GList *templates, const gchar *utf8_filename) @@ -549,9 +574,15 @@ gl_xml_template_write_templates_to_file (GList *templates, } -/****************************************************************************/ -/* Write single template to XML file. */ -/****************************************************************************/ + +/** + * gl_xml_template_write_template_to_file: + * @template: #glTemplate structure to be written + * @utf8_filename: Filename of templates file (name encoded as UTF-8) + * + * Write a single #glTemplate structures to a glabels XML template file. + * + */ void gl_xml_template_write_template_to_file (const glTemplate *template, const gchar *utf8_filename) @@ -565,9 +596,16 @@ gl_xml_template_write_template_to_file (const glTemplate *template, g_list_free (templates); } -/****************************************************************************/ -/* Add XML Template Node */ -/****************************************************************************/ + +/** + * gl_xml_template_create_template_node: + * @template: #glTemplate structure to be written + * @root: parent node to receive new child node + * @ns: a libxml #xmlNsPtr + * + * Add a single #glTemplate child node to given #xmlNodePtr. + * + */ void gl_xml_template_create_template_node (const glTemplate *template, xmlNodePtr root, -- 2.39.5