https://github.com/Raku/doc/issues/3753
> On 28 Dec 2020, at 16:23, Parrot Raiser <1parr...@gmail.com> wrote: > > 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 >> >>
