+2005-04-02 Jim Evins <evins@snaught.com>
+
+ * 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 <evins@snaught.com>
* INSTALL:
<SECTION>
-<FILE>enums</FILE>
-glUnitsType
+<FILE>libglabels</FILE>
+<INCLUDE>libglabels/libglabels.h</INCLUDE>
</SECTION>
<SECTION>
-<FILE>libglabels</FILE>
+<FILE>enums</FILE>
+<INCLUDE>libglabels/enums.h</INCLUDE>
+glUnitsType
</SECTION>
<SECTION>
<FILE>paper</FILE>
+<INCLUDE>libglabels/paper.h</INCLUDE>
glPaper
gl_paper_init
gl_paper_new
<SECTION>
<FILE>template</FILE>
+<INCLUDE>libglabels/template.h</INCLUDE>
glTemplate
glTemplateLabelType
glTemplateLayout
<SECTION>
<FILE>xml-paper</FILE>
+<INCLUDE>libglabels/xml-paper.h</INCLUDE>
gl_xml_paper_read_papers_from_file
gl_xml_paper_parse_papers_doc
gl_xml_paper_parse_paper_node
<SECTION>
<FILE>xml-template</FILE>
+<INCLUDE>libglabels/xml-templates.h</INCLUDE>
gl_xml_template_read_templates_from_file
gl_xml_template_parse_templates_doc
gl_xml_template_parse_template_node
<SECTION>
<FILE>xml</FILE>
+<INCLUDE>libglabels/xml.h</INCLUDE>
gl_xml_get_prop_double
gl_xml_get_prop_boolean
gl_xml_get_prop_int
-14% symbol docs coverage.
-11 symbols documented.
-66 not documented.
+47% symbol docs coverage.
+36 symbols documented.
+41 not documented.
glPaper
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
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
<!-- ##### SECTION Title ##### -->
-enums
+Basic Enumerations
<!-- ##### SECTION Short_Description ##### -->
-
+Common enumerations used by libglabels
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section defines enumerations used to interact with libglabels.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### ENUM glUnitsType ##### -->
<para>
-
+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).
</para>
@GL_UNITS_POINT:
<!-- ##### SECTION Title ##### -->
-paper
+Paper Definitions
<!-- ##### SECTION Short_Description ##### -->
-
+Paper size definitions
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section describes a structure for representing a paper size definition
+and related functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### SECTION Title ##### -->
-xml-paper
+XML Paper Functions
<!-- ##### SECTION Short_Description ##### -->
-
+Functions to parse glabels XML paper definition files
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section describes a number of functions for parsing glabels
+XML paper definition files.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### SECTION Title ##### -->
-xml-template
+XML Template Functions
<!-- ##### SECTION Short_Description ##### -->
-
+Functions to create and parse glabels XML template nodes and files
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+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.
</para>
<!-- ##### SECTION See_Also ##### -->
/* 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,
static GList *read_paper_files_from_dir (GList *papers,
const gchar *dirname);
-\f
-/*****************************************************************************/
-/* 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)
{
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,
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;
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)
{
}
-/*****************************************************************************/
-/* 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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
}
/*--------------------------------------------------------------------------*/
-/* PRIVATE. Read papers from various files. */
+/* PRIVATE. Read papers from various files. */
/*--------------------------------------------------------------------------*/
static GList *
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,
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)
{
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) */
};
/* Local function prototypes */
/*===========================================*/
-\f
-/*****************************************************************************/
-/* 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)
{
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)
{
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)
{
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)
{
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)
{
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)
{
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)
}
-/****************************************************************************/
-/* 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)
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,
projects / glabels / commitdiff