Add documentation for paths in positional arguments

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/" },

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

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 />