Skip Menu |
Report information
Id: 128048
Status: open
Priority: 0/
Queue: perl6

Owner: Nobody
Requestors: jkeenan <jkeenan [at] cpan.org>
Cc:
AdminCc:

Severity: (no value)
Tag: (no value)
Platform: (no value)
Patch Status: (no value)
VM: (no value)



Subject: Need command-line tool for reading embedded documentation
Download (untitled) / with headers
text/plain 1.8k
One of the joys of Perl 5 is that at the command-line I can issue a command like: ##### perldoc DBI ##### ... and get the author's documentation fed into a pager and highlighted in man-like style. Yesterday, I started using the 'DBIish' library which is bundled with Rakudo Star. https://github.com/perl6/DBIish states that I should be able to read the documentation with: ##### perl6 --doc <filename> ##### But that presumes I know (a) the basename of the file in which the documentation is found; and (b) the path to that file. Perl 5's 'perldoc' (at least in its simplest and most common usage) requires neither. It gets worse. If I go to the top-level directory for my Rakudo Star installation and search the tree for files with 'DBIish' in their names, I come up with nothing. That, I am told, is because the files are there only renamed with SHA1 hashes in their filenames. So I then have to ack or grep the tree and hope for the best. Eventually I came up with: ##### perl6 --doc share/perl6/site/sources/8B5538E93290C550228635C3FE5A7111890C4339 ##### ... which appears to show in the terminal the documentation found at https://github.com/perl6/DBIish/blob/master/lib/DBIish.pm6. Moreover, 'perl6 --doc <filename>' appears to neither page the documentation nor highlight it as 'man' and 'perldoc' do. Here, at least, I had the advantage that I knew that DBIish was bundled with Rakudo Star, so I could make a reasonable guess as to where to start searching within the file system. But I would have been considerably more lost if I had installed this library from CPAN (or wherever Perl6 libraries are housed -- I haven't gotten that far yet). As I noted in #perl6, this falls into the category of "barriers to adoption to the Perl6 language." Is there a plan to remedy the situation? Thank you very much. -- James E Keenan (jkeenan@cpan.org)
Download (untitled) / with headers
text/plain 2.4k
On Sun May 01 05:27:42 2016, jkeenan wrote: Show quoted text
> One of the joys of Perl 5 is that at the command-line I can issue a > command like: > > ##### > perldoc DBI > ##### > > ... and get the author's documentation fed into a pager and > highlighted in man-like style. > > Yesterday, I started using the 'DBIish' library which is bundled with > Rakudo Star. https://github.com/perl6/DBIish states that I should be > able to read the documentation with: > > ##### > perl6 --doc <filename> > ##### > > But that presumes I know (a) the basename of the file in which the > documentation is found; and (b) the path to that file. Perl 5's > 'perldoc' (at least in its simplest and most common usage) requires > neither. > > It gets worse. If I go to the top-level directory for my Rakudo Star > installation and search the tree for files with 'DBIish' in their > names, I come up with nothing. That, I am told, is because the files > are there only renamed with SHA1 hashes in their filenames. So I then > have to ack or grep the tree and hope for the best. Eventually I came > up with: > > ##### > perl6 --doc > share/perl6/site/sources/8B5538E93290C550228635C3FE5A7111890C4339 > ##### > > ... which appears to show in the terminal the documentation found at > https://github.com/perl6/DBIish/blob/master/lib/DBIish.pm6. Moreover, > 'perl6 --doc <filename>' appears to neither page the documentation nor > highlight it as 'man' and 'perldoc' do. > > Here, at least, I had the advantage that I knew that DBIish was > bundled with Rakudo Star, so I could make a reasonable guess as to > where to start searching within the file system. But I would have > been considerably more lost if I had installed this library from CPAN > (or wherever Perl6 libraries are housed -- I haven't gotten that far > yet). > > As I noted in #perl6, this falls into the category of "barriers to > adoption to the Perl6 language." > > Is there a plan to remedy the situation? > > Thank you very much.
Follow-up. I tried the following: ##### [rakudo-star] 25 $ perl6doc DBIish No command 'perl6doc' found, did you mean: Command 'perldoc' from package 'perl-doc' (main) Command 'perldoc' from package 'perl' (main) perl6doc: command not found ##### I had better luck with: ##### p6doc DBIish ##### ... which produced results similar to that of 'perl6 --doc <filename>' in the original post, i.e., output to STDOUT, unpaged, sans 'man' highlighting. So, partly this is a question of incorrect or misleading documentation. -- James E Keenan (jkeenan@cpan.org)
Download (untitled) / with headers
text/plain 1.6k
Show quoted text
> I had better luck with: > > ##### > p6doc DBIish > ##### > > ... which produced results similar to that of 'perl6 --doc <filename>' > in the original post, i.e., output to STDOUT, unpaged, sans 'man' > highlighting. > > So, partly this is a question of incorrect or misleading > documentation.
Synopsis 26[1] states that --doc should be capable of most of the things p6doc does now, one of them being capable of finding where a given module (like DBIish here) lives and display its Pod after parsing and formatting it. I see two courses of action here: 1) (proposed on IRC) -- deprecate --doc, possibly rename it to --renderpod and direct people to p6doc instead, since --doc is barely useful to them and quite misleading 2) (which I'll be in favour of) -- stick to original S26 ideas, and improve --doc so it's actually useful for end-users. We already have a precendent in rakudo for delegating some of the optional heavy-lifting-y stuff to modules: perl6-debug requires Debugger::Commandline::UI; --doc=HTML will ask the user to install Pod::To::HTML. I think it's a reasonable step to turn p6doc into this sort of 'second-degree core' module, where --doc will either work as it does now (generate pod from paths), or attempt to load p6doc and delegate work to it, optionally showing an error message that it needs to be installed for it to work. This way the core rakudo installation (the compiler itself) still gives you a usable --doc for your own development, while distributions like Star will ship p6doc with it and make --doc better, as it was originally intended. [1] https://design.perl6.org/S26.html#How_Pod_is_parsed_and_processed


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

For issues related to this RT instance (aka "perlbug"), please contact perlbug-admin at perl.org