As I write technical posts, typographical and “blog style” issues can sometimes be important. Since mentioning the rules in each post is unwieldy, repeats myself and not very easy to lookup, I created this page where I’ll slowly add conventions as I make them up. I’ll try hard to adhere to my own conventions, but you get what you pay for here, so no guarantees.

Source quotations
When referring to a file name I’ll put it in teletype text, like so ./path/to/file.py. On occasion I’ll include the function name, line number, or line quotation from the file after the file name, like so: ./path/to/file.py: func_name. Which one I chose should be clear from context.

When quoting source (copying and pasting), I’ll add comments as I see fit. I will not remove or modify parts of the quoted source without adding a comment saying I did so, unless explicitly mentioned otherwise in the post. I’ll prefix my comments with “n2w:” (nil to write), so you know they’re there for the blog post.

Terminal quotations
Unless explicitly mentioned other wise, I may edit terminal quotations (interactive interpreter sessions, shell session, gdb sessions, etc) as I see fit. Naturally, I will do my best to avoid any changes that might affect your ability to copy/paste what I typed into your terminal and get similar results.

When doing “short” terminal quotations, i.e., not in their own paragraph, $ represents a UNIX shell prompt and >>> represents a Python prompt. So >>> print("foo") means I literally typed ‘print(“foo”)’ in my Python prompt (and so could you!).

Typographical conventions
HTML lets me differentiate teletype quotes and keyboard input using <tt> and <kbd>. Effective immediately I’ll try to use them appropriately, though at the time of this writing my CSS does not differentiate them visibly. Naturally, teletype quotes may include keyboard input in them and vice versa, I’ll tag them based on the more meaningful meaning.

I have some English (British) heritage, and though English isn’t quite native to me (it is my mother’s tongue, but I didn’t grow up speaking it), I always try to improve it. Specifically, I’d love making my spelling 100% UK English, so if you happen to be from the UK and find someplace where I used non UK spelling, please, do correct me.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: