Skip to content
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

Open
p6rt opened this issue May 1, 2016 · 4 comments
Open

Need command-line tool for reading embedded documentation #5288

p6rt opened this issue May 1, 2016 · 4 comments
Labels

Comments

@p6rt
Copy link

@p6rt p6rt commented May 1, 2016

Migrated from rt.perl.org#128048 (status was 'open')

Searchable as RT128048$

@p6rt
Copy link
Author

@p6rt p6rt commented May 1, 2016

From @jkeenan

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)

Loading

@p6rt
Copy link
Author

@p6rt p6rt commented May 1, 2016

From @jkeenan

On Sun May 01 05​:27​:42 2016, jkeenan wrote​:

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)

Loading

@p6rt
Copy link
Author

@p6rt p6rt commented May 1, 2016

From @tadzik

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

Loading

@p6rt
Copy link
Author

@p6rt p6rt commented May 1, 2016

The RT System itself - Status changed from 'new' to 'open'

Loading

@p6rt p6rt added the NYI label Jan 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
1 participant