
Mdoc(7) – semantic markup language for formatting manual pages - beefhash
http://man.openbsd.org/OpenBSD-current/man7/mdoc.7
======
brynet
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.

[http://undeadly.org/cgi?action=article&sid=20170304230520](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...](http://undeadly.org/cgi?action=article&sid=20150721180312&mode=expanded)

~~~
carussell
> more recently, markdown

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

~~~
tedunangst
It's very easy to write some plaintext and iteratively add mdoc markup. Trying
to do get it all right in one shot is probably a mistake. Most of the common
macros, like .Fa for function argument, are mneumonic.

~~~
carussell
That's besides the point. No one is ever going to _read_ mdoc, because it's
not meant for human consumption, outside of editing an mdoc file. This is not
true for markdown, where the raw form is as fit for consumption as the
rendered form.

~~~
tedunangst
I guess I don't see the problem. It's not meant for reading, so don't read it.

~~~
carussell
Man pages' source texts are not human readable.

If they were, that would bring good things.

This is the entire motivation behind my comment.

I don't know how I can be clearer here.

~~~
gbrown_
> If they were, that would bring good things.

Like what?

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

Slides - [https://www.openbsd.org/papers/eurobsdcon2014-mandoc-
slides....](https://www.openbsd.org/papers/eurobsdcon2014-mandoc-slides.pdf)

Video 1 -
[https://www.youtube.com/watch?v=csA7-SUtUcw](https://www.youtube.com/watch?v=csA7-SUtUcw)

Video 2 - [https://www.youtube.com/watch?v=ntf-
dNahJQc](https://www.youtube.com/watch?v=ntf-dNahJQc)

------
rwmj
At least at first glance, it looks like roff?

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...](https://raw.githubusercontent.com/libguestfs/nbdkit/master/docs/nbdkit.pod)
)

~~~
JadeNB
I think that it's less about YAML, and more about the capability to offer
semantic annotation. See, for example, brynet's post
([https://news.ycombinator.com/item?id=13834037](https://news.ycombinator.com/item?id=13834037)).

------
cat199
Original? pages concerning the format, later reimplemented in standalone
mandoc processor:

[http://modman.unixdev.net/index.php?sektion=7&page=mdoc&manp...](http://modman.unixdev.net/index.php?sektion=7&page=mdoc&manpath=4.4BSD-
Lite2)
[http://modman.unixdev.net/index.php?page=mdoc.samples&sektio...](http://modman.unixdev.net/index.php?page=mdoc.samples&sektion=7&manpath=4.4BSD-
Lite2)

------
daurnimator
I use pandoc ([http://pandoc.org/](http://pandoc.org/)) to be able to write in
markdown, and output to man pages.

See e.g. [https://github.com/daurnimator/lua-
http/blob/master/doc/Make...](https://github.com/daurnimator/lua-
http/blob/master/doc/Makefile#L45) (and the 'doc' directory in general)

------
eb0la
Looks more complicated than actualy it is. For instance .Sh is section header.
Easier to remember than it looks at first sight.

Also gives hints to text formatters that dump the doc to txt, console, ps, or
html.

