cleaning up build instruction files

2 files changed, 117 insertions, 60 deletions

diff --git a/ruby/BuildInstructionsLinux.md b/ruby/BuildInstructionsLinux.md
index e13d5dda574..4bca4b13ab6 100644
--- a/ruby/BuildInstructionsLinux.md
+++ b/ruby/BuildInstructionsLinux.md
@@ -1,16 +1,22 @@
 # Building Ice for Ruby on Linux
 
-This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms.
+This document describes how to build and install Ice for Ruby from source code.
+If you prefer, you can also download [binary distributions][1] for the supported
+platforms.
 
 ## Ruby Build Requirements
 
 ### Operating Systems and Compilers
 
-Ice for Ruby is expected to build and run properly on any recent Linux distribution for x86 and x86_64, and was extensively tested using the operating systems and Ruby versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html).
+Ice for Ruby is expected to build and run properly on any recent Linux distribution
+for x86 and x86_64, and was extensively tested using the operating systems and Ruby
+versions listed for our [supported platforms][2].
 
 ### Ruby Versions
 
-Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or binary installation of Ruby. If you use an RPM installation, the following packages are required:
+Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or binary
+installation of Ruby. If you use an RPM installation, the following packages are
+required:
 
     ruby
     ruby-devel
@@ -18,17 +24,21 @@ Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or bina
 
 ### Ice Development Kit
 
-You will need the Ice development kit for C++, which you can install as a binary distribution or compile from source yourself.
+You will need the Ice development kit for C++, which you can install as a binary
+distribution or compile from source yourself.
 
 ## Building the Ruby Extension
 
-The instructions for compiling the Ice extension assume that you have already installed Ruby.
+The instructions for compiling the Ice extension assume that you have already
+installed Ruby.
 
-If you installed Ruby in a non-standard location, set the ```RUBY_HOME``` environment variable to the installation directory. For example:
+If you installed Ruby in a non-standard location, set the `RUBY_HOME` environment
+variable to the installation directory. For example:
 
     $ export RUBY_HOME=/opt/ruby
 
-If you have not built Ice for C++ in the ```cpp``` subdirectory, set ```ICE_HOME``` to the directory of your Ice for C++ installation. For example:
+If you have not built Ice for C++ in the `cpp` subdirectory, set `ICE_HOME`
+to the directory of your Ice for C++ installation. For example:
 
     $ export ICE_HOME=/opt/Ice
 
@@ -36,9 +46,10 @@ Change to the Ice for Ruby source subdirectory:
 
     $ cd ruby
 
-Edit ```config/Make.rules```and adjust as necessary. For example, you may wish to enable ```OPTIMIZE```.
+Edit `config/Make.rules`and adjust as necessary. For example, you may wish to
+enable `OPTIMIZE`.
 
-Run ```make``` to build the extension.
+Run `make` to build the extension.
 
 ## Installing Ice for Ruby
 
@@ -46,9 +57,16 @@ You can perform an automated installation with the following command:
 
     $ make install
 
-This process uses the ```prefix``` variable in ```config/Make.rules``` as the installation's root directory. The subdirectory ```<prefix>/ruby``` is created as a copy of the local ```ruby``` directory and contains the Ice for Ruby extension library (```IceRuby.so```) as well as Ruby source code. Using this installation method requires that you modify your environment as described in *Using Ice for Ruby* below.
+This process uses the `prefix` variable in `config/Make.rules` as the
+installation's root directory. The subdirectory `<prefix>/ruby` is created
+as a copy of the local `ruby` directory and contains the Ice for Ruby
+extension library (`IceRuby.so`) as well as Ruby source code. Using this
+installation method requires that you modify your environment as described
+in *Using Ice for Ruby* below.
 
-Another option is to copy the contents of the local ```ruby``` directory to your Ruby installation's ```site_ruby``` directory. For example, if you installed Ruby via RPM, you can use the steps below:
+Another option is to copy the contents of the local `ruby` directory to your
+Ruby installation's `site_ruby` directory. For example, if you installed Ruby
+via RPM, you can use the steps below:
 
     # cd <Ice source directory>/ruby/ruby
     # sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -)
@@ -61,17 +79,21 @@ There is no need to modify your environment if you use this approach.
 
 ## Configuring your Environment for Ruby
 
-The Ruby interpreter must be able to locate the Ice extension. If you used the automated installation described above, you need to define the ```RUBYLIB``` environment variable as follows:
+The Ruby interpreter must be able to locate the Ice extension. If you used the
+automated installation described above, you need to define the `RUBYLIB`
+environment variable as follows:
 
     $ export RUBYLIB=/opt/Ice/ruby:$RUBYLIB
 
-This example assumes that your Ice for Ruby installation is located in the ```/opt/Ice``` directory.
+This example assumes that your Ice for Ruby installation is located in the
+`/opt/Ice` directory.
 
-You must also modify ```LD_LIBRARY_PATH``` to include the directory ```/opt/Ice/lib```:
+You must also modify `LD_LIBRARY_PATH` to include the directory `/opt/Ice/lib`:
 
     $ export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH
 
-To verify that Ruby can load the Ice extension successfully, open a command window and start the interpreter using ```irb```:
+To verify that Ruby can load the Ice extension successfully, open a command
+window and start the interpreter using `irb`:
 
     > irb
     irb(main):001:0>
@@ -80,41 +102,50 @@ At the prompt, enter
 
     require "Ice"
 
-If the interpreter responds with the value true, the Ice extension was loaded successfully. Enter ```exit``` to quit the interpreter.
+If the interpreter responds with the value true, the Ice extension was loaded
+successfully. Enter `exit` to quit the interpreter.
 
 ## Running the Ruby Tests
 
-The ```test``` subdirectory contains Ruby implementations of the core Ice test suite. Python is required to run the test suite.
+The `test` subdirectory contains Ruby implementations of the core Ice test suite.
+Python is required to run the test suite.
 
-The test suites require that the Ice for C++ tests be built in the ```cpp``` subdirectory of this source distribution.
+The test suites require that the Ice for C++ tests be built in the `cpp`
+subdirectory of this source distribution.
 
-Open a command window and change to the top-level directory. At the command prompt, execute:
+Open a command window and change to the top-level directory. At the command
+prompt, execute:
 
     > python allTests.py
 
-You can also run tests individually by changing to the test directory and running this command:
+You can also run tests individually by changing to the test directory and
+running this command:
 
     > python run.py
 
-If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```.
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
 
 ## SELinux Notes for Ruby
 
-If SELinux is enabled on your RHEL system, you may encounter this error message when Ruby attempts to load the Ice extension:
+If SELinux is enabled on your RHEL system, you may encounter this error message
+when Ruby attempts to load the Ice extension:
 
     cannot restore segment prot after reloc: Permission denied
 
 There are two ways to solve this problem:
 
-- Change the default security context for the Ice extension using the following command:
+- Change the default security context for the Ice extension using the following
+command:
 
-   ```
-   $ chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so
-   ```
+        $ chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so
 
-    Replace ```/opt/Ice``` with your installation directory.
-- Disable SELinux completely by adding the following line to your ```/etc/sysconfig/selinux``` file:
+    Replace `/opt/Ice` with your installation directory.
 
-   ```
-   SELINUX=disabled
-   ```
+- Disable SELinux completely by adding the following line to your
+`/etc/sysconfig/selinux` file:
+
+        SELINUX=disabled
+
+[1]: https://zeroc.com/download.html
+[2]: https://zeroc.com/platforms_3_6_0.html
diff --git a/ruby/BuildInstructionsWindows.md b/ruby/BuildInstructionsWindows.md
index ce2a5a82f59..4d985134a84 100644
--- a/ruby/BuildInstructionsWindows.md
+++ b/ruby/BuildInstructionsWindows.md
@@ -1,12 +1,16 @@
 # Building Ice for Ruby on Windows
 
-This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms.
+This page describes how to build and install Ice for Ruby from source code.
+If you prefer, you can also download [binary distributions][1] for the
+supported platforms.
 
 ## Ruby Build Requirements
 
 ### Operating Systems
 
-Ice for Ruby is expected to build and run properly on Windows, and was extensively tested using the operating systems and Ruby versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html).
+Ice for Ruby is expected to build and run properly on Windows, and was extensively
+tested using the operating systems and Ruby versions listed for our [supported
+platforms][2].
 
 ### Prerequisites
 
@@ -17,16 +21,21 @@ To build Ice for Ruby you must have the following:
 - Ruby Development Kit 4.7.2
 - mingw 4.7.3 (only for 32-bit builds)
 
-The Ruby distribution for Windows uses the MinGW compiler, therefore MinGW is the only C++ compiler supported by Ice for Ruby.
+The Ruby distribution for Windows uses the MinGW compiler, therefore MinGW is the
+only C++ compiler supported by Ice for Ruby.
 
-The instructions in this file make the following assumptions about your build environment:
+The instructions in this file make the following assumptions about your build
+environment:
 
-1. You have installed the Ice 3.6.0 distribution using the ZeroC installer. The default installation directory is ```C:\Program Files (x86)\ZeroC\Ice-3.6.0```.
-1. You have installed Ruby 2.2.1 using the Windows installer. The default installation directory is ```C:\Ruby221```.
-1. You have installed the Ruby Development Kit 4.7.2 in ```C:\RubyDevKit-4.7.2```.
-1. For 32-bit builds, you have installed mingw 4.7.3 in ```C:\mingw-4.7.3```.
+1. You have installed the Ice 3.6.0 distribution using the ZeroC installer. The
+default installation directory is `C:\Program Files (x86)\ZeroC\Ice-3.6.0`.
+2. You have installed Ruby 2.2.1 using the Windows installer. The default installation
+directory is `C:\Ruby221`.
+3. You have installed the Ruby Development Kit 4.7.2 in `C:\RubyDevKit-4.7.2`.
+4. For 32-bit builds, you have installed mingw 4.7.3 in `C:\mingw-4.7.3`.
 
-If you selected different installation directories, you will need to modify the relevant path names in the steps below to match your configuration.
+If you selected different installation directories, you will need to modify the
+relevant path names in the steps below to match your configuration.
 
 ## Building the Ruby Extension
 
@@ -34,34 +43,36 @@ Open a Windows command prompt and add Ruby to your environment:
 
     > C:\Ruby221\bin\setrbvars.bat
 
-Run the ```devkitvars.bat``` batch file from the Ruby development kit to setup your environment:
+Run the `devkitvars.bat` batch file from the Ruby development kit to setup your
+environment:
 
     > C:\RubyDevKit-4.7.2\devkitvars.bat
 
 If you are building for Windows 32-bit:
 
-1. Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby development kit:
+1. Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby
+development kit:
 
-    ```
-    > set PATH=C:\mingw-4.7.3\bin;%PATH%
-    ```
+        > set PATH=C:\mingw-4.7.3\bin;%PATH%
 
 1. Then double-check the desired version of g++ is in your PATH:
 
-    ```
-    > g++ -dumpversion
-    4.7.3
-    ```
+        > g++ -dumpversion
+        4.7.3
 
 Change to the Ice for Ruby source directory:
 
     > cd ruby
 
-If you have not built Ice for C++ in the ```cpp``` subdirectory, set the ```ICE_HOME``` environment variable to point to your Ice installation. This path must contain forward slashes (/) as directory separators, and cannot contain any space. If your Ice installation's path contains any space, use the DOS 8-character name as a work-around, for example:
+If you have not built Ice for C++ in the `cpp` subdirectory, set the `ICE_HOME`
+environment variable to point to your Ice installation. This path must contain
+forward slashes (/) as directory separators, and cannot contain any space.
+If your Ice installation's path contains any space, use the DOS 8-character
+name as a work-around, for example:
 
     > set ICE_HOME=C:/PROGRA~2/Ice-3.6.0
 
-You can use ```dir /x``` to get this DOS name, for example:
+You can use `dir /x` to get this DOS name, for example:
 
     > cd c:\
     > dir /x
@@ -82,17 +93,24 @@ You can perform an automated installation with the following command:
 
     > make install
 
-This process uses the ```prefix``` variable in ```config\Make.rules``` as the installation's root directory. The subdirectory ```<prefix>\ruby``` is created as a copy of the local ruby directory and contains the Ice for Ruby extension library (```IceRuby.so```) as well as Ruby source code. Using this installation method requires that you modify your environment as described below.
+This process uses the `prefix` variable in `config\Make.rules` as the installation's
+root directory. The subdirectory `<prefix>\ruby` is created as a copy of the local
+ruby directory and contains the Ice for Ruby extension library (`IceRuby.so`) as
+well as Ruby source code. Using this installation method requires that you modify
+your environment as described below.
 
 ## Configuring your Environment for Ruby
 
-The Ruby interpreter must be able to locate the Ice extension. One way to configure the interpreter is to define the ```RUBYLIB``` environment variable as follows:
+The Ruby interpreter must be able to locate the Ice extension. One way to configure
+the interpreter is to define the `RUBYLIB` environment variable as follows:
 
     > set RUBYLIB=C:\Ice-3.6.0\ruby
 
-This example assumes your Ice for Ruby installation is located in the ```C:\Ice-3.6.0``` directory.
+This example assumes your Ice for Ruby installation is located in the `C:\Ice-3.6.0`
+directory.
 
-In addition, you must modify your PATH environment variable to include the following directories:
+In addition, you must modify your PATH environment variable to include the following
+directories:
 
     C:\Program Files (x86)\ZeroC\Ice-3.6.0\bin
     C:\Ice-3.6.0\bin
@@ -103,16 +121,24 @@ At a command prompt, you can set your PATH as shown below:
 
 ## Running the Ruby Tests
 
-The ```test``` subdirectory contains Ruby implementations of the core Ice test suite. Python is required to run the test suite.
+The `test` subdirectory contains Ruby implementations of the core Ice test suite.
+Python is required to run the test suite.
 
-The test suites require that the Ice for C++ tests be built in the ```cpp``` subdirectory of this source distribution.
+The test suites require that the Ice for C++ tests be built in the `cpp`
+subdirectory of this source distribution.
 
-Open a command window and change to the top-level directory. At the command prompt, execute:
+Open a command window and change to the top-level directory. At the command
+prompt, execute:
 
     > python allTests.py
 
-You can also run tests individually by changing to the test directory and running this command:
+You can also run tests individually by changing to the test directory and
+running this command:
 
     > python run.py
 
-If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```.
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
+
+[1]: https://zeroc.com/download.html
+[2]: https://zeroc.com/platforms_3_6_0.html