add UNIX manual pages for all scripts using binman

.gitignore

@@ -0,0 +1,2 @@
+!/man/man?/*.?
+/man

README.md

@@ -1,3 +1,7 @@
+* Code: <https://github.com/sunaku/dasht>
+* Docs: <https://sunaku.github.io/dasht/man>
+* Bugs: <https://github.com/sunaku/dasht/issues>
+
 # dasht - API documentation in your terminal
 
 dasht is a collection of shell scripts for searching, browsing, and managing
@@ -45,6 +49,14 @@ Optional:
 * [socat] for dasht-server(1) search engine
   [socat]: http://www.dest-unreach.org/socat/
 
+Development:
+
+* [binman] and [md2man] to build manual pages
+  [binman]: https://sunaku.github.io/binman/
+  [md2man]: https://sunaku.github.io/md2man/
+
+        gem install binman md2man
+
 ## Installation
 
 1.  Clone or [download] this Git repository onto your system.
@@ -68,148 +80,35 @@ If unspecified, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`, or
 
 ## Usage
 
-First, install some [docsets]:
+### Tutorial
+
+First, install some [docsets] using dasht-docsets-install(1):
 
     dasht-docsets-install bash
 
-Next, perform a direct search:
+Next, perform a direct search from the terminal using dasht(1):
 
     dasht 'c - x'
 
-Then, repeat in a web browser:
+Then, repeat the search in a web browser using dasht-server(1):
 
     dasht-server
 
-Done! You are now ready to go.
-
-### dasht(1)
-
-Displays dasht-query-html(1) results, if any, using the w3m(1) browser.
-
-### dasht-query-html(1)
-
-Decorates dasht-query-line(1) results as HTML table rows.
-
-### dasht-query-line(1)
-
-    Usage: dasht-query-line [PATTERN] [DOCSET...]
-
-Searches for the given PATTERN in [Dash] docsets whose names loosely match the
-given DOCSETs (or in all installed [Dash] docsets if no DOCSETs are specified)
-and then prints the results in groups of four lines, in the following order:
-
-    name = VALUE    # value of the token that matched the PATTERN
-    type = VALUE    # type of the token, as defined in the docset
-    from = VALUE    # name of the docset this result was found in
-    url = VALUE     # URL of the API documentation for this result
-
-Whitespace characters in the PATTERN are treated as wildcards, whereas the
-SQL LIKE wildcard characters `%` and `_` are not: they are taken literally.
-
-The given PATTERN is surrounded by whitespace wildcards before searching so
-that it can match anywhere: beginning, middle, or end.  If unspecified, its
-value is assumed to be a whitespace wildcard so that it matches everything.
-
-### dasht-query-exec(1)
-
-    Usage: dasht-query-exec PATTERN DATABASE [OPTIONS_FOR_SQLITE3...]
-
-Searches for the given PATTERN in the given [Dash] docset DATABASE.
-
-SQL LIKE wildcard characters in PATTERN are backslash escapable.
-For example, `\%` and `\_` are escaped, but `%` and `_` are not.
-
-Any specified OPTIONS\_FOR\_SQLITE3 are passed down to sqlite3(1).
-
-### dasht-server(1)
-
-    Usage: dasht-server [PORT]
-
-Runs a local search engine on the given PORT at http://127.0.0.1:PORT
-which is intended to be accessed by web browsers on the same machine.
-
-If no PORT number is specified, then its value is assumed to be 54321.
-
-The search engine's URL is printed to stdout for the user's reference.
-You can use this to launch a web browser along with the search engine:
-
-    dasht-server | xargs -n1 w3m
-
-#### Browser refuses to load `file://` links
-
-Some web browsers refuse to load `file://` links from `http://127.0.0.1` URLs.
-However, the following web browsers do not suffer from this limitation and are
-thereby recommended for use with the search engine powered by dasht-server(1).
-
-Recommended terminal web browsers:
-
-* [w3m]
-
-* [elinks]
-  [elinks]: http://elinks.or.cz
-
-* [lynx]
-  [lynx]: http://lynx.invisible-island.net
-
-Recommended graphical web browsers:
-
-* [Dillo]
-  [Dillo]: http://www.dillo.org
-
-* [NetSurf]
-  [NetSurf]: http://www.netsurf-browser.org
-
-* [Firefox] needs a workaround (see below)
-  [Firefox]: http://www.mozilla.org/firefox
-
-##### Firefox
-
-The workaround for Firefox is to add this snippet to your `prefs.js` file:
-
-    user_pref("capability.policy.policynames", "localfilelinks");
-    user_pref("capability.policy.localfilelinks.sites", "http://127.0.0.1:54321");
-    user_pref("capability.policy.localfilelinks.checkloaduri.enabled", "allAccess");
-
-See <http://kb.mozillazine.org/Links_to_local_pages_do_not_work> for details.
-
-### dasht-server-http(1)
-
-Reads a single HTTP request from stdin and writes a response to stdout.
-
-### dasht-docsets(1)
-
-    Usage: dasht-docsets [NAME...]
-
-Lists the names of [Dash] docsets installed in `$DASHT_DOCSETS_DIR`.
-
-If any NAMEs are specified, the list is filtered to include
-only those docsets whose names loosely match the given NAMEs.
-
-### dasht-docsets-install(1)
-
-    Usage: dasht-docsets-install [NAME...]
-
-Installs available [Dash] docsets whose names loosely match the given NAMEs.
-You are asked to confirm this destructive operation for every such match.
-
-If no NAMEs are specified, all available docsets are selected for install.
-
-### dasht-docsets-update(1)
-
-    Usage: dasht-docsets-update [NAME...]
+You are now ready to use dasht!  Read the manuals below to learn even more.
 
-Updates installed [Dash] docsets whose names loosely match the given NAMEs.
+### Manuals
 
-If no NAMEs are specified, all available docsets are selected for update.
+* You can browse the manuals online at <https://sunaku.github.io/dasht/man/>.
 
-### dasht-docsets-remove(1)
+* If you installed dasht from your system's package manager, run `man dasht`.
 
-    Usage: dasht-docsets-remove [NAME...]
+* Else, run `man -M location_where_you_cloned_or_downloaded_dasht/man dasht`.
 
-Removes installed [Dash] docsets whose names loosely match the given NAMEs.
-You are asked to confirm this destructive operation for every such match.
+## Development
 
-If no NAMEs are specified, all installed docsets are selected for removal.
+If you make changes to the embedded manual pages found in the comment headers
+at the top of script files in the `bin/` directory, then remember to run the
+`binman-rake` command afterward to regenerate UNIX manual pages for packaging.
 
 ## License
 

bin/dasht

@@ -1,6 +1,59 @@
 #!/bin/sh -e
 #
-# Displays dasht-query-html(1) results, if any, using the w3m(1) browser.
+# # DASHT 1                       2016-01-24                            1.0.0
+#
+# ## NAME
+#
+# dasht - API documentation in your terminal
+#
+# ## SYNOPSIS
+#
+# `dasht` [*PATTERN*] [*DOCSET*]...
+#
+# ### Examples
+#
+# `dasht`
+#   First 100 topics from each installed docset.
+#
+# `dasht` 'c - x'
+#   Search for "c - x" in all installed docsets.
+#
+# `dasht` 'c - x' bash
+#   Search for "c - x" only in the "bash" docset.
+#
+# `dasht` 'c - x' bash css
+#   Search for "c - x" only in the "bash" and "css" docsets.
+#
+# ## DESCRIPTION
+#
+# Searches for *PATTERN* in all installed [Dash] docsets, optionally searching
+# only in those whose names match *DOCSET*s, by calling dasht-query-html(1).
+# The results, if any, are then displayed in the w3m(1) terminal web browser,
+# which terminates when you press the `q` key, just as typical UNIX pagers do.
+#
+# ### Searching
+#
+# Whitespace characters in *PATTERN* are treated as wildcards, whereas the
+# SQL LIKE wildcard characters `%` and `_` are not: they are taken literally.
+#
+# Before searching, *PATTERN* is surrounded by whitespace wildcards so that it
+# can match anywhere: beginning, middle, or end.  As a result, if *PATTERN* is
+# undefined, it becomes a whitespace wildcard and thereby matches everything.
+#
+# ## ENVIRONMENT
+#
+# `DASHT_DOCSETS_DIR`
+#   Defines the filesystem location where your [Dash] docsets are installed.
+#   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
+#   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
+#
+# ## SEE ALSO
+#
+# w3m(1), dasht-query-html(1), dasht-docsets(1), [Dash]
+#
+# [Dash]: https://kapeli.com/dash
+#
+# ## AUTHOR
 #
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (see the LICENSE file).

bin/dasht-docsets

@@ -1,11 +1,47 @@
 #!/bin/sh -e
 #
-# Usage: dasht-docsets [NAME...]
+# # DASHT-DOCSETS 1               2016-01-24                            1.0.0
 #
-# Lists the names of Dash docsets installed in $DASHT_DOCSETS_DIR.
+# ## NAME
 #
-# If any NAMEs are specified, the list is filtered to include
-# only those docsets whose names loosely match the given NAMEs.
+# dasht-docsets - lists installed [Dash] docsets
+#
+# ## SYNOPSIS
+#
+# `dasht-docsets` [*NAME*...]
+#
+# ### Examples
+#
+# `dasht-docsets`
+#   Lists all installed [Dash] docsets.
+#
+# `dasht-docsets` sh
+#   Lists installed [Dash] docsets whose names contain "sh".
+#
+# `dasht-docsets` sh 'c$'
+#   Lists installed [Dash] docsets whose names contain "sh" or end in "c".
+#
+# ## DESCRIPTION
+#
+# Lists the names of [Dash] docsets installed under `DASHT_DOCSETS_DIR`.  The
+# listing is optionally filtered to include only those docset names that match
+# the *NAME* regex(7) patterns, if specified, before it is printed to stdout.
+#
+# ## ENVIRONMENT
+#
+# `DASHT_DOCSETS_DIR`
+#   Defines the filesystem location where your [Dash] docsets are installed.
+#   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
+#   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
+#
+# ## SEE ALSO
+#
+# dasht-docsets-install(1), dasht-docsets-update(1), dasht-docsets-remove(1),
+# dasht(1), [Dash]
+#
+# [Dash]: https://kapeli.com/dash
+#
+# ## AUTHOR
 #
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (see the LICENSE file).

bin/dasht-docsets-install

@@ -1,11 +1,46 @@
 #!/bin/sh -e
 #
-# Usage: dasht-docsets-install [NAME...]
+# # DASHT-DOCSETS-INSTALL 1       2016-01-24                            1.0.0
 #
-# Installs available Dash docsets whose names loosely match the given NAMEs.
-# You are asked to confirm this destructive operation for every such match.
+# ## NAME
 #
-# If no NAMEs are specified, all available docsets are selected for install.
+# dasht-docsets-install - installs new [Dash] docsets
+#
+# ## SYNOPSIS
+#
+# `dasht-docsets-install` [*NAME*...]
+#
+# ### Examples
+#
+# `dasht-docsets-install`
+#   Installs all new [Dash] docsets currently available.
+#
+# `dasht-docsets-install` sh
+#   Installs new [Dash] docsets whose names contain "sh".
+#
+# `dasht-docsets-install` sh 'c$'
+#   Installs new [Dash] docsets whose names contain "sh" or end in "c".
+#
+# ## DESCRIPTION
+#
+# Installs new [Dash] docsets whose names match the *NAME* regex(7) patterns.
+# If no *NAME*s are given, all new docsets currently available are matched.
+# You are prompted to confirm this destructive operation for each match.
+#
+# ## ENVIRONMENT
+#
+# `DASHT_DOCSETS_DIR`
+#   Defines the filesystem location where your [Dash] docsets are installed.
+#   If undefined, its value is assumed to be `$XDG_DATA_HOME/dasht/docsets/`
+#   or, if `XDG_DATA_HOME` is undefined, `$HOME/.local/share/dasht/docsets/`.
+#
+# ## SEE ALSO
+#
+# dasht-docsets-update(1), dasht-docsets-remove(1), dasht-docsets(1), [Dash]
+#
+# [Dash]: https://kapeli.com/dash
+#
+# ## AUTHOR
 #
 # Written in 2016 by Suraj N. Kurapati <https://github.com/sunaku/dasht>
 # Distributed under the terms of the ISC license (see the LICENSE file).