Ticket #14498: trac_14498-further-docfixes-dg.patch

File trac_14498-further-docfixes-dg.patch, 9.1 KB (added by darij, 6 years ago)

now with fixed doc :)

  • sage/combinat/abstract_tree.py

    # HG changeset patch
    # User darij grinberg <darijgrinberg@gmail.com>
    # 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 b by a word describing a path from the roo 
    4444
    4545**Canonical labellings**
    4646
    47 Equality between instances of classes extending both of :class:`AbstractTree`
     47Equality between instances of classes extending both :class:`AbstractTree`
    4848and ``A`` is entirely defined by the equality defined on the elements of
    49 ``A``. A canonical labelling of such a tree however, should be such that two
    50 trees ``a`` and ``b`` satisfying ``a == b`` should have the same canonical
     49``A``. A canonical labelling of such a tree, however, should be such that
     50two trees ``a`` and ``b`` satisfying ``a == b`` have the same canonical
    5151labellings. On the other hand, the canonical labellings of trees ``a`` and
    5252``b`` satisfying ``a != b`` are expected to be different.
    5353
    class AbstractClonableTree(AbstractTree) 
    16141614
    16151615    def __getitem__(self, idx):
    16161616        """
     1617        Return the ``idx``-th child of ``self`` (which is a subtree) if
     1618        ``idx`` is an integer, or the ``idx[n-1]``-th child of the
     1619        ``idx[n-2]``-th child of the ... of the ``idx[0]``-th child of
     1620        ``self`` if ``idx`` is a list (or iterable) of length `n`.
     1621
     1622        The indexing of the children is zero-based.
     1623
    16171624        INPUT:
    16181625
    1619         - ``idx`` -- a valid path in ``self`` identifying a node
     1626        - ``idx`` -- an integer, or a valid path in ``self`` identifying a node
    16201627
    16211628        .. NOTE::
    16221629
    class AbstractClonableTree(AbstractTree) 
    16381645            Traceback (most recent call last):
    16391646            ...
    16401647            IndexError: list index out of range
     1648
     1649            sage: u = BinaryTree(None)
     1650            sage: v = BinaryTree([u, u])
     1651            sage: w = BinaryTree([u, v])
     1652            sage: t = BinaryTree([v, w])
     1653            sage: z = BinaryTree([w, t])
     1654            sage: z[0,1]
     1655            [., .]
     1656            sage: z[0,0]
     1657            .
     1658            sage: z[1]
     1659            [[., .], [., [., .]]]
     1660            sage: z[1,1]
     1661            [., [., .]]
     1662            sage: z[1][1,1]
     1663            [., .]
    16411664        """
    16421665        if isinstance(idx, slice):
    16431666            return ClonableArray.__getitem__(self, idx)
    class AbstractLabelledTree(AbstractTree) 
    17321755
    17331756    def label(self, path=None):
    17341757        """
    1735         Returns the label of ``self``
     1758        Return the label of ``self``.
    17361759
    17371760        INPUT:
    17381761
    class AbstractLabelledTree(AbstractTree) 
    17661789
    17671790    def labels(self):
    17681791        """
    1769         Returns the list of labels of ``self``
     1792        Return the list of labels of ``self``.
    17701793
    17711794        EXAMPLES::
    17721795
    class AbstractLabelledTree(AbstractTree) 
    17831806
    17841807    def leaf_labels(self):
    17851808        """
    1786         Returns the list of labels of the leaves of ``self``
     1809        Return the list of labels of the leaves of ``self``.
     1810
     1811        In case of a labelled binary tree, these "leaves" are not actually
     1812        the leaves of the binary trees, but the nodes whose both children
     1813        are leaves!
    17871814
    17881815        EXAMPLES::
    17891816
  • sage/combinat/binary_tree.py

    diff --git a/sage/combinat/binary_tree.py b/sage/combinat/binary_tree.py
    a b class BinaryTree(AbstractClonableTree, C 
    14221422        is a quotient of the weak order on the `n`-th symmetric group.
    14231423        See [CP12]_.
    14241424
    1425         EXAMPLES::
     1425        EXAMPLES:
    14261426
    14271427        For example, the tree::
    14281428
    class BinaryTree(AbstractClonableTree, C 
    14841484        This list is computed by performing all left rotates possible on
    14851485        its nodes.
    14861486
    1487         EXAMPLES::
     1487        EXAMPLES:
    14881488
    14891489        For this tree::
    14901490
    class BinaryTree(AbstractClonableTree, C 
    15421542        is a quotient of the weak order on the `n`-th symmetric group.
    15431543        See [CP12]_.
    15441544
    1545         EXAMPLES::
     1545        EXAMPLES:
    15461546
    15471547        The tree::
    15481548
    class BinaryTree(AbstractClonableTree, C 
    15881588        This is the list of all trees obtained by a right rotate of
    15891589        one of its nodes.
    15901590
    1591         EXAMPLES::
     1591        EXAMPLES:
    15921592
    15931593        The list of successors of::
    15941594
    class BinaryTree(AbstractClonableTree, C 
    20072007        EXAMPLES:
    20082008
    20092009        Showing only the nodes of a binary tree, here is an
    2010         example for the over operation:
     2010        example for the over operation::
    20112011
    20122012            |   o       __o__       _o_         |
    20132013            |  / \  /  /     \  =  /   \        |
    class BinaryTree(AbstractClonableTree, C 
    20592059            [      \     /  ]
    20602060            [       o   o   ]
    20612061
    2062         The same in the labelled case:
     2062        The same in the labelled case::
    20632063
    20642064            sage: b1 = b1.canonical_labelling()
    20652065            sage: b2 = b2.canonical_labelling()
    class BinaryTree(AbstractClonableTree, C 
    20882088    @combinatorial_map(name="Under operation on Binary Trees")
    20892089    def under(self, bt):
    20902090        r"""
    2091         The ``under`` (`\backslash`) operation defined by Loday-Ronco
    2092         [LodayRonco]_.
     2091        Return ``self`` under ``bt``, where "under" is the ``under``
     2092        (`\backslash`) operation defined by Loday-Ronco [LodayRonco]_.
    20932093
    20942094        If `T` and `T'` are two binary trees, then `T` under `T'`
    2095         (written `T \ T'`) is defined as the tree obtained by grafting
    2096         `T` on the leftmost leaf of `T'`. More precisely, `T \ T'` is
    2097         defined by identifying the root of `T` with the leftmost
    2098         leaf of `T'`. See section 4.5 of [HNT05]_.
    2099 
    2100         If `T'` is empty, then `T \ T' = T`.
    2101 
    2102         EXAMPLES::
     2095        (written `T \backslash T'`) is defined as the tree obtained
     2096        by grafting `T` on the leftmost leaf of `T'`. More precisely,
     2097        `T \backslash T'` is defined by identifying the root of `T`
     2098        with the leftmost leaf of `T'`. See section 4.5 of [HNT05]_.
     2099
     2100        If `T'` is empty, then `T \backslash T' = T`.
     2101
     2102        EXAMPLES:
    21032103
    21042104        Showing only the nodes of a binary tree, here is an
    2105         example for the under operation:
     2105        example for the under operation::
    21062106
    21072107            sage: b1 = BinaryTree([[],[]])
    21082108            sage: b2 = BinaryTree([None,[]])
    class BinaryTree(AbstractClonableTree, C 
    21422142            [      \        ]
    21432143            [       o       ]
    21442144
    2145         The same in the labelled case:
     2145        The same in the labelled case::
    21462146
    21472147            sage: b1 = b1.canonical_labelling()
    21482148            sage: b2 = b2.canonical_labelling()
    class LabelledBinaryTree(AbstractLabelle 
    27782778    Labelled binary trees.
    27792779
    27802780    A labelled binary tree is a binary tree (see :class:`BinaryTree` for
    2781     the meaning of this) with a label assigned to each node and leaf.
     2781    the meaning of this) with a label assigned to each node.
    27822782    The labels need not be integers, nor are they required to be distinct.
    27832783    ``None`` can be used as a label.
    27842784
     2785    .. WARNING::
     2786
     2787        While it is possible to assign values to leaves (not just nodes)
     2788        using this class, these labels are disregarded by various
     2789        methods such as
     2790        :meth:`~sage.combinat.abstract_tree.AbstractLabelledTree.labels`,
     2791        :meth:`~sage.combinat.abstract_tree.AbstractLabelledTree.map_labels`,
     2792        and (ironically)
     2793        :meth:`~sage.combinat.abstract_tree.AbstractLabelledTree.leaf_labels`.
     2794
    27852795    INPUT:
    27862796
    27872797    - ``children`` -- ``None`` (default) or a list, tuple or iterable of
    27882798      length `2` of labelled binary trees or convertible objects. This
    27892799      corresponds to the standard recursive definition of a labelled
    2790       binary tree as given by a pair of:
    2791 
    2792       - either a leaf or a pair of labelled binary trees,
     2800      binary tree as being either a leaf, or a pair of:
     2801
     2802      - a pair of labelled binary trees,
    27932803      - and a label.
    27942804
    27952805      (The label is specified in the keyword variable ``label``; see
    class LabelledBinaryTree(AbstractLabelle 
    28052815      explicitly).
    28062816
    28072817      It is also allowed to abbreviate ``[None, None]`` by ``[]`` if
    2808       one does not want to label the leaves.
     2818      one does not want to label the leaves (which one shouldn't do
     2819      anyway!).
    28092820
    28102821    - ``label`` -- (default: ``None``) the label to be put on the root
    28112822      of this tree.
    class LabelledBinaryTree(AbstractLabelle 
    28232834
    28242835        sage: LabelledBinaryTree(None)
    28252836        .
    2826         sage: LabelledBinaryTree(None, label="ae")
     2837        sage: LabelledBinaryTree(None, label="ae")    # not well supported
    28272838        'ae'
    28282839        sage: LabelledBinaryTree([])
    28292840        None[., .]
    2830         sage: LabelledBinaryTree([], label=3)
     2841        sage: LabelledBinaryTree([], label=3)    # not well supported
    28312842        3[., .]
    28322843        sage: LabelledBinaryTree([None, None])
    28332844        None[., .]
    class LabelledBinaryTree(AbstractLabelle 
    29682979            algorithms like Robinson-Schensted-Knuth, binary
    29692980            search tree insertion involves no bumping.
    29702981
    2971         EXAMPLES::
     2982        EXAMPLES:
    29722983
    29732984        The example from Fig. 2 of [HNT05]_::
    29742985