Refresh commands

rgwood · rgwood · commit 218f600a9dd3 · 2022-04-08T14:35:54.000-07:00
diff --git a/book/commands/alias.md b/book/commands/alias.md
@@ -19,6 +19,11 @@ usage: |
  -  `name`: name of the alias
  -  `initial_value`: equals sign followed by value
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Alias ll to ls -l
diff --git a/book/commands/ansi.md b/book/commands/ansi.md
@@ -21,6 +21,51 @@ usage: |
  -  `--osc`: operating system command (ocs) escape sequence without the escape character(s)
  -  `--list`: list available ansi code names
 
+## Notes
+```text
+For escape sequences:
+Escape: '\x1b[' is not required for --escape parameter
+Format: #(;#)m
+Example: 1;31m for bold red or 2;37;41m for dimmed white fg with red bg
+There can be multiple text formatting sequence numbers
+separated by a ; and ending with an m where the # is of the
+following values:
+    attribute_number, abbreviation, description
+    0     reset / normal display
+    1  b  bold or increased intensity
+    2  d  faint or decreased intensity
+    3  i  italic on (non-mono font)
+    4  u  underline on
+    5  l  slow blink on
+    6     fast blink on
+    7  r  reverse video on
+    8  h  nondisplayed (invisible) on
+    9  s  strike-through on
+
+    foreground/bright colors    background/bright colors
+    30/90    black              40/100    black
+    31/91    red                41/101    red
+    32/92    green              42/102    green
+    33/93    yellow             43/103    yellow
+    34/94    blue               44/104    blue
+    35/95    magenta            45/105    magenta
+    36/96    cyan               46/106    cyan
+    37/97    white              47/107    white
+    39       default            49        default
+    https://en.wikipedia.org/wiki/ANSI_escape_code
+
+OSC: '\x1b]' is not required for --osc parameter
+Example: echo [(ansi -o '0') 'some title' (char bel)] | str collect
+Format: #
+    0 Set window title and icon name
+    1 Set icon name
+    2 Set window title
+    4 Set/read color palette
+    9 iTerm2 Grown notifications
+    10 Set foreground color (x11 color spec)
+    11 Set background color (x11 color spec)
+    ... others
+```
 ## Examples
 
 Change color to green
diff --git a/book/commands/date_to-timezone.md b/book/commands/date_to-timezone.md
@@ -18,6 +18,10 @@ usage: |
 
  -  `time zone`: time zone description
 
+## Notes
+```text
+Use 'date list-timezone' to list all supported time zones.
+```
 ## Examples
 
 Get the current date in UTC+05:00
diff --git a/book/commands/decode.md b/book/commands/decode.md
@@ -18,6 +18,14 @@ usage: |
 
  -  `encoding`: the text encoding to use
 
+## Notes
+```text
+Multiple encodings are supported, here is an example of a few:
+big5, euc-jp, euc-kr, gbk, iso-8859-1, utf-16, cp1252, latin5
+
+For a more complete list of encodings please refer to the encoding_rs
+documentation link at https://docs.rs/encoding_rs/0.8.28/encoding_rs/#statics
+```
 ## Examples
 
 Decode the output of an external command
diff --git a/book/commands/def-env.md b/book/commands/def-env.md
@@ -20,6 +20,11 @@ usage: |
  -  `params`: parameters
  -  `block`: body of the definition
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Set environment variable by call a custom command
diff --git a/book/commands/def.md b/book/commands/def.md
@@ -20,6 +20,11 @@ usage: |
  -  `params`: parameters
  -  `block`: body of the definition
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Define a command and run it
diff --git a/book/commands/dfr_as-date.md b/book/commands/dfr_as-date.md
@@ -19,6 +19,13 @@ usage: |
  -  `format`: formatting date string
  -  `--not-exact`: the format string may be contained in the date (e.g. foo-2021-01-01-bar could match 2021-01-01)
 
+## Notes
+```text
+Format example:
+        "%Y-%m-%d"    => 2021-12-31
+        "%d-%m-%Y"    => 31-12-2021
+        "%Y%m%d"      => 2021319 (2021-03-19)
+```
 ## Examples
 
 Converts string to date
diff --git a/book/commands/dfr_as-datetime.md b/book/commands/dfr_as-datetime.md
@@ -19,6 +19,21 @@ usage: |
  -  `format`: formatting date time string
  -  `--not-exact`: the format string may be contained in the date (e.g. foo-2021-01-01-bar could match 2021-01-01)
 
+## Notes
+```text
+Format example:
+        "%y/%m/%d %H:%M:%S"  => 21/12/31 12:54:98
+        "%y-%m-%d %H:%M:%S"  => 2021-12-31 24:58:01
+        "%y/%m/%d %H:%M:%S"  => 21/12/31 24:58:01
+        "%y%m%d %H:%M:%S"    => 210319 23:58:50
+        "%Y/%m/%d %H:%M:%S"  => 2021/12/31 12:54:98
+        "%Y-%m-%d %H:%M:%S"  => 2021-12-31 24:58:01
+        "%Y/%m/%d %H:%M:%S"  => 2021/12/31 24:58:01
+        "%Y%m%d %H:%M:%S"    => 20210319 23:58:50
+        "%FT%H:%M:%S"        => 2019-04-18T02:45:55
+        "%FT%H:%M:%S.%6f"    => microseconds
+        "%FT%H:%M:%S.%9f"    => nanoseconds
+```
 ## Examples
 
 Converts string to datetime
diff --git a/book/commands/exec.md b/book/commands/exec.md
@@ -19,6 +19,10 @@ usage: |
  -  `command`: the command to execute
  -  `...rest`: any additional arguments for the command
 
+## Notes
+```text
+Currently supported only on Unix-based systems.
+```
 ## Examples
 
 Execute external 'ps aux' tool
diff --git a/book/commands/export.md b/book/commands/export.md
@@ -14,6 +14,11 @@ usage: |
 
 ```> export ```
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Export a definition from a module
diff --git a/book/commands/export_alias.md b/book/commands/export_alias.md
@@ -19,6 +19,11 @@ usage: |
  -  `name`: name of the alias
  -  `initial_value`: equals sign followed by value
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 export an alias of ll to ls -l, from a module
diff --git a/book/commands/export_def-env.md b/book/commands/export_def-env.md
@@ -20,6 +20,11 @@ usage: |
  -  `params`: parameters
  -  `block`: body of the definition
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Define a custom command that participates in the environment in a module and call it
diff --git a/book/commands/export_def.md b/book/commands/export_def.md
@@ -20,6 +20,11 @@ usage: |
  -  `params`: parameters
  -  `block`: body of the definition
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Define a custom command in a module and call it
diff --git a/book/commands/export_env.md b/book/commands/export_env.md
@@ -19,6 +19,11 @@ usage: |
  -  `name`: name of the environment variable
  -  `block`: body of the environment variable definition
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Import and evaluate environment variable from a module
diff --git a/book/commands/export_extern.md b/book/commands/export_extern.md
@@ -19,6 +19,11 @@ usage: |
  -  `def_name`: definition name
  -  `params`: parameters
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Export the signature for an external command
diff --git a/book/commands/extern.md b/book/commands/extern.md
@@ -19,6 +19,11 @@ usage: |
  -  `def_name`: definition name
  -  `params`: parameters
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Write a signature for an external command
diff --git a/book/commands/fetch.md b/book/commands/fetch.md
@@ -23,6 +23,10 @@ usage: |
  -  `--headers {any}`: custom headers you want to add
  -  `--raw`: fetch contents as text rather than a table
 
+## Notes
+```text
+Performs HTTP GET operation.
+```
 ## Examples
 
 Fetch content from url.com
diff --git a/book/commands/for.md b/book/commands/for.md
@@ -21,6 +21,11 @@ usage: |
  -  `block`: the block to run
  -  `--numbered`: returned a numbered item ($it.index and $it.item)
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Echo the square of each integer
diff --git a/book/commands/glob.md b/book/commands/glob.md
@@ -19,6 +19,10 @@ usage: |
  -  `glob`: the glob expression
  -  `--depth {int}`: directory depth to search
 
