RFE: dd in the docs

[ToddAndMargo]

Request for Enhancement: please add dd to the "routine" docs

https://docs.perl6.org/routine/dd
404: Page Not Found

Search does not work either

$ p6 'my Real $x; $x = 3.1415; dd $x;'
Rat $x = 3.1415

And in the description, please state why dd thinks a Real is a Rat

Many thanks,
-T

[JJ]

dd is not part of the language, but part of the implementation; that is, it's Rakudo-specific, not Perl 6-specific. #2057 specifically forbids from using it in the documentation, and as a matter of fact, it's not part of the test set (roast) either. All uses of dd were changed in #1680 . S

[JJ]

The Real vs. Rat issue is something completely different, and it has to do with the dynamics of assignment. First,

say 3.1416.^name;# OUTPUT: «Rat␤»

Then, Real is just a Role, it's not a class or Type. While $x is not a Real, it still does Real:

my Real $x := 3.1415;
say $x ~~ Real; # OUTPUT: «True␤»

You can use Roles to declare variables, but their class is not going to be changed.

[ToddAndMargo]

On 9/16/18 10:24 PM, Juan Julián Merelo Guervós wrote: |dd| is not part of the language, but part of the implementation; that is, it's Rakudo-specific, not Perl 6-specific. #2057 <#2057> specifically forbids from using it in the documentation, and as a matter of fact, it's not part of the test set (roast) either. All uses of |dd| were changed in #1680 <#1680> . S

Hi Juan, I got `dd` from Timo on the chat line. Timo is a genius lever developer who is extremely gracious with helping us beginner riff-raff. How was I suppose to know he was using something that wasn't real Perl? It was Timo! But that could be easily fixed by creating a special section in the docs for Rakudo extensions. Rakudo IS NOT going away. If you were to do so, us riff-raff would easily find it with the search function and know what was going on. `dd` would be a good place to start. Would you please consider reopening? Many thanks, -T

[JJ]

Thanks for taking this in good stride. No, Rakudo is not going away. yes, @timotimo is great. Yep, you can use it however you want.
But.
This repo is for "Perl 6" documentation. Not for "This implementation which is immensely popular, and, to be sincere, the only one". When there's no other way out than describing something that is Rakudo specific (say, when it's used for implementing some feature and is also user-facing) we take extreme care to make it very clear that it's Rakudo specific, so use it only under your responsability. In general, we would like Rakudo to implement their specific things, but they are not doing it: rakudo/rakudo#1941.
So see, this is not per se about dd. It's about documenting Rakudo specific features, which is totally not my turf. And even if it was, rules as I have pointed out are quite strict: don't. So I'm really sorry about this. If you want to reopen my issue in Rakudo, or open your own asking for documentation of Rakudo-specific routines and classes, I'll thumbs-up it, because that's something that is missing.

[AlexDaniel]

But dd is documented. Here: https://docs.perl6.org/programs/01-debugging#index-entry-dd

@ToddAndMargo is there any reason why you were looking at https://docs.perl6.org/routine/dd ?

You said that search does not work but it does for me, can you please double check?

[ToddAndMargo]

On 9/17/18 3:10 PM, Aleks-Daniel Jakimenko-Aleksejev wrote: But |dd| *is* documented. Here: https://docs.perl6.org/programs/01-debugging#index-entry-dd @ToddAndMargo <https://github.com/ToddAndMargo> what is there any reason why you were looking at https://docs.perl6.org/routine/dd ?

Because it is a routine. Also because it did not show in the search tool. And until you become familiar with it, no one will know it is a "debugging" function. If it is documented elsewhere, I would be happy if you put a remark to that in the routines: Suggested working: Dumper function see https://docs.perl6.org/programs/01-debugging#index-entry-dd That way it shows up in "routines" and is caught by the search function. And it keeps in mind that the reason folks are looking in the documents is because they don't know what they are doing and are trying to figure things out. You should never figure that folks already know what they are doing.

[zoffixznet]

is there any reason why you were looking at https://docs.perl6.org/routine/dd ?

FWIW, I always look up types and routines by just going to /routine/ or /type/ URLs directly. The perl6.party website even has markup shortcut for linking to docs that works on that assumption...

[ToddAndMargo]

On 9/19/18 5:37 PM, Zoffix Znet wrote: is there any reason why you were looking at https://docs.perl6.org/routine/dd ?

That is where I expect to find routines. The search tool is nice but sometimes can be overwhelming, especially when the term searched for is also a common term, such as "perl" or "contains". So, I just tack the routine name on the end of https://docs.perl6.org/routine/ Works pretty well, except this time. When I program, I have my code editor open, a run terminal, a test "one liner" terminal, and the manual open, usually with multiple tabs open. I make the RTFM (now called "just Google it") wish they had never coined the term.

[coke]

So, given that 'dd' is searchable, I think that's fine. There's another ticket (long open but I still hope we get there: #1099) about adding a server side search feature, which would let you do a real search for dd (or subs, or methods) without having to assume the structure of the website.

[ToddAndMargo]

On 9/21/18 11:02 AM, Will Coleda wrote: So, given that 'dd' is searchable, I think that's fine. There's another ticket (long open but I still hope we get there: #1099 <#1099>) about adding a server side search feature, which would let you do a real search for dd (or subs, or methods) without having to assume the structure of the website.

Hi Will, When I go to https://docs.perl6.org/routine.html and search, I get https://docs.perl6.org/type/X::Syntax::Comment::Embedded When I go to https://docs.perl6.org/ and search, I get a big drop down, with a lot of things with "dd" in it such as "add" an "additional", but no link to the "dd" routine. My suggestion of putting a reference/link to where "dd" is actually located in the "routines" section would solve this issue. Please consider reopening.

…

-T

[JJ]

It is open.

[coke]

BTW, When I search for dd, there is a response that is just dd. It's under the "Reference" section.

There are other search related tickets for improving the results of the search process; forcing dd to sit in a certain URL path is a very specific way to fix this issue; Improving the search mechanism is a much more generic way that will, I think, have a bigger positive impact.

[ToddAndMargo]

On 09/25/2018 09:30 AM, Will Coleda wrote: BTW, When I search for dd, there is a response that is just dd. It's under the "Reference" section. There are other search related tickets for improving the results of the search process; forcing dd to sit in a certain URL path is a very specific way to fix this issue; Improving the search mechanism is a much more generic way that will, I think, have a bigger positive impact.

Hi Will, The big issue here is how to get all the different camps to agree on a compromise. From my viewpoint, it is a "routine", so it belongs in Routines. Other's viewpoints is that is is a Rakudo Extension, so it belongs somewhere else, such as debugging. My viewpoint is that Rakudo is what everyone uses, so it should be catered to. If one does not want it is the "pure" Perl section, create a "Rakudo Extensions" section. Or, place a link to somewhere else in the regular routines section that says it is a Rakudo extension and can be found <here>. Other's think that because, with some effort, you can find dd eventually in the search functions, that nothing should be done. Right now dd resides in an "obscure" section called "Programs": https://docs.perl6.org/programs.html What is the world does the "Programs" sections have to do with a routine? So how do we come up with a compromise that makes everyone happy and that makes the routine easy to find? Everyone remember the term RTFM (Read The Freakin' Manual). Those seeking wisdom from the manuals have no idea what is and what is not "pure" Perl. The object is to make finding things in the manual "intuitive".

…

-T