ri bug -- might be Windows only

[Austin Ziegler]

I am preparing for a Diff::LCS 1.0.3 release because of a bug report
submitted. It's basically ready, but I want to be able to generate the
RI documentation, too. The problem is -- and this may be specific to
the Windows installer -- is that it looks like ri is not additive when
using ri --ri-site. I have my Ruby installed in c:\Apps\Ruby, and the
ri documentation is in c:\Apps\Ruby\share\ri\1.8\site. In Diff::LCS, I
have diff/lcs/array.rb that simply consists of :

require 'diff/lcs'

class Array
include Diff::LCS
end

This completely clears the existing ri documentation for Array when I do:

rdoc --ri-site --show-hash

I haven't yet added a comment, but I should for the HTML doc output,
so I don't want to add a #:nodoc: marker if I can avoid it

Is this broken in ri? Is this broken in the Windows installer only
(e.g., should the default be in --ri-system instead)?

As a note, when I changed the rdoc line to:

rdoc --ri-system --show-hash

I get:

ri Array

More than one class or module matched your request. You can refine
your search by asking for information on one of:

Array, Array

So it seems that this will break ri in any case. This seems suboptimal.

I don't have Ruby installed on anything *but* Windows right at the
moment (that will change, but not in the next three weeks , so I
can't verify this behaviour on non-Windows boxen.

-austin

 

[Dave Thomas]

This completely clears the existing ri documentation for Array when I
do:

rdoc --ri-site --show-hash

Did you use the --merge option?


Cheers

Dave

 

[Austin Ziegler]

------=_Part_48_15532205.1091990606662
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

Did you use the --merge option?

Not initially, but I think there's something broken here anyway.

1)
% rdoc --ri-site --merge bin\* lib\diff\lcs.rb lib\diff\lcs\*.rb

htmldiff: c
ldiff: mc.
lcs.rb: mmm......mc............
array.rb: c
block.rb: c...
callbacks.rb: cc...cc...c....c.....cc.
change.rb: c.........
event.rb: c.
hunk.rb: c............
string.rb: c

Generating RI...
You asked me to merge this source into existing
documentation. This file references a class or
module called HTMLDiff which I don't
have existing documentation for.

Perhaps you need to generate its documentation first.

Using the merge option means that I have to know which parts the
user may have generated in the past. I can manage this part -- it is
my project after all This will be important for authors of
package managers to be aware of, because I don't think that either
RubyGEMs or RPA currently offers a way to specify which items will
be merged and which items will be replaced. However, I'm not really
sure that this is the right way to do this.

I'm attaching a modification to rdoc/options.rb and
rdoc/generators/ri_generator.rb to add a --force-merge option which
will bypass the error mentioned. Since update_or_replace is called
in any case, this is a natural change. This should probably be the
default behaviour, but that's just my opinion.

With this change, I get the desired behaviour.

