[docs] cleanup documentation on lit substitutions

[bd1976llvm]

Summary

1. Added missing substitutions to the documentation in docs/TestingGuide.rst
2. Modified docs/CommandGuide/lit.rst to only document the "base" set of substitutions and to refer the reader to docs/TestingGuide.rst for more detailed info on substitutions.

[rengolin]

I don't know enough about the Windows behaviour, but the move looks good to me.

docs/TestingGuide.rst

474 ↗

(On Diff #86275)

From the old doc, it seems to be the other way round.

488 ↗

(On Diff #86275)

I had no idea this worked at all! Then again, last time I used Windows was when it was still being launched from DOS.

[bd1976llvm]

docs/TestingGuide.rst

474 ↗

(On Diff #86275)

I think that the new doc is correct. From the source code:

1. "%/[STpst]" should be normalized. substitutions.extend([ ('%/s', escapedSourcePath.replace('\\', '/')),

474 ↗

(On Diff #86275)

Well that came out badly :( The key point is that the code does this: replace('\\', '/')

488 ↗

(On Diff #86275)

You have no idea what your missing out on :)

[bd1976llvm]

docs/TestingGuide.rst

488 ↗

(On Diff #86275)

You have no idea what you're missing out on :)

[rengolin]

docs/TestingGuide.rst

474 ↗

(On Diff #86275)

Right, this is in line with what I remembered, tbh.

[bd1976llvm]

ping

[rengolin]

No one shouted, so LGTM. Thanks! :)

llvm/trunk/docs/CommandGuide/lit.rst

 be used to define subdirectories of optional tests, or to change other
 configuration parameters --- for example, to change the test format, or the
 suffixes which identify test files.
 
 PRE-DEFINED SUBSTITUTIONS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 :program:`lit` provides various patterns that can be used with the RUN command.
-These are defined in TestRunner.py.
+These are defined in TestRunner.py. The base set of substitutions are:
 
  ========== ==============
   Macro      Substitution
  ========== ==============
  %s         source path (path to the file currently being run)
  %S         source dir (directory of the file currently being run)
  %p         same as %S
  %{pathsep} path separator
  %t         temporary file name unique to the test
  %T         temporary directory unique to the test
  %%         %
- %/s        same as %s but replace all / with \\
- %/S        same as %S but replace all / with \\
- %/p        same as %p but replace all / with \\
- %/t        same as %t but replace all / with \\
- %/T        same as %T but replace all / with \\
  ========== ==============
 
-Further substitution patterns might be defined by each test module.
-See the modules :ref:`local-configuration-files`.
+Other substitutions are provided that are variations on this base set and
+further substitution patterns can be defined by each test module. See the
+modules :ref:`local-configuration-files`.
 
-More information on the testing infrastucture can be found in the
+More detailed information on substitutions can be found in the
 :doc:`../TestingGuide`.
 
 TEST RUN OUTPUT FORMAT
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The :program:`lit` output for a test run conforms to the following schema, in
 both short and verbose modes (although in short mode no PASS lines will be
 shown).  This schema has been chosen to be relatively easy to reliably parse by

llvm/trunk/docs/TestingGuide.rst

``%T``
    Directory of ``%t``.
 
    Example: ``/home/user/llvm.build/test/MC/ELF/Output``
 
 ``%{pathsep}``
 
    Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
 
+``%/s, %/S, %/t, %/T:``
+
+  Act like the corresponding substitution above but replace any ``\``
+  character with a ``/``. This is useful to normalize path separators.
+
+   Example: ``%s:  C:\Desktop Files/foo_test.s.tmp``
+   
+   Example: ``%/s: C:/Desktop Files/foo_test.s.tmp``
+
+``%:s, %:S, %:t, %:T:``
+
+  Act like the corresponding substitution above but remove colons at
+  the beginning of Windows paths. This is useful to allow concatenation
+  of absolute paths on Windows to produce a legal path.
+
+   Example: ``%s:  C:\Desktop Files\foo_test.s.tmp``
+
+   Example: ``%:s: C\Desktop Files\foo_test.s.tmp``
+
 
 **LLVM-specific substitutions:**
 
 ``%shlibext``
    The suffix for the host platforms shared library files. This includes the
    period as the first character.
 
    Example: ``.so`` (Linux), ``.dylib`` (OS X), ``.dll`` (Windows)