Command file library

The scripts

There are a number of predefined JOT command file in the ${JOT_HOME}/coms area - see installation. In general these have a one-line description at the start of the command file. The most useful ones are described below

These are run by first typing the name of the script, followed by any arguments and then pressing the 'F2' button i.e:

If the <<Do>> function has not been mapped to the F2 button then, as a temporary workaround you can type in the command %r=<scriptName>. If the script happens to be one that takes arguments then you must manually define the arguments in the $ buffer - this is always used to define script and macro arguments. Then run the script with %r=<scriptName> like this:

In addition to Do there are two script-search functions ScriptByName and ScriptByFunc. ScriptByName searches for scripts in ${JOT_HOME}/coms and your PWD for those with the '.jot' name extension whose names match the given string (if no string given then it just lists all scripts in the searched areas e.g:

To apply the script on your buffer, move the cursor to the line with your script name and run macro 0 (normally {KP_0}.

By convention, all jot scripts should have a one-line comment in the first line. This should briefly describe what the script is intended to do. If it's a complicated script then detailed instructions should be left in the ? buffer.

ScriptByFunc searches these first-line comments in the search areas and returns a list of those matching the string e.g:

To apply a script on your buffer, first select one by moving the cursor to the line with your script name and run macro 0 (normally {KP_0}.

startup.jot

The script ${JOT_HOME}/coms/startup.jot is normally run by the editor as it starts up but if some other startup-script has been specified (see notes on the -startup section of command-line qualifiers) then that script can call this startup script normally (e.g: %r=startup; ) or if it is necessary to defer finalisation of the keymap setup, it can be called with the -nofinalize option (e.g: %r=startup -nofinalize; ) - see below for usage notes on the -nofinalize option.

It's principal functions are:

• To define a basic viewing window, it normally fills the screen except for the last four lines, which are used for user interaction and to display messages.

• To define editor functions in native jot code.

• To define the mapping of keystrokes to editor actions. Most of the rest of this section is dedicated to explaining how this works.

This script creates a mapping of xterm escape sequences to code calls. It's first requirement is to have a map detailing the translation of key codes the to key names that appear in all the documentation.

The mapping of key names to function calls is entirely for the the convenience of the user and can be changed to suit user requirements.

In linux, the mapping of keys to actual key codes is a two stage process, firstly the physical signals received from the keyboard must be identified, then they are translated to a set of hardware-independent keycodes. Many, but not all, modern linux distributions use X Keyboard Extension (XKB). Followed by terminfo/termcap database identified by your TERM variable. For most linux distributions this seems to default to "xterm". If you are interested in that sort of thing, there's a compiled terminfo database file below /usr/share/terminfo/... - if your $TERM is set to xterm, for example, you will pick up the file /usr/share/terminfo/x/xterm.

Although there seems to be pretty broad agreement on what the default setting for $TERM should be, there is no standardisation on what it's capabilities should be and, in particular, what keycodes should be returned for some of the Shift - Ctrl - Alt combinations (see translation of keyboard events to actions).

If the current directory contains a startup.jot file then jot picks up this in preference to the ${JOT_HOME}/coms version.

If the optional CLI arg -startup is specified (see command-line qualifiers), then this overrides any startup path from ${JOT_HOME}/coms or the current directory. if the qualifier is given without the '=<pathName>' value, this is equivalent to -startup=/dev/null i.e. no startup script.

In summary, the startup-file selection is, in order of precedence:

• 1 The -startup=<pathName> arg,

• 2 a startup.jot in the current directory and, finally,

• 3 ${JOT_HOME}/coms/startup.jot

There are two mapping tables used to fully define the finished key translations table in the ( ^ ) buffer:

• The key-names to key-codes table - set up in buffer ( @ ) by the curses_keys_<version>.jot or WindowsNT_keys.jot script. Each line of this table contains two entries - first a keycode or escape sequence then a key description of the form "{<[shift][Ctrl][Alt]<keyName>}" separated by any amount of whitespace. These items may be followed by a comment.

• The assignment of functions to key-names map in buffer ( ! ) set to by the startup.jot script. Each line of this table consists of a function name enclosed by '<<' and '>>' followed by either a key description or an explicit escape sequence description. Once again, these entries are separated by any amount of whitespace.

The startup script will finalize initialization of the editor by merging thes two tables into the key-to-function translation table in buffer ( ^ ) - see translation of keyboard events to actions. It is this last step that is suppressed by the -nofinalize option.

If the -nofinalize option is given, the macro to do the finalisation is defined in buffer ( # ) as the startup script exits, this allows your startup script to modify the final setup in some way before invoking this macro or maybe some different macro to setup the functions and keymap buffers.

The startup script also defines the following dats objects in the code-repository ( * ) hashtable:

• *=OriginalArgs - list of arguments passed in from the CLI when startup.jot is invoked as a secondary startup e.g:

$  jot ... -startup="<primaryStartupScript> -<argsList>"

• *=DocLeftMargin - defines the default left margin for document processing, defaults to 2 characters.

• *=DocRightMargin defines the default right margin for document processing, defaults to 78 characters.

• *=DocBulletString - defines the default bullet string for document processing - defaults to "- "

• *=DocHeaderMax - defines the default maximum header depth for underlining headers in the document-processing system.

• *=DefaultLineDrawing - defines the default character set to be used for line drawing - defaults to ( a ), i.e: using simple ASCII character set.

• *=LineIntersectionLookup - defines the intersection table to be used for line drawing, this defines the character to be used for various types f line intersections in the drawing.

nomod.jot

$ jot <pathName> -st=nomod

In addition, qr.jot also accepts the qualifier -nomod, which causes it to display the prefix key sequence instead of modifiers.

curses_keys_<version>.jot

Theses scripts are run by the standard startup.jot script, they define mapping of keys to whatever key codes are generated by your terminfo, these are then assigned functions by the startup.jot script. Currently there is a keymap file for the following:

• curses_keys_6_0_20160213.jot -- For linux distributions on ncurses 6.0.20160213

• curses_keys_6_1_20190803.jot -- For linux distributions on ncurses 6.0.20190803

• curses_keys_xterm.jot -- generic fallback when TERM env is set to "xterm"

• curses_keys_xterm1.jot -- generic fallback when TERM env is set to "xterm1"

• curses_keys_xterm-vt220.jot -- generic fallback when TERM env is set to "xterm-vt220"

• curses_keys_vt220.jot -- generic fallback when TERM env is set to "vt220"

• curses_keys_vt100.jot -- generic fallback when TERM env is set to "vt100"

These script only work when called by startup.jot this then attaches functions to the key definitions in these scripts. If run directly, it's only effect of these scripts is to load buffer @ with the key-names to key-codes map.

In addition to providing the all-important mapping of editing functions to keystrokes these files also map the unassigned and unassignable key combinations. Some key combinations are unassignable because they collide with other keys or because they've been hijacked by the operating system for some system shortcuts. Feel free to add your own functions or rearrange the or redefine the assignments as in whatever way seems appropriate.

The key mappings tend to vary significantly, so a utility is provided to assist with redefining and checking the key-map script - see define_keymap.jot and verify_keys.jot respectively.

WindowsNT_keys.jot

The function of this is identical to the various flavours of curses_keys (see curses_keys_<version>.jot) in that it associates functions with their respective keycodes - i.e it defines key bindings.

uc_basic.jot

This script defines a small number of basic unicode characters that may then be entered using a four-key sequence beginning {Esc}, {u}, {c1>} and {<c2>} where the characters c1 and c2 uniquely define a character in the supported unicode subset. The uc_basic script performs this substitution on the command line using %s=commandstring. See also about unicode.

These are the escape sequences and characters supported by uc_basic.jot:

uc_math.jot

This script sets up some characters used in maths and engineering, essentially it is used in the same way as uc_basic.jot. It follows the vim digraph scheme.

• {Esc u + -} ± -- plus minus

• {Esc u 2 S} ² -- squared (superscript 2)

• {Esc u * P} ∏ -- coproduct (big, tall Pi)

• {Esc u + Z} ∑ -- summation (big, tall Sigma)

• {Esc u S b} ∙ -- bullet operator (dot product)

• {Esc u R T} √ -- (square) root

• {Esc u 0 0} ∞ -- infinity

• {Esc u G *} Γ -- Gamma

• {Esc u D *} Δ -- Delta

• {Esc u H *} Θ -- Theta

• {Esc u P *} Π -- Pi

• {Esc u S *} Σ -- Sigma

• {Esc u F *} Φ -- Phi

• {Esc u Q *} Ψ -- Psi

• {Esc u W *} Ω -- Omega

• {Esc u a *} α -- alpha

• {Esc u b *} β -- beta

• {Esc u g *} γ -- gamma

• {Esc u d *} δ -- delta

• {Esc u e *} ε -- epsilon

• {Esc u y *} η -- eta

• {Esc u h *} θ -- theta

• {Esc u k *} κ -- kappa

• {Esc u l *} λ -- lambda

• {Esc u m *} μ -- mu

• {Esc u p *} π -- pi

• {Esc u r *} ρ -- rho

• {Esc u s *} σ -- sigma

• {Esc u * s} ς -- sigma (alternative)

• {Esc u t *} τ -- tau

• {Esc u f *} φ -- phi*

• {Esc u q *} ψ -- psi*

• {Esc u w *} ω -- omega*

• {Esc u / -} † -- dagger (sword)

• {Esc u / =} ‡ -- double dagger (double sword)

• {Esc u < -} ← -- left arrow*

• {Esc u - !} ↑ -- up arrow

• {Esc u - >} → -- right arrow

• {Esc u - v} ↓ -- down arrow

• {Esc u F A} ∀ -- for all (for any)

• {Esc u d P} ∂ -- partial differential (curled little d)

• {Esc u T E} ∃ -- there exists (backwards capital E)

• {Esc u A N} ∧ -- logical and

• {Esc u O R} ∨ -- logical or

• {Esc u . :} ∴ -- therefore (triangle of dots)

• {Esc u : .} ∵ -- because (upside-down triangle of dots)

• {Esc u / 0} ∅ -- Null set, empty set, var nothing, capital O slash

• {Esc u O /} Ø -- Null set, empty set, var nothing, capital O slash

• {Esc u ( -} ∈ -- element of

• {Esc u - )} ∋ -- contains as member

• {Esc u ( U} ∩ -- set intersect

• {Esc u U )} ∪ -- set union

• {Esc u ( C} ⊂ -- subset of (contained in)

• {Esc u ) C} ⊃ -- superset of (contains)

• {Esc u ( _} ⊆ -- subset of or equal to

• {Esc u ) _} ⊇ -- superset of or equal to

• {Esc u O b} ∘ -- concatenation, centered dot

• {Esc u I n} ∫ -- integral S

• {Esc u D I} ∬ -- double integral S

• {Esc u I o} ∮ -- line integral S with circle

• {Esc u D E} ∆ -- Delta

• {Esc u N B} ∇ -- Nabla

• {Esc u ? 1} ∼ -- tilde operator (centered tilde, proportional)

• {Esc u ? =} ≅ -- approximately equal to

• {Esc u ? 2} ≈ -- almost equal to

• {Esc u ! =} ≠ -- not equal to

• {Esc u = <} ≤ -- less than or equal to

• {Esc u > =} ≥ -- greater than or equal to

define_keymap.jot

$  jot ${JOT_HOME}/coms/curses_keys_Vn.jot -in="%r=define_keymap[ -init]"

Be aware though, that certain keys are hardwired as system shortcuts. These can cause evil or, at least, bizarre unhelpful, things to happen. Alt+F12 on some systems, for example, closes the current window. Now why we should need a shortcut to close a window when there must be at least half a dozen other ways of doing it is a question beyond the scope of this user guide. But that's what it does, it's very annoying, and there seems to be no way of turning it off - not without re-coding and recompiling slabs of kernel. See also Translation of keyboard events to actions

The define_keymap script sniffs through the key map file you give it and wherever it finds "????????" in the escape-sequence field, it prompts you to hit the specified modifier and function-key combination. So first launch an ordinary editing session to reset the dodgy keys to "????????" before launching define_keymap:

$  jot new_keys.jot -in="%r=define_keymap"

It recognizes the special escape sequence {Esc s k} as an instruction to skip the current keycode. This causes the current line of the keycode file to be left unchanged.

If you've made a mistake or just want to take a break, you can interrupt with {Ctrl+c} and manually change the incorrect keycode back to "????????" then save your work, exit and restart.

In the unlikely event of you needing to redefine all keys codes, use define_keymap.jot with the -init qualifier:

$  jot new_keys.jot -in="%r=define_keymap -init"

The -init qualifier tells it to begin by scrubbing all keycodes in the file, replacing each with the string "????????". The main section of the script then searches these reset keycodes, prompts you to prod that combination of keys and picks up the keycode which then replaces the reset keycode. This process is repeated until all missing keycodes have been filled in.

verify_keys.jot

$ jot -in=%r=verify_keys

tk.jot

• Menu name - Introduces the definition of a new menu. When called iinitailly by the application this will create the top-level menu - typically either a menu bar or a buttin box. It can also be callback to menus to create a loewr-level menu cascade.

• Menu clear - Clears out any preexiisting menu text.

• Menu xpitch - Specifes horizontal menu and sets the minimum spacing between entries.

• Menu ypitch - Specifes horizontal menu and sets the minimum spacing between entries.

• Menu leftOffset - Used by cascading menus to shift the menu body to the right of the mouse-event point. This helps determines the placement of the menu on the screen.

• Menu colour - Specifies the colour-pair to use for this item - menus may gave buttons with several different colour schemes. If it's new then define the pair - first pick up the colour-pair name.

• Menu space - Specified number spacing blanks in horizontal menus or blank lines in vertical menus.

• Menu item - Defines a callback menu entry, it's button text and it's callback code.

• Menu button - Just like a menu item except that it's of a defined size.

• Menu switch - This item is linked to a numeric data object which has the value "off" (zero) or "on" (any non-zero value). The menu displays the current value of the item, clicking reverses the state.

• Menu bits - In this case the menu definition specifies a bit n. in the numeric data object. Clicking will reverse the state of the seleced bit.

• Menu decimal - This item is linked to a numerical data object, it displays the current balue in the menu and, when clicked, it prompts for a new value which replaces the original.

• Menu hex - Almost identical to decimal (see above) - except that it takes values in hexadecimal.

• Menu string - it is linked to a buffer and the current value is displayed in the menu. Clicking it prompts for a new value for that line of the buffer.

The tk.jot script provides two demonstration functions:

• tk_demo_menubar and

• tk_demo_buttonbox

These can be seen in action thusly:

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt -in="%r=tk; %h=call tk_demo_buttonbox;"

or

$ jot ${JOT_RESOURCES}/Richard_III_Entire_Play.txt -in="%r=tk; %h=call tk_demo_menubar;"

A real-world example would be the jot debugging environment dbg.jot

dbg.jot

$ jot -st="dbg[ -nostartup][ -testtree]
$ jot -st="dbg[ -ide

$ jot -st=dbg ...

• This runs the normal startup but creates only a 20-line window.

Or, it's sometimes expediant to not run the full startup at all (e.g. when using gdb and we don't want to wade through loads of breakpoints in the startup sequence.

$ jot -st="dbg -nostartup" ...

• It does, however give you a 20-line window and creates the hashrable in buffer ( * ).

For debugging problems in data-object paths, the -testtree option creates a deep tree and populates it with a few leaf objects.

$ jot -st="dbg -testtree" ...

Finally, the -ide option. Purists may contend that for anything to qualify as an IDE it must be fully graphical - and doubtless they'd be right as purists so frequently and so anoyingly are but back here in the real world, the qualifier is -ide and that's the end of it.

$ jot ... -st="dbg -ide <ideQuals>":

• -nomouse - prevents initialization of the mouse - probably only uesful for debugging the ide code.

• -nocode - While stepping from breakpoints, source code tracing is, by default, performed by moving the cursor in the code window. To do this, the system must refocus the source-code fiew to the step currently being executed. In some cases it is desirable for this window to remain focused on the target code, -nocode does this..

• -height=<n> sets the height of the data-object monitor window, defaults to 15.

• -width=<n> - sets the width of the data-object monitor window defaults to 30.

• -codebuf=<bufferPath> - defines the buffer holding the code to be debugged, defaults to ( * ).

• -setup=<jotCommands> - defines any setup required e.g. scripts to be run. This sequence is run once, aitomatically, as dbg.jot initializes itself. If no -setup is specified, it's absense is silently ignored.

• -launch=<jotCommands> - defines commands required to launch the code to be debugged.

• -function=<functionName> - defines the name of the function to be debugged. This is used by dbg.jot for various purposes, many are not particularly critical but quite helpful to the user (e.g the code winow is aligned to the start of the nominated function).

• -init=<commandSeq> - defines the command sequence to initialize for a new run.

• -run=<commandSeq> - defines the command sequence to run the code.

This splits the screen into 5 areas, starting at the top of the screen:

• A one-line window containing a menu bar with menu items in blue,

• a 15 by 20-line monitor window (these defaults may be changed by the -height and -width CLI args) - this can be set up to display values of a selection of data objects so we can warch then change as we progress through the code.

• 20-line slice occupying the right side of the screenshowing the code repository.

• A floating window (i.e. displays whatever is the current buffer) and

• a console area.

The size of the last two items is adjusted to give the floating window about 2/3rds of the remaining screen and about 1/3 for the console.

The debugger script dbg.jot uses tk.jot to set up the top menu bar.

dbg shortcuts

Adds a breakpoint to selected point in code - see dbg_addBreakpoint entry in dbg Breakpoints.

Sets condition on the seleced breakpoint. - see dbg_setBreakCondition in dbg Breakpoints.

Sets an action to be performed on entry to breakpoint - see dbg_setBreakAction in dbg Breakpoints.

Disables code tracing in the code window.

To trace code in the source-code window (the default) the system must refocus the source-code fiew to the step currently being executed. This is usually helpful but less so when some other function is being operated upon, then we want to remain focused on the target code.

Housekeeping menu

• "Verbosity" adjusts bits in the jot verbose vector - see %s=verbosity.

• "Trace" adjusts bits in the tracedefault vector. Note that changing these bits does not immediately affect the trace mode. It affects the default trace settings that are applied when a T command is encountered and when a breakpoint is triggered.

• "Add Restart button" - Adds a Restart button to the monitor window - effectively making the monitor window a button box.

The effect of this button is identical to the Run->Restart menu item but avoids having to drill down layers of menus.

• "Add Run button" - Similar to "Add Restart button"

• "Add Continue button" - Similar to "Add Restart button"

• "Add Step button" - Similar to "Add Restart button"

• "Done" - removes the "Houskeeping" menu from the screen

• "Quit" - exits the session.

Run menu

• "Restart" performs whatever operations you've specified in the -init=<seq> CLI qualifier and then launches the application using commands specified by -run.

• "Run" launches the application using commands you've specified in the -run=<seq>

• "Continue" resumes normal execution of the application code from a breakpoint.

• "Step" steps on to the next trace point. Typically this will be a single-command step to another break as defined by the trace vector settings - see %s=trace for details.

• "Done" - removes the "Run" menu from the screen.

The Breakpoint menu

The dbg.jot script inserts breakpoints into the compiled code for the function under investigation. Breakpoints are a form of jot trace points (see the jot debugger) - essentially a trace point is created by inserting either a T or a %s=trace command into the code.

Ideally, one would set a breakpoint just ahead of a troublesome section of code then single-step through the code noting values on the stack and in relevant buffers and data objects to identify the problem. In reality it's not always quite as easy as that. One common difficulty is the breakpoint may be inside one or more loops and we are only interested in a specific pass. To do this we set a condition on the breakpoint.

The dbg script defines the following functions and associated menu items for breakpoints:

• dbg_addBreakpoint - "Add breakpoint" - A point in the source code must first be selected by a left-button click. The source code is tagged and the breakpoint is inserted into the compiled code just before the selected command see %b=addtag). Rge breakpoint is in the form of a call of a specially constructed function Breakpoint_<n> where n is a number chosen to give it a unique name. Breakpoints are highlighted in white with a green background.

• dbg_setBreakCondition - "Set conditon" - First select a point in the code. This adds a conditional expression you provide in response to a prompt. Note that the conditional expression must not interfere with the run state.

• dbg_setBreakAction - "Set action" - First select a point in the code. This defines defines some action to be taken whenever the breakpoint is entered (any conditionals have been met).

• Delete breakpoint - First select a point in the code. This will remove the breakpoint, its tags and it's inserted code from the source and the compiled code.

The Monitor menu

The Command Counter menu

The command counter is an important element in the jot debugging toolbox (see using %s=commandcounter in debugging). Briefly, it is used in two ways:

• It is initially set to zero and is incremenred ar eaxh new command, if something causes execution to stop unexpetedly then it gives an indication of how much progress had been made.

• If it is set to a negative value and the application is restarted, it will force a break at the point when it gets to zero.

Provided the failure is consistent and repeatable, we can use the command counter to trap execution at some point, hopefully, just before the failure occurs.

dbg Traps

showline.jot

qr.jot

$ jot -st=qr

or for users of nomod.jot (an alternative startup for CTS/RSI sufferers):

$ jot -st="qr -nomod"

qr.jot reads the main jot user documentation in their raw ( .txt ) form to provide a useful quick-reference entry point to the words, using the linkdocs.jot script insert the link metadata. Valid links are highlighted in green.

A left-button click on a link will follow the link. A left-button click in any other part of the window will return to the previous view.

If you are in a non-mouse environment, macro_1 is set up to emulate mouse clicks - move the cursor to a link and {Esc 1} emulates a mouse click.

The -nomod qualifier changes toe {Ctrl|Shift|Alt+Fn} modified keystrokes in the documentation, to the prefix form defined by nomod.jot.

ide.jot

$ cd <projectDir>; jot <projectName>

$ cd work ; jot ide_hello

$ cd work ; jot ide_jot

The script operates by setting up a window on buffer ( L ) and associating it with an interactive command pipe (see %E), any suitable compilers can be used - typically gcc (linux) and cl (windows). The script runs windows programmes with wine and the winedbg debugger and gdb for linux.

The script defines the following data objects and default values as follows, these may be redefined in your startup script - for examples see ${JOT_RESOURCES}/ide/projects/startup.jot:

• .=linCompile Default value cd ~/ ; make lin - Compiles source file for linux.

• .=winCompile Default value cd ~/ ; make win - Compiles source file for windows.

• .=linExePath Default value ~/bin/a.out - Executable pathname - linux.

• .=winExePath Default value ~/bin/exe.exe - Executable pathname - windows.

• .=testArgs Default value - Args to run the executable for testing.

A typical session might begin with a bit of editing of the source in the main window, then either hit the "Save" button or manually type in the usual file-write command (%O) to save the source-file image, then press the "Compile" button to run your specified compile command. The script will refuse the compile request if the source has not yet been saved.

One might then hit "Run", which will run your compiled programme either in your default shell (linux) or in wine, if you have selected windows.

If you have bugs to diagnose, you might then invoke the debugger - gdb or, if you have selected windows, winedbg.

The selection of Linux (the default state) or windows is set by the "Linuxland" or "Windowsland" buttons below the "File" menu item.

For examples see working with ide.jot.

fake_nano, fake_vim and fake_emacs

fake_nano.jot, fake_vim.jot and fake_emacs.jot are attempts at emulating the behaviour of these editors in jot.

A good question, at this point, would be "why bother with a nano/vim/emacs emulator when there are perfectly good versions available for free anyway?" Well, it would be true to say it's a good demonstration of the power and flexibility of jot that it can do reasonable emulations of two entirely different editors without resorting to magic modes or special tricks.

For occasional vim users or less experienced users wanting to progress, fake_vim.jot may, at some future point in it's development, offer a progression route for those daunted by the labyrinthine complexity of the emacs and, to a lesser extent, of vim and the immensity of it's user documentation (the vim quick-reference guide quickref.txt runs to over 1500 lines)

The end point for this project is defined by a vim quick-reference guide I found at http://users.ece.utexas.edu/~adnan/vimqrc.html. It's clearly not a complete guide to all the features but it looks like a good solid introduction.

fake_nano.jot

$ jot -st="fake_nano <pathName/option1>[ <pathName/option2>[ ...]]"

$ jot -in="%r=fake_nano <path/opt1>[ <path/opt2>[ ...]];"

If it is required to run some -init="..." commands these may also be added in the usual way (see -init) but note that these do not get executed until exiting nano mode. This is because fake_nano has it's own command scanner. This is not a big restriction as two {Alt+i} commands in quick succession will run your initialization and then return you to nano mode.

The startup options it currently accepts are:

• -F or --multibuffer- allows creation of multi-buffers - by default, fake_nano (just like the real article) unhelpfully inserts the extra files into the current buffer.

• -x or --nohelp - suppresses the two-line help/menu bar at the bottom of the screen.

• -m or --mouse - enables mouse activity (this is also controlled by the {Alt+M} hotkey - allows mouse-clicks to change focus in the screen or to trigger mouse-click callbacks.

• --white (not in genuine nano) tells fake_nano you are working with a terminal that has a white background.

• -debug (not in genuine nano) creates a much smaller main window in order to make more messages visible in the console area. The -debug option also causes the help page to be prefixed with a status report showing the state of various internal variables.

• -test does not automatically enter the nano command scanner on completion of the fake_nano script, instead it remains in jot mode awaiting a {Esc i} command - this allows test script to control the editor.

• --nohelp - does not write the useless help/menu lines.

• --multibuffer

The fake_nano.jot script also respects many of the most important nano hotkeys - one big problem is that each new version of nano seems to have an entirely different set of hotkey actions. In the end fake_nano approximates to nano v2.5.3

One significant difference is that fake_nano uses the jot console area to display messages - but jot, jot insists that the console must always follow the display windows. Thus it is that fake_nano messages appear in a one-line console at the bottom of the screen whereas, with genuine nano, these appear immediately above the help menu.

The help screen ( {F1} ) is copied from the v2.5.3 man page and the v2.5.3 help screen but with a hashmark prefix on line describing features not respected by fake_nano. At the very end of the help screen is a little report giving the current fake_nano setup.

Important deficiencies:

• Spelling: jot supports spell checking so future editions of fake_nano may well support this too.

• Undo/Redo: this has not been implement in jot because it it's very difficult for a fully programmable editor like jot, however, it may yet happen for fake nano which only has to emulate the behaviour of a simple editor like nano.

Initialization commands may be entered after the

Commands supported by fake_nano.jot

fake_vim.jot

$ jot -st="fake_vim <pathName1>[ <pathName2>[ ...]][ -<option1>[ -<option2>[...]]"

• Starts a fake-vim session on the specified list of file pathnames.

Valid options:

• -c=<vimCmd> e.g:

$ jot -st="fake_vim ... -c=<cmd1>[ +<cmd2>[ +<cmd3>[ +...]]];"

executes the specified vim commands before starting the interactive session. Commands using control characters should be escaped by prefixing with carat ( ^ ) - eg for an escape use "^[". There is no limit to the number of commands that may be passed in using -in and + they are executed in left-to-right order.

• -debug Reduces the height of the fake_vim window in order to display more lines of messages in the console.

• -test Starts up in normal jot command mode (by default fake_vim starts up in vim command mode) the vim command mode can then be entered by typing the command {Esc i} - this is used by test_all.jot.

The remainder of this section is devoted to differences between the behaviour of fake_vim and that of standard vim, as defined by this guide. Different versions of vim have slightly different behaviours. for my analysis of vim behaviour I used two builds of the same version:

• Crouton Chromebook - 7.4 (2013 Aug 10, compiled Nov 24 2016 16:44:48)

• Fedora PC - 7.4 (2013 Aug 10, compiled Apr 8 2016 11:52:51)

Also look at the ( ? ) buffer after starting fake_vim - this contains a complete list of vim actions supported by your version of the fake_vim script.

• Startup - As described above, start jot with the startup file fake_vim.jot followed by normal vim arguments.

• jot functions - all of the key functions described in the user guide (see Functions defined at startup and key bindings) are available in addition to vim editing keys.

• Nomenclature alert: in vimspeak tags refer to index points (e.g. read from a file generated by Exuberant Ctags), similarly a Ctags-generated file is known as an index file in jot.

Why does jot rename something when there's already a perfectly good name that everyone knows and understands? Well, in jotspeak tags are little bits of metadata that can be sprinkled over an, otherwise, plain-text file image (for details take a look at About Tagged Text). Most native english speakers could probably guess what an index file might be used for. They would also probably be able to guess what a tag might be.

• fake_vim completely ignores whatever you may have in your ~/.viminfo

• {Ctrl+w} - this is a prefix to several important window control functions but it closes the current page on my Chromebook and it's not so easy to nobble Chromebook shortcuts, so fake_vim picks these up on {Esc w} instead.

• Handling multiple files - When switching between open files in vim it insists on either writing or abandoning any edits you've done before moving to the next file. This affects :n, jumps and tag operations. The fake_vim behaviour is to allow any file-to-file jumps but the session cannot be closed until all modified file images have been written.

• Messages, warnings and errors - no effort was gone gone to in the making of fake_vim messages to exactly match genuine-vim messages. Also fake_vim messages disappear on the next command and many error conditions, reported by vim, do not result in fake_vim messages.

• Currently, the {d} and {y} prefixes to movement commands behaves slightly differently to genuine vim. If the movement ends up at the beginning of the next line then genuine vim {d} will delete the character left of the cursor, {y} yanks to the end of the line. Whether this be either bug or feature fake_vim does not attempt to replicate it - fake vim deletes and yanks are consistent with the underlying movement command.

• The vim cursor is red, fake_vim's is white.

• There are all kinds of subtleties in the definition of a sentence for {(} and {)} - the implementation in fake_vim fails to respect a lot of these.

• When genuine vim writes a report (eg :reg - reports register status) ir replaces the last few lines of the display with the report text - the view is restored on next keystroke, fake_vim replaces the entire view and prompts user to hit {Return} to continue. Unlike vim, the keystroke does not contribute to the next command string.

• Currently there is no undo/redo facility available in jot or fake_vim. While this is not too difficult to implement for vim commands, its impracticable for jot command strings. One of the main motivations behind fake_vim was to allow super-powerful jot command sequences to be mixed with vim commands.

• jot does not support any form of line-wrapping mode. Hence :set [no]wrap is not supported in fake_vim. The {zh} and {zl} commands are fully supported though.

• In the event of {zl} or {zh} causing the current character to go out of view, genuine vim will adjust the cursor position to keep it in view. It's hard to see how this feature could be even remotely helpful, so fake_vim allows the cursor to go out of view and repeats the relevant section of the line in the console area.

• The arrow keys are set up for normal jot operation - vim-style cursor control is available on the {h}, {j}, {k} and {l} keys.

• When near the end of the file image, vim will often display blank lines. Also the last line is deleted vim will generally move up the screen to the previous line leaving another blank line behind. In contrast, jot will only display blank lines when the file image is smaller than the window.

• Genuine vim will not normally allow the cursor to go past the end of a line of text, the only exception appears to be with entirely blank lines. In vim these are displayed as though the line contains whitespace. This aversion to allowing the cursor past the end of the line probably explains the abundance of vim functions with before/after-the-cursor variants.

The native jot end-of-line behaviour is to allow the cursor to go just one character past the end of line displaying a tilde ( ~ ) after the actual end of the line. This native jot end-of-line behaviour is adopted in fake_vim.

• In genuine vim, either {Esc} or {Ctrl+c} will exit insert mode. Unfortunately, jot is not clever enough to know whether an escape is a manual exit from insert mode or the begining of an escape sequence. Since it's quite useful to allow escape sequences (e.g. cursor-control keys) in insert mode fake_vim exits insert mode in response to {Ctrl+c} or {Esc i}. On exit from insert mode, vim will, for some reason, move the cursor back one character, jot just leaves it after the inserted text.

• The {U} command, in genuine vim will restore the last line where insert mode was begun. For vim, this only works if the insertion created no new lines (ie no {return} was entered in the text) then no restoration is done. In fake_vim the first line is restored and the additional lines are left as-is.

Commands supported by fake_vim.jot

fake_emacs.jot

$ jot <filePathName> -st=fake_emacs

The fake_emacs script is designed to replace the normal startup script - in fact it calls the normal startup script (see startup.jot) so most of the normal jot functionality is also available.

The end point for this project is a good implementation of the functions described in the mg man page (mg is a minimal-functionality emacs). Unfortunately, as it stands, fake_emacs.jot is not anywhere near that endpoint.

There are some features of emacs features which will probably never be fully implemented in jot because they're either too hard, impossible or because jot already has a better approach:

• "Undo changes" - undo commands are very difficult, maybe impossible, to implement in editors like jot as one operation can affect any number of buffers and internal bits of state. However it is quite likely that the journal system (see recover.jot and about not losing your work) could be adapted for this purpose.

• "Incremental search" - although this looks flashy, it doesn't seem to be a particularly helpful feature. Jot does an adequate emulation of it but the jot PopupSearch function offers a better way viewing the population of partial matches to a string. The emacs incremental search restricts the horizon to one page, PopupSearch searches toe entire document.

Commands supported by fake_emacs.jot

$ jot <pathName> -st=fake_emacs

$ jot <pathName> -st="fake_emacs -option1>[ -<option2>[ ...]]"

fake_emacs function Escape sequence

get.jot

• The pathSpec may fully-defined path, in which case the script lists all members of the initial directory and invites you to select a child file or a subdirectory.

• Alternatively, the pathSpec may contain simple wild cards "*" any number of times in the names of any number of path elements. The result will be a list of all possible matching path/file names.

• In addition to simple wildcards, an entire path element may be replaced by "/**/" (a tree-search wildcard). In this case it launches a breadth-first search of the filing system. The search-depth limit defaults to 5 but may be set by adding the required depth e.g: /**10/ will set the search-depth limit to 10.

• -to=<chr> - specifies buffer key to be used for the first selected file, for any subsequent files get.jot will prompt for a buffer key.

• -allto=<chr> - specifies buffer key, every selected file will be appended to the contents of the buffer. If both -to= and -allto= are specified then the value set by -to= is silently ignored.

• -indent when combined with -allto= this requests each nonblank line be indented by two blanks - this is used with -allto= and ensures that each new document is identified as a separate chapter in the buffer - see About words, lines, phrases, sentences, paragraphs, sections and chapters. If -allto= is not given then -indent is silently ignored.

• -depth=<n> specifies the maximum allowable search depth for tree searches (see wildcards, above).

• -list specifies that the results are displayed as a list of fully-formed paths - by default results are displayed in the form of a list of parent-directory paths, each followed by a list of children.

• -stdout - on completion results are written to stdout and the session terminates This option is probably of little value unless the path specification contains wildcards but with wildcards it allows the breadth-first filing-system searches to be used from the CLI.

If an initial path is given then the contents of the specified directory is displayed as the parent pathname followed by a list of it's children in the ( + ) buffer. The ( + ) buffer is effectively a menu - navigate up and down with the Up/DownArrow buttons and hit {F1} to descend to an item. Four types of item are recognized and the behaviour for each is as follows:

• If the child is a recognized document type the file is opened and displayed in the nominated buffer. MS-word documents (.doc and .docx) are first converted to plain text using tika, XL spreadsheets are also converted using tika and PDFs are converted using ps2ascii.

• If the child is another directory then the full pathname of that directory with a list of children are appended to the menu buffer ( + ).

• If the selected child is an archive file ( .tar, .tz, .zip or .cab ) then the full pathname for the archive, followed by it's contents is appended to the menu buffer ( + ).

• If the child is none of the above it is assumed to be some sort of plain-text document and it is read into the editor - so avoid descending into binary files.

This get.jot script defines the function getDiag, this displays the state of important internal buffers and data objects etc. It is accessed via the escape sequence {Esc d i a g}.

The get.jot script modifies the behaviour of the Help function. Whereas {F1} normally enters the help pages unconditionally, the script causes it to first check the current buffer. If it's in buffer ( + ) then it descends to the selected file.

For each directory/archive entry in the menu buffer ( + ) the path is prefixed with a key followed by an ascii tab (ascii tabs are displayed as tildes ( ~ ) in jot). This is used to determine the correct approach for opening the object. The following keys are currently used:

• dir - a simple directory.

• tar --list --file - a tar archive.

• tar -tvf - a compressed tar archive.

• unzip -l - a zip-file archive.

• cabextract -l - an MS-cabenet archive.

If the original path contains wildcards then the filing system is searched for matching subpaths, the following wildcards are recognized:

• * - Replaces any number of characters in a path-element name.

• ** - Replaces any number (up to a preset limit) of path elements. Note that the ** must be an entire path element i.e. should be ( /**/ ). The search depth can be set using the -depth=<n> modifier.

On completion of a search entries are appended to the menu buffer - one for each matching path.

If the ( 3 ) macro is used and -toall= was given then all files listed in the menu buffer ( + ) are loaded in the specified buffer. If -toall was not given then macro-1 exits with an error message.

e.g.

> get ${JOT_RESOURCES}*.t{F2}

• selects all files ending.t, in your jot resources area.

> get ${JOT_RESOURCES}/**/*t.t{F2}
• selects all files ending "t.t", at any level of your jot resources tree.

The get script picks up a directory path and lists files in the directory in a simple menu-style buffer. The intrepid explorer of filing systems may then browse through this buffer using the cursor-control or find keys to select either a file or directory. The target is selected by running the 0 macro (bound to the numeric-keypad 0 button). e.g:

> '0{Return}

or

> {KP_0}

If the target file turns out to be some sort of archive (.tar, .tz, .zip and .cab are currently supported), then the file contents are listed and you are invited to select one of the member files. The selected file is then unpacked and it's image turns up in the nominated buffer.

If the target file is an MS-word document (.doc or .docx), a Portable document format document (.pdf) or Excel an appropriate conversion utility is deployed to translate it to plain text.

On completion of a search pass, the ( + ) buffer shows a directory listing shows one item to each line of the buffer, with the directory path at the head of the list, subdirectory names are suffixed with an oblique ( / ). The list contents of each directory is headed by the directory path, normally headed by the word "dir "followed by an ASCII tab this will be displayed as a tilde ( ~ ) in the window.

If no pathname is given, the current buffer is checked - if the cursor points to a string that matches a valid pathName relative to the current file then that is used. If not, then the env GetDefaultPath is used as a path prefix.

When a file is selected, the get script identifies the file type from the name extension:

• <name>.xls - a microsoft excel spreadsheet,

• <name>.doc - a microsoft word document,

• <name>.docx - a microsoft word document,

• <name>.pdf - a PDF document,

• <name>.htm - a html document,

• <name>.html - a html document,

• <name>.tar - a tar archive,

• <name>.tz - a compressed tar archive,

• <name>.zip - a zip archive,

• <name>.cab - a microsoft cabinet archive,

• Files with any other extension are treated as plain text.

If your selection is a directory (including the .. directory to descend the directory tree) then the new directory redefines the menu. If the target is a file and you did not specify a destination buffer on the command line, you will be prompted for a destination buffer and the file will be loaded into that buffer.

To force get to pick up the current file-image path, even when the text under the cursor could be interpreted as a pathName, then enter some wildcard as the path - e.g:

get *{F2}

The get script will open some classes of non-text documents and archive files using a helper app where necessary, this requires the installation of the helper:

• excel spreadsheets use ssconvert, this is part of the gnumeric suite.

• it's compiled c not java, so it goes like the wind,

• it can extract a list of sheets for you to browse; tika, by contrast just dumps all the sheets into one vast page.

• PDF, MS-word (.doc and .docx) and gnumeric for spreadsheets

• It opens tar archives with tar - this should be on your linux search path. In MS-windows systems, a suitable version of tar can be downloaded from the sourceforge gnu project.

• It opens zip files with unzip.

Here is a full list of the various helper co-processors you may need

• cabextract - microsoft, in most linux distributions

• file - gnu.org, in most linux distributions

• gunzip - gnu.org, in most linux distributions

• iconv - gnu.org

• gtar - gnu.org, in most linux distributions

• tika - tika.apache.org/download.html, get.jot expects to find this in ${JOT_HOME}/bin - you will also need java.

• unzip - gnu.org, in most linux distributions

• which - gnu.org, in most linux distributions

• gnumeric - gnu.org

comp.jot

If the -backup value is given, then the most recent backup version is read to the ! buffer - see backup.jot. The path for the backup directory is assumed to be <originalFilePath>/backup - if no backupVersion string is specified it takes the most recent backup version. If a backupVersion string is specified then the extracted version name will match this string. In the even of more than one backup versions matching the given string, an error message is issued.

By default, comp.jot will redefine the windows to give you a split-screen view of the two buffers. The left pane is floating and will show the current buffer, the right pane is fixed to the nominated reference buffer. To run comp.jot with your current window configuration - use the optional the -nosplit option.

The -horizontal qualifier causes the screen to be split into two equal-sized horizontal windows.

It also redefines macros 4, 5 and 6 (bound to numeric-keypad buttons 4, 5 and 6).

• Macro 5 ( {KP_5} or {Esc 5} ) will compare successive lines in the current buffer with those the ref buffer, starting at the current character position in both progressing forwards through the buffers.

When the comparison reaches the end of a buffer all colour tags are removed from that buffer. This behaviour gives an easy way to remove the colour tags from the buffers:

> m0{KP_5}
• Button 4 is similar, except that it compares backwards and does not clear the colour tags.

• If a jot command string is entered before hitting buttons 4 or 5, then instead of running the comparison, the jot command string is applied to both buffers - this is designed to facilitate re-synchronization of the two buffers.

• For those lacking a numeric keypad, or for linux users when the keypad has not been set up for jot (see X-windows setup) then {Esc 4}, {Esc 5} and {Esc 6} will work.

• Button 6 initially repeats the previous interactive command but in the other buffer. Subsequently, it repeats the same command in both buffers.

See also CompareBufs.

recover.jot

$ jot <fileName> -st=recover[ -norun]

Journal files are collected when the editor is started with the -journal qualifier see About not losing your work. These can be used to retrace every step in an editor session in the event of an abnormal exit. The journal files are held in a subdirectory alongside the primary file named <filename>.jnl (where fileName is the primary file). It holds snapshots of all files and system queries read by the session and a history.txt file containing a log of your keyboard and mouse activity. All these files are deleted when the editor restarts normally. The journal directory also holds a lockfile, imaginatively named LOCK, this is normally deleted as the session exits - unless the session terminates abnormally. The LOCK file has the effect of preventing a new session starting and destroying the journal files.

The recover.jot script works by translating the history.txt file into a command script (named recover_now.jot) that will retrace your interactive session with snapshot copies of your input files and then winding it's way through all of your interactive commands and keystrokes.

The identities of saved-copies of files is preserved but they are uniquified by suffixing them with the file modification-time datestamp. An extended session may read, modify and write a file and then read it in again later. It therefor keeps a separate snapshot of every read of the same file. If, on inspection, it finds the file's modification time is unchanged on the second or subsequent re-reads, the file is not copied again.

The history.txt file, in addition to all your interactive activity, contains the uniquified pathnames for the various snapshot files. As they are read, the editor checks that the files are read in the same order as in the original session. It does this by verifying the new pathname against the original, which is also held in the history file.

For the duration of the recovery run all file writes are disabled - when the recover_now script script terminates the session should continue normally, Appending any new commands to the original history.txt file and adding new snapshot files.

On completion of a successful recovery, the original journal files are left untouched, you must delete them before launching a new editing session.

The recovery process starts with a special initialisation script recover.jot which reads the history.txt file and creates a runnable recovery script in your pwd, named recover_now.jot it then runs this recovery script. Here is the full process, from the start of the crashing session:

$ jot <fileName> -journal

• The power fails or something crashes (to simulate this, suspend and kill the session. The journal files should visible in ./<fileName>.jnl/

• Start of the recovery procedure (note this next editor session is started with no -journal qualifier if you did it would fail immediately complaining that it could not create a new LOCK file).

$ jot <fileName> -st=recover

This creates a customized recovery script recover_now.jot which runs through all the keystrokes and commands in the original session. this file is run - if all goes well you will end up exactly where you were. On completion of the recovery, any new commands or keystrokes are appended to the journal repository. In theory, you can keep on crashing and recovering the sessions.

In some instances you will want to edit the recovery file before running it. In this case use the -norun to exit before running the recover_now script - e.g. when winding back activity as a substitute for an undo function.

$ jot <fileName> -st="recover -norun"

The recommended method of analysing and editing these scripts is with the is to edit with the annotate_recovery_file.jot script.

Now, if the recovery session crashes in the same way at the same point, congratulations, you have probably discovered a genuine jot bug!! Please report your bug - a tarball of the journal directory would be most helpful to the investigation into what went wrong. To recover from such a situation, edit the recover_now.jot recovery script, removing the last command then restart using the modified script:

(rl)0
$ jot <fileName> -startup -init="%r= -asConsole ./recover_now.jot"

• This approach is also useful for recovering from self-inflicted disasters. Suppose that, at some point in the session, you've destroyed something and now you'd now like to see it back again. Then edit the recover_now script, deleting the commands that caused the problem and all subsequent commands. Or, maybe, by inserting a command to save whatever it is you you wanted to keep.

• The recover_now.jot script must be run with -asConsole because they contain escape sequences - see %R.

• Optionally add the -hold qualifier, this holds the screen before exiting so, in the event of an early exit, you can see what's happening - see

-hold.

• It is essential to include the -startup qualifier to avoid running the default startup script, the recover_now script will run the original startup and things can break if the startup is run more than once.

There are several things that might go wrong with this approach to session recovery:

• If there is some discrepancy in the environment of the recovery session, compared to that of the original session, then it is possible for the sequence of recovery-file pathnames to go out of synchronization. When a script opens a series of files, it is assumed that the recovery session will open the same files in the same order. Although this situation cannot be avoided it can, at least, be detected by checking the original pathnames.

The operation of the jot debugger is also different in recovery mode, if the original session invoked the debugger then the recovery session will emulate the debugger interaction from the original session. This could be a problem if it is required to single-step the recovery process.

In order to single step through the recovery process, set the Trace_Recovery bit (0x100) of the trace mask - see %S=trace e.g:

> %s=trace 0F901;

to set an immediate breakpoint or

to enable the next t or %s=commandcounter command. Otherwise these will be treated as though they were from the original session.

When this condition is detected the recovery will normally stop abruptly with a message of the form:

Disaster

Note: the history file in the journal area is entirely separate from the history maintained for the %Q query history and is not affected by the the CLI -history setting.

Undoing changes

• When embarking on an editor session which might be problematic, always add the -journal qualifier - this creates the history.txt file and various backup files for the session:

$ jot <yourFile> -jou

this creates the directory <yourFile>.jnl which contains a history.txt this is a record of how the session started and all of the keyboard and mouse activity. It also maintains snapshots of any files read by the session.

• First run the recovery script, the -norun qualifier speeds things up as it causes the recovery to exit before attempting to restore the session.

$ jot <yourFile> -st="recover -norun;"

• The first step will have created a recover_now.jot file - this will restore your session past the point where you went wrong. So we edit this file removing the command that caused the problem and, in general, all the following commands.

$ jot recover_now.jot -in="%r=annotate_recovery_file;"

• The annotate_recovery_file.jot script displays the recovery file in a sliced window showing the meaning of escape sequences. At the end of this file you should see the command "%s=recoverymode 0" - this is important as it re-enables normal I/O activity allowing you to write normally so don't remove this from the file. Write the modified recover_now.jot with "%C".

• Now, finally, you're ready to run the recovery script:

$ jot <yourFile> -startup -in="%r= -asconsole recover_now.jot;"

annotate_recovery_file.jot

$ jot recover_now.jot -in=%r=annotate_recovery_file;

The script reads the recover_now.jot script (this is generated by recover.jot, see also about not losing your work) and displays it in a vertically-split window with the recovery file in the righthand slice and the linenumbers and annotation in the left. Note that the recovery script contains escape sequences and this script is intended to simplify the manipulation of these scripts by showing the functions attached to the key codes in the recover_now script.

$ jot <fileName> -st=recover -norun

It is recommended that the recovery script be run with the -norun option - this exits immediately after creating the recover_now script.

You should now be the proud owner of a recover_now.jot script. Run this now (as described in recover.jot) and you should be in the same position as you were when the original session stopped.

However, since you are editing the recover_now script you are having problems with the recovery or, maybe you just want to let it run until some mistake was made in the editing - jot does not have an undo function. Now the recovery script contains the escape sequences picked up by the original session and, just looking at these, it is not always easy to see what's going on.

recover.jot Restrictions

$ jot <fileName> -startup -init="%r= -asConsole ./recover_now.jot"

• The recovery process will only work if the recovery session has an identical environment to the original - unfortunately. This can never be achievable since the clock will have ticked on since the original session and a few, but not many, scripts and procedures are time dependant. However response of all system queries via the %E command are held in the journal area - so they're fine, system queries using %Q may be problematic.

The query dir is most likely to cause trouble - the directory contents might change between the original session and the recovery session. Then scrolling down a fixed number of filename may lead to the wrong file. If the selected file is then read with the %i command, then it will always pick up the correct file from the journal area because the correct file name is picked up from the history.txt file.

• If something, in the original session, fails and then it's fixed by making some adjustment to the filing system (e.g. a chmod, mkdir or some-such) - then the command that originally failed will now succeed in the recovery session. This might cause the overall recovery session to diverge and possibly fail.

• The recovery should be done in the same sized xterm as in the original session. If <<PageUp>> and <<PageDown>> operations were used, these set the focus point with reference to the window size. Also, the outcome of basic functions like <<WordRight>> and <<WordLeft>> are dependant on the screen width. The standard startup script sets window size in relation to screen size. For this reason the recover.jot script will refuse to proceed unless the window height in the recovery session is the same as that in the original session.

• If, in the original session, you interrupted something with Ctrl+C, the command count at interrupt time is noted and the recovery session is interrupted at the same point by setting a command counter.

Recovery notes

32 18<<MOUSE>> -- The event position was line 32, column 18 in buffer ( . )

%iq=x.lis
%%Recovery pathname:  32 l99.t.jnl//x.lis_20220417_114221, Original pathname:   5 x.lis

(r, m, m-0)0  

%qz=file .; z. (r, m, m-0)0
%%Recovery record:                  Name = "."
%%Recovery record:                 inode = 410
%%Recovery record:                  Mode =  40755
%%Recovery record:                   uid = 1000
%%Recovery record:                   gid = 1000
%%Recovery record:                  size = 2920
%%Recovery record:  writable by this UID = yes
%%Recovery record:             directory = 1
%%Recovery record:                  link = 0
%%Recovery record:           Access time = 2022/04/17, 13:04:03 (1650197043)
%%Recovery record:           Modify time = 2022/04/17, 13:16:42 (1650197802)
%%Recovery record:         Creation time = 2022/04/17, 13:16:42 (1650197802)

• When the original session contains debugging activity including single stepping and continuation from breakpoints. The keyboard activity is recorded in the history file in the same way as normal session activity with the debugger reading commands from the recover_now file.

There is a special problem that arises when debugging the operation of the recovery commands - by default the debugger will take commands from the recovery script not the keyboard. The Trace_Recovery bit of the %s=trace vector tells the debugger to accept commands from the keyboard. So to debug the recovery script, instead of inserting a simple T command insert %s=trace F901;

cerr.jot

do.jot

ls2list.jot

Transforms the output of a unix ls -laRF listing to a list of paths for multi_do.jot, multi_ed.jot etc.

multi_do.jot

This script assumes that the current buffer is a list of pathnames. It takes a CLI command as it's argument this is applied to all files in the list and the results are captured in the @ buffer. See also ls2list.jot.

• The -quick option runs the command with lists of pathnames as extended argument lists this is faster for big heavyweight commands which take time to activate.

• The optional $1 entries are replaced by each pathname from the list ($1 only allowed once when -quick is given).

Examples:

$ ls $JOT_RESOURCES/*.txt | jot_dev -in="%r=multi_do cat \$1 | sed s/ and / AND / -quick"
$ ls $JOT_RESOURCES/*.txt | jot_dev -in="%r=multi_do cat \$1 | sed s/ and / AND /"

multi_pair

$  mkdir test; cd test

$  cp -R $JOT_RESOURCES/* .

$  ls -aRF | jot -in="%r=ls2list; (rr-n.r0aa&i:\t$JOT_RESOURCES/:ham)0 %r=multi_pair diff"

$  jot l99.t -in=f/__50/s/zzz/ %c
$  chmod u+w test_get/another_dir1/t.t; jot test_get/another_dir1/t.t -in=f/jon/s/zzz/ %c

$  ls -aRF | jot -in="%r=ls2list; (rr-n.r0aa&i:\t$JOT_RESOURCES/:ham)0 %r=multi_pair diff"

multi_ed.jot

$ ls *.doc | jot

sync.jot

$ jot -st=sync

$ jot -st="sync[ -check|tostick|fromstick][ -bydate][ -newstick][ -newfs][ -localpath <path>][ -debug][ -setstick][ -newfs]"

ced.jot

$ jot -st="ced [-lin][ -win][ -notest][ -preproc][ -debug][ -dynamic][ -strip]

• -lin -- compiles a linux executable for the same architecture as the host, by default it also runs the basic test script (see test.jot). Also, by default, it links with the static ncureses library and includes symbolic-debugging metadata in the executable (see -static and -strip - below).

• -notest -- suppresses the testing of linux executables when combined with the -lin qualifier (see above), when -lin is not given, this has no effect.

• -dynamic -- the linux executable is linked using the dynamic versions of ncurses libraries.

• -preproc -- Only runs the preprocessor stage - it outputs the expanded source code.

• -strip -- links without the debugging symbol table.

• -win -- Compiles a windows executable using CL (the Microsoft Visual-C compiler) using mainly VC libraries and some GNU libraries. When running under linux it uses the wine compatibility layer.

Note that the following paths must be registered:

• include paths:

• libgw32c-0.4/include

• "Program Files (x86)/Windows Kits/ ... /ucrt"

• "Program Files (x86)/Microsoft Visual Studio/ ... /include"

• "Program Files (x86)/Windows Kits/ ... /um"

• "Program Files (x86)/Windows Kits/ ... /shared"

• lib paths:

• libgcc.lib

• libgw32c.a

• "Program Files (x86)/Windows Kits/ ... /ucrt/x86"

• "Program Files (x86)/Windows Kits/ ... /um/x86"

• "Program Files (x86)/Microsoft Visual Studio/ ... /lib/x86"

• "Program Files (x86)/Microsoft Visual Studio/ ... /bin/Hostx64/x86"

• -debug -- The windows version is compiled with Microsoft debugging symbolic and line-number metadata.

retab.jot

This script is intended for use as a precursor to autotab.jot, autotabjust.jot, autotabdp.jot - see tabulated text.

retabhere.jot

This inserts tabs in the current-character column. This is used in conjunction with retab.jot, autotab.jot and autotabjust.jot.

This script is useful for preservation of one column of a partly-formatted table - see tabulated text. If you have several tab points to insert, it is important to start with the rightmost tab point and work leftwards.

autotab.jot

Lines which do not contain any tabs are ignored - see tabulated text.

autotabjust.jot

Similar to autotab, but right-justifies so that, on any line containing tabs, the following tabs are aligned - see tabulated text.

autotabdp.jot

Similar to autotab but inserts blanks so as to align decimal points in the column following the tab - see tabulated text.

tab.jot

mail.jot

Usage example

Defined escape sequences

c.jot

It also sets the env variable GetDefaultPath to /usr/include - the effect of this is to tell the get.jot script to default to the specified path, with this set you can set the cursor to a library include file and it will find it.

The speedup due to the hashtables, although welcome, is not really the principal motivation for their use. Because C allows multi-line comments and text strings, it is difficult, perhaps impossible, to reliably parse C when plodding back through the code. The c script plods forwards once to get forward and back links for the hashtable.

• {KP_1} - Calls macro 1, this finds last '}' character then goes back to it's matching '{' using the hash table for that buffer - see about hashtables.

• {KP_2} - Calls macro 2, this Find next '{' character then goes to it's matching '}'.

jot.jot

Sets up macros 1, 2 and 3 (bound to numeric-keypad 1-3) to functions suitable for browsing jot command scripts. As with the c.jot script, it uses hash tables. Jot code is another one of those difficult ones where it's difficult to plod back through the code.

In interactive usage, unterminated strings are allowed - e.g. f/fred{Return}, jot also allows these in macros although this is not recommended. When one of these is left unterminated in a script it is generally a coding mistake, but it might lead to the jot command parser being unable to match parenthesis. Such errors are difficult to trace. Use {* KP_3} to locate unterminated strings in your scripts.

Note that jot.jot adds tags to the code, this will cause code called via the %H=call command to fail when it is next recompiled. See Calling functions by name.

• {Esc 1} Calls macro 1 - find previous ')' then refocus to its matching '(' using hashtables.

• {Esc 2} Calls macro 2 - find next '(' then refocus to its matching ')' using hashtables.

• [<jotCommandString>]{Esc 3} - If no jotCommandString is specified then this macro simply checks the jot code for syntax errors. When a command string is specified the command string is executed at the start of each jot command in the text. This can be used to search scripts and macros for specific commands and, if necessary, change them.

Something like the following was used to to modify scripts when the old W command was abolished and replaced by %w=refresh;

> (v/w/s/%w=refresh;/ %o;, ){Esc 3}

When the macro encounters a "W" command in the script being scanned, it is replaced by "%w=refresh;" The following command line was used to find all instances of "%W;" in every jot script and replace each them with %w= -refresh;

$ jot -in="%r=jot.jot; %eq=ls ${JOT_HOME}/coms/*.jot; ( %iw='q; %d$=(v/%w\\;/s/%w=refresh\\;/ %o\\;, ); '3 zqm)0"

perl.jot

skill.jot

csh.jot

sh.jot

ksh.jot

Similar to sh.jot but supports some additional ksh keywords.

mif.jot

edif.jot

verilog.jot

Restrictions/Assumptions:

Buffer usage:

HotKeys

vhdl.jot

tcl.jot

bt.jot

This script is useful when debugging complicated modular jot scripts. It sets up some backtrace functions using the query backtrace report.

• <<RawBacktrace>> - this simply extracts an ordinary backtrace report to buffer @.

> {Esc a b t}
• <<AdjustedBacktrace>> - This extracts a query backtrace report to buffer @ and attempts to adjust the line numbers so that they match those in the source file.

The backtrace query only gives the linenumbers as they are in the code-repository buffer ( * ). This report would be more useful if the line numbers referred to the linenumbers in the source file. It attempts to identify the source file using grep - searching for the last function name in the code repository buffer. It then calculates the correct line-number offset to get the lines in the source file and adjusts the linenumbers accordingly.

There are at least two ways in which this can fail to give an accurate result:

• 1 the last function in the code repository may not be from the same file as the functions in the backtrace report and

• 2 the file may not be in the place where bt.jot does the search ( ${JOT_HOME}/coms )

trap_failure.jot

This script can be useful for debugging scripts, functions and commands. When something fails it's not always immediately obvious what went wrong. This script runs the command sequence (or macro or function) through to failure, notes the command counter and then re-launches the command with the command counter set to trigger a breakpoint at the point of failure - see the jot debugger and %s=commandcounter.

Note that, in order to get a repeatable command count, the initialization must be consistent. Many initialization command sequences can just be included in the command sequence but, where the initialization involves conditional commands this might not be the case and a separate initialization sequence must be specified using the optional -init=... modifier.

See setting command-counter breakpoints for examples of usage.

searchbuffers.jot

listbufs.jot

age.jot

date.jot

backup.jot

copy.jot

paste.jot

count.jot

unlockall.jot

freeall.jot

exit.jot

doc2fold.jot

This translates a document to a folded help document suitable for use in the jot help system. The document sections and paragraphs must be structured according to the jot document form - see text document preparation and about help files.

fold2doc.jot

This performs the reverse of the doc2fold.jot process, it is only useful when a help file requires major changes and the original source document is not available - see also about help files.

doc2mif.jot

Translates the text in the current buffer into a framemaker mif file - sections and paragraph format - see text document preparation

txt2html.jot

         [ -split [ -head <fooheadterImagePath>][ -foot <footerImagePath>][ -index]]{F2}

For example, the following line (from the examples text), refers to functions defined at startup and key bindings.

HREF references are checked - these must match a section heading either in the current document or in some other html in the same directory. If, after searching these, it still cannot resolve the HREF then the HREF target is added to a list of unresolved HREFs and the script terminates without writing any html.

If the document contains more than one section with the same section-name string, then this is listed and the script terminates without writing any html.

pdf2txt.jot

doc2txt.jot

txt2

html2txt.jot

$ jot [listPathName>] -in="%r="html2txt [{-url=<url>|-seturl=<url>|-raw=<pathName>|-list}];"

$ ls ~/Downloads/* | jot -in="%r=html2txt -list;"

The html2txt.jot script defines two functions and two macros, it also uses pdf2txt.jot and doc2txt.jot to define functions pdf2txt_translate and doc2txt_translate respectively. It also uses curl to download references.

• html2txt_main - the main argument scanner function.

• html2txt_translate - function translates a html to plain text.

• html2txt_FollowLink - function is a mouse-click callback, it downloads a child page and translates it, either by calling html2txt_translate (htmls), pdf2txt_translate, doc2txt_translate or tika to translate spreadsheets.

• macro 7 identifies all links in the current collection of files and downloads them using curl. This feature is superseded by get.jot - the -allto=<key> is a better method of doing this.

• macro 6 lists all URLs in the current collection.

Note that it can only descend into referenced documents for simple web sites

• curl cannot descend to documents in MS Ondrive-hosted sites.

If the document contains hypertext links, these are represented by green-background text in the text document, local links can be clicked as in a linkdocs.jot document. If the link is to an external document, then this document downloaded, converted to text and appended to the current document. If the external reference is to a PDF or MS-word document then pdf2txt.jot or doc2txt.jot are used to extract text from these document types.

The objective of all this is not to invent yet another web browser, but to bring web documents into a form where jot's powerful search features (see Navigation by context and, most especially, the proximity search functions) may be used.

Examples:

$  jot -st=dbg -in="%r=html2txt -url=file://${JOT_HOME}/docs/jot_ug.html;"
$  jot docs/jot_qr.html -st=dbg -in="%r=html2txt -seturl=file://${JOT_HOME}/docs/jot_qr;"

dic.jot

When you run dic.jot for the first time an index file is written to your JOT_RESOURCES area - you must have write access to this area. The index file is named ${JOT_RESOURCES}/websters_index.txt it is plain text file, about one tenth the size of the actual dictionary (about 2.2Mb compared to about 28Mb for the complete dictionary). The index file structure is a bit more complicated than the index files used by big_file.jot - it has an explicit entry for the length of each section.

• First download the dictionary,

• now create the index:

$ jot -in="%r=dic"

big_file.jot

$ jot -in="%r=big_file -file=<pathName>[ -size=<n>][ -all][  -cdlIndex|-vlogindex]

• <SectionName>{Esc b q} - big_file Query - reads the specified section (e.g. a subcircuit) and brings it into view. Sections appear in the order in which they were requested, the first (header) line of the section

• <String>{Esc b g} big_file Grep - greps the big file searching for the specified string.

• {Esc b w} - big_file Write - writes the modified file back to the filing system.

• {Esc b d} - big_file diagnostic - displays a temporary buffer showing the current value of all of the scripts internal state variables. To see a list of section-name keys use the query keys command - e.g:

> %qz=keys .=;

This script is designed to facilitate browsing and, to a limited extent, editing of very large files (see about large files). It works on the assumption that nobody's ever going to want to look at all of some huge file and that these files are structured and sections and that each section be identified by a unique name. The file is first scanned to create a section-name index which can be read by the editor. The user can then interactively pull sections into the editor session.

If there is some text before the first section listed in the index, this is assigned the section name "Initial_gumpf" to make it accessible.

In practice, grep, or something similar, can be used to create the index, this task can be performed in advance, maybe as part of the batch job that created the big files. The jot session reads the index file, and responds to interactive requests to view named sections of the big file by pulling them into view. The index provides jot with two values a byte-count offset to the start of the section and a byte-count length of the section. It uses the offset and byte-count to read these sections using the -seek=<value> and -bytes=<value> %I qualifiers.

The index file can be prepared earlier and read from disc or it can be generated as the session starts up. The index file is marked with with the big-file's original datestamp. When the index file is contains this datestamp the big_file.jot script can detect situations when the index is out of date e.g: the big-file has been re-extracted or edited in some way.

The optional -index qualifier specifies an index-file pathname - this defaults to the big-file's pathname with "_index" appended. The script uses the index file to reference your big file.

If either the -grep=<Rex>, -vlogindex or cdlindex qualifiers are given then the script will generate a new index file, even if the file already exits. Otherwise it fails if the index file does not exist.

The -grep qualifier is grep command string that can be used to create a new index file with the appropriate datestamp mark. The -trim qualifier specifies some jot commands that transform a line of raw grep output to a usable entry for the index file. Typically grep outputs three colon-separated fields - linebumber, byte startpoint and the matching line. The trim command is required to reduce the matching line to a useful key.

The script defines these functions:

• bf_init - the initialization routine.

• bf_verifyMainFile - checks that the main-file datestamp matches the index-file check data.

• bf_simpleQuery - reads the specified section, adding it to the end of the viewable sections:

> <sectionName>{Esc b q}

e.g:

In this case it reads the section "fred", appending it's contents to the primary buffer ( . ). Note that sections appear in the order in which you query them *not* in the order they appear in the original text.

e.g:

• bf_writeModifiedFile - writes any changes you have made to the sections loaded by bf_simpleQuery.

> {Esc b w}

In the new version all the sections read into the editor replace those in the original file. Other sections are copied from the original file, preserving original section order. Before beginning to write the new version of the file, it renames the original to <pathName>_orig. As the modified file is written, a progress monitor popup appears in the top-right corner of the display.

The index file is used to create hashtable entries for the named sections which can then be accessed reasonably quickly using the -section=<key> qualifier of the %I command.

The index file contains a one-line header followed by any number of one-line entries - one for each for each section in the file.

The header line specifies the index creation time, f the file is found to be later than this, the index is deemed to be obsolete and is rejected.

Each section entry has three colon-separated fields.:

• The line number of the section start - it is used by big_file.jot queries to set line numbers.

• The start byte, this is used by big_file.jot to index the file.

• The key used by big_file to reference the section.

Sections are assumed to end immediately before the next one starts and entries must be in ascending byte order. Section-keys must, of course, be unique. This structure is exactly compatible with the output of the grep command when used with the -b option.

To generate the index at the start of the session - specify the grep and trim commands on the command line - these is an example of this in working with large files.

For CDL files there is a predefined grep and trim activated with the -cdlindex modifier:

$ jot -in="%r=big_file -file=<bf_name>.cdl -cdlindex;"

This will create and write the index file and you can then use the {KP_7} to pull any subcircuits of interest.

If the jot session is to be run as a batch job then add the exit command %A to terminate the session:

$ jot -in="%r=big_file -file=<bf_name>.cdl -cdlindex; %a;"

The index file will be assigned the name <bf_name>.cdl_index

Subsequent interactive sessions can then be started using the batch-job generated index:

$ jot -in="%r=big_file -file=<bf_name>.cdl;"

It is possible to write a modified version of the complete file but some care is required. The big_files.jot script defines the function <<bf_writeModifiedFile>> for this. It writes all sections in their original order but any section you've loaded using the section-reading functions will be written from the editors memory, replacing the original. This is one very good reason for using internally-generated index files which allow date-stamp checks.

If your changes should change the total number of characters in a section, then the index file will be wrong. The big_file script seeks to avoid this situation by writing the original big file's datestamp in the index - the big_file script checks this against current big file datestamp.

There's an example for you to try in the examples - Working with large files

multi_file.jot

$ ls -aRF <rootDir> | jot -in="%r=multi_file [ ... ]"

$ jot -in="%r=multi_file[ <options as above>"

There is an example at first with multi_file.jot index files (a subsection of working with collections of source files).

The multi_file script is intended for browsing large collections of source files belonging to some system see about large collections of files. Selected sections are read into a buffer for viewing - typically the sections will correspond to programming-language modules. These are typically referenced by module name.

The optional arguments are:

• -indextype=<type> - specifies that a new index file is to be built and the type of files to be indexed - see below.

• c - for C-language files. The detection of c-function definitions is a compromise between run time and accuracy. It checks each line of the file and selects lines which match the following criteria, after removing any potentially-confusing comments and strings:

• The first character on the line must be a lower-case alpha character,

• the line must contain an open bracket ' ( ' character and

• the line must not end with a semicolon.

This catches almost all valid function definitions and rejects almost all non-function-definition lines.

• perl - for perl scripts. It identifies lines begining withe "sub " followed by the subroutine name and an opn-brace character ' { '

• -index=<pathName>[,<pathname2>[,...]] - specifies the pathnames to be used for the index file, this defaults to multi_file_index in your PWD. You can use as many index files as necessary and they need not all refer to the same file types - indexes referring to any supported file type (currently C and perl) can be used together as appropriate.

• -htabsize=<n> - specifies the hashtable size, this corresponds to the number of modules in the index file. It defaults to 100,000.

• -destbuf=<key> specifies which buffer to accumulate the extracted modules, this defaults to the current buffer. Note that this buffer is used to hold the index-file images and is cleared after initialization.

The script define these functions:

• multi_file_init - As it's name suggests it's the main initialization routine, it checks and parses parameters, creates the hashtable and, when requested by the -indextype arg, it launches an index rebuild operation.

• multi_file_create_index - This reads the ls report and creates the index file.

• multi_file_simpleQuery - This expects to find a valid section-name in buffer ( $ ). This function is attached to macro_7 - ( {KP_7} or {Esc 7}

• multi_search_section_names - This searches the valid keys for any matching a string in the ( $ ) buffer.

Usage:

or, if you're lacking a numeric keypad:

Passes the section name to multi_file_simpleQuery. If successful, the module text is appended to the primary buffer.

or, if you're lacking a numeric keypad:

Passes the string to multi_search_section_names, this searches all the valid keys for any matching the string. The matching process is pretty crude - it obtains a list of keys and then filters out lines that don't match the string. Note that queries using the strings Byte, Section, Seek or any other strings that appear a lot in query keys reports are going to return lots of results.

Note that there is no facility for writing back modified versions of these files from a multi_file session - you must load the relevant files normally, in a separate buffer, then make your changes and write the complete file.

As with big_file.jot, multi_file.jot is driven by user queries and an index file. In this case, however, the files will normally be of moderate size but there may be hundreds of them with each one defining dozens of sections.

In the event of a name collision, the first instance of a name, as it appears in the index file, is taken as-is. Subsequent instances are uniquified by suffixing the name with __nnn, where nnn is the index-file line number for the duplicated name.

ctags.jot

$ jot <tagsFile> -in=%r=ctags;

$ jot <tagsFile> -in=%r=ctags -AtoZ;

There is an example in now a ctags-generated index (a subsection of working with collections of source files).

Exuberant Ctags is a GNU tool that generates source-code index files except that these are, for reasons unknown, called tags files. Anyway these function as index files and can be picked up by jot using this script. The script was developed and tested using ctags files generated by ctags 5.9, this announces it's _TAG_FILE_FORMAT as being type 2. The ctags.jot script therefore performs a similar function to multi_file.jot

Once it has read and inwardly-digested the ctags-generated index you can launch queries using macro ( 7 ), which is bound to key 7 on the numeric keypad ( {KP_7} ). If you do not have a numeric keypad or, if you have not set it up for jot (see X-windows setup) then Escape followed by 7 {Esc 7} will do. There is an example exercise - see working with collections of source files and now a Ctags-generated index e.g:

$ jot -st=dbg ${JOT_HOME}/source/tags -in="%r=ctags;"  

This opens an editor view of source file ${JOT_HOME}/source/jot.c and sets up the view to the start of the function SubstituteString.

In the same editor buffer it changes view to the start of the c function FreeTag.

ctags.jot reads the ctags-generated index file and defines a macro which takes an index-key and checks to see if it already has the relevant source file in memory. If not, the source file is read before the editor focuses to the start of the relevant section.

If you have more than a handful of source files in memory, you may find it helpful to run the listbufs.jot script especially with the -changed option, this reports the status of file images in jot buffers.

Without the -AtoZ qualifier, the script will always display the requested definition in a secondary buffer - that is a buffer created on the stack, with the buffer key ( ~ ). This allows the session to hold and display any number of source files but, in the general case, it's not possible to switch between them.

In contrast, with the -AtoZ qualifier, the source files are read into buffers A, B, ... Z, this limits the number of viewable files to 26 but navigating between them is quick and convenient. For collections of 26 files or less, the buffer keys are allocated at the start of the session, then all sessions using the same ctags index will have the same, fixed, buffer-key assignments.

If, however, there are more than 26 source files but you won't need to view more than 26 but maybe this doesn't matter since keeping track of more than 26 source files in a session would take some doing. The buffer keys are allocated at query time - the first will be ( A ), then ( B ) ... to ( Z ).

This script may be combined with ide.jot if desired.

thes.jot

duplicates.jot

purge.jot

mc.jot

$ jot ${JOT_HOME}/docs/spell.dic -ini="%r=mc"
$ ls /usr/lib64 | jot -ini=%r=mc
$ ls /usr/lib64 | jot_dev -ini="%r=mc -size=80x90"

mc2.jot

Similar to mc.jot except that it always splits the page int two columns.

mc3.jot

Similar to mc.jot except that it always splits the page int three columns.

mc4.jot

Similar to mc.jot except that it always splits the page int four columns.

mc5.jot

Similar to mc.jot except that it always splits the page int five columns.

mc6.jot

Similar to mc.jot except that it always splits the page int six columns.

expand_verilog_busses.jot

findcol.jot

find

hex2ascii.jot

This simple script appends a text annotation to each line in the hex dump generated by the -binary option of %I.

Example output - this is a fragment of hex dump of the test file ${JOT_RESOURCES}/l99.t, the text "80: abc ..." was added by hex2ascii.jot notice that any nonprinting characters are represented by carats ( ^ ).

2 1 1 A 20 61 62 63 20 64 65 66 20 67 68 69 20  80: abc def ghi                               
3 A 6B 6C 20 6D 6E 6F 20 70 71 72 20 73 74 75 20  jkl mno pqr stu                               
4 1 1 1 1 A 3A 30 31 32 33 34 35 36 37 38 39  vwxyz:0123456789                              
5 1 F 5F 37 39 3A 20 61 62 63 20 64 65 66 20 67  ^__79: abc def g            

updatehelp.jot

manhelp.jot

nonprinting.jot

csvprop.jot

cli.jot

path.jot

sccs.jot

sort.jot

This script uses the %b=sort command to reorder the lines in a buffer. Whereas the sort command will only sort by UTF-8 character codes (typically ASCII codes), the sort.jot script allows various alternatives.

Optional qualifiers

• -reverse - reverses the sort order.

• -filedate - the buffer is assumed to contain valid pathnames and is reordered in ascending date order

• -match=<string> - Simple alphabetical taking the substring immediately following the given string.

• -date=<dateFormatSpec1>[, <DateFormatSpec2>[, ...]] - records are parsed and datestamps extracted using the date format specifications and the records are then sorted in ascending date order. If the first specification fails to match on a line, then the next specification is tried ... etc. If none of the given specifications matches a line then the date for that line is set to the begining of unix time.

The date specification expression may contain the following elements:

• yyyy - this matches to the first four consecutive digits and is taken to be a year in the range 0 (0000) to 9999

• yy this matches to two consecutive digits in the range 0 to 99. for numbers in the range 22-to-99 these are assumed to be 20th. centuary dates and have 1900 added, for numbers in the range 0-to-21, these are assumed to be 21st. centuary years and gave 2000 added to them.

• mm this specifies a month and matches to one or two consecutive digits with a value in the range 1-to-12.

• month this matches to the englist name of months (case pattern is normally ignored) e.g. matches to january, May, JUNE etc.

• dd matches one or two consecutive digits with a value in the range 1-to-31 and is taken to be a day of the month.

• th matches to any of the following: st, nd, th - and normally follows a "dd" specification element.

• day matches the normal english words for a dates in the range 1-to-31 e.g. First, second, TWENTYSIXth

• ? A single wild character - matches to any character and is ignored.

• * Any number of wild characters - matches to any number of characters.

• other characters are taken as separators

Some examples:

• *mm/dd/yy will match dates in the north american format e.g: manu_9/21/19_for_children

• *dd.mm.yy will match dates in european format e.g: weather_forcast_21.09.19_with_tide_tables

• *:ddthmonthyyyy - will match agenda:21stMay2015

• *:ddmmyy. will match to 210919 123456210919.txt

pascal.jot

print.jot

wideprint.jot

renumber.jot

timex.jot

trace.jot

This sets the trace-vector bits (see %s=trace) symbolically. If no args are given, it displays the options (shown below) and prompts.

Trace bits 0x0001 to 0x0040 define the trigger points - i.e. they select which class of event will trigger a trace or other diagnostic response. Trace bits 0x1000 to 0x8000 define the desired action.

These can be set directly - e.g. to set a breakpoint on the start of each new command line we would say %s=trace 8002 to dump the stack we would OR with 0x1000 giving %s=trace 9002 - trace.jot sets these symbolically.

Trace arguments - trigger points:

• a - trace all commands

• l - trace at start of each new command line.

• f - trace only failed commands.

• bl - trace at start of each new block.

• m - trace at start of each new macro.

• f - trace on entry to command files.

• i - trace Ctrl+C interrupts.

Trace arguments - trace actions:

• s - dump stack at each trace point.

• p - print current line of current buffer at each trace point.

• c - show command line at each trace point.

• b - breakpoint - stop on trigger points.

So to dump the stack and breakpoint at each new line of a script or macro:

cal.jot

match_words.jot

linkdocs.jot

This script identifies links in jot-style documents (see text document preparation) and add colour tags, hashtables and sets up a mouse-event handler to allow clicking through the links.

The -bufs qualifier introduces a whitespace-separated list of buffer keys, these are the buffers to be analyzed. If -bufs list is not given, then it analyses the primary buffer ( . ) and all buffer with an alphabetical buffer key (a, b, c ...).

The -allxrefs matches references to headings in all text - by default it only matches to cross-references enclosed in backticks.

Macro_1 is defined for users without mice - first navigate the cursor to a link (or a non-link if returning) then {Esc 0}

The list of buffer keys specifies the buffers containing suitable documents, if this list is not given then linkdocs inspects each buffer in the range A-Z and processes those which appear to have doc-style section headings - see text document preparation.

A good example to try would be the jot user documents:

$ jot ${JOT_HOME}/docs/jot_qr.txt -in="%it=jot_tech; %ic=jot_coms; \

%iu=jot_ug; %iw=jot_examples; %r=linkdocs -bufs=. c t u w;"

The file images are displayed normally except that links are highlighted in green (unresolved links are highlighted in red). Clicking the left button with the mouse over over a green link will switch context to that section.

The linkdocs script also checks for obvious errors such as duplicated headings and unresolved references. If any are detected, the script displays these in buffer ( ; ) and invites the user to hit return to continue.

See also qr.jot

time_trial.jot

$ jot -in="%r=time_trial [ -tasks <taskSpec>]

iconv.jot

$ jot <pathname> -in=%r=iconv

See also practicalities of unicode etc. and jot

bookings.jot

$ jot ${JOT_RESOURCES}/resources.txt -in="%r=bookings -mail=${JOT_RESOURCES}/mail -resource=The House"

The bookings system also has a simple Email reader. Although this lacks even the ability to send emails, it can still be useful because incoming messages are integrated into the bookings system. It is assumed that most users will be using a modern webmail mailer based on a remote imap server, bookings.jot uses a local POP mail file. POP is a simple plain-text file containing mail messages. In most cases this will be copied from the remote imap server using a mail-retrieval agent (MRA) such as fetchmail. Messages are then assembled in a POP mail file using a mail delivery agent (MDA) such as procmail. See http://dev.mutt.org/trac/wiki/MailConcept for a basic description of how this works and http://www.andrews-corner.org/mutt.html for a description of how to set up your MRA and MDA.

Buttons and Menus

Mouse and keyboard actions:

xword.jot

The words and phrases are read from the on-line Roget's (see thes.jot), these are munged into a database that's saved as xword_db.txt in your JOT_RESOURCES area. The xword_db.txt file is designed for speedy searching, altough takes a few moments to create, subsequent calls take no time to read the database.

The query syntax is

<n> <c1>=<l1>[<l2>[<l3>...]]] [<c2>=<l1>[<l2>[<l3>...]]]...

where

• n is the number of characters in the word or phrase you're looking for.

• c1 denotes the character number of the first character in the first query element.

• l1 is the first letter of a substring beginning at c1.

• l2, l3 are the letters immediately after l1.

• Any number of query elements are allowed in any order.

• Any single character may be replaced by the wildcard character '?'.

Queries are entered using macro 4, defined by xword and attached to {KP_4}. Suppose we're looking for a 6 letter word with the 3rd. letter t and the 5th letter e - then any of these queries would identify the same set of matching words:

Other jot scripts

• ascii.jot - lists ASCII codes (UTF 0-255) in the @ buffer.

• awk.jot - Sets up macros 1 and 2 for editing awk command scripts.

• bcpl.jot - Sets up macros 1 and 2 for editing bcpl source code.

• bcplc.jot - converts bcpl source code to c.

• calendar.jot - derived from bookings.jot

• cdl.jot - an early attempt at parsing cdl for big_file.jot - superseded by the -cdl qualifier to big_file.jot

• compare.jot - an early version of comp.jot

• countrep.jot - counts repeated occurrences of each line in the buffer.

• curses_keys_6_0_20160213.jot - keymap for curses version v6.0.20160213

• curses_keys_6_1_20181013.jot - similar to above.

• curses_keys_6_1_20190803.jot - similar to above.

• curses_keys_6_2_20200212.jot - similar to above.

• curses_keys_chrome.jot - similar to above.

• curses_keys_xterm-256color.jot - similar to above.

• curses_keys_xterm-jot.jot - similar to above.

• curses_keys_xterm.jot - similar to above.

• cuthelp.jot - copies from the help buffer.

• dc.jot - sets up for navigating dc_shell scripts.

• diary.jot - a project started but later abandoned in support of iCalendar files.

• dic_indexed.jot - an early version if dic.jot

• edifhier.jot - A hierarchical search tool for edif netlists.

• edifinst.jot - Finds an instance in a netlist from an pt_shell-style expanded instance name.

• epic.jot - support for epic/pathmill netlists.

• epic_tidy.jot - similar to above.

• epichier.jot - similar to above.

• epicman.jot - similar to above.

• epicnet.jot - similar to above.

• epicpath.jot - similar to above.

• epicpred.jot - similar to above.

• error_search.jot - following a monkey_test.jot failure - this boils the failing script down the the few lines that triggered the failure.

• files.jot - Searches all valid buffers for filenames - generates report in buffer '@

• find.jot - Searches filing system for files matching pathname.

• findfun.jot - search a bcpl source file for the nominated function.

• fold2txt.jot - extracts a text file from a jot help page.

• frame2txt.jot - extracts a text file from a framemaker document.

• gdb.jot - an early version of ide.jot

• get_dos.jot - An early version of get.jot, from the time when get.jot did not work in windowsland.

• grep_index.jot - an early attempt at extracting index files for big_file.jot

• help.jot - Toolbox for touching up help files.

• helpin.jot - Searches entries in or below current help entry.

• helpmap.jot - Creates a map of the current help entries in the help buffer.

• hot_keys.jot - Defines hot-key keycodes for users with no function keys..

• infohelp.jot - Converts an info document to help format.

• intexrno.jot - converts a .tex file to runoff format.

• iview2hl.jot - Converts a the .doc derived from ps2doc of an iview document to help format.

• jot_old.jot - an old development version of jot.jot

• jothelp.jot - Lists first comment line of every jot command file in JOT_HOME/coms directory.

• kill.jot - kills the current (jot) process.

• latexrno.jot - converts a latex-format document to intex.

• makeconf.jot - Inserts configuration statements in hierarchical VHDL from synopsys.

• makeman.jot - prettifies the output of a unix man query.

• man2help.jot - converts a man page to a jot help page - an early version of manhelp.jot.

• mans.jot - something to do with construction of bcpl MANIFEST declarations.

• maphelp.jot - Generates a map of the help entries.

• mcpage.jot - multi-columns using Page (CTRL+L) marks to identify pages, the original text must *not* contain tabs.

• mif.jot - sets up editor for navigating framemaker mif files.

• mif2txt.jot - extracts plaintext from framemaaker mif files.

• monkey_test.jot - part of the jot test suite - generates files containing sequences of meaningless but valid commands which can be run to see if it crashes.

• multi_sccs.jot - applies an sccs command to a list of file pathnames.

• multifind.jot - superseded by the proximity function ProximityLines.

• near.jot - similar to multifind.jo6

• pads_setup.jot - setup editor for navigating pads-tool source files.

• pause.jot - Holds up execution until user types "go" (used to allow adjustment of wineconsole sizes etc.).

• pic.jot - sets up editor for line drawing - superseded by line-drawing functions

• pop_mail.jot - Transforms users mail file into folded text in the help area.

• ps2txt.jot - uses ghostscript to extract plain text from a postscript file - probably superseded by pdf2txt.jot

• rnointex.jot - converts a DEC runoff document to latex-like source.

• rtf2txt.jot - translates rtf to plain-text document

• search_html.jot - Runs jot proximity-matching functions on a html archive.

• showbuff.jot - Lists contents of all buffers in current jot session.

• spell.jot - superseded by SpellcheckDocument, SpellcheckSection etc.

• synopsys.jot - Tidies output of ps2doc script.

• tabhere.jot - Command file to resolve first tab in a line at current column.

• tags_index.jot - superseded by ctags.jot, the ctags-generated tags-index file is in the primary buffer, reads files as requested by user queries.

• test.jot - part of the jot test suite

• test_all.jot - part of the jot test suite

• test_visual.jot - part of the jot test suite

• tika2txt.jot - Probably superseded by pdf2txt - Munges the output of Apache Tika to a doc.jot-compatible form of plaintext.

• time_trial.jot - runs a bunch of tasks past various editors see text-editor evaluation and comparison

• transpose.jot - transposes a block of text around the leading diagonal.

• txt2doc.jot - Copies .txt text in current buffer to .doc (MS-Word) format using libroffice.

• txt2fram.jot - converts a structured text file to framemaker format.

• txt2mif.jot - converts a structured text file to framemaker MIF format.

• txt2tex.jot - Translates document in plain text (see doc.jot) to simple latex source.

• txt2wiki.jot - Turns current doc-style document into a wiki page.

• uc_graph.jot - similar to uc_basic.jot but for line-drawing characters.

• uc_math.jot - similar to uc_basic.jot but for mathematical characters.

• unhelp.jot - Removes a folded help file from the help buffer.

• verifyall.jot - Verifies consistency of all active buffers (except $ and ; ) using %q=verify.

• wherehelp.jot - Shows current location in help tree.

• xget.jot - an old development version of get.jot