Merge pull request #3304 from masatake/canon-filenames

readtags: canonicalize the input file name based on CWD ptag

Tmain/readtags-canonicalize-input-names.d/drive-letter0.tags

@@ -0,0 +1,12 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	C:\tmp	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+a_fn	xyz/a.c	/^static void a_fn(void) {}$/;"	f	typeref:typename:void	file:

Tmain/readtags-canonicalize-input-names.d/drive-letter1.tags

@@ -0,0 +1,12 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	D:/tmp	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+a_fn	xyz/a.c	/^static void a_fn(void) {}$/;"	f	typeref:typename:void	file:

Tmain/readtags-canonicalize-input-names.d/exit-expected.txt

@@ -0,0 +1 @@
+0

Tmain/readtags-canonicalize-input-names.d/good-ptags.tags

@@ -0,0 +1,12 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/../../tmp	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+!_TAG_PROC_DUMMY	/../../tmp	//

Tmain/readtags-canonicalize-input-names.d/good0.tags

@@ -0,0 +1,34 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/tmp/abc/	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+a_fn	xyz/a.c	/^static void a_fn(void) {}$/;"	f	typeref:typename:void	file:
+b_fn	b.c	/^static void b_fn(void) {}$/;"	f	typeref:typename:void	file:
+c_fn	./c.c	/^static void c_fn(void) {}$/;"	f	typeref:typename:void	file:
+d_fn	./../d.c	/^static void d_fn(void) {}$/;"	f	typeref:typename:void	file:
+e_fn	../e.c	/^static void e_fn(void) {}$/;"	f	typeref:typename:void	file:
+f_fn	../../f.c	/^static void f_fn(void) {}$/;"	f	typeref:typename:void	file:
+g_fn	../../../g.c	/^static void g_fn(void) {}$/;"	f	typeref:typename:void	file:
+h_fn	../../../../h.c	/^static void h_fn(void) {}$/;"	f	typeref:typename:void	file:
+i_fn	.././../../../i.c	/^static void i_fn(void) {}$/;"	f	typeref:typename:void	file:
+j_fn	.././../j.c	/^static void j_fn(void) {}$/;"	f	typeref:typename:void	file:
+k_fn	.././.././././k.c	/^static void k_fn(void) {}$/;"	f	typeref:typename:void	file:
+l_fn	././././././l.c	/^static void l_fn(void) {}$/;"	f	typeref:typename:void	file:
+m_fn	./././../abc/./m.c	/^static void m_fn(void) {}$/;"	f	typeref:typename:void	file:
+n_fn	./././../abc/X/.././n.c	/^static void n_fn(void) {}$/;"	f	typeref:typename:void	file:
+o_fn	.////.///////./////..//abc//X//..///.///o.c	/^static void o_fn(void) {}$/;"	f	typeref:typename:void	file:
+p_fn	./../xyz/p.c	/^static void p_fn(void) {}$/;"	f	typeref:typename:void	file:
+q_fn	./../xyz/../././xyz/q.c	/^static void q_fn(void) {}$/;"	f	typeref:typename:void	file:
+r_fn	/r.c	/^static void r_fn(void) {}$/;"	f	typeref:typename:void	file:
+s_fn	/../s.c	/^static void s_fn(void) {}$/;"	f	typeref:typename:void	file:
+t_fn	/../././t.c	/^static void t_fn(void) {}$/;"	f	typeref:typename:void	file:
+u_fn	/../././tmp/./u.c	/^static void u_fn(void) {}$/;"	f	typeref:typename:void	file:
+v_fn	/../././tmp/./../tmp/abc/./v.c	/^static void v_fn(void) {}$/;"	f	typeref:typename:void	file:
+w_fn	/../././tmp/./../tmp/../abc/./w.c	/^static void w_fn(void) {}$/;"	f	typeref:typename:void	file:

Tmain/readtags-canonicalize-input-names.d/good1.tags

