README

Title: Oboeta Plain-Text Flashcard System
Author: Jordan Vaughan <jordan.t.vaughan@gmail.com>
Language: en-US
Created: 2012-11-07
Last-Modified: 2017-08-10
Revision: 2.0.0 Jordan Vaughan
Encoding: UTF-8
Preferred-Line-Width: 80

Table of Contents

   1. Introduction
      1.1. The Problem
      1.2. The Solution
   2. Requirements      
   3. Installation
   4. The Scripts
      4.1. oleitner
      4.2. osm2
      4.3. oboeta
      4.4. oboetatty
      4.5. oboetahttp
      4.6. ocloze
   5. Use
   6. Sample Framework Built on Oboeta
   7. License
   8. Contributors
   9. Copyright

1.  Introduction

   This collection of simple scripts helps users manage simple,
   plain-text collections of flashcards.  It focuses on the essence of
   flashcard systems: scheduling.  It also provides some very simple
   programs for displaying flashcards.  A lot of the inspiration for this
   project comes from <http://suckless.org> and <http://cat-v.org>.

   "Oboeta" is a Japanese verb in the simple past tense.
   It means "remembered" or "memorized".

1.1.  The Problem

   I love electronic flashcards.  There are so many things to like
   about them:

      1. They're easy to create, modify, and destroy.

      2. It's especially easy to automatically generate hordes of cards
         from a few sentences if they're formatted properly.

      3. It's easy to apply changes across electronic flashcard decks.

      4. Computers can schedule reviews and track progress more quickly
         and accurately than humans.

      5. Electronic flashcards are easy to back up and transport.

      6. They occupy very little physical space.  (Hence (5).)

   But I also hate the most popular flashcard programs, such as Anki.
   They're complex, buggy, too restrictive, and tied to GUIs
   and storage formats that make my skin crawl.  (OK, SQLite isn't
   too bad, but extracting data from it is still a pain in the ass.)
   I tried many programs and was never satisfied.  All I wanted was
   something that operated on plain text and separated flashcards
   from their metadata.

   Plain text is an awesome way to store flashcards and their metadata
   because:

      1. plain text is universal: it'll be around when your
         grandchildren's grandchildren become worm food;

      2. plain text can be easily edited via any text editor;

      3. plain text files aren't tied to a particular program
         or library; and

      4. all standard UNIX/POSIX tools can manipulate plain text files.

   And then there's my love for paper flashcards.  I admit that they're
   a pain to create and manage, but there are reasons to use them:

      1. You can format paper flashcards however you want.
         No supporting tools or complicated formatting algorithms
         are necessary: Just write what you want and be done with it.

      2. Sometimes paper flashcards are easier to carry around
         and faster to use than a smart phone.  I have a little
         plastic pencil case that I bought for about $5 into which my
         B7-sized flashcards fit perfectly.  All I have to do to access
         them is unzip the case and pull them out.

      3. For people learning new languages with complex writing systems
         (such as some East Asian languages), paper flashcards force them
         to practice writing.  Typing doesn't help.

      4. Some people feel better when they use paper flashcards.
         I'm one of them.  I don't understand why, but I get that
         mysteriously good feeling that a lot of people say they have
         when they use paper products rather than electronic devices
         (e.g., for reading).

      5. Paper flashcards grab attention.  Smart phones and laptops
         don't do that because they're common and everyone around
         the user assumes she's playing games, sending messages,
         or surfing the web.  For language learners, the best thing
         about grabbing people's attention with flashcards is that
         it creates opportunities to practice.  Curious people start
         conversations, which lead to new sentences, which lead to
         new flashcards.  It's a beautiful circle.

1.2.  The Solution

   I wrote Oboeta to combine electronic and paper flashcards into
   a hybrid system.  The scripts are deliberately minimalistic
   so that you can format the flashcard data however you want.
   You can use them to maintain a paper or electronic flashcard system.

   Oboeta provides two scheduling systems.  The first is based on the
   Leitner system <http://en.wikipedia.org/wiki/Leitner_system>, which
   forms BUCKETS of flashcards, each bucket of which contains an
   associated interval in days.  The intervals determine how much time
   is added to a card's due date when you pass it.  This simple system
   provides only two responses for each card: "pass" and "fail".
   Oboeta used to use this Leitner system exclusively: I have retained
   it because others might like it.

   The second scheduling system is a slight variation of version 2 of the
   SuperMemo algorithm <http://www.supermemo.com/english/ol/sm2.htm>,
   also called "SM-2".  Each card has an associated EASINESS FACTOR,
   an INTERVAL in days, and an INTERVAL NUMBER, all of which determine
   how much time should be added to the card when you review it.
   SM-2 provides more fine-grained responses than Leitner systems:
   Instead of the binary pass/fail responses, you have to choose an
   integer between 0 and 5, where 0 means complete memory blackout
   and 5 means "Piece of cake!"  Your response determines the card's
   other parameters.

   Here's how the overall system works: You maintain a collection of
   (paper) flashcards organized any way you like provided that each one
   has a unique identifier.  (I use monotonically-increasing positive
   integers for mine.)  On the electronic side, you maintain two plain
   UTF-8-encoded text files:

      1. a delimiter-separated values (DSV) file (the DECK) containing
         one flashcard per line, each beginning with the flashcard's
         unique identifier; and

      2. a DSV file (the LOG) containing records of flashcard reviews.

   Oboeta is agnostic about the deck's data: It only expects that the
   file is a DSV file and that the first field of each line is a unique
   identifier.  You can format everything else however you want.
   This makes adding, editing, and reformatting flashcards a cinch:
   Just edit the deck file.  You can do this with any text editor.

   On the other hand, the requirements for the log are more stringent:

      1. Each nonempty line must have exactly three fields:
         a flashcard's identifier, a timestamp, and either of the
         '+' and '-' characters if your reviews use the Leitner system
         OR an integer in the range [0,5] if you use SM-2.

      2. The flashcard's identifier need not actually name a flashcard.
         (This makes deleting flashcards easy: Just remove them from the
         deck.  You can remove their entries in the log, too, but you
         don't have to.)

      3. The timestamp can be formatted however you wish,
         but you must be consistent.

      4. If your reviews use the Leitner system, then the third field
         must be either a single '+' character or a single '-' character.
         '+' indicates that you successfully reviewed the associated
         flashcard on the date represented by the timestamp,
         whereas '-' indicates that you failed.  On the other hand,
         if your reviews use SM-2, then the third field must be
         an integer between 0 and 5, inclusive.

   Oboeta uses the log to schedule flashcards for review.  You ask Oboeta
   to dump a bunch of new or due cards to the screen, select the
   corresponding paper flashcards, and review them.  When you're finished
   reviewing your cards, update the log accordingly.  Alternatively, you
   can use the console- and HTTP-based review scripts to review the cards
   on your computer, which will automatically update the log.

2.  Requirements

   I wrote most of the code in Python 3.(Die-hard Python 2 fans
   can cry me a river: Python 3 is the new standard.
   Welcome to the present AND the future.)  It runs fine with CPython,
   the standard implementation.

3.  Installation

   Open a terminal, navigate to the directory containing Oboeta's
   source code, and execute the install.sh script, passing the directory
   where you want to install executables as the first parameter.
   For example:

       $ ./install.sh /usr/bin

   This will copy the scripts to the specified directory.
   You might have to change users (e.g., run sudo)
   depending on which installation directory you select.

4.  The Scripts

   All of these scripts only depend on the standard Python 3 libraries.
   They can be executed independently but are designed to be plugged
   together via UNIX pipes or temporary files.

   For detailed help on a script, run it with an "-h"
   or "--help" argument.

4.1.  oleitner

   Process the deck and log files using the Leitner system
   and display flashcards that are due for review on standard output.

4.2.  osm2

   This is like oleitner but uses SM-2 instead of the Leitner system.

4.3.  oboeta

   Review flashcards from standard input, shuffling and writing them
   one at a time to standard output, while reading commands (pass, fail,
   quit) from a file (usually a named pipe).

4.4.  oboetatty

   Read flashcards one at a time from a file (usually a named pipe)
   and write them to standard output, get user input from standard input,
   and write the results (pass, fail, quit) to a file (usually a named
   pipe).  This program is only suitable for text-only flashcards.

4.5.  oboetahttp

   This is like oboetatty but reads cards from standard input instead
   and serves the cards as HTML5 over HTTP.

4.6.  ocloze

   Generate cloze deletion flashcards from standard input.

5.  Use

   oleitner and osm2 randomly choose new and due flashcards
   from a deck using history stored in a log file.
   They're simple filters reading from stdin and writing to stdout.

   oboeta is designed to work with oboetatty and oboetahttp,
   though you could write other programs to interact with it.

      o  oboeta functions as a flashcard randomizer and logger,
         reading flashcards chosen by oleitner and osm2 via stdin.

      o  oboetatty and oboetahttp focus on displaying the flashcards
         that oboeta chooses and sending results back to oboeta.

   oboetatty requires two named pipes:

      1. one for receiving cards from oboeta

      2. one for sending commands to oboeta

   On the other hand, oboetahttp requires only one named pipe,
   which it uses to send commands to oboeta.  oboetahttp reads cards
   from standard input.

   It gets a little more complicated, though.  You have to break up
   each card that oboeta prints into two lines per card
   before feeding them to oboetatty or oboetahttp.

      1. The first line contains the front side's fields.

      2. The second line contains the back side's fields.

   sed(1) and awk(1) scripts can usually handle this job.

   Here's a diagram illustrating the data flow between scripts:


               DECK FILE --.   .-------- LOG FILE <---------.
                           |   |                            |
                           |   |                            |
                           |   |                            |
                     stdin |   | command line argument      |
                           v   v                            |
                       +-----------+                        |
                       | oleitner/ |                        |
                       |   osm2    |                        |
                       +-----------+                        |
                             | stdout                       |
                             |                              |
                             v stdin                        |
           named pipe  +-----------+                        |
         .------------>|  oboeta   |------------------------'
         |             +-----------+  command line argument
         |                   | stdout
         |                   |
         |                   v stdin
         |         +--------------------+
         |         | Split lines in two |
         |         |  (front and back)  |
         |         +--------------------+
         |                   | stdout
         |                   |
         |                   v
         |             +------------+
         |             | oboetatty  |--------.
         '-------------|    or      |        | User reviews flashcards
           named pipe  | oboetahttp |<-------'
                       +------------+

   Let's check out some example pipelines.  Suppose your deck uses
   the SM-2 algorithm and you want reviews to have at most 20 old cards
   and 10 new ones.  If you want to review the cards on the console
   using fields two and three as the front and back, respectively,
   then this Bourne shell code will do it:

       mkfifo -m 0700 cardpipe commandpipe
       ( osm2 -n 20 -e 10 deck.log <deck.csv | \
         oboeta -2 $commandpipe deck.log | awk -F \\t '{
             print $2
             print $3
             system("")  # to flush awk's stdout buffer
         }' >$cardpipe ) &
       oboetatty -2 $cardpipe $commandpipe

   The -2 flags enable SM-2 support in oboeta and oboetatty.

   If you want to review cards via your favorite web browser,
   do this instead:

       mkfifo -m 0700 commandpipe
       osm2 -n 20 -e 10 deck.log <deck.csv | \
         oboeta -2 $commandpipe deck.log | awk -F \\t '{
             print $2
             print $3
             system("")  # to flush awk's stdout buffer
         }' | oboetahttp -2 >$commandpipe

   Of course, you can insert your own text processing pipelines
   between the oboeta scripts: That's the beauty of writing
   decoupled text-based programs.  For example, I like to insert
   a script between osm2 and oboeta to transform custom Japanese
   furigana (rubi) annotations into HTML5 <ruby> tags.

6.  Sample Framework Built on Oboeta

   If you want an example of a framework built on top of Oboeta,
   see my Honden repo at <https://github.com/joodan-van-github/honden>.
   Beware: I no longer maintain Honden.  It's kinda old.

7.  License

   All of the files in this collection have been dedicated to the
   public domain via the Creative Commons CC0 Public Domain Dedication
   in the hope that they would be circulated widely and without
   restriction.  I won't make any money from this code and I feel that
   it's more important that other people are free to use, modify,
   and distribute it as they please, with or without charge,
   even if I could make money from this.  Simply put, I like contributing
   to a healthy public domain.  See the file LICENSE for a complete copy
   of the public domain dedication.

8.  Contributors

   o  Jordan Vaughan (main contributor) <https://github.com/jtvaughan>

   o  wzel <https://github.com/wzel>

9.  Copyright

      ##########
      ###    ###
      ##  ##  ##   To the extent possible under law,
      #  # ##  #   the authors have waived all copyright
      #  # ##  #   and related and neighboring rights to
      #  ## #  #   this work.  For more information, please see
      #  ## #  #   <https://creativecommons.org/publicdomain/zero/1.0/>.
      ##  ##  ##
      ###    ###
      ##########