[ruby-core:68137] improve semantics of manpages
0 views
Skip to first unread message
Anthony J. Bentley
Feb 17, 2015, 1:57:33 AM2/17/15
to ruby...@ruby-lang.org
Hi,
Here is a patch that improves the semantic macros used in manpages, along
with various cleanup and linting. The pages now pass the mdocml linter.
- Semantically mark up links and email addresses
- Use correct syntax for document title
- Delete empty paragraphs
- Escape ASCII apostrophes when necessary
- New sentence, new line (troff requires this to get the spacing right)
Changelog entry:
* man/erb.1: [DOC] Improve semantics of -mdoc macros. Cleanup to
pass the Mandoc project's manual linter.
* man/goruby.1: ditto.
* man/irb.1: ditto.
* man/ri.1: ditto.
* man/ruby.1: ditto.
Index: man/erb.1
===================================================================
--- man/erb.1 (revision 49621)
+++ man/erb.1 (working copy)
@@ -1,7 +1,7 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt ERB(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt ERB 1
+.Os
.Sh NAME
.Nm erb
.Nd Ruby Templating
@@ -14,8 +14,7 @@
.Op Fl T Ar mode
.Op Fl r Ar library
.Op Fl -
-.Op file ...
-.Pp
+.Op Ar file ...
.Sh DESCRIPTION
.Nm
is a command line front-end for
@@ -29,29 +28,24 @@
.Nm
is a part of
.Nm Ruby .
-.Pp
.Sh OPTIONS
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -version
Prints the version of
.Nm .
-.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
-Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+Specifies the default value(s) for external encodings and internal encoding.
+Values should be separated with colon (:).
.Pp
You can omit the one for internal encodings, then the value
.Pf ( Li "Encoding.default_internal" ) will be nil.
-.Pp
.It Fl P
Evaluates lines starting with
.Li "%"
as Ruby code and removes the tailing EOLs.
-.Pp
.It Fl S Ar level
Specifies the safe level in which eRuby script will run.
-.Pp
.It Fl T Ar mode
Specifies trim mode (default 0).
.Ar mode
@@ -59,55 +53,42 @@
.Bl -hang -offset indent
.It Sy 0
EOL remains after the embedded ruby script is evaluated.
-.Pp
.It Sy 1
EOL is removed if the line ends with
.Li "%>" .
-.Pp
.It Sy 2
EOL is removed if the line starts with
.Li "<%"
and ends with
.Li "%>" .
-.Pp
.It Sy -
EOL is removed if the line ends with
.Li "-%>" .
And leading whitespaces are removed if the erb directive starts with
.Li "<%-" .
-.Pp
.El
-.Pp
.It Fl U
-can be one of
Sets the default value for internal encodings
.Pf ( Li "Encoding.default_internal" ) to UTF-8.
-.Pp
.It Fl d
.It Fl -debug
Turns on debug mode.
.Li "$DEBUG"
will be set to true.
-.Pp
.It Fl h
.It Fl -help
Prints a summary of the options.
-.Pp
.It Fl n
Used with
.Fl x .
Prepends the line number to each line in the output.
-.Pp
.It Fl v
Enables verbose mode.
.Li "$VERBOSE"
will be set to true.
-.Pp
.It Fl x
Converts the eRuby script into Ruby script and prints it without line numbers.
-.Pp
.El
-.Pp
.Sh EXAMPLES
Here is an eRuby script
.Bd -literal -offset indent
@@ -131,9 +112,8 @@
<library>2, 3, 5, 7</library>
</erb-example>
.Ed
-.Pp
.Sh SEE ALSO
-.Xr ruby 1 .
+.Xr ruby 1
.Pp
And see
.Xr ri 1
@@ -140,18 +120,16 @@
documentation for
.Li "ERB"
class.
-.Pp
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after being fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (http://bugs.ruby-lang.org).
+And you can report other bugs and feature requests via the
+.Lk http://bugs.ruby-lang.org "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
-Written by Masatoshi SEKI.
+.An -nosplit
+Written by
+.An Masatoshi SEKI .
Index: man/goruby.1
===================================================================
--- man/goruby.1 (revision 49621)
+++ man/goruby.1 (working copy)
@@ -1,13 +1,13 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt GORUBY(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt GORUBY 1
+.Os
.Sh NAME
.Nm goruby
.Nd A code-golfer's best friend
.Sh SYNOPSIS
.Nm
-.Op options ...
+.Op Ar options ...
.Op Fl -
.Op Ar program_file
.Op Ar argument ...
@@ -23,7 +23,6 @@
.Bd -literal -offset indent
require"date";puts Date.today
.Ed
-.Pp
.Sh OPTIONS
.Sy goruby
takes same options as
@@ -33,7 +32,8 @@
.It Xr ruby 1
The stiff version of Ruby interpreter.
.El
-.Pp
.Sh AUTHORS
-Originally written by Nobuyoshi Nakada and developed by the
-Ruby core team.
+.An -nosplit
+Originally written by
+.An Nobuyoshi Nakada
+and developed by the Ruby core team.
Index: man/irb.1
===================================================================
--- man/irb.1 (revision 49621)
+++ man/irb.1 (working copy)
@@ -1,7 +1,7 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt IRB(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt IRB 1
+.Os
.Sh NAME
.Nm irb
.Nd Interactive Ruby Shell
@@ -22,90 +22,82 @@
.Op Fl -back-trace-limit Ar n
.Op Fl -irb_debug Ar n
.Op Fl -
-.Op program_file
-.Op argument ...
-.Pp
+.Op Ar program_file
+.Op Ar argument ...
.Sh DESCRIPTION
.Nm
-is the REPL(read-eval-print loop) environment for Ruby programs.
-.Pp
+is the REPL (read-eval-print loop) environment for Ruby programs.
.Sh OPTIONS
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -version
Prints the version of
.Nm .
-.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
-Same as `ruby -E' .
-Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+Same as
+.Sq ruby -E .
+Specifies the default value(s) for external encodings and internal encoding.
+Values should be separated with colon (:).
.Pp
You can omit the one for internal encodings, then the value
.Pf ( Li "Encoding.default_internal" ) will be nil.
-.Pp
.It Fl I Ar path
-Same as `ruby -I' .
+Same as
+.Sq ruby -I .
Specifies
.Li $LOAD_PATH
directory
-.Pp
.It Fl U
-Same as `ruby -U' .
+Same as
+.Sq ruby -U .
Sets the default value for internal encodings
.Pf ( Li "Encoding.default_internal" ) to UTF-8.
-.Pp
.It Fl d
-Same as `ruby -d' .
+Same as
+.Sq ruby -d .
Sets
.Li $DEBUG
to true.
-.Pp
.It Fl f
Suppresses read of
.Pa ~/.irbrc .
-.Pp
.It Fl h
.It Fl -help
Prints a summary of the options.
-.Pp
.It Fl m
Bc mode (load mathn, fraction or matrix are available)
-.Pp
.It Fl r Ar library
-Same as `ruby -r'.
+Same as
+.Sq ruby -r .
Causes irb to load the library using require.
-.Pp
.It Fl -inspect
-Uses `inspect' for output (default except for bc mode)
-.Pp
+Uses
+.Sq inspect
+for output (default except for bc mode)
.It Fl -noinspect
Doesn't use inspect for output
-.Pp
.It Fl -readline
Uses Readline extension module.
-.Pp
.It Fl -noreadline
Doesn't use Readline extension module.
-.Pp
.It Fl -prompt Ar mode
.It Fl -prompt-mode Ar mode
-Switch prompt mode. Pre-defined prompt modes are
-`default', `simple', `xmp' and `inf-ruby'.
-.Pp
+Switch prompt mode.
+Pre-defined prompt modes are
+.Sq default ,
+.Sq simple ,
+.Sq xmp
+and
+.Sq inf-ruby .
.It Fl -inf-ruby-mode
Uses prompt appropriate for inf-ruby-mode on emacs.
Suppresses --readline.
-.Pp
.It Fl -simple-prompt
Makes prompts simple.
-.Pp
.It Fl -noprompt
No prompt mode.
-.Pp
.It Fl -tracer
Displays trace for each execution of commands.
-.Pp
.It Fl -back-trace-limit Ar n
Displays backtrace top
.Ar n
@@ -112,16 +104,12 @@
and tail
.Ar n Ns .
The default value is 16.
-.Pp
.It Fl -irb_debug Ar n
Sets internal debug level to n (not for popular use)
-.Pp
.El
-.Pp
.Sh ENVIRONMENT
.Bl -tag -width "RUBYLIB_PREFIX" -compact
.It Ev IRBRC
-.Pp
.El
.Pp
Also
@@ -128,14 +116,11 @@
.Nm
depends on same variables as
.Xr ruby 1 .
-.Pp
.Sh FILES
.Bl -tag -width "RUBYLIB_PREFIX" -compact
.It Pa ~/.irbrc
Personal irb initialization.
-.Pp
.El
-.Pp
.Sh EXAMPLES
.Dl % irb
.Dl irb(main):001:0> Ic 1 + 1
@@ -153,21 +138,18 @@
.Dl => :ok
.Dl irb(main):009:0> Ic quit
.Dl %
-.Pp
.Sh SEE ALSO
-.Xr ruby 1 .
-.Pp
+.Xr ruby 1
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after being fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (http://bugs.ruby-lang.org).
+And you can report other bugs and feature requests via the
+.Lk http://bugs.ruby-lang.org "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
-Written by Keiju ISHITSUKA.
+.An -nosplit
+Written by
+.An Keiju ISHITSUKA .
Index: man/ri.1
===================================================================
--- man/ri.1 (revision 49621)
+++ man/ri.1 (working copy)
@@ -1,7 +1,7 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt RI(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt RI 1
+.Os
.Sh NAME
.Nm ri
.Nd Ruby API reference front end
@@ -40,8 +40,8 @@
for both class and instance methods
.El
.Pp
-All class names may be abbreviated to their minimum unambiguous form. If a name
-is ambiguous, all valid options will be listed.
+All class names may be abbreviated to their minimum unambiguous form.
+If a name is ambiguous, all valid options will be listed.
.Pp
For example:
.Bd -literal -offset indent
@@ -54,25 +54,22 @@
Note that shell quoting may be required for method names containing
punctuation:
.Bd -literal -offset indent
-ri 'Array.[]'
+ri \(aqArray.[]\(aq
ri compact\!
.Ed
.Sh OPTIONS
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -version
Prints the version of
.Nm .
-.Pp
.It Fl T
.It Fl -no-pager
Send output directly to stdout, rather than to a pager.
-.Pp
.It Fl d Ar directory
.It Fl -doc-dir Ns = Ns Ar directory
-List of directories from which to source documentation in addition to the standard
-directories. May be repeated.
-.Pp
+List of directories from which to source documentation in addition to the
+standard directories.
+May be repeated.
.It Fl f Ar FORMAT
.It Fl -fmt Ar FORMAT
.It Fl -format Ns = Ns FORMAT
@@ -80,9 +77,11 @@
.Pp
ansi, bs, html, plain, simple
.Pp
-Use 'bs' (backspace) with most pager programs. To use ANSI, either disable the
+Use
+.Sq bs
+(backspace) with most pager programs.
+To use ANSI, either disable the
pager or tell the pager to allow control characters.
-.Pp
.It Fl i
.It Fl -interactive
This makes
@@ -92,13 +91,12 @@
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
+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
.It Fl -list-doc-dirs
List the directories from which ri will source documentation on stdout and exit.
-.Pp
.It Fl -no-standard-docs
Do not include documentation from the Ruby standard library,
.Pa site_lib ,
@@ -109,73 +107,59 @@
.Fl -no-system , Fl -no-site , Fl -no-gems ,
and
.Fl -no-home .
-.Pp
.It Fl - Ns Oo Cm no- Oc Ns Cm system
-Include documentation from Ruby's standard library. Defaults to true.
-.Pp
+Include documentation from Ruby's standard library.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm site
- Include documentation from libraries installed in site_lib. Defaults to true.
-.Pp
+ Include documentation from libraries installed in site_lib.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm gems
-Include documentation from RubyGems. Defaults to true.
-.Pp
+Include documentation from RubyGems.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm home
-Include documentation stored in ~/.rdoc. Defaults to true.
-.Pp
+Include documentation stored in ~/.rdoc.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm use-cache
Whether or not to use
.Nm Ns
-.Ns 's cache. True by default.
-.Pp
+\&'s cache.
+True by default.
.It Fl w Ar width
.It Fl -width Ns = Ns Ar width
Set the width of the output.
-.Pp
.El
-.Pp
.Sh ENVIRONMENT
.Bl -tag -width "USERPROFILE" -compact
-.Pp
.It Ev RI
Additional options.
-.Pp
.It Ev PAGER
Used as the name of pager program for displaying.
-.Pp
.It Ev HOME
.It Ev USERPROFILE
.It Ev HOMEPATH
Path to user's home directory.
.El
-.Pp
.Sh FILES
.Bl -tag -width "USERPROFILE" -compact
-.Pp
.It Pa ~/.ri
Caches recently referenced documents here.
-.Pp
.It Pa ~/.rdoc
Searches user-wide documents here.
-.Pp
.El
-.Pp
.Sh SEE ALSO
+.Xr gem 1 ,
+.Xr rdoc 1 ,
.Xr ruby 1
-.Xr rdoc 1
-.Xr gem 1
-.Pp
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after being fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (http://bugs.ruby-lang.org).
+And you can report other bugs and feature requests via the
+.Lk http://bugs.ruby-lang.org "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
-Written by Dave Thomas
-.Aq da...@pragmaticprogrammer.com
+.An -nosplit
+Written by
+.An Dave Thomas Aq Mt da...@pragmaticprogrammer.com .
Index: man/ruby.1
===================================================================
--- man/ruby.1 (revision 49621)
+++ man/ruby.1 (working copy)
@@ -1,8 +1,8 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt RUBY(1) "" "Ruby Programmers Reference Guide"
+.Dt RUBY 1
.\".Dt RUBY 1
-.Os UNIX
+.Os
.Sh NAME
.Nm ruby
.Nd Interpreted object-oriented scripting language
@@ -31,8 +31,10 @@
.Op Ar argument ...
.Sh DESCRIPTION
Ruby is an interpreted scripting language for quick and easy
-object-oriented programming. It has many features to process text
-files and to do system management tasks (like in Perl). It is simple,
+object-oriented programming.
+It has many features to process text
+files and to do system management tasks (like in Perl).
+It is simple,
straight-forward, and extensible.
.Pp
If you want a language for easy object-oriented programming, or you
@@ -45,75 +47,69 @@
.It Sy "Interpretive"
Ruby is an interpreted language, so you don't have to recompile
programs written in Ruby to execute them.
-.Pp
.It Sy "Variables have no type (dynamic typing)"
-Variables in Ruby can contain data of any type. You don't have to
-worry about variable typing. Consequently, it has a weaker compile
+Variables in Ruby can contain data of any type.
+You don't have to
+worry about variable typing.
+Consequently, it has a weaker compile
time check.
-.Pp
.It Sy "No declaration needed"
You can use variables in your Ruby programs without any declarations.
Variable names denote their scope - global, class, instance, or local.
-.Pp
.It Sy "Simple syntax"
Ruby has a simple syntax influenced slightly from Eiffel.
-.Pp
.It Sy "No user-level memory management"
-Ruby has automatic memory management. Objects no longer referenced
+Ruby has automatic memory management.
+Objects no longer referenced
from anywhere are automatically collected by the garbage collector
built into the interpreter.
-.Pp
.It Sy "Everything is an object"
Ruby is a purely object-oriented language, and was so since its
-creation. Even such basic data as integers are seen as objects.
-.Pp
+creation.
+Even such basic data as integers are seen as objects.
.It Sy "Class, inheritance, and methods"
Being an object-oriented language, Ruby naturally has basic
features like classes, inheritance, and methods.
-.Pp
.It Sy "Singleton methods"
-Ruby has the ability to define methods for certain objects. For
+Ruby has the ability to define methods for certain objects.
+For
example, you can define a press-button action for certain widget by
-defining a singleton method for the button. Or, you can make up your
+defining a singleton method for the button.
+Or, you can make up your
own prototype based object system using singleton methods, if you want
to.
-.Pp
.It Sy "Mix-in by modules"
Ruby intentionally does not have the multiple inheritance as it is a
-source of confusion. Instead, Ruby has the ability to share
-implementations across the inheritance tree. This is often called a
+source of confusion.
+Instead, Ruby has the ability to share
+implementations across the inheritance tree.
+This is often called a
.Sq Mix-in .
-.Pp
.It Sy "Iterators"
Ruby has iterators for loop abstraction.
-.Pp
.It Sy "Closures"
In Ruby, you can objectify the procedure.
-.Pp
.It Sy "Text processing and regular expressions"
Ruby has a bunch of text processing features like in Perl.
-.Pp
.It Sy "M17N, character set independent"
-Ruby supports multilingualized programming. Easy to process texts
+Ruby supports multilingualized programming.
+Easy to process texts
written in many different natural languages and encoded in many
different character encodings, without dependence on Unicode.
-.Pp
.It Sy "Bignums"
With built-in bignums, you can for example calculate factorial(400).
-.Pp
.It Sy "Reflection and domain specific languages"
-Class is also an instance of the Class class. Definition of classes and methods
-is an expression just as 1+1 is. So your programs can even write and modify programs.
+Class is also an instance of the Class class.
+Definition of classes and methods
+is an expression just as 1+1 is.
+So your programs can even write and modify programs.
Thus you can write your application in your own programming language on top of Ruby.
-.Pp
.It Sy "Exception handling"
-As in Java(tm).
-.Pp
+As in Java\(tm.
.It Sy "Direct access to the OS"
Ruby can use most
.Ux
system calls, often used in system programming.
-.Pp
.It Sy "Dynamic loading"
On most
.Ux
@@ -120,64 +116,64 @@
systems, you can load object files into the Ruby interpreter
on-the-fly.
.It Sy "Rich libraries"
-Libraries called "builtin libraries" and "standard libraries" are bundled with Ruby.
-And you can obtain more libraries via the package management system called `RubyGems'.
+Libraries called
+.Dq builtin libraries
+and
+.Dq standard libraries
+are bundled with Ruby.
+And you can obtain more libraries via the package management system called
+.Sq RubyGems .
.Pp
Moreover there are thousands of Ruby projects on GitHub
.Aq Pa https://github.com/languages/Ruby .
.El
-.Pp
.Sh OPTIONS
Ruby interpreter accepts following command-line options (switches).
They are quite similar to those of
.Xr perl 1 .
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -copyright
Prints the copyright notice.
-.Pp
.It Fl -version
Prints the version of Ruby interpreter.
-.Pp
.It Fl 0 Ns Op Ar octal
(The digit
.Dq zero . )
Specifies the input record separator
.Pf ( Li "$/" )
-as an octal number. If no digit is given, the null character is taken
-as the separator. Other switches may follow the digits.
+as an octal number.
+If no digit is given, the null character is taken
+as the separator.
+Other switches may follow the digits.
.Fl 00
turns Ruby into paragraph mode.
.Fl 0777
makes Ruby read whole file at once as a single string since there is
no legal character with that value.
-.Pp
.It Fl C Ar directory
.It Fl X Ar directory
Causes Ruby to switch to the directory.
-.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
-Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+Specifies the default value(s) for external encodings and internal encoding.
+Values should be separated with colon (:).
.Pp
You can omit the one for internal encodings, then the value
.Pf ( Li "Encoding.default_internal" ) will be nil.
-.Pp
.It Fl -external-encoding Ns = Ns Ar encoding
.It Fl -internal-encoding Ns = Ns Ar encoding
Specify the default external or internal character encoding
-.Pp
.It Fl F Ar pattern
Specifies input field separator
.Pf ( Li "$;" ) .
-.Pp
.It Fl I Ar directory
-Used to tell Ruby where to load the library scripts. Directory path
+Used to tell Ruby where to load the library scripts.
+Directory path
will be added to the load-path variable
.Pf ( Li "$:" ) .
-.Pp
.It Fl K Ar kcode
-Specifies KANJI (Japanese) encoding. The default value for script encodings
+Specifies KANJI (Japanese) encoding.
+The default value for script encodings
.Pf ( Li "__ENCODING__" ) and external encodings ( Li "Encoding.default_external" ) will be the specified one.
.Ar kcode
can be one of
@@ -184,22 +180,19 @@
.Bl -hang -offset indent
.It Sy e
EUC-JP
-.Pp
.It Sy s
Windows-31J (CP932)
-.Pp
.It Sy u
UTF-8
-.Pp
.It Sy n
ASCII-8BIT (BINARY)
.El
-.Pp
.It Fl S
Makes Ruby use the
.Ev PATH
environment variable to search for script, unless its name begins
-with a slash. This is used to emulate
+with a slash.
+This is used to emulate
.Li #!
on machines that don't support it, in the following manner:
.Bd -literal -offset indent
@@ -207,30 +200,32 @@
# This line makes the next one a comment in Ruby \e
exec /usr/local/bin/ruby -S $0 $*
.Ed
-.Pp
.It Fl T Ns Op Ar level=1
Turns on taint checks at the specified level (default 1).
-.Pp
.It Fl U
Sets the default value for internal encodings
.Pf ( Li "Encoding.default_internal" ) to UTF-8.
-.Pp
.It Fl W Ns Op Ar level=2
Turns on verbose mode at the specified level without printing the version
-message at the beginning. The level can be;
+message at the beginning.
+The level can be;
.Bl -hang -offset indent
.It Sy 0
-Verbose mode is "silence". It sets the
+Verbose mode is
+.Dq silence .
+It sets the
.Li "$VERBOSE"
to nil.
-.Pp
.It Sy 1
-Verbose mode is "medium". It sets the
+Verbose mode is
+.Dq medium .
+It sets the
.Li "$VERBOSE"
to false.
-.Pp
.It Sy 2 (default)
-Verbose mode is "verbose". It sets the
+Verbose mode is
+.Dq verbose .
+It sets the
.Li "$VERBOSE"
to true.
.Fl W Ns
@@ -238,7 +233,6 @@
.Fl w
.
.El
-.Pp
.It Fl a
Turns on auto-split mode when used with
.Fl n
@@ -247,41 +241,38 @@
In auto-split mode, Ruby executes
.Dl $F = $_.split
at beginning of each loop.
-.Pp
.It Fl c
Causes Ruby to check the syntax of the script and exit without
-executing. If there are no syntax errors, Ruby will print
+executing.
+If there are no syntax errors, Ruby will print
.Dq Syntax OK
to the standard output.
-.Pp
.It Fl d
.It Fl -debug
Turns on debug mode.
.Li "$DEBUG"
will be set to true.
-.Pp
.It Fl e Ar command
Specifies script from command-line while telling Ruby not to search
the rest of the arguments for a script file name.
-.Pp
.It Fl h
.It Fl -help
Prints a summary of the options.
-.Pp
.It Fl i Ar extension
-Specifies in-place-edit mode. The extension, if specified, is added
-to old file name to make a backup copy. For example:
+Specifies in-place-edit mode.
+The extension, if specified, is added
+to old file name to make a backup copy.
+For example:
.Bd -literal -offset indent
% echo matz > /tmp/junk
% cat /tmp/junk
matz
-% ruby -p -i.bak -e '$_.upcase!' /tmp/junk
+% ruby -p -i.bak -e \(aq$_.upcase!\(aq /tmp/junk
% cat /tmp/junk
MATZ
% cat /tmp/junk.bak
matz
.Ed
-.Pp
.It Fl l
(The lowercase letter
.Dq ell . )
@@ -291,7 +282,6 @@
.Li "$/" ,
and secondly chops every line read using
.Li chop! .
-.Pp
.It Fl n
Causes Ruby to assume the following loop around your script, which
makes it iterate over file name arguments somewhat like
@@ -304,22 +294,21 @@
...
end
.Ed
-.Pp
.It Fl p
Acts mostly same as -n switch, but print the value of variable
.Li "$_"
-at the each end of the loop. For example:
+at the each end of the loop.
+For example:
.Bd -literal -offset indent
-% echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
+% echo matz | ruby -p -e \(aq$_.tr! "a-z", "A-Z"\(aq
MATZ
.Ed
-.Pp
.It Fl r Ar library
-Causes Ruby to load the library using require. It is useful when using
+Causes Ruby to load the library using require.
+It is useful when using
.Fl n
or
.Fl p .
-.Pp
.It Fl s
Enables some switch parsing for switches after script name but before
any file name arguments (or before a
@@ -326,10 +315,11 @@
.Fl - ) .
Any switches found there are removed from
.Li ARGV
-and set the corresponding variable in the script. For example:
+and set the corresponding variable in the script.
+For example:
.Bd -literal -offset indent
#! /usr/local/bin/ruby -s
-# prints "true" if invoked with `-xyz' switch.
+# prints "true" if invoked with \(aq-xyz\(aq switch.
print "true\en" if $xyz
.Ed
.Pp
@@ -338,34 +328,37 @@
does not always contain the full pathname, so you need the
.Fl S
switch to tell Ruby to search for the script if necessary (to handle embedded
-spaces and such). A better construct than
+spaces and such).
+A better construct than
.Li "$*"
would be
.Li ${1+"$@"} ,
but it does not work if the script is being interpreted by
.Xr csh 1 .
-.Pp
.It Fl v
-Enables verbose mode. Ruby will print its version at the beginning
+Enables verbose mode.
+Ruby will print its version at the beginning
and set the variable
.Li "$VERBOSE"
-to true. Some methods print extra messages if this variable is true.
+to true.
+Some methods print extra messages if this variable is true.
If this switch is given, and no other switches are present, Ruby quits
after printing its version.
-.Pp
.It Fl w
Enables verbose mode without printing version message at the
-beginning. It sets the
+beginning.
+It sets the
.Li "$VERBOSE"
variable to true.
-.Pp
.It Fl x Ns Op Ar directory
-Tells Ruby that the script is embedded in a message. Leading garbage
+Tells Ruby that the script is embedded in a message.
+Leading garbage
will be discarded until the first line that starts with
.Dq #!
and contains the string,
.Dq ruby .
-Any meaningful switches on that line will be applied. The end of the script
+Any meaningful switches on that line will be applied.
+The end of the script
must be specified with either
.Li EOF ,
.Li "^D" ( Li "control-D" ) ,
@@ -374,15 +367,15 @@
.Li __END__ .
If the directory name is specified, Ruby will switch to that directory
before executing script.
-.Pp
.It Fl y
.It Fl -yydebug
DO NOT USE.
.Pp
-Turns on compiler debug mode. Ruby will print a bunch of internal
-state messages during compilation. Only specify this switch you are going to
+Turns on compiler debug mode.
+Ruby will print a bunch of internal
+state messages during compilation.
+Only specify this switch you are going to
debug the Ruby interpreter.
-.Pp
.It Fl -disable- Ns Ar FEATURE
.It Fl -enable- Ns Ar FEATURE
Disables (or enables) the specified
@@ -391,23 +384,22 @@
.Bl -tag -width "--disable-rubyopt" -compact
.It Fl -disable-gems
.It Fl -enable-gems
-Disables (or enables) RubyGems libraries. By default, Ruby will load the latest
-version of each installed gem. The
+Disables (or enables) RubyGems libraries.
+By default, Ruby will load the latest
+version of each installed gem.
+The
.Li Gem
constant is true if RubyGems is enabled, false if otherwise.
-.Pp
.It Fl -disable-rubyopt
.It Fl -enable-rubyopt
Ignores (or considers) the
.Ev RUBYOPT
-environment variable. By default, Ruby considers the variable.
-.Pp
+environment variable.
+By default, Ruby considers the variable.
.It Fl -disable-all
.It Fl -enable-all
Disables (or enables) all features.
-.Pp
.El
-.Pp
.It Fl -dump Ns = Ns Ar target
DO NOT USE.
.Pp
@@ -417,31 +409,29 @@
.Bl -hang -offset indent
.It Sy insns
disassembled instructions
-.Pp
.El
.Pp
Only specify this switch if you are going to debug the Ruby interpreter.
-.Pp
.It Fl -verbose
Enables verbose mode without printing version message at the
-beginning. It sets the
+beginning.
+It sets the
.Li "$VERBOSE"
variable to true.
If this switch is given, and no other switches are present, Ruby quits
after printing its version.
.El
-.Pp
.Sh ENVIRONMENT
.Bl -tag -width "RUBYSHELL" -compact
.It Ev RUBYLIB
A colon-separated list of directories that are added to Ruby's
library load path
-.Pf ( Li "$:" ) . Directories from this environment variable are searched
+.Pf ( Li "$:" ) .
+Directories from this environment variable are searched
before the standard load path is searched.
.Pp
e.g.:
.Dl RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
-.Pp
.It Ev RUBYOPT
Additional Ruby options.
.Pp
@@ -453,21 +443,21 @@
.Fl -disable- Ns Ar FEATURE
and
.Fl -enable- Ns Ar FEATURE .
-.Pp
.It Ev RUBYPATH
A colon-separated list of directories that Ruby searches for
Ruby programs when the
.Fl S
-flag is specified. This variable precedes the
+flag is specified.
+This variable precedes the
.Ev PATH
environment variable.
-.Pp
.It Ev RUBYSHELL
-The path to the system shell command. This environment variable is
-enabled for only mswin32, mingw32, and OS/2 platforms. If this
+The path to the system shell command.
+This environment variable is
+enabled for only mswin32, mingw32, and OS/2 platforms.
+If this
variable is not defined, Ruby refers to
.Ev COMSPEC .
-.Pp
.It Ev PATH
Ruby refers to the
.Ev PATH
@@ -481,7 +471,6 @@
.Bd -literal -offset indent
% gem help
.Ed
-.Pp
.Sh GC ENVIRONMENT
The Ruby garbage collector (GC) tracks objects in fixed-sized slots,
but each object may have auxillary memory allocations handled by the
@@ -490,9 +479,12 @@
.Xr calloc 3 ,
and
.Xr realloc 3 ) .
-In this documentatation, the "heap" refers to the Ruby object heap
-of fixed-sized slots, while "malloc" refers to auxillary
-allocations commonly referred to as the "process heap".
+In this documentatation, the
+.Dq heap
+refers to the Ruby object heap of fixed-sized slots, while
+.Dq malloc
+refers to auxillary allocations commonly referred to as the
+.Dq process heap .
Thus there are at least two possible ways to trigger GC:
.Bl -hang -offset indent
.It Sy 1
@@ -499,7 +491,6 @@
Reaching the object limit.
.It Sy 2
Reaching the malloc limit.
-.Pp
.El
In Ruby 2.1, the generational GC was introduced and the limits are divided
into young and old generations, providing two additional ways to trigger
@@ -515,90 +506,78 @@
the the following 11 environment variables:
.Bl -hang -compact -width "RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR"
.It Ev RUBY_GC_HEAP_INIT_SLOTS
-Initial allocation slots. Introduced in Ruby 2.1, default: 10000.
-.Pp
+Initial allocation slots.
+Introduced in Ruby 2.1, default: 10000.
.It Ev RUBY_GC_HEAP_FREE_SLOTS
Prepare at least this amount of slots after GC.
Allocate this number slots if there are not enough slots.
Introduced in Ruby 2.1, default: 4096
-.Pp
.It Ev RUBY_GC_HEAP_GROWTH_FACTOR
Increase allocation rate of heap slots by this factor.
Introduced in Ruby 2.1, default: 1.8, minimum: 1.0 (no growth)
-.Pp
.It Ev RUBY_GC_HEAP_GROWTH_MAX_SLOTS
Allocation rate is limited to this number of slots,
preventing excessive allocation due to RUBY_GC_HEAP_GROWTH_FACTOR.
Introduced in Ruby 2.1, default: 0 (no limit)
-.Pp
.It Ev RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR
Perform a full GC when the number of old objects is more than R * N,
where R is this factor and N is the number of old objects after the
last full GC.
Introduced in Ruby 2.1.1, default: 2.0
-.Pp
.It Ev RUBY_GC_MALLOC_LIMIT
The initial limit of young generation allocation from the malloc-family.
GC will start when this limit is reached.
Default: 16MB
-.Pp
.It Ev RUBY_GC_MALLOC_LIMIT_MAX
The maximum limit of young generation allocation from malloc before GC starts.
Prevents excessive malloc growth due to RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR.
Introduced in Ruby 2.1, default: 32MB.
-.Pp
.It Ev RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR
Increases the limit of young generation malloc calls, reducing
GC frequency but increasing malloc growth until RUBY_GC_MALLOC_LIMIT_MAX
is reached.
Introduced in Ruby 2.1, default: 1.4, minimum: 1.0 (no growth)
-.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT
The initial limit of old generation allocation from malloc,
a full GC will start when this limit is reached.
Introduced in Ruby 2.1, default: 16MB
-.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT_MAX
The maximum limit of old generation allocation from malloc before a
full GC starts.
Prevents excessive malloc growth due to RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR.
Introduced in Ruby 2.1, default: 128MB
-.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR
Increases the limit of old generation malloc allocation, reducing full
GC frequency but increasing malloc growth until RUBY_GC_OLDMALLOC_LIMIT_MAX
is reached.
Introduced in Ruby 2.1, default: 1.2, minimum: 1.0 (no growth)
-.Pp
.El
.Sh STACK SIZE ENVIRONMENT
Stack size environment variables are implementation-dependent and
-subject to change with different versions of Ruby. The VM stack is used
-for pure-Ruby code and managed by the virtual machine. Machine stack is
+subject to change with different versions of Ruby.
+The VM stack is used
+for pure-Ruby code and managed by the virtual machine.
+Machine stack is
used by the operating system and its usage is dependent on C extensions
-as well as C compiler options. Using lower values for these may allow
+as well as C compiler options.
+Using lower values for these may allow
applications to keep more Fibers or Threads running; but increases the
chance of SystemStackError exceptions and segmentation faults (SIGSEGV).
These environment variables are available since Ruby 2.0.0.
All values are specified in bytes.
-.Pp
.Bl -hang -compact -width "RUBY_THREAD_MACHINE_STACK_SIZE"
.It Ev RUBY_THREAD_VM_STACK_SIZE
VM stack size used at thread creation.
default: 131072 (32-bit CPU) or 262144 (64-bit)
-.Pp
.It Ev RUBY_THREAD_MACHINE_STACK_SIZE
Machine stack size used at thread creation.
default: 524288 or 1048575
-.Pp
.It Ev RUBY_FIBER_VM_STACK_SIZE
VM stack size used at fiber creation.
default: 65536 or 131072
-.Pp
.It Ev RUBY_FIBER_MACHINE_STACK_SIZE
Machine stack size used at fiber creation.
default: 262144 or 524288
-.Pp
.El
.Sh SEE ALSO
.Bl -hang -compact -width "http://www.ruby-lang.org/123"
@@ -607,23 +586,19 @@
.It https://www.ruby-toolbox.com/
Comprehensive catalog of Ruby libraries.
.El
-.Pp
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after they've been fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (https://bugs.ruby-lang.org/).
+And you can report other bugs and feature requests via the
+.Lk https://bugs.ruby-lang.org/ "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
Ruby is designed and implemented by
-.An Yukihiro Matsumoto Aq ma...@netlab.jp .
+.An Yukihiro Matsumoto Aq Mt ma...@netlab.jp .
.Pp
See
-.Aq Pa https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors
+.Lk https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors
for contributors to Ruby.
Here is a patch that improves the semantic macros used in manpages, along
with various cleanup and linting. The pages now pass the mdocml linter.
- Semantically mark up links and email addresses
- Use correct syntax for document title
- Delete empty paragraphs
- Escape ASCII apostrophes when necessary
- New sentence, new line (troff requires this to get the spacing right)
Changelog entry:
* man/erb.1: [DOC] Improve semantics of -mdoc macros. Cleanup to
pass the Mandoc project's manual linter.
* man/goruby.1: ditto.
* man/irb.1: ditto.
* man/ri.1: ditto.
* man/ruby.1: ditto.
Index: man/erb.1
===================================================================
--- man/erb.1 (revision 49621)
+++ man/erb.1 (working copy)
@@ -1,7 +1,7 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt ERB(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt ERB 1
+.Os
.Sh NAME
.Nm erb
.Nd Ruby Templating
@@ -14,8 +14,7 @@
.Op Fl T Ar mode
.Op Fl r Ar library
.Op Fl -
-.Op file ...
-.Pp
+.Op Ar file ...
.Sh DESCRIPTION
.Nm
is a command line front-end for
@@ -29,29 +28,24 @@
.Nm
is a part of
.Nm Ruby .
-.Pp
.Sh OPTIONS
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -version
Prints the version of
.Nm .
-.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
-Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+Specifies the default value(s) for external encodings and internal encoding.
+Values should be separated with colon (:).
.Pp
You can omit the one for internal encodings, then the value
.Pf ( Li "Encoding.default_internal" ) will be nil.
-.Pp
.It Fl P
Evaluates lines starting with
.Li "%"
as Ruby code and removes the tailing EOLs.
-.Pp
.It Fl S Ar level
Specifies the safe level in which eRuby script will run.
-.Pp
.It Fl T Ar mode
Specifies trim mode (default 0).
.Ar mode
@@ -59,55 +53,42 @@
.Bl -hang -offset indent
.It Sy 0
EOL remains after the embedded ruby script is evaluated.
-.Pp
.It Sy 1
EOL is removed if the line ends with
.Li "%>" .
-.Pp
.It Sy 2
EOL is removed if the line starts with
.Li "<%"
and ends with
.Li "%>" .
-.Pp
.It Sy -
EOL is removed if the line ends with
.Li "-%>" .
And leading whitespaces are removed if the erb directive starts with
.Li "<%-" .
-.Pp
.El
-.Pp
.It Fl U
-can be one of
Sets the default value for internal encodings
.Pf ( Li "Encoding.default_internal" ) to UTF-8.
-.Pp
.It Fl d
.It Fl -debug
Turns on debug mode.
.Li "$DEBUG"
will be set to true.
-.Pp
.It Fl h
.It Fl -help
Prints a summary of the options.
-.Pp
.It Fl n
Used with
.Fl x .
Prepends the line number to each line in the output.
-.Pp
.It Fl v
Enables verbose mode.
.Li "$VERBOSE"
will be set to true.
-.Pp
.It Fl x
Converts the eRuby script into Ruby script and prints it without line numbers.
-.Pp
.El
-.Pp
.Sh EXAMPLES
Here is an eRuby script
.Bd -literal -offset indent
@@ -131,9 +112,8 @@
<library>2, 3, 5, 7</library>
</erb-example>
.Ed
-.Pp
.Sh SEE ALSO
-.Xr ruby 1 .
+.Xr ruby 1
.Pp
And see
.Xr ri 1
@@ -140,18 +120,16 @@
documentation for
.Li "ERB"
class.
-.Pp
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after being fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (http://bugs.ruby-lang.org).
+And you can report other bugs and feature requests via the
+.Lk http://bugs.ruby-lang.org "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
-Written by Masatoshi SEKI.
+.An -nosplit
+Written by
+.An Masatoshi SEKI .
Index: man/goruby.1
===================================================================
--- man/goruby.1 (revision 49621)
+++ man/goruby.1 (working copy)
@@ -1,13 +1,13 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt GORUBY(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt GORUBY 1
+.Os
.Sh NAME
.Nm goruby
.Nd A code-golfer's best friend
.Sh SYNOPSIS
.Nm
-.Op options ...
+.Op Ar options ...
.Op Fl -
.Op Ar program_file
.Op Ar argument ...
@@ -23,7 +23,6 @@
.Bd -literal -offset indent
require"date";puts Date.today
.Ed
-.Pp
.Sh OPTIONS
.Sy goruby
takes same options as
@@ -33,7 +32,8 @@
.It Xr ruby 1
The stiff version of Ruby interpreter.
.El
-.Pp
.Sh AUTHORS
-Originally written by Nobuyoshi Nakada and developed by the
-Ruby core team.
+.An -nosplit
+Originally written by
+.An Nobuyoshi Nakada
+and developed by the Ruby core team.
Index: man/irb.1
===================================================================
--- man/irb.1 (revision 49621)
+++ man/irb.1 (working copy)
@@ -1,7 +1,7 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt IRB(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt IRB 1
+.Os
.Sh NAME
.Nm irb
.Nd Interactive Ruby Shell
@@ -22,90 +22,82 @@
.Op Fl -back-trace-limit Ar n
.Op Fl -irb_debug Ar n
.Op Fl -
-.Op program_file
-.Op argument ...
-.Pp
+.Op Ar program_file
+.Op Ar argument ...
.Sh DESCRIPTION
.Nm
-is the REPL(read-eval-print loop) environment for Ruby programs.
-.Pp
+is the REPL (read-eval-print loop) environment for Ruby programs.
.Sh OPTIONS
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -version
Prints the version of
.Nm .
-.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
-Same as `ruby -E' .
-Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+Same as
+.Sq ruby -E .
+Specifies the default value(s) for external encodings and internal encoding.
+Values should be separated with colon (:).
.Pp
You can omit the one for internal encodings, then the value
.Pf ( Li "Encoding.default_internal" ) will be nil.
-.Pp
.It Fl I Ar path
-Same as `ruby -I' .
+Same as
+.Sq ruby -I .
Specifies
.Li $LOAD_PATH
directory
-.Pp
.It Fl U
-Same as `ruby -U' .
+Same as
+.Sq ruby -U .
Sets the default value for internal encodings
.Pf ( Li "Encoding.default_internal" ) to UTF-8.
-.Pp
.It Fl d
-Same as `ruby -d' .
+Same as
+.Sq ruby -d .
Sets
.Li $DEBUG
to true.
-.Pp
.It Fl f
Suppresses read of
.Pa ~/.irbrc .
-.Pp
.It Fl h
.It Fl -help
Prints a summary of the options.
-.Pp
.It Fl m
Bc mode (load mathn, fraction or matrix are available)
-.Pp
.It Fl r Ar library
-Same as `ruby -r'.
+Same as
+.Sq ruby -r .
Causes irb to load the library using require.
-.Pp
.It Fl -inspect
-Uses `inspect' for output (default except for bc mode)
-.Pp
+Uses
+.Sq inspect
+for output (default except for bc mode)
.It Fl -noinspect
Doesn't use inspect for output
-.Pp
.It Fl -readline
Uses Readline extension module.
-.Pp
.It Fl -noreadline
Doesn't use Readline extension module.
-.Pp
.It Fl -prompt Ar mode
.It Fl -prompt-mode Ar mode
-Switch prompt mode. Pre-defined prompt modes are
-`default', `simple', `xmp' and `inf-ruby'.
-.Pp
+Switch prompt mode.
+Pre-defined prompt modes are
+.Sq default ,
+.Sq simple ,
+.Sq xmp
+and
+.Sq inf-ruby .
.It Fl -inf-ruby-mode
Uses prompt appropriate for inf-ruby-mode on emacs.
Suppresses --readline.
-.Pp
.It Fl -simple-prompt
Makes prompts simple.
-.Pp
.It Fl -noprompt
No prompt mode.
-.Pp
.It Fl -tracer
Displays trace for each execution of commands.
-.Pp
.It Fl -back-trace-limit Ar n
Displays backtrace top
.Ar n
@@ -112,16 +104,12 @@
and tail
.Ar n Ns .
The default value is 16.
-.Pp
.It Fl -irb_debug Ar n
Sets internal debug level to n (not for popular use)
-.Pp
.El
-.Pp
.Sh ENVIRONMENT
.Bl -tag -width "RUBYLIB_PREFIX" -compact
.It Ev IRBRC
-.Pp
.El
.Pp
Also
@@ -128,14 +116,11 @@
.Nm
depends on same variables as
.Xr ruby 1 .
-.Pp
.Sh FILES
.Bl -tag -width "RUBYLIB_PREFIX" -compact
.It Pa ~/.irbrc
Personal irb initialization.
-.Pp
.El
-.Pp
.Sh EXAMPLES
.Dl % irb
.Dl irb(main):001:0> Ic 1 + 1
@@ -153,21 +138,18 @@
.Dl => :ok
.Dl irb(main):009:0> Ic quit
.Dl %
-.Pp
.Sh SEE ALSO
-.Xr ruby 1 .
-.Pp
+.Xr ruby 1
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after being fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (http://bugs.ruby-lang.org).
+And you can report other bugs and feature requests via the
+.Lk http://bugs.ruby-lang.org "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
-Written by Keiju ISHITSUKA.
+.An -nosplit
+Written by
+.An Keiju ISHITSUKA .
Index: man/ri.1
===================================================================
--- man/ri.1 (revision 49621)
+++ man/ri.1 (working copy)
@@ -1,7 +1,7 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt RI(1) "" "Ruby Programmers Reference Guide"
-.Os UNIX
+.Dt RI 1
+.Os
.Sh NAME
.Nm ri
.Nd Ruby API reference front end
@@ -40,8 +40,8 @@
for both class and instance methods
.El
.Pp
-All class names may be abbreviated to their minimum unambiguous form. If a name
-is ambiguous, all valid options will be listed.
+All class names may be abbreviated to their minimum unambiguous form.
+If a name is ambiguous, all valid options will be listed.
.Pp
For example:
.Bd -literal -offset indent
@@ -54,25 +54,22 @@
Note that shell quoting may be required for method names containing
punctuation:
.Bd -literal -offset indent
-ri 'Array.[]'
+ri \(aqArray.[]\(aq
ri compact\!
.Ed
.Sh OPTIONS
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -version
Prints the version of
.Nm .
-.Pp
.It Fl T
.It Fl -no-pager
Send output directly to stdout, rather than to a pager.
-.Pp
.It Fl d Ar directory
.It Fl -doc-dir Ns = Ns Ar directory
-List of directories from which to source documentation in addition to the standard
-directories. May be repeated.
-.Pp
+List of directories from which to source documentation in addition to the
+standard directories.
+May be repeated.
.It Fl f Ar FORMAT
.It Fl -fmt Ar FORMAT
.It Fl -format Ns = Ns FORMAT
@@ -80,9 +77,11 @@
.Pp
ansi, bs, html, plain, simple
.Pp
-Use 'bs' (backspace) with most pager programs. To use ANSI, either disable the
+Use
+.Sq bs
+(backspace) with most pager programs.
+To use ANSI, either disable the
pager or tell the pager to allow control characters.
-.Pp
.It Fl i
.It Fl -interactive
This makes
@@ -92,13 +91,12 @@
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
+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
.It Fl -list-doc-dirs
List the directories from which ri will source documentation on stdout and exit.
-.Pp
.It Fl -no-standard-docs
Do not include documentation from the Ruby standard library,
.Pa site_lib ,
@@ -109,73 +107,59 @@
.Fl -no-system , Fl -no-site , Fl -no-gems ,
and
.Fl -no-home .
-.Pp
.It Fl - Ns Oo Cm no- Oc Ns Cm system
-Include documentation from Ruby's standard library. Defaults to true.
-.Pp
+Include documentation from Ruby's standard library.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm site
- Include documentation from libraries installed in site_lib. Defaults to true.
-.Pp
+ Include documentation from libraries installed in site_lib.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm gems
-Include documentation from RubyGems. Defaults to true.
-.Pp
+Include documentation from RubyGems.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm home
-Include documentation stored in ~/.rdoc. Defaults to true.
-.Pp
+Include documentation stored in ~/.rdoc.
+Defaults to true.
.It Fl - Ns Oo Cm no- Oc Ns Cm use-cache
Whether or not to use
.Nm Ns
-.Ns 's cache. True by default.
-.Pp
+\&'s cache.
+True by default.
.It Fl w Ar width
.It Fl -width Ns = Ns Ar width
Set the width of the output.
-.Pp
.El
-.Pp
.Sh ENVIRONMENT
.Bl -tag -width "USERPROFILE" -compact
-.Pp
.It Ev RI
Additional options.
-.Pp
.It Ev PAGER
Used as the name of pager program for displaying.
-.Pp
.It Ev HOME
.It Ev USERPROFILE
.It Ev HOMEPATH
Path to user's home directory.
.El
-.Pp
.Sh FILES
.Bl -tag -width "USERPROFILE" -compact
-.Pp
.It Pa ~/.ri
Caches recently referenced documents here.
-.Pp
.It Pa ~/.rdoc
Searches user-wide documents here.
-.Pp
.El
-.Pp
.Sh SEE ALSO
+.Xr gem 1 ,
+.Xr rdoc 1 ,
.Xr ruby 1
-.Xr rdoc 1
-.Xr gem 1
-.Pp
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after being fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (http://bugs.ruby-lang.org).
+And you can report other bugs and feature requests via the
+.Lk http://bugs.ruby-lang.org "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
-Written by Dave Thomas
-.Aq da...@pragmaticprogrammer.com
+.An -nosplit
+Written by
+.An Dave Thomas Aq Mt da...@pragmaticprogrammer.com .
Index: man/ruby.1
===================================================================
--- man/ruby.1 (revision 49621)
+++ man/ruby.1 (working copy)
@@ -1,8 +1,8 @@
.\"Ruby is copyrighted by Yukihiro Matsumoto <ma...@netlab.jp>.
.Dd November 7, 2012
-.Dt RUBY(1) "" "Ruby Programmers Reference Guide"
+.Dt RUBY 1
.\".Dt RUBY 1
-.Os UNIX
+.Os
.Sh NAME
.Nm ruby
.Nd Interpreted object-oriented scripting language
@@ -31,8 +31,10 @@
.Op Ar argument ...
.Sh DESCRIPTION
Ruby is an interpreted scripting language for quick and easy
-object-oriented programming. It has many features to process text
-files and to do system management tasks (like in Perl). It is simple,
+object-oriented programming.
+It has many features to process text
+files and to do system management tasks (like in Perl).
+It is simple,
straight-forward, and extensible.
.Pp
If you want a language for easy object-oriented programming, or you
@@ -45,75 +47,69 @@
.It Sy "Interpretive"
Ruby is an interpreted language, so you don't have to recompile
programs written in Ruby to execute them.
-.Pp
.It Sy "Variables have no type (dynamic typing)"
-Variables in Ruby can contain data of any type. You don't have to
-worry about variable typing. Consequently, it has a weaker compile
+Variables in Ruby can contain data of any type.
+You don't have to
+worry about variable typing.
+Consequently, it has a weaker compile
time check.
-.Pp
.It Sy "No declaration needed"
You can use variables in your Ruby programs without any declarations.
Variable names denote their scope - global, class, instance, or local.
-.Pp
.It Sy "Simple syntax"
Ruby has a simple syntax influenced slightly from Eiffel.
-.Pp
.It Sy "No user-level memory management"
-Ruby has automatic memory management. Objects no longer referenced
+Ruby has automatic memory management.
+Objects no longer referenced
from anywhere are automatically collected by the garbage collector
built into the interpreter.
-.Pp
.It Sy "Everything is an object"
Ruby is a purely object-oriented language, and was so since its
-creation. Even such basic data as integers are seen as objects.
-.Pp
+creation.
+Even such basic data as integers are seen as objects.
.It Sy "Class, inheritance, and methods"
Being an object-oriented language, Ruby naturally has basic
features like classes, inheritance, and methods.
-.Pp
.It Sy "Singleton methods"
-Ruby has the ability to define methods for certain objects. For
+Ruby has the ability to define methods for certain objects.
+For
example, you can define a press-button action for certain widget by
-defining a singleton method for the button. Or, you can make up your
+defining a singleton method for the button.
+Or, you can make up your
own prototype based object system using singleton methods, if you want
to.
-.Pp
.It Sy "Mix-in by modules"
Ruby intentionally does not have the multiple inheritance as it is a
-source of confusion. Instead, Ruby has the ability to share
-implementations across the inheritance tree. This is often called a
+source of confusion.
+Instead, Ruby has the ability to share
+implementations across the inheritance tree.
+This is often called a
.Sq Mix-in .
-.Pp
.It Sy "Iterators"
Ruby has iterators for loop abstraction.
-.Pp
.It Sy "Closures"
In Ruby, you can objectify the procedure.
-.Pp
.It Sy "Text processing and regular expressions"
Ruby has a bunch of text processing features like in Perl.
-.Pp
.It Sy "M17N, character set independent"
-Ruby supports multilingualized programming. Easy to process texts
+Ruby supports multilingualized programming.
+Easy to process texts
written in many different natural languages and encoded in many
different character encodings, without dependence on Unicode.
-.Pp
.It Sy "Bignums"
With built-in bignums, you can for example calculate factorial(400).
-.Pp
.It Sy "Reflection and domain specific languages"
-Class is also an instance of the Class class. Definition of classes and methods
-is an expression just as 1+1 is. So your programs can even write and modify programs.
+Class is also an instance of the Class class.
+Definition of classes and methods
+is an expression just as 1+1 is.
+So your programs can even write and modify programs.
Thus you can write your application in your own programming language on top of Ruby.
-.Pp
.It Sy "Exception handling"
-As in Java(tm).
-.Pp
+As in Java\(tm.
.It Sy "Direct access to the OS"
Ruby can use most
.Ux
system calls, often used in system programming.
-.Pp
.It Sy "Dynamic loading"
On most
.Ux
@@ -120,64 +116,64 @@
systems, you can load object files into the Ruby interpreter
on-the-fly.
.It Sy "Rich libraries"
-Libraries called "builtin libraries" and "standard libraries" are bundled with Ruby.
-And you can obtain more libraries via the package management system called `RubyGems'.
+Libraries called
+.Dq builtin libraries
+and
+.Dq standard libraries
+are bundled with Ruby.
+And you can obtain more libraries via the package management system called
+.Sq RubyGems .
.Pp
Moreover there are thousands of Ruby projects on GitHub
.Aq Pa https://github.com/languages/Ruby .
.El
-.Pp
.Sh OPTIONS
Ruby interpreter accepts following command-line options (switches).
They are quite similar to those of
.Xr perl 1 .
.Bl -tag -width "1234567890123" -compact
-.Pp
.It Fl -copyright
Prints the copyright notice.
-.Pp
.It Fl -version
Prints the version of Ruby interpreter.
-.Pp
.It Fl 0 Ns Op Ar octal
(The digit
.Dq zero . )
Specifies the input record separator
.Pf ( Li "$/" )
-as an octal number. If no digit is given, the null character is taken
-as the separator. Other switches may follow the digits.
+as an octal number.
+If no digit is given, the null character is taken
+as the separator.
+Other switches may follow the digits.
.Fl 00
turns Ruby into paragraph mode.
.Fl 0777
makes Ruby read whole file at once as a single string since there is
no legal character with that value.
-.Pp
.It Fl C Ar directory
.It Fl X Ar directory
Causes Ruby to switch to the directory.
-.Pp
.It Fl E Ar external Ns Op : Ns Ar internal
.It Fl -encoding Ar external Ns Op : Ns Ar internal
-Specifies the default value(s) for external encodings and internal encoding. Values should be separated with colon (:).
+Specifies the default value(s) for external encodings and internal encoding.
+Values should be separated with colon (:).
.Pp
You can omit the one for internal encodings, then the value
.Pf ( Li "Encoding.default_internal" ) will be nil.
-.Pp
.It Fl -external-encoding Ns = Ns Ar encoding
.It Fl -internal-encoding Ns = Ns Ar encoding
Specify the default external or internal character encoding
-.Pp
.It Fl F Ar pattern
Specifies input field separator
.Pf ( Li "$;" ) .
-.Pp
.It Fl I Ar directory
-Used to tell Ruby where to load the library scripts. Directory path
+Used to tell Ruby where to load the library scripts.
+Directory path
will be added to the load-path variable
.Pf ( Li "$:" ) .
-.Pp
.It Fl K Ar kcode
-Specifies KANJI (Japanese) encoding. The default value for script encodings
+Specifies KANJI (Japanese) encoding.
+The default value for script encodings
.Pf ( Li "__ENCODING__" ) and external encodings ( Li "Encoding.default_external" ) will be the specified one.
.Ar kcode
can be one of
@@ -184,22 +180,19 @@
.Bl -hang -offset indent
.It Sy e
EUC-JP
-.Pp
.It Sy s
Windows-31J (CP932)
-.Pp
.It Sy u
UTF-8
-.Pp
.It Sy n
ASCII-8BIT (BINARY)
.El
-.Pp
.It Fl S
Makes Ruby use the
.Ev PATH
environment variable to search for script, unless its name begins
-with a slash. This is used to emulate
+with a slash.
+This is used to emulate
.Li #!
on machines that don't support it, in the following manner:
.Bd -literal -offset indent
@@ -207,30 +200,32 @@
# This line makes the next one a comment in Ruby \e
exec /usr/local/bin/ruby -S $0 $*
.Ed
-.Pp
.It Fl T Ns Op Ar level=1
Turns on taint checks at the specified level (default 1).
-.Pp
.It Fl U
Sets the default value for internal encodings
.Pf ( Li "Encoding.default_internal" ) to UTF-8.
-.Pp
.It Fl W Ns Op Ar level=2
Turns on verbose mode at the specified level without printing the version
-message at the beginning. The level can be;
+message at the beginning.
+The level can be;
.Bl -hang -offset indent
.It Sy 0
-Verbose mode is "silence". It sets the
+Verbose mode is
+.Dq silence .
+It sets the
.Li "$VERBOSE"
to nil.
-.Pp
.It Sy 1
-Verbose mode is "medium". It sets the
+Verbose mode is
+.Dq medium .
+It sets the
.Li "$VERBOSE"
to false.
-.Pp
.It Sy 2 (default)
-Verbose mode is "verbose". It sets the
+Verbose mode is
+.Dq verbose .
+It sets the
.Li "$VERBOSE"
to true.
.Fl W Ns
@@ -238,7 +233,6 @@
.Fl w
.
.El
-.Pp
.It Fl a
Turns on auto-split mode when used with
.Fl n
@@ -247,41 +241,38 @@
In auto-split mode, Ruby executes
.Dl $F = $_.split
at beginning of each loop.
-.Pp
.It Fl c
Causes Ruby to check the syntax of the script and exit without
-executing. If there are no syntax errors, Ruby will print
+executing.
+If there are no syntax errors, Ruby will print
.Dq Syntax OK
to the standard output.
-.Pp
.It Fl d
.It Fl -debug
Turns on debug mode.
.Li "$DEBUG"
will be set to true.
-.Pp
.It Fl e Ar command
Specifies script from command-line while telling Ruby not to search
the rest of the arguments for a script file name.
-.Pp
.It Fl h
.It Fl -help
Prints a summary of the options.
-.Pp
.It Fl i Ar extension
-Specifies in-place-edit mode. The extension, if specified, is added
-to old file name to make a backup copy. For example:
+Specifies in-place-edit mode.
+The extension, if specified, is added
+to old file name to make a backup copy.
+For example:
.Bd -literal -offset indent
% echo matz > /tmp/junk
% cat /tmp/junk
matz
-% ruby -p -i.bak -e '$_.upcase!' /tmp/junk
+% ruby -p -i.bak -e \(aq$_.upcase!\(aq /tmp/junk
% cat /tmp/junk
MATZ
% cat /tmp/junk.bak
matz
.Ed
-.Pp
.It Fl l
(The lowercase letter
.Dq ell . )
@@ -291,7 +282,6 @@
.Li "$/" ,
and secondly chops every line read using
.Li chop! .
-.Pp
.It Fl n
Causes Ruby to assume the following loop around your script, which
makes it iterate over file name arguments somewhat like
@@ -304,22 +294,21 @@
...
end
.Ed
-.Pp
.It Fl p
Acts mostly same as -n switch, but print the value of variable
.Li "$_"
-at the each end of the loop. For example:
+at the each end of the loop.
+For example:
.Bd -literal -offset indent
-% echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
+% echo matz | ruby -p -e \(aq$_.tr! "a-z", "A-Z"\(aq
MATZ
.Ed
-.Pp
.It Fl r Ar library
-Causes Ruby to load the library using require. It is useful when using
+Causes Ruby to load the library using require.
+It is useful when using
.Fl n
or
.Fl p .
-.Pp
.It Fl s
Enables some switch parsing for switches after script name but before
any file name arguments (or before a
@@ -326,10 +315,11 @@
.Fl - ) .
Any switches found there are removed from
.Li ARGV
-and set the corresponding variable in the script. For example:
+and set the corresponding variable in the script.
+For example:
.Bd -literal -offset indent
#! /usr/local/bin/ruby -s
-# prints "true" if invoked with `-xyz' switch.
+# prints "true" if invoked with \(aq-xyz\(aq switch.
print "true\en" if $xyz
.Ed
.Pp
@@ -338,34 +328,37 @@
does not always contain the full pathname, so you need the
.Fl S
switch to tell Ruby to search for the script if necessary (to handle embedded
-spaces and such). A better construct than
+spaces and such).
+A better construct than
.Li "$*"
would be
.Li ${1+"$@"} ,
but it does not work if the script is being interpreted by
.Xr csh 1 .
-.Pp
.It Fl v
-Enables verbose mode. Ruby will print its version at the beginning
+Enables verbose mode.
+Ruby will print its version at the beginning
and set the variable
.Li "$VERBOSE"
-to true. Some methods print extra messages if this variable is true.
+to true.
+Some methods print extra messages if this variable is true.
If this switch is given, and no other switches are present, Ruby quits
after printing its version.
-.Pp
.It Fl w
Enables verbose mode without printing version message at the
-beginning. It sets the
+beginning.
+It sets the
.Li "$VERBOSE"
variable to true.
-.Pp
.It Fl x Ns Op Ar directory
-Tells Ruby that the script is embedded in a message. Leading garbage
+Tells Ruby that the script is embedded in a message.
+Leading garbage
will be discarded until the first line that starts with
.Dq #!
and contains the string,
.Dq ruby .
-Any meaningful switches on that line will be applied. The end of the script
+Any meaningful switches on that line will be applied.
+The end of the script
must be specified with either
.Li EOF ,
.Li "^D" ( Li "control-D" ) ,
@@ -374,15 +367,15 @@
.Li __END__ .
If the directory name is specified, Ruby will switch to that directory
before executing script.
-.Pp
.It Fl y
.It Fl -yydebug
DO NOT USE.
.Pp
-Turns on compiler debug mode. Ruby will print a bunch of internal
-state messages during compilation. Only specify this switch you are going to
+Turns on compiler debug mode.
+Ruby will print a bunch of internal
+state messages during compilation.
+Only specify this switch you are going to
debug the Ruby interpreter.
-.Pp
.It Fl -disable- Ns Ar FEATURE
.It Fl -enable- Ns Ar FEATURE
Disables (or enables) the specified
@@ -391,23 +384,22 @@
.Bl -tag -width "--disable-rubyopt" -compact
.It Fl -disable-gems
.It Fl -enable-gems
-Disables (or enables) RubyGems libraries. By default, Ruby will load the latest
-version of each installed gem. The
+Disables (or enables) RubyGems libraries.
+By default, Ruby will load the latest
+version of each installed gem.
+The
.Li Gem
constant is true if RubyGems is enabled, false if otherwise.
-.Pp
.It Fl -disable-rubyopt
.It Fl -enable-rubyopt
Ignores (or considers) the
.Ev RUBYOPT
-environment variable. By default, Ruby considers the variable.
-.Pp
+environment variable.
+By default, Ruby considers the variable.
.It Fl -disable-all
.It Fl -enable-all
Disables (or enables) all features.
-.Pp
.El
-.Pp
.It Fl -dump Ns = Ns Ar target
DO NOT USE.
.Pp
@@ -417,31 +409,29 @@
.Bl -hang -offset indent
.It Sy insns
disassembled instructions
-.Pp
.El
.Pp
Only specify this switch if you are going to debug the Ruby interpreter.
-.Pp
.It Fl -verbose
Enables verbose mode without printing version message at the
-beginning. It sets the
+beginning.
+It sets the
.Li "$VERBOSE"
variable to true.
If this switch is given, and no other switches are present, Ruby quits
after printing its version.
.El
-.Pp
.Sh ENVIRONMENT
.Bl -tag -width "RUBYSHELL" -compact
.It Ev RUBYLIB
A colon-separated list of directories that are added to Ruby's
library load path
-.Pf ( Li "$:" ) . Directories from this environment variable are searched
+.Pf ( Li "$:" ) .
+Directories from this environment variable are searched
before the standard load path is searched.
.Pp
e.g.:
.Dl RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
-.Pp
.It Ev RUBYOPT
Additional Ruby options.
.Pp
@@ -453,21 +443,21 @@
.Fl -disable- Ns Ar FEATURE
and
.Fl -enable- Ns Ar FEATURE .
-.Pp
.It Ev RUBYPATH
A colon-separated list of directories that Ruby searches for
Ruby programs when the
.Fl S
-flag is specified. This variable precedes the
+flag is specified.
+This variable precedes the
.Ev PATH
environment variable.
-.Pp
.It Ev RUBYSHELL
-The path to the system shell command. This environment variable is
-enabled for only mswin32, mingw32, and OS/2 platforms. If this
+The path to the system shell command.
+This environment variable is
+enabled for only mswin32, mingw32, and OS/2 platforms.
+If this
variable is not defined, Ruby refers to
.Ev COMSPEC .
-.Pp
.It Ev PATH
Ruby refers to the
.Ev PATH
@@ -481,7 +471,6 @@
.Bd -literal -offset indent
% gem help
.Ed
-.Pp
.Sh GC ENVIRONMENT
The Ruby garbage collector (GC) tracks objects in fixed-sized slots,
but each object may have auxillary memory allocations handled by the
@@ -490,9 +479,12 @@
.Xr calloc 3 ,
and
.Xr realloc 3 ) .
-In this documentatation, the "heap" refers to the Ruby object heap
-of fixed-sized slots, while "malloc" refers to auxillary
-allocations commonly referred to as the "process heap".
+In this documentatation, the
+.Dq heap
+refers to the Ruby object heap of fixed-sized slots, while
+.Dq malloc
+refers to auxillary allocations commonly referred to as the
+.Dq process heap .
Thus there are at least two possible ways to trigger GC:
.Bl -hang -offset indent
.It Sy 1
@@ -499,7 +491,6 @@
Reaching the object limit.
.It Sy 2
Reaching the malloc limit.
-.Pp
.El
In Ruby 2.1, the generational GC was introduced and the limits are divided
into young and old generations, providing two additional ways to trigger
@@ -515,90 +506,78 @@
the the following 11 environment variables:
.Bl -hang -compact -width "RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR"
.It Ev RUBY_GC_HEAP_INIT_SLOTS
-Initial allocation slots. Introduced in Ruby 2.1, default: 10000.
-.Pp
+Initial allocation slots.
+Introduced in Ruby 2.1, default: 10000.
.It Ev RUBY_GC_HEAP_FREE_SLOTS
Prepare at least this amount of slots after GC.
Allocate this number slots if there are not enough slots.
Introduced in Ruby 2.1, default: 4096
-.Pp
.It Ev RUBY_GC_HEAP_GROWTH_FACTOR
Increase allocation rate of heap slots by this factor.
Introduced in Ruby 2.1, default: 1.8, minimum: 1.0 (no growth)
-.Pp
.It Ev RUBY_GC_HEAP_GROWTH_MAX_SLOTS
Allocation rate is limited to this number of slots,
preventing excessive allocation due to RUBY_GC_HEAP_GROWTH_FACTOR.
Introduced in Ruby 2.1, default: 0 (no limit)
-.Pp
.It Ev RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR
Perform a full GC when the number of old objects is more than R * N,
where R is this factor and N is the number of old objects after the
last full GC.
Introduced in Ruby 2.1.1, default: 2.0
-.Pp
.It Ev RUBY_GC_MALLOC_LIMIT
The initial limit of young generation allocation from the malloc-family.
GC will start when this limit is reached.
Default: 16MB
-.Pp
.It Ev RUBY_GC_MALLOC_LIMIT_MAX
The maximum limit of young generation allocation from malloc before GC starts.
Prevents excessive malloc growth due to RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR.
Introduced in Ruby 2.1, default: 32MB.
-.Pp
.It Ev RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR
Increases the limit of young generation malloc calls, reducing
GC frequency but increasing malloc growth until RUBY_GC_MALLOC_LIMIT_MAX
is reached.
Introduced in Ruby 2.1, default: 1.4, minimum: 1.0 (no growth)
-.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT
The initial limit of old generation allocation from malloc,
a full GC will start when this limit is reached.
Introduced in Ruby 2.1, default: 16MB
-.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT_MAX
The maximum limit of old generation allocation from malloc before a
full GC starts.
Prevents excessive malloc growth due to RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR.
Introduced in Ruby 2.1, default: 128MB
-.Pp
.It Ev RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR
Increases the limit of old generation malloc allocation, reducing full
GC frequency but increasing malloc growth until RUBY_GC_OLDMALLOC_LIMIT_MAX
is reached.
Introduced in Ruby 2.1, default: 1.2, minimum: 1.0 (no growth)
-.Pp
.El
.Sh STACK SIZE ENVIRONMENT
Stack size environment variables are implementation-dependent and
-subject to change with different versions of Ruby. The VM stack is used
-for pure-Ruby code and managed by the virtual machine. Machine stack is
+subject to change with different versions of Ruby.
+The VM stack is used
+for pure-Ruby code and managed by the virtual machine.
+Machine stack is
used by the operating system and its usage is dependent on C extensions
-as well as C compiler options. Using lower values for these may allow
+as well as C compiler options.
+Using lower values for these may allow
applications to keep more Fibers or Threads running; but increases the
chance of SystemStackError exceptions and segmentation faults (SIGSEGV).
These environment variables are available since Ruby 2.0.0.
All values are specified in bytes.
-.Pp
.Bl -hang -compact -width "RUBY_THREAD_MACHINE_STACK_SIZE"
.It Ev RUBY_THREAD_VM_STACK_SIZE
VM stack size used at thread creation.
default: 131072 (32-bit CPU) or 262144 (64-bit)
-.Pp
.It Ev RUBY_THREAD_MACHINE_STACK_SIZE
Machine stack size used at thread creation.
default: 524288 or 1048575
-.Pp
.It Ev RUBY_FIBER_VM_STACK_SIZE
VM stack size used at fiber creation.
default: 65536 or 131072
-.Pp
.It Ev RUBY_FIBER_MACHINE_STACK_SIZE
Machine stack size used at fiber creation.
default: 262144 or 524288
-.Pp
.El
.Sh SEE ALSO
.Bl -hang -compact -width "http://www.ruby-lang.org/123"
@@ -607,23 +586,19 @@
.It https://www.ruby-toolbox.com/
Comprehensive catalog of Ruby libraries.
.El
-.Pp
.Sh REPORTING BUGS
-.Bl -bullet
-.Li Security vulnerabilities should be reported via an email to
-.Aq secu...@ruby-lang.org Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt secu...@ruby-lang.org .
Reported problems will be published after they've been fixed.
.Pp
-.Li And you can report other bugs and feature requests via the
-Ruby Issue Tracking System (https://bugs.ruby-lang.org/).
+And you can report other bugs and feature requests via the
+.Lk https://bugs.ruby-lang.org/ "Ruby Issue Tracking System" .
Do not report security vulnerabilities
via the system because it publishes the vulnerabilities immediately.
-.El
.Sh AUTHORS
Ruby is designed and implemented by
-.An Yukihiro Matsumoto Aq ma...@netlab.jp .
+.An Yukihiro Matsumoto Aq Mt ma...@netlab.jp .
.Pp
See
-.Aq Pa https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors
+.Lk https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors
for contributors to Ruby.
Reply all
Reply to author
Forward
0 new messages