gh-125562: Update to documentation for exec* functions

[jlownie]

gh-125562: Update to documentation for exec* functions

This PR includes the following changes:

• Moving the documentation of the first argument to the exec* functions from the start of the Process Management section to the documentation of the exec* functions.
• Adding of headings within the exec* documentation.
• Moving the final paragraph of the exec* functions documentation to the "Location of the executable", which is where it is logically relevant.
• Adding links between the system(), execl and spawnl functions.
• Adding links to the subprocess module.

---

📚 Documentation preview 📚: https://cpython-previews--125565.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[vadmium]

Putting the bracketed deprecation paragraphs at the top of each description is not great. Maybe move them down, if needed at all.

[vadmium]

Since you already edited the second sentence, I’ll point out that often the first word on a command line is indeed the program name (e.g. shell command “echo bar”) so saying “not an argument . . . typed on a command line” is confusing if not wrong.

[jlownie]

I'm open to any suggestions as to better wording? That phrasing came from the original documentation, I agree it's not great but I found it difficult to come up with something better that I was confident was correct.

[vadmium]

Here is my attempt:

The exec functions take a list of arguments for the new program. The first of these is by convention the command name from the command line, rather than an argument to the command, and becomes argv[0] passed to the main function of a C program. For example, os.execv('/bin/echo', ['echo', 'foo', 'bar']) would only print foo bar; the echo argument would seem to be ignored.

[vadmium]

I’m not sure breaking the paragraph works. “This” refers to the name of the program (topic of the last sentence of the last paragraph), not the overall Program Arguments heading.

[jlownie]

I decided to retain the paragraph break and instead reworded the first sentence in the paragraph. I'm not entirely sure what the documentation is getting at with the second sentence in the paragraph. I'm open to further suggestions for improving this paragraph - I feel it could be improved but I'm not sure how.

[vadmium]

Here is my attempt:

The exec functions take a list of arguments for the new program. The first of these is by convention the command name from the command line, rather than an argument to the command, and becomes argv[0] passed to the main function of a C program. For example, os.execv('/bin/echo', ['echo', 'foo', 'bar']) would only print foo bar; the echo argument would seem to be ignored.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[jlownie]

I forgot about this but got a reminder today, and I was able to fix the problems with it. All the checks are passing now, so it's ready for review again.