[RAKE] rdoc task fails on Win2k

[James Britt]

When using rake to create rdoc files on Windows 2000, I get this error

rdoc -o doc --main 'README.rdoc' -T 'html' README.rdoc ./lib/catapult.rb
/lib
rake aborted!
Command Failed: [rdoc -o doc --main 'README.rdoc' -T 'html' README.rdoc
/lib/catapult.rb ./lib]


But if I copy and paste that top command string, it runs fine in a CMD box.

Here's the task def:

Rake::RDocTask.new( :rdoc ){ |rd|
rd.rdoc_dir = 'doc'
rd.rdoc_files.add( 'README.rdoc', './lib/catapult.rb', './lib' )
rd.main = "README.rdoc"
}


Specs:

ruby 1.8.2 (2004-07-29) [i386-mswin32]
rake, version 0.4.9

I saw a similar message posted here about this problem on WinXP, but did
not see a reply.

James

P.S.

I updated my Rake gem before writing, to see if the current version
fixed this issue. I used this command:

gem update rake

which just seemed like The Way It Would Work. But it updated all my
gems. Which, after running 'gem help update', I then understood.

Is there a way to update just a particular gem file? In lieu of that,
shouldn't I get an error for passing an unknown parameter, so at least I
don't run something I didn't intend?

 

[Jim Weirich]

rdoc -o doc --main 'README.rdoc' -T 'html' README.rdoc ./lib/catapult.rb
./lib
rake aborted!
Command Failed: [rdoc -o doc --main 'README.rdoc' -T 'html' README.rdoc
./lib/catapult.rb ./lib]

Rake just feeds the command string to the system call. Try executing

system %{rdoc -o doc --main 'README.rdoc' -T 'html'
README.rdoc ./lib/catapult.rb ./lib}

and see what happens. If it fails the same way, then we need to figure out
what we need to feed windows to get it to run (e.g. maybe system
%{rdoc.cmd ...} or something like that).

I updated my Rake gem before writing, to see if the current version
fixed this issue. I used this command:

gem update rake

which just seemed like The Way It Would Work. But it updated all my
gems. Which, after running 'gem help update', I then understood.

Is there a way to update just a particular gem file?

Actually, {gem install rake} will install the latest version. But it will
also reinstall if you already have the latest. Hmmm .... I can understand a
desire for a single gem update capability.

In lieu of that, shouldn't I get an error for passing an unknown parameter,
so at least I don't run something I didn't intend?

So noted.

 

[James Britt]

Rake just feeds the command string to the system call. Try executing

system %{rdoc -o doc --main 'README.rdoc' -T 'html'
README.rdoc ./lib/catapult.rb ./lib}

and see what happens. If it fails the same way, then we need to figure out
what we need to feed windows to get it to run (e.g. maybe system
%{rdoc.cmd ...} or something like that).

Here's what I ran, same dir as running rake

puts( system( %{rdoc -o doc --main 'README.rdoc' -T 'html' README.rdoc
./lib/catapult.rb ./lib} ) )
puts( $? )


and here's what I get:
false
nil

So it fails, but there's no residue.

It appears to be related to rdoc on windows being called through rdoc.bat

I wrote a simple batch file, foo.bat:
REM foo.bat
dir

and tried this Ruby code:

puts( system( %{foo} ) ) # false, doesn't seem to find foo.bat
puts( $? ) # nil

But this correctly calls foo.bat:

puts( system( %{foo.bat} ) ) # prints directory, then true
puts( $? ) # 0


So I added the '.bat' extension to the rdoc call, and 'system' is quite
happy:

puts( system( %{rdoc.bat -o doc --main 'README.rdoc' -T 'html'
README.rdoc ./lib/catapult.rb ./lib} ) ) # Works!



...

 

[James Britt]

It appears to be related to rdoc on windows being called through rdoc.bat

Not a patch, but a description of a hack that fixes this for me:

In rdoctask.r, I added

def rdoc
RUBY_PLATFORM =~ /win32/ ? 'rdoc.bat' : 'rdoc'
end

At the end of 'define', I changed that last call to 'sh' to get the
platform-specific rdoc script name:

def define
# ...
file rdoc_target => @rdoc_files + ["Rakefile"] do
rm_r @rdoc_dir rescue nil
opts = option_list.join(' ')
sh %{#{rdoc} -o #{@rdoc_dir} #{opts} #{@rdoc_files}}
end
self
end


Now there is rdoc goodness

Has not been tested on anything other than my Win2k laptop.



James

 

[Dave Thomas]

rdoc -o doc --main 'README.rdoc' -T 'html' README.rdoc
./lib/catapult.rb
./lib
rake aborted!
Command Failed: [rdoc -o doc --main 'README.rdoc' -T 'html'
README.rdoc
./lib/catapult.rb ./lib]

Rake just feeds the command string to the system call. Try executing

system %{rdoc -o doc --main 'README.rdoc' -T 'html'
README.rdoc ./lib/catapult.rb ./lib}

and see what happens. If it fails the same way, then we need to figure
out
what we need to feed windows to get it to run (e.g. maybe system
%{rdoc.cmd ...} or something like that).

I believe that Rake might not be quoting the command (last time we saw
a post about this, the path had spaces in it).


Cheers

Dave

 

[Dave Thomas]

I believe that Rake might not be quoting the command (last time we saw
a post about this, the path had spaces in it).

Or not...


Cheers

Dave

 

[Jim Weirich]

Not a patch, but a description of a hack that fixes this for me:

[... changes for sensing the platform and calling the proper rdoc elided ...]

I like this.

Now there is rdoc goodness

Has not been tested on anything other than my Win2k laptop.

Is rdoc universally called via a .bat file on all windows installs? Is this
likely to change? Do I need to be more aggresive in determining the rdoc
command name?

Thanks for the bug/patch report.

 

[Austin Ziegler]

Not a patch, but a description of a hack that fixes this for me:

[... changes for sensing the platform and calling the proper rdoc elided ...]
Is rdoc universally called via a .bat file on all windows installs? Is this
likely to change? Do I need to be more aggresive in determining the rdoc
command name?

Thanks for the bug/patch report.

Why not bypass the need for calling the batch file entirely?

def build_rdoc(files)
r = RDoc::RDoc.new
r.document(["--main", "README", "--title", "Diff::LCS -- A Diff Algorithm",
"--line-numbers"] + files)

rescue RDoc::RDocError => e
$stderr.puts e.message
rescue Exception => e
$stderr.puts "Couldn't build RDoc documentation\n#{e.message}"
end

def build_ri(files)
ri = RDoc::RDoc.new
ri.document(["--ri-site", "--merge"] + files)
rescue RDoc::RDocError => e
$stderr.puts e.message
rescue Exception => e
$stderr.puts "Couldn't build Ri documentation\n#{e.message}"
end

These could easily be massaged into something more generic and task-oriented.

-austin

 

[Jim Weirich]

Austin Ziegler said:

Is rdoc universally called via a .bat file on all windows installs? Is
this
likely to change? Do I need to be more aggresive in determining the
rdoc
command name?

Why not bypass the need for calling the batch file entirely?

def build_rdoc(files)
r = RDoc::RDoc.new
r.document(["--main", "README", "--title", "Diff::LCS -- A Diff
Algorithm",
"--line-numbers"] + files)
rescue RDoc::RDocError => e
$stderr.puts e.message
rescue Exception => e
$stderr.puts "Couldn't build RDoc documentation\n#{e.message}"
end

Also an excellent suggestiong. The #document method in the example, I
assume it takes all the standard command line arguments that RDoc accepts.
Correct?

Any gotchas in this approach?

 

[Dave Thomas]

Austin Ziegler said:

r = RDoc::RDoc.new
r.document(["--main", "README", "--title", "Diff::LCS -- A Diff

Also an excellent suggestiong. The #document method in the example, I
assume it takes all the standard command line arguments that RDoc
accepts.
Correct?

Yup - for normal use, it's just ARGV.

Any gotchas in this approach?

Only slight thing is you're vulnerable to API changes in RDoc, but its
unlikely to happen at that level.


Cheers

Dave