Volunteers to upgrade rdoc_chm gem?

[Luis Lavena]

Hello,

RubyInstaller depends on successfully generate CHM help files for the
installers. The gem to extract RDoc and generate the CHM is named
rdoc_chm:

https://github.com/vertiginous/rdoc_chm

It depends on RDoc 2.5.11, since newer RDoc changed the plugin architecture.

That particular version of RDoc don't handle properly Ruby 1.9.3
encodings, so it fails trying to parse and build CHM for Ruby.

To simply test this issue, just remove the gem constrain from RubyInstaller:

https://github.com/oneclick/rubyinstaller/blob/master/recipes/tools/docs.rake#L7-9

Install latest rdoc and rdoc_chm gems and try building latest Ruby
1.8.7 or 1.9.3

Of course, you need Ruby 1.9.3 itself.

Any volunteers? I can ask Gordon to grant permission to repository and
gem so they can push the updated version.

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

[Justin Baker]

On Friday, March 2, 2012 5:21:27 PM UTC-6, Luis Lavena wrote:

Hello,

RubyInstaller depends on successfully generate CHM help files for the
installers. The gem to extract RDoc and generate the CHM is named
rdoc_chm:

https://github.com/vertiginous/rdoc_chm

It depends on RDoc 2.5.11, since newer RDoc changed the plugin architecture.

That particular version of RDoc don't handle properly Ruby 1.9.3
encodings, so it fails trying to parse and build CHM for Ruby.

Yeah, I'm looking at it, but I didn't actually think it would be as simple as it was when I 

first looked at it. But I've got most of it complete and it's looking good so far.

 

To simply test this issue, just remove the gem constrain from RubyInstaller:

https://github.com/oneclick/rubyinstaller/blob/master/recipes/tools/docs.rake#L7-9

Install latest rdoc and rdoc_chm gems and try building latest Ruby
1.8.7 or 1.9.3

Of course, you need Ruby 1.9.3 itself.

Any volunteers? I can ask Gordon to grant permission to repository and
gem so they can push the updated version.

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

I've got the template working with the new RDoc versions but I think that there are some quirks

that I've got to look at. But the problem is the fact that the ruby1.9.3 stdlib has 'UTF-8' Japanese 

characters and the default encoder for windows is IBM437 doesn't understand. So I had to change 

the Rdoc builder in the docs.rake to use 'UTF-8' as the encoder. You might be able to do this

with the current setup to get it working again, but I didn't try.

Overall I have the chm files are building and they "look" ok, but I'm going to go over them to make

sure and then clean up the code and figure out if everything I changed was actually necessary. 

Also, I rewrote a lot of the docs.rake task to make it more malleable while I was playing around.

I also ended up adding an option to build the docs using the regular Darkfish generator while

I was debugging. I don't know if that's something you guys would be interested in but I could

clean it up and load it in to a github fork later if you guys want to look at it. But it works just

fine with just a minor tweak to the current docs.rake.

Justin

[Luis Lavena]

Hello Justin,

On Thu, Mar 8, 2012 at 5:08 PM, Justin Baker <azol...@gmail.com> wrote:
>
> Yeah, I'm looking at it, but I didn't actually think it would be as simple
> as it was when I
> first looked at it. But I've got most of it complete and it's looking good
> so far.
>

Nice!

> I've got the template working with the new RDoc versions but I think that
> there are some quirks
> that I've got to look at. But the problem is the fact that the ruby1.9.3
> stdlib has 'UTF-8' Japanese
> characters and the default encoder for windows is IBM437 doesn't understand.

My console is 1252 (Windows-1252) which you can change using "chcp"
from the console.

> So I had to change
> the Rdoc builder in the docs.rake to use 'UTF-8' as the encoder. You might
> be able to do this
> with the current setup to get it working again, but I didn't try.

If latest RDoc is having problems to detect that, please open a issue
on RDoc for them to fix the encoding issue:

https://github.com/rdoc/rdoc

> Overall I have the chm files are building and they "look" ok, but I'm going
> to go over them to make
> sure and then clean up the code and figure out if everything I changed was
> actually necessary.
>

