Manpage improvements:

- Added a manpage for ms_print.

- Added docs/xml/manpages-index.xml, which is just used as a convenient
  single file to hang all the man pages off so they can be generated in a
  single command.

- Added facility whereby manpage generation will attempt to find the
  stylesheet in multiple places.  This means I don't have to constantly edit
  XSL_MAN_STYLE to build manpages on my machine.

- Changed vg-docs-path to start with $INSTALL instead of /usr/, because we
  can't assume that's the installation dir.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10740

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 5759f0aae88dd860dca64019a71c9074ce40ca33..9cf464e0f0fabcd3d8927e0bf54e064401e6c114 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -57,6 +57,7 @@ EXTRA_DIST = \
        xml/dist-docs.xml \
        xml/index.xml \
        xml/licenses.xml \
+       xml/manpages-index.xml \
        xml/manual.xml \
        xml/manual-intro.xml \
        xml/manual-core.xml \
@@ -106,7 +107,9 @@ XSL_HTML_CHUNK_STYLE  = $(mylibdir)/vg-html-chunk.xsl
 XSL_FO_STYLE          = $(mylibdir)/vg-fo.xsl
 XSL_TEXT_STYLE        = $(mylibdir)/vg-faq2txt.xsl
 XSL_WEBSITE_STYLE     = $(mylibdir)/vg-html-website.xsl
-XSL_MAN_STYLE = /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
+XSL_MAN_STYLES = \
+    /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl \
+    /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
 
 all-docs: FAQ.txt man-page html-docs print-docs
 
@@ -119,16 +122,21 @@ FAQ.txt:
        export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
        $(XSLTPROC) $(XSLTPROC_FLAGS) -o ./FAQ.txt $(XSL_TEXT_STYLE) $(myxmldir)/FAQ.xml
 
-# the valgrind manpage
+# the valgrind manpages
 man-page:
-       if test ! -f $(XSL_MAN_STYLE); then \
-           echo "Error: I can't find the file '$(XSL_MAN_STYLE)'";     \
-           echo "Please check where it lives on your system, and"      \
-                "amend the line 'XSL_MAN_STYLE = ' in this Makefile."; \
-                 exit 1; \
-       fi;
-       export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
-       $(XSLTPROC) $(XSLTPROC_FLAGS) -o ./ $(XSL_MAN_STYLE) $(myxmldir)/valgrind-manpage.xml
+       for x in $(XSL_MAN_STYLES) ; do \
+           if test -f $$x; then \
+               echo "Using manpage stylesheet: $$x"; \
+               export XML_CATALOG_FILES=$(XML_CATALOG_FILES) && \
+               $(XSLTPROC) $(XSLTPROC_FLAGS) -o ./ $$x $(myxmldir)/manpages-index.xml; \
+               exit 0; \
+           fi; \
+       done; \
+       echo ""; \
+       echo "Error: I can't find the XSL_MAN_STYLE file";     \
+       echo "Please check where it lives on your system, and"      \
+            "amend the line 'XSL_MAN_STYLES = ' in this Makefile."; \
+       exit 1;
 
 # chunked html, on a chapter-by-chapter basis
 html-docs:

diff --git a/docs/README b/docs/README
index dcccb5f6a0017eb8fba6082dc888f814674750c7..77ecbc5829475e81c7449c2137899a994cb23466 100644 (file)
--- a/docs/README
+++ b/docs/README
@@ -128,11 +128,12 @@ For Ubuntu 9.04, to build HTML docs I had to:
 Actually, I'm not sure if the 'docbook' is necessary, but 'docbook-xsl'
 definitely is.
 
-To build the man pages I also had to change the value of XSL_MAN_STYLE from this:
+To build the man pages I also changed the Makefile.am to try this
+stylesheet:
 
     /usr/share/xml/docbook/stylesheet/nwalsh/current/manpages/docbook.xsl
 
-to this:
+if it can't find this one:
 
     /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl
 

diff --git a/docs/xml/manpages-index.xml b/docs/xml/manpages-index.xml
new file mode 100644 (file)
index 0000000..60aacf3
--- /dev/null
+++ b/docs/xml/manpages-index.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!-- This file is not part of the distributed docs, it's just here so we can
+     point $(XSTLPROC) at a single file and get all the man pages. -->
+
+<set>
+
+<!-- valgrind -->
+<xi:include href="valgrind-manpage.xml" parse="xml"  
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<!-- ms_print -->
+<xi:include href="../../massif/docs/ms_print-manpage.xml" parse="xml"  
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</set>
+

diff --git a/docs/xml/valgrind-manpage.xml b/docs/xml/valgrind-manpage.xml
index d0557746210a1dea5b8693bd920e7263a5aacefa..d1988db421b6c539b6beae5247da45e32825043a 100644 (file)
--- a/docs/xml/valgrind-manpage.xml
+++ b/docs/xml/valgrind-manpage.xml
@@ -222,8 +222,8 @@ system: <filename>&vg-docs-path;</filename>, or online:
 <title>See Also</title>
 
 <para>
