|author||Eric Wong <firstname.lastname@example.org>||2010-09-15 14:57:27 -0700|
|committer||Eric Wong <email@example.com>||2010-10-04 20:13:45 +0000|
We switched to RDoc 2.5.x long ago and this should clarify some documentation preferences I have. (cherry picked from commit 505a9e72d320fe3ae521ceb0f381c1c0f5ae4389)
1 files changed, 10 insertions, 3 deletions
@@ -16,8 +16,8 @@ Tests are good, but slow tests make development slow, so we make tests
faster (in parallel) with GNU make (instead of Rake) and avoiding
-Users of GNU-based systems (such as GNU/Linux) usually have GNU make installed
-as "make" instead of "gmake".
+Users of GNU-based systems (such as GNU/Linux) usually have GNU make
+installed as "make" instead of "gmake".
Since we don't load RubyGems by default, loading Rack properly requires
setting up RUBYLIB to point to where Rack is located. Not loading
@@ -57,11 +57,18 @@ programming experience will come in handy (or be learned) here.
-We use RDoc 2.4.x with Darkfish for documentation as much as possible,
+We use RDoc 2.5.x with Darkfish for documentation as much as possible,
if you're on Ruby 1.8 you want to install the latest "rdoc" gem. Due to
the lack of RDoc-to-manpage converters we know about, we're writing
manpages in Markdown and converting to troff/HTML with Pandoc.
+Please wrap documentation at 72 characters-per-line or less (long URLs
+are exempt) so it is comfortably readable from terminals.
+When referencing mailing list posts, use
+"http://mid.gmane.org/$MESSAGE_ID" if possible since the Message-ID
+remains searchable even if Gmane becomes unavailable.
=== Ruby/C Compatibility
We target Ruby 1.8.6+, 1.9 and will target Rubinius as it becomes