shapr/fermatslastmargin
1
1
Fork 0
mirror of https://github.com/shapr/fermatslastmargin.git synced 2024-11-22 01:52:47 +03:00
Code Issues Projects Releases Wiki Activity
tool for creating and sharing annotations, using github for storage and social network
113 Commits 2 Branches 0 Tags 1.4 MiB
Haskell 67.4%
Nix 14.5%
JavaScript 10.8%
CSS 5%
HTML 2.3%
master
Go to file
Shae Erisson c145e6c0e6 small cleanups, update nix to use hls 1.5.1
2022-01-09 12:53:29 -05:00
.github/workflows don't enable tests in deps 2020-01-24 22:01:46 -05:00
nix small cleanups, update nix to use hls 1.5.1 2022-01-09 12:53:29 -05:00
src small cleanups, update nix to use hls 1.5.1 2022-01-09 12:53:29 -05:00
static Support editing of metadata, this fixes #18 2019-11-11 17:01:58 -05:00
.gitignore Initial commit 2019-05-25 14:09:08 -04:00
CHANGELOG.md add CONTRIBUTORS, add more requirements 2019-11-08 20:01:33 -05:00
CONTRIBUTORS.md lower case all DOI everywhere, this fixes #26 2019-11-10 23:39:23 -05:00
default.nix update to ghc 8.10.7 2021-11-30 18:11:32 -05:00
fermatslastmargin.cabal update to ghc 8.10.7 2021-11-30 18:11:32 -05:00
haskell.yml update ghc to 8.8.4 for nix 2021-01-10 19:09:32 -05:00
LICENSE weeks later, initial version for github 2019-09-16 12:09:49 -04:00
Main.hs small cleanups, update nix to use hls 1.5.1 2022-01-09 12:53:29 -05:00
Migrate.hs Add migrate function. 2020-01-23 13:42:35 -05:00
README.md Update README.md 2020-05-16 12:49:07 -07:00
Setup.hs weeks later, initial version for github 2019-09-16 12:09:49 -04:00
shell.nix update to ghc 8.10.7 2021-11-30 18:11:32 -05:00

README.md

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!