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


 

Forums >

comp.lang.ruby

A RDoc template without frames

David Heinemeier Hansson

12/20/2004 6:36:00 PM

Despite the snazzy look of the new default RDoc templates with three
panes at the top, I keep coming back to the original flat look of
http://www.rubycentral.com/book/bui.... There's something deeply
usable with having all the modules and methods take up a full screen
instead of being cramped into tiny panes at the top. Of course, it
could also be, as Dave Thomas suggested, that I'm just "getting old and
inflexible".

Regardless of which, I'd be terribly appreciative if anyone had the
insight and energy to make a set of RDoc templates that used this flat
format with 1 index and 1 page per module. I'd *really* like to have it
for the unveiling of the new Ruby on Rails site, which is coming
shortly.

Even Dave says its not supposed to be that hard: "...if someone wanted
to create a new output template and generator, it would be fairly
simple: just change the stuff that generates the current top frame to
store it all in one file, not three"

Anyone up for it? :)
--
David Heinemeier Hansson,
http://www.basec... -- Web-based Project Management
http://www.rubyon... -- Web-application framework for Ruby
http://macro... -- TextMate: Code and markup editor (OS X)
http://www.loudthi... -- Broadcasting Brain
16 Answers

Aredridel

12/20/2004 6:47:00 PM

0

> Regardless of which, I'd be terribly appreciative if anyone had the
> insight and energy to make a set of RDoc templates that used this flat
> format with 1 index and 1 page per module. I'd *really* like to have it
> for the unveiling of the new Ruby on Rails site, which is coming
> shortly.

+1. I wish I had time to just do it!

Nicholas Van Weerdenburg

12/20/2004 9:51:00 PM

0

I'm not a big fan of the 3 pane view, but am waiting to see if my
brain adjusts to it.


On Tue, 21 Dec 2004 03:47:18 +0900, Aredridel <aredridel@gmail.com> wrote:
> > Regardless of which, I'd be terribly appreciative if anyone had the
> > insight and energy to make a set of RDoc templates that used this flat
> > format with 1 index and 1 page per module. I'd *really* like to have it
> > for the unveiling of the new Ruby on Rails site, which is coming
> > shortly.
>
> +1. I wish I had time to just do it!
>
>

gabriele renzi

12/20/2004 9:55:00 PM

0

Nicholas Van Weerdenburg ha scritto:
> I'm not a big fan of the 3 pane view, but am waiting to see if my
> brain adjusts to it.
>
>

actually it is a 4 pane view.
I'm a fan of the three pane one as it comes out from javadoc :/

Nicholas Van Weerdenburg

12/20/2004 10:33:00 PM

0

Oops. Right.

I am used to Java doc layout, and like it. But I am giving my brain
time to see if it adjusts to the 4 pane view.

Thanks,
Nick

On Tue, 21 Dec 2004 06:57:03 +0900, gabriele renzi
<rff_rff@remove-yahoo.it> wrote:
> Nicholas Van Weerdenburg ha scritto:
> > I'm not a big fan of the 3 pane view, but am waiting to see if my
> > brain adjusts to it.
> >
> >
>
> actually it is a 4 pane view.
> I'm a fan of the three pane one as it comes out from javadoc :/
>
>


--
Nicholas Van Weerdenburg

Ben Giddings

12/21/2004 1:15:00 AM

0

David Heinemeier Hansson wrote:
> Despite the snazzy look of the new default RDoc templates with three
> panes at the top, I keep coming back to the original flat look of
> http://www.rubycentral.com/book/bui.... There's something deeply
> usable with having all the modules and methods take up a full screen
> instead of being cramped into tiny panes at the top. Of course, it could
> also be, as Dave Thomas suggested, that I'm just "getting old and
> inflexible".

I don't have the time to do it either, but I'd really appreciate it too.
If (like me) you constantly use Firefox/Mozilla's type-ahead-find
feature you'll be messed up constantly by framed sites.

There are lots of problems with the online ruby book HTML, but I've
always found it much more useable than any of the rdoc documentation.

I think the absolute ideal of Ruby documentation would be something
along the lines of:

* Ruby language reference
* keywords and their meanings
* alias
alias <new name> <old name>

