su.1: Try to clarify confusing -c options

[0mp]

Summary

su.1: Try to clarify flags handling

The -c flag to su(1) seems to be particularly confusing, especially to users
who are not used to the convention of providing flags before arguments to
utilities. Try to document various ways su(1) may interpret flags,
especially -c.

PR:	250405

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=250405

[bcr]

Minor writing style nit.

usr.bin/su/su.1

221

s/your/the/

(discouraging the use of "you")

[0mp]

usr.bin/su/su.1

221

Oh yeah, right. I think I'd like to tackle this one in another revision as the whole manual is using you/your all the time currently :(

What do you think?

[bcr]

Sure, I'm fine with a follow-up commit to fix those.

[0mp]

Hmmm, I'm a bit puzzled, as after reading the existing version of the manual, it is possible to figure out the difference between the -c flags... I am not if adding extra examples outside the EXAMPLES section helps...

[fernape]

In D26941#601252, @0mp wrote:

Hmmm, I'm a bit puzzled, as after reading the existing version of the manual, it is possible to figure out the difference between the -c flags... I am not if adding extra examples outside the EXAMPLES section helps...

Since phabricator add me to the mix, I am going to participate :-)

I would add those two examples to the EXAMPLES section one right after the other. I think examples in the middle of a description are easier to miss.

I would also write all the description for the examples before the commands and not after. Specially since there are sentences like "same as above" and right above we have the command for the current example, not the previous one (which is two paragraphs above).

[0mp]

In D26941#601352, @fernape wrote:

In D26941#601252, @0mp wrote:

Hmmm, I'm a bit puzzled, as after reading the existing version of the manual, it is possible to figure out the difference between the -c flags... I am not if adding extra examples outside the EXAMPLES section helps...

Since phabricator add me to the mix, I am going to participate :-)

Thank you!

I would add those two examples to the EXAMPLES section one right after the other. I think examples in the middle of a description are easier to miss.

Good point, perhaps I should do that.

I would also write all the description for the examples before the commands and not after. Specially since there are sentences like "same as above" and right above we have the command for the current example, not the previous one (which is two paragraphs above).

Hmm, at this point I guess it is inevitable to just rewrite the EXAMPLES section completely with good examples.