RDoc 2.4.1

Eric Hodel | Fri, 27 Feb 2009 03:19:22 GMT

RDoc is an application that produces documentation for one or more Ruby source files. RDoc includes the rdoc and ri tools for generating and displaying online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur further API changes beyond what has been made to RDoc 1.0.1. Command-line tools are largely unaffected, but internal APIs may shift rapidly.

See RDoc for a description of RDoc’s markup and basic use.

Changes:

  • 1 Minor Enhancements
    • Added :attr:, :attr_reader:, :attr_writer:, :attr_accessor: directives. Replaces—accessor. See RDoc::Parser::Ruby for details.
  • 3 Bug Fixes
    • Don’t complain when exiting normally. Bug by Matt Neuburg.
    • Restore—inline-source that warns
    • Fixed links to files in Darkfish output

Posted in , ,  | no comments

RDoc 2.4.0

Eric Hodel | Wed, 25 Feb 2009 06:02:13 GMT

RDoc is an application that produces documentation for one or more Ruby source files. RDoc includes the rdoc and ri tools for generating and displaying online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur further API changes beyond what has been made to RDoc 1.0.1. Command-line tools are largely unaffected, but internal APIs may shift rapidly.

Project Page RDoc Documentation

Changes

  • 9 Minor Enhancements
    • `ri -f html` is now XHTML-happy
    • Clarified RDoc::Markup link syntax. Bug #23517 by Eric Armstrong.
    • Number of threads to parse with is now configurable
    • Darkfish can now use alternate templates from $LOAD_PATH via -T
    • Removed F95 parser in favor of the rdoc-f95 gem
    • Moved HTML and XML generators to unmaintained
      • No gem will be provided as it’s too difficult to make them work
      • Removed options—one-file,—style=,—inline-source,—promiscuous, —op-name
    • Removed support for—accessor, use regular documentation or the method directive instead. See RDoc::Parser::Ruby
    • Removed—ri-system as it is unused by Ruby’s makefiles
    • Added method list to index.html
  • 6 Bug Fixes
    • nodoc’d classes no longer appear in the index. Bug #23751 by Clifford Heath.
    • Fix 1.9 compatibility issues. Bug #23815 by paddor.
    • Darkfish now respects—charset
    • RDoc no longer attempts to be lazy when building HTML. This is a workaround. Bug #23893 by Stefano Crocco.
    • RDoc doesn’t crash with def (blah).foo() end
    • RDoc doesn’t crash with #define functions

Posted in ,  | no comments

A RubyGems + GitHub proposal

Eric Hodel | Thu, 05 Feb 2009 02:33:09 GMT

I know many people have added GitHub to their RubyGems sources list and find it sub-optimal. For example, Nokogiri is installed via gem install nokogiri from RubyForge and gem install tenderlove-nokogiri from GitHub. Furthermore, it’s possible to create a username/gem name combo on GitHub that overlaps a RubyForge name which could lead to pain and suffering for GitHub users.

I’ve come up with a potential solution to this problem:

  • Add an alias name attribute to gem specifications that point to the “RubyForge name” for the gem
  • Add an index to the gem server that maps alias names to “RubyForge names”
  • Only signed gems with an alias name will be included in this index
  • When RubyGems looks for a gem to install it considers aliased gems as exact matches for a name, provided they satisfy the user’s trust policy

Using this solution, a user could install a gem that has a dependency on nokogiri. If nokogiri is signed on GitHub and there’s a newer version on GitHub than on RubyForge, the GitHub version would be installed.

Here are some discussions points this solution presents:

  • GitHub currently builds gems for authors, so it is impossible for these gems to be signed. GitHub would have to store the author’s private key for signing.
  • By default RubyGems sets no security policy, so it doesn’t address the name overlap problem (this default could be changed)
  • Furthermore, it would not prevent a trusted author from turning rogue
  • Using a trust policy, a user can choose to pull gems from GitHub for specific authors by trusting the author’s public key (e.g. only install signed gems, only install trusted gems)
  • There’s no infrastructure for easily trusting an author’s key (beyond gem cert)
  • It doesn’t give GitHub a central authority for gems, but one could be built through a web of trust

Posted in  | 21 comments