2) def build_ri(files)
ri = RDoc::RDoc.new
ri.document(%w{--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

Couldn't build Ri documentation
Unhandled special: Special: type=17, text="Computes"

When running ri programmatically with the above, I get the message
above. This applies for both --merge and --force-merge. Is there a
different way that I should be doing this programmatically? Is there
something special about the ri_generator when run this way, because
I don't get this error when running it through the rdoc binfile
(which uses the same pattern, more or less).

-austin
--
Austin Ziegler * (e-mail address removed)
* Alternate: (e-mail address removed)

------=_Part_48_15532205.1091990606662
Content-Type: application/octet-stream; name="options.rb.diff"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="options.rb.diff"

LS0tIHJkb2Ncb3B0aW9ucy5yYi5vbGQJMjAwNC0wNC0wNCAwMTowMzowMCBFYXN0ZXJuIFN0YW5k
YXJkIFRpbWUNCisrKyByZG9jXG9wdGlvbnMucmIJMjAwNC0wOC0wOCAxMzo1NjowOSBFYXN0ZXJu
IERheWxpZ2h0IFRpbWUNCg0KQEAgLTMxLDYgKzMxLDkgQEANCiAgICMgbWVyZ2UgaW50byBjbGFz
c2VzIG9mIHRoZSBuYW1lIG5hbWUgd2hlbiBnZW5lcmF0aW5nIHJpDQogICBhdHRyX3JlYWRlciA6
bWVyZ2UNCiANCisgICMgZm9yY2UgdGhlIG1lcmdlDQorICBhdHRyX3JlYWRlciA6Zm9yY2VfbWVy
Z2UNCisNCiAgICMgRG9uJ3QgZGlzcGxheSBwcm9ncmVzcyBhcyB3ZSBwcm9jZXNzIHRoZSBmaWxl
cw0KICAgYXR0cl9yZWFkZXIgOnF1aWV0DQogDQoNCkBAIC0xNjUsOCArMTY4LDEzIEBADQogDQog
ICAgICAgWyAiLS1tZXJnZSIsICAgICAgICAgIi1NIiwgICBuaWwsDQogICAgICAgICAid2hlbiBj
cmVhdGluZyByaSBvdXRwdXQsIG1lcmdlIHByb2Nlc3NlZCBjbGFzc2VzXG4iICsNCi0gICAgICAg
ICJpbnRvIHByZXZpb3VzbHkgZG9jdW1lbnRlZCBjbGFzc2VzIG9mIHRoZSBuYW1lIG5hbWUiXSwN
CisgICAgICAgICJpbnRvIHByZXZpb3VzbHkgZG9jdW1lbnRlZCBjbGFzc2VzIG9mIHRoZSBzYW1l
IG5hbWUiXSwNCiANCisgICAgICBbICItLWZvcmNlLW1lcmdlIiwgICAiLVoiLCAgIG5pbCwNCisg
ICAgICAgICJ3aGVuIGNyZWF0aW5nIHJpIG91dHB1dCwgbWVyZ2UgcHJvY2Vzc2VkIGNsYXNzZXNc
biIgKw0KKyAgICAgICAgImludG8gcHJldmlvdXNseSBkb2N1bWVudGVkIGNsYXNzZXMgb2YgdGhl
IHNhbWUgbmFtZVxuIiArDQorICAgICAgICAidGhpcyBvcHRpb24gd2lsbCBmb3JjZSB0aGUgbWVy
Z2UuIl0sDQorDQogICAgICAgWyAiLS1vbmUtZmlsZSIsICAgICAgIi0xIiwgICBuaWwsDQogICAg
ICAgICAicHV0IGFsbCB0aGUgb3V0cHV0IGludG8gYSBzaW5nbGUgZmlsZSIgXSwNCiANCkBAIC0z
OTEsNiArMzk5LDcgQEANCiAgICAgICAgIHdoZW4gIi0tbGluZS1udW1iZXJzIiAgdGhlbiBAaW5j
bHVkZV9saW5lX251bWJlcnMgPSB0cnVlDQogICAgICAgICB3aGVuICItLW1haW4iICAgICAgICAg
IHRoZW4gQG1haW5fcGFnZSAgICAgPSBhcmcNCiAgICAgICAgIHdoZW4gIi0tbWVyZ2UiICAgICAg
ICAgdGhlbiBAbWVyZ2UgICAgICAgICA9IHRydWUNCisgICAgICAgIHdoZW4gIi0tZm9yY2UtbWVy
Z2UiICAgdGhlbiBAbWVyZ2UsIEBmb3JjZV9tZXJnZSA9IHRydWUsIHRydWUNCiAgICAgICAgIHdo
ZW4gIi0tb25lLWZpbGUiICAgICAgdGhlbiBAYWxsX29uZV9maWxlICA9IHRydWUNCiAgICAgICAg
IHdoZW4gIi0tb3AiICAgICAgICAgICAgdGhlbiBAb3BfZGlyICAgICAgICA9IGFyZw0KICAgICAg
ICAgd2hlbiAiLS1vcG5hbWUiICAgICAgICB0aGVuIEBvcF9uYW1lICAgICAgID0gYXJnDQo=
------=_Part_48_15532205.1091990606662
Content-Type: application/octet-stream; name="ri_generator.rb.diff"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="ri_generator.rb.diff"

LS0tIHJkb2NcZ2VuZXJhdG9yc1xyaV9nZW5lcmF0b3IucmIub2xkCTIwMDQtMDEtMDIgMDE6MDE6
MTIgRWFzdGVybiBTdGFuZGFyZCBUaW1lDQorKysgcmRvY1xnZW5lcmF0b3JzXHJpX2dlbmVyYXRv
ci5yYgkyMDA0LTA4LTA4IDEzOjU3OjQ2IEVhc3Rlcm4gRGF5bGlnaHQgVGltZQ0KDQoNCkBAIC0y
MzQsMTkgKzIzNCwyMyBAQA0KICAgICBkZWYgdXBkYXRlX29yX3JlcGxhY2UoY2xzX2Rlc2MpDQog
ICAgICAgb2xkX2NscyA9IG5pbA0KIA0KLSAgICAgIGlmIEBvcHRpb25zLm1lcmdlDQorICAgICAg
aWYgQG9wdGlvbnMubWVyZ2Ugb3IgQG9wdGlvbnMuZm9yY2VfbWVyZ2UNCiAgICAgICAgIHJkciA9
IFJJOjpSaVJlYWRlci5uZXcoUkk6OlJpQ2FjaGUubmV3KEBvcHRpb25zLm9wX2RpcikpDQogDQog
ICAgICAgICBuYW1lc3BhY2UgPSByZHIudG9wX2xldmVsX25hbWVzcGFjZQ0KICAgICAgICAgbmFt
ZXNwYWNlID0gcmRyLmxvb2t1cF9uYW1lc3BhY2VfaW4oY2xzX2Rlc2MubmFtZSwgbmFtZXNwYWNl
KQ0KICAgICAgICAgaWYgbmFtZXNwYWNlLmVtcHR5Pw0KLSAgICAgICAgICAkc3RkZXJyLnB1dHMg
IllvdSBhc2tlZCBtZSB0byBtZXJnZSB0aGlzIHNvdXJjZSBpbnRvIGV4aXN0aW5nICINCi0gICAg
ICAgICAgJHN0ZGVyci5wdXRzICJkb2N1bWVudGF0aW9uLiBUaGlzIGZpbGUgcmVmZXJlbmNlcyBh
IGNsYXNzIG9yICINCi0gICAgICAgICAgJHN0ZGVyci5wdXRzICJtb2R1bGUgY2FsbGVkICN7Y2xz
X2Rlc2MubmFtZX0gd2hpY2ggSSBkb24ndCINCi0gICAgICAgICAgJHN0ZGVyci5wdXRzICJoYXZl
IGV4aXN0aW5nIGRvY3VtZW50YXRpb24gZm9yLiINCi0gICAgICAgICAgJHN0ZGVyci5wdXRzIA0K
LSAgICAgICAgICAkc3RkZXJyLnB1dHMgIlBlcmhhcHMgeW91IG5lZWQgdG8gZ2VuZXJhdGUgaXRz
IGRvY3VtZW50YXRpb24gZmlyc3QiDQotICAgICAgICAgIGV4aXQgMQ0KKyAgICAgICAgICB1bmxl
c3MgQG9wdGlvbnMuZm9yY2VfbWVyZ2UNCisgICAgICAgICAgICAkc3RkZXJyLnB1dHMgIllvdSBh
c2tlZCBtZSB0byBtZXJnZSB0aGlzIHNvdXJjZSBpbnRvIGV4aXN0aW5nICINCisgICAgICAgICAg
ICAkc3RkZXJyLnB1dHMgImRvY3VtZW50YXRpb24uIFRoaXMgZmlsZSByZWZlcmVuY2VzIGEgY2xh
c3Mgb3IgIg0KKyAgICAgICAgICAgICRzdGRlcnIucHV0cyAibW9kdWxlIGNhbGxlZCAje2Nsc19k
ZXNjLm5hbWV9IHdoaWNoIEkgZG9uJ3QiDQorICAgICAgICAgICAgJHN0ZGVyci5wdXRzICJoYXZl
IGV4aXN0aW5nIGRvY3VtZW50YXRpb24gZm9yLiINCisgICAgICAgICAgICAkc3RkZXJyLnB1dHMg
DQorICAgICAgICAgICAgJHN0ZGVyci5wdXRzICJQZXJoYXBzIHlvdSBuZWVkIHRvIGdlbmVyYXRl
IGl0cyBkb2N1bWVudGF0aW9uIGZpcnN0Ig0KKyAgICAgICAgICAgIGV4aXQgMQ0KKyAgICAgICAg
ICBlbHNlDQorICAgICAgICAgICAgb2xkX2NscyA9IG5pbA0KKyAgICAgICAgICBlbmQNCiAgICAg
ICAgIGVsc2UNCiAgICAgICAgICAgb2xkX2NscyA9IG5hbWVzcGFjZVswXQ0KICAgICAgICAgZW5k
DQo=
------=_Part_48_15532205.1091990606662--

 

[Mauricio Fernández]

Using the merge option means that I have to know which parts the
user may have generated in the past. I can manage this part -- it is
my project after all This will be important for authors of
package managers to be aware of, because I don't think that either
RubyGEMs or RPA currently offers a way to specify which items will

The modified ri distributed via rpa-base (ri-rpa) isolates completely the
documentation from different ports (libs) and is therefore not affected
by this issue; e.g. if you do

$ rpa install diff-lcs

then you can

$ ri-rpa -p diff-lcs Array
(...)
Includes:
---------
Diff::LCS(diff, lcs, patch, sdiff, traverse_balanced,
traverse_sequences)

I have to say that this is clearly suboptimal (and I do not like it
either) and I will soon work on a more general solution to the problem
(intelligent merging with "subviews").