Nice, just let us know when you're done the fork link ;-)

> Also, I rewrote a lot of the docs.rake task to make it more malleable while
> I was playing around.

Patches are welcome, I love patches, show us! :-D

> I also ended up adding an option to build the docs using the regular
> Darkfish generator while
> I was debugging. I don't know if that's something you guys would be
> interested in but I could
> clean it up and load it in to a github fork later if you guys want to look
> at it. But it works just
> fine with just a minor tweak to the current docs.rake.
>

Last time I played with darkfish it didn't play nice for embedded C
source code, I believe that was the reason we had a custom theme.

I wouldn't mind a lighter theme like the one used by YARD, but can I
dream, right? :)

Thank you for your time and looking forward your changes!

[Justin Baker]

On Thursday, March 8, 2012 2:20:22 PM UTC-6, Luis Lavena wrote:

Hello Justin,

On Thu, Mar 8, 2012 at 5:08 PM, Justin Baker <azol...@gmail.com> wrote:
>
> Yeah, I'm looking at it, but I didn't actually think it would be as simple
> as it was when I
> first looked at it. But I've got most of it complete and it's looking good
> so far.
>

Nice!

Sorry, I've been busy the past few days. I should have some free time this

weekend to finish it up. But the chcp command helped me understand 

what was up a little bit better.

 

My console is 1252 (Windows-1252) which you can change using "chcp"
from the console.

That's pretty awesome, I can't believe I never knew about this. Anyway I

found that RDoc won't build using the 1252 code page either but will with

the 65001 (UTF-8) page. Not surprisingbut still useful to know.   

If latest RDoc is having problems to detect that, please open a issue
on RDoc for them to fix the encoding issue:

https://github.com/rdoc/rdoc

Alright, I'll try and to do it tomorrow sometime.

 

Last time I played with darkfish it didn't play nice for embedded C
source code, I believe that was the reason we had a custom theme.

I wouldn't mind a lighter theme like the one used by YARD, but can I
dream, right? :)

I don't know what the old Darkfish template looks like, so I don't know

if it's any better or worse. But I can say that the core and stdlib docs I

built from Darkfish look a lot like ruby-doc.org, minus some niceties and

and different styling, but the docs look a lot a like. So unless I'm missing

something it shouldn't be too difficult to get into a YARD format.

Personally, I'll probably try to sneak an sdoc task in there too and see

how that looks now.

Thank you for your time and looking forward your changes!

 Nope problem! Glad I can help and I'll let you know how it's going.

Justin

[Justin Baker]

On Saturday, March 10, 2012 12:45:57 AM UTC-6, Justin Baker wrote:

 Nope problem! Glad I can help and I'll let you know how it's going.

Alright, I've got rdoc_chm done and uploaded.

https://github.com/Azolo/rdoc_chm 

with a pull request

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

The only caveat is that you have to change your page file to UTF-8 via 'chcp 65001'

or use the '--encoding=UTF-8' option.

I have an issue open for RDoc for that too.

I think I'm going start working on the rubyinstaller 'docs' task now. I'll try to get something on

that done within the next few days.

Justin

[Justin Baker]

On Sunday, March 11, 2012 1:38:19 PM UTC-5, Justin Baker wrote:

On Saturday, March 10, 2012 12:45:57 AM UTC-6, Justin Baker wrote:

 Nope problem! Glad I can help and I'll let you know how it's going.

Alright, I've got rdoc_chm done and uploaded.

Maybe not, it looks like file pages aren't getting output. I saw they were

being processed during a debug but didn't realize they weren't getting any

output. 

Looks like if there's no text defined in a file then RDoc skips an output file.

I could get the legacy behavior back but there's another bug in the Darkfish

template that is preventing that...

I'll get another bug report in for RDoc tomorrow and then see what I can do

until then.

Sorry, missed that =/

Justin

[Luis Lavena]

On Tue, Mar 13, 2012 at 1:45 AM, Justin Baker <azol...@gmail.com> wrote:
>
> Maybe not, it looks like file pages aren't getting output. I saw they were
> being processed during a debug but didn't realize they weren't getting any
> output.
>
> Looks like if there's no text defined in a file then RDoc skips an output
> file.
> I could get the legacy behavior back but there's another bug in the Darkfish
> template that is preventing that...
>
> I'll get another bug report in for RDoc tomorrow and then see what I can do
> until then.
>
> Sorry, missed that =/
>

No need to sorry Justin, just keep us posted on your progress and let
us know when we can start poking around :D

Once again thank you.

[Justin Baker]

On Wednesday, March 14, 2012 6:13:06 PM UTC-5, Luis Lavena wrote:

No need to sorry Justin, just keep us posted on your progress and let
us know when we can start poking around :D

Once again thank you.

 I finally got some free time the last couple days and got the rake changes I used to

troubleshoot the problem kinda cleaned up, anyway here's the compare on github.

https://github.com/Azolo/rubyinstaller/compare/docs

They seem to work with "most" rdoc generators, but the don't have they nice separate

core and stdlib (but you can build them separately or as a combonation). I mainly did it so I 

could understand what was going on in the other rake task, but was proud enough of

it to share, haha.

For get the darkfish template you would just do:

rake ruby19:docs format=darkfish

or for just the core or stdlib

rake ruby19:docs:core format=darkfish

rake ruby19:docs:stdlib format=darkfish 

It's versatile enough that you should just be able to drop any format you want in there and it

will build the docs. (I got sdoc building after editing sdoc)

Now I'm going to go back and use my free time to try finish the rdoc_chm. Hopefully I can get that

done in the next week or so.

Justin

[Justin Baker]

On Wednesday, March 14, 2012 6:13:06 PM UTC-5, Luis Lavena wrote:

No need to sorry Justin, just keep us posted on your progress and let
us know when we can start poking around :D

Once again thank you.

Alright, it looks like the rdoc_chm gem is working better now.

So, when you get a chance take a look at it and let me know if you see anything

out of the ordinary.

There might be a few differences, But most of are improvements in my opinion.

I ended up copying the new Darkfish css over and just changing the margins so 

it looked better on the page. Other than that it's pretty much just the new css file.

Justin

[Luis Lavena]

Hello Justin

Sorry for not getting back to you before but work has been taking all
my free time over the past weeks (not to mention health hasn't been
top).

Anyway, don't want you to feel that your work is not valuable, but I
think will be great if you can write up a new thread describing what
where your objectives, what have you done to achieve them, which
branch should I check for it and I'll go over it in one pass instead
of scanning over this thread and your individual commits without
following the conversation properly.

It will also serve me to ask Gordon for commit and push permissions
for rdoc_chm gem, which is what we are aiming to.

I want to integrate those changes since I believe being stuck at one
particular version is bad for us.

Thank you for your work and hope you understand my reasons for this request.

Regards,

[Justin Baker]

On Sunday, April 15, 2012 4:33:05 PM UTC-5, Luis Lavena wrote:

Hello Justin

Sorry for not getting back to you before but work has been taking all
my free time over the past weeks (not to mention health hasn't been
top).

It's completely fine. =) I hope you feel better.

Don't worry about me too much.

 

Anyway, don't want you to feel that your work is not valuable, but I
think will be great if you can write up a new thread describing what
where your objectives, what have you done to achieve them, which
branch should I check for it and I'll go over it in one pass instead
of scanning over this thread and your individual commits without
following the conversation properly.

It will also serve me to ask Gordon for commit and push permissions
for rdoc_chm gem, which is what we are aiming to.

I want to integrate those changes since I believe being stuck at one
particular version is bad for us.

Thank you for your work and hope you understand my reasons for this request.

Sure, but I'm a little confused. Do you want me to create a new thread just for the rdoc_chm

pull request?

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

Or everything else too? Because the rdoc_chm update should pretty much work with the current 

doc recipe.

Plus everything else is more like an experiment and an exercise for my benefit. 

I don't mind explaining it, but it's probably separate anyway.

Either way, I don't mind doing it but I just wanted to make sure what you want me to do before

I start doing something you really didn't want/need.

Justin