Rubyinstaller devel - Jul 2009 - ri documentation included in final installer?

While testing out 1.9.1 preview1, none of my ri Class, ri Object, ri IO queries
came back with anything as the share/ri tree is missing.

I see that the installer creates Start menu links to ruby-doc.org, and
I''m wondering if the plan is to include the ri docs only for the final
installer but none of the previews.

I think that''s fine if that''s the plan.

On Mon, Jul 6, 2009 at 5:44 PM, Jon<jon.forums at gmail.com>
wrote:
> While testing out 1.9.1 preview1, none of my ri Class, ri Object, ri IO
queries came back with anything as the share/ri tree is missing.
>
The ri and rdocs docuements generated a 8MB additional size, even with
high compression due being so many files.

When installing, those took long time to extract and verify stamping.

To reduce the installer and the installing process time, I decided to
remove those (see all the --no-ri and --disable-install-doc options of
the recipes).
> I see that the installer creates Start menu links to ruby-doc.org, and
I''m wondering if the plan is to include the ri docs only for the final
installer but none of the previews.
>
The links are in current One-Click and I thought will be good to have
those in the new version.
> I think that''s fine if that''s the plan.
The plan is integrate the Compiled HTML Help
(http://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help)

Gordon Thiesfeld worked on that and there was a feature request to
have it bundled with the installer:

http://rubyforge.org/tracker/index.php?func=detail&aid=16782&group_id=167&atid=718

CHM is way faster to search and find documentation, and was more in
the lines of Windows.

File allocation on Windows sucks, and ri is not Windows-friendly in that way.

The CHM generation needs to be automated, and maybe supplied with a
CSS style to pair with the new website contest.

I see the value of having ri and "help" from IRB, but personally I
don''t use them and revert to tools like APIdock or
api.rubyonrails.org.

Please guys let me know if I''m wrong, this can be easily fixed now
that automated installers can be easily updated.

Cheers,
-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

> The ri and rdocs docuements generated a 8MB additional size, even with
> high compression due being so many files.
>
> When installing, those took long time to extract and verify stamping.
Perhaps two versions one with and one without [I would most definitely
almost always choose the one without--I''ve never had a good experience
with RI--or maybe that''s my own fault].

=r

> I see the value of having ri and "help" from IRB, but personally
I
> don''t use them and revert to tools like APIdock or
> api.rubyonrails.org.
Good point they could end up being useful via IRB.

Also don''t forget http://allgems.ruby-forum.com/gems

Sorry couldn''t resist the self-promo :)

=r

> CHM is way faster to search and find documentation, and was more in
> the lines of Windows.
One wrinkle I see is that RubyGems will create ri and rdoc documentation upon
gem installs, and I believe that any gem that opens up a core class like Module,
Class, etc will cause ri to display only partial info about the enhanced core
class.

For example, I get these unhelpful results...

D:\Jon>ri Class
-------------------------------------------------------------- Class: Class <
Object
     Allows attributes to be shared within an inheritance hierarchy, but where
each
     descendant gets a copy of their parents'' attributes, instead of
just a pointer
     to the same. This means that the child can add elements to, for example, an
     array without those additions being shared with either their parent,
siblings,
     or children, which is unlike the regular class-level attributes that are
     shared across the entire hierarchy.

------------------------------------------------------------------------------------

D:\Jon>ri IO
Nothing known about IO



Very frustrating if you happen to be offline, sleep deprived, and have forgotten
the details on your favorite object.


Maybe there''s a clever way to hook ri so that you could wrap a custom
header/footer message around whatever ri wants to return and alert the user to
check out the CHM that contains the docs on core and std lib?

On Mon, Jul 6, 2009 at 6:23 PM, Jon<jon.forums at gmail.com>
wrote:
>> CHM is way faster to search and find documentation, and was more in
>> the lines of Windows.
>
> One wrinkle I see is that RubyGems will create ri and rdoc documentation
upon gem installs, and I believe that any gem that opens up a core class like
Module, Class, etc will cause ri to display only partial info about the enhanced
core class.
>
> For example, I get these unhelpful results...
>
> D:\Jon>ri Class
> -------------------------------------------------------------- Class: Class
< Object
> ? ? Allows attributes to be shared within an inheritance hierarchy, but
where each
> ? ? descendant gets a copy of their parents'' attributes, instead
of just a pointer
> ? ? to the same. This means that the child can add elements to, for
example, an
> ? ? array without those additions being shared with either their parent,
siblings,
> ? ? or children, which is unlike the regular class-level attributes that
are
> ? ? shared across the entire hierarchy.
>
>
------------------------------------------------------------------------------------
>
> D:\Jon>ri IO
> Nothing known about IO
>
>
>
> Very frustrating if you happen to be offline, sleep deprived, and have
forgotten the details on your favorite object.
>
>
> Maybe there''s a clever way to hook ri so that you could wrap a
custom header/footer message around whatever ri wants to return and alert the
user to check out the CHM that contains the docs on core and std lib?
>
Well, what about a faster ri version that do not fill the filesystem
with so many files? I found "ri" so slow, and decided not to use.

