search

oils-for-unix / oils

Oils is our upgrade path from bash to a better language and runtime. It's also for Python and JavaScript users who avoid shell!
http://www.oilshell.org/
Other
2.81k stars 152 forks source link

Write Tour of the Project, including OSH compatibility and Oil clean slate #1127

Open andychu opened 2 years ago

andychu commented 2 years ago

Somehow after years of writing it's not clear to people that OSH is both POSIX compatible and the most bash compatible shell by a mile

https://lobste.rs/s/jdxhu9/sqlite_go_with_without_cgo#c_fka0da

bar-g commented 2 years ago

Here is a suggested explanation text for the homepageproject-summary page:

The Oilshell package provides an improved Unix shell. (Pitfalls and security flaws removed, programming features added!)

It's very POSIX compatible and the most bash compatible shell by a mile, with an upgrade path to a better language and runtime, even amicable for Python and JavaScript users who avoid shell.

It is test-based and implements the agreeable common subset of other shells by default (as /bin/osh).

The OIL interpreter (osh setting oil:all, or simply run as /bin/oil) will cautiously disable all legacy shell warts and the support for a few conflicting, and well superseded, shell idioms. Merely deprecated shell idioms may be identified with a lint option. Using Oil is the final target for a script migration, as well as the clean slate for a fresh start into shell scripting.

Also:

bar-g commented 2 years ago

Initial confusion might also be reducable by more carefully, and explicitly distinguishing between oil/oil-language/oilshell/osh. Avoiding to talk about just "oil" instead of a more precise meaning: "oil language", or "oilshell interpreter", or meaning "osh mode", etc.

project and interpreter (oilshell?) mode to support "other shell"s scripts (osh?) new language and mode (oil?)

bar-g commented 2 years ago
bar-g commented 2 years ago

I updated the intro/mini-tour for the homepage in the above comment https://github.com/oilshell/oil/issues/1127#issuecomment-1133749799

bar-g commented 2 years ago

after years of writing it's not clear to people that OSH is both POSIX compatible and the most bash compatible shell by a mile

I'd see that as a result of talking early, much, and mostly about oil, an incompatible (even if not by much for upgrades) language. Whereas oilshell provides osh and oil. So simply mentioning and clearing up this correlation at crucial places on the homepage and in the docs should be able to avoid that misconception. And then, there shouldn't be a problem in going on to talk about everything nice about Oil.

andychu commented 2 years ago

FWIW you may be wondering why I haven't been eager to merge this, so here is some detailed feedback

Here is a suggested "intro" for the homepage:

Oilshell provides an improved Unix shell. (Pitfalls and security flaws removed, programming features added!)

It's POSIX compatible and the most bash compatible shell by a mile, with an upgrade path from {a,ba,da,k,z}sh to a better language and runtime, even amicable for Python and JavaScript users who avoid shell.

The {a,ba} stuff is way too clever and jargon-y

There are a significant number of shell users (actually probably a majority) who have never used or read brace expansion

It is test-based and "very"-compatible, implementing the agreeable common subset of other shells by default (as /bin/osh).

"very" in quotes is also awkward

