New RDoc template, and a question

ruby-talk
1

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

You can see what this looks like at

 http://rdoc.sourceforge.net/newdoc/

Click on one of the Ruby method names in the top-right pane, then click
on the [source] link to see the effect.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

Cheers

Dave

2

FWIW, it works fine in Konqueror 3.0.5 in
Red Hat 8. Also in my (fairly old) IE on
Win98.

Minor nit: I do think the dark background
makes the source a little hard to read.

Hal

···

----- Original Message -----
From: “Dave Thomas” dave@pragprog.com
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Tuesday, July 22, 2003 11:41 PM
Subject: New RDoc template, and a question

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

You can see what this looks like at

 http://rdoc.sourceforge.net/newdoc/

Click on one of the Ruby method names in the top-right pane, then click
on the [source] link to see the effect.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

–
Hal Fulton
hal9000@hypermetrics.com

3

Dave Thomas wrote:

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

You can see what this looks like at

http://rdoc.sourceforge.net/newdoc/

Click on one of the Ruby method names in the top-right pane, then click
on the [source] link to see the effect.

I really like it! I must say, I find the colour scheme a little difficult to read, and my poor old eyes need a slightly larger font, particularly for the source code listings. I’m sure that’s all configurable via CSS, though.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

It works fine in Mozilla 1.4, but in IE 6.0, the [Source] tags don’t appear in the listings.

That doesn’t worry me, because I only use Mozilla, but I figured I’d test it.

Harry O.

4

Wow. Purdy.

I really like it, although I happen to be biased because those are nearly the
colours I use in XEmacs anyhow. :wink: On the other hand, I think the font
could stand to be a bit bigger by default.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

My guess is that as long as the stuff it uses is cross-browser for current
browsers it should be ok.

This is, afterall, designed for Ruby programmers, no? My mom might not have
updated her browser since she bought her computer, but my mom isn’t the
target audience for this sort of thing. I’d suggest that as long as it fails
gracefully and/or warns users with older browsers that they’re missing out it
should be fine.

Ben

···

On Wed July 23 2003 12:41 am, Dave Thomas wrote:

5

Very nice! I’d like to see this be the default, especially since its being
based on CSS would encourage people to send in customisations.

martin

···

Dave Thomas dave@pragprog.com wrote:

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

6

I agree that it looks great – except that the source code is to tiny
compared to the other text. I would recommend regular text at 1em and
source at 0.8em.

It works in Safari and in a text browser (links). Beyond that, I don’t
see why older generation IE and Netscape browsers need to be supported.

Regards,

Mark

···

On Wednesday, July 23, 2003, at 12:41 AM, Dave Thomas wrote:

[snip]
You can see what this looks like at

http://rdoc.sourceforge.net/newdoc/

Click on one of the Ruby method names in the top-right pane, then
click on the [source] link to see the effect.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?
[snip]

7

wrote (more or less):

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

You can see what this looks like at

http://rdoc.sourceforge.net/newdoc/

Click on one of the Ruby method names in the top-right pane, then click
on the [source] link to see the effect.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

It depends if you’re publishing only for desktop machines, or for
desktops and also for handheld devices, which tend to have less
compute power for powerful browsers, as well as more limited displays
(e.g. monochrome)

Cheers,
Euan
Gawnsoft: http://www.gawnsoft.co.sr
Symbian/Epoc wiki: http://html.dnsalias.net:1122
Smalltalk links (harvested from comp.lang.smalltalk) http://html.dnsalias.net/gawnsoft/smalltalk

···

On Wed, 23 Jul 2003 13:41:16 +0900, Dave Thomas dave@pragprog.com

8

Michael Granger has produced a wonderful new RDoc template, which looks
…
could make this the default style, or do we still need to support the
previous generation?

FWIW, I’m using IE 5.1.7 on Mac OS 9.2.2. When the Source link is clicked,
a dark block appear with no code. Always the same size too.

On my VIC-20 the text wraps at the 22nd column, making it difficult
to follow the source. (Yes, that is a joke.)

I’m not suggesting that you should support either of these configurations,
just giving some feedback :slight_smile:

