sagemathgh-37331: Fixed the doc sets/recursively_enumerated_set.py

Modified the doc in `sets/recursively_enumerated_set.py ` (in the section `Example: Forest structure`) to display the HTML nicely; also corrected some typos.   Sphinx `.. MATH::` directive is unable to render the `picture` environment in LaTeX, as a result of which the image is not begin displayed nicely in [sets/recursively_enumerated_set](https://doc.sagema th.org/html/en/reference/sets/sage/sets/recursively_enumerated_set.html) . I generated the pdf and png of the required image by compiling the LaTeX code and attached the image. The inspiration is from `Figure: The five complete binary trees with four leaves` in [combinat/tutorial](http s://doc.sagemath.org/html/en/reference/combinat/sage/combinat/tutorial.h tml).  This PR resolves an open issue, that is -- sagemath#37084.  The link of the original documentation -- [sets/recursively_enumerated_s et](https://doc.sagemath.org/html/en/reference/sets/sage/sets/recursivel y_enumerated_set.html). ### 📝 Checklist     - [x] The title is concise, informative, and self-explanatory. - [x] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. - [ ] I have created tests covering the changes. (Not required it seems.) - [x] I have updated the documentation accordingly. ### ⌛ Dependencies  None.  URL: sagemath#37331 Reported by: Janmenjaya Panda Reviewer(s): Martin Rubey
vbraun · Feb 17, 2024 · fca3c75 · fca3c75
2 parents 91e5ffa + ba1f5d7
commit fca3c75
Showing 1 changed file with 38 additions and 58 deletions.
diff --git a/src/sage/sets/recursively_enumerated_set.pyx b/src/sage/sets/recursively_enumerated_set.pyx
@@ -9,25 +9,23 @@ sets that are described by some ``seeds`` and a successor function
 graded, forest) or not. The elements of a set having a symmetric, graded or
 forest structure can be enumerated uniquely without keeping all of them in
 memory. Many kinds of iterators are provided in this module: depth first
-search, breadth first search or elements of given depth.
+search, breadth first search and elements of given depth.
 
 See :wikipedia:`Recursively_enumerable_set`.
 
-See documentation of :func:`RecursivelyEnumeratedSet` below for the
+See the documentation of :func:`RecursivelyEnumeratedSet` below for the
 description of the inputs.
 
 AUTHORS:
 
 - Sébastien Labbé, April 2014, at Sage Days 57, Cernay-la-ville
 
-EXAMPLES:
-
 No hypothesis on the structure
 ------------------------------
 
 What we mean by "no hypothesis" is that the set is not known
 to be a forest, symmetric, or graded. However, it may have other
-structure, like not containing an oriented cycle, that does not
+structure, such as not containing an oriented cycle, that does not
 help with the enumeration.
 
 In this example, the seed is 0 and the successor function is either ``+2``
@@ -141,7 +139,7 @@ Forest structure
 ----------------
 
 The set of words over the alphabet `\{a,b\}` can be generated from the
-empty word by appending letter `a` or `b` as a successor function. This set
+empty word by appending the letter `a` or `b` as a successor function. This set
 has a forest structure::
 
     sage: seeds = ['']
@@ -175,41 +173,23 @@ classes being very similar):
 
 .. MATH::
 
