A while back, I wrote about how handy it was to redirect a man page into Preview. This allows you to keep the man page open, search it, and generally have a better user experience than struggling with
less) to navigate through the information provided there.
man -t apropos | open -fa Preview
Recently, someone asked me about more modern command line interaction, specifically, commands that use
--help or similar to provide their documentation. Could that information be opened in Preview as well.
So I put on my thinking hat and set to work. The first command line utility I decided to work with was
screencapture because I’ve been using it fairly heavily over the last few days. However, it appears that Apple failed to build in an actual help system beyond
man. It was a poor choice to try to use to render but I decided to keep plugging away at it because I wanted to be able to pipe both
stderr to Preview.
What I came up with looked something like this, all in one line of course:
bash -c "screencapture -? &> $TMPDIR/previewrendertext.txt; /usr/sbin/cupsfilter -i text/plain -D $TMPDIR/previewrendertext.txt 2> /dev/null | open -fa Preview"
This all relies on
cupsfilter, which can convert a file of text to a printable form, which just happens to be readable by Preview as a PDF.
I’m doing quite a bit of conglomeration, joining the stderr and stdout streams using
&> and saving them into my Mac’s
$TMPDIR. That file is cleaned up by the
-D option from
I also am removing the incessant debug messages from
cupsfilter by redirecting them to
/dev/null before opening the print output in Preview.
Please note that I’m still using
bash on my main system, so that certainly affects things. Since I needed a little of the
bash nuance, I decided to run it all squished as a single
-c command. (I’m sure if I spent enough time, I could do it all in
csh but I really didn’t want to spend that time.)
As you can see in the previous screenshot, an older utility meant for
man output doesn’t really look all that hot shoved into Preview via
cupsfilter, especially with line lengths. There’s also no nice groffing and troffing to make everything pretty, the way you get with
So how could would this kludge work with a modern command-line app, such as those produced using the Swift Argument Parser (https://github.com/apple/swift-argument-parser)? First, I built a utility that would let me run any command (well, so long as it was properly quoted) without having to type all the details out each time I ran it:
#! /bin/bash $@ &> $TMPDIR/previewrendertext.txt ; /usr/sbin/cupsfilter -i text/plain -D $TMPDIR/previewrendertext.txt 2> /dev/null | open -fa Preview
This allowed me to call
preview "now --help" to redirect the standard help message from my
now utility (https://github.com/erica/now) to Preview. Yeah, originally I wanted to just pipe stuff into it but I couldn’t figure out how to get the stderr and the stdout piped together into a single stream, let alone convert them into a file form because
cupsfilter doesn’t know or do pipes.
It’s pretty readable and well-formatted due to the automatic configuration that the Swift Argument Parser provides from my code but it just feels, you know, very very plain.
So I went ahead and tried to see what would happen if I groffed it up a little by passing it through
/usr/bin/groff -Tps -mandoc -c instead of using
bash -c "now --help &> $TMPDIR/previewrendertext.txt; /usr/bin/groff -Tps -mandoc -c $TMPDIR/previewrendertext.txt" | open -fa preview
And it’s…pretty meh. I tried mandoc, mdoc, me, mm, ms, and www formats. They all came out the same, and none of the SAP tabs really worked. I think it looks a lot more “manny” than the straight printout but the indentation really bugged:
I decided to stop at about this point as there’s really a time when further effort just isn’t worth further investment — so I could throw it out there and see if this was of interest to anyone else.
Let me know.