Add manpage for documentation

8 files changed, 393 insertions, 73 deletions

diff --git a/README.md b/README.md
index 4654b65..61d0cf1 100644
--- a/README.md
+++ b/README.md
@@ -2,16 +2,17 @@
 Dumb as fuck file manager is a minimal tui file manager with the goal of not being a file manager.
 At its core, it only provides a directory browser, providing ways to conviniently run shell commands to manage your files via keybinds and command line input.
 
-(documentation wip)
-
 ![screenshot](./media/screenshot.jpg)
 
 ## Install
 - Clone the repo and build it: `cabal build daffm` or `nix build`
-- Nix flakes users can also install it as a flake: `github:phenax/daffm#daffm`
+- Nix flakes users can install it as a flake: `github:phenax/daffm#daffm`
 
+## Usage
+Run `man daffm` to see the manual -> [./docs/daffm.md](./docs/daffm.md)
 
 ## Config
+
 Configuration is written in toml. By default it will try to load `$XDG_CONFIG_HOME/daffm/config.toml`.
 You can load config in a different path using `daffm -c <path-to-config>`.
 You can also store alternate configs in `$XDG_CONFIG_HOME/daffm/config.custom-thing.toml` and load it as `daffm -c @custom-thing`.
@@ -67,15 +68,9 @@ m3 = """command-shell echo "<daffm>map <space>3 cd %d" """
 m4 = """command-shell echo "<daffm>map <space>4 cd %d" """
 ```
 
-The substituions (%,%f,%s,%F,%S) are replaced with absolute file paths
-- `%`: File under cursor
-- `%s`: Selected files separated by spaces
-- `%S`: Selected files separated by newlines
-- `%f`: Same as `%s` but if there are no selections, uses file under cursor
-- `%F`: Same as `%S` but if there are no selections, uses file under cursor
-
 
 ## Default keys (no need to define these in config)
+Configuration files loaded override the following defaults
 
 ```toml
 [keymap]
@@ -85,11 +80,17 @@ rr = "reload"
 ":" = "cmdline-enter"
 
 # Search in directory
-"/" = "cmdline-set search "
+"/" = "cmdline-set /"
 n = "search-next"
 N = "search-prev"
 
 # Navigation (j/k for up/down)
+gg = "move 0"
+G = "move $"
+gj = "move 0"
+gk = "move $"
+j = "move +1"
+k = "move -1"
 l = "open"
 h = "back"
 "<cr>" = "open"
