From 206d8c77bc0ac15a5c4e7a56aeff2e9fc280e6a3 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Wed, 15 Sep 2010 14:57:27 -0700 Subject: doc: update HACKING for documentation contributions We switched to RDoc 2.5.x long ago and this should clarify some documentation preferences I have. (cherry picked from commit 505a9e72d320fe3ae521ceb0f381c1c0f5ae4389) --- HACKING | 13 ++++++++++--- 1 file 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 -- cgit v1.2.3-24-ge0c7