From 4caf9df8b070140ee62218d3ea678f9732c1b8a7 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 20 Feb 2018 18:33:19 +0000
Subject: Build man page and reference for eos-profile

Documenting CLI tools that we ship should be part of the API reference.
---
 configure.ac                            | 13 ++++++
 docs/reference/endless/Makefile.am      | 30 +++++++++++-
 docs/reference/endless/endless-docs.xml |  5 ++
 docs/reference/endless/eos-profile.xml  | 83 +++++++++++++++++++++++++++++++++
 4 files changed, 130 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/endless/eos-profile.xml

diff --git a/configure.ac b/configure.ac
index 66edc49..b42cf64 100644
--- a/configure.ac
+++ b/configure.ac
@@ -121,6 +121,8 @@ AC_PATH_PROG([GIRDOCTOOL], [g-ir-doc-tool], [notfound])
 AC_ARG_VAR([GIRDOCTOOL], [Path to g-ir-doc-tool])
 AC_PATH_PROG([YELPBUILD], [yelp-build], [notfound])
 AC_ARG_VAR([YELPBUILD], [Path to yelp-build])
+AC_PATH_PROG([XSLTPROC], [xsltproc], [notfound])
+AC_ARG_VAR([XSLTPROC], [Path to xsltproc])
 GLIB_COMPILE_RESOURCES=`$PKG_CONFIG --variable glib_compile_resources gio-2.0`
 AC_SUBST(GLIB_COMPILE_RESOURCES)
 AC_PATH_PROG([DBUS_RUN_SESSION], [dbus-run-session])
@@ -190,6 +192,17 @@ AS_IF([test "x$enable_gir_doc" = "xyes"], [
 		[AC_MSG_ERROR([yelp-build must be installed for --enable-gir-doc])])])
 AM_CONDITIONAL([ENABLE_GIR_DOC], [test "x$enable_gir_doc" = "xyes"])
 
+AC_ARG_ENABLE([man],
+        [AS_HELP_STRING([--enable-man],
+                [Build man pages for the installed tools @<:@default=no@:>@])])
+AS_IF([test "x$enable_man" != xno], [
+        AS_IF([test "x$XSLTPROC" = xnotfound], [
+                AS_IF([test "x$enable_man" = xyes], [
+                        AC_MSG_ERROR([xsltproc must be installed for --enable-man])])
+                enable_man=no])])
+
+AM_CONDITIONAL([ENABLE_MAN], [test "x$enable_man" != xno])
+
 # For 'make dist' or 'make distcheck', both of --enable-gtk-doc and
 # --enable-gir-doc are required
 AC_MSG_CHECKING([whether this configuration allows building distributions])
diff --git a/docs/reference/endless/Makefile.am b/docs/reference/endless/Makefile.am
index c5143ef..3fa85a6 100644
--- a/docs/reference/endless/Makefile.am
+++ b/docs/reference/endless/Makefile.am
@@ -73,7 +73,9 @@ 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=
+content_files=\
+	eos-profile.xml \
+	$(NULL)
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -106,3 +108,29 @@ TESTS_ENVIRONMENT = \
 	export BUILDDIR=$(abs_builddir);
 TESTS = $(GTKDOC_CHECK)
 endif
+
+man_MANS =
+
+if ENABLE_MAN
+
+man_MANS += \
+	eos-profile.1 \
+	$(NULL)
+
+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 1 \
+	$(NULL)
+
+.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/docs/reference/endless/endless-docs.xml b/docs/reference/endless/endless-docs.xml
index 35a741f..f88da92 100644
--- a/docs/reference/endless/endless-docs.xml
+++ b/docs/reference/endless/endless-docs.xml
@@ -28,6 +28,11 @@
     <!--<xi:include href="xml/hello.xml"/>-->
   </chapter>
 
+  <chapter id="tools">
+    <title>Tools</title>
+    <xi:include href="eos-profile.xml"/>
+  </chapter>
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
diff --git a/docs/reference/endless/eos-profile.xml b/docs/reference/endless/eos-profile.xml
new file mode 100644
index 0000000..dc3b09f
--- /dev/null
+++ b/docs/reference/endless/eos-profile.xml
@@ -0,0 +1,83 @@
+<refentry id="eos-profile-tool" lang="en">
+  <refentryinfo>
+    <title>eos-profile</title>
+    <productname>Endless</productname>
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Emmanuele</firstname>
+        <surname>Bassi</surname>
+        <org><orgname>Endless</orgname></org>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>eos-profile</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>eos-profile</refname>
+    <refpurpose>Inspect profiling data</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>eos-profile</command>
+      <arg choice="plain">help</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>eos-profile</command>
+      <arg choice="plain">show</arg>
+      <arg choice="plain"><replaceable>FILE</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>eos-profile</command>
+      <arg choice="plain">convert</arg>
+      <arg choice="plain"><replaceable>FILE</replaceable></arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>eos-profile</command>
+      <arg choice="plain">diff</arg>
+      <arg choice="plain" rep="repeat"><replaceable>FILE</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      <command>eos-profile</command> is a tool for inspecting, converting, and
+      comparing profile data files generated by the Endless SDK.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Commands</title>
+    <variablelist>
+      <varlistentry>
+        <term><option>show</option></term>
+        <listitem><para>
+          Prints out a list of the profiling probes for the given file,
+          as well as the various timing information associated to each
+          probe, and their location in the source.
+        </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>convert</option></term>
+        <listitem><para>
+          Converts a profile data file into other formats, like JSON.
+        </para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>diff</option></term>
+        <listitem><para>
+          Compares two or more profile data files, and prints out the
+          timing information for each probe in each file.
+        </para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+</refentry>
-- 
cgit v1.2.3