From 14c4da8cdd8b76b765370048fb45fa741b899dad Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 5 Nov 2000 18:38:08 +0000 Subject: [PATCH] rename G_MARKUP_FOO to G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG 2000-11-05 Havoc Pennington * 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 * glib/tmpl/markup.sgml: Write docs --- ChangeLog | 7 +++ ChangeLog.pre-2-0 | 7 +++ ChangeLog.pre-2-10 | 7 +++ ChangeLog.pre-2-12 | 7 +++ ChangeLog.pre-2-2 | 7 +++ ChangeLog.pre-2-4 | 7 +++ ChangeLog.pre-2-6 | 7 +++ ChangeLog.pre-2-8 | 7 +++ docs/reference/ChangeLog | 4 ++ docs/reference/glib/tmpl/markup.sgml | 111 ++++++++++++++++++++++++++++++----- glib/gmarkup.c | 2 +- glib/gmarkup.h | 2 +- gmarkup.c | 2 +- gmarkup.h | 2 +- 14 files changed, 161 insertions(+), 18 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4199a7d..dec95db 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,5 +1,12 @@ 2000-11-05 Havoc Pennington + * 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 + * 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 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,9 @@ 2000-11-05 Havoc Pennington + * glib/tmpl/markup.sgml: Write docs + +2000-11-05 Havoc Pennington + * 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 --- a/docs/reference/glib/tmpl/markup.sgml +++ b/docs/reference/glib/tmpl/markup.sgml @@ -3,10 +3,83 @@ Simple XML Subset Parser +Parses a subset of XML +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. + + + +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 <[[ has special meaning in XML and not +in GMarkup. However, invalid XML documents are not considered valid +GMarkup documents. + + + +Simplifications to XML include: + + + +Only UTF-8 encoding is allowed. + + + + +No CDATA, no user-defined entities. + + + + +Processing instructions and comments are "passed through" but are not +interpreted in any way. + + + + +No DTD or validation. + + + + + + + + + +The markup format does support: + + + +Elements + + + + +Attributes + + + + +5 standard entities: &amp; &lt; &gt; &quot; &apos; + + + + +Character references + + + @@ -19,12 +92,12 @@ Simple XML Subset Parser -@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 @@ -35,10 +108,10 @@ Simple XML Subset Parser - +There are no flags right now -@G_MARKUP_FOO: +@G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: @@ -48,14 +121,24 @@ Simple XML Subset Parser - +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. -@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 diff --git a/glib/gmarkup.c b/glib/gmarkup.c index e44bc59..e955f7c 100644 --- 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 --- 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 --- 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 --- 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; -- 2.7.4