From: Ray Andrews <rayandrews@eastlink.ca>
To: zsh-users@zsh.org
Subject: Re: manual
Date: Thu, 22 Dec 2022 05:50:10 -0800 [thread overview]
Message-ID: <0f445101-6c98-1a7c-277d-e0f5bbb5d460@eastlink.ca> (raw)
In-Reply-To: <a6b802da-7787-4de0-8713-679679d70971@app.fastmail.com>
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.
prev parent reply other threads:[~2022-12-22 13:51 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-12-20 22:41 manual Ray Andrews
2022-12-21 0:43 ` manual Lawrence Velázquez
2022-12-21 1:15 ` manual Ray Andrews
2022-12-21 1:44 ` manual Lawrence Velázquez
2022-12-21 4:15 ` manual Ray Andrews
2022-12-21 2:00 ` manual Daniel Shahaf
2022-12-21 4:12 ` manual Ray Andrews
2022-12-21 4:43 ` manual Bart Schaefer
2022-12-21 14:04 ` manual Ray Andrews
2022-12-22 6:31 ` manual Lawrence Velázquez
2022-12-22 14:20 ` manual Ray Andrews
2022-12-21 9:38 ` manual Lawrence Velázquez
2022-12-22 7:03 ` manual Lawrence Velázquez
2022-12-22 13:50 ` Ray Andrews [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=0f445101-6c98-1a7c-277d-e0f5bbb5d460@eastlink.ca \
--to=rayandrews@eastlink.ca \
--cc=zsh-users@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).