+## Notes
+```text
+For more glob pattern help please refer to https://github.com/olson-sean-k/wax
+```
 ## Examples
 
 Search for *.rs files
diff --git a/book/commands/grid.md b/book/commands/grid.md
@@ -20,6 +20,15 @@ usage: |
  -  `--color`: draw output with color
  -  `--separator {string}`: character to separate grid with
 
+## Notes
+```text
+grid was built to give a concise gridded layout for ls. however,
+it determines what to put in the grid by looking for a column named
+'name'. this works great for tables and records but for lists we
+need to do something different. such as with '[one two three] | grid'
+it creates a fake column called 'name' for these values so that it
+prints out the list properly.
+```
 ## Examples
 
 Render a simple list to a grid
diff --git a/book/commands/hide.md b/book/commands/hide.md
@@ -18,6 +18,14 @@ usage: |
 
  -  `pattern`: import pattern
 
+## Notes
+```text
+Symbols are hidden by priority: First aliases, then custom commands, then environment variables.
+
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+
+```
 ## Examples
 
 Hide the alias just defined
diff --git a/book/commands/if.md b/book/commands/if.md
@@ -20,6 +20,11 @@ usage: |
  -  `then_block`: block to run if check succeeds
  -  `else_expression`: expression or block to run if check fails
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Output a value if a condition matches, otherwise return nothing
diff --git a/book/commands/let.md b/book/commands/let.md
@@ -19,6 +19,11 @@ usage: |
  -  `var_name`: variable name
  -  `initial_value`: equals sign followed by value
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Set a variable to a value
diff --git a/book/commands/module.md b/book/commands/module.md
@@ -19,6 +19,11 @@ usage: |
  -  `module_name`: module name
  -  `block`: body of the module
 
+## Notes
+```text
+This command is a parser keyword. For details, check
+https://www.nushell.sh/book/thinking_in_nushell.html#parsing-and-evaluation-are-different-stages
+```
 ## Examples
 
 Define a custom command in a module and call it
diff --git a/book/commands/path.md b/book/commands/path.md
@@ -13,3 +13,19 @@ usage: |
 ## Signature
 
 ```> path ```
+
+## Notes
+```text
+There are three ways to represent a path:
+
+* As a path literal, e.g., '/home/viking/spam.txt'
+* As a structured path: a table with 'parent', 'stem', and 'extension' (and
+* 'prefix' on Windows) columns. This format is produced by the 'path parse'
+  subcommand.
+* As an inner list of path parts, e.g., '[[ / home viking spam.txt ]]'.
+  Splitting into parts is done by the `path split` command.
+
+All subcommands accept all three variants as an input. Furthermore, the 'path
+join' subcommand can be used to join the structured path or path parts back into
+the path literal.
+```
diff --git a/book/commands/path_join.md b/book/commands/path_join.md
@@ -19,6 +19,11 @@ usage: |
  -  `append`: Path to append to the input
  -  `--columns {table}`: Optionally operate by column path
 
+## Notes
+```text
+Optionally, append an additional path to the result. It is designed to accept
+the output of 'path parse' and 'path split' subcommands.
+```
 ## Examples
 
 Append a filename to a path
diff --git a/book/commands/path_parse.md b/book/commands/path_parse.md
@@ -19,6 +19,11 @@ usage: |
  -  `--columns {table}`: Optionally operate by column path
  -  `--extension {string}`: Manually supply the extension (without the dot)
 
+## Notes
+```text
+Each path is split into a table with 'parent', 'stem' and 'extension' fields.
+On Windows, an extra 'prefix' column is added.
+```
 ## Examples
 
 Parse a single path
diff --git a/book/commands/path_relative-to.md b/book/commands/path_relative-to.md
diff --git a/book/commands/post.md b/book/commands/post.md
diff --git a/book/commands/register.md b/book/commands/register.md
diff --git a/book/commands/source.md b/book/commands/source.md
diff --git a/book/commands/use.md b/book/commands/use.md
