I just went to the page at docs.raku.org on multi-line comments, to suggest a couple of clarifying edits. The pencil icon invoked a 404 from GitHub.
When one goes to make a fix, and the fixer is broken, it's a bit recursive. Can anyone cure problem #1, so I can get to step #2? :-)* On 12/28/20, Elizabeth Mattijsen <l...@dijkmat.nl> wrote: > ❤️ > >> On 28 Dec 2020, at 13:54, Richard Hainsworth <rnhainswo...@gmail.com> >> wrote: >> >> Todd, >> >> Some of what you have said in this email list over the years has been very >> valuable. You ask questions that get some very illuminating answers. I >> wrote a Module just for you (although I' still trying to get it to work on >> Windows) and it inspired me to look much more deeply at GTK::Simple, which >> I have just become the maintainer for. >> >> So please take what I say now as a plea for you to adapt a little, not to >> get pissed off with us even though you do seem to have pissed some of us >> off. >> >> You have very definite ideas about what the documentation should and >> shouldn't be. You have stated them over and over again. The Raku community >> at large - based on replies from multiple individuals over the years - >> disagrees with you. >> >> The Raku community has come to the concensus that there is a distinction >> between Tutorials and Reference, and that the Documentation site should >> contain both. Tutorials define how to use some aspect of Raku, with >> example text and explanation. Reference tries to cover as much of the >> language as possible, covering all the methods/subs/names/types etc as >> possible. Reference is written for a person who already knows how to >> program and who uses Raku. The assumption is that if a person reading a >> reference does not understand some term, then s/he will search in the >> documentation on that term to understand it. >> >> No set of documentation standards will please everyone - that's life. Even >> so, there ARE STILL areas of the Raku documentation that are lacking (just >> look at the issues on the Documentation repository, any of them raised by >> our indefatigable JJ). >> >> However, the balances between prolixity and brevity, examples and >> assumption of knowledge, exhibited in the Raku Documentation do by and >> large reflect a community consensus. >> >> It is polite in a community of rational human beings to accept what seems >> to be the general consensus, even if you do not agree with it. By >> continuing to demand your views about documentation should be accepted >> without any support from anyone else, is quite irritating. So please try >> to find a different way to express ways to improve the documentation that >> will not piss people off. >> >> You have suggested in this email list a variety of 'keepers', which seem >> to be the way you document your use of Raku. However, these 'keeper' texts >> are full of spelling mistakes, indicating you do not use a spell-checker, >> and also are ambiguous or technically wrong. Personally, I have not found >> your keepers to have been any use at all. But they may be useful to >> someone. Even worse, it is not possible for me to find a collection of >> your keepers because they are in posts to this email list, and I am not >> going to search through thousands of emails for your keepers on something >> whose keywords I would need to guess at. So the form you have made the >> keepers available is not easily accessible. >> >> In addition, the way the Raku community has evolved to work is to make >> changes to Documentation, whether Tutorials or Reference, by actually >> suggesting changes. If you look on the upper right of any primary document >> (the docs.raku.org site displays pages that are both automatically >> generated from primary documents, and the primary documents themselves - >> basically the documents referenced from the home page), you will see a >> Pencil icon. Click on that, and you will be taken to the github site and >> you can directly edit the document. The change is then submitted as a Pull >> Request, and it will be reviewed. If the change is seen to be reasonable, >> it is included. >> >> In this way, every single member of the Raku Community has the ability to >> make or suggest a contribution. >> >> However, a word of caution about human nature. If you go and try to >> completely change all the documentation to the way you want it, trashing >> everything that has already been contributed, it is extremely unlikely >> that your amendments will ever be accepted. Further, you run the risk that >> contributions with your name will never be considered by the Core >> Developers because they have rejected PRs you made before. >> >> Contribute in a way that enhances the Documentation, and your work will be >> praised. >> >> I hope whatever end of year, mid-winter or religious festival you >> celebrated was festive, even in our pandemic afflicted world, and I wish >> you a safe and productive CE 2021. >> >> Regards, >> >> Richard >> >> On 28/12/2020 11:55, ToddAndMargo via perl6-users wrote: >>> On 12/25/20 8:10 AM, Ralph Mellor wrote: >>>>> On 12/23/20 4:28 PM, Ralph Mellor wrote: >>>>> > If a method does not explicitly specify its invocant type, it is >>>>> set >>>>> > to the type of the enclosing class. >>>>> >>>>> But it does not specify an invocant. It just leaves it blank >>>> >>>> This is how it works in Raku source code. If there's no signature at >>>> all, >>>> or if the invocant is blank, or if the invocant's type is not specified, >>>> its >>>> type is the type of the class which encloses or composes the method >>>> (or `Mu` for a mainline `my` method). >> <snip> >>> >>> >>> Hi Ralph, >>> >>> What is used in the source code is written for a >>> purpose that is different from the documentation >>> in that the developers are expected to be freakin' >>> geniuses and know Raku like the back of the hand. >>> The source code is NOT meant to teach. >>> >>> If you have seem some of my other letters lately, you >>> know I have been grubbing around in the source code. >>> It can be rather enlightening. >>> >>> Now my technical opinion is that the documentation is >>> for a different purpose that the source code. It is >>> to teach those who are not freakin' geniuses. What >>> you seems to be telling me is that the two should >>> match. >>> >>> So basically if I knew what I was doing, I would know >>> all the defaults, and I could just use the source >>> code and would not need the documentation. >>> >>> The documentation need to show all the defaults. >>> The documentation's purpose should be to teach, >>> not to repeat the source code. >>> >>> -T > >
