Re: No. It is lucid! Re: Could this be any more obscure?
On 10/2/18 9:02 PM, Richard Hainsworth wrote: The Perl6 community is warm, generous, and intellectually inspiring. Those virtues should be defended against unseemly and intemperate language. Calling a documentation writer a 'jerk' is wrong. Agreed. They are very much so. And since you are a native English speaker, you know there is a difference between calling someone a jerk for lording it over the recipient that he knows more than you do and me calling anyone on the Perl 6 community a jerk. I was criticizing a writing style, not the Perl 6 community. That you thought I had I had done that is beyond me.
Re: No. It is lucid! Re: Could this be any more obscure?
This could only too easily become a flame war, so I am replying once and will not answer again unless it is about substance. The Perl6 community is warm, generous, and intellectually inspiring. Those virtues should be defended against unseemly and intemperate language. Calling a documentation writer a 'jerk' is wrong. On 03/10/18 07:40, ToddAndMargo wrote: On 9/30/18 9:11 PM, Richard Hainsworth wrote: But I thought you just implied you wanted pro stuff, not beginner stuff. I have no idea how you got that out of what I said. I want the beginners stuff included with the pro stuff. Yes the best of all worlds, and it must be short. Demand the impossible and complain when it does not happen. There are a number of people trying very hard to balance the contradictions of writing documentation. We need to support them and offer constructive suggestions. Clearly my post was wrong because you did not *think* about what I said, only reacted negatively to my British sense of humour. So what is wanted is 'common user' stuff (see below). You are mixing socialist political terms with what I am stating. By "common user" I mean a typical user. The term was meant to differentiate typical users from experts. Where did 'socialist' come from? You said 'common user' and I was trying to elicit from you what it meant. But as it happens I do not think that 'socialist' is a negative word, and for many people it means an emphasis on society and community (as in this very valuable Perl6 community) rather than on solitary individuals. Actually, I do not understand what you are saying at all, eg., 'I have know how to use ...' is not clear. Again, I have no idea how you got that out of what I said. I quoted your words from your post. They are in quotes. Your use of English grammar is not standard, and consequently it is ambiguous. When I use a function all the time, I know who to use the you know 'who to use' or 'how to use'? It would be useful for you to read what you have written for mistakes before clicking on the 'send' button. That way, other people can understand you better. function. The problem was that I could not reverse engineer the documentation. In other words, I figured out how to use the function from other sources than the documentation. Had I used the documentation, I never would have figured it out. That is the issue. This use of 'reverse engineer' is obscure. But if you mean that you had to read around a bit in order to understand, I suggest that this is quite a normal intellectual activity. That is why repeatedly it has been suggested that you read a book. But I am confused about what *you* want from the reference documentation. I think maybe there is a translation issue between your native language and mine. I have been very clear what I am after, so I won't repeat it yet again. My native language is English. I was born to English parents, went to school in Leeds, went to University in London, studied computer science and economics in Birmingham, spent 20 years editing and translating into English from Russian in Moscow. I speak and write Russian, and I am learning Cantonese. I do get it: you are following the example of the current crop of political leaders in the US. When someone demonstrates - as I did in the previous post, and in this one - that your English grammar and spelling are slovenly, you throw back the criticism as if I am guilty of the same, and charge that my native language is not English. So no it is not a translation issue. What you want is not clear because (a) you do not write clearly, (b) you ask for different things at different times, (c) you assume that the world is predominantly the same as you, when it is not. 3) when calling other term to explain things, it should pick the easiest term available. It should not pick any nasty, advanced terms. (Unless the writer enjoys confusing the reader and bragging about how smart he is. And he is a jerk.) This does not seem to be correct English. You are again missing the point. It is wonderful if the writer wants to share an interesting, complex way of doing things. But only AFTER he explains it in is simple terms. You don't share a calculus equation with someone until after you teach them the fundamentals of arithmetic. I did not miss the point. You deleted the part of my response where I agreed that there should be simple examples. You also deleted the part where I pointed out that calling someone a 'jerk' is not polite. It is possible to get carried away by beauty and elegance and forget the need to start with simple things. That might make the explanation cryptic; it does not make them a jerk. We come again to this category: 'the common user'. This person (possibly there are more) is not a 'beginner' nor a 'pro'. What is to be expected of a 'common user' of perl6? Can we assume that a 'common user' has read an introduction to
Re: No. It is lucid! Re: Could this be any more obscure?
On 9/30/18 9:11 PM, Richard Hainsworth wrote: But I thought you just implied you wanted pro stuff, not beginner stuff. I have no idea how you got that out of what I said. I want the beginners stuff included with the pro stuff. So what is wanted is 'common user' stuff (see below). You are mixing socialist political terms with what I am stating. By "common user" I mean a typical user. The term was meant to differentiate typical users from experts. Actually, I do not understand what you are saying at all, eg., 'I have know how to use ...' is not clear. Again, I have no idea how you got that out of what I said. When I use a function all the time, I know who to use the function. The problem was that I could not reverse engineer the documentation. In other words, I figured out how to use the function from other sources than the documentation. Had I used the documentation, I never would have figured it out. That is the issue. But I am confused about what *you* want from the reference documentation. I think maybe there is a translation issue between your native language and mine. I have been very clear what I am after, so I won't repeat it yet again. 3) when calling other term to explain things, it should pick the easiest term available. It should not pick any nasty, advanced terms. (Unless the writer enjoys confusing the reader and bragging about how smart he is. And he is a jerk.) This does not seem to be correct English. You are again missing the point. It is wonderful if the writer wants to share an interesting, complex way of doing things. But only AFTER he explains it in is simple terms. You don't share a calculus equation with someone until after you teach them the fundamentals of arithmetic. We come again to this category: 'the common user'. This person (possibly there are more) is not a 'beginner' nor a 'pro'. What is to be expected of a 'common user' of perl6? Can we assume that a 'common user' has read an introduction to perl6? You are mixing socialist political terms with what I am saying again. Perl 5's perldoc did a wonderful job of this. I never liked perldoc. 'To whom how', as they say in Russian. I find perldocs from the command line a total pain in the butt. Fortunately, it is repeated on web beautifully. I have been posting RFE about this as they come up. So I am trying to be part of the solution instead of constantly gripping about the problem. Indeed this discussion has, at times, been gripping, but I hope you don't think I have been griping. ;) I think that there is a translation and maybe a cultural difference that has lead you to misconstrue my statements. That or you are just trying to pick a fight. Your "buffoon in the White House" statement is definitely trying to pick a fight.
Re: No. It is lucid! Re: Could this be any more obscure?
On 10/1/18 4:17 PM, Brandon Allbery wrote: That just sounds like the backing store got restored from backup, losing anything added after the backup was taken. Which is not the best way to do things (incrementals are nice), but if things had gone wrong enough might have been the best they could do. That does sound very plausible.
Re: No. It is lucid! Re: Could this be any more obscure?
That just sounds like the backing store got restored from backup, losing anything added after the backup was taken. Which is not the best way to do things (incrementals are nice), but if things had gone wrong enough might have been the best they could do. On Mon, Oct 1, 2018 at 7:13 PM ToddAndMargo wrote: > On 9/30/18 9:11 PM, Richard Hainsworth wrote: > > your 'perl' box was corrupted. > > > Somewhere the imap daemons got appeased and suddenly a day later, > I watched it all come blazing back. > > Hopefully tomorrow I will get a chance to read over what yo wrote. > > By the way, the eMail I send about the thread disappearing > got removed when the rest came back. Hmm > -- brandon s allbery kf8nh allber...@gmail.com
Re: No. It is lucid! Re: Could this be any more obscure?
On 9/30/18 9:11 PM, Richard Hainsworth wrote: your 'perl' box was corrupted. Somewhere the imap daemons got appeased and suddenly a day later, I watched it all come blazing back. Hopefully tomorrow I will get a chance to read over what yo wrote. By the way, the eMail I send about the thread disappearing got removed when the rest came back. Hmm
No. It is lucid! Re: Could this be any more obscure?
Todd, I've already added to this conversation given that your 'perl' box was corrupted. But when I read this post last week, I felt it needed some response. You actually have touched on some deep issues. Please allow for some humour below. First off, courses, beginners books, and the likes, do not work for me. So you do not want to read beginners' stuff, just the stuff real pros want. What does work is just code what my customers and I need. And a lot of what do is to Read The Freakin' Manual (RTFM, now-a-days called "just Google it"). Read the manual. Got it. I do that a lot for many languages, eg. php, css, html. Actually, the manuals for css and html are bloody awful. Much better are tutorial sites. So the problem of documenting something complex in a balanced way is not unique to perl6, and it is a deep issue. The Perl 6 routine's documentation is written as a refresher to those how already know what they are doing, and as such is pretty useless to common users seeking wisdom. But I thought you just implied you wanted pro stuff, not beginner stuff. So what is wanted is 'common user' stuff (see below). Why even post it to the general public? The design specifications and not posted (except if you Google them). This is a misrepresentation of reality. Larry wrote about the 'whirlpool' rather than 'waterfall' concept of development. Perl6 was not written to specs, rather the specs and the language and the tests (considered a part of the specs) have co-evolved. There is a link to them on the main perl6.org page, but the documents are historical, not prescriptive. And so the links to them are not given prominence, so as not to confuse the commoner, as it were. *** I am not after the manual to teach me how to use Perl. *** Well I agree, if you want beginner stuff to learn, first read a book. In several instances, I have know how to use functions and looked backwards in the manual to see if there were any other bits I could use. I COULD NOT REVERSE ENGINEER the manual EVEN THOUGH I completely understood how to use the function. This is bad. Really bad. Actually, I do not understand what you are saying at all, eg., 'I have know how to use ...' is not clear. Do you already know about some 'functions' and want to know more, or do you need to know about a function? Even though you SHOUTED at us, I do not know what you mean by 'reverse engineer the manual'. So I cannot fathom why not being able to do so is bad. This is what I am after: The manual should be written like a spoken language dictionary. First 'should' is subjective to you. It is not imperative to those who contribute. It *is* a part of the process of writing the documentation to evolve a style and a terminology to accomplish several self-contradictory things, eg., brevity and comprehensiveness. The balance is not easy to accomplish, and we all want something better. This is a deep issue. There is no single answer for everyone. 1) it should tell you what that word is Everyone would agree with this point. Frankly, having read the documentation for other software, the perl6 docs succeed very well. However, I think your problem is that you don't like the terminology that is being developed by perl6 documentation contributors (part of the deep issue). But all spoken language dictionaries (I looked up 'if' and 'as' on Websters, Collins, and Oxford dictionary sites) have terminology and special signs for pronunciation, or for grammatical function, eg., pronoun, conjunction, adverb. To understand a dictionary, you have to learn about the terminology. If you look up words for other spoken languages, eg., Cantonese, then you get things like sentential particles or classifiers, neither of which exist in English. (A bit like the difference between perl6 and perl5). This means that you actually have to know something about a language before being able to use the dictionary, and dictionaries for different languages are, well, different. 2) show you how to use it in context. No quibble here. But perl6 documentation does provide examples. I would agree that there should often be more. Contributions are welcome. As programmers work through different contexts, they come up with interesting examples. I don't think anyone has rejected new examples. And I might point out that a dictionary is not a HOW TO book to teach you the language. We all agree. There is a difference between reference documentation and tutorials. The problem is that it is difficult to discern from your own explanations (even this very post) what it is you want. And given my experience in other languages, sometimes tutorials are good, sometimes manuals are good. Often `stackoverflow` is the best goto. There is not a single experience. Personally for perl6, the docs are the best. But I am confused about what *you* want from the reference documentation. 3) when calling other term to explain things, it should
