Hacker News new | past | comments | ask | show | jobs | submit login
Mandoc: becoming the main BSD manual toolbox [pdf] (openbsd.org)
25 points by fcambus on June 14, 2015 | hide | past | favorite | 6 comments

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

> 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/bsdcan14-mandoc.pdf http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html

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.

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

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

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.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact