21

21Displaying code fragmentse

21.3

Using Google Prettify

I use Google Prettify to display mainly HTML, CSS and JavaScript code, that is after all what goes into a website. This however, can be a bit of a problem.

21.3.1

The problem with displaying code fragments

Let’s say for example that I want to display the following bit of HTML code:

<p class="hyp">Paragraph 1</p>
<p class="hyp">Paragraph 2</p>

And let’s say I add it to a <pre> element on the 99-00-typicals.html page, thus:

<p class="hyp">A first attempt</p>
                   
<div class="code-extract">                          <!-- Start of code fragment -->
    <div class="code-header">css</div>              <!-- Code file name -->
    <div class="code-area">                         <!-- Start of code extract holder -->
       <pre class="prettyprint linenums lang-html"> 
<p class="hyp">Paragraph 1</p>
<p class="hyp">Paragraph 2</p>
       </pre>
    </div>                                           <!-- End of code extract holder -->
    <div class="code-caption">Code 99.3 &mdash; Code Fragment&mdash;CSS</div> 
</div>                                               <!-- End of code fragment -->

OK, there is the code fragment (green background) pasted in between the <pre>...</pre> tags.

Now when I look at the web page, I want to see a code fragment that looks like this:

Figure 21.23 - First attempt at an HTML fragment — what I expect
Figure 21.23   First attempt at an HTML fragment — what I expect

But what I actually get is:

Figure 21.24 - First attempt at an HTML fragment — actual result
Figure 21.24   First attempt at an HTML fragment — actual result

So what the bloody hell is going on?

The problem is the browser. The browser has the following code on its web page:

<p class="hyp">A first attempt</p>
                   
<div class="code-extract">                          <!-- Start of code fragment -->
    <div class="code-header">css</div>              <!-- Code file name -->
    <div class="code-area">                         <!-- Start of code extract holder -->
       <pre class="prettyprint linenums lang-html"> 
<p class="hyp">Paragraph 1</p>
<p class="hyp">Paragraph 2</p>
       </pre>
    </div>                                           <!-- End of code extract holder -->
    <div class="code-caption">Code 99.3 &mdash; Code Fragment&mdash;CSS</div> 
</div>                                               <!-- End of code fragment -->

It sees the <pre> element and to the browser this is just another semantic element, just like a <div> and then it sees two paragraph elements <p> within it. So it just renders the paragraphs in the <pre> element and we get Figure Figure 21.24.

That is the trouble with trying to display HTML as code fragments, the browser just thinks it’s more HTML and displays it as such.

21.3.2

The solution to displaying code fragments

Remember in § 6.11 where I explained about reserved characters in HTML

html reserved characters

The following have special meaning in HTML:

Less than

<

Replacement code:

&lt;

Greater than

>

Replacement code:

&gt;

Ampersand

&

Replacement code:

&amp;

Double quotation mark

"

Replacement code:

&quot;

Single quotation mark

'

Replacement code:

&apos;

If a code fragment has any of these characters within it, that character must be replaced by its &code (see above).

So, to display our code fragment, the HTML must become:

<p class="hyp">A first attempt</p>
                   
<div class="code-extract">                          <!-- Start of code fragment -->
    <div class="code-header">css</div>              <!-- Code file name -->
    <div class="code-area">                         <!-- Start of code extract holder -->
       <pre class="prettyprint linenums lang-html"> 
&lt;p class="hyp"&gt;Paragraph 1&lt;/p&gt;
&lt;p class="hyp"&gt;Paragraph 2&lt;/p&gt;
       </pre>
    </div>                                           <!-- End of code extract holder -->
    <div class="code-caption">Code 99.3 &mdash; Code Fragment&mdash;CSS</div> 
</div>                                               <!-- End of code fragment -->

This now gives us what we were looking for:

Figure 21.25 - Code fragment with reserved characters replaced with &codes
Figure 21.25   Code fragment with reserved characters replaced with &codes

Let’s look at what I’ve done here.

Take the first line, the original was:

<p class="hyp">Paragraph 1</p>

Take the first line, the original was:

I’ve replaced every < with &lt; and every > with &gt; to give me:

&lt;p class="hyp"&gt;Paragraph 1&lt;/p&gt;

Er... Yep, I’m not kidding, that’s how you do it.

So now you’re thinking “fuck me, that’s a shitload of work just to get my code to display”.

Yes that’s what I thought too.

I looked around at this point and I found some websites that do this sort of thing for you, they’re called HTML encoders and there are a lot of them. You paste your code in, hit the encode button and copy what comes out. Just paste that in between the <pre> tags and Bob’s your uncle.

Only, I found that a lot of these site make certain assumptions, some takeout the line breaks, some fiddle with the indentations.

21.3.3

The Practical Series HTML conversion document

I produced a Word document with macros that does the conversion for you. You can get it here. It is called ps-html-converter.docm and it looks like this:

Figure 21.26 - Code fragment with reserved characters replaced with &codes
Figure 21.26   Code fragment with reserved characters replaced with &codes

I’ll give you an example of how to use it, let’s say we want to display the title bar section of the code from the 99-00-typicals web page as a code fragment.

The title section looks like this in Brackets (I’ve selected it, it’s in blue):

Figure 21.27 - Section of code in Brackets
Figure 21.27   Section of code in Brackets

To convert the code, select it (as shown, 15 lines) and copy it.

Now open the conversion document (note, Word may ask you to enable macros, it depends on your settings, if it does, enable the macros) and paste it in to the last page of the document (Figure 21.28):

Figure 21.28 - Text from Brackets pasted directly into the conversion document
Figure 21.28   Text from Brackets pasted directly into the conversion document

In the document, select the text you have just pasted in (as shown) and press ctrl+alt+R to run the macro (alternatively select view → macros and select HTML_replacement from the list and click run).

Doing this will turn all the text blue, and will replace all the HTML reserved characters with &codes.

In short it will look like Figure 21.29 (I’ve zoomed in on the text):

Figure 21.29 - Converted code
Figure 21.29   Converted code

In the document select all the converted text and copy it.

Now back in Brackets paste it in between the two <pre>...</pre> tags we had before . It looks like this (pasted text highlighted):

Figure 21.30 - Converted code pasted in between the <pre>...<pre>
Figure 21.30   Converted code pasted in between the <pre>...<pre>

If you preview it you get the right result (the code fragment looks like proper HTML):

Figure 21.31 - Converted code on the web page
Figure 21.31   Converted code on the web page

21.3.4

Copying code fragments

The code fragment that is rendered in the browser is copyable; you can select it with a mouse and copy it:

Figure 21.32 - Copying a code fragment
Figure 21.32   Copying a code fragment

If you now past this code into say Brackets or Notepad, you get the proper code, not the thing with all the &codes in it. This is the above code pasted into Notepad

Figure 21.33 - A copied code fragment
Figure 21.33   A copied code fragment

This is very useful, it means that any code you display with Google Prettify can be copied directly from your website and used somewhere else.

You have to do the work converting it in the first place; but then it is available to everybody as proper, usable code. They don’t have to do anything themselves, they can just use it.

21.3.5

Copying code fragments

OK, there are a few classes of my own to go through to finish off the displaying of code fragments, take a typical example:

code fragment html
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     CODE FRAGMENT DISPLAY - STANDARD BLOCK WITH HEADER & CAPTION (HTML)
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
<div class="code-extract">                          <!-- Start of code fragment -->
    <div class="code-header">filename</div>         <!-- Code file name -->
    <div class="code-area">                         <!-- Start of code extract holder -->
        <pre class="prettyprint linenums lang-html" id="js--c99-01">
&lt;nav&gt;                            &lt;!-- TOP NAVIGATION BAR --&gt;
    &lt;div class="top-nav"&gt;
        &lt;div class="rg-row"&gt;
            &lt;a class="nav-wide" href="#"&gt;&lt;span class="top-nav-icon"&gt;l&lt;/span&gt;&lt;span class="top-nav-text"&gt;Prev. section&lt;/span&gt;&lt;/a&gt;
            &lt;a class="nav-wide" href="#"&gt;&lt;span class="top-nav-icon"&gt;u&lt;/span&gt;&lt;span class="top-nav-text"&gt;Prev. chapter&lt;/span&gt;&lt;/a&gt;
            &lt;a class="nav-wide nav-home" href="#"&gt;&lt;span class="top-nav-text"&gt;Home&lt;/span&gt;&lt;span class="top-nav-icon"&gt;h&lt;/span&gt;&lt;/a&gt;
            &lt;a class="nav-narrow js--sc-top" href="#"&gt;&lt;span class="top-nav-icon"&gt;t&lt;/span&gt;&lt;span class="top-nav-text"&gt;Top&lt;/span&gt;&lt;/a&gt;
            &lt;a class="nav-narrow" href="#"&gt;&lt;span class="top-nav-text"&gt;Home&lt;/span&gt;&lt;span class="top-nav-icon"&gt;h&lt;/span&gt;&lt;/a&gt;
            &lt;a class="nav-wide" href="#"&gt;&lt;span class="top-nav-text"&gt;Next chapter&lt;/span&gt;&lt;span class="top-nav-icon"&gt;d&lt;/span&gt;&lt;/a&gt;
            &lt;a class="nav-wide" href="#"&gt;&lt;span class="top-nav-text"&gt;Next section&lt;/span&gt;&lt;span class="top-nav-icon"&gt;r&lt;/span&gt;&lt;/a&gt;
        &lt;/div&gt;
    &lt;/div&gt;
&lt;/nav&gt;                            &lt;!-- END OF TOP NAVIGATION --&gt;
        </pre>
    </div>                                          <!-- End of code extract holder -->
    <div class="code-caption">Code 99.1 &emsp; Code Fragment &mdash; html extract</div> 
</div>                                                  <!-- End of code fragment -->
<!--  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
Code 21.4   A typical code fragment

The bit with the blue background is the code fragment itself, the stuff we looked at in the previous section. In this section, I’m going to look at the other stuff, all the div elements and classes that go around it to make it look nice on the website; this is very similar to what we did with figures and tables.

There are four classes associated with a code fragment: code-extract, code-header, code-area and code-caption. There is absolutely nothing to get excited about in any of them, the CSS for the classes is:

code fragment css
.code-extract {                             /* holder for the whole code extract */
    width: 100%;
}
.code-header {                              /* code header (filename header) */
    font-family: "conc-t3-r";
    font-feature-settings: "ss02";
    text-transform: lowercase;
    text-align: right;
    padding: 0.1rem 0.2rem 0.2rem 0.2rem;
    background-color: #e8e8e8;
}
.code-area {                                /* area holding the extracted code */
    background-color: #fbfbfb;
    padding: 0.2rem 0;
    border-bottom: 1px solid #e8e8e8;
    border-top: 1px solid #e8e8e8;
}
.code-caption {                             /* code caption area */
    font-family: "conc-t3-r";
    font-feature-settings: "ss02";
    font-size: 0.6rem;
    color: #404030;
    text-align: center;
    padding-top: 0.2rem;
    margin-bottom: 1rem;
}
Code 21.5   Code fragment CSS

I’ll go through this very quickly, it’s mostly fonts and margins — the usual stuff.

The code-extract class is the container for the whole code fragment, everything else is inside this and all it does is make sure the code fragment spans the width of the central column:

    width: 100%;

The code-header class is the top line above the code fragment:

Figure 21.34 - A copied code fragment
Figure 21.34   A typical code fragment

It is the bit at the top that says filename in lowercase letters.

The idea is that if a the code is associated with a particular file (they usually are) the filename can be added here.

The CSS is straight forward:

    font-family: "conc-t3-r";
    font-feature-settings: "ss02";
    text-transform: lowercase;
    text-align: right;
    padding: 0.1rem 0.2rem 0.2rem 0.2rem;
    background-color: #e8e8e8;

It uses a Concourse font (British settings, ss02) and is right justified (text-align: right). It is also forced to be in lower case (remember all filenames are in lowercase).

There is a bit of padding to give space around the text and the background colour is set to grey (#e8e8e8).

The code-area holds the code fragment itself:

.code-area {                                /* area holding the extracted code */
    background-color: #fbfbfb;
    padding: 0.2rem 0;
    border-bottom: 1px solid #e8e8e8;
    border-top: 1px solid #e8e8e8;
}

The code-area has a slightly lighter, grey background (#fbfbfb) and has a top and bottom border (1 pixel high) in the same grey as the heading area. The padding just gives a gap at the top and bottom.

The code-caption is a space underneath the code fragment that allows a caption to be entered for the code fragment:

    font-family: "conc-t3-r";
    font-feature-settings: "ss02";
    font-size: 0.6rem;
    color: #404030;
    text-align: center;
    padding-top: 0.2rem;
    margin-bottom: 1rem;

It just sets the font, its colour and adds a bottom margin to give a following whitespace area.

Simple stuff.



End flourish image