commit 25697fdc9756f9174aec91af0f238bcacbf48e34 Author: Ximin Luo <infinity0@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.... 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