# Bibiman
[](https://matrix.to/#/#bibiman-tui:matrix.org)
## TL;DR
`bibiman` is a simple terminal user interface for handling your BibLaTeX
database as part of a terminal-based scientific workflow.
Here's a small impression how it looks and works:
[](https://postimg.cc/56Xvz3z4)
## Installation
You can install `bibiman` directly from `crates.io` using `cargo`:
```bash
cargo install bibiman
```
To use the version including the newest commits, you can clone the repo and
build it from source using `cargo`:
```bash
git clone https://codeberg.org/lukeflo/bibiman
cd bibiman
# Build the binary to /target/release
cargo build --release
# OR
# Install the binary to CARGO_HOME/bin which normally is in PATH
cargo install --path=. --locked
```
## Usage
The following arguments are possible:
```
USAGE:
bibiman [FLAGS] [files/dirs]
POSITIONAL ARGS:
Path to .bib file
Path to directory containing .bib files
FLAGS:
-h, --help Show this help and exit
-v, --version Show the version and exit
--light-terminal Enable color mode for light terminal background
```
As seen, you can pass a single file, multiple files, the path of a directory
containing bibfiles, or mix files and directories.
Directories will be searched recursively for files with the `.bib` extension and
add them to the entry list. Other files will be ignored.Thus, be careful not to
pass a directory with multiple subdirectories (like eg `/home/usr/`), because
this could lead to some delay while parsing GBs of data.
The following lines are all valid CLI calls to run `bibiman` using the test
files from the `tests` folder:
```bash
# single file
bibiman tests/biblatex-test.bib
# multiple files
bibiman tests/multi-files/bibfile1.bib tests/multi-files/bibfile2.bib
# directory containing bibfiles
bibman tests/multi-files/
# mixed arguments
bibiman tests/biblatex-test.bib tests/multi-files/
```
Here as small demo gif which shows different ways of loading files/dirs:
[](https://postimg.cc/DmpgXmST)
Furthermore, in issue #3 it was asked to enable a color customization to run
`bibiman` also in terminal setups with light background. Thus, now it is
possible to enable a light terminal mode with the `--light-terminal` flag. Full
color customization is not possible right now, but maybe will be added with the
implementation of a config file.
Here is how the light terminal scheme looks:
## Features
These are the current features, the list will be updated:
- [x] **Browse** through the bib entries using _Vim-like keybindings_ and a
_fuzzy search_ mode.
- [x] **Filter** the bib entries by _keywords_ (and afterwards filter further by
fuzzy searching).
- [x] **Edit** the current entry by opening a _terminal-based editor_ at the
specific line.
- [x] **Yank/Copy** the citekey of the current entry to the system clipboard.
- [x] **Open related PDF** file (`file` BibLaTeX key) with keypress.
- [x] **Open related URL/DOI** with keypress.
- [x] **Scrollbar** for better navigating.
- [x] **Sort Entries** by column (`Authors`, `Title`, `Year`, `Pubtype`), or by
position in bibfile.
- [x] **Load multiple files** into one session.
- [x] **Add Entry via DOI**.
- [ ] **Open related notes file** for specific entry.
- [ ] **Implement config file** for setting some default values like main
bibfile, PDF-opener, or editor
- [ ] **Support Hayagriva(`.yaml`)** format as input (_on hold for now_, because
the Hayagriva Yaml style doesn't offer keywords; s. issue in
[Hayagriva repo](https://github.com/typst/hayagriva/issues/240)).
**Please feel free to suggest further features through the issue
functionality.**
## Keybindings
Use the following keybindings to manage the TUI:
| Key | Action |
| ---------------------------------------- | -------------------------------------------------------- |
| `?` | Open help popup with keybindings |
| `j`, `k` \| `Down`, `Up` | Move down/up by 1 |
| `Ctrl-d`, `Ctrl-u` | Move down/up by 5 |
| `g`, `G` | Go to first/last entry |
| `h`, `k` \| `Left`, `Right` | Select previous/next entry column |
| `s` | Sort entries by current column (toggles) |
| `S` | Sort entries by position in file |
| `PageDown`, `PageUp` \| `Alt-j`, `Alt-k` | Scroll Info window |
| `y` | Yank/copy citekey of selected entry |
| `e` | Open editor at selected entry |
| `a` | Add entry through DOI |
| `o` | Open related PDF or URL/DOI |
| `TAB` | Switch between entries and keywords |
| `/`, `Ctrl-f` | Enter search mode |
| `Enter` | Filter by selected keyword / Confirm search or selection |
| `ESC` | Abort search / Reset current list |
| `q`, `Ctrl-c` | Quit TUI |
## Search
The search mode uses the `nucleo-matcher` crate. Thus, _fuzzy searching_ is
enabled by default. You can use some special chars to alter pattern matching:
- `^...` matches literally at beginning of the string.
- `...$` matches literally at end of the string.
- `'...` matches literally everywhere in string.
## Edit bib entry
For now, the TUI only supports editors set through the environment variables
`VISUAL` and `EDITOR` in this order. The fallback solution is `vi`.
I've tested the following editors (set as value of `VISUAL`):
- [x] **Helix**: `export VISUAL="hx"`
- [x] **Vim/Neovim**: `export VISUAL="vim/nvim"`
- [x] **Emacs (Terminal)**: `export VISUAL="emacs -nw"`
- [x] **Nano**: `export VISUAL="nano"`
- [x] **Emacs (GUI)**: `export VISUAL="emacs"` (open emacs in separate window,
blocks the terminal running `bibiman` as long as emacs is opened)
Feel free to try other editors and report. Important is that the editor supports
the argument `+..` to set the line number that the cursor should be placed at.
Otherwise, the functionality might not work properly.
While this behaviour is most likely supported on UNIX-based systems (Linux,
MacOS), it might not work under Windows. I can't test it on a Windows machine,
thus, there might be unexpected errors with it.
## Open connected files or links
`bibiman` also provides the possibility to open PDFs (as value of the `file`
BibLaTeX field), as well as DOIs and URLs.
For selecting the right program, it uses `xdg-open` on Linux, `open` on MacOS,
and `start` on Windows. Thanks to the report from @bastislack in #2 MacOS seems
to work.
_However, Windows does not work. Have to figure this out. Reports from some
Windows users are very welcome._
Furthermore, DOIs have to begin with either `https://doi...` as full URL or
`10.(...)` as regular DOI style. URLs work if they begin with either `http...`
or with `www...`.
## Issues and code improvement
This is my first Rust project and, thus, also a learning process. If you find
any issues or code flaws, please open an issue.
## Alternatives
`bibiman` is a project tailored to my personal needs. I use a single main file
for all my bib entries and want to use `bibiman` mainly as kind of
(terminal)-graphical wrapper for often emerging tasks, since I work in the
terminal most of the time.
I used `JabRef` for many years, but its way to bloated in my eyes. There exists
a bunch of other graphical tools...
But there are also some TUI alternatives with slightly different approaches.
Maybe one of these might fit _your_ personal needs better:
- [bibman (Haskell)](https://codeberg.org/KMIJPH/bibman): A very nice CLI
program including a TUI I also used for some times. It has way more CLI
features (export etc.) at the moment.
- [bibman (Python)](https://github.com/ductri/bibman): A TUI written in Python
with focus on Zotero-like functions. If you're used to Zotero, this might be a
good fit.
- [bibman (Perl)](https://github.com/maciejjan/bibman): A fast and simple TUI
written in good ol' Perl. It looks like back in the days, but seems not being
maintained anymore.
- [cobib](https://github.com/mrossinek/cobib): Very elaborated bib manager with
CLI and TUI functions.
- [papis](https://github.com/papis/papis): Powerful CLI tool for managing
bibliographies and documents. Has also some TUI features.
### Comparison
I compared `bibiman` only free-hand to `bibman` (Haskell) and `bibman` (Perl),
since there is no simple benchmark test for TUIs. At least, I couldn't find one.
Loading a test file containing 25.000 dummy entries as well as a directory
containing 25.000 single dummy `.bib` files `bibiman` was significantly faster
on startup than both other programs. The performance also did not suffer. Only
on a test file with more than 50.000 dummy entries a very short delay after
keypresses was recognizable when scrolling the entry list.
After all, `bibiman` is really fast and runs very smooth while having the most
complex user interface by far compared to the other programs.