JOT Examples

This is a set of examples for those who just want to get their hands dirty without going into the finer details of jot - such details may be found in the jot user guide and the jot technical guide.

Examples Syntax

In the forgoing text the following shorthand applies (see About metasyntax):

• This is a description of some text rather than the literal text: <description>

• This is an instruction for you to you, type something in response to the computers Command-Line Interpreter prompt (CLI - e.g. the Windows console or unix shell):

$ <a CLI Command>

• This is an instruction for you, type something in response to the editors command prompt:

> <a jot command or key>
• {Key} - This specifies a key on your keyboard.

• {Esc key1[ Key2[ Key3]]} This specifies a sequence keys in order (as read from left to right) e.g. {Esc w t} means hit the Escape key, followed by the ( w } key and then the ( t ) key.

• {[ModKey1[+{[ModKey2][+...]]]+FunctionKey} This means press and hold one or more Modifier keys (Ctrl, Alt and/or Shift) and then hit the function key., the function key is typically one of the top-row function keys, a mid-keypad or numeric-keypad key. E.g: {Ctrl+Alt+F3} means hold down the Control and Alt keys while giving the F3 function key a dab.

N.B. literal env-variable references of the form ${<envVariableName>} (e.g: ${JOT_HOME}) should not be confused with the {<key>} metasyntax.

The name of the key given in the curly brackets is generally the name printed on the key cap. The main exceptions are the beancounters keypad where the key names are prefixed KP_ and the cursor control keys referred to as {UpArrow}, {DownArrow}, etc..

• << ... >> - is a reference to some jot function. This might be attached to a hotkey e.g. <<FindNext>> refers to the jot FindNext function, normally attached to {F8}.

• [<optional>] - some optional element of a command syntax.

• [<option1>|<option2>|...<lastOption>] - a series of optional alternatives, you may give one or more of these.

• [|<option1>|<option2>|...<lastOption>] - a series of optional alternatives, you must chose none or only one of these.

Basics

Jot is a command-driven screen-based editor - it obeys commands either typed-in directly or picked up from function keys etc and it maintains an screen image of the text being edited and displays changes as they happen.

Text is held in buffers, in the form of a complete file image or fragments. Jot maintains a number of buffers. Each buffer is identified by a single character key, typically A to Z, 0 to 9 and the various punctuation marks etc. In addition to these buffers may be created and destroyed in the jot operand stack - more about that later but, for anyone wanting to disappear down that rabbit hole right now - take a look at the stack.

Jot has a small number of primitive commands and some structure-building syntax elements. On completion, most commands return a success/failure indication which can be picked up by the structural elements of the language.

Sequences of commands can also be held, as text, in buffers (a macro) and macros can be run and will deliver status results like the primitive commands.

Starting jot for the first time

The usual way to start jot is from a command line - i.e. an xterm (linux) or a console (windows). It is also possible to set it up to fire up from an icon of your choice - but then since you can't explicitly-specify a pathname you will have to hunt around in some idiotic menu to identify the file you already knew you wanted to work on.

Assuming your environment is set up correctly (see installation) in linux you can start the editor from the command line from an xterm like this:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt

In windows, start from a windows console (or MS-DOS prompt window) with exactly the same commend:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt

notice that the JOT_RESOURCES env is presented in the unix/linux form ${<envName>} - this form is ignored by the MSdos command-line interpreter which passes it through to jot. You are, however, at liberty to let the CLI do the translation thusly:

$ jot %JOT_RESOURCES%/Richard_III_Entire_Play.txt

You should see the text appear in your terminal window - as the name suggests it's Richard III by Shakespere. This text was chosen as it's long, well known and very much out of copyright. This version was downloaded from: http://shakespeare.mit.edu/richardiii/full.html - thanks.

At the bottom of the terminal window you should see the prompt "1 .> " This is an invitation to type commands to the editor the '1' is the line number, the '.' is the buffer key - see below.

Look at the jot display

Look again at the Richard III session you started earlier.

• Notice the screen is split into two areas. At the top there's an image of the file - a display window,

• then there's a delimiter line in reverse video showing the pathname and the buffer key.

• Finally, at the bottom, is the console area. Immediately after startup there should be four messages visible - these originate from the various scripts that comprise the startup procedure. Finally, in the bottommost line there's a command prompt "1 .>" this in invitation for you to type in a command. The ( 1 ) indicates that we are currently focused on line 1 of the text. The full stop (or period, according to taste) ( . ) indicates which buffer we're looking at. In jot the main buffers are identified by a single character. The buffer associated with ( . ) is the primary buffer containing an image of the file specified in the command line.

The startup script (more about that later) has set the size of the main viewing area to leave you with one line in the console area. Any messages sent by the editor are displayed by encroaching into the display area, they will disappear when you enter a command or just hit {Return} This allows you to see any messages jot sends to the console area. After you've looked at the messages hit return to clear them off the display without affecting the text in any way:

> {Return}

Now look now at the top-left corner of the window - it should be displaying a tilde ( ~ ) in reverse video. The reverse video indicates that this is the current cursor position, the tilde indicates that the cursor has moved to the right of any displayable text - that's because this file starts off with an entirely blank line.

Jot Messages

We will be seeing a lot of error and warning messages soon - so it's a good plan to know what they look like and understand what they're saying. We're going to type in a command that's guaranteed to generate a warning. Just type in the letter ( r ) and then return - r is the command to move the cursor one character rightwards and, since it's already at the end of a line, jot will inform you that the command failed:

> r {Return}

The response should be:

{Command-sequence failed.}(1)r

The message comes wrapped up in curly braces followed by a number in brackets and the full command line, with the failing command highlighted. The number following the message is the command counter, this counts commands executed up to and including the failed command since the command was launched by the {return}. It is useful for debugging long complicated command strings involving macro and function calls.

Now try this:

> m1234m-1234r23m1234m-1234

This first tells it to move the cursor 1234 lines down the file, 1234 lines back - it did that alright and, unsurprisingly, we ended up exactly where we started. It was then instructed to go right 23 characters then forwards and backwards 1234 lines again. It's the same message, but now the highlighting identifies the failing command ( r23 ).

Some basic commands to get started

These are the most basic operations for anything claiming to be some sort of text editor - staying with the session you started earlier:

• FindNext {F8} and FindBack {F7} note that the search string is entered before hitting th function key. eg to find the next occurrence of "king":

> king{F8}

Look at the screen, in linux the ( k ) in kink is displayed in reverse video, the remaining characters are underlined the k is now the current character and the substring "king" is the current substring - we'll be looking at the significance of that later. In Windows, the current character and current substring are displayed differently.

To find the next instance:

> {F8} > {F8}

the editor remembers the last-searched substring so you don't need to retype it. {F7} is similar except that it searches back up the text.

> {F7}

it goes back up the text locating the previous instance of "king".

• Now use the find primitive directly:

> f/king/{Return}

That's all there is to command-driven working, note the absence of any special manoeuvres to get it to take your command - you just type something in, hit return and your entry is taken as a command.

• Substitute string {F5} substitutes the currently-selected substring with the given new substring. eg:

> aardvark{F5}

the currently-selected substring is changed to "aardvark" and this word becomes the currently-selected string.

• Insert a substring {F6} - inserts the given substring at the current character position and the given substring becomes the currently-selected substring. eg:

> wonderful{F6}
• We have already encountered one of jot's primitive commands - F (find) there are about 20 of these primitive commands - basic editing functions, these move the cursor, find, substitute, verify assertions move slabs of text between buffers etc. - the sort of thing you'd expect to see in any editor.

In addition to those text-editing primitive commands, there are a number of housekeeping commands, dealing with I/O (input and output), interaction with the operating system, adjusting parameters of the display and parameters and querying system information. Lets start off with a few essentials:

• Exit and save the primary buffer %c - note, this fails and refuses to exit if you do not have permission to write this file or if you are currently editing some buffer other than the primary buffer.

• Exit without saving %a (abandon).

• Save - write the buffer back to the filing system %o (output). Pathname defaults to the one remembered from when the file was read.

• Save-as - write the buffer to some specified pathname - %o=<pathname>

• Read specified file to a buffer - %i<key>[=<pathName>] -

• <key> is a single-character buffer identifier key,

• <pathName> specifies the filing-system path file name add name extension, missing elements are filled in from the pathname of the current buffer and, failing that, from your PWD.

• Enter - a new line of text is inserted below the current line. The line is first typed into the console area and then the <<Enter>> function is invoked. This function is attached to the {KP_Enter} key (The {Enter} key on the numeric keypad - but, for those without a numeric keypad, it is also attached to the escape sequence {Esc e}

> This is a completely new line of text I've added.{KP_Enter}

or

> This is a completely new line of text I've added.{Esc e}

Notice that the new line inherits the indentation level of the previous line.

Some Basic Function Keys

• The up and down-arrow keys move to the begining of the previous or next line respectively.

• Do it again {F10} - whatever command you last did, make it happen again.

• Repeat to exhaustion {Shift+F10}, like it says on the tin, it will repeat the command until it fails But with the added bonus of telling you how may times the command succeeded. This is particularly useful if you want to know how may instances of a given string exist in a buffer. Suppose we wanted to know how many instances of "king" there are in Richard III we might use the AgainExhaustive function:

> m-0 > king{F8} > {Shift+F10}

AgainExhaustive replies with: "Completed 450 repeats of ..." Note that the reported count does not include the original command. Note that AgainExhaustive will count successful repeats of any function or command string but some functions, by their nature will *never* fail.

• Entering text. Like most other modern editors, jot has an insert mode but it's generally easier to stay in command mode - see Command-mode vs. insert mode.

To insert some new text into a preexisting line, move the cursor to the required place then use the Insert function.

> <newTextString>{F6}

To insert a new line of text, there is the Enter function for entering new lines of text - either {KP_Enter} (that's the enter key on the numeric keypad) or, if you don't have a numeric keypad, then {Esc e}:

> <lineOfText>{KP_Enter}

or

> <lineOfText>{Esc e}
• Navigation through, deletion and restoration of text.

• The left and right arrow keys move, unsurprisingly, left and right. If at the end of a line, the rightarrow key moves to the start of the next line, the behaviour of the leftarrow key is similar. When combined with the Alt key, these delete the previous/next character respectively.

• With the Shift key, left/right arrow keys move to the start of the previous word or the end of the next word respectively. With shift and Alt they delete the previous or next word respectively.

• With the Ctrl key, left/right arrow keys move to the start or end of the line respectively. If already at the start/end of a line they move to the relevant position of the previous/next line respectively. With Ctrl and Alt they delete to the start/end of the line respectively.

• {Ctrl+Shift+Alt+LeftArrow} restores one character previously deleted by {*Alt+LeftArrow}, similarly for {Ctrl+Shift+Alt+RightArrow}.

• {Esc r l} (RestoreLineRight) will restore a complete line.

Continue to play around with the text file:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt

To see all of the available function keys and to explore their functions in jot, start up a qr (quick-reference) session:

$ jot -st=qr

or follow this link: jot quick reference

Do a few easy edits with function keys

Try out a few of the edit keys mentioned in the Some Basic Function Keys section. For full details and all the other predefined keys look at functions defined at startup and key bindings. First try hitting the cursor-control keys a few times - one surprise may be that the up and down-arrow keys move to the start of the next/previous line. Why-so some may ask - after all every decent editor aims to hold the cursor to a column? Put simply, the jot behaviour is more likely to be useful and, when it is required to hold the cursor to a column, jot offers a more predictable way of defining which column - see NewWordUp and NewWordDown.

Now try the up/down/left/right-arrow keys while holding down the Shift key - this moves left or right by a full word or up and down in a column.

Try a search using <<FindNext>> the {F8} function key, note that, in jot, arguments to functions are entered before hitting the function key:

Now just hit {F8} a few more times with no search string - each will find the next instances of "gloucester" {F7} key is similar but searches back:

Now use the <<Insert>> function ({F6}) to insert the string abcdef

Now, using the <<Substitute>> function ( {F5} ) to change that to 123456

Now play around with the <<FindNext>> {F8}, <<FindBack>> {F7}, <<Insert>> {F6} and <<Substitute>> {F5} keys. Then re-read a clean copy of the original file with the %I command:

This re-reads the original file into the buffer, destroying all your changes. If you're concerned that jot doesn't prevent you throwing away your precious work, take a quick look at about not losing your work.

A few more basic function keys

Every editor has to have some way adjusting the view and of copying and moving slabs of text.

In jot cut and copy operations are done by first noting the start of the desired section and then moving to the end of the section to copy or cut (abstract in ecce-speak).

• <<Note>> - {Ctrl+Shift+F1} - Remembers the current cursor position for later a Cut or Copy operation.

• <<Cut>> - {Ctrl+Shift+F2} - moves text, starting from the previous <<Note>> operation to the current cursor position, text is placed in the _ buffer.

• <<Copy>> - {Ctrl+Shift+F3} - similar to Cut except that the source buffer is unchanged.

• <<Paste>> - {Ctrl+Shift+F4} - text in the paste buffer ( _ ) is inserted immediately before the cursor.

• <<ViewUp>>, <<ViewDown>>, <<ViewLeft>> and <<ViewRight>> ( {Shift+UpArrow}, {Shift+DownArrow}, {Shift+LeftArrow} and {Shift+RightArrow} respectively). These adjust the position of the text on the screen but do not effect the buffer being viewed.

• <<WindowStretch>> and <<WindowShrink>> ( {Ctrl+Alt+DownArrow} and {Ctrl+Alt+UpArrow} respectively). These adjust the size of the view, not by changing the xterm dimensions but by expanding or shrinking the area dedicated to displaying the buffer.

First move away from the start of the text image and then try the ViewUp and ViewDown functions:

> york{F8} > 10

You located the next occurrence of "york" and then repeated that command a further 10 times - typing a number always gives you the specified number of repeats of the previous command.

> {Ctrl+Shift+UpArrow}

This shifts the view up the screen by one line.

> 10{Ctrl+Shift+UpArrow}

This shifts the view up the screen by ten lines.

Next try copying a section of text:

> {Ctrl+Shift+F1}

This sets the note point at the start of "YORK"

> {F7}

Locates the previous "YORK"

> {Ctrl+Shift+F3}

This has copied the slab of text.

> zq{return} > {Ctrl+Shift+F4}

We've moved to the buffer ( q ) and copied the text there. Now return to the main buffer.

> z.{return}

Deletion and restoration of text

• <<DeleteChrRight>> {Alt+RightArrow} deletes the character under the cursor.

• <<DeleteChrLeft>> {Alt+LeftArrow} deletes the character left of the cursor.

• <<DeleteWordRight>> {Alt+Shift+RightArrow} deletes from the cursor to end of word.

• <<DeleteWordLeft>> {Shift+Alt+LeftArrow} deletes from the cursor to start of word.

• <<DeleteLineRight>> {Ctrl+Alt+RightArrow} deletes from the cursor to end of line.

• <<DeleteLineLeft>> {Ctrl+Alt+LeftArrow} deletes from the cursor to start of line.

• <<RestoreChrRight>> {Ctrl+Shift+Alt+RightArrow} restores one character under the cursor.

• <<RestoreChrLeft>> {Ctrl+Shift+Alt+LeftArrow} restores one character left of the cursor.

• <<RestoreWordLeft>> - {Esc - l w} restores one leftwards-deleted word to the current character position.

• <<RestoreWordRight>> - {Esc - r w} restores one rightwards-deleted word to the current character position.

• <<RestoreLineLeft>> - {Esc - l l} restores one leftwards-deleted line to the current character position.

• <<RestoreLineRight>> - {Esc - r l} restores one rightwards-deleted line to the current character position.

In the context of the word-orientated functions, a word is any string of ascii alphanumeric characters bounded by either non-alpha characters or the start or end of the line. At present jot treats all unicode as non-alpha characters.

Note that there is only one graveyard for deleted text (the % buffer). All <<Delete...Right>> functions move deleted text to the end of this buffer, all <<Delete...Left>> functions move text to it's start. This means the <<RestoreWord...>> functions will restore characters and words deleted by the <<DeleteChr...>> functions and similarly <<RestoreLine...>> functions will restore words and characters that were not part of the original deleted word.

Getting help

Jot supports an online help system. The <<Help>> function uses specially structured files derived from ordinary jot documents (see About help files). The structure of these documents is quite simple, entries are bounded by fold marks '{{{' and '}}}' at the beginning of a line and these may be nested to any depth.

The help entries you are about to look at are images of files in ${JOT_RESOURCES}/help/...

When the <<Help>> function is invoked for the first time in a session, it presents you with the contents of the file ${JOT_RESOURCES}/help/help.hlp yours should contain some instructions and three entries:

The square brackets indicate that this is a file fold - it is currently empty. Opening it causes the file to be read. The cursor should already be on the jot entry, open it by calling <<Help>> again:

It opens up similar screen but this one contains four entries - these are all help files made from jot documentation. The cursor should be on the jot_ug entry so open that one:

This page announces that you're looking at the jot user guide and contains just two entries - these correspond to the two top-level entries in the user guide.

To descend another level down the hierarchy move the cursor to any part of a line starting with a fold mark and hit {F1}, to return back up the hierarchy move the cursor to any line without a fold mark and hit {F1}.

At any time you can return to your original work buffer e.g:

and then return to the help entry you last looked at:

Jot windows and views

Jot splits terminal into various sections referred to as windows, by default, jot displays only one buffer in a simple window as described previously in Starting jot for the first time.

It is possible to split the display to view more than one buffer at the same time. These functions are provided to help you tweak the display to let you see everything you need to look at:

• {Esc w 1} - 'WindowOne' - Restores a basic single window display, clears colour tags in current buffer and resets the buffers leftoffset (see About long lines) to 0.

• {Esc w v} - 'WindowVertSplit' - Splits the display vertically.

• {Esc w h} - 'WindowHorizSplit' - Splits the display horizontally.

• {Esc w -} - 'WindowShrink' - Reduces the height of a simple window, split-window behaviour is a bit more complicated.

• {Esc w +} - 'WindowStretch' - Increases the height of a simple window, split-window behaviour is a bit more complicated.

• {Esc w s} - 'WindowSave' - saves the current window configuration for later restoration.

• {Esc w r} - 'WindowRestore' - restores a previously saved window configuration.

• {Esc w l} - WindowWithLineNumbers - adds/removes linenumber slice.

• {Esc v s} - 'ViewSave' - saves the current view for later restoration.

• {Esc v a} - 'ViewAgain' - restores a previously saved view.

First try a simple horizontal split. Start a session on Richard III:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt

Now read in another two buffers with different files:

> %ia=${JOT_RESOURCES}/UTF-8-demo.txt > %ib=${JOT_RESOURCES}/l99.t

You should end up looking at l99.t in buffer b. Now do a simple horizontal split:

> {Esc w h}

The screen is now split between to (roughly) equal windows, the tom one is dedicated to buffer ( B ) (this buffer was current when WindowHorizSplit was called, and a floating screen, currently displaying nothing.

The floating window will display the current window except, as is the case, when the current window is already displayed in another window. Let's display something in there - go back to the primary buffer:

> z.

Back comes Richard III, go back to the UTF-8 test file:

> za

Invoking WindowHorizSplit will add another window by splitting the screen into three roughly equal windows ... etc. But now try splitting vertically. WindowVertSplit will count how many windows are currently in the display and reconfigure the display as n+1 vertical slices, where n is the current window count.

> {Esc w v}

The screen is now split into three vertical slices, the first (leftmost) slice is dedicated to buffer ( B ), the next (centre) is the uTF-8 demo and the last (rightmost) slice is floating because the current buffer is being displayed in the centre window. Switch to the primary buffer to fill that floating window.

> z.

Now save this window configuration using WindowSave:

> {Esc w s}

The display flips back to the default single-window display. WindowSave can be given an optional name parameter allowing you to save any number of named window configurations but for now, we'll keep it simple. Try shrinking the window by one line:

> {Esc w -}

or

> {Ctrl+Alt+UpArrow}

Repeat either of these a few times (remember {F10} will repeat the last command). This expands the console area allowing it to display more lines of messages.

Now stretch the window with WindowStretch

> {Esc w +}

or

> {Ctrl+Alt+DownArrow}

Repeat until you're back to a single-line console area.

In a split-window environment these functions stretch or shrink the window displaying the current buffer - split the window again:

> {Esc w h} > za > {Esc w -}

This shrinks the window displaying the current buffer ( a ). Repeat that a few times then switch back to the primary butter ( . )

> {Esc w -} > {Esc w -} > z.

Now stretch this window:

> {Esc w +} > {Esc w +}

Now restore your vertically-split display with WindowRestore - this, like WindowSave takes optional name parameters but our saved window configuration was saved with the default name.

> {Esc w r}

In a vertically-split screen, WindowStretch/Shrink change the width of the current slice - go back to leftmost slice as this makes it easier to see what's going on the shrink by a few columns:

> zb > {Esc w -} > {Esc w -} > {Esc w -}

Now back to buffer ( a ) and stretch:

> {Esc w +} > {Esc w +} > {Esc w +}

Sometimes it's useful to have the line numbers displayed - most other times the linenumber prompt is sufficient and we don't want to waste screen space on line numbers. To display line numbers use the WindowWithLineNumbers function:

> z. > {Esc w l}

Now move around in the main buffer - the linenumbers will follow.

When you've seen enough - make it go away:

> {Esc w l}

Note that this line numbers display will only work with a simple window.

You can save and restore a view with the WindowSave and WindowRestore functions these also take optional name parameters. Move to any point in any of the three buffers ( . a or b ) and save the view with the default name:

> {Esc v s}

Now go to some other point in any of the buffers and save a view with the name fred:

> fred{Esc v s}

now go to any other point in any of the buffers and save that view with the name jim:

> jim{Esc v s}

You may now hop around between these views:

> {Esc v r} > jim{Esc v r} > fred{Esc v r}

...

Line shuffling

Sometimes, perhaps we're splitting a paragraph into two, all we need to do is to push some words from the end of one line and prepend them to the next line. Or, maybe, lop words from the start of a line and append them to the previous line. These two requirements are met by the <<AppendRightNext>> {{Alt+F10} and <<AppendLeftPrev>> ( {Alt+F9} ) respectively.

Returning to Richard III we notice that Shakespere could have achieved a more optimal text density. Given the size of a typical "complete works" there'd be loads more trees standing now if only if only he'd bothered to cram a few more words on each line. Let's sort it out for him:

That seems to have done it, but, oh dear! it doesn't seem to scan quite right now, maybe there is something to be said for his iambic pentameters after all - better put it back the way it was. Fortunately <<AppendRightNext>> will do exactly that:

Another pair of functions, useful when editing programming languages, are <<IndentFromNext>> {Ctrl+Shift+F10} and <<IndentFromPrev>> {Ctrl+Shift+F9} - these change the indentation level of the current line to match, respectively, the previous line or the next line - first prepare some lines of differing indentation levels:

First inherit the indentation from the next line:

then from the previous line:

restore the text:

Using matching functions

The startup script defines some useful parenthesis and other matching functions:

• <<ParagraphUp>> {F3} and <<ParagraphDown>> {F4}, respectively, find the start and end of the current paragraph. In this context a paragraph is taken to be any number of non-blank lines of text bounded by either blank lines or the buffer's end points.

• <<ChapterUp>> {Shift+F3} and <<ChapterDown>> {Shift+F4} respectively find the start of the current chapter/code section and the start of the next chapter/code section. In jot a code section is deemed to be any number of lines beginning with an alpha character in the first character of a line. Typically in computer programming language subroutines and other sections are introduced with an un-indented keyword followed by indented code.

• <<MatchIndentUp>> {Ctrl+Shift+F7} and <<MatchIndentDown>> {Ctrl+Shift+F8} respectively locate the previous and next line with the same indentation level as the current line.

• <<MatchParenLeft>> {Shift+Alt+F5} first searches back through the text for the previous parenthesis-end ')' then finds it's matching start '('. <<MatchParenRight>> {Shift+Alt+F6} is similar except it searches forwards for the next '(' and then finds the matching ')'.

• <<MatchCurlyLeft>> {Ctrl+Shift+Alt+F5} and <<MatchCurlyRight>> {Ctrl+Shift+Alt+F6} are similar except that they operate on curly braces ( '{' and '}').

• <<MatchAngleLeft>> {Ctrl+Shift+F5} and <<MatchAngleRight>> {Ctrl+Shift+F6} are similar except that they operate on angle braces ( ' <' and '>').

• <<MatchMarkupLeft>> {Alt+F5} and <<MatchMarkupRight>> {Alt+F6} are similar except that they operate on html/xml blocks.

In the Richard III text play around with the ParagraphUp and ParagraphDown functions:

> z. > {F4} > {F4} > {F4} > {F3} > {F3} > ...

Open the test_block.txt file in your resources area - this has some simple examples of nested blocks and indentation:

> %it=test_block.txt;

First do an indentation match:

> level 3 start{F8} > {Ctrl+Shift+F8}

Another <<MatchIndentDown>> takes you into the curly brace match set.

> {Ctrl+Shift+F8} > {Ctrl+Shift+F7}

Buffers

In a modern text editor, the text you see on your screen is an image of the file as it currently exists as a text buffer in the computers memory. As the edit session progresses this may not match what's currently spinning in the filing system.

Jot supports a number of separate buffers each identified by a single-character key - the following buffers are accessible but some are used by jot scripts:

• . the primary buffer - by default jot starts up in this buffer.

• A-to-Z - not assigned any special meaning and are freely available for your use.

• 0-to-9 user-defined functions attached to numeric-keypad keys 0-9 but otherwise freely available for your use.

• ~ Temporary (stack) buffer or numeric value at top of stack - available for your use.

• _@#$ - may be used and redefined by jot standard startup functions.

• !"#%&'()*+-./:;<=>?@[\]_ may be used and redefined by scripts.

• ^ used for escape-sequence mapping - do not use or redefine.

• : is used to hold the help repository.

• ; is used for viewing help

To change focus to another buffer we use the Z command

• z<key> - zoom (i.e. switch context) to buffer indicated by the single-character key e.g. zq will switch context to buffer q.

You should be in buffer ( t ) at present, let's go back to the primary buffer ( . ):

Copying and Moving Text - 1

No text editor is complete without some facility for picking up slabs of text to be moved or copied. In ecce-speak this process is abstraction.

The first step is to indicate the start point for abstraction with the N (note) command then move the cursor and then abstract to the destination buffer with the A (abstract) command.

Normally there is a dedicated buffer defined by the system for copying and moving slabs of text. Typically known as the paste/pick/put/copy ... buffer, in jot you can use any buffer you fancy - given that some buffers may be used by hot-key functions defined by the startup script - see buffers. The predefined hotkey copy/paste functions use the '_' buffer.

The basic cut/copy and paste keys use the jot note and abstract commands:

• <<Note>> - Ctrl+Shift+F1} notes one end of the text to be moved at the current cursor position.

• <<Cut>> - {Ctrl+Shift+F2} removes text from the note point to the current cursor position.

• <<Copy>> - {Ctrl+Shift+F3} - copies (i.e. copies to the paste buffer without changing the original) text from the note point to the current cursor position.

• <<Paste>> {Ctrl+Shift+F4} - text in the paste buffer is inserted at the current cursor position.

We're going to pick up the phrase 'glorious summer by this sun of ' from Richards opening soliloquy and reinsert them.

The first and second lines of text, as far as York, disappears.

> {Ctrl+Shift+F4}

The text reappears.

The last two operations could have been performed by the copy function:

At this point, the text is still in the paste buffer and can be inserted anywhere you fancy in any of the editors buffers. You can also make the paste buffer ( _ ) the current buffer to check what's in there:

Now return to the primary buffer ( . ):

Adjusting focus and view.

Some of these operations are best done with a file with very long lines (i.e. wider than your terminal) load the test_table.txt file into buffer w.

Note that you did not need to type in the pathname to read this file, jot first tries to read the file from your PWD (present working directory), if it can't find it in there it tries prepending the path from the current buffer - in this case ${JOT_RESOURCES}, it should find ${JOT_RESOURCES}/test_table.txt

The file you've just loaded is a tab-separated tabular file designed to show up any jot bugs affecting the display of tabular text. Later we'll find out how to display this file properly. For now we'll display it as linear text, jot displays tabs (and all other control characters) as tildes ( ~ ).

Do a few <<Down>> {DownArrow} and <<WordRight>> {Shift+RightArrow} operations until the cursor approaches the right margin of your window. Now do another <<WordRight>> {Shift+RightArrow} watching the display carefully. The editor is scrolling the entire view rightwards to bring the currently-selected word into view. Also try <<WordLeft>> {Shift+LeftArrow}

• the behaviour is similar.

You can adjust the view manually with the <<ViewLeft>> and <<ViewRight>> functions ({Ctrl+Shift+LeftArrow} and {Ctrl+Shift+RightArrow} respectively), if you shift the view to the extent that the cursor slips off the left or right margin of the screen the editor will re-display the current section of the line in the console area.

Similarly, you can manually scroll up and down with the <<ViewUp>> and <<ViewDown>> functions ({Ctrl+Shift+Up/DownArrow}). Note that none of these functions affect the current editor focus, only the display - play around with these functions.

The <<WordUp>> and <<WordDown>> functions ({Shift+UpArrow} and {Shift+DownArrow} respectively) move up and down in a column. Now <<WordUp>> and <<WordDown>> use the ( Y ) primitive command. This will hold to the same column, ignoring the starting column. This behaviour is useful for moving up and down performing repetitive operations in tabular or similarly formatted text. But we will want to change column from time to time, this is done with the <<NewWordDown>> and <<NewWordUP>> functions ({Ctrl+UpArrow} and {Ctrl+DownArrow} respectively) . These reset the ( Y ) column offset to the current cursor position.

Now, tell the editor to display the text in this buffer as a table - we will be covering this in more detail in the next section. Just type this in:

> %b=tabstops -1

and play around with the {Shift+[Left|Right|Up|Down]Arrow} keys. Also insert some text to make one cell wider:

> abcdefghijklmnopqrstuvwxyz{F6}

and erase some characters from a cell to make it shorter than the others:

> e6{Return}

Occasionally you will want to shrink the view in your console in order to display more of the system messages flying past. Especially if you are using the jot debugger. The function to do this is WindowShrink ({Ctrl+Alt+UpArrow}) or to expand the view there's WindowStretch ({Ctrl+Alt+DownArrow} each of these adjusts the window size by one line.

> {Ctrl+Alt+UpArrow} > {Ctrl+Alt+UpArrow} > {Ctrl+Alt+UpArrow} > {Ctrl+Alt+DownArrow} > {Ctrl+Alt+DownArrow} > {Ctrl+Alt+DownArrow}

Some fancy flavours of find - 1

The standard startup script defines several more functions for finding text we're going to give them an outing now.

Return to Richard_III_Entire_Play.txt, it's in the primary buffer ( . ):

The <<FindExact>> function (normally {F9} ) will only match to a whole word or number - i.e. one bounded by the start or end of a line or any non-alphanumeric character, in natural-language text this would typically be whitespace or a punctuation mark. We will be searching for exact matches to the string 'our' - first go to the top of the buffer:

sure enough it matches to 'our' in 'Now is the winter of our discontent'

this time it matches to 'our' in 'clouds that lour'd upon our house' notice it did not match to the word lour'd in the same line. The function <<FindExactBack>> ( {Shift+F9} ) does the same sort of thing but searches backwards.

Some fancy flavours of find - 2

Now read the repetitive test file l99.t into buffer r, it's pretty dull but useful for demonstrating repetitive edits. Note jot is set up to respect env variables but only if they are expressed in the form ${<envName>}

First set the default find string to 'abc' and the default substitute/insert string to 'Abc':

The <<SubsThenFindNx>> function will now repeat the substitution and locate the next matching substring:

Hit {Shift+F8} a few more times. To repeat a command <n> times enter the number of repeats to the command line - let's change the next 10 occurrences of abc:

To repeat the last command until something fails type zero:

you should now be at the last line of the file (line 101) with all 'abc' changed to 'Abc'

Some fancy flavours of find - 3

One more function, quite useful when dealing with natural-language text, is <<FindSequence>> {Esc f q} - this identifies a string of words irrespective of punctuation, whitespace and line breaks.

it highlights the first word of the given list of words. The function <<FindSequenceBack>> ( {Esc - f q} ) is similar, except that it searches backwards.

Locating text in columns and blocks

These functions are probably not of much interest - except for specialised users dealing with text in line drawings, patterns for digital testing and digital simulation stmulii and reports. See The vertical-search functions for a brief description of what these functions do.

Full disclosure: jot has no find-vertical primitives - these functions are built entirely using normal left-to-right primitives.

First off, we need a sample of text containing meaningful text written from top-to-bottom in columns - we can make a suitable sample from Richards opening soliloquy of Richard III:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt \

-in="f/Now/r-0n.(rm)0aq&zq %h=call rotateDiagonal; m-0((i/ /r)0m)0 m-0"

What we've just done is copy the opening paragraph to buffer Q and rotate it around the leading diagonal. (see rotateDiagonal for details). Then to make it a bit easier on the eye, blank separator columns have been added. The four blank lines at the top correspond to the indentation of the original.

The text contains three instances of the word "clarence" towards the end of the passage (the original text is still available in buffer ( . ) if you want to check back), lets go and find them with the function findVert:

The search is case insensitive, by default, notice that the vertical string is highlighted as black text against a magenta background. Now find the next instance of "clarence":

and the final instance:

finally, this fails:

Notice that the current character is placed just to the right of the first character of the matching column. This behaviour simplifies repeated searches in the same direction.

There's also a backwards-searching version findVertBack:

These functions can also be used to search for incomplete specifications using simple wildcards, similar to the filing-system filename globbing.

• a ( . ) will match to any single character,

• a ( * ) will match to any number of characters if the characters following this wildcard match,

• blanks ( ) are ignored,

• any of these special characters may be escaped with a backslash ( \ ).

For example if we want to locate the line about Clarence being mew'd up:

The functions FindCol and FindColBack are similar except that they only operate in the current column.

As you can see, FindCol leaves the cursor immediately below the first matching character as does FindColBack:

Now this is a pretty contrived example to demonstrate searching for a block of text ... but here goes. The words "clouds", "bosom", "brows" and "arms" all happen to align nicely in the scrambled text so we're going to find them. First we have to construct a 2-dimensional search specification in buffer ( Z ):

clouds

bosom

brows

arms
:

Now run the search:

Note that this search specification is not rectangular, three of the search words are longer than the first word. the magenta rectangle it places over the matching text is in fact the closest-fitting rectangle and the height is determined by the longest matching string.

Using the Context-Proximity functions

The <<ProximityPara>> {Esc f p} function finds the next paragraph containing all of the substrings in the blank-separated list argument. We're going to find the famous "A Horse, a horse my kingdom ... " speech:

z.

the first matching paragraph is not what we're looking for so try it again:

nooo! try again.

Note that adding a second "horse" to the word list or changing the order of the list makes no difference.

The <<ProximityParaBack>> function ( {Esc - f p} ) is similar except that it searches back towards the start of the buffer.

This sample document is not structured into chapters recognisable to jot, the following manoeuvre reformats the scene-numbering lines. Note that jot's working definition of a chapter is any number of lines of text, bounded by the buffer limits or by lines containing an alphanumeric character in column 0. All this does is to identify these lines then remove the leading whitespace:

Regular expression usage

Many battle-hardened unix users are quite good at regular expressions, some may even enjoy using them (see %X for details). Here we're just going to demonstrate the jot %F interface to the gnu regular-expression functions.

now search back from, the end of the buffer.

Fancy flavours of substitution and insertion - 1

An occasionally-useful function is <<Overwrite>> ({Shift+F6}) which, as it's name suggests, overwrites whatever happens to be there with the given string.

Return to the test_block.txt this has some simple block diagrams.

this has a couple of simple block diagrams. There are some special functions for dealing with these but, for now, the important point about these diagrams is that if you just insert text with the simple <<Insert>> ( {F5} ) function it will mess up the picture to the right of the insertion point. For this job we need the <<Overwrite>> function - it's on {Shift+F6}. The first box lacks a label on it's third input:

A detailed look at a tab-separated table

Return to the test_table.txt file,

as we've already discovered, this contains table entries (cells) separated by tab characters - a special control character that emulates a manual typewriters tab key.

Manual typewriters! - remember them? Anyone who's looked inside of one will know exactly what tabstops are - little metal pegs that select where the carriage ends up after the tab key is pressed. This ensures that addresses, headings and tabular entries all appear in the right position on the paper. In computers and text editors a similar behaviour is mechanized with logical and arithmetic operations based on the tab character.

In jot tabstops work in much the same was as in manual typewriters - tabstops are a list of positions where the next column in the table is to appear. e.g. for four 8-character columns we might write:

%b=tabstops 8 16 24 32;

But it's a real drag typing in all that stuff - this command has the same effect:

%b=tabstops 8;

this sets the first column width to 8 and subsequent columns inherit the same width.

Setting the column width to -1 is an instruction to jot to calculate an optimal set of tabstops for the section of table that's currently in view.

Now, for tabular text we might find it easier if the header line was fixed in the window. There is a command to do this the line of text we want to use in this example happens to be the first line try typing in this command string:

The "m-0" element tells it to go back to the first line of the buffer, in this case, this happens to be the header line. "%b=header " is the command to set the header and the "'w" element indicates that the text to use for the header is in the current line of buffer w. With this set up we can move right down so the first line scrolls off the top of the screen and still see the header.

Play around with the <<WordRight>> {Shift+RightArrow}, <<WordLeft>> {Shift+LeftArrow}, <<WordUp>> {Shift+UpArrow} and <<WordDown>> {Shift+DownArrow} functions.

Tabular text - 1

When we look at some real tabular data using, say, a spreadsheet viewer we sometimes see that a cell has been truncated because the text-width in the cell is greater than the width allocated for that column. In contrast, our simple concept of tabstops will allow the cell to overflow into the next column - not really very desirable for real tabular data. Thus we have two slightly different settings:

• %b=tabstops <n1> <n2> ... ; - sets simple tabstops,

• %b=tabcells <n1> <n2> ... ; - defines columns similar to spreadsheets.

Staying with the test_table.txt session, first set the tabstops all to 12 characters:

now go to a cell on the screen and make it much wider:

The effect has been for the cell to encroach right across three columns - undesirable for tabular data like this. Of course we could set the tabstops to -1, then the editor would expand that column:

But, what a spreadsheet viewer would do would be to mark the over-wide cell and truncate it. The tabcells setting approximates to this behaviour:

Tabular text - 2

A line of tabular text consists of substrings (cells) separated by value-separator characters. By default, this separator character is Tab and tabs are represented on the screen, like any other control character, with a tilde '~'.

Read a more typical spreadsheet table into buffer e.g:

and tell the editor to display this as 6-character cells

this is equivalent to saying %b=tabcells 6 12 18 24 30 ... i.e. the default cell width is the width of the previous cell.

The main body of the spreadsheet should display in a nice neat tabular form with 6-character columns - not quite wide enough for some cells. In particular, the first column of the main spreadsheet is a year followed by Q{1-4} - this requires at least 8 columns to display clearly. When you've not given a column sufficient to display a cell, the cell is repeated in the console area of the screen. Looking a that we can see that the first column needs at least 7 characters to display properly.

We could ask the window manager to assign tabcells automatically, like this:

but some of the cells are very wide and tend to mess up the display.

Hit {Shift+DownArrow} and {Shift+UpArrow} a few more times, sufficient to scroll the screen - taking note of the way the column widths change. This is because tabcells -1 will adjust the column widths to accommodate the widest column-cell currently in view. See %b=leftoffset and about long lines.

Try this instead:

This makes the first two columns 8 characters and subsequent columns all inherit the 6-character width assigned to column 3. Also, the initial comments are in very wide cells and much of this text has been truncated. If the cursor ends up in a cell that, for any reason, has been truncated it repeats the cell text in the console area like this:

In the console area you should see something like this, showing the cursor in truncated cell and bits of it's neighbouring cells. If, as might happen in this case, you still can't see all of the cell, then press {RightArrow} until all of the cell is visible in the console area - it should look something like this:

onal care~Hairdressing salons and personal grooming establishments~Electrical ap

Finally, when scrolling through a spreadsheet it's useful to have a static header at the top. For this file we might chose the 4-character column key, this is on line 13 of the file:

Colour-tagged text

Jot supports user-specified colouring for specific strings in the text. In jot this is referred to as tagging text. There are two stages to the process first we define a colour scheme and assign it a name (see %b=tagtype) and then the tags can be added to the text (see %b=addtag).

We're going to define two colour pairs - a foreground and background colour combination is known as a colour pair. the colours identified by numbers in the range 0 to 7 - see %b=TagType for details.

The colour pair normal is used to switch back to normal text colour after the coloured-in cell. Now let's stick some colour on a cell:

m+40r8 %b=addtag red; r5 %b=addtag normal;r-0

Well it would be a real drag having to go round spreadsheets adding tags manually. In practice, the useful thing about colour tags is that they can be used to highlight important details that might otherwise have been missed.

Suppose we were interested in places where an entry for one row is less than the previous entry Now pick up the following, down-to and including '$ line, then drop it into the console area. It defines a little macro that highlights in red any cell that has a lower value than the corresponding cell in the previous year.

%g$
%%Macro to highlight spreadsheet entries where on year's entry in a column is less than the previous year.
%%
%%Clear any preexisting colour tags.
m-0n.m0a@h@
%%Locate first row with digits in column 1 - assumed to be the year.
m-0(q/0-9/\m)0
%%Initialize column counter.
ol0
( %%Column loop - index to next column, initialize previous-cell value to 0 then find start of yearly entries.

ol-1o+ ol0os m-0f/1997/ ( %%Year (Row) loop.

mm- %%Step past the year column. ((q/0-9 Q/r)0rq/0-9/\m)0 %%Now index to the current column. o# (o~ (q/0-9/r)0 r)0 ok (rr-, okokr-0 %x=All done;) %%Pick up value from this cell and compare it to previous. os (oid oso> %b=addtag normal;, %b=addtag red;) mos )0 osok )0

:
'$

Note that these tags can not persist beyond the current session, it's all done with metadata that is not part of the plaintext file.

Graphical text - 1

With this type of text, it is important to preserve the position of text to the right of the cursor. It is also important to have some line-drawing and block-move operations.

The most convenient way of doing this is with a numeric keypad - the startup script attaches the functions to the various numeric-keypad keys. Windows users should find these work anyway but linux users will have to set up the keypad with xmodmap - see X-windows setup. If you don't have a numeric keypad and you want to have a go at this, the functions are available as escape sequences but, trust me, it's a real drag doing it that way.

First clear buffer r by abstracting an empty string to r (it should be empty anyway) then move into it:

The buffer is completely empty, notice that the cursor-control keys ({[Left|Right|Up|Down]Arrow}) fail to shift the cursor off the top-left corner of the screen because there is no text to navigate.

In the empty buffer, you can navigate around using

These are attached, respectively, to the <<Left>>, <<RightRegardless>>, <<UpRegardless>> and <<DownRegardless>> functions the latter three insert blank lines and whitespace into the buffer as necessary.

So first have a little play with these keys. Move the cursor to somewhere near the centre of your screen.

Now draw the first hyphen of an easterly line by hitting

• users with no numeric keypad should do

> {Esc l e}

These call the <<LineE>> function. Now hit the repeat key {F10} five times you should see a horizontal line of six hyphens with the cursor one place to the right of the last hyphen.

Now draw a vertical line down using the <<LineS>> function, this is on

> {Ctrl+KP_2}

or

> {Esc l s}

and repeat this five times by hitting {F10} 5 times. Notice the corner - <<LineS>> detects the change in direction and left a blank at the corner to avoid any untidyness.

> {Ctrl+KP_4} or {Esc l w}

will draw a horizontal line using the <<LineW>> function - again it detects the change in direction and puts a blank at the corner. Finally

> {Ctrl+KP_8} or {Esc l n}

will draw a line going up, using the <<LineN>> function.

Graphical text - 2

In the previous section we looked at drawing wit simple ASCII characters namely Hyphen ( - ), vertical Bar ( | ) and blanks ( ) the latter, although not explicitly mentioned, are used to form corners and intersections.

In this section we'll look at how to use the unicode line-drawing characters. It turns out there are quite a lot of them. In addition to horizontals and verticals there are various corners and intersection characters - and three line-drawing font-styles - light lines, heavy lines and double lines.

As we've already seen, jot's line drawing defaults to simple ASCII hyphens and vertical bars, the first thing to do is to select one of the unicode line-drawing fonts. In the following we'll select light lines.

Now move the cursor to a suitably-empty part of the screen (using {Ctrl+KP_8}, {Ctrl+KP_2}, ... And start drawing:

Now move upwards and rightwards a couple of times:

Now draw a line down into the box

Notice that it has replaced the simple horizontal with an inverted-T intersection character. Now draw the line one step further down, into the box.

Notice that the inverted-T has been replaced by a crossover character and it has drawn another vertical-line character.

Now let's change font to double lines.

and start drawing towards the left side of the box.

It has inserted the correct crossover character.

Now for the bad news:

• There are some font-changing tees and crossovers missing from the character set - e.g: there is an asymmetric tee ( ┭ ) linking the light and heavy fonts but no similar tee for light and double fonts.

• The character-selection method does not always insert tees when it should - consider this example:

C D

A ╶─────┬─────┼───────── B

│ │

v ^

The line A to B was drawn initially, the line down from C was successfully added by starting at C and drawing down. The similar line was drawn upwards towards point D, instead of inserting a tee when it joined the vertical, it was necessary to draw past the horizontal and so ended up with a cross.

Graphical text - 3

The <<LineNE>>, <<LineNW>>, <<LineSE>> and <<LineSW>> functions draw diagonal lines with Slash and Backslash ( / and \ ) characters. On the numeric keypad these are attached to {Ctrl+KP_9}, {Ctrl+KP_7}, {Ctrl+KP_3} and {Ctrl+KP_1} respectively (for those without a numeric keypad use the following instead: {Esc \ u}, {Esc / u}, {Esc \ d} and {Esc / d}).

Try drawing a few lozenge shapes with these keys and draw a few lines mixing these with the horizontal and vertical drawing functions.

To cut and paste blocks of this kind of text use the <<Note>> {Ctrl+Shift+F1}, <<CutRectangle>> {Ctrl+Shift+Alt+F3} and <<PasteRectangle>> {Ctrl+Shift+Alt+F4}. The note point must be at the top-left corner of the rectangle you want to cut. First position the cursor to the top-left corner of the rectangle to be cut, then hit note:

then move the cursor to the bottom-right corner of the rectangle and cut the rectangle:

The cursor should now be back at the original note point and all the text in the rectangle has been replaced by whitespace.

To restore the original text use the <<PasteRectangle>> function - {Ctrl+Shift+Alt+F4} before moving the cursor. Then move to the place where you want the top-right corner to go and apply <<PasteRectangle>> again.

To create a complete box use the <<Box>> function, it takes two arguments, the box width and box height with the top-left corner at the current cursor position:

This creates a box 7 characters wide by 5 lines high.

To create a complete lozenge with it's apex below the current cursor position use the <<Lozenge>> function:

The DSLozenge function is similar except that the horizontal pitch is doubled:

Graphical text - 4

Each of the line-drawing functions take an optional text-string argument - this allows you to draw using text strings when required. For the functions that draw right-to-left or bottom-to-top, the string is reversed to make it easier to read (left-to-right or top-to-bottom).

Navigate to the centre of your screen and type:

Now create a small box of 7 characters wide by about 5 lines. Now navigate to anywhere in the box and insert text using the <<BoxText>> function - {Esc b t}

You should get something resembling this:

                                   ------
                                  | Text |
                                  | in   |
                                  | the  |
                                  | box  |
                                  |      |
                                   ------

As an example of this type of text, open the text version of the jot user guide and go to the diagram showing the mid-keypad assignments:

Set the note point at the top-left corner inside the box:

then navigate to the bottom-right corner and <<CutRectangle>>:

The text disappears - it's actually in the _ buffer - take a quick look:

Now return and restore the text:

Insert mode

Up to now, everything has been types into the console area at the bottom of the screen. With, many modern editors the stuff you type in appears WYSIWYG-style (What You See Is What You Get) directly in the the text image image on the screen and, according to modern myth, WYSIWYG is always best. Indeed, if all you're doing is brain dumping your thoughts directly into a text-file image or sometimes when doing lots of fiddly but non-repetitive changes to a small block of text then this is a pretty good way to work - see Command-mode vs. insert mode.

Clear a buffer then zoom into it, put the editor into insert mode and just start typing.

This switches the editor to insert mode:

Now just type in a few lines, each line is terminated by {Return} if you want to rub out something just press the {Backspace} key. This little nursery rhyme will do:

Tom, Tom, the pipers son stole a pig and away did run pig was eat and Tom was beat and Tom went howling down the street.

The cursor-control keys will all work just the same, as will most of the function keys. The exceptions are those which take parameters - e.g. <<FindBack>> and <<FindNext>> - these prompt you for a search string e.g:

Find string> tom{Return}

now try {F7} again and hit {Return} in response to the "Find string>" prompt.

Find string> {Return}

it finds the previous occurrence of Tom ok, but better yet, use <<FindBackAgain>> ( {Ctrl+F7 ) this repeats the search without prompting:

{Esc I n} also exits insert mode.

You are now back in command-driven mode alternatively, {Ctrl+c} will also get you back to command mode.

In addition to the semi-perminant insert mode described above, jot offers a temporary version - {Esc i n} (see TempInsertMode) enters a insert mode that persists until the next use of any function, cursor or escape sequence.

Type in some text.

More importantly, TempInsertMode can be used to temporarily exit the insert mode in order to type a command line to the console.

It works in pretty-much the same way for tabular text - in this example the tabcells mode and insert mode are set by the initialization sequence:

$ jot ${JOT_RESOURCES}/test_table.txt -in="%b=tabcells -1; %s=commandmode 2;"

Navigate your way around to any cell and type some stuff in. Note that, in order for you to see what you're doing, it initially displays your typing by allowing the enlarged cell to shift rightwards, encroaching into the neighbouring column. Then when you press any function or cursor key, the entire view is redrawn with the enlarged cell in a neatly tabulated and suitably widened column.

Command-editing

There is a simple command-edit/repeat facility (see about command editing). It works my getting a buffer containing command-history and editing the desired command string in that buffer. By default, the command-history depth is just 20 lines, if you feel that is not enough, you can increase the size of the history buffer with the -history CLI qualifier. When you're happy with your command line you exit and your command line appears in the console area.

Typically command-editing offer a very restricted range of editing functions but are entered by simply pressing the relevant cursor keys. In contrast, jot's command editing facility requires one escape sequence to enter and exit it also switches focus to a different buffer, but, once you're there the full range of editor functions are available. It's also worth noting that the jot command editor allows you to operate over several lines of history. On exit you are returned to your original focus point.

• <<CmdEditStart>> {Esc c e} - Switches focus to a buffer showing whatever you might have been typing and the last few lines of command history.

• <<CmdEditGo>> {Esc c g} - pushes the current line of history into console command buffer. You can then hit return launch it as a command or any function key that uses an argument.

Return to the Richard III text in the primary buffer and go to the start:

Now fill the history buffer with simple commands - hold down the {DownArrow} key until you have passed line 20 (by default, the history buffer is 20 lines long - see -History). Then enter an easily identifiable command:

Now enter a few simple commands - the <<Right>> function will do:

Now enter the command editor:

Now insert "%d1=" at the start of the macro - so that the command text defines the macro attached to button 1. First navigate to the start of the "Hello world" line then:

Push the command back into the console command buffer:

You should be back in your original context and see the modified command string in the command area looking, for all the world, as though you'd just typed it in. At this point hit {Return} to run it.

Take a look at the definition of macro 1 - we should see our original command:

Using the popup menu

Jot has a simple yet useful popup menu. It can, for example, be used to reproduce hard-to-spell, hard-to-remember or tedious-to-type words in documents or object names in computer coding languages. The popup menu is also used to offer spelling corrections suggested by Aspell - see text document preparation.

For details see PopupSearch, PopupIncrementalSearch, PopupMouseSelect, PopupRestore, PopupScreenNext and PopupScreenPrev.

Fire up a session on RichardIII:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt

Search for words containing the sting 'men':

You will notice a list of words appear, on a blue background, in the top-right corner of the screen - this is the popup menu.

Now select one of these words by moving the mouse cursor into the popup area and clicking the left button on the mouse - if you are unfortunate enough to be working with a laptop touchpad there is doubtless some equivalent motion.

Notice that the popup menu has disappeared and that your selected word has appeared in the console area. You can now apply this word in some other jot function - say Find:

You might equally have invoked FindBack {F7}, FindExact {F9}, Insert {F6}, Substitute {F5}, etc.

When the search returns more results than can be accommodated in a 20-line popup, use the PopupScreenPrev and PopupScreenNext to view more of the list:

and

The function PopupIncrementalSearch is similar except that it searches the document as you type in the search string. This allows the search to be refined interactively. Note that the popup-menu clicks are disabled until the search exits by hitting {Return}.

We're going to go fishing for the word marquess, as this is a good example and appears in two different spellings. Again, with Richard III, start an interactive popup find:

Notice the prompt string, it's telling you that the search string is currently empty and that there are 0 matching words. Now type in the first character of our search string - I suggest ( q ) we shall see why later.

Currently 0 matching words> q

the popup appears with a list of words from the text each contains ( q ). Now type in the next letter - this has to be ( u ).

Currently 39 matching words> qu

Now try entering a ( e ):

Currently 39 matching words> que

Now add a ( s ) to the search string:

Currently 15 matching words> ques

Now remove the last letter with the {Backspace} key:

Currently 5 matching words> ques{Backspace}

We should be back to 15 matching words again. Now exit the search by hitting {Return}:

Currently 15 matching words> ques{Return}

Now, why did I suggest starting with the letter ( q )? This is not a very commonly used letter in english, if I were to have chosen a letter like ( a ), ( t ) or ( s) any of these would have matched to thousands of words in this text. Each match must be processed and this processing would have introduced a significant delay - try it:

Currently 0 matching words> s

After a noticeable delay it is ready to receive the next character - let's try ( t ):

Currently 1679 matching words> st

The delay is now much shorter because there are far fewer matches and much less processing. This could be a problem for big documents, the solution is to start PopupIncrementalSearch further down the search - it takes an optional parameter which is the initial search string.

First exit that search buy entering {Return}, then start the search with a short initial-search string:

Currently 309 matching words> st{Return}

Currently 41 matching words> str

The searching and processing delay was hardly noticeable and we can now continue interactively.

Percent commands - 1

These are mainly to do with housekeeping operations and system interfaces. %q (system Query) is an important one, it supports several queries. Essentially it offers you little peepholes to see what's going on inside the editor.

Another important one is %s (System settings) - changes various default settings inside the editor.

There's also %b (Buffer settings) - changes some default state in the current buffer. Only a few key options are explored by this introduction - see percent commands for more details.

Two quite handy ones are %M and %X, %m just sends a message to the console e.g.:

%X also sends a message but it forces an exit from whatever macro is currently running:

The %Q group of commands - 1

First, let's look at the words on system queries - %Q, these report system and internal editor state. For most of these the destination buffer is mandatory, in these examples the report is directed to buffer z.

The editor focus changes to buffer z, this now contains two records, first the string 'version', followed by the editor version - this query is more useful than might be immediately apparent - it can be used by a macro to find out if it's running on windows or unix.

Buffer z now contains two records, first the string 'date', followed by the date as reported by the system.

This time it replies with the current value of that env variable.

This replies with several lines reporting internal state for the current buffer - refer to query buffer for details.

This does not write a report, it simply sets the failure flag if the buffer has been changed since it was last read or last saved - i.e. the image in front of you is, possibly, different to the version held by the filing system.

The %Q group of commands - 2

This extracts a directory listing for your JOT_RESOURCES area. There are several options for extracting more information about the files - see query dir for details. Here's an example:

If, by chance, you want the report ordered by file size, there are some options on the sort function that can help (see %b=tabsort):

Percent commands, %B and %E

The %B commands set some of the buffer attributes reported by the %qz=buffer query above. You've already encountered two of these in the section about tabular data (%b=tabcells and %b=header) - another important one is %b=pathname - this sets the default pathName used by %O and some other commands that refer to the filing-system.

The %E command is very useful - it passes a command down to your CLI and, optionally, collects the reply in a nominated buffer.

The unix status for the command is picked up and defines the editor failure flag.

Note that many useful CLI commands contain semicolons (in unixland they do anyway), and escaping these with backslashes makes it difficult to predict what actually emerges after the various layers have stuck their oars in.

Jot also allows two-way communication between itself and interactive processes that are not fussy about receiving commands from a pipe (many text editors will refuse to cooperate unless they are speaking to a genuine tty device). Fortunately, gdb, for example, does allow this and so does jot. The significance of gdb is that we can use jot to wrap it up in an ide-like environment but for now we'll use jot.

In this example we will set up a child jot session with %E, using %P to control it and monitoring it's responses in the parent session. We will also define the exit command a "%A" - although that's only required in windowsland:

That should create a second jot session listening for commands sent from our session using the %P command it also defines the exit command - in this case %a. Linux users can check that this happened by going to another console and checking for the new process:

$ ps -ef | grep jot

You should see this one: "jot ${JOT_RESOURCES}/l99.t -quiet -obey -tty"

Windows users can check the process monitor.

Now send it a simple command and pick up the response in the attached buffer ( Q ):

the attached buffer should now contain the correct response lines:

p3{CR}
__01: abc def ghi jkl mno pqr stu vwxyz:0123456789{CR}
__02: abc def ghi jkl mno pqr stu vwxyz:0123456789{CR}
__03: abc def ghi jkl mno pqr stu vwxyz:0123456789{CR}

The lines are terminated with Carriage-return characters because the slave session is set up to send this stuff to a terminal rather than a file.

You can send it any number of commands, the response from each is appended to the buffer. The session closes automatically when the destination buffer is re-initialized:

Comparing buffers with comp.jot

To detect differences between a pair of buffers use the comp.jot script. In it's simplest form, this compares the current buffer with some other nominated buffer - typically these might be a new and an old version of some text.

Fire up a jot session on an example file and place a slightly different version in some other buffer. Since the comp.jot script splits the screen, you might chose to increase the width of your terminal window before you start.

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt \

-in="%iq; (f/thy/s/your/)0m-0f/horse/naaha3m-0 z."

The -initialization commands read in another copy of the sample text into buffer ( Q ) and changed every instance of "thy" to "your", it has also inserted two extra copies of the first line containing the string "horse" - let's now go and spot the differences.

The comp script has redefined the window configuration, we now have a vertical split with the left side showing the original text and the right side showing the modified text.

Looking down the display we see, sure enough, two similar lines highlighted with can forground and a white background, the same two lines are repeated in the console area where we see the expected difference.

We can search forwards for the next mismatching line, using macro 5:

Is is usual when searching forwards in jot, the mismatched lines are right at the bottom of the display. To see the mismatched lines in context, shift the current lines of all in-view buffers to the centre of their respective windows use the ViewAlignCent function to improve the view. (the ViewAlignTop {Esc v t} or the ViewUp {Ctrl+Shift+UpArrow} (for windows users {Esc v u} may work) functions might be useful, according to taste).

An alternative approach would be to set a window guardband (see %s=guardband) this prevents the current character approaching the top or bottom margins of the window by less than a specified number of lines - it defaults to 0 lines. Here we're setting it to 5 lines - it will make no difference now since you've already cantered the display but you will see the difference after the next operation.

Now find the next mismatching pair of lines:

This time, something different has happened - we can see that the two lines are completely different. This is because our initialization commands have inserted two extra copies of lines containing the string "horse". So again view it in context:

As a result of the duplicated lines, the two buffers are out of alignment. Repeated macro-5 calls will not realign the buffers - this requires some human intervention. One way would be to go into the modified buffer and move it's current line down by enough lines to make the next macro-5 call work. In the more usual case a section of text has been re-written and we need to re-align to some point soon after the texts reconverge. We would usually do something like this: z.f/With lies well/ zqf// But that's a bit of a performance so we could use another feature of macro-5. If it is given a parameter, then macro-5 assumes that this is a jot command sequence to be applied to both the buffers.

In addition to macro-5 comp.jot also defines macro-4 - almost exactly the same except that it searches back towards the start of the buffer.

It also defined macro-6 this repeats a command string in the reference buffer. If you have performed some operation in the primary buffer (that's the one in the left window) then macro-6 will repeat that command sequence in the reference buffer (that's the one showing in the right window). To see macro-6 in action we first go looking for the well-known "a horse, a horse" passage using ProximityPara and using the context-proximity functions:

Finally, when you've seen enough of the split-screen display invoke WindowOne function to restore the normal display window.

Redefining function and hot-key mappings.

The mapping of functions to keystrokes is performed by the standard startup script (see about startup scripts). Take a quick look at this file - in particular the definition of functions in the ( ' ) buffer.

This only defines the functions. The startup script calls a secondary startup script to curses_keys_<TERM>.jot to define the keycodes used to recognize keystrokes. In windowsland it's WindowsNT_keys.jot, take a look at one of the relevant files:

or

The syntax is quite simple - each line has three entries first an 8-character keycode, a function name and finally an optional comment describing the keystroke but note that this is not a free-format file - the keycode must be passed out to 8 characters with whitespace.

The keycode 'xxxxxxxx' indicates that this OS does not support a key combination.

At the end of startup.jot we see this line

obz@m-0 (f1/<</\k, n.f1/>>/-a$&z:m-0f'$-n.r0a$&z@l0r8e0h$m, z@m)0 z^m-0h@ oz

this code merges function definitions from the ( ' ) buffer with keycode definitions from the @ buffer and adds them to the key-mapping buffer ^ this is the buffer where jot has to find key-to-function mappings.

Essentially, to redefine your own key mappings, you should create your own startup.jot which defines any new functions and a new key-map file to replace unix_keys/WindowsNT_keys.jot with a customized key-map.

Command-line options

When we fire up a jot session we can simply type:

$ jot <pathName>

• where pathName is the full path and name specification of a file we want to edit. The full list of command-line options is presented here command-Line qualifiers here are three that earn a mention in these examples.

Jot has a number of CLI qualifiers (see command-Line qualifiers) but here we will only need to know about three of them: -journal, -init and -startup

$ jot ... -journal

may be abbreviated to

$ jot ... -j

This causes the editor to keep a journal which can be used to recover the session in the event of a crash or a power failure and

$ jot ... -init="<jotCommands>"

may be abbreviated to

$ jot ... -i="<jotCommands>"

After running the normal startup script, but before starting the normal interactive session, the given command sequence is executed.

$ jot ... -startup=<pathName>

may be abbreviated to

$ jot ... -st=<pathName>

Runs the specified startup script instead of default one.

By default, jot picks up the file ${JOT_HOME}/coms/startup.jot, this defines functions and key mappings described here and in the rest of the jot documentation.

$ jot ... -st

Runs the editor with no startup script. There will be no predefined functions and no predefined hot-key mapping.

Command Files

Command-file library

There are lots of command files (scripts) designed to take on specific functions. In some cases, the scripts may be a tad over-specfic but that's OK because it's easy enough to adapt them. here's a list of the most important ones:

• get.jot - directory browser and file loader.

• dic.jot - word lookup based on websters online dictionary.

• thes.jot (thesaurus) - cross-match words in the online Roget's

• c.jot - c-code browser

• perl.jot - perl-code browser.

• jot.jot - jot code browser.

• txt2html.jot - converts a text document to html.

• comp.jot - compares two buffers.

• do.jot - runs a CLI command and collects the results.

• cli.jot - applies CLI command to current file's pathName.

• path.jot - applies CLI command to current file's path.

• multi_do.jot - applies a CLI command to all files listed in buffer.

• multi_ed.jot - applies a jot command to pathnames listed in buffer.

• ls2list.jot - converts ls output to a list for multi_do and multi_ed.

• age.jot - returns current age of file in current buffer.

• searchbuffers.jot - searches all open buffers for a given string.

• purge.jot - identifies and removes duplicated records in buffer.

• duplicates.jot - finds next duplicated record in buffer.

• mc.jot - Displays the current buffer in multicolumned format.

• cal.jot - gets a calendar using the cal command and adds week numbers.

• xword.jot - word-search query server, useful to crossword enthusiasts.

The get script - 1

A most useful script, it is used to interactively browse the filing system directories and archive files - see get.jot for full details. It can pick up a path from any of the following sources in the priority order listed.

Most of these usages of get.jot result in the editor focus changing to a list of files in the ( + ) buffer. Subdirectory names are suffixed with a slash ( / ). To select a file, or to descend another directory, navigate down to an entry and do {Esc 0}.

• An absolute path given as a command-line argument.

> get /*{F2}

it shows a list of all files in the root area.

• Buffer ( . ) contains the Richard III sample from your ${JOT_RESOURCES} area, this one offers a list of all files here.

> z. > get{F2}
• When the current buffer has no valid pathname, it takes your PWD:

> n.aqzq{Return} > get *{F2}
• A path relative to your PWD.

> get <aFileOrDirNameInYourPwd>{F2}
• A path specified by the env GetDefaultPath.

This env is set to the default c include path by c.jot, for example.

> get stdlib.h{F2}

The get script - 2

Another useful feature of get.jot is that it will descend into archive files of various sorts. In unixland tar (Tape ARchive) is a popular archive format (including compressed tarballs). In windows zip is a common one and there's also the microsoft cabextract format. In linux get.jot recognizes these files by applying the file utility, in windows it goes by file extension. Various helper co-processors are used to do this, some of which may need to be downloaded from various providers (see get.jot for details).

There's a few little sample archives in ${JOT_RESOURCES}/test_get - lets see what's in them:

Along with various test files and subdirectories there's test_get.tar and test_get.zip - let's try pulling something from test_get.tar:

It shows you a list of files and directories in this small test archive. Ignore the directories (entries ending with {/}select the file test_get/hello.c:

Note that the buffer has not been given a proper pathname - in window-terminator line it just says something like

"[ From CLI command ...

this is because the archive may contain absolute pathname, as this one does, and if it came from a different filing system you will not be able to write the buffer to this path. As it is, in all cases you must set the pathname (see %b=pathname) of the buffer before saving the file.

It's a similar story with spreadsheet file containing multiple sheets - let's take a look at the original xls file in ${JOT_RESOURCES}

It first asks you for a buffer key - we'll put the sheet in buffer z:

It presents you with a list of sheets in the spreadsheet file - 12KN is the one we've looked at before:

The get script - 3

The get script recognizes some binary file formats and can launch co-processors to extract plaintext from them - see installation.

In the ${JOT_RESOURCES} area are some versions of the test file t.t in various formats:

• t.t - plain text.

• t.doc - old-style microsoft word format.

• t.docx - New-style microsoft word format (2007+).

• t.pdf - guess what - a PDF version.

get.jot uses tika (a java application supported by apache) to suck meaningful text out of these files.

In response to the 'Buffer key?' prompt, tell it to read it into buffer x:

doc - document preparation toolbox - 1

The doc script is a useful toolbox of basic functions for writers. We're going to try some out on some text written using the document preparation functions - see text document preparation. First read the plaintext jot user guide:

this is another copy of the jot user guide, which was written using the document preparation functions.

One of the most important document-processing hotkeys is probably {Esc p a}, this re-formats the current paragraph. Let's add some text and then use this to reformat a paragraph:

we've inserted a few words to the text, but the paragraph is now out of alignment. re-make the paragraph:

Now let's try breaking and joining paragraphs. Suppose we decided we wanted the last sentence of this line to be at the start of the next paragraph. The function we're going to use <<AppendRightNext>> {Alt+F10}, remember, moves text to the next line past indentation.

The process can be reversed by using <<AppendLeftPrev>> {Alt+F9} -

This time merge the lines by erasing the line break - the function <<DeleteChrLeft>> {Alt+LeftArrow} deletes the line break when at the start of a line, as it is now:

doc - document preparation toolbox - 2

• {Esc h e} - makes the current line into a section heading.

• {Esc h a} - resets all headings, preserving header levels.

• {Esc h +} - current line becomes a heading at an increased header level.

• {Esc h -} - current line becomes a heading at an decreased header level.

Go to any line of text and enter a new line:

> This a new heading.{Esc h e}

Notice that the new heading has the correct header numbers relative to the previous heading - but the next heading is now wrong. This will be fixed later.

Add three more headings at various header levels:

> This is at a higher level.{Esc a} > {Esc h +} > This is at an even higher level.{Esc a} > {Esc h +} > This is going back one level.{Esc a} > {Esc h -}

Having added a new section may wonder what about all those out-of-sequence section heading numbers further along? ... Well {Esc H} is here to help:

> {Esc h a}

All the section numbers have been fixed.

doc - document preparation toolbox - 3

Spelling checks are an important part of document preparation - except for those of us who can remember all spellings and never miss-type a word. The doc.jot spelling check uses the gnu aspell programme - see Unix and linux setup,

• {Esc s p} - checks the current paragraph for spelling mistakes.

• {Esc s d} - checks the entire document for spelling mistakes.

• {Esc n i} - moves to the next instance of the current misspelled word.

• {Esc n w} - moves to the next word in list of bad spellings.

• <re>{Esc l x} - this greps for the regular expression in the mini lexicon.

First find a good-sized paragraph and drop a in few incorrect spellings.

> inner{F8} > bananaz {F6}} > {Esc s p}

The word "bananaz" appears in the console area. {Esc s p} is useful as a quick check of a freshly-updated paragraph or use {Esc s d} to check the whole document.

Now check the entire document with {Esc s d}:

> {Esc s d}

With the full-document spelling check the list of miss-spelled words is not displayed in the console but is held in a buffer (the @ buffer). The <<NextMisspelledInstance>> function finds the next instance of the current reported word and each new application of {Esc n i} will find the next instance of the current reported word.

> {Esc n i}

Sometimes, the word is a correctly-spelled technical term or someone's name that appears dozens of times and we just want to skip to the next reported word - the <<NextMisspelling>> function does just that:

> {Esc n w}

It can, sometimes, be a long process looking up words in a dictionary. A regular expression search of the lexicon can sometimes help. Use the <<GrepLexicon>> function to find the correct spelling of a word. Results are displayed in the console area, if there are too many to see whet you're looking for, you can browse them in the $ buffer.

> ^ac.*mpl{Esc l x}

dic (dictionary) and thes (thesaurus)

These are quite useful for authors. They are indeed useful when reading text in difficult or archaic english. The dic.jot script is set to find the Gutenberg websters ebook - see installation. The scripts are designed around the Gutenberg Ebook version of websters dictionary and Roget's. These can be downloaded from the Gutenberg project - see dic.jot and thes.jot. The dic and thes scripts expect to find these in your JOT_RESOURCES area.

The dic.jot script reads the dictionary and creates an index. Now the dictionary is pretty big - about 19MB and it takes a few moments to read. Once this is done it writes the index and, keep the faith, next time you run the dictionary script it'll go like the wind.

Once it's read it's book we can fire off a few queries.

if you've not got a numeric keypad or it's not been set up, then this will do it:

The thes script is based on the Gutenberg Roget's ebook. This script takes a list of words and returns the categories containing all of them. Queries are handled by macro 8. Note that, although the thesaurus contains phrases, the search does not currently support phrases.

On completion the $ buffer contains a list of headings for matching sections, the @ buffer contains copies of the complete sections.

Now try intersecting it with another word.

c, jot, perl, sh, csh, skill, verilog, vhdl, tcl, edif, mif - code browsers.

These all match block starts and ends in their respective machine languages. The functions are similar - {KP_2} (or {Esc 2}) searches forwards in the text for the next valid block-start token and then locates the corresponding block-end token. {KP_1} (or {Esc 1}) is similar but works backwards.

The browsers for c and jot have been used with recent versions of jot and are pretty bulletproof. Those further down the list have not been used much recently and may benefit from updating. We're now going to look at c and jot. First open a new editor session on some c:

$ jot $JOT_HOME/source/ed.c

To avoid corrupting the definitive file change the pathname:

Now load the c-code browser:

When you first hit {KP_2} there is a momentary pause while it maps all the blocks in the file. When it comes back, the focus has changed to a block end token ('}' in c) at the end of a c function definition. Further pumping of {KP_2} takes us to the end of successive function definitions. The {KP_1} key takes us back, but this time it goes to block-start tokens.

If the C-code contains mismatched curly braces, c.jot will fail creating the hashtable. In these cases use the plodding versions - {x KP1} (or {x Esc 1}) and {x KP_2} (or {x Esc 2}) these work by plodding through the code counting curly-braces. The backwards-matching macro (Macro 1) is less reliable in this mode of operation because C cannot be reliably parsed in reverse - nevertheless, it gets it right most of the time.

To descend into a block just move the cursor anywhere inside the outer braces and hit {KP_2} again - Run_Sequence is a function with plenty of internal structure:

The c script uses hashtables, not for speed - although this is a most welcome by-product, but to improve the reliability of reverse scanning. The main pitfall of using hashtables is when there's a mismatch somewhere and we want to locate it.

The {Mod} key (normally x ) modifies the function of {KP_1} and {KP_2} so that, instead of using hashtables, they plod through the code. These functions can be useful in the quest for mismatched braces.

Journal files and recovery from crashes

First start a jot session with the optional qualifier -journal - this causes jot to keep a journal of your activity. Since the JOT_RESOURCES files are normally read only, first make a working copy of Richard, then launch a jot session with journal files.

$ cp ${JOT_RESOURCES}/Richard_III_Entire_Play.txt .
$ jot Richard_III_Entire_Play.txt -jou

Just play around using the keys and commands you've looked at in previous sections of this example - move around in the text, inserting, searching, substituting, copying and pasting. Also read in some other files and cut and paste from those into the primary text.

While you're doing all this, your activity is being recorded in a particular journal file - history.txt. Now close the session with %A and take a look at what's gone into the history.txt file:

$ jot Richard_III_Entire_Play.txt.jnl/history.txt

It begins by noting a few details of your session and files read the startup script. Then , a few lines down, there is a line like this:

As the words suggest, this point marks the end of startup-script activity. After this, most of the entries are of the form ~Xxxxx - if you're viewing it with jot, the escapes will be represented as tildes ( ~ ) - these are keycodes. For keys that take an argument, the argument appears as a prefix before the escape.

All the journal files and the journal directory are destroyed when the editor exits normally (the %C or %A commands).

The journal directory holds the following items:

• the history.txt file - mainly your typed-in command activity,

• any writable file read by the session, these are held as unique files.

• copies of responses to %E commands are held as unique files,

• results system queries are held as entries in the history.txt file.

Now restart the editor but with the recovery script as it's startup:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt -st=recover

you may recognize some of the activity flashing past on the screen.

What's happening is that the recover.jot script has read the raw records of your original activity from the history.txt file and has created a new script ( ./recover_now.jot, in your PWD), it's now following your original activity. Whenever it needs to read a file, it reads the archived version from the journal - see also about journal files.

While in recovery mode, jot %i, %e reads and some %Q queries are intercepted and return the same results as they did in the original session. Theses results are from files held in the journal directory. Also jot writes are disabled to avoid corrupting anything.

When it's finished, all buffers in the recovered session should be exactly the same as in your original session and reading and writing are back to normal. You may continue with the session as if nothing had happened, new commands will be appended to the history.txt file and file reads and writes behave as normal.

A quick way of comparing the recovered version of the file and version in the original session is to use comp.jot go back to the original session and write the current buffer, then in the recovery session type this:

The comparison script splits the screen to display both versions side by side. On completion both windows should be displaying an identical view of of the file image.

As the original session fires up, it creates a new journal directory. A LOCK file is added to the journal directory, the LOCK is deleted when the session exits normally. In the event of an abnormal exit, the LOCK file remains in the journal. If a new jot ... -journal session is started, it first checks the old journal for a LOCK - if it exists then the session terminates abruptly without changing any files. The LOCK, or the entire journal directory can be deleted manually if desired.

Some more advanced topics.

The following sections are of more interest to those seeking to write their own macro-commands, scripts and redefinitions of the startup files.

This section shows a few macro commands of moderate complexity , takes them to pieces and analyzes them.

A profiling macro

Suppose we were interested in the distribution of words in this text - we might want to count how frequently each word appears in there - something like this will generate such a report in the @ buffer.

Begin by copying the text into the @ buffer and changing all alpha characters to lower case.

Place each word on a separate line then sort them alphabetically.

Finalize the report by counting instances of each word

How does this work - 2

There were four lines of code involved:

m-0n.m0r0a@&z@ m-0(q/A-Z/c, r, m)0 
m-0(q/a-z/(q//r)0b, rr-(q/a-z/\e)0, j)0     
%b=sort
m-0 (r\j)0 r-0 (n.r0a$&ol1m(v'$r0v-'$o~k)0 m-oo/%5d - /m)0

In the first line:

• m-0 - this sends the cursor to the beginning of line 1.

• n. makes a note of the cursor position (at the very start of the buffer the subsequent abstraction will move text to the nearest character.

• m0r0 takes us to the very end of the buffer.

• a@& abstracts (copies) all the text from the note point to the current cursor position, to the @ buffer. Without the & suffix, the a command would cut - i.e. remove the text from the original buffer.

• The "q/A-Z/" command checks for upper-case alpha characters.

• For upper-case alphas, the c command changes them to lower case and all commands from the comma up to the end of the block are ignored.

• For other characters the Q command fails so commands following the next comma are obeyed.

• The r command moves the cursor right by one character.

• The next comma indicates the commands to handle the situation when the r fails (i.e. at the very end of a line).

• The m command moves to the start of the next line.

• ( ... )0 - this is a block of commands that keeps repeating until an untrapped failure occurs - in this case the final m command will fail at the last line of a buffer.

The second line chops up sentences to yield a list of all the words in the original file in their original order. Again, the q command detects non-alpha characters then the ( b ) command breaks up the lines on the word boundaries removing any more adjacent non-alpha characters with the ( e ) command.

In the third line, the %b=sort calls the system quicksort service (see %b=sort).

In the final line there are a few new commands:

• the backslash after the r command reverses the success/failure state.

• j joins the current line with the next.

• ol1 loads the value 1 onto the stack.

• v verifies that the string following the cursor is the same as that given in the argument. In this case the argument is an indirect reference to the $ buffer.

• The v- is similar, except that it looks back, at characters left of the cursor.

• The o~ command increments the value on the stack.

• The k command deletes (kills) the current line.

• the oo command outputs the value on the stack using the given format string, in this case "%5d - ".

Macros

We could scoop up all of those commands into a buffer. That would then become a macro command to generate a similar report for any text. Macros 0 to 9 are attached to numeric-keypad buttons 0 to 9 - so, for this example we're putting the commands into buffer 3 and adding some commentary.

The %g command is a good way of doing this - it copies all text from the keyboard into the specified buffer, until terminated with a colon ( : ).

%%Copy text to @ and change all alphas to lower case.
m-0n.m0r0a@&z@ m-0(q/A-Z/c, r, m)0 

%%Place each word on a separate line then sort them alphabetically.
m-0(q/a-z/(q//r)0b, rl(q/a-z/\e)0, j)0     
%b=sort

%%Finally, count up instances of each word 
m-0 (r\j)0 l0(n.r0a$&ol1m(v'$r0v-'$o~k)0 m-oo/%5d - /m)0
:

Now go to the original text and run the macro - KP_3 denotes button 3 in the numeric-keypad - if your keyboard lacks a numeric keypad then use {Esc 3} - the escape key followed by 3

The stack - 1

The simplest usage of the stack is just a temporary parking place for various fragments of numerical and textual data. It can also be used to perform simple arithmetic and logical operations including counting.

One common problem in the design of macro commands is that we need to switch context to some buffer to pick up some information and then return to the original focus - the stack is there to help.

• ob - puts the buffer key onto the stack.

• %q~=... puts the reply in a temporary buffer and leaves a pointer to that buffer at the top of the stack - see basic commands.

• os swaps the top two items on the stack, so the buffer key is now at the top.

• oz changes focus to the buffer indicated by the key at the top of the stack.

• the '~ expression in the insert command means insert the current record from that buffer - see basic commands.

• ok removes the top item, in this case it's a temporary buffer so the buffer is also deleted.