
Mandoc: becoming the main BSD manual toolbox [pdf] - fcambus
http://www.openbsd.org/papers/bsdcan15-mandoc.pdf
======
kaolinite
As the author of a fairly popular manual viewer for iOS[1], I was shocked when
building the documents at the state of the tools and the availability of
documentation for man. You would think that such a widely used command would
have tonnes of information, formatting tools, parsing libraries, etc, plus
articles and such - but surprisingly, there isn't that much available. Of the
libraries that I found, many of them only supported certain formats or had
strange bugs.

So, any improvements made to man are very much welcomed! I do feel, however,
that a new format might be the best way to go - possibly something based
loosely on Markdown or (my personal preference) JSON. I feel that if we had a
more structured manpage format, we could do a lot more with it. I was hoping
in my app, for example, to be able to pull out commands (e.g. enter "ls -lh"
and it'll highlight the information for "-l" and "-h".) It is possible
([http://explainshell.com/](http://explainshell.com/) does it really nicely)
but it would be far easier with a nicely structured format.

[1] [https://itunes.apple.com/us/app/manuals-linux-bsd-
manpages/i...](https://itunes.apple.com/us/app/manuals-linux-bsd-
manpages/id957578357?ls=1&mt=8)

~~~
anjbe
> So, any improvements made to man are very much welcomed! I do feel, however,
> that a new format might be the best way to go

This is actually already the case. The original man(7) language (actually a
set of macros for troff) has been around since the early 70s and was part of
Unix since the beginning. It’s a simple language but entirely
presentation‐focused, so it’s not helpful for semantic manipulation.

Modern manpages should be written in mdoc(7), another troff macro set that’s
both more semantic and more expressive than man(7). mdoc(7) was first
developed in 1989 for BSD and has been the standard documentation format there
ever since, and is fairly common in Linux software as well (although there’s
still a large contingent using the old, non‐semantic man(7) macros).

A lot of mandoc’s power comes from the semantic ability of mdoc(7) manpages,
including the ability to search by flags/options/environment
variables/whatever, and the ability to convert to semantic HTML5. Ingo didn’t
cover so much of that in this talk, but he has in some other talks:

[http://www.openbsd.org/papers/eurobsdcon2014-mandoc-
slides.p...](http://www.openbsd.org/papers/eurobsdcon2014-mandoc-slides.pdf)
[http://www.openbsd.org/papers/bsdcan14-mandoc.pdf](http://www.openbsd.org/papers/bsdcan14-mandoc.pdf)
[http://www.openbsd.org/papers/bsdcan11-mandoc-
openbsd.html](http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html)

------
legulere
The memory-unsafety bugs they found through fuzzing is worrying for newly
written code.

It really shows that you should try to avoid writing C code when possible.

~~~
andrewchambers
Hmm, I think OS level syscall restriction is also a good mitigation for simple
programs. Things like
[https://en.wikipedia.org/wiki/Seccomp](https://en.wikipedia.org/wiki/Seccomp).

~~~
dmix
How popular is Seccomp? I know Chrome uses it, but I'm not familiar with many
other programs outside of sandboxing software.

~~~
andrewchambers
Things like gzip or tar or compilers should use it imo. They are programs
which just read from one file descriptor and write to another.

