aeosynth/bk

Terminal Epub reader

bk

bk is a terminal EPUB reader, written in Rust.

Features

• Cross platform - Linux, macOS and Windows support
• Single binary, instant startup
• EPUB 2/3 support
• Vim bindings
• Incremental search
• Bookmarks

Install

Install from crates.io:

cargo install bk

or from github:

git clone https://github.com/aeosynth/bk
cargo install --path bk

Usage

Usage: bk [<path>] [-m] [-t] [-w <width>]

read a book

Options:
  --bg              background color (eg 282a36)
  --fg              foreground color (eg f8f8f2)
  -m, --meta        print metadata and exit
  -t, --toc         start with table of contents open
  -w, --width       characters per line
  --help            display usage information

Running bk without a path will load the most recent EPUB.

Type any function key (eg F1) to see the keybinds.

Check if your terminal supports italics:

echo -e "\e[3mitalic\e[0m"

Comparison

	bk	epr/epy
runtime deps	❌	python, curses
wide characters	✔️	❌
incremental search	✔️	❌
multi line search	✔️	❌
regex search	❌	✔️
links	✔️	❌
images	❌	✔️
themes	✔️	✔️
choose file from history	❌	✔️
additional formats	❌	FictionBook, Mobi, AZW3
external integration	see 1	dictionary

1: you can use the --meta switch to use bk as a file previewer with eg nnn

Inspiration

https://github.com/wustho/epr

bk's Issues

inline styles are buggy

<em><strong>test</strong></em>

if this text is at the top of the screen it will only be bolded, not italicized. i think instead of creating a list of (position, attribute) tuples, we need (position, state), where state is a bitmask of (bold | italic). this way we can 'rehydrate' from any point.

clicking links

we should explore ways to make links easier to click, those single character footnotes are annoying.

• make the hitbox larger by a fixed amount (1 col/row padding)

• partition the screen into hitboxes, visually selecting a link on mouse move. example: tiling window manager.

keyboard selection seems solved, a key to highlight and label all links, type the label to follow

Release it as a binary on github

Thank you for your work. Eager to try this to compare to epr.
Would it be possible to release it as a binary ? At least compiled for x86_64.
It would make it much easier to release this as a precompiled package (as an alternative to a source package) for arch linux and other distros. It would make much easier for people who dont have / dont want to download the 500 mega rust distribution just to quickly try it out.

Also, think of low spec devices like less powered old laptops or the Rasbperry Pi, where constantly recompiling compiling may not be that desirable

bold reset = double underline

apparently nobold is inconsistent, sometimes treated as double underline. will have to go back to using reset everywhere, or maybe normalintensity

affects at least: kitty, gnome-terminal, xterm, termite, xfce4-terminal

bk on NetBSD

FYI, I've packaged bk for NetBSD.
Due to the on-going package freeze ahead of the Q4-release, the package is currently in the WIP-repo, https://mail-index.netbsd.org/pkgsrc-wip-changes/2020/12/22/msg018889.html

Once the freeze is over, I'll import the package into the main branch.

Name duplicate with bitkeeper

In the void linux distribution there is also a package called as bk.
https://github.com/bitkeeper-scm/bitkeeper

no associated item named `Down` found for struct `MouseEvent`

bk (master)$ cargo install --path .
  Installing bk v0.5.1 (/home/roman/personal_projects/vendor/bk)
    Updating crates.io index
   Compiling bk v0.5.1 (/home/roman/personal_projects/vendor/bk)
error[E0599]: no associated item named `Down` found for struct `MouseEvent` in the current scope
   --> src/view.rs:136:25

Request: be more permissive with poorly formatted epub

In books converted from .lit with clit I get:
thread 'main' panicked at 'called Option::unwrap() on a None value', /home/user/.cargo/registry/src/github.com-1ecc6299db9ec823/bk-0.5.3/src/epub.rs:139:41
epr says AttributeError: 'Epub' object has no attribute 'toc'

