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

[url]http://rdoc.sourceforge.net/newdoc/[/url]

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]

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
>
> [url]http://rdoc.sourceforge.net/newdoc/[/url]
>
> 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]

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.

[Martin DeMello]

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?

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.

On Wed July 23 2003 12:41 am, 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?

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

[Mark Wilson]

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

> [snip]
> You can see what this looks like at
>
> [url]http://rdoc.sourceforge.net/newdoc/[/url]
>
> 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]

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

[Gawnsoft]

On Wed, 23 Jul 2003 13:41:16 +0900, Dave Thomas <dave@pragprog.com>
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
>
> [url]http://rdoc.sourceforge.net/newdoc/[/url]
>
>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: [url]http://www.gawnsoft.co.sr[/url]
Symbian/Epoc wiki: [url]http://html.dnsalias.net:1122[/url]
Smalltalk links (harvested from comp.lang.smalltalk) [url]http://html.dnsalias.net/gawnsoft/smalltalk[/url]

[Brian Candler]

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)

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]

* Brian Candler <B.Candler@pobox.com> [0757 10:57]:

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

> 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. ]
--
I have made mistakes but I have never made the mistake of claiming
that I have never made one.
-- James Gordon Bennett
Rasputin :: Jack of All Trades - Master of Nuns

[Frank Mitchell]

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 [url]http://www.fsf.org/philosophy/no-word-attachments.html[/url]

[John Johnson]

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

> 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 :-)

Regards,
JJ

--
Regards,
JJ

Be Kind, Be Careful, Be Yourself

[Jim Weirich]

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?

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?

--
-- Jim Weirich [email]jweirich@one.net[/email] [url]http://onestepback.org[/url]
-----------------------------------------------------------------
"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)

[Dmitry V. Sabanin]

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

--
sdmitry -=- Dmitry V. Sabanin
MuraveyLabs.

[Aredridel]

On Tue, 2003-07-22 at 22:41, 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
>
> [url]http://rdoc.sourceforge.net/newdoc/[/url]
>
> 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]

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

>
>
> Cheers
>
>
> Dave
>
>
>

[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]

Aredridel wrote:

>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] [url]http://simon.incutio.com/archive/2003/05/20/defeatingIE5[/url]
[2] [url]http://www.thenoodleincident.com/tutorials/box_lesson/font/[/url]

--

Chris
[url]http://clabs.org/blogki[/url]

[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 :o)

-Kurt

On Wed, Jul 23, 2003 at 11:45:08PM +0900, james_b wrote:

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

> >
> >
> >Cheers
> >
> >
> >Dave
> >
> >
> >

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

[Michael Granger]

On Wednesday, Jul 23, 2003, at 02:03 US/Pacific, 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)

The generated HTML should look fine in less-featureful browsers, too,
since there's nothing that's really dependent on the DHTML or CSS for
display. It looks fine under both 'w3m' and 'links', for example. The
code-hiding is done with CSS, so if a browser doesn't support it, it
just appears inline as it would with the (current) default template.

--
Michael Granger <ged@FaerieMUD.org>
Rubymage, Believer, Architect
The FaerieMUD Consortium <http://www.FaerieMUD.org/>