binman 5.0.1 → 5.1.0

data/VERSION.markdown

@@ -1,3 +1,37 @@
+## Version 5.1.0 (2016-02-28)
+
+This release splits binman(1) into pieces and improves the documentation.
+
+### Minor:
+
+  * binman(1) is now deprecated, to be removed in the next major version.
+    Please run the new binman-* programs, listed below, directly instead.
+
+  * Split binman(1) commands into independent programs:
+
+      * binman-help(1) - add help options to your program
+      * binman-html(1) - HTML manpage from header comment
+      * binman-rake(1) - run rake(1) tasks from command line
+      * binman-roff(1) - UNIX manpage from header comment
+      * binman-show(1) - show manpage from header comment
+      * binman-text(1) - extract embedded manpage sources
+
+  * binman-rake(1): allow task names without namespace.
+
+    You can now run `binman-rake man` instead of `binman-rake binman:man`,
+    and similarly `binman-rake web` instead of `binman-rake binman:web`,
+    and similarly `binman-rake mkd` instead of `binman-rake binman:mkd`.
+
+### Patch:
+
+  * README: an epic revision; add copy of md2man(5).
+
+  * README: add dasht manual pages to examples section.
+
+  * Clarify optionalness of *PATTERN* in `--help` option.
+
+  * Upgrade to md2man version 5.1.
+
 ## Version 5.0.1 (2016-02-13)
 
 ### Major:
@@ -19,14 +53,6 @@
 
 ## Version 4.2.1 (2016-02-12)
 
