sg: Fix usage and manual page

[stoeckmann]

The usage message of sg and its manual page contain different information. Synchronize both and document what sg's options do.

[stoeckmann]

Closing this PR due to chatter overflow. Based on these suggestions, someone who is actually willing to progress can find a solution. See #1460

[alejandro-colomar]

Closing this PR due to chatter overflow. Based on these suggestions, someone who is actually willing to progress can find a solution. See #1460

I'm actually willing to progress. I said I'm okay with the commits as they are. I'd just like to improve this with a fourth commit that makes it even better. The documentation, as you've improved it, still doesn't document the actual behavior: the synopsis doesn't say anything about -l. It is much much better than it was, but it is still confusing to a reader.

At least the paragraphs now are understandable, so I'm happy to merge this as is.

[stoeckmann]

The documentation, as you've improved it, still doesn't document the actual behavior: the synopsis doesn't say anything about -l. It is much much better than it was, but it is still confusing to a reader.

I assume that the different styles of usage messages and manual pages across the various shadow tools must be the reason why people stop using shadow where possible because they are confusing to them? Is it documented anywhere how these are supposed to look like or is a mixture of various styles actually what you want (in which case it doesn't make sense to "fix" this very one manual page, since it adds variation)?

At least the paragraphs now are understandable, so I'm happy to merge this as is.

You might want to adjust the su manual page then because it cannot be understandable either. At least, if you actually build and read it as a maintainer, since your distribution rightfully abandons shadow tools where it can.

[alejandro-colomar]

The documentation, as you've improved it, still doesn't document the actual behavior: the synopsis doesn't say anything about -l. It is much much better than it was, but it is still confusing to a reader.

I assume that the different styles of usage messages and manual pages across the various shadow tools must be the reason why people stop using shadow where possible because they are confusing to them?

I don't know. All of that predates my involvement in the project (and even in programming), and I'm not a distribution maintainer, so I don't know why distros prefer some binaries from shadow and some from other projects.

Is it documented anywhere how these are supposed to look like or is a mixture of various styles actually what you want (in which case it doesn't make sense to "fix" this very one manual page, since it adds variation)?

I'm not talking about style here. I'm talking about undocumented features. But as we discussed in the other PR, what should probably do is to change the behavior of sg(1) to align with that of su(1).

At least the paragraphs now are understandable, so I'm happy to merge this as is.

You might want to adjust the su manual page then because it cannot be understandable either. At least, if you actually build and read it as a maintainer, since your distribution rightfully abandons shadow tools where it can.

I have been wanting to fix the manual pages for a long time, indeed. It's just that the XML is too painful for me to do it.

I might eventually port them to man(7) source code and improve them from there.