Re: Documentation guidlines (Was: 2nd try at date/format.rb & pty.c)

On Aug 20, 2006, at 6:46 AM, Randy Kramer wrote:
> On Sunday 20 August 2006 04:39 am, Eric Hodel wrote:
>> On Aug 19, 2006, at 5:46 PM, Eric Hodel wrote:
>>> * Documentation wrapped to 80 characters
>
> Sorry, I missed the original post that included that (and hope I  
> have the
> attribution right), but want to comment (or question) now.
>
>
> I'm assuming that the guideline cited above is aimed at (possibly  
> among other things), aimed at (i.e., against) documentation that  
> requires horizontal scrolling to view the full length of a line?
>
> While I am fiercely against documentation that requires such  
> horizontal
> scrolling, I'm not sure that is the best way to achieve that  
> objective.
>
> In general, I much prefer when documentation is not "hard  
> wrapped" (with
> embedded \n (or similar) characters) but is free to be "soft  
> wrapped" by the displaying application (and thus be wrapped  
> (dynamically) to the width of the current viewing window).
>
> (I may be totally off-base here--if this is for documentation  
> intended to be embedded in the code as comments or similar, maybe  
> that guideline (or a
> similar one, for a (somewhat/slightly) shorter line is appropriate.)
>
> If my comment is totally off-base, sorry for the waste of bandwidth.

The embedded documentation should be wrapped because RDoc takes care  
of it for us.  In ri, paragraphs can be re-wrapped to any width (- 
w).  In HTML it Just Works.

For code 80 characters is a reasonable limitation, it keeps the code  
looking good for ri and sets a limit on code complexity.  Also, all  
other documentation fits in 80 characters.

-- 
Eric Hodel - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com