[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [flashproxy/master] add help2man build scripts to generate manpages for the facilitator



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



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits