6.11 Using Ruby section:

- Document most common variables for Ruby related ports

Approved by:	remko

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -5144,7 +5144,127 @@ _DOCSDIR=       .
     <sect1 id="using-ruby">
       <title>Using Ruby</title>
 
-      <para>This section is yet to be written.</para>
+      <table frame="none">
+	<title>Useful variables for ports that use Ruby</title>
+
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Variable</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry><makevar>USE_RUBY</makevar></entry>
+
+	      <entry>The port requires Ruby.</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>USE_RUBY_EXTCONF</makevar></entry>
+
+	      <entry>The port uses <filename>extconf.rb</filename> to
+		configure.</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>USE_RUBY_SETUP</makevar></entry>
+
+	      <entry>The port uses <filename>setup.rb</filename> to
+		configure.</entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>RUBY_SETUP</makevar></entry>
+
+	      <entry>Set to the alternative name of
+		<filename>setup.rb</filename>.  Common value is
+		<filename>install.rb</filename>.</entry>
+	    </row>
+
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <para>The following table shows the selected variables available to port
+	authors via the ports infrastructure.  These variables should be used
+	to install files into their proper locations.  Use them in
+	<filename>pkg-plist</filename> as much as possible.  These variables
+	should not be redefined in the port.</para>
+
+      <table frame="none">
+	<title>Selected read-only variables for ports that use Ruby</title>
+
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Variable</entry>
+	      <entry>Description</entry>
+	      <entry>Example value</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+
+	    <row>
+	      <entry><makevar>RUBY_PKGNAMEPREFIX</makevar></entry>
+
+	      <entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to distinguish
+		packages for different Ruby versions.</entry>
+
+	      <entry><literal>ruby18-</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>RUBY_VERSION</makevar></entry>
+
+	      <entry>Full version of Ruby in the form of
+		<literal>x.y.z</literal>.</entry>
+
+	      <entry><literal>1.8.2</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>RUBY_SITELIBDIR</makevar></entry>
+
+	      <entry>Architecture independent libraries installation
+		path.</entry>
+
+	      <entry><literal>/usr/local/lib/ruby/site_ruby/1.8</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>RUBY_SITEARCHILIBDIR</makevar></entry>
+
+	      <entry>Architecture dependent libraries installation
+		path.</entry>
+
+	      <entry><literal>/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>RUBY_MODDOCDIR</makevar></entry>
+
+	      <entry>Module documentation installation path.</entry>
+
+	      <entry><literal>/usr/local/share/doc/ruby18/patsy</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry><makevar>RUBY_MODEXAMPLESDIR</makevar></entry>
+
+	      <entry>Module examples installation path.</entry>
+
+	      <entry><literal>/usr/local/share/examples/ruby18/patsy</literal></entry>
+	    </row>
+
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <para>A complete list of available variables can be found in
+	<filename>/usr/ports/Mk/bsd.ruby.mk</filename>.</para>
+
     </sect1>
 
     <sect1 id="using-sdl">