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.

Sign up for GitHub

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
+7 −5
Open

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

Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
bb5fc2c
[doc/ysh-faq] conclude "unmolested" thread in consistent way
bar-g Feb 11, 2024
95779e4
thead consistency
bar-g Feb 11, 2024
2964853
reasoning
bar-g Feb 11, 2024
59eaefb
shorten
bar-g Feb 11, 2024
85a5d40
shorten
bar-g Feb 11, 2024
25ebb58
show echo equivalence
bar-g Feb 11, 2024
8722d38
align comment
bar-g Feb 11, 2024
48ec70b
shorten
bar-g Feb 11, 2024
86bb2a8
optionless -> flagless echo
bar-g Feb 11, 2024
c2f3050
minimize changes
bar-g Feb 11, 2024
a534a63
echo's reason to be
bar-g Feb 11, 2024
4f25d32
minimize changes
bar-g Feb 11, 2024
8aef138
minimize changes
bar-g Feb 11, 2024
519d703
switch to YES / synonym examples
bar-g Feb 13, 2024
7fd26b4
use orig words
bar-g Feb 13, 2024
14cc921
finally making good sense
bar-g Feb 13, 2024
c61202e
This -> It
bar-g Feb 18, 2024
e3b5422
align all comments in section
bar-g Feb 20, 2024
1035cc4
write example for comparison
bar-g Feb 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions doc/ysh-faq.md
View file
Open in desktop
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 •
edited
Loading

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
Loading