Also, personally disabled RDoc generation on gem installation:

C:\Users\Luis>type .gemrc
---
:benchmark: false
:update_sources: true
:bulk_threshold: 1000
:verbose: true
:sources:
- http://gems.rubyforge.org/
- http://gems.github.com
:backtrace: false
gem: --no-ri --no-rdoc --env-shebang

(the --env-shebang is to avoid adding C:/Path/to/Ruby in the stub scripts).

Anyhow, good point that you raised, and I''m willing to go any route
that ends being a win/win situation:

* Can be easily generated and automated.
* Compact file size to distribute installer.

-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

>> For example, I get these unhelpful results...
Yeah I hate running ri File and getting back a single method from the
FileUtils class [which has happened before].  I think that was caused
by a buggy old RI version though.


>> Maybe there''s a clever way to hook ri so that you could wrap a
custom header/footer message around whatever ri wants to return and alert the
user to check out the CHM that contains the docs on core and std lib?
You could submit a patch to ri that makes it pluggable... :)

> Well, what about a faster ri version that do not fill the filesystem
> with so many files? I found "ri" so slow, and decided not to use.
Yeah I think it still has the many file aspect, but I believe it''s
faster now [only a few seconds, not like 10].

> Also, personally disabled RDoc generation on gem installation:
Me too--takes forever, and the docs are already online anyway.

> Anyhow, good point that you raised, and I''m willing to go any
route
> that ends being a win/win situation:

I think the only win win is to have it optionally install them, and by
default *not* install them.  That or release two installers, one
large, one small.

Speaking of which, I do miss the old sciTe that came with the old OCI.
 Maybe we could make it into a separate distributable?  I like the new
links to web pages [much better].  They''re also better than
distributing it with a ruby book in CHM, I think.  But <sniff> miss
SciTe.

Thoughts?
Thanks.
r

> You could submit a patch to ri that makes it pluggable... :)
> 
Well...I can''t imagine any interest in a hacky patch for something that
may not be as helpful as it once was ;)

> > Anyhow, good point that you raised, and I''m willing to go any
route
> > that ends being a win/win situation:
> 
> 
> I think the only win win is to have it optionally install them, and by
> default *not* install them.  That or release two installers, one
> large, one small.
My vote is for the two installers route.  If someone really wants full local
docs they download the "rubyinstaller-1.9.1p129-fulldocs.exe" and they
get a fast, searchable CHM.

They know about the two options up front, they''re not surpised, and
they don''t feel the need to file a bug against the installer.

On Tue, Jul 7, 2009 at 2:24 PM, Jon<jon.forums at gmail.com>
wrote:
> [...]
>
> My vote is for the two installers route. ?If someone really wants full
local docs they download the "rubyinstaller-1.9.1p129-fulldocs.exe"
and they get a fast, searchable CHM.
>
What about a installer just for the Docs?

Also, keep in mind that CHM file is not going to offer help for "ri"
or "help" in IRB.

This installer could include any of the cool and free Book of Ruby
available, or the 1st edition of Programming Ruby, since was handed
over to us (RubyInstaller project).
> They know about the two options up front, they''re not surpised,
and they don''t feel the need to file a bug against the installer.
Amen for that ;-)

-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

> What about a installer just for the Docs?
> 
> Also, keep in mind that CHM file is not going to offer help for
"ri"
> or "help" in IRB.
> 
> This installer could include any of the cool and free Book of Ruby
> available, or the 1st edition of Programming Ruby, since was handed
> over to us (RubyInstaller project).

Personally I *really* like this option (for many reasons) especially if both
installers are predominantly featured in the download area.

I''m not as familiar with Inno as I am with NSIS, but it would be cool
for the Doc installer to attempt to find it''s default install dir based
upon the install dir chosen for the main Ruby installation.

Power users of course can install wherever, but for the person just wanting to
install in the same location as their Ruby install, they just keep clicking Next
-> and everything is installed under one dir.

>> This installer could include any of the cool and free Book of Ruby
>> available, or the 1st edition of Programming Ruby, since was handed
>> over to us (RubyInstaller project).
>
>
> Personally I *really* like this option (for many reasons) especially if
both installers are predominantly featured in the download area.
+1 a download that had the books and the docs and...everything
[scite?] would be sweet.
=r

