From 22ee5d41758dee08a679bf49a74456847b6f9f72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Tue, 27 Sep 2022 02:17:50 +0200 Subject: [PATCH] Add man page (#1438) `rbenv help` without arguments now runs `man rbenv` on systems where man is present. --- .gitattributes | 1 + Makefile | 4 + libexec/rbenv-help | 5 +- share/man/man1/rbenv.1 | 163 ++++++++++++++++++++++++++++++++++++ share/man/man1/rbenv.1.adoc | 87 +++++++++++++++++++ test/help.bats | 6 ++ 6 files changed, 265 insertions(+), 1 deletion(-) create mode 100644 .gitattributes create mode 100644 Makefile create mode 100644 share/man/man1/rbenv.1 create mode 100644 share/man/man1/rbenv.1.adoc diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..c2a1783 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +/share/man/man[1-8]/*.[1-8] linguist-generated diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..8cd8a0f --- /dev/null +++ b/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%=%) $< diff --git a/libexec/rbenv-help b/libexec/rbenv-help index fefbaab..e7a45df 100755 --- a/libexec/rbenv-help +++ b/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 []" - [ -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 diff --git a/share/man/man1/rbenv.1 b/share/man/man1/rbenv.1 new file mode 100644 index 0000000..5ee1091 --- /dev/null +++ b/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\fP [\fI\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\fP] +.RS 4 +View or change the global Ruby version +.RE +.sp +\fBrbenv local\fP [\fI\fP] +.RS 4 +View or change the local Ruby version +.RE +.sp +\fBrbenv shell\fP [\fI\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\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\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\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ć \ No newline at end of file diff --git a/share/man/man1/rbenv.1.adoc b/share/man/man1/rbenv.1.adoc new file mode 100644 index 0000000..97af50f --- /dev/null +++ b/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* __ [__...] + +== 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* [__]:: + View or change the global Ruby version + +*rbenv local* [__]:: + View or change the local Ruby version + +*rbenv shell* [__]:: + 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* [__]:: + (Provided by the *ruby-build* plugin) Download and install a new Ruby version + +*rbenv rehash*:: + Regenerate shims for all known Ruby executables + +*rbenv which* [__]:: + View the executable path that a command resolves to + +*rbenv init*:: + Help bootstrap rbenv into the current shell environment + +*rbenv help* [__]:: + 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 diff --git a/test/help.bats b/test/help.bats index 9862d63..fddaafc 100644 --- a/test/help.bats +++ b/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 []" +} + @test "invalid command" { run rbenv-help hello assert_failure "rbenv: no such command \`hello'"