-    \begin{picture}(-300,0)(600,0)
-    % Root
-    \put(0,0){\circle*{7}}
-    \put(0,10){\makebox(0,10){``\ ''}}
-    % First Children
-    \put(-150,-60){\makebox(0,10){``a''}}
-    \put(0,-60){\makebox(0,10){``b''}}
-    \put(150,-60){\makebox(0,10){``c''}}
-    \multiput(-150,-70)(150,0){3}{\circle*{7}}
-    % Second children
-    \put(-200,-130){\makebox(0,10){``aa''}}
-    \put(-150,-130){\makebox(0,10){``ab''}}
-    \put(-100,-130){\makebox(0,10){``ac''}}
-    \put(-50,-130){\makebox(0,10){``ba''}}
-    \put(0,-130){\makebox(0,10){``bb''}}
-    \put(50,-130){\makebox(0,10){``bc''}}
-    \put(100,-130){\makebox(0,10){``ca''}}
-    \put(150,-130){\makebox(0,10){``cb''}}
-    \put(200,-130){\makebox(0,10){``cc''}}
-    \multiput(-200,-140)(50,0){9}{\circle*{7}}
-    % Legend
-    \put(100,-5){\makebox(0,10)[l]{1) An initial element}}
-    \put(-250,-5){\makebox(0,10)[l]{2) A function of an element enumerating}}
-    \put(-235,-20){\makebox(0,10)[l]{its children (if any)}}
-    % Arrows
-    \thicklines
-    \put(0,-10){\vector(0,-1){30}}
-    \put(-15,-5){\vector(-2,-1){110}}
-    \put(15,-5){\vector(2,-1){110}}
-    \multiput(-150,-80)(150,0){3}{\vector(0,-1){30}}
-    \multiput(-160,-80)(150,0){3}{\vector(-1,-1){30}}
-    \multiput(-140,-80)(150,0){3}{\vector(1,-1){30}}
-    \put(90,0){\vector(-1,0){70}}
-    \put(-215,-30){\vector(1,-1){40}}
-    \end{picture}
+    \begin{array}{ccc}
+                      & ``\," \\
+        \hfil\swarrow & \downarrow & \searrow\hfil\\
+                 ``a" & ``b" & ``c" \\
+        \begin{array}{ccc}
+             \swarrow & \downarrow & \searrow \\
+                ``aa" & ``ab" & ``ac" \\
+        \end{array}   & 
+        \begin{array}{ccc}
+             \swarrow & \downarrow & \searrow \\
+                ``ba" & ``bb" & ``bc" \\
+        \end{array}   & 
+        \begin{array}{ccc}
+             \swarrow & \downarrow & \searrow \\
+                ``ca" & ``cb" & ``cc" \\
+        \end{array}
+    \end{array}
 
 For the previous example, the two necessary pieces of information are:
 
