Comment by detaro
8 years ago
Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.
8 years ago
Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.
Why would you want a manpage that doesn't have the structure of a manpage? If every other manpage has one structure, you want yours to have another? What's special about yours?
The consistency is not an accident and my personal experience is that the format works well.
The point is exactly that people do not want something like a man page, so they make their own thing that's not like a man page, and the suggestion "go contribute to manpages instead" isn't a good one, because it would mean making bad man pages (or not fixing the issue people have). If aspects are useful for the man pages (e.g. to make better examples sections), they can still be pulled out and added there as well.
"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.
Many of these pages would make fine EXAMPLES sections for the corresponding man pages without compromising the overall structure.
It's more important that there is convention than that the convention is optimal.
If the problem is that manuals aren't user friendly enough to new users and should have more examples of common tasks then they belong in the EXAMPLES section.
There's nothing that says you need to stick to the conventional sections either. A TUTORIAL section wouldn't be out of place.