P.R. submitted for step #2
On 12/28/20, Richard Hainsworth <rnhainswo...@gmail.com> wrote: > This seems to have been fixed already. > > The speed this problem was noted and fixed demonstrates (a) the > importance given to documentation, and (b) the diligence of JJ. > > Kudos to JJ and those who helped fix the problem. > > Richard > > On 28/12/2020 15:35, Elizabeth Mattijsen wrote: >> 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 >>>> >