@@ -107,8 +108,3 @@ gx = "!xdg-open % >/dev/null 2>&1" # Open externally
 gcfg = "cd ~/.config/daffm" # Open default configurations directory
 ```
 
-
-## Commands
-
-WIP
-
diff --git a/daffm.cabal b/daffm.cabal
index e8e9abe..1a4cbdb 100644
--- a/daffm.cabal
+++ b/daffm.cabal
@@ -9,6 +9,11 @@ build-type:      Simple
 synopsis:        Dumb as fuck file manager
 description:     Dumb as fuck file manager
 
+extra-doc-files: docs/daffm.1
+data-files: docs/daffm.1
+install-includes: docs/daffm.1
+extra-source-files: docs/daffm.1
+
 source-repository head
   type:     git
   location: https://github.com/makedaft/daffm.git
diff --git a/docs/daffm.1 b/docs/daffm.1
new file mode 100644
index 0000000..8fdbcde
--- /dev/null
+++ b/docs/daffm.1
@@ -0,0 +1,145 @@
+.TH DAFFM 1 daffm\-VERSION
+.SH NAME
+daffm \- dumb as fuck file manager
+.SH SYNOPSIS
+.B daffm
+.RB [ \-c
+.IR config-file ]
+.RB [ directory_or_file ]
+.SH DESCRIPTION
+.B daffm
+is a dumb file manager/directory explorer that is meant to integrate with system utils for file management features.
+
+
+.SH OPTIONS
+.TP
+.B \-c, \-\-config " config-path"
+Load toml config from file. If path is prefixed with @, will use alternate config.
+  Example: \-c @foo will load $XDG_CONFIG_HOME/daffm/config.foo.toml
+  Default: $XDG_CONFIG_HOME/daffm/config.toml
+.TP
+.B \-v
+Prints version information.
+.TP
+.B \-h, \-\-help
+Prints help information.
+
+
+.SH CONFIGURATION
+.TP
+.B keymap
+A mapping of key sequences to the commands.
+  Example: gdl = "cd ~/Downloads"
+
+.TP
+.B extend
+Which config file to extend. This can use file paths or @-prefix for alternate configs
+  Example: extend = "@custom-config"
+
+.TP
+.B opener
+Shell script that is executed when open command is invoked on a file.
+  Example: extend = "xdg-open %" # Opens file under cursor (ignores selections)
+
+
+.SH COMMANDS
+
+.TP
+.B back
+Goes back one level in directory.
+
+.TP
+.B cd <dir>
+Change current directory shown.
+
+.TP
+.B cmdline-enter
+Switch focus to the command line input
+
+.TP
+.B cmdline-leave
+Exit cmdline if focused
+
+.TP
+.B cmdline-set <text ...>
+Enter the command line input with given text prefilled
+
+.TP
+.B eval <command> [...args]
+Runs command in shell. Any line in stdout that begins with <daffm> is evaluated as a daffm command. This can be used to create more dynamic commands and keybinds.
+
+.TP
+.B map <key-sequence> <command>
+Add a new keymap to run given command when the key sequence is pressed
+
+.TP
+.B move <pos>
+Move the cursor to position. To move the cursor relative to current position, use +/- (eg: 'move +1' goes down 5 lines). You can also use 'move $' to move the cursor to the last item in the list.
+
+.TP
+.B open
+If cursor is on a directory, cd into the directory, otherwise, run opener
+
+.TP
+.B quit
+Quit
+
+.TP
+.B reload
+Reloads the current directory and shows the latest information. Daffm doesn't watch the directory for changes but after a call to a shell or eval command, the directory contents are reloaded.
+
+.TP
+.B search [text]
+Search the given text in the filenames in current directory. If text is empty, stops search highlighting
+
+.TP
+.B search-next
+Jump to next item in the search results
+
+.TP
+.B search-prev
+Jump to previous item in the search results
+
+.TP
+.B selection-clear
+Clear all selections
+
+.TP
+.B selection-toggle
+Toggle selection for file under cursor
+
+.TP
+.B shell <command> [...args]
+Run a command in shell. If a command exits with non-zero status code, a "Press any key to continue" prompt is shown.
+
+.TP
+.B shell! <command> [...args]
+Same as shell but it adds a "Press any key to continue" prompt after the command runs regardless of exit status code.
+
+
+
+.SH COMMAND SUBSTITUIONS
+The following pattern (%,%d,%f,%s,%F,%S) are replaced with absolute paths
+
+%: File under cursor
+
+%d: Current directory
+
+%s: Selected files separated by spaces
+
+%S: Selected files separated by newlines
+
+%f: Same as %s but if there are no selections, uses file under cursor
+
+%F: Same as %S but if there are no selections, uses file under cursor
+
+
+.SH AUTHORS
+Akshay Nair <phenax5@gmail.com>
+
+.SH LICENSE
+See the LICENSE file for the terms of redistribution.
+
+.SH BUGS AND FEATURE REQUESTS
+https://github.com/phenax/daffm/issues
+
diff --git a/docs/daffm.md b/docs/daffm.md
new file mode 100644
index 0000000..d89a429
--- /dev/null
+++ b/docs/daffm.md
@@ -0,0 +1,199 @@
+# NAME
+
+daffm - dumb as fuck file manager
+
+# SYNOPSIS
+
+**daffm** \[**-c** *config-file*\] \[**directory_or_file**\]
+
+# DESCRIPTION
+
+**daffm** is a dumb file manager/directory explorer that is meant to
+integrate with system utils for file management features.
+
+# OPTIONS
+
+**-c, \--config config-path**
+
+:   Load toml config from file. If path is prefixed with @, will use
+    alternate config. Example: -c \@foo will load
+    \$XDG_CONFIG_HOME/daffm/config.foo.toml Default:
+    \$XDG_CONFIG_HOME/daffm/config.toml
+
+**-v**
+
+:   Prints version information.
+
+**-h, \--help**
+
+:   Prints help information.
+
+# CONFIGURATION
+
+**keymap**
+
+:   A mapping of key sequences to the commands. Example: gdl = \"cd
+    \~/Downloads\"
+
+<!-- -->
+
+**extend**
+
+:   Which config file to extend. This can use file paths or @-prefix for
+    alternate configs Example: extend = \"@custom-config\"
+
+<!-- -->
+
+**opener**
+
+:   Shell script that is executed when open command is invoked on a
+    file. Example: extend = \"xdg-open %\" \# Opens file under cursor
+    (ignores selections)
+
+# COMMANDS
+
+**back**
+
+:   Goes back one level in directory.
+
+<!-- -->
+
+**cd \<dir\>**
+
+:   Change current directory shown.
+
+<!-- -->
+
+**cmdline-enter**
+
+:   Switch focus to the command line input
+
+<!-- -->
+
+**cmdline-leave**
+
+:   Exit cmdline if focused
+
+<!-- -->
+
+**cmdline-set \<text \...\>**
+
+:   Enter the command line input with given text prefilled
+
+<!-- -->
+
+**eval \<command\> \[\...args\]**
+
+:   Runs command in shell. Any line in stdout that begins with \<daffm\>
+    is evaluated as a daffm command. This can be used to create more
+    dynamic commands and keybinds.
+
+<!-- -->
+
+**map \<key-sequence\> \<command\>**
+
+:   Add a new keymap to run given command when the key sequence is
+    pressed
+
+<!-- -->
+
+**move \<pos\>**
+
+:   Move the cursor to position. To move the cursor relative to current
+    position, use +/- (eg: \'move +1\' goes down 5 lines). You can also
+    use \'move \$\' to move the cursor to the last item in the list.
+
+<!-- -->
+
+**open**
+
+:   If cursor is on a directory, cd into the directory, otherwise, run
+    opener
+
+<!-- -->
+
+**quit**
+
+:   Quit
+
+<!-- -->
+
+**reload**
+
+:   Reloads the current directory and shows the latest information.
+    Daffm doesn\'t watch the directory for changes but after a call to a
+    shell or eval command, the directory contents are reloaded.
+
+<!-- -->
+
+**search \[text\]**
+
+:   Search the given text in the filenames in current directory. If text
+    is empty, stops search highlighting
+
+<!-- -->
+
+**search-next**
+
+:   Jump to next item in the search results
+
+<!-- -->
+
+**search-prev**
+
+:   Jump to previous item in the search results
+
+<!-- -->
+
+**selection-clear**
+
+:   Clear all selections
+
+<!-- -->
+
+**selection-toggle**
+
+:   Toggle selection for file under cursor
+
+<!-- -->
+
+**shell \<command\> \[\...args\]**
+
+:   Run a command in shell. If a command exits with non-zero status
+    code, a \"Press any key to continue\" prompt is shown.
+
+<!-- -->
+
+**shell! \<command\> \[\...args\]**
+
+:   Same as shell but it adds a \"Press any key to continue\" prompt
+    after the command runs regardless of exit status code.
+
+# COMMAND SUBSTITUIONS
+
+The following pattern (%,%d,%f,%s,%F,%S) are replaced with absolute
+paths
+
+%: File under cursor
+
+%d: Current directory
+
+%s: Selected files separated by spaces
+
+%S: Selected files separated by newlines
+
+%f: Same as %s but if there are no selections, uses file under cursor
+
+%F: Same as %S but if there are no selections, uses file under cursor
+
+# AUTHORS
+
+Akshay Nair \<phenax5@gmail.com\>
+
+# LICENSE
+
+See the LICENSE file for the terms of redistribution.
+
+# BUGS AND FEATURE REQUESTS
+
+https://github.com/phenax/daffm/issues
diff --git a/flake.lock b/flake.lock
index a864823..c8e9ece 100644
--- a/flake.lock
+++ b/flake.lock
@@ -5,11 +5,11 @@
         "nixpkgs-lib": "nixpkgs-lib"
       },
       "locked": {
-        "lastModified": 1759362264,
-        "narHash": "sha256-wfG0S7pltlYyZTM+qqlhJ7GMw2fTF4mLKCIVhLii/4M=",
+        "lastModified": 1760948891,
+        "narHash": "sha256-TmWcdiUUaWk8J4lpjzu4gCGxWY6/Ok7mOK4fIFfBuU4=",
         "owner": "hercules-ci",
         "repo": "flake-parts",
-        "rev": "758cf7296bee11f1706a574c77d072b8a7baa881",
+        "rev": "864599284fc7c0ba6357ed89ed5e2cd5040f0c04",
         "type": "github"
       },
       "original": {
@@ -20,11 +20,11 @@
     },
     "haskell-flake": {
       "locked": {
-        "lastModified": 1759022640,
-        "narHash": "sha256-blv+xY7A3BVxxKHfJjCXb9KaTzPHlb9SWfs0WqDvKZE=",
+        "lastModified": 1761010941,
+        "narHash": "sha256-x4tZ/4MhrFD166lGT0umQbRmNlJ57HI/nE5KV8/V21c=",
         "owner": "srid",
         "repo": "haskell-flake",
-        "rev": "1c26ac95f69e563781feccd6610fd7637bebbd10",
+        "rev": "7b56be2ea5c3b3fa2706d1a3244050ecc8e81e1a",
         "type": "github"
       },
       "original": {
diff --git a/flake.nix b/flake.nix
index 3795d37..68140fc 100644
--- a/flake.nix
+++ b/flake.nix
@@ -19,10 +19,13 @@
               ./exe
               ./lib
               ./specs
+              ./docs
               ./daffm.cabal
             ];
           });
-          otherFiles = [];
+          installFiles = [
+            { source = ./docs/daffm.1; target = "$out/share/man/man1/daffm.1"; }
+          ];
           configurationFlags = [
             "--ghc-options=-O2"
           ];
@@ -30,7 +33,7 @@
             pkg-config
           ];
 
-          devPackages = with pkgs; [just];
+          devPackages = with pkgs; [ just pandoc ];
         in {
           haskellProjects.default = {
             inherit projectRoot;
@@ -44,8 +47,10 @@
                 strip = true;
                 custom = drv:
                   (pkgs.haskell.lib.compose.appendConfigureFlags configurationFlags drv).overrideAttrs (old: {
-                    preBuild = ''
-                      ${toString (map (f: ''cp -r ${f.source} ${f.target};'') otherFiles)}
+                    postInstall = ''
+                      ${toString (map (f: ''
+                        install -Dm644 "${f.source}" "${f.target}";
+                      '') installFiles)}
                     '';
                   })
                 ;
diff --git a/justfile b/justfile
index 9dff968..e11c187 100644
--- a/justfile
+++ b/justfile
@@ -6,3 +6,7 @@ run *args:
 
 test *args:
   cabal test {{args}}
+
+doc:
+  pandoc -f man -t markdown docs/daffm.1 -o docs/daffm.md
+
diff --git a/notes.org b/notes.org
index f7c7eaa..663acf6 100644
--- a/notes.org
+++ b/notes.org
@@ -1,49 +1,15 @@
-** Essentials
-- [X] select multiple files
-- [X] Support multikey bindings
-- [X] Show file permissions
-- [X] Run shell command
-- [X] Reload
-- [X] Preserve cursor position per dir while navigating
-- [X] Command: shell & shell! (alias for !, !!)
-- [X] Command substitution %s:selections
-- [X] Command substitution %d:cwd
-- [X] Command substitution %
-- [X] Command parsing
-- [X] Cmdline must be single line
-- [X] Internal commands?
-- [X] parsing key sequence
-- [X] configuration file (toml?)
-- [X] Error handling
-- [X] Expand ~ to home in internal commands (cd)
-- [X] Show current pending keys in statusline
-- [X] Opener configuration
-- [X] Cli arg parsing (dir arg)
-- [X] Cli arg parsing (-c flag for custom config path)
-- [X] handle on open (for external integrations) (opener in custom config)
-- [X] Given file name, open dir of file with cursor on file
-** Right after
-- [X] chain multiple commands
-- [X] Fix cmd substitution for all command args
-- [X] Command: command-shell special variant of shell that evaluates output as commands
-- [X] Config extend (extend = true will extend config.toml)
-- [X] Finish nvim integration
-- [X] Command: search, search-next, search-prev
-- [X] cd into dir symlinks
-- [X] Command: map
-- [X] shorten/trim from left in header for long paths
-- [ ] Allow escaping % in commands
-- [ ] Cmdline history
-- [ ] Store last directory path (for auto cd in shell)
-- [ ] Preserve back directory when going inside sym link to directories
+- [X] commands: move cursor: move +1, move -1, move 5, move $, move 0
+- [X] rename command-shell to evaluate
+- [ ] Use ls for file listing respecting ansi colors
+- [ ] Generalize cd/opener/back
+- [ ] Allow recursive config extends (@A -> @B -> @C)
+- [ ] allow escaping % in commands
+- [ ] custom commands
+- [ ] cmdline autocompletion
+- [ ] handle permissions errors
 ** Later
-- [ ] Rethink % substituions
-- [ ] cmdline tab completion
-- [ ] theme from config
-- [ ] Fix keymap evaluation with timeout? (If vd is bound, it doesnt evaluate a v binding)
-- [ ] Allow escaping % in commands
-- [ ] Custom commands
-- [ ] aliases for builtin commands
-- [ ] some caching for file list?
-- [ ] copy/move/paste across instances?
+- [ ] Show last cmd in cmdline
+- [ ] preserve back directory when going inside symlink to directories
+- [ ] cmdline history
+- [ ] some caching for file list? (might be good to have for large lists)
 - [ ] watch for changes?