Cleanup of libglabels documentation.

Added documentation for new functionality in 3.0, including the vendor
database and a new "natural order" compare function for sorting
part numbers.

diff --git a/docs/libglabels/libglabels-3.0-docs.sgml b/docs/libglabels/libglabels-3.0-docs.sgml
index 9473f36c16671cdf5796b68e7d3e619dcb3ea4f3..28ddc6124d23561d117b4881a7bff2edd9e53c6a 100644 (file)
--- a/docs/libglabels/libglabels-3.0-docs.sgml
+++ b/docs/libglabels/libglabels-3.0-docs.sgml
@@ -14,6 +14,7 @@
     <xi:include href="xml/template.xml"/>
     <xi:include href="xml/paper.xml"/>
     <xi:include href="xml/category.xml"/>
+    <xi:include href="xml/vendor.xml"/>
   </chapter>
 
   <chapter>
@@ -21,6 +22,7 @@
     <xi:include href="xml/xml-paper.xml"/>
     <xi:include href="xml/xml-category.xml"/>
     <xi:include href="xml/xml-template.xml"/>
+    <xi:include href="xml/xml-vendor.xml"/>
     <xi:include href="xml/xml.xml"/>
   </chapter>
 

diff --git a/docs/libglabels/libglabels-3.0-sections.txt b/docs/libglabels/libglabels-3.0-sections.txt
index e6fb32f05c791c452f765a27af217fa83286fe43..93918084240e2b3a0bf79029e209c8982276cdb8 100644 (file)
--- a/docs/libglabels/libglabels-3.0-sections.txt
+++ b/docs/libglabels/libglabels-3.0-sections.txt
@@ -36,6 +36,12 @@ lgl_db_get_template_name_list_unique
 lgl_db_get_template_name_list_all
 lgl_db_free_template_name_list
 lgl_db_lookup_template_from_name
+lgl_db_lookup_template_from_brand_part
+<SUBSECTION Vendor Functions>
+lgl_db_get_vendor_name_list
+lgl_db_free_vendor_name_list
+lgl_db_is_vendor_name_known
+lgl_db_lookup_vendor_from_name
 <SUBSECTION Debugging Functions>
 lgl_db_print_known_papers
 lgl_db_print_known_categories
@@ -66,10 +72,12 @@ lglTemplateMarkupMargin
 lglTemplateMarkupLine
 lglTemplateMarkupCircle
 lglTemplateMarkupRect
+lglTemplateMarkupEllipse
 <SUBSECTION Origin Structure>
 lglTemplateOrigin
 <SUBSECTION Template Functions>
 lgl_template_new
+lgl_template_new_from_equiv
 lgl_template_dup
 lgl_template_free
 lgl_template_add_category
@@ -87,6 +95,7 @@ lgl_template_alias_dup
 lgl_template_alias_free
 <SUBSECTION Frame Functions>
 lgl_template_frame_rect_new
+lgl_template_frame_ellipse_new
 lgl_template_frame_round_new
 lgl_template_frame_cd_new
 lgl_template_frame_dup
@@ -106,6 +115,7 @@ lgl_template_markup_margin_new
 lgl_template_markup_line_new
 lgl_template_markup_circle_new
 lgl_template_markup_rect_new
+lgl_template_markup_ellipse_new
 lgl_template_markup_dup
 lgl_template_markup_free
 </SECTION>
@@ -128,6 +138,15 @@ lgl_category_dup
 lgl_category_free
 </SECTION>
 
+<SECTION>
+<FILE>vendor</FILE>
+<INCLUDE>libglabels/vendor.h</INCLUDE>
+lglVendor
+lgl_vendor_new
+lgl_vendor_dup
+lgl_vendor_free
+</SECTION>
+
 <SECTION>
 <FILE>xml-paper</FILE>
 <INCLUDE>libglabels/xml-paper.h</INCLUDE>
@@ -155,6 +174,14 @@ lgl_xml_template_write_template_to_file
 lgl_xml_template_create_template_node
 </SECTION>
 
+<SECTION>
+<FILE>xml-vendor</FILE>
+<INCLUDE>libglabels/xml-vendor.h</INCLUDE>
+lgl_xml_vendor_read_vendors_from_file
+lgl_xml_vendor_parse_vendors_doc
+lgl_xml_vendor_parse_vendor_node
+</SECTION>
+
 <SECTION>
 <FILE>xml</FILE>
 <INCLUDE>libglabels/xml.h</INCLUDE>
@@ -197,5 +224,6 @@ lgl_units_get_units_per_point
 <FILE>str</FILE>
 <INCLUDE>libglabels/str.h</INCLUDE>
 lgl_str_utf8_casecmp
+lgl_str_part_name_cmp
 </SECTION>
 

diff --git a/docs/libglabels/tmpl/db.sgml b/docs/libglabels/tmpl/db.sgml
index 3d5d2de3568f52670ccc86f2c90d1ed9ac64a688..4c2705bff34e91d042de93c64c26d1b50f62699a 100644 (file)
--- a/docs/libglabels/tmpl/db.sgml
+++ b/docs/libglabels/tmpl/db.sgml
@@ -283,6 +283,50 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_db_lookup_template_from_brand_part ##### -->
+<para>
+
+</para>
+
+@brand: 
+@part: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_db_get_vendor_name_list ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_db_free_vendor_name_list ##### -->
+<para>
+
+</para>
+
+@names: 
+
+
+<!-- ##### FUNCTION lgl_db_is_vendor_name_known ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_db_lookup_vendor_from_name ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
 <!-- ##### FUNCTION lgl_db_print_known_papers ##### -->
 <para>
 

diff --git a/docs/libglabels/tmpl/str.sgml b/docs/libglabels/tmpl/str.sgml
index 53cbd3b998cb536d9c4dc889d9db41a33a3390ff..e333fb0046898b54aa854607cd6a70032903145f 100644 (file)
--- a/docs/libglabels/tmpl/str.sgml
+++ b/docs/libglabels/tmpl/str.sgml
@@ -28,3 +28,13 @@ possible use to a user of libglabels.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_str_part_name_cmp ##### -->
+<para>
+
+</para>
+
+@s1: 
+@s2: 
+@Returns: 
+
+

diff --git a/docs/libglabels/tmpl/template.sgml b/docs/libglabels/tmpl/template.sgml
index ae363e42d025c16b731c7b6f46061016543abba1..57e7405c1c2d32b507bd8359467abe512e1dc8d6 100644 (file)
--- a/docs/libglabels/tmpl/template.sgml
+++ b/docs/libglabels/tmpl/template.sgml
@@ -208,6 +208,17 @@ This structure defines a simple rectangle markup.  The rectangle can have rounde
 @h: Height of rectangle in points.
 @r: Radius of corners in points.  Should be zero for sharp corners.
 
+<!-- ##### STRUCT lglTemplateMarkupEllipse ##### -->
+<para>
+This structure defines a simple elliptical markup.
+</para>
+
+@type: Common field.  Always #LGL_TEMPLATE_MARKUP_ELLIPSE for #lglTemplateMarkupEllipse.
+@x1: Distance (in points) of left edge of markup from left edge of label or card.
+@y1: Distance (in points) of top edge of markup from top edge of label or card.
+@w: Width of rectangle in points.
+@h: Height of rectangle in points.
+
 <!-- ##### STRUCT lglTemplateOrigin ##### -->
 <para>
 This structure represents the cartesian coordinates of the origin of a label or card on the page.
@@ -232,6 +243,17 @@ relative to the upper left corner of the page.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_template_new_from_equiv ##### -->
+<para>
+
+</para>
+
+@brand: 
+@part: 
+@equiv_part: 
+@Returns: 
+
+
 <!-- ##### FUNCTION lgl_template_dup ##### -->
 <para>
 
@@ -366,6 +388,18 @@ relative to the upper left corner of the page.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_template_frame_ellipse_new ##### -->
+<para>
+
+</para>
+
+@id: 
+@w: 
+@h: 
+@waste: 
+@Returns: 
+
+
 <!-- ##### FUNCTION lgl_template_frame_round_new ##### -->
 <para>
 
@@ -530,6 +564,18 @@ relative to the upper left corner of the page.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_template_markup_ellipse_new ##### -->
+<para>
+
+</para>
+
+@x1: 
+@y1: 
+@w: 
+@h: 
+@Returns: 
+
+
 <!-- ##### FUNCTION lgl_template_markup_dup ##### -->
 <para>
 

diff --git a/docs/libglabels/tmpl/vendor.sgml b/docs/libglabels/tmpl/vendor.sgml
new file mode 100644 (file)
index 0000000..1dee004
--- /dev/null
+++ b/docs/libglabels/tmpl/vendor.sgml
@@ -0,0 +1,53 @@
+<!-- ##### SECTION Title ##### -->
+The lglVendor Structure
+
+<!-- ##### SECTION Short_Description ##### -->
+Vendor definitions
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This section describes a structure for representing vendor data.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT lglVendor ##### -->
+<para>
+This structure defines a vendor.
+</para>
+
+@name: Vendor name.  (e.g. "Avery")
+@url: URL to vendor website
+
+<!-- ##### FUNCTION lgl_vendor_new ##### -->
+<para>
+
+</para>
+
+@name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_vendor_dup ##### -->
+<para>
+
+</para>
+
+@orig: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_vendor_free ##### -->
+<para>
+
+</para>
+
+@vendor: 
+
+

diff --git a/docs/libglabels/tmpl/xml-vendor.sgml b/docs/libglabels/tmpl/xml-vendor.sgml
new file mode 100644 (file)
index 0000000..2550d25
--- /dev/null
+++ b/docs/libglabels/tmpl/xml-vendor.sgml
@@ -0,0 +1,46 @@
+<!-- ##### SECTION Title ##### -->
+XML Vendor Functions
+
+<!-- ##### SECTION Short_Description ##### -->
+Functions to parse glabels XML vendor descriptions
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This section describes several functions for parsing vendor XML description files.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### FUNCTION lgl_xml_vendor_read_vendors_from_file ##### -->
+<para>
+
+</para>
+
+@utf8_filename: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_xml_vendor_parse_vendors_doc ##### -->
+<para>
+
+</para>
+
+@vendors_doc: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lgl_xml_vendor_parse_vendor_node ##### -->
+<para>
+
+</para>
+
+@vendor_node: 
+@Returns: 
+
+

diff --git a/libglabels/str.c b/libglabels/str.c
index 627e6be41817b184aaafd54ac4ae906ba5b0f139..e93a9913756c6adb5bd9e3246a8a7ad95f761f0c 100644 (file)
--- a/libglabels/str.c
+++ b/libglabels/str.c
@@ -86,10 +86,15 @@ lgl_str_utf8_casecmp (const gchar *s1,
  *
  * Compare two UTF-8 strings representing part names or numbers.  This function
  * uses a natural sort order:
+ *
  *  - Ignores case.
+ *
  *  - Strings are divided into chunks (numeric and non-numeric)
+ *
  *  - Non-numeric chunks are compared character by character
+ *
  *  - Numerical chunks are compared numerically, so that "20" precedes "100".
+ *
  *  - Comparison of chunks is performed left to right until the first difference
  *    is encountered or all chunks evaluate as equal.
  *

diff --git a/libglabels/template.c b/libglabels/template.c
index 9c1e71f2b0200ddba5fc230e44890e29ad07ed95..0af4e5deda2a72111bf1f864a5aee5451ed699a7 100644 (file)
--- a/libglabels/template.c
+++ b/libglabels/template.c
@@ -414,9 +414,7 @@ lgl_template_frame_rect_new  (const gchar         *id,
  *   @id:      ID of frame.  (This should currently always be "0").
  *   @w:       width of frame in points.
  *   @h:       height of frame in points.
- *   @r:       radius of rounded corners in points.  (Should be 0 for square corners.)
- *   @x_waste: Amount of overprint to allow in the horizontal direction.
- *   @y_waste: Amount of overprint to allow in the vertical direction.
+ *   @waste:   Amount of overprint to allow in points.
  *
  * This function creates a new template frame for an elliptical label or card.
  *

diff --git a/libglabels/vendor.c b/libglabels/vendor.c
index 9ee29bfb96e7bfec296206c116b135479a09fdbf..e7f950bd3e3360a1fadd877829f5b57abde8ccaa 100644 (file)
--- a/libglabels/vendor.c
+++ b/libglabels/vendor.c
@@ -49,12 +49,7 @@
 
 /**
  * lgl_vendor_new:
- * @id:       Id of vendor definition. (E.g. US-Letter, A4, etc.)  Should be
- *            unique.
  * @name:     Localized name of vendor.
- * @width:    Width of vendor in points.
- * @height:   Height of vendor in points.
- * @pwg_size: PWG 5101.1-2002 size name.
  *
  * Allocates and constructs a new #lglVendor structure.
  *

diff --git a/libglabels/xml-template.c b/libglabels/xml-template.c
index a6f10a45a83af3514256a8961bb90103f4c9e9b3..75b6fec415f69de6ea36ed8db08310b1c3ffc5e3 100644 (file)
--- a/libglabels/xml-template.c
+++ b/libglabels/xml-template.c
@@ -104,8 +104,6 @@ static void  xml_create_alias_node          (const lglTemplateAlias       *alias
  *
  * Read glabels templates from template file.
  *
- * Returns: a list of #lglTemplate structures.
- *
  */
 void
 lgl_xml_template_read_templates_from_file (const gchar *utf8_filename)
@@ -142,8 +140,6 @@ lgl_xml_template_read_templates_from_file (const gchar *utf8_filename)
  *
  * Read glabels templates from a libxml #xmlDocPtr tree.
  *
- * Returns: a list of #lglTemplate structures.
- *
  */
 void
 lgl_xml_template_parse_templates_doc (const xmlDocPtr templates_doc)