Fix examples and documentation to correctly escape or quote shell cha…

[sptramer]

…racters where required. [#4876]

Simplify user-supplied values by marking them as ${...} variables.

---

This checklist is used to make sure that common guidelines for a pull request are followed.

General Guidelines

• The PR has modified HISTORY.rst describing any customer-facing, functional changes. Note that this does not include changes only to help content. (see Modifying change log).

Command Guidelines

• Each command and parameter has a meaningful description.
• Each new command has a test.

(see Authoring Command Modules)

[azuresdkci]

View a preview at https://prompt.ws/r/Azure/azure-cli/5066
This is an experimental preview for @microsoft.com users.
(It may take a minute or two for your instance to be ready)
Email feedback to 'azfeedback' with subject 'Prompt Feedback'.

[tjprescott]

I see some examples like ${this} and others like {$this}. Are we intending this to be bash-specific variable notation, or is this more of a doc markup issue?

[sptramer]

@tjprescott This is probably a sed issue on my part. I am intending this to be bash-style variable notation to both make it clear that these are user-provided values and to allow for easier cut-and-paste from examples. As part of fixing the PR I may standardize the variable names into CAP_SNAKE_CASE instead of CamelCase.

[tjprescott]

@sptramer thanks. Before we had discussed avoiding shell-specific nomenclature or at the very least calling it out. This would make many examples that would work in bash or CMD now bash-specific. I'm not necessarily against that--I just want that to be a deliberate decision. I agree with the CAP_SNAKE vs. CamelCase.

[sptramer]

@tjprescott I believe that we have standardized on the idea that examples and inline code presented in documentation is meant to be bash-style only since we have multiple examples which do not work on all platforms. Double-check with @JasonRShaver on that. If we'd like to keep things platform-agnostic I can reformat ${USER_VALUE} into something user-supplied but not system-specific by removing the leading $.

[tjprescott]

I'm okay with the bash specific if Jason is. But I would like use to resolve the ${foo} or {$foo} references in the PR :)

[sptramer]

@tjprescott On it and it should be fixed by EOB today.

[sptramer]

@tjprescott - Went ahead and fixed things. Right now I'm leaving off the $ identifiers because I want to make sure that this is a good docs strategy, and there isn't time to fix everything (even piece by piece.) This should be good for now. There's not currently a consistent way to present arguments or object ID paths in the documentation anyway and one needs to be designed.

[sptramer]

@tjprescott CI is failing due to not having version-bumped the command modules, but in the past we have agreed that _help.py changes alone should not require a version bump. Merging is blocked however, due to the versioning issue. What's the recommendation?

[tjprescott]

Due to recent changes to the CLI core, you will need to rebase your changes against the latest in the dev branch.

[sptramer]

@tjprescott Rebased and updated.

[tjprescott]

@derekbekoe can the version check script be updated to ignore modules whose only changes are to _help.py?

[tjprescott]

Can you rebase the latest dev changes? Should fix the issue with role version.