Jon
2009-Jul-06 20:44 UTC
[Rubyinstaller-devel] 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.
Luis Lavena
2009-Jul-06 21:00 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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
Roger Pack
2009-Jul-06 21:03 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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
Roger Pack
2009-Jul-06 21:06 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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
Jon
2009-Jul-06 21:23 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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?
Luis Lavena
2009-Jul-06 21:30 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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
Roger Pack
2009-Jul-07 13:02 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
>> 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
Jon
2009-Jul-07 17:24 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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.
Luis Lavena
2009-Jul-07 17:28 UTC
[Rubyinstaller-devel] ri documentation included in final 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
Jon
2009-Jul-07 18:08 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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.
Roger Pack
2009-Jul-07 18:20 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
>> 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
Luis Lavena
2009-Jul-07 19:33 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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
Roger Pack
2009-Jul-17 02:44 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
>>> 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
Luis Lavena
2009-Jul-22 05:51 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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
Roger Pack
2009-Jul-22 14:52 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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
Luis Lavena
2009-Jul-22 19:07 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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
Phillip Gawlowski
2009-Jul-23 12:48 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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.
Roger Pack
2009-Jul-23 13:28 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
> 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
Luis Lavena
2009-Jul-23 13:35 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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
Phillip Gawlowski
2009-Jul-23 14:00 UTC
[Rubyinstaller-devel] ri documentation included in final installer?
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.