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

Conversation

bar-g
Copy link
Contributor

@bar-g bar-g commented Feb 11, 2024

No description provided.

@bar-g
Copy link
Contributor Author

bar-g commented Feb 11, 2024

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

@andychu
Copy link
Contributor

andychu commented Feb 11, 2024

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
Copy link
Contributor Author

bar-g commented Feb 11, 2024

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
Copy link
Contributor Author

bar-g commented Feb 13, 2024

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
Copy link
Contributor Author

bar-g commented Feb 13, 2024

Finally found some few words that make good sense.

@bar-g bar-g changed the title [doc/ysh-faq] conclude "unmolested" thread in consistent way [doc/ysh-faq] This allowed YSH to have echo $x (an even shorter synonym) Feb 13, 2024
@bar-g bar-g changed the title [doc/ysh-faq] This allowed YSH to have echo $x (an even shorter synonym) [doc/ysh-faq] Why Removed?: having write -- $x allowed YSH to have echo $x (#YES: an even shorter way, ... # synonym) Feb 21, 2024
@bar-g bar-g changed the title [doc/ysh-faq] Why Removed?: having write -- $x allowed YSH to have echo $x (#YES: an even shorter way, ... # synonym) [doc/ysh-faq] Why Removed?: ...having write -- $x allowed YSH to have echo $x (#YES: an even shorter way, ... # synonym) Feb 21, 2024

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

@andychu
Copy link
Contributor

andychu commented Feb 28, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants