Binman 2.0.0

binman - UNIX man pages for Ruby bin/ scripts
https://github.com/sunaku/binman#readme


What is it?

binman produces UNIX man pages for your Ruby bin/ scripts using
markdown(7), roff(7), Redcarpet2 for conversion thereof, and man(1).

Here is an obligatory screen-shot of binman in action:

Here is an example bin/ script to help you get started:


What is new?

Breaking changes:

  • Removed the deprecated binman/rake_tasks helper library. Use
    binman/rakefile instead.

External changes:

  • Fixed infinite looping in the binman/gemspec helper library.

Internal changes:

  • Upgraded to md2man v1 for Markdown to UNIX man page conversion.

  • Do not hard-code the version number in binman/gemspec helper.

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.

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.

Marc H. 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 T. 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.

Chad P. wrote in post #1035596:

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.

Glad to hear that. Please enjoy! :slight_smile:

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs