From 54f796b1b6e161e92b975e25f06c3a5b7121179d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 17 Jun 2003 23:08:37 +0000 Subject: [PATCH] New macros to check for XML catalog contents and path, borrowed from 2003-06-17 Matthias Clasen * 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. --- ChangeLog | 18 ++ ChangeLog.pre-2-10 | 18 ++ ChangeLog.pre-2-12 | 18 ++ ChangeLog.pre-2-4 | 18 ++ ChangeLog.pre-2-6 | 18 ++ ChangeLog.pre-2-8 | 18 ++ acinclude.m4 | 46 +++ configure.in | 20 ++ docs/reference/ChangeLog | 33 ++ docs/reference/glib/Makefile.am | 12 +- docs/reference/glib/glib-docs.sgml | 10 +- docs/reference/glib/glib-gettextize.1 | 59 ++++ docs/reference/glib/glib-gettextize.xml | 78 +++++ docs/reference/gobject/Makefile.am | 19 +- docs/reference/gobject/glib-genmarshal.1 | 253 ++++++++++++++++ docs/reference/gobject/glib-genmarshal.xml | 336 +++++++++++++++++++++ docs/reference/gobject/glib-mkenums.1 | 168 +++++++++++ docs/reference/gobject/glib-mkenums.xml | 271 +++++++++++++++++ docs/reference/gobject/gobject-docs.sgml | 11 + docs/reference/gobject/gobject-query.1 | 80 +++++ docs/reference/gobject/gobject-query.xml | 111 +++++++ gobject/Makefile.am | 5 - 22 files changed, 1612 insertions(+), 8 deletions(-) create mode 100644 docs/reference/glib/glib-gettextize.1 create mode 100644 docs/reference/glib/glib-gettextize.xml create mode 100644 docs/reference/gobject/glib-genmarshal.1 create mode 100644 docs/reference/gobject/glib-genmarshal.xml create mode 100644 docs/reference/gobject/glib-mkenums.1 create mode 100644 docs/reference/gobject/glib-mkenums.xml create mode 100644 docs/reference/gobject/gobject-query.1 create mode 100644 docs/reference/gobject/gobject-query.xml diff --git a/ChangeLog b/ChangeLog index cbac35d14..3d1456b11 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,21 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-15 Tor Lillqvist * glib-zip.in (DLLDIR): Test where the DLLs actually are. diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index cbac35d14..3d1456b11 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,21 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-15 Tor Lillqvist * glib-zip.in (DLLDIR): Test where the DLLs actually are. diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index cbac35d14..3d1456b11 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,21 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-15 Tor Lillqvist * glib-zip.in (DLLDIR): Test where the DLLs actually are. diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index cbac35d14..3d1456b11 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,21 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-15 Tor Lillqvist * glib-zip.in (DLLDIR): Test where the DLLs actually are. diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index cbac35d14..3d1456b11 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,21 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-15 Tor Lillqvist * glib-zip.in (DLLDIR): Test where the DLLs actually are. diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index cbac35d14..3d1456b11 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,21 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-15 Tor Lillqvist * glib-zip.in (DLLDIR): Test where the DLLs actually are. diff --git a/acinclude.m4 b/acinclude.m4 index efb43d218..1e7207690 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -73,6 +73,52 @@ if test $ac_cv_func_printf_unix98 = yes; then fi ])# AC_FUNC_PRINTF_UNIX98 +# Checks the location of the XML Catalog +# Usage: +# JH_PATH_XML_CATALOG +# Defines XMLCATALOG and XML_CATALOG_FILE substitutions +AC_DEFUN([JH_PATH_XML_CATALOG], +[ + # check for the presence of the XML catalog + AC_ARG_WITH([xml-catalog], + AC_HELP_STRING([--with-xml-catalog=CATALOG], + [path to xml catalog to use]),, + [with_xml_catalog=/etc/xml/catalog]) + XML_CATALOG_FILE="$with_xml_catalog" + AC_MSG_CHECKING([for XML catalog ($XML_CATALOG_FILE)]) + if test -f "$XML_CATALOG_FILE"; then + AC_MSG_RESULT([found]) + else + AC_MSG_RESULT([not found]) + AC_MSG_ERROR([XML catalog not found]) + fi + AC_SUBST([XML_CATALOG_FILE]) + + # check for the xmlcatalog program + AC_PATH_PROG(XMLCATALOG, xmlcatalog, no) + if test "x$XMLCATALOG" = xno; then + AC_MSG_ERROR([could not find xmlcatalog program]) + fi +]) + +# Checks if a particular URI appears in the XML catalog +# Usage: +# JH_CHECK_XML_CATALOG(URI, [FRIENDLY-NAME], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) +AC_DEFUN([JH_CHECK_XML_CATALOG], +[ + AC_REQUIRE([JH_PATH_XML_CATALOG])dnl + AC_MSG_CHECKING([for ifelse([$2],,[$1],[$2]) in XML catalog]) + if AC_RUN_LOG([$XMLCATALOG --noout "$XML_CATALOG_FILE" "$1" >&2]); then + AC_MSG_RESULT([found]) + ifelse([$3],,,[$3 +])dnl + else + AC_MSG_RESULT([not found]) + ifelse([$4],, + [AC_MSG_ERROR([could not find ifelse([$2],,[$1],[$2]) in XML catalog])], + [$4]) + fi +]) diff --git a/configure.in b/configure.in index 34cf21663..30d64a7af 100644 --- a/configure.in +++ b/configure.in @@ -1896,6 +1896,26 @@ dnl ************************** GTK_DOC_CHECK([1.0]) +AC_ARG_ENABLE(man, + [AC_HELP_STRING([--enable-man], + [regenerate man pages from Docbook [default=no]])],enable_man=yes, + enable_man=no) + +dnl +dnl Check for xsltproc +dnl +AC_PATH_PROG([XSLTPROC], [xsltproc]) +if test -z "$XSLTPROC"; then + enable_man=no +fi + +dnl check for DocBook DTD and stylesheets in the local catalog. +JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.1.2//EN], + [DocBook XML DTD V4.1.2],,enable_man=no) +JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl], + [DocBook XSL Stylesheets],,enable_man=no) +AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) + dnl ****************************** dnl *** output the whole stuff *** dnl ****************************** diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 8c51866aa..3d2c3b15d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,36 @@ +2003-06-18 Matthias Clasen + + * 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. + +2003-06-17 Matthias Clasen + + * 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. + 2003-06-17 Matthias Clasen * gobject/gobject-docs.sgml: diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am index 5959840e4..4f0244f11 100644 --- a/docs/reference/glib/Makefile.am +++ b/docs/reference/glib/Makefile.am @@ -48,11 +48,21 @@ content_files = \ changes.sgml \ compiling.sgml \ resources.sgml \ - version.xml + version.xml \ + glib-gettextize.xml # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS= +man_MANS = glib-gettextize.1 + +if ENABLE_MAN + +%.1 : %.xml + @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +endif + # include common portion ... include $(top_srcdir)/gtk-doc.make diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml index 4451349f0..2be3fa5ca 100644 --- a/docs/reference/glib/glib-docs.sgml +++ b/docs/reference/glib/glib-docs.sgml @@ -61,6 +61,8 @@ + + ]> @@ -155,7 +157,13 @@ OS/2 and BeOS. GLib is released under the GNU Library General Public License &glib-Caches; &glib-Memory-Allocators; - + + + GLib Tools + + &glib-gettextize; + + diff --git a/docs/reference/glib/glib-gettextize.1 b/docs/reference/glib/glib-gettextize.1 new file mode 100644 index 000000000..693f09ac2 --- /dev/null +++ b/docs/reference/glib/glib-gettextize.1 @@ -0,0 +1,59 @@ +.\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "GLIB-GETTEXTIZE" 1 "" "" "" +.SH NAME +glib-gettextize \- gettext internationalization utility +.SH "SYNOPSIS" + +.nf +\fBglib-gettextize\fR [option...] [directory] +.fi + +.SH "DESCRIPTION" + +.PP + \fBglib-gettextize\fR helps to prepare a source package for being internationalized through gettext\&. It is a variant of the \fBgettextize\fR that ships with gettext\&. + +.PP + \fBglib-gettextize\fR differs from \fBgettextize\fR in that it doesn't create an \fIintl/\fR subdirectory and doesn't modify \fIpo/ChangeLog\fR (note that newer versions of \fBgettextize\fR behave like this when called with the \fB--no-changelog\fR option)\&. + +.SS "Options" + +.TP +\fB--help\fR +print help and exit + +.TP +\fB--version\fR +print version information and exit + +.TP +\fB-c\fR, \fB--copy\fR +copy files instead of making symlinks + +.TP +\fB-f\fR, \fB--force\fR +force writing of new files even if old ones exist + +.SH "SEE ALSO" + +.PP + \fBgettextize\fR(1) + diff --git a/docs/reference/glib/glib-gettextize.xml b/docs/reference/glib/glib-gettextize.xml new file mode 100644 index 000000000..54efe7a9c --- /dev/null +++ b/docs/reference/glib/glib-gettextize.xml @@ -0,0 +1,78 @@ + + + +glib-gettextize +1 + + + +glib-gettextize +gettext internationalization utility + + + + +glib-gettextize +option +directory + + + +Description + +glib-gettextize helps to prepare a source package for being +internationalized through gettext. +It is a variant of the gettextize that ships with +gettext. + + + +glib-gettextize differs +from gettextize in that it doesn't create an +intl/ subdirectory and doesn't modify +po/ChangeLog (note that newer versions of +gettextize behave like this when called with the + option). + +Options + + + + + +print help and exit + + + + + + +print version information and exit + + + + +, + +copy files instead of making symlinks + + + + +, + +force writing of new files even if old ones exist + + + + + + +See also + +gettextize(1) + + + + + diff --git a/docs/reference/gobject/Makefile.am b/docs/reference/gobject/Makefile.am index b756b19e1..6f1d2a0f0 100644 --- a/docs/reference/gobject/Makefile.am +++ b/docs/reference/gobject/Makefile.am @@ -28,12 +28,29 @@ MKDB_OPTIONS= HTML_IMAGES = # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE) -content_files = version.xml +content_files = version.xml \ + glib-mkenums.xml \ + glib-genmarshal.xml \ + gobject-query.xml # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS=--extra-dir=$(srcdir)/../glib/html +man_MANS = glib-mkenums.1 glib-genmarshal.1 gobject-query.1 + +if ENABLE_MAN + +%.1 : %.xml + @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< + +endif + include $(top_srcdir)/gtk-doc.make # Other files to distribute EXTRA_DIST += version.xml.in + + + + + diff --git a/docs/reference/gobject/glib-genmarshal.1 b/docs/reference/gobject/glib-genmarshal.1 new file mode 100644 index 000000000..026161238 --- /dev/null +++ b/docs/reference/gobject/glib-genmarshal.1 @@ -0,0 +1,253 @@ +.\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "GLIB-GENMARSHAL" 1 "" "" "" +.SH NAME +glib-genmarshal \- C code marshaller generation utility for GLib closures +.SH "SYNOPSIS" + +.nf +\fBglib-genmarshal\fR [options...] [files...] +.fi + +.SH "DESCRIPTION" + +.PP + \fBglib-genmarshal\fR is a small utility that generates C code marshallers for callback functions of the GClosure mechanism in the GObject sublibrary of GLib\&. The marshaller functions have a standard signature, they get passed in the invoking closure, an array of value structures holding the callback function parameters and a value structure for the return value of the callback\&. The marshaller is then responsible to call the respective C code function of the closure with all the parameters on the stack and to collect its return value\&. + +.SH "INVOKATION" + +.PP + \fBglib-genmarshal\fR takes a list of marshallers to generate as input\&. The marshaller list is either read from standard input or from files passed as additional arguments on the command line\&. + +.SS "Options" + +.TP +\fB--header\fR +Generate header file contents of the marshallers\&. + +.TP +\fB--body\fR +Generate C code file contents of the marshallers\&. + +.TP +\fB--prefix=string\fR, \fB--prefix string\fR +Specify marshaller prefix\&. The default prefix is `g_cclosure_marshal'\&. + +.TP +\fB--skip-source\fR +Skip source location remarks in generated comments\&. + +.TP +\fB--nostdinc\fR +Do not use the standard marshallers of the GObject library, and skip \fIgmarshal\&.h\fR include directive in generated header files\&. + +.TP +\fB--g-fatal-warnings\fR +Make warnings fatal, that is, exit immediately once a warning occurs\&. + +.TP +\fB-h\fR, \fB--help\fR +Print brief help and exit\&. + +.TP +\fB-v\fR, \fB--version\fR +Print version and exit\&. + +.SS "Marshaller list format" + +.PP +The marshaller lists are processed line by line, a line can contain a comment in the form of + +.nf + +# this is a comment + +.fi + or a marshaller specification of the form + +.nf + +\fIRTYPE\fR:\fIPTYPE\fR +\fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR +\fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR,\fIPTYPE\fR + +.fi + (up to 16 \fIPTYPE\fRs may be present)\&. + +.PP +The \fIRTYPE\fR part specifies the callback's return type and the \fIPTYPE\fRs right to the colon specify the callback's parameter list, except for the first and the last arguments which are always pointers\&. + +.SS "Parameter types" + +.PP +Currently, the following types are supported: + +.TP +\fIVOID\fR +indicates no return type, or no extra parameters\&. If \fIVOID\fR is used as the parameter list, no additional parameters may be present\&. + +.TP +\fIBOOLEAN\fR +for boolean types (gboolean) + +.TP +\fICHAR\fR +for signed char types (gchar) + +.TP +\fIUCHAR\fR +for unsigned char types (guchar) + +.TP +\fIINT\fR +for signed integer types (gint) + +.TP +\fIUINT\fR +for unsigned integer types (guint) + +.TP +\fILONG\fR +for signed long integer types (glong) + +.TP +\fIULONG\fR +for unsigned long integer types (gulong) + +.TP +\fIENUM\fR +for enumeration types (gint) + +.TP +\fIFLAGS\fR +for flag enumeration types (guint) + +.TP +\fIFLOAT\fR +for single-precision float types (gfloat) + +.TP +\fIDOUBLE\fR +for double-precision float types (gdouble) + +.TP +\fISTRING\fR +for string types (gchar*) + +.TP +\fIBOXED\fR +for boxed (anonymous but reference counted) types (GBoxed*) + +.TP +\fIPARAM\fR +for GParamSpec or derived types (GParamSpec*) + +.TP +\fIPOINTER\fR +for anonymous pointer types (gpointer) + +.TP +\fIOBJECT\fR +for GObject or derived types (GObject*) + +.TP +\fINONE\fR +deprecated alias for \fIVOID\fR + +.TP +\fIBOOL\fR +deprecated alias for \fIBOOLEAN\fR + + +.SH "EXAMPLE" + +.PP +To generate marshallers for the following callback functions: + +.nf + +void foo (gpointer data1, + gpointer data2); +void bar (gpointer data1, + gint param1, + gpointer data2); +gfloat baz (gpointer data1, + gboolean param1, + guchar param2, + gpointer data2); + +.fi + +.PP +The marshaller list has to look like this: + +.nf + +VOID:VOID +VOID:INT +FLOAT:BOOLEAN,UCHAR + +.fi + +.PP +The generated marshallers have the arguments encoded in their function name\&. For this particular list, they are + +.nf + +g_cclosure_marshal_VOID__VOID(), +g_cclosure_marshal_VOID__INT(), +g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR()\&. + +.fi + +.PP +They can be used directly for GClosures or be passed in as the GSignalCMarshaller c_marshaller; argument upon creation of signals: + +.nf + +GClosure *cc_foo, *cc_bar, *cc_baz; + +cc_foo = g_cclosure_new (NULL, foo, NULL); +g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID); +cc_bar = g_cclosure_new (NULL, bar, NULL); +g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT); +cc_baz = g_cclosure_new (NULL, baz, NULL); +g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR); + +.fi + +.SH "SEE ALSO" + +.PP + \fBglib-mkenums\fR(1) + +.SH "BUGS" + +.PP +None known yet\&. + +.SH "AUTHOR" + +.PP + \fBglib-genmarshal\fR has been written by Tim Janik \&. + +.PP +This manual page was provided by Tim Janik \&. + diff --git a/docs/reference/gobject/glib-genmarshal.xml b/docs/reference/gobject/glib-genmarshal.xml new file mode 100644 index 000000000..e2f5d49f7 --- /dev/null +++ b/docs/reference/gobject/glib-genmarshal.xml @@ -0,0 +1,336 @@ + + + +glib-genmarshal +1 + + + +glib-genmarshal +C code marshaller generation utility for GLib closures + + + + +glib-genmarshal +options +files + + + +Description + +glib-genmarshal is a small utility that generates C code +marshallers for callback functions of the GClosure mechanism in the GObject +sublibrary of GLib. The marshaller functions have a standard signature, +they get passed in the invoking closure, an array of value structures holding +the callback function parameters and a value structure for the return value +of the callback. The marshaller is then responsible to call the respective C +code function of the closure with all the parameters on the stack and to +collect its return value. + + + +Invokation + +glib-genmarshal takes a list of marshallers to generate as +input. The marshaller list is either read from standard input or from files +passed as additional arguments on the command line. + + +Options + + + + + +Generate header file contents of the marshallers. + + + + + + +Generate C code file contents of the marshallers. + + + + +, + +Specify marshaller prefix. The default prefix is `g_cclosure_marshal'. + + + + + + +Skip source location remarks in generated comments. + + + + + + +Do not use the standard marshallers of the GObject library, and skip +gmarshal.h include directive in generated header files. + + + + + + +Make warnings fatal, that is, exit immediately once a warning occurs. + + + + +, + +Print brief help and exit. + + + + +, + +Print version and exit. + + + + + + +Marshaller list format + +The marshaller lists are processed line by line, a line can contain a +comment in the form of + +# this is a comment + +or a marshaller specification of the form + +RTYPE:PTYPE +RTYPE:PTYPE,PTYPE +RTYPE:PTYPE,PTYPE,PTYPE + +(up to 16 PTYPEs may be present). + + +The RTYPE part specifies the callback's return +type and the PTYPEs right to the colon specify +the callback's parameter list, except for the first and the last arguments +which are always pointers. + + +Parameter types + +Currently, the following types are supported: + + +VOID + +indicates no return type, or no extra parameters. +If VOID is used as the parameter list, no +additional parameters may be present. + + + + +BOOLEAN + +for boolean types (gboolean) + + + + +CHAR + +for signed char types (gchar) + + + + +UCHAR + +for unsigned char types (guchar) + + + + +INT + +for signed integer types (gint) + + + + +UINT + +for unsigned integer types (guint) + + + + +LONG + +for signed long integer types (glong) + + + + +ULONG + +for unsigned long integer types (gulong) + + + + +ENUM + +for enumeration types (gint) + + + + +FLAGS + +for flag enumeration types (guint) + + + + +FLOAT + +for single-precision float types (gfloat) + + + + +DOUBLE + +for double-precision float types (gdouble) + + + + +STRING + +for string types (gchar*) + + + + +BOXED + +for boxed (anonymous but reference counted) types (GBoxed*) + + + + +PARAM + +for GParamSpec or derived types (GParamSpec*) + + + + +POINTER + +for anonymous pointer types (gpointer) + + + + +OBJECT + +for GObject or derived types (GObject*) + + + + +NONE + +deprecated alias for VOID + + + + +BOOL + +deprecated alias for BOOLEAN + + + + + + +Example + +To generate marshallers for the following callback functions: + + +void foo (gpointer data1, + gpointer data2); +void bar (gpointer data1, + gint param1, + gpointer data2); +gfloat baz (gpointer data1, + gboolean param1, + guchar param2, + gpointer data2); + + +The marshaller list has to look like this: + + +VOID:VOID +VOID:INT +FLOAT:BOOLEAN,UCHAR + + +The generated marshallers have the arguments encoded in their function name. +For this particular list, they are + + +g_cclosure_marshal_VOID__VOID(), +g_cclosure_marshal_VOID__INT(), +g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR(). + + +They can be used directly for GClosures or be passed in as the +GSignalCMarshaller c_marshaller; argument upon creation of signals: + + +GClosure *cc_foo, *cc_bar, *cc_baz; + +cc_foo = g_cclosure_new (NULL, foo, NULL); +g_closure_set_marshal (cc_foo, g_cclosure_marshal_VOID__VOID); +cc_bar = g_cclosure_new (NULL, bar, NULL); +g_closure_set_marshal (cc_bar, g_cclosure_marshal_VOID__INT); +cc_baz = g_cclosure_new (NULL, baz, NULL); +g_closure_set_marshal (cc_baz, g_cclosure_marshal_FLOAT__BOOLEAN_UCHAR); + + +See also + +glib-mkenums(1) + + +Bugs + +None known yet. + + +Author + +glib-genmarshal has been written by Tim Janik +timj@gtk.org. + + +This manual page was provided by Tim Janik timj@gtk.org. + + + + + diff --git a/docs/reference/gobject/glib-mkenums.1 b/docs/reference/gobject/glib-mkenums.1 new file mode 100644 index 000000000..bff0a1411 --- /dev/null +++ b/docs/reference/gobject/glib-mkenums.1 @@ -0,0 +1,168 @@ +.\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "GLIB-MKENUMS" 1 "" "" "" +.SH NAME +glib-mkenums \- C language enum description generation utility +.SH "SYNOPSIS" + +.nf +\fBglib-mkenums\fR [options...] [files...] +.fi + +.SH "DESCRIPTION" + +.PP + \fBglib-mkenums\fR 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\&. + +.SH "INVOKATION" + +.PP + \fBglib-mkenums\fR 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\&. + +.SS "Options" + +.TP +\fB--fhead\fR \fItext\fR +Put out \fItext\fR prior to processing input files\&. + +.TP +\fB--fprod\fR \fItext\fR +Put out \fItext\fR everytime a new input file is being processed\&. + +.TP +\fB--ftail\fR \fItext\fR +Put out \fItext\fR after all input files have been processed\&. + +.TP +\fB--eprod\fR \fItext\fR +Put out \fItext\fR everytime an enum is encountered in the input files\&. + +.TP +\fB--vhead\fR \fItext\fR +Put out \fItext\fR before iterating over the set of values of an enum\&. + +.TP +\fB--vprod\fR \fItext\fR +Put out \fItext\fR for every value of an enum\&. + +.TP +\fB--vtail\fR \fItext\fR +Put out \fItext\fR after iterating over all values of an enum\&. + +.TP +\fB--comments\fR \fItext\fR +Template for auto-generated comments, the default (for C code generations) is "/* @comment@ */"\&. + +.TP +\fB--template\fR \fIfile\fR +Read templates from the given file\&. The templates are enclosed in specially-formatted C comments .nf /*** BEGIN section ***/ /*** END section ***/ .fi where section may be file-header, file-production, file-tail, enumeration-production, value-header, value-production, value-tail or comment\&. + +.TP +\fB--help\fR +Print brief help and exit\&. + +.TP +\fB--version\fR +Print version and exit\&. + +.SS "Production text substitutions" + +.PP +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: + +.nf + +typedef enum +{ + PREFIX_THE_XVALUE = 1 << 3, + PREFIX_ANOTHER_VALUE = 1 << 4 +} PrefixTheXEnum; + +.fi + + +.TP +@EnumName@ +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)\&. + +.TP +@enum_name@ +The enum name with words lowercase and word-separated by underscores (e\&.g\&. prefix_the_xenum)\&. + +.TP +@ENUMNAME@ +The enum name with words uppercase and word-separated by underscores (e\&.g\&. PREFIX_THE_XENUM)\&. + +.TP +@ENUMSHORT@ +The enum name with words uppercase and word-separated by underscores, prefix stripped (e\&.g\&. THE_XENUM)\&. + +.TP +@VALUENAME@ +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)\&. + +.TP +@valuenick@ +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)\&. + +.TP +@type@ +This is substituted either by "enum" or "flags", depending on whether the enum value definitions contained bit-shift operators or not (e\&.g\&. flags)\&. + +.TP +@Type@ +The same as @type@ with the first letter capitalized (e\&.g\&. Flags)\&. + +.TP +@TYPE@ +The same as @type@ with all letters uppercased (e\&.g\&. FLAGS)\&. + +.TP +@filename@ +The name of the input file currently being processed (e\&.g\&. foo\&.h)\&. + + +.SS "Trigraph extensions" + +.PP +Some C comments are treated specially in the parsed enum definitions, such comments start out with the trigraph sequence /*< and end with the trigraph sequence >*/\&. 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: + +.nf + +typedef enum /*< skip >*/ +{ + PREFIX_FOO +} PrefixThisEnumWillBeSkipped; +typedef enum /*< flags,prefix=PREFIX >*/ +{ + PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ + PREFIX_THE_FIRST_VALUE, + PREFIX_THE_SECOND_VALUE, + PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/ +} PrefixTheFlagsEnum; + +.fi + + +.SH "SEE ALSO" + +.PP + \fBglib-genmarshal\fR(1) + 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 @@ + + + +glib-mkenums +1 + + + +glib-mkenums +C language enum description generation utility + + + + +glib-mkenums +options +files + + + +Description + +glib-mkenums 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. + + + +Invokation + +glib-mkenums 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. + + +Options + + + + text + +Put out text prior to processing input files. + + + + + text + +Put out text everytime a new input file +is being processed. + + + + + text + +Put out text after all input files have been +processed. + + + + + text + +Put out text everytime an enum is encountered +in the input files. + + + + + text + +Put out text before iterating over the set of +values of an enum. + + + + + text + +Put out text for every value of an enum. + + + + + text + +Put out text after iterating over all values +of an enum. + + + + + text + +Template for auto-generated comments, the default (for C code generations) is +"/* @comment@ */". + + + + + file + +Read templates from the given file. The templates are enclosed in +specially-formatted C comments + +/*** BEGIN section ***/ +/*** END section ***/ + +where section may be file-header, +file-production, file-tail, +enumeration-production, value-header, +value-production, value-tail or +comment. + + + + + + +Print brief help and exit. + + + + + + +Print version and exit. + + + + + + +Production text substitutions + +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: + +typedef enum +{ + PREFIX_THE_XVALUE = 1 << 3, + PREFIX_ANOTHER_VALUE = 1 << 4 +} PrefixTheXEnum; + + + +@EnumName@ + +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). + + + + +@enum_name@ + +The enum name with words lowercase and word-separated by underscores +(e.g. prefix_the_xenum). + + + + +@ENUMNAME@ + +The enum name with words uppercase and word-separated by underscores +(e.g. PREFIX_THE_XENUM). + + + + +@ENUMSHORT@ + +The enum name with words uppercase and word-separated by underscores, +prefix stripped (e.g. THE_XENUM). + + + + +@VALUENAME@ + +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). + + + + +@valuenick@ + +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). + + + + +@type@ + +This is substituted either by "enum" or "flags", depending on whether the +enum value definitions contained bit-shift operators or not (e.g. flags). + + + + +@Type@ + +The same as @type@ with the first letter capitalized (e.g. Flags). + + + + +@TYPE@ + +The same as @type@ with all letters uppercased (e.g. FLAGS). + + + + +@filename@ + +The name of the input file currently being processed (e.g. foo.h). + + + + + +Trigraph extensions + +Some C comments are treated specially in the parsed enum definitions, +such comments start out with the trigraph sequence /*< +and end with the trigraph sequence >*/. +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: + +typedef enum /*< skip >*/ +{ + PREFIX_FOO +} PrefixThisEnumWillBeSkipped; +typedef enum /*< flags,prefix=PREFIX >*/ +{ + PREFIX_THE_ZEROTH_VALUE, /*< skip >*/ + PREFIX_THE_FIRST_VALUE, + PREFIX_THE_SECOND_VALUE, + PREFIX_THE_THIRD_VALUE, /*< nick=the-last-value >*/ +} PrefixTheFlagsEnum; + + + + +See also + +glib-genmarshal(1) + + + + + diff --git a/docs/reference/gobject/gobject-docs.sgml b/docs/reference/gobject/gobject-docs.sgml index bc14ff501..691d5d3e0 100644 --- a/docs/reference/gobject/gobject-docs.sgml +++ b/docs/reference/gobject/gobject-docs.sgml @@ -14,6 +14,9 @@ + + + ]> @@ -84,6 +87,14 @@ &gobject-Value-Arrays; + + Tools Reference + + &glib-mkenums; + &glib-genmarshal; + &gobject-query; + + diff --git a/docs/reference/gobject/gobject-query.1 b/docs/reference/gobject/gobject-query.1 new file mode 100644 index 000000000..b8ae5db94 --- /dev/null +++ b/docs/reference/gobject/gobject-query.1 @@ -0,0 +1,80 @@ +.\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH "GOBJECT-QUERY" 1 "" "" "" +.SH NAME +gobject-query \- display a tree of types +.SH "SYNOPSIS" + +.nf +\fBgobject-query\fR froots [options...] +.fi + +.nf +\fBgobject-query\fR tree [options...] +.fi + +.SH "DESCRIPTION" + +.PP + \fBgobject-query\fR is a small utility that draws a tree of types\&. + +.SH "INVOKATION" + +.PP + \fBgobject-query\fR takes a mandatory argument that specifies whether it should iterate over the fundamental types or print a type tree\&. + +.SS "Options" + +.TP +\fBfroots\fR +iterate over fundamental roots + +.TP +\fBtree\fR +print type tree + +.TP +\fB-r\fR \fItype\fR +specify the root type + +.TP +\fB-n\fR +don't descend type tree + +.TP +\fB-b\fR \fIstring\fR +specify indent string + +.TP +\fB-i\fR \fIstring\fR +specify incremental indent string + +.TP +\fB-s\fR \fInumber\fR +specify line spacing + +.TP +\fB-h\fR, \fB--help\fR +Print brief help and exit\&. + +.TP +\fB-v\fR, \fB--version\fR +Print version and exit\&. + diff --git a/docs/reference/gobject/gobject-query.xml b/docs/reference/gobject/gobject-query.xml new file mode 100644 index 000000000..a2fbf2731 --- /dev/null +++ b/docs/reference/gobject/gobject-query.xml @@ -0,0 +1,111 @@ + + + +gobject-query +1 + + + +gobject-query +display a tree of types + + + + +gobject-query +froots +options + + +gobject-query +tree +options + + + +Description + +gobject-query is a small utility that draws a tree of +types. + + + +Invokation + +gobject-query takes a mandatory argument that specifies +whether it should iterate over the fundamental types or print a type tree. + + +Options + + + + + +iterate over fundamental roots + + + + + + +print type tree + + + + + type + +specify the root type + + + + + + +don't descend type tree + + + + + string + +specify indent string + + + + + string + +specify incremental indent string + + + + + + number + +specify line spacing + + + + +, + +Print brief help and exit. + + + + +, + +Print version and exit. + + + + + + + + + diff --git a/gobject/Makefile.am b/gobject/Makefile.am index 2489052c9..20e78b580 100644 --- a/gobject/Makefile.am +++ b/gobject/Makefile.am @@ -190,11 +190,6 @@ gobject_query_LDADD = $(progs_LDADD) testgobject_LDADD = $(progs_LDADD) testoverride_LDADD = $(progs_LDADD) -# -# manual pages to install -# -man_MANS = glib-genmarshal.1 glib-mkenums.1 - # # auxillary files #