gmane.comp.lang.ruby.documentation

来自timelimit的邮件

timelimit — 2011-10-08T05:34:37

 unsubscribe

Documentation Translations

Chris White — 2011-08-20T01:11:54

Hello Everyone,

I had someone approach me earlier about helping out with Spanish translations of the Ruby documentation. With that in mind I'd like to get a feel for what, if at any, progress has been made to translate the Ruby documentation into something other than English (or Japanese if there is any untranslated documentation). 

The objective of this is to try and get a documentation translation team together, and start to centralize activity. Please respond on or off list if you have interest or know of existing translation projects.

Regards,
Chris White
http://www.twitter.com/cwgem

Re: ObjectSpace#each_object example issue

Roger Pack — 2011-08-02T20:28:49

I'd probably just add a little note explaining the different ("this is
for 32 bit systems, for 64 bit it would...")
But that's just me.
Feel free to formulate a patch to the core and submit it for consideration:
http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentation.html
Cheers!
-roger-

On Fri, Jul 29, 2011 at 1:16 PM, Chris White <cwprogram< at >live.com> wrote:

Re: Documentation Improvement Proposal

Chris White — 2011-08-02T19:57:26

On Aug 2, 2011, at 11:54 AM, Eric Hodel wrote:


Well, I prefer doing it in markdown to avoid the clutter of tags, converting to HTML using a tool of some sort. As for the layout part, I wish I were more familiar with how the documentation is generated. I'd like to improve on the overall style, but the best I can provide is a sample template with HTML, CSS, and JS showing how I think it should like. If someone can offer me guidance on how to integrate that into the generation workflow that would be great.


The out of sync part is I don't see where there's an easy to spot place on the documentation page that details the core syntax and details such as field input separators, blocks, yield, etc. It's the core API classes and the standard library, please a few links to books and what not, but those can become out of date. Take for example:

http://doc.ruby-lang.org/ja/1.9.2/doc/spec=2fcall.html

This is Japanese documentation explaining a few things such as yield and block arguments.


That's why I was sugges

Re: Documentation Improvement Proposal

Eric Hodel — 2011-08-02T18:54:39

Your focus seems to be largely on the HTML documentation, but there's also ri.  Why don't we take your proposed front matter and check it into ruby itself where both ri and any generated HTML can take advantage of it?


The documentation from the core standard library is written in English, so I'm uncertain about what will become out of sync between the two.  I think you're writing the wrong mailing list though, you should contact the rurema people to have your concerns addressed.


Having user contributions only on a website seems like a waste of community effort.  User contributions should be aggressively curated to fold documentation improvements back in to the source material and remove bug reports and "how do I use this?" type questions.


James Britt is the current maintainer of ruby-doc.org, you can contact him from his email address in the sidebar.


I suggest you get in touch with the rurema people before attempting to build something they don't want and won't use.  When I spoke to okkez at RubyKai

ObjectSpace#each_object example issue

Chris White — 2011-07-29T19:16:55

The documentation for ObjectSpace#each_object has the following sample code:

 *     a = 102.7
 *     b = 95       # Won't be returned
 *     c = 12345678987654321
 *     count = ObjectSpace.each_object(Numeric) {|x| p x }
 *     puts "Total count: #{count}"
 *
 *  <em>produces:</em>
 *
 *     12345678987654321
 *     102.7
 *     2.71828182845905
 *     3.14159265358979
 *     2.22044604925031e-16
 *     1.7976931348623157e+308
 *     2.2250738585072e-308
 *     Total count: 7

In this case, c, with the value of 12345678987654321 is supposed to show for being a Bignum. However on 64 bit systems this isn't the case:

= 64bit MacOSX Ruby SVN HEAD =
irb(main):001:0> puts RUBY_VERSION + " " + RUBY_PLATFORM + " " + RUBY_PATCHLEVEL.to_s
1.9.2 x86_64-darwin10.8.0 290
=> nil
irb(main):002:0> 12345678987654321.class
=> Fixnum

This won't show because as explained, "Immediate objects (Fixnums, Symbols true, false, and nil) are never returned.

Re: alias - error in documentation

Roger Pack — 2011-07-13T01:57:59

I'd recommend creating and submitting a patch with the change.
http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentation.html
Cheers!
-roger-

On Tue, Jul 12, 2011 at 11:22 AM, Hazins, Kalman
<Kalman.Hazins< at >jhuapl.edu> wrote:

alias - error in documentation

Hazins, Kalman — 2011-07-12T17:22:47

All, 

I believe I found an error in the documentation for a ruby keyword - alias.

The documentation, under 1.9 keywords link=> alias, states that

p.full_name = "David"   # Please use fullname=

I believe the comment is incorrect. The full_name= is still referencing the old name= definition and not the newly defined one. 

(I have of course verified my hypothesis by actually running the code.)

Hope this is useful, 

-Kalman Hazins

(unknown)

Roger Newton — 2011-07-04T15:45:28

unsubscribe

Re: Array and Enum: Elements or Objects?

Hugh Sasse — 2011-05-13T17:24:23


Yes.  It really didn't help that I was thinking about the effects of
Array#compact, thinking they applied to uniq. Sorry about that. I
proved myself wrong, you right, with IRB in 30 seconds.  I've just
searched through the array docs, and have not found anything that
could have caused me to think this, so I don't know where that came
from.  Oh well. "Open mouth, insert foot, echo internationally" as
the old FIDOnet .sig used to go.


OK, that is more precise.  

I think I've just proved that I am not sufficiently accurate in my thinking
to comment on this activity, so I'll say no more.
        Hugh

Re: Array and Enum: Elements or Objects?

Gary Wright — 2011-05-13T16:49:22

On May 13, 2011, at 12:41 PM, Hugh Sasse wrote:

Sorry about the trimming.  I didn't mean to mis-represent your thoughts.  I was responding to:


Uniq doesn't treat nil differently than any other object so I wasn't sure why you were suggesting that nil wasn't an object in this context.

I think things are clearer when people realize that 'nil' is simply one particular object that has an agreed upon name.  it is a sigil or sentinel that can be used for a wide variety of purposes.  Its value is that it will never be confused with other objects and that it evaluates to false in a boolean context.   I think it goes too far to describe it as representing 'nothing' though.  

Gary Wright

Re: Array and Enum: Elements or Objects?

Loren Segal — 2011-05-13T16:45:54

I'd agree with this viewpoint. Although "flow" has value, it's more 
important to be very accurate with word choice in technical 
documentation. Users expect and are very attentive to this. When a user 
sees the words object and element interchanged, they might be wondering 
why the term "object" was chosen in this instance but not the last one, 
not realizing that it was arbitrary. Because of this, they might 
misinterpret the documentation. It's hard to say how, but there are less 
surprises when you use consistent wording. In that sense, I don't think 
it's wise to use synonyms if the goal is simply to make the prose more 
interesting. If anything, I would say repetitive word choice is a good 
thing in technical documentation.

Of course this is all assuming that the usage is inconsistent. I haven't 
read all of the docs, but so long as the usage implies different 
contexts between "objects" and "elements", the usage is fine. If they 
really do mean "elements" when using objects, I'd support changing it.

Re: Array and Enum: Elements or Objects?

Hugh Sasse — 2011-05-13T16:41:48


Agreed, and that's why I asked about cases where confusion is arising.

Agreed.

This paragraph would have been unnecessary if you had not trimmed my last
sentence! :-)  It does carry semantics of being nothing, so it is legitimate
to regard it as a non-object in cases where that applies such as uniq.  I
still had to use the term non-nil to make this distinction apparent, because
it is an object with a class and methods.
        Hugh

Re: Array and Enum: Elements or Objects?

Gary Wright — 2011-05-13T16:25:47

