Wednesday, September 19, 2007
Recently, a reader inquired as to how I format the source code samples on my blog. After writing up the set of steps that I normally run through, I decided that I should post them here so that 1) interested readers might benefit, and 2) I won't forget my own process.

First of all, I should point out that there are several tools available to help format source code for the web, and Brig Lamoreaux has a good review of several here. My personal tool of choice is CopySourceAsHtml. It does a great job of getting code out of Visual Studio with accurate syntax highlighting. With a few tweaks to the HTML, it can produce exactly what I need.

Here is the exact process that I go through to create code samples that look equally good on the web and in RSS feeds.

Step 1: Write Your Code

Step 1: Write Your Code

Some important tips:

  • The code should be concise and well formatted. Most readers skim code, so it should be clear enough to get the general idea from a brief overview.
  • Make sure the code compiles! It can be quite embarrassing to be contacted by a reader who, after copying and pasting the code, found that it didn't compile.

Step 2: Copy As HTML

Step 2: Copy As HTML

Select the code sample in Visual Studio, and decrease the indent (Shift+Tab) until the code is aligned at column 1. Next, select "Copy As HTML..." from the editor's context menu. At this point, you'll be presented with the "Copy As HTML" dialog.

The first time that the dialog is displayed, some options need to be set. Fortunately, the dialog remembers your settings so that you don't need to change them next time. On the "General" tab, uncheck everything except for "Embed styles."

Step 2a: Copy As HTML (General tab)

Next, switch to the "File Style" tab to add additional CSS styles to the <div> tag that will surround the HTML-formatted code sample. Here are the styles that I use for my blog:

border: 1px dotted rgb(221, 221, 221);
margin: 4px;
padding: 4px;
font-family: Consolas,'Courier New',Courier,monospace;
font-size: small;
color: rgb(0, 0, 0);
background-color: rgb(255, 255, 255);

Step 2b: Copy As HTML (File Style tab)

Finally, click the OK button to copy the code to the clipboard.

Step 3: Massage the HTML

Once pasted in the HTML source editor of your choice, the code sample will render like this:

Sub Main()
  Dim publicationdate = Date.Today
  Dim isbn = 42
  Dim price = 0.99D
  Dim firstName = "Dustin"
  Dim lastName = "Campbell"
 
  Dim book = <book publicationdate=<%= publicationdate %> ISBN=<%= isbn %>>
               <title>F#: For The Excessively Nerdy</title>
               <price><%= price %></price>
               <author>
                 <first-name><%= firstName %></first-name>
                 <last-name><%= lastName %></last-name>
               </author>
             </book>
End Sub

Unfortunately, CopySourceAsHtml wraps every line in the code sample with <pre style="margin: 0px;"></pre> tags. These tags override some of the CSS styles that we specified for the <div> tag. Thankfully, this is easily corrected with two replace operations:

  1. Replace all instances of <pre margin="0px"> with blank text.
  2. Replace all instances of </pre> with <br /> to preserve the line breaks.

The syntax coloring is achieved by using <span> tags. Occasionally, a space will appear between two uses of a <span> tag. For example, in the code sample above, "End Sub" is actually represented like this:

<span style="color: blue;">End</span> <span style="color: blue;">Sub</span>

Some RSS readers make the mistake of removing the space in between these <span> tags, causing the words to run together. To fix this potential problem, just replace all instances of "</span> <span" with "</span>&nbsp;<span".

When finished, the code sample should render like this:

Sub Main()
  Dim publicationdate = Date.Today
  Dim isbn = 42
  Dim price = 0.99D
  Dim firstName = "Dustin"
  Dim lastName = "Campbell"
 
  Dim book = <book publicationdate=<%= publicationdate %> ISBN=<%= isbn %>>
               <title>F#: For The Excessively Nerdy</title>
               <price><%= price %></price>
               <author>
                 <first-name><%= firstName %></first-name>
                 <last-name><%= lastName %></last-name>
               </author>
             </book>
End Sub

Really, it's not that much effort. Once the CopySourceAsHtml options are set to your liking, it is a simple matter to copy, paste and make a few modifications to get the desired result. Most of the work is in writing the code sample.

posted on Wednesday, September 19, 2007 1:39:54 PM (Pacific Standard Time, UTC-08:00)  #    Comments [3]

kick it on DotNetKicks.com