The problem

The ancient art of cross‑stitch is one of the most popular forms of embroidery.

The artist pulls a soft cotton canvas taught in a hoop, equips a needle, gathers reams of coloured threads and sets to work stitching row after row to create an intricate pattern of crosses. The more elaborate pieces contain different shapes of stitches, each with their own threading technique.

At the beginning of it all, before the threads are assembled or needle is put to canvas, is the careful study of a pattern.

A cross‑stitch pattern is a printed grid depicting exactly where each stitch should be made, its colour and the technique used to form it.

Most patterns are sold as images: printed coloured charts with legends to accompany them. The patterns we’ll be working with are humble text files. You should have downloaded a bank of these when setting up.

Open the coe‑xx/logo.xx file.

Windows and buffers

You’ll notice that Emacs is unphased by the .xx extension. It treats the pattern as it would treat any other text file.

It opens the file contents in a buffer called logo.xx , and displays it in the current window.

• A window is a portion of the Emacs screen. The screen can be split into multiple windows, both horizontally and vertically.

• A window is a view onto a buffer. Buffers contain the contents that we edit. They exist even when we’re not viewing them.

We can tell which buffer a window views by looking at its label. This window is labelled logo.xx.

A pattern is composed of a title, a legend and a grid.

The grid depicts the stitches that must be made. Each letter code represents a different kind of stitch.

The legend above it shows what each of these codes mean: the colour of thread, how many strands to thread through the needle, and what technique to use when making the stitch.

A text file like this is hardly a good view of the pattern. It is, at first glance, much more difficult to interpret than an image. In later chapters we’ll write an xx‑mode function that displays it properly.

Let’s have a peek at that function now.

Calling functions

As part of your setup, you should have downloaded a bunch of functions prefixed by coe‑xx, the acronym for “Craft of Emacs cross-stitch”. These functions are identical to the ones you will write yourself.

Let’s call the coe‑xx‑mode function.

Hold down the Alt and x keys.

Your minibuffer will look like this:

M-x ^ 

The M stands for Meta. At Emacs’s birth in the 1970s, the Meta key was commonplace on keyboards. It has since been replaced by Alt, but Emacs keeps to its traditions.

The minibuffer is the area used to call functions like so:

M-x ^coe-xx-mode 

Type coe‑xx‑mode and press the Return key.

From now on, we’ll denote these key presses as follows:

This means “hold down the Alt and x keys to use the minibuffer; type coe‑xx‑mode and press Return”

The pattern buffer is now much more colourful.

Describing functions

What did coe‑xx‑mode do, aside from colouring in the grid? Did it change anything else? And where exactly did it come from?

Emacs has a helpful function for finding out. It’s called describe‑function.

Call M‑x describe‑function.

You’ll see a “Describe function:” prompt. We need to input a function name.

Type coe‑xx‑mode and press Return.

Describe function: coe-xx-mode 

We’ll denote calling functions with inputs like so:

Describing the function opens up a new window with a *Help* buffer.

coe-xx-mode is an interactive Lisp function in
`/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'.

(coe-xx-mode)

Major mode for viewing cross stitch patterns.

Each cross stitch in the pattern is displayed as a 'x' coloured
according to its thread colour.

key             binding
---             -------

C-c		Prefix Command
<mouse-1>	coe-xx-code-select

C-c a		coe-xx-basket-add
C-c c		coe-xx-code-select
C-c r		coe-xx-ruler-mode

.

This mode runs the hook `coe-xx-mode-hook', as the final or
penultimate step during initialization.

The function description is very detailed, quite possibly you won’t understand it all yet. Let’s pick out the important points:

• coe‑xx‑mode is a function.

• coe‑xx‑mode is also a major mode.

• It added some new keybindings to the logo.xx buffer.

Loosely speaking, a major mode is a function that governs a buffer. It may alter the way it is displayed, and will usually add keybindings to it.

Using keybindings

A keybinding is a mapping from a key, or combination of keys, to a function.

coe‑xx‑mode added several keybindings:

<mouse-1>	coe-xx-code-select

C-c a		coe-xx-basket-add
C-c c		coe-xx-code-select
C-c r		coe-xx-ruler-mode

The left mouse click <mouse-1> is also considered a key.

Left click on a red cross in the logo.xx buffer

The red crosses are the only ones displayed. According to the *Help* text, a mouse click is bound to coe‑xx‑code‑select. What does it do?

Describe the coe‑xx‑code‑select function.

coe-xx-code-select is an interactive Lisp function in
`/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'.

It is bound to <mouse-1>, C-c c.

(coe-xx-code-select)

Displays stitches with the thread colour and stitch type at
point. All other stitches are hidden.

Displays the entire pattern if called when a code (a thread
colour and stitch type) is already selected.

Use this to focus on the stitches you care about when filling in the
pattern.

Cross-stitchers fill in their patterns one colour at a time, so displaying a single colour is useful.

The point mentioned in the text is the position of the cursor, usually denoted by a shaded rectangle. Left clicking on a red cross moved the point to it, hence a red stitch type was selected.

According to the description, calling coe‑xx‑code‑select again will show stitches of all colours. Let’s give it a try.

Call M‑x coe‑xx‑code‑select.

There are other keybindings to explore. Let’s take a look at the keybinding for coe‑xx‑ruler‑mode.

Hold down the Control and c keys, then type r.

This keybinding is denoted as C‑c r where C stands for Control.

coe‑xx‑ruler‑mode added a ruler to either side of the grid, useful for counting stitches.

How can you learn more about coe‑xx‑ruler‑mode?

Describing the function shows that it is a minor mode.

coe-xx-ruler-mode is an interactive Lisp function in
`/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'.

It is bound to C-c r.

(coe-xx-ruler-mode &optional ARG)

Minor mode for measuring cross stitch patterns.
...

A minor mode can be thought of as a function that adds extra behaviour. In this case, the function added rulers.

Describing keys

Let’s try clicking on a stitch with the ruler present.

Left click on a red cross.

You’ll notice that it does something else. Did it even call coe‑xx‑code‑select? We can find out by describing the key.

Call M‑x describe‑key and left click.

<mouse-1> at that spot runs the command coe-xx-ruler-focus (found in
coe-xx-ruler-mode-map), which is an interactive Lisp function in
`/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'.

It is bound to <mouse-1>, C-c f.

(coe-xx-ruler-focus)

Not documented.

[back]

A mouse click is now bound to the coe‑xx‑ruler‑focus function; it adds ticks on the ruler to indicate the point. This must have been bound by coe‑xx‑ruler‑mode.

Let’s examine some more keybindings.

Call the keybinding C‑c a.

That didn’t seem to do anything. What did it call?

Describe the keybinding C‑c a.

C-c a runs the command coe-xx-basket-add (found in coe-xx-mode-map),
which is an interactive Lisp function in
`/nix/store/pr02pm66hvf3bvam6wb1l893b6l6k853-source/coe-xx.el'.

It is bound to C-c a.

(coe-xx-basket-add)

Adds a pattern's materials to a 'shopping basket'.
This is used to calculate materials for multiple patterns at once.

See also `coe-xx-basket-clear' and `coe-xx-basket-view'

It is indeed still bound and working, and altered an invisible “basket”.

The description references a couple of other functions: coe‑xx‑basket‑clear and coe‑xx‑basket‑view.

Call M‑x coe‑xx‑basket‑view

This shows the materials we need for the pattern. A skein is a length of thread wound in a ball. An artist needs to know how many to buy, or fish out from their closet, before starting to stitch.

The function M‑x coe‑xx‑basket‑clear removes all skeins from the basket.

Verify this by calling M‑x coe‑xx‑basket‑clear then M‑x coe‑xx‑basket‑view.

Exploring source code

The basket manipulation functions weren’t listed in the description of coe‑xx‑mode. There might be more functions we haven’t found out about. How can we know what they are?

The last place to look is the Emacs Lisp source code. We can do this by finding the function.

Call M‑x find‑function xx‑basket‑view.

You’ll be launched into a rather lengthy coe‑xx.el file. This has many other functions within it, most of which aren’t relevant at the moment.

The Elisp code probably contains a lot of constructs you’re unfamiliar with. Over the course of the book you’ll write each one of these yourself, and we’ll take the time to thoroughly explore them.

Composing functions

We’re now familiar with all the main functions of the pattern viewer.

Next, we’ll make a function of our own.

Let’s compose a sequence of coe‑xx functions to create a specific view. We’ll code these up into a xx‑view function in the next section.

Take a look at the demo to see what we’ll create:

Call M‑x normal‑mode to put logo.xx in its original state.

Call M‑x coe‑demo‑xx‑view.

The demo displays a pattern grid with rulers and adds a single pattern to the basket .

Create the same view as the demo by calling a sequence of coe‑xx functions. You can reset the buffers by calling M‑x normal‑mode and M‑x coe‑xx‑basket‑clear.

Write down the sequence of functions you called.

Next, we’ll turn this sequence into a proper function.