Proposed rdoc_chm changes

[Justin Baker]

I've updated rdoc_chm gem and at the request of Luis I'm making a new thread

to outline my changes.

The goal of my changes were to upgrade the rdoc_chm gem to use atleast RDoc 3.12,

(currently stuck on 2.5.11).

Currently rubyinstaller can't create chm doc files for Ruby 1.9 using Ruby 1.9 so this

update is to fix that.

Pull Request: https://github.com/vertiginous/rdoc_chm/pull/4

My fork/branch: https://github.com/Azolo/rdoc_chm/tree/newrdoc_compat

The History.txt holds a pretty good outline of the changes:

https://github.com/Azolo/rdoc_chm/blob/newrdoc_compat/History.txt

So I won't just repeat that here.

Here are my changes and the rational for my changes (actual change in bold):

The only big API change seemed to be that "render_template" binding is now 

captured in a block. So, changing that was the first step, along with changing 

a few variable names for clarity sake.

But "assemble_template" in the Darkfish generator had changed with 3.12 and 

would break when assembling '.hhk' files. 

So I overrode the 'assemble_template" method.

Then, I found a bug in RDoc that would cause legacy file names to break. 

Until the next version of RDoc is released I had to override 'generate_file_files' 

to allow the legacy template naming and produce pages for files.

The only real change I made to the HTML that is produced was remove 

the Debug dumps from the templates.

Finally the styling of the new files didn't look good with the 'rdoc.css' that was 

being used. But instead of the time consuming process of pecking around and 

trying to find the differences between the old stylesheet and the Darkfish one, 

I just copied the new stylesheet over and edited it for chm viewing.

Some of the minor changes are:

* Updated 'discover.rb' to use RDoc's suggested format

* Updated version number

* Updated RDoc version requirements

* Added DESCRIPTION constant for list in available generators

If anyone finds any problems with it, let me know.

Justin

[Jon]

> The goal of my changes were to upgrade the rdoc_chm gem to use atleast RDoc
> 3.12, (currently stuck on 2.5.11).
>
> Currently rubyinstaller can't create chm doc files for Ruby 1.9 using Ruby
> 1.9 so this update is to fix that.
>
> Pull Request: https://github.com/vertiginous/rdoc_chm/pull/4
> My fork/branch: https://github.com/Azolo/rdoc_chm/tree/newrdoc_compat
>
> The History.txt holds a pretty good outline of the changes:
> https://github.com/Azolo/rdoc_chm/blob/newrdoc_compat/History.txt
> So I won't just repeat that here.

Fantastic...will do a fresh install of HTML Help and try from scratch. A few questions:

1) Must install the http://www.microsoft.com/download/en/details.aspx?id=21138 version?
2) Can build both 1.8.x and 1.9.x CHMs using existing RubyInstaller recipes using 1.9.3 as the build Ruby?
3) Can build CHMs using 1.8.7 as the build Ruby?...IMO, a "who cares if it doesn't"
4) Can build CHMs with both RDoc 3.12 and legacy 2.5.11?...if only 3.10+ I think it's OK

Jon

[Justin Baker]

Fantastic...will do a fresh install of HTML Help and try from scratch.  A few questions:

1) Must install the http://www.microsoft.com/download/en/details.aspx?id=21138 version?

Hmmm, I don't know. I used the hh.exe that came with windows 7.

I didn't touch any of that code though, so if it worked before it should work now.

 

2) Can build both 1.8.x and 1.9.x CHMs using existing RubyInstaller recipes using 1.9.3 as the build Ruby?

Yes, there is an important caveat that I forgot to mention though. RDoc #106 is a encoding bug and 

Ruby 1.9 has some characters that require UTF-8. You can fix this by adding '--encoding=UTF-8' to

'default_ops'.

 

3) Can build CHMs using 1.8.7 as the build Ruby?...IMO, a "who cares if it doesn't"

I'm like 99% sure it does. I think I tested this case, but I don't remember.

Either way I think that is more dependent on RDoc. If it doesn't work I'll let you know.

 

4) Can build CHMs with both RDoc 3.12 and legacy 2.5.11?...if only 3.10+ I think it's OK

I know it can't with 2.5.11, it requires atleast RDoc 3.12 as a dependency also. So

there is that...

Justin

[Jon]

> > Fantastic...will do a fresh install of HTML Help and try from scratch. A
> > few questions:
> >
> > 1) Must install the
> > http://www.microsoft.com/download/en/details.aspx?id=21138 version?
> >
> Hmmm, I don't know. I used the hh.exe that came with windows 7.
>
> I didn't touch any of that code though, so if it worked before it should
> work now.

I'm guessing you installed HTML Help Workshop at some time in order to get `hhc.exe` as I couldn't find it on my Win7 32bit in C:\Windows or C:\Program Files.

https://github.com/vertiginous/rdoc_chm/blob/master/lib/rdoc/generator/chm.rb#L23

Probably should add a FAQ entry in our Development section to make sure this is clear since MSFTs doco and version mismatches muddies the water for any newcomer...is it 1.3 or 1.0!? :(

http://msdn.microsoft.com/en-us/library/windows/desktop/ms670169%28v=vs.85%29.aspx
http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=21138

> > 2) Can build both 1.8.x and 1.9.x CHMs using existing RubyInstaller
> > recipes using 1.9.3 as the build Ruby?
> >

> Yes, there is an important caveat that I forgot to mention though. RDoc #106<https://github.com/rdoc/rdoc/issues/106> is

> a encoding bug and
> Ruby 1.9 has some characters that require UTF-8. You can fix this by adding
> '--encoding=UTF-8' to 'default_ops'.

Good to know...FAQ entry on our wiki?

> > 3) Can build CHMs using 1.8.7 as the build Ruby?...IMO, a "who cares if it doesn't"
> >
> I'm like 99% sure it does. I think I tested this case, but I don't remember.
> Either way I think that is more dependent on RDoc. If it doesn't work I'll
> let you know.

I don't think we should do anything special to support building with 1.8.7. If it works, great. If not, download our latest 1.9.x and be happy. Of course, Luis' perspective is the final one :)

> > 4) Can build CHMs with both RDoc 3.12 and legacy 2.5.11?...if only 3.10+ I think it's OK
> >
> I know it can't with 2.5.11, it requires atleast RDoc 3.12 as a dependency
> also. So there is that...

I have no real issue with a 3.12+ dep, but we may want more flexibility by allowing 3.10+ (2011-10-08 release)...Luis' decision.

Jon

[Justin Baker]

I'm guessing you installed HTML Help Workshop at some time in order to get `hhc.exe` as I couldn't find it on my Win7 32bit in C:\Windows or C:\Program Files.

  https://github.com/vertiginous/rdoc_chm/blob/master/lib/rdoc/generator/chm.rb#L23

Probably should add a FAQ entry in our Development section to make sure this is clear since MSFTs doco and version mismatches muddies the water for any newcomer...is it 1.3 or 1.0!? :(

  http://msdn.microsoft.com/en-us/library/windows/desktop/ms670169%28v=vs.85%29.aspx
  http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=21138

It must have installed with VS 2010, haha. I don't have have the HTML Help Workshop installed. 

The only thing in the HTML Help Workshop folder is [hhc.exe, itcc.dll], so I don't know

if mine is 1.0 or 1.3... Sorry =X... The only information I can offer is the version is:

Microsoft HTML Help Compiler 4.74.8702

 

> > 2) Can build both 1.8.x and 1.9.x CHMs using existing RubyInstaller
> > recipes using 1.9.3 as the build Ruby?
> >
> Yes, there is an important caveat that I forgot to mention though. RDoc #106<https://github.com/rdoc/rdoc/issues/106> is
> a encoding bug and
> Ruby 1.9 has some characters that require UTF-8. You can fix this by adding
> '--encoding=UTF-8' to 'default_ops'.

Good to know...FAQ entry on our wiki?

Sure, but the rubyinstaller doc recipe still needs to be updated though.

But I don't know if it's a wiki eligible problem. I should have said

ruby19-stdlib has some characters that require UTF-8. I haven't seen

the problem anywhere else.

I don't think we should do anything special to support building with 1.8.7. If it works, great. If not, download our latest 1.9.x and be happy. Of course, Luis' perspective is the final one :)

 I just checked it builds with 1.8.7.

