DOC: clarify description of the "install" interface to reflect its convoluted behavior

[yarikoptic]

Prompted by #7441 and might even close it if @asmacdo acdo agrees that it does.

I also changed "recommended" to "possible" in the paragraph about 'description' since I think we converged in some discussion in datalad-handbook that it is typically not recommended.

Now --help would look like

Usage: datalad install [-h] [-s URL-OR-PATH] [-d DATASET] [-g]
                       [-D DESCRIPTION] [-r] [-R LEVELS]
                       [--reckless [auto|ephemeral|shared-...]] [-J NJOBS]
                       [--branch BRANCH] [--version]
                       [URL-OR-PATH ...]

Install one or many datasets from remote URL(s) or local PATH source(s).

This command creates local sibling(s) of existing dataset(s) from
(remote) locations specified as URL(s) or path(s). Optional recursion into
potential subdatasets, and download of all referenced data is supported.
The new dataset(s) can be optionally registered in an existing
superdataset by identifying it via the DATASET argument (the new
dataset's path needs to be located within the superdataset for that).

If no explicit -s|--source option is specified, then all positional
URL-OR-PATH arguments are considered to be "sources" if they are URLs
or target locations if they are paths. If a target location path
corresponds to a submodule, the source location for it is figured out
from its record in the `.gitmodules`. If -s|--source is specified,
then a single optional positional PATH would be taken as the
destination path for that dataset.

It is possible to provide a brief description to label the dataset's
nature *and* location, e.g. "Michael's music on black laptop". This helps
...

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: -0.18 ⚠️

Comparison is base (684c842) 91.51% compared to head (3fa1405) 91.34%.

Additional details and impacted files

@@            Coverage Diff             @@
##            maint    #7445      +/-   ##
==========================================
- Coverage   91.51%   91.34%   -0.18%     
==========================================
  Files         325      325              
  Lines       43392    43390       -2     
  Branches     5819        0    -5819     
==========================================
- Hits        39711    39635      -76     
- Misses       3666     3755      +89     
+ Partials       15        0      -15     

Impacted Files	Coverage Δ
datalad/distribution/install.py	98.86% <ø> (ø)

... and 25 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[yarikoptic]

we need a release with prior PR merged/resolving the issue. So I marked this for a candidate to kick out the release

[asmacdo]

+1 this closes my issue.

[yarikoptic]

@mih or @adswa - any blessings (like clicking "Merge") or concerns? if none - I would merge tomorrow.

[yarikoptic-gitmate]

PR released in 0.19.2