[ANN] Frameless RDoc template ('technology preview')

[ES]

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-functional-1.html



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

 

[Eric Hodel]

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

 

[Adam P. Jenkins]

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]

[...]

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]

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

 

[ES]

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

 

[ES]

[...]

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

 

[John W. Long]

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-test-1.html

and

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

 

[Eric Hodel]

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

Will do!


Check; it is fairly straightforward in both cases.

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

 

[Adam Sanderson]

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]

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.

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

 

[ES]

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.

The drop-downs will spawn scrollbars if necessary; I will place some
[back to top] links on the pages to help the latter aspect.

It should be possible to split it up into multiple documents.

All JavaScript solutions for 'requiring' files are highly
platform-dependent so the only possible way I can think of
involves using XmlHttpRequest with free-standing pages. I
am looking into that.

Would you like any help? Send me an email,

Also, if you have ideas, this e-mail address is fine.

.adam sanderson

E

 

[ajalkane]

I like the basic layout better than the frames based version which is
awkward.

But the navigation, due to it's heavy use of javascript, has some
annoying side-effects. Mainly: you can't open a new page easily in new
tab. Often when I am coding I reopen new documentation links and keep
them open for reference. Also it's impossible to link to individual
pages as it stands now.

 

[Ben Giddings]

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-test-1.html

and

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

Hey John, lovely design as usual.

The problem I see isn't so much "framed" vs "frameless" but more the
contents of the boxes.

The files box: Most of the time, I don't care what file something is in. I
can't think of the last time I used the "files" area.

The classes box: This is useful, until there are too many classes. I think
the current core has far too many classes for them to just be thrown in a
list with no grouping. There should be some kind of grouping or packaging
to make it easier for humans to navigate.

The methods box: Whoa. If there are too many classes to navigate, there
are *way* too many methods. Sometimes a full list of every method that
exists in the core is useful, but that's more of an "appendix" sort of
thing. Mostly I want to know what methods exist in a particular class
I've selected.

I still think the original pickaxe online documentation has the easiest to
navigate interface to the core api:

http://www.rubycentral.com/book/builtins.html

You have to scroll the page to see everything, but searching for a class is
easy, and finding the methods of a particular class is really intuitive.
If you want to find a method but can't remember what class it's in, you
can always use the browser's page search to find the method.

I wonder, is RDoc flexible enough to allow someone to generate a page like
the above?

Ben

 

[John W. Long]

Hey John, lovely design as usual.

The problem I see isn't so much "framed" vs "frameless" but more the
contents of the boxes.

The files box: Most of the time, I don't care...

The classes box: This is useful, until...

The methods box: Whoa...

I still think the original pickaxe online documentation has the easiest to
navigate interface to the core api:

http://www.rubycentral.com/book/builtins.html

. . .

I wonder, is RDoc flexible enough to allow someone to generate a page like
the above?

I'm sure it is. It might take a little hacking, but I'm sure you could
get it to do that.

Did you notice that the list boxes are linked in my first link:

http://johnwlong.com/downloads/rubyred-rdoc-template-test-1.html

Clicking one of the items in the list narrows the amount of items
displayed in the list next to it on the right. Do you think this
improves on the current framed/frameless approaches?

If you don't mind a robust Javascript approach, you could even build a
search box right into the page to make it easier to filter the lists for
the method you are looking for.

Here's another idea: why not use Ajax combined with a small servlet to
pull in user comments about the page that you are on? This would make it
easier for users to note changes that need to be made in the
documentation, offer tips, etc...

 

[Gennady Bystritksy]

FWIW, It does not work in Firefox showing content only in the leftmost
pannel, other 2 are empty (IE is ok).

Gennady.

 

[John W. Long]

Yeah, it was more of a proof of concept than anything else.

--
John

FWIW, It does not work in Firefox showing content only in the leftmost
pannel, other 2 are empty (IE is ok).

Gennady.