I have no real issue with a 3.12+ dep, but we may want more flexibility by allowing 3.10+ (2011-10-08 release)...Luis' decision.

Hmm, let me see what has changed in 3.10 to 3.12, although the next 

version of RDoc fixes a bug that I had to work around (plus the encoding issue).

Justin

[Jon]

On Win7 32bit with 1.9.3p196 the following worked well

* built and installed rdoc_chm gem from Justin's newrdoc_compat branch
* tweaked the docs.rake recipe for versions and encoding workaround
* `rake ruby19:docs local=...`

except for incorrect versions in the chm titles due to the recipe not extracting version/patch info from version.h (RUBY_VERSION, RUBY_PATCHLEVEL) for local repo builds https://github.com/oneclick/rubyinstaller/blob/master/recipes/tools/docs.rake#L54

[Jon]

With these mods to our `recipes\tools\docs.rake`

diff --git a/recipes/tools/docs.rake b/recipes/tools/docs.rake
index 1359fb7..966213f 100644
--- a/recipes/tools/docs.rake
+++ b/recipes/tools/docs.rake
@@ -4,9 +4,10 @@ require 'rubygems'
interpreters = [RubyInstaller::Ruby18, RubyInstaller::Ruby19]

begin
- gem 'rdoc', '~> 2.5.11'
+ gem 'rdoc', '3.10'
require 'rdoc/rdoc'
- gem 'rdoc_chm', '~> 2.4.2'
+ gem 'rdoc_chm', '>= 2.4.3'
+ puts 'RDoc version: %s' % RDoc::VERSION
rescue Gem::LoadError
if Rake.application.options.show_tasks
puts "You need rdoc 2.5.11 and rdoc_chm 2.4.2 gems installed"
@@ -45,7 +46,7 @@ interpreters.each do |package|

stdlib_files = ['./lib', './ext']

- default_opts = ['--format=chm']
+ default_opts = ['--format=chm', '--encoding=UTF-8']

# build file dependencies
rdocs = [

I get this failure when attempting to build with rdoc 3.10 and 3.11....rdoc 3.12 works fine:

C:\projects\rubyinstaller-git>rake ruby19:docs local=c:\Users\Jon\Documents\RubyDev\ruby-git
RDoc version: 3.10
cd c:/Users/Jon/Documents/RubyDev/ruby-git
invalid options: --format=chm
(invalid options are ignored)
Parsing sources...
100% [75/75] vsnprintf.c

Generating Darkfish format into C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19-core...

Files: 75

Classes: 88 ( 7 undocumented)
Modules: 18 ( 4 undocumented)
Constants: 93 (42 undocumented)
Attributes: 1 ( 1 undocumented)
Methods: 1611 (31 undocumented)

Total: 1811 (85 undocumented)
95.31% documented

Elapsed: 36.9s
cp C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19-core/ruby19-core.chm C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19-core.chm
rake aborted!
No such file or directory - C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19-core/ruby19-core.chm

Tasks: TOP => ruby19:docs => C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19.chm => C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19-core.chm

As rdoc 3.12 came out 2012-12-15, I say use `gem 'rdoc', '~> 3.12'` and other `docs.rake` tweaks, see if uber-debugger Luis can break things, and move on to the next thing :)

Jon

---
Fail fast. Fail often. Fail publicly. Learn. Adapt. Repeat.
http://thecodeshop.github.com | http://jonforums.github.com/
twitter: @jonforums

[Justin Baker]

I get this failure when attempting to build with rdoc 3.10 and 3.11....rdoc 3.12 works fine:

That's totally because of this line:

https://github.com/Azolo/rdoc_chm/blob/eea54d6829bb6f523f78f8a4cfe48e94fe452d55/lib/rdoc/generator/chm.rb#L1

Those requirements should be moved to here though:

https://github.com/Azolo/rdoc_chm/blob/f93ce12db946bcae5f47ca3a1b260c082ea28fde/lib/rdoc/discover.rb

 

As rdoc 3.12 came out 2012-12-15, I say use `gem 'rdoc', '~> 3.12'` and other `docs.rake` tweaks, see if uber-debugger Luis can break things, and move on to the next thing :)

And it is working right now, I'll just keep that in the back of my head on things to do list.

I think that adding it to the pull request is meh though.

Justin

[Jon]

> > I get this failure when attempting to build with rdoc 3.10 and
> > 3.11....rdoc 3.12 works fine:
> >
>
> That's totally because of this line:
> https://github.com/Azolo/rdoc_chm/blob/eea54d6829bb6f523f78f8a4cfe48e94fe452d55/lib/rdoc/generator/chm.rb#L1
>
> Those requirements should be moved to here though:
>
> https://github.com/Azolo/rdoc_chm/blob/f93ce12db946bcae5f47ca3a1b260c082ea28fde/lib/rdoc/discover.rb

Or should it be hoisted all the way up to gem install time?

https://github.com/Azolo/rdoc_chm/blob/master/Rakefile#L22

Haven't really spelunked rdoc_chm, but I think it's cleaner to try to keep all the dependent gem versions handled in one place...the gemspec.

[Justin Baker]

It's an RDoc discovery thing. So you can say that this is less of a dependency and more of a guard.

Right now, it's requiring the file then the file is throwing the LoadError there. We should be throwing

the LoadError in the discover.rb so that another file doesn't get loaded.

Atleast that's how I understood it. =P

Justin

[Jon]

 

If the guard is trying to do part of the package management role of RG, then it's doing too much.

It's OK for client code to guard library/gem usage like we're doing in `docs.rake`

  https://github.com/oneclick/rubyinstaller/blob/9223cac4c31e91d29680da2f7856dcb36f753381/recipes/tools/docs.rake#L6-18

but a library/gem should delegate it's dependency/guard management to the package manager. As I said, I haven't looked in detail at `rdoc_gem` but this look contradictory as the gemspec says it's OK to install a downrev version, but the guard code causes failures unless an uplevel version is used.

  https://github.com/Azolo/rdoc_chm/blob/master/Rakefile#L22
  https://github.com/Azolo/rdoc_chm/blob/eea54d6829bb6f523f78f8a4cfe48e94fe452d55/lib/rdoc/generator/chm.rb#L1

You know the `rdoc_gem` much better than I do, but it looks like this part of the code is best delegated to RG.

Jon

[Justin Baker]

It's an RDoc discovery thing. So you can say that this is less of a dependency and more of a guard.

Right now, it's requiring the file then the file is throwing the LoadError there. We should be throwing

the LoadError in the discover.rb so that another file doesn't get loaded.

 

If the guard is trying to do part of the package management role of RG, then it's doing too much.

It's OK for client code to guard library/gem usage like we're doing in `docs.rake`

  https://github.com/oneclick/rubyinstaller/blob/9223cac4c31e91d29680da2f7856dcb36f753381/recipes/tools/docs.rake#L6-18

but a library/gem should delegate it's dependency/guard management to the package manager. As I said, I haven't looked in detail at `rdoc_gem` but this look contradictory as the gemspec says it's OK to install a downrev version, but the guard code causes failures unless an uplevel version is used.

  https://github.com/Azolo/rdoc_chm/blob/master/Rakefile#L22
  https://github.com/Azolo/rdoc_chm/blob/eea54d6829bb6f523f78f8a4cfe48e94fe452d55/lib/rdoc/generator/chm.rb#L1

You know the `rdoc_gem` much better than I do, but it looks like this part of the code is best delegated to RG.

 Oops, I didn't notice forgot to update the gem dependencies =X

That being said, you'll have to talk to Eric Hodel about the discover.rb thing. I don't know

exactly how it all works. But here is the page that tells me to do that =P

https://github.com/rdoc/rdoc/blob/v3.12/DEVELOPERS.rdoc

Thanks for letting me know about the gem dependency thing.

Justin

[Jon]

Ah, I see. Looks like the `discover.rb` file allows customization of how rdoc loads your rdoc plugin gem. Even though his example shows a version check, it's not a requirement.

For your `rdoc_chm` branch, I think it's OK for `discover.rb` to contain only `require 'rdoc/generator/chm'` and rely RG to do the right thing due to your recent `~> 3.12` gemspec update.

It will also be DRYer as no one will have to remember to maintain version constraints in two places.

Jon

[Justin Baker]

> > If the guard is trying to do part of the package management role of RG,
> > then it's doing too much.
> >
> > It's OK for client code to guard library/gem usage like we're doing in
> > `docs.rake`
> >
> > https://github.com/oneclick/rubyinstaller/blob/9223cac4c31e91d29680da2f7856dcb36f753381/recipes/tools/docs.rake#L6-18
> >
> > but a library/gem should delegate it's dependency/guard management to the
> > package manager. As I said, I haven't looked in detail at `rdoc_gem` but
> > this look contradictory as the gemspec says it's OK to install a downrev
> > version, but the guard code causes failures unless an uplevel version is
> > used.
> >
> >   https://github.com/Azolo/rdoc_chm/blob/master/Rakefile#L22
> >   https://github.com/Azolo/rdoc_chm/blob/eea54d6829bb6f523f78f8a4cfe48e94fe452d55/lib/rdoc/generator/chm.rb#L1
> >
> > You know the `rdoc_gem` much better than I do, but it looks like this part
> > of the code is best delegated to RG.
> >
>
>  Oops, I didn't notice forgot to update the gem dependencies =X
>
> That being said, you'll have to talk to Eric Hodel about the discover.rb
> thing. I don't know exactly how it all works. But here is the page that tells me to do that =P
>
> https://github.com/rdoc/rdoc/blob/v3.12/DEVELOPERS.rdoc


Ah, I see. Looks like the `discover.rb` file allows customization of how rdoc loads your rdoc plugin gem. Even though his example shows a version check, it's not a requirement.

For your `rdoc_chm` branch, I think it's OK for `discover.rb` to contain only `require 'rdoc/generator/chm'` and rely RG to do the right thing due to your recent `~> 3.12` gemspec update.

It will also be DRYer as no one will have to remember to maintain version constraints in two places.

Touché. So what kind of magic is going in Gem.find_files that I'm missing? I looked at this for hours yesterday wanting to know how.

I'm pretty sure I'm more confused today than I was yesterday, haha.

Justin

[Jon]

> > Ah, I see. Looks like the `discover.rb` file allows customization of how
> > rdoc loads your rdoc plugin gem. Even though his example shows a version
> > check, it's not a requirement.
> >
> > For your `rdoc_chm` branch, I think it's OK for `discover.rb` to contain
> > only `require 'rdoc/generator/chm'` and rely RG to do the right thing due
> > to your recent `~> 3.12` gemspec update.
> >
> > It will also be DRYer as no one will have to remember to maintain version
> > constraints in two places.
> >
>
> Touché. So what kind of magic is going in Gem.find_files that I'm missing?
> I looked at this for hours yesterday wanting to know how.
> I'm pretty sure I'm more confused today than I was yesterday, haha.

I looked again and I'm wrong. Even though the version check in `discover.rb` isn't DRY, it's a red herring. Your mod is more robust and looks to be how the rdoc plugin system is meant to work.

# file: rdoc/rdoc.rb
if Gem.respond_to? :find_files then
rdoc_extensions = Gem.find_files 'rdoc/discover'

rdoc_extensions.each do |extension|
begin
load extension


# file: rubygems.rb
...
# Note that find_files will return all files even if they are from different
# versions of the same gem.
...

The `discover.rb` check handles the scenario where one has multiple installed rdoc versions and client code tries to use an unacceptable downrev rdoc version with `rdoc_chm`. The gemspec install-time version check will not catch this runtime issue.

Sorry for the distraction, b761775 should be reverted. Hopefully we can get your branch committed, a new rdoc_chm gem released, and update our `docs.rake` recipe.

Jon

[Justin Baker]

> > Ah, I see. Looks like the `discover.rb` file allows customization of how
> > rdoc loads your rdoc plugin gem. Even though his example shows a version
> > check, it's not a requirement.
> >
> > For your `rdoc_chm` branch, I think it's OK for `discover.rb` to contain
> > only `require 'rdoc/generator/chm'` and rely RG to do the right thing due
> > to your recent `~> 3.12` gemspec update.
> >
> > It will also be DRYer as no one will have to remember to maintain version
> > constraints in two places.
> >
>
> Touché. So what kind of magic is going in Gem.find_files that I'm missing?
> I looked at this for hours yesterday wanting to know how.
> I'm pretty sure I'm more confused today than I was yesterday, haha.

I looked again and I'm wrong. Even though the version check in `discover.rb` isn't DRY, it's a red herring. Your mod is more robust and looks to be how the rdoc plugin system is meant to work.

  # file: rdoc/rdoc.rb
  if Gem.respond_to? :find_files then
    rdoc_extensions = Gem.find_files 'rdoc/discover'

    rdoc_extensions.each do |extension|
      begin
        load extension
 

  # file: rubygems.rb
  ...
  # Note that find_files will return all files even if they are from different
  # versions of the same gem.
  ...

The `discover.rb` check handles the scenario where one has multiple installed rdoc versions and client code tries to use an unacceptable downrev rdoc version with `rdoc_chm`. The gemspec install-time version check will not catch this runtime issue.

Alright, that's what I thought, but it worked well without it and I couldn't ever replicate that situation.

So I just said, alright and commited it. =P

 

Sorry for the distraction, b761775 should be reverted. Hopefully we can get your branch committed, a new rdoc_chm gem released, and update our `docs.rake` recipe.

The revert is done.

Justin

[Jon]

> Alright, that's what I thought, but it worked well without it and I couldn't
> ever replicate that situation. So I just said, alright and commited it. =P

It may turn out to be a BS scenario, but don't give up on your
solutions too early...make someone *prove* they've discovered a better
mousetrap. :)

Active debate leads to higher quality code. Short-term, it may feel
more "combative", but the back-and-forth tussle of ideas is one of the
few defenses we have to guard against crappy code. It's important to
let the tussle of ideas organically play out. It's why I rarely play
the bike-shedding card as I've found it's very easy to play the card
too early and stifle creativity and innovation.

Of course, discussion style is crucial, but you've got the discussion
style nailed: focus on the issue and don't take issue feedback
personally. If someone ever does take your legitimate, issue-specific
feedback too personally, it's their problem and they need find a way
to get over it and move on.

Thanks for this work and hopefully a few others will test it out and
see if they can make it fall down ;)

Jon

[Justin Baker]

It may turn out to be a BS scenario, but don't give up on your
solutions too early...make someone *prove* they've discovered a better
mousetrap. :)

I spent a couple hours testing it last night, it never actually loads the chm

format without those lines. 

So essentially, I had no argument about why it shouldn't be changed.

But what I didn't realize last night is that it does screw with the 

other additional generators that should get loaded. Plus 

probably some other things.

 

Active debate leads to higher quality code. Short-term, it may feel
more "combative", but the back-and-forth tussle of ideas is one of the
few defenses we have to guard against crappy code. It's important to
let the tussle of ideas organically play out. It's why I rarely play
the bike-shedding card as I've found it's very easy to play the card
too early and stifle creativity and innovation.

Of course, discussion style is crucial, but you've got the discussion
style nailed: focus on the issue and don't take issue feedback
personally. If someone ever does take your legitimate, issue-specific
feedback too personally, it's their problem and they need find a way
to get over it and move on.

 

Thanks for this work and hopefully a few others will test it out and
see if they can make it fall down ;)

Thank you for the compliment. =) Glad to help.

Justin

[Luis Lavena]

Hello Justin,

Sorry for top posting but wanted to let you know that Gordon gave me
commit bits on rdoc_chm and will review your pull request and merge
the following days.

If everything looks good will be able to do a gem release that we can
use on RubyInstaller.

Thank you for your hard work and your patience.

> --
> You received this message because you are subscribed to the Google Groups
> "RubyInstaller" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/rubyinstaller/-/NMQmxA5B1fIJ.
> To post to this group, send email to rubyin...@googlegroups.com.
> To unsubscribe from this group, send email to
> rubyinstalle...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/rubyinstaller?hl=en.



--
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

[Luis Lavena]

On Tue, May 1, 2012 at 10:05 PM, Luis Lavena <luisl...@gmail.com> wrote:
> Hello Justin,
>
> Sorry for top posting but wanted to let you know that Gordon gave me
> commit bits on rdoc_chm and will review your pull request and merge
> the following days.
>
> If everything looks good will be able to do a gem release that we can
> use on RubyInstaller.
>
> Thank you for your hard work and your patience.
>

Hello Justin.

I took a look to the changes and everything seems to be good with
rdoc_chm, meaning I will merge and prepare for a release.

However, I'm having problems using this against RubyInstaller.

It has been 15 minutes since it started building stdlib documentation,
eating 50% of CPU (Core 2 Duo) and around 250MB of RAM:

C:\Users\Luis\Projects\oss\oneclick\rubyinstaller>tasklist | find "ruby"
ruby.exe 4124 Console 1 238.724 K

On previous versions that process didn't take that long. I'm using TCS
builds but I don't think that could be the culprit.

I've also used your rdoc changes against RubyInstaller
(docs_config_refactor branch)

Would you mind taking a look to figure out why is taking that long?
(there is no progress on what is doing also, seems to be creating the
topic files)

Thank you.

[Justin Baker]

On Wed, May 9, 2012 at 8:09 PM, Luis Lavena <luisl...@gmail.com> wrote:

I took a look to the changes and everything seems to be good with

rdoc_chm, meaning I will merge and prepare for a release.

However, I'm having problems using this against RubyInstaller.

It has been 15 minutes since it started building stdlib documentation,
eating 50% of CPU (Core 2 Duo) and around 250MB of RAM:

C:\Users\Luis\Projects\oss\oneclick\rubyinstaller>tasklist | find "ruby"
ruby.exe                      4124 Console                    1    238.724 K

On previous versions that process didn't take that long. I'm using TCS
builds but I don't think that could be the culprit.

I've also used your rdoc changes against RubyInstaller
(docs_config_refactor branch)

Would you mind taking a look to figure out why is taking that long?
(there is no progress on what is doing also, seems to be creating the
topic files)

Thank you.

Sure, I'm building them right now.

If maybe you could add '--debug' to default_opts we could see where all

that time is going too. ie

  default_opts = ['--format=chm', '--debug', '--encoding=UTF-8']

It might be that something in rdoc changed.

Anyway, I'm gonna grab dinner then I'll get back to you.

Justin

[Justin Baker]

On Wed, May 9, 2012 at 8:35 PM, Justin Baker <azol...@gmail.com> wrote:

On Wed, May 9, 2012 at 8:09 PM, Luis Lavena <luisl...@gmail.com> wrote:

I took a look to the changes and everything seems to be good with

rdoc_chm, meaning I will merge and prepare for a release.

However, I'm having problems using this against RubyInstaller.

It has been 15 minutes since it started building stdlib documentation,
eating 50% of CPU (Core 2 Duo) and around 250MB of RAM:

C:\Users\Luis\Projects\oss\oneclick\rubyinstaller>tasklist | find "ruby"
ruby.exe                      4124 Console                    1    238.724 K

On previous versions that process didn't take that long. I'm using TCS
builds but I don't think that could be the culprit.

I've also used your rdoc changes against RubyInstaller
(docs_config_refactor branch)

Would you mind taking a look to figure out why is taking that long?
(there is no progress on what is doing also, seems to be creating the
topic files)

It looks like it's a difference in rdoc 3.12 vs rdoc 2.5.11.

Rdoc 3.12 file generation takes much longer.

https://gist.github.com/2650612

ruby18:docs stdlib build time:

72.9s(2.5.11) vs 215.4s(3.12)

So, that's why it's taking so long. =/

Justin

[Luis Lavena]

On Wed, May 9, 2012 at 11:38 PM, Justin Baker <azol...@gmail.com> wrote:
>
> It looks like it's a difference in rdoc 3.12 vs rdoc 2.5.11.
>
> Rdoc 3.12 file generation takes much longer.
>
> https://gist.github.com/2650612
>
> ruby18:docs stdlib build time:
> 72.9s(2.5.11) vs 215.4s(3.12)
>
> So, that's why it's taking so long. =/
>

The weird thing is that it stuck when saying "creating chm" (from the
top of my head)

All the HTML files already existed before the process got stuck.

My computer is off for tonight, but will check tomorrow morning.

[Justin Baker]

The weird thing is that it stuck when saying "creating chm" (from the

top of my head)

All the HTML files already existed before the process got stuck.

My computer is off for tonight, but will check tomorrow morning.

Yeah, that would be a different problem heh.

Let me know tomorrow and I'll look into it!

Justin

[Luis Lavena]

Here you go:

Outputting to C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/ruby19-stdlib.hhp
rendering C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/contents.hhc
Outputting to C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/contents.hhc

(here stalls for 10 minutes with 250MB RAM)

After that it output the list of topics, but don't have more than 3K
of buffer to scroll back.

[Luis Lavena]

On Thu, May 10, 2012 at 2:46 PM, Luis Lavena <luisl...@gmail.com> wrote:
>
> Here you go:
>
> Outputting to C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/ruby19-stdlib.hhp
>  rendering C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/contents.hhc
> Outputting to C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/contents.hhc
>
> (here stalls for 10 minutes with 250MB RAM)
>
> After that it output the list of topics, but don't have more than 3K
> of buffer to scroll back.
>

And the "piece of ressistance":

Compression decreased file by 18,782,232 bytes.

Files: 614

Classes: 1165 ( 631 undocumented)
Modules: 279 ( 147 undocumented)
Constants: 1391 ( 756 undocumented)
Attributes: 858 ( 441 undocumented)
Methods: 7118 (2596 undocumented)

Total: 10811 (4571 undocumented)
57.72% documented

Elapsed: 504.8s

500 seconds...

:-P

[Justin Baker]

On Thu, May 10, 2012 at 12:54 PM, Luis Lavena <luisl...@gmail.com> wrote:

On Thu, May 10, 2012 at 2:46 PM, Luis Lavena <luisl...@gmail.com> wrote:
>
> Here you go:
>
> Outputting to C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/ruby19-stdlib.hhp
>  rendering C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/contents.hhc
> Outputting to C:/Users/Luis/Projects/oss/oneclick/rubyinstaller/sandbox/doc/ruby19/ruby19-stdlib/contents.hhc
>
> (here stalls for 10 minutes with 250MB RAM)
>
> After that it output the list of topics, but don't have more than 3K
> of buffer to scroll back.
>

And the "piece of ressistance":

Compression decreased file by 18,782,232 bytes.

Files:        614

Classes:     1165 ( 631 undocumented)
Modules:      279 ( 147 undocumented)
Constants:   1391 ( 756 undocumented)
Attributes:   858 ( 441 undocumented)
Methods:     7118 (2596 undocumented)

Total:      10811 (4571 undocumented)
 57.72% documented

Elapsed: 504.8s

500 seconds...

:-P

Basically 10 minutes of you life for documentation. Is it worth it?!

Seriously though, I'll look into making generation faster. (RDoc already 

has it's search stuff I can look into)

Also I'll test it against TCS_ruby too and make sure that it isn't slower.

Right now I have a killer headache so I'm gonna go home and take a nap.

And then I will do these important things. =P

Justin

[Luis Lavena]

On Thu, May 10, 2012 at 6:17 PM, Justin Baker <azol...@gmail.com> wrote:
>
> Basically 10 minutes of you life for documentation. Is it worth it?!
>

Hmm, documentation is worth it, sure, but 10 minutes? c'mon!

Just kidding.

I never noticed how slow RDoc has become.

Building documentation with default darkfish (not CHM) takes 700
seconds, even when using TheCodeShop (TCS) builds.

> Seriously though, I'll look into making generation faster. (RDoc already
> has it's search stuff I can look into)
> Also I'll test it against TCS_ruby too and make sure that it isn't slower.
>
> Right now I have a killer headache so I'm gonna go home and take a nap.
> And then I will do these important things. =P
>

Take a break, get some rest and recover, I bet hunting this down is
going to take lot of time and brain power, and we need you fresh for
more useful stuff.

Since I'm moving building of the installers to another computer I
don't care too much it takes 10 minutes on this notebook anymore.

I'm going to merge your rdoc_chm modifications, perform a gem release
and then merge the changes to RubyInstaller.

Thank you so much for your work Justin!