add man pages & justfile to organiseman

3 files changed, 457 insertions, 0 deletions

diff --git a/justfile b/justfile
new file mode 100644
index 0000000..4094b20
--- /dev/null
+++ b/justfile
@@ -0,0 +1,76 @@
+# Justfile for bibiman
+
+# Installation directories
+PREFIX := "/usr/local"
+MANDIR := PREFIX + "/man"
+BINDIR := PREFIX + "/bin"
+
+# Default recipe
+default: build
+
+# Build the binary in release mode
+build:
+    cargo build --release
+
+# Development build
+dev:
+    cargo build
+
+# Run the binary in development mode
+run: dev
+    cargo run
+
+# Install the binary and man pages
+# Note: Requires sudo when installing to system directories
+install: build
+    #!/usr/bin/env sh
+    set -eu
+    install -D target/release/bibiman "${DESTDIR:-}"{{BINDIR}}/bibiman
+    install -D man/bibiman.1 "${DESTDIR:-}"{{MANDIR}}/man1/bibiman.1
+    install -D man/bibiman.toml.5 "${DESTDIR:-}"{{MANDIR}}/man5/bibiman.toml.5
+    echo "Installation complete. Run 'sudo mandb' to update man page database if needed."
+
+# Install only man pages
+# Note: Requires sudo when installing to system directories
+install-man:
+    #!/usr/bin/env sh
+    set -eu
+    install -D man/bibiman.1 "${DESTDIR:-}"{{MANDIR}}/man1/bibiman.1
+    install -D man/bibiman.toml.5 "${DESTDIR:-}"{{MANDIR}}/man5/bibiman.toml.5
+    echo "Man pages installed. Run 'sudo mandb' to update man page database if needed."
+
+# Uninstall
+uninstall:
+    #!/usr/bin/env sh
+    set -eu
+    rm -f "${DESTDIR:-}"{{BINDIR}}/bibiman
+    rm -f "${DESTDIR:-}"{{MANDIR}}/man1/bibiman.1
+    rm -f "${DESTDIR:-}"{{MANDIR}}/man5/bibiman.toml.5
+
+# Clean build artifacts
+clean:
+    cargo clean
+
+# Run tests
+test:
+    cargo test
+
+# Format code
+fmt:
+    cargo fmt --all
+
+# Run clippy lints
+clippy:
+    cargo clippy -- -D warnings
+
+# Check the code
+check:
+    cargo check
+
+# Build and run with test files
+test-run: dev
+    cargo run -- tests/biblatex-test.bib
+
+# Show available recipes
+list:
+    just --list
\ No newline at end of file
diff --git a/man/bibiman.1 b/man/bibiman.1
new file mode 100644
index 0000000..dce1b32
--- /dev/null
+++ b/man/bibiman.1
@@ -0,0 +1,197 @@
+.TH BIBIMAN 1 "2024-12-19" "bibiman 0.13.1" "User Commands"
+.SH NAME
+bibiman \- TUI for interacting with BibLaTeX databases
+.SH SYNOPSIS
+.B bibiman
+[\fIOPTIONS\fR] [\fIFILE\fR]...
+.br
+.B bibiman
+[\fIOPTIONS\fR] [\fIDIRECTORY\fR]...
+.SH DESCRIPTION
+bibiman is a simple terminal user interface for handling your BibLaTeX
+database as part of a terminal-based scientific workflow. It provides a
+TUI for browsing, searching, editing, and managing bibliography entries
+with Vim-like keybindings and fuzzy search capabilities.
+.SH OPTIONS
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Show this help and exit
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Show the version and exit
+.TP
+\fB\-c\fR, \fB\-\-config\-file\fR=\fIVALUE\fR
+Path to config file used for current session.
+Takes precedence over standard config file.
+.TP
+\fB\-\-light-terminal\fR
+Enable color mode for light terminal background
+.TP
+\fB\-\-pdf-path\fR=\fIVALUE\fR
+Use PDF files named by citekey at the given path and its
+subdirs as value for the `file` field of the entry matching
+the citekey for the current session.
+Does not overwrite or change the original file.
+(might not work with citekeys containing special chars)
+.SH ARGUMENTS
+.TP
+\fIFILE\fR
+Path to .bib file
+.TP
+\fIDIRECTORY\fR
+Path to directory containing .bib files
+.SH CONFIGURATION
+bibiman can be configured through a config file. The standard location is:
+.RS
+.IP
+$XDG_CONFIG_HOME/bibiman/bibiman.toml
+.RE
+.IP
+Or as fallback:
+.RS
+.IP
+$HOME/.config/bibiman/bibiman.toml
+.RE
+.SS General Configuration
+The following values can be set in the config file:
+.TP
+bibfiles
+Default files/dirs which are loaded on startup (array of paths)
+.TP
+editor
+Default editor to use when editing files (default: "vim")
+.TP
+pdf_opener
+Default app to open PDFs/Epubs (default: "xdg-open")
+.TP
+url_opener
+Default app to open URLs/DOIs (default: "xdg-open")
+.TP
+file_prefix
+Prefix which is prepended to the filepath from the `file` field
+.TP
+pdf_path
+Path to folder containing PDF files with the basename "citekey.pdf"
+.TP
+note_path
+Path to folder containing note files with the basename "citekey.extension"
+.TP
+note_extensions
+Array of valid note file extensions (default: ["md", "txt"])
+.TP
+file_symbol, link_symbol, note_symbol
+Symbols to show if entry has specific attachment
+.TP
+custom_column
+Custom column for the bibentry list (default: "pubtype")
+Possible values: "journaltitle", "organization", "institution", "series", "publisher", "pubtype"
+.SS Color Configuration
+Colors can be customized using ANSI color names, 256-color indices, or HEX codes.
+Available color settings include main_text_color, highlight_text_color, entry_color,
+keyword_color, info_color, confirm_color, warn_color, bar_bg_color, popup_fg_color,
+popup_bg_color, selected_row_bg_color, note_color, file_color, link_color,
+author_color, title_color, and year_color.
+.SH KEYBINDINGS
+.TS
+allbox tab(:);
+l l.
+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 field value of selected entry to clipboard
+e:Open editor at selected entry
+a:Add entry through DOI
+o:Open related PDF or URL/DOI
+n:Create new note file for selected entry
+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
+.TE
+.SS Fast Selection Keys
+.TP
+o-o, o-l, o-n
+Directly open the first file|link|note for the selected entry
+.TP
+y-y
+Directly yank the citekey of the selected entry to the clipboard
+.SH FEATURES
+.TP
+Browse through bib entries using Vim-like keybindings
+.TP
+Filter entries by keywords with fuzzy search
+.TP
+Edit entries using a terminal-based editor
+.TP
+Yank/copy citekeys to system clipboard
+.TP
+Open related PDF files, URLs, and DOIs
+.TP
+Scrollbar for better navigation
+.TP
+Sort entries by column or position in bibfile
+.TP
+Load multiple files into one session
+.TP
+Add entry via DOI
+.TP
+Open and create note files for entries
+.SH EDITORS
+The following editors have been tested and work with bibiman:
+.RS
+.IP
+\(bu  Helix (hx)
+.IP
+\(bu  Vim/Neovim
+.IP
+\(bu  Emacs (terminal and GUI)
+.IP
+\(bu  Nano
+.RE
+The editor must support the `+..` argument to set the cursor line number.
+.SH EXAMPLES
+Open a single bib file:
+.RS
+.IP
+bibiman tests/biblatex-test.bib
+.RE
+Open multiple files:
+.RS
+.IP
+bibiman tests/multi-files/bibfile1.bib tests/multi-files/bibfile2.bib
+.RE
+Open directory containing bib files:
+.RS
+.IP
+bibiman tests/multi-files/
+.RE
+Mixed arguments:
+.RS
+.IP
+bibiman tests/biblatex-test.bib tests/multi-files/
+.RE
+Use custom config file:
+.RS
+.IP
+bibiman --config-file="/path/to/temporary/config" /path/to/bibfile.bib
+.RE
+.SH FILES
+.TP
+$XDG_CONFIG_HOME/bibiman/bibiman.toml
+Main configuration file
+.TP
+$HOME/.config/bibiman/bibiman.toml
+Fallback configuration file location
+.SH AUTHOR
+Lukeflo <lukeflo_git@posteo.de>
+.SH "REPORTING BUGS"
+Report issues at: https://codeberg.org/lukeflo/bibiman/issues
+.SH "SEE ALSO"
+The full documentation is available at: https://codeberg.org/lukeflo/bibiman
\ No newline at end of file
diff --git a/man/bibiman.toml.5 b/man/bibiman.toml.5
new file mode 100644
index 0000000..895551f
--- /dev/null
+++ b/man/bibiman.toml.5
@@ -0,0 +1,184 @@
+.TH BIBIMAN.TOML 5 "2024-12-19" "bibiman 0.13.1" "File Formats"
+.SH NAME
+bibiman.toml \- Configuration file for bibiman
+.SH SYNOPSIS
+$XDG_CONFIG_HOME/bibiman/bibiman.toml
+.br
+$HOME/.config/bibiman/bibiman.toml
+.SH DESCRIPTION
+bibiman.toml is the configuration file for bibiman, a TUI for interacting with
+BibLaTeX databases. The file uses TOML format and allows customization of
+general behavior, file paths, and color schemes.
+.SH FILE LOCATION
+The configuration file is searched in the following order:
+.RS
+.IP 1.
+Path specified with \fB--config-file\fR command line option
+.IP 2.
+$XDG_CONFIG_HOME/bibiman/bibiman.toml
+.IP 3.
+$HOME/.config/bibiman/bibiman.toml
+.RE
+If none exists, bibiman will offer to create a default configuration file.
+.SH SECTIONS
+.SS [general] Section
+Contains general configuration options.
+.TP
+\fBbibfiles\fR = ["/path/to/bibfile", "path/to/dir/with/bibfiles"]
+Array of default files/directories to load on startup. Use absolute paths
+(~ for HOME works).
+.TP
+\fBeditor\fR = "vim"
+Default editor to use when editing files. Arguments are possible, e.g. "vim -y".
+If not set, uses VISUAL and EDITOR environment variables, falling back to "vi".
+.TP
+\fBpdf_opener\fR = "xdg-open"
+Default application to open PDFs/Epubs files.
+.TP
+\fBurl_opener\fR = "xdg-open"
+Default application to open URLs/DOIs.
+.TP
+\fBfile_prefix\fR = "/some/path/prefix"
+Prefix prepended to filepaths from the `file` field in bib entries.
+Use absolute paths (~ for HOME works).
+.TP
+\fBpdf_path\fR = "/path/to/pdf-folder"
+Path to folder (with subfolders) containing PDF files with the basename
+format "citekey.pdf". Use absolute paths (~ for HOME works).
+.TP
+\fBnote_path\fR = "path/to/note-files"
+Path to folder containing note files with the basename "citekey.extension".
+Use absolute paths (~ for HOME works).
+.TP
+\fBnote_extensions\fR = ["md", "txt"]
+Array of valid file extensions for note files.
+.TP
+\fBfile_symbol\fR = ""
+Symbol to show if entry has attached file.
+.TP
+\fBlink_symbol\fR = ""
+Symbol to show if entry has URL/DOI link.
+.TP
+\fBnote_symbol\fR = ""
+Symbol to show if entry has note file.
+.TP
+\fBcustom_column\fR = "pubtype"
+Select a custom column beside standard "author", "title" and "year".
+Possible values:
+.RS
+.IP "journaltitle"
+Lists the title of the journal
+.IP "organization"
+Name of the organization
+.IP "institution"
+Name of the institution
+.IP "series"
+Title of the book series
+.IP "publisher"
+Name of the publisher
+.IP "pubtype"
+BibLaTex pubtype (article, book, incollection, etc.)
+.RE
+.SS [colors] Section
+Contains color configuration for the TUI. Colors can be set using:
+.RS
+.IP \(bu
+ANSI color names (e.g., "darkgray", "light_black")
+.IP \(bu
+256-color indices (e.g., "237")
+.IP \(bu
+HEX codes (e.g., "#3a3a3a")
+.RE
+.TP
+\fBmain_text_color\fR = "250"
+Main text color
+.TP
+\fBhighlight_text_color\fR = "254"
+Highlighted text color
+.TP
+\fBentry_color\fR = "36"
+Entry list color
+.TP
+\fBkeyword_color\fR = "101"
+Keyword color
+.TP
+\fBinfo_color\fR = "99"
+Info window color
+.TP
+\fBconfirm_color\fR = "47"
+Confirmation message color
+.TP
+\fBwarn_color\fR = "124"
+Warning message color
+.TP
+\fBbar_bg_color\fR = "234"
+Status bar background color
+.TP
+\fBpopup_fg_color\fR = "43"
+Popup foreground color
+.TP
+\fBpopup_bg_color\fR = "234"
+Popup background color
+.TP
+\fBselected_row_bg_color\fR = "237"
+Selected row background color
+.TP
+\fBnote_color\fR = "123"
+Note file color
+.TP
+\fBfile_color\fR = "209"
+PDF file color
+.TP
+\fBlink_color\fR = "27"
+URL/DOI link color
+.TP
+\fBauthor_color\fR = "38"
+Author column color
+.TP
+\fBtitle_color\fR = "37"
+Title column color
+.TP
+\fByear_color\fR = "135"
+Year column color
+.SH EXAMPLES
+A minimal configuration file:
+.sp
+.nf
+.RS
+[general]
+bibfiles = ["~/Documents/biblio/main.bib"]
+editor = "nvim"
+pdf_opener = "zathura"
+url_opener = "firefox"
+.RE
+.fi
+.sp
+A full configuration with custom colors:
+.sp
+.nf
+.RS
+[general]
+bibfiles = ["~/papers/bibliography", "~/refs/important.bib"]
+editor = "emacs -nw"
+pdf_opener = "mupdf"
+url_opener = "qutebrowser"
+file_prefix = "~/Documents/literature"
+pdf_path = "~/papers/pdfs"
+note_path = "~/papers/notes"
+note_extensions = ["md", "txt", "org"]
+file_symbol = ""
+link_symbol = ""
+note_symbol = ""
+custom_column = "journaltitle"
+
+[colors]
+main_text_color = "#ffffff"
+highlight_text_color = "#ffff00"
+entry_color = "cyan"
+selected_row_bg_color = "#444444"
+.RE
+.fi
+.SH "SEE ALSO"
+.BR bibiman (1)
+.SH AUTHOR
+Lukeflo <lukeflo_git@posteo.de>
\ No newline at end of file