Re: manual

[Ray Andrews <rayandrews@xxxxxxxxxxx>]

On 2022-12-21 23:03, Lawrence Velázquez wrote:
> Partitioning the synopsis isn't a bad idea, but your partition is
> misleading because most of the options you separated can actually
> be used together in a single "set" command.
I'm pleased to have made as few mistakes as I did.  There was no hope 
that I'd get it right the first time.  It was just a sort of 
template/sample for my thoughts on how a manual page could be made more 
useful.  Indeed the way functionalities can be piled on top of each 
other is why I called 'set' a dog's breakfast.  IMHO we should have 
setopt (already do), setarray, and setparam.  But I appreciate that set 
probably got that way by accretion -- over the years stuff got added on 
and there was no point at which anyone wanted to back out and rethink 
the thing from the ground up.  London vs. Paris. As you say, a more 
broken up synopsis -- tho always the better way -- runs into trouble 
when functionalities can be piled on top of each other but with all 
sorts of ifs ands buts and maybees  (like the way that '+s' works with 
'-A' but not with '+A').  It's something to explore how that might be 
handled.  (Mostly by shaking out the commands themselves!)
> POSIX.1-2017 does partition its synopsis [*], but later it has to
> explicitly explain that setting and unsetting attributes can be
> mixed in a single invocation because the synopsis implies otherwise.
>
> 	set [-abCefhmnuvx] [-o option] [argument...]
> 	set [+abCefhmnuvx] [+o option] [argument...]
> 	set -- [argument...]
> 	set -o
> 	set +o

Ironically IMHO that's going too far.

	set [{+,-}abCefhmnuvx] [{+,-}o option] [argument...]

... would be quite tractable.  (I myself prefer the comma to the pipe but that's just me.)

Dunno, on the one hand I think that manuals should be quite rigid in their use of terminology and the syntax of things like synopses, OTOH there are times when you hafta just 'get it done' -- explain the thing however it needs to be explained and that might mean bending a rule as to synopsis grammar.  Interesting questions!  But we're out of time anyway.  The only real test of/for any doc is whether or not it is useful to the people who might actually need to read it.  That means force feeding it to newbies -- the way you force feed medicine to lab rats -- and then asking them if the document is understandable.  If it is the doc is good, if not it needs work -- simple as that.  I'm trying to be that lab rat.  But there are so few of me.

> 2): set {+|-}s [STRING] [STRING] ... :

> The term "string" is next to useless when discussing shell.  Almost
> everything is what you might consider a string.

That very well could be.  In the world according to Ray, the manual 
would start with a glossary of terms which would have rigid usage 
throughout.  Not 'flag' or 'switch' or 'option', pick one and define it 
exactly and use it exclusively.  Note that even in my experimental run, 
I took 'option' to mean a switch (cuz it's often used that way) whereas 
in that case it meant a single letter OPTION -- which is not explained 
in any way.  One could read that man-page and never know there is any 
such thing as a single-letter option.

> As I already mentioned, this is incorrect. Options and positional
> parameters can be mixed in the same invocation.

No worries, it was just a dry run.  You're taking it more seriously than 
I did.  If ever a man-page were to be rewritten by me, it would be 
subject to checking and editing by knowledgeable people like yourself.  
I would never presume to have the final word on anything.  We'd  get it 
right on the 5th edit.  But I do have a talent for clarity.


> > DON'T KNOW WHAT TO DO WITH THAT.
> Leave it in?

As you would decide.  I'm only saying I myself can't do anything with it.

Good writing is a very difficult thing.  Especially good technical 
writing and coders are notoriously bad at it.