ruby-core

On Thursday, December 18, 2003, 1:08:17 PM, Dave wrote:

> On Dec 17, 2003, at 18:45, James Brtt wrote:
>> Are 'rdoc' directories only for the output of running rdoc?  I'm 
>> guessing not, but if these are directories for documentation in 
>> general, would it not be better to call them simply 'doc'?
>>
> Yes - they're simply for rdoc output (given that that's the tool I'm
> writing). I certainly don't want to be telling other people where to
> put stuff: I just needed to make sure that I put the things I need in
> the correct place.

>> Or is there a reason to distinguish between what comes from RDoc and
>> other doc sources?

> Yes: the intermediate form that RDoc generates for ri is not for human
> consumption. That's what's going in to these directories. When RDoc 
> generates HTML (or anything else, really) it will do it the same as 
> now, defaulting to a doc subdirectory with --op used to override that.

Has that been the premise all along?  Have you been talking only about
'ri' data?  I thought the question "where to install documentation"
concerned RDoc HTML output as well.

I'm happy with 'ri' data going in $datadir, and with the directories
proposed (they didn't appear to concern themselves with Ruby version,
though?).  It is "data", after all.

I don't understand what is meant by "$datadir is configurable", as it
appears to be set within rbconfig.rb.

As for RDoc HTML output, I think we need to move towards enabling that
to be installed as system, site-wide, or user documentation, and that
we need to consider RDoc as being one part of the documentation
puzzle.  I'm not suggesting that RDoc needs to "do" any of this ...
yet.  What we need is:
  - agreed standard *documentation* directories (system, site-wide,
    user) that are accessible through rbconfig.rb
  - a package installer that makes use of the above
    - modifying install.rb/setup.rb will be trivial
    - rake can be made to take on this job as well
    - RubyGems takes a self-contained approach, and/but it's a step in
      the right direction

As RDoc is now part of the standard distribution, it should also play
its part in the standard Ruby documentation interface.  Therefore,
commands like the following may one day be realistic:

  rdoc --system ...
  rdoc --site-wide ...
  rdoc --user ...

However, with hypothetical good installers providing everything RDoc
needs to "do the right thing" (i.e. a good argument to --op), the
above shouldn't really be necessary.

Anyway, I have been planning an RCR on enabling a good Ruby
documentation interface, and look forward to the new RCR process
coming online.  I hope it engenders some discussion and action,
because we can ill afford to keep ignoring the valid complaints that
Ruby documentation is not up to scratch.  And really, we have the
tools, the ability, and even the material in most cases; it's only
the process that's lacking.

The eventual RCR will have benefited from many words of wisdom in this
thread, as well as the sustained focus of the ruby-doc.org project/ML,
so thank you all for your input.

Cheers,
Gavin

Thread

Prev Next

In This Thread

Prev Next