Configuration

You can configure a small range of settings relevant for the processing. This is done in a JSON-formatted file.

You give the location of the config file in the argument --config-file. The script will automatically look for a config file with the name ~/.samewords.json, so if you put it there, you won’t have to specify the command line argument every time you call the script. That can be very handy if you often need to use the same configuration.

The configuration file recognizes the following parameters:

  • exclude_macros
  • ellipsis_patterns
  • sensitive_context_match
  • context_distance
  • punctuation

JSON requires backslashes to be escaped if you want to preserved them in the string. You do that with another backslash, so \\ will result in a single backslash. You must remember this when noting TeX strings or regular expressions that contain backslashes.

Example file

A complete configuration file could contain the following content:

{
  "ellipsis_patterns": [
    "--",
    "–"
  ],
  "exclude_macros": [
    "\\excludedMacro"
  ]
}

Parameters

exclude_macros

You might want to define some macros which are entirely ignored in the comparison of text segments. That will typically be macros that do not contain text content.

For example, you might use a custom macro called \msbreak{} to indicate a pagebreak in your edition. The content of that is not printed in the text, but in the margin. So you don’t want the comparison to figure in the content of this macro. Take this example phrase:

I\msbreak{23v} know that \edtext{I know}{\Afootnote{I don't know B}}
nothing.

Since the content of (almost) all macros is included by default, this would give the comparison of the phrase I know (\edtext content) with I23v know that (context). It will not match, and hence not annotate the phrase.

If we add the macro to the excluded_macros field in a settings file and pass that to the script, \msbreak will be ignored in processing, and we will get a comparison between I know (\edtext content) with I know that (context). This will match and hence correctly annotate the phrase.

Another example: The script searches for words or phrases identical to those in the \edtext{}{} macros to identify possible conflicts. By default the content of practically all macros are included in this comparison.

Take this passage:

\edtext{Sortes\test{1}}{\Afootnote{Socrates B}} dicit: Sortes\test{2} probus

Will result in a search for “Sortes1” in the string “dicit Sortes2 probus”, which will not succeed.

On the other hand, this passage:

\edtext{Sortes\test{1}}{\Afootnote{Socrates B}} dicit: Sortes\test{1} probus

Will result in a search for “Sortes1” in the string “dicit Sortes1 probus”, which will succeed and therefore annotate the instances.

If you add \test to the excluded_macros field, both examples above will compare “Sortes” with “Sortes” and hence give a positive match.

ellipsis_patterns

This key contains a list of patterns that should be included when matching for ellipsis symbols in \lemma{}. These are used in a regular expression match, so any valid python regular expression will work.

Say you use “–” and “…” to indicate ellipsis. Actually, you ought to write the dotted ellipsis with \dots{} in LaTeX, but if you insist, you could give the key the following list (but you shouldn’t, really. Use \dots{}):

{
  "ellipsis_patterns": [
    "\\.\\.\\.",
    "-+"
  ]
}

This looks complicated, but don’t worry. The “…” is matched with a regex pattern, which requires us to escape the regular “.” – that would normally look like this \.\.\.. But since we also need to escape the backslashes, they are doubly escaped.

The second is a lot simpler, it is just a regex that will match one or more regular dashes in your text. Note that this comes with some danger as it will match if your lemma contains a single dash, even though you might not have thought of it as an “ellipsis”-dash. In these cases, its better to be explicit and either use double dashes (--) or real unicode en-dashes (–). It is also typographically much better.

Another example of a regex match pattern would be to match for the thin space command in LaTeX, which is \,, which produces a space of just 0.16667em. A comma is a meta-character in regex, so it would need escaped, which would look like \\,, but the backslash is also a meta-character, so that needs escaping too. This means that to match the literal expression \, the regex would look like this: \\\\,. So if we wanted to match the LaTeX expression \,-\, (thin space, a dash, and another thin space), we would write the following regex: \\\\,-\\\\,. But as we would probably want to match any length of dashes, it could be improved to \\\\,-+\\\\,.

sensitive_context_match

The value of the settings variable sensitive_proximity_match determines whether the search for matches in the proximity is case sensitive. By default it is case insensitive, but if the value is set to True, it will be case sensitive.

In JSON:

{
  "sensitive_context_match": true
}

That would mean that the search for “an” in the context string “An example” would not match. This is a sensible setting when lemma words are not lower cased in the critical apparatus.

context_distance

This determines the amount of words that will be compared with a match phrase at either side of an \edtext{}{} entry. A normal length line rarely contains more than 15 words, so the default of 20 should often be enough. If a layout with every long lines is used, it may be necessary to increase it, while it may make sense to reduce the distance if maybe a two column setup is used. But a bit too many \sameword{} annotations really does no harm.

punctuation

Punctuation may be critical when adjacent to potential sameword matches. If exotic punctuation is used it might not automatically be separated from the rest of the word. By default all characters that are not word characters, punctuation or \ { or } is considered part of a word.

Currently the following groups of characters are considered punctuation:

If you use characters as punctuation that are not in any of these groups, you can add them manually via the punctuation field. It can either be just the raw characters, regular expression statements or Unicode codepoints (e.g. \u0101 = ā) or ranges of Unicode codepoints (\u0100—\u017F = the Latin Extended A block). The \u tells Python that we are dealing with escaped Unicode codepoints.

If you feel bold you could of course edit the punctuation list in the settings file.

multiword

In cases where an \edtext{}{} macro contains a phrase, and there is a phrase of that match in the context, it is usually possible to either annotate each words of the phrase separately or all in one \sameword{} macro.

Default setting is False, meaning that each word is annotated separately.

For example: > A word with edtext{a word}{Afootnote{another D}} after it.

If that is annotated with multiple \sameword{} macros, it will look like this:

\sameword{A} \sameword{word} with \edtext{\sameword[1]{a}
\sameword[1]{word}}{\Afootnote{another D}} after it.

This will result in an apparatus note with the numbering “A² word²”. If it is annotated with a single “multiword” annotation, it looks like this:

\sameword{A word} with \edtext{\sameword[1]{a word}}{\Afootnote{another D}}
after it.

This will result in an apparatus note withe the numbering “A word²”.

Which of these solutions is prefered usually a question of the individual taste and intuition of the editor.

In some cases this may however lead to problems: When multiple levels of \edtext{}{} annotations are nested and are in need of disambiguation, this might however lead to unexpected results where the apparatus note occurs as if it were annotated with the words separately (e.g. “A² word²”). Furthermore, there is a risk that these “multiword” annotations yield a result where the beginning or end of a \edtext{}{} overlaps with that of a \sameword{}. This is invalid LaTeX and will therefore not compile. The separate sameword annotations will never give this problem, so it is prefered as default with the option of the editor to enable the slightly more risky multiword approach.