From 202dc44a6dba403c5d13986fe4c3701a45a223c9 Mon Sep 17 00:00:00 2001
From: lukeflo
Date: Fri, 30 May 2025 17:18:13 +0200
Subject: update README: pdf_path variable

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 37 insertions(+), 19 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index e39d8dd..01268a7 100644
--- a/README.md
+++ b/README.md
@@ -122,12 +122,16 @@ POSITIONAL ARGS:
     <dir>     Path to directory containing .bib files
 
 FLAGS:
-    -h, --help          Show this help and exit
-    -v, --version       Show the version and exit
-    -c, --config-file=  Path to config file for current session needed as argument.
-                        Takes precedence over standard config file 
-    --light-terminal    Enable color mode for light terminal background
-
+    -h, --help                  Show this help and exit
+    -v, --version               Show the version and exit
+    -c, --config-file=<value>   Path to config file used for current session.
+                                Takes precedence over standard config file.
+    --light-terminal=<value>    Enable color mode for light terminal background
+    --pdf-dir=<value>           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)"
 ```
 
 As seen, you can pass a single file, multiple files, the path of a directory
@@ -200,6 +204,10 @@ url_opener = "xdg-open"
 # Prefix which is prepended to the filepath from the `file` field
 # Use absolute paths (~ for HOME works). Otherwise, loading might not work.
 file_prefix = "/some/path/prefix"
+# Path to folder (with subfolders) containing PDF files with the basename
+# of the format "citekey.pdf". Other PDF basenames are not accepted.
+# Use absolute paths (~ for HOME works). Otherwise, loading might not work.
+pdf_path = "/path/to/pdf-folder"
 ```
 
 If no file or dir is set as `bibfiles` value, you *have to* add a path via CLI
@@ -207,22 +215,32 @@ interface. If the `bibfiles` value is set *and* a further path (or multiple) is
 provided through the CLI call, the entries of all those files will be opened in
 the started `bibiman` session.
 
-The file prefix offers the possibility to keep file paths in your `.bib` file
-short: E.g. a combination of those values in config and bibfile:
+`file_prefix`
 
-```toml
-# bibiman.toml
-file_prefix = "~/Documents/literature"
-```
+: The `file_prefix` offers the possibility to keep file paths in your `.bib`
+  file short: E.g. a combination of those values in config and bibfile:
 
-```bibtex
-# bibfile.bib
-file = {aristotle.pdf}
-```
+  ```toml
+  # bibiman.toml
+  file_prefix = "~/Documents/literature"
+  ```
+
+  ```latex
+  # bibfile.bib
+  file = {aristotle.pdf}
+  ```
+
+  Will result in opening the file `~/Documents/literature/aristotle.pdf` when
+  trying to open the PDF from inside `bibiman`. The `.bib` file itself will not
+  be edited!
+
+`pdf_path`
 
-Will result in opening the file `~/Documents/literature/aristotle.pdf` when
-trying to open the PDF from inside `bibiman`. The `.bib` file itself will not be
-edited!
+: The `pdf_path` is used as path wich is recursivley searched for files which
+  basename consists of the an entrys `citekey` plus a `.pdf` ending. Every file
+  which matches this pattern for an existing `citekey` is associated with the
+  particular entry for the current `bibiman` session and can be opened from
+  within.
 
 ### Color Configuration<a name="color-configuration"></a>
 
-- 
cgit v1.2.3