## Utility functions

Utility functions —

## Synopsis

    gboolean    cong_util_is_docbook            (CongDocument *doc);
    gboolean    cong_util_is_pure_whitespace    (const gchar *utf8_text);
    gchar*      cong_util_cleanup_text          (const gchar *text);
    gchar*      cong_util_text_header           (const gchar *text,
                                                 guint truncation_length);
    gchar*      cong_utils_get_norman_walsh_stylesheet_path
                                                (void);
    gchar*      cong_utils_get_norman_walsh_stylesheet
                                                (const gchar *stylesheet_relative_path);
    GdkPixbuf*  cong_util_load_icon             (const gchar *icon_basename);
    void        cong_util_append                (gchar **string,
                                                 const gchar *to_add);
    void        cong_util_prepend               (gchar **string,
                                                 const gchar *to_add);
    void        cong_util_print_xslfo           (GtkWindow *toplevel_window,
                                                 GnomePrintContext *gpc,
                                                 xmlDocPtr xml_doc);
    #define     CONG_GET_VAR_STR                (msg, str)
    xmlDtdPtr   cong_util_make_dtd              (xmlDocPtr xml_doc,
                                                 const gchar *root_element,
                                                 const gchar *ExternalID,
                                                 const gchar *SystemID);
    xmlDtdPtr   cong_util_add_external_dtd      (xmlDocPtr xml_doc,
                                                 const gchar *root_element,
                                                 const gchar *ExternalID,
                                                 const gchar *SystemID);
    void        cong_util_run_add_dtd_dialog    (CongDocument *doc,
                                                 GtkWindow *parent_window);
    void        cong_util_draw_blended_line     (GtkWidget *w,
                                                 const GdkColor *col,
                                                 int x0,
                                                 int y0,
                                                 int x1);
    gboolean    cong_util_ns_equality           (const xmlNs *xml_ns1,
                                                 const xmlNs *xml_ns2);
    gboolean    cong_util_ns_uri_equality       (const gchar *uri0,
                                                 const gchar *uri1);
    gint        cong_util_ns_uri_sort_order     (const gchar *uri0,
                                                 const gchar *uri1);
    GtkWidget*  cong_util_make_source_view      (const gchar *source_mime_type,
                                                 GtkTextView **output_text_view);
    GtkWidget*  cong_source_view_new_full       (CongDocument *doc,
                                                 const gchar *source_mime_type,
                                                 void (*regeneration_cb) (CongDocument *doc,GtkTextBuffer *text_buffer));
    gboolean    cong_util_attribute_value_equality
                                                (const gchar *value0,
                                                 const gchar *value1);
    CongElementDescription* cong_element_description_new
                                                (const gchar *ns_uri,
                                                 const gchar *local_name);
    CongElementDescription* cong_element_description_clone
                                                (const CongElementDescription *element_desc);
    void        cong_element_description_free   (CongElementDescription *element_desc);
    CongNodePtr cong_element_description_make_node
                                                (const CongElementDescription *element_desc,
                                                 CongDocument *doc,
                                                 CongNodePtr ns_search_node);
    CongDispspecElement* cong_element_description_get_dispspec_element_for_doc
                                                (const CongElementDescription *element_desc,
                                                 CongDocument *doc);
    CongDispspecElement* cong_element_description_get_dispspec_element_for_dispspec
                                                (const CongElementDescription *element_desc,
                                                 CongDispspec *ds);
    gchar*      cong_element_description_get_qualified_name
                                                (const CongElementDescription *element_desc,
                                                 CongDispspec *ds);
    void        cong_element_description_list_free
                                                (GList *list_of_element_desc);
    CongElementDescription* cong_util_modal_element_selection_dialog
                                                (const gchar *title,
                                                 const gchar *description,
                                                 CongDocument *doc,
                                                 GList *elements);
    GtkMenuItem* cong_util_make_menu_item       (const gchar *label,
                                                 const gchar *tip,
                                                 GdkPixbuf *pixbuf);
    GtkMenuItem* cong_util_make_stock_menu_item (const gchar *stock_id);
    void        cong_util_add_menu_separator    (CongPrimaryWindow *primary_window,
                                                 const gchar *parent_ui_path);
    char*       cong_util_get_qualified_attribute_name
                                                (const xmlNs *namespace,
                                                 const gchar *local_attribute_name);
    void        cong_util_show_in_window        (GtkWidget *content,
                                                 const gchar *title);
    GtkFileFilter* cong_util_make_file_filter   (const gchar *name,
                                                 const gchar *mime_type);

## Description

## Details

### cong_util_is_docbook ()

    gboolean    cong_util_is_docbook            (CongDocument *doc);

TODO: Write me

`doc` : |
Returns : |

### cong_util_is_pure_whitespace ()

    gboolean    cong_util_is_pure_whitespace    (const gchar *utf8_text);

TODO: Write me

`utf8_text` : |
Returns : |

### cong_util_cleanup_text ()

    gchar*      cong_util_cleanup_text          (const gchar *text);

Handy function for taking UTF8 text and turning it into something you can see in a log: tabs and carriage returns etc are turned into visible characters.

`text` : | input UTF8 text
Returns : | a freshly-allocated string, with all tabs and carriage returns turned into their printf equivalents

### cong_util_text_header ()

    gchar*      cong_util_text_header           (const gchar *text,
                                                 guint truncation_length);

Handy function for taking UTF8 text and turning it into something you can use in short user-visible message: tabs and carriage returns etc are turned into spaces, and it is truncated with an ellipsis if above a certain length.

`text` : | input UTF8 text
`truncation_length` : |
Returns : | a freshly-allocated string, cleaned up as described above

### cong_utils_get_norman_walsh_stylesheet_path ()

    gchar*      cong_utils_get_norman_walsh_stylesheet_path
                                                (void);

Try to locate Norman Walsh's stylesheets for DocBook using the local catalog to find them.

Returns : | a string containing the path (which the caller must delete), or NULL

### cong_utils_get_norman_walsh_stylesheet ()

    gchar*      cong_utils_get_norman_walsh_stylesheet
                                                (const gchar *stylesheet_relative_path);

TODO: Write me

`stylesheet_relative_path` : |
Returns : |

### cong_util_load_icon ()

    GdkPixbuf*  cong_util_load_icon             (const gchar *icon_basename);

TODO: Write me

`icon_basename` : |
Returns : |

### cong_util_append ()

    void        cong_util_append                (gchar **string,
                                                 const gchar *to_add);

TODO: Write me

`string` : |
`to_add` : |

### cong_util_prepend ()

    void        cong_util_prepend               (gchar **string,
                                                 const gchar *to_add);

TODO: Write me

`string` : |
`to_add` : |

### cong_util_print_xslfo ()

    void        cong_util_print_xslfo           (GtkWindow *toplevel_window,
                                                 GnomePrintContext *gpc,
                                                 xmlDocPtr xml_doc);

TODO: Write me

`toplevel_window` : |
`gpc` : |
`xml_doc` : |

### CONG_GET_VAR_STR()

    #define     CONG_GET_VAR_STR(msg, str)

`msg` : |
`str` : |

### cong_util_make_dtd ()

    xmlDtdPtr   cong_util_make_dtd              (xmlDocPtr xml_doc,
                                                 const gchar *root_element,
                                                 const gchar *ExternalID,
                                                 const gchar *SystemID);

Make DTD declaration, and assigns it to the given document. Doesn't add it to doc tree

`xml_doc` : |
`root_element` : |
`ExternalID` : |
`SystemID` : |
Returns : | the xmlDtdPtr that was assigned

### cong_util_add_external_dtd ()

    xmlDtdPtr   cong_util_add_external_dtd      (xmlDocPtr xml_doc,
                                                 const gchar *root_element,
                                                 const gchar *ExternalID,
                                                 const gchar *SystemID);

Make DTD declaration, assigns it to the given document, and add it to the tree. Call `cong_document_set_external_dtd()` instead if you want notifications to work.

`xml_doc` : |
`root_element` : |
`ExternalID` : |
`SystemID` : |
Returns : | the xmlDtdPtr that was assigned

### cong_util_run_add_dtd_dialog ()

    void        cong_util_run_add_dtd_dialog    (CongDocument *doc,
                                                 GtkWindow *parent_window);

Open a dialog for choosing a DTD to associate with the document

`doc` : |
`parent_window` : |

### cong_util_draw_blended_line ()

    void        cong_util_draw_blended_line     (GtkWidget *w,
                                                 const GdkColor *col,
                                                 int x0,
                                                 int y0,
                                                 int x1);

TODO: Write me

`w` : |
`col` : |
`x0` : |
`y0` : |
`x1` : |

### cong_util_ns_equality ()

    gboolean    cong_util_ns_equality           (const xmlNs *xml_ns1,
                                                 const xmlNs *xml_ns2);

Compares the namespace URIs of both namespaces. The prefixes are not checked. If both are NULL they are also equal.

`xml_ns1` : | A namespace. Can be NULL.
`xml_ns2` : | Another namespace. Can be NULL.
Returns : |

### cong_util_ns_uri_equality ()

    gboolean    cong_util_ns_uri_equality       (const gchar *uri0,
                                                 const gchar *uri1);

Compare two namespace URIs, either or both of which can be NULL.

Currently the comparison is an exact string comparison, which might be too strict, see p118 of "Effective XML" for a discussion of ambiguities in the spec.

`uri0` : |
`uri1` : |
Returns : | TRUE if they are the same URI (or both NULL), FALSE otherwise

### cong_util_ns_uri_sort_order ()

    gint        cong_util_ns_uri_sort_order     (const gchar *uri0,
                                                 const gchar *uri1);

Compare two namespace URIs, either or both of which can be NULL.

Currently the comparison is an exact string comparison, which might be too strict, see p118 of "Effective XML" for a discussion of ambiguities in the spec.

`uri0` : |
`uri1` : |
Returns : | 0 if they are the same URI (or both NULL), otherwise positive or negative to give an ordering

### cong_util_make_source_view ()

    GtkWidget*  cong_util_make_source_view      (const gchar *source_mime_type,
                                                 GtkTextView **output_text_view);

`source_mime_type` : |
`output_text_view` : |
Returns : |

### cong_source_view_new_full ()

    GtkWidget*  cong_source_view_new_full       (CongDocument *doc,
                                                 const gchar *source_mime_type,
                                                 void (*regeneration_cb) (CongDocument *doc,GtkTextBuffer *text_buffer));

`doc` : |
`source_mime_type` : |
`regeneration_cb` : |
Returns : |

### cong_util_attribute_value_equality ()

    gboolean    cong_util_attribute_value_equality
                                                (const gchar *value0,
                                                 const gchar *value1);

Compare two attribute value strings for equality; either or both might be NULL

`value0` : |
`value1` : |
Returns : | TRUE if they are equal (i.e. the same string, or both are NULL)

### cong_element_description_new ()

    CongElementDescription* cong_element_description_new
                                                (const gchar *ns_uri,
                                                 const gchar *local_name);

TODO: Write me

`ns_uri` : |
`local_name` : |
Returns : |

### cong_element_description_clone ()

    CongElementDescription* cong_element_description_clone
                                                (const CongElementDescription *element_desc);

TODO: Write me

`element_desc` : |
Returns : |

### cong_element_description_free ()

    void        cong_element_description_free   (CongElementDescription *element_desc);

TODO: Write me

`element_desc` : |

### cong_element_description_make_node ()

    CongNodePtr cong_element_description_make_node
                                                (const CongElementDescription *element_desc,
                                                 CongDocument *doc,
                                                 CongNodePtr ns_search_node);

TODO: Write me

`element_desc` : |
`doc` : |
`ns_search_node` : |
Returns : |

### cong_element_description_get_dispspec_element_for_doc ()

    CongDispspecElement* cong_element_description_get_dispspec_element_for_doc
                                                (const CongElementDescription *element_desc,
                                                 CongDocument *doc);

TODO: Write me

`element_desc` : |
`doc` : |
Returns : |

### cong_element_description_get_dispspec_element_for_dispspec ()

    CongDispspecElement* cong_element_description_get_dispspec_element_for_dispspec
                                                (const CongElementDescription *element_desc,
                                                 CongDispspec *ds);

TODO: Write me

`element_desc` : |
`ds` : |
Returns : |

### cong_element_description_get_qualified_name ()

    gchar*      cong_element_description_get_qualified_name
                                                (const CongElementDescription *element_desc,
                                                 CongDispspec *ds);

`element_desc` : |
`ds` : |
Returns : |

### cong_element_description_list_free ()

    void        cong_element_description_list_free
                                                (GList *list_of_element_desc);

TODO: Write me

`list_of_element_desc` : |

### cong_util_modal_element_selection_dialog ()

    CongElementDescription* cong_util_modal_element_selection_dialog
                                                (const gchar *title,
                                                 const gchar *description,
                                                 CongDocument *doc,
                                                 GList *elements);

Runs a modal element selection dialog.

`title` : | Title for the dialog
`description` : | Descriptive text for the dialog
`doc` : | The document, so that dispspecs can be searched for descriptions
`elements` : | A GList of CongElementDescription
Returns : | the selected element (which the caller must free), or NULL if the dialog was cancelled

### cong_util_make_menu_item ()

    GtkMenuItem* cong_util_make_menu_item       (const gchar *label,
                                                 const gchar *tip,
                                                 GdkPixbuf *pixbuf);

TODO: Write me

`label` : |
`tip` : |
`pixbuf` : |
Returns : |

### cong_util_make_stock_menu_item ()

    GtkMenuItem* cong_util_make_stock_menu_item (const gchar *stock_id);

TODO: Write me

`stock_id` : |
Returns : |

### cong_util_add_menu_separator ()

    void        cong_util_add_menu_separator    (CongPrimaryWindow *primary_window,
                                                 const gchar *parent_ui_path);

Adds a separator to a menu.

`primary_window` : |
`parent_ui_path` : |

### cong_util_get_qualified_attribute_name ()

    char*       cong_util_get_qualified_attribute_name
                                                (const xmlNs *namespace,
                                                 const gchar *local_attribute_name);

`namespace` : | Namespace of attribute (can be NULL).
`local_attribute_name` : | Local name of attribute.
Returns : |

### cong_util_show_in_window ()

    void        cong_util_show_in_window        (GtkWidget *content,
                                                 const gchar *title);

Embed the chosen GtkWidget in an appropriate frame, with the application icon etc. Anything using this probably needs some HIG love.

`content` : |
`title` : |

### cong_util_make_file_filter ()

    GtkFileFilter* cong_util_make_file_filter   (const gchar *name,
                                                 const gchar *mime_type);

`name` : |
`mime_type` : |
Returns : |