Open indigoviolet opened 2 years ago
Examples of specific things I struggled with as a dabbler in shell and an oil novice:
exit 0
the script if they failedrun
, but I can't find documentation for itHi thanks for the feedback. The docs are definitely behind (as mentioned on the blog).
The way it works now is that there is a skeleton of the docs, but the contents of many docs are missing, so they have a pink warning at the top. I think that page has a similar structure to what you want.
But to avoid hitting the pink warnings all the time, I put the docs that are done at the top level: https://www.oilshell.org/release/0.9.7/
(I'll probably move all the benchmark / test stuff to a different page)
I think we have the start of everything you list, except the builtin reference, which is #388. Someone else mentioned that recently as well, so I agree it's important.
Oil definitely isn't done and some recent blog posts try to give people a sense of where it's at:
http://www.oilshell.org/blog/2021/12/backlog-assess.html
Also feel free to join Zulip and ask questions. That is the best way to prompt me to update the docs. I often answer there, and then copy the answers into the docs.
What I will do is make this clearer on the home page -- there is an #oil-help
Zulip channel (that most people don't know about right now).
For the specific issues:
shopt --xtrace
works ? Can you give an example?
set -x
and set -o xtrace
, but Oil prefers shopt`)run
builtin appears in docs? I thought I had changed those all try
, but I could have missed some.exit 0
if they failed, but you can use try --assign :st mycommand
to set the status to the $st
variable. And then do whatever logic you want. Feel free to chat on Zulip if this doesn't make senseSo yeah what I will do is
Thanks for trying it!
For now the documentation seems scrambled and fragmented. This is really bad for anyone trying to learn osh/ysh. I would like to suggest spliting the documentation, blogs and some random unimplemented ideas so user have a clearer view.
Also, it seems like the website is customized created, I would like to suggest migrating to something like https://github.com/facebook/docusaurus . I may step in and help if that's preferred.
The best way to help write now is to try YSH, and when you have a problem, look for the docs
First in in doc/ref
If you can't find it, post a message on Zulip
Then I'll suggest a PR you can make. The docs are open to PRs, but it will help if you're more familiar with the project first
I have been aware of this project for a while but decided to try and convert some simple shell scripts today. My biggest frustration that is making me abandon this course for now:
The documentation is confusing, missing links and an overall obvious structure, hard to navigate through. Compare to something like https://docs.python.org/3/index.html -- I would suggest an organization like
In the case of oil, these things are not clearly delineated. There is confusing information about what is implemented and what isn't. I would expect uses of builtins etc. in the Introductions to link to their detailed reference sections. There are no breadcrumbs to help jump between sections. There is some documentation on github and some on the website. Some links are broken.
I appreciate that this is a huge undertaking and am grateful for all the effort that has gone into it already. I hope this is useful as insight into what might help/prevent adoption (at least for n=1). I will continue to keep tabs on oil for the future, thank you.