GNOME.org
 

[json-glib] docs: Add infrastructure to build man pages

commit 436ed4f2b0ce86764c84af8e0ad4b1181a287050
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Oct 27 23:11:56 2013 +0000

    docs: Add infrastructure to build man pages
    
    The small utilities we build and install should have their own manual
    pages.

 .gitignore                           |    2 +
 build/autotools/Makefile.am          |    1 +
 build/autotools/jh-catalog.m4        |   54 ++++++++++++++++++++++
 configure.ac                         |   50 +++++++++++++++++++++
 doc/reference/Makefile.am            |   31 ++++++++++++-
 doc/reference/json-glib-format.xml   |   81 ++++++++++++++++++++++++++++++++++
 doc/reference/json-glib-validate.xml |   67 ++++++++++++++++++++++++++++
 7 files changed, 283 insertions(+), 3 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index fe3cdb9..e470526 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,6 +21,8 @@ config.status
 config.sub
 depcomp
 /doc/reference/version.xml
+/doc/reference/json-glib-format.1
+/doc/reference/json-glib-validate.1
 gtk-doc.make
 install-sh
 json-glib-1.0.pc
diff --git a/build/autotools/Makefile.am b/build/autotools/Makefile.am
index 6d7f809..3df2235 100644
--- a/build/autotools/Makefile.am
+++ b/build/autotools/Makefile.am
@@ -4,6 +4,7 @@ EXTRA_DIST = \
        glib-tap.mk             \
        glibtests.m4            \
        introspection.m4        \
+       jh-catalog.m4           \
        Makefile.am.silent      \
        Makefile.am.enums       \
        Makefile.am.marshal     \
diff --git a/build/autotools/jh-catalog.m4 b/build/autotools/jh-catalog.m4
new file mode 100644
index 0000000..dd01f16
--- /dev/null
+++ b/build/autotools/jh-catalog.m4
@@ -0,0 +1,54 @@
+# Checks the location of the XML Catalog
+# Usage:
+#   JH_PATH_XML_CATALOG([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
+# 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])
+  jh_found_xmlcatalog=true
+  XML_CATALOG_FILE="$with_xml_catalog"
+  AC_SUBST([XML_CATALOG_FILE])
+  AC_MSG_CHECKING([for XML catalog ($XML_CATALOG_FILE)])
+  if test -f "$XML_CATALOG_FILE"; then
+    AC_MSG_RESULT([found])
+  else
+    jh_found_xmlcatalog=false
+    AC_MSG_RESULT([not found])
+  fi
+
+  # check for the xmlcatalog program
+  AC_PATH_PROG(XMLCATALOG, xmlcatalog, no)
+  if test "x$XMLCATALOG" = xno; then
+    jh_found_xmlcatalog=false
+  fi
+
+  if $jh_found_xmlcatalog; then
+    ifelse([$1],,[:],[$1])
+  else
+    ifelse([$2],,[AC_MSG_ERROR([could not find XML catalog])],[$2])
+  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],[JH_PATH_XML_CATALOG(,[:])])dnl
+  AC_MSG_CHECKING([for ifelse([$2],,[$1],[$2]) in XML catalog])
+  if $jh_found_xmlcatalog && \
+     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.ac b/configure.ac
index abc2839..38d45ca 100644
--- a/configure.ac
+++ b/configure.ac
@@ -267,6 +267,55 @@ dnl === Documentation =========================================================
 
 GTK_DOC_CHECK([1.13], [--flavour no-tmpl])
 
+AC_ARG_ENABLE([man,]
+              [AS_HELP_STRING([--enable-man], [generate man pages [default=auto]])],
+              [],
+              [enable_man=maybe])
+
+AS_IF([test "$enable_man" != no], [
+  AC_PATH_PROG([XSLTPROC], [xsltproc])
+  AS_IF([test -z "$XSLTPROC"], [
+    AS_IF([test "$enable_man" = yes], [
+      AC_MSG_ERROR([xsltproc is required for --enable-man])
+    ])
+    enable_man=no
+  ])
+])
+
+AS_IF([ test "$enable_man" != no ], [
+  dnl check for DocBook DTD in the local catalog
+  JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.1.2//EN],
+     [DocBook XML DTD V4.1.2], [have_docbook_dtd=yes], [have_docbook_dtd=no])
+  AS_IF([test "$have_docbook_dtd" != yes], [
+    AS_IF([test "$enable_man" = yes ], [
+      AC_MSG_ERROR([DocBook DTD is required for --enable-man])
+    ])
+    enable_man=no
+  ])
+])
+
+AS_IF([test "$enable_man" != no], [
+  dnl check for DocBook XSL stylesheets in the local catalog
+  JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl],
+     [DocBook XSL Stylesheets], [have_docbook_style=yes],[have_docbook_style=no])
+  AS_IF([ test "$have_docbook_dtd" != yes ], [
+    AS_IF([ test "$enable_man" = yes ], [
+      AC_MSG_ERROR([DocBook XSL Stylesheets are required for --enable-man])
+    ])
+    enable_man=no
+  ])
+])
+
+AM_CONDITIONAL(ENABLE_MAN, test "$enable_man" != no)
+
+AC_MSG_CHECKING([whether to generate man pages])
+AS_IF([ test "$enable_man" != no ], [
+  enable_man=yes
+  AC_MSG_RESULT([yes])
+], [
+  AC_MSG_RESULT([no])
+])
+
 dnl === Introspection =========================================================
 
 GOBJECT_INTROSPECTION_CHECK([0.9.5])
