[Rubyinstaller-devel] [ANN] RDoc_CHM

Gordon Thiesfeld gthiesfeld at gmail.com
Sun Jul 26 16:23:36 EDT 2009


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


More information about the Rubyinstaller-devel mailing list