# HG changeset patch
# User darij grinberg
# Date 1384242654 28800
# Node ID 645f74745bca8cf681b73802e25122aa2f90b89c
# Parent fb8dd8c8318ff82b48906574aa800df67c5e935e
trac #14498: more doc fixes
diff git a/sage/combinat/abstract_tree.py b/sage/combinat/abstract_tree.py
 a/sage/combinat/abstract_tree.py
+++ b/sage/combinat/abstract_tree.py
@@ 44,10 +44,10 @@ by a word describing a path from the roo
**Canonical labellings**
Equality between instances of classes extending both of :class:`AbstractTree`
+Equality between instances of classes extending both :class:`AbstractTree`
and ``A`` is entirely defined by the equality defined on the elements of
``A``. A canonical labelling of such a tree however, should be such that two
trees ``a`` and ``b`` satisfying ``a == b`` should have the same canonical
+``A``. A canonical labelling of such a tree, however, should be such that
+two trees ``a`` and ``b`` satisfying ``a == b`` have the same canonical
labellings. On the other hand, the canonical labellings of trees ``a`` and
``b`` satisfying ``a != b`` are expected to be different.
@@ 1614,9 +1614,16 @@ class AbstractClonableTree(AbstractTree)
def __getitem__(self, idx):
"""
+ Return the ``idx``th child of ``self`` (which is a subtree) if
+ ``idx`` is an integer, or the ``idx[n1]``th child of the
+ ``idx[n2]``th child of the ... of the ``idx[0]``th child of
+ ``self`` if ``idx`` is a list (or iterable) of length `n`.
+
+ The indexing of the children is zerobased.
+
INPUT:
  ``idx``  a valid path in ``self`` identifying a node
+  ``idx``  an integer, or a valid path in ``self`` identifying a node
.. NOTE::
@@ 1638,6 +1645,22 @@ class AbstractClonableTree(AbstractTree)
Traceback (most recent call last):
...
IndexError: list index out of range
+
+ sage: u = BinaryTree(None)
+ sage: v = BinaryTree([u, u])
+ sage: w = BinaryTree([u, v])
+ sage: t = BinaryTree([v, w])
+ sage: z = BinaryTree([w, t])
+ sage: z[0,1]
+ [., .]
+ sage: z[0,0]
+ .
+ sage: z[1]
+ [[., .], [., [., .]]]
+ sage: z[1,1]
+ [., [., .]]
+ sage: z[1][1,1]
+ [., .]
"""
if isinstance(idx, slice):
return ClonableArray.__getitem__(self, idx)
@@ 1732,7 +1755,7 @@ class AbstractLabelledTree(AbstractTree)
def label(self, path=None):
"""
 Returns the label of ``self``
+ Return the label of ``self``.
INPUT:
@@ 1766,7 +1789,7 @@ class AbstractLabelledTree(AbstractTree)
def labels(self):
"""
 Returns the list of labels of ``self``
+ Return the list of labels of ``self``.
EXAMPLES::
@@ 1783,7 +1806,11 @@ class AbstractLabelledTree(AbstractTree)
def leaf_labels(self):
"""
 Returns the list of labels of the leaves of ``self``
+ Return the list of labels of the leaves of ``self``.
+
+ In case of a labelled binary tree, these "leaves" are not actually
+ the leaves of the binary trees, but the nodes whose both children
+ are leaves!
EXAMPLES::
diff git a/sage/combinat/binary_tree.py b/sage/combinat/binary_tree.py
 a/sage/combinat/binary_tree.py
+++ b/sage/combinat/binary_tree.py
@@ 1422,7 +1422,7 @@ class BinaryTree(AbstractClonableTree, C
is a quotient of the weak order on the `n`th symmetric group.
See [CP12]_.
 EXAMPLES::
+ EXAMPLES:
For example, the tree::
@@ 1484,7 +1484,7 @@ class BinaryTree(AbstractClonableTree, C
This list is computed by performing all left rotates possible on
its nodes.
 EXAMPLES::
+ EXAMPLES:
For this tree::
@@ 1542,7 +1542,7 @@ class BinaryTree(AbstractClonableTree, C
is a quotient of the weak order on the `n`th symmetric group.
See [CP12]_.
 EXAMPLES::
+ EXAMPLES:
The tree::
@@ 1588,7 +1588,7 @@ class BinaryTree(AbstractClonableTree, C
This is the list of all trees obtained by a right rotate of
one of its nodes.
 EXAMPLES::
+ EXAMPLES:
The list of successors of::
@@ 2007,7 +2007,7 @@ class BinaryTree(AbstractClonableTree, C
EXAMPLES:
Showing only the nodes of a binary tree, here is an
 example for the over operation:
+ example for the over operation::
 o __o__ _o_ 
 / \ / / \ = / \ 
@@ 2059,7 +2059,7 @@ class BinaryTree(AbstractClonableTree, C
[ \ / ]
[ o o ]
 The same in the labelled case:
+ The same in the labelled case::
sage: b1 = b1.canonical_labelling()
sage: b2 = b2.canonical_labelling()
@@ 2088,21 +2088,21 @@ class BinaryTree(AbstractClonableTree, C
@combinatorial_map(name="Under operation on Binary Trees")
def under(self, bt):
r"""
 The ``under`` (`\backslash`) operation defined by LodayRonco
 [LodayRonco]_.