Regards,
JJ

···

on 7/23/03 12:41 AM, Dave Thomas at dave@pragprog.com wrote:

–
Regards,
JJ

Be Kind, Be Careful, Be Yourself

9

Dave Thomas wrote:

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

Hm. I’m using Opera 6.11 on Linux, and superclass and filename links at
the top of the page in the lower frame appear as all-white rectangles
until I mouse over. However, when I I tell Opera to emulate MSIE 5.0
and refresh, it looks pretty normal.

AFAIK, the “Identify as MSIE 5.0” option only changes the User-Agent
string that Opera sends to the server and reports through JavaScript.
Getting different behavior based on the User-Agent string is kinda
annoying …

···

–
Frank Mitchell (frankm each bayarea period net)

Please avoid sending me Word or PowerPoint attachments.
See We Can Put an End to Word Attachments - GNU Project - Free Software Foundation

10

Looks great, although I will agree with those that say the source (&
pre) code font needs to be a bit larger. The source code colors are OK
except for the comments that could use a brighter red for better
contrast against the black background.

Hey, I’ve got aging eyes. What can I say?

···

On Wed, 2003-07-23 at 00:41, Dave Thomas wrote:

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

–
– Jim Weirich jweirich@one.net http://onestepback.org

“Beware of bugs in the above code; I have only proved it correct,
not tried it.” – Donald Knuth (in a memo to Peter van Emde Boas)

11

It’s plain super, where can i get one? :slight_smile:

···

–
sdmitry -=- Dmitry V. Sabanin
MuraveyLabs.

12

The hard thing when looking at something like this is that one has no
earthly idea if the thing they’re seeing is supposed to look that way, or if
it really does look funky on their box. My minor nit is with the links in
the top three frames; in my browser, at least, the text shows up with a
light blue background that is different than the white background of the
frame. If it’s currently looking that way everywhere, it seems it might be
better to make them both the same background color. If it’s only local,
well, I’m running IE 6 on Windows 2000 (which is sufficient explanation for
any funky behavior :-/ ).

Other than that, it’s very, very slick! Thanks Michael and Dave!

Nathaniel

<:((><

···

Dave Thomas [mailto:dave@pragprog.com] wrote:

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

13

Dave Thomas wrote:

You can see what this looks like at

http://rdoc.sourceforge.net/newdoc/

My glass-is-half-empty $0.02 :slight_smile:

Inline source is cool, but colors for the source seem weird. Dark red,
black, sky blue and hazel-ish brown – dunno, I like the previous color
scheme better. Having a different background color for links I think
clutters up the page. I’d rather see a sans-serif font. The black text
on dark grey background for method headers isn’t as readable to me. Too
many background colors (in one view I can see 5 at one time: white,
light gray, dark grey, light blue, black). In general, it seems busier
than the previous default.

···

–

Chris
http://clabs.org/blogki

14

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

You can see what this looks like at

 http://rdoc.sourceforge.net/newdoc/

Click on one of the Ruby method names in the top-right pane, then click
on the [source] link to see the effect.

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

Considering I use w3m for browsing docs while coding, yes, support old
browsers.

Also, people turn JS off.

Also, for I in /usr/share/doc//.html; do lynx -dump “$I” > "$(echo $I

sed -e ‘s/.html/.txt/’)"; done

Also, good design is to make anything that uses javascript gracefully
degrade so that /all content/ is visible and navigable with no
javascript. It’s not that hard with the right thinking cap on.

Also, scripts shouldn’t be inlined whenever possible – make the
javascript an external library, referenced by a
tag. It’s even possible to add event handlers via the DOM that way, so
you can have pure HTML files, and the script is entirely orthagonal.
It’s not easy to think that way, but once you do, your script is
cacheable and your code is faster, and your HTML is smaller and also
completely backward-compatible. I would love to see all the “onclick”
events handled that way, and even the “[Source]” links added that way.

Also, I would desparately want a “show all source” option. I’m good at
reading through reams of online text to find what I want, but terrible
at grabbing the mouse while reading.

That said, I like the concept.

Ari

···

On Tue, 2003-07-22 at 22:41, Dave Thomas wrote:

15

Dave Thomas wrote:

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

The behavior is fine in IE 6 and Mozilla 1.3.1.
All links have an odd purple glow; I’m guessing, though, that this is
intentional. Not sure how this helps usability.

The black background for the source code, though, makes the text hard to
read.

If the use of scripting and CSS is acceptable across a sufficient number
of browsers, perhaps a CSS switcher script (sucah as described at [0])
should be included as a well, with a reasonable slection of style sheets
(big fonts, or plain colors, or whatever).

James

[0] Alternative Style: Working With Alternate Style Sheets – A List Apart

···

Cheers

Dave

16

The consensus seems to be that the 

 font is too small, some people

don’t like the “glowing purple” links, and that the light-on-dark

colors are icky. =:)


