A Tour of the Oil Language
I&#x27;m interested in and excited about oil, but three things have stopped me every time I&#x27;ve tried to give it a go.<p>1. The complete and utter lack of useful documentation. There&#x27;s not even a link to any docs from the main page of the shell&#x27;s site. You have to get to the docs from the release page, [1] but I had to find this out by Googling. Given the number of blog-post-like entries in the docs, seems like it would have been less effort and more effective just to write standardized and complete documentation from the start.<p>Just as an example: can anyone tell me what built-ins Oil has, how to use them, and where they are documented? I&#x27;ll give you a hint. I found out from one of the blog posts that oil has &quot;min&quot; and &quot;max&quot; commands. The following is valid Oil code:<p><pre><code>    const x = min(1, 2)
</code></pre>
But what other commands does Oil have, and how do I use them? I have no idea. Some of the doc pages 404 so maybe they&#x27;re supposed to be there. I have found <i>some</i> pages listing built-ins which are mostly undocumented, but none of them list min or max, so I know they&#x27;re not complete.<p>2. It&#x27;s still pretty buggy and lots of features are missing. Development has seemingly moved slowly over the last several years. If it ever did get to the point where I could make it a daily driver then I&#x27;d be willing to track down and report bugs, of course.<p>3. I&#x27;m a little concerned by how much emphasis is put on POSIX &#x2F; Bash compatibility. Unless there&#x27;s going to be a way to <i>fully</i> disable what Oil considers &quot;legacy&quot; language support in a script, then that is going to leave a ton of footguns for people who want to write &quot;modern&quot; Oil code. It&#x27;s not clear to me whether that&#x27;s the plan or not (I haven&#x27;t read every one of the blog posts), but it seems like a mistake to me to sacrifice possible syntax improvements on the altar of compatibility.<p>To be clear, I realize this is basically someone&#x27;s solo project, and I am impressed by how far it&#x27;s been taken, just clarifying why I don&#x27;t think it&#x27;s ready for general use yet.<p>[1] <a href="https:&#x2F;&#x2F;www.oilshell.org&#x2F;release&#x2F;latest&#x2F;doc&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.oilshell.org&#x2F;release&#x2F;latest&#x2F;doc&#x2F;</a>