[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

[ANN] Frameless RDoc template ('technology preview'

ES

6/17/2005 7:59:00 PM

Hi!

From a slight frustration with the current RDoc templates and general
boredom I decided to try my hand in implementing one; the main goal was
to get rid of frames in a graceful manner.

The template works and produces (apparently) correct output, but before
I release the actual thing to the wild, I wanted to gather some input.
Folks on #ruby-lang have been kind enough to start on that, and no
showstoppers have been found yet. Please take a moment to view the
site and let me know your thoughts (read Issues and so on below before
mailing, though).

The two issues that will probably come up despite being listed below:
no, the colour scheme is not going to be that (it may in fact end up
customizable) and no, I have not given any thought to Explorer support
yet.


http://www.magical-cat.org/rdoc/rue-functio...



== Issues
- The colour scheme is not final! Will probably go with less... red.
- When generating the docs, one _must_ select +--one-file+
and +--inline-source+.
- +--one-file+ requires the output file exists or it dumps to stdout.
- The ordering of classes and 'main' file is positionally sensitive
when invoking +rdoc<+. Essentially, whichever file is processed
first becomes the 'main' file (displayed initially) and classes are
displayed in the order their files are read in.
- It is all on one page and there is a bit of JavaScript magick involved
so the document tends to be large and the initial load is a bit slow
and choppy; however, once the file has loaded, it works very fast.
- The JavaScript works but is absolutely atrocious.
- Some minor CSS issues.
- Probably will not render right in IE nor possibly Opera. Only actually
tested on recent Mozilla-stemmed browsers.

== Known bugs
- RDoc stats get inserted into the document (outside the HTML, no less)!
Would probably have to mess with RDoc internals to correct that. I
have the distinct feeling that the +--one-file+ option was something
of an afterthought or side-project.
- Internal links (#) to classes on the pages do _not_ work. All other
links should be fine. Again, a RDoc-internal issue.

== ToDo / ToFindOut
- Refactor the JavaScript
- Work out CSS bugs
- IE support
- onLoad() will the header and content be paired correctly?
- Adjust colour scheme?
- Make colours overridable?
- Are all RDoc output cases taken into account?


Thanks!

E

--
template<typename duck>
void quack(duck& d) { d.quack(); }
16 Answers

Eric Hodel

6/17/2005 8:28:00 PM

0

On 17 Jun 2005, at 12:59, ES wrote:

> == Issues
> - It is all on one page and there is a bit of JavaScript magick
> involved
> so the document tends to be large and the initial load is a bit slow
> and choppy; however, once the file has loaded, it works very fast.
> - The JavaScript works but is absolutely atrocious.

It doesn't work very well with w3m.

The menus are just a big blob of text. How about lists instead?

JS links aren't clickable:

<li><a href="#M000027" onclick="scroll_to('#M000027'); false">add</
a></li> (untested)

instead of shoving JS into the href?

I bet you could do something similar with list_scroll_to, but it
would require more time than a glance for me to propose something.

--
Eric Hodel - drbrain@segment7.net - http://se...
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

Adam P. Jenkins

6/17/2005 8:32:00 PM

0

ES wrote:
> Hi!
>
> From a slight frustration with the current RDoc templates and general
> boredom I decided to try my hand in implementing one; the main goal was
> to get rid of frames in a graceful manner.
>
> The template works and produces (apparently) correct output, but before
> I release the actual thing to the wild, I wanted to gather some input.
> Folks on #ruby-lang have been kind enough to start on that, and no
> showstoppers have been found yet. Please take a moment to view the
> site and let me know your thoughts (read Issues and so on below before
> mailing, though).

Looks good.

One problem is, since you're using the scroll_to() javascript function
instead of links to jump to function documentation, I can't use my
browser's back function to get back to the top of the page after jumping
to a function. I'm using Firefox.

Adam

Patrick Gundlach

6/17/2005 11:31:00 PM

0


[...]

quite nice, but the following hit me at the beginning:

> so the document tends to be large and the initial load is a bit slow
> and choppy; however, once the file has loaded, it works very fast.

I don't want to read documentation for the standard lib on one page.
It would take forever to dl.


Patrick

ES

6/18/2005 3:03:00 AM

0

Eric Hodel wrote:
> On 17 Jun 2005, at 12:59, ES wrote:
>
>> == Issues
>> - It is all on one page and there is a bit of JavaScript magick involved
>> so the document tends to be large and the initial load is a bit slow
>> and choppy; however, once the file has loaded, it works very fast.
>> - The JavaScript works but is absolutely atrocious.
>
>
> It doesn't work very well with w3m.

OK; are the below items specifically what was wrong or it just generally
does not work with w3m (and lynx and others)? I will try to get to XHTML
1.0 conformance before finalising in any case.

> The menus are just a big blob of text. How about lists instead?

Will do!

> JS links aren't clickable:
>
> <li><a href="#M000027" onclick="scroll_to('#M000027'); false">add</
> a></li> (untested)
>
> instead of shoving JS into the href?
>
> I bet you could do something similar with list_scroll_to, but it would
> require more time than a glance for me to propose something.

Check; it is fairly straightforward in both cases.


E

--
template<typename duck>
void quack(duck& d) { d.quack(); }

ES

6/18/2005 3:06:00 AM

0

Adam P. Jenkins wrote:
> ES wrote:
>
>> Hi!
>>
>> From a slight frustration with the current RDoc templates and general
>> boredom I decided to try my hand in implementing one; the main goal was
>> to get rid of frames in a graceful manner.
>>
>> The template works and produces (apparently) correct output, but before
>> I release the actual thing to the wild, I wanted to gather some input.
>> Folks on #ruby-lang have been kind enough to start on that, and no
>> showstoppers have been found yet. Please take a moment to view the
>> site and let me know your thoughts (read Issues and so on below before
>> mailing, though).
>
>
> Looks good.
>
> One problem is, since you're using the scroll_to() javascript function
> instead of links to jump to function documentation, I can't use my
> browser's back function to get back to the top of the page after jumping
> to a function. I'm using Firefox.

You are absolutely correct... it has been since the dot-com era that I
last used JavaScript, but I believe it is _possible_ to manipulate the
history in that fashion: most likely it would involve having a second
identifier for each link so that the 'caller' could be stored. I will
see what I can do. I am with you on this, it is annoying. At the very
least I will throw in [back to top] links.

> Adam

E


--
template<typename duck>
void quack(duck& d) { d.quack(); }

ES

6/18/2005 3:39:00 AM

0

Patrick Gundlach wrote:
> [...]
>
> quite nice, but the following hit me at the beginning:
>
>
>> so the document tends to be large and the initial load is a bit slow
>> and choppy; however, once the file has loaded, it works very fast.
>
>
> I don't want to read documentation for the standard lib on one page.
> It would take forever to dl.

Well, long at any rate. That is true, the whole stdlib is not really a
feasible use case. With an external index, though, one could store one
library per page.

> Patrick

E


--
template<typename duck>
void quack(duck& d) { d.quack(); }

John W. Long

6/18/2005 4:29:00 AM

0

ES wrote:
> From a slight frustration with the current RDoc templates and general
> boredom I decided to try my hand in implementing one; the main goal was
> to get rid of frames in a graceful manner.

Wow. This is cool. Am I right to assume that all of the pages are
contained in a single document?

I was working on my own template a while back:

http://johnwlong.com/downloads/rubyred-rdoc-template-t...

and

http://johnwlong.com/downloads/rubyred-rdoc-te...

--
John Long
http://wiseheart...

Eric Hodel

6/18/2005 4:56:00 AM

0

On 17 Jun 2005, at 20:02, ES wrote:

> Eric Hodel wrote:
>
>> On 17 Jun 2005, at 12:59, ES wrote:
>>
>>> == Issues
>>> - It is all on one page and there is a bit of JavaScript magick
>>> involved
>>> so the document tends to be large and the initial load is a bit
>>> slow
>>> and choppy; however, once the file has loaded, it works very fast.
>>> - The JavaScript works but is absolutely atrocious.
>>>
>> It doesn't work very well with w3m.
>
> OK; are the below items specifically what was wrong or it just
> generally
> does not work with w3m (and lynx and others)? I will try to get to
> XHTML
> 1.0 conformance before finalising in any case.

The document is readable, but not navigable with w3m. That probably
applies to lynx as well. (I have found newer versions of w3m support
some CSS, like display: none.)

>> The menus are just a big blob of text. How about lists instead?
>
> Will do!
>
>> JS links aren't clickable:
>> <li><a href="#M000027" onclick="scroll_to('#M000027');
>> false">add</ a></li> (untested)
>> instead of shoving JS into the href?
>> I bet you could do something similar with list_scroll_to, but it
>> would require more time than a glance for me to propose something.
>
> Check; it is fairly straightforward in both cases.

I think this will also solve the history problem mentioned by Adam.

--
Eric Hodel - drbrain@segment7.net - http://se...
FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04

netghost

6/18/2005 6:21:00 PM

0

Hey that's pretty neat. There are a few problems I can see though. If
you are using this on a large code base, like the Standard Library or
Rails, will those drop downs show everything? Plus large documents
will be particularly annoying to read.

It should be possible to split it up into multiple documents. Would
you like any help? Send me an email,
.adam sanderson

ES

6/19/2005 2:25:00 AM

0

Eric Hodel wrote:
> On 17 Jun 2005, at 20:02, ES wrote:
>
>> Eric Hodel wrote:
>>
>>> On 17 Jun 2005, at 12:59, ES wrote:
>>>
>>>> == Issues
>>>> - It is all on one page and there is a bit of JavaScript magick
>>>> involved
>>>> so the document tends to be large and the initial load is a bit slow
>>>> and choppy; however, once the file has loaded, it works very fast.
>>>> - The JavaScript works but is absolutely atrocious.
>>>>
>>> It doesn't work very well with w3m.
>>
>>
>> OK; are the below items specifically what was wrong or it just generally
>> does not work with w3m (and lynx and others)? I will try to get to XHTML
>> 1.0 conformance before finalising in any case.
>
>
> The document is readable, but not navigable with w3m. That probably
> applies to lynx as well. (I have found newer versions of w3m support
> some CSS, like display: none.)

I will attempt to get that resolved; it does seem that keyboard-based
navigation works in graphical browsers (links take you to the right
place etc.) right now.

I also achieved XHTML 1.0 Strict and CSS conformance and the main
accessibility validators do not have a problem with the code as
it stands, either.

>>> The menus are just a big blob of text. How about lists instead?
>>
>>
>> Will do!
>>
>>> JS links aren't clickable:
>>> <li><a href="#M000027" onclick="scroll_to('#M000027'); false">add</
>>> a></li> (untested)
>>> instead of shoving JS into the href?
>>> I bet you could do something similar with list_scroll_to, but it
>>> would require more time than a glance for me to propose something.
>>
>>
>> Check; it is fairly straightforward in both cases.
>
>
> I think this will also solve the history problem mentioned by Adam.

Unfortunately not; that problem is more complex than I thought (and
now that I think about it, for good reasons). JavaScript does not
offer any direct ways to manipulate history entries (a Good Thing
in general), which means that any such manipulation that I can
think of would have to be done by reloading the document which
somewhat defeats the purpose. I will go back to the drawing board
with this (ideas/scripts) are of course welcome; for right now, I
will put in [back to top] links.


Thanks!

E

--
template<typename duck>
void quack(duck& d) { d.quack(); }