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.
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
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<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'.
> 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...
> 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.
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!? :(
> > 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.
> 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.
> 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!? :(
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
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=...`
> 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=...`
Elapsed: 36.9s cp C:/projects/rubyinstaller-git/sandbox/doc/ruby19/ruby19-core/ruby19-core.ch m 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.ch m
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 :)
> 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.
> 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.
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.
>> 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.
> 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`
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.
> 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`
> 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.
> 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
> > 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`
> > 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.
> > 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
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.
> > > 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.
> > > 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
> 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.
> > 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.
> > > 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.
> 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 ;)
> 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
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.
On Wed, Apr 18, 2012 at 1:46 PM, Justin Baker <azolo1...@gmail.com> wrote:
> 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.
> 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
> --
> 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 rubyinstaller@googlegroups.com.
> To unsubscribe from this group, send email to
> rubyinstaller+unsubscribe@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
On Tue, May 1, 2012 at 10:05 PM, Luis Lavena <luislav...@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.
-- 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, May 9, 2012 at 8:09 PM, Luis Lavena <luislav...@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:
> 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
>> 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.
> 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.
Thank you.
-- 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, May 9, 2012 at 11:43 PM, Justin Baker <azolo1...@gmail.com> wrote:
>> 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!
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
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
