Go over documentation

docs/commands/data/disassemble.rst

@@ -4,16 +4,20 @@
 Disassemble (CPython disassembly)
 ---------------------------------
 
-**disassemble** [ *thing* ] [ *start-line* [ *end-line* ]]
+**disassemble** [*thing*]disassemble [*addresss-range*]
 
-With no argument, disassemble the current frame. With an integer
-start-line, the disassembly is narrowed to show lines starting at that
-line number or later; with an end-line number, disassembly stops when
-the next line would be greater than that or the end of the code is hit.
+Disassembles bytecode. See `help syntax arange` for what can go in an
+assembly-list range.
 
-If *start-line* or *end-line is* ``.``, ``+``, or ``-``, the current
-line number is used. If instead it starts with a plus or minus prefix to
-a number, then the line number is relative to the current frame number.
+Without arguments, print lines starting from where the last list left off
+since the last entry to the debugger. We start off at the location indicated
+by the current stack.
+
+in addition you can also use:
+
+  - a '.' for the location of the current frame
+  - a '-' for the lines before the last list
+  - a '+' for the lines after the last list
 
 With a class, method, function, pyc-file, code or string argument
 disassemble that.
@@ -23,14 +27,16 @@ Examples:
 
 ::
 
-       disassemble    # Possibly lots of stuff dissassembled
-       disassemble .  # Disassemble lines starting at current stopping point.
-       disassemble +                  # Same as above
-       disassemble +0                 # Same as above
-       disassemble os.path            # Disassemble all of os.path
-       disassemble os.path.normcase   # Disaassemble just method os.path.normcase
-       disassemble -3  # Disassemble subtracting 3 from the current line number
-       disassemble +3  # Disassemble adding 3 from the current line number
-       disassemble 3                  # Disassemble starting from line 3
-       disassemble 3 10               # Disassemble lines 3 to 10
-       disassemble myprog.pyc         # Disassemble file myprog.pyc
+   disassemble    # Possibly lots of stuff dissassembled
+   disassemble .  # Disassemble lines starting at current stopping point.
+   disassemble +                    # Same as above
+   disassemble os.path              # Disassemble all of os.path
+   disassemble os.path.normcase()   # Disaassemble just method os.path.normcase
+   disassemble 3                    # Disassemble starting from line 3
+   disassemble 3, 10                # Disassemble lines 3 to 10
+   disassemble *0, *10              # Disassemble offset 0-10
+   disassemble myprog.pyc           # Disassemble file myprog.pyc
+
+.. seealso::
+
+  :ref:`help syntax arange` for the specification of a address range :ref:`deparse <deparse>`, :ref:`list <list>`, :ref: `info pc <info_pc>`

docs/commands/files/list.rst

@@ -4,56 +4,46 @@
 List (show me the code!)
 ------------------------
 
-**list** [*module] [ *first* [ *num* ]]
+**list** [ *range* ]
 
-**list** *location* [*num*]
+**list**  **+** | **-** | **.**
 
-List source code.
+List source code. See :ref:`help syntax range` for what can go in a list range.
 
 Without arguments, print lines centered around the current line. If
 *num* is given that number of lines is shown.
 
-If this is the first `list` command issued since the debugger command
-loop was entered, then the current line is the current frame. If a
-subsequent list command was issued with no intervening frame changing,
-then that is start the line after we last one previously shown.
+Without arguments, print lines starting from where the last list left off
+since the last entry to the debugger. We start off at the location indicated
+by the current stack.
 
-A *location* is either:
+in addition you can also use:
 
-* a number, e.g. 5,
-* a function, e.g. `join` or `os.path.join`
-* a module, e.g. os or os.path
-* a filename, colon, and a number, e.g. `foo.py:5`,
-* a module name and a number, e.g,. `os.path:5`.
-* a "." for the current line number
-* a "-" for the lines before the current linenumber
-
-If the location form is used with a subsequent parameter, the
-parameter is the starting line number is used. When there two numbers
-are given, the last number value is treated as a stopping line unless
-it is less than the start line, in which case it is taken to mean the
-number of lines to list instead.
-
-Wherever a number is expected, it does not need to be a constant --
-just something that evaluates to a positive integer.
+  - a '.' for the location of the current frame
+  - a '-' for the lines before the last list
+  - a '+' for the lines after the last list
 
 Examples:
 +++++++++
 
 ::
 
-    list 5            # List starting from line 5
-    list 4+1          # Same as above.
-    list foo.py:5     # List starting from line 5 of foo.py
-    list os.path:5    # List starting from line 5 of os.path
-    list os.path 5    # Same as above.
-    list os.path 5 6  # list lines 5 and 6 of os.path
-    list os.path 5 2  # Same as above, since 2 < 5.
-    list foo.py:5 2   # List two lines starting from line 5 of foo.py
-    list os.path.join # List lines around the os.join.path function.
-    list .            # List lines centered from where we currently are stopped
-    list -            # List lines previous to those just shown
+    list 5               # List starting from line 5 of current file
+    list 5 ,             # Same as above.
+    list , 5             # list listsize lines before and up to 5
+    list foo.py:5        # List starting from line 5 of file foo.py
+    list foo()           # List starting from function foo
+    list os.path:5       # List starting from line 5 of module os.path
+    list os.path:5, 6    # list lines 5 and 6 of os.path
+    list os.path:5, +1   # Same as above. +1 is an offset
+    list os.path:5, 1    # Same as above, since 1 < 5.
+    list os.path:5, +6   # list lines 5-11
+    list os.path.join()  # List lines centered around the os.join.path function.
+    list .               # List lines centered from where we currently are stopped
+    list -               # List lines previous to those just shown
+    list                 # List continuing from where we last left off
 
 .. seealso::
 
    :ref:`set listize <set_listsize>`, or :ref:`show listsize <show_listsize>` to see or set the number of source-code lines to list.
+	:ref:`help syntax location` for the specification of a location and :ref:`help syntax range` for the specification of a range.

docs/syntax.rst

@@ -4,5 +4,8 @@ Command Syntax
 .. toctree::
    :maxdepth: 1
 
+   syntax/arange
    syntax/command
+   syntax/examples
+   syntax/range
    syntax/suffixes

docs/syntax/arange.rst

@@ -0,0 +1,33 @@
+Syntax for Address Ranges
+=========================
+
+Address ranges are used in the `disassemble` command. It is like a
+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
+
+
+A *location* is described elsewhere. *first* and *last* can also be
+linespecs but they also may be a number or address (bytecode
+offset). And finally *last* can be an (line number) offset.
+
+A number is just a decimal number. An offset is a number prefaced with "+" and
+indicates the number to increment the line number found in *first*.
+
+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
+  
+
+See also
+---------
+  `help syntax location`

docs/syntax/examples.rst

@@ -0,0 +1,15 @@
+Command examples
+================
+
+	# This line does nothing. It is a comment. Useful in debugger command files.
+	    # This line also does nothing.
+	s    # by default, this is an alias for the "step" command
+	info program;;list # error no command 'program;;list'
+	info program ;; list # Runs two commands "info program" and "list"
+
+See also:
+---------
+
+`macro`, `alias`, `irb`, `set auto eval`, `set auto irb`, `set
+abbrev`, `info macro`, and the *show* variants of the above *set*
+commands.

docs/syntax/filename.rst

@@ -0,0 +1,13 @@
+Syntax for Indicating a Filename
+================================
+
+Filename Examples:
+------------------
+
+    file.py       => file.py
+    /tmp/file.py  =>  /tmp/file.py
+    C\:file.py    =>  C:file.py  # For Microsoft OS's
+    C\:\file.py   =>  C:\file.py # For Microsoft OS's
+    C\:\\file.py  =>  C:\file.py  # Note: double slash not needed
+    \\new.py    =>  \new.py     # Note: double slash, or filename has newline
+    my\ file.py  =>  my file.py

docs/syntax/range.rst

@@ -0,0 +1,42 @@
+Syntax for List Ranges
+======================
+
+List ranges are used in the `list` and `disassemble` commands.
+
+A list range is in one of the following forms:
+
+    location       # starting line only
+    first, last    # starting and ending line
+    , last         # ending line only
+
+
+A *location* is described elsewhere. *first* and *last* can also be
+locations but they also may be a number. And finally *last* can be a (line number)
+offset.
+
+A number is just a decimal number. An offset is a number prefaced with "+" and
+indicates the number to increment the line number found in *first*.
+
+Examples
+--------
+
+    5                    # start from line 5 of current file
+    5 ,                  # Same as above.
+    , 5                 # listsize lines before and up to 5
+    foo.py:5             # start from line 5 of file foo.py
+    foo()                # start from function foo
+    os.path:5            # start from line 5 of module os.path
+    os.path:5            # Same as above.
+    os.path:5, 6         # list lines 5 and 6 of os.path
+    os.path:5, +1        # Same as above. +1 is an offset
+    os.path:5, 1         # Same as above, since 1 < 5.
+    os.path:5, +6        # lines 5-11
+    os.path.join()       # lines starting with the os.join.path function.
+    "c:\foo.py":10,      # listsize lines starting from line 10 of c:\foo.py
+    , 'My Doc/foo.py':20 # listsize lines ending at line 20 of file: My Doc/foo.py
+
+
+See also:
+---------
+
+`help syntax location`

trepan/processor/command/disassemble.py

@@ -52,7 +52,8 @@ def cache_from_source(path, debug_override=None):
 class DisassembleCommand(Mbase_cmd.DebuggerCommand):
     """**disassemble** [*thing*]disassemble [*addresss-range*]
 
-Disassembles bytecode. See `help syntax range` for what can go in a list range.
+Disassembles bytecode. See `help syntax arange` for what can go in a
+assembly-list range.
 
 Without arguments, print lines starting from where the last list left off
 since the last entry to the debugger. We start off at the location indicated
@@ -81,6 +82,10 @@ class DisassembleCommand(Mbase_cmd.DebuggerCommand):
    disassemble *0, *10              # Disassemble offset 0-10
    disassemble myprog.pyc           # Disassemble file myprog.pyc
 
+See also:
+---------
+
+`help syntax arange`, `deparse`, `list`, `info pc`.
 """
 
     aliases       = ('disasm',)  # Note: we will have disable