ruby-core

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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- man/erb.1	(revision 49621)
+++ man/erb.1	(working copy)
@@ -1,7 +1,7 @@
 .\"Ruby is copyrighted by Yukihiro Matsumoto <[email protected]>.
 .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 encodi=
ng. Values should be separated with colon (:).
+Specifies the default value(s) for external encodings and internal encodi=
ng.
+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 num=
bers.
-.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 [email protected] Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt [email protected] .
 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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- man/goruby.1	(revision 49621)
+++ man/goruby.1	(working copy)
@@ -1,13 +1,13 @@
 .\"Ruby is copyrighted by Yukihiro Matsumoto <[email protected]>.
 .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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- man/irb.1	(revision 49621)
+++ man/irb.1	(working copy)
@@ -1,7 +1,7 @@
 .\"Ruby is copyrighted by Yukihiro Matsumoto <[email protected]>.
 .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 encodi=
ng. Values should be separated with colon (:).
+Same as
+.Sq ruby -E .
+Specifies the default value(s) for external encodings and internal encodi=
ng.
+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 =3D> :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 [email protected] Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt [email protected] .
 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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- man/ri.1	(revision 49621)
+++ man/ri.1	(working copy)
@@ -1,7 +1,7 @@
 .\"Ruby is copyrighted by Yukihiro Matsumoto <[email protected]>.
 .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 =3D 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 =3D Ns FORMAT
@@ -80,9 +77,11 @@
 .Pp
 ansi, bs, html, plain, simple
 .Pp
-Use 'bs' (backspace) with most pager programs. To use ANSI, either disabl=
e 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.  I=
t 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 r=
eadline
 is supported) when viewing a class.
-.Pp
 .It Fl -list-doc-dirs
 List the directories from which ri will source documentation on stdout an=
d 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 =3D 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 [email protected] Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt [email protected] .
 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 [email protected]
+.An -nosplit
+Written by
+.An Dave Thomas Aq Mt [email protected] .
Index: man/ruby.1
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- man/ruby.1	(revision 49621)
+++ man/ruby.1	(working copy)
@@ -1,8 +1,8 @@
 .\"Ruby is copyrighted by Yukihiro Matsumoto <[email protected]>.
 .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 m=
ethods
-is an expression just as 1+1 is. So your programs can even write and modi=
fy 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 t=
op 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 calle=
d `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 calle=
d
+.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 encodi=
ng. Values should be separated with colon (:).
+Specifies the default value(s) for external encodings and internal encodi=
ng.
+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 =3D Ns Ar encoding
 .It Fl -internal-encoding Ns =3D 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 encodin=
gs
+Specifies KANJI (Japanese) encoding.
+The default value for script encodings
 .Pf ( Li "__ENCODING__" ) and external encodings ( Li "Encoding.default_e=
xternal" ) 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=3D1
 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=3D2
 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 =3D $_.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 embe=
dded
-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 scr=
ipt
+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 goin=
g 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 =3D 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=3D"$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 divide=
d
 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 st=
arts.
 Prevents excessive malloc growth due to RUBY_GC_MALLOC_LIMIT_GROWTH_FACTO=
R.
 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_FA=
CTOR.
 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_M=
AX
 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 [email protected] Ns
-.Li .
+Security vulnerabilities should be reported via an email to
+.Aq Mt [email protected] .
 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 [email protected] .
+.An Yukihiro Matsumoto Aq Mt [email protected] .
 .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.