[line-directive] Add usage and explanatory text

Author: Dave Abrahams

utils/line-directive

@@ -10,14 +10,44 @@
 # See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
 #
 # ----------------------------------------------------------------------------
-#
-# Converts line numbers in error messages according to "line directive"
-# comments.
-#
-# ----------------------------------------------------------------------------
-
 from __future__ import print_function
 
+usage = '''"#sourceLocation" is a directive used by tools like the Swift
+compiler and debugger to adjust the lines reported in diagnostics and to
+determine what source you see when you're stepping. "#sourceLocation"
+corresponds to "#line" in C/C++ which is inserted by code generators like
+Lex/Flex/Yacc/Bison so that you deal with the actual code you wrote and not the
+generated result. For dealing with errors in the Swift generated by your gyb
+source it's important that your tools can take you to the right line in your
+.gyb file rather than in generated .swift file. If you don't have such a tool,
+manually indirecting through the generated code is tedious, but at least it's
+possible since gyb leaves "#sourceLocation" information behind.
+
+But Swift's "#sourceLocation" directive is suboptimal for the purposes of the
+freeform code generation done with gyb because it can only appear between
+grammatically-complete declarations and statements (or something like that). So
+instead of inserting "#sourceLocation" directives, gyb inserts "//
+###sourceLocation" comments (by default---it's tunable). This line-directive
+tool remaps file and line information in the output of your swift compiler (or
+whatever tool you are using to process generated source---gyb is not
+swift-specific) so that the error points to the right place in the .gyb
+source. You invoke it as follows:
+
+  line-directive <generated-sources> -- <compilation command>
+
+e.g., if you have foo.swift.gyb, bar.swift.gyb, and baz.swift, instead of
+
+  gyb foo.swift.gyb -o foo.swift
+  gyb bar.swift.gyb -o bar.swift
+  swiftc foo.swift bar.swift baz.swift
+
+You do this:
+
+  gyb foo.swift.gyb -o foo.swift
+  gyb bar.swift.gyb -o bar.swift
+  line-directive foo.swift bar.swift -- swiftc foo.swift bar.swift baz.swift
+'''
+
 import bisect
 import os
 import re
@@ -639,6 +669,9 @@ def run():
         import doctest
         failure_count, _ = doctest.testmod()
         sys.exit(failure_count)
+    elif len(sys.argv) == 2 and sys.argv[1] == '--help':
+        print(usage)
+        sys.exit(1)
     elif '--' not in sys.argv:
         source_file = sys.argv[1]
         source_line = int(sys.argv[2])