summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <normalperson@yhbt.net>2010-09-15 14:57:27 -0700
committerEric Wong <normalperson@yhbt.net>2010-10-04 20:13:45 +0000
commit206d8c77bc0ac15a5c4e7a56aeff2e9fc280e6a3 (patch)
tree3525380aba01add7b37dc6d0c8ee1efbb244e0cf
parent0bf83bb4246aefe172e2c5adcb8b28bda9dae283 (diff)
We switched to RDoc 2.5.x long ago and this should clarify
some documentation preferences I have.
(cherry picked from commit 505a9e72d320fe3ae521ceb0f381c1c0f5ae4389)
-rw-r--r--HACKING13
1 files changed, 10 insertions, 3 deletions
diff --git a/HACKING b/HACKING
index 6a05d4b..781c4ca 100644
--- a/HACKING
+++ b/HACKING
@@ -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
 RubyGems.
 
-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.
 
 === Documentation
 
-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