-<filename>&vg-docs-path;</filename>, 
-and/or 
+ms_print(1),
+<filename>&vg-docs-path;</filename> or
 <filename>&vg-docs-url;</filename>.
 </para>
 
@@ -233,12 +233,9 @@ and/or
 <refsect1 id="author">
 <title>Author</title>
 
-<para>This manpage has been written by Andres Roldan &lt;aroldan@debian.org&gt;
-for the Debian Project, but can be used for any other distribution.</para>
-
-<para>Updated, rearranged and expanded by Robert Walsh
-&lt;rjwalsh@durables.org&gt; for the 2.4.0 release, and by other
-Valgrind developers subsequently.</para>
+<para>This manpage written by Andres Roldan &lt;aroldan@debian.org&gt;,
+Robert Walsh &lt;rjwalsh@durables.org&gt;, and the Valgrind
+developers.</para>
 
 </refsect1>
 

diff --git a/docs/xml/vg-entities.xml b/docs/xml/vg-entities.xml
index 1f0d0652fa0f5543ee1397d94197c4542a5ac20d..5da7c013a43a6e94e994599ccb067af9e15d63c9 100644 (file)
--- a/docs/xml/vg-entities.xml
+++ b/docs/xml/vg-entities.xml
@@ -9,7 +9,7 @@
 <!ENTITY rel-date    "2 January 2009">
 
 <!-- where the docs are installed -->
-<!ENTITY vg-docs-path  "/usr/share/doc/valgrind/html/index.html">
+<!ENTITY vg-docs-path  "$INSTALL/share/doc/valgrind/html/index.html">
 
 <!-- valgrind website links used in lots of places in the docs  -->
 <!-- kept in here 'cos everytime the website gets changed, it`s -->

diff --git a/massif/Makefile.am b/massif/Makefile.am
index bfb54a38369fe2b31a087a6dfb2aeee94c8a012d..32c54dd032ebfec5a09d3bd230c6561a78271059 100644 (file)
--- a/massif/Makefile.am
+++ b/massif/Makefile.am
@@ -2,7 +2,9 @@ include $(top_srcdir)/Makefile.tool.am
 
 SUBDIRS += perf
 
-EXTRA_DIST = docs/ms-manual.xml
+EXTRA_DIST = \
+       docs/ms-manual.xml \
+       docs/ms_print-manpage.xml
 
 #----------------------------------------------------------------------------
 # Headers, etc

diff --git a/massif/docs/ms-manual.xml b/massif/docs/ms-manual.xml
index 804e400f18e4de882cf5f45c2531c7d0511ce6b7..e9f34474ba3b99a92e76ed4b20ead2e7861dca0b 100644 (file)
--- a/massif/docs/ms-manual.xml
+++ b/massif/docs/ms-manual.xml
@@ -829,7 +829,8 @@ way.</para>
 
 <para>ms_print's options are:</para>
 
-<variablelist>
+<!-- start of xi:include in the manpage -->
+<variablelist id="ms_print.opts.list">
 
   <varlistentry>
     <term>

diff --git a/massif/docs/ms_print-manpage.xml b/massif/docs/ms_print-manpage.xml
new file mode 100644 (file)
index 0000000..efec8fd
--- /dev/null
+++ b/massif/docs/ms_print-manpage.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0"?> <!-- -*- sgml -*- -->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]>
+
+
+<refentry id="ms_print">
+
+<refmeta>
+  <refentrytitle>ms_print</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Release &rel-version;</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>ms_print</refname>
+  <refpurpose>post-processing tool for the Valgrind tool Massif</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+  <command>ms_print</command>
+  <arg><replaceable>options</replaceable></arg>
+  <arg>filename</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsect1 id="description">
+<title>Description</title>
+
+<para><command>ms_print</command> takes an output file produced by the
+Valgrind tool Massif and prints the information in an easy-to-read form.
+</para>
+
+</refsect1>
+
+
+
+<refsect1 id="options">
+<title>Options</title>
+
+<xi:include href="ms-manual.xml" xpointer="ms_print.opts.list"
+            xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+</refsect1>
+
+
+
+
+<refsect1 id="see_also">
+<title>See Also</title>
+
+<para>
+valgrind(1),
+<filename>&vg-docs-path;</filename> or
+<filename>&vg-docs-url;</filename>.
+</para>
+
+</refsect1>
+
+
+<refsect1 id="author">
+<title>Author</title>
+
+<para>Nicholas Nethercote.</para>
+
+</refsect1>
+
+
+</refentry>
+
+

diff --git a/massif/ms_print.in b/massif/ms_print.in
index 76f72aa6709d1bc92b960baa707d87b061872fde..2b2a4123958e2048b06e11f5d402a5e1b2c43be2 100755 (executable)
--- a/massif/ms_print.in
+++ b/massif/ms_print.in
@@ -67,7 +67,7 @@ usage: ms_print [options] <file>
   options for the user, with defaults in [ ], are:
     -h --help             show this message
     --version             show version
-    --threshold=<n.n>     significance threshold, in percent [$threshold]
+    --threshold=<m.n>     significance threshold, in percent [$threshold]
     --x=<4..1000>         graph width, in columns [72]
     --y=<4..1000>         graph height, in rows [20]