+ Return ``self`` under ``bt``, where "under" is the ``under``
+ (`\backslash`) operation defined by LodayRonco [LodayRonco]_.
If `T` and `T'` are two binary trees, then `T` under `T'`
 (written `T \ T'`) is defined as the tree obtained by grafting
 `T` on the leftmost leaf of `T'`. More precisely, `T \ T'` is
 defined by identifying the root of `T` with the leftmost
 leaf of `T'`. See section 4.5 of [HNT05]_.

 If `T'` is empty, then `T \ T' = T`.

 EXAMPLES::
+ (written `T \backslash T'`) is defined as the tree obtained
+ by grafting `T` on the leftmost leaf of `T'`. More precisely,
+ `T \backslash T'` is defined by identifying the root of `T`
+ with the leftmost leaf of `T'`. See section 4.5 of [HNT05]_.
+
+ If `T'` is empty, then `T \backslash T' = T`.
+
+ EXAMPLES:
Showing only the nodes of a binary tree, here is an
 example for the under operation:
+ example for the under operation::
sage: b1 = BinaryTree([[],[]])
sage: b2 = BinaryTree([None,[]])
@@ 2142,7 +2142,7 @@ class BinaryTree(AbstractClonableTree, C
[ \ ]
[ o ]
 The same in the labelled case:
+ The same in the labelled case::
sage: b1 = b1.canonical_labelling()
sage: b2 = b2.canonical_labelling()
@@ 2778,18 +2778,28 @@ class LabelledBinaryTree(AbstractLabelle
Labelled binary trees.
A labelled binary tree is a binary tree (see :class:`BinaryTree` for
 the meaning of this) with a label assigned to each node and leaf.
+ the meaning of this) with a label assigned to each node.
The labels need not be integers, nor are they required to be distinct.
``None`` can be used as a label.
+ .. WARNING::
+
+ While it is possible to assign values to leaves (not just nodes)
+ using this class, these labels are disregarded by various
+ methods such as
+ :meth:`~sage.combinat.abstract_tree.AbstractLabelledTree.labels`,
+ :meth:`~sage.combinat.abstract_tree.AbstractLabelledTree.map_labels`,
+ and (ironically)
+ :meth:`~sage.combinat.abstract_tree.AbstractLabelledTree.leaf_labels`.
+
INPUT:
 ``children``  ``None`` (default) or a list, tuple or iterable of
length `2` of labelled binary trees or convertible objects. This
corresponds to the standard recursive definition of a labelled
 binary tree as given by a pair of:

  either a leaf or a pair of labelled binary trees,
+ binary tree as being either a leaf, or a pair of:
+
+  a pair of labelled binary trees,
 and a label.
(The label is specified in the keyword variable ``label``; see
@@ 2805,7 +2815,8 @@ class LabelledBinaryTree(AbstractLabelle
explicitly).
It is also allowed to abbreviate ``[None, None]`` by ``[]`` if
 one does not want to label the leaves.
+ one does not want to label the leaves (which one shouldn't do
+ anyway!).
 ``label``  (default: ``None``) the label to be put on the root
of this tree.
@@ 2823,11 +2834,11 @@ class LabelledBinaryTree(AbstractLabelle
sage: LabelledBinaryTree(None)
.
 sage: LabelledBinaryTree(None, label="ae")
+ sage: LabelledBinaryTree(None, label="ae") # not well supported
'ae'
sage: LabelledBinaryTree([])
None[., .]
 sage: LabelledBinaryTree([], label=3)
+ sage: LabelledBinaryTree([], label=3) # not well supported
3[., .]
sage: LabelledBinaryTree([None, None])
None[., .]
@@ 2968,7 +2979,7 @@ class LabelledBinaryTree(AbstractLabelle
algorithms like RobinsonSchenstedKnuth, binary
search tree insertion involves no bumping.
 EXAMPLES::
+ EXAMPLES:
The example from Fig. 2 of [HNT05]_::