Amanuensis

What is Amanuensis?

Amanuensis is a Chrome extension that facilitates taking notes on phrases you find as you browse the web. It captures the phrase, its context — the surrounding text — the time you recorded it, the URL, and any tags and notes, either on the phrase generally or particular citations. You can link notes together, edit them, merge them, search for them, export them, or import them from an export.

In principal, you can use Amanuensis to take any sort of note. It was designed, however, with language learning in mind.

Use

The general pattern of usage: You're reading an article on something that interests you. You find a phrase of particular interest. If you're using Amanuensis to learn a language, it's an unfamiliar phrase or idiom. If you're using it as a research tool, it's a fact, observation, or data point. You highlight the phrase and click the Amanuensis icon or press ctrl-shift-A to start a note.If you are studying a language, you will need some other source to provide definitions, part of speech, etc. I find wiktionary is a great resource. It provides you considerably more and more trustworthy information than you get from Google Translate, for instance. You add relevant information, perhaps some tags; you look for similar or related notes and link them. You save it.

Later, you wish to continue with an article. Say it's the last article. You click the icon or press ctrl-shift-A and open Amanuensis. You search, sorting for the most recently updated note. You click on the first note, then click on the URL. This takes you to the page, highlighting the phrase. You click on the search tab and see a list of all the notes you took on the page.

Philosophy

When people learn languages in a classroom, most context is removed. Words are learned in lists and are taught when the textbook or professor deems best, not when the student is interested. But learning facts unconnected to your interests is inefficient. If you don't already want to know the answer, the answer doesn't sink in.

The idea with Amanuensis is that you find something which is inherently interesting to you and you try to read it. When you come across unfamiliar words, you will be more likely to remember them, because you want to know what they mean.

When you come across the words again, and look them up again, as one does, you will be reminded of the last context in which you saw the word. The words will all hang together in a web of meaning and association.

Future

I have written Amanuensis because it is the language learning tool I want. I am sharing it because, having written it, it costs me nothing to do so.

It is free. It will remain free. I have no plans to make money off of it.

However, for the same reason I cannot guarantee it will be supported and developed forever. I will keep working on it as long as I have use for it. Since I love learning languages, I will keep at it for decades, as long as I keep my health. But Amanuensis has a bus number of one. If support drops off, something bad has happened. Still, I imagine it will keep working, just without additional bells and whistles.

Installation

To install Amanuensis, go to its page in the chrome web store and click the "Add to Chrome" button.

Amanuensis is open source. If you are feeling adventurous you can clone the repository, run the compile script, and load the unpacked extension into chrome.

The respository is at https://github.com/dfhoughton/amanuensis-2.Why "amanuensis-2"? Because there was an earlier version of this extension that worked with an earlier version of the Chrome extension spec. That version reached end of life and the extension died. This is a thorough rewrite. It is somewhat less ambitious but uses more modern tech.

To run the build script, you must have installed node. Then, in a terminal, cd to the install directory and run npm run release-build.

Documentation

Design Constraints

Amanuensis, like many extensions, lives in a little box in the top left corner of the screen. It needs to stay out of the way of the text you're reading, so everything needs to compact, minimal, abbreviated. We do what we can with tooltips and icons with familiar meanings, but if we had more real estate on the screen we would have made other choices.

Note

Notes are the basic unit of Amanuensis. Their creation is its central purpose. They collect information about citations. When you highlight a bit of text and invoke Amanuensis, it begins a new note for you.

The various parts of a note are enumerated in the figure.

lemma

A note's lemma is the canonical form of its various citations. If you are using Amanuensis to study English, the you would probably consider the lemma of cats, cat's, and cat to be cat.

save icon

Click this to save the note. When you begin a note by highlighting some text and opening Amanuensis, it is not yet saved.

language

Amanuensis uses a Chrome API to guess the language of a particular citation from its content and context. There are many more languages than Google attempts to recognize, however, and it is not always correct in its guess. The language Google guesses is represented as a "locale", a two-letter identifier. You can see the locale for Finnish, "fi", as a blue badge overlay on the language selector in the figure.

To use this guess, you must specify in the configuration tab which languages you are interested in. Amanuensis will attempt to map Google's guess onto these languages. The language selector allows you to edit this guess when Amanuensis gets it wrong.

lemma note

This is where you writen things that are true for all uses of the phrase. Typically, this is the phrase's definition.

tags

Tags represent frequently occurring, important bits of information. If you hover over a tag, the information it represents will appear as a tooltip. Click in this element to add a tag.

links

Links connect one note to another. In the example shown in the figure, the motivation for linking the two notes was that they both contain vallat. You might link notes because they are synonyms or antonyms, or for any reason whatsoever.

Clicking on a link takes you to the note linked.

Links are always bidirectional. If you link a to b, b will also be linked to a.

Links are created within the dictionary. You will find each entry has a link icon. This looks like a link in a chain. If you click it, you will create a link to the current note.

citations

Every note has at least one citation. A citation is a use of the note's lemma in context. Quite likely until you have been using Amanuensis for some time each note will have just the one citation. If you have a memory like a steel trap, you will only ever have the one. But if you have an ordinary memory, or you find many interesting citations, this number will grow.

If you have more than one citation, as in the figure, you may pick a "canonical" one to display by default when browsing notes. You may also delete citations. You cannot delete the last citation.

You only have these options for the currently displayed citation. Click on another to display it. 5 in the figure is a non-selected citation. For non-selected citations only the form, any note for that citation, and the date it was recorded are displayed.

citation context

The citation context is shown for the displayed citation. Its parts are enumerated in the figure. These are the title (7), the date the citation was recorded (8), the URL (9), and the phrase itself and its surrounding text (10).

The title, date, and URL are displayed in abbreviation. If you hover over them their full content will appear in a tooltip. In the case of the date, this tooltip shows the time of day that the citation was recorded.

If you click on the URL, Chrome will navigate to this page, where it will attempt to highlight the phrase cited and bring it into view. If the page has changed since you recorded the citation, highighting the original phrase in its original context may not be possible.

citation note

Each citation has its own note in which you can record anything interesting about the particular citation. This is (11) in the figure.

citation tags

Every citation also may have its own tags. This is (12) in the figure.

Dictionary

The dictionary is where one may browse notes. As shown in the figure, there are three manners in which one may browse the dictionary (1): ad hoc search, by similarity to the current citation, and by page (URL). Every manner of search has a form (2). Every search results in zero or more notes (3).

Each note in turn is represented by its lemma (4), its lemma note (5), its language (6), and some actions one may take: merge the note with the current note — the note currently displayed in the note tab — (7), link the note to the current note (8), or delete the note (9).

If you click on a note in the dictionary, this will take you to the note tab, where the note will be displayed. It is now the current note, the note to which other notes displayed in the dictionary may be merged or linked.

search results

Every search produces zero or more search results. These are basically abbreviated notes. One may click on them to view them in full. See the figure for a sample search result.

In addition to the lemma, lemma note, and locale, each results provides a number of actions one may take: merge this note with the note currently displayed in the note tab, link it to that note, or delete it from the database. The more destructive of these actions, merging and deletion, require confirmation and, in the case of mergin, possible editing to complete.

search

The search tab labeled simply "search" is the most flexible, and consequently the most complex. See the figure.

There are two areas that allow you to search text, the lemma area and the free text area. The first searches only lemmas. The second searches lemmas, notes, citations — the phrases themselves and the context before and after — and citation notes.

Both text searches allow you to specify whether it is a whole word search (5), whether it is a fuzzy search (6), and whether it is case-insensitive (7).

A "whole word" search is a search where the first and last letters in the search field should be the first and last letters in words matched.

A "fuzzy" search is one where letters may intervene between characters matched. A fuzzy search for era would also match terra and tertiary, because in all three words the letters e, r, and a occur in that order.

A "case-insensitive" search will match letters regardless of their case. A case-insensitive search for cat would match CAT. A case-insensitive fuzzy search for cat would match A Canticle for Leibowitz.

Tag searches look for notes where a particular tag occurs in the note's lemma or citation tags.

Language searches search for notes with particular locales.

By default the search results are sorted by lemma. Sometimes it helps to apply a different sort order. This is the purpose of the icon showing three horizontal bars of descending size (the figure). I frequently use the last sort order, by time of last update descending, to find where I last left off.

similar phrase

The same phrase may have different forms — cat and cats, for example. It may appear as part of another word — cat and catfish. To facilitate linking a note to related notes, or to merge different citations into the same note, Amanuensis has the similar phrase search (the figure).

When you highlight some text and invoke Amanuensis, it creates a provisional note, and searches for similar notes within the language inferred by Chrome. This facilitates merging the citation highlighted with an existing note immediately. The search is over all lemmas and citations. Because of this pattern of use, the similar phrase search form has only two fields: lemma and language.

Amanuensis must apply a string similarity metric to do a phrase similarity search. There are many of these with different virtues and flaws. Some work better than others for a given language. For this reason, the simularity metric is configurable.

One could in principle rank all notes for their similarity to a given phrase. In practice, however, there is little value in looking too far down the list. For this reason, the maximum number of results displayed in a similarity search is configurable as well.

citations on page

The form to find citations on a given page is the simplest (the figure). The "page" in this case is just the URL, so the only field in the search form contains a URL. The search performed is a search for notes which have some citation whose URL starts with the string in the search form. This means you can use this form to search for all citations on a particular site, not just a particular page.

Tags

Tags consist of a short identifier, a visually distinctive style, and some content. They appear in Amanuensis as colored bubbles. When you hover over a tag, the content appears as tooltip text. Identifiers must be unique — you can have only one tag identified as "M".

Tags serve two functions:

• they concisely encapsulate recurring information
• they facilitate the discovery of similar things

The tag tab (the figure) is where you create, edit, and delete tags. If you click on a tag in the tag tab Amanuensis will perform a search for you of all notes bearing this tag.

If you wish to create a new category of tags, you click the plus icon (1). This allows you to create all the elements of your tag from scratch (the figure). So long as this tag is distinctive in its foreground or background color, it will be the first member of a new category of tags.

More commonly you will want to create a tag in an existing category. Perhaps you have a category of tags that indicate part of speech — noun, verb, adjective, etc. — and you wish to add a tag for prepositions. Perhaps you nave a category of tags that represent noun class — masculine versus feminine, animate versus inanimate, abstract versus concrete — and you wish to add a new class. The class is represented stylistically. You part of speech class might be purple text on a yellow background. Your noun class might be red on pink. To create a new tag in an existing class, you click the duplicate icon (6) and then add the tag, text, and perhaps locales it pertains to.

When tags are listed, they are sorted primarily by category, in the order in which the category was created, and secondarily by identifer in alphabetical order.

tag locales

Sometimes a particular tag will be useful for all languages. All languages have nouns and verbs, for instance, so whenever you are creating a note, whatever the language, you may want to be able to tag a lemma as a noun or a verb.

Some languages have particular categories which are very important to them but mean nothing in other languages. Uralic languages, for example, have an elative case. A noun in the elative case is describing, roughly, motion out of a space: talosta — "out of the house" in Finnish. If you create an elative tag for Finnish, it's probably of no use to you for notes about Mandarin.

To reduce tag clutter, therefore, Amanuensis allows you to specify the locales for which a tag is relevant. If you provide no locales for a tag, it is available for all notes.

You only see a tag's locales listed explicitly in the tags tab. Elsewhere they serve only to hide irrelevant tags.

In the tags tab, if a tag has a single locale, that locale is shown in the locales bubble. If it has more than one, the bubble contains an ellipsis. If you hove over a tag's locale bubble in the tags tab, all its locales will appear in a tooltip. See (4) in the figure.

Configuration

Amanuensis does not yet have many configurable parameters. Those that there are, together with some database actions, can be found on the configuration tab (the figure).

The configuration tab is also where one can find the link to this documentation — (1) in the figure — something which you likely already know, since it's likely what has brought you to be reading this text.

string distance metrics

If you capture a citation of cars, you probably don't want it to live in a separate note from a note on car, if any. You can add the citation to the existing car by finding the note via search and then clicking the merge button.

But how do you find the car note? Amanuensis provides a special variety of search for this purpose: the similarity search. Similarity searches look for notes whose lemma or citations are particularly similar to a given phrase. For this they need a definition of similarity. These are the string distance metrics.

The default string distance metric is called Jaro-Winkler. It is fast and considers changes to the beginning of words to be more important than changes to the end, so cars will be found to be more similar than scar to car. This is just what you want for suffixing languages like English, where grammatical markers tend to go on the end of words. If you are working with a prefixing language like Swahili, where watu is a form of the word mtu, this is not so good.

If you find the similar words found by similarity search are not all that similar, and in particular if you know that there's a similar note but it's not finding it, you could try a different string distance metric. Perhaps another will work better.

max similar phrases

In a similarity search you are unlikely to find any interesting similar phrases after the first few notes, so rather than display all the notes in the dictionary for the given language sorted by similarity Amanuensis just shows the few most similar ones. This parameter controls how many are shown.

database actions

Amanuensis saves all its data on your machine in a database. It doesn't call home to a central server. It doesn't store data in the cloud.

This design provides simplicity and privacy. It also potentially locks you into one device and prevents sharing notes with others. The database actions provide some workarounds if you want a bit of both worlds.

clear

The clear action — (4) in the figure — allows you to reset Amanuensis to "factory settings". Once done one cannot restore the database unless you've exported the data, so a confirmation modal will intervene and ask whether you really mean to do this before your data is erased forever.

export

The export database action — (5) in the figure — dumps the entire contents of your Amanuensis database into a JSON file.

Having exported your database to a file, you can now save a backup copy, install Amanuensis on another machine and restore your database there, or share your notes with someone else.

If you want to use your notes for some other purpose, you can write a script in some programming language that will parse the exported JSON allow you to manipulate, transform, or extract it.

import

The import database action — (6) in the figure — allows you to add the notes exported from a different instance of Amanuensis into your current one.

The import process takes some pains to import notes without clobbering existing notes. This may result in duplicate notes and tags requiring merging or deletion.

languages

You do not need to use Amanuensis to study languages. You can use it simply as a note taking tool. Amanuensis begins configured to use only one language, the "unknown" language — (8) in the figure. You do not need to configure it further. If you create a note, it will begin and remain assigned to the unkown language.

If you do wish to study a particular language you need to tell Amanuensis which languages you wish to study so that it can attempt to categorize your notes correctly. This will ensure that similar phrases are sought only within the correct language and that only those tags appropriate to the language are offered.

To add a language, click the add-language icon — (7) in the figure. This will open a modal where you can select a language with an ISO-639-1 language code. At this time, Amanuensis does not provide a mechanism to add a language which lacks an ISO-639-1 code. There are many languages that lack such a code — Yinjibarndi, for example, or Sumerian. Amanuensis does not yet provide a means to add these for study. If I am made aware of a demand for this, I this may hasten my adding it. I may add it regardless of whether anyone demands it. I simply have not yet.

When you create a note, Chrome uses the phrase selected and the surrounding text to guess its language. It may guess wrong, or be unable to identify the language at all, assigning it the unknown language. You can correct this using the language picker widget — (3) in the figure. Amanuensis will record this discrepancy and use it to improve its language assignment for subsequent notes. In (9) in the figure you can see an instance of this: 4 notes on Finnish were guessed by Chrome to contain Estonian (et).

Acknowledgements

Though so far I'm the only person who has committed code to Amanuensis, others have helped bring it to its current state and deserve acknowledgement

Martha coached me through some confusion as I was learning React while writing this code.

Dedication

Amanuensis, like most of my projects, is dedicated to my son Jude, who died on February 1st, 2023. He was a better programmer and a better, kinder, more interesting person than me. I was looking forward to being surprised and amazed by him as he went out into the world. He shared repositories in github under the name TurkeyMcMac.

In elementary school, Jude wrote the story of Oofla the Gloofoo (the figure). He did this to amuse himself and his friends and siblings. Each day they would gather around to watch the latest installment unspool as he wrote. On the last page of the exercise book there was an "about the author" section — some lines for text and a box for a picture. As was his way — Jude never spoke about himself — Jude omitted the text. For a picture he provided an image of Oofla. So I have always thought of Oofla as an avatar of Jude. Because I wish he were still around, I used Oofla as Amanuensis's logo. Amanuensis is still around if Jude isn't.

We love you and miss you, Jude.