Asciidoc man page rework (shadowsocks#699)

* Add 'tunnel_address' support for json config parser And allow ss-tunnel to use the newly introduced parser. Signed-off-by: Adam Anonymous <anonymous_temp_user@yahoo.co.jp> * Add "mode" support for jconf Now jconf supports "mode" setting, allowed values are "tcp_only", "tcp_and_udp" and "udp_only". Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Use jconf "mode" for server/local/tunnel/manager Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Add per-project vimrc to gitignore As the coding style differs from kernel and other projects, so such project vimrc should be helpful. Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Introduce asciidoc based documentation framework Use asciidoc for new documentation framework, which could not only output man pages, but also htmls. And asciidoc documentation is much more human-readable than roff man pages. Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert shadowsocks-libev man page to asciidoc The port to asciidoc has some format change compared to old one. The most obvious one is the options listed in SYNOPSIS. Now the options list is not split into 2/3 columns, or we must use asciidoc tables and introduce table frames. Other small change includes the removal of AUTHOR sector, as it's not an expendable method to update AUTHOR sector every time it gets updated. Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert ss-local man page to asciidoc Also modify gitignore, since it use too generic rules to ignore such documentation. Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert ss-manager man page to asciidoc Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert ss-nat man page to asciidoc Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert ss-redir man page to asciidoc Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert ss-server man page to asciidoc Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Convert ss-tunnel man page to asciidoc Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Remove old roff man pages Welcome to the new age of asciidoc. Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp> * Doc: Add equivalent tables for command line options and config file Now user can get a more clear view of config file and command line options. Signed-off-by: Adam Anonymous <anonymous_temp_mail@yahoo.co.jp>
knight084 · Jul 4, 2016 · f793d26 · f793d26
1 parent d4aabcb
commit f793d26
Show file tree

Hide file tree

Showing 22 changed files with 1,285 additions and 1,177 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,14 +6,15 @@ libev/Makefile
 libudns/Makefile
 libcork/Makefile
 libipset/Makefile
+Doc/Makefile
 autom4te.cache/
 /config.h
 config.log
 config.status
 libtool
 pid
 ss.*
-ss-*
+src/ss-*
 stamp-h1
 .libs
 .pc
@@ -36,6 +37,11 @@ libsodium/src/libsodium/include/sodium/version.h
 # Ignore vim cache
 *.swp
 
+# Documentation files
+Doc/*.gz
+Doc/*.xml
+Doc/*.html
+
 #	Do not edit the following section
 # 	Edit Compile Debug Document Distribute
 *~

diff --git a/Doc/Makefile.in b/Doc/Makefile.in
@@ -0,0 +1,105 @@
+ASCIIDOC = @ASCIIDOC@
+ASCIIDOC_EXTRA =
+MANPAGE_XSL = manpage-normal.xsl
+XMLTO = @XMLTO@
+XMLTO_EXTRA = -m manpage-bold-literal.xsl
+GZIPCMD = @GZIP@
+INSTALL = @INSTALL@
+RM = @RM@
+MV = @MV@
+SED = @SED@
+VERSION = $(shell $(SED) -n 's/.*PACKAGE_VERSION "\(.*\)"/\1/p'\
+		  ../config.h)
+
+# Guard against environment variables
+MAN1_TXT =
+MAN1_TXT += ss-local.asciidoc
+MAN1_TXT += ss-manager.asciidoc
+MAN1_TXT += ss-nat.asciidoc
+MAN1_TXT += ss-redir.asciidoc
+MAN1_TXT += ss-server.asciidoc
+MAN1_TXT += ss-tunnel.asciidoc
+
+MAN8_TXT =
+MAN8_TXT += shadowsocks-libev.asciidoc
+
+ifeq ($(DISABLE_DOCUMENTATION),1)
+  MAN1_TXT =
+  MAN8_TXT =
+endif
+
+MAN_TXT = $(MAN8_TXT) $(MAN1_TXT)
+MAN_XML = $(patsubst %.asciidoc,%.xml,$(MAN_TXT))
+MAN_HTML = $(patsubst %.asciidoc,%.html,$(MAN_TXT))
+
+DOC_MAN1 = $(patsubst %.asciidoc,%.1,$(MAN1_TXT))
+GZ_MAN1 = $(patsubst %.asciidoc,%.1.gz,$(MAN1_TXT))
+
+DOC_MAN8 = $(patsubst %.asciidoc,%.8,$(MAN8_TXT))
+GZ_MAN8 = $(patsubst %.asciidoc,%.8.gz,$(MAN8_TXT))
+
+prefix = @prefix@
+mandir ?= $(prefix)/share/man
+man1dir = $(mandir)/man1
+man8dir = $(mandir)/man8
+
+ifneq ($(findstring $(MAKEFLAGS),s),s)
+ifndef V
+	QUIET_RM	= @
+	QUIET_ASCIIDOC	= @echo "    [ASCII]  $@";
+	QUIET_XMLTO	= @echo "    [XMLTO]  $@";
+	QUIET_GZIP	= @echo "    [GZ]     $@";
+	QUIET_STDERR	= 2> /dev/null
+	QUIET_SUBDIR0	= +@subdir=
+	QUIET_SUBDIR1	= ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
+			  $(MAKE) $(PRINT_DIR) -C $$subdir
+	export V
+endif
+endif
+
+all: man
+man: man1 man8
+man1: $(GZ_MAN1)
+man8: $(GZ_MAN8)
+html: $(MAN_HTML)
+
+install: install-man
+
+install-man: man
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+	$(INSTALL) -d -m 755 $(DESTDIR)$(man8dir)
+ifdef GZ_MAN1
+	$(INSTALL) -m 644 $(GZ_MAN1) $(DESTDIR)$(man1dir)
+endif
+ifdef GZ_MAN8
+	$(INSTALL) -m 644 $(GZ_MAN8) $(DESTDIR)$(man8dir)
+endif
+
+clean:
+	$(QUIET_RM)$(RM) -f *.xml *.xml+ *.1 *.1.gz *.8 *.8.gz *.html
+
+%.1.gz : %.1
+	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
+
+%.8.gz : %.8
+	$(QUIET_GZIP)$(GZIPCMD) -n -c $< > $@
+
+%.1 : %.xml
+	$(QUIET_XMLTO)$(RM) -f $@ && \
+	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+%.8 : %.xml
+	$(QUIET_XMLTO)$(RM) -f $@ && \
+	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+
+%.xml : %.asciidoc asciidoc.conf
+	$(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \
+	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
+	    -aversion=$(VERSION) $(ASCIIDOC_EXTRA) -o $@+ $< && \
+	$(MV) $@+ $@
+
+%.html : %.asciidoc asciidoc.conf
+	$(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \
+	$(ASCIIDOC) -b html -d article -f asciidoc.conf \
+		-aversion=$(VERSION) $(ASCIIDOC_EXTRA) -o $@+ $< && \
+	$(MV) $@+ $@
diff --git a/Doc/asciidoc.conf b/Doc/asciidoc.conf
@@ -0,0 +1,36 @@
+[tags]
+bracket-emphasis={1?[{1}]}<emphasis>&lt;|&gt;</emphasis>
+
+[quotes]
+&lt;|&gt;=#bracket-emphasis
+
+[attributes]
+asterisk=&#42;
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+backslash=&#92;
+tilde=&#126;
+apostrophe=&#39;
+backtick=&#96;
+litdd=&#45;&#45;
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Shadowsocks-libev</refmiscinfo>
+<refmiscinfo class="version">{version}</refmiscinfo>
+<refmiscinfo class="manual">Shadowsocks-libev Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
diff --git a/Doc/manpage-base.xsl b/Doc/manpage-base.xsl
@@ -0,0 +1,35 @@
+<!-- manpage-base.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
+<!-- convert asciidoc callouts to man page format;
+     git.docbook.backslash and git.docbook.dot params
+     must be supplied by another XSL file or other means -->
+<xsl:template match="co">
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB(',
+			      substring-after(@id,'-'),')',
+			      $git.docbook.backslash,'fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>sp&#10;</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>&#10;</xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB',
+			      substring-after(@arearefs,'-'),
+			      '. ',$git.docbook.backslash,'fR')"/>
+	<xsl:apply-templates/>
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>br&#10;</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Doc/manpage-bold-literal.xsl b/Doc/manpage-bold-literal.xsl
@@ -0,0 +1,17 @@
+<!-- manpage-bold-literal.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- render literal text as bold (instead of plain or monospace);
+     this makes literal text easier to distinguish in manpages
+     viewed on a tty -->
+<xsl:template match="literal">
+	<xsl:value-of select="$git.docbook.backslash"/>
+	<xsl:text>fB</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:value-of select="$git.docbook.backslash"/>
+	<xsl:text>fR</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Doc/manpage-normal.xsl b/Doc/manpage-normal.xsl
@@ -0,0 +1,13 @@
+<!-- manpage-normal.xsl:
+     special settings for manpages rendered from asciidoc+docbook
+     handles anything we want to keep away from docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the normal values for the roff control characters -->
+<xsl:param name="git.docbook.backslash">\</xsl:param>
+<xsl:param name="git.docbook.dot"	>.</xsl:param>
+
+</xsl:stylesheet>