1 files changed, 62 insertions, 0 deletions
diff --git a/doc/posix-cd.html b/doc/posix-cd.html
new file mode 100644
index 0000000..3a24602
--- /dev/null
+++ b/doc/posix-cd.html
@@ -0,0 +1,62 @@
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>execline: the posix-cd command</title>
+ <meta name="Description" content="execline: the posix-cd command" />
+ <meta name="Keywords" content="execline command cd chdir posix posix-cd" />
+ <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+</head>
+<body>
+
+<p>
+<a href="index.html">execline</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>posix-cd</tt> program </h1>
+
+<p>
+<tt>posix-cd</tt> changes the current working directory to a
+given directory, then executes a program.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     posix-cd <em>dir</em> <em>prog...</em>
+</pre>
+
+<p>
+<tt>posix-cd</tt> changes the current working directory to <em>dir</em>
+according to the
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/cd.html">POSIX
+specification for a <tt>cd</tt> external utility</a>. Then, if <em>prog...</em> is
+not empty, it execs into it.
+</p>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> <tt>posix-cd</tt> is only available when execline has been configured
+with the <tt>--enable-pedantic-posix</tt> option, and in this case, the
+<a href="cd.html">cd</a> binary is a symbolic link to it. </li>
+ <li> <tt>posix-cd</tt> fully conforms to the
+<a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/cd.html">POSIX
+specification</a>. When <em>prog...</em> is not empty, the behaviour of a
+<tt>cd</tt> utility is not specified by POSIX, so <tt>posix-cd</tt> extends
+the spec to be actually useful and usable in an execline program with the same
+interface as the regular execline <a href="cd.html">cd</a> command. </li>
+ <li> Nobody ever executes or needs the external version (i.e. not a shell
+builtin) of the POSIX <tt>cd</tt> command. Compared to the regular execline
+<a href="cd.html">cd</a>, <tt>posix-cd</tt> is uselessly bloated and slow.
+The only reason it exists is that some distributions refuse to package
+execline correctly unless it is strictly POSIX-compliant; the
+<tt>--enable-pedantic-posix</tt> configure option is there to appease them. </li> 
+</ul>
+
+
+</body>
+</html>