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
2025-02-20 01:02:10 +01:00 · 2000-11-05 18:38:08 +00:00 · 2000-11-05 18:38:08 +00:00 · 14c4da8cdd
commit 14c4da8cdd
parent 194ae56882
14 changed files with 161 additions and 18 deletions
--- a/7
+++ b/7
@ -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
--- a/ChangeLog.pre-2-0
+++ b/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
--- a/ChangeLog.pre-2-10
+++ b/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
--- a/ChangeLog.pre-2-12
+++ b/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
--- a/ChangeLog.pre-2-2
+++ b/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
--- a/ChangeLog.pre-2-4
+++ b/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
--- a/ChangeLog.pre-2-6
+++ b/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
--- a/ChangeLog.pre-2-8
+++ b/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
--- a/docs/reference/ChangeLog
+++ b/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,
--- 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>
--- 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."
--- 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;

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