On Tue, Jul 7, 2009 at 3:08 PM, Jon<jon.forums at gmail.com>
wrote:
>> What about a installer just for the Docs?
>>
>> Also, keep in mind that CHM file is not going to offer help for
"ri"
>> or "help" in IRB.
>>
>> This installer could include any of the cool and free Book of Ruby
>> available, or the 1st edition of Programming Ruby, since was handed
>> over to us (RubyInstaller project).
>
>
> Personally I *really* like this option (for many reasons) especially if
both installers are predominantly featured in the download area.
>
> I''m not as familiar with Inno as I am with NSIS, but it would be
cool for the Doc installer to attempt to find it''s default install dir
based upon the install dir chosen for the main Ruby installation.
>
Yes, is possible using the exact same AppId for the documentation
installers. Need to verify it and how the uninstall process be
affected. I believe is doable.
> Power users of course can install wherever, but for the person just wanting
to install in the same location as their Ruby install, they just keep clicking
Next -> and everything is installed under one dir.
The idea of the Runtime was get it out of the box soon, but took us
(ala: me) a lot of time get it out of the door.

Now that preview1 is out, and we got some feedback, is time to start
collecting the feature request and value those with our goal list ;-)

Candidates for better documentation than "Programming Ruby" are:

The Little Book of Ruby, 1.1MB:
http://www.sapphiresteel.com/The-Little-Book-Of-Ruby

The Book of Ruby, 2.9MB:
http://www.sapphiresteel.com/The-Book-Of-Ruby

Let''s start a new thread about this, since Programming Ruby 1st
edition has become so old and sometimes is inaccurate reference.

Now, for Ruby-core and Stdlib, the option will be a CHM file.

Sounds good?
-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

>>> Also, keep in mind that CHM file is not going to offer help for
"ri"
>>> or "help" in IRB.
If we do offer a second installer for documentation and books and
such, my own leaning would be to include all the ri, too.

Otherwise you can''t do any offline doc lookup [well, not as easily].
Thoughts?
=r

On Thu, Jul 16, 2009 at 11:44 PM, Roger Pack<rogerdpack at gmail.com>
wrote:
>>>> Also, keep in mind that CHM file is not going to offer help for
"ri"
>>>> or "help" in IRB.
>
> If we do offer a second installer for documentation and books and
> such, my own leaning would be to include all the ri, too.
>
> Otherwise you can''t do any offline doc lookup [well, not as
easily].
> Thoughts?
Does Ri inject properly at runtime the documentation? I mean it alters
the definition based on "required" files. I believe it not, so CHM is
going to be the same, you search for it and read the docs.

-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

> Does Ri inject properly at runtime the documentation? I mean it alters
> the definition based on "required" files. I believe it not, so
CHM is
> going to be the same, you search for it and read the docs.
I''m not sure if I understand what inject means.  It is also true that
95% of end users won''t use RI [they''ll just use
ruby-doc.org]...hmm...I''m still in thinking that we could perhaps
release two versions of each--one that is *large, fat, slow* and one
that is lean and mean.
Thoughts?
=r

On Wed, Jul 22, 2009 at 11:52 AM, Roger Pack<rogerdpack at gmail.com>
wrote:
>> Does Ri inject properly at runtime the documentation? I mean it alters
>> the definition based on "required" files. I believe it not,
so CHM is
>> going to be the same, you search for it and read the docs.
>
> I''m not sure if I understand what inject means. ?It is also true
that
> 95% of end users won''t use RI [they''ll just use
> ruby-doc.org]
For example, if I call ri Object would read the documentation for it,
but wouldn''t that change if I loaded before (using require) something
that contained it''s own documentation for the same element?

Perhaps intellisense is not something that RI has been built for ;-)

Anyhow...

...hmm...I''m still in thinking that we could
perhaps
> release two versions of each--one that is *large, fat, slow* and one
> that is lean and mean.
> Thoughts?
Please take a look to this:

http://rubyosx.rubyforge.org/

You have the installers for 1.8.6 (and upcoming 1.9.1) and a separate
installer with full RI and RDocs.

I agree that I would love to split them, but going back to the original message:

ri Something come back empty.

I wonder how many people actually use ri.

Current One-Click ships with FXIRB, an interactive console which at
the same time offer access to the documentation.

I must say never used it, and considered too much (ok, I''m a man of a
simple notepad and the command prompt, so...)

