Redefine / clarify purpose of examples
camstuart opened this issue · comments
See also @Altai-man's comment: #57 (comment)
The examples directory requires attention. I am in the process of bringing file extensions (see also #72) and shebangs inline with current Raku conventions. But further attention is required to tidy up these examples, and repair publishing.
At a high level, my view is the Raku/examples directory should:
- Make it easy for users to find (and execute) examples
- have a "real world" nature wherever possible, including some explanatory text
- Offer the community a place to contribute their valuable examples for others to benefit from
- Have strong ties (bi-directional links to) official Raku documentation (IE, see example and follow link to reference docs, or see reference docs and follow link back to examples)
Commencing with the cookbook:
I propose further cookbook style recipes that offer typical programming activities and how they might be solved in Raku. Including multi paradigm examples, and alternative approaches to achieve the same result to ensure the TIMTOWTDI mindset can continue to prosper.
Currently, the Raku/examples/cookbook is a "tip of the hat" back to the excellent Perl Cookbook.
This is fantastic for Perl 5's posterity and certainly something we should continue maintain, however it fails to showcase Raku's capabilities that make it a more modern language. For one example, concurrency. One area among others that most certainly should have multiple cookbook recipes.
TODO:
Continue to maintain and enhance the existing cookbook examples:
Test::Script::Output is designed to help with testing, but you might want to use anything else. I released that to test the examples in my "Perl 6 Quick Syntax Reference" book.
Hi, thanks for bringing some attention to this issue! I will now provide some "historical" context to the question.
Originally, since maybe last winter I was interested in re-vitalizing of this repo. There is an enchance/enhance (not sure if I did a typo there now) branch which has some cleanup and contains maybe half-finished porting to Cro done.
There was even a proposal made, https://gist.github.com/Altai-man/b0d23ec59c4a5bc32b2d5137cddf3bc9 <- this one.
However, some sane arguments were provided by AlexDaniel at https://colabti.org/irclogger/irclogger_log/raku-dev?date=2020-06-15#l37 <- please, read the whole conversation.
1)About "make examples be useful and tied with docs" <- why not just improve docs?
2)If a cookbook is needed, there is https://uzluisf.gitlab.io/raku-by-example/ <- just contribute to the repo, promote it, improve it?
There were also points made like those ones:
- (also, minor note: I don't think publishing euler problem solutions is a good idea, both because the euler people really don't like it when people do that, and because they're supposed to be puzzles you have to work out yourself)
- just looking at it briefly: 99 problems should be a single page, Rosettacode should simply be a link (or a set of links) to rosettacode, Cookbook is another single page, Euler should be removed according to ShimmerFairy, Rosalind is perhaps similar to Euler (I don't know), Tutorial section should be moved to Doc tutorials (we already have them), …
So in the end I just abandoned this idea and spent my resources on making a new UI for docs, which is for now WIP.
With all the above, I have no ideas on how to utilize this repo for the great good, really. "Make it source of new integration of tests" - everything should be in roast/rakudo. I would just archive it, but if anyone has some bright ideas on how to make it cool, that's inspiring and I can try to help with it.
Lol, yes a lot to take in!
@Altai-man & @JJ are you happy then if I work through this repo and do two things:
- Update as Raku and remove Perl6 stuff
- Ensure all code is working, documented, tested
We can discuss further in the background the future of this repo while I do that.
And then to @Altai-man's point, even if this gets archived, it is done so in a clean state.
If not, @JJ can either hand over, or work with me on CRO / deployment / hosting of the examples if we feel that is the appropriate path to take.
Update as Raku and remove Perl6 stuff
Feel free to steal work from enchance branch, it is already done there.
it is done so in a clean state.
Fair enough.
Where can I see example with a test covered, with good docs et cetera? So called example for create example (kha-ha).
@lenin1917 for what purpose?
As a reference, something like https://github.com/Raku/examples/blob/enchance/categories/parsers/CSSGrammar.raku plus https://github.com/Raku/examples/blob/enchance/t/categories/parsers/CSSGrammar.t
@Altai-man to know what you mean when you write about improving this repo.