OK thanks, I think all the shebangs should be #!/usr/bin/env oil or osh, because Unix ... e.g. when you do ./configure it's not clear where it will end up.

/usr/bin/env is POSIX I believe ... (i.e. it's not /bin/env)

There we have it again. Path security.

I don't think env does supports a -p option to only use the unaltered, original systems' $PATH (from getconf PATH?), like maybe command -p.

Unfortunately, it can't be relied upon command -peither. Check: https://github.com/modernish/modernish#use-syscmdextern
And who always uses -p?
And then there are still systems that only take a single argument in the shebang.

I think the only thing that may work is, limiting $PATH configuration and mutations to su/sudo/doas operations, and making these non-overridable.

wiki updated

The wiki formatting issue isn't nice, but I think it's worse not to provide any links to basics like the design principles and usage table from the hompage/getting-started.

OK thanks, well the table is technically inaccurate now since we haven't done #1137

But yeah I think we should start that in the next release

I've pasted a copy of the table above, to see a working html version, and I think you should also have write access to this issue's description.
Maybe remove the broken duplicate wiki page?

Could you tell for what reason was the title changed from "Oilshell Usage" to "Oil Usage"? I think the table specifically tries to discern the most basic different parts of osh and oil languages and interpreters for new users, it's not just about the oil interpretter and language. (The usage table is, at the same time, an overview of oilshell as a whole.) That's the sort of "mixing-things" I meant in #1127 (comment), which can make the docs seemingly easy to read but actually leaves the user only frustrated and confused later. Talking of the same word all the time doesn't help, rather the contrary.

I used oilshell there to mean the whole thing that is osh and oil and can deal with a whole lot of different shell language stuff.

I really do see a merit in using the shorter "oil" only for the language and its interpreter/setup. It's also really nice and short --and correct-- for the later day-to-day usage. But it seems much better to use three different words in the beginning, to talk about the three different scopes involved and better coming to grips with the project parts and migrating scripts.

PS: On the other hand, for the package name though it might actually be worse to use the shorter name, the slightly longer "oilshell" name is still short enough but provides more context and better search hits (as in broader and specific searches).

s/sort of things/sort of "mixing-things"/ (...which I meant)

inherit_errexit is on in oil:basic.

Wouldn't strict_errexit (+inherit_errexit and more error stuff?) be a something (a usage task) for users to enable in osh?

Hm I don't understand the question ...

Wouldn't strict_errexit (+inherit_errexit and maybe other non-strict_* error stuff?) be a something (a usage task) that users could enable in osh and which could be worth showing in the usage table?

• strict_errexit is part of strict:all which is in the table
• inherit_errexit is part of oil:basic/upgrade which is in the table

In general the individual options should be "hidden" from "getting started" docs. They are a little scary and unfriendly.

Hence the purpose of having all the recommended options bundled under bin/oil

BTW I think the table is generally good now, except the words on the LHS are not "crisp" enough. The RHS of the table is good and accurate.

However I think it needs to be complemented by something with examples, like

https://github.com/oilshell/oil/wiki/Gradually-Upgrading-Shell-to-Oil

This is more of a "reference table", which is good and we should have it. But I think it needs to link elsewhere.

I'm surprised the wiki doesn't work?

It can also go in doc/usage-table.md or something like that, and we can link it up later. That needs to be CommonMark, so again we should have

build/doc.sh split-and-render doc/usage-table.md

In CommonMark you can put markdown inside HTML, like

<table>
  <tr>
     <td>

This is *markdown*

     </td>
  </tr>
</table>

It shouldn't be too bad for this table.

Only editing the table did I realize the --line option to write affects only the $_line varible and is not needed for the line wise default mode, is that correct?

Maybe that could be made more obvious by something that looks odd at first, but quickly telling after a second: read --_line. (This may possibly even be generalizable into a generic short option to write into status vars: -_)

Hm as far as the words oilshell, oil, osh:

• I think the tarball will be called oilshell-$VERSION.tar.gz eventually. It matches the domain name
• Oil is bin/oil and the Oil language. Sometimes I say "the Oil language"
• OSH is bin/osh and the OSH langauge

I think the way you've written Oilshell in several places is awkward ... I do not want that to become the colloquial name.

I think the table could just be called "Using OSH and Oil" -- rather than "Oilshell Usage"

I do not want [Oilshell] to become the colloquial name.

Hm, but do you have a better idea? Because large parts of the confusion (and thoughs in the direction of "why's this guy writing so confusing stuff") I had can be related to talking about "oil" but really meaning different things. Somewhere (and probably at different places) it seems necessary to spell out that Oilshell means osh and oil. I don't think the common name would need to be used everywhere, that wouldn't be correct either. Talking about oil (language/interpreter) is often more precise (and the focus of the development and docs anyway).

So, I think using "Oilshell" would not be necessary in too many places, but only in some crucial places, especially for newcomers. Probably only (and always) together with explaining the osh/oil parts.

Let's see an example:
Currently the getting-started says "There are many ways to use Oil!" and goes on saying to use as compatible osh or legacy-free oil.
Unfortunately, that leaves an unclear nomenclature, even raising contradicions, most obvious: oil can't be both oil and osh, when using osh oil (lang) can't be used (but partly).

Also: "legacy-free" may convey dropping a lot of compatibility, maybe "pitfall-freed" or "freed from shell-pittfalls" could describe that part of oil more positively.

I think the table could just be called "Using OSH and Oil" -- rather than "Oilshell Usage"

I think that title is kind of is a crucial line to provide orientation to new users and made an update to the pull request, but maybe it's still improvable. Oilshell Usage through bin/osh and /bin/oil, or something?

Ah, ok, "colloquial" name no, but the "overarching" one, useful to clear things up in the intro?

With the current suggestion I tried to remove the awkwardness from the intro, explaining the first thing to "get-started" like this:

Oilshell provides a multi-purpose interpreter runtime.

• You can use it interactively, or run and write "shell scripts" for it.
  (Shell is the best language for ad hoc automation.)

• You can start it to use a language that's compatible with other shells (using bin/osh),
  or, to use the much improved Oil language, a very coherent pitfall-freed shell upgrade with
  selected python/js/etc. features (using bin/oil).

As of 2021, the OSH language is mature, and the Oil language is under development.
...

Note that for a user that has heard or read about oil or oilshell, and goes straight to the website looking for downloads (or even was directly referred to downloads), I think the "getting-started" document is the first (and likely only eligible) place that allows to provide the basic overview to the user just once before it's too late to avoid confusion with mainly oil focused texts. (And it's also good for pointing users back to "getting-started" later on.)

