[ANN] www.ruby-doc.org

[James6 (James)]

Jim Freeze’s presentation at RubyConf 2002 mentioned, among other things, the
need for a ruby-docs project and/or general docs web site. I’ve taken the
initiative and created a site at www.ruby-doc.org, so that we now have:

• A place to track developments concerning the ruby-doc documentation project.
  We have a ruby-doc mailing list, and a list archive [0], but not a web home.

• A place to store assorted documents, both by and for the ruby-doc group, and
  for Ruby documentation in general

• A central reference site for tutorials, API and syntax refs, online books,
  Ruby articles, and the like, whether hosted directly or online elsewhere

• Yet Another Example of eating one’s own dog food; the entire site is built
  using pure Ruby. It’s mostly Blogtari [1], with some wrappers around ri (munged
  using Rimport[2]). REXML [3] is used for some intra-site RSS transformations,
  too.

• Something similar to the www.php.net URL shortcuts
  (http://www.php.net/urlhowto.php) for grabbing reference info.

For example, you can do this:

http://www.ruby-doc.org/find/ri/Array

and get back the ri info for the Array class. This URL

http://www.ruby-doc.org/find/ri/Array/sort

tells you about the sort method for the Array class.

The code just runs ri on the server and adds some elementary markup.
The transformation includes modding the method list so that the results contain
hyperlinks to other queries. For example, if you pull back the general info
about the Array class, each of the listed methods is a link for a subsequent
query on that specific method.

Now, what’s in ri by default is what’s in the pickaxe book, but the URLs for
various pickaxe pages aren’t so clean. To get the page about the Array class,
for example, you need to know how to mangle the file name (i.e.,
ref_c_array.html). To get to the page anchor for a given method, you need to
know that format, too (e.g. ref_c_array.html#Array.sort).

So, I wrote some URL rewriting code to handle that automatically.

Pickaxe URL searches work basically the same way as for ri, resolving path info
into URL matching class, module, or tutorial HTML files.

For example,

http://www.ruby-doc.org/find/pickaxe/array

gives you the Programming Ruby page for Arrays:

http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_array.html

The URL

http://www.ruby-doc.org/find/pickaxe/array/sort

gives you the Array page, jumping to the page anchor marking the ‘sort’ method:

http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_array.html#Array.sort

If the code cannot make a reasonable guess it gives you (I hope) the index page.
If the derived page anchor is working, you should at least get the top of the
related page. For example,

http://www.ruby-doc.org/find/pickaxe/array/foo

maps to

http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_array.html#Array.foo

which is a bogus anchor, but a real page.

There’s more work to be done on the site, but comments are invited. I want to
add more data to the site’s ri so that things currently missing from ri (and the
pickaxe) are retrievable via the munged version online. Right now, for example,
you can get Matrix info online, something not available from the standard ri,
though the code was sparsely commented. Likewise, WeakRef, Pstore, and a few
others are in there via rimport.

I also need to sort out additional pages for more details on things like doc
tools, project documents, syntax help, and so on.

James Britt

[0] http://www.moonwolf.com/~arcml/cgi-bin/arcml/?rm=threadlist&list_id=2
[1] http://www.jamesbritt.com/articles/blogatari.html
[2] http://www.ruby-lang.org/en/raa-list.rhtml?id=413
[3] http://www.germane-software.com/software/rexml/

[Brian_Wisti1 (Brian Wisti)]

Hi James,

This is a great resource. Thanks for setting it up! Just one
question: Is it possible to browse (almost) randomly through the Standard
Library API?

-Brian W

···

At 02:34 PM 11/10/2002 +0900, JamesBritt wrote:

Jim Freeze’s presentation at RubyConf 2002 mentioned, among other things, the
need for a ruby-docs project and/or general docs web site. I’ve taken the
initiative and created a site at www.ruby-doc.org, so that we now have:

• A place to track developments concerning the ruby-doc documentation project.
  We have a ruby-doc mailing list, and a list archive [0], but not a web home.

• A place to store assorted documents, both by and for the ruby-doc group, and
  for Ruby documentation in general

• A central reference site for tutorials, API and syntax refs, online books,
  Ruby articles, and the like, whether hosted directly or online elsewhere

• Yet Another Example of eating one’s own dog food; the entire site is built
  using pure Ruby. It’s mostly Blogtari [1], with some wrappers around ri
  (munged
  using Rimport[2]). REXML [3] is used for some intra-site RSS transformations,
  too.

• Something similar to the www.php.net URL shortcuts
  (http://www.php.net/urlhowto.php) for grabbing reference info.

For example, you can do this:

http://www.ruby-doc.org/find/ri/Array

and get back the ri info for the Array class. This URL

http://www.ruby-doc.org/find/ri/Array/sort

tells you about the sort method for the Array class.

The code just runs ri on the server and adds some elementary markup.
The transformation includes modding the method list so that the results
contain
hyperlinks to other queries. For example, if you pull back the general info
about the Array class, each of the listed methods is a link for a subsequent
query on that specific method.

Now, what’s in ri by default is what’s in the pickaxe book, but the URLs for
various pickaxe pages aren’t so clean. To get the page about the Array class,
for example, you need to know how to mangle the file name (i.e.,
ref_c_array.html). To get to the page anchor for a given method, you need to
know that format, too (e.g. ref_c_array.html#Array.sort).

So, I wrote some URL rewriting code to handle that automatically.

Pickaxe URL searches work basically the same way as for ri, resolving path
info
into URL matching class, module, or tutorial HTML files.

For example,

http://www.ruby-doc.org/find/pickaxe/array

gives you the Programming Ruby page for Arrays:

Programming Ruby: The Pragmatic Programmer's Guide

The URL

http://www.ruby-doc.org/find/pickaxe/array/sort

gives you the Array page, jumping to the page anchor marking the ‘sort’
method:

Programming Ruby: The Pragmatic Programmer's Guide

If the code cannot make a reasonable guess it gives you (I hope) the index
page.
If the derived page anchor is working, you should at least get the top of the
related page. For example,

http://www.ruby-doc.org/find/pickaxe/array/foo

maps to

Programming Ruby: The Pragmatic Programmer's Guide

which is a bogus anchor, but a real page.

There’s more work to be done on the site, but comments are invited. I want to
add more data to the site’s ri so that things currently missing from ri
(and the
pickaxe) are retrievable via the munged version online. Right now, for
example,
you can get Matrix info online, something not available from the standard ri,
though the code was sparsely commented. Likewise, WeakRef, Pstore, and a few
others are in there via rimport.

I also need to sort out additional pages for more details on things like doc
tools, project documents, syntax help, and so on.

James Britt

[0] http://www.moonwolf.com/~arcml/cgi-bin/arcml/?rm=threadlist&list_id=2
[1] http://www.jamesbritt.com/articles/blogatari.html
[2] http://www.ruby-lang.org/en/raa-list.rhtml?id=413
[3] http://www.germane-software.com/software/rexml/

[Jostein_Berntsen]

Hi,

A fine site and a good resource! I believe good, structured documentation like
this on the web can be a booster for language promotion.

• Default look: In my Mozilla browser the fonts are very small in the right
  frame. Maybe Default should somewhere in between Default and Big type? Ugly
  might deserve it’s name.
• A note on the front saying that the entire site was written in Ruby?
• Are there any documentation for using eRuby?
• A “How to use the site”-doc could be cool.
• A search tool made in Ruby.

I will keep digging…

Regards,

Jostein

···

On Sunday 10 November 2002 06:34, JamesBritt wrote:

Jim Freeze’s presentation at RubyConf 2002 mentioned, among other things,
the need for a ruby-docs project and/or general docs web site. I’ve taken
the initiative and created a site at www.ruby-doc.org, so that we now have:

• A place to track developments concerning the ruby-doc documentation
  project. We have a ruby-doc mailing list, and a list archive [0], but not a
  web home.

• A place to store assorted documents, both by and for the ruby-doc group,
  and for Ruby documentation in general

• A central reference site for tutorials, API and syntax refs, online
  books, Ruby articles, and the like, whether hosted directly or online
  elsewhere

• Yet Another Example of eating one’s own dog food; the entire site is
  built using pure Ruby. It’s mostly Blogtari [1], with some wrappers around
  ri (munged using Rimport[2]). REXML [3] is used for some intra-site RSS
  transformations, too.

• Something similar to the www.php.net URL shortcuts
  (http://www.php.net/urlhowto.php) for grabbing reference info.

For example, you can do this:

http://www.ruby-doc.org/find/ri/Array

and get back the ri info for the Array class. This URL

http://www.ruby-doc.org/find/ri/Array/sort

tells you about the sort method for the Array class.

The code just runs ri on the server and adds some elementary markup.
The transformation includes modding the method list so that the results
contain hyperlinks to other queries. For example, if you pull back the
general info about the Array class, each of the listed methods is a link
for a subsequent query on that specific method.

Now, what’s in ri by default is what’s in the pickaxe book, but the URLs
for various pickaxe pages aren’t so clean. To get the page about the Array
class, for example, you need to know how to mangle the file name (i.e.,
ref_c_array.html). To get to the page anchor for a given method, you need
to know that format, too (e.g. ref_c_array.html#Array.sort).

So, I wrote some URL rewriting code to handle that automatically.

Pickaxe URL searches work basically the same way as for ri, resolving path
info into URL matching class, module, or tutorial HTML files.

For example,

http://www.ruby-doc.org/find/pickaxe/array

gives you the Programming Ruby page for Arrays:

Programming Ruby: The Pragmatic Programmer's Guide

The URL

http://www.ruby-doc.org/find/pickaxe/array/sort

gives you the Array page, jumping to the page anchor marking the ‘sort’
method:

Programming Ruby: The Pragmatic Programmer's Guide
rt

If the code cannot make a reasonable guess it gives you (I hope) the index
page. If the derived page anchor is working, you should at least get the
top of the related page. For example,

http://www.ruby-doc.org/find/pickaxe/array/foo

maps to

Programming Ruby: The Pragmatic Programmer's Guide
o

which is a bogus anchor, but a real page.

There’s more work to be done on the site, but comments are invited. I want
to add more data to the site’s ri so that things currently missing from ri
(and the pickaxe) are retrievable via the munged version online. Right
now, for example, you can get Matrix info online, something not available
from the standard ri, though the code was sparsely commented. Likewise,
WeakRef, Pstore, and a few others are in there via rimport.

I also need to sort out additional pages for more details on things like
doc tools, project documents, syntax help, and so on.

James Britt

[0] http://www.moonwolf.com/~arcml/cgi-bin/arcml/?rm=threadlist&list_id=2
[1] http://www.jamesbritt.com/articles/blogatari.html
[2] http://www.ruby-lang.org/en/raa-list.rhtml?id=413
[3] http://www.germane-software.com/software/rexml/

[Thomas_Hurst]

Cool resource.

Your HTML (and CSS) leave something to be desired, though.

Since I think it’s important for sites like this to be accessable, I’ve
redone the markup for the front page using XHTML strict and proper
semantic tags rather than your

, and soup. I’ll do the
CSS in a bit, then upload it somewhere so you can (hopefully) intergrae
it back into the site

···

• JamesBritt (james@jamesbritt.com) wrote:

Jim Freeze’s presentation at RubyConf 2002 mentioned, among other
things, the need for a ruby-docs project and/or general docs web site.
I’ve taken the initiative and created a site at www.ruby-doc.org, so
that we now have:

–
Thomas ‘Freaky’ Hurst - freaky@aagh.net - http://www.aagh.net/

Emacs, n:
A slow-moving parody of a text editor.

[Dave_Thomas]

" JamesBritt" james@jamesbritt.com writes:

There’s more work to be done on the site, but comments are invited.
I want to add more data to the site’s ri so that things currently
missing from ri (and the pickaxe) are retrievable via the munged
version online. Right now, for example, you can get Matrix info
online, something not available from the standard ri, though the
code was sparsely commented. Likewise, WeakRef, Pstore, and a few
others are in there via rimport.

For what it’s worth, I applaud the effort, but disagree with this
approach.

A little history.

When we wrote PickAxe, we used LaTeX, as it gave us the typographic
control we needed. We tried fairly hard to use logical (as opposed to
physical) markup. This was fortunate, as it meant that is was fairly
straightforward to convert the book from LaTeX to XML (and then on to
HTML) when we put the book online (the diagrams remain troublesome, as
they’re in PSTricks).

Once it was in XML, it became easier to play with it. In particular, I
was playing with it one day and realized it would be simple to produce
a command line reference from the builtin library section of the
book–all I had to do was interpret the logical markup and strip out
the physical markup and cross references. This became ri.

‘ri’ represents the lowest common denominator of documentation: it has
almost no semantic information in it. ‘ri’ was always intended to be
a stop-gap. The final goal was always more ambitious.

What I envisage is an integrated tool for the documentation of Ruby
libraries and code. ri as we know it now would be thrown away.
Instead, documentation would be produced by a beefed-up version of
RDoc and stored in a repository. This process would be incremental:
new documentation could be added (and existing documentation updated)
at all times. Repositories would be stored on user’s local machines:
we could even have multiple repositories for multiple users where
necessary (in fact I think we’d want to support hierarchies of
repositories: when a system administrator installs Ruby, the
repository for the standard libraries gets installed. When a user then
installs their own copy of package X, then the documentation for it
could be stored locally for that user, but hyperlinked to the
system-wide repository where necessary.)

The documentation in this repository would have all the formatting
capabilities of rdoc, and would also enjoy all the automated
hyperlinking that rdoc provides. The documentation would also be
produced from the code (so it is more likely to be up to date). Matz
has already agreed to let me add the rdoc documentation for all the
built-in library into the interpreter C-source.

Once the repository is built, it can be read in many ways. A command
line tool similar to ‘ri’ is an obvious start. So is HTML access over
the web. But I’d also like to use this documentation to update the
PickAxe, so that when when new versions of Ruby come along, the
library documentation in the book in guaranteed to be up to date.

The idea behind ruby-doc.org is a good one. But, as I discussed with
James at RubyConf, let’s try to get the most out of the energy being
put in to it. Rather than simply repackaging existing stuff, let’s
try to show the world how language and library documentation should be
done.

What needs to happen?

First, RDoc needs some work.

• it doesn’t currently bother to record the fully qualified names of
  methods: it didn’t need to until now.

• it doesn’t have a repository - it goes from source to whatever
  output format you select. However, this isn’t a major problem - it
  does have that division internally, so splitting it in two shouldn’t
  be too hard

• once we have a repository, it needs to be made incremental. Again,
  this shouldn’t be too hard.

• Given the repository, the existing RDoc mechanisms could be adapted
  to produce HTML, XML, and RDF from it. We could also write a
  command-line query tool to replace ri.

• Once all this is in place, we have ‘documentation day’. We take the
  PickAxe documentation for both the built-in methods and the standard
  library and add it to the source. Much of this can be automated, but
  it needs people to check the result.

• Finally, we include all these tools with the standard distribution,
  so that Ruby documentation is available ‘out of the box’.

Web sites such as ruby-doc could then feed straight from this
repository, giving them far richer content.

I’m trying to work on this, but to be honest I’m finding it hard to
make the time. A combination of some deaths of friends and family,
along with a heavy workload, have meant that progress on RDoc has been
slow recently. If anyone thinks this vision has merit and has the time
to spend to help make it real, I’d welcome the help.

Regards

Dave

[Dave_Thomas]

" JamesBritt" james@jamesbritt.com writes:

Now, what’s in ri by default is what’s in the pickaxe book, but the
URLs for various pickaxe pages aren’t so clean. To get the page
about the Array class, for example, you need to know how to mangle
the file name (i.e., ref_c_array.html). To get to the page anchor
for a given method, you need to know that format, too
(e.g. ref_c_array.html#Array.sort).

One of the reasons for the method name mangling is that ‘&’ is not a
valid target…

Cheers

Dave

[Daniel10 (Daniel)]

awesome I’d love to see something in the style of PHP’s php.net.
I’ve found theirs to be the most helpful document project ever.
Thoughts?

db

···

On Sun, Nov 10, 2002 at 02:34:17PM +0900, JamesBritt wrote:

Jim Freeze’s presentation at RubyConf 2002 mentioned, among other things, the
need for a ruby-docs project and/or general docs web site. I’ve taken the
initiative and created a site at www.ruby-doc.org, so that we now have:

• A place to track developments concerning the ruby-doc documentation project.
  We have a ruby-doc mailing list, and a list archive [0], but not a web home.

• A place to store assorted documents, both by and for the ruby-doc group, and
  for Ruby documentation in general

• A central reference site for tutorials, API and syntax refs, online books,
  Ruby articles, and the like, whether hosted directly or online elsewhere

• Yet Another Example of eating one’s own dog food; the entire site is built
  using pure Ruby. It’s mostly Blogtari [1], with some wrappers around ri (munged
  using Rimport[2]). REXML [3] is used for some intra-site RSS transformations,
  too.

• Something similar to the www.php.net URL shortcuts
  (http://www.php.net/urlhowto.php) for grabbing reference info.

For example, you can do this:

http://www.ruby-doc.org/find/ri/Array

and get back the ri info for the Array class. This URL

http://www.ruby-doc.org/find/ri/Array/sort

tells you about the sort method for the Array class.

The code just runs ri on the server and adds some elementary markup.
The transformation includes modding the method list so that the results contain
hyperlinks to other queries. For example, if you pull back the general info
about the Array class, each of the listed methods is a link for a subsequent
query on that specific method.

Now, what’s in ri by default is what?s in the pickaxe book, but the URLs for
various pickaxe pages aren’t so clean. To get the page about the Array class,
for example, you need to know how to mangle the file name (i.e.,
ref_c_array.html). To get to the page anchor for a given method, you need to
know that format, too (e.g. ref_c_array.html#Array.sort).

So, I wrote some URL rewriting code to handle that automatically.

Pickaxe URL searches work basically the same way as for ri, resolving path info
into URL matching class, module, or tutorial HTML files.

For example,

http://www.ruby-doc.org/find/pickaxe/array

gives you the Programming Ruby page for Arrays:

Programming Ruby: The Pragmatic Programmer's Guide

The URL

http://www.ruby-doc.org/find/pickaxe/array/sort

gives you the Array page, jumping to the page anchor marking the ‘sort’ method:

Programming Ruby: The Pragmatic Programmer's Guide

If the code cannot make a reasonable guess it gives you (I hope) the index page.
If the derived page anchor is working, you should at least get the top of the
related page. For example,

http://www.ruby-doc.org/find/pickaxe/array/foo

maps to

Programming Ruby: The Pragmatic Programmer's Guide

which is a bogus anchor, but a real page.

There’s more work to be done on the site, but comments are invited. I want to
add more data to the site’s ri so that things currently missing from ri (and the
pickaxe) are retrievable via the munged version online. Right now, for example,
you can get Matrix info online, something not available from the standard ri,
though the code was sparsely commented. Likewise, WeakRef, Pstore, and a few
others are in there via rimport.

I also need to sort out additional pages for more details on things like doc
tools, project documents, syntax help, and so on.

James Britt

[0] http://www.moonwolf.com/~arcml/cgi-bin/arcml/?rm=threadlist&list_id=2
[1] http://www.jamesbritt.com/articles/blogatari.html
[2] http://www.ruby-lang.org/en/raa-list.rhtml?id=413
[3] http://www.germane-software.com/software/rexml/

–
A.D. 1844: Samuel Morse invents Morse code. Cryptography export
restrictions prevent the telegraph’s use outside the U.S. and Canada.

[Gavin_Sinclair]

For what it’s worth, I applaud the effort, but disagree with this
approach.

A little history.

[…]

Dave,

Thanks for spelling all that out; it’s most interesting. In fact, at some
levels it mirrors what James and I were discussing on the ruby-doc ML a couple
of weeks ago - it’s just that your vision is a bit wider.

So I’d like to help where I can. My time is a bit tight at the moment as well.
We’re waiting to see where Jim Freeze takes the Ruby-Doc group at the moment,
but basically we’d be aiming to help create the vision you’ve spelled out,
among other (organisational) things.

Cheers,
Gavin

···

From: “Dave Thomas” Dave@PragmaticProgrammer.com

[James6 (James)]

This link gives the index and table of contents for the pickaxe book:
http://www.ruby-doc.org/docs/ProgrammingRuby/

This link
http://www.ruby-doc.org/find/ri

should give you a list of all classes know to ri (it’s been augmented with a few
things not found in the default ri).

Is there something else you would like to see?

James

···

-----Original Message-----
From: Brian Wisti [mailto:brian@coolnamehere.com]
Sent: Sunday, November 10, 2002 12:56 AM
To: ruby-talk ML
Subject: Re: [ANN] www.ruby-doc.org

Hi James,

This is a great resource. Thanks for setting it up! Just one
question: Is it possible to browse (almost) randomly through the Standard
Library API?

[James6 (James)]

Hi,

A fine site and a good resource! I believe good, structured
documentation like
this on the web can be a booster for language promotion.

That’s the plan, at least.

• Default look: In my Mozilla browser the fonts are very small in the right
  frame. Maybe Default should somewhere in between Default and Big type? Ugly
  might deserve it’s name.

I changed the CSS to use a fixed font size for ‘p’ elements, and some checking
using assorted browser/platforms shows a big improvement. Let me know if it
still doesn’t look right.

• A note on the front saying that the entire site was written in Ruby?

At the very bottom, under ‘Colophon’, there are some notes on how it was built.
Plus there’s the “Powered by Ruby” button. Maybe we need a “100% pure Ruby”
button?

• Are there any documentation for using eRuby?

I imagine there is, but it’s not explicitly listed on the site. Perhaps the
site could have a taxonmy/hierachical/something page to direct users to known
documentation (on the site or elsewhere) based on category/purpose.

• A “How to use the site”-doc could be cool.

Yes, needs that.

• A search tool made in Ruby.

That would be nice!

I will keep digging…

Regards,

Jostein

James

[James6 (James)]

Cool resource.

Thank you.

Your HTML (and CSS) leave something to be desired, though.

OK.

Since I think it’s important for sites like this to be accessable, I’ve
redone the markup for the front page using XHTML strict and proper
semantic tags rather than your

, and soup. I’ll do the
CSS in a bit, then upload it somewhere so you can (hopefully) intergrae
it back into the site

I look forward to seeing it.

James

···

–
Thomas ‘Freaky’ Hurst - freaky@aagh.net - http://www.aagh.net/

Emacs, n:
A slow-moving parody of a text editor.

[Austin_Ziegler2 (Austin Ziegler)]

Note that XHTML strict still allows for

and . These
tags, in fact, are very useful. (I have an article that I wrote a
while back that I’m getting ready to publish on my website; it uses

quite a bit with CSS2.) My website also uses

to separate the navigation bar (on the left) and the heading (on the top) from the body of the website, and uses CSS-positioning to keep them in place. The good thing about the use of

over tables for positioning is that if positioning isn't supported, the work will (generally) be read in the proper order.

-austin
– Austin Ziegler, austin@halostatue.ca on 2002.11.10 at 15.14.10

···

On Sun, 10 Nov 2002 23:07:47 +0900, Thomas Hurst wrote:

• JamesBritt (james@jamesbritt.com) wrote:

Jim Freeze’s presentation at RubyConf 2002 mentioned, among other
things, the need for a ruby-docs project and/or general docs web
site. I’ve taken the initiative and created a site at
www.ruby-doc.org, so that we now have:
Cool resource.

Your HTML (and CSS) leave something to be desired, though.

Since I think it’s important for sites like this to be accessable,
I’ve redone the markup for the front page using XHTML strict and
proper semantic tags rather than your

, and
soup. I’ll do the CSS in a bit, then upload it somewhere so you
can (hopefully) intergrae it back into the site

[Adamon]

Dave Thomas Dave@PragmaticProgrammer.com wrote in message news:m28z01v6ih.fsf@zip.local.thomases.com…

" JamesBritt" james@jamesbritt.com writes:

There’s more work to be done on the site, but comments are invited.
I want to add more data to the site’s ri so that things currently
missing from ri (and the pickaxe) are retrievable via the munged
version online. Right now, for example, you can get Matrix info
online, something not available from the standard ri, though the
code was sparsely commented. Likewise, WeakRef, Pstore, and a few
others are in there via rimport.

For what it’s worth, I applaud the effort, but disagree with this
approach.

A little history.

When we wrote PickAxe, we used LaTeX, as it gave us the typographic
control we needed. We tried fairly hard to use logical (as opposed to
physical) markup. This was fortunate, as it meant that is was fairly
straightforward to convert the book from LaTeX to XML (and then on to
HTML) when we put the book online (the diagrams remain troublesome, as
they’re in PSTricks).

Once it was in XML, it became easier to play with it. In particular, I
was playing with it one day and realized it would be simple to produce
a command line reference from the builtin library section of the
book–all I had to do was interpret the logical markup and strip out
the physical markup and cross references. This became ri.

‘ri’ represents the lowest common denominator of documentation: it has
almost no semantic information in it. ‘ri’ was always intended to be
a stop-gap. The final goal was always more ambitious.

Hasn’t docbook been proposed for documentation in the past? I too
like the idea of having abstract logical document markup in XML and
then using a suite of tools to convert it into XHTML, plain HTML,
LaTeX, troff, PDF, etc. Indeed, docbook (or perhaps simplified
docbook, as docbook is very rich) was designed for this very purpose.
The sites http://www.docbook.org and
Index of /docbook/xml/simple decribe the XML and SGML
standards for docbook and simplified docbook.

Indeed, I think James Britt himself has mentioned using docbook for
embedded documentation. The site www.rubydoc.org is down right now,
otherwise I’d check to see if support for docbook is in the planning
stages.

[Tom_Clarke2 (Tom Clarke)]

As part of automating the installation of ruby-packages through
raa-install I need a way to figure out what version of a library I have
installed. I would like to do this without using any kind of database so
that it works however you happened to install the library.

One idea I had is to do:

module MyModule
VERSION = “2.3.4”

.....

end

I don’t really care what the standard is, just there is some way of
find out out what version of a package I have (nor do I care how many
spaces or tabs there are before VERSION :-))

Other related questions are:

• Should all library code be contained within name spaces?
  (like the example module above)
• Should we have a naming convention for loading modules?

It also brings up the general question - is there a will within those
who develop ruby modules to adhere to some simple standards like this?
What procedure would we use to make it somewhat official?

-Tom

[James6 (James)]

[…]

Dave,

Thanks for spelling all that out; it’s most interesting. In fact, at some
levels it mirrors what James and I were discussing on the ruby-doc ML a couple
of weeks ago - it’s just that your vision is a bit wider.

So I’d like to help where I can. My time is a bit tight at the
moment as well.
We’re waiting to see where Jim Freeze takes the Ruby-Doc group at the moment,
but basically we’d be aiming to help create the vision you’ve spelled out,
among other (organisational) things.

Dave explained his vision for RDoc to Jim and I at RubyConf 2002, and while I do
not want to speak for Jim , I believe it satisfies many of the goals outlined on
ruby-doc.

My work on Rimport, and to some extent ruby-doc.org, were sort of “gee, I wonder
if …” type things, and were fairly easy to implement. Throwing a web
interface over ri was low-hanging fruit. But I’d rather not spend time hacking
add-ons when there’s a opportunity to do it right.

So, Dave, I’m offering my help to work on RDoc.

James

···

Cheers,
Gavin

[Jostein_Berntsen]

Hi, built. Plus there’s the “Powered by Ruby” button. Maybe we need a
“100%
pure Ruby” button?

• Are there any documentation for using eRuby?

I imagine there is, but it’s not explicitly listed on the site. Perhaps
the site could have a taxonmy/hierachical/something page to direct users to
known documentation (on the site or elsewhere) based on category/purpose.

Hi,

Does anyone know of any decent eRuby documentation and/or tutorials? I could
wish for something like http://www.php.net/

Jostein

···

On Sunday 10 November 2002 18:12, JamesBritt wrote:

[Thomas_Hurst]

Yes, I know. I was refering, however, to their use as containers for
things such as headings and paragraphs where more semantically rich tags
already exist for them.

Compare the source of:

http://www.ruby-doc.org/

with my (incomplete) 30-minute rewrite:

http://voi.aagh.net/designs/ruby-doc/1/

I use

extensively, but only to group other elements together and
provide objects I can style, rather than to contain actual content
directly (usually).

···

• Austin Ziegler (austin@halostatue.ca) wrote:

On Sun, 10 Nov 2002 23:07:47 +0900, Thomas Hurst wrote:

Since I think it’s important for sites like this to be accessable,
I’ve redone the markup for the front page using XHTML strict and
proper semantic tags rather than your

, and
soup. I’ll do the CSS in a bit, then upload it somewhere so you can
(hopefully) intergrae it back into the site

Note that XHTML strict still allows for

and . These tags,
in fact, are very useful.

–
Thomas ‘Freaky’ Hurst - freaky@aagh.net - http://www.aagh.net/

Q: What’s the difference between an Irish wedding and an Irish wake?
A: One more drunk.

[James6 (James)]

Hasn’t docbook been proposed for documentation in the past? I too
like the idea of having abstract logical document markup in XML and
then using a suite of tools to convert it into XHTML, plain HTML,
LaTeX, troff, PDF, etc. Indeed, docbook (or perhaps simplified
docbook, as docbook is very rich) was designed for this very purpose.
The sites http://www.docbook.org and
Index of /docbook/xml/simple decribe the XML and SGML
standards for docbook and simplified docbook.

Indeed, I think James Britt himself has mentioned using docbook for
embedded documentation. The site www.rubydoc.org is down right now,
otherwise I’d check to see if support for docbook is in the planning
stages.

I like DocBook as one of many possible end or intermediate forms, i.e., if you
plan on treating the information as book material, DocBook may be a realy good
choice. I don’t recall ever endorsing DocBook for embedded documentation
(though it’s conceivable), since hand-editing XML is a pain in the ass.

To be sure, it would be useful if RDoc could emit DocBook XML, but if the
default RDoc XML contains sufficient semantic information then converting it to
DocBook (or whatever else) should be straightforward.

However, while the data emitted by RDoc is most likely intended for use as
documentation, it shouldn’t be burdened with a tag set that is perhaps not
focused on source code semantics. The RDoc XML element set should be designed
to capture the semantic information of Ruby code, not a book. DocBook may not
have the best model for the expression of relationships as found in dynamic, OO
code.

James

···