Which sections should a man page have?

[yoshuawuyts]

I'm thinking almost all sections should be optional, but we want to somewhat restrict which sections are possible. Which sections should we have?

From what I've seen, we should probably support the following sections:

Required

This should probably be part of the ::new() constructor?

• Name: name of the project (to be displayed at the top)
• Version: version (to be displayed at the bottom)

Optional

• Synopsis: quite similar to the short output of -h in CLIs
• Description: what does this CLI do?
• Authors: who wrote this?
• Flags: which CLI flags can be passed?
• Options: which CLI flags that require arguments can be passed
• See Also: related projects
• Files: which files does this project use (e.g. ~/.ifconfig)
• Exit Codes: what are the possible exit codes?
• Environment Variables: which env vars are checked?

[Screwtapello]

The semantic-markup mdoc(7) format lists the following sections:

NAME          Name section, should include the ‘.Nm’ or ‘.Fn’ and the ‘.Nd’ macros.
SYNOPSIS      Usage.
DESCRIPTION   General description, should include options and parameters.
RETURN VALUE  Sections two and three function calls.
ENVIRONMENT   Describe environment variables.
FILES         Files associated with the subject.
EXAMPLES      Examples and suggestions.
DIAGNOSTICS   Normally used for section four device interface diagnostics.
ERRORS        Sections two and three error and signal handling.
SEE ALSO      Cross references and citations.
CONFORMING TO
              Conformance to standards if applicable.
HISTORY       If a standard is not applicable, the history of the subject should be
              given.
BUGS          Gotchas and caveats.
other         Customized headers may be added at the authors discretion.

groff_mdoc(7), under the heading "A MANUAL PAGE TEMPLATE" includes an even longer list of suggested header names:

• NAME
• SYNOPSIS
• DESCRIPTION
• IMPLEMENTATION NOTES
• ENVIRONMENT
• FILES
• EXIT STATUS (returned to the shell)
• EXAMPLES
• DIAGNOSTICS (things printed to stderr)
• COMPATIBILITY
• SEE ALSO
• STANDARDS
• HISTORY
• AUTHORS
• CAVEATS
• BUGS

[codesections]

I've compiled the sections listed above into the table below, which lists those sections man already implements and then divides the remainder into higher and lower priorities (in my view, at least). My thought with the lower priority items is partly that they don't have (much) custom formatting, so they would be fairly easy for users to implement with the .custom API until they're implemented in man.

Implemented	High Priority	Lower Priority
Name	Version	See Also
Description	Examples	Environment Variables
Synopsis		Reporting Bugs
Authors		Bugs
Flags		License
Options*
Exit Codes

*As discussed in #7, the options implementation does not yet handle optional arguments correctly.

Based on the above, I plan to open issues on the Version and Examples sections with proposed APIs soon and prioritize those as the next two sections to implement. But please let me know if anyone feels other sections should be a higher priority.