https://github.com/shapr/fermatslastmargin
tool for creating and sharing annotations, using github for storage and social network
https://github.com/shapr/fermatslastmargin
annotations doi research-paper
Last synced: 1 day ago
JSON representation
tool for creating and sharing annotations, using github for storage and social network
- Host: GitHub
- URL: https://github.com/shapr/fermatslastmargin
- Owner: shapr
- License: agpl-3.0
- Created: 2019-05-25T18:09:08.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2022-01-09T18:47:47.000Z (over 3 years ago)
- Last Synced: 2025-06-12T19:45:38.807Z (3 days ago)
- Topics: annotations, doi, research-paper
- Language: Haskell
- Homepage:
- Size: 1.33 MB
- Stars: 90
- Watchers: 8
- Forks: 9
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Fermat's Last Margin
A tool for annotating research papers (and more) and sharing those annotations (via git for starters)
[Fermat's Last Theorem](https://en.wikipedia.org/wiki/Fermat%27s_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](https://poppler.freedesktop.org/), 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/`
# Features
- [X] add paper info
- [X] read/write annotations
- [X] load page images
- [X] render 'uploaded' PDF to page images
- [X] push to github repo
- [X] pull from friends' github repo
- [X] switch notes view to see github friends' notes
- [X] setup new user (ask for github OAuth and username, set git remote correctly)
- [X] search crossref.org by title to get DOI
- [X] 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](http://hackage.haskell.org/package/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/`
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!