Auto merge of #2124 - str4d:2086-help2man, r=str4d

Improve autogenerated manpages

Cherry-picked from bitcoin/bitcoin#8608.

Closes #2086.

Makefile.am

@@ -1,5 +1,8 @@
 ACLOCAL_AMFLAGS = -I build-aux/m4
 SUBDIRS = src
+if ENABLE_MAN
+SUBDIRS += doc/man
+endif
 .PHONY: deploy FORCE
 
 GZIP_ENV="-9n"
@@ -280,5 +283,7 @@ CLEANFILES = $(OSX_DMG) $(BITCOIN_WIN_INSTALLER)
 
 .INTERMEDIATE: $(COVERAGE_INFO)
 
+DISTCHECK_CONFIGURE_FLAGS = --enable-man
+
 clean-local:
 	rm -rf test_bitcoin.coverage/ zcash-gtest.coverage/ total.coverage/ $(OSX_APP)

configure.ac

@@ -164,6 +164,12 @@ AC_ARG_ENABLE([zmq],
 
 AC_ARG_WITH([protoc-bindir],[AS_HELP_STRING([--with-protoc-bindir=BIN_DIR],[specify protoc bin path])], [protoc_bin_path=$withval], [])
 
+AC_ARG_ENABLE(man,
+    [AS_HELP_STRING([--disable-man],
+                    [do not install man pages (default is to install)])],,
+    enable_man=yes)
+AM_CONDITIONAL(ENABLE_MAN, test "$enable_man" != no)
+
 # Enable debug
 AC_ARG_ENABLE([debug],
     [AS_HELP_STRING([--enable-debug],
@@ -975,7 +981,7 @@ AC_SUBST(GMP_LIBS)
 AC_SUBST(GMPXX_LIBS)
 AC_SUBST(LIBSNARK_LIBS)
 AC_SUBST(LIBZCASH_LIBS)
-AC_CONFIG_FILES([Makefile src/Makefile share/setup.nsi share/qt/Info.plist src/test/buildenv.py])
+AC_CONFIG_FILES([Makefile src/Makefile doc/man/Makefile share/setup.nsi share/qt/Info.plist src/test/buildenv.py])
 AC_CONFIG_FILES([qa/pull-tester/run-bitcoind-for-test.sh],[chmod +x qa/pull-tester/run-bitcoind-for-test.sh])
 AC_CONFIG_FILES([qa/pull-tester/tests-config.sh],[chmod +x qa/pull-tester/tests-config.sh])
 

contrib/devtools/README.md

@@ -81,6 +81,12 @@ It will do the following automatically:
 
 See doc/translation-process.md for more information.
 
+gen-manpages.sh
+===============
+
+A small script to automatically create manpages in ../../doc/man by running the release binaries with the -help option.
+This requires help2man which can be found at: https://www.gnu.org/software/help2man/
+
 git-subtree-check.sh
 ====================
 

contrib/devtools/gen-manpages.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+
+TOPDIR=${TOPDIR:-$(git rev-parse --show-toplevel)}
+SRCDIR=${SRCDIR:-$TOPDIR/src}
+MANDIR=${MANDIR:-$TOPDIR/doc/man}
+
+ZCASHD=${ZCASHD:-$SRCDIR/zcashd}
+ZCASHCLI=${ZCASHCLI:-$SRCDIR/zcash-cli}
+ZCASHTX=${ZCASHTX:-$SRCDIR/zcash-tx}
+
+[ ! -x $ZCASHD ] && echo "$ZCASHD not found or not executable." && exit 1
+
+# The autodetected version git tag can screw up manpage output a little bit
+ZECVER=($($ZCASHCLI --version | head -n1 | awk -F'[ -]' '{ print $5, $6 }'))
+
+# Create a footer file with copyright content.
+# This gets autodetected fine for zcashd if --version-string is not set,
+# but has different outcomes for zcash-cli.
+echo "[COPYRIGHT]" > footer.h2m
+$ZCASHD --version | sed -n '1!p' >> footer.h2m
+
+for cmd in $ZCASHD $ZCASHCLI $ZCASHTX; do
+  cmdname="${cmd##*/}"
+  help2man -N --version-string=${ZECVER[0]} --include=footer.h2m -o ${MANDIR}/${cmdname}.1 ${cmd}
+  sed -i "s/\\\-${ZECVER[1]}//g" ${MANDIR}/${cmdname}.1
+done
+
+rm -f footer.h2m

doc/man/Makefile.am

@@ -0,0 +1 @@
+dist_man1_MANS=zcashd.1 zcash-cli.1 zcash-fetch-params.1 zcash-tx.1

doc/man/zcash-cli.1

@@ -1,9 +1,9 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.3.
-.TH ZCASH-CLI "1" "February 2017" "Zcash RPC client version v1.0.6" "User Commands"
+.TH ZCASH-CLI "1" "February 2017" "zcash-cli v1.0.6" "User Commands"
 .SH NAME
-zcash-cli \- RPC client for the Zcash daemon
+zcash-cli \- manual page for zcash-cli v1.0.6
 .SH DESCRIPTION
-Zcash RPC client version v1.0.6
+Zcash RPC client version v1.0.6\-dirty
 .SS "Usage:"
 .TP
 zcash\-cli [options] <command> [params]
@@ -64,27 +64,14 @@ SSL options: (see the Bitcoin Wiki for SSL setup instructions)
 .IP
 Use OpenSSL (https) for JSON\-RPC connections
 .SH COPYRIGHT
-Copyright \(co 2009\-2017 The Bitcoin Core Developers
+Copyright (C) 2009-2017 The Bitcoin Core Developers
-.br
+Copyright (C) 2015-2017 The Zcash Developers
-Copyright \(co 2015\-2017 The Zcash Developers
+
-.PP
 This is experimental software.
-.PP
+
 Distributed under the MIT software license, see the accompanying file COPYING
-or <http://www.opensource.org/licenses/mit\-license.php>.
+or <http://www.opensource.org/licenses/mit-license.php>.
-.PP
+
 This product includes software developed by the OpenSSL Project for use in the
 OpenSSL Toolkit <https://www.openssl.org/> and cryptographic software written
 by Eric Young and UPnP software written by Thomas Bernard.
-.SH "SEE ALSO"
-The full documentation for
-.B Zcash
-is maintained as a Texinfo manual.  If the
-.B info
-and
-.B Zcash
-programs are properly installed at your site, the command
-.IP
-.B info Zcash
-.PP
-should give you access to the complete manual.

doc/man/zcash-tx.1

@@ -0,0 +1,97 @@
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.3.
+.TH ZCASH-TX "1" "February 2017" "zcash-tx v1.0.6" "User Commands"
+.SH NAME
+zcash-tx \- manual page for zcash-tx v1.0.6
+.SH DESCRIPTION
+Zcash zcash\-tx utility version v1.0.6\-dirty
+.SS "Usage:"
+.TP
+zcash\-tx [options] <hex\-tx> [commands]
+Update hex\-encoded zcash transaction
+.TP
+zcash\-tx [options] \fB\-create\fR [commands]
+Create hex\-encoded zcash transaction
+.SH OPTIONS
+.HP
+\-?
+.IP
+This help message
+.HP
+\fB\-create\fR
+.IP
+Create new, empty TX.
+.HP
+\fB\-json\fR
+.IP
+Select JSON output
+.HP
+\fB\-txid\fR
+.IP
+Output only the hex\-encoded transaction id of the resultant transaction.
+.HP
+\fB\-regtest\fR
+.IP
+Enter regression test mode, which uses a special chain in which blocks
+can be solved instantly.
+.HP
+\fB\-testnet\fR
+.IP
+Use the test network
+.PP
+Commands:
+.IP
+delin=N
+.IP
+Delete input N from TX
+.IP
+delout=N
+.IP
+Delete output N from TX
+.IP
+in=TXID:VOUT
+.IP
+Add input to TX
+.IP
+locktime=N
+.IP
+Set TX lock time to N
+.IP
+nversion=N
+.IP
+Set TX version to N
+.IP
+outaddr=VALUE:ADDRESS
+.IP
+Add address\-based output to TX
+.IP
+outscript=VALUE:SCRIPT
+.IP
+Add raw script output to TX
+.IP
+sign=SIGHASH\-FLAGS
+.IP
+Add zero or more signatures to transaction. This command requires JSON
+registers:prevtxs=JSON object, privatekeys=JSON object. See
+signrawtransaction docs for format of sighash flags, JSON objects.
+.PP
+Register Commands:
+.IP
+load=NAME:FILENAME
+.IP
+Load JSON file FILENAME into register NAME
+.IP
+set=NAME:JSON\-STRING
+.IP
+Set register NAME to given JSON\-STRING
+.SH COPYRIGHT
+Copyright (C) 2009-2017 The Bitcoin Core Developers
+Copyright (C) 2015-2017 The Zcash Developers
+
+This is experimental software.
+
+Distributed under the MIT software license, see the accompanying file COPYING
+or <http://www.opensource.org/licenses/mit-license.php>.
+
+This product includes software developed by the OpenSSL Project for use in the
+OpenSSL Toolkit <https://www.openssl.org/> and cryptographic software written
+by Eric Young and UPnP software written by Thomas Bernard.

doc/man/zcashd.1

@@ -1,9 +1,9 @@
-.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.3.
-.TH ZCASHD "1" "February 2017" "Zcash Daemon version v1.0.6" "User Commands"
+.TH ZCASHD "1" "February 2017" "zcashd v1.0.6" "User Commands"
 .SH NAME
-zcashd \- Network daemon for interacting with the Zcash blockchain
+zcashd \- manual page for zcashd v1.0.6
 .SH DESCRIPTION
-Zcash Daemon version v1.0.6
+Zcash Daemon version v1.0.6\-dirty
 .SS "Usage:"
 .TP
 zcashd [options]
@@ -66,7 +66,7 @@ Keep at most <n> unconnectable transactions in memory (default: 100)
 .HP
 \fB\-par=\fR<n>
 .IP
-Set the number of script verification threads (\fB\-8\fR to 16, 0 = auto, <0 =
+Set the number of script verification threads (\fB\-4\fR to 16, 0 = auto, <0 =
 leave that many cores free, default: 0)
 .HP
 \fB\-pid=\fR<file>
@@ -457,27 +457,14 @@ output (default: 1 if running in a console, 0 otherwise)
 Number of seconds between metrics refreshes (default: 1 if running in a
 console, 600 otherwise)
 .SH COPYRIGHT
-Copyright \(co 2009\-2017 The Bitcoin Core Developers
+Copyright (C) 2009-2017 The Bitcoin Core Developers
-.br
+Copyright (C) 2015-2017 The Zcash Developers
-Copyright \(co 2015\-2017 The Zcash Developers
+
-.PP
 This is experimental software.
-.PP
+
 Distributed under the MIT software license, see the accompanying file COPYING
-or <http://www.opensource.org/licenses/mit\-license.php>.
+or <http://www.opensource.org/licenses/mit-license.php>.
-.PP
+
 This product includes software developed by the OpenSSL Project for use in the
 OpenSSL Toolkit <https://www.openssl.org/> and cryptographic software written
 by Eric Young and UPnP software written by Thomas Bernard.
-.SH "SEE ALSO"
-The full documentation for
-.B Zcash
-is maintained as a Texinfo manual.  If the
-.B info
-and
-.B Zcash
-programs are properly installed at your site, the command
-.IP
-.B info Zcash
-.PP
-should give you access to the complete manual.

doc/release-process.md

@@ -37,13 +37,6 @@ previous release:
     configure.ac
     contrib/gitian-descriptors/gitian-linux.yml
 
-Build and commit to update versions, and then perform the following commands:
-
-    help2man -n "RPC client for the Zcash daemon" src/zcash-cli > contrib/debian/manpages/zcash-cli.1
-    help2man -n "Network daemon for interacting with the Zcash blockchain" src/zcashd > contrib/debian/manpages/zcashd.1
-
-Check the version number in the man pages as they use the commit id e.g. 1.0.6-xxxxxxx which may need to be manually cleaned up.  Also check the titles use "zcashd" and "zcash-cli", not "zcash".
-
 In `configure.ac` and `clientversion.h`:
 
 - Increment `CLIENT_VERSION_BUILD` according to the following schema:
@@ -60,6 +53,12 @@ In `configure.ac` and `clientversion.h`:
 If this release changes the behavior of the protocol or fixes a serious bug, we may
 also wish to change the `PROTOCOL_VERSION` in `version.h`.
 
+Build and commit to update versions, and then perform the following command:
+
+    $ bash contrib/devtools/gen-manpages.sh
+
+Commit the changes.
+
 ### B2. Write release notes
 
 Run the release-notes.py script to generate release notes and update authors.md file. For example:

zcutil/build-debian-package.sh

@@ -9,6 +9,7 @@ BUILD_PATH="/tmp/zcbuild"
 PACKAGE_NAME="zcash"
 SRC_PATH=`pwd`
 SRC_DEB=$SRC_PATH/contrib/debian
+SRC_DOC=$SRC_PATH/doc
 
 umask 022
 
@@ -45,9 +46,9 @@ cp $SRC_DEB/changelog $DEB_DOC/changelog.Debian
 cp $SRC_DEB/copyright $DEB_DOC
 cp -r $SRC_DEB/examples $DEB_DOC
 # Copy manpages
-cp $SRC_DEB/manpages/zcashd.1 $DEB_MAN
+cp $SRC_DOC/man/zcashd.1 $DEB_MAN
-cp $SRC_DEB/manpages/zcash-cli.1 $DEB_MAN
+cp $SRC_DOC/man/zcash-cli.1 $DEB_MAN
-cp $SRC_DEB/manpages/zcash-fetch-params.1 $DEB_MAN
+cp $SRC_DOC/man/zcash-fetch-params.1 $DEB_MAN
 # Copy bash completion files
 cp $SRC_PATH/contrib/bitcoind.bash-completion $DEB_CMP/zcashd
 cp $SRC_PATH/contrib/bitcoin-cli.bash-completion $DEB_CMP/zcash-cli