In summary, the launcher documentation needs to be extended as follows:

    * Include an example of a shebang with a normal Windows path:

      #!"C:\Program Files\Python310\python.exe"

      Highlight the importance of quoting paths that contain spaces.
      Also, quoting ensures a real filesystem path will never
      mistakenly match a virtual command. 

      Due to questionable design in the launcher, it will still try 
      searching [1] for part of the name up to the first space, such
      as "C:\Program", but, presuming the path is quoted, the search
      will at least never succeed since double quotes are not
      allowed in filenames.

    * Show how to define custom commands in py.ini:

      [commands]
      pypy3=C:\pypy3.7\pypy3.exe

      The launcher is limited to 100 commands since it uses a hard-
      coded array size.

      Note that regular CLI commands take precedence. In other words,
      if a command name is found in the standard search path [1], then
      the search result is used instead of the value defined in py.ini.

      This is buggy behavior that should be fixed. When reading py.ini, 
      it should not search for the command. The find_command() function
      needs a `search` parameter to support this. If it's false, 
      find_command() should only check its `commands` array.

    * Explain that the Unix path prefixes "/usr/bin/env ", 
      "/usr/bin/", and "/usr/local/bin/" are ignored when matching
      a command name -- except for the already documented case of
      "/usr/bin/env python" (without a version spec).

      Except for reserved "python" commands, currently any command
      name will be searched for [1], with or without the
      "/usr/bin/env " prefix. For example:
     
      #!name

      The launcher will search for "name.COM", "name.EXE",
      "name.BAT", and so on.

      This is buggy behavior that should be fixed. The skip-prefix 
      feature needs to be smarter. The launcher should only search
      the filesystem for commands that use the "/usr/bin/env "
      prefix. The find_command() function needs a `search`
      parameter to support this, as mentioned above.


Bugs mentioned in this message need a separate issue. I don't know to what extent questionable behavior should be documented, with warnings about security and misbehavior. In practice it seems that most users limit themselves to a restricted subset of the launcher's capabilities, and never stray from the well-worn path. So I don't want to needlessly scare or worry people. But the buggy behavior SHOULD be taken seriously and fixed.

---

[1] The launcher uses the system's default non-safe search path
    for data files. It should enable the safe search via

    SetSearchPathMode(BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE)

    The non-safe search path includes the application directory
    (of the launcher); the current directory; the System32,
    System and Windows directories (unsafe because they're after
    the current directory); and the directories in the PATH
    environment variable.

    If there's no "." in the name, the launcher tries searching 
    for the name plus each extension that's listed in the PATHEXT 
    environment variable. To search for a filename that has no
    extension, add a trailing dot to the command name, e.g.
    "spam.".