Update about.rakudoc (#4650) #1
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Change subtitle to remove the implication that contributing to Raku, beyond the documentation, is addressed.
…4653) * In pragmas.rakudoc, un-stub MONKEY-SEE-NO-EVIL and MONKEY-TYPING * In independent-routines.rakudoc, add comment that `use Test;` also activates pragma
…so comprise syllabic chars (#4654) the meaning of the character being "camel"
|
Meta query with this commit and/or PR as subject. My commit here seemed to be handled oddly by the easy-edit feature of the doc site. Previously all my doc-site-PRs have been just my edits alone. Bug or feature? |
…clarify some more (#4657) * In regexes.rakudoc, add <same> and <at(n)> * add link that clarifies <ident> * wrap + and - in C<…>, because the backslash in `\-` got shown Unicode set unions/differences are formed with `+` and `-`, never with a backslash before (verification: in roast, «- :» is used for set substraction [ripgrep command: rg '\- :'], whereas «\- :» never occurs [ripgrep command: rg '\\- :']) * remove rakudoc formatting in tables * properly indent table * add link to explanation of "FQN name"
"but not both" doesn't match what the example actually shows changed "either commas, or whitespace, but not both" to "whitespace, with or without commas"
…h';` (#4663) * add substution example `$str ~~ s[replace] = 'with';` Currently there's no substitution example involving balancing delimiters (brackets etc.) and operating on a named string variable. The behavior is intended, see e.g. this roast: https://github.com/Raku/roast/blob/b822369da22c305b84968acdb04328eeb3bd8947/S05-substitution/subst.t#L273 * add code preamble declaring $str * remove duplicate word "section" * "to the section Adverbs" --> "to the Adverbs section" * fix malformatted "OUTPUT" comment * fix code indentation (so far it renders as plain text) * slightly improve clarity and readability * further small stylistic changes * singular * change "parentheses" to singular "parenthesis" where single one is meant * correct the explanation for how the 24 iterations come about * Expand the iteration log (but for brevity keep only the relevant 2 lines per iteration; it should be transparent through the words and code that are above) * The current explanation for the number 24 is incorrect (based on a numerical coincidence; and where it says 'OUTPUT: «23»' the output is actually 22) * The correct explanation (as can be seen from the complete iteration log) is that 24 = 10 + 14 = (1+9)+(1+13), i.e. that first the 10 chars of " database!" get backtracked [down to 1, taking 10 trials total], and then the 13 chars of "SQL database!" get backtracked [down to 0, taking 14 trials total, with the last one a match] * whitespace * Correct extended backtracking example, making it about frugal quantifiers In the current line "say $string ~~ / (SQL) (.+) $1 /; # OUTPUT: «Nil»", positional capture group should have been $0 rather than $1. Changing it to $0 actually makes most of the supposedly failing examples (a) work and (b) non-informative because of that. What's missing so far though is an illustration of frugal quantifiers in the context of backtracking/ratcheting, so I've introduced some. (The subsequent subsection is more about frugal _ratcheting_ and mentions frugal quantifiers only briefly.) * add comments to example output, addressing whitespace * move the word "section" out of links everywhere
Clarify discussion of when subclasses can usefully inherit this method and when they should reimplement it instead.
Current code does not work because `$_` is the invocant of `.say` within the block. Pointy block variable must match outside/inside the block, and this pull request fixes the issue.
Update `for` code on control.rakudoc
... because it's not for the functionality
…4672) * In control.rakudoc, show how topicalization with `if` can be useful, and add reference to `with`. (The example is inspired by Bruce Gray's lecture 'Raku for Beginners Part 2' from TPRC 2023.) * remove 'else' from example, and improve text a bit
* regularized routine/sub/method headings in Mu.rakudoc * merged separate `take` & `defined` entries into routine take & routine defined * listing method before sub * move sub item from Any to Mu and merge with method item
…arators; some fixes here and there (#4669) * Complete overhaul of section on double semicolon (;;) parameter separator in file Language/signatures.rakudoc * Expand section Type captures (adding text on coercion and constraints). Also various fixes. * correct definition of subset Even, and adjust output * clarify explanation re. Nil/is-default * further clarify difference between parameters and variables with default values when assigned Nil * restore text that apparently was unintentionally deleted in 2024 with commit 348e623 * fix sentence relationship in section "Constraining signatures of Callables", and make examples more pertinent * skip test for failing code & align code * sigilled -> sigiled * add missing formatting code * fix Num -> Numeric * captured types can in fact be used as return types. +make spaces consistent * fix rakudoc syntax (C<->> to C«->») and add note to pod.rakudoc * add example for using captured type as return type constraint * add example combining capture with type smiley * add resulting signatures to examples * add link to explanation of itemization * Show how itemization prevents flattening in slurpies. Move section 'Type captures' up, and sections on slurpies down. * Moving section 'Type captures' up keeps the material on type constraints together. * Moving sections on slurpies down so that the more elementary section 'Positional vs. named arguments' appears first. * consistent usage of puntuation before examples * Add basic slurpies to introduction
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Change subtitle to remove the implication that contributing to Raku, beyond the documentation, is addressed. Reordered clauses to likely order of interest.