Re: manual

[Ray Andrews <rayandrews@xxxxxxxxxxx>]

On 2022-12-20 18:00, Daniel Shahaf wrote:
> The last sentence goes without saying, for several reasons: 

Even in the unlikely event that the devs were interested in my writing, 
it goes without saying that there will be edits. And obviously the devs 
have the last word on any issue, however:

> - As a rule, the manual isn't in the business of describing what the
>    syntax is not; the manual should describe what the syntax /is/.
>    
>    Putting =(…) there isn't nearly common enough an error to make an
>    exception to the rule for.
It's part of my philosophy to throw in 'helpful hints'.  It's what makes 
a document actually helpful.  OTOH, as you correctly say, manuals are 
not focused on that, and in any case it would have to be broadly agreed 
that any particular helpful hint is really needed.  I needed it, but 
that's not sufficient.
> The assumed knowledge includes the fact that calling any builtin,
>    function, or external command with anything enclosed in parentheses
>    would be a syntax error.
First I've heard of that!  Seemed to me 'obvious' that there'd be 
parentheses -- an array is being assigned..  Mind, again, my particular 
ignorance is no test of what's worth mentioning.
>    All of the first three work, because they all follow exactly the same
>    "list of shell words" syntax; the only difference between them is what
>    relative order they are considered (looked up) in.  (Functions are
>    looked up first, which is why a function named "autoload" or "env"
>    would shadow the builtin or the external command respectively.)
I need to know more about all that.
> Normally the manual would end such a sentence at the comma. Rule
> against surplusage, I guess ☺
Yes of course, but it was a first draft!  Actually not even a draft, 
more like a sample of how I think a manual should be written.  Lots of 
examples -- actual runnable code that could be pasted to the CL and 
run.  Break up the synopsis into several lines,  each one covering some 
specific subset of functionality.  Give some thought to readability.  
Remember that people reading the doc are looking for usable information 
and the test of a doc is that it is helpful to the non-expert.  And so on.
> Unfortunately, as written this assumes the reader takes "overwriting" to
> be an operation that involves "truncation" at some point, and we can't
> assume the reader's mental model of overwriting is that.
Indeed.  It's clear to me but maybe not to the next guy.  The main thing 
I was trying to communicate with that little effort is that it's the 
*example* that makes it clear, not the exposition.
> That's unusual: most synopses spell out all valid flags
Yes!  Very lazy.  And I took 'options' there to mean option names. Mind, 
it does actually work that way.
> So, thanks again for the contribution. Let's try and focus please and
> the two specific issues identified («set -A» and types; «set -A» and
> prefixes).
After you mentioned it, I couldn't stop thinking about it, so had to 
give it a go.  I was writing it in my dreams last night.