From 82d983ecfb1565d93671f4cd45c26c36f3c12dc8 Mon Sep 17 00:00:00 2001
From: Dhruv Bhanushali <dhruv_b@live.com>
Date: Thu, 26 Oct 2023 11:44:25 +0400
Subject: [PATCH] Add documentation for paths in positional arguments

---
 docs/astro.config.mjs                        |  1 +
 docs/src/content/docs/guides/get_started.mdx |  3 +-
 docs/src/content/docs/guides/paths.mdx       | 83 ++++++++++++++++++++
 3 files changed, 86 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/content/docs/guides/paths.mdx

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index d4c09d9d..95d6dee8 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -28,6 +28,7 @@ export default defineConfig({
           label: "Guides",
           items: [
             { label: "Get started", link: "/guides/get_started/" },
+            { label: "Paths", link: "/guides/paths/" },
             { label: "Markup", link: "/guides/markup/" },
             { label: "Specs", link: "/guides/specs/" },
             { label: "Contribute", link: "/guides/contribute/" },
diff --git a/docs/src/content/docs/guides/get_started.mdx b/docs/src/content/docs/guides/get_started.mdx
index c34b054c..f8fa8cc9 100644
--- a/docs/src/content/docs/guides/get_started.mdx
+++ b/docs/src/content/docs/guides/get_started.mdx
@@ -105,7 +105,8 @@ $ pls
 ```
 
 By default, <Pls /> lists the contents of the current working directory, but you
-can pass a different file or directory as a positional argument.
+can pass any number of different files or directories as
+[positional arguments](/pls/guides/paths).
 
 If a directory path is passed, all the files and directories within that
 directory are listed. This is useful to see what's in the folder. If a file path
diff --git a/docs/src/content/docs/guides/paths.mdx b/docs/src/content/docs/guides/paths.mdx
new file mode 100644
index 00000000..0ab86388
--- /dev/null
+++ b/docs/src/content/docs/guides/paths.mdx
@@ -0,0 +1,83 @@
+---
+title: Paths
+description:
+  pls organises paths supplied as CLI arguments into groups of files and
+  individual directories.
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+import { Content as FilesAndDirs } from "@/examples/files_and_dirs/files_and_dirs.mdx";
+import { Content as OuterConf } from "@/examples/file_group/outer.mdx";
+import { Content as InnerConf } from "@/examples/file_group/inner.mdx";
+import { Content as FileGroup } from "@/examples/file_group/file_group.mdx";
+import { Content as Symlinks } from "@/examples/symlinks/symlinks.mdx";
+import { Content as Destination } from "@/examples/symlinks/destination.mdx";
+
+First <Pls /> organises paths supplied as CLI arguments into groups of solo
+files and individual directories. Then it prints each group one by one.
+
+```console
+$ pls README.md Cargo.toml Cargo.lock src docs
+```
+
+<FilesAndDirs />
+
+## Solo files
+
+The solo files group consists of all files supplied individually. These files
+are collected into one group. Each of the files in this group comes with its own
+separate configuration derived from `.pls.yml` files.
+
+The special thing here is that the group also has its own configuration
+determined from the common ancestor of all these files. This group-level
+configuration sets top-level options such as table headings, box-drawing
+characters and importance scales.
+
+Consider the following filesystem tree:
+
+```
+file_group
+├── .pls.yml
+├── a
+└── subdir
+    ├── .pls.yml
+    └── b
+```
+
+<Tabs>
+  <TabItem label="file_group/.pls.yml">
+    <OuterConf />
+  </TabItem>
+  <TabItem label="file_group/subdir/.pls.yml">
+    <InnerConf />
+  </TabItem>
+</Tabs>
+
+```console
+$ pls a ./../file_group/./subdir/a
+```
+
+<FileGroup />
+
+Note how both files retain their individual configurations for the row, but the
+table settings come from the outer `.pls.yml` file. Also note that the file
+names are shown exactly as they were passed on the command line.
+
+## Symlinks
+
+By default, <Pls /> does not follow symlinks in the arguments provided to it. So
+a symlink to a directory will be treated as a file input and will not list the
+contents of the target directory.
+
+```console
+$ pls sym
+```
+
+<Symlinks />
+
+```console
+$ pls ./dir
+```
+
+<Destination />