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.
---
 docs/reference/endless/Makefile.am      | 30 +++++++++++-
 docs/reference/endless/endless-docs.xml |  5 ++
 docs/reference/endless/eos-profile.xml  | 83 +++++++++++++++++++++++++++++++++
 3 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/endless/eos-profile.xml

(limited to 'docs')

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