Comments (3)
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
.
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.
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.
Related Issues (17)
- Have method for file path HOT 3
- Have "source" section
- Add DESCRIPTION section
- API design HOT 2
- The README example does not compile HOT 1
- Support for custom sections? HOT 3
- Improve `exit status` section HOT 5
- Add version/date API HOT 1
- Add examples API HOT 1
- Format example in README to show bold HOT 1
- Document full use-case (e.g., `build.rs` script) HOT 5
- Options with no "="
- update to roff 0.2? HOT 1
- Accept more types of positional arguments
- Design: how should we display subcommands? HOT 1
- Move clap v3 -> man glue code to clap_generate HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from man.