-### Patch:
-
-  * Failure when `binman show` is given input on STDIN.
-
-    binman.rb:51:in `basename': no implicit conversion of IO into String (TypeError)
-
-## Version 4.2.0 (2016-02-12)
-
 ### Minor:
 
   * Add `binman:mkd` rake task to extract `man/man1/*.1.markdown` files.
@@ -49,6 +75,12 @@
 
     binman.rb:47:in `basename': no implicit conversion of IO into String (TypeError)
 
+  * Failure when `binman show` is given input on STDIN.
+
+    binman.rb:51:in `basename': no implicit conversion of IO into String (TypeError)
+
+### Patch:
+
 ## Version 4.1.0 (2016-02-10)
 
 ### Minor:

data/bin/binman

@@ -1,11 +1,11 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# BINMAN 1 2016-02-13 5.0.1
+# BINMAN 1                        2016-02-28                            5.1.0
 
 ## NAME
 
-binman - man pages for bin scripts
+binman - deprecated; use binman-* instead
 
 ## SYNOPSIS
 
@@ -13,90 +13,36 @@ binman - man pages for bin scripts
 
 ## DESCRIPTION
 
-[binman] produces UNIX manual pages for your executable scripts. It can
-extract their leading comment headers (defined below), convert them from
-markdown(7) into roff(7) using [md2man], and display them using man(1).
+Runs the fellow "`binman`-*COMMAND*" programs listed under "Commands" below.
 
-### Leading comment headers
-
-A leading comment header can be one of the following two things:
-
-1.  A contiguous sequence of single-line comments (which begin with `#`
-    and optionally continue with a single space followed by any number of
-    characters until the end of the line) starting at the beginning of the
-    file (after shebang and encoding comments plus optional blank lines) and
-    ending at the first single blank line.
-
-2.  The first embedded document delimited by `=begin` and `=end` lines, which
-    begin with the respective delimiters and optionally continue with a single
-    space followed by any number of characters until the end of the line.
-
-### Markdown processing divergence
-
-Although your leading comment headers are written in markdown(7), `binman
-conv` inherits the following additions to markdown(7) syntax from md2man(5):
-
-  * There can be at most one top-level heading (H1).  It is emitted as `.TH`
-    in the roff(7) output to define the UNIX manual page's header and footer.
-
-  * Paragraphs whose lines are all uniformly indented by two spaces are
-    considered to be "indented paragraphs".  They are unindented accordingly
-    before emission as `.IP` in the roff(7) output.
-
-  * Paragraphs whose subsequent lines (all except the first) are uniformly
-    indented by two spaces are considered to be a "tagged paragraphs".  They
-    are unindented accordingly before emission as `.TP` in the roff(7) output.
-
-### Markdown processing extensions
-
-The following [Redcarpet] extensions are enabled while processing markdown(7):
-
-  * tables
-  * autolink
-  * superscript
-  * strikethrough
-  * fenced\_code\_blocks
+> Note: This program is deprecated for removal in the next major version. To
+> prepare yourself, please run the fellow binman-* programs directly instead.
 
 ## OPTIONS
 
 `-h` [*PATTERN*], `--help` [*PATTERN*]
-  Show this help manual and search for *PATTERN* regular expression therein.
+  Show this help manual and optionally search for *PATTERN* regular expression.
 
 ## COMMANDS
 
-`text` [*FILE*]
-  Print the leading comment header extracted from the given *FILE* or STDIN.
+`text` ...
+  Runs binman-text(1).
 
-`roff` [*FILE*]
-  Print the roff(7) conversion of the leading comment header extracted from
-  the given *FILE* or STDIN.
+`roff` ...
+  Runs binman-roff(1).
 
-`html` [*FILE*]
-  Print the HTML conversion of the leading comment header extracted from
-  the given *FILE* or STDIN.
+`html` ...
+  Runs binman-html(1).
 
-`show` [*FILE*] [*PATTERN*]
-  Use man(1) to display the roff(7) conversion of the leading comment header
-  extracted from the given *FILE* or STDIN.  If *PATTERN* is given, search for
-  it within the output displayed by man(1) and jump to first match if found.
-  If man(1) cannot display the roff(1) conversion, fall back to the showing
-  the HTML conversion; if that fails too, display the extracted text as-is.
+`show` ...
+  Runs binman-show(1).
 
-`help` *FILE* ... [`-h`|`--help` [*PATTERN*]] ... [`--`] ...
-  If the given argument sequence contains `-h` or `--help`, except after
-  `--`, optionally followed by a *PATTERN* regular expression that specifies
-  text to search for and, if found, jump to inside the displayed man page,
-  then this program extracts the given *FILE*'s leading comment header,
-  converts it into roff(7), displays it using man(1), and finally exits with
-  status code `0`.  Otherwise, this program exits with status code `111`.
+`help` ...
+  Runs binman-help(1).
 
 ## SEE ALSO
 
-binman-rake(1), man(1), roff(7), markdown(7)
-
-[binman]: https://github.com/sunaku/binman
-[md2man]: https://github.com/sunaku/md2man
-[Redcarpet]: https://github.com/vmg/redcarpet
+binman-rake(1)
 
 =end =========================================================================
 

data/bin/binman-help

@@ -0,0 +1,208 @@
+#!/usr/bin/env ruby
+#
+# # BINMAN-HELP 1                 2016-02-28                            5.1.0
+#
+# ## NAME
+#
+# binman-help - add help options to your program
+#
+# ## SYNOPSIS
+#
+# `binman-help` *FILE* ... [`-h`|`--help` [*PATTERN*]] ... [`--`] ...
+#
+# ## DESCRIPTION
+#
+# If the given argument sequence contains `-h` or `--help`, except after `--`,
+# then this program displays the given *FILE*'s "embedded manpage source",
+# described in binman-text(1), and then terminates with exit status `0`.
+# Otherwise, this program terminates with the nonzero exit status `111`.
+#
+# ### Examples
+#
+# See "Embedded manpage sources" in binman-text(1) for header comment syntax.
+#
+# #### From a shell script
+#
+# ```sh
+# #!/usr/bin/sh
+# # your program's manual page goes here
+#
+# binman-help "$0" "$@" && exit
+# ```
+#
+# #### From a Ruby script
+#
+# ```ruby
+# #!/usr/bin/env ruby
+# # your program's manual page goes here
+#
+# require 'binman'
+# BinMan.help
+# ```
+#
+# You can also specify your program's source file encoding above the manual:
+#
+# ```ruby
+# #!/usr/bin/env ruby
+# # -*- coding: utf-8 -*-
+# # your program's manual page goes here
+# ```
+#
+# You can also write the manual as a multi-line Ruby comment:
+#
+# ```ruby
+# #!/usr/bin/env ruby
+# =begin
+# your program's manual page goes here
+# =end
+# ```
+#
+# You can also specify your program's source file encoding above the manual:
+#
+# ```ruby
+# #!/usr/bin/env ruby
+# # -*- coding: utf-8 -*-
+# =begin
+# your program's manual page goes here
+# =end
+# ```
+#
+# #### From a Perl script
+#
+# ```perl
+# #!/usr/bin/env perl
+# # your program's manual page goes here
+#
+# system('binman-help', __FILE__, @ARGV) == 0 and exit;
+# ```
+#
+# You can also write the manual as a multi-line Ruby comment after `__END__`:
+#
+# ```perl
+# #!/usr/bin/env perl
+# print "your program's code goes here";
+# __END__
+# =begin
+# your program's manual page goes here
+# =end
+# ```
+#
+# #### From a Python script
+#
+# ```python
+# #!/usr/bin/env python
+# # your program's manual page goes here
+#
+# import sys, subprocess
+#
+# subprocess.call(['binman-help', __file__] + sys.argv) == 0 and sys.exit()
+# ```
+#
+# You can also specify your program's source file encoding above the manual:
+#
+# ```python
+# #!/usr/bin/env python
+# # -*- coding: utf-8 -*-
+# # your program's manual page goes here
+# ```
+#
+# You can also write the manual as a multi-line Ruby comment inside a docstring:
+#
+# ```python
+# #!/usr/bin/env python
+# """
+# =begin
+# your program's manual page goes here
+# =end
+# """
+# ```
+#
+# You can also specify your program's source file encoding above the manual:
+#
+# ```python
+# #!/usr/bin/env python
+# # -*- coding: utf-8 -*-
+# """
+# =begin
+# your program's manual page goes here
+# =end
+# """
+# ```
+#
+# #### From an AWK script
+#
+# The technique for determining current AWK script file name [comes from here](
+# http://www.mombu.com/programming/programming/t-the-name-of-script-itself-2040784-print.html
+# ).
+#
+# ```awk
+# #!/usr/bin/awk -f
+# # your program's manual page goes here
+#
+# BEGIN {getline c <"/proc/self/cmdline"; sub(".*-f\0"," ",c); gsub("\0"," ",c);
+#        if(system("binman-help" c) == 0){ exit }}
+# ```
+#
+# #### From a Tcl script
+#
+# ```tcl
+# #!/usr/bin/env tclsh
+# # your program's manual page goes here
+#
+# if {![catch {exec -- >/dev/tty binman-help $argv0 {*}$argv}]} {exit}
+# ```
+#
+# You can also write the manual as a multi-line Ruby comment inside an `if 0`:
+#
+# ```tcl
+# #!/usr/bin/env tclsh
+# if 0 {
+# =begin
+# your program's manual page goes here
+# =end
+# }
+# ```
+#
+# #### From a Node.js script
+#
+# ```javascript
+# /*
+# =begin
+# your program's manual page goes here
+# =end
+# */
+#
+# var exec = require('child_process').exec;
+# exec(['>/dev/tty', 'binman-help', __filename].concat(process.argv).
+# join(' '), function(error){ if (error === null){ process.exit(); } });
+# ```
+#
+# ## OPTIONS
+#
+# `-h` [*PATTERN*], `--help` [*PATTERN*]
+#   Display manpage and optionally search for *PATTERN* regular expression.
+#
+# ## EXIT STATUS
+#
+# 0
+#   Arguments contained help options so manpage was displayed.
+#
+# 111
+#   Arguments lacked help options so manpage was not displayed.
+#
+# ## SEE ALSO
+#
+# binman-text(1), binman-roff(1), binman-html(1), binman-show(1), binman(1)
+#
+
+require 'binman'
+
+# display requested manpage
+file, *args = ARGV
+BinMan.help file, args
+
+# fallback to this manpage
+BinMan.help
+
+# no manpage was displayed
+exit 111