The font-size is easily remedied: just eliminate the ‘pre {…}’ line

of the CSS.


As for code-highlighting colors: I hesitate to ask, but is there some

reasonable way of determining what the least-offensive color scheme for

highlighting code is?


Since most of the complaints are about CSS-related things, might I

suggest a feature for RDoc: a --css= or --stylesheet=

command-line flag that allowed the %style_url% field to be set when

rdoc was invoked would help eliminate most people’s aesthetic

differences, I think.


If you want me to make any changes, Dave, just let me know what you

want and I’ll send you a patch or two.



···

On Tuesday, Jul 22, 2003, at 21:41 US/Pacific, Dave Thomas wrote:




Now the question: this new template relies on DHTML, Javascript, and a

lot of CSS. Has the world of browsers advanced to the point where I

could make this the default style, or do we still need to support the

previous generation?




–

Michael Granger ged@FaerieMUD.org

Rubymage, Believer, Architect

The FaerieMUD Consortium http://www.FaerieMUD.org/
17

looks cool !
btw, imo too many colors are line noise, I’d use the same color used
in the top 3 windows’ links for the source backgorund.

But, actually… I’ll plug something new in this thread:
this html template made the same choice from the old one:
to have three windows in the top of the page.
ImVho this is bad.
I have to move the slider every time that I’m looking for something,
even when using documentation for not large projects.

Anybody ever thought about moving one (or two) of this windows to the
side of the main one (someway like the java html api)?
Most of monitors should have more space to use in X than Y…

···

il Wed, 23 Jul 2003 13:41:16 +0900, Dave Thomas dave@pragprog.com ha scritto::

Michael Granger has produced a wonderful new RDoc template, which looks
about 1067 times better than any HTML I ever produced. What’s even
better: if you use the “inline source” option, the source is inlined
into the page, but is hidden until you click on the ‘source’ button.

You can see what this looks like at

http://rdoc.sourceforge.net/newdoc/
18

… but in IE 6.0, the [Source] tags don’t
appear in the listings.

Whoops! I was looking at a class (Exception) whose methods didn’t have [Source] tags.

19

Hal E. Fulton wrote:

FWIW, it works fine in Konqueror 3.0.5 in
Red Hat 8. Also in my (fairly old) IE on
Win98.

Minor nit: I do think the dark background
makes the source a little hard to read.

I agree.

A minor oddity: after I click on the source button, a second click
doesn’t make the source disppear. I have to move the mouse off the
source button and back on it before clicking, and then it works. This is
with Konqueror 3.1.0. It’s ok in Mozilla, so I guess it’s just Konq.

20

If it works in lynx, it should work in anything. In lynx, I see the source
code always there (the ‘source’ link is there, but doesn’t do anything,
since there is no hidden source to unhide)

Cheers,

Brian.

···

On Wed, Jul 23, 2003 at 06:03:31PM +0900, Gawnsoft wrote:

Now the question: this new template relies on DHTML, Javascript, and a
lot of CSS. Has the world of browsers advanced to the point where I
could make this the default style, or do we still need to support the
previous generation?

It depends if you’re publishing only for desktop machines, or for
desktops and also for handheld devices, which tend to have less
compute power for powerful browsers, as well as more limited displays
(e.g. monochrome)