@@ -219,7 +199,7 @@ For the previous example, the two necessary pieces of information are:
 
       lambda x: [x + letter for letter in ['a', 'b', 'c']
 
-This would actually describe an **infinite** set, as such rules describes
+This would actually describe an **infinite** set, as such rules describe
 "all words" on 3 letters. Hence, it is a good idea to replace the function by::
 
     lambda x: [x + letter for letter in ['a', 'b', 'c']] if len(x) < 2 else []
@@ -256,7 +236,7 @@ This example was provided by Florent Hivert.
 
 Here is a little more involved example. We want to iterate through all
 permutations of a given set `S`. One solution is to take elements of `S` one
-by one an insert them at every positions. So a node of the generating tree
+by one and insert them at every position. So a node of the generating tree
 contains two pieces of information:
 
 - the list ``lst`` of already inserted element;
@@ -320,7 +300,7 @@ def RecursivelyEnumeratedSet(seeds, successors, structure=None,
 
     A set `S` is called recursively enumerable if there is an algorithm that
     enumerates the members of `S`. We consider here the recursively
-    enumerated set that are described by some ``seeds`` and a successor
+    enumerated sets that are described by some ``seeds`` and a successor
     function ``successors``.
 
     Let `U` be a set and ``successors`` `:U \to 2^U` be a successor function
@@ -406,7 +386,7 @@ def RecursivelyEnumeratedSet(seeds, successors, structure=None,
 
     .. WARNING::
 
-        If you do not set the good structure, you might obtain bad results,
+        If you do not set a valid structure, you might obtain bad results,
         like elements generated twice::
 
             sage: f = lambda a: [a-1,a+1]
@@ -781,8 +761,8 @@ cdef class RecursivelyEnumeratedSet_generic(Parent):
         r"""
         Iterate over the elements of ``self`` of given depth.
 
-        An element of depth `n` can be obtained applying `n` times the
-        successor function to a seed.
+        An element of depth `n` can be obtained by applying the
+        successor function `n` times to a seed.
 
         INPUT:
 
@@ -847,7 +827,7 @@ cdef class RecursivelyEnumeratedSet_generic(Parent):
         r"""
         Iterate on the elements of ``self`` (breadth first).
 
-        This code remembers every elements generated and uses python
+        This code remembers every element generated and uses python
         queues. It is 3 times slower than the other one.
 
         See :wikipedia:`Breadth-first_search`.
@@ -876,7 +856,7 @@ cdef class RecursivelyEnumeratedSet_generic(Parent):
         r"""
         Iterate on the elements of ``self`` (in no particular order).
 
-        This code remembers every elements generated.
+        This code remembers every element generated.
 
         TESTS:
 
@@ -905,7 +885,7 @@ cdef class RecursivelyEnumeratedSet_generic(Parent):
         r"""
         Iterate on the elements of ``self`` (depth first).
 
-        This code remembers every elements generated.
+        This code remembers every element generated.
 
         The elements are traversed right-to-left, so the last element returned
         by the successor function is visited first.
@@ -1552,7 +1532,7 @@ def search_forest_iterator(roots, children, algorithm='depth'):
          [0, 0, 0], [0, 0, 1], [0, 1, 0], [0, 1, 1],
          [1, 0, 0], [1, 0, 1], [1, 1, 0], [1, 1, 1]]
 
-    This allows for iterating trough trees of infinite depth::
+    This allows for iterating through trees of infinite depth::
 
         sage: it = search_forest_iterator([[]], lambda l: [l+[0], l+[1]], algorithm='breadth')
         sage: [ next(it) for i in range(16) ]
@@ -1574,9 +1554,9 @@ def search_forest_iterator(roots, children, algorithm='depth'):
          [0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]
     """
     # Little trick: the same implementation handles both depth and
-    # breadth first search. Setting position to -1 makes a depth search
+    # breadth first search. Setting position to -1 initiates a depth search
     # (you ask the children for the last node you met). Setting
-    # position on 0 makes a breadth search (enumerate all the
+    # position on 0 initiates a breadth search (enumerate all the
     # descendants of a node before going on to the next father)
     if algorithm == 'depth':
         position = -1
@@ -1920,8 +1900,8 @@ class RecursivelyEnumeratedSet_forest(Parent):
     def _elements_of_depth_iterator_rec(self, depth=0):
         r"""
         Return an iterator over the elements of ``self`` of given depth.
-        An element of depth `n` can be obtained applying `n` times the
-        children function from a root. This function is not affected
+        An element of depth `n` can be obtained by applying the
+        children function `n` times from a root. This function is not affected
         by post processing.
 
         EXAMPLES::
@@ -1951,8 +1931,8 @@ class RecursivelyEnumeratedSet_forest(Parent):
     def elements_of_depth_iterator(self, depth=0):
         r"""
         Return an iterator over the elements of ``self`` of given depth.
-        An element of depth `n` can be obtained applying `n` times the
-        children function from a root.
+        An element of depth `n` can be obtained by applying the
+        children function `n` times from a root.
 
         EXAMPLES::
 
@@ -2010,7 +1990,7 @@ class RecursivelyEnumeratedSet_forest(Parent):
         depth first search and breadth first search failed. The
         following example enumerates all ordered pairs of nonnegative
         integers, starting from an infinite set of roots, where each
-        roots has an infinite number of children::
+        root has an infinite number of children::
 
             sage: from sage.sets.recursively_enumerated_set import RecursivelyEnumeratedSet_forest
             sage: S = RecursivelyEnumeratedSet_forest(Family(NN, lambda x : (x, 0)),