Suggestions to the Ruby community

ruby-talk
1

I’ve been following the documentation discussion with some interest. Some
of this has focused on rd2.

At the risk of being branded a heretic by the Ruby Community, I believe
there’s an alternative that we haven’t considered.

POD.

That’s right - POD. POD as in Perl’s “Plain Old Data”. POD and rd2 are
markup languages. They have nothing to do with the language (i.e. Perl or
Ruby) itself. I can put rd2 documentation in a Perl module just as easily
as I can use POD to document my Ruby modules.

“But, but, but…the parsers are written in Perl!” - So what? A healthy
chunk of your gnu utilities are written in Perl. Many others are bash or
korn shell scripts. I’ll bet that doesn’t stop you from using those
tools.

“RDoc and POD aren’t the same, though” - You’re right. They create
different documents. But then, rd2 and RDoc are just as different. If you
prefer the documentation that RDoc generates, stick with RDoc.

“Why not stick with rd2?” - POD’s been around longer and the output looks
nicer. As a result of more years of development, there are several pod
tools for generating more output types, including man pages, latex, html and
plain text. That’s right, I said MAN pages. There are also tools for
reading nroff-like formatting (in addition to the man stuff) and even
colorizing. I haven’t even mentioned the parsing utilities that exist.

“But it’s not written in Ruby!” - So friggin’ what? Get over it.
Seriously, if you refuse to use a tool because of the language it’s written
in, you can put yourself in the “religious zealot” category right now.
Hell, even I use Eclipse, and I hate Java - but I like Eclipse. :slight_smile:

“Won’t this create confusion?” - If you’re really worried about it, you can
stick the POD in a separate file altogether. There’s no rule that says the
documentation has to be included in the source file. Just as long as there
is documentation. :slight_smile:

/me is now prepared for the kindling and matches.

Regards,

Dan

2

I personally am not opposed to looking at POD, and I ‘personally’ don’t have
any problems with it being written in Perl, because I use unix and
perl is part of the install. But I don’t think a solution should require
users (read windows) to install additional 3rd party software - like Perl.

With that said, it may be reasonable to look at porting the pod tools
to ruby…Just a thought.

···

On Thu, Sep 05, 2002 at 09:52:25PM +0900, Berger, Daniel wrote:

I’ve been following the documentation discussion with some interest. Some
of this has focused on rd2.

At the risk of being branded a heretic by the Ruby Community, I believe
there’s an alternative that we haven’t considered.

POD.

–
Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

3

In article 7DC1217518FCD311A08A0050DA78574003C6B5BF@iamspems04.interprise.com,

I’ve been following the documentation discussion with some interest. Some
of this has focused on rd2.

At the risk of being branded a heretic by the Ruby Community, I believe
there’s an alternative that we haven’t considered.

POD.

That’s right - POD. POD as in Perl’s “Plain Old Data”. POD and rd2 are
markup languages. They have nothing to do with the language (i.e. Perl or
Ruby) itself. I can put rd2 documentation in a Perl module just as easily
as I can use POD to document my Ruby modules.

    • Actually this jibes with some thoughts I’ve had as well. I
      think it would be very cool if rdoc could output POD or rd2.
      I’m not sure what the easiest path is whether to try and
      transform the xml output or just write a rd2/POD generator.
    • POD’s great advantage is that you actually don’t need any tools
      to read it. rd2 is fairly readable as well. If we could
      standardize on an output format that was easily transformable
      and easily parsable, they lot’s of handy reference tools could
      be built. Here’s my thoughts for moving forward.

    1. Get rdoc to write out rd2

    2. Teach ri to read rd2 and look for it in installed ruby libs.

    3. Write some documentation and stick it on the ruby-lang.org
      wiki. The Japanese Ruby Doc project seems to be getting
      regular input. The english side hasn’t been touched in over
      a year.

    • Booker C. Bense
···

Berger, Daniel djberge@qwest.com wrote:

4

Not a bad idea. But I imagine the ability to grab a Ruby distribution,
install it, and being able to start viewing/extracting/whatever the docs
right away. I’d rather not have to go and install Perl (which isn’t
installed by default on Windows boxen).

James

···

-----Original Message-----
From: Berger, Daniel [mailto:djberge@qwest.com]
Sent: Thursday, September 05, 2002 5:52 AM
To: ruby-talk ML
Subject: RE: suggestions to the Ruby community

I’ve been following the documentation discussion with some interest. Some
of this has focused on rd2.

At the risk of being branded a heretic by the Ruby Community, I believe
there’s an alternative that we haven’t considered.

POD.

That’s right - POD. POD as in Perl’s “Plain Old Data”. POD and rd2 are
markup languages. They have nothing to do with the language (i.e. Perl or
Ruby) itself. I can put rd2 documentation in a Perl module just as easily
as I can use POD to document my Ruby modules.

5

The reasons for using POD are good, but here are the cons:

  • relying on Perl installation is not good (as above)
  • porting to Ruby is questionable - need to keep up-to-date
  • we already have doc formats in Ruby; let’s evolve them and
    “almost port” POD if necessary (I don’t even know what in
    particular is so great about it).

I think it’s time we started a new thread; even better, a new ML!

Gavin

···

----- Original Message -----
From: " JamesBritt" james@jamesbritt.com

-----Original Message-----
From: Berger, Daniel [mailto:djberge@qwest.com]
Sent: Thursday, September 05, 2002 5:52 AM
To: ruby-talk ML
Subject: RE: suggestions to the Ruby community

I’ve been following the documentation discussion with some interest. Some
of this has focused on rd2.

At the risk of being branded a heretic by the Ruby Community, I believe
there’s an alternative that we haven’t considered.

POD.

That’s right - POD. POD as in Perl’s “Plain Old Data”. POD and rd2 are
markup languages. They have nothing to do with the language (i.e. Perl or
Ruby) itself. I can put rd2 documentation in a Perl module just as easily
as I can use POD to document my Ruby modules.

Not a bad idea. But I imagine the ability to grab a Ruby distribution,
install it, and being able to start viewing/extracting/whatever the docs
right away. I’d rather not have to go and install Perl (which isn’t
installed by default on Windows boxen).

James

6

I second that.

To an all knowing Rubyist: Here is my plea:

How do we get a ruby-doc@ruby-lang.org mailing list setup??

Thanks

···

On Fri, Sep 06, 2002 at 01:02:08AM +0900, Gavin Sinclair wrote:

I think it’s time we started a new thread; even better, a new ML!

Gavin

–
Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

7

“Gavin Sinclair” gsinclair@soyabean.com.au writes:

  • we already have doc formats in Ruby; let’s evolve them and
    “almost port” POD if necessary (I don’t even know what in
    particular is so great about it).

I for one would be very interested in this. What would we want to add
to rdoc format to make it more generally useful.

Tables of contents and indices spring to mind. There are also some
great ideas on the Feature Request list on SourceForge.

I’d be very happy to open up RDoc development to get it moving forward
if folks were interested.

Cheers

Dave

8

In article 02c901c254f5$7a04c990$f51032d2@nosedog, Gavin Sinclair wrote:

The reasons for using POD are good, but here are the cons:

  • relying on Perl installation is not good (as above)
  • porting to Ruby is questionable - need to keep up-to-date
  • we already have doc formats in Ruby; let’s evolve them and
    “almost port” POD if necessary (I don’t even know what in
    particular is so great about it).

I think it’s time we started a new thread; even better, a new ML!

Does ML mean mailing list or markup language here?

If you’re looking for a non-POD markup then SDF may be worth a look.
http://www.xpenguin.biz/download/sdf/doc/ and
http://www.xpenguin.biz/download/sdf/doc/paper/sdfintro.html are good
starting points.

I’m not advocating anything here, merely pointing out that others have
been here before…

Mike

···

–
mike@stok.co.uk | The “`Stok’ disclaimers” apply.
http://www.stok.co.uk/~mike/ | GPG PGP Key 1024D/059913DA
mike@exegenix.com | Fingerprint 0570 71CD 6790 7C28 3D60
http://www.exegenix.com/ | 75D2 9EC4 C1C0 0599 13DA

9

Some features I can think of are:

  1. output to single page html
  2. output to man page
  3. output to ri format

BTW, Dave, my requests for a mailing list have gone
unheeded. What are your thoughts on a ruby-doc mailing
list for all this traffic? Can you facilitate the creation
of such a list?

···

On Fri, Sep 06, 2002 at 01:41:37AM +0900, Dave Thomas wrote:

“Gavin Sinclair” gsinclair@soyabean.com.au writes:

  • we already have doc formats in Ruby; let’s evolve them and
    “almost port” POD if necessary (I don’t even know what in
    particular is so great about it).

I for one would be very interested in this. What would we want to add
to rdoc format to make it more generally useful.

Tables of contents and indices spring to mind. There are also some
great ideas on the Feature Request list on SourceForge.

I’d be very happy to open up RDoc development to get it moving forward
if folks were interested.

From my perspective, I think that rdoc fits the bill nicely.

Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

10

Hi,

···

In message “Re: suggestions to the Ruby community” on 02/09/06, Jim Freeze jim@freeze.org writes:

To an all knowing Rubyist: Here is my plea:

How do we get a ruby-doc@ruby-lang.org mailing list setup??

Thanks

OK, I will set up the list soon.

						matz.
11

“Gavin Sinclair” gsinclair@soyabean.com.au writes:

  • we already have doc formats in Ruby; let’s evolve them and
    “almost port” POD if necessary (I don’t even know what in
    particular is so great about it).

I for one would be very interested in this. What would we want to add to
rdoc format to make it more generally useful.

Good question.

Tables of contents and indices spring to mind. There are also some great
ideas on the Feature Request list on SourceForge.

I’d be very happy to open up RDoc development to get it moving forward
if folks were interested.

This will probably be one of the aims of the Commitee for Liberation of
People’s Front of Judea …, er … RDP.

Cheers
Dave

Gavin

12

Jim Freeze wrote:

BTW, Dave, my requests for a mailing list have gone
unheeded. What are your thoughts on a ruby-doc mailing
list for all this traffic? Can you facilitate the creation
of such a list?

Since rdoc is already on sourceforge this should be trivial as sourceforge
has built-in facilities for setting up a ML.

Curt

13

In article 20020905135318.A80433@freeze.org,

“Gavin Sinclair” gsinclair@soyabean.com.au writes:

  • we already have doc formats in Ruby; let’s evolve them and
    “almost port” POD if necessary (I don’t even know what in
    particular is so great about it).
    • The great part about POD is that it isn’t great, it’s the
      absolute minimum required to provide some structure to a
      document. You can quite easily read it with /bin/cat.

I for one would be very interested in this. What would we want to add
to rdoc format to make it more generally useful.

Tables of contents and indices spring to mind. There are also some
great ideas on the Feature Request list on SourceForge.

I’d be very happy to open up RDoc development to get it moving forward
if folks were interested.

From my perspective, I think that rdoc fits the bill nicely.
Some features I can think of are:

  1. output to single page html
  2. output to man page
  3. output to ri format
    • An rd2 output format would take care of the first two. I think
      there’s a lot of potential in the idea of using rdoc as the
      document creating tool and something POD-like as the output
      format. The one problem that I see is that rdoc produces
      output that is some ways “ruby-smart”, it knows methods belong
      to classes. It would be good if the basic output format
      could preserve that knowledge in some way. As far as I know,
      rd2 is just markup.
    • Also, there is quite a bit of existing rd documentation
      already. There’s just been no unified way to get at it.
    • Booker C. Bense
···

Jim Freeze jim@freeze.org wrote:

On Fri, Sep 06, 2002 at 01:41:37AM +0900, Dave Thomas wrote:

14

Thanks Matz!

···

On Fri, Sep 06, 2002 at 09:46:08AM +0900, Yukihiro Matsumoto wrote:

Hi,

In message “Re: suggestions to the Ruby community” > on 02/09/06, Jim Freeze jim@freeze.org writes:

To an all knowing Rubyist: Here is my plea:

How do we get a ruby-doc@ruby-lang.org mailing list setup??

Thanks

OK, I will set up the list soon.

  					matz.

–
Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

15

If ML means mailing list, then I’m not sure that is the place
to put the rdoc ML since ‘rdoc’ is only a tool and does
not cover the entire Ruby documentation project.

···

On Fri, Sep 06, 2002 at 03:04:17AM +0900, Curt Hibbs wrote:

Jim Freeze wrote:

BTW, Dave, my requests for a mailing list have gone
unheeded. What are your thoughts on a ruby-doc mailing
list for all this traffic? Can you facilitate the creation
of such a list?

Since rdoc is already on sourceforge this should be trivial as sourceforge
has built-in facilities for setting up a ML.

–
Jim Freeze

Programming Ruby
def initialize; fun; end
A language with class

16

bbense+comp.lang.ruby.Sep.05.02@telemark.stanford.edu writes:

An rd2 output format would take care of the first two. I think
there’s a lot of potential in the idea of using rdoc as the
document creating tool and something POD-like as the output
format. The one problem that I see is that rdoc produces
output that is some ways “ruby-smart”, it knows methods belong
to classes. It would be good if the basic output format
could preserve that knowledge in some way. As far as I know,
rd2 is just markup.

I’m not sure I see the benefit in the intermediate rd2 or POD
step. RDoc already generates XML, so just about any format you need is
just an XSL transform away, and I personally believe that RDoc format
is just as readable as POD. Remember too that RDoc doesn’t just work
on Ruby source: you can feed it text files and it’s quite happy.

Dave

17

Hi,

···

In message “Re: suggestions to the Ruby community” on 02/09/06, Jim Freeze jim@freeze.org writes:

OK, I will set up the list soon.

Thanks Matz!

I think it’s done. Try ruby-doc@ruby-lang.org.
You jim@freeze.org and me are already registered.

						matz.
18

Yukihiro Matsumoto wrote:

I think it’s done. (ruby-doc mailing list)

Worked for me. I used mailto:ruby-doc-ctl@ruby-lang.org with

subscribe First-name Last-name

in the body.

BTW: the confirmation email has a typo: ‘fucntion’.

···

–
Bil

19

In article m2sn0o45em.fsf@zip.local.thomases.com,

bbense+comp.lang.ruby.Sep.05.02@telemark.stanford.edu writes:

An rd2 output format would take care of the first two. I think
there’s a lot of potential in the idea of using rdoc as the
document creating tool and something POD-like as the output
format. The one problem that I see is that rdoc produces
output that is some ways “ruby-smart”, it knows methods belong
to classes. It would be good if the basic output format
could preserve that knowledge in some way. As far as I know,
rd2 is just markup.

I’m not sure I see the benefit in the intermediate rd2 or POD
step. RDoc already generates XML, so just about any format you need is
just an XSL transform away, and I personally believe that RDoc format
is just as readable as POD.

    • I’m not argueing that, I guess there’s some confusion of terms,
      I view “rdoc” as a document writing tool. Perhaps we should
      call “rdoc” the tool and RDoc the formatting conventions.

Remember too that RDoc doesn’t just work
on Ruby source: you can feed it text files and it’s quite happy.

    • Well as I see it there are two things missing in the ruby doc
      world.

    1. A standard output format

    2. A standard place to find it.

    • rdoc does not solve either of these problems. POD solves them
      by

    a. being trivial

    b. Always being between the =begin and =end part of the
    installed module.

    Once you have these two things, you can write all kinds of
    document tools. In some ways rdoc is “just too damn smart”,
    it takes plain code and produces useful documentation. However,
    since the rdoc “src” is scattered all over the original src
    code, getting docs on the fly is somewhat difficult.

    I’ve taken a closer look at rd and it at least knows enough
    Ruby to differentiate method lists from regular lists.

    • If you want to emulate perldoc, then you could use XML as
      and intermediate format, but IMHO, XML is unreadable and
      there’s the question of where to put it. It also raises
      the bar for tool writers, although I guess XML is now ubiquitous
      enough that is not that much of an issue.
    • I guess I’m just enough of a Unix Luddite that I think there’s
      a significant advantage to having a document format
      that I can use /bin/cat on. The other advantages I see are

  1. Play nice with the people already happily using rdtool.

  2. Possible to include all the tools required to do documentation
    in a ruby-only code with the standard distribution.

    • Perhaps, we could clarify the situation with a couple use
      cases, I’d like a tool that could answer these questions.

      “Show me all the installed library objects that have
      a read method.”

      “Show me the names of all the installed classes.”

    • I could brute force this by running rdoc on all the installed
      ruby src and then grepping the XML… I’d kind of like a more
      elegant solution. How were you planning to generalize ri from
      rdoc output?
    • Booker C. Bense
···

Dave Thomas Dave@PragmaticProgrammer.com wrote:

20

Hi,

···

In message “Re: suggestions to the Ruby community” on 02/09/06, Bil Kleb W.L.Kleb@larc.nasa.gov writes:

BTW: the confirmation email has a typo: ‘fucntion’.

Oops, thank you.

						matz.