snify

snify

snify has an shell-based interface like an old ispell and just steps through a set of sTeX files and suggests term reference annotations based on the verbalizations in the SMGloM. The user can select annotations by number, and snify inserts the appropriate annotation in the sTeX source, together with the respective imports (if necessary and consistent). A couple of other keyboard-based interactions allow to fine-tune the workflow and/or skip/refine annotations.

snify is a good productivity tool for bulk annotation of existing LaTeX source files. It works well, if the material covered is backed by a well-developed domain model (for the respective language).

Basic usage

You can call snify and pass a list of files to be annotated. Example:

stextools snify path/to/file1.tex path/to/file2.tex

On the first run, snify will scan all of MathHub for verbalizations, symbols, etc. This may take a while. Subsequent runs will be faster, as snify caches the results.

If everything works as expected, you will see the annotation prompt, similar to the following:

You can now enter commands. If you want to annotate the highlighted word, you can enter the number of the annotation you want to use and press Return. If you want to skip the word, you can enter s to skip it. snify will then move on to the next candidate for annotation.

There are many more commands available. The next section gives a more detailed overview of the available commands.

Commands

The list if all commands in snify can be invoked at any time by typing h to the prompt. We give more details below.

High-level commands

• [h]elp Displays a command overview similar to this one.
• [q]uit Quits the program. You will get asked if you want to resume the session at a later point. This will save the current state of your annotation progress. Next time you start snify, you will get asked if you want to resume an existing session.
• [X] Exit file Stops annotating the file and and continues with the next one.
• [u]ndo Undoes the most recent modification.
• [uu] redo ("undo undo") Redoes the most recently undone modification.
• [R]escan Rescans all of MathHub. If files have changed, it will process them to update the verbalization database. This might be useful if you do a git pull during a snify session (whenever you start snify, it will do an automatic rescan).

Annotation commands

• [𝑖] annotate with 𝑖 Annotates the current selection with option number 𝑖. If the symbol is not in scope, a dialog will pop-up with different import options.
• [l]ookup a symbol Lookup a symbol for annotation. This is helpful if the correct symbol is not in the suggestions. It requires https://junegunn.github.io/fzf/ for fuzzy search (if fzf is not available, installation instructions will be displayed).
• [x𝑖] explain 𝑖 Provides more information about suggested symbol no. 𝑖. At the moment, this is restricted to explaining why it was suggested, i.e. where a matching verbalization was found. This may be useful if a symbol is suggested due to a wrong annotation in a different file. In the future, we plan to also explain how the symbol was imported (if it is in the current scope as indicated by the green checkmark). This could help with "trimming the import tree" if a symbol is unexpectedly in scope.

Selection modification

Sometimes, the selected range in the document is not precisely what you had in mind. The following commands can modify the selected range.

• [p]revious token should be included Extends the selection to include the previous token.
• [P] exclude first selected token Opposite of [p]. Excludes the first token from the selection.
• [n]ext token should be included Extends the selection to include the next token.
• [N] exclude last selected token Opposite of [n]. Excludes the last token from the selection.

Skipping

• [s]kip once Skips the current selection and continues with the next possible annotation.
• [s!]kip until end of file snify will not propose any occurrences of the selected phrase in this file anymore (until the end of the session).
• [s!!]kip until end of session snify will not propose any occurrences of the selected phrase in this session.
• [i]gnore the selected word forever The word gets put into the (language-specific) ignore list and will never be proposed for annotation again, unless removed from that list. This is useful, if you are sure you never never never want to annotate this word. This includes all the tiny stop words like "and", "or", and "not", but also any other word you are sure has no technical meaning for you. You can find the ignore list at ~/.config/stextools/srify_ignore.*.txt.
• [S]kip word in this file forever snify will never propose the word again in the current context, i.e. in this file. The end of a file contains a comment starting with % srskip that lists all words that should be skipped by snify.
• [SS]kip stem (i.e. all words with the same stem) in this file forever Like [S], but snify will also skip other forms of the word. For example, if you apply it to the word documents, snify will also not propose document or documenting or documentation for annotation.

Focussing

The idea of focussing in snify is to reduce the mental overhead of seeing a different list of candidate symbols for every annotation. By focussing on a particular word (or rather, word stem), snify will effectively fix the list of candidate symbols and ignore all other words. Afterwards, snify will go back to the place where you started focussing and continue as usual.

• [f]ocus on stem snify will focus on the word stem until the end of the file.
• [f!]ocus on stem in all remaining files snify will focus on the word stem for all remaining files in the session.
• [f!!]ocus on stem in all files snify will focus on the word stem in all files in MathHub.

Viewing and editing files

• [r]eplace Asks you to enter a new string that should replace the selected range of the document. This is useful to fix typos or poor wording. For more powerful editing capabilities, you should consider [e].
• [v]iew file Snify displays the current file in the pager.
• [v𝑖] view document for 𝑖 Displays the document that introduces symbol no. 𝑖.
• [e]dit file Opens the current file in an editor. The editor can be specified in the config file. If no editor is specified, snify will use the EDITOR environment variable, and defaults to nano.
• [e𝑖] edit document for 𝑖 Opens the document that introduces symbol no. 𝑖 in an editor (as [e]).
• [ee]dit file with editor 2 Like [e], but using editor 2 from the config file. A typical setup is to use a command line editor (vim/emacs/nano/...) a editor 1, and VSCode with the sTeX plugin as editor 2.
• [ee𝑖] edit document for 𝑖 with editor 2 Like [e𝑖], but with editor 2.

Configuration and command line options

Filtering and ignoring archives

If you only want annotations from certain archives, you can specify them with --filter:

# only use symbols from the SMGloM
stextools snify --filter 'smglom/*' path/to/file.tex
# you can use comma-separated lists
stextools snify --filter 'smglom/sets,smglom/mv' path/to/file.tex

Note: * is a wild card. If you do not use single quotes, you may need to escape the * with a backslash.

You can also ignore certain archives with --ignore (also using wildcards):

stextools snify --ignore 'smglom/experimental' path/to/file.tex

You can also combine --filter and --ignore:

stextools snify --filter 'smglom/*' --ignore 'smglom/experimental' path/to/file.tex

To make these settings permanent, you can add them to your ~/.config/stextools/config file:

[stextools.snify]
filter = smglom/*
ignore = smglom/experimental

Other configuration options

You can also set the following options in your ~/.config/stextools/config file:

[stextools.snify]
# number of lines to show before and after the current line
context-lines=3
# editor to use for editing files
editor=vim
# alternative editor to use for editing files
editor2=code