On May 13, 2011, at 11:45 AM, Hugh Sasse wrote:


Consistency is very important in technical documentation. Using synonyms introduces ambiguity because it often isn't clear when the synonym is being used for no particular reason or when it is being used to indicate a distinctly different technical meaning.

That being said, I think 'element' is an appropriate term to use when referring to an object stored in a container of some sort.  Using 'element' emphasizes the context.  So when referring to the container/containee role 'element' is appropriate but when the container/containee role is irrelevant, then 'object' is OK.  So I would encourage the use of both terms as long as the usage is consistent and not just reflective of different authors choices.

I also think it is completely appropriate to refer to 'nil' as an object.  Everything that has methods is an object in Ruby: nil, true, false, fixnum, symbols, etc.  I know that some people like to introduce a dichotomy between objects that can be referenced

Re: Array and Enum: Elements or Objects?

Hugh Sasse — 2011-05-13T15:45:22

Before you put this work in, I'd be inclined to ask: why is this a problem?
Are you seeing some possible form of confusion?  Just reading this paragraph
and not refreshing my memory of the docs, I'd tend to only distinguish between
elements and objects for things like Array#uniq where non-nil elements are
objects.  Otherwise, a variety of word use tends to make English flow better.
Why does English have another word for "walrus"?  Searching for 
synonyms improve writing
produces a lot of relevant results.  Repetitive word choice seems to be
widely considered a fault.  That's anecdotal, but is supported in a limited
way by searching for this kind of critique.  In Ruby most elements are going
to be objects, and even nil is an object.
        HTH
        Hugh


On Fri, 13 May 2011, Loren Sands-Ramshaw wrote:

Array and Enum: Elements or Objects?

Loren Sands-Ramshaw — 2011-05-13T15:01:40

The documentation in array.c and enum.c uses the terms elements and objects
inconsistently. Currently there are 100 elements and 18 objects in array.c
and 59 elements and 21 objects in enum.c. I think element is the most
widely-used term for things in an array. For enum I can see the argument for
object given the range of things that can be enumerable, but wikipedia uses
element to refer to the things that are being enumerated. Should I make
everything in array.c element and everything in enum.c object, or just
everything element? Or something else?

Thanks,
Loren

Date, Time, DateTime -- documentation improvements

mathew — 2011-05-06T14:06:34

Someone on Reddit recently pointed at the documentation for Date as an
example of Ruby being inferior to that other language, citing the
number of undocumented methods, and methods like floor() that have no
obvious meaning for a date.

So I'm considering taking a pass at cleaning up the RubyDoc for date.
Before I do, I'm wondering if there are any methods which aren't
supposed to be part of the API?  Things like dhms_to_delta and divmod
don't look as though they should be a guaranteed feature of a
date/time API.


mathew

Re: Welcome to our (ruby-doc ML) You are added automatically

program uni — 2011-04-18T20:40:24

Re: Little issue in Array#compact! doc

Roger Pack — 2011-04-15T19:49:49

I would create a patch to ruby's core (trunk) and submit it to the
ruby-lang redmine.
Cheers!
-r

On Sun, Apr 10, 2011 at 8:36 AM, Dorian . <pr.dorian< at >gmail.com> wrote:

Little issue in Array#compact! doc

Dorian . — 2011-04-10T14:36:16

Hi, if you look at
Array#compact!<http://www.ruby-doc.org/core/classes/Array.html#M000279>doc,
you can see there is :

So there is little issur with HTML markup, it should be

Re: Class:Hash

Slevin McGuigan — 2010-12-31T12:46:14

Just to make sure we have the same understanding (would be pretty goofy 
if my first patch to be submitted would be identical to the one you 
submitted just a couple of days ago... :o )

By saying "I'd write a patch" you mean "if I were you I would write a 
patch. I don't plan to write one".

Thanks to all. I will write a patch. (this will take a while, I first 
need to get into the rules & tools etc. ...)

Best Regards and a happy new year!
SMG