4 ms·

I really wish that Ruby had an actual language reference instead of just the core and stdlib docs. If those same docs were versioned and updated along with the

I really wish that Ruby had an actual language reference instead of just the core and stdlib docs. If those same docs were versioned and updated along with the code, then changes in the language would have docs changes that could be linked together into a "What's New" section. Decent basic tutorial material wouldn't hurt either. This is an area where so many other languages like Python[1], Go[2], etc. get it right. The only semblance of an online language reference is a version of the Pickaxe book that was already out of date back when Rails was a screaming v1.0 newborn. [1] Python language ref: http://docs.python.org/3/reference/index.html http://docs.python.org/3/reference/index.html [2] Go language ref: http://golang.org/ref/spec http://golang.org/ref/spec

steveklabnik 13y ago
There is an ISO standard for 1.8.7 and RubySpec for all versions.
- VeejayRampay 13y ago
  Though 1.8.7 was released more than 5 years ago (and the language has evolved a lot since then) and the RubySpec are usually not up to date, at least not documenting all the features as they come in (as Brian Ford and others have pointed out several times). Not to be an ungrateful d*ck, I think the progress made is fantastic and supported by a bunch of extremely dedicated, talented and courageous people, but there is something of a void in terms of Ruby-as-formally-specified-language, hard to deny. But as usual, I guess it's hard to find the manpower, the time and the money to support such efforts.
  - steveklabnik 13y ago
    Yup. I totally agree with you, a formal spec would be great. But it's not in the cards, so we do the best with what we've got.
- saidajigumi 13y ago
  Not to be rude, but 1.8.7 is dead. RubySpec is first, not linked from [1] and second, just about completely inaccessible to someone not already familiar with Ruby. It's an executable specification, not a language reference manual. It's aims, structure, and information architecture are inappropriate for the purposes of a human with questions about the language, ala "what's the syntax and semantics for X in Ruby 2.0?" (for X = case, method definition, etc., etc.) We're already starting to see third-party sources bitrotting. E.g. eigenclass' 1.9 pages are now gone. Without an authoritative source for "What's new in 1.9.x?" and later, this bitrot will get worse and make it needlessly painful for folks who still need to move 1.8 code (or brains...) to 1.9/2.0. Part of my point is that the sources directly linked from ruby-lang.org are a mish-mash as well. There's virtually nothing authoritative, maintained by ruby-lang.org itself. The links at [1] are a mix of ok, good, and rather out of date. ruby-doc.org, not linked from [1] (wat.), is about as good as we've got for a standard reference. Sadly, it's missing the language reference piece and it's auto-generated information architecture sucks hard. An example of that last point: hit [2]. What's above the fold? A useless list of files. Scroll down and you'll eventually get to the filterable lists of core classes and methods. Click on "Array"[3] and we actually get a nice summary doc with examples that walks us through this class. For comparison, we'll go to the standard library[4]. Click on "net/http" in the left sidebar[5]. Instead of getting a nice summary page, instead we get an opaque class and method list. The reader is left to divine which, if any, link might provide some clues about the use and organization of this library. (Hint: it's "Net::HTTP", third from the top on the left.) If you already know which is the "main" class for this library, then you can usually guess right. It's ridiculous for reference material to assume the user is already familiar with it in order to successfully navigate it. Again, other languages' library references do a much better job w.r.t. navigability. Coda: I don't mean to harsh on ruby-doc.org too much; it's just a central example in the Ruby world. Nevertheless I feel the need to highlight how the Ruby community's disconnected, scattershot approach to documentation presents both a user education and a marketing problem. [1] https://www.ruby-lang.org/en/documentation/ https://www.ruby-lang.org/en/documentation/ [2] http://ruby-doc.org/core-2.0.0/ http://ruby-doc.org/core-2.0.0/ [3] http://ruby-doc.org/core-2.0.0/Array.html http://ruby-doc.org/core-2.0.0/Array.html [4] http://ruby-doc.org/stdlib-2.0.0/ http://ruby-doc.org/stdlib-2.0.0/ [5] http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/index.html http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/index....

steveklabnik 13y ago

There is an ISO standard for 1.8.7 and RubySpec for all versions.

VeejayRampay 13y ago
Though 1.8.7 was released more than 5 years ago (and the language has evolved a lot since then) and the RubySpec are usually not up to date, at least not documenting all the features as they come in (as Brian Ford and others have pointed out several times). Not to be an ungrateful d*ck, I think the progress made is fantastic and supported by a bunch of extremely dedicated, talented and courageous people, but there is something of a void in terms of Ruby-as-formally-specified-language, hard to deny. But as usual, I guess it's hard to find the manpower, the time and the money to support such efforts.
- steveklabnik 13y ago
  Yup. I totally agree with you, a formal spec would be great. But it's not in the cards, so we do the best with what we've got.
saidajigumi 13y ago
Not to be rude, but 1.8.7 is dead. RubySpec is first, not linked from [1] and second, just about completely inaccessible to someone not already familiar with Ruby. It's an executable specification, not a language reference manual. It's aims, structure, and information architecture are inappropriate for the purposes of a human with questions about the language, ala "what's the syntax and semantics for X in Ruby 2.0?" (for X = case, method definition, etc., etc.) We're already starting to see third-party sources bitrotting. E.g. eigenclass' 1.9 pages are now gone. Without an authoritative source for "What's new in 1.9.x?" and later, this bitrot will get worse and make it needlessly painful for folks who still need to move 1.8 code (or brains...) to 1.9/2.0. Part of my point is that the sources directly linked from ruby-lang.org are a mish-mash as well. There's virtually nothing authoritative, maintained by ruby-lang.org itself. The links at [1] are a mix of ok, good, and rather out of date. ruby-doc.org, not linked from [1] (wat.), is about as good as we've got for a standard reference. Sadly, it's missing the language reference piece and it's auto-generated information architecture sucks hard. An example of that last point: hit [2]. What's above the fold? A useless list of files. Scroll down and you'll eventually get to the filterable lists of core classes and methods. Click on "Array"[3] and we actually get a nice summary doc with examples that walks us through this class. For comparison, we'll go to the standard library[4]. Click on "net/http" in the left sidebar[5]. Instead of getting a nice summary page, instead we get an opaque class and method list. The reader is left to divine which, if any, link might provide some clues about the use and organization of this library. (Hint: it's "Net::HTTP", third from the top on the left.) If you already know which is the "main" class for this library, then you can usually guess right. It's ridiculous for reference material to assume the user is already familiar with it in order to successfully navigate it. Again, other languages' library references do a much better job w.r.t. navigability. Coda: I don't mean to harsh on ruby-doc.org too much; it's just a central example in the Ruby world. Nevertheless I feel the need to highlight how the Ruby community's disconnected, scattershot approach to documentation presents both a user education and a marketing problem. [1] https://www.ruby-lang.org/en/documentation/ https://www.ruby-lang.org/en/documentation/ [2] http://ruby-doc.org/core-2.0.0/ http://ruby-doc.org/core-2.0.0/ [3] http://ruby-doc.org/core-2.0.0/Array.html http://ruby-doc.org/core-2.0.0/Array.html [4] http://ruby-doc.org/stdlib-2.0.0/ http://ruby-doc.org/stdlib-2.0.0/ [5] http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/index.html http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/index....