Forgetting for one second that generating RDoc for Ruby-core eats the
processor and RAM, the additional installers should contain RI and
RDoc, while the CHM should be bundled with the standard installer.

People will still have access to documentation with the package, and
those wanting to have ri and rdoc for stdlib and core, they can
download the additional package.

-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

On Wed, Jul 22, 2009 at 9:07 PM, Luis Lavena<luislavena at gmail.com>
wrote:
> I agree that I would love to split them, but going back to the original
message:
On the grippind hand, maybe you can make it a downloadable component
in the installer? Thus, if somebody wants the docs installed, the
installer downloads them on demand. That would kill two birds with one
stone (and an "all inclusive installer" for corporate deployment.
I''m
thinking Windows Service Packs here, whihh download only what''s
needed, but are available as a full download for corporate
deployments).

Phillip Gawlowski

Though the folk I have met,
(Ah, how soon!) they forget
When I''ve moved on to some other place,
There may be one or two,
When I''ve played and passed through,
Who''ll remember my song or my face.

> Forgetting for one second that generating RDoc for Ruby-core eats the
> processor and RAM, the additional installers should contain RI and
> RDoc, while the CHM should be bundled with the standard installer.
That sounds reasonable compromise.  Another option would be to include
the core src...and people can generate their own if they so desire?
[except maybe without tk since that''s so many files :) ]

@Philip "download on demand" nice but who wants to do the installer
recipes :)
=r

On Thu, Jul 23, 2009 at 9:48 AM, Phillip
Gawlowski<cmdjackryan at googlemail.com> wrote:
> On Wed, Jul 22, 2009 at 9:07 PM, Luis Lavena<luislavena at gmail.com>
wrote:
>
>> I agree that I would love to split them, but going back to the original
message:
>
> On the grippind hand, maybe you can make it a downloadable component
> in the installer? Thus, if somebody wants the docs installed, the
> installer downloads them on demand. That would kill two birds with one
> stone (and an "all inclusive installer" for corporate deployment.
I''m
> thinking Windows Service Packs here, whihh download only what''s
> needed, but are available as a full download for corporate
> deployments).
>
> Phillip Gawlowski
>
Thank you Phillip for chiming in.

Download on demand is not as easy as may sound, and also jump the
complexity of the installer itself.

One way is putting it on a way of "select the components to be
installed", which I''m wanting to avoid (to keep the clicks to the
minimum).

The other is a the successful installation screen, but that means
another installer to be downloaded (something we are thinking of).

The issue over there is that a installer that bundles everything and
one with just the docs are too much to maintain. I would rather keep
them separated and offer a link in the menu shortcuts to go the
website to grab the installers.

-- 
Luis Lavena
AREA 17
-
Perfection in design is achieved not when there is nothing more to add,
but rather when there is nothing more to take away.
Antoine de Saint-Exup?ry

On Thu, Jul 23, 2009 at 3:35 PM, Luis Lavena<luislavena at gmail.com>
wrote:
> Download on demand is not as easy as may sound, and also jump the
> complexity of the installer itself.
Point well taken. However, that is the problem that the installer team
has to solve. ;)
> One way is putting it on a way of "select the components to be
> installed", which I''m wanting to avoid (to keep the clicks to
the
> minimum).
Well, sensible defaults would be needed there. The trouble is, that
finding these out would need a usability study, which costs money.

Though, during development you could run a blind A/B test, and have
the installer send back inforamtion to a central server, and then
slice and dice the data to find out what''s most commonly installed
(i.e. which options are checked, where is Ruby installed to, these
things).

That, however, would create an enormous workload for the project at large. :(
> The other is a the successful installation screen, but that means
> another installer to be downloaded (something we are thinking of).
Which is a) another click (as you put it ;), and b) much more of a
burden on the users than an option to download the docs from within.
An option would be to download an installer from the website (the same
that would install documentary if you did this step manually), and
simply execute it once the Ruby interpreted has done its tasks.

I''m strictly speaking from a user''s perspective. And while the
target
audience are programmers and sys admins, we all know how lazy *those*
are. ;)
> The issue over there is that a installer that bundles everything and
> one with just the docs are too much to maintain. I would rather keep
> them separated and offer a link in the menu shortcuts to go the
> website to grab the installers.
Well, a "docs only" installer introduces an additional script ot the
build process. A lot of the work would be a one-time cost, I think.

It''d be the same workload as maintaining a "Ruby non-doc" and
a "Ruby
including docs" installer, in the end.


Phillip Gawlowski

Though the folk I have met,
(Ah, how soon!) they forget
When I''ve moved on to some other place,
There may be one or two,
When I''ve played and passed through,
Who''ll remember my song or my face.