Documented the manpage output.

Author: matejak

ChangeLog

@@ -7,6 +7,7 @@ New features:
 * Allow scripts generated by argbash-init with complete separation (`-s -s`) to be run from a symbolic link.
 * Double quotes in help messages are escaped (fixes #61).
 * Introduced the `ARG_VERSION_AUTO` macro.
+* Enabled manpage output consumable by the `rst2man` utility.
 
 
 2.7.1 (2018-08-15)

doc/usage.rst

@@ -246,6 +246,8 @@ POSIX script                    posix-script                    none
 POSIX script parsing section    posix-script                    user-content
 Bash completion                 completion                      all
 docopt help message             docopt                          all
+manpage template                manpage                         all
+manpage template definitions    manpage-defs                    all
 ============================    =======================         ==========================
 
 
@@ -296,6 +298,7 @@ Typically, you generate bash completion ``my-script.sh`` from the generated scri
 
 and you move the created completion file ``my-script.sh`` to ``/etc/bash_completion.d/`` directory.
 
+
 .. _docopt_output:
 
 Docopt help message
@@ -315,6 +318,27 @@ Typically, you generate docopt output to the standard output from the generated
   $ argbash my-script --type docopt --strip all
 
 
+Manpage output
+++++++++++++++
+
+Argbash can generate source for the manual page for your script.
+There are two files in the process --- the template, and definitions.
+Those two files are in the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ format, and the template is supposed to be processed by the `rst2man <http://docutils.sourceforge.net/sandbox/manpage-writer/rst2man.txt>`_ utility.
+
+The manpage template is supposed to be generated as script's metadata change, definitions are required to be maintained manually, as they are supposed to contain content that is not present in the script.
+You can regenerate the template using the ``manpage`` output, while you are probably going to use the ``manpage-defs`` once to get you kickstarted and then continue to maintain it manually.
+
+So given a argbash-powered script or m4 file, your manpage workflow will typically look like this:
+
+.. code-block:: shell-session
+
+  $ argbash my-script --type manpage-defs --strip all -o my-script-defs.rst
+  $ argbash my-script --type manpage --strip all -o my-script.rst
+  $ vim my-script-defs.rst  # Edit the definitions file
+  $ rst2man my-script.rst > my-script.1
+  $ man ./my-script.1
+
+
 .. _api_change:
 
 API changes support

resources/Makefile

@@ -59,6 +59,7 @@ EXAMPLES = \
 	$(NUL)
 
 ROOT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+MANPAGE = argbash.1.gz
 
 $(GENPARSE): ../src/argbash.m4 $(M4_SRC)
 	ARGBASH_INTENDED_DESTINATION="$@" bash $(GENPARSE) $< -o argbash.temp && mv argbash.temp $@
@@ -146,7 +147,15 @@ define-version:
 	$(eval VERSION_MAJOR := $(shell cut -f 1 -d . ../src/version))
 	$(eval VERSION_SUFFIX := -$(VERSION_MAJOR).$(VERSION_MINOR).$(VERSION_PATCH))
 
-install: $(GENPARSE) $(A_INIT) $(ARGBASH_TO) $(COMPLETION)
+argbash.rst: ../src/argbash.m4 $(ARGBASH_EXEC)
+	$(ARGBASH_EXEC) --type manpage --strip all -o $@ $<
+
+man: $(MANPAGE)
+
+$(MANPAGE): argbash.rst argbash-defs.rst
+	rst2man $< | gzip > $@
+
+install: $(GENPARSE) $(A_INIT) $(ARGBASH_TO) $(COMPLETION) $(MANPAGE)
 	@echo Installing to prefix "'/$(PREFIX)' of root $(ROOT)"
 	mkdir -p "$(ROOT)/$(PREFIX)/bin"
 	touch "$(ROOT)/$(PREFIX)/bin/argbash$(VERSION_SUFFIX)"
@@ -158,6 +167,8 @@ install: $(GENPARSE) $(A_INIT) $(ARGBASH_TO) $(COMPLETION)
 	cp -p $(A_INIT) "$(ROOT)/$(PREFIX)/bin/argbash-init$(VERSION_SUFFIX)" && chmod a+x "$(ROOT)/$(PREFIX)"/bin/argbash-init$(VERSION_SUFFIX)
 	chmod a+x "$(ROOT)/$(PREFIX)/bin/argbash$(VERSION_SUFFIX)"
 	test "$(INSTALL_COMPLETION)" = "no" || (mkdir -p "$(ROOT)/$(BASH_COMPLETION_DIRECTORY)" && mv "$(COMPLETION)" "$(ROOT)/$(BASH_COMPLETION_DIRECTORY)/")
+	mkdir -p "$(ROOT)/$(PREFIX)/share/man/man1/"
+	cp -p $(MANPAGE) "$(ROOT)/$(PREFIX)/share/man/man1/"
 
 altpreclean: define-version
 	$(RM) "$(ROOT)/$(PREFIX)/bin/argbash-$(VERSION_MAJOR).$(VERSION_MINOR)"
@@ -176,6 +187,7 @@ uninstall:
 	$(RM) "$(ROOT)/$(PREFIX)"/bin/argbash-*
 	rmdir "$(ROOT)/$(PREFIXED_LIBDIR)/argbash$(VERSION_SUFFIX)"
 	$(RM) "$(ROOT)/$(BASH_COMPLETION_DIRECTORY)/$(COMPLETION)"
+	$(RM) "$(ROOT)/$(PREFIX)/share/man/man1/$(MANPAGE)"
 
 altuninstall: define-version uninstall
 
@@ -199,4 +211,4 @@ tag:
 
 # Update using
 # grep '^[-a-z]*:' Makefile | cut -f 1 -d ':' | sort | tr '\n' ' '
-.PHONY: altinstall altpreclean bootstrap check check-shellcheck define-version develop examples install release tag uninstall unittests version
+.PHONY: altinstall altpreclean bootstrap check check-shellcheck define-version develop examples install man release tag uninstall unittests version

resources/argbash-defs.rst

@@ -0,0 +1,34 @@
+
+.. |AUTHOR| replace:: Matěj Týč
+
+.. |MAN_SECTION| replace:: 1
+
+.. |DESCRIPTION| replace::
+   Argbash is a code generator that typically generates a bash argument-parsing library tailor-made for your script.
+   It lets you to describe arguments your script should take and then, you can generate the ``bash`` parsing code.
+   It stays in your script by default, but you can have it generated to a separate file and let ``bash`` to include it in your script for you.
+   ``Argbash`` is very simple to use and the generated code is relatively nice to read.
+   Moreover, argument definitions stay embedded in the script, so when you need to update the parsing logic, you just re-run the ``argbash`` script on the already generated script.
+
+.. |OPTION_OUTPUT| replace:: \
+
+.. |OPTION_TYPE| replace:: Check out the documentation to learn about all argbash capabilities that are supported.
+
+.. |OPTION_LIBRARY| replace:: This option is deprecated and it is the same as ``--strip user-content``.
+
+.. |OPTION_STRIP| replace::
+   You can either strip ``none``, which is useful for scripts.
+   If you strip ``user-content``, you keep the Argbash header.
+   If you strip ``all``, you will have only the generated content in the result.
+
+.. |OPTION_CHECK_TYPOS| replace:: \
+
+.. |OPTION_COMMENTED| replace:: \
+
+.. |OPTION_SEARCH| replace:: \
+
+.. |OPTION_DEBUG| replace:: \
+
+.. |OPTION_HELP| replace:: \
+
+.. |OPTION_VERSION| replace:: \

src/output-manpage-defs.m4

@@ -33,8 +33,10 @@ dnl $3: Padding of $2
 dnl $4: Help (optional)
 dnl $5: Default (optional)
 m4_define([_FORMAT_MANPAGE_OPTION], [m4_do(
+	[_POSSIBLY_REPEATED_COMMENT_BLOCK([option], [], 0,
+		m4_quote([..  You can have single-paragraph multi-line indented description instead of the '\']_ENDL_()))],
 	[_FORMAT_REPLACEMENT([OPTION_]m4_toupper(m4_translit([[$1]], [-], [_])),
-		[<Elaborate description], [of the option --$1], [or just leave there \ for no description]>.])],
+		[\])],
 	[_ENDL_()],
 )])
 
@@ -45,6 +47,8 @@ dnl $2: Program description
 dnl $3: Program description 2
 m4_define([MAKE_RST_CONTENT], [m4_do(
 	[_FORMAT_REPLACEMENT([AUTHOR], [<Your name goes here>])_ENDL_()],
+	[_FORMAT_REPLACEMENT([VERSION], [\])_ENDL_()],
+	[_FORMAT_REPLACEMENT([MAN_SECTION], [1])_ENDL_()],
 	[_FORMAT_REPLACEMENT([DESCRIPTION], [<More elaborate description], [goes here>.])_ENDL_()],
 	[MAKE_OPTIONS_SUMMARY([_FORMAT_MANPAGE_OPTION])],
 )])

src/output-manpage.m4

@@ -16,11 +16,12 @@ m4_define([ARGBASH_GO_BASE], [m4_do(
 
 dnl
 dnl $1: date
+dnl $2: program name
 m4_define([_MAKE_METADATA], [[
 :Author: |AUTHOR|
 :Date:   $1
-:Version: ]m4_ifdef([PROVIDED_VERSION_STRING], PROVIDED_VERSION_STRING, [[|VERSION|]])[
-:Manual section: 1
+:Version: ]m4_ifdef([PROVIDED_VERSION_STRING], m4_quote([$2 ]PROVIDED_VERSION_STRING), [[|VERSION|]])[
+:Manual section: |MAN_SECTION|
 ]])
 
 
@@ -56,7 +57,7 @@ m4_define([MAKE_RST_CONTENT], [m4_do(
 	[_ENDL_(2)],
 	[UNDERLINE([$2], -, -)],
 	[_ENDL_()],
-	[_MAKE_METADATA(__today__)],
+	[_MAKE_METADATA(__today__, [$1])],
 	[_ENDL_(2)],
 	[UNDERLINE([SYNOPSIS], =)],
 	[_ENDL_(2)],

src/utilities.m4

@@ -98,8 +98,8 @@ dnl Otherwise, act like _COMM_BLOCK
 m4_define([_POSSIBLY_REPEATED_COMMENT_BLOCK], [m4_ifndef([_COMMENT_$1_LOCATION], [m4_do(
 	[m4_define([_COMMENT_$1_LOCATION], [[$2]])],
 	[_COMM_BLOCK($3, m4_shiftn(3, $@))],
-)], [m4_do(
-	[_COMM_BLOCK([$3], m4_quote([# ]m4_indir([_COMMENT_$1_LOCATION])))],
+)], [m4_do(m4_ifblank([$2], ,
+		[_COMM_BLOCK([$3], m4_quote([# ]m4_indir([_COMMENT_$1_LOCATION])))]),
 )])])