Hi Folks,
Is it intentional that 'ri' documentation is not provided for ruby-foo
packages? If so, what is the rationale?
I see that modules that are shipped with the 'libruby2.5' package have 'ri'
documenation shipped in the 'ruby2.5-doc' package. But it seems that other
'ruby-${libname}' packages have neither any 'ri' docs shipped as part of a
package, nor any generated at package installation time.
$ apt-file search '.ri' | grep -v -e '^ri1[.]9[.]1:' -e
'^ruby2[.][0-9]-doc:' | grep '[.]ri$' | wc -l
0
Because 'ri'[0] won't find documentation for the non-core ruby modules
installed on the system, doesn't that limit its out-of-the-box usefulness? I
found that it is easily (enough) worked around (see below), but was surprised
that it did not "just work" without having to manually build part of the
index.
I've been reading up[1] on it (some research notes below), but thus far
haven't found anything concrete. Before opening a wishlist bug I figured I'd
ask about it here.
Is there some other tool or approach folks use for reading the docs for
non-core Ruby modules?
Any insight much appreciated; thanks,
-Al
Notes
-----
In this example, the 'ri YAML' invocation works the way I would expect:
$ dpkg -S /usr/share/ri/2.5.0/system/YAML
ruby2.5-doc: /usr/share/ri/2.5.0/system/YAML
$ ri -l YAML
Classes and Modules starting with YAML:
YAML
YAML::DBM
YAML::Store
YAML::Syck
$ ri YAML
[ works, shows the content from
/usr/share/ri/2.5.0/system/YAML/cdesc-YAML.ri ]
However, the following was a surprise to me[2] in that 'ri' did not find the
documentation:
$ dpkg -S /usr/lib/ruby/vendor_ruby/text/levenshtein.rb
ruby-text: /usr/lib/ruby/vendor_ruby/text/levenshtein.rb
$ dpkg -l ruby-text | tail -n 1
ii ruby-text 1.3.0-1 all Collection of text algorithms
for Ruby
$ ri -l Text::Levenshtein
Classes and Modules starting with Text::Levenshtein:
[no other output]
$ ri Text::Levenshtein
Nothing known about Text::Levenshtein
I started looking into the issue. 'ri' told me it was looking for data in the
following directories:
$ ri2.5 --list-doc-dirs
/usr/share/ri/2.5.0/system
/usr/share/ri/2.5.0/site
/home/someuser/.rdoc
With a little more research, I found a workaround in manually kicking off the
generation of the ri documenation for content that packages have installed
beneath /usr/lib/ruby/vendor_ruby/, and then using the 'RI' environment
variable to augment the default list of paths[3]:
$ ( cd /usr/lib/ruby/vendor_ruby/ && rdoc --ri --op /tmp/aljunk-rdoc/ )
Parsing sources...
Couldn't find file to include 'README.rdoc' from minitest.rb
100% [3048/3048] zip/version.rb
Generating RI format into /tmp/aljunk-rdoc...
Files: 3048
Classes: 2979 ( 1635 undocumented)
Modules: 2133 ( 1641 undocumented)
Constants: 3755 ( 2852 undocumented)
Attributes: 3155 ( 1972 undocumented)
Methods: 19645 ( 9312 undocumented)
Total: 31667 (17412 undocumented)
45.02% documented
Elapsed: 49.4s
$ export RI='--doc-dir=/tmp/aljunk-rdoc'
$ ri2.5 --list-doc-dirs
/tmp/aljunk-rdoc
/usr/share/ri/2.5.0/system
/usr/share/ri/2.5.0/site
/home/ads/.rdoc
$ ri -l Text::Levenshtein
Classes and Modules starting with Text::Levenshtein:
Text::Levenshtein
$ ri Text::Levenshtein
[ works, shows the content from
/tmp/aljunk-rdoc/Text/Levenshtein/cdesc-Levenshtein.ri ]
My expectations may be off, however. Maybe there is a tool other than 'ri'
that most people use instead?
I know 'perldoc' and 'ri' are different programs serving different (though
partially overlapping) audiences, but I mention the following comparison
because it influenced my expectation of what the out-of-the-box behavior for
'ri' might be.
The 'perldoc' tool works for most (all?) perl modules installed as Debian
packages, regardless of whether or not they are part of the perl core. For
example, 'Carp' is a core module, with its documentation installed by the
'perl-doc' package. The 'perldoc' tool finds it:
$ perldoc -l Carp
/usr/share/perl/5.28/Carp.pod
$ readlink -f /usr/share/perl/5.28/Carp.pod
/usr/share/perl/5.28.1/Carp.pod
$ dpkg -S /usr/share/perl/5.28.1/Carp.pod
perl-doc: /usr/share/perl/5.28.1/Carp.pod
The Perl 'Text::Levenshtein' module is a non-core module, installed by the
'libtext-levenshtein-perl' package; 'perldoc' finds it, too:
$ perldoc -l Text::Levenshtein
/usr/share/perl5/Text/Levenshtein.pm
$ readlink -f /usr/share/perl5/Text/Levenshtein.pm
/usr/share/perl5/Text/Levenshtein.pm
$ dpkg -S /usr/share/perl5/Text/Levenshtein.pm
libtext-levenshtein-perl: /usr/share/perl5/Text/Levenshtein.pm
Moreover, the Perl modules also get registered in the '3pm' section of the
manpages index:
$ man -aw Carp
/usr/share/man/man3/Carp.3perl.gz
$ man -k carp
Carp (3perl) - alternative warn and die for modules
carp (4freebsd) - Common Address Redundancy Protocol
Carp::Clan (3pm) - Report errors from perspective of caller of a "clan"
o...
CGI::Carp (3pm) - CGI routines for writing to the HTTPD (or other)
error...
redcarpet (1) - Markdown prosessing like butterflies and popcorn
$ man -aw Text::Levenshtein
/usr/share/man/man3/Text::Levenshtein.3pm.gz
$ man -k levenshtein
Text::Levenshtein (3pm) - calculate the Levenshtein edit distance between
two...
That's extra nice, because 'man -aw foo' and 'man -k foo' are usually my first
stops when looking something up (not that it could be a full replacement
language-specific doc tools, though ('ri File#open', 'perldoc -f open', ...).
[0] For the sake of completeness, the 'ri' command used above is the 'ri2.5'
program as shipped with the 'ruby2.5' package:
$ type -P ri
/usr/bin/ri
$ ls -l /usr/bin/ri{,2.5}
lrwxrwxrwx 1 root root 5 2018-03-21 22:46:07 /usr/bin/ri -> ri2.5
-rwxr-xr-x 1 root root 187 2020-07-03 14:37:58 /usr/bin/ri2.5
$ dpkg -S /usr/bin/ri2.5
ruby2.5: /usr/bin/ri2.5
$ dpkg -l ruby2.5 | tail -n 1
ii ruby2.5 2.5.5-3+deb10u2 amd64 Interpreter of
object-oriented scripting language Ruby
[1] I read through the below wiki pages
https://wiki.debian.org/Teams/Ruby
https://wiki.debian.org/Teams/Ruby/Packaging
https://wiki.debian.org/Teams/Ruby/Packaging/Conventions
https://wiki.debian.org/Teams/Ruby/Packaging/gem2deb
https://wiki.debian.org/Teams/Ruby/RubyExtras/UpstreamDevelopers
https://wiki.debian.org/Teams/Ruby/RubyExtras/OnRubygems
The '.../Ruby/Packaging' page says:
<quote>
gem2deb can be considered to some extend [sic] as the reference
implementation of the Debian Ruby policy.
</quote>
Together with the fact that 'gem_installer.rb' from gem2deb is explicitly
using the '--no-ri' and '--no-rdoc' options (and since gem2deb commit
5718dcff16ba2bc4f918324af4ecae92492081b4 from 2019-12-20, '--no-document'),
the install-time behavior is deliberate. Is it intended to always be so?
Are there disk space concerns? Something else?
[2] For sure a very casual Ruby user.
[3] I did find in the rdoc2.5(1) manpage entries for the '--ri-site' and
'--ri-system' options, which I suppose might put the generated files into
one of the directories in which 'ri' searches by default. This was just an
experiment, though, and anyway it seems like a (hypothetical)
'--ri-vendor' option might make more sense as representing library content
installed beneath /usr/lib/ruby/vendor_ruby. It was not clear from the
manpage what precisely was meant by the phrases "a site-wide directory"
and "a system-level directory" used in the descriptions for those options.