@@ -324,6 +373,7 @@ echo " • Debug level: ${enable_debug}"
 echo " • Compiler flags: ${CFLAGS} ${MAINTAINER_CFLAGS}"
 echo ""
 echo " • API reference: ${enable_gtk_doc}"
+echo " • Manual pages: ${enable_man}"
 echo ""
 echo " • Enable test suite: ${enable_modular_tests}"
 echo " • Install tests: ${enable_installed_tests}"
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index b160070..65328ed 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -63,7 +63,10 @@ HTML_IMAGES =
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files = version.xml
+content_files = \
+       json-glib-format.xml \
+       json-glib-validate.xml \
+       version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -93,6 +96,28 @@ check-local: test
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
 
-# Other files to distribute
-# e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST += version.xml.in
+
+man_MANS =
+
+if ENABLE_MAN
+man_MANS += \
+       json-glib-format.1 \
+       json-glib-validate.1
+
+XSLTPROC_FLAGS = \
+       --nonet \
+       --stringparam man.output.quietly 1 \
+       --stringparam funcsynopsis.style ansi \
+       --stringparam man.th.extra1.suppress 1 \
+       --stringparam man.authors.section.enabled 0 \
+       --stringparam man.copyright.section.enabled 0
+
+.xml.1:
+       $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) 
http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+endif
+
+CLEANFILES ?=
+CLEANFILES += $(man_MANS)
+EXTRA_DIST += $(man_MANS)
diff --git a/doc/reference/json-glib-format.xml b/doc/reference/json-glib-format.xml
new file mode 100644
index 0000000..d4ba59e
--- /dev/null
+++ b/doc/reference/json-glib-format.xml
@@ -0,0 +1,81 @@
+<refentry id="json-format-tool" lang="en">
+
+<refentryinfo>
+  <title>json-glib-format</title>
+  <productname>JSON-GLib</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Emmanuele</firstname>
+      <surname>Bassi</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>json-glib-format</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>json-glib-format</refname>
+  <refpurpose>JSON-GLib formatting tool</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>json-glib-format</command>
+    <arg><option>-h</option>, <option>--help</option></arg>
+    <arg><option>--prettify</option></arg>
+    <arg><option>--indent-spaces</option> <replaceable>SPACES</replaceable></arg>
+    <arg choice="plain">URI</arg>
+    <arg>
+      <arg choice="plain" rep="repeat">URI</arg>
+    </arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>json-glib-format</command> offers a simple command line
+interface to format JSON data. It reads a list or URIs, applies the
+spacified formatting rules on the JSON data, and outputs the formatted
+JSON to the standard output.</para>
+
+<para>
+The resources to operate on are specified by the <replaceable>URI</replaceable>
+argument.
+</para>
+
+</refsect1>
+
+<refsect1><title>Commands</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Prints help and exits.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-p</option>, <option>--prettify</option></term>
+<listitem><para>
+Prettifies the output, by adding spaces and indentation. This argument is
+useful to improve the readability of JSON data, at the expense of its size.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--indent-spaces</option> <replaceable>SPACES</replaceable></term>
+<listitem><para>
+Changes the number of spaces using to indent the JSON data from the default of 2.
+This argument is only considered if <option>--prettify</option> is used.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</refsect1>
+</refentry>
diff --git a/doc/reference/json-glib-validate.xml b/doc/reference/json-glib-validate.xml
new file mode 100644
index 0000000..1cd5c6d
--- /dev/null
+++ b/doc/reference/json-glib-validate.xml
@@ -0,0 +1,67 @@
+<refentry id="json-validate-tool" lang="en">
+
+<refentryinfo>
+  <title>json-glib-validate</title>
+  <productname>JSON-GLib</productname>
+  <authorgroup>
+    <author>
+      <contrib>Developer</contrib>
+      <firstname>Emmanuele</firstname>
+      <surname>Bassi</surname>
+    </author>
+  </authorgroup>
+</refentryinfo>
+
+<refmeta>
+  <refentrytitle>json-glib-validate</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>json-glib-validate</refname>
+  <refpurpose>JSON-GLib validation tool</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>json-glib-validate</command>
+    <arg><option>-h</option>, <option>--help</option></arg>
+    <arg choice="plain">URI</arg>
+    <arg>
+      <arg choice="plain" rep="repeat">URI</arg>
+    </arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>json-glib-validate</command> offers a simple command line
+interface to validate JSON data. It lets you list URIs that point to JSON
+data and checks that the data conforms to the JSON syntax.</para>
+
+<para>
+The resources to operate on are specified by the <replaceable>URI</replaceable>
+argument.
+</para>
+
+<para>
+If the JSON data is valid, <command>json-glib-validate</command> will terminate
+with an exit code of 0; if the data is invalid, an error will be printed on
+<replaceable>stderr</replaceable> and <command>json-glib-validate</command> will
+terminate with a nonzero exit code.</para>
+</refsect1>
+
+<refsect1><title>Commands</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+Prints help and exits.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</refsect1>
+</refentry>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]