On Mar 8, 1:54 pm, "Daniel Brumbaugh Keeney" <[EMAIL PROTECTED]> wrote:
> RubyGems is a package management system. It is common and appropriate > that documentation be distributed along with software. RubyGems is > unique, however, in that, with a particular documentation system, it > generates the documentation on the user's computer, rather than > generating it during packaging and including it within the package. It > is important to note, that of course any documentation system could be > used and distributed within the gem as is common in other packaging > systems. However, I consider the fact that documentation is generated > on the user's computer to be a significant feature of RubyGems, and > agree that it is worthwhile to ensure that an alternative > documentation system could be similarly integrated. > > I agree with your solution, that it should be possible to have a Ruby > script, included in the gem, should be executed after installation of > the gem. That permits the use of arbitrary programs for documentation, > such as rdoc, or other install procedures, such as adding menu items, > currently not possible during RubyGems' install process. This, as > well, I consider to be a major flaw in RubyGems, which a post-install > script would cleanly solve. Of course, this would also require a > pre-removal script, and it is important to consider the authority > these scripts will be given. Basically, I think it's a fantastic idea. > > However, I think that same idea directly conflicts with your other > proposal. As it stands, it should be fairly simple to allow > customization of rdoc generation, having local options override ones > contained in the gem, since the rdoc command is neatly separated. Don't get me wrong. I'm not against having an rdoc generation feature. That's fine. I'm only saying that it would be better for this feature to participate in a broader convention, whereby it would generate those rdocs into a conventional directory location. That way we can supply there own pre-built docs, if we prefer, and RubyGems need not bother generating the rdocs --that's a simple way in fact for RubyGems to know if it should generate rdocs, rather than using the has_rdoc config, just look to see if there is any content in the conventional location or not. > If rdoc generation moves into a post-install script, it will become > much more difficult to override. Contained within an arbitrary script, > there would be no good way to separate the rdoc generation command and > override its options. This suggests that a special format or library > would be in use for post-install scripts, something like: > command_line_task( false, 'rdoc', "--main=README --title 'Cool Program'" ) > where false is in an indicator that it's okay if rdoc isn't available, > the program will still run. Then the user could set a local option to > append '--template=**' any commands to 'rdoc'. That's too complicated. I thought of it as a simple separate dedicated ruby script, not part of another arbitrary one. But the more I think about this the more I think this isn't needed. Either let RubyGems generate the rdocs or supply a pre-built set in the package. That's enough. The need for pre- and post- install scripts is a separate question. > Anyhow, I would suggest making a way for the user to change rdoc > options locally first, since that should be fairly simple. Adding > post-install and pre-removal scripts would be a major change to > RubyGems, but I think it's the right choice. The template is probably the only rdoc option that it makes sense to let the user determine. In my modified setup.rb, in which I added an rdoc feature, I used an environment variable for this, RDOC_TEMPLATE. T. _______________________________________________ Rubygems-developers mailing list [email protected] http://rubyforge.org/mailman/listinfo/rubygems-developers
