docs: describe placeholder option for positional args

Signed-off-by: Michael Molisani <[email protected]>
Signed-off-by: Michael Molisani <[email protected]>

docs/docs/features/argument-parsing/examples/placeholder-argument.txt

@@ -0,0 +1,27 @@
+import { buildCommand, type CommandContext } from "@stricli/core";
+
+export const root = buildCommand({
+  func(this: CommandContext, _: {}, src: string, dest: string) {
+    this.process.stdout.write(`Copying file from ${src} to ${dest}`);
+  },
+  parameters: {
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          brief: "Source file",
+          parse: String,
+          placeholder: "src",
+        },
+        {
+          brief: "Destination path",
+          parse: String,
+          placeholder: "dest",
+        },
+      ],
+    },
+  },
+  docs: {
+    brief: "Example for live playground with positional arguments labeled by placeholders",
+  },
+});

docs/docs/features/argument-parsing/positional.mdx

@@ -67,3 +67,13 @@ import DefaultTupleArgumentCode from "./examples/default-tuple-argument.txt";
 <StricliPlayground filename="default-tuple-argument" rootExport="root" appName="run" defaultInput="">
     {DefaultTupleArgumentCode}
 </StricliPlayground>
+
+## Placeholder
+
+Positional arguments don't truly have names as a name cannot be included in the input (for named arguments, use [flags](./flags.mdx) instead). However, they still have a semantic meaning and it can be useful to refer to it with a name for simplicity. To avoid confusion with named flags, you can specify a "placeholder" for positional arguments. These placeholders are used in the auto-generated usage lines and in the help text.
+
+import PlaceholderArgumentCode from "./examples/placeholder-argument.txt";
+
+<StricliPlayground filename="placeholder-argument" rootExport="root" appName="run" defaultInput="--help">
+    {PlaceholderArgumentCode}
+</StricliPlayground>