From 55d4717d000af10d2fcc81db083595c07559c9fe Mon Sep 17 00:00:00 2001
From: rocky <rocky@gnu.org>
Date: Mon, 9 Dec 2024 19:11:42 -0500
Subject: [PATCH] Go over jump, skip and eval, and python doc

---
 docs/commands/data/eval.rst      |  3 ++-
 docs/commands/running/jump.rst   | 14 +++++++++++---
 docs/commands/running/skip.rst   |  6 +++---
 docs/commands/support/python.rst |  2 ++
 trepan/processor/command/eval.py |  6 +++---
 trepan/processor/command/jump.py | 17 +++++++++++++++--
 trepan/processor/command/skip.py |  3 +--
 7 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/docs/commands/data/eval.rst b/docs/commands/data/eval.rst
index d18f83ec..6b34092e 100644
--- a/docs/commands/data/eval.rst
+++ b/docs/commands/data/eval.rst
@@ -14,7 +14,7 @@ given, the following translations occur:
 
 ::
 
-   assert = <expr>       => <expr>
+   assert <expr>         => <expr>
    {if|elif} <expr> :    => <expr>
    while <expr> :        => <expr>
    return <expr>         => <expr>
@@ -37,5 +37,6 @@ Eval Examples
 
 .. seealso::
 
+   :ref:`python <pyton>`,
    :ref:`set autoeval <set_autoeval>`, :ref:`pr <pr>`,
    :ref:`pp <pp>` and :ref:`examine <examine>`.
diff --git a/docs/commands/running/jump.rst b/docs/commands/running/jump.rst
index 35b172cd..e0b5ef7a 100644
--- a/docs/commands/running/jump.rst
+++ b/docs/commands/running/jump.rst
@@ -6,9 +6,17 @@ Jump
 
 **jump** *lineno*
 
-Set the next line that will be executed. The line must be within the
-stopped or bottom-most execution frame.
+Set the next line that will be executed.
+
+There are a number of limitations on what line can be set.
+
+You can't jump:
+- into the body of a for loop
+- into an ``except`` block from outside
+- outside or inside of a code block you are stopped
+
 
 .. seealso::
 
-   :ref:`step <step>` :ref:`skip <skip>`, :ref:`next <next>`, :ref:`continue <continue>`, and :ref:`finish <finish>` provide other ways to progress
+   :ref:`skip <skip>`,
+   :ref:`next <next>`, :ref:`step <step>` :ref:`continue <continue>`, and :ref:`finish <finish>` provide other ways to progress
diff --git a/docs/commands/running/skip.rst b/docs/commands/running/skip.rst
index 8282aea7..086a1acb 100644
--- a/docs/commands/running/skip.rst
+++ b/docs/commands/running/skip.rst
@@ -6,9 +6,9 @@ Skip
 
 **skip** [*count*]
 
-Set the next line that will be executed. The line must be within the
-stopped or bottom-most execution frame.
+Skip over (don't run) the next line that will be executed.
 
 .. seealso::
 
-   :ref:`step <step>` :ref:`jump <jump>`, :ref:`continue <continue>`, and :ref:`finish <finish>` provide other ways to progress execution.
+   :ref:`next <next>` :ref:`step <step>` :ref:`jump <jump>`, :ref:`continue <continue>`, and
+   :ref:`finish <finish>` provide other ways to progress execution.
diff --git a/docs/commands/support/python.rst b/docs/commands/support/python.rst
index cc09d7de..424cbe98 100644
--- a/docs/commands/support/python.rst
+++ b/docs/commands/support/python.rst
@@ -20,4 +20,6 @@ To issue a debugger command use function *dbgr()*. For example:
 
 .. seealso::
 
+   :ref:`eval <eval>`,
+   :ref:`set autoeval <set_autoeval>`,
    :ref:`ipython <ipython>`, and :ref:`bpython <bpython>`.
diff --git a/trepan/processor/command/eval.py b/trepan/processor/command/eval.py
index dcc9d574..528a8f64 100644
--- a/trepan/processor/command/eval.py
+++ b/trepan/processor/command/eval.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-#  Copyright (C) 2012-2013, 2015, 2017, 2020, 2023 Rocky Bernstein
+#  Copyright (C) 2012-2013, 2015, 2017, 2020, 2023-2024 Rocky Bernstein
 #
 #  This program is free software: you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -29,7 +29,7 @@ class EvalCommand(DebuggerCommand):
     about to be run. If the command ends `?` (via an alias) and no string is
     given, the following translations occur:
 
-       assert = <expr>       => <expr>
+       assert <expr>         => <expr>
        {if|elif} <expr> :    => <expr>
        while <expr> :        => <expr>
        return <expr>         => <expr>
@@ -53,7 +53,7 @@ class EvalCommand(DebuggerCommand):
     See also:
     ---------
 
-    `deval`, `set autoeval`, `pr`, `pp` and `examine`."""
+    `python`, `deval`, `set autoeval`, `pr`, `pp` and `examine`."""
 
     aliases = ("eval?", "?")
     short_help = "Print value of expression EXP"
diff --git a/trepan/processor/command/jump.py b/trepan/processor/command/jump.py
index 18ac5358..9bf35015 100644
--- a/trepan/processor/command/jump.py
+++ b/trepan/processor/command/jump.py
@@ -26,8 +26,21 @@
 class JumpCommand(DebuggerCommand):
     """**jump** *lineno*
 
-    Set the next line that will be executed. The line must be within the
-    stopped or bottom-most execution frame."""
+    Set the next line that will be executed.
+
+    There are a number of limitations on what line can be set.
+
+    You can't jump:
+      - into the body of a for loop
+      - into an 'except' block from outside
+      - outside or inside of a code block you are stopped
+
+    See also:
+    ---------
+
+    `skip`, `next`, `step`, `jump`, `continue`, `return` and
+    `finish` for other ways to progress execution.
+    """
 
     aliases = ("j",)
     category = "running"
diff --git a/trepan/processor/command/skip.py b/trepan/processor/command/skip.py
index f8432fec..ba0362e1 100644
--- a/trepan/processor/command/skip.py
+++ b/trepan/processor/command/skip.py
@@ -23,8 +23,7 @@
 class SkipCommand(DebuggerCommand):
     """**skip** [*count*]
 
-    Set the next line that will be executed. The line must be within the
-    stopped or bottom-most execution frame.
+    Skip over (don't run) the next line that will be executed.
 
     See also:
     ---------