git: 407dbb9254 - main - [phb] Document USES=ruby

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=407dbb9254e7b6b379b8257f34f7732ed1afc71f

commit 407dbb9254e7b6b379b8257f34f7732ed1afc71f
Author:     Fernando Apesteguía <fernape@FreeBSD.org>
AuthorDate: 2023-01-19 16:12:05 +0000
Commit:     Fernando Apesteguía <fernape@FreeBSD.org>
CommitDate: 2023-01-31 11:29:09 +0000

    [phb] Document USES=ruby
    
    Following changes in the ports framework in:
    
    https://cgit.freebsd.org/ports/commit/?id=18c6e18276691edf5274406bf82a3b06792ff9ae
    
    Reviewed by:    bofh@
    Differential Revision: https://reviews.freebsd.org/D38121
---
 .../en/books/porters-handbook/special/_index.adoc  | 63 ----------------------
 .../en/books/porters-handbook/uses/_index.adoc     | 47 ++++++++++++++++
 2 files changed, 47 insertions(+), 63 deletions(-)

diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index cdd57b2b3b..d31179deca 100644
--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -3667,69 +3667,6 @@ It is possible to specify the desired version of `tcl` by appending `:_xx_`, for
 See the crossref:uses[uses-tcl,`USES=tcl`] and crossref:uses[uses-tk,`USES=tk`] of crossref:uses[uses,Using `USES` Macros] for a full description of those variables.
 A complete list of those variables is available in [.filename]#/usr/ports/Mk/Uses/tcl.mk#.
 
-[[using-ruby]]
-== Using Ruby
-
-[[using-ruby-variables]]
-.Useful Variables for Ports That Use Ruby
-[cols="1,1", frame="none", options="header"]
-|===
-| Variable
-| Description
-
-|`USE_RUBY`
-|Adds build and run dependencies on Ruby.
-
-|`USE_RUBY_EXTCONF`
-|The port uses [.filename]#extconf.rb# to configure.
-
-|`USE_RUBY_SETUP`
-|The port uses [.filename]#setup.rb# to configure.
-
-|`RUBY_SETUP`
-|Override the name of the setup script from [.filename]#setup.rb#. Another common value is [.filename]#install.rb#.
-|===
-
-This table shows the selected variables available to port authors via the ports infrastructure.
-These variables are used to install files into their proper locations.
-Use them in [.filename]#pkg-plist# as much as possible.
-Do not redefine these variables in the port.
-
-[[using-ruby-variables-ro]]
-.Selected Read-Only Variables for Ports That Use Ruby
-[cols="1,1,1", frame="none", options="header"]
-|===
-| Variable
-| Description
-| Example value
-
-|`RUBY_PKGNAMEPREFIX`
-|Used as a `PKGNAMEPREFIX` to distinguish packages for different Ruby versions.
-|`ruby19-`
-
-|`RUBY_VERSION`
-|Full version of Ruby in the form of `x.y.z[.p]`.
-|`1.9.3.484`
-
-|`RUBY_SITELIBDIR`
-|Architecture independent libraries installation path.
-|`/usr/local/lib/ruby/site_ruby/1.9`
-
-|`RUBY_SITEARCHLIBDIR`
-|Architecture dependent libraries installation path.
-|`/usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10`
-
-|`RUBY_MODDOCDIR`
-|Module documentation installation path.
-|`/usr/local/share/doc/ruby19/patsy`
-
-|`RUBY_MODEXAMPLESDIR`
-|Module examples installation path.
-|`/usr/local/share/examples/ruby19/patsy`
-|===
-
-A complete list of available variables can be found in [.filename]#/usr/ports/Mk/bsd.ruby.mk#.
-
 [[using-sdl]]
 == Using SDL
 
diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
index 75597e1561..817ed80eb3 100644
--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -503,6 +503,8 @@ Possible arguments: (none), `noautoplist`
 Handle building with RubyGems.
 If `noautoplist` is used, the packing list is not generated automatically.
 
+This implies `USES=ruby`.
+
 [[uses-gettext]]
 == `gettext`
 
@@ -1711,6 +1713,51 @@ Possible arguments: (none), `port`
 Uses readline as a library dependency, and sets `CPPFLAGS` and `LDFLAGS` as necessary.
 If the `port` argument is used or if readline is not present in the base system, add a dependency on package:devel/readline[]
 
+
+[[uses-ruby]]
+== `ruby`
+
+Possible arguments: (none), `build`, `extconf`, `run`, `setup`
+
+Provide support for Ruby related ports.
+`(none)` without arguments adds runtime dependency on package:lang/ruby[].
+`build` adds a dependency on package:lang/ruby[] at build time.
+`extconf` states that the port uses extconf.rb to configure.
+`run` adds a dependency on package:lang/ruby[] at run time. This is also the default.
+`setup` states that the port uses setup.rb to configure and build.
+
+The user may have the following variables defined:
+
+`RUBY_VER`::
+Alternative short version of ruby in the form of `x.y'.
+
+`RUBY_DEFAULT_VER`::
+Set to (e.g.) `2.7` to use `ruby27` as the default version.
+
+`RUBY_ARCH`::
+Set the architecture name (e.g. i386-freebsd7).
+
+The following variables are exported to be used by the port:
+
+`RUBY`::
+Set to full path of ruby.
+If set, the values of the following variables are automatically obtained from
+the ruby executable: `RUBY_ARCH`, `RUBY_ARCHLIBDIR`, `RUBY_LIBDIR`,
+`RUBY_SITEARCHLIBDIR`, `RUBY_SITELIBDIR`, `RUBY_VER` and `RUBY_VERSION`
+
+`RUBY_VER`::
+Set to the alternative short version of ruby in the form of `x.y'.
+
+`RUBY_EXTCONF`::
+Set to the alternative name of extconf.rb (default: extconf.rb).
+
+`RUBY_EXTCONF_SUBDIRS`::
+Set to list of subdirectories, if multiple modules are included.
+
+`RUBY_SETUP`::
+Set to the alternative name of setup.rb (default: setup.rb).
+
+
 [[uses-samba]]
 == `samba`