Improve documentation of global script options

[ehmicky]

This improves the documentation related to sharing options with $.

Unfortunately, users cannot just do:

import {$} from 'execa';
$ = $(options);

Because imports are const.

Doing the following:

import {$} from 'execa';
const $$ = $(options);

Requires renaming all $ to $$ in the file.

The following does not require any renaming:

import {$ as $$} from 'execa';
const $ = $$(options);

I've tried thinking of a better pattern, but could not come up with one. :/

[sindresorhus]

It may be less confusing to do this, since we already use $$ for a different purpose.

import {$ as $_} from 'execa';
const $ = $_(options);

[ehmicky]

$_ sounds good to me since it makes it clearer that is no different than $. 👍

For the other places where we are using $$, are those purposes different? 🤔 We currently document creating $$ as a new $ with bound options. We could draw a distinction between whether this new $ will be used in the whole script ("global" options) or only a few commands ("shared" options), but in the end, it is quite similar and uses the same method.

In other words, maybe we should replace all $$ by $_ in the documentation?

[tommy-mitchell]

I like the distinction between a global $ and a local $$. I use them separately here: https://github.com/tommy-mitchell/listr-cli/blob/main/src/tasks.ts

[ehmicky]

Thanks for your input @tommy-mitchell and @aaronccasanova, let's go with what you suggest:

• global options: import {$ as $_} + const $ = $_(options)
• shared options: const $$ = $(options)

In the end, those are just variable names, and users could use different ones, but it's nice to have a convention.

I have updated the PR accordingly.
@tommy-mitchell and @aaronccasanova please feel free to review this PR if you want, thanks!

[ehmicky]

This file also includes an example of const $$ = $(options) for shared options. It shows the following text, which did not need to be changed:

This can be used to either:
  - Set options for a specific command: `$(options)`command` `
  - Share options for multiple commands: `const $$ = $(options); $$`command`; $$`otherCommand`;`