[doc/ysh-faq] Why Removed?: ...having write -- $x allowed YSH to have echo $x (#YES: an even shorter way, ... # synonym)

[bar-g]

No description provided.

[bar-g]

I really found the statement sequence a larger stretch, that broke the easy reading comprehension flow too much.

[andychu]

Hm I don't see that this improves the doc, I think it makes sense as is

There are probably many other areas of the docs that can use polishing / review

[bar-g]

I minimized the changes, now.

Mainly leaving the comments untouched, only adding words I found really missing to actually have written down some reasoning. When left out I find it's barely listing statements and leaving more questions than answers.

As author your can think of all this along the structure of the code, but external readers really benefit from connecting things with a tad more reasoning.

It makes a difference, sure the statements are not wrong without, but unfortunate to not be that helpful to understand either.

[bar-g]

Please reconsider the minimized changes.

I can only fill some bumpy gaps in the docs after I got enough experience with the topic.

You're really good at condensing stuff, but it can be a bit sparse at parts, taking longer to actually understand for readers new to osh/ysh.

I'm now proposing just the minimal bits I found where causing the problem/unclear/questions here.

[bar-g]

Finally found some few words that make good sense.

[andychu]

--sep ' ' is sort of irrelevant here, I think it just confuses things more

This is a FAQ entry, so not everything needs to be packed here.

That equivalence can be noted in the doc/ref topics for echo and/or write

And we can add links from the FAQ to the reference -- I've been doing that in a few places

[bar-g]

That equivalence can be noted in the doc/ref topics for echo and/or write.

But that is too late.

Probably no one thinks of first needing to read docs about echo and write, ever after a first hello world script. (And echo and write can work for a long way interchangeably as long as used with a single quoted arg.)

Thus mentioning echo and write things in the FAQ makes perfect sense, but then leaving out this line-wrapping bit is just leaving the reader in the lurch. Knowingly sending them into some error/bug situation... that will bring frequently asked questions that the FAQ... does not answer, actually glosses over?

No, I'm first-hand sure the --sep ' ' is an important bit, and the command is not a synonym without it. What's a FAQ mean to leave it out?

It's similar to why I think it's important to mention the "args on a line" vs. "a line per arg" defaults also right in the ysh-toc overview: To get the attention during early contact with ysh, i.e. when skimming the reference or reading the faq (before ysh appears to have gone "astray" on some most basic things).

I have come to understand and like the difference, but it really came as a bad surprise (intricate follow-up error, unexpected, deviating behavior), where it shall rather be a "oh, that's peculiar... ok, there are alternative ways,... hm, yes, it's really a good choice to have, makes sense".

To make this bit more explicitly apparent in the FAQ I now think it makes much sense to actually apply short additions to really complete the example here:

echo $x                # YES: an even shorter way
write --sep ' ' -- $x  # synonym
write -- $x $y         # alternative (one line per arg)

So there they are: The two idiomatic ways to "print" in ysh.
(Oh, peculiar, the FAQ has just become enlightening to read...
ok, there are alternative ways,...
hm,...)

[andychu]

The hints about echo/write can be put SOMEWHERE, just not here.

This FAQ entry isn't the right place

It can be in either doc/ref or in another FAQ section perhaps, but it has to be worded well

[andychu]

I prefer putting most information in doc/ref. Then if you think it's hard to find, write a short FAQ entry that describes the actual question you had, and link directly to doc/ref