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

ChangeLog

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-0

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-10

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-12

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-2

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-4

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-6

@@ -1,3 +1,10 @@
+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

ChangeLog.pre-2-8

@@ -1,3 +1,10 @@
+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

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+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,

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_BAD_UTF8: text being parsed was not valid UTF-8
-@G_MARKUP_ERROR_EMPTY: 
+@G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
-@G_MARKUP_ERROR_PARSE: 
+@G_MARKUP_ERROR_PARSE: document was ill-formed
-@G_MARKUP_ERROR_UNKNOWN_ELEMENT: 
+@G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
-@G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: 
+@G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
-@G_MARKUP_ERROR_INVALID_CONTENT: 
+@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: 
+@start_element: Callback to invoke when the opening tag of an element
-@end_element: 
+is seen.
-@text: 
+@end_element: Callback to invoke when the closing tag of an element is seen
-@passthrough: 
+@text: Callback to invoke when some text is seen (text is always
-@error: 
+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>

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."

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;
 

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."

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;