[tor-commits] [flashproxy/master] add help2man build scripts to generate manpages for the facilitator
infinity0 at torproject.org
infinity0 at torproject.org
Fri Dec 6 19:57:08 UTC 2013
commit 25697fdc9756f9174aec91af0f238bcacbf48e34
Author: Ximin Luo <infinity0 at gmx.com>
Date: Mon Dec 2 16:02:36 2013 +0000
add help2man build scripts to generate manpages for the facilitator
- wrapper script mkman.sh to work around help2man generating non-standard formatting in usage synopses
- keep mkman.sh in top-level, for future use by other components
- symlinks in facilitator/ are so `make distcheck` works. this could be cleaner, but for now I thought we'd keep up the charade of facilitator/ as a self-contained autotools package
- remove -Werror from automake so we can use %-patterns
---
facilitator/.gitignore | 1 +
facilitator/HACKING | 2 +-
facilitator/INSTALL | 2 +-
facilitator/Makefile.am | 13 ++++++++---
facilitator/configure.ac | 2 +-
facilitator/mkman.inc | 1 +
facilitator/mkman.sh | 1 +
mkman.inc | 9 ++++++++
mkman.sh | 55 ++++++++++++++++++++++++++++++++++++++++++++++
9 files changed, 80 insertions(+), 6 deletions(-)
diff --git a/facilitator/.gitignore b/facilitator/.gitignore
index cd4d36b..3c413c1 100644
--- a/facilitator/.gitignore
+++ b/facilitator/.gitignore
@@ -18,6 +18,7 @@
# files built by make
/examples/fp-facilitator.conf
+/doc/*.1
# files for binary-distribution
/flashproxy-facilitator-*.tar.*
diff --git a/facilitator/HACKING b/facilitator/HACKING
index f102880..1bb9f77 100644
--- a/facilitator/HACKING
+++ b/facilitator/HACKING
@@ -19,7 +19,7 @@ than a more appropriate copy.
2. Export PYTHONPATH when you need to run
$ export PYTHONPATH=..
- $ make check
+ $ make && make check
The disadvantage is that you need to do this every shell session.
diff --git a/facilitator/INSTALL b/facilitator/INSTALL
index 7716ccc..a68bffa 100644
--- a/facilitator/INSTALL
+++ b/facilitator/INSTALL
@@ -1,6 +1,6 @@
Install the dependencies.
- # apt-get install make openssl python-m2crypto
+ # apt-get install help2man make openssl python-m2crypto
# apt-get install automake autoconf # if running from git
# apt-get install apache2
diff --git a/facilitator/Makefile.am b/facilitator/Makefile.am
index 9e56a19..935a197 100644
--- a/facilitator/Makefile.am
+++ b/facilitator/Makefile.am
@@ -12,9 +12,12 @@ appenginedir = $(pkgdatadir)/appengine
pkgconfdir = $(sysconfdir)/flashproxy
appengineconfdir = $(pkgconfdir)/reg-appspot
+PYENV = PYTHONPATH='$(srcdir):$(PYTHONPATH)'; export PYTHONPATH;
+
# automake PLVs
dist_bin_SCRIPTS = facilitator facilitator-email-poller facilitator-reg-daemon facilitator-reg
+man1_MANS = doc/facilitator.1 doc/facilitator-email-poller.1 doc/facilitator-reg-daemon.1 doc/facilitator-reg.1
dist_cgibin_SCRIPTS = facilitator.cgi
if DO_INITSCRIPTS
initscript_SCRIPTS = init.d/facilitator init.d/facilitator-email-poller init.d/facilitator-reg-daemon
@@ -26,14 +29,14 @@ dist_example_DATA = examples/fp-facilitator.conf examples/reg-email.pass example
pkgconf_DATA = examples/facilitator-relays
dist_appengine_DATA = appengine/app.yaml appengine/config.go appengine/fp-reg.go
appengineconf_DATA = appengine/config.go
-CLEANFILES = examples/fp-facilitator.conf
-EXTRA_DIST = examples/fp-facilitator.conf.in HACKING $(TESTS)
+CLEANFILES = examples/fp-facilitator.conf $(man1_MANS)
+EXTRA_DIST = examples/fp-facilitator.conf.in mkman.sh mkman.inc HACKING $(TESTS)
TESTS = facilitator-test.py
# see http://www.gnu.org/software/automake/manual/html_node/Parallel-Test-Harness.html#index-TEST_005fEXTENSIONS
TEST_EXTENSIONS = .py
PY_LOG_COMPILER = $(PYTHON)
-AM_TESTS_ENVIRONMENT = PYTHONPATH='$(srcdir):$(PYTHONPATH)'; export PYTHONPATH;
+AM_TESTS_ENVIRONMENT = $(PYENV)
AM_PY_LOG_FLAGS =
# AC_CONFIG_FILES doesn't fully-expand directory variables
@@ -42,6 +45,10 @@ subst_vars = sed -e 's,[@]cgibindir[@],$(cgibindir),g'
# our own targets
+doc/%.1: % mkman.sh mkman.inc Makefile
+ { $(PYENV) $(PYTHON) "$<" --help; } \
+ | { $(PYENV) ./mkman.sh "$<" $(VERSION) > "$@"; }
+
examples/fp-facilitator.conf: examples/fp-facilitator.conf.in Makefile
# mkdir needed for out-of-source build
mkdir -p $$(dirname "$@")
diff --git a/facilitator/configure.ac b/facilitator/configure.ac
index e5184a2..cc41b8b 100644
--- a/facilitator/configure.ac
+++ b/facilitator/configure.ac
@@ -1,6 +1,6 @@
AC_PREREQ([2.68])
AC_INIT([flashproxy-facilitator], [1.4])
-AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AM_INIT_AUTOMAKE([-Wall foreign])
AC_ARG_VAR(fpfacilitatoruser, [the user/group for the facilitator to run as])
fpfacilitatoruser="${fpfacilitatoruser:-fp-facilitator}"
diff --git a/facilitator/mkman.inc b/facilitator/mkman.inc
new file mode 120000
index 0000000..f10056c
--- /dev/null
+++ b/facilitator/mkman.inc
@@ -0,0 +1 @@
+../mkman.inc
\ No newline at end of file
diff --git a/facilitator/mkman.sh b/facilitator/mkman.sh
new file mode 120000
index 0000000..dcd1d5f
--- /dev/null
+++ b/facilitator/mkman.sh
@@ -0,0 +1 @@
+../mkman.sh
\ No newline at end of file
diff --git a/mkman.inc b/mkman.inc
new file mode 100644
index 0000000..6207f0b
--- /dev/null
+++ b/mkman.inc
@@ -0,0 +1,9 @@
+[REPORTING BUGS]
+.sp
+Please report using \fBhttps://trac\&.torproject\&.org/projects/tor\fR\&.
+
+[SEE ALSO]
+.sp
+\fBhttp://crypto\&.stanford\&.edu/flashproxy/\fR
+.sp
+\fBhttps://www\&.torproject\&.org/docs/pluggable\-transports\&.html\&.en\fR
diff --git a/mkman.sh b/mkman.sh
new file mode 100755
index 0000000..1087e41
--- /dev/null
+++ b/mkman.sh
@@ -0,0 +1,55 @@
+#!/bin/bash
+# Wrapper around help2man that takes input from stdin.
+
+set -o errexit
+
+# Read a python program's description from the first paragraph of its docstring.
+get_description() {
+ PYTHONPATH=".:$PYTHONPATH" python - "./$1" <<EOF
+import imp, sys
+sys.dont_write_bytecode = True
+mod = imp.load_source("mod", sys.argv[1])
+doclines = mod.__doc__.splitlines()
+# skip to start of first paragraph
+while not doclines[0]:
+ doclines.pop(0)
+# find where the paragraph ends
+try:
+ r = doclines.index("")
+except ValueError:
+ r = len(doclines)
+print " ".join(doclines[:r]).strip()
+EOF
+}
+
+# Fixes some help2man quirks, see `man man`
+help2man_fixup() {
+ sed -re '
+# restricted to usage synopsis section
+/^\.SH SYNOPSIS$/,/^\.SH \w+$/{
+ # change hypenated parameters to bold, "type exactly as shown"
+ s/\\fI\-/\\fB\-/g;
+ # change ALL-CAPS parameters to italic, "replace with appropriate argument"
+ s/\b([A-Z]+)\b/\\fI\1\\fR/g;
+}'
+}
+
+prog="$1"
+ver="$2"
+name="${3:-$(get_description "$1")}"
+
+# Prepare a temporary executable file that just dumps its own contents.
+trap 'rm -rf .tmp.$$' EXIT INT TERM
+shebang="#!/usr/bin/tail -n+2"
+mkdir -p ".tmp.$$"
+{
+echo "$shebang"
+cat
+} > ".tmp.$$/$prog"
+test $(stat -c "%s" ".tmp.$$/$prog") -gt $((${#shebang} + 1)) || { echo >&2 "no input received; abort"; exit 1; }
+chmod +x ".tmp.$$/$prog"
+
+help2man ".tmp.$$/$prog" --help-option="-q" \
+ --name="$name" --version-string="$ver" \
+ --no-info --include "$(dirname "$0")/mkman.inc" \
+ | help2man_fixup
More information about the tor-commits
mailing list