Merge pull request #2297 from rbenv/man-page

Add ruby-build(1) man page

.gitattributes

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

Makefile

@@ -0,0 +1,8 @@
+release_version := $(shell grep "^RUBY_BUILD_VERSION" bin/ruby-build | cut -d\" -f2)
+
+.PHONY: install
+install:
+	bash install.sh
+
+share/man/man1/%.1: share/man/man1/%.1.adoc bin/ruby-build
+	asciidoctor -b manpage -a version=$(release_version:v%=%) -o $@ $<

bin/rbenv-install

@@ -2,27 +2,27 @@
 #
 # Summary: Install a Ruby version using ruby-build
 #
-# Usage: rbenv install [-f|-s] [-kpv] <version>
+# Usage: rbenv install [-f|-s] [-kpv] <version> [-- <configure-args...>]
 #        rbenv install [-f|-s] [-kpv] <definition-file>
-#        rbenv install -l|--list
+#        rbenv install --list
 #        rbenv install --version
 #
-#   -l/--list          List latest stable versions for each Ruby
-#   -L/--list-all      List all local versions
-#   -f/--force         Install even if the version appears to be installed already
-#   -s/--skip-existing Skip if the version appears to be installed already
+#   -l, --list           List latest stable versions for each Ruby
+#   -L, --list-all       List all local versions, including outdated ones
+#   -f, --force          Allow overwriting an existing installed version
+#   -s, --skip-existing  Avoid overwriting an existing installed version
 #
 #   ruby-build options:
 #
-#   -k/--keep          Keep source tree in $RBENV_BUILD_ROOT after installation
-#                      (defaults to $RBENV_ROOT/sources)
-#   -p/--patch         Apply a patch from stdin before building
-#   -v/--verbose       Verbose mode: print compilation status to stdout
-#   --version          Show version of ruby-build
+#   -v, --verbose   Verbose mode: forward all build output to stdout/stderr
+#   -p, --patch     Apply a patch from stdin before building
+#   -k, --keep      Keep source tree in RBENV_BUILD_ROOT after installation
+#                   (defaults to "RBENV_ROOT/sources")
+#   --version       Show version of ruby-build
 #
-# For detailed information on installing Ruby versions with
-# ruby-build, including a list of environment variables for adjusting
-# compilation, see: https://github.com/rbenv/ruby-build#usage
+# For detailed information on installing Ruby versions with ruby-build,
+# including a list of environment variables for adjusting compilation,
+# see: https://github.com/rbenv/ruby-build#usage
 #
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
@@ -100,7 +100,7 @@ for option in "${OPTIONS[@]}"; do
     [ ! -t 1 ] || {
       echo
       echo "Only latest stable releases for each Ruby implementation are shown."
-      echo "Use 'rbenv install --list-all / -L' to show all local versions."
+      echo "Use \`rbenv install --list-all' to show all local versions."
     } 1>&2
     exit
     ;;
@@ -239,15 +239,15 @@ if [ "$STATUS" == "2" ]; then
       echo "$candidates" | indent
     fi
     echo
-    echo "See all available versions with \`rbenv install --list'."
+    echo "See all available versions with \`rbenv install --list-all'."
     echo
     echo -n "If the version you need is missing, try upgrading ruby-build"
     if [ "$here" != "${here#"$(brew --prefix 2>/dev/null)"}" ]; then
       printf ":\n\n"
       echo "  brew upgrade ruby-build"
     elif [ -d "${here}/.git" ]; then
       printf ":\n\n"
-      echo "  git -C ${here} pull"
+      echo "  git -C ${here/${HOME}\//~/} pull"
     else
       printf ".\n"
     fi

bin/ruby-build

@@ -1,17 +1,18 @@
 #!/usr/bin/env bash
 #
-# Usage: ruby-build [-kpv] <definition> <prefix>
-#        ruby-build --definitions
+# Usage: ruby-build [-kpv] <definition> <prefix> [-- <configure-args...>]
+#        ruby-build {--list|--definitions}
 #        ruby-build --version
 #
-#   -k/--keep        Do not remove source tree after installation
-#   -p/--patch       Apply a patch from stdin before building
-#   -v/--verbose     Verbose mode: print compilation status to stdout
-#   -4/--ipv4        Resolve names to IPv4 addresses only
-#   -6/--ipv6        Resolve names to IPv6 addresses only
-#   --definitions    List all local definitions
-#   -l/--list        List latest stable releases for each Ruby
-#   --version        Show version of ruby-build
+#   -l, --list      List latest stable releases for each Ruby
+#   --definitions   List all local definitions, including outdated ones
+#   --version       Show version of ruby-build
+#
+#   -v, --verbose   Verbose mode: forward all build output to stdout/stderr
+#   -p, --patch     Apply a patch from stdin before building
+#   -k, --keep      Do not remove source tree after installation
+#   -4, --ipv4      Resolve names to IPv4 addresses only
+#   -6, --ipv6      Resolve names to IPv6 addresses only
 #
 
 RUBY_BUILD_VERSION="20231025"

install.sh

@@ -13,8 +13,10 @@ fi
 
 BIN_PATH="${PREFIX}/bin"
 SHARE_PATH="${PREFIX}/share/ruby-build"
+MAN_PATH="${PREFIX}/share/man/man1"
 
-mkdir -p "$BIN_PATH" "$SHARE_PATH"
+mkdir -p "$BIN_PATH" "$SHARE_PATH" "$MAN_PATH"
 
 install -p bin/* "$BIN_PATH"
 install -p -m 0644 share/ruby-build/* "$SHARE_PATH"
+install -p -m 0644 share/man/man1/*.1 "$MAN_PATH"

script/release

@@ -39,8 +39,9 @@ fi
 
 sed -i.bak -E "s!^(RUBY_BUILD_VERSION=).+!\\1\"${new_version}\"!" "$binfile"
 rm -f "${binfile}.bak"
+make share/man/man1/ruby-build.1
 
-git commit -m "ruby-build ${new_version}" -- "$binfile"
+git commit -m "ruby-build ${new_version}" -- "$binfile" share/man/man1/ruby-build.1
 
 git tag "$version_tag"
 git push origin master "${version_tag}"