Re: boo-boo in run docs?

On 11/8/25 11:59 AM, Richard Hainsworth wrote:
> Hi Todd,
> 
> Long time since I responded to one of your questions. This thread seems 
> to have a lot in common, both in tone and approach, with other 
> assertions you have made.
> 
> I'm responding to the original post although I have read all the 
> responses by others.
> 
> First, lets look at the document in the url you posted. It clearly states:
> 
> run
> 
> Combined from primary sources listed below'
> 
> Although you have been accessing the docs website for many years now, it 
> seems that the structure of the website is not as transparent to you as 
> it should be. There are about 700 'primary' source pages, and some 1500 
> 'secondary' ones. The secondary pages are automatically generated every 
> time the website is built from the primary ones (about once every 2 
> hours - I think).
> 
> The reason for this is that quite a few methods are defined for many 
> classes (try searching for 'new'). They are each documented in the 
> primary sources for those classes, but naturally we want to see a single 
> page with all the references in one place. Hence the need for secondary 
> pages.
> 
> The documentation on 'run' is literally combined from other primary 
> sources. You can click on the link to 'independent routines', and in 
> that document is a link to the primary document on class 'Proc' (not 
> Pro, which you sometimes write).
> 
> Raku is quite different from some other languages in the way it handles 
> Objects. For example, 'run' as an independent routine, returns an object 
> of type 'Proc'. In the same way the fragment 'hello world' creates an 
> object of type Str. Hence 'my $v = "hello world" puts an object of type 
> Str into the variable $y.
> 
> Once the object is created, all the methods associated with that object 
> can now be used, so `say $v.tc` will output "Hello world". The method 
> `tc` is defined on Str objects, and $v contains a Str object.
> 
> In the same way, `my $proc = run <cat "my-file">` will run the program 
> cat with input 'my-file', and the object will be stored in $proc.
> 
> Now that $proc has a Proc object, the method 'exitcode' can be run on $proc.
> 
> So, 'exitcode' has nothing to do with the method 'run', and so should 
> not be included in the documentation for 'run'.
> 
> All the other methods that you noted (in subsequent posts) are 
> associated with class Proc and can therefore be run on an object of type 
> Proc.
> 
> They are not a part of or associated with 'run'.
> 
> This way of thinking about objects is fundamental to Raku and what gives 
> it a great deal of power. However, Raku is in a sense very modest, you 
> dont need to know about its power to use it for simple things.
> 
> I hope this helps you understand why there isn't a 'boo boo' in the 
> documentation, and why what others have said is actually answering the 
> question you asked.
> 
> Regards,
> 
> Richard (finanalyst)
> 


Hi Richard,

I under stand why it is done that way.  I just
do not like how it is done.

"run" return its results in the OOP class "Proc".
I wish the documentation would define what is
put into your Proc variable when "run" exits.
Not divide it up all over the place.

As you said, Raku does wonderful things for you,
so you do not have to know how everything works.
just trust that it does.

$proc.exit code is an example.  It contains the
exit code from the program you ran.  So
there is no need to rat pack it down somewhere
at the bottom of everything because under
the hood, Raku did it for you.

The doc's should just state what it does up front.
Down the road they can break things down
as to how.

This might seems a bit weird to you becasue
you are one of those experts stand out in your
field, but the docs need to be usable for
both your skill level and beginners like me too.

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