ps.1: Revamp: Explain general principles, update to match reality

[olce]

Summary

The preamble has been revamped to give a thorough overview of the
different aspects of the ps(1) command in the following separate
paragraphs:

1. What it outputs.
2. Which processes are listed.
3. Which information is displayed by process.
4. How lines are sorted.
5. Considerations about the (mostly broken) output width.
6. Backwards compatibility features.

Fix or expand the description of several options to match their actual
behavior.

Expand the STANDARDS section, noting the options conforming to POSIX and
those that do not (but may be changed to), as well as current diverging
behaviors.

Expand the BUGS section with a thorough description of other known
problems.

While here, document the POSIX-specified '-A' option. We have been
supporting it since 2004 (commit "Support more POSIX/SUSv3 options:",
a4c8a745a85b18d7, r127499) and it has been standard for longer. It
seems now highly unlikely we will ever want to use it for any other
purpose, so just stop trying to hide it.

While here, re-order flags according to mdoc(7)'s prescription. Given
the current state, this also requires less changes than, e.g., putting
all uppercase flags first.

While here, move the detailed specifications of keywords from the
DESCRIPTION to the KEYWORDS section.

While here, fix the formatting of some references to keywords.

[ziaee]

Wow, thanks for doing this! Just some first thoughts, I can help review more detailed after work!

bin/ps/ps.1

47

Line 46 and 47 are switched.

Does it make sense fix the program usage output in this commit too, and then we could MFC that doc bugfix without usage change to stable branches?

[olce]

bin/ps/ps.1

47

Absolutely. This has been changed in my local commit.

That said, I do hope that the whole series (or almost) will get reviewed fast enough to be MFCed into stable/14 for 14.3.

[ziaee]

I don't think we're allowed to make changes that change existing default behavior in stable?

Edit: Not saying that I think we should or shouldn't change it for the future, breaking POLA is bad but increased posix compliance is good so I don't know how I feel yet.

[olce]

In D49605#1131247, @ziaee wrote:

I don't think we're allowed to make changes that change existing default behavior in stable?

Edit: Not saying that I think we should or shouldn't change it for the future, breaking POLA is bad but increased posix compliance is good so I don't know how I feel yet.

Fixing bugs is generally OK, although we should be careful. In this series, I've refrained for making changes that would clearly violate POLA, but some may still be considered a bit too risky to MFC, we'll see.

[kib]

If adding so detailed descriptions, some discussion of the 'command and arguments' is needed. In particular, that the strings are first taken from execve(2), then potentially overwritten by the process. Also some words about cached p_comm and args, esp. if attempt to find userspace strings failed.

bin/ps/ps.1

117

at least this is how I accustomed to read such statements

120

I would not say associated there.

[olce]

bin/ps/ps.1

117

Apparently, "consist in" is used to describe essential qualities, rather than composition as "consist of". It probably also works in this context, which is a definition. But "consist of" seems more appropriate.

Changed it to "consist of" in my local commit, as well as another similar occurrence near the top of the manual page.

120

So what would you say instead? "associated" is the original word. I did not change it because I find it relatively vague and don't think the prologue is a proper place to mention the details of how this information is produced. "attributed" maybe?

I can link to the notes about how the command is determined.

[emaste]

bin/ps/ps.1

75

I'm not sure what this -U with the real user ID text means

205–207

I don't understand this "as -U would determine" text

[olce]

bin/ps/ps.1

75

This is intended to mean "it is as if you had explicitly specified -U with the real user ID of the ps process and -X".

I've reformulated.

205–207

I intended to mean something like "your own processes are those that -U with the real user ID of the ps process would select". But that's probably too much detail, and this text is anyway removed in D49623 after -U's change in behavior.

I've reformulated in a simpler way.

[olce]

• Address comments.
• Move the keyword specification list under the KEYWORDS section, after the first reference list.
• Move the text explaining the printed command, initially after the keyword specification list, into a new "command" keyword entry in this list.
• Remove the "<exiting>" part in the printed command explanation (not true today). Properly quote the "ucomm" keyword references there.
• Change the short description for "ucomm".
• Rework a bit the description for '-a'.
• Fix some newly-introduced references to "command" (were misspelled as "commands").
• Tiny changes in the paragraph about '-g' in the STANDARDS section.
• Fix order of some options (swap '-d' and '-D', '-j' and '-J').