markup.sgml   [plain text]

<!-- ##### SECTION Title ##### -->
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. 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. 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 user-defined entities.
</para>
</listitem>
<listitem>
<para>
Processing instructions, comments and the doctype declaration are "passed through" but are not 
interpreted in any way.
</para>
</listitem>
<listitem>
<para>
No DTD or validation.
</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>
<listitem>
<para>
Sections marked as CDATA
</para>
</listitem>
</itemizedlist>
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### ENUM GMarkupError ##### -->
<para>
Error codes returned by markup parsing.
</para>

@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>
Error domain for markup parsing. Errors in this domain will
be from the #GMarkupError enumeration. See #GError for information on 
error domains.
</para>



<!-- ##### ENUM GMarkupParseFlags ##### -->
<para>
There are no flags right now. Pass "0" for the flags argument to all 
functions.
</para>

@G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use.

<!-- ##### STRUCT GMarkupParseContext ##### -->
<para>
A parse context is used to parse a stream of bytes that you expect to
contain marked-up text. See g_markup_parse_context_new(),
#GMarkupParser, and so on for more details.
</para>


<!-- ##### 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: 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, processing
instructions and doctype declarations; 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>

</para>

@text: 
@length: 
@Returns: 


<!-- ##### FUNCTION g_markup_printf_escaped ##### -->
<para>

</para>

@format: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_markup_vprintf_escaped ##### -->
<para>

</para>

@format: 
@args: 
@Returns: 


<!-- ##### FUNCTION g_markup_parse_context_end_parse ##### -->
<para>

</para>

@context: 
@error: 
@Returns: 


<!-- ##### FUNCTION g_markup_parse_context_free ##### -->
<para>

</para>

@context: 


<!-- ##### FUNCTION g_markup_parse_context_get_position ##### -->
<para>

</para>

@context: 
@line_number: 
@char_number: 


<!-- ##### FUNCTION g_markup_parse_context_get_element ##### -->
<para>

</para>

@context: 
@Returns: 


<!-- ##### FUNCTION g_markup_parse_context_new ##### -->
<para>

</para>

@parser: 
@flags: 
@user_data: 
@user_data_dnotify: 
@Returns: 


<!-- ##### FUNCTION g_markup_parse_context_parse ##### -->
<para>

</para>

@context: 
@text: 
@text_len: 
@error: 
@Returns: