Emacs ringing system: User instructions

There are two main ways to use the emacs ringing system:

as a major mode for visiting a microsiril library file, in which single-character commands to display and ring methods may be used
with interactive commands which can be typed from any buffer

For either of these, you will need to load ringing.el, which loads the other files as needed.

microsiril mode

For this, you need to set auto-mode-alist up to put microsiril files into microsiril mode.

From the msiril library file, you can type the command keys:

return: ring the method on the current line, interactively
?: display the method on the current line
r: teach one randomly chosen lead of this method
r: teach randomly chosen leads of this method until the user's had enough and calls stand!
p: print the method via postscript (see printing via postscript)
p: print a group of methods via postscript (see printing via postscript and using method groups)
v: preview the method via postscript (see printing via postscript)
v: preview a group of methods via postscript (see printing via postscript and using method groups)
m: mark or unmark the method at point, as part of the ephemeral group of methods for this buffer (see using method groups)
&: display the result of combining the method at point (for above the treble) with the method at mark (for below the treble).
w: list the methods you have tried, lead by lead, worst lead first (see record keeping)
w: teach you to ring your present worst lead (see record keeping)
l: show your log of methods tried
x: explore the method as a full grid -- see full grid exploration and editing
m-e: edit the method, as a full grid -- see full grid exploration and editing

you can also type digits (and e, t for eleven and twelve) which the commands working on whole plain courses take as which starting bell to draw the red line for.

Interactive commands

The interactive commands which may be used from any buffer are:

m-x ringing;show-plain-course
m-x ringing:ring-plain-course
m-x ringing:show-touch
(ringing touches interactively is not yet written)
m-x ringing:teach-random-lead-of-method
m-x ringing:teach-random-leads-of-method
m-x ringing:teach-each-lead-of-method-until-perfect
m-x ringing:teach-random-methods-from-file
m-x ringing:teach-random-methods-from-group
m-x ringing:teach-with-mad-conductor
m-x ringing:teach-lead-until-perfect
m-x ringing:teach-each-lead-of-method-until-perfect
m-x teach-ringing:display-all-teaching-data
m-x teach-ringing:forget-mistakes
m-x ringing:display-anonymous-method

It will then prompt you for the information it needs, such as the method to ring (and for the first time, will first ask you where the methods are stored), and then (if you are ringing interactively) which bell you want to ring manually.

These commands offer you completion wherever possible, such as on method names. To make this possible, they have to read all the method library files for the stage concerned, which takes a while. An ``*apologies for the delay*'' buffer is presented while this is in progress, which, once each files has been read, shows how many methods it defined. While the reading happens, the method names are flashed up in the minibuffer, so you can see how far into the file it has got... At least the first letter or so stays the same for long enough to read on the longer files, and the methods are in alphabetical order in each file.

See the configuration documentation for how to configure the system.

Ringing interactively (command `m-x ringing:ring-plain-course`)

Having selected the method and the manual bell, you then ring by typing the number for place you want to ring in next, (with e t a b c d for eleven, twelve, thirteen... must be in upper case as lower case are used for other purposes), starting with the first row after rounds, or using the cursor arrow keys thus:

left arrow: move down a place
down arrow: make places
right arrow: move up a place
up arrow: stand (and stop displaying the method buffer)

The method so far is drawn in a buffer as you ring. If the option ringing:highlight-bad-rows is set, rows on which you've made a mistake are highlighted. A more detailed report is available when you're using the teaching commands.

When the course comes round, it will stop automatically (and anything further that you type will be inserted at the end of the buffer).

The keys z, x, and c as alternatives to left, down and right arrows, to make ringing left-handed easier (to spread the load between the hands, to reduce rsi). Likewise, q w d or q w e may be used for left, down, and right. (These must be lower case, as c, d and e are used for bells 15, 16 and 11.)

Ringing in real time

If you enable the flag ringing:use-timing (using m-x ringing:set-one-variable or m-x ringing:set-variables), as well as the keys described above you can use the space bar to indicate when to ring. An indicator is drawn in the echo area showing how far in the possible time range you are: a lengthening series of . is drawn, with : used to mark the boundaries between ringing early enough to come down a place, late enough to go up a place, or to make places; the centre being marked with |. These boundaries are marked by the variables ringing:time-early and ringing:time-late, which are integers indicating how far they are into the maximum time in which you can try to ring; the number of time steps (to which these are relative) is set by ringing:time-max, and the duration of a step is set by ringing:time-step. These are not yet settable from the option variables commands.

Ringing non-interactively (command `m-x ringing:show-plain-course`)

The method is drawn in a buffer, row by row, with a pause (adjustable) between rows. To make it hurry up, just press ctrl-l to make emacs' pause routine (sit-for) assume you're ready to type some more.

Teaching

Some of the commands are for teaching you methods: they optionally draw the line for one lead (according to teach-ringing:preview-leads -- some prefer to have it drawn for them, some to test themselves without being reminded), then give you the chance to ring it. Some of these commands give you random leads, and others work through them systematically. You can get a teaching report to show what mistakes you've made on which rows.

Systematic teaching

The command m-x ringing:teach-each-lead-of-method-until-perfect gives you each lead of a method in turn, repeating each lead until you get it right. This is described in more detail on the intensive teaching page.

m-x ringing:teach-lead-until-perfect: teaches the specified lead of a specified method, by showing you the lead and then getting you to ring it, until you've got it right some number of times -- see the intensive teaching page for more details.
m-x ringing:teach-each-lead-of-method-until-perfect: does ringing:teach-lead-until-perfect on each lead in turn, also first showing you the whole line, and afterwards giving you a plain course to ring.

Random teaching

A group of commands for throwing random leads (from suitable collections) at you are available, along with commands for displaying a summary of your mistakes, and resetting the mistakes data.

m-x ringing:teach-random-leads-of-method: picks random leads of a specified method, optionally shows you each lead first (controlled by teach-ringing:preview-leads), and gets them to ring it. this ends when you give a stand command (up-arrow).
m-x ringing:teach-random-lead-of-method: picks one lead of a specified method.
m-x ringing:teach-random-methods-from-file: picks random methods from a method library file, and each time picks a random lead for you to try.
m-x ringing:teach-random-methods-from-group: picks a random method from a group as specified in a groups file. this can also be called from method-group-mode as method-group-mode:quiz-random-leads, in which it is normally bound to q. with a prefix argument other than 1, it stops after that number of leads.
m-x ringing:quiz-at-stage: Tests you on random leads from a group that you've defined for the purpose. These groups are called quiz-n where n is the number of bells (as a number), and are in the groups directory along with the other groups files. If called from a shell mode buffer, this command shows you the shell buffer after each lead, for ringing:quiz-between-leads-delay-time seconds (so you can use this while waiting for a compilation to finish, for example).
M-x ringing:teach-with-mad-conductor: Calls a touch from a specified group of methods, with bobs, singles and changes of methods coming randomly.

Teaching reports

These commands handle reporting of your mistakes.

M-x teach-ringing:display-all-teaching-data: Displays a report on the faults you've made so far in each lead of each method while using the teaching commands above.
M-x teach-ringing:display-one-lead-teaching-data: Displays a report on your mistakes in a specified lead of a specified method.
M-x teach-ringing:forget-mistakes: Resets your faults list.

Using microSiRiL method libraries

The method libraries are used both from microSiRiL mode and from the independent interactive commands.

To use the method libraries, pick them up from microSiRiL method libraries on sunsite and place them in ~/ringing/method-libraries/ (or the place named by the emacs variable method-library:directory).

Full grid exploration and editing

The full grid commands draw a method as a full grid of one lead, using ASCII graphics, and, if editing, let you alter the places and crossings made.

The method is displayed with a giant cursor made by highlighting and underlining the pair under consideration. The command placenotation-mode:symbol-here (normally bound to *, and also via a command on the right mouse button) tries to re-arrange the places and crossings so that one of them goes through the character position that point is on.

Using method groups

You can provide a collection of method groups in a directory specified by method-groups:groups-directory. A groups file looks like this:

# Standard Eight methods, particularly for Major
s Cambridge
s Yorkshire
s Lincolnshire
s Rutland
s Superlative
s Pudsey
s London
s Bristol

where the letter at the start of each line (along with the number of bells) gives which file in the methods library directory, for example when ringing major, s refers to the file s8. An optional number immediately following the letter makes it into a full library filename, for example s8.

Letters in brackets after the names may be given for reference from touch files (however, touch files are not yet implemented). For example,

s8 Cambridge(C)

Lines of the form

key=value

set some further fields of the data structure representing the group. Currently, these are used only to set style defaults for printing via PostScript. Currently defined keys are:

method-title-style: Sets the default style for titles of individual methods
line-style: Sets the default style for plotting methods
layout-style: Sets the default style for layout of the group as a whole
group-title: The method title; if this is not given, a comment on the first line is tried, and, failing that, the last part of the filename is used.

Ephemeral groups

Each buffer in mSiRiL-mode can have an ``ephemeral group'' associated with it. To toggle whether the method at point is in the ephemeral group, press m. Methods currently in the ephemeral group are highlighted in their buffer.

Ephemeral groups are also constructed from the touch book and from all the methods you have rung in this emacs session.

Ephemeral groups are like any other method groups, but are generated by emacs and not read from files (and so are not kept from session to session, unless you put something in an emacs state saver to do so).

Special group files

The group names quiz-n are used by the command ringing:quiz-at-stage to find which methods the user would like to be quizzed on for each number of bells.

My own older method file format

As well as microSiRiL method library files, the program can read methods from a format based on the Ringing World diary.

Record keeping

The package keeps a touch book for you, in the file ~/.touch-book.el. The command M-x touch-book:list-my-methods displays which methods you have rung, along with how many of the attempts were perfect.

The command touch-book:worst-leads-first (normally bound to w in mSiRiL-mode) produces a buffer containing list of leads that you have tried, ordered by the proportion of attempts that you have got wrong so far; thus, the top entry in this buffer is something you're at which you're likely to need more practice. The command touch-book:teach-worst-lead (W in mSiRiL-mode) will do this for you, using the intensive teaching functions. After this, the list will re-order itself according to how well you done this time.

The command touch-book:revise-my-methods will take you through all your leads in order of difficulty, asking you whether you want to try or skip each one, or quit. With a prefix argument, it will start at the one at which you've done best, instead. This is bound to v in mSiRiL-mode.

Within the buffer listing your performance on each lead, the command g will re-order the buffer to catch up with any ringing you've done through commands that don't update the buffer; RET will teach you the lead that point is on,v will go through the leads for revision, and w will teach you your current worst lead.