Add man page (#1438)

`rbenv help` without arguments now runs `man rbenv` on systems where man is present.

.gitattributes

@@ -0,0 +1 @@
+/share/man/man[1-8]/*.[1-8] linguist-generated

Makefile

@@ -0,0 +1,4 @@
+release_version := $(shell git describe --tags)
+
+share/man/man1/rbenv.1: share/man/man1/rbenv.1.adoc
+	asciidoctor -b manpage -a version=$(release_version:v%=%) $<

libexec/rbenv-help

@@ -154,8 +154,11 @@ if [ "$1" = "--usage" ]; then
 fi
 
 if [ -z "$1" ] || [ "$1" == "rbenv" ]; then
+  if [ -z "$usage" ] && [ -t 1 ] && type -p man >/dev/null; then
+    MANPATH="${BASH_SOURCE%/*}/../share/man:$MANPATH" exec man rbenv
+  fi
   echo "Usage: rbenv <command> [<args>]"
-  [ -z "$usage" ] || exit
+  [ -n "$usage" ] && exit
   echo
   echo "Some useful rbenv commands are:"
   print_summaries commands local global shell install uninstall rehash version versions which whence

share/man/man1/rbenv.1

@@ -0,0 +1,163 @@
+'\" t
+.\"     Title: rbenv
+.\"    Author: Mislav Marohnić
+.\" Generator: Asciidoctor 2.0.17
+.\"      Date: 2022-09-26
+.\"    Manual: Rbenv Manual
+.\"    Source: rbenv 1.2.0-29-g7c7c4dc
+.\"  Language: English
+.\"
+.TH "RBENV" "1" "2022-09-26" "rbenv 1.2.0\-29\-g7c7c4dc" "Rbenv Manual"
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.ss \n[.ss] 0
+.nh
+.ad l
+.de URL
+\fI\\$2\fP <\\$1>\\$3
+..
+.als MTO URL
+.if \n[.g] \{\
+.  mso www.tmac
+.  am URL
+.    ad l
+.  .
+.  am MTO
+.    ad l
+.  .
+.  LINKSTYLE blue R < >
+.\}
+.SH "NAME"
+rbenv \- manage your application\*(Aqs Ruby environment
+.SH "SYNOPSIS"
+.sp
+\fBrbenv\fP \fI<command>\fP [\fI<args>\fP...]
+.SH "DESCRIPTION"
+.sp
+rbenv respects the \fI.ruby\-version\fP file in a project directory by making sure that any \fBruby\fP, \fBgem\fP, \fBbundle\fP, or other Ruby command invocation automatically invokes the Ruby version configured for that project.
+.sp
+It does so by generating shims for all Ruby executables. As long as rbenv shims directory is prepended to PATH, rbenv automatically ensures transparent switching between Ruby versions.
+.sp
+rbenv looks for available Ruby versions in the \fI{RBENV_ROOT}/versions/\fP directory.
+.SH "COMMANDS"
+.sp
+\fBrbenv global\fP [\fI<version>\fP]
+.RS 4
+View or change the global Ruby version
+.RE
+.sp
+\fBrbenv local\fP [\fI<version>\fP]
+.RS 4
+View or change the local Ruby version
+.RE
+.sp
+\fBrbenv shell\fP [\fI<version>\fP]
+.RS 4
+View or change the Ruby version for the current shell session
+.RE
+.sp
+\fBrbenv version\fP
+.RS 4
+View the currently active Ruby version and where it is set from
+.RE
+.sp
+\fBrbenv versions\fP
+.RS 4
+List all locally installed Ruby versions known to rbenv
+.RE
+.sp
+\fBrbenv install\fP [\fI<version>\fP]
+.RS 4
+(Provided by the \fBruby\-build\fP plugin) Download and install a new Ruby version
+.RE
+.sp
+\fBrbenv rehash\fP
+.RS 4
+Regenerate shims for all known Ruby executables
+.RE
+.sp
+\fBrbenv which\fP [\fI<command>\fP]
+.RS 4
+View the executable path that a command resolves to
+.RE
+.sp
+\fBrbenv init\fP
+.RS 4
+Help bootstrap rbenv into the current shell environment
+.RE
+.sp
+\fBrbenv help\fP [\fI<command>\fP]
+.RS 4
+View help text for any rbenv command
+.RE
+.SH "ENVIRONMENT VARIABLES"
+.sp
+\fBRBENV_VERSION\fP (default: read from \fI.ruby\-version\fP file)
+.RS 4
+The Ruby version name to be used
+.RE
+.sp
+\fBRBENV_ROOT\fP (default: \fI~/.rbenv\fP)
+.RS 4
+The location where rbenv discovers Ruby versions, plugins, and other configuration
+.RE
+.sp
+\fBRBENV_DEBUG\fP
+.RS 4
+Activates printing debug information about rbenv internals to standard error
+.RE
+.sp
+\fBRBENV_HOOK_PATH\fP
+.RS 4
+Colon\-separated list of paths searched for rbenv plugin scripts
+.RE
+.sp
+\fBRBENV_DIR\fP (default: \fI{PWD}\fP)
+.RS 4
+Directory to traverse bottom\-up to locate the \fI.ruby\-version\fP file
+.RE
+.SH "PLUGINS"
+.sp
+rbenv only performs Ruby version switching as its core functionality, but offers a plugin mechanism to hook into and override almost any aspect of its functionality.
+.sp
+The most common plugin for rbenv is \fBruby\-build\fP which facilitates installing new Ruby versions into the \fI{RBENV_ROOT}/versions/\fP directory.
+.sp
+Read more at \c
+.URL "https://github.com/rbenv/rbenv/wiki/Plugins" "" ""
+.SH "NOTES"
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+.URL "https://github.com/rbenv/rbenv/discussions" "" ""
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+.URL "https://github.com/rbenv/rbenv/wiki" "" ""
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.  sp -1
+.  IP \(bu 2.3
+.\}
+.URL "https://github.com/rbenv/ruby\-build#readme" "" ""
+.RE
+.SH "AUTHOR"
+.sp
+Mislav Marohnić

share/man/man1/rbenv.1.adoc

@@ -0,0 +1,87 @@
+= rbenv(1)
+Mislav Marohnić
+:doctype: manpage
+:man manual: Rbenv Manual
+:man source: rbenv {version}
+:man-linkstyle: pass:[blue R < >]
+
+== Name
+
+rbenv - manage your application's Ruby environment
+
+== Synopsis
+
+*rbenv* _<command>_ [_<args>_...]
+
+== Description
+
+rbenv respects the _.ruby-version_ file in a project directory by making sure that any *ruby*, *gem*, *bundle*, or other Ruby command invocation automatically invokes the Ruby version configured for that project.
+
+It does so by generating shims for all Ruby executables. As long as rbenv shims directory is prepended to PATH, rbenv automatically ensures transparent switching between Ruby versions.
+
+rbenv looks for available Ruby versions in the _{RBENV_ROOT}/versions/_ directory.
+
+== Commands
+
+*rbenv global* [_<version>_]::
+  View or change the global Ruby version
+
+*rbenv local* [_<version>_]::
+  View or change the local Ruby version
+
+*rbenv shell* [_<version>_]::
+  View or change the Ruby version for the current shell session
+
+*rbenv version*::
+  View the currently active Ruby version and where it is set from
+
+*rbenv versions*::
+  List all locally installed Ruby versions known to rbenv
+
+*rbenv install* [_<version>_]::
+  (Provided by the *ruby-build* plugin) Download and install a new Ruby version
+
+*rbenv rehash*::
+  Regenerate shims for all known Ruby executables
+
+*rbenv which* [_<command>_]::
+  View the executable path that a command resolves to
+
+*rbenv init*::
+  Help bootstrap rbenv into the current shell environment
+
+*rbenv help* [_<command>_]::
+  View help text for any rbenv command
+
+== Environment Variables
+
+*RBENV_VERSION* (default: read from _.ruby-version_ file)::
+  The Ruby version name to be used
+
+*RBENV_ROOT* (default: _~/.rbenv_)::
+  The location where rbenv discovers Ruby versions, plugins, and other configuration
+
+*RBENV_DEBUG*::
+  Activates printing debug information about rbenv internals to standard error
+
+*RBENV_HOOK_PATH*::
+  Colon-separated list of paths searched for rbenv plugin scripts
+
+*RBENV_DIR* (default: _{PWD}_)::
+  Directory to traverse bottom-up to locate the _.ruby-version_ file
+
+== Plugins
+
+rbenv only performs Ruby version switching as its core functionality, but offers a plugin mechanism to hook into and override almost any aspect of its functionality.
+
+The most common plugin for rbenv is *ruby-build* which facilitates installing new Ruby versions into the _{RBENV_ROOT}/versions/_ directory.
+
+Read more at https://github.com/rbenv/rbenv/wiki/Plugins
+
+== Notes
+
+* https://github.com/rbenv/rbenv/discussions
+
+* https://github.com/rbenv/rbenv/wiki
+
+* https://github.com/rbenv/ruby-build#readme

test/help.bats

@@ -9,6 +9,12 @@ load test_helper
   assert_line "Some useful rbenv commands are:"
 }
 
+@test "usage flag" {
+  run rbenv-help --usage
+  assert_success
+  assert_output "Usage: rbenv <command> [<args>]"
+}
+
 @test "invalid command" {
   run rbenv-help hello
   assert_failure "rbenv: no such command \`hello'"