doc/upgrade-breakage: Carefully adjust to the two available heading levels

[bar-g]

Focused only on a helpful documentation TOC .

See the individual commits for steped details.

Unknown: Is =foo as first-word, is too similar to = foo still relevant after this: dc51f5b

[bar-g]

Hm, I may understand you might have tried to sort the "syntax now parsed, if not quoted" items from most to least probable?
So things like keyword that are most of the time ok (actually silently enabled in osh, by default already), last? (-> I'll change that back.)

Do I interpret it correctly that bare assignment issue (= argument quoting) will now only apply "within blocks"?

[bar-g]

BTW As the (...) subshell to forkwait {..} stuff seems to be discouragement/deprecation, not breakage, that might be shortened/left to the link mentioned under "summary"?

[andychu]

As mentioned in the previous thread, I don't agree with promoting those items to a top level heading.

It seems like "making a mountain out of a mole hill", i.e. spending a lot of space on something that's minor.

Also I don't think most of these are wording improvemenets, e.g. the heading

"Syntax Parsed, if not quoted (usually ok)"

is very awkward and hard to read.

[andychu]

I'm still sort of interested in the table change on getting-started, but there were 2 problems there:

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

If there was only one problem, I would probably be more excited and help get it into shape ... But since there are 2 different problems, I will just work on all the other important stuff (like hiring the compiler engineer) until something closer comes along, or someone else hits it, etc.

[bar-g]

It seems like "making a mountain out of a mole hill", i.e. spending a lot of space on something that's minor.

Hm, though my own feeling, when first reading the doc, and having to "spoon collect" the docs, though, has been much more like "what the heck, there's stuff being hidden and not told, to make it look less". Thus rather getting wary about ugly things just waiting to break scripts.

That's where the motivation to fix this comes from. It made me very glad to see the things are harmless, get a nice error message, and are really easy to fix.

"Syntax Parsed, if not quoted (usually ok)" is very awkward and hard to read.

Sure, if you tell me what you find awkward like now, that should be easy for us to work out. And I know you can do nice and short wording, better than me. But naturally, short things may sometimes be understood differently, and could end up better after slight improvements.

For example, what I wondered about was the "more"in "More Quotes May Be Needed" -> how many more, yet?

What about "Some Quotes May Be Needed"? Maybe even adding (in a few/rare occasions)?

[bar-g]

(The general problem with too short wording seems to be that it can create more questions than answers for people not knowing as much about it as you do.)

[bar-g]

Ok, found the forkwait and cd block idioms and examples are properly mentioned in: https://www.oilshell.org/release/latest/doc/idioms.html (EDIT: Which is linked at the end)

Better to simply remove those from upgrade-breakage, to not distract/confuse readers, and end up providing a concise overview?

[bar-g]

After quite some refinements and shortenings, I think it has now started to be a listing that can be shown (linked to) "with a straight face".

[bar-g]

A thing that seems to be contradicting and might need your attention: Extended Globs are disabled by Simple Word Evaluation, but then ,(...) is a substitute for the @(...) ext. glob?

[bar-g]

Why not check how your doc actually answers its question. Just some. Where your document does not list simple word eval (splice/glob/maybe) the document is incomplete, vague at best (no thanks/know-how to use later), where it mentions the oil:upgrade group it's redundant to the initial statement, where it says unconditional it's proofs wrong its "you don't need to read this for osh". The parts dealing with forkwait and blocks are not breakages at all. But I've now read enough feedback in the wild already complaining about that state of the "docs" not giving a proper answer, to know this can't be unknown to you.