mdoc is the language used for all BSD system manuals, which is certainly more consistent than writing man(7)/roff source.
At least mandoc(1) lets you convert cleaner mdoc(7) into other formats used by other systems, including man(7). But also pdf/ps/html and more recently, markdown.
Not directly related, but the semantic hints in mdoc(7) allows some really nifty features to be implemented, like semantic searching, w/ internal man(1) jump targets using less :t.
I'd rather have a markdown-like notation for the source text itself. I imagine that if it were the norm for Unix-like systems to come with online documentation that were as trivially editable as a set of flat markdown files and also aimed for the benefits of brevity you get from short man pages and the depth of coverage of GNU info (without the pain of navigating due to the info viewer's Emacs-inspired keybindings), then most projects' docs would be far more complete and wouldn't find themselves wanting for contributors to write them.*
I'm totally flummoxed, therefore, by statements that markdown is "abominable" and more poorly designed than DocbBook, whose "syntax encumbers the source code to the point of making it unreadable".
Vanilla markdown is obviously unsuitable as a source language for man pages (unless you're willing to throw out the semantics), but mdoc would do well to take a page from the markdown philosophy. I.e., standardize a set of defacto constructs that resemble the types of formatting that people are already embedding in plain text and—crucially—resembles something that you could conceivably find yourself reading in "raw" rather than "rendered" form.
The idea that mdoc (or any similar macro-based formatting system) is human-readable is something that sounds like a joke, except that I know they're not joking. It may not be roff, but that doesn't mean it isn't still junk.
* I see the proliferation of sites like StackOverflow and Read the Docs as indicators of how the officially anointed docs are coming up short. (There's the ADHD, don't-want-to-RTFM, copy-and-paste brogrammer appeal behind those sites, too, but even accounting for that will show that there's something lacking about TFM.)
Not sure why this has come up on HN, I think I saw talk of markdown export support being added on the mailing list. Anyway people may want to check out the following presentation.
[+] [-] brynet|9 years ago|reply
At least mandoc(1) lets you convert cleaner mdoc(7) into other formats used by other systems, including man(7). But also pdf/ps/html and more recently, markdown.
http://undeadly.org/cgi?action=article&sid=20170304230520
Not directly related, but the semantic hints in mdoc(7) allows some really nifty features to be implemented, like semantic searching, w/ internal man(1) jump targets using less :t.
http://undeadly.org/cgi?action=article&sid=20150721180312&mo...
[+] [-] carussell|9 years ago|reply
I'd rather have a markdown-like notation for the source text itself. I imagine that if it were the norm for Unix-like systems to come with online documentation that were as trivially editable as a set of flat markdown files and also aimed for the benefits of brevity you get from short man pages and the depth of coverage of GNU info (without the pain of navigating due to the info viewer's Emacs-inspired keybindings), then most projects' docs would be far more complete and wouldn't find themselves wanting for contributors to write them.*
I'm totally flummoxed, therefore, by statements that markdown is "abominable" and more poorly designed than DocbBook, whose "syntax encumbers the source code to the point of making it unreadable".
Vanilla markdown is obviously unsuitable as a source language for man pages (unless you're willing to throw out the semantics), but mdoc would do well to take a page from the markdown philosophy. I.e., standardize a set of defacto constructs that resemble the types of formatting that people are already embedding in plain text and—crucially—resembles something that you could conceivably find yourself reading in "raw" rather than "rendered" form.
The idea that mdoc (or any similar macro-based formatting system) is human-readable is something that sounds like a joke, except that I know they're not joking. It may not be roff, but that doesn't mean it isn't still junk.
* I see the proliferation of sites like StackOverflow and Read the Docs as indicators of how the officially anointed docs are coming up short. (There's the ADHD, don't-want-to-RTFM, copy-and-paste brogrammer appeal behind those sites, too, but even accounting for that will show that there's something lacking about TFM.)
[+] [-] joepvd|9 years ago|reply
[+] [-] gbrown_|9 years ago|reply
Slides - https://www.openbsd.org/papers/eurobsdcon2014-mandoc-slides....
Video 1 - https://www.youtube.com/watch?v=csA7-SUtUcw
Video 2 - https://www.youtube.com/watch?v=ntf-dNahJQc
[+] [-] rwmj|9 years ago|reply
I use POD to write man pages, which is a widely supported, reasonably lightweight markup that generates nice looking man pages. (Example: https://raw.githubusercontent.com/libguestfs/nbdkit/master/d... )
[+] [-] JadeNB|9 years ago|reply
[+] [-] cat199|9 years ago|reply
http://modman.unixdev.net/index.php?sektion=7&page=mdoc&manp... http://modman.unixdev.net/index.php?page=mdoc.samples&sektio...
[+] [-] daurnimator|9 years ago|reply
See e.g. https://github.com/daurnimator/lua-http/blob/master/doc/Make... (and the 'doc' directory in general)
[+] [-] eb0la|9 years ago|reply
Also gives hints to text formatters that dump the doc to txt, console, ps, or html.