aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorlukeflo2024-10-07 11:01:50 +0200
committerlukeflo2024-10-12 22:41:38 +0200
commit8226331926bd0d1b4944fac537fbac32528818fe (patch)
treef1708aa2ddf7daa89de69fd17c4eb0aa5fbc1de4 /README.md
parent7f4f17680bcf23b2eb0d265cc9f35a9403f5537e (diff)
downloadbibiman-8226331926bd0d1b4944fac537fbac32528818fe.tar.gz
bibiman-8226331926bd0d1b4944fac537fbac32528818fe.zip
format README, fix typos
Diffstat (limited to 'README.md')
-rw-r--r--README.md126
1 files changed, 78 insertions, 48 deletions
diff --git a/README.md b/README.md
index 7ea3b84..5847a80 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,16 @@
# Bibiman
-`bibiman` is a simple terminal user interface for handling your BibLaTeX database as part of a terminal-based scientific workflow.
+`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:
-![A demo gif of bibiman](./img/bibiman-demo-vhs.gif)
+![A demo gif of bibiman](./img/bibiman-demo-vhs.gif)
## Installation
-For now, `bibiman` is only available via Codeberg. You have to build it from source yourself using `cargo` and `rustup`:
+For now, `bibiman` is only available via Codeberg. You have to build it from
+source yourself using `cargo` and `rustup`:
```bash
git clone https://codeberg.org/lukeflo/bibiman
@@ -17,16 +19,17 @@ cd bibiman
# Build the binary to /target/release
cargo build --release
-# OR
-# Install the binary to CARGO_HOME which normally is in PATH
-cargo install --path=. --locked
-
# optional: create symlink:
ln -sf /target/release/bibiman ~/.local/bin
+# OR
+# Install the binary to CARGO_HOME/bin which normally is in PATH
+cargo install --path=. --locked
+
```
-If you use the symlink option, you have to make sure that the directory containing the symlink is in your `PATH`.
+If you use the symlink option, you have to make sure that the directory
+containing the symlink is in your `PATH`.
## Usage
@@ -34,77 +37,104 @@ You need to pass a single `.bib` file as first positional argument:
`bibiman /path/to/bibfile.bib`
-Of course, this can be aliased if you only use one main file. E.g. in `.bashrc`/`.zshrc`:
+Of course, this can be aliased if you only use one main file. E.g. in
+`.bashrc`/`.zshrc`:
`alias bibi=bibiman /path/to/bibfile.bib`
## Features
-For now, `bibiman` only has some very basic features implemented which are important for my personal workflow:
+For now, `bibiman` only has some very basic features implemented which are
+important for my personal workflow:
-+ **Browse** through the bib entries using *Vim-like keybindings* and a *fuzzy search* mode.
-+ **Filter** the bib entries by *keywords* (and afterwards filter further by fuzzy searching).
-+ **Edit** the current entry by opening a *terminal-based editor* at the specific line
-+ **Yank/Copy** the citekey of the current entry to the system clipboard.
+- **Browse** through the bib entries using _Vim-like keybindings_ and a _fuzzy
+ search_ mode.
+- **Filter** the bib entries by _keywords_ (and afterwards filter further by
+ fuzzy searching).
+- **Edit** the current entry by opening a _terminal-based editor_ at the
+ specific line
+- **Yank/Copy** the citekey of the current entry to the system clipboard.
Furthermore, I want to implement the following features:
- [ ] **Open PDF**: Open related PDF file (`file` BibLaTeX key) with keypress.
- [ ] **Open URL/DOI**: Open related DOI/URL with keypress.
-- [ ] **Add Entry via DOI**: Download bibliographic metadata for inserted DOI and add it to `.bib` file
+- [ ] **Add Entry via DOI**: Download bibliographic metadata for inserted DOI
+ and add it to `.bib` file
## Keybindings
Use the following keybindings to manage the TUI:
-| Key | Action |
-|--------------- | --------------- |
-| **j/k** \| **Down/Up** | Move selected list |
-| **g/G** | Go to first/last entry |
-| **y** | Yank/copy citekey of selected entry |
-| **e** | Open editor at selected entry |
-| **TAB** | Switch between entries and keywords |
-| **/** \| **Ctrl+f** | Enter search mode |
-| **Enter** | Filter by selected keyword / Confirm search |
-| **ESC** | Abort search / Reset current list |
-| **q** \| **Ctrl-C** | Quit TUI |
+| Key | Action |
+| -------------------------- | ------------------------------------------- |
+| **`j/k`** \| **`Down/Up`** | Move selected list |
+| **`g/G`** | Go to first/last entry |
+| **`y`** | Yank/copy citekey of selected entry |
+| **`e`** | Open editor at selected entry |
+| **`TAB`** | Switch between entries and keywords |
+| **`/`** \| **`Ctrl+f`** | Enter search mode |
+| **`Enter`** | Filter by selected keyword / Confirm search |
+| **`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:
+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 only the beginning of the string.
-+ `...$` matches only the end of the string.
-+ `'...` matches literally (no fuzzy 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`.
+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)
+- [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. 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.
+Feel free to try other editors. 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.
-Since 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.
+Since 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.
## 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. I plan to make PRs possible in the future when its a little bit less early alpha state.
+This is my first Rust project and, thus, also a learning process. If you find
+any issues or code flaws, please open an issue. I plan to make PRs possible in
+the future when its a little bit less early alpha state.
## 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. Just check it yourself...
-
-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 features (export etc.) at the moment. The main difference is that its based on a multi file approach. If you also use a separate file per entry, look there!
-+ [bibman (Python)](https://github.com/ductri/bibman): A TUI written in Python with focus on Zotero-like functions. If you're uses 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
+`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. Just check it yourself...
+
+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. The main difference is that its based on
+ a multi file approach. If you also use a separate file per entry, look there!
+- [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