language/control and language/statement-prefixes cross contaminate

[0rir]

1. Statement Prefixes is a misleading name since all of the prefixes apply to Blocks.
2. There are three categories of controllers on these pages: a) execution flow, b) message flow, and c) execution modifier.
3. The docs for quietly should merged into Prefixes.
4. The docs for try, do, sink, once, start, gather, react, and supply should be consolidated to Control Flow.

[Altai-man]

That's a nice one! Thank you very much.

Statement Prefixes is a misleading name since all of the prefixes apply to Blocks.

Should it be removed / renamed?

[0rir]

The distinction of taking a block and/or statement is not worth splitting the documentation of any one of these words onto two pages.

So I suggest renaming it 'Pragmatic Prefixes' and leaving only lazy, eager, hyper, race, and quietly on that page. The effect of these keywords is practical and interfering which matches the English meaning; and that effect also echos well that of 'pragmas'.

[0rir]

I suggest "Prefixes", the only other Raku use seems to be in creating operators. I don't see that as confusing, though document index entries might need a extra word.

An amendment because I just suffered for believing the "statement prefix" tag. I liked "Code Prefixes" but worried that the Code-type implication is not correct (my ignorance about that class is great).

lazy my @seq = 0 ... 1_000_000_000_000; is probably unwanted enough to warrant a compile time warning. It is clear that my @seq = lazy 0...$x; is using lazy in a statement.
Lacking discouragement, I will submit an issue for this.

And, as a starting point, I volunteer to merge the two pages while conserving their current meanings.

[Altai-man]

And, as a starting point, I volunteer to merge the two pages while conserving their current meanings.

If you can tweak the search categories in this area, welcome! This will be a great help.

[raiph]

lazy ...; is probably unwanted enough to warrant a compile time warning. ... Lacking discouragement, I will submit an issue for this.

I presume that should always have raised a compile time sink warning. But, as I once wrote in an SO answer:

My suspicion is that someone needs to clean the kitchen sink, i.e. pick up where Zoffix left off with his Flaws in implied sinkage / &unwanted helper issue.

(I've added a comment to that issue linking to another SO answer with more links.)

In short, the Sink handling in the current front end is full of holes.

A couple years ago jnthn said he expected RakuAST to make solving this intricate problem much easier.

(If you were wondering about some role you could play in polishing RakuAST, one that would give you a rich, small-bite-at-a-time-sized payoff in both contributing to Raku(do) and accelerating your learning of it, I imagine focusing on polishing sink handling using RakuAST might be just the ticket.)

In sum, I think filing an issue for this is moot and would be unhelpful make-work more than anything useful; whereas I'm pretty sure that working on sink handling post RakuAST merge would be helpful make-better.

(Just my 2c. And if you prefer to file an issue because you plan on being the one to have the fun of closing it, ie you intend it to be make-fun rather than make-work, well I'd say that's tickety-boo.)

[0rir]

@raiph, thanks. I'll take that as discouragement; and so will not submit a redundant issue.

And also thanks for the encouragement to nibble at the new AST. I will take a look at it, but I will still focus on learning the LOW. That is proving to be ample fun.

@Altai-man, I am taking your 'tweak the search' as an approval of my intention. I agree that chasing down the links is important.
That chasing will take some time. I would also try to fill any related holes in the glossary, but those can be independent PRs.

Let me know if this will have any procedural differences from a small, one-and-done patch.

[raiph]

What's LOW?

[0rir]

The Lower Order Workings of Raku.

[Altai-man]

I am taking your 'tweak the search' as an approval of my intention

Sure. We had a pretty hard time to establish the need for categorizing things in search in the first place, and I did the heavy-lifting to some degree, but I'm very far from being someone who does think deep about languages, so improvements are surely encouraged.

Let me know if this will have any procedural differences from a small, one-and-done patch

+1

[0rir]

I have a 'issue.txt' of 2754 words describing my intentions and concerns regarding fixing this issue. I am willing to put that here,
or as a comment to the PR. But...

It touches upon a few tangential issues which may be moot by being road-mapped or as a matter of policy or procedure. So rather than possibly provoke useless discussion and waste other's time, I would take pointers to the road-map, procedural guide, policy statement and/or some insider's discreet advice. That is fishing for help, but getting some coarse 'that is just not going to fly' feedback might be more efficient for all.

I also have a branch, with the consolidation of a few of words.

[Altai-man]

It touches upon a few tangential issues which may be moot by being road-mapped or as a matter of policy or procedure

There is no way for me (or someone else) to guess what do you have in mind without explicitly stating it, so if you already have the text, it would help if you can post it.

As for the roadmap: I was the one who designed/implemented those categories according to my understanding. It's a very long story, the starter discussion is #1410
Then the document is https://github.com/Raku/problem-solving/blob/master/solutions/documentation/search-categories.md

What you might find interesting is maybe this section: https://github.com/Raku/problem-solving/blob/master/solutions/documentation/search-categories.md#appendix-b-updates-to-the-list-of-supported-search-term-categories

I think there are not so many people who maintain the website, so matters like this one can be discussed openly and make into living as is, based on just the agreement of those concerned.

[0rir]

This is to address the LTA inclusion, based on syntactic position, of "keywords" in both statement_prefixes.pod6 and control.pod6. The basis of this sorting is not consistently defined and the duplication is not helpful.

Actions for a fix (not in any real order):

A) Merge or move sections:
     Control Flow         Statement Prefix
        quietly     -->  quietly
                    <--  try
                    ?-?  do
                    ?-?  sink
        once        <--  once
        gather/take <--  gather
        start       <--  start
                    <--  react
        supply/emit <--  supply

B) Revise the combined text to maintain readability.

C) Rename "Statement Prefixes" so it names its content as a group
    by a semantic commonality instead of by syntactical position;
    I assume the filename will need changing to match the top
    heading/link.

D) Correct the links that get broken.

Expanding on the above.

Regarding the name 'Statement Prefix', now my preference is for a name with the meaning of 'pragma' but I see 'pragma' as unavailable. I have a mostly unsatisfying list of words meaning 'modifier' (which heads the list). I'll keep those to myself so anyone may freshly brainstorm names.

Pragma, implies 'interfering', and what I intend to leave in the prefix file interferes in a like manner. Branching words belong in control flow.

So lazy, eager, hyper, race belong with modifiers as a programmer's sense of the branching doesn't much change with their presence.

Whereas, supply, react, start, gather, once and try all equate to a traditional conditional jumps or, loosely, a specialized set of them.

do and sink seem the odd cases. do traditionally is a control word, but grouping or otherwise packaging some code to be runnable is a syntactical wedge, not a branching. So there is roughly fifty years of tradition, fifty years of hindsight, massive memory expansion, and roughly 100 years of future to consider.

sink seems much easier to put with the prefixes. It announces what is so often implied.

[0rir]

Since hyper and race are prefixes only applicable to for, I am indexing them under control 'for'.
And 'try' should be consolidated from statement_prefixes to exceptions. I'll create an issue sometime.