Skip to content
This repository

Help page formatting #11

Closed
dag opened this Issue July 20, 2012 · 2 comments

2 participants

Dag Odenhall Paolo Capriotti
Dag Odenhall
dag commented July 20, 2012

Possibly related to #10.

The CmdTheLine package supports formatting the help page in many ways: normal plain text, pager, man page, groff markup. I tried this package and really liked the man-page-like help page, but ended up with optparse-applicative in the end because I found CmdTheLine awkward in other areas (specifically the subcommands handling). Also it uses some weird custom string interpolation for writing these help pages.

Would be nice if optparse-applicative could do this as well, but using something like ansi-wl-pprint for the "markup" instead.

I'm also thinking that when possible it could find out the width of the terminal window and wrap lines nicely to that margin. This is easy with ansi-wl-pprint. For example I have this in my program, and it's longer than a normal terminal width of 80 columns:

  --output MODE            Control how output is printed (tty|colored|plain|quiet)

Using smart wrapping this could render as something like, pretending we have a really narrow terminal window:

  --output MODE            Control how output is
                           printed (tty|colored|plain|quiet)

Also if a line in the column where the flags are listed is longer than that column, the description could be pushed down to a new line instead of indented further, like,

  -h,--help                Show this help text
  --trace-level SOME_INSANELY_LONG_METAVAR
                           Set the tracing level for the XML parser

I suspect (but baseless-assertion.jpg) that this sort of thing is also easy with ansi-wl-pprint.

It would also remove the need for the Options.Applicative.Utils module.

Dag Odenhall
dag commented July 20, 2012

Oh yea, it could also detect if the output device is a terminal to control the default help format. That way if you pipe --help to a file you don't get lots of ANSI escapes in it.

http://hackage.haskell.org/packages/archive/base/4.5.1.0/doc/html/System-IO.html#v:hIsTerminalDevice

To get the width of the terminal I use the terminfo package and code like this:

#if WINDOWS
    let width = Nothing
#else
    width <- fmap (`getCapability` termColumns) setupTermFromEnv
#endif
    let prettyPrint = displayIO stdout . renderPretty 1.0 (fromMaybe 80 width)
                                       . (<> linebreak)

But I'm not sure if this is optimal. It might be possible to get the width on Windows, and it might be that the terminfo package requires certain C header files (although its cabal file mentions none)...

Paolo Capriotti
Owner

Branch formatting was merged in 73a25ac. Closing.

Paolo Capriotti pcapriotti closed this December 16, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.