Skip to content

tool for creating and sharing annotations, using github for storage and social network

License

Notifications You must be signed in to change notification settings

shapr/fermatslastmargin

Repository files navigation

Fermat's Last Margin

A tool for annotating research papers (and more) and sharing those annotations (via git for starters)

Fermat's Last Theorem was captioned "I have a truly marvelous demonstration of this proposition which this margin is too narrow to contain."

This tool intends to be an infinite margin.

WHY WOULD I USE THIS?

Do you read many research papers or PhD theses? If yes, you might want to use this tool!

I like to write in the margins of my books and printed research papers. I want to read what other people have to say about a paper after I write down my own notes. I want to be able to search my notes. I want to be able to share my notes! I want to be able to remember why I downloaded a paper years later.

Why are notes separate from the paper itself?

Distributing PDFs will get you sued for lots of money ( https://en.wikipedia.org/wiki/Sci-Hub#United_States ). I don't want to get sued.

Getting Started

  • install poppler-utils, or more specifically, make sure the pdftocairo binary from poppler-utils is in your $PATH
  • git clone this repository
  • run this from cabal cabal run (optionally: nix-shell --run "cabal run")
  • point your web browser to localhost:3000 All of the annotations are saved in a local directory ~/.fermatslastmargin/localuser and your friend's annotations are saved in ~/.fermatslastmargin/friends/<github_name_of_friend>

Features

  • add paper info
  • read/write annotations
  • load page images
  • render 'uploaded' PDF to page images
  • push to github repo
  • pull from friends' github repo
  • switch notes view to see github friends' notes
  • setup new user (ask for github OAuth and username, set git remote correctly)
  • search crossref.org by title to get DOI
  • update PDF when viewing paper
  • plugin system to download paper (as PDF) when given unique ID (DOI for now)
  • search arxiv by title to get DOI
  • swap to github v4 graphql API so pulling friend repos doesn't get rate limited

Dependencies

  • git
  • poppler-utils (apt install poppler-utils)
  • zlib (apt install zlib1g-dev)

Dependencies when building from source

  • cabal 2.4 - if you get "cabal: fermatslastmargin.cabal:14: Parse of field 'build-depends' failed." you need to upgrade with "cabal install Cabal"
  • GHC 8.6 (at least, that's all I've tried)

Mac

  • brew install poppler
  • brew install zlib

Project Implementation

Scotty is used to handle a bunch of HTTP endpoints.

All state is saved in ~/.fermatslastmargin/. For the user viewing the papers, their state will be in ~/.fermatslastmargin/localuser.

The notes for each paper will be in ~/.fermatslastmargin/localuser/$DOI/paper.json. For example, Conor McBride's paper "Everybody's Got to be Somewhere" has a DOI of 10.4204/EPTCS.275.6. Once that paper is added, the notes will be saved into ~/.fermatslastmargin/localuser/10.4204/EPTCS.275.6/paper.json

Notes written by users followed by this user will be in ~/.fermatslastmargin/friends/<github_name_of_friend>

When a PDF is uploaded to create a new paper, the PDF is saved into ~/.fermatslastmargin/pageimages/$DOI/paper.pdf. Next, page images are generated by poppler-utils into ~/.fermatslastmargin/pageimages/$DOI/page-1.png up to however many pages in the PDF.

Front End code

The front end uses jquery in a thoroughly haphazard manner.

The state is mostly passed around as GET parameters for DOI, page number, and friend name. For example, http://localhost:3000/index.html?pagenum=1&uid=10.2168/LMCS-10(3:19)2014&friendview=chazzam

The front end javascript calls HTTP endpoints defined in Main.hs.

  • page images are fetched from the filesystem via a static endpoint
  • local and friend notes are fetched by GET'ing from /getannotate
  • a new or updated note is saved by posting to /annotate
  • friends are found by GET'ing the DOI from /friends?paperuid=DOI
  • pushing local notes to github GETs /gitpush
  • pulling remote notes from github GETs /gitpull
  • creating a new paper POSTs to /paper
  • creating a new user will hit /newuser

Migrate!

If you created a local repository and annotated papers before January 2020, you'll need to do cabal run migrate to get your repository in the new format!

About

tool for creating and sharing annotations, using github for storage and social network

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published