Which sections should a man page have? about man HOT 3 OPEN

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

from man.

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.

*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.

from man.

"Synopsis" is actually not quite implemented because you are supposed to, in systems that take man pages seriously (i.e. old school Unix and current BSD), give a big overview of what you do. So instead of "prog [options] files...", you write "prog [-AavV46xy] [-e expr] files...". Folks these days don't see it because (sigh) everyone uses a GNU-influenced system, and GNU has always treated man as an afterthought with help2man and DocBook.

I mean, the whole "structured" bit in the crate description can be heavily debated once you see what mdoc(7) (of 1977, 4.4BSD!) has brought to this barren language originally dominated by man(7). mdoc(7) really shines once you run mandoc -T html on it, with every flag given an anchor, every semantic thing given a class &c.

The OpenBSD mandoc people have produced long forms of the mdoc(7) documentation at https://mandoc.bsd.lv/mdoc/. There are whole pages on Synopsis and Section order – an extremely well-written and useful resource. And it's all written in mdoc(7) just to show what the language can do.

Generating mdoc is tough if you are starting from a "semantics-less" format like Markdown or Asciidoc. It is possible in rust-man with the expanded access to flags, but the restructuring needed will take a lot of work: a LOT MORE macros are called, many of them inline requiring No or a "delimiter" to close. You may need changes in the roff crate to help with tracking these states, as unhappy as it is with being constrained to specific macro packages.

It would be a cool feat for the crab crowd though, seeing it might just be the first mdoc(7) code generator, ever. Might deserve a rust rave or something if you get it done.

from man.