Add task/usage table to "getting-started" doc

bar-g commented 2 years ago

The usage table was temporarily in the wiki, but didn't render well there: https://github.com/oilshell/oil/wiki/Oilshell-Usage-(The-table-missing-in-getting-started.md)

The newest version (html table with markdown text) is in: https://github.com/oilshell/oil/pull/1151

Usage (as osh and oil)

Task	Usage
Running an existing script as initially written for other shells. * Usually not even minimal quoting/spacing adjustments needed. (Adjustments may only be required due to implementing the "Common Subset" of consistent and sane shell execution compatibility. For example, if a script was using an inconsistent associative array pattern, or relied on dynamic parsing.) NB: By default, basic Oil language features without a side-effect beyond occupying namespace do already work as well (e.g. `const`/`var`/`setvar` incl. Oil expressions, `read --line/all/qsn/-0/...`, `write`, etc). So, these only break in other shells if not shipping a fallback.	Execute script in osh interpreter: `osh my.sh` Or, adapt script, and let it begin with: `#!/usr/bin/env osh`
...and, lint shell fragilities. Improved scripts will run with less errors in other shells. NB: The example on the right enables all strict options at once, but individual strict_ options allow fixing issue by issue.	Add a line near the top of the script, to set a shell option with error fallback (keep #!/shebang): "shopt --set strict:all 2>/dev/null \|\| true" After that execute the script in osh: `osh my.sh`
...and, allow adding new Oil language syntax. Only a minimized amount of legacy code will need adjustments. However, adding new syntax/semantics to a script will drop compatibility with other shells. (The adjustments needed in legacy code should mostly be just quoting/spacing, for disambiguation. Except, the requirement for proper error handling, and to add explicit split/glob functions to variables due to Simple Word Evaluation default. Of course only where variables were originally left correctly(!) unquoted and split/globbed.)	Adapt script to begin with: `#!/usr/bin/env osh` `shopt --set oil:upgrade`
Coming pretty close to the Oil interpreter. (Intersection of osh & oil & strict.)	`#!/usr/bin/env osh` `shopt --set oil:upgrade strict:all`
Using all of the Oil interpeter. Implements all positive features of classic shells, compatibly. All identified pitfalls removed. * Gracefully adding the best from Python, JavaScript and others. (Everything parsed as Oil syntax. Only unavoidable Oil language warts remain.)	Adapt script to begin with: `#!/usr/bin/env osh` `shopt --set oil:all` Or, simply use: `#!/usr/bin/env oil`

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 https://github.com/oilshell/oil/issues/1127#issuecomment-1133750439, 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.

word	meaning
Oilshell	project, and the muli-mode interpreter it creates (oilshell contains both words oil and osh)
osh	interpreter mode to support "other shell"s scripts
oil	new language and interpreter mode

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).

bar-g commented 2 years ago

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

bar-g commented 2 years ago

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?

andychu commented 2 years ago

Hm I don't understand the question ...

bar-g commented 2 years ago

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?

andychu commented 2 years ago

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

andychu commented 2 years ago

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.

bar-g commented 2 years ago

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: -_)

andychu commented 2 years ago

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"

bar-g commented 2 years ago

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?

bar-g commented 2 years ago

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

bar-g commented 2 years ago

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. ...

bar-g commented 2 years ago

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.)

bar-g commented 2 years ago

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 https://github.com/oilshell/oil/issues/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 (https://github.com/oilshell/oil/pull/1151)
and linking a usefull page that lists all deprecations and cutbacks when upgrading from other shells to oil https://github.com/oilshell/oil/pull/1145

andychu commented 2 years ago

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

andychu commented 2 years ago

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 :)

bar-g commented 2 years ago

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.

andychu commented 2 years ago

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

bar-g commented 2 years ago

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.)

bar-g commented 2 years ago

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).

oils-for-unix / oils

Add task/usage table to "getting-started" doc #1142

Usage (as osh and oil)

Related