@@ -0,0 +1,34 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/tmp/abc/../././abc/../abc	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+a_fn	xyz/a.c	/^static void a_fn(void) {}$/;"	f	typeref:typename:void	file:
+b_fn	b.c	/^static void b_fn(void) {}$/;"	f	typeref:typename:void	file:
+c_fn	./c.c	/^static void c_fn(void) {}$/;"	f	typeref:typename:void	file:
+d_fn	./../d.c	/^static void d_fn(void) {}$/;"	f	typeref:typename:void	file:
+e_fn	../e.c	/^static void e_fn(void) {}$/;"	f	typeref:typename:void	file:
+f_fn	../../f.c	/^static void f_fn(void) {}$/;"	f	typeref:typename:void	file:
+g_fn	../../../g.c	/^static void g_fn(void) {}$/;"	f	typeref:typename:void	file:
+h_fn	../../../../h.c	/^static void h_fn(void) {}$/;"	f	typeref:typename:void	file:
+i_fn	.././../../../i.c	/^static void i_fn(void) {}$/;"	f	typeref:typename:void	file:
+j_fn	.././../j.c	/^static void j_fn(void) {}$/;"	f	typeref:typename:void	file:
+k_fn	.././.././././k.c	/^static void k_fn(void) {}$/;"	f	typeref:typename:void	file:
+l_fn	././././././l.c	/^static void l_fn(void) {}$/;"	f	typeref:typename:void	file:
+m_fn	./././../abc/./m.c	/^static void m_fn(void) {}$/;"	f	typeref:typename:void	file:
+n_fn	./././../abc/X/.././n.c	/^static void n_fn(void) {}$/;"	f	typeref:typename:void	file:
+o_fn	.////.///////./////..//abc//X//..///.///o.c	/^static void o_fn(void) {}$/;"	f	typeref:typename:void	file:
+p_fn	./../xyz/p.c	/^static void p_fn(void) {}$/;"	f	typeref:typename:void	file:
+q_fn	./../xyz/../././xyz/q.c	/^static void q_fn(void) {}$/;"	f	typeref:typename:void	file:
+r_fn	/r.c	/^static void r_fn(void) {}$/;"	f	typeref:typename:void	file:
+s_fn	/../s.c	/^static void s_fn(void) {}$/;"	f	typeref:typename:void	file:
+t_fn	/../././t.c	/^static void t_fn(void) {}$/;"	f	typeref:typename:void	file:
+u_fn	/../././tmp/./u.c	/^static void u_fn(void) {}$/;"	f	typeref:typename:void	file:
+v_fn	/../././tmp/./../tmp/abc/./v.c	/^static void v_fn(void) {}$/;"	f	typeref:typename:void	file:
+w_fn	/../././tmp/./../tmp/../abc/./w.c	/^static void w_fn(void) {}$/;"	f	typeref:typename:void	file:

Tmain/readtags-canonicalize-input-names.d/good2.tags

@@ -0,0 +1,34 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/tmp/abc/../././abc/../abc/	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+a_fn	xyz/a.c	/^static void a_fn(void) {}$/;"	f	typeref:typename:void	file:
+b_fn	b.c	/^static void b_fn(void) {}$/;"	f	typeref:typename:void	file:
+c_fn	./c.c	/^static void c_fn(void) {}$/;"	f	typeref:typename:void	file:
+d_fn	./../d.c	/^static void d_fn(void) {}$/;"	f	typeref:typename:void	file:
+e_fn	../e.c	/^static void e_fn(void) {}$/;"	f	typeref:typename:void	file:
+f_fn	../../f.c	/^static void f_fn(void) {}$/;"	f	typeref:typename:void	file:
+g_fn	../../../g.c	/^static void g_fn(void) {}$/;"	f	typeref:typename:void	file:
+h_fn	../../../../h.c	/^static void h_fn(void) {}$/;"	f	typeref:typename:void	file:
+i_fn	.././../../../i.c	/^static void i_fn(void) {}$/;"	f	typeref:typename:void	file:
+j_fn	.././../j.c	/^static void j_fn(void) {}$/;"	f	typeref:typename:void	file:
+k_fn	.././.././././k.c	/^static void k_fn(void) {}$/;"	f	typeref:typename:void	file:
+l_fn	././././././l.c	/^static void l_fn(void) {}$/;"	f	typeref:typename:void	file:
+m_fn	./././../abc/./m.c	/^static void m_fn(void) {}$/;"	f	typeref:typename:void	file:
+n_fn	./././../abc/X/.././n.c	/^static void n_fn(void) {}$/;"	f	typeref:typename:void	file:
+o_fn	.////.///////./////..//abc//X//..///.///o.c	/^static void o_fn(void) {}$/;"	f	typeref:typename:void	file:
+p_fn	./../xyz/p.c	/^static void p_fn(void) {}$/;"	f	typeref:typename:void	file:
+q_fn	./../xyz/../././xyz/q.c	/^static void q_fn(void) {}$/;"	f	typeref:typename:void	file:
+r_fn	/r.c	/^static void r_fn(void) {}$/;"	f	typeref:typename:void	file:
+s_fn	/../s.c	/^static void s_fn(void) {}$/;"	f	typeref:typename:void	file:
+t_fn	/../././t.c	/^static void t_fn(void) {}$/;"	f	typeref:typename:void	file:
+u_fn	/../././tmp/./u.c	/^static void u_fn(void) {}$/;"	f	typeref:typename:void	file:
+v_fn	/../././tmp/./../tmp/abc/./v.c	/^static void v_fn(void) {}$/;"	f	typeref:typename:void	file:
+w_fn	/../././tmp/./../tmp/../abc/./w.c	/^static void w_fn(void) {}$/;"	f	typeref:typename:void	file:

