Configuration file

Configuration file

The configuration file ~/.scdict/scdictrc.lisp uses Lisp-like syntax. It allows you to define viewers and associate them with file types and particular dictionaries as well as manage your dictionary collection by introducing aliases (so-called nicks) and creating groups of dictionaries.

Defining a viewer

In order to set a default viewer, you first define one. To do so you use the following syntax:

(defviewer <viewer-name> (<file> <page>) <format-string> <format-arguments>)

Here

• <viewer-name> is any sequence of letters (typically lowercase with hyphens as separators; in what follows such sequences are referenced to as symbols);

• <file> is a symbol standing for variable file name;

• <page> is a symbol standing for variable page number;

• <format-string> is a string delimited by double quotes possibly including sequences ~A. More generally, it can be an arbitrary Common Lisp format string. Note that inside strings literal double quotes and backslashes must be escaped with a backslash;

• <format-arguments> are several symbols (one for each ~A) used for substitution into the format string.

Example: djview4

Say, you want to use djview4 as your default DjVu viewer. A possible command to open a file at a given page would be

djview -page=<page> "<file>"

(see man djview for more options). Note that you should quote the file name as it may contain spaces. In your scdictrc.lisp you use write as follows:

(defviewer default-djvu-viewer (f p) "djview -page=~A \"~A\"" p f)

Here defviewer means that we are defining a new viewer and default-djvu-viewer is its name (you could choose another one to your liking). Next, as we mentioned, we specify two symbols f and p that will stand for the file name and page number. You could chose any two letters (identifiers) you like, but the first letter in parentheses after the viewer's name will always stand for the file name, while the second one will stand for the page. Next we see our command in the form of a format string. The string has two gaps for the page number and the file name which are both represented by ~A. After the string we supply the values to fill in the gaps in the order the gaps occur, i. e. first the page number, then the file name. Notice once again that the format string (as any string) is delimited by double quotes and you must escape literal double quotes with backslashes.

Example: mupdf

Here is another example for mupdf:

(defviewer my-favourite-pdf-viewer (file page)
  "mupdf \"~A\" ~A" file page)

Here the syntax is simpler and can be written in the form

mupdf <file> <page>

We have used the variable names file and page instead of just f and p.

Observe that you can split Lisp code between multiple lines (anyway, computer reads it by parentheses) and it it customary (though not absolutely necessary) to indent the body of a macro by two spaces. Further, observe that Lisp code is typically written in lower case with hyphens as separators (rather than e. g. underscores). Of course, a dedicated text editor makes formatting code much easier, but if you are not going to code that much, you can have pretty rc files even without it.

Setting up default viewers

Next, we want to associate our viewers with formats. The format of a dictionary is its format property and typically is "PDF" or "DJVU". To establish associations, use the following syntax:

(set-default-viewer "PDF" my-favourite-pdf-viewer)
(set-default-viewer "DJVU" default-djvu-viewer)

The magic word set-default-viewer does the trick. It is followed by the format designator and by the name of the viewer defined earlier.

Setting up viewers for specific dictionaries

Moreover, you can establish viewers for individual dictionaries using set-viewer as follows:

(defviewer djview-fullscreen (f p)
  "djview -fullscreen -page=~A \"~A\"" p f)

(set-viewer "MY-DICT" djview-fullscreen)

In this case the dictionary by nick "MY-DICT" will be opened in the fullscreen mode.

Renaming dictionaries

Dictionaries are identified by the field name of their JSON description. This means that the names should be long enough to prevent name clashes when adding new dictionaries to an existent collection. However, it is often more handy to replace long names by convenient shorter ones.

SCDICT distinguishes between three kinds of names.

The primary means to identify dictionaries is the name field of the JSON records.

A user may set up global nicks for dictionaries. A dictionary having a nick can still be referenced by the name unless the name is shadowed by another nick. However, SCDICT prefers to mention dictionaries by nicks rather than by names (e. g. when listing loaded dictionaries).

Within a group dictionaries may have local aliases (akas). These are treated in the subsection Grouping.

Typically a name may be a not-so-short string, a nick may be a more convenient designation in the context of your own dictionary collection, and an aka may be a handy one-letter shortcut for easy referring to a dictionary when switching, etc.

You set up a nick as follows:

(nick <name> <nick>)

where <name> and <nick> are strings (double-quoted, as usually).</nick></name>

Example:

(nick "A_Copious_and_Critical_Klingon-English_Lexicon" "KL-EN")

This means that the A Copious... dictionary may be further referred to as "KL-EN", and that SCDICT will generally prefer to display the latter notation. Anyway, general information about a dictionary is not its name field, but its title and description.

Grouping

If you use numerous dictionaries, it is convenient to organize them into groups. A group is a collection of dictionaries typically having a name and a description. Dictionaries belonging to a group can have one or more aliases referred to as akas; they are local to the group. It is convenient to have short akas in order to quickly switch between dictionaries during an interactive session.

A group is defined as follows:

(defgroup <name>
  (description <description>)
  (items
    (<nick> <options>)
    ...
    (<nick> <options>)))

Here <name> is the name of the group to be defined, <description> is a (double-quoted) string, <nick> is the name or the nick of a dictionary, and <options> come in pairs <option name> <option value>. Currently only option <aka> is supported, its values are strings.

Example:

(defgroup kl
  (description "Klingon dictionaries")
  (items
    ("EN-KL" aka "E")
    ("KL-EN" aka "K")
    ("KL-KL" aka "A" aka "B")))

The description and items clauses can go in an arbitrary order, the first one being optional.