Re: LTA documentation page

[Gianni Ceccarelli]

On 2021-01-06 yary  wrote:
> I have been going through quite a few contortions to look at the
> source code for installed modules in raku, and would very much like
> rakudoc to have an option similarly to perldoc -l showing the cached
> path and hashed local file names of installed modules.


zef does that::

   $ zef locate Zef
   ===> From Distribution: zef:ver<0.8.4>:auth:api<0>
   Zef => /home/dakkar/.raku/sources/65C34BD7E4A3F74D2F2637DFFF9507F33639635A

-- 
Dakkar - 
GPG public key fingerprint = A071 E618 DD2C 5901 9574
 6FE2 40EA 9883 7519 3F88
key id = 0x75193F88

Re: LTA documentation page

[yary]

In the Perl world, I use perldoc all the time to view the exact
documentation for the installed module I’m working with. And on a regular
basis, it’s useful for me to inspect the source code of the installed
modules.

I have been going through quite a few contortions to look at the source
code for installed modules in raku, and would very much like rakudoc to
have an option similarly to perldoc -l showing the cached path and hashed
local file names of installed modules.

On Wed, Jan 6, 2021 at 11:25 AM Richard Hainsworth 
wrote:

> We have a Google Summer of Code project to work on rakudoc, and the latest
> version of rakudoc points to "noisgul" 's repo.
>
> But ... rakudo aka p6doc was intended to work in the same way as perldoc.
>
> At the time the p6doc project was started, there was actually very little
> documentation, so most of the energy of people interested in documentation
> was on getting Perl 6 / Raku  documented. As projects evolved, the best way
> to access the documentation turned out to be via the website.
>
> Work on rakudoc languished because for most people, looking on line was
> easier and quicker than looking for installed modules.
>
> There REMAINS a need for a tool to look at the documentation associated
> with installed modules. That documentation exists if it is contained in the
> distribution that zef installs. As Vadim said Raku can robustly keep
> multiple versions of the same Module differing by version number and author
> fork. So in principle, if the Module is there, so is the documentation. But
> rakudoc does not access that information.
>
> So rakudoc does not do what you might think it should.
> On 05/01/2021 17:41, JJ Merelo wrote:
>
> Yep, there are a couple of (known) issues here:
> https://github.com/Raku/problem-solving/issues/252 which request to
> remove it from the ecosystem (and I'll probably do it when I finish this
> email), and this one https://github.com/Raku/doc/issues/2896 Build.pm
> does not really work now, to it should probably be removed. And if it is,
> there's actually nothing to "install" so it should be removed.
> Maybe we should work first on releasing rakudoc. Let me see if we can do
> that soon-ish or it requires a lot of work. And in any case we will
> probably encourage people to use the online version of the documentation
> (or to build it themselves via Documentable)
>
> Thanks anyways for the checks, cheers
>
> El mar, 5 ene 2021 a las 18:02, Gianni Ceccarelli ()
> escribió:
>
>> On 2021-01-05 William Michels via perl6-users 
>> wrote:
>> > Raiph's suggestion works for me (on rakudo-2020.10). I mean, p6doc
>> > installs
>>
>> Oh, that points to new, different, problems.
>>
>> https://modules.raku.org/search/?q=p6doc links to
>> https://github.com/Raku/doc which does not contain a ``p6doc`` script,
>> which means that what I get with ``zef install p6doc`` is not the same
>> thing (this is a general problem with pointing at repositories instead
>> of distribution artifacts, it's not specific to p6doc)
>>
>> Then, ``zef install p6doc`` fails here, because::
>>
>>   Failed to create directory '/usr/share/perl6/site/doc' with mode
>>   '0o777': Failed to mkdir: Permission denied
>>
>> AIUI, distributions should install to the CompUnit::Repository in my
>> home directory, not into the system-wide one.
>>
>> --
>> Dakkar - 
>> GPG public key fingerprint = A071 E618 DD2C 5901 9574
>>  6FE2 40EA 9883 7519 3F88
>> key id = 0x75193F88
>>
>>
>
> --
> JJ
>
> --
-y

Re: LTA documentation page

[Richard Hainsworth]

We have a Google Summer of Code project to work on rakudoc, and the 
latest version of rakudoc points to "noisgul" 's repo.


But ... rakudo aka p6doc was intended to work in the same way as perldoc.

At the time the p6doc project was started, there was actually very 
little documentation, so most of the energy of people interested in 
documentation was on getting Perl 6 / Raku documented. As projects 
evolved, the best way to access the documentation turned out to be via 
the website.


Work on rakudoc languished because for most people, looking on line was 
easier and quicker than looking for installed modules.


There REMAINS a need for a tool to look at the documentation associated 
with installed modules. That documentation exists if it is contained in 
the distribution that zef installs. As Vadim said Raku can robustly keep 
multiple versions of the same Module differing by version number and 
author fork. So in principle, if the Module is there, so is the 
documentation. But rakudoc does not access that information.


So rakudoc does not do what you might think it should.

On 05/01/2021 17:41, JJ Merelo wrote:
Yep, there are a couple of (known) issues here: 
https://github.com/Raku/problem-solving/issues/252 
 which request to 
remove it from the ecosystem (and I'll probably do it when I finish 
this email), and this one https://github.com/Raku/doc/issues/2896 
 Build.pm does not really 
work now, to it should probably be removed. And if it is, there's 
actually nothing to "install" so it should be removed.
Maybe we should work first on releasing rakudoc. Let me see if we can 
do that soon-ish or it requires a lot of work. And in any case we will 
probably encourage people to use the online version of the 
documentation (or to build it themselves via Documentable)


Thanks anyways for the checks, cheers

El mar, 5 ene 2021 a las 18:02, Gianni Ceccarelli 
(mailto:dak...@thenautilus.net>>) escribió:


On 2021-01-05 William Michels via perl6-users
mailto:perl6-users@perl.org>>
wrote:
> Raiph's suggestion works for me (on rakudo-2020.10). I mean, p6doc
> installs

Oh, that points to new, different, problems.

https://modules.raku.org/search/?q=p6doc
 links to
https://github.com/Raku/doc  which
does not contain a ``p6doc`` script,
which means that what I get with ``zef install p6doc`` is not the same
thing (this is a general problem with pointing at repositories instead
of distribution artifacts, it's not specific to p6doc)

Then, ``zef install p6doc`` fails here, because::

  Failed to create directory '/usr/share/perl6/site/doc' with mode
  '0o777': Failed to mkdir: Permission denied

AIUI, distributions should install to the CompUnit::Repository in my
home directory, not into the system-wide one.

-- 
        Dakkar - 

        GPG public key fingerprint = A071 E618 DD2C 5901 9574
                                     6FE2 40EA 9883 7519 3F88
                            key id = 0x75193F88



--
JJ

Re: LTA documentation page

[William Michels via perl6-users]

Can you try 'mkdir' manually beforehand to create the desired
'/usr/share/perl6/site/doc' directory, then run 'zef install p6doc' ?

Just wondering... . I note your other comments with great interest.

Best, Bill.

On Tue, Jan 5, 2021 at 9:02 AM Gianni Ceccarelli 
wrote:

> On 2021-01-05 William Michels via perl6-users 
> wrote:
> > Raiph's suggestion works for me (on rakudo-2020.10). I mean, p6doc
> > installs
>
> Oh, that points to new, different, problems.
>
> https://modules.raku.org/search/?q=p6doc links to
> https://github.com/Raku/doc which does not contain a ``p6doc`` script,
> which means that what I get with ``zef install p6doc`` is not the same
> thing (this is a general problem with pointing at repositories instead
> of distribution artifacts, it's not specific to p6doc)
>
> Then, ``zef install p6doc`` fails here, because::
>
>   Failed to create directory '/usr/share/perl6/site/doc' with mode
>   '0o777': Failed to mkdir: Permission denied
>
> AIUI, distributions should install to the CompUnit::Repository in my
> home directory, not into the system-wide one.
>
> --
> Dakkar - 
> GPG public key fingerprint = A071 E618 DD2C 5901 9574
>  6FE2 40EA 9883 7519 3F88
> key id = 0x75193F88
>
>

Re: LTA documentation page

[JJ Merelo]

Yep, there are a couple of (known) issues here:
https://github.com/Raku/problem-solving/issues/252 which request to remove
it from the ecosystem (and I'll probably do it when I finish this email),
and this one https://github.com/Raku/doc/issues/2896 Build.pm does not
really work now, to it should probably be removed. And if it is, there's
actually nothing to "install" so it should be removed.
Maybe we should work first on releasing rakudoc. Let me see if we can do
that soon-ish or it requires a lot of work. And in any case we will
probably encourage people to use the online version of the documentation
(or to build it themselves via Documentable)

Thanks anyways for the checks, cheers

El mar, 5 ene 2021 a las 18:02, Gianni Ceccarelli ()
escribió:

> On 2021-01-05 William Michels via perl6-users 
> wrote:
> > Raiph's suggestion works for me (on rakudo-2020.10). I mean, p6doc
> > installs
>
> Oh, that points to new, different, problems.
>
> https://modules.raku.org/search/?q=p6doc links to
> https://github.com/Raku/doc which does not contain a ``p6doc`` script,
> which means that what I get with ``zef install p6doc`` is not the same
> thing (this is a general problem with pointing at repositories instead
> of distribution artifacts, it's not specific to p6doc)
>
> Then, ``zef install p6doc`` fails here, because::
>
>   Failed to create directory '/usr/share/perl6/site/doc' with mode
>   '0o777': Failed to mkdir: Permission denied
>
> AIUI, distributions should install to the CompUnit::Repository in my
> home directory, not into the system-wide one.
>
> --
> Dakkar - 
> GPG public key fingerprint = A071 E618 DD2C 5901 9574
>  6FE2 40EA 9883 7519 3F88
> key id = 0x75193F88
>
>

-- 
JJ

Re: LTA documentation page

[Gianni Ceccarelli]

On 2021-01-05 William Michels via perl6-users 
wrote:
> Raiph's suggestion works for me (on rakudo-2020.10). I mean, p6doc
> installs

Oh, that points to new, different, problems.

https://modules.raku.org/search/?q=p6doc links to
https://github.com/Raku/doc which does not contain a ``p6doc`` script,
which means that what I get with ``zef install p6doc`` is not the same
thing (this is a general problem with pointing at repositories instead
of distribution artifacts, it's not specific to p6doc)

Then, ``zef install p6doc`` fails here, because::

  Failed to create directory '/usr/share/perl6/site/doc' with mode
  '0o777': Failed to mkdir: Permission denied

AIUI, distributions should install to the CompUnit::Repository in my
home directory, not into the system-wide one.

-- 
Dakkar - 
GPG public key fingerprint = A071 E618 DD2C 5901 9574
 6FE2 40EA 9883 7519 3F88
key id = 0x75193F88

Re: LTA documentation page

[William Michels via perl6-users]

On Tue, Jan 5, 2021 at 5:10 AM Ralph Mellor  wrote:
>
> I googled rakudoc and that led to:
>
> https://github.com/Raku/rakudoc
>
> which says it's forked from:
>
> https://github.com/noisegul/perl6-p6doc
>
> So I tried that in m.r.o and it's listed:
>
> https://modules.raku.org/search/?q=p6doc
>
> So, perhaps you can zef install p6doc?
>
> Maybe the doc you read mentioning rakudoc
> is ahead of the situation in rakudo versions, or
> at least yours, as well as being ahead of the
> ecosystem?
>
> love, raiph

Raiph's suggestion works for me (on rakudo-2020.10). I mean, p6doc installs:

Last login: Tue Jan  5 08:23:11 on ttys023
user@mbook:~$ ~/rakudo/rakudo-2020.10/zef/bin/zef install p6doc
===> Searching for: p6doc
===> Updating cpan mirror:
https://raw.githubusercontent.com/ugexe/Perl6-ecosystems/master/cpan1.json
===> Updating p6c mirror:
https://raw.githubusercontent.com/ugexe/Perl6-ecosystems/master/p6c1.json
===> Updated p6c mirror:
https://raw.githubusercontent.com/ugexe/Perl6-ecosystems/master/p6c1.json
===> Updated cpan mirror:
https://raw.githubusercontent.com/ugexe/Perl6-ecosystems/master/cpan1.json
===> Searching for missing dependencies: Pod::To::BigPage:ver<0.5.1+>
===> Searching for missing dependencies: HTTP::UserAgent, Test::When
===> Building: p6doc:ver<1.002001>
===> Building [OK] for p6doc:ver<1.002001>
===> Testing: HTTP::UserAgent:ver<1.1.51>:auth
[HTTP::UserAgent] # NETWORK_TESTING was not set
[HTTP::UserAgent] # NETWORK_TESTING was not set
[HTTP::UserAgent] # NETWORK_TESTING was not set
[HTTP::UserAgent] # NETWORK_TESTING was not set
[HTTP::UserAgent] # NETWORK_TESTING was not set
[HTTP::UserAgent] # NETWORK_TESTING was not set
===> Testing [OK] for HTTP::UserAgent:ver<1.1.51>:auth
===> Testing: Test::When:ver<1.001008>
===> Testing [OK] for Test::When:ver<1.001008>
===> Testing: Pod::To::BigPage:ver<0.5.2>:auth
===> Testing [OK] for Pod::To::BigPage:ver<0.5.2>:auth
===> Testing: p6doc:ver<1.002001>
===> Testing [OK] for p6doc:ver<1.002001>
===> Installing: HTTP::UserAgent:ver<1.1.51>:auth
===> Installing: Test::When:ver<1.001008>
===> Installing: Pod::To::BigPage:ver<0.5.2>:auth
===> Installing: p6doc:ver<1.002001>

2 bin/ scripts [pod2onepage p6doc] installed to:
/Users/me/rakudo/rakudo-2020.10/install/share/perl6/site/bin
user@mbook:~$

HTH, Bill.

Re: LTA documentation page

[Vadim Belman]

And here it comes again, the common mess about Raku and Rakudo. :)

The point is that Rakudo doesn't come bundled with documentation about Raku 
because the former just implements the latter. It's not like it is with perl 
where `perl` binary and `Perl` are the same and `perl -v` is your current 
version of Perl. From this point of view, one would have to know the difference 
between 6.d and 6.l version of Raku because these differences might be 
overwhelming. Even now it'd be good to know about the differences in role 
behavior between 6.c/6.d and 6.e.

Contrary, one is better not care about the differences between Rakudo 2019.10 
and 2020.12 for as long as they both implement same Raku versions. Apparently, 
I'm not talking about bug compatibility here. So, for as long as one's code 
always starts with `use v6.d` they really may not be worried about any upcoming 
Raku language version up until their compiler starts deprecation cycle for 6.d.

The task of the online documentation is to allow one to find out what version 
of Raku introduced a requested feature. We'll most certainly need a section 
related to versioning and have it pinned at some easy to spot location. And it 
will be there when our resources allow which must be read as: when somebody 
find time to do it. Any help is welcome! :)

Best regards,
Vadim Belman

> On Jan 5, 2021, at 9:48 AM, Gianni Ceccarelli  wrote:
> 
> On 2021-01-05 Brad Gilbert  wrote:
>> There really shouldn't be that much difference between what the
>> documentation says and how your version works.
> 
> I've worked on machines stuck with perl 5.8 when the online
> documentation was for 5.26
> 
> I'd like to live in a world where:
> 
> * raku is popular and widespread enough that you find old versions it
>  on old machines
> * I won't have to struggle to remember the differences between 6.d and
>  6.l
> 
> For now, yes, the online docs are "good enough" (when I have network
> connectivity, at least!)
> 
>> Even if rakudoc did install, it would just copy the most recent docs
>> as of the time you installed it.
> 
> rakudoc != p6doc
> 
> rakudoc looks at the POD6 in installed distributions / modules
> 
> -- 
>   Dakkar - 
>   GPG public key fingerprint = A071 E618 DD2C 5901 9574
>6FE2 40EA 9883 7519 3F88
>   key id = 0x75193F88
> 

Re: LTA documentation page

[Gianni Ceccarelli]

On 2021-01-05 Brad Gilbert  wrote:
> There really shouldn't be that much difference between what the
> documentation says and how your version works.

I've worked on machines stuck with perl 5.8 when the online
documentation was for 5.26

I'd like to live in a world where:

* raku is popular and widespread enough that you find old versions it
  on old machines
* I won't have to struggle to remember the differences between 6.d and
  6.l

For now, yes, the online docs are "good enough" (when I have network
connectivity, at least!)

> Even if rakudoc did install, it would just copy the most recent docs
> as of the time you installed it.

rakudoc != p6doc

rakudoc looks at the POD6 in installed distributions / modules

-- 
Dakkar - 
GPG public key fingerprint = A071 E618 DD2C 5901 9574
 6FE2 40EA 9883 7519 3F88
key id = 0x75193F88

Re: LTA documentation page

[Brad Gilbert]

There really shouldn't be that much difference between what the
documentation says and how your version works.

The biggest thing would be new functions that you don't have yet.
(Which you could just copy the code from the sources into your program if
you need them.)

Even if rakudoc did install, it would just copy the most recent docs as of
the time you installed it.

It's not like the Perl docs which are in the same repository as the code.
The Raku docs aren't even controlled by the same organization on
GitHub, let alone being in the same repository.
(There are different requirements to being in the different projects.)

On Tue, Jan 5, 2021 at 7:31 AM Gianni Ceccarelli 
wrote:

> On 2021-01-05 JJ Merelo  wrote:
> > Gianni is basically right. rakudoc has not really been released yet
> > into the ecosystem, and p6doc will get you the documentation itself,
> > which you will have to build then. So LTA is true, and there's some
> > work to be done. There's probably an issue already created, but it
> > will pop up if you create another one, so please do raise the issue
> > and focus it on the documentation part if it does not.
>
> https://github.com/Raku/doc/issues/3769
>
> > We really encourage people to peruse the documentation online, though.
> > https://docs.raku.org
>
> Why? The online documentation will not, in the general case, match the
> rakudo version I have installed.
>
> --
> Dakkar - 
> GPG public key fingerprint = A071 E618 DD2C 5901 9574
>  6FE2 40EA 9883 7519 3F88
> key id = 0x75193F88
>
>

Re: LTA documentation page

[Gianni Ceccarelli]

On 2021-01-05 JJ Merelo  wrote:
> Gianni is basically right. rakudoc has not really been released yet
> into the ecosystem, and p6doc will get you the documentation itself,
> which you will have to build then. So LTA is true, and there's some
> work to be done. There's probably an issue already created, but it
> will pop up if you create another one, so please do raise the issue
> and focus it on the documentation part if it does not.

https://github.com/Raku/doc/issues/3769

> We really encourage people to peruse the documentation online, though.
> https://docs.raku.org

Why? The online documentation will not, in the general case, match the
rakudo version I have installed.

-- 
Dakkar - 
GPG public key fingerprint = A071 E618 DD2C 5901 9574
 6FE2 40EA 9883 7519 3F88
key id = 0x75193F88

Re: LTA documentation page

[JJ Merelo]

Gianni is basically right. rakudoc has not really been released yet into
the ecosystem, and p6doc will get you the documentation itself, which you
will have to build then. So LTA is true, and there's some work to be done.
There's probably an issue already created, but it will pop up if you create
another one, so please do raise the issue and focus it on the documentation
part if it does not.

We really encourage people to peruse the documentation online, though.
https://docs.raku.org. If what you want is to check out the documentation
of installed modules... Well, as said above, work needs to be done.

El mar, 5 ene 2021 a las 14:10, Ralph Mellor ()
escribió:

> I googled rakudoc and that led to:
>
> https://github.com/Raku/rakudoc
>
> which says it's forked from:
>
> https://github.com/noisegul/perl6-p6doc
>
> So I tried that in m.r.o and it's listed:
>
> https://modules.raku.org/search/?q=p6doc
>
> So, perhaps you can zef install p6doc?
>
> Maybe the doc you read mentioning rakudoc
> is ahead of the situation in rakudo versions, or
> at least yours, as well as being ahead of the
> ecosystem?
>
> love, raiph
>


-- 
JJ

Re: LTA documentation page

[Ralph Mellor]

I googled rakudoc and that led to:

https://github.com/Raku/rakudoc

which says it's forked from:

https://github.com/noisegul/perl6-p6doc

So I tried that in m.r.o and it's listed:

https://modules.raku.org/search/?q=p6doc

So, perhaps you can zef install p6doc?

Maybe the doc you read mentioning rakudoc
is ahead of the situation in rakudo versions, or
at least yours, as well as being ahead of the
ecosystem?

love, raiph