Add more docs

Also, prepare for release.
3 years ago · 32a32e9180
parent d29f6aed6d
commit 32a32e9180
6 changed files with 313 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -53,6 +53,8 @@ Table of content
  - [Layouts](https://arijitbasu.in/xplr/en/layouts.html)
  - [Node Types](https://arijitbasu.in/xplr/en/node_types.html)
  - [Style](https://arijitbasu.in/xplr/en/style.html)
+  - [Sorting](https://arijitbasu.in/xplr/en/sorting.html)
+  - [Filtering](https://arijitbasu.in/xplr/en/filtering.html)
 - [Default Key Bindings](https://arijitbasu.in/xplr/en/default-key-bindings.html)
 - [Plugin](https://arijitbasu.in/xplr/en/plugin.html)
  - [Installing Plugins](https://arijitbasu.in/xplr/en/installing-plugins.html)
--- a/docs/en/src/SUMMARY.md
+++ b/docs/en/src/SUMMARY.md
@ -12,6 +12,8 @@ A hackable, minimal, fast TUI file explorer
  - [Layouts](layouts.md)
  - [Node Types](node_types.md)
  - [Style](style.md)
+  - [Sorting](sorting.md)
+  - [Filtering](filtering.md)
 - [Default Key Bindings](default-key-bindings.md)
 - [Plugin](plugin.md)
  - [Installing Plugins](installing-plugins.md)
--- a/docs/en/src/filtering.md
+++ b/docs/en/src/filtering.md
@ -0,0 +1,87 @@
+Filtering
+=========
+
+xplr supports filtering paths by different properties. The filtering mechanism
+works like a pipeline, which in visible in the `Sort & filter` panel.
+
+Example:
+
+```
+rel!^. › [i]abs=~abc › [i]rel!~xyz
+```
+
+This line means that the nodes visible on the table will first be filtered by
+the condition: *relative path does not start with `.`*, then by the condition:
+*absolute path contains `abc` (case insensitive)*, and finally by the
+condition: *relative path does not contain `xyz`*.
+
+Each part of this pipeline is called [Node Filter Applicable](#node-filter-applicable).
+
+
+Node Filter Applicable
+----------------------
+
+It contains the following information:
+
+- [filter](#filter)
+- [input](#input)
+
+### filter
+
+A filter can be one of the following:
+
+- "RelativePathIs"
+- "RelativePathIsNot"
+- "IRelativePathIs"
+- "IRelativePathIsNot"
+- "RelativePathDoesStartWith"
+- "RelativePathDoesNotStartWith"
+- "IRelativePathDoesStartWith"
+- "IRelativePathDoesNotStartWith"
+- "RelativePathDoesContain"
+- "RelativePathDoesNotContain"
+- "IRelativePathDoesContain"
+- "IRelativePathDoesNotContain"
+- "RelativePathDoesEndWith"
+- "RelativePathDoesNotEndWith"
+- "IRelativePathDoesEndWith"
+- "IRelativePathDoesNotEndWith"
+- "AbsolutePathIs"
+- "AbsolutePathIsNot"
+- "IAbsolutePathIs"
+- "IAbsolutePathIsNot"
+- "AbsolutePathDoesStartWith"
+- "AbsolutePathDoesNotStartWith"
+- "IAbsolutePathDoesStartWith"
+- "IAbsolutePathDoesNotStartWith"
+- "AbsolutePathDoesContain"
+- "AbsolutePathDoesNotContain"
+- "IAbsolutePathDoesContain"
+- "IAbsolutePathDoesNotContain"
+- "AbsolutePathDoesEndWith"
+- "AbsolutePathDoesNotEndWith"
+- "IAbsolutePathDoesEndWith"
+- "IAbsolutePathDoesNotEndWith"
+
+
+TODO: document each
+
+### input
+
+Type: string
+
+The input for the condition.
+
+
+Example:
+--------
+
+```lua
+ToggleNodeFilter = {
+  filter = "RelativePathDoesNotStartWith",
+  input = "."
+}
+```
+
+Here, `ToggleNodeFilter` is a [message](message.md) that adds or removes
+(toggles) the filter applied.
--- a/docs/en/src/general-config.md
+++ b/docs/en/src/general-config.md
@ -61,7 +61,140 @@ initial_layout

 Type: string

-The name of one of the defined [layouts](layouts.md) to use when xplr loads.
+The name of one of the [layout](layouts.md) to use when xplr loads.


+initial_mode
+------------
+
+Type: string
+
+The name of one of the [mode](modes.md) to use when xplr loads.
+
+
+initial_sorting
+---------------
+
+Type: list of [Node Sorter Applicable](sorting.md#node-sorter-applicable)
+
+Initial group if sorters applied to the nodes list in the table.
+
+
+table.style
+-----------
+
+Type: [Style](style.md)
+
+Default style of the table.
+
+
+table.col_spacing
+-----------------
+
+Type: nullable integer
+
+Default spacing of the columns in the table.
+
+
+table.col_widths
+----------------
+
+Type: nullable list of [Constraint](layouts.md#constraint)
+
+Width of each column in the table.
+
+table.header.height
+----------------
+
+Type: nullable integer
+
+Height of the table header.
+
+
+table.header.style
+---------------
+
+Type: [Style](style.md)
+
+Style of table header.
+
+
+table.header.cols
+-----------------
+
+Type: List of column configuration
+
+Each column config contains `format` field (string) and `style` field
+([Style](style.md)), that define the content and style of header.
+
+
+table.row.height
+----------------
+
+Type: nullable integer
+
+Height of each row in the table.
+
+
+table.row.style
+---------------
+
+Type: [Style](style.md)
+
+Style of table rows.
+
+
+table.row.cols
+-----------------
+
+Type: List of column configuration
+
+Each column config contains `format` field (string) and `style` field
+([Style](style.md)).
+
+However, unlike [table.header.cols](#tableheadercols), the `format` field here
+points to a Lua function that receives a
+[special argument](https://docs.rs/xplr/latest/xplr/ui/struct.NodeUiMetadata.html)
+as input and returns a string that will be displayed in the column.
+
+TODO: Document the argument fields here.
+
+xplr by default provides the following functions:
+
+- `xplr.fn.builtin.fmt_general_table_row_cols_0`
+- `xplr.fn.builtin.fmt_general_table_row_cols_1`
+- `xplr.fn.builtin.fmt_general_table_row_cols_2`
+- `xplr.fn.builtin.fmt_general_table_row_cols_3`
+- `xplr.fn.builtin.fmt_general_table_row_cols_4`
+
+You can either overwrite these functions, or create new functions in
+`xplr.fn.custom` and point to them.
+
+Terminal colors are supported.
+
+Example:
+
+```lua
+xplr.fn.custom.fmt_simple_column = function(m)
+  return m.prefix .. m.relative_path .. m.suffix
+end
+
+xplr.config.general.table.header.cols = {
+  { format = "  path" }
+}
+
+xplr.config.general.table.row.cols = {
+  { format = "custom.fmt_simple_column" }
+}
+
+xplr.config.general.table.col_widths = {
+  { Percentage = 100 }
+}
+
+-- With this config, you should only see a single column displaying the
+-- relative paths.
+```
+
+------------
+
 TODO: Continue documentation
--- a/docs/en/src/sorting.md
+++ b/docs/en/src/sorting.md
@ -0,0 +1,83 @@
+Sorting
+=======
+
+xplr supports sorting paths by different properties. The sorting mechanism
+works like a pipeline, which in visible in the `Sort & filter` panel.
+
+Example:
+
+```
+size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑
+```
+
+This line means that the nodes visible on the table will be first sorted by
+relative file size, then by case insensitive relative path, then by the
+canonical (symlink resolved) type of the node, and finally by whether or not
+the node is a symlink.
+
+The arrows denote the order.
+
+Each part of this pipeline is called [Node Sorter Applicable](#node-sorter-applicable).
+
+
+Node Sorter Applicable
+----------------------
+
+It contains the following information:
+
+- [sorter](#sorter)
+- [reverse](#reverse)
+
+
+### sorter
+
+A sorter can be one of the following:
+
+- "ByRelativePath"
+- "ByIRelativePath"
+- "ByExtension"
+- "ByIsDir"
+- "ByIsFile"
+- "ByIsSymlink"
+- "ByIsBroken"
+- "ByIsReadonly"
+- "ByMimeEssence"
+- "BySize"
+- "ByCanonicalAbsolutePath"
+- "ByICanonicalAbsolutePath"
+- "ByCanonicalExtension"
+- "ByCanonicalIsDir"
+- "ByCanonicalIsFile"
+- "ByCanonicalIsReadonly"
+- "ByCanonicalMimeEssence"
+- "ByCanonicalSize"
+- "BySymlinkAbsolutePath"
+- "ByISymlinkAbsolutePath"
+- "BySymlinkExtension"
+- "BySymlinkIsDir"
+- "BySymlinkIsFile"
+- "BySymlinkIsReadonly"
+- "BySymlinkMimeEssence"
+- "BySymlinkSize"
+
+TODO: document each
+
+
+### reverse
+
+Type: boolean
+
+It defined the direction of the order.
+
+
+Example
+-------
+
+```lua
+xplr.config.general.initial_sorting = {
+    { sorter = "ByCanonicalIsDir", reverse = true },
+    { sorter = "ByIRelativePath", reverse = false },
+}
+```
+
+This snippet defines the initial sorting logic to be applied when xplr loads.
--- a/docs/en/src/upgrade-guide.md
+++ b/docs/en/src/upgrade-guide.md
@ -46,7 +46,7 @@ compatibility.

 ### Instructions

-#### [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -> [v0.14.2](https://github.com/sayanarijit/xplr/releases/tag/v0.14.2)
+#### [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -> [v0.14.3](https://github.com/sayanarijit/xplr/releases/tag/v0.14.3)

 - macOS users need to place their config file (`init.lua`) in
  `$HOME/.config/xplr/` or `/etc/xplr/`.
@ -55,6 +55,10 @@ compatibility.
  for [FIFO based file previews](https://github.com/sayanarijit/xplr/pull/229#issue-662426960).
 - You can disable the recover mode using `config.general.disable_recover_mode = true`.
 - Try running `xplr --help`. Yes, CLI has been implemented.
+- Since version `v0.14.3`, `StartFifo` and `ToggleFifo` will write to the FIFO
+  path when called. So, there's no need to pipe the focus path explicitely.
+- Since version `v0.14.3`, general config `xplr.config.start_fifo` is available
+  which can be set to a file path to start a fifo when xplr starts.

 <sub>Like this project so far? **[Please consider contributing](contribute.md)**.</sub>