Changes between Initial Version and Version 1 of terminal_transcripts

Timestamp:

Dec 3, 2010, 8:06:45 PM (13 years ago)

Author:

Daniel Kahn Gillmor

Comment:

--

terminal_transcripts

@@ +1 @@
+= Best practices for transcripts from a computer terminal =
+
+When using command-line computer utilities (like a shell or a database client), it is sometimes useful to e-mail a transcript of your session to other people, or to post a transcript to [http://paste.debian.net/ a public pastebin] or a ticketing system.
+
+This page attempts to document some suggestions for making sure that transcript is clear and useful.
+
+[[PageOutline]]
+
+== Preserve as plaintext ==
+
+some e-mail and web-based systems like to treat things as fancy markup.  a transcript is basically plain text, and should remain as such.  For example, when entering a transcript on this ticketing system, your transcript will be better-preserved and more readable if you prefix it with `{{{` and put `}}}` after it concludes (the docs call this [wiki:WikiFormatting#PreformattedText Preformatted Text].
+
+== Avoid linewrapping ==
+
+If at all possible, try to preserve the format of you transcript without line-wrapping.  Many popular webmail services enforce line-wrapping, limiting the text to 80 columns wide.  This makes it hard for the people reading your e-mail to know what you actually saw.  If your webmail service or mail user agent does this and you can't figure out how to make it stop, you could paste the transcript into a text file (also without linewrapping!) and attach it to your e-mail.
+
+== Include your prompt, and the command you ran! ==
+
+You might think people are just interested in the output that the computer shows you.  But they don't know what you ran to generate the output.  They also don't know where you started from.
+
+Most shell prompts give a clue about where you started from, so include them, along with the command that you actually ran.
+
+== Include the trailing prompt ==
+
+It's also very useful to show people where the end of the computer's output is.  You can do this easily by including the trailing prompt that you are returned to.
+
+== Include the return code ==
+
+If you're using a shell (or other command-line interface that has return codes for each command), modify your shell prompt to include the return code if possible ''before'' generating your transcript.  That adds an extra hint for your readers about what happened, and will be useful for you.
+
+If you use bash as your shell, make sure there is a literal `$?` in the prompt someplace.  For a one-off transcript, you can add the return code to the beginning of your prompt with:
+{{{
+export PS1='$? '$PS1
+}}}
+If you want this permanently, you can do it in `~/.bashrc`, or wherever where the `PS1` environment variable is described.  So if your `~/.bashrc` contains this line:
+{{{
+PS1='${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '
+}}}
+you can change it by just adding a `$?` ''inside'' the single-quotes: 
+{{{
+PS1='$? ${debian_chroot:+($debian_chroot)}\u@\h:\w\$ '
+}}}
+
+= Example transcripts =
+
+== Bad ==
+
+(no bad examples at the moment -- if you have a nice bad example, feel free to add it!)
+
+== Good ==
+
+{{{
+0 dkg@pip:~$ time wget -O/dev/null http://nytimes.com
+--2010-12-03 15:05:34--  http://nytimes.com/
+Resolving nytimes.com... 199.239.136.200
+Connecting to nytimes.com|199.239.136.200|:80... connected.
+HTTP request sent, awaiting response... 301 Moved Permanently
+Location: http://www.nytimes.com/ [following]
+--2010-12-03 15:05:34--  http://www.nytimes.com/
+Resolving www.nytimes.com... 199.239.136.200
+Reusing existing connection to nytimes.com:80.
+HTTP request sent, awaiting response... 200 OK
+Length: unspecified [text/html]
+Saving to: “/dev/null”
+
+    [  <=>                                  ] 133,240      623K/s   in 0.2s    
+
+2010-12-03 15:05:35 (623 KB/s) - “/dev/null” saved [133240]
+
+
+real    0m0.298s
+user    0m0.004s
+sys     0m0.004s
+0 dkg@pip:~$ 
+}}}