* OSH runs most existing scripts more securely without having to re-enable any backwards-compat option. (Scripts that are using [excluded, inconsistent or problematic features](https://www.oilshell.org/release/latest/doc/known-differences.html) are most often better to, and simple to, fix right in the script, anyway. And every oilshell error message should provide you with a useful hint.)

As mentioned on the known differences page, most users will not run into it. It is a distraction to mention it on the home page

* OSH provides additional, individual strict* modes (and `strict:all`) to increase the robustness of shell scripts even when they run in other shells. Adding any strict* option may, of course, require some script adjustments, see [shell idioms](https://www.oilshell.org/release/latest/doc/shell-idioms.html) for some compatible solutions.

This is true, but I tend to emphasize features over "strictness" (preventing you from doing bad things). For example I wrote "Why Use Oil?" page a year ago: https://www.oilshell.org/why.html

It mentions the strictness / dev tool stuff. I explained this to people on lobste.rs and so forth and it's just not enough for them to switch.

There is a reasonable "scare" of using a new shell that others aren't using, and the strict options are not enough to push it over.

Also, there are far fewer people than you'd think that want to run their program under multiple shells. Just like I never run my Python scripts under both CPython and PyPy -- I use CPython.

So I think the strict options are very valuable, but I'm not keen on emphasizing them too much for this reason. They are something nice AFTER somebody has decided to use the Oil project

* OSH allows "dropwise" addition of the evolved Oil language idioms to existing shell scripts (`oil:upgrade`) with [only minimal breaking changes of legacy shell syntax](https://www.oilshell.org/release/latest/doc/deprecations.html). This enables adding nice ad-hoc solutions for legacy shell problems. However, using oil syntax in the script would of course require some fallback shim library for it to still run in other shells.

I don't understand "dropwise"

This also has too many words

When using all of the Oil interpreter (osh setting oil:all, or simply by starting it as /bin/oil) it cautiously disables all shell warts and the support for a few conflicting, and well superseded, legacy shell idioms. Deprecated shell idioms may be identified with a lint option. Using Oil is the final target for a script migration, as well as the clean slate for a fresh start into shell scripting.

Again way too many words

So yeah I think your feedback is good, but I'm not excited about the solutions proposed :-/

As mentioned I think the usage table is adding missing info but I haven't seen the preview yet

If you don't have time for it, I will probably get to it in 2 months after I find people to hire to work on Oil, and after we launch features that will cause people to ACTUALLY switch to Oil

Right now it's too slow and the Oil language isn't mature enough; those are the main blocking points of the project

andychu commented 2 years ago

FWIW I put a preview here of something with MANY FEWER words:

https://www.oilshell.org/index2.html

again I think you're overestimating how much people will read

But I am not entirely happy with this either.

I agree there is some "Oil" confusion, but I think "Oilshell" is not distinct enough.

Even if we add "Oilshell", "Oil" is still going to refer to either the language or the project.

Similar to "Go" and "Golang" which people use to refer to both the language and project (although there is only one language in that case.)

A different although unlikely solution is to rename the Oil language. Oil the project could be both OSH and "Tea" or "Soil" (those are names I used for other subprojects, so they are not available, but give you an idea)

I think this would be a lot of effort and make all previous blog entries confusing ... But possibly less confusing than introducing a similar-but-different "Oilshell" term

andychu commented 2 years ago

Existing tagline

Oil is a new Unix shell. It's our upgrade path from bash to a better language and runtime. It's also for Python and JavaScript users who avoid shell!

That draft was

A new Unix shell with 2 parts:

  1. OSH is the most bash-compatible shell by a mile!
  2. Oil is our upgrade path from bash to a better language and runtime. It's also for Python and JavaScript users who avoid shell.

Here is another one:

Oil is a new Unix shell. It runs your existing shell scripts, but it's also a new language for Python and JavaScript users who avoid shell.

It's our upgrade path from bash to a better language and runtime.

Hmmm I actually like that

Then in the Project Tour which is linked up front, we will mention bin/osh and bin/oil

andychu commented 2 years ago

OK I updated the home page:

https://www.oilshell.org/

Oil is a new Unix shell. It runs your existing shell scripts, and it's a new language for Python and JavaScript users who avoid shell!

It's our upgrade path from bash to a better language and runtime.

I think this is good because we can have three links:

And now we have shopt --set oil:ugprade, which is very easy to remember! (thanks for that feedback)

bar-g commented 2 years ago

Thanks, much appreciated. Let me add my thoughts, and some background reasoning.

As Oilshell is the domain name as well as the prospective package name I think it's rather an omission or oversight not to use it for in explaining. Not confusing at all, rather necessary to mention.

Shell users, especially early adopters, I'd expect to actually appreciate helpful condensed information, and not being even slightly afraid of extensive docs at all, but happy not having to go through blogs and docs just for the basics.

{a,ba} stuff is way too clever and jargon-y

Yeah, let's drop that.

"very" in quotes

same

"scare" of using a new shell

That's actually a specific background reasoning for mentioning things like "unneeded backwards-compat options", "strict*", and "run under multiple shells" hints.

Rather than seeing these as a distraction see them as valuable bits of info, mentioned to assure readers it's taken care of, providing confidence to start downloading and playing with oilshell. Things for them to check off as covered, instead of leaving them wary of unforeseen compatibility problems etc., waiting to hit them. The "run under other shells" hints are especially related to assessing lock-in.

I don't understand "dropwise"

I wanted to describe adding some new features to a script and using oil for the additions, but keeping the other parts mostly unchanged.

Concerning the length of the intro, I really don't think anyone looking into a new shell would be scared off by a postcard sized executive summary, rather the contrary. (Especially for pre 1.0 versions.) Though, surely there are still be improvements possible.

bar-g commented 2 years ago

I think this is good because we can have three links:

Well, I'd say it scatters information instead of gathering and presenting a summary.

andychu commented 2 years ago

Yeah I think they can actually all link to three sections of the same project tour:

  1. run existing shell scripts
  2. new language
  3. upgrade path
bar-g commented 2 years ago

Note that when you don't explain things a bit and tell new users, for example, there are (minimal) things that will break in osh, you'll likely loose them before you know. Ah it's broken->bye.

bar-g commented 2 years ago

But I am not entirely happy with this either. I agree there is some "Oil" confusion, but I think "Oilshell" is not distinct enough.

Then maybe you might have to look for a name, maybe something like Oilscript?

Regarding the intro, I think, yep, having the intro (only) on a single(!), but multi-linked, second summary-page could work, too. (If you really prefer a no-text, nav-only homepage.)