Add syntax location rst

docs/syntax/arange.rst

@@ -6,6 +6,7 @@ range but we allow addresses. An add
 
 An address range is in one of the following forms:
 
+::
     location       # starting line only
     first, last    # starting and ending line
     , last         # ending line only
@@ -24,8 +25,8 @@ Examples
 ::
 
   *5                 # start from bytecode offset 5 of current file
-  *5 ,                 # Same as above.
-  foo.py:*5            # start from bytecode offset 5 of file foo.py
+  *5 ,               # Same as above.
+  foo.py:*5          # start from bytecode offset 5 of file foo.py
 
 
 .. seealso::

docs/syntax/location.rst

@@ -0,0 +1,112 @@
+Syntax for Source-Code Locations
+================================
+
+A number of commands like "break", and "list" have locations
+embedded in them.
+
+A location can be either a *linespec* an explicit function, or a *module linespec*
+
+
+Linespec
+--------
+
+A linespec has a colon-separated pair of a source-location parameter
+and a line number.  A source location is a file path or a module name.
+
+In [*path*:]*linenum* , the line *linenum* in the source file *path*
+is indicated. When *path* is omitted, some default value is given,
+usually it is the *path* associated with the current frame. Or in
+list-like commands it is the *path* what was most-recently set; the
+most-recently set path starts out as the current frame's path.
+
+If *filename* is a relative file name, then Python's `sys.path` items
+(which are assumed to be a list of directories) is tried in the order
+given. Often the current working directory or `.` is in that
+list. Note that `.` can be set with `cd` debugger command.
+
+To specify a path containing non-alphanumeric characters, specifically
+blanks (" "), backslashes ("\"), or quotes, in there are a number of
+quoting mechanisms one can use. You can enclose the path in single
+quotes, double quotes or triple double as you would do in Python
+
+Examples:
++++++++++
+
+    10                   # line 10 of the most-recently used path
+    myfile.py:2          # line 2 of myfile.py where the directory name is
+                         #resolved from `sys.path`
+    ./../myfile.py:3     # line 3 of the parent of some directory in `sys.path`
+    /tmp/foo.py:4        # line 4 of absolute path /tmp/foo.py
+    "foo's.py":1"        # One way to specify a path with a quote
+    '''foo's.py"''':2    # Another way to specify a path with a quote
+    'c:\foo.bat':1"      # One way to specify a Windows file name,
+    '/My Docs/foo.py':1" # One way to specify path with blanks in it
+
+
+
+function()
+----------
+
+Specifies the line that function *function* starts on. This is the
+line that contains `def`. We get this information from the Python code
+object, in particular the `co_firstlineno` field.
+
+contrast to *gdb*, use parenthesis at the end of the function name
+to indicate this is a function.
+
+You can also specify functions though the values in Python program
+variables or the function indicated in an instance method.
+
+For example consider this program:
+
+    class Foo():
+        def food(): return
+    f = Foo()
+    b = [f.food]
+    x = 2
+
+If you are stopped at the last line `x = 2`. You can specify the function `food`
+as either of these ways:
+
+   Foo.food()
+   f.food()
+   b[0]()
+
+Although in the last example `b[0]()` the expressions can get a bit
+complex, to simplify parsing, we don't allow arbitrary expressions. We
+currently allow only alphanumeric symbols as you'd find in valid
+Python identifiers along with extra symbols ".", "[", and "]".  This
+means `b[i+1]()` would be invalid because it contains "+".  So would
+`b["foo"]()`, assuming `b` were a dictionary, because of the quote
+symbol.
+
+*Right now we don't allow line offsets from functions. If the need
+arises we may do so in the future.*
+
+module linespec
+---------------
+
+While functions need a closing `()` to indicate their function-ness,
+Python module names don't. What we do here is first look up the name
+as a file path.  If that's not found we look up the file as a Python
+module name. Modules have to have been imported before it accepted in
+the debugger. However you can run `eval` (or `autoeval`) to have
+Python import the module inside the debugger.
+
+In sum file names are distinguished from method names purely by
+semantic means. However *gdb* and thus this debugger has no means to
+explicitly tag names as a file path or Python module name. We, but not
+*gdb*, make a distinction between functions versus modules and file
+paths.
+
+Examples:
++++++++++
+
+    os.path:45  # Line 45 of the file that contains os.path
+    os:1        # First line of module os
+    os          # Invalid! (for now)
+
+Note that the last line is invalid. In contrast to functions, you need
+to give a line numbers. Also it is assumed there is not a *file*
+called `os` in the last example line. Nor a file called `os.path` in
+the first example.