However I think it needs to be complemented by something with examples, like
https://github.com/oilshell/oil/wiki/Gradually-Upgrading-Shell-to-Oil
This is more of a "reference table", which is good and we should have it. But I think it needs to link elsewhere.

Yes, looks like the outcome of #1130, i.e. the new /doc/index, could be the best place to link to in the future and for gathering all the links.

For the moment I've added https://www.oilshell.org/release/latest#Documentation (though the html anchor does not seem to work, currently).

FWIW, creating Oil/OSH/Oilshell confusion should be pretty much be a thing of the past with just

• adding an overview intro and links to the homepage (1127#issuecomment-1133749799) (Could not find the homepage in the oil repo, though.)
• a usage table in getting-started (doc/getting-started: basic sort, add usage table #1151)
• and linking a usefull page that lists all deprecations and cutbacks when upgrading from other shells to oil doc/deprecations: sort out old/intermingled parts into revised structure #1145

That is too detailed for the home page ... (which is in the private blog repo, though I could make it public).

The usage table is a good idea, but I still want to see the preview. (Also my feeling is that there are too many words there as well)

In general I think you're overestimating how much people read documentation. I think the real issue is that people need to use Oil and write about it on their OWN website!!! i.e. languages spread socially.

But yes there is a chicken-and-egg problem ... there are people who come to the project fresh, and sometimes they do try it out and read the docs

About naming, I suggest using the words "Oil Project" and "Oil Language". I have been using "Oil language" consistently, and I use "Oil" whenever I mean the project. But "Oil project" is also OK.

Actually that is in the title of the issue #1127

FWIW this command will extract the table ... but only the source text, not the rendered HTML.

curl   -H "Accept: application/vnd.github.v3+json"   https://api.github.com/repos/oilshell/oil/issues/1142

But in general I feel like this is not rocket science; if you want an HTML table, then make an HTML table :)

Who wants an html table? You mentioned CommonMark above.

However, I only found some important introductory usage info that is missing in the documents presented on oilshell.org. Which I had to gather from elsewhere, and thus submitted it as contribution.

I don't see the problem that you seem to have about previewing, it looks ok to me.

CommonMark is basically a superset of HTML. So if you write any HTML, it can be pasted into a CommonMark doc (which all our docs are)

So HTML tables are the way to do tables in our doc system.

It doesn't have to be a table, though I agree it can be nice in many situations

I'm surprised the wiki doesn't work

There, the line-breaks </br> did not work in the right column. You can still see it in the history/previews: https://github.com/oilshell/oil/wiki/Oilshell-Usage-(The-table-missing-in-getting-started.md)/91ced3da6fe132a52f5057958d0c3b9296aeb02b

If submitted online contributions can't be tested (yet) directly in your toolchain, maybe it's possible you get/sync/fetch/pull? the published branch and check/apply/preview/adjust it out locally? (I'm not a software dev, so those git things are only hearsay for me.)

Oilshell in several places is awkward

I've polished things and just removed those. And at the top simply states: "The project provides..." (so no mismatching of any following terms).