data/bin/binman-html

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# BINMAN-HTML 1                   2016-02-28                            5.1.0
+
+## NAME
+
+binman-html - HTML manpage from header comment
+
+## SYNOPSIS
+
+`binman-html` [*OPTION*]... [*FILE*]
+
+
+## DESCRIPTION
+
+Extracts the "embedded manpage source", described in binman-text(1), from the
+given *FILE* or STDIN and transforms it into HTML for use in a web browser.
+
+## SEE ALSO
+
+binman-text(1), binman-roff(1), binman(1)
+
+=end =========================================================================
+
+require 'binman'
+BinMan.help
+puts BinMan.html(ARGF)

data/bin/binman-rake

@@ -1,11 +1,11 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# BINMAN-RAKE 1 2016-02-13 5.0.1
+# BINMAN-RAKE 1                   2016-02-28                            5.1.0
 
 ## NAME
 
-binman-rake - run rake(1) tasks from binman(1)
+binman-rake - run rake(1) tasks from command line
 
 ## SYNOPSIS
 
@@ -23,20 +23,20 @@ If no *TASK* is specified, then the `binman` task is run by default.
 ## TASKS
 
 `binman`
-  Runs the `binman:man` and `binman:web` tasks, in that order.
+  Runs the `binman:mkd`, `binman:man`, and `binman:web` tasks, in that order.
 
-`binman:mkd`
+`binman:mkd` or `mkd`
   Extracts manual page sources embedded in scripts found in your `bin/`
   directory and saves them as `man/man1/*.1.markdown` files, which can
   then be rendered as HTML or UNIX manual pages using md2man-rake(1).
 
-`binman:man`
+`binman:man` or `man`
   Builds UNIX manual pages from scripts found in your `bin/` directory.
   It also runs the `md2man:man` task, provided by md2man-rake(1), which
   builds UNIX manual pages from `*.markdown`, `*.mkd`, and `*.md` files
   found in or beneath the `man/` subdirectory in your working directory.
 
-`binman:web`
+`binman:web` or `web`
   Builds HTML manual pages from scripts found in your `bin/` directory.
   It also runs the `md2man:web` task, provided by md2man-rake(1), which
   builds HTML manual pages from `*.markdown`, `*.mkd`, and `*.md` files
@@ -44,8 +44,8 @@ If no *TASK* is specified, then the `binman` task is run by default.
 
 ## OPTIONS
 
-`-h` [*REGEXP*], `--help` [*REGEXP*]
-  Show this help manual and search for *REGEXP* regular expression therein.
+`-h` [*PATTERN*], `--help` [*PATTERN*]
+  Show this help manual and optionally search for *PATTERN* regular expression.
 
 ...
   Anything else is passed to rake(1); run `rake --help` for documentation.
@@ -64,5 +64,8 @@ Rake.application.init File.basename(__FILE__)
 
 require 'binman/rakefile'
 task :default => :binman
+task :mkd => 'binman:mkd'
+task :man => 'binman:man'
+task :web => 'binman:web'
 
 Rake.application.top_level