On Wed, Dec 07, 2011 at 05:51:16PM +0900, Marc H. wrote:
That screenshot looks GREAT.
I myself do not use man-pages (I am proudly of the WWW generation, not
the “man foo” generation) but I really think this seems AWESOME.
I do use manpages – a lot – and I think this is an excellent
library.
I’ll probably use it quite a bit in the future, in fact. Thanks, Suraj
N. Kurapati.
I’ve used and developed several documentation systems over the years
and have been gradually converging to something similar to literate
programming. This Markdown to UNIX man page conversion flow, with
documentation right beside its associated code (bin script, in this
case) feels so easy that I am encouraged to write more tools & docs.
Going further, there is something to be said of the refreshingly
simple, accessible, and convenient aesthetic of UNIX man pages. I
think Ryan T. explains this very well in his Ronn tool’s docs:
Some think UNIX manual pages are a poor and outdated form of
documentation. I disagree:
Manpages follow a well defined structure that’s immediately
familiar. This gives developers a starting point when
documenting new tools, libraries, and formats.
Manpages get to the point. Because they’re written in an
inverted style, with a SYNOPSIS section followed by additional
detail, prose and references to other sources of information,
manpages provide the best of both cheat sheet and reference
style documentation.
Historically, manpages use an extremely – unbelievably –
limited set of text formatting capabilities. You get a couple of
headings, lists, bold, underline and no more. This is a feature.
Although two levels of section hierarchy are technically
supported, most manpages use only a single level. Unwieldy
document hierarchies complicate otherwise good documentation.
Remember that Feynman covered all of physics – heavenly bodies
through QED – with only two levels of document hierarchy (The
Feynman Lectures on Physics, 1970).
The classical terminal manpage display is typographically well
thought out. Big bold section headings, justified monospace
text, nicely indented paragraphs, intelligently aligned
definition lists, and an informational header and footer.
Manpages have a simple referencing syntax; e.g., sh(1), fork(2),
markdown(7). HTML versions can use this to generate links
between pages.
Unfortunately, figuring out how to create a manpage is a fairly
tedious process. The roff/mandoc/mdoc macro languages are highly
extensible, fractured between multiple dialects, and include a
bunch of device specific stuff irrelevant to modern publishing
tools.
