ri.1: rewrite ri man page
* man/ri.1: update the (very outdated) ri man page: * update document date * fix document title formatting and volume name * update descriptions and options to current ri --help text * fix some mdoc formatting errors (missing escaping of `\', wrong macro for bullet list items) * various rewordings and other improvements git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58410 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
parent
3d709948f7
commit
760472349d
228
man/ri.1
228
man/ri.1
@ -1,47 +1,56 @@
|
|||||||
.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
|
.\"Ruby is copyrighted by Yukihiro Matsumoto <matz@netlab.jp>.
|
||||||
.Dd July 10, 2013
|
.Dd April 20, 2017
|
||||||
.Dt RI(1) "" "Ruby Programmers Reference Guide"
|
.Dt RI \&1 "Ruby Programmer's Reference Guide"
|
||||||
.Os UNIX
|
.Os UNIX
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
.Nm ri
|
.Nm ri
|
||||||
.Nd Ruby API reference front end
|
.Nd Ruby API reference front end
|
||||||
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
||||||
.Nm
|
.Nm
|
||||||
.Op Fl alTi
|
.Op Fl ahilTv
|
||||||
.Op Fl d Ar directory
|
.Op Fl d Ar DIRNAME
|
||||||
.Op Fl f Ar format
|
.Op Fl f Ar FORMAT
|
||||||
.Op Fl w Ar width
|
.Op Fl w Ar WIDTH
|
||||||
.Op Fl -server Ns [= Ns Ar PORT Ns ]
|
.Op Fl - Ns Oo Cm no- Oc Ns Cm pager
|
||||||
.Op Fl -no-standard-docs
|
.Op Fl -server Ns Oo = Ns Ar PORT Oc
|
||||||
.Op Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
|
.Op Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
|
||||||
|
.Op Fl -no-standard-docs
|
||||||
.Op Fl - Ns Oo Cm no- Oc Ns Bro Cm system Ns | Ns Cm site Ns | Ns Cm gems Ns | Ns Cm home Brc
|
.Op Fl - Ns Oo Cm no- Oc Ns Bro Cm system Ns | Ns Cm site Ns | Ns Cm gems Ns | Ns Cm home Brc
|
||||||
.Op Ar target ...
|
.Op Fl - Ns Oo Cm no- Oc Ns Cm profile
|
||||||
|
.Op Fl -dump Ns = Ns Ar CACHE
|
||||||
|
.Op Ar name ...
|
||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
.Nm
|
.Nm
|
||||||
is a CLI front end for the Ruby API reference.
|
is a command-line front end for the Ruby API reference.
|
||||||
You can search and read API reference for classes and methods with
|
You can search and read the API reference for classes and methods with
|
||||||
.Nm .
|
.Nm .
|
||||||
.Pp
|
.Pp
|
||||||
.Nm
|
.Nm
|
||||||
is a part of Ruby.
|
is a part of Ruby.
|
||||||
.Pp
|
.Pp
|
||||||
.Ar target
|
.Ar name
|
||||||
can be one of the following forms:
|
can be:
|
||||||
.Bl -diag -offset indent
|
.Bl -diag -offset indent
|
||||||
.It Class
|
.It Class | Module | Module::Class
|
||||||
for classes
|
.Pp
|
||||||
.It Class::method
|
.It Class::method | Class#method | Class.method | method
|
||||||
for class methods
|
.Pp
|
||||||
.It Class#method
|
.It gem_name: | gem_name:README | gem_name:History
|
||||||
for instance methods
|
|
||||||
.It Class.method
|
|
||||||
for both class and instance methods
|
|
||||||
.It method
|
|
||||||
for both class and instance methods
|
|
||||||
.El
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
All class names may be abbreviated to their minimum unambiguous form. If a name
|
All class names may be abbreviated to their minimum unambiguous form.
|
||||||
is ambiguous, all valid options will be listed.
|
If a name is ambiguous, all valid options will be listed.
|
||||||
|
.Pp
|
||||||
|
A
|
||||||
|
.Ql \&.
|
||||||
|
matches either class or instance methods, while #method
|
||||||
|
matches only instance and ::method matches only class methods.
|
||||||
|
.Pp
|
||||||
|
README and other files may be displayed by prefixing them with the gem name
|
||||||
|
they're contained in. If the gem name is followed by a
|
||||||
|
.Ql \&:
|
||||||
|
all files in the gem will be shown.
|
||||||
|
The file name extension may be omitted where it is unambiguous.
|
||||||
.Pp
|
.Pp
|
||||||
For example:
|
For example:
|
||||||
.Bd -literal -offset indent
|
.Bd -literal -offset indent
|
||||||
@ -49,23 +58,51 @@ ri Fil
|
|||||||
ri File
|
ri File
|
||||||
ri File.new
|
ri File.new
|
||||||
ri zip
|
ri zip
|
||||||
|
ri rdoc:README
|
||||||
.Ed
|
.Ed
|
||||||
.Pp
|
.Pp
|
||||||
Note that shell quoting may be required for method names containing
|
Note that shell quoting or escaping may be required for method names
|
||||||
punctuation:
|
containing punctuation:
|
||||||
.Bd -literal -offset indent
|
.Bd -literal -offset indent
|
||||||
ri 'Array.[]'
|
ri 'Array.[]'
|
||||||
ri compact\!
|
ri compact\e!
|
||||||
.Ed
|
.Ed
|
||||||
|
.Pp
|
||||||
|
To see the default directories
|
||||||
|
.Nm
|
||||||
|
will search, run:
|
||||||
|
.Bd -literal -offset indent
|
||||||
|
ri --list-doc-dirs
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
Specifying the
|
||||||
|
.Fl -system , Fl -site , Fl -home , Fl -gems ,
|
||||||
|
or
|
||||||
|
.Fl -doc-dir
|
||||||
|
options will limit
|
||||||
|
.Nm
|
||||||
|
to searching only the specified directories.
|
||||||
|
.Pp
|
||||||
|
.Nm
|
||||||
|
options may be set in the
|
||||||
|
.Ev RI
|
||||||
|
environment variable.
|
||||||
|
.Pp
|
||||||
|
The
|
||||||
|
.Nm
|
||||||
|
pager can be set with the
|
||||||
|
.Ev RI_PAGER
|
||||||
|
environment variable or the
|
||||||
|
.Ev PAGER
|
||||||
|
environment variable.
|
||||||
|
.Pp
|
||||||
.Sh OPTIONS
|
.Sh OPTIONS
|
||||||
.Bl -tag -width "1234567890123" -compact
|
.Bl -tag -width "1234567890123" -compact
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl -help
|
.It Fl i
|
||||||
Show help and exit.
|
.It Fl - Ns Oo Cm no- Oc Ns Cm interactive
|
||||||
.Pp
|
In interactive mode you can repeatedly
|
||||||
.It Fl v
|
look up methods with autocomplete.
|
||||||
.It Fl -version
|
|
||||||
Output version information and exit.
|
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl a
|
.It Fl a
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm all
|
.It Fl - Ns Oo Cm no- Oc Ns Cm all
|
||||||
@ -77,115 +114,134 @@ List classes
|
|||||||
.Nm
|
.Nm
|
||||||
knows about.
|
knows about.
|
||||||
.Pp
|
.Pp
|
||||||
|
.It Fl - Ns Oo Cm no- Oc Ns Cm pager
|
||||||
|
Send output to a pager,
|
||||||
|
rather than directly to stdout.
|
||||||
|
.Pp
|
||||||
.It Fl T
|
.It Fl T
|
||||||
.It Fl -no-pager
|
Synonym for
|
||||||
Send output directly to stdout, rather than to a pager.
|
.Fl -no-pager .
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl d Ar directory
|
.It Fl w Ar WIDTH
|
||||||
.It Fl -doc-dir Ns = Ns Ar directory
|
.It Fl -width Ns = Ns Ar WIDTH
|
||||||
List of directories from which to source documentation in addition to the standard
|
Set the width of the output.
|
||||||
directories. May be repeated.
|
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl -server Ns [= Ns Ar PORT Ns ]
|
.It Fl -server Ns Oo = Ns Ar PORT Oc
|
||||||
Run RDoc server on the given port. The default port is 8214.
|
Run RDoc server on the given port.
|
||||||
|
The default port is\~8214.
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl f Ar FORMAT
|
.It Fl f Ar FORMAT
|
||||||
.It Fl -format Ns = Ns FORMAT
|
.It Fl -format Ns = Ns Ar FORMAT
|
||||||
Format to use when displaying output:
|
Use the selected formatter.
|
||||||
|
The default formatter is
|
||||||
|
.Li bs
|
||||||
|
for paged output and
|
||||||
|
.Li ansi
|
||||||
|
otherwise.
|
||||||
|
Valid formatters are:
|
||||||
|
.Li ansi , Li bs , Li markdown , Li rdoc .
|
||||||
.Pp
|
.Pp
|
||||||
ansi, bs, markdown, rdoc
|
.It Fl h
|
||||||
|
.It Fl -help
|
||||||
|
Show help and exit.
|
||||||
.Pp
|
.Pp
|
||||||
Use 'bs' (backspace) with most pager programs. To use ANSI, either disable the
|
.It Fl v
|
||||||
pager or tell the pager to allow control characters.
|
.It Fl -version
|
||||||
|
Output version information and exit.
|
||||||
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl i
|
Data source options:
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm interactive
|
.Bl -tag -width "1234567890123" -compact
|
||||||
This makes
|
|
||||||
.Nm
|
|
||||||
go into interactive mode.
|
|
||||||
.Pp
|
|
||||||
When
|
|
||||||
.Nm
|
|
||||||
is in interactive mode it will allow the user to disambiguate lists of
|
|
||||||
methods in case multiple methods match against a method search string. It also
|
|
||||||
will allow the user to enter in a method name (with auto-completion, if readline
|
|
||||||
is supported) when viewing a class.
|
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
|
.It Fl - Ns Oo Cm no- Oc Ns Cm list-doc-dirs
|
||||||
List the directories from which ri will source documentation on stdout and exit.
|
List the directories from which
|
||||||
|
.Nm
|
||||||
|
will source documentation on stdout and exit.
|
||||||
|
.Pp
|
||||||
|
.It Fl d Ar DIRNAME
|
||||||
|
.It Fl -doc-dir Ns = Ns Ar DIRNAME
|
||||||
|
List of directories from which to source
|
||||||
|
documentation in addition to the standard
|
||||||
|
directories. May be repeated.
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl -no-standard-docs
|
.It Fl -no-standard-docs
|
||||||
Do not include documentation from the Ruby standard library,
|
Do not include documentation from the Ruby standard library,
|
||||||
.Pa site_lib ,
|
.Pa site_lib ,
|
||||||
installed gems, or
|
installed gems, or
|
||||||
.Pa ~/.rdoc .
|
.Pa ~/.rdoc .
|
||||||
.Pp
|
Use with
|
||||||
Equivalent to specifying the options
|
.Fl -doc-dir .
|
||||||
.Fl -no-system , Fl -no-site , Fl -no-gems ,
|
|
||||||
and
|
|
||||||
.Fl -no-home .
|
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm system
|
.It Fl - Ns Oo Cm no- Oc Ns Cm system
|
||||||
Include documentation from Ruby's standard library. Defaults to true.
|
Include documentation from Ruby's standard library. Defaults to true.
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm site
|
.It Fl - Ns Oo Cm no- Oc Ns Cm site
|
||||||
Include documentation from libraries installed in site_lib. Defaults to true.
|
Include documentation from libraries installed in
|
||||||
|
.Pa site_lib .
|
||||||
|
Defaults to true.
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm gems
|
.It Fl - Ns Oo Cm no- Oc Ns Cm gems
|
||||||
Include documentation from RubyGems. Defaults to true.
|
Include documentation from RubyGems. Defaults to true.
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl - Ns Oo Cm no- Oc Ns Cm home
|
.It Fl - Ns Oo Cm no- Oc Ns Cm home
|
||||||
Include documentation stored in ~/.rdoc. Defaults to true.
|
Include documentation stored in
|
||||||
|
.Pa ~/.rdoc .
|
||||||
|
Defaults to true.
|
||||||
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
.It Fl w Ar width
|
Debug options:
|
||||||
.It Fl -width Ns = Ns Ar width
|
.Bl -tag -width "1234567890123" -compact
|
||||||
Set the width of the output.
|
|
||||||
.Pp
|
.Pp
|
||||||
|
.It Fl - Ns Oo Cm no- Oc Ns Cm profile
|
||||||
|
Run with the Ruby profiler.
|
||||||
|
.Pp
|
||||||
|
.It Fl -dump Ns = Ns Ar CACHE
|
||||||
|
Dump data from an ri cache or data file.
|
||||||
.El
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
.Sh ENVIRONMENT
|
.Sh ENVIRONMENT
|
||||||
.Bl -tag -width "USERPROFILE" -compact
|
.Bl -tag -width "USERPROFILE" -compact
|
||||||
.Pp
|
.Pp
|
||||||
.It Ev RI
|
.It Ev RI
|
||||||
Additional options.
|
Options to prepend to those specified on the command-line.
|
||||||
.Pp
|
.Pp
|
||||||
|
.It Ev RI_PAGER
|
||||||
.It Ev PAGER
|
.It Ev PAGER
|
||||||
Used as the name of pager program for displaying.
|
Pager program to use for displaying.
|
||||||
.Pp
|
.Pp
|
||||||
.It Ev HOME
|
.It Ev HOME
|
||||||
.It Ev USERPROFILE
|
.It Ev USERPROFILE
|
||||||
.It Ev HOMEPATH
|
.It Ev HOMEPATH
|
||||||
Path to user's home directory.
|
Path to the user's home directory.
|
||||||
.El
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
.Sh FILES
|
.Sh FILES
|
||||||
.Bl -tag -width "USERPROFILE" -compact
|
.Bl -tag -width "USERPROFILE" -compact
|
||||||
.Pp
|
.Pp
|
||||||
.It Pa ~/.ri
|
|
||||||
Caches recently referenced documents here.
|
|
||||||
.Pp
|
|
||||||
.It Pa ~/.rdoc
|
.It Pa ~/.rdoc
|
||||||
Searches user-wide documents here.
|
Path for ri data in the user's home directory.
|
||||||
.Pp
|
.Pp
|
||||||
.El
|
.El
|
||||||
.Pp
|
.Pp
|
||||||
.Sh SEE ALSO
|
.Sh SEE ALSO
|
||||||
.Xr ruby 1
|
.Xr ruby 1 ,
|
||||||
.Xr rdoc 1
|
.Xr rdoc 1 ,
|
||||||
.Xr gem 1
|
.Xr gem 1
|
||||||
.Pp
|
.Pp
|
||||||
.Sh REPORTING BUGS
|
.Sh REPORTING BUGS
|
||||||
.Bl -bullet
|
.Bl -bullet
|
||||||
.Li Security vulnerabilities should be reported via an email to
|
.It
|
||||||
.Aq security@ruby-lang.org .
|
Security vulnerabilities should be reported via an email to
|
||||||
|
.Mt security@ruby-lang.org .
|
||||||
Reported problems will be published after being fixed.
|
Reported problems will be published after being fixed.
|
||||||
.Pp
|
.Pp
|
||||||
.Li And you can report other bugs and feature requests via the
|
.It
|
||||||
|
Other bugs and feature requests can be reported via the
|
||||||
Ruby Issue Tracking System
|
Ruby Issue Tracking System
|
||||||
.Pq Lk https://bugs.ruby-lang.org/ .
|
.Pq Lk https://bugs.ruby-lang.org/ .
|
||||||
Do not report security vulnerabilities
|
Do not report security vulnerabilities
|
||||||
via the system because it publishes the vulnerabilities immediately.
|
via this system because it publishes the vulnerabilities immediately.
|
||||||
.El
|
.El
|
||||||
.Sh AUTHORS
|
.Sh AUTHORS
|
||||||
Written by Dave Thomas
|
Written by
|
||||||
.Aq dave@pragmaticprogrammer.com
|
.An Dave Thomas Aq dave@pragmaticprogrammer.com .
|
||||||
|
Loading…
x
Reference in New Issue
Block a user