Re: boo-boo in run docs?

--000000000000171a4c064363913b
Content-Type: text/plain; charset="UTF-8"

On Sun, 9 Nov 2025, 04:27 ToddAndMargo via perl6-users, <
[email protected]> wrote:

> On 11/8/25 11:59 AM, Richard Hainsworth wrote:
> > Hi Todd,
> >
> > Long time since I responded to one of your questions.
>
Snip

>
> Hi Richard,
>
> I under stand why it is done that way.  I just
> do not like how it is done.
>
We all have our likes and dislikes.
I know you document things with your keepers. But to be honest the ones you
have published contain errors because they gloss over important topics.

For example in your next sentence:

>
> "run" return its results in the OOP class "Proc".
>
There is an error! 'run' does NOT return it's results in the OOP class
Proc!!!

'run' returns an object of type Proc. This is important because you can
have many objects but there is still only one class. And the difference
between type and class arises because (in Raku but not in many other
languages) you can add roles to an object which means it will do more than
just the methods of class Proc.

And that is precisely what methods are documented by class and not by the
routines which return objects of that class.

The whole point of the secondary files is to aid in finding relevant
information.

But that is also the reason for the functionality in the search button.

 I think everyone agrees that search and the website could be improved.

If you could find a way to suggest a systematic way of showing you how to
get the information you need in a more intuitive way, please let me know.

I'm writing a new version of the docs website. Take a look at
https://new-raku.finanayst.org

It looks a bit like the old one, but it works better on mobiles and tablets.

There are bugs in it still.

Currently I'm working on an upgrade to the RakuDoc Renderer, so the bugs
will be there for a bit.

However I really would like to have a better search function.

> I wish the documentation would define what is
> put into your Proc variable when "run" exits.
> Not divide it up all over the place.
>
> Snip
>
> And, I should not have to find the source code
> more readable and explanatory than the documents.
> And that should tell you something!
>
> Thank you for the well written letter.
> I appreciate it.
>
> -T
>
>
>

--000000000000171a4c064363913b
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"auto"><div><br><br><div class=3D"gmail_quote gmail_quote_contai=
ner"><div dir=3D"ltr" class=3D"gmail_attr">On Sun, 9 Nov 2025, 04:27 ToddAn=
dMargo via perl6-users, &lt;<a href=3D"mailto:[email protected]">perl6-u=
[email protected]</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" sty=
le=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 11/=
8/25 11:59 AM, Richard Hainsworth wrote:<br>
&gt; Hi Todd,<br>
&gt; <br>
&gt; Long time since I responded to one of your questions.=C2=A0<br></block=
quote></div></div><div dir=3D"auto">Snip</div><div dir=3D"auto"><div class=
=3D"gmail_quote gmail_quote_container"><blockquote class=3D"gmail_quote" st=
yle=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Hi Richard,<br>
<br>
I under stand why it is done that way.=C2=A0 I just<br>
do not like how it is done.<br></blockquote></div></div><div dir=3D"auto">W=
e all have our likes and dislikes.</div><div dir=3D"auto">I know you docume=
nt things with your keepers. But to be honest the ones you have published c=
ontain errors because they gloss over important topics.</div><div dir=3D"au=
to"><br></div><div dir=3D"auto">For example in your next sentence:</div><di=
v dir=3D"auto"><div class=3D"gmail_quote gmail_quote_container"><blockquote=
 class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc soli=
d;padding-left:1ex">
<br>
&quot;run&quot; return its results in the OOP class &quot;Proc&quot;.<br></=
blockquote></div></div><div dir=3D"auto">There is an error! &#39;run&#39; d=
oes NOT return it&#39;s results in the OOP class Proc!!!</div><div dir=3D"a=
uto"><br></div><div dir=3D"auto">&#39;run&#39; returns an object of type Pr=
oc. This is important because you can have many objects but there is still =
only one class. And the difference between type and class arises because (i=
n Raku but not in many other languages) you can add roles to an object whic=
h means it will do more than just the methods of class Proc.</div><div dir=
=3D"auto"><br></div><div dir=3D"auto">And that is precisely what methods ar=
e documented by class and not by the routines which return objects of that =
class.</div><div dir=3D"auto"><br></div><div dir=3D"auto">The whole point o=
f the secondary files is to aid in finding relevant information.</div><div =
dir=3D"auto"><br></div><div dir=3D"auto">But that is also the reason for th=
e functionality in the search button.</div><div dir=3D"auto"><br></div><div=
 dir=3D"auto">=C2=A0I think everyone agrees that search and the website cou=
ld be improved.=C2=A0</div><div dir=3D"auto"><br></div><div dir=3D"auto">If=
 you could find a way to suggest a systematic way of showing you how to get=
 the information you need in a more intuitive way, please let me know.</div=
><div dir=3D"auto"><br></div><div dir=3D"auto">I&#39;m writing a new versio=
n of the docs website. Take a look at <a href=3D"https://new-raku.finanayst=
.org">https://new-raku.finanayst.org</a></div><div dir=3D"auto"><br></div><=
div dir=3D"auto">It looks a bit like the old one, but it works better on mo=
biles and tablets.</div><div dir=3D"auto"><br></div><div dir=3D"auto">There=
 are bugs in it still.</div><div dir=3D"auto"><br></div><div dir=3D"auto">C=
urrently I&#39;m working on an upgrade to the RakuDoc Renderer, so the bugs=
 will be there for a bit.</div><div dir=3D"auto"><br></div><div dir=3D"auto=
">However I really would like to have a better search function.</div><div d=
ir=3D"auto"><div class=3D"gmail_quote gmail_quote_container"><blockquote cl=
ass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;p=
adding-left:1ex">
I wish the documentation would define what is<br>
put into your Proc variable when &quot;run&quot; exits.<br>
Not divide it up all over the place.<br><br>Snip<br>
<br>
And, I should not have to find the source code<br>
more readable and explanatory than the documents.<br>
And that should tell you something!<br>
<br>
Thank you for the well written letter.<br>
I appreciate it.<br>
<br>
-T<br>
<br>
<br>
</blockquote></div></div></div>

--000000000000171a4c064363913b--