This Web

Other Webs

Schematics

RSS

Scheme Links

Including Source Code in the Cookbook

Keywords and Inline Expressions

Keywords and other inline expressions can be highlighted and rendered in fixed font by surrounding them with "=" signs. For example, the notorious function name, call-with-current-continuation, was just embedded there using the following syntax:

=call-with-current-continuation=

Small Source Code Snippets

Small source code snippets can be formatted using the SyntaxHighlightingPlugin syntax, for example:

%begin scheme%
(define hello
  (lambda ()
    (display "Hello, web page")))
%end%

This results in the code being displayed as follows:

(define hello
  (lambda ()
    (display "Hello, web page")))

Including External Code

For any non-trivial code, and perhaps even for some trivial code, it's better to keep the code separately from the book text. Among other things, this will allow the code to be more easily run and tested within Scheme, as well as making it easier to package the code for distribution.

The current approach to including external code is that for each code sample, a topic should be created in the Scm web, for example Scm.Start1. Note that using a WikiName may be helpful, but it's not essential in this case. The raw source code should be stored in this topic - for now, simply cutting and pasting the source from a local copy should suffice, later we'll set up ways to manage this better.

Once the code is stored in a topic, it can be included in the book using syntax like this:

%begin scheme%
%INCLUDE{"Scm.Start1"}%
%end%

This results in the following:

(define (display-type x)
  (cond
   [(number? x) (display "It's a number!")]
   [(string? x) (display "It's a string!")]
   [else (display "It's something else!")]))

-- AntonVanStraaten - 31 Mar 2004

Comments

Is it possible to keep the original indenting? I'm a little annoyed with the indenting on StringRecipeDecodingBinaryMessages. Looking closer, it seems it the square brackets that are causing the problem (see the so-expression).

-- JensAxelSoegaard - 01 Apr 2004

Looks like BeautifierPlugin can't really handle Scheme properly, and fixing it looks like work (I looked at the Perl source; it's fairly primitive). Browsing the plugin list at twiki.org, I found and installed SyntaxHighlightingPlugin, which uses GNU enscript to do the highlighting. I've changed StringRecipeDecodingBinaryMessages to use this - check it out and see what you think. The tags you need look like this:

%begin scheme%
(let ([a 0])
      [b 1])
  (+ a b))
%end%

which produces this:

(let ([a 0])
      [b 1])
  (+ a b))

which improves on BeautifierPlugin's indentation:

(let ([a 0])
  [b 1])
(+ a b))

Long term, I'm a little concerned that shelling out to enscript to format every code snippet could be hard work for the server, but for now I think it's OK.

BTW, enscript generates font elements with hardcoded colors, and I'm not crazy about the colors. I have about a dozen lines of Perl lying around somewhere that translates this into CSS classes. When I get a chance I'll patch that in, at which point the source highlighting will be under the control of the skin (and will even support per-user customization).

Noel, you previously mentioned Moshi's Scheme code formatting abilities. Was that based on WebIt, or do you have some other code for that?

-- AntonVanStraaten - 01 Apr 2004

Moshi supports enscript. In addition BrentFulgham wrote some formatting code for the OriginalCookbook and I've brutually hacked it into my Moshi install (not in CVS yet). The code uses regexps and is in /doc/cookbook/fontify.ss

-- NoelWelsh - 02 Apr 2004

Anton, the enscript output is much better. Changing the colors of it much be relatively easy. If it turns out to be slow, we must figure out a way to cache the pages, so only new code snippets are passed to enscript.

Not that long ago I looked at the source of the source highlighter of the syntax checker tool, because I wanted to add a "Save highlighted code as HTML"-button. I was hoping to steal/reuse a function returning the code as syntax objects with color properties. However I had a hard time grasping the relation to the GUI as such, so I dropped the idea. It would however be cool to have the same syntax highlighting as in DrScheme. The code is in syncheck.ss.

-- JensAxelSoegaard - 02 Apr 2004

I've updated this topic to describe the new SyntaxHighlightingPlugin instead of BeautifierPlugin. I've also changed the converted cookbook pages to use this. The new plugin has had the side-effect of fixing the CookBook page so that it displays the whole (original) book, complete with source code.

I'm fine with enscript for now - I doubt we'll need to worry about performance for some time. As you say, caching could adddress that. Reusing PLT's Check Syntax sounds ambitious! Their new "dumb" syntax highlighter might be easier.

-- AntonVanStraaten - 03 Apr 2004