# The ruby syntax
**URL:** https://rubytalk.org/t/the-ruby-syntax/64881
**Category:** ruby-talk
**Created:** [12 February 2012 12:36 UTC](https://rubytalk.org/t/the-ruby-syntax/64881 "2012-02-12T12:36:42Z")
**Posts on this page:** 19
**Page:** 1
### Author:  [@maven\_apache](https://rubytalk.org/u/maven_apache)
#### Post date: [12 February 2012 12:36 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/1 "2012-02-12T12:36:42Z")
Hi:
I like ruby the first time I read its document.
However then I found that the syntax is too fliexible to learn it.
For example:
The IO.open method,this is the api page:
> **[Class: IO (Ruby 1.9.3)](https://ruby-doc.org/core-1.9.3/IO.html#method-c-new)**
>
> Class : IO - Ruby 1.9.3
This is the argument of this method:
new(fd [, mode] [, opt])
I am confused by the third argument-'opt'.
Is its type is 'hash'??
If so I think this is the way to call it:
> new("data.txt", "w",{:encoding=\>'xxx',:autoclose=\>true...})
But I found so many people call it like this:
IO.new("data.txt", mode: 'w:UTF-16LE', cr\_newline: true)
What does this mean?
'data.txt' is the first argument. How about the others? which is the
second? and which is the third?
> **···**
>
> -------------------------------
>
> BTW, the above is just an example,in fact I found so many syntax that I can
> not understand.
>
> So I wonder if there is any documents cover all of ruby's \*fiexible\* syntax?
---
### Author:  [@11142](https://rubytalk.org/u/11142)
#### Post date: [12 February 2012 13:14 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/2 "2012-02-12T13:14:36Z")
When a hash is the last argument to a method, you can skip its open-
and close-braces.
So this:
IO.new("data.txt", mode: 'w:UTF-16LE', cr\_newline: true)
Is the same as this:
IO.new("data.txt", {mode: 'w:UTF-16LE', cr\_newline: true})
The first argument is the "data.txt" string, the second argument is
the entire hash. The method then checks the type of second argument,
and in this case - since it's a hash - it considers it to be the opt
variable, with mode taking default value.
-- Matma Rex
---
### Author:  [@Josh\_Cheek](https://rubytalk.org/u/Josh_Cheek)
#### Post date: [12 February 2012 13:32 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/3 "2012-02-12T13:32:50Z")
I don't know of one, I'd recommend an alternative that when you see syntax
like this, you make a hypothesis about how it works, then go test your
hypothesis. In this case, you could just write a method that prints the
inspection of its arguments, then try calling it both ways to see what
happens. If it contradicts your hypothesis, modify it to accomodate the new
information.
> **···**
>
> On Sun, Feb 12, 2012 at 6:36 AM, maven apache \wrote:
>
> > BTW, the above is just an example,in fact I found so many syntax that I can
> > not understand.
> >
> > So I wonder if there is any documents cover all of ruby's \*fiexible\*
> > syntax?
---
### Author:  [@maven\_apache](https://rubytalk.org/u/maven_apache)
#### Post date: [12 February 2012 13:49 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/4 "2012-02-12T13:49:11Z")
> When a hash is the last argument to a method, you can skip its open-
> and close-braces.
>
> So this:
> IO.new("data.txt", mode: 'w:UTF-16LE', cr\_newline: true)
> Is the same as this:
> IO.new("data.txt", {mode: 'w:UTF-16LE', cr\_newline: true})
But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
Definiation of a hash should like this:
{'key'=\>'value'.....}
Now in the IO.new exmaple,it is written as {key:value}. Is the ':' symbol
same as '=\>'?? I do not find it is methioned in any document.
> **···**
>
> 2012/2/12 Bartosz Dziewoński \
>
> > The first argument is the "data.txt" string, the second argument is
> > the entire hash. The method then checks the type of second argument,
> > and in this case - since it's a hash - it considers it to be the opt
> > variable, with mode taking default value.
> >
> > -- Matma Rex
---
### Author:  [@11142](https://rubytalk.org/u/11142)
#### Post date: [12 February 2012 14:49 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/5 "2012-02-12T14:49:45Z")
There are two ways to define a hash.
First is, as you are saying, {key =\> value}, where both key and value
can be anything. {'key' =\> 'value'} is okay (key and value are
strings), but for example this is also valid: { [1,2] =\> {3 =\> 4} }
(here key is an array, value is another hash).
The second way, introduced in Ruby 1.9, is {key: value}. Value is
still an arbitrary Ruby value, but the key is converted to a Symbol -
so this: {key: value} is equivalent to this: {:key =\> value}. The
second method is less typing, so it's more often used now, when you
don't care about compatibility with Ruby 1.8, and you are fine with
your keys all being symbols.
You can also mix both styles in a single hash definition.
-- Matma Rex
> **···**
>
> 2012/2/12 maven apache \:
>
> > But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> >
> > Definiation of a hash should like this:
> >
> > {'key'=\>'value'.....}
> >
> > Now in the IO.new exmaple,it is written as {key:value}. Is the ':' symbol
> > same as '=\>'?? I do not find it is methioned in any document.
---
### Author:  [@Josh\_Cheek](https://rubytalk.org/u/Josh_Cheek)
#### Post date: [12 February 2012 15:13 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/6 "2012-02-12T15:13:52Z")
So, again, you could figure out the answer to this by writing a method that
simply prints the inspection of its args. Try this:
def meth(arg)
p arg
end
meth {:a =\> 'b'}
# ~\> -:5: syntax error, unexpected tASSOC, expecting '}'
# ~\> ...9178\_68393\_18610 = (meth {:a =\> 'b'});$stderr.puts("!XMP1329...
# ~\> ... ^
# hmm, that's strange, what if I do this?
meth({:a =\> 'b'})
# \>\> {:a=\>"b"}
# well that worked, I wonder why (contemplate it for later, or ask if you
can't figure it out)
# now what about those curly braces?
meth(:a =\> 'b')
# \>\> {:a=\>"b"}
# okay, I guess they are the same.
# now I was thinking that the ':' symbol is same as '=\>', lets see
meth(a: 'b')
# \>\> {:a=\>"b"}
# aah, apparently it is... but wait, what if I have a number for a key?
meth(1: 'b')
# ~\> -:5: syntax error, unexpected ':', expecting ')'
# ~\> meth(1: 'b')
# ~\> ^
# ~\> -:5: syntax error, unexpected ')', expecting $end
# Hmm, maybe it only works for symbol arguments
# ... etc ...
> **···**
>
> On Sun, Feb 12, 2012 at 7:49 AM, maven apache \wrote:
>
> > 2012/2/12 Bartosz Dziewoński \
> >
> > \> When a hash is the last argument to a method, you can skip its open-
> > \> and close-braces.
> > \>
> > \> So this:
> > \> IO.new("data.txt", mode: 'w:UTF-16LE', cr\_newline: true)
> > \> Is the same as this:
> > \> IO.new("data.txt", {mode: 'w:UTF-16LE', cr\_newline: true})
> > \>
> >
> > But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> >
> > Definiation of a hash should like this:
> >
> > {'key'=\>'value'.....}
> >
> > Now in the IO.new exmaple,it is written as {key:value}. Is the ':' symbol
> > same as '=\>'?? I do not find it is methioned in any document.
---
### Author:  [@Ryan\_Davis1](https://rubytalk.org/u/Ryan_Davis1)
#### Post date: [12 February 2012 16:31 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/7 "2012-02-12T16:31:55Z")
Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at [http://www.opencontent.org/openpub/\](http://www.opencontent.org/openpub/%5C))).
> **···**
>
> On Feb 12, 2012, at 05:49 , maven apache wrote:
>
> > But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> >
> > Definiation of a hash should like this:
> >
> > {'key'=\>'value'.....}
> >
> > Now in the IO.new exmaple,it is written as {key:value}. Is the ':' symbol
> > same as '=\>'?? I do not find it is methioned in any document.
---
### Author:  [@Saji\_Hameed](https://rubytalk.org/u/Saji_Hameed)
#### Post date: [13 February 2012 11:19 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/8 "2012-02-13T11:19:51Z")
Unfortunately, even the latest rubydoc
[http://ruby-doc.org/core-1.9.3/Hash.html](http://ruby-doc.org/core-1.9.3/Hash.html) somehow does not mention this
new syntax.
saji
> **···**
>
> On Sun, Feb 12, 2012 at 10:49 PM, maven apache \ wrote:
>
> > But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> >
> > Definiation of a hash should like this:
> >
> > {'key'=\>'value'.....}
> >
> > Now in the IO.new exmaple,it is written as {key:value}. Is the ':' symbol
> > same as '=\>'?? I do not find it is methioned in any document.
>
> --
>
> Saji N Hameed,
> ARC-ENV, Center for Advanced Information Science and Technology,
> University of Aizu, Tsuruga, Ikki-machi,
> Aizuwakamatsu-shi, Fukushima 965-8580,
> Japan
>
> Tel: +81242 37-2736
> Fax:+81242 37-2760
> email: saji@u-aizu.ac.jp
> url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
---
### Author:  [@Josh\_Cheek](https://rubytalk.org/u/Josh_Cheek)
#### Post date: [13 February 2012 11:55 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/9 "2012-02-13T11:55:17Z")
Okay, but ruby-doc's purpose isn't to teach you the language, it's to give
you an API reference.
> **···**
>
> On Mon, Feb 13, 2012 at 5:19 AM, Saji Hameed \ wrote:
>
> > On Sun, Feb 12, 2012 at 10:49 PM, maven apache \ \> wrote:
> >
> > \> But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> > \>
> > \> Definiation of a hash should like this:
> > \>
> > \> {'key'=\>'value'.....}
> > \>
> > \> Now in the IO.new exmaple,it is written as {key:value}. Is the ':'
> > symbol
> > \> same as '=\>'?? I do not find it is methioned in any document.
> > \>
> >
> > Unfortunately, even the latest rubydoc
> > [Class: Hash (Ruby 1.9.3)](http://ruby-doc.org/core-1.9.3/Hash.html) somehow does not mention this
> > new syntax.
---
### Author:  [@maven\_apache](https://rubytalk.org/u/maven_apache)
#### Post date: [13 February 2012 12:10 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/10 "2012-02-13T12:10:46Z")
But without knowing the syntax of this language,what is the meaning of the
API reference?
I think there should be some documents about the syntax of ruby including
the hidden feature like the hash exmple in this post.
> **···**
>
> 2012/2/13 Josh Cheek \
>
> > On Mon, Feb 13, 2012 at 5:19 AM, Saji Hameed \ wrote:
> >
> > \> On Sun, Feb 12, 2012 at 10:49 PM, maven apache \ \> \> wrote:
> > \>
> > \> \> But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> > \> \>
> > \> \> Definiation of a hash should like this:
> > \> \>
> > \> \> {'key'=\>'value'.....}
> > \> \>
> > \> \> Now in the IO.new exmaple,it is written as {key:value}. Is the ':'
> > \> symbol
> > \> \> same as '=\>'?? I do not find it is methioned in any document.
> > \> \>
> > \>
> > \> Unfortunately, even the latest rubydoc
> > \> [Class: Hash (Ruby 1.9.3)](http://ruby-doc.org/core-1.9.3/Hash.html) somehow does not mention this
> > \> new syntax.
> > \>
> > \>
> > Okay, but ruby-doc's purpose isn't to teach you the language, it's to give
> > you an API reference.
---
### Author:  [@Robert\_K1](https://rubytalk.org/u/Robert_K1)
#### Post date: [13 February 2012 12:22 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/11 "2012-02-13T12:22:28Z")
And the std lib (especially documentation of a particular class) is
not the proper place for such a documentation. That's all Josh said.
Kind regards
robert
> **···**
>
> On Mon, Feb 13, 2012 at 1:10 PM, maven apache \ wrote:
>
> > 2012/2/13 Josh Cheek \
> >
> > \> On Mon, Feb 13, 2012 at 5:19 AM, Saji Hameed \ wrote:
> > \>
> > \> \> On Sun, Feb 12, 2012 at 10:49 PM, maven apache \ \> \> \> wrote:
> > \> \>
> > \> \> \> But in the ruby document:[Programming Ruby: The Pragmatic Programmer's Guide](http://www.ruby-doc.org/docs/ProgrammingRuby/)
> > \> \> \>
> > \> \> \> Definiation of a hash should like this:
> > \> \> \>
> > \> \> \> {'key'=\>'value'.....}
> > \> \> \>
> > \> \> \> Now in the IO.new exmaple,it is written as {key:value}. Is the ':'
> > \> \> symbol
> > \> \> \> same as '=\>'?? I do not find it is methioned in any document.
> > \> \> \>
> > \> \>
> > \> \> Unfortunately, even the latest rubydoc
> > \> \> [http://ruby-doc.org/core-1.9.3/Hash.html](http://ruby-doc.org/core-1.9.3/Hash.html) somehow does not mention this
> > \> \> new syntax.
> > \> \>
> > \> \>
> > \> Okay, but ruby-doc's purpose isn't to teach you the language, it's to give
> > \> you an API reference.
> >
> > But without knowing the syntax of this language,what is the meaning of the
> > API reference?
> >
> > I think there should be some documents about the syntax of ruby including
> > the hidden feature like the hash exmple in this post.
>
> --
> remember.guy do |as, often| as.you\_can - without end
> [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
---
### Author:  [@Saji\_Hameed](https://rubytalk.org/u/Saji_Hameed)
#### Post date: [13 February 2012 12:30 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/12 "2012-02-13T12:30:01Z")
as a new syntax, i would tend to think that rubydoc (which is derived
from the source code documentation) would be more or less the right
place to
mention it. we all know that rubydoc is not perfect... maybe we
should not try to defend it too much 😉
saji
> **···**
>
> > And the std lib (especially documentation of a particular class) is
> > not the proper place for such a documentation. That's all Josh said.
> >
> > Kind regards
> >
> > robert
> >
> > --
> > remember.guy do |as, often| as.you\_can - without end
> > [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
>
> --
>
> Saji N Hameed,
> ARC-ENV, Center for Advanced Information Science and Technology,
> University of Aizu, Tsuruga, Ikki-machi,
> Aizuwakamatsu-shi, Fukushima 965-8580,
> Japan
>
> Tel: +81242 37-2736
> Fax:+81242 37-2760
> email: saji@u-aizu.ac.jp
> url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
---
### Author:  [@maven\_apache](https://rubytalk.org/u/maven_apache)
#### Post date: [13 February 2012 12:41 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/13 "2012-02-13T12:41:31Z")
🙂
I never think rubydoc is useless.
In fact, I like ruby . I just want to find some documents about this
language.
Since when I read the ruby(in fact rails) source codes,I often can not
understand some syntaxs even after I read the 'Programming ruby' and 'why's
(poignant) guide to ruby'.
And asking for help is my last choice, I can not expect people answer all
my questions about the syntaxs. 🙂
> **···**
>
> 2012/2/13 Saji Hameed \
>
> > as a new syntax, i would tend to think that rubydoc (which is derived
> > from the source code documentation) would be more or less the right
> > place to
> > mention it. we all know that rubydoc is not perfect... maybe we
> > should not try to defend it too much 😉
> >
> > saji
> >
> > \> And the std lib (especially documentation of a particular class) is
> > \> not the proper place for such a documentation. That's all Josh said.
> > \>
> > \> Kind regards
> > \>
> > \> robert
> > \>
> > \>
> > \> --
> > \> remember.guy do |as, often| as.you\_can - without end
> > \> [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
> > \>
> >
> > --
> >
> > Saji N Hameed,
> > ARC-ENV, Center for Advanced Information Science and Technology,
> > University of Aizu, Tsuruga, Ikki-machi,
> > Aizuwakamatsu-shi, Fukushima 965-8580,
> > Japan
> >
> > Tel: +81242 37-2736
> > Fax:+81242 37-2760
> > email: saji@u-aizu.ac.jp
> > url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> > bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
---
### Author:  [@Saji\_Hameed](https://rubytalk.org/u/Saji_Hameed)
#### Post date: [13 February 2012 12:46 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/14 "2012-02-13T12:46:02Z")
yes, please do keep asking -- it was a perfectly good question and i
am sure lots of people out here would be willing to share their
knowledge of ruby with you...
cheers,
saji
> **···**
>
> On Mon, Feb 13, 2012 at 9:41 PM, maven apache \ wrote:
>
> > 🙂
> >
> > I never think rubydoc is useless.
> >
> > In fact, I like ruby . I just want to find some documents about this
> > language.
> >
> > Since when I read the ruby(in fact rails) source codes,I often can not
> > understand some syntaxs even after I read the 'Programming ruby' and 'why's
> > (poignant) guide to ruby'.
> >
> > And asking for help is my last choice, I can not expect people answer all
> > my questions about the syntaxs. 🙂
> >
> > 2012/2/13 Saji Hameed \
> >
> > > as a new syntax, i would tend to think that rubydoc (which is derived
> > > from the source code documentation) would be more or less the right
> > > place to
> > > mention it. we all know that rubydoc is not perfect... maybe we
> > > should not try to defend it too much 😉
> > >
> > > saji
> > >
> > > \> And the std lib (especially documentation of a particular class) is
> > > \> not the proper place for such a documentation. That's all Josh said.
> > > \>
> > > \> Kind regards
> > > \>
> > > \> robert
> > > \>
> > > \>
> > > \> --
> > > \> remember.guy do |as, often| as.you\_can - without end
> > > \> [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
> > > \>
> > >
> > > --
> > >
> > > Saji N Hameed,
> > > ARC-ENV, Center for Advanced Information Science and Technology,
> > > University of Aizu, Tsuruga, Ikki-machi,
> > > Aizuwakamatsu-shi, Fukushima 965-8580,
> > > Japan
> > >
> > > Tel: +81242 37-2736
> > > Fax:+81242 37-2760
> > > email: saji@u-aizu.ac.jp
> > > url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> > > bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
>
> --
>
> Saji N Hameed,
> ARC-ENV, Center for Advanced Information Science and Technology,
> University of Aizu, Tsuruga, Ikki-machi,
> Aizuwakamatsu-shi, Fukushima 965-8580,
> Japan
>
> Tel: +81242 37-2736
> Fax:+81242 37-2760
> email: saji@u-aizu.ac.jp
> url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
---
### Author:  [@Robert\_K1](https://rubytalk.org/u/Robert_K1)
#### Post date: [13 February 2012 14:01 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/15 "2012-02-13T14:01:55Z")
Please do not top post.
> I never think rubydoc is useless.
It's just not the proper medium for documentation of the language.
JavaDoc is also not used to document the language - for that the JLS
is used.
> In fact, I like ruby . I just want to find some documents about this
> language.
I recommend
> **[The Ruby Programming Language: Everything You Need to Know: Flanagan, David,...](https://www.amazon.com/Ruby-Programming-Language-Everything-Need/dp/0596516177)**
>
> The Ruby Programming Language: Everything You Need to Know \[Flanagan, David, Matsumoto, Yukihiro\] on Amazon.com. \*FREE\* shipping on qualifying offers. The Ruby Programming Language: Everything You Need to Know
> **[Programming Ruby 1.9: The Pragmatic... by Thomas, Dave](https://www.amazon.com/Programming-Ruby-1-9-Pragmatic-Programmers/dp/1934356085)**
>
> Programming Ruby 1.9: The Pragmatic Programmers' Guide (Facets of Ruby) \[Thomas, Dave, Fowler, Chad, Hunt, Andy\] on Amazon.com. \*FREE\* shipping on qualifying offers. Programming Ruby 1.9: The Pragmatic Programmers' Guide (Facets of Ruby)
> **[The Well-Grounded Rubyist: Covers Ruby... by David A. Black](https://www.amazon.com/Well-Grounded-Rubyist-Covers-Ruby-1-9-1/dp/1933988657)**
>
> The Well-Grounded Rubyist: Covers Ruby 1.9.1 \[David A. Black\] on Amazon.com. \*FREE\* shipping on qualifying offers. The Well-Grounded Rubyist: Covers Ruby 1.9.1
Kind regards
robert
> **···**
>
> On Mon, Feb 13, 2012 at 1:41 PM, maven apache \ wrote:
>
> --
> remember.guy do |as, often| as.you\_can - without end
> [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
---
### Author:  [@maven\_apache](https://rubytalk.org/u/maven_apache)
#### Post date: [13 February 2012 13:36 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/16 "2012-02-13T13:36:12Z")
Thanks for the kind of all you guys.
I will keep asking if need.
Thanks. 🙂
> **···**
>
> 2012/2/13 Saji Hameed \
>
> > yes, please do keep asking -- it was a perfectly good question and i
> > am sure lots of people out here would be willing to share their
> > knowledge of ruby with you...
> >
> > cheers,
> > saji
> >
> > On Mon, Feb 13, 2012 at 9:41 PM, maven apache \ \> wrote:
> > \> 🙂
> > \>
> > \> I never think rubydoc is useless.
> > \>
> > \> In fact, I like ruby . I just want to find some documents about this
> > \> language.
> > \>
> > \> Since when I read the ruby(in fact rails) source codes,I often can not
> > \> understand some syntaxs even after I read the 'Programming ruby' and
> > 'why's
> > \> (poignant) guide to ruby'.
> > \>
> > \> And asking for help is my last choice, I can not expect people answer all
> > \> my questions about the syntaxs. 🙂
> > \>
> > \> 2012/2/13 Saji Hameed \
> > \>
> > \>\> as a new syntax, i would tend to think that rubydoc (which is derived
> > \>\> from the source code documentation) would be more or less the right
> > \>\> place to
> > \>\> mention it. we all know that rubydoc is not perfect... maybe we
> > \>\> should not try to defend it too much 😉
> > \>\>
> > \>\> saji
> > \>\>
> > \>\> \> And the std lib (especially documentation of a particular class) is
> > \>\> \> not the proper place for such a documentation. That's all Josh said.
> > \>\> \>
> > \>\> \> Kind regards
> > \>\> \>
> > \>\> \> robert
> > \>\> \>
> > \>\> \>
> > \>\> \> --
> > \>\> \> remember.guy do |as, often| as.you\_can - without end
> > \>\> \> [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
> > \>\> \>
> > \>\>
> > \>\>
> > \>\>
> > \>\> --
> > \>\>
> > \>\> Saji N Hameed,
> > \>\> ARC-ENV, Center for Advanced Information Science and Technology,
> > \>\> University of Aizu, Tsuruga, Ikki-machi,
> > \>\> Aizuwakamatsu-shi, Fukushima 965-8580,
> > \>\> Japan
> > \>\>
> > \>\> Tel: +81242 37-2736
> > \>\> Fax:+81242 37-2760
> > \>\> email: saji@u-aizu.ac.jp
> > \>\> url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> > \>\> bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
> > \>\>
> > \>\>
> >
> > --
> >
> > Saji N Hameed,
> > ARC-ENV, Center for Advanced Information Science and Technology,
> > University of Aizu, Tsuruga, Ikki-machi,
> > Aizuwakamatsu-shi, Fukushima 965-8580,
> > Japan
> >
> > Tel: +81242 37-2736
> > Fax:+81242 37-2760
> > email: saji@u-aizu.ac.jp
> > url: [http://www.u-aizu.ac.jp](http://www.u-aizu.ac.jp)
> > bib: [Web of Science](http://www.researcherid.com/rid/B-9188-2009)
---
### Author:  [@Kevin2](https://rubytalk.org/u/Kevin2)
#### Post date: [15 February 2012 02:08 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/17 "2012-02-15T02:08:00Z")
I remember saying in one of these threads that documentation should be
pervasive and this is a perfect example of why this should be the
case. The syntax rules of any language, natural or constructed,
belongs in the standard documentation of said language. The only
reason this wasn't really done in the past is that a printed book
couldn't contain this information in a reasonable way. Hypertext
allows us to achieve this.
> **···**
>
> On Mon, Feb 13, 2012 at 9:01 AM, Robert Klemme \ wrote:
>
> > Please do not top post.
> >
> > On Mon, Feb 13, 2012 at 1:41 PM, maven apache \ wrote:
> >
> > > I never think rubydoc is useless.
> >
> > It's just not the proper medium for documentation of the language.
> > JavaDoc is also not used to document the language - for that the JLS
> > is used.
> >
> > > In fact, I like ruby . I just want to find some documents about this
> > > language.
> >
> > I recommend
> > [Amazon.com](http://www.amazon.com/Ruby-Programming-Language-David-Flanagan/dp/0596516177/)
> > [Amazon.com](http://www.amazon.com/Programming-Ruby-1-9-Pragmatic-Programmers/dp/1934356085/)
> > [Amazon.com](http://www.amazon.com/Well-Grounded-Rubyist-David-Black/dp/1933988657/)
> >
> > Kind regards
> >
> > robert
> >
> > --
> > remember.guy do |as, often| as.you\_can - without end
> > [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
---
### Author:  [@Robert\_K1](https://rubytalk.org/u/Robert_K1)
#### Post date: [15 February 2012 10:29 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/18 "2012-02-15T10:29:05Z")
> I remember saying in one of these threads that documentation should be
> pervasive and this is a perfect example of why this should be the
> case. The syntax rules of any language, natural or constructed,
> belongs in the standard documentation of said language. The only
> reason this wasn't really done in the past is that a printed book
> couldn't contain this information in a reasonable way.
What exactly is your definition of "reasonable"? According to my
definition a book is perfectly capable of providing documentation of
syntax in a reasonable way - and actually there are tons of books
around which present syntax of languages in a way useful for the
reader.
> Hypertext allows us to achieve this.
Of course you can also document formal language syntax in a hypertext
document, and maybe even better than in a printed book. It is not
necessary though.
Kind regards
robert
> **···**
>
> On Wed, Feb 15, 2012 at 3:08 AM, Kevin \ wrote:
>
> --
> remember.guy do |as, often| as.you\_can - without end
> [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)
---
### Author:  [@Kevin2](https://rubytalk.org/u/Kevin2)
#### Post date: [16 February 2012 05:05 UTC](https://rubytalk.org/t/the-ruby-syntax/64881/19 "2012-02-16T05:05:41Z")
By reasonable I mean that the volume would not become overly large and
cumbersome to navigate. Containing a proper treatment of the entire
grammar of most languages would be about the same size as a good
pocket or abridged dictionary. Then there is all the flipping around
between pages which doesn't help concentration. In the context of
constructed languages like Ruby one may well be literate but not be
familiar with all of the different parts of the syntax. A language
doesn't exist without the grammar and the API. Technical limitations
have prevented us from representing this fact for most of human
history, instead we've tried to club the entire grammar of our
languages into our heads with some success. That doesn't mean we
should keep doing that when we have the tools to avoid it. Imagine if
we tried to include the entire source for the whole standard library
in the pickaxe the book would be huge and a true pain to navigate.
This annoyance is of course lessened in the electronic versions
because you get links you can click to quickly navigate from the index
at least and you usually have some capacity to do a find for a
specific word etc. Emacs got the right idea, even if the format used
isn't as nice as hypertext. The main things I would add are a
function that could tell me what a given function is made of\*, and
integration with the elisp manual. That would complement the fact
that describe-function defaults to selecting the function at the
current depth.\*\*
I've been getting better and better at reading code as I go deeper
into programming, but I still long for better and more easily
navigable documentation.
\*Eg. Move into an Emacs function fire off command that shows the
various parts of a function and links to relevant sections of the
manual that explain those things. Though I don't think that is
technically possible.
\*\*If you have code like (let ((f b))) if you put the cursor within the
level of (let) describe-function will have let already selected.
> **···**
>
> On Wed, Feb 15, 2012 at 5:29 AM, Robert Klemme \ wrote:
>
> > On Wed, Feb 15, 2012 at 3:08 AM, Kevin \ wrote:
> >
> > > I remember saying in one of these threads that documentation should be
> > > pervasive and this is a perfect example of why this should be the
> > > case. The syntax rules of any language, natural or constructed,
> > > belongs in the standard documentation of said language. The only
> > > reason this wasn't really done in the past is that a printed book
> > > couldn't contain this information in a reasonable way.
> >
> > What exactly is your definition of "reasonable"? According to my
> > definition a book is perfectly capable of providing documentation of
> > syntax in a reasonable way - and actually there are tons of books
> > around which present syntax of languages in a way useful for the
> > reader.
> >
> > > Hypertext allows us to achieve this.
> >
> > Of course you can also document formal language syntax in a hypertext
> > document, and maybe even better than in a printed book. It is not
> > necessary though.
> >
> > Kind regards
> >
> > robert
> >
> > --
> > remember.guy do |as, often| as.you\_can - without end
> > [http://blog.rubybestpractices.com/](http://blog.rubybestpractices.com/)