Also as in issue #13 / #25, not sure anything can be done outside of roxmltree though
thread 'main' panicked at 'called Result::unwrap() on an Err value: UnknownEntityReference("lsquo", TextPos { row: 11, col: 35 })', /home/user/.cargo/registry/src/github.com-1ecc6299db9ec823/bk-0.5.3/src/epub.rs:57:63

Both of the above are readable with Moon+ Reader on Android. It would be nice if bk could be a little more permissive.

New release

Hello,

thanks for the great console reader. Could you please make a release after all the changes taken since 2021?

Also, is this project abandoned? If yes, it would be great shame and pity, since it's the only console reader I'm aware of, which is not written in python. And python is, you know, slow and greedy.

[Feature Request] Use human identifiable colors

Thank you for your work on bk. I've only been using this app to read epub, ever since I'd first tried.

I appreciate you adding the ability to define colors (hex codes) for background and foreground. While that's an improvement, it is still very difficult to get hex codes for colors when I'm not on a computer. I would suggest to add human readable/writable color names, like, Graphicsmagick's Color Names. While at it, I'd like some preset themes added, as implemented by another rust project - bat.

I haven't worked on a rust project before, so, it does seem like a good time to pick it up.

Handling whitespace in text content

bk currently doesn't handle whitespace properly.
The default behaviour in browsers is to collapse spaces in some tags (e.g. <p>). As an example, if you have:

<p>This is a
test.</p>

You should end up with This is a test. on output.
Instead, the embedded newline is left in.

Error for a specific epub

i recently when playing around with bk encountering a mysterious bug:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: UnknownEntityReference("rsquo", TextPos { row: 12, col: 36 })', /home/kaito/.cargo/registry/src/github.com-1ecc6299db9ec823/bk-0.5.3/src/epub.rs:57:63
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace .

i though first that the problem was coming from the epub which may be corrupted, but i found that it can be read with other terminal reader like epr
i really like this project and i want to use it to read epub, but this limitation makes it harder to use

Move cursor with table of contents

If you activate the table of contents with tab, the hardware cursor isn't put on the selected item.
This makes it impossible to find your location if using a screen reader or braille display.
The cursor should be able to be moved even while still hidden.

Visual feedback on adding marks?

Just a suggestion, what do you think about having some visual feedback on adding marks? Like, showing a short info message at the bottom after adding a mark, e.g., Mark 'a' set?

terminal hyperlinks

https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
my terminal (alacritty) supports this now

Losing text

bk loses the last portion of the section in some cases.
See the attached test epub file, viewed with bk -w 75.

If there's a br at the end, it works correctly.
test.zip

Key documentation

I found

bk/src/view.rs

Lines 80 to 103 in 8d52778

	let text = r#"
	Esc q Quit
	Fn Help
	Tab Table of Contents
	i Progress and Metadata
	PageDown Right Space f l Page Down
	PageUp Left b h Page Up
	d Half Page Down
	u Half Page Up
	Down j Line Down
	Up k Line Up
	Home g Chapter Start
	End G Chapter End
	[ Previous Chapter
	] Next Chapter
	/ Search Forward
	? Search Backward
	n Repeat search forward
	N Repeat search backward
	mx Set mark x
	'x Jump to mark x
	"#;

in the source code, but I didn't find out how to display this help page in bk itself.
What is "Fn"? I had tried 'h' and '?', but I see that these do something else.
Can you please add mention the key to get help in the bk -h output?

Thank you!

html entities problem

I have epub from https://helion.pl and could not read it with bk.

I have modified the epub file like here https://github.com/kisswiki/kisswiki/blob/master/src/00other/epub_bk_reader_html_entities.md

Maybe this could be handled automatically?

Strange double underline which dissapears after scroll

And here after scroll:

[question] will there be a new public release?

Compiling from source is really smoothly but an updated release would help me in requesting the Void Linux -the O.S. I use- maintainers to have bk added as an official package in the distribution repository.
I want to do this because bk is the best terminal epub reader I've tried to date :-)
Thank you for this really well thought out project!

Termux Porting Problem while reading

thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/epub.rs:261:18
stack backtrace:
   0:       0x602ab7a378 - <unknown>
   1:       0x602ab932a8 - <unknown>
   2:       0x602ab62dd8 - <unknown>
   3:       0x602ab7b980 - <unknown>
   4:       0x602ab7b4f4 - <unknown>
   5:       0x602ab7c108 - <unknown>
   6:       0x602ab7bbf4 - <unknown>
   7:       0x602ab7a470 - <unknown>
   8:       0x602ab7bb88 - <unknown>
   9:       0x602ab923a8 - <unknown>
  10:       0x602ab9232c - <unknown>
  11:       0x602ab36070 - <unknown>
  12:       0x602ab2b084 - <unknown>
  13:       0x602ab1ef6c - <unknown>
  14:       0x602ab1ef80 - <unknown>
  15:       0x602ab7c3b8 - <unknown>
  16:       0x602ab2cb74 - <unknown>
  17:       0x7f196de79c - <unknown>  

cpu usage on mousemove

rearrange the render loop to not rerender on mousemove

[Feature request] Images

It really isn't a fully featured experience without the ability to view images in some way.
For some (non-fiction) books it is kind of a necessity.

If it is too much to incorporate some sort of terminal image viewing like sixel or ueberzug, then at least give us the ability to press the [IMG] to open it in our default image viewer (xdg-open).

Support for coming back from link jumps

So I've been reading a book that is full of footnotes. The footnotes themselves link to appendices. And appendices themselves have links to other parts of the book.
In such kind of book, as Quality of Life improvement to the reader, is keeping a mark for the return of each jump, as the current code allow with the ' mark, but that allows only for one jump.
The backspace could be bound to this move.
It is similar to what Ctrl + O does on vim.

Crash on startup

Terminal: foot
OS: Gentoo
on Wayland

thread 'main' panicked at /home/rat/.cargo/registry/src/index.crates.io-6f17d22bba15001f/bk-0.6.0/src/epub.rs:60:63:
called `Result::unwrap()` on an `Err` value: UnknownEntityReference("nbsp", TextPos { row: 12, col: 32 })
stack backtrace:
   0: rust_begin_unwind
             at /rustc/07dca489ac2d933c78d3c5158e3f43beefeb02ce/library/std/src/panicking.rs:645:5
   1: core::panicking::panic_fmt
             at /rustc/07dca489ac2d933c78d3c5158e3f43beefeb02ce/library/core/src/panicking.rs:72:14
   2: core::result::unwrap_failed
             at /rustc/07dca489ac2d933c78d3c5158e3f43beefeb02ce/library/core/src/result.rs:1649:5
   3: bk::epub::Epub::new
   4: bk::main

Wishlist and thanks

bk is exactly what I was looking for, a terminal epub reader that is easy to install on any platform or architecture. Thanks for your work!

Just wanted to comment on the to-do list you posted in the README and add a few random ideas:

• configuration: key options would be number of columns to show, font size, font colour, background colour, line spacing, possibly font family
• pan/zoom/reset keybindings (useful to zoom on an image); not necessarily with dynamic text wrapping (this could be slow and the configuration file could be used to change font size and rewrap text when relaunching bk, or maybe add another keybinding to update configuration file according to the current viewing options)
• double column option (terminals windows are most often wider than tall, yet reading narrow text is easier, so double columns would allow easy reading while keeping a bit more context visible if the reader wants to go back to a previous sentence)
• command line options to go directly to table of contents, to a given page, or to a given chapter
• command line option to show the total number of pages, author, year or any other metadata
• highlight keywords found when searching
• images? Yes please, would be very useful for books with maps or charts
• gui? As long as the extra dependencies are not mandatory to install and use the terminal version
• mobi? I don't have any but I can see how that could be useful to many people
• css? I'm not sure what are the implications for an epub reader; more customization options?
• html? Same
• better unicode support? I didn't face any issue so far but I am just a few hours in

This is just my humble wishlist (yet long, I know, but no preessure, I'm enjoying bk already with its minimal features), thanks!

Losing text with A tag

More lost text, this time the text in the A tag, if it has no href.

test.zip