Tmain/readtags-canonicalize-input-names.d/run.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+
+# Copyright: 2021 Masatake YAMATO
+# License: GPL-2
+
+READTAGS=$3
+
+. ../utils.sh
+
+#V="valgrind --leak-check=full -v"
+V=
+
+if ! [ -x "${READTAGS}" ]; then
+	skip "no readtags"
+fi
+
+
+echo2()
+{
+	echo "$@"
+	echo "$@" 1>&2
+}
+
+run_test()
+{
+	echo2 "# $@"
+	"${READTAGS}" -F '(list $name "\t" $input "\n")' $2 -t $1 $3
+}
+
+run_test good0.tags -C -l &&
+run_test good1.tags --canonicalize-input -l &&
+run_test good2.tags -C -l &&
+! run_test drive-letter0.tags --canonicalize-input -l &&
+! run_test drive-letter1.tags -C -l &&
+run_test good-ptags.tags -C -D &&
+run_test good0.tags -A -l &&
+run_test good1.tags --absolute-input -l &&
+run_test good2.tags -A -l &&
+! run_test drive-letter0.tags --absolute-input -l &&
+! run_test drive-letter1.tags -A -l &&
+run_test good-ptags.tags -A -D

Tmain/readtags-canonicalize-input-names.d/stderr-expected.txt

@@ -0,0 +1,16 @@
+# good0.tags -C -l
+# good1.tags --canonicalize-input -l
+# good2.tags -C -l
+# drive-letter0.tags --canonicalize-input -l
+!_TAG_PROC_CWD must start with '/': C:\tmp
+# drive-letter1.tags -C -l
+!_TAG_PROC_CWD must start with '/': D:/tmp
+# good-ptags.tags -C -D
+# good0.tags -A -l
+# good1.tags --absolute-input -l
+# good2.tags -A -l
+# drive-letter0.tags --absolute-input -l
+!_TAG_PROC_CWD must start with '/': C:\tmp
+# drive-letter1.tags -A -l
+!_TAG_PROC_CWD must start with '/': D:/tmp
+# good-ptags.tags -A -D

Tmain/readtags-canonicalize-input-names.d/stdout-expected.txt

