New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Need command-line tool for reading embedded documentation #5288
Comments
From @jkeenanOne of the joys of Perl 5 is that at the command-line I can issue a command like: ##### ... 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: ##### 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: ##### ... 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. -- |
From @jkeenanOn Sun May 01 05:27:42 2016, jkeenan wrote:
Follow-up. I tried the following: ##### I had better luck with: ##### ... 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. -- |
From @tadzik
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 |
The RT System itself - Status changed from 'new' to 'open' |
Migrated from rt.perl.org#128048 (status was 'open')
Searchable as RT128048$
The text was updated successfully, but these errors were encountered: