From: Suraj Kurapati <sunaku@...>
Date: 2011-12-08T09:50:45+09:00
Subject: Re: binman 2.0.0

Marc Heiler wrote in post #1035502:
> That screenshot looks GREAT.

Thanks, those colors are from my adaptation of the xoria256 scheme:

http://snk.tuxfamily.org/log/xoria256-terminal-color-scheme.html

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

Since these man pages are just Markdown, you can make WWW pages too:

    binman load YOUR_BIN_SCRIPT | markdown > YOUR_WWW_PAGE.html

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 Tomayko explains this very well in his Ronn tool's docs:

(from the "Background" section at https://github.com/rtomayko/ronn/)

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

Cheers.

-- 
Posted via http://www.ruby-forum.com/.