quasi does not get a lot of documentation

[JJ]

Problem or new feature

quasi does not get its own entry in the reference, and barely a few words in the macro documentation. We don't know, for instance, it needs a "scoped block" (#4079) or what kind of arguments it has

Suggestions

Improve macro documentation, or give quasi its own page (or create one for experimental features)

[raiph]

1. Aiui quasi (and macros in general) are like harmless zombies, not remotely close to being worthy of documentation, nor the effort of deprecation or removal except as part of point 2.

2. Aiui it is reasonable to hope that macros and quasi (or some other paint) will become non-experimental at some point in the next 1-3 years as part of the RakuAST work.

3. Per this line of code, a "scoped block" is, syntactically speaking, a code block (cf the type Block and code of the form { ... }).

4. Semantically speaking, a quasi block is not a Block. It might be a sub class implementation-wise (in the experimental code and/or the hopefully upcoming non-experimental code per point 2), but just as likely won't be given that it is a fundamentally different beast in at least one respect, and perhaps a second one. The definite difference is that, in the general case, it's a template of code that allows some fragments to be substituted in. The possible additional difference is that, aiui, the braces might not always establish a lexical scope (i.e. the "scoped block" is, aiui, quite possibly entirely misleading). Aiui this latter possible difference depends on how folk decide to handle "hygienic" vs "non-hygienic" macros.

5. As a bikeshed paint point, I hope to persuade Rakoons to consider choosing a better word than quasi (when the time is right, which I'm presuming will be when RakuAST is much further along). I don't think this issue is the right place and time to detail the excellent rationale I've seen Carl Masak and others provide for using the word quasi, nor the ones I see for not using it. Instead I will just note that, aiui, a quasi returns a fragment of AST (which is compiled from the "block" that follows the keyword), or perhaps some variant of an AST that is a template of AST; and the word I have mentally penciled in as a strawman proprosal is ToAST, short for either to AST or Template of AST.