Autogenerating terminal window screenshots from text/commands for documentation? - macos

Question

Ok, I hope that stackoverflow is the right place to ask this: I've searched high and wide and haven't come up with a good solution so far.
I'm writing a bunch of documentation for command-line and programming newbies, including nice screenshots of what they might see as they interact with a terminal window. I am thinking of doing this in something like restructuredtext so that I can keep it version controlled and multiformat (for later conversion to html, latex/pdf, etc). Is there any way that I can keep the commands/code/text/etc in a document for revision control, and yet still produce nice user-friendly screenshots in an automated way for inclusion in the final doc? Just as an example, perhaps in in my markup I had something like this (I'm not very familiar with restructuredtext directives yet, but they seem pretty powerful):
.. terminal:: ls_example.png
pre:
/Users/soneil/Documents/test% ls
post:
/Users/soneil/Documents/test% ls
testfile todo.txt
/Users/soneil/Documents/test%
and get two screenshots of terminal windows with the appropriate text in them. The trickier part would be ansi characters for things like editors:
.. terminal:: nano_example.png
pre:
/Users/soneil/Documents/test% ls
testfile todo.txt
/Users/soneil/Documents/test% nano todo.txt
post:
(Either the contents of test.txt right here [with or without editor decoration as well,
which could be faked if needed],
or let a script actually run the command and capture the output somehow)
Resulting in something like:
Pre: http://d.pr/i/a1JS
Post: http://d.pr/i/Edu4
(Sorry for the links, I guess I don't have enough reputation for images yet, nor do I have enough reputation to post more than two links).
I'm working on OSX now, but I'm not tied to the Terminal app (or even OSX, really). If I could specify the cols/rows of the windows as well that would be nice. Creative solutions involving programming, imagemagick, ttyrec, etc. welcome; I've even considered applescript interaction with Terminal.app but with minimal success. I am hoping to get something out the other end with ansi colors (e.g. views of top, htop) and preferably window chrome, so a raster format like png seems logical so far.
Whew! Thanks for your time-

Answer 1

Your idea of automatically generating screenshots is great, but if you actually do them as image files, it won’t be so great because people won’t be able to copy-and-paste from them.
What I’d suggest instead is to using AppleScript with the copy-as-formatted text feature in the Mavericks terminal to make rich-text copies of the terminal display, and convert that to HTML for including in your documents.
Here’s a ruby script:
#!/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/bin/ruby
command = '/bin/ls -G /'
clipboard = `osascript -e '
tell application "Terminal"
set newTab to do script
delay 0.1
do script "#{command}" in newTab
delay 0.1
activate newTab
-- ⌘-A select all
tell application "System Events" to keystroke "a" using command down
-- ⌘-C copy
tell application "System Events" to keystroke "c" using command down
delay 0.1
do script "exit" in newTab
end tell
get the clipboard as «class RTF »
'`
# this returns "«data RTF 7B5C…27D»"; need to strip out the hex data
hex_data = /[A-F0-9]{2,}/.match(clipboard).to_s
data = [hex_data].pack('H*')
converter = IO.popen('textutil -cat html -stdin -stdout', 'w+')
converter.puts data
converter.close_write
puts converter.gets(sep='')
It sends command to the terminal, copies the terminal contents, grabs the terminal contents from the clipboard, and converts it to HTML.
If you plop the output of that straight into a browser
you get a copy of your terminal, with fonts and colours preserved, all copy-and-pastable:
The output HTML can be a bit messy, but since it’s already data inside Ruby you can write code to clean it up. And if you still want the terminal frame around the terminal output, you can do that with CSS.
Hope this helps!