deep-philology / deepreader

a highly modular, Vue.js-based framework designed for building online reading environments for deep reading of texts with rich annotations and integrated learning tools

DeepReader

DeepReader is a highly modular, Vue.js-based framework designed for building online reading environments for deep reading of texts with rich annotations and integrated learning tools.

It is particulary intended for the study of classical languages such as Ancient Greek but could be applied to any texts with rich annotations. What is here is an early prototype using the MorphGNT API and the CTS protocol but we plan to support other text services as well including EPUB.

Reading environments built with the DeepReader framework could be as simple as Kindle-like apps but the real intention is to support deep reading with integrated dictionaries, linguistic annotations, and commentaries, as well as learning tools such as vocabulary flashcards and parsing drills.

Each widget is a separate Vue.js component. We are working to make it as simple as possible to develop new widgets that interact and engage with the current passage, optionally calling out to external APIs.

We are also experimenting with Firebase for persistence. Offline use is also planned as is packaging DeepReader up as an app for mobile use.

Setup

To run DeepReader in development mode, clone this repo then:

npm install
npm run dev

Presently, there are two readers accessible at these paths:

• CTS: http://localhost:5066/#/cts
• MorphGNT: http://localhost:5066/#/morphgnt

If you hover over the reader, you'll see various pluggable widgets on the left and right. Those on the left are used to choose what passage to read, and those on the right are used to present additional information about the passage and its individual words, and to control the appearance of the passage.

You can expand or collapse any widget by clicking on its title. You can use the arrow keys on your keyboard to pagination between passages in a work.

More Background

• Short Term Plans
• A Reference Model for Capabilities of Online Readers
• Widget Framework

deepreader's Issues

note taking component

better error handling when API calls fail

one way to do this would be to have a widget-level boolean property that indicates whether the last API call errored or not. We could then style the widget based on that property (e.g. red if the API call failed)

Clicking on word multiple times creates duplicate entries

If I click on the same word multiple times in the main window, I get a new entry for each click in the word info widget.

add bookmark widget to CTS reader

introduce consistent notion of text annotations in the store and how widgets interact with them

Some text services (e.g. MorphGNT) already have annotation on words. Some widgets add extra annotations (e.g. frequency) by calling an API. While we don't have any examples yet, some widgets could add annotations via internal processing (e.g. syllabification).

These annotations are either used for display in the main panel with the text (colour, or interlinear info) or information shown in a widget when a word is selected.

We need to make sure all this works in a consistent way. This may involve considerable changes to some of the widgets. For example, frequency might (as previously discussed) be split into one that makes the API call and does the annotation in the store and one (that is perhaps more generic) that just does heatmaps on words based on a particular annotation already there (regardless of where it comes from).

I wonder if it also affects things like the Morpheus widget. When you click on a word, does it just make an API call and display the result or does it make an annotation in the store and then the display part of the widget draws from the annotation. Latter allows for more widget code re-use I suspect and is a form of caching.

This also means that a widget similar to the "word info" widget might actually just display all word-level annotations regardless of where they came from, without prior knowledge of what they are.

One thing that we might need to support all this is flags on the store as to what annotations are on the words (without having to check them all). For example, we may have a flag that says that words are annotated with frequency. Or perhaps a flag that says words are annotated with some number that could be used for a word heat map.

There's so much I've said here, we might need to break it apart into smaller steps.

switch to using universal-fetch everywhere

reading plan widget

list widgets

for each widget, explain what it does, what external services it uses, what assumptions it makes about the store, what assumptions it makes about other widgets, etc.

clicking on text formatting sizes in CTS reader causes text to disappear

(on unify-passage branch)

GNT lexicons - Abbott-Smith, Mounce?

I would like Abbott-Smith and Mounce lexicons in the MorphGNT reader.

discuss how to do automated testing

particularly to make sure PRs don't regress anything

frequency toggle should not incur API hit when removing

Presently, when frequency is turned off, the widget will make an API call to determine what to turn off. This isn't necessary if we maintain a list of what we toggled on.

spacing between lines in interlinear should be tighter

I prefer the tighter spacing on master compared with what's on the unify branch right now.

pagination has visible scroll bar

See screen shot below for example

clean up word margins

The margins I tweaked for frequency widget are highly sensitive to other margins set on words and so should probably be calculated via a formula using variables.

update landing page based on README

Currently only MorphGNT route has landing page with full instructions. That should be tweaked to fit the new README and also shown at CTS and cite-services route.

add (newer) Morpheus widget to CTS reader

support CLTK API

https://github.com/cltk/cltk_api

Book Info links no longer work

They give URLs like http://localhost:5066/#/morphgnt?passage=%5Bobject%20Object%5D

think through widgets in central column, not just passages

At the moment, the assumption is there is a passage in the middle (or nothing if no passage is being viewed) and all widgets are on the left or right. But it should be possible for certain other widgets to go in the middle if the overall "thing" being focused on is something other than a passage.

For example, it should be possible to have a collection, text group, or work as the main thing being focused on.

At the other end of the spectrum, it should be possible for a word to be the thing being focused on.

Lexicon support: LSJ

Need support for LSJ - Great Scott might cause some real estate issues when you do this.

consider how to make responsive

Not clear at all how best to handle widgets in this case

switch to Noto by default

While I'll likely use Skolar for various reading environments built on DeepReader, we need to switch to an open typeface as the default for the DeepReader framework.

Noto Serif (and possibly also Noto Sans) probably makes sense given its decent pan-linguistic support.

prototype initial EPUB support

Just a minimal proof-of-concept initially including sorting out where the EPUB lives given the DeepReader architecture.

cts urn widget

Not only display current CTS URN (like I did for cite services) but make it a text input you can type directly into to retrieve that URN (without having to edit the query string manually)

Paradigms - Masternarde? greek-inflexion?

I would like to be able to quickly access paradigms for words. Masternarde's paradigms are a useful resource for this. You probably have better based on greek-inflexion.

fix scss @import webpack resolve behavior

To load styles/common.scss we are using relative paths, but we could use webpack resolution like @/styles/common.scss.

However, that does not work at the moment.

consider widgets that can be used independently of main reader

There may be widgets it makes sense to support running on other sites, outside the regular context of the main reader.

context-clicking on word in Safari selects previous word

(on unify-passage branch)

prototype map component

if text has places marked up

system for picking which widgets to display

task mode

I can imagine using DeepReader for specific tasks, either student assessment or student/expert crowdsourcing. e.g. find all the finite verbs in this passage; or disambiguate the morphology of all the words in red.

I imagine the way this would work is that you'd be in task mode which would limit some of the things you can do until you leave the task. During the task, a widget would explain the task at hand, provide stats, etc.

interlinear missing gender plus regression in spacing before dots

(on unify-passage branch)

Principal Parts

For verbs, I often want to look up the principal parts, e.g. when I am preparing a lesson and need to write questions about the text (in Greek). I would like an easy way to get this for any verb.

Bookmark Widget no longer has add button

(on unify-passage branch)

support intra-passage fragment referencing

rename LORE to DeepReader in header

persist word info like bookmarks

Don't automatically persist words selected but instead allow the current selected word info to be saved to list

Export to Anki?

I would like to see integration with Anki to drill things I learn when reading new texts.

text service component for non-chunked (local) files

we haven't really worked out how text service components work (whether they are a completely different kind of pluggable component to widgets) but I wanted to make a note about creating a text service component for handling non-chunked files that are either local or just served up as-is via HTTP.

e.g. I have a MorphGNT word-per-line file on disk for an entire book; or I have a TEI XML file for an entire work.

There's no reason we couldn't have a component that loads this into the store and does the chunking client side.

implement store-based system for text-level CSS toggling

area in the store that has boolean and string-valued properties than get turned into text-level CSS classes.

Boolean property becomes key and string-value property becomes key-value

more styling cleanup

I've got PR #65 with a lot of reorganization but there are a couple more things I didn't do so we can have more discussion.

1. I think we should have a separate file for theming variables (including the stuff from #51 but don't call it common.scss — maybe theme.scss would be better). It should JUST be variables but cover font and colour choices.

2. I think common.scss should still exist but be for small reusable things like the definition of .click or li.hanging

3. the widget styling could move to the Widget component (not 100% sure)

4. what's left in App.vue should mostly be skeleton stuff. Not sure if it could be further divided but I think we might want to move it all into .scss files anyway and keep App.vue lean.

new Morpheus widget that presents styled information (not just raw)

Initial load of passage does not render in reader

Either loading a particular URN or navigating to a passage the text is not rendered in the reader. However, going to the next page will work.

My initial attempts at debugging this is leading to a race condition. More work is needed to better understand why.

passage title isn't cleared when switching to CTS from MorphGNT

work out how to avoid innerHTML hack for document fragment coming from XSLT

prototype parallel reading

support "chrome" toggling by hotkey

At the moment, the demo readers toggle the "chrome" (i.e. widgets and header) on hover but some individual reader developers may want to support this via a hotkey (or give their users the choice, or even not allow chrome hiding at all).

fixed frequency heat map

currently doesn't toggle and when you change pages you get some stale styling

move any "magic" numbers in styles to common.scss