Documentation roadmap?

On Aug 25, 2006, at 5:56 PM, Rich Morin wrote:

>> Most syntax highlighting hurts my eyes.  (Insert
quotes about
>> taste+disputes.)  I might like it if I could 
select a highlighting
>> scheme (with 'none' as the default) when
generating the rdoc, but
>> cringe at the though of having a default scheme
foisted upon me.
>
> What he said...

Guess coloring the stdlib docs might not be a great idea
then.  What  
about some sort of easy configuration?  So the users that
liked it  
could get it but not all users were forced.  If we can't
count on  
server-side scripts, seems like javascript cookies would do.
-Mat

On Aug 25, 2006, at 22:29, Mat Schaffer wrote:

> Guess coloring the stdlib docs might not be a great
idea then.  What 
> about some sort of easy configuration?  So the users
that liked it 
> could get it but not all users were forced.  If we
can't count on 
> server-side scripts, seems like javascript cookies
would do.

Server-side scripts? Cookies? Are we talking about
syntax-color-coding 
a user's locally generated HTML-based (or maybe ri-based
with terminal 
ANSI codes) RDoc-generated documentation, or color-coding
the 
documentation hosted at ruby-doc.org?

The former would (should?) be a matter of picking a
non-default 
template when generating the documentation. The
latter...well, although 
I'm definitely pro-color-coding, I don't think it's a
good idea for the 
ruby-doc archives.  Colored source that uses a different
scheme than 
the one I'm used to can be worse than none at all.

On Aug 25, 2006, at 22:29, Mat Schaffer wrote:

> Guess coloring the stdlib docs might not be a great
idea then.  What 
> about some sort of easy configuration?  So the users
that liked it 
> could get it but not all users were forced.  If we
can't count on 
> server-side scripts, seems like javascript cookies
would do.

Server-side scripts? Cookies? Are we talking about
syntax-color-coding 
a user's locally generated HTML-based (or maybe ri-based
with terminal 
ANSI codes) RDoc-generated documentation, or color-coding
the 
documentation hosted at ruby-doc.org?

The former would (should?) be a matter of picking a
non-default 
template when generating the documentation. The
latter...well, although 
I'm definitely pro-color-coding, I don't think it's a
good idea for the 
ruby-doc archives.  Colored source that uses a different
scheme than 
the one I'm used to can be worse than none at all.

On Aug 28, 2006, at 1:31 PM, Dave Howell wrote:
> On Aug 25, 2006, at 22:29, Mat Schaffer wrote:
>
>> Guess coloring the stdlib docs might not be a great
idea then.   
>> What about some sort of easy configuration?  So the
users that  
>> liked it could get it but not all users were
forced.  If we can't  
>> count on server-side scripts, seems like javascript
cookies would do.
>
> Server-side scripts? Cookies? Are we talking about
syntax-color- 
> coding a user's locally generated HTML-based (or maybe
ri-based  
> with terminal ANSI codes) RDoc-generated documentation,
or color- 
> coding the documentation hosted at ruby-doc.org?
>
> The former would (should?) be a matter of picking a
non-default  
> template when generating the documentation. The
latter...well,  
> although I'm definitely pro-color-coding, I don't
think it's a good  
> idea for the ruby-doc archives.  Colored source that
uses a  
> different scheme than the one I'm used to can be worse
than none at  
> all.

To be honest I was just throwing ideas out here on this
thread and we  
sort of got into a debate about colorization in general. 
Color  
coding in the [view source] already exists, implemented via
<span>  
tags and CSS.  And only on ruby code.
I'd love to see the feature work for C code and examples in
the  
documentation as well.

The javascript/server-side comment was just an attempt at a 

compromise between those who want it and those who don't. 
You could  
use javascript to permit viewers of any rdoc (not just
stdlib) to set  
and retain preferences about syntax colorization.

Sorry if I'm causing confusion,
Mat

On Aug 28, 2006, at 1:31 PM, Dave Howell wrote:
> On Aug 25, 2006, at 22:29, Mat Schaffer wrote:
>
>> Guess coloring the stdlib docs might not be a great
idea then.   
>> What about some sort of easy configuration?  So the
users that  
>> liked it could get it but not all users were
forced.  If we can't  
>> count on server-side scripts, seems like javascript
cookies would do.
>
> Server-side scripts? Cookies? Are we talking about
syntax-color- 
> coding a user's locally generated HTML-based (or maybe
ri-based  
> with terminal ANSI codes) RDoc-generated documentation,
or color- 
> coding the documentation hosted at ruby-doc.org?
>
> The former would (should?) be a matter of picking a
non-default  
> template when generating the documentation. The
latter...well,  
> although I'm definitely pro-color-coding, I don't
think it's a good  
> idea for the ruby-doc archives.  Colored source that
uses a  
> different scheme than the one I'm used to can be worse
than none at  
> all.

To be honest I was just throwing ideas out here on this
thread and we  
sort of got into a debate about colorization in general. 
Color  
coding in the [view source] already exists, implemented via
<span>  
tags and CSS.  And only on ruby code.
I'd love to see the feature work for C code and examples in
the  
documentation as well.

The javascript/server-side comment was just an attempt at a 

compromise between those who want it and those who don't. 
You could  
use javascript to permit viewers of any rdoc (not just
stdlib) to set  
and retain preferences about syntax colorization.

Sorry if I'm causing confusion,
Mat