Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 19 commits into
base: master
Choose a base branch
from
12 changes: 7 additions & 5 deletions doc/ysh-faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,15 +107,17 @@ That is, `echo "$flag"` always has a few bugs: when `$flag` is `-e`, `-n`,

So portable shell scripts use:

printf '%s\n' "$x" # print $x "unmolested" in POSIX shell
printf '%s\n' "$x" # print "unmolested" in POSIX shell

We could have chosen to respect `echo -- $x`, but YSH already has:
We could have chosen to respect `echo -- $x`, but as YSH already has:

write -- $x # print $x "unmolested" in YSH
write -- $x # print $x "unmolested" in YSH

That means YSH has:
It allowed YSH to have:

echo $x # an even shorter way
echo $x # YES: an even shorter way
write --sep ' ' -- $x # synonym
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--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

Copy link
Contributor Author

@bar-g bar-g Feb 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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,...)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

write -- $x $y # alternative (one line per arg)

So `echo` is technically superfluous in YSH, but it's also short, familiar, and
correct.
Expand Down