lit-reader 1.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- lit_reader-1.2.0/.gitignore +9 -0
- lit_reader-1.2.0/LICENSE +21 -0
- lit_reader-1.2.0/PKG-INFO +269 -0
- lit_reader-1.2.0/README.md +249 -0
- lit_reader-1.2.0/docs/screenshot.png +0 -0
- lit_reader-1.2.0/pyproject.toml +39 -0
- lit_reader-1.2.0/src/lit_reader/__init__.py +3 -0
- lit_reader-1.2.0/src/lit_reader/__main__.py +5 -0
- lit_reader-1.2.0/src/lit_reader/core.py +3377 -0
- lit_reader-1.2.0/src/lit_reader/epub.py +419 -0
- lit_reader-1.2.0/src/lit_reader/fonts/OFL.txt +93 -0
- lit_reader-1.2.0/src/lit_reader/fonts/literata-opsz-italic.woff2 +0 -0
- lit_reader-1.2.0/src/lit_reader/fonts/literata-opsz-normal.woff2 +0 -0
- lit_reader-1.2.0/src/lit_reader/mail.py +240 -0
- lit_reader-1.2.0/src/lit_reader/reader.css +443 -0
- lit_reader-1.2.0/src/lit_reader/reader.js +899 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R1.py +13 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R11.py +15 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R12.py +10 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R16.py +11 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R2.py +10 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R3.py +12 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R5.py +10 -0
- lit_reader-1.2.0/tests/regressions/2026-11-21-R6.py +11 -0
- lit_reader-1.2.0/tests/regressions/browser/2026-11-21-R7.js +19 -0
- lit_reader-1.2.0/tests/regressions/bundle_harness.py +60 -0
- lit_reader-1.2.0/tests/regressions/run.sh +7 -0
lit_reader-1.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Robin Kwong
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: lit-reader
|
|
3
|
+
Version: 1.2.0
|
|
4
|
+
Summary: Turn academic papers into offline HTML reading copies.
|
|
5
|
+
Project-URL: Repository, https://github.com/RobinKwong/lit-reader
|
|
6
|
+
Project-URL: Issues, https://github.com/RobinKwong/lit-reader/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/RobinKwong/lit-reader#changelog
|
|
8
|
+
Author: Robin Kwong
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
License-File: src/lit_reader/fonts/OFL.txt
|
|
12
|
+
Keywords: academic papers,arxiv,html,pdf,reading
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: MacOS
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: Text Processing :: Markup :: HTML
|
|
18
|
+
Requires-Python: >=3.9
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# lit-reader
|
|
22
|
+
|
|
23
|
+
lit-reader turns an academic paper into an offline HTML reading copy, with reflowed text, a contents sidebar, citation cards, sidenotes and a saved reading position. It can also build a set of papers into one folder, with an index and links between them.
|
|
24
|
+
|
|
25
|
+

|
|
26
|
+
|
|
27
|
+
<sub>Shown: Setälä, Christensen, Leino and Strandberg, "Beyond polarization and selective trust", *Politics* (2021), doi:10.1177/02633957211024474, CC BY-NC.</sub>
|
|
28
|
+
|
|
29
|
+
## Why lit-reader
|
|
30
|
+
|
|
31
|
+
Most academic papers are published as PDFs laid out for print, which makes them hard work to read on a laptop. lit-reader is for researchers, students, journalists and anyone else who reads papers closely on a screen. It resets the paper for long reading and never summarises or rewrites it. Conversion can still lose or garble text, so lit-reader reports how much of the text reached the page. That check catches lost text but can't tell when text is out of order.
|
|
32
|
+
|
|
33
|
+
Unlike most PDF viewers, which show you the printed page, lit-reader reflows the text from PDFs and adds tools for reading it:
|
|
34
|
+
|
|
35
|
+
- **Text set for reading.** By default, lines run to about 65 characters, and lit-reader adds no automatic hyphenation. Long paragraphs are split at sentence ends, and an "As published" setting restores the original breaks.
|
|
36
|
+
- **Citations that open in place.** Point at or click a citation to read the reference in a card without losing your place; on a laptop, clicking it while its card is showing goes on to the reference list. Footnotes sit in the margin, except in papers built from a PDF, where they follow the paragraph.
|
|
37
|
+
- **A sense of where you are.** The contents sidebar shows the minutes in each section, and the Contents button hides it when you want only the text. The top bar shows the time left, and the page reopens where you stopped. Papers built from a PDF also keep their original page numbers in the margin.
|
|
38
|
+
- **Quotes saved with their citation.** Select a passage and choose "Save quote", or press Q. The Quotes button in the top bar copies each quote with its author, year and page, or downloads them all as a Markdown file. Quotes are kept in your browser, not in a file, so once you have saved some, the Quotes panel and the end of the paper remind you of any you haven't downloaded. Page numbers come only from papers built from a PDF.
|
|
39
|
+
- **Settings for your own eyes.** You can change the theme, font, size, line length and line spacing. People read fastest in different fonts, and [the font you like best may not be your fastest](https://research.adobe.com/publication/towards-individuated-reading-experiences-different-fonts-increase-reading-speed-for-different-individuals).
|
|
40
|
+
- **Several papers as one set.** A bundle builds a list of papers into one folder, with an index showing what you've started and finished, links from a citation to another paper of the set, and all your saved quotes in one file. See [Bundles](#bundles-several-papers-together).
|
|
41
|
+
- **A check on the build.** lit-reader reports the share of the source's words that reached the page and lists any long passages that didn't. Tables and figures from a PDF appear as images, so their words count as missing. The check can't run on scanned PDFs, or on arXiv pages built without poppler. Where a PDF page lost ordinary sentences, the reading copy offers that page as printed.
|
|
42
|
+
- **Private and offline.** Each reading copy is a local HTML page that loads nothing from the network and needs no account or server.
|
|
43
|
+
- **Copies for your phone or e-reader.** On a phone, the top bar steps aside while you read, citations open in a sheet along the bottom, the contents sit in a drawer, and tapping a figure or table opens it full screen. `--epub` adds an EPUB, with its page list and linked notes, for Apple Books or another e-reader. `--single-file` adds the reading copy as one HTML file with nothing beside it, and `--email` sends either copy to you. On an iPhone, the EPUB is the copy to read: see [Reading on a phone](#reading-on-a-phone).
|
|
44
|
+
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
lit-reader is on [PyPI](https://pypi.org/project/lit-reader/) and has only been tested on macOS so far. With [uv](https://docs.astral.sh/uv/), you can try it without installing anything permanently:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
uvx lit-reader 2401.04088
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
To install the `lit-reader` command:
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
uv tool install lit-reader
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
or, with pipx, `pipx install lit-reader`. To update it later, run `uv tool upgrade lit-reader`.
|
|
60
|
+
|
|
61
|
+
Papers with an arXiv HTML version or open-access text in Europe PMC need nothing else to build, though arXiv pages skip the coverage check without poppler. To read PDFs, also install [poppler](https://poppler.freedesktop.org/) and [Docling](https://github.com/docling-project/docling):
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
brew install poppler # Debian or Ubuntu: sudo apt install poppler-utils
|
|
65
|
+
uv tool install docling --python 3.12
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Docling downloads about 2 GB of models the first time it runs.
|
|
69
|
+
|
|
70
|
+
## Usage
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
lit-reader paper.pdf
|
|
74
|
+
lit-reader 2401.04088
|
|
75
|
+
lit-reader https://arxiv.org/abs/2401.04088
|
|
76
|
+
lit-reader 10.1371/journal.pmed.0020124
|
|
77
|
+
lit-reader PMC1182327
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The reading copy is written to `./<slug>/index.html`, where the slug combines the first author, year and title. Open that file in a browser. Keep the folder together, because the page uses the `assets` folder beside it.
|
|
81
|
+
|
|
82
|
+
| Option | What it does |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `-o DIR` | Writes the reading copy to `DIR` instead. |
|
|
85
|
+
| `--route ROUTE` | Chooses the source, as described in the next section. |
|
|
86
|
+
| `--pages A-B` | Converts only these pages of a PDF, for example `--pages 12-30`. |
|
|
87
|
+
| `--epub` | Also writes an EPUB copy into the same folder. |
|
|
88
|
+
| `--single-file` | Also writes `<slug>.html` into the same folder: the same reading copy with its styles, script and fonts inside it, so the one file works on its own. It leaves out links to a local PDF, which wouldn't travel with it. |
|
|
89
|
+
| `--email` | Also emails the EPUB to you, for Apple Books or another e-reader. `--email html` sends the single file instead. It needs the setup in [Emailing a copy to yourself](#emailing-a-copy-to-yourself). |
|
|
90
|
+
|
|
91
|
+
### Bundles: several papers together
|
|
92
|
+
|
|
93
|
+
A bundle is a set of papers read for one purpose, such as a seminar week, a literature review or an essay. List them in a plain text file, one per line, in any of the forms `lit-reader` takes for one paper:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
# Groups, trust and AI
|
|
97
|
+
# For the essay: it rests on these papers or has to answer them.
|
|
98
|
+
arXiv:2508.08242
|
|
99
|
+
10.1177/02633957211024474
|
|
100
|
+
papers/beavers-2026.pdf pages=253-314
|
|
101
|
+
PMC7104178 route=online
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Lines starting with `#` before the first paper give the bundle's title (the first such line) and a note (any others). After a paper, `pages=A-B` and `route=ROUTE` work as the options of the same name do for one paper. A relative PDF path is read from the text file's folder. The same PDF can be listed more than once with different pages, such as the chapters of a book, and each range becomes its own reading copy.
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
lit-reader bundle reading.txt
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
This writes every reading copy into one folder, `./<title>/` (or `-o DIR`), with an `index.html` listing them in order:
|
|
111
|
+
|
|
112
|
+
- **The index** shows whether you've started or finished each paper and how many quotes you've saved from it. Under the list, a Saved quotes section downloads or copies every saved quote as one Markdown file, grouped by paper with each one's citation.
|
|
113
|
+
- **Each paper's top bar** shows its place in the bundle ("3 of 7") and links back to the index.
|
|
114
|
+
- **Citations between papers.** When a reference in one paper is another paper of the bundle, its citation card says so and links to that paper's reading copy. That paper's top bar then offers the way back to the citation.
|
|
115
|
+
|
|
116
|
+
A paper that can't be converted is listed on the index and at the end of the command's output, with the reason and what to do about it, and the rest are still built. Running the command again rebuilds the bundle in the same folder. The index reads your progress and quotes from browser storage, which has been checked in Chrome only: see [Limits and testing](#limits-and-testing).
|
|
117
|
+
|
|
118
|
+
| Option | What it does |
|
|
119
|
+
|---|---|
|
|
120
|
+
| `-o DIR` | Writes the bundle to `DIR` instead. |
|
|
121
|
+
| `--route ROUTE` | The source for every paper, unless its line says otherwise. |
|
|
122
|
+
| `--epub` | Also writes EPUBs. `--epub papers` (the default) writes one per paper, `--epub bundle` writes one EPUB holding every paper, with the bundle's contents first, and `--epub both` writes both. To make a bare `--epub` mean `bundle` or `both`, add a line such as `epub = "both"` to the settings file, `~/.config/lit-reader/config.toml`. |
|
|
123
|
+
| `--single-file` | Also writes each paper as one HTML file, in `single-file/`. A single file leaves out the links to the other papers, which don't travel with it. |
|
|
124
|
+
|
|
125
|
+
### Emailing a copy to yourself
|
|
126
|
+
|
|
127
|
+
`--email` sends the copy through your own mail account. To set it up, run this in Terminal and answer its questions:
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
lit-reader setup-email
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
It asks for your address, fills in the mail server for Gmail and iCloud addresses, and shows the settings before it writes them. On a Mac it then stores your password in Keychain and offers to send you a test email. Run it again to change anything.
|
|
134
|
+
|
|
135
|
+
Gmail, iCloud and many other providers don't accept your normal password from a program, so create an app password in your account's security settings first. The command says where to find it for Gmail and iCloud.
|
|
136
|
+
|
|
137
|
+
lit-reader checks the settings and password before it starts converting. If sending fails, the copies it has written stay where they are.
|
|
138
|
+
|
|
139
|
+
To set it up by hand instead, add an `[email]` section to the settings file, `~/.config/lit-reader/config.toml`:
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
[email]
|
|
143
|
+
to = "you@example.com"
|
|
144
|
+
smtp_host = "smtp.gmail.com"
|
|
145
|
+
smtp_port = "587" # optional: 587 (the default) or 465
|
|
146
|
+
smtp_user = "you@example.com" # optional: defaults to the "to" address
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The password never goes in that file. On a Mac, store it in Keychain with this command, which asks for it:
|
|
150
|
+
|
|
151
|
+
```
|
|
152
|
+
security add-generic-password -s lit-reader -a you@example.com -w
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
On other systems, set the `LIT_READER_SMTP_PASSWORD` environment variable.
|
|
156
|
+
|
|
157
|
+
## Which source is used
|
|
158
|
+
|
|
159
|
+
**If you give a PDF, lit-reader reads that PDF.** Your file may be a particular version of the paper, such as an accepted manuscript, so it is never replaced by an online copy without your asking.
|
|
160
|
+
|
|
161
|
+
**If you give an identifier**, lit-reader uses the best source it can find: arXiv's HTML, then Europe PMC's full-text XML for open-access papers, then [ar5iv](https://ar5iv.labs.arxiv.org/)'s conversion, then arXiv's PDF. ar5iv is arXiv Labs' earlier HTML conversion, and lit-reader uses it only when arXiv says it has no HTML version of the paper. If arXiv is down, lit-reader says so and doesn't try ar5iv.
|
|
162
|
+
|
|
163
|
+
To change this, use `--route`:
|
|
164
|
+
|
|
165
|
+
| Option | What it does |
|
|
166
|
+
|---|---|
|
|
167
|
+
| `--route auto` | The default, as described above. |
|
|
168
|
+
| `--route online` | Prefers arXiv's HTML or Europe PMC's XML, even when you give a PDF. If neither is available, it falls back to your PDF. |
|
|
169
|
+
| `--route arxiv` | Uses arXiv's HTML, or ar5iv's conversion when arXiv has none. |
|
|
170
|
+
| `--route jats` | Uses Europe PMC's XML only. |
|
|
171
|
+
| `--route pdf` | Uses the PDF only. |
|
|
172
|
+
|
|
173
|
+
For example, `lit-reader paper.pdf --route online` looks for an online version of the paper in your PDF. It can only do this if the PDF's first page shows an arXiv ID or a DOI.
|
|
174
|
+
|
|
175
|
+
On every route, lit-reader sends an arXiv ID or DOI found on a PDF's first page to arXiv or Crossref to look up the title and authors. The PDF itself is never uploaded.
|
|
176
|
+
|
|
177
|
+
### What each source gives you
|
|
178
|
+
|
|
179
|
+
| Source | Best for | What to expect |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| arXiv HTML | arXiv papers | Real headings, linked citations and live tables. arXiv labels this format experimental, and some figures don't convert. The page links to the PDF for those. ar5iv's conversions can stop partway, which the coverage check shows. |
|
|
182
|
+
| Europe PMC XML | Open-access papers in Europe PMC | Real headings, linked citations and the publisher's figures. |
|
|
183
|
+
| PDF | Everything else | Text converted by Docling, with the original page numbers in the margin. Figures and tables are images cropped from the page. |
|
|
184
|
+
|
|
185
|
+
## Checking a reading copy
|
|
186
|
+
|
|
187
|
+
lit-reader compares the page with the source text and prints the result:
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
coverage: 95.6% of the 5438 words in the PDF's text reached the page
|
|
191
|
+
missing run of 58 words: the proportion of repeated layer 0 0 20 0 15 ...
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The check counts words, so it catches text that was lost but not text in the wrong order, such as two columns read across, or a misread equation. A missing run is a stretch of 25 or more source words that didn't reach the page. Runs of numbers and labels usually come from charts and tables, which is expected when they appear as images. A run of ordinary sentences means text was lost, so check that passage against the original. For a PDF, the reading copy then offers a "Show the original page" button at that page, for up to ten pages, and the build lists the pages it flagged.
|
|
195
|
+
|
|
196
|
+
Pages built from arXiv HTML or a PDF are compared with the PDF's text, which needs poppler. Without it, arXiv pages still build but skip the check. Pages built from Europe PMC are compared with the article's XML.
|
|
197
|
+
|
|
198
|
+
If a paper converts badly, please [open an issue](https://github.com/RobinKwong/lit-reader/issues) with its arXiv ID, DOI or a link to it.
|
|
199
|
+
|
|
200
|
+
## Reading on a phone
|
|
201
|
+
|
|
202
|
+
The reading copies lay out for a phone screen, but how you get one onto a phone matters, because a phone's preview of an attachment may not run the page's script.
|
|
203
|
+
|
|
204
|
+
- **iPhone:** use the EPUB. `--email` sends it to you; open the attachment from Mail and it goes into Books, or in the Gmail app choose Books from the share sheet. Apple Books gives you its own contents, footnote pop-ups, font settings and highlights. A single HTML file opened from the Gmail app on an iPhone shows the text, but the preview runs no script and can't follow links within the page, so the contents, citations and settings don't respond.
|
|
205
|
+
- **Android, or a laptop:** a `--single-file` copy opened in a browser works like the folder copy.
|
|
206
|
+
|
|
207
|
+
Where no script runs, a single file still shows the text, its time to read, footnotes under their paragraphs and each table's text version, and it hides the buttons that can't work.
|
|
208
|
+
|
|
209
|
+
## Limits and testing
|
|
210
|
+
|
|
211
|
+
lit-reader is tuned for academic papers, and it also handles other long PDFs with selectable text, such as dissertations and reports. A 370-page dissertation took about two minutes to convert on a Mac laptop.
|
|
212
|
+
|
|
213
|
+
- **Formats:** it accepts PDFs, arXiv IDs or URLs, DOIs and PMCIDs. It doesn't accept EPUB, Word, HTML, plain text or links to web articles.
|
|
214
|
+
- **DOIs:** a DOI only works when arXiv or Europe PMC has the full text openly available. For a book or a paywalled paper, supply the PDF.
|
|
215
|
+
- **Headings:** the contents sidebar depends on headings that look different from the body text. A plainly typeset manuscript may come through as one long section.
|
|
216
|
+
- **Scanned PDFs:** Docling recognises the text, but the coverage check can't run because the PDF has no text to compare against.
|
|
217
|
+
- **Figures and tables as images:** under each table in a PDF, a closed "as text" section holds Docling's reading of the table, for screen readers and small screens. It hasn't been checked by hand, and the page says so. In some Europe PMC papers, a screen reader can reach a table's caption but not its data. A chart's only description is its caption.
|
|
218
|
+
- **Citations and footnotes:** citation cards need a reference list that lit-reader can recognise. In PDFs, footnotes appear as small text after the paragraph instead of in the margin.
|
|
219
|
+
- **Equations:** arXiv pages keep real maths. Europe PMC pages use the article's maths if it has any, and otherwise its image of the equation or its TeX source. In PDFs, an equation Docling can read appears as plain text, so check it against the original. One it can't read appears as an image of the printed equation.
|
|
220
|
+
- **Screens:** lit-reader is designed for reading on a laptop or desktop, and pages also lay out for phones. The phone layout has been checked in a desktop browser's phone emulation. On a real iPhone, an EPUB in Apple Books and a single file in the Gmail app's preview have been tried, but not a single file in a phone's browser. A page needs the `assets` folder beside it unless you build it with `--single-file`. Each browser keeps its own quotes and reading position: a phone won't have what you saved on a laptop.
|
|
221
|
+
- **Browsers:** reading copies have been checked in Chrome. A bundle's index reads each paper's quotes and finished mark from browser storage, which works when the browser shares storage between local files in one folder, as Chrome does. Safari and Firefox are untested.
|
|
222
|
+
- **E-readers:** EPUB copies pass structural checks and open in Apple Books on an iPhone, but haven't been tested on a Kindle yet. How maths and wide tables look depends on the e-reader.
|
|
223
|
+
- **Languages:** accented Latin text comes through correctly, but pages are marked as English and line-break repair uses an English word list. Right-to-left scripts and Chinese, Japanese and Korean are untested.
|
|
224
|
+
|
|
225
|
+
## Privacy
|
|
226
|
+
|
|
227
|
+
lit-reader uses no AI service, analytics or account. Conversion happens on your machine, reading copies load nothing from the internet, and your settings, reading position and saved quotes stay in your browser. It uses the network only in these cases:
|
|
228
|
+
|
|
229
|
+
- **Fetching a paper:** an arXiv ID, DOI or PMCID is sent to arXiv, ar5iv, Crossref or Europe PMC, and the paper comes back.
|
|
230
|
+
- **Looking up a local PDF:** an arXiv ID or DOI found on the first page is sent to arXiv or Crossref to find the title and authors. This happens on every route, including `--route pdf`, and can't be turned off. The PDF itself is never uploaded.
|
|
231
|
+
- **Emailing a copy:** with `--email`, the copy is sent through the mail server in your settings, logging in over an encrypted connection.
|
|
232
|
+
- **Installing:** uv downloads lit-reader, and Docling downloads its models the first time it runs.
|
|
233
|
+
- **Following a link:** links in a reading copy open in your browser like any other link.
|
|
234
|
+
|
|
235
|
+
## Copyright
|
|
236
|
+
|
|
237
|
+
Reading copies are for your own use. The MIT licence below covers this software, not the papers you convert, which keep their own copyright and licences. Please don't redistribute reading copies of paywalled papers. A reading copy made from a PDF includes a copy of that PDF in its folder, so take particular care when sharing one. A single file or an EPUB copy doesn't include the PDF, but it does include the paper's full text and figures, so the same care applies. A bundle's folder and its EPUB hold every paper in the bundle, which matters when you hand one to a reading group.
|
|
238
|
+
|
|
239
|
+
## Licence
|
|
240
|
+
|
|
241
|
+
lit-reader is released under the [MIT licence](https://github.com/RobinKwong/lit-reader/blob/main/LICENSE). It includes the Literata typeface, which is licensed under the [SIL Open Font License](https://github.com/RobinKwong/lit-reader/blob/main/src/lit_reader/fonts/OFL.txt).
|
|
242
|
+
|
|
243
|
+
## Changelog
|
|
244
|
+
|
|
245
|
+
### v1.2
|
|
246
|
+
|
|
247
|
+
v1.2 reads several papers as one set.
|
|
248
|
+
|
|
249
|
+
- **Bundles.** `lit-reader bundle <file>` builds every paper listed in a text file into one folder, with an index page showing which papers you've started or finished and how many quotes you've saved from each. A paper that can't be converted is listed with the reason and what to do, and the rest are still built.
|
|
250
|
+
- **Moving between papers.** Each paper's top bar shows its place in the bundle ("3 of 7"). A citation of another paper in the bundle links to its reading copy, and that paper's bar then offers the way back to the citation.
|
|
251
|
+
- **Quotes across the bundle.** The index downloads or copies every saved quote as one Markdown file, grouped by paper with each one's citation.
|
|
252
|
+
- **One EPUB for the bundle.** `--epub bundle` writes one book holding every paper, with the bundle's contents first and references between its papers linked. `--epub both` also writes one EPUB per paper.
|
|
253
|
+
- **A thinner bar on a phone.** The top bar holds only the contents button and the reading status, and steps aside as you scroll down. All papers, Quotes and the reading settings sit at the top of the contents drawer.
|
|
254
|
+
- **Smaller changes.** "Finished" on the index now has enough contrast in every theme, and marking a paper finished is announced to screen readers.
|
|
255
|
+
|
|
256
|
+
### v1.1
|
|
257
|
+
|
|
258
|
+
v1.1 takes the reading copies off the laptop, onto a phone or an e-reader, and lets you keep quotes from what you read.
|
|
259
|
+
|
|
260
|
+
- **Reading on a phone.** Pages lay out for a phone screen. Citations open in a sheet along the bottom, the contents sit in a drawer, buttons are sized for touch, and tapping a figure or table opens it full screen.
|
|
261
|
+
- **Copies to take with you.** `--epub` writes an EPUB for Apple Books or a Kindle. `--single-file` writes the reading copy as one HTML file that survives being emailed and still shows its text where no script runs. `--email` sends either copy to you through your own mail account, and `lit-reader setup-email` sets that up.
|
|
262
|
+
- **Saved quotes.** Select a passage and save it with its author, year and page, then copy it or download all your quotes as Markdown. A tip on your first few papers points out the feature, the Quotes panel and the end of the paper remind you of quotes you haven't downloaded, and a removed quote can be restored until the panel closes.
|
|
263
|
+
- **More of the paper, and a check on what's missing.** When arXiv has no HTML version of a paper, lit-reader tries ar5iv's conversion before the PDF. Where a PDF page lost ordinary sentences, the reading copy offers that page as printed. Under each table from a PDF, an unchecked text version helps screen readers and small screens.
|
|
264
|
+
- **Cleaner PDF conversions.** A footnote that runs over a page break is joined back together, a numbered list of affiliations no longer splits the paragraph around it, and a summary in run-in labels (Science's "INTRODUCTION:", "RATIONALE:" and so on) gets its own heading in the contents, with an "Introduction" heading where the untitled article begins.
|
|
265
|
+
- **Smaller changes.** On a laptop, the Contents button hides the sidebar. Clicking a citation whose card is already showing goes on to the reference list. "Go to reference list" leaves a button back to where you were, and the contents show "6 min" rather than "6′". "Mark as finished" sits where the main text ends, before any appendix and the references. EPUBs aren't hyphenated, to match the reading copies.
|
|
266
|
+
|
|
267
|
+
### v1.0
|
|
268
|
+
|
|
269
|
+
The first public release, on 18 November 2026, first numbered 0.1.0. It turns a PDF, arXiv ID or URL, DOI or PMCID into an offline reading copy from arXiv's HTML, Europe PMC's XML or the PDF. The copy has reflowed text, a contents sidebar with the minutes in each section, citation cards, sidenotes, the printed page numbers, reading settings and a saved reading position. Each build reports how much of the source's text reached the page.
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# lit-reader
|
|
2
|
+
|
|
3
|
+
lit-reader turns an academic paper into an offline HTML reading copy, with reflowed text, a contents sidebar, citation cards, sidenotes and a saved reading position. It can also build a set of papers into one folder, with an index and links between them.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
<sub>Shown: Setälä, Christensen, Leino and Strandberg, "Beyond polarization and selective trust", *Politics* (2021), doi:10.1177/02633957211024474, CC BY-NC.</sub>
|
|
8
|
+
|
|
9
|
+
## Why lit-reader
|
|
10
|
+
|
|
11
|
+
Most academic papers are published as PDFs laid out for print, which makes them hard work to read on a laptop. lit-reader is for researchers, students, journalists and anyone else who reads papers closely on a screen. It resets the paper for long reading and never summarises or rewrites it. Conversion can still lose or garble text, so lit-reader reports how much of the text reached the page. That check catches lost text but can't tell when text is out of order.
|
|
12
|
+
|
|
13
|
+
Unlike most PDF viewers, which show you the printed page, lit-reader reflows the text from PDFs and adds tools for reading it:
|
|
14
|
+
|
|
15
|
+
- **Text set for reading.** By default, lines run to about 65 characters, and lit-reader adds no automatic hyphenation. Long paragraphs are split at sentence ends, and an "As published" setting restores the original breaks.
|
|
16
|
+
- **Citations that open in place.** Point at or click a citation to read the reference in a card without losing your place; on a laptop, clicking it while its card is showing goes on to the reference list. Footnotes sit in the margin, except in papers built from a PDF, where they follow the paragraph.
|
|
17
|
+
- **A sense of where you are.** The contents sidebar shows the minutes in each section, and the Contents button hides it when you want only the text. The top bar shows the time left, and the page reopens where you stopped. Papers built from a PDF also keep their original page numbers in the margin.
|
|
18
|
+
- **Quotes saved with their citation.** Select a passage and choose "Save quote", or press Q. The Quotes button in the top bar copies each quote with its author, year and page, or downloads them all as a Markdown file. Quotes are kept in your browser, not in a file, so once you have saved some, the Quotes panel and the end of the paper remind you of any you haven't downloaded. Page numbers come only from papers built from a PDF.
|
|
19
|
+
- **Settings for your own eyes.** You can change the theme, font, size, line length and line spacing. People read fastest in different fonts, and [the font you like best may not be your fastest](https://research.adobe.com/publication/towards-individuated-reading-experiences-different-fonts-increase-reading-speed-for-different-individuals).
|
|
20
|
+
- **Several papers as one set.** A bundle builds a list of papers into one folder, with an index showing what you've started and finished, links from a citation to another paper of the set, and all your saved quotes in one file. See [Bundles](#bundles-several-papers-together).
|
|
21
|
+
- **A check on the build.** lit-reader reports the share of the source's words that reached the page and lists any long passages that didn't. Tables and figures from a PDF appear as images, so their words count as missing. The check can't run on scanned PDFs, or on arXiv pages built without poppler. Where a PDF page lost ordinary sentences, the reading copy offers that page as printed.
|
|
22
|
+
- **Private and offline.** Each reading copy is a local HTML page that loads nothing from the network and needs no account or server.
|
|
23
|
+
- **Copies for your phone or e-reader.** On a phone, the top bar steps aside while you read, citations open in a sheet along the bottom, the contents sit in a drawer, and tapping a figure or table opens it full screen. `--epub` adds an EPUB, with its page list and linked notes, for Apple Books or another e-reader. `--single-file` adds the reading copy as one HTML file with nothing beside it, and `--email` sends either copy to you. On an iPhone, the EPUB is the copy to read: see [Reading on a phone](#reading-on-a-phone).
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
lit-reader is on [PyPI](https://pypi.org/project/lit-reader/) and has only been tested on macOS so far. With [uv](https://docs.astral.sh/uv/), you can try it without installing anything permanently:
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
uvx lit-reader 2401.04088
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
To install the `lit-reader` command:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
uv tool install lit-reader
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
or, with pipx, `pipx install lit-reader`. To update it later, run `uv tool upgrade lit-reader`.
|
|
40
|
+
|
|
41
|
+
Papers with an arXiv HTML version or open-access text in Europe PMC need nothing else to build, though arXiv pages skip the coverage check without poppler. To read PDFs, also install [poppler](https://poppler.freedesktop.org/) and [Docling](https://github.com/docling-project/docling):
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
brew install poppler # Debian or Ubuntu: sudo apt install poppler-utils
|
|
45
|
+
uv tool install docling --python 3.12
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Docling downloads about 2 GB of models the first time it runs.
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
lit-reader paper.pdf
|
|
54
|
+
lit-reader 2401.04088
|
|
55
|
+
lit-reader https://arxiv.org/abs/2401.04088
|
|
56
|
+
lit-reader 10.1371/journal.pmed.0020124
|
|
57
|
+
lit-reader PMC1182327
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The reading copy is written to `./<slug>/index.html`, where the slug combines the first author, year and title. Open that file in a browser. Keep the folder together, because the page uses the `assets` folder beside it.
|
|
61
|
+
|
|
62
|
+
| Option | What it does |
|
|
63
|
+
|---|---|
|
|
64
|
+
| `-o DIR` | Writes the reading copy to `DIR` instead. |
|
|
65
|
+
| `--route ROUTE` | Chooses the source, as described in the next section. |
|
|
66
|
+
| `--pages A-B` | Converts only these pages of a PDF, for example `--pages 12-30`. |
|
|
67
|
+
| `--epub` | Also writes an EPUB copy into the same folder. |
|
|
68
|
+
| `--single-file` | Also writes `<slug>.html` into the same folder: the same reading copy with its styles, script and fonts inside it, so the one file works on its own. It leaves out links to a local PDF, which wouldn't travel with it. |
|
|
69
|
+
| `--email` | Also emails the EPUB to you, for Apple Books or another e-reader. `--email html` sends the single file instead. It needs the setup in [Emailing a copy to yourself](#emailing-a-copy-to-yourself). |
|
|
70
|
+
|
|
71
|
+
### Bundles: several papers together
|
|
72
|
+
|
|
73
|
+
A bundle is a set of papers read for one purpose, such as a seminar week, a literature review or an essay. List them in a plain text file, one per line, in any of the forms `lit-reader` takes for one paper:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
# Groups, trust and AI
|
|
77
|
+
# For the essay: it rests on these papers or has to answer them.
|
|
78
|
+
arXiv:2508.08242
|
|
79
|
+
10.1177/02633957211024474
|
|
80
|
+
papers/beavers-2026.pdf pages=253-314
|
|
81
|
+
PMC7104178 route=online
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Lines starting with `#` before the first paper give the bundle's title (the first such line) and a note (any others). After a paper, `pages=A-B` and `route=ROUTE` work as the options of the same name do for one paper. A relative PDF path is read from the text file's folder. The same PDF can be listed more than once with different pages, such as the chapters of a book, and each range becomes its own reading copy.
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
lit-reader bundle reading.txt
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
This writes every reading copy into one folder, `./<title>/` (or `-o DIR`), with an `index.html` listing them in order:
|
|
91
|
+
|
|
92
|
+
- **The index** shows whether you've started or finished each paper and how many quotes you've saved from it. Under the list, a Saved quotes section downloads or copies every saved quote as one Markdown file, grouped by paper with each one's citation.
|
|
93
|
+
- **Each paper's top bar** shows its place in the bundle ("3 of 7") and links back to the index.
|
|
94
|
+
- **Citations between papers.** When a reference in one paper is another paper of the bundle, its citation card says so and links to that paper's reading copy. That paper's top bar then offers the way back to the citation.
|
|
95
|
+
|
|
96
|
+
A paper that can't be converted is listed on the index and at the end of the command's output, with the reason and what to do about it, and the rest are still built. Running the command again rebuilds the bundle in the same folder. The index reads your progress and quotes from browser storage, which has been checked in Chrome only: see [Limits and testing](#limits-and-testing).
|
|
97
|
+
|
|
98
|
+
| Option | What it does |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `-o DIR` | Writes the bundle to `DIR` instead. |
|
|
101
|
+
| `--route ROUTE` | The source for every paper, unless its line says otherwise. |
|
|
102
|
+
| `--epub` | Also writes EPUBs. `--epub papers` (the default) writes one per paper, `--epub bundle` writes one EPUB holding every paper, with the bundle's contents first, and `--epub both` writes both. To make a bare `--epub` mean `bundle` or `both`, add a line such as `epub = "both"` to the settings file, `~/.config/lit-reader/config.toml`. |
|
|
103
|
+
| `--single-file` | Also writes each paper as one HTML file, in `single-file/`. A single file leaves out the links to the other papers, which don't travel with it. |
|
|
104
|
+
|
|
105
|
+
### Emailing a copy to yourself
|
|
106
|
+
|
|
107
|
+
`--email` sends the copy through your own mail account. To set it up, run this in Terminal and answer its questions:
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
lit-reader setup-email
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
It asks for your address, fills in the mail server for Gmail and iCloud addresses, and shows the settings before it writes them. On a Mac it then stores your password in Keychain and offers to send you a test email. Run it again to change anything.
|
|
114
|
+
|
|
115
|
+
Gmail, iCloud and many other providers don't accept your normal password from a program, so create an app password in your account's security settings first. The command says where to find it for Gmail and iCloud.
|
|
116
|
+
|
|
117
|
+
lit-reader checks the settings and password before it starts converting. If sending fails, the copies it has written stay where they are.
|
|
118
|
+
|
|
119
|
+
To set it up by hand instead, add an `[email]` section to the settings file, `~/.config/lit-reader/config.toml`:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
[email]
|
|
123
|
+
to = "you@example.com"
|
|
124
|
+
smtp_host = "smtp.gmail.com"
|
|
125
|
+
smtp_port = "587" # optional: 587 (the default) or 465
|
|
126
|
+
smtp_user = "you@example.com" # optional: defaults to the "to" address
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The password never goes in that file. On a Mac, store it in Keychain with this command, which asks for it:
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
security add-generic-password -s lit-reader -a you@example.com -w
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
On other systems, set the `LIT_READER_SMTP_PASSWORD` environment variable.
|
|
136
|
+
|
|
137
|
+
## Which source is used
|
|
138
|
+
|
|
139
|
+
**If you give a PDF, lit-reader reads that PDF.** Your file may be a particular version of the paper, such as an accepted manuscript, so it is never replaced by an online copy without your asking.
|
|
140
|
+
|
|
141
|
+
**If you give an identifier**, lit-reader uses the best source it can find: arXiv's HTML, then Europe PMC's full-text XML for open-access papers, then [ar5iv](https://ar5iv.labs.arxiv.org/)'s conversion, then arXiv's PDF. ar5iv is arXiv Labs' earlier HTML conversion, and lit-reader uses it only when arXiv says it has no HTML version of the paper. If arXiv is down, lit-reader says so and doesn't try ar5iv.
|
|
142
|
+
|
|
143
|
+
To change this, use `--route`:
|
|
144
|
+
|
|
145
|
+
| Option | What it does |
|
|
146
|
+
|---|---|
|
|
147
|
+
| `--route auto` | The default, as described above. |
|
|
148
|
+
| `--route online` | Prefers arXiv's HTML or Europe PMC's XML, even when you give a PDF. If neither is available, it falls back to your PDF. |
|
|
149
|
+
| `--route arxiv` | Uses arXiv's HTML, or ar5iv's conversion when arXiv has none. |
|
|
150
|
+
| `--route jats` | Uses Europe PMC's XML only. |
|
|
151
|
+
| `--route pdf` | Uses the PDF only. |
|
|
152
|
+
|
|
153
|
+
For example, `lit-reader paper.pdf --route online` looks for an online version of the paper in your PDF. It can only do this if the PDF's first page shows an arXiv ID or a DOI.
|
|
154
|
+
|
|
155
|
+
On every route, lit-reader sends an arXiv ID or DOI found on a PDF's first page to arXiv or Crossref to look up the title and authors. The PDF itself is never uploaded.
|
|
156
|
+
|
|
157
|
+
### What each source gives you
|
|
158
|
+
|
|
159
|
+
| Source | Best for | What to expect |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| arXiv HTML | arXiv papers | Real headings, linked citations and live tables. arXiv labels this format experimental, and some figures don't convert. The page links to the PDF for those. ar5iv's conversions can stop partway, which the coverage check shows. |
|
|
162
|
+
| Europe PMC XML | Open-access papers in Europe PMC | Real headings, linked citations and the publisher's figures. |
|
|
163
|
+
| PDF | Everything else | Text converted by Docling, with the original page numbers in the margin. Figures and tables are images cropped from the page. |
|
|
164
|
+
|
|
165
|
+
## Checking a reading copy
|
|
166
|
+
|
|
167
|
+
lit-reader compares the page with the source text and prints the result:
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
coverage: 95.6% of the 5438 words in the PDF's text reached the page
|
|
171
|
+
missing run of 58 words: the proportion of repeated layer 0 0 20 0 15 ...
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The check counts words, so it catches text that was lost but not text in the wrong order, such as two columns read across, or a misread equation. A missing run is a stretch of 25 or more source words that didn't reach the page. Runs of numbers and labels usually come from charts and tables, which is expected when they appear as images. A run of ordinary sentences means text was lost, so check that passage against the original. For a PDF, the reading copy then offers a "Show the original page" button at that page, for up to ten pages, and the build lists the pages it flagged.
|
|
175
|
+
|
|
176
|
+
Pages built from arXiv HTML or a PDF are compared with the PDF's text, which needs poppler. Without it, arXiv pages still build but skip the check. Pages built from Europe PMC are compared with the article's XML.
|
|
177
|
+
|
|
178
|
+
If a paper converts badly, please [open an issue](https://github.com/RobinKwong/lit-reader/issues) with its arXiv ID, DOI or a link to it.
|
|
179
|
+
|
|
180
|
+
## Reading on a phone
|
|
181
|
+
|
|
182
|
+
The reading copies lay out for a phone screen, but how you get one onto a phone matters, because a phone's preview of an attachment may not run the page's script.
|
|
183
|
+
|
|
184
|
+
- **iPhone:** use the EPUB. `--email` sends it to you; open the attachment from Mail and it goes into Books, or in the Gmail app choose Books from the share sheet. Apple Books gives you its own contents, footnote pop-ups, font settings and highlights. A single HTML file opened from the Gmail app on an iPhone shows the text, but the preview runs no script and can't follow links within the page, so the contents, citations and settings don't respond.
|
|
185
|
+
- **Android, or a laptop:** a `--single-file` copy opened in a browser works like the folder copy.
|
|
186
|
+
|
|
187
|
+
Where no script runs, a single file still shows the text, its time to read, footnotes under their paragraphs and each table's text version, and it hides the buttons that can't work.
|
|
188
|
+
|
|
189
|
+
## Limits and testing
|
|
190
|
+
|
|
191
|
+
lit-reader is tuned for academic papers, and it also handles other long PDFs with selectable text, such as dissertations and reports. A 370-page dissertation took about two minutes to convert on a Mac laptop.
|
|
192
|
+
|
|
193
|
+
- **Formats:** it accepts PDFs, arXiv IDs or URLs, DOIs and PMCIDs. It doesn't accept EPUB, Word, HTML, plain text or links to web articles.
|
|
194
|
+
- **DOIs:** a DOI only works when arXiv or Europe PMC has the full text openly available. For a book or a paywalled paper, supply the PDF.
|
|
195
|
+
- **Headings:** the contents sidebar depends on headings that look different from the body text. A plainly typeset manuscript may come through as one long section.
|
|
196
|
+
- **Scanned PDFs:** Docling recognises the text, but the coverage check can't run because the PDF has no text to compare against.
|
|
197
|
+
- **Figures and tables as images:** under each table in a PDF, a closed "as text" section holds Docling's reading of the table, for screen readers and small screens. It hasn't been checked by hand, and the page says so. In some Europe PMC papers, a screen reader can reach a table's caption but not its data. A chart's only description is its caption.
|
|
198
|
+
- **Citations and footnotes:** citation cards need a reference list that lit-reader can recognise. In PDFs, footnotes appear as small text after the paragraph instead of in the margin.
|
|
199
|
+
- **Equations:** arXiv pages keep real maths. Europe PMC pages use the article's maths if it has any, and otherwise its image of the equation or its TeX source. In PDFs, an equation Docling can read appears as plain text, so check it against the original. One it can't read appears as an image of the printed equation.
|
|
200
|
+
- **Screens:** lit-reader is designed for reading on a laptop or desktop, and pages also lay out for phones. The phone layout has been checked in a desktop browser's phone emulation. On a real iPhone, an EPUB in Apple Books and a single file in the Gmail app's preview have been tried, but not a single file in a phone's browser. A page needs the `assets` folder beside it unless you build it with `--single-file`. Each browser keeps its own quotes and reading position: a phone won't have what you saved on a laptop.
|
|
201
|
+
- **Browsers:** reading copies have been checked in Chrome. A bundle's index reads each paper's quotes and finished mark from browser storage, which works when the browser shares storage between local files in one folder, as Chrome does. Safari and Firefox are untested.
|
|
202
|
+
- **E-readers:** EPUB copies pass structural checks and open in Apple Books on an iPhone, but haven't been tested on a Kindle yet. How maths and wide tables look depends on the e-reader.
|
|
203
|
+
- **Languages:** accented Latin text comes through correctly, but pages are marked as English and line-break repair uses an English word list. Right-to-left scripts and Chinese, Japanese and Korean are untested.
|
|
204
|
+
|
|
205
|
+
## Privacy
|
|
206
|
+
|
|
207
|
+
lit-reader uses no AI service, analytics or account. Conversion happens on your machine, reading copies load nothing from the internet, and your settings, reading position and saved quotes stay in your browser. It uses the network only in these cases:
|
|
208
|
+
|
|
209
|
+
- **Fetching a paper:** an arXiv ID, DOI or PMCID is sent to arXiv, ar5iv, Crossref or Europe PMC, and the paper comes back.
|
|
210
|
+
- **Looking up a local PDF:** an arXiv ID or DOI found on the first page is sent to arXiv or Crossref to find the title and authors. This happens on every route, including `--route pdf`, and can't be turned off. The PDF itself is never uploaded.
|
|
211
|
+
- **Emailing a copy:** with `--email`, the copy is sent through the mail server in your settings, logging in over an encrypted connection.
|
|
212
|
+
- **Installing:** uv downloads lit-reader, and Docling downloads its models the first time it runs.
|
|
213
|
+
- **Following a link:** links in a reading copy open in your browser like any other link.
|
|
214
|
+
|
|
215
|
+
## Copyright
|
|
216
|
+
|
|
217
|
+
Reading copies are for your own use. The MIT licence below covers this software, not the papers you convert, which keep their own copyright and licences. Please don't redistribute reading copies of paywalled papers. A reading copy made from a PDF includes a copy of that PDF in its folder, so take particular care when sharing one. A single file or an EPUB copy doesn't include the PDF, but it does include the paper's full text and figures, so the same care applies. A bundle's folder and its EPUB hold every paper in the bundle, which matters when you hand one to a reading group.
|
|
218
|
+
|
|
219
|
+
## Licence
|
|
220
|
+
|
|
221
|
+
lit-reader is released under the [MIT licence](https://github.com/RobinKwong/lit-reader/blob/main/LICENSE). It includes the Literata typeface, which is licensed under the [SIL Open Font License](https://github.com/RobinKwong/lit-reader/blob/main/src/lit_reader/fonts/OFL.txt).
|
|
222
|
+
|
|
223
|
+
## Changelog
|
|
224
|
+
|
|
225
|
+
### v1.2
|
|
226
|
+
|
|
227
|
+
v1.2 reads several papers as one set.
|
|
228
|
+
|
|
229
|
+
- **Bundles.** `lit-reader bundle <file>` builds every paper listed in a text file into one folder, with an index page showing which papers you've started or finished and how many quotes you've saved from each. A paper that can't be converted is listed with the reason and what to do, and the rest are still built.
|
|
230
|
+
- **Moving between papers.** Each paper's top bar shows its place in the bundle ("3 of 7"). A citation of another paper in the bundle links to its reading copy, and that paper's bar then offers the way back to the citation.
|
|
231
|
+
- **Quotes across the bundle.** The index downloads or copies every saved quote as one Markdown file, grouped by paper with each one's citation.
|
|
232
|
+
- **One EPUB for the bundle.** `--epub bundle` writes one book holding every paper, with the bundle's contents first and references between its papers linked. `--epub both` also writes one EPUB per paper.
|
|
233
|
+
- **A thinner bar on a phone.** The top bar holds only the contents button and the reading status, and steps aside as you scroll down. All papers, Quotes and the reading settings sit at the top of the contents drawer.
|
|
234
|
+
- **Smaller changes.** "Finished" on the index now has enough contrast in every theme, and marking a paper finished is announced to screen readers.
|
|
235
|
+
|
|
236
|
+
### v1.1
|
|
237
|
+
|
|
238
|
+
v1.1 takes the reading copies off the laptop, onto a phone or an e-reader, and lets you keep quotes from what you read.
|
|
239
|
+
|
|
240
|
+
- **Reading on a phone.** Pages lay out for a phone screen. Citations open in a sheet along the bottom, the contents sit in a drawer, buttons are sized for touch, and tapping a figure or table opens it full screen.
|
|
241
|
+
- **Copies to take with you.** `--epub` writes an EPUB for Apple Books or a Kindle. `--single-file` writes the reading copy as one HTML file that survives being emailed and still shows its text where no script runs. `--email` sends either copy to you through your own mail account, and `lit-reader setup-email` sets that up.
|
|
242
|
+
- **Saved quotes.** Select a passage and save it with its author, year and page, then copy it or download all your quotes as Markdown. A tip on your first few papers points out the feature, the Quotes panel and the end of the paper remind you of quotes you haven't downloaded, and a removed quote can be restored until the panel closes.
|
|
243
|
+
- **More of the paper, and a check on what's missing.** When arXiv has no HTML version of a paper, lit-reader tries ar5iv's conversion before the PDF. Where a PDF page lost ordinary sentences, the reading copy offers that page as printed. Under each table from a PDF, an unchecked text version helps screen readers and small screens.
|
|
244
|
+
- **Cleaner PDF conversions.** A footnote that runs over a page break is joined back together, a numbered list of affiliations no longer splits the paragraph around it, and a summary in run-in labels (Science's "INTRODUCTION:", "RATIONALE:" and so on) gets its own heading in the contents, with an "Introduction" heading where the untitled article begins.
|
|
245
|
+
- **Smaller changes.** On a laptop, the Contents button hides the sidebar. Clicking a citation whose card is already showing goes on to the reference list. "Go to reference list" leaves a button back to where you were, and the contents show "6 min" rather than "6′". "Mark as finished" sits where the main text ends, before any appendix and the references. EPUBs aren't hyphenated, to match the reading copies.
|
|
246
|
+
|
|
247
|
+
### v1.0
|
|
248
|
+
|
|
249
|
+
The first public release, on 18 November 2026, first numbered 0.1.0. It turns a PDF, arXiv ID or URL, DOI or PMCID into an offline reading copy from arXiv's HTML, Europe PMC's XML or the PDF. The copy has reflowed text, a contents sidebar with the minutes in each section, citation cards, sidenotes, the printed page numbers, reading settings and a saved reading position. Each build reports how much of the source's text reached the page.
|
|
Binary file
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "lit-reader"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Turn academic papers into offline HTML reading copies."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE", "src/lit_reader/fonts/OFL.txt"]
|
|
13
|
+
authors = [{ name = "Robin Kwong" }]
|
|
14
|
+
keywords = ["academic papers", "reading", "arxiv", "pdf", "html"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Operating System :: MacOS",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Topic :: Text Processing :: Markup :: HTML",
|
|
21
|
+
]
|
|
22
|
+
dependencies = []
|
|
23
|
+
|
|
24
|
+
[project.urls]
|
|
25
|
+
Repository = "https://github.com/RobinKwong/lit-reader"
|
|
26
|
+
Issues = "https://github.com/RobinKwong/lit-reader/issues"
|
|
27
|
+
Changelog = "https://github.com/RobinKwong/lit-reader#changelog"
|
|
28
|
+
|
|
29
|
+
[project.scripts]
|
|
30
|
+
lit-reader = "lit_reader.core:main"
|
|
31
|
+
|
|
32
|
+
[tool.hatch.version]
|
|
33
|
+
path = "src/lit_reader/__init__.py"
|
|
34
|
+
|
|
35
|
+
[tool.hatch.build.targets.sdist]
|
|
36
|
+
include = ["src/lit_reader", "tests", "docs", "README.md", "LICENSE", "pyproject.toml"]
|
|
37
|
+
|
|
38
|
+
[tool.hatch.build.targets.wheel]
|
|
39
|
+
packages = ["src/lit_reader"]
|