doc/getting-started: basic sort, add usage table

[bar-g]

Fixes: #1142

I now did everything from the things you mentioned in the issue as far as I could through the web-interface. In particular the markdown-within-html-table part.

Please test and adjust with your own site building toolchain.

[andychu]

Hm in reading over the doc, I agree there is something that could be improved here....

But yeah I would lean toward making it doc/usage-table.md as mentioned in the bug.

Or maybe I would change my mind if I could see the output. As mentioned I think we need a way for you to upload a preview

I do that here https://www.oilshell.org/preview/doc/error-handling.html

Another way to do that is to have a continuous build task to do it

#1038

[bar-g]

Concerning the re-arranged text. Have you tried the "view file" under "files changed"?
https://github.com/oilshell/oil/blob/be671fe85f92bd594011b79e65639cacb1d52ceb/doc/getting-started.md
I think the CommonMark rendering would still need to be tested separately, though.

[bar-g]

The link I posted to the preview seems static and not showing the last revision. But the latest previews are available in the three dot (...) menu of the changed files.

[bar-g]

Well, to get something moving, what about moving the config/setup section into the INSTALL doc?

Preview here:
https://github.com/oilshell/oil/blob/08c1b92f85bfbd509bd06963e31e2085f4a30bc7/doc/getting-started.md

[andychu]

Hm how does that help?

As mentioned I think the information in the table is good and should be somewhere ... There are lots of options

• the wiki if we can get tables to work, and then link from this doc
• a separate doc/usage-table.md, and then link from this doc
• inline in this doc

But I want to see the rendered HTML. It is not hard to build

I think I have seen tables in wikis too, there is probably some way to make it work

Maybe "curl" from Github's API will also allow rendering an issue table as HTML

[bar-g]

how does that help?

Moving install details to where they belong will move the usage info nearer to the top.

What's the problem with this preview?
https://github.com/oilshell/oil/blob/08c1b92f85bfbd509bd06963e31e2085f4a30bc7/doc/getting-started.md

Doesn't it provide you an overview about he changes, that you can compare?
If it's about testing in your toolchain, can't you paste the markdown-whithin-html-table (source) into your toolchain to check its rendering?

[bar-g]

1. It has to be tested and previewed
2. The prose was also awkward / lengthy

Have you tried to open the online-editor? I checked "maintainers can edit", it might look better as the diff view.
https://github.com/bar-g/oil/edit/patch-2/doc/getting-started.md?pr=%2Foilshell%2Foil%2Fpull%2F1151

Unfortunately I'm not able to help with 1., about 2. I have tried to improve on what you already commented, would need new ideas/pointers.