New macros to check for XML catalog contents and path, borrowed from

2003-06-17  Matthias Clasen  <maclas@gmx.de>

	* acinclude.m4 (JH_PATH_XML_CATALOG, JH_CHECK_XML_CATALOG): New
	macros to check for XML catalog contents and path, borrowed from
	gtk-doc.
	* configure.in: New option --enable-man to enable regeneration of
	man pages from Docbook, if the necessary tools are found.

	* gobject/Makefile.am: Add rule to regenerate man pages from
	Docbook.
	(man_MANS): Add glib-mkenums.1, glib-genmarshal.1 and gobject-query.1.
	(content_files): Add glib-mkenums.xml, glib-genmarshal.xml and
	gobject-query.xml.

	* gobject/glib-mkenums.xml:
	* gobject/glib-genmarshal.xml:
	* gobject/gobject-query.xml: New refentries.

	* gobject/glib-mkenums.1:
	* gobject/glib-genmarshal.1:
	* gobject/gobject-query.1: Man pages generated from the .xml
	sources.

	* gobject/gobject-docs.sgml: Include glib-mkenums.xml,
	glib-genmarshal.xml and gobject-query.xml.

	* glib/Makefile.am: Add rule to regenerate man pages from
	Docbook.
	(man_MANS): Add glib-gettextize.1.
	(content_files): Add glib-gettextize.xml.

	* glib/glib-gettextize.xml: New refentry.

	* glib/glib-gettextize.1: Man page generated from the .xml source.

	* glib/glib-docs.sgml: Include glib-gettextize.xml.

1 files changed, 271 insertions, 0 deletions

diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml
new file mode 100644
index 000000000..b8e4032fa
--- /dev/null
+++ b/docs/reference/gobject/glib-mkenums.xml
@@ -0,0 +1,271 @@
+<refentry id="glib-mkenums">
+
+<refmeta>
+<refentrytitle>glib-mkenums</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname>glib-mkenums</refname>
+<refpurpose>C language enum description generation utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>glib-mkenums</command>
+<arg choice="opt" rep="repeat">options</arg>
+<arg choice="opt" rep="repeat">files</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para>
+<command>glib-mkenums</command> is a small perl-script utility that parses C
+code to extract enum definitions and produces enum descriptions based on text
+templates specified by the user. Most frequently this script is used to 
+produce C code that contains enum values as strings so programs can provide 
+value name strings for introspection.
+</para>
+</refsect1>
+
+<refsect1><title>Invokation</title>
+<para>
+<command>glib-mkenums</command> takes a list of valid C code files as
+input. The options specified control the text that is output, certain 
+substitutions are performed on the text templates for keywords enclosed 
+in @ characters.
+</para>
+
+<refsect2><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>--fhead</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> prior to processing input files.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--fprod</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> everytime a new input file 
+is being processed.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--ftail</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> after all input files have been 
+processed.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--eprod</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> everytime an enum is encountered 
+in the input files.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--vhead</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> before iterating over the set of 
+values of an enum.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--vprod</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> for every value of an enum.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--vtail</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Put out <replaceable>text</replaceable> after iterating over all values 
+of an enum.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--comments</option> <replaceable>text</replaceable></term>
+<listitem><para>
+Template for auto-generated comments, the default (for C code generations) is
+<literal>"/* @comment@ */"</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--template</option> <replaceable>file</replaceable></term>
+<listitem><para>
+Read templates from the given file. The templates are enclosed in
+specially-formatted C comments
+<programlisting>
+/*** BEGIN section ***/
+/*** END section ***/
+</programlisting>
+where section may be <literal>file-header</literal>, 
+<literal>file-production</literal>, <literal>file-tail</literal>,
+<literal>enumeration-production</literal>, <literal>value-header</literal>, 
+<literal>value-production</literal>, <literal>value-tail</literal> or
+<literal>comment</literal>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--help</option></term>
+<listitem><para>
+Print brief help and exit.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--version</option></term>
+<listitem><para>
+Print version and exit.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+
+<refsect2><title>Production text substitutions</title>
+<para>
+Certain keywords enclosed in @ characters will be substituted in the 
+emitted text. For the substitution examples of the keywords below, 
+the following example enum definition is assumed:
+<programlisting>
+typedef enum
+{
+  PREFIX_THE_XVALUE    = 1 &lt;&lt; 3,
+  PREFIX_ANOTHER_VALUE = 1 &lt;&lt; 4
+} PrefixTheXEnum;
+</programlisting>
+<variablelist>
+<varlistentry>
+<term>@EnumName@</term>
+<listitem><para>
+The name of the enum currently being processed, enum names are assumed to be
+properly namespaced and to use mixed capitalization to separate
+words (e.g. PrefixTheXEnum).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@enum_name@</term>
+<listitem><para>
+The enum name with words lowercase and word-separated by underscores 
+(e.g. prefix_the_xenum).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@ENUMNAME@</term>
+<listitem><para>
+The enum name with words uppercase and word-separated by underscores 
+(e.g. PREFIX_THE_XENUM).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@ENUMSHORT@</term>
+<listitem><para>
+The enum name with words uppercase and word-separated by underscores, 
+prefix stripped (e.g. THE_XENUM).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@VALUENAME@</term>
+<listitem><para>
+The enum value name currently being processed with words uppercase and 
+word-separated by underscores,
+this is the assumed literal notation of enum values in the C sources 
+(e.g. PREFIX_THE_XVALUE).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@valuenick@</term>
+<listitem><para>
+A nick name for the enum value currently being processed, this is usually 
+generated by stripping common prefix words of all the enum values of the 
+current enum, the words are lowercase and underscores are substituted by a 
+minus (e.g. the-xvalue).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@type@</term>
+<listitem><para>
+This is substituted either by "enum" or "flags", depending on whether the 
+enum value definitions contained bit-shift operators or not (e.g. flags).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@Type@</term>
+<listitem><para>
+The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@TYPE@</term>
+<listitem><para>
+The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS).
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>@filename@</term>
+<listitem><para>
+The name of the input file currently being processed (e.g. foo.h).
+</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</refsect2>
+<refsect2><title>Trigraph extensions</title>
+<para>
+Some C comments are treated specially in the parsed enum definitions, 
+such comments start out with the trigraph sequence <literal>/*&lt;</literal> 
+and end with the trigraph sequence <literal>&gt;*/</literal>.
+Per enum definition, the options "skip" and "flags" can be specified, to 
+indicate this enum definition to be skipped, or for it to be treated as 
+a flags definition, or to specify the common prefix to be stripped from 
+all values to generate value nicknames, respectively.
+Per value definition, the options "skip" and "nick" are supported. 
+The former causes the value to be skipped, and the latter can be used to 
+specify the otherwise auto-generated nickname.
+Examples:
+<programlisting>
+typedef enum /*&lt; skip &gt;*/
+{
+  PREFIX_FOO
+} PrefixThisEnumWillBeSkipped;
+typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
+{
+  PREFIX_THE_ZEROTH_VALUE,	/*&lt; skip &gt;*/
+  PREFIX_THE_FIRST_VALUE,
+  PREFIX_THE_SECOND_VALUE,
+  PREFIX_THE_THIRD_VALUE,	/*&lt; nick=the-last-value &gt;*/
+} PrefixTheFlagsEnum;
+</programlisting>
+</para>
+</refsect2>
+</refsect1>
+<refsect1><title>See also</title>
+<para>
+<command>glib-genmarshal</command>(1)
+</para>
+</refsect1>
+</refentry>
+
+