rename G_MARKUP_FOO to G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG

2000-11-05  Havoc Pennington  <hp@pobox.com>

* gmarkup.h: rename G_MARKUP_FOO to
G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG

* gmarkup.c: don't start doc comments with "Returns"

2000-11-05  Havoc Pennington  <hp@pobox.com>

* glib/tmpl/markup.sgml: Write docs

diff --git a/ChangeLog b/ChangeLog
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-0
+++ b/ChangeLog.pre-2-0
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-2
+++ b/ChangeLog.pre-2-2
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 4199a7d..dec95db 100644 (file)
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,5 +1,12 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * gmarkup.h: rename G_MARKUP_FOO to
+       G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG
+
+       * gmarkup.c: don't start doc comments with "Returns"
+       
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * gmarkup.c: inline docs
        (unescape_text): properly check strtoul for failure.
        

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index cf3c50c..a31059f 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,9 @@
 2000-11-05  Havoc Pennington  <hp@pobox.com>
 
+       * glib/tmpl/markup.sgml: Write docs
+
+2000-11-05  Havoc Pennington  <hp@pobox.com>
+
        * glib/glib-sections.txt: remove parens from section name,
        confuses gtk-doc
 

diff --git a/docs/reference/glib/tmpl/markup.sgml b/docs/reference/glib/tmpl/markup.sgml
index 8079a4c..69680e3 100644 (file)
--- a/docs/reference/glib/tmpl/markup.sgml
+++ b/docs/reference/glib/tmpl/markup.sgml
@@ -3,10 +3,83 @@ Simple XML Subset Parser
 
 <!-- ##### SECTION Short_Description ##### -->
 
+Parses a subset of XML
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+The "GMarkup" parser is intended to parse a simple markup format
+that's a subset of XML format. This is a small, efficient, easy-to-use
+parser. It should not be used if you expect to interoperate with other 
+applications generating full-scale XML. However, it's very useful for
+application data files, config files, etc. where you know your
+application will be the only one writing the file. Full-scale XML
+parsers should be able to parse the subset used by GMarkup, so you can
+easily migrate to full-scale XML at a later time if the need arises.
+</para>
+
+<para>
+GMarkup is not guaranteed to signal an error on all invalid XML; the
+parser may accept documents that an XML parser would not, e.g. the
+sequence <literal>&lt;[[</literal> has special meaning in XML and not
+in GMarkup. However, invalid XML documents are not considered valid
+GMarkup documents. 
+</para>
+
+<para>
+Simplifications to XML include:
+<itemizedlist>
+<listitem>
+<para>
+Only UTF-8 encoding is allowed.
+</para>
+</listitem>
+<listitem>
+<para>
+No CDATA, no user-defined entities.
+</para>
+</listitem>
+<listitem>
+<para>
+Processing instructions and comments are "passed through" but are not 
+interpreted in any way.
+</para>
+</listitem>
+<listitem>
+<para>
+No DTD or validation.
+</para>
+</listitem>
+<listitem>
+<para>
+</para>
+</listitem>
+</itemizedlist>
+</para>
 
+<para>
+The markup format does support:
+<itemizedlist>
+<listitem>
+<para>
+Elements
+</para>
+</listitem>
+<listitem>
+<para>
+Attributes
+</para>
+</listitem>
+<listitem>
+<para>
+5 standard entities: <literal>&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;</literal>
+</para>
+</listitem>
+<listitem>
+<para>
+Character references
+</para>
+</listitem>
+</itemizedlist>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -19,12 +92,12 @@ Simple XML Subset Parser
 
 </para>
 
-@G_MARKUP_ERROR_BAD_UTF8: 
-@G_MARKUP_ERROR_EMPTY: 
-@G_MARKUP_ERROR_PARSE: 
-@G_MARKUP_ERROR_UNKNOWN_ELEMENT: 
-@G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: 
-@G_MARKUP_ERROR_INVALID_CONTENT: 
+@G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
+@G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
+@G_MARKUP_ERROR_PARSE: document was ill-formed
+@G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
+@G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
+@G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; something was wrong with contents of the document, e.g. invalid attribute value
 
 <!-- ##### MACRO G_MARKUP_ERROR ##### -->
 <para>
@@ -35,10 +108,10 @@ Simple XML Subset Parser
 
 <!-- ##### ENUM GMarkupParseFlags ##### -->
 <para>
-
+There are no flags right now
 </para>
 
-@G_MARKUP_FOO: 
+@G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: 
 
 <!-- ##### STRUCT GMarkupParseContext ##### -->
 <para>
@@ -48,14 +121,24 @@ Simple XML Subset Parser
 
 <!-- ##### STRUCT GMarkupParser ##### -->
 <para>
-
+Any of the fields in #GMarkupParser can be %NULL, in which case they
+will be ignored. Except for the @error function, any of these
+callbacks can set an error; in particular the
+%G_MARKUP_ERROR_UNKNOWN_ELEMENT, %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE,
+and %G_MARKUP_ERROR_INVALID_CONTENT errors are intended to be set 
+from these callbacks. If you set an error from a callback,
+g_markup_parse_context_parse() will report that error back to its caller.
 </para>
 
-@start_element: 
-@end_element: 
-@text: 
-@passthrough: 
-@error: 
+@start_element: Callback to invoke when the opening tag of an element
+is seen.
+@end_element: Callback to invoke when the closing tag of an element is seen
+@text: Callback to invoke when some text is seen (text is always
+inside an element)
+@passthrough: Callback to invoke for comments and processing
+instructions; if you're re-writing the parsed document, write the
+passthrough text back out in the same position
+@error: Callback to invoke when an error occurs
 
 <!-- ##### FUNCTION g_markup_escape_text ##### -->
 <para>

diff --git a/glib/gmarkup.c b/glib/gmarkup.c
index e44bc59..e955f7c 100644 (file)
--- a/glib/gmarkup.c
+++ b/glib/gmarkup.c
@@ -1702,7 +1702,7 @@ g_markup_parse_context_end_parse (GMarkupParseContext *context,
  * @line_number: return location for a line number, or %NULL
  * @char_number: return location for a char-on-line number, or %NULL
  *
- * Returns the current line number and the number of the character on
+ * Retrieves the current line number and the number of the character on
  * that line. Intended for use in error messages; there are no strict
  * semantics for what constitutes the "current" line number other than
  * "the best number we could come up with for error messages."

diff --git a/glib/gmarkup.h b/glib/gmarkup.h
index 487678d..57a7c1e 100644 (file)
--- a/glib/gmarkup.h
+++ b/glib/gmarkup.h
@@ -48,7 +48,7 @@ GQuark g_markup_error_quark ();
 typedef enum
 {
   /* Hmm, can't think of any at the moment */
-  G_MARKUP_FOO = 1 << 0
+  G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0
   
 } GMarkupParseFlags;
 

diff --git a/gmarkup.c b/gmarkup.c
index e44bc59..e955f7c 100644 (file)
--- a/gmarkup.c
+++ b/gmarkup.c
@@ -1702,7 +1702,7 @@ g_markup_parse_context_end_parse (GMarkupParseContext *context,
  * @line_number: return location for a line number, or %NULL
  * @char_number: return location for a char-on-line number, or %NULL
  *
- * Returns the current line number and the number of the character on
+ * Retrieves the current line number and the number of the character on
  * that line. Intended for use in error messages; there are no strict
  * semantics for what constitutes the "current" line number other than
  * "the best number we could come up with for error messages."

diff --git a/gmarkup.h b/gmarkup.h
index 487678d..57a7c1e 100644 (file)
--- a/gmarkup.h
+++ b/gmarkup.h
@@ -48,7 +48,7 @@ GQuark g_markup_error_quark ();
 typedef enum
 {
   /* Hmm, can't think of any at the moment */
-  G_MARKUP_FOO = 1 << 0
+  G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0
   
 } GMarkupParseFlags;