@@ -0,0 +1,174 @@
+# good0.tags -C -l
+a_fn	xyz/a.c
+b_fn	b.c
+c_fn	c.c
+d_fn	/tmp/d.c
+e_fn	/tmp/e.c
+f_fn	/f.c
+g_fn	/g.c
+h_fn	/h.c
+i_fn	/i.c
+j_fn	/j.c
+k_fn	/k.c
+l_fn	l.c
+m_fn	m.c
+n_fn	n.c
+o_fn	o.c
+p_fn	/tmp/xyz/p.c
+q_fn	/tmp/xyz/q.c
+r_fn	/r.c
+s_fn	/s.c
+t_fn	/t.c
+u_fn	/tmp/u.c
+v_fn	/tmp/abc/v.c
+w_fn	/abc/w.c
+# good1.tags --canonicalize-input -l
+a_fn	xyz/a.c
+b_fn	b.c
+c_fn	c.c
+d_fn	/tmp/d.c
+e_fn	/tmp/e.c
+f_fn	/f.c
+g_fn	/g.c
+h_fn	/h.c
+i_fn	/i.c
+j_fn	/j.c
+k_fn	/k.c
+l_fn	l.c
+m_fn	m.c
+n_fn	n.c
+o_fn	o.c
+p_fn	/tmp/xyz/p.c
+q_fn	/tmp/xyz/q.c
+r_fn	/r.c
+s_fn	/s.c
+t_fn	/t.c
+u_fn	/tmp/u.c
+v_fn	/tmp/abc/v.c
+w_fn	/abc/w.c
+# good2.tags -C -l
+a_fn	xyz/a.c
+b_fn	b.c
+c_fn	c.c
+d_fn	/tmp/d.c
+e_fn	/tmp/e.c
+f_fn	/f.c
+g_fn	/g.c
+h_fn	/h.c
+i_fn	/i.c
+j_fn	/j.c
+k_fn	/k.c
+l_fn	l.c
+m_fn	m.c
+n_fn	n.c
+o_fn	o.c
+p_fn	/tmp/xyz/p.c
+q_fn	/tmp/xyz/q.c
+r_fn	/r.c
+s_fn	/s.c
+t_fn	/t.c
+u_fn	/tmp/u.c
+v_fn	/tmp/abc/v.c
+w_fn	/abc/w.c
+# drive-letter0.tags --canonicalize-input -l
+# drive-letter1.tags -C -l
+# good-ptags.tags -C -D
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/tmp	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+!_TAG_PROC_DUMMY	/../../tmp	//
+# good0.tags -A -l
+a_fn	/tmp/abc/xyz/a.c
+b_fn	/tmp/abc/b.c
+c_fn	/tmp/abc/c.c
+d_fn	/tmp/d.c
+e_fn	/tmp/e.c
+f_fn	/f.c
+g_fn	/g.c
+h_fn	/h.c
+i_fn	/i.c
+j_fn	/j.c
+k_fn	/k.c
+l_fn	/tmp/abc/l.c
+m_fn	/tmp/abc/m.c
+n_fn	/tmp/abc/n.c
+o_fn	/tmp/abc/o.c
+p_fn	/tmp/xyz/p.c
+q_fn	/tmp/xyz/q.c
+r_fn	/r.c
+s_fn	/s.c
+t_fn	/t.c
+u_fn	/tmp/u.c
+v_fn	/tmp/abc/v.c
+w_fn	/abc/w.c
+# good1.tags --absolute-input -l
+a_fn	/tmp/abc/xyz/a.c
+b_fn	/tmp/abc/b.c
+c_fn	/tmp/abc/c.c
+d_fn	/tmp/d.c
+e_fn	/tmp/e.c
+f_fn	/f.c
+g_fn	/g.c
+h_fn	/h.c
+i_fn	/i.c
+j_fn	/j.c
+k_fn	/k.c
+l_fn	/tmp/abc/l.c
+m_fn	/tmp/abc/m.c
+n_fn	/tmp/abc/n.c
+o_fn	/tmp/abc/o.c
+p_fn	/tmp/xyz/p.c
+q_fn	/tmp/xyz/q.c
+r_fn	/r.c
+s_fn	/s.c
+t_fn	/t.c
+u_fn	/tmp/u.c
+v_fn	/tmp/abc/v.c
+w_fn	/abc/w.c
+# good2.tags -A -l
+a_fn	/tmp/abc/xyz/a.c
+b_fn	/tmp/abc/b.c
+c_fn	/tmp/abc/c.c
+d_fn	/tmp/d.c
+e_fn	/tmp/e.c
+f_fn	/f.c
+g_fn	/g.c
+h_fn	/h.c
+i_fn	/i.c
+j_fn	/j.c
+k_fn	/k.c
+l_fn	/tmp/abc/l.c
+m_fn	/tmp/abc/m.c
+n_fn	/tmp/abc/n.c
+o_fn	/tmp/abc/o.c
+p_fn	/tmp/xyz/p.c
+q_fn	/tmp/xyz/q.c
+r_fn	/r.c
+s_fn	/s.c
+t_fn	/t.c
+u_fn	/tmp/u.c
+v_fn	/tmp/abc/v.c
+w_fn	/abc/w.c
+# drive-letter0.tags --absolute-input -l
+# drive-letter1.tags -A -l
+# good-ptags.tags -A -D
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_OUTPUT_EXCMD	mixed	/number, pattern, mixed, or combineV2/
+!_TAG_OUTPUT_FILESEP	slash	/slash or backslash/
+!_TAG_OUTPUT_MODE	u-ctags	/u-ctags or e-ctags/
+!_TAG_PATTERN_LENGTH_LIMIT	96	/0 for no limit/
+!_TAG_PROC_CWD	/tmp	//
+!_TAG_PROGRAM_AUTHOR	Universal Ctags Team	//
+!_TAG_PROGRAM_NAME	Universal Ctags	/Derived from Exuberant Ctags/
+!_TAG_PROGRAM_URL	https://ctags.io/	/official site/
+!_TAG_PROGRAM_VERSION	5.9.0	/e08db39a3/
+!_TAG_PROC_DUMMY	/../../tmp	//

docs/man/readtags.1.rst

@@ -73,6 +73,19 @@ Controlling the Output
 By default, the output of readtags contains only the name, input and pattern
 field. The Output can be tweaked using these options:
 
+``-A``, ``--absolute-input``
+	Do the same as ``-C`` option but use only absolute path form.
+
+``-C``, ``--canonicalize-input``
+	Resolve '..' and '.' in input fields of regular tags.
+	This produces a unique representation of the input path.
+	This option works only with tags files having ``!_TAG_PROC_CWD`` pseudo
+	tag.
+
+	NOTE: The current implementation accepts only ``!_TAG_PROC_CWD``
+	starting with ``/``; a Windows directory name starting with a
+	drive letter like ``C:\Somewhere`` is not acceptable.
+
 ``-d``, ``--debug``
 	Turn on debugging output.