I thought I should start a new thread for this, rather than hijack the TODO thread. I''ve just heard back from Eric Hodel, and I''m officially the rdoc_chm maintainer. I''ll be using my github[1] repo as the "official" rdoc_chm repo, but I''ll be releasing to rubyforge, so releases will be listed on the rdoc rubyforge project page[2]. The next release will be rdoc_chm 2.4.0, and will be compatible with rdoc 2.4. I''m also kicking around an idea that would allow people to generate a chm documentation index of all their rubygems. More to come on that. I''ve uploaded my chm files for Ruby 1.9 to github[3] if anyone wants to take a look. I''m hoping for lots of feedback ;-) [1] http://github.com/vertiginous/rdoc_chm/tree/master [2] http://rubyforge.org/projects/rdoc [3] http://github.com/vertiginous/rubyinstaller/downloads
> I''ve uploaded my chm files for Ruby 1.9 to github[3] if anyone wants > to take a look. I''m hoping for lots of feedback ;-)Perhaps you could provide a download to an example chm file so we could take a look at how it works? Oh and congrats on your new responsibility :) =r
On Thu, Jul 23, 2009 at 9:23 AM, Roger Pack<rogerdpack at gmail.com> wrote:>> I''ve uploaded my chm files for Ruby 1.9 to github[3] if anyone wants >> to take a look. I''m hoping for lots of feedback ;-) > > Perhaps you could provide a download to an example chm file so we > could take a look at how it works?I provided a link to the Ruby1.9 chm files. It''s a 7z file, consisting of 3 chm files. Two are generated by rdoc_chm: ruby19-core.chm ruby19-stdlib.chm The third is a "master" file which simply links the first two into one. This one is generated using separate ERB templates, and the docs:meta_docs rake task. ruby19.chm Would you like to see some other sort of example?> Oh and congrats on your new responsibility :)Thanks. Gordon
> I provided a link to the Ruby1.9 chm files. ?It''s a 7z file, > consisting of 3 chm files. Two are generated by rdoc_chm:Oops I missed that link for some reason. You had read my mind :) =r
> I''ve uploaded my chm files for Ruby 1.9 to github[3] if anyone wants > to take a look. I''m hoping for lots of feedback ;-)Gordon, Nice. They work great so far and are so much better than dealing with ri. Thanks! Jon Feedback ======= * I like the Ruby version number as a title for ruby19.chm''s main window. * The README file in ruby19.chm doesn''t really add any value and it was poorly formatted. I''m for completely removing the file. * The documentation in the "Files" folder of both core and stdlib is mostly missing. In core there''s zero useful information. I''m for removing both of these folders from the .chm''s. That said, this may be unwise for stdlib as it appears some info would be lost. For example "lib/English.rb" in the Files folder of stdlib contains some info, but there''s nothing in the Classes folder. * I''m not a fan of the 1px red border for "Not Documented" content. I''d prefer the "<dd class="description missing-docs">(Not documented)</dd>" placeholders not even be created. * Typos in the comments. "Important" typos such as "Dir.[]" getting mangled into "..]] => array" really needs a core committer to clean it up in trunk. In this specific example, there''s also a link reference that got incorrectly generated.
On Sat, Jul 25, 2009 at 1:38 PM, Jon<jon.forums at gmail.com> wrote:> [...] > > * Typos in the comments. ?"Important" typos such as "Dir.[]" getting mangled into "..]] => array" really needs a core committer to clean it up in trunk. ?In this specific example, there''s also a link reference that got incorrectly generated. >There was lot of RDoc fixes on trunk for 1.9.2 that didn''t get backported to 1.9.1, perhaps next 1.9.1 release get those integrated, but highly likely the wouldn''t. -- 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 10:56 AM, Gordon Thiesfeld<gthiesfeld at gmail.com> wrote:> I thought I should start a new thread for this, rather than hijack the > TODO thread. >Nice ;-)> [...] > > I''ve uploaded my chm files for Ruby 1.9 to github[3] if anyone wants > to take a look. I''m hoping for lots of feedback ;-) >My feedback: It seem that the colors codesamples of darkfish template are weird, they can barely be read :-P (talking about the embedded source for some methods). Also, seems the checking Index for "new (Date)" display me the standard library twice, and once clicked both are directed to the same document reference. Great work Gordon, as always! Wish: I would love the new help system for Visual Studio 2010 get released... standard HTML in a zip 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 Sat, Jul 25, 2009 at 11:38 AM, Jon<jon.forums at gmail.com> wrote:> Feedback > =======> > * I like the Ruby version number as a title for ruby19.chm''s main window. > > * The README file in ruby19.chm doesn''t really add any value and it was poorly formatted. ?I''m for completely removing the file.I''ve been on the fence about this one for a while. I agree it doesn''t add much value. I *would* like to add some extra content, though. Maybe an "about rubyinstaller" page or something, a links page would be nice, and possibly a license page.> > * The documentation in the "Files" folder of both core and stdlib is mostly missing. ?In core there''s zero useful information. ?I''m for removing both of these folders from the .chm''s. ?That said, this may be unwise for stdlib as it appears some info would be lost. ?For example "lib/English.rb" in the Files folder of stdlib contains some info, but there''s nothing in the Classes folder. >Yeah, this is sort of default rdoc behavior. Have a look at the files section on ruby-doc.org, for example. I''d rather have some blank pages, and play it safe.> * I''m not a fan of the 1px red border for "Not Documented" content. ?I''d prefer the "<dd class="description missing-docs">(Not documented)</dd>" placeholders not even be created. >I don''t know, I kind of like this feature. I also don''t want to change the Darkfish template any more than I need to to make it work in a chm file.> * Typos in the comments. ?"Important" typos such as "Dir.[]" getting mangled into "..]] => array" really needs a core committer to clean it up in trunk. ?In this specific example, there''s also a link reference that got incorrectly generated. >This is definitely a problem. I''m actually excluding the rdoc files in the stdlib rdoc generation, because the MS HTML Help compiler chokes on the html output. Thanks, Gordon
On Sat, Jul 25, 2009 at 1:42 PM, Luis Lavena<luislavena at gmail.com> wrote:> My feedback: > > It seem that the colors codesamples of darkfish template are weird, > they can barely be read :-P > (talking about the embedded source for some methods).This is fixed. IE apparently doesn''t support the "inherit" CSS property. I also fixed the problem with the HTML Help compiler not adding the image files.> > Also, seems the checking Index for "new (Date)" display me the > standard library twice, and once clicked both are directed to the same > document reference. >There should be a link to the instance method new and a link to the class method new.> Wish: I would love the new help system for Visual Studio 2010 get > released... standard HTML in a zip package :-)Yeah. I''ve been keeping my eye on MS Help 3. Thanks, Gordon
> I *would* like to add some extra content, though. > Maybe an "about rubyinstaller" page or something, a links page would > be nice, and possibly a license page.How about an intro page that gives a quick blurb on what documentation is included, warnings that there may be missing doc info due to missing comments in the original source files, and some links to some useful documentation sites? Even if these links duplicate the items installed in the Start menu by OCI, I think the duplication is OK. Do you think there''s a need for a license page specific to the documentation?> I''d rather have some blank pages, and play it safe.Is there any way to filter these out between the generation and compilation-into-a-CHM phases? I''m for trashing the completely empty ones if it''s possible without too much drama.> I don''t know, I kind of like this feature. I also don''t want to > change the Darkfish template any more than I need to to make it work > in a chm file.Understood. Any you''re in the unenviable role of having to sort through both functional and stylistic feedback :( Hey, one benefit to the red boxes is that they hilite where additional comments in the source could be useful :)> ...because the MS HTML Help compiler chokes on the html output.Maybe the compiler is only smart enough to understand the IE6 dialect of things?...cheap shot. ADDITIONAL FEEDBACK ================== * Method signature formatting is mangled in cases of multiple aliases/usages. For example, check out Kernel.open in which the signature info for the block and non-block version get''s munged together instead of being broken up into two separate lines. * I haven''t found any docs for Digest::SHA1 and Digest::MD5. It appears that Digest::Instance has some of the important class methods like ''digest'' and ''hexdigest'' documented, but where''s the ''file'' method? I''m guessing you''re handcuffed on this one as the problem is likely due to missing comments in the source rather than anything in rdoc/MS HTML Help compiler.