New RDoc template, and a question

[Dave Thomas]

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

 

[Harry Ohlsen]

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.

 

[Joel VanderWerf]

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.

 

[Martin DeMello]

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?

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

 

[Ben Giddings]

Wow. Purdy.

I really like it, although I happen to be biased because those are nearly the
colours I use in XEmacs anyhow. 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

 

[Gawnsoft]

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

 

[Brian Candler]

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)

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.

 

[Rasputin]

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)

Ditto in elinks.

[ FWIW, I'm not a Luddite, it's just my normal development environment
is a screen(1) session with vim in one window, elinks at the rdoc in
another, pickaxe in a third, another elinks at the website I'm working on,
another tailing the webserver logs, probably a chat session in another,
etc. etc. ]

 

[Jim Weirich]

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?

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?

 

[Dmitry V. Sabanin]

It's plain super, where can i get one?

 

[Aredridel]

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 <script src="..."/>
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. <grin>

That said, I like the concept.

Ari

 

[james_b]

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] http://www.alistapart.com/stories/alternate/

 

[Aredridel]

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

Speaking as another pair of aging eyes I have to say "Me, too." Something
brighter than this red, please.

Make sure the font sizes are not specified absolutely, for sure -- no
px, pt, in, cm, mm or pc units, please!

 

[Chris Morris]

Make sure the font sizes are not specified absolutely, for sure -- no
px, pt, in, cm, mm or pc units, please!

I'll throw this in the mix:

From [1]:

A good resource for understanding the scope of this problem is Owen
Brigg's excellent Text Sizing article
<http://www.thenoodleincident.com/tutorials/box_lesson/font/>[2],
which includes 274 screenshots of different font sizing techniques
in different environments. To cut a long story short, the only
reliable cross browser sizing method is to specify the size of the
font in pixels. This comes with one massive drawback: doing so will
prevent IE users from resizing the text in their browsers. If you
care at all about accessibility you'll know why this is a bad idea.


[1] http://simon.incutio.com/archive/2003/05/20/defeatingIE5
[2] http://www.thenoodleincident.com/tutorials/box_lesson/font/

 

[Aredridel]

I'll throw this in the mix:

From [1]:

A good resource for understanding the scope of this problem is Owen
Brigg's excellent Text Sizing article
<http://www.thenoodleincident.com/tutorials/box_lesson/font/>[2],
which includes 274 screenshots of different font sizing techniques
in different environments. To cut a long story short, the only
reliable cross browser sizing method is to specify the size of the
font in pixels. This comes with one massive drawback: doing so will
prevent IE users from resizing the text in their browsers. If you
care at all about accessibility you'll know why this is a bad idea.

The best solution is not to care: suggest a readable size, and let
browsers adjust -- that's what the font-size control in the UI is for
;-)

 

[Kurt M. Dresner]

I would have to agree with the people that say the source is hard to
read with those colors. Additionally. I liked the way that more
files/classes/methods fit in those top windows before. And I'd really
like the option to view one of the files. If I see blahblah.rb I might
just want to look at the whole thing instead of having to click on every
function in the file.

Other than that, I like it a lot )

-Kurt

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] http://www.alistapart.com/stories/alternate/

Cheers


Dave

======= End of Original Message =======<

 

[gabriele renzi]

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/

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..

 

[Dave Thomas]

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..

RDoc comes with a template that does does that:

rdoc -T kilmer ...

puts the menus down the left hand side.


Cheers


Dave