example:
alias oldBackquote `
def `(cmd)
result = oldBackquote(cmd)
if $? != 0
raise "Command #{cmd} failed"
end
result
end
print `date`
print `data`
...
* rescue
rescue <ExceptionClassList>
rescue <ExceptionClassList> => <varname>

example:
begin
eval string
rescue SyntaxError, NameError => boom
print "String doesn't compile: " + boom
rescue StandardError => bang
print "Error running script: " + bang
end
...
* regexp reference
...
* m - multiline
...
* commandline reference
...
* Ruby core builtins
* Array
* []
...
* each
...
* String
...
* length
...
* All ruby builtins
...
* CGI
...
* Process
...
* Test
* Unit
...
* Zlib
* GzipFile
* Ruby standard library
* soap
* webrick
* <webrick documentation or link to webrick documentation site>
* yaml
* <yaml documentation or link to yaml documentation site>
* Yaml
* dump
* load


As far as I know, the keyword documentation I'm dreaming of doesn't
exist anywhere, but it would be just amazing to have. I always forget
little details, like does 'alias' have symbols after it, or bare
function names? Does it use a comma separator or whitespace? How do
you assign a variable for the exception when you rescue it? What are
the options for creating a multiline, case-insensitive regular expression?

As for the documentation of the built in classes, I think the builtins
page linked above is a masterful work of UI design. It is exactly
what's required when you are asking yourself the question "What's the
name of that method that converts an id number to a string, and what
class is it in?"

I go to that page, and after a bit of quick scanning I spot
Fixnum#id2name, I click on that and get an explanation and a great example.

The way that page is laid out, there are about 1.5 screens (for me)
worth of text, all of it laid out in a clear hierarchy, all of it
hyperlinked. Compare that to http://www.ruby-doc...

The page is mostly blank, but at the top I get 3 scrollable frames, each
about 20 "windows" long. It just isn't as easy to browse.

Once I choose a class/file the documentation is excellent and readable,
but because of the frames, my type-ahead-find doesn't work.

Now, Ruby has gotten bigger between the release of the first book and
the documentation on ruby-doc.org, but the list at the book site is
still better for me. I use Array far more than I do
Zlib::GzipFile::NoFooter. While they may both technically be part of
the core, Array, String, Hash, etc. really deserve special status as
inner core, or uber-mega core, or something. 99% of the time I find I'm
looking up uber-mega core information or keywords, and
Zlib::GzipFile::NoFooter just gets in the way.

My not-so-humble opinion. ;)

Ben

Curt Sampson

12/21/2004 2:21:00 AM

0

gabriele renzi

12/21/2004 12:01:00 PM

0

Curt Sampson ha scritto:

>
> Funny, that 3-pane format reminded me a lot of a Smalltalk class/method
> browser, except it isn't one, of course. The problem is that it's
> static, not dynamic. Given that we have rails here, how about a real
> browser, rather than static web pages? Heck, you might even contemplate
> generating the documentation on the fly, so you just point it at a
> directory and you can start browsing.
>

well, I don't think visitors of the site are expected to add
classes/methods/objects to the rails space from a form.. even if it
would be really cool :D

John W. Long

12/21/2004 12:52:00 PM

0

> This copyright could be included in the generated templates. At the
> bottom, in the same fashion seen in your mockup. If you have a name for
> your design, it might work better to say "Regal Elegance Design is
> Copyright (c) 2004, John W. Long." Should you determine that your
> templates are regal and elegant enough (and they are) to warrant a name
> such as Regal Elegance.

I'm not planning on copyrighting the design. I would like it to be used
and modified by everybody. But as a developer I'd want to copyright my
documentation.

The design's name is Ruby Red, although Regal Elegance does have a
certain ring to it. =)

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

Douglas Livingstone

12/21/2004 1:12:00 PM

0

> I'm not planning on copyrighting the design.

You already have, simply by making it. You'd have to "uncopyright" it.
(copyleft, creative commons, GPL, FSF, etc)

Douglas

gabriele renzi

12/21/2004 1:26:00 PM

0

Douglas Livingstone ha scritto:
>>I'm not planning on copyrighting the design.
>
>
> You already have, simply by making it. You'd have to "uncopyright" it.
> (copyleft, creative commons, GPL, FSF, etc)
>

just to know.. is someone else missing the previous messages of this
thread?
I'm afraid my newsserver is going mad, but I'm more afraid of news2ml.rb
getting broken :/