Ticket #5542: trac_5542-docstring-fixes.patch

File trac_5542-docstring-fixes.patch, 37.9 KB (added by mvngu, 4 years ago)

  • sage/groups/perm_gps/permgroup.py 

    # HG changeset patch
# User Minh Van Nguyen <nguyenminh2@gmail.com>
# Date 1237275995 25200
# Node ID 664f5d732bc8c38fa5df8c48c054201eee39eaba
# Parent  5f82fbe330b31b7707d99f60c0ad8ea867a0057d
Docstring fixes for permgroup.py; follow up to #5536

diff -r 5f82fbe330b3 -r 664f5d732bc8 sage/groups/perm_gps/permgroup.py
    a b  
    11r""" 
    22Permutation groups 
    33 
    4 A permutation group is a finite group G whose elements are 
    5 permutations of a given finite set X (i.e., bijections X -> X) and 
    6 whose group operation is the composition of permutations. The 
    7 number of elements of `X` is called the degree of G. 
     4A permutation group is a finite group `G` whose elements are 
     5permutations of a given finite set `X` (i.e., bijections 
     6`X \longrightarrow X`) and whose group operation is the composition of 
     7permutations. The number of elements of `X` is called the degree of `G`. 
    88 
    9 In Sage a permutation is represented as either a string that 
     9In Sage, a permutation is represented as either a string that 
    1010defines a permutation using disjoint cycle notation, or a list of 
    11 tuples, which represent disjoint cycles. 
    12  
    13 :: 
     11tuples, which represent disjoint cycles. That is:: 
    1412 
    1513    (a,...,b)(c,...,d)...(e,...,f)  <--> [(a,...,b), (c,...,d),..., (e,...,f)] 
    1614                      () = identity <--> [] 
    … …  
    2018constructions: 
    2119 
    2220- permutation group generated by elements, 
    23 - direct_product_permgroups, which takes a list of permutation 
     21- ``direct_product_permgroups``, which takes a list of permutation 
    2422  groups and returns their direct product. 
    2523 
    2624JOKE: Q: What's hot, chunky, and acts on a polygon? A: Dihedral 
    … …  
    137135def load_hap(): 
    138136     """ 
    139137     Load the GAP hap package into the default GAP interpreter 
    140      interface, and if this fails, try one more time to load it. 
     138     interface. If this fails, try one more time to load it. 
    141139 
    142      EXAMPLES: 
     140     EXAMPLES:: 
     141 
    143142         sage: sage.groups.perm_gps.permgroup.load_hap() 
    144143     """ 
    145144     try: 
    … …  
    149148 
    150149def direct_product_permgroups(P): 
    151150    """ 
    152     Takes the direct product of the permutation groups listed in P. 
     151    Takes the direct product of the permutation groups listed in ``P``. 
    153152     
    154153    EXAMPLES:: 
    155154     
    … …  
    180179 
    181180def from_gap_list(G, src): 
    182181    r""" 
    183     Convert a string giving a list of GAP permutations into a list of elements of G. 
     182    Convert a string giving a list of GAP permutations into a list of 
     183    elements of ``G``. 
    184184     
    185185    EXAMPLES:: 
    186186     
    … …  
    210210    INPUT: 
    211211     
    212212     
    213     -  ``gens`` - list of generators 
     213    -  ``gens`` - list of generators (default: ``None``) 
    214214     
    215     -  ``gap_group`` - a gap permutation group 
     215    -  ``gap_group`` - a gap permutation group (default: ``None``) 
    216216     
    217     -  ``canonicalize`` - bool (default: True), if True 
     217    -  ``canonicalize`` - bool (default: ``True``); if ``True``, 
    218218       sort generators and remove duplicates 
    219219     
    220220     
    221     OUTPUT: a permutation group 
     221    OUTPUT:  
     222 
     223    - A permutation group. 
    222224     
    223225    EXAMPLES:: 
    224226     
    … …  
    237239        [(1,2,3,4), (1,3)] 
    238240     
    239241    We can also create permutation groups whose generators are Gap 
    240     permutation objects. 
    241      
    242     :: 
     242    permutation objects:: 
    243243     
    244244        sage: p = gap('(1,2)(3,7)(4,6)(5,8)'); p 
    245245        (1,2)(3,7)(4,6)(5,8) 
    246246        sage: PermutationGroup([p]) 
    247247        Permutation Group with generators [(1,2)(3,7)(4,6)(5,8)] 
    248248     
    249     EXAMPLES: There is an underlying gap object that implements each 
    250     permutation group. 
    251      
    252     :: 
     249    There is an underlying gap object that implements each 
     250    permutation group:: 
    253251     
    254252        sage: G = PermutationGroup([[(1,2,3,4)]]) 
    255253        sage: G._gap_() 
    … …  
    299297        INPUT: 
    300298         
    301299         
    302         -  ``gens`` - list of generators 
     300        -  ``gens`` - list of generators (default: ``None``) 
    303301         
    304         -  ``gap_group`` - a gap permutation group 
     302        -  ``gap_group`` - a gap permutation group (default: ``None``) 
    305303         
    306         -  ``canonicalize`` - bool (default: True), if True 
     304        -  ``canonicalize`` - bool (default: ``True``); if ``True``, 
    307305           sort generators and remove duplicates 
    308306         
    309307         
    310         OUTPUT: a permutation group 
     308        OUTPUT:  
     309 
     310        - A permutation group. 
    311311         
    312         EXAMPLES: We explicitly construct the alternating group on four 
    313         elements. 
    314          
    315         :: 
     312        EXAMPLES:  
     313 
     314        We explicitly construct the alternating group on four 
     315        elements:: 
    316316         
    317317            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 
    318318            Permutation Group with generators [(2,3,4), (1,2,3)] 
    … …  
    368368 
    369369    def _gap_init_(self): 
    370370        r""" 
    371         Returns a string showing how to declare / initialize self in Gap. 
     371        Returns a string showing how to declare / initialize ``self`` in Gap. 
    372372        Stored in the ``self._gap_string`` attribute. 
    373373         
    374         EXAMPLES: The ``_gap_init_`` method shows how you 
     374        EXAMPLES:  
     375 
     376        The ``_gap_init_`` method shows how you 
    375377        would define the Sage ``PermutationGroup_generic`` 
    376378        object in Gap:: 
    377379         
    … …  
    384386 
    385387    def _magma_init_(self, magma): 
    386388        r""" 
    387         Returns a string showing how to declare / intialize self in Magma. 
     389        Returns a string showing how to declare / initialize self in Magma. 
    388390         
    389         EXAMPLES: We explicitly construct the alternating group on four 
     391        EXAMPLES: 
     392 
     393        We explicitly construct the alternating group on four 
    390394        elements. In Magma, one would type the string below to construct 
    391         the group. 
    392          
    393         :: 
     395        the group:: 
    394396         
    395397            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 
    396398            Permutation Group with generators [(2,3,4), (1,2,3)] 
    … …  
    402404 
    403405    def __cmp__(self, right): 
    404406        """ 
    405         Compare self and right. 
     407        Compare ``self`` and ``right``. 
    406408         
    407409        The ordering is whatever it is in Gap. 
    408410         
    … …  
    422424 
    423425    def __call__(self, x, check=True): 
    424426        """ 
    425         Coerce x into this permutation group. 
     427        Coerce ``x`` into this permutation group. 
    426428         
    427429        The input can be either a string that defines a permutation in 
    428430        cycle notation, a permutation group element, a list of integers 
    429431        that gives the permutation as a mapping, a list of tuples, or the 
    430432        integer 1. 
    431433         
    432         EXAMPLES: We illustrate each way to make a permutation in S4:: 
     434        EXAMPLES: 
     435 
     436        We illustrate each way to make a permutation in `S_4`:: 
    433437 
    434438            sage: G = SymmetricGroup(4) 
    435439            sage: G((1,2,3,4)) 
    … …  
    482486 
    483487    def _coerce_impl(self, x): 
    484488        r""" 
    485         Implicit coercion of x into self. 
     489        Implicit coercion of ``x`` into ``self``. 
    486490         
    487         EXAMPLES: We illustrate some arithmetic that involves implicit 
    488         coercion of elements in different permutation groups. 
    489          
    490         :: 
     491        EXAMPLES: 
     492 
     493        We illustrate some arithmetic that involves implicit 
     494        coercion of elements in different permutation groups:: 
    491495         
    492496            sage: g1 = PermutationGroupElement([(1,2),(3,4,5)]) 
    493497            sage: g1.parent() 
    … …  
    540544 
    541545    def __contains__(self, item): 
    542546        """ 
    543         Returns boolean value of "item in self" 
     547        Returns boolean value of ``item`` in ``self``. 
    544548         
    545549        EXAMPLES:: 
    546550         
    … …  
    567571 
    568572    def has_element(self, item): 
    569573        """ 
    570         Returns boolean value of "item in self" - however *ignores* 
     574        Returns boolean value of ``item`` in ``self`` - however *ignores* 
    571575        parentage. 
    572576         
    573577        EXAMPLES:: 
    … …  
    610614            sage: G.gens() 
    611615            [(1,2), (1,2,3)] 
    612616         
    613         Note that the generators need not be minimal though duplicates are 
    614         removed. 
    615          
    616         :: 
     617        Note that the generators need not be minimal, though duplicates are 
     618        removed:: 
    617619         
    618620            sage: G = PermutationGroup([[(1,2)], [(1,3)], [(2,3)], [(1,2)]]) 
    619621            sage: G.gens() 
    620622            [(2,3), (1,2), (1,3)] 
    621623         
    622         :: 
     624        We can use index notation to access the generators returned by 
     625        ``self.gens``:: 
    623626         
    624627            sage: G = PermutationGroup([[(1,2,3,4), (5,6)], [(1,2)]]) 
    625628            sage: g = G.gens() 
    … …  
    628631            sage: g[1] 
    629632            (1,2,3,4)(5,6) 
    630633         
    631         TESTS: We make sure that the trivial group gets handled correctly. 
    632          
    633         :: 
     634        TESTS: 
     635 
     636        We make sure that the trivial group gets handled correctly:: 
    634637         
    635638            sage: SymmetricGroup(1).gens() 
    636639            [()] 
    … …  
    640643 
    641644    def gens_small(self): 
    642645        """ 
    643         Returns a generating set of G which has few elements. As neither 
    644         irredundancy, nor minimal length is proven, it is fast. 
     646        Returns a generating set of a group `G`, which has few elements. 
     647        As neither irredundancy nor minimal length is proven, it is fast. 
    645648         
    646649        EXAMPLES:: 
    647650         
    … …  
    660663 
    661664    def gen(self, i): 
    662665        r""" 
    663         Returns the ith generator of self; that is, the ith element of the 
    664         list ``self.gens()``. 
     666        Returns the i-th generator of ``self``; that is, the i-th element 
     667        of the list ``self.gens()``. 
    665668         
    666         EXAMPLES: We explicitly construct the alternating group on four 
     669        EXAMPLES: 
     670 
     671        We explicitly construct the alternating group on four 
    667672        elements:: 
    668673         
    669674            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 
    … …  
    683688    def cayley_table(self, names="x"): 
    684689        """ 
    685690        Returns the multiplication table, or Cayley table, of the finite 
    686         group G in the form of a matrix with symbolic coefficients. This 
     691        group `G` in the form of a matrix with symbolic coefficients. This 
    687692        function is useful for learning, teaching, and exploring elementary 
    688         group theory. Of course, G must be a group of low order. 
    689          
     693        group theory. Of course, `G` must be a group of low order. 
     694        
     695        EXAMPLES: 
     696  
    690697        As the last line below illustrates, the ordering used here in the 
    691         first row is the same as in G.list(). 
    692          
    693         EXAMPLES:: 
     698        first row is the same as in ``G.list()``:: 
    694699         
    695700            sage: G = PermutationGroup(['(1,2,3)', '(2,3)']) 
    696701            sage: G.cayley_table() 
    … …  
    757762    def exponent(self): 
    758763        """ 
    759764        Computes the exponent of the group. The exponent `e` of a 
    760         group `G` is the lcm of the orders of its elements, that 
     765        group `G` is the LCM of the orders of its elements, that 
    761766        is, `e` is the smallest integer such that `g^e=1` 
    762767        for all `g \in G`. 
    763768         
    … …  
    840845     
    841846    def _repr_(self): 
    842847        r""" 
    843         Returns a string describing self. 
     848        Returns a string describing ``self``. 
    844849         
    845         EXAMPLES: We explicitly construct the alternating group on four 
     850        EXAMPLES: 
     851 
     852        We explicitly construct the alternating group on four 
    846853        elements. Note that the ``AlternatingGroup`` class has 
    847         its own representation string. 
    848          
    849         :: 
     854        its own representation string:: 
    850855         
    851856            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 
    852857            Permutation Group with generators [(2,3,4), (1,2,3)] 
    … …  
    859864 
    860865    def _latex_(self): 
    861866        r""" 
    862         Method for describing self in LaTeX. Encapsulates 
    863         ``self.gens()`` in angle brackets to denote that self 
    864         in generated by these elements. Called by the 
     867        Method for describing ``self`` in LaTeX. Encapsulates 
     868        ``self.gens()`` in angle brackets to denote that ``self`` 
     869        is generated by these elements. Called by the 
    865870        ``latex()`` function. 
    866871         
    867         EXAMPLES: We explicitly construct the alternating group on four 
    868         elements. 
    869          
    870         :: 
     872        EXAMPLES: 
     873 
     874        We explicitly construct the alternating group on four 
     875        elements:: 
    871876         
    872877            sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 
    873878            Permutation Group with generators [(2,3,4), (1,2,3)] 
    … …  
    930935 
    931936    def id(self): 
    932937        """ 
    933         (Same as self.group_id().) Return the ID code of this group, which 
     938        (Same as ``self.group_id()``.) Return the ID code of this group, which 
    934939        is a list of two integers. Requires "optional" database_gap-4.4.x 
    935940        package. 
    936941         
    … …  
    944949 
    945950    def center(self): 
    946951        """ 
    947         Return the subgroup of elements of that commute with every element 
     952        Return the subgroup of elements that commute with every element 
    948953        of this group. 
    949954         
    950955        EXAMPLES:: 
    … …  
    961966 
    962967    def direct_product(self,other,maps=True): 
    963968        """ 
    964         Wraps GAP's DirectProduct, Embedding, and Projection. 
     969        Wraps GAP's ``DirectProduct``, ``Embedding``, and ``Projection``. 
    965970         
    966         Sage calls GAP's DirectProduct, which chooses an efficient 
     971        Sage calls GAP's ``DirectProduct``, which chooses an efficient 
    967972        representation for the direct product. The direct product of 
    968973        permutation groups will be a permutation group again. For a direct 
    969         product D, the GAP operation Embedding(D,i) returns the 
    970         homomorphism embedding the i-th factor into D. The GAP operation 
    971         Projection(D,i) gives the projection of D onto the i-th factor. 
    972          
     974        product ``D``, the GAP operation ``Embedding(D,i)`` returns the 
     975        homomorphism embedding the i-th factor into ``D``. The GAP operation 
     976        ``Projection(D,i)`` gives the projection of ``D`` onto the i-th factor. 
     977        This method returns a 5-tuple: a permutation group and 4 morphisms. 
     978 
    973979        INPUT: 
    974980         
    975981         
    976982        -  ``self, other`` - permutation groups 
    977983         
    978            This method returns a 5-tuple - a permutation groups and 4 
    979            morphisms. 
    980984         
    981985         
    982986        OUTPUT: 
    … …  
    985989        -  ``D`` - a direct product of the inputs, returned as 
    986990           a permutation group as well 
    987991         
    988         -  ``iota1`` - an embedding of self into D 
     992        -  ``iota1`` - an embedding of ``self`` into ``D`` 
    989993         
    990         -  ``iota2`` - an embedding of other into D 
     994        -  ``iota2`` - an embedding of ``other`` into ``D`` 
    991995         
    992         -  ``pr1`` - the projection of D onto self (giving a 
     996        -  ``pr1`` - the projection of ``D`` onto ``self`` (giving a 
    993997           splitting 1 - other - D - self - 1) 
    994998         
    995         -  ``pr2`` - the projection of D onto other (giving a 
     999        -  ``pr2`` - the projection of ``D`` onto ``other`` (giving a 
    9961000           splitting 1 - self - D - other - 1) 
    9971001         
    9981002         
    … …  
    10421046 
    10431047    def subgroup(self, gens): 
    10441048        """ 
    1045         Wraps the PermutationGroup_subgroup constructor. The argument gens 
    1046         is a list of elements of self. 
     1049        Wraps the ``PermutationGroup_subgroup`` constructor. The argument 
     1050        ``gens`` is a list of elements of ``self``. 
    10471051         
    10481052        EXAMPLES:: 
    10491053         
    … …  
    10831087 
    10841088    def cohomology(self, n, p = 0): 
    10851089        r""" 
    1086         Computes the group cohomology H_n(G, F), where F = Z if p=0 and F 
    1087         = Z/pZ if p 0 is a prime. Wraps HAP's GroupHomology function, 
    1088         written by Graham Ellis. 
     1090        Computes the group cohomology `H^n(G, F)`, where `F = \mathbb{Z}` 
     1091        if `p=0` and `F = \mathbb{Z} / p \mathbb{Z}` if `p > 0` is a prime. 
     1092        Wraps HAP's ``GroupHomology`` function, written by Graham Ellis. 
    10891093         
    10901094        REQUIRES: GAP package HAP (in gap_packages-\*.spkg). 
    10911095         
    … …  
    11061110            ... 
    11071111            ValueError: p must be 0 or prime 
    11081112         
    1109         This computes `H^4(S_3,ZZ)`, `H^4(S_3,ZZ/2ZZ)`, 
    1110         resp. 
     1113        This computes `H^4(S_3, \mathbb{Z})` and 
     1114        `H^4(S_3, \mathbb{Z} / 2 \mathbb{Z})`, respectively. 
    11111115         
    11121116        AUTHORS: 
    11131117 
    … …  
    11371141    def cohomology_part(self, n, p = 0): 
    11381142        """ 
    11391143        Computes the p-part of the group cohomology `H^n(G, F)`, 
    1140         where `F = Z` if `p=0` and `F = Z/pZ` if 
    1141         `p >0` is a prime. Wraps HAP's Homology function, written 
     1144        where `F = \mathbb{Z}` if `p=0` and `F = \mathbb{Z} / p \mathbb{Z}` if 
     1145        `p > 0` is a prime. Wraps HAP's Homology function, written 
    11421146        by Graham Ellis, applied to the `p`-Sylow subgroup of 
    11431147        `G`. 
    11441148         
    … …  
    11751179    def homology(self, n, p = 0): 
    11761180        r""" 
    11771181        Computes the group homology `H_n(G, F)`, where 
    1178         `F = Z` if `p=0` and `F = Z/pZ` if 
    1179         `p >0` is a prime. Wraps HAP's GroupHomology function, 
     1182        `F = \mathbb{Z}` if `p=0` and `F = \mathbb{Z} / p \mathbb{Z}` if 
     1183        `p > 0` is a prime. Wraps HAP's ``GroupHomology`` function, 
    11801184        written by Graham Ellis. 
    11811185         
    11821186        REQUIRES: GAP package HAP (in gap_packages-\*.spkg). 
    … …  
    11851189 
    11861190        - David Joyner and Graham Ellis 
    11871191         
    1188         The example below computes `H_7(S_5,ZZ)`, 
    1189         `H_7(S_5,ZZ/2ZZ)`, `H_7(S_5,ZZ/3ZZ)`, and 
    1190         `H_7(S_5,ZZ/5ZZ)`, resp. To compute the `2`-part 
    1191         of `H_7(S_5,ZZ)`, use the ``homology_part`` 
     1192        The example below computes `H_7(S_5, \mathbb{Z})`, 
     1193        `H_7(S_5, \mathbb{Z} / 2 \mathbb{Z})`,  
     1194        `H_7(S_5, \mathbb{Z} / 3 \mathbb{Z})`, and 
     1195        `H_7(S_5, \mathbb{Z} / 5 \mathbb{Z})`, respectively. To compute the 
     1196        `2`-part of `H_7(S_5, \mathbb{Z})`, use the ``homology_part`` 
    11921197        function. 
    11931198         
    11941199        EXAMPLES:: 
    … …  
    12271232    def homology_part(self, n, p = 0): 
    12281233        r""" 
    12291234        Computes the `p`-part of the group homology 
    1230         `H_n(G, F)`, where `F = Z` if `p=0` and 
    1231         `F = Z/pZ` if `p >0` is a prime. Wraps HAP's 
    1232         Homology function, written by Graham Ellis, applied to the 
     1235        `H_n(G, F)`, where `F = \mathbb{Z}` if `p=0` and 
     1236        `F = \mathbb{Z} / p \mathbb{Z}` if `p > 0` is a prime. Wraps HAP's 
     1237        ``Homology`` function, written by Graham Ellis, applied to the 
    12331238        `p`-Sylow subgroup of `G`. 
    12341239         
    12351240        REQUIRES: GAP package HAP (in gap_packages-\*.spkg). 
    … …  
    12631268        r""" 
    12641269        Returns the matrix of values of the irreducible characters of a 
    12651270        permutation group `G` at the conjugacy classes of 
    1266         `G`. The columns represent the the conjugacy classes of 
     1271        `G`. The columns represent the conjugacy classes of 
    12671272        `G` and the rows represent the different irreducible 
    12681273        characters in the ordering given by GAP. 
    12691274         
    … …  
    13201325            [(1, 1, 1, 1, 1, 1, 1), (5, 1, 2, -1, -1, 0, 0), (5, 1, -1, 2, -1, 0, 0), (8, 0, -1, -1, 0, zeta5^3 + zeta5^2 + 1, -zeta5^3 - zeta5^2), (8, 0, -1, -1, 0, -zeta5^3 - zeta5^2, zeta5^3 + zeta5^2 + 1), (9, 1, 0, 0, 1, -1, -1), (10, -2, 1, 1, 0, 0, 0)] 
    13211326         
    13221327        Suppose that you have a class function `f(g)` on 
    1323         `G` and you know the values `v_1, ..., v_n` on 
     1328        `G` and you know the values `v_1, \dots, v_n` on 
    13241329        the conjugacy class elements in 
    13251330        ``conjugacy_classes_representatives(G)`` = 
    13261331        `[g_1, \ldots, g_n]`. Since the irreducible characters 
    … …  
    13301335        a linear combination of these basis elements, 
    13311336        `f = c_1\rho_1 + \cdots + c_n\rho_n`. To find 
    13321337        the coefficients `c_i`, you simply solve the linear system 
    1333         ``character_table_values(G)``\*`[v_1, ..., v_n] = [c_1, ..., c_n]`, 
    1334         where `[v_1, ...,v_n]` = 
    1335         ``character_table_values(G)`` `^{-1}[c_1, ...,c_n]`. 
     1338        ``character_table_values(G)``\* [v_1, ..., v_n] = [c_1, ..., c_n], 
     1339        where [v_1, ..., v_n] = ``character_table_values(G)`` ^(-1)[c_1, ..., c_n]. 
    13361340         
    13371341        AUTHORS: 
    13381342         
    … …  
    13411345        .. note:: 
    13421346          
    13431347           The ordering of the columns of the character table of a group 
    1344            corresponds to the ordering of the list. However, in general there is 
    1345            no way to canonically list (or index) the conjugacy classes of a group. 
    1346            Therefore the ordering of  the columns of the character table of  
    1347            a group is somewhat random. 
     1348           corresponds to the ordering of the list. However, in general 
     1349           there is no way to canonically list (or index) the conjugacy 
     1350           classes of a group. Therefore the ordering of the columns of the 
     1351           character table of a group is somewhat random. 
    13481352        """ 
    13491353        current_randstate().set_seed_gap() 
    13501354        G    = self._gap_() 
    … …  
    13651369 
    13661370    def irreducible_characters(self): 
    13671371        r""" 
    1368         Returns a list of the irreducible characters of self. 
     1372        Returns a list of the irreducible characters of ``self``. 
    13691373         
    13701374        EXAMPLES:: 
    13711375         
    … …  
    13811385 
    13821386    def trivial_character(self): 
    13831387        r""" 
    1384         Returns the trivial character of self. 
     1388        Returns the trivial character of ``self``. 
    13851389         
    13861390        EXAMPLES:: 
    13871391         
    … …  
    13931397 
    13941398    def character(self, values): 
    13951399        r""" 
    1396         Returns a group character of from values, where values is a list of 
    1397         the values of the character evaluated on the conjugacy classes. 
     1400        Returns a group character of from ``values``, where ``values`` is 
     1401        a list of the values of the character evaluated on the conjugacy 
     1402        classes. 
    13981403         
    13991404        EXAMPLES:: 
    14001405         
    … …  
    14081413    def conjugacy_classes_representatives(self): 
    14091414        """  
    14101415        Returns a complete list of representatives of conjugacy classes in 
    1411         a permutation group G. The ordering is that given by GAP. 
     1416        a permutation group `G`. The ordering is that given by GAP. 
    14121417         
    14131418        EXAMPLES:: 
    14141419         
    … …  
    14381443    def conjugacy_classes_subgroups(self): 
    14391444        """  
    14401445        Returns a complete list of representatives of conjugacy classes of 
    1441         subgroups in a permutation group G. The ordering is that given by 
     1446        subgroups in a permutation group `G`. The ordering is that given by 
    14421447        GAP. 
    14431448         
    14441449        EXAMPLES:: 
    … …  
    14771482         
    14781483    def normalizer(self, g): 
    14791484        """ 
    1480         Returns the normalizer of g in self. 
     1485        Returns the normalizer of ``g`` in ``self``. 
    14811486         
    14821487        EXAMPLES:: 
    14831488         
    … …  
    14971502 
    14981503    def centralizer(self, g): 
    14991504        """ 
    1500         Returns the centralizer of g in self. 
     1505        Returns the centralizer of ``g`` in ``self``. 
    15011506         
    15021507        EXAMPLES:: 
    15031508         
    … …  
    15171522 
    15181523    def isomorphism_type_info_simple_group(self): 
    15191524        """ 
    1520         Is the group is simple, then this returns the name of the group. 
     1525        If the group is simple, then this returns the name of the group. 
    15211526         
    15221527        EXAMPLES:: 
    15231528         
    … …  
    15351540     
    15361541    def is_abelian(self): 
    15371542        """ 
    1538         Return True if this group is abelian. 
     1543        Return ``True`` if this group is abelian. 
    15391544         
    15401545        EXAMPLES:: 
    15411546         
    … …  
    15501555         
    15511556    def is_commutative(self): 
    15521557        """ 
    1553         Return True if this group is commutative. 
     1558        Return ``True`` if this group is commutative. 
    15541559         
    15551560        EXAMPLES:: 
    15561561         
    … …  
    15651570 
    15661571    def is_cyclic(self): 
    15671572        """ 
    1568         Return True if this group is cyclic. 
     1573        Return ``True`` if this group is cyclic. 
    15691574         
    15701575        EXAMPLES:: 
    15711576         
    … …  
    15801585 
    15811586    def is_elementary_abelian(self): 
    15821587        """ 
    1583         Return True if this group is elementary abelian. An elementary 
    1584         abelian group is a finite Abelian group, where every nontrivial 
    1585         element has order p, where p is a prime. 
     1588        Return ``True`` if this group is elementary abelian. An elementary 
     1589        abelian group is a finite abelian group, where every nontrivial 
     1590        element has order `p`, where `p` is a prime. 
    15861591         
    15871592        EXAMPLES:: 
    15881593         
    … …  
    15971602     
    15981603    def isomorphism_to(self,right): 
    15991604        """ 
    1600         Return an isomorphism self to right if the groups are isomorphic, 
    1601         otherwise None. 
     1605        Return an isomorphism from ``self`` to ``right`` if the groups 
     1606        are isomorphic, otherwise ``None``. 
    16021607         
    16031608        INPUT: 
    16041609         
    … …  
    16081613        -  ``right`` - a permutation group 
    16091614         
    16101615         
    1611         OUTPUT: None or a morphism of permutation groups. 
     1616        OUTPUT: 
     1617 
     1618        - ``None`` or a morphism of permutation groups. 
    16121619         
    16131620        EXAMPLES:: 
    16141621         
    … …  
    16411648 
    16421649    def is_isomorphic(self, right): 
    16431650        """ 
    1644         Return True if the groups are isomorphic. If mode="verbose" then an 
     1651        Return ``True`` if the groups are isomorphic. If mode="verbose" then an 
    16451652        isomorphism is printed. 
    16461653         
    16471654        INPUT: 
    … …  
    16521659        -  ``right`` - a permutation group 
    16531660         
    16541661         
    1655         OUTPUT: bool 
     1662        OUTPUT: 
     1663 
     1664        - boolean; ``True`` if ``self`` and ``right`` are isomorphic groups;  
     1665          ``False`` otherwise. 
    16561666         
    16571667        EXAMPLES:: 
    16581668         
    … …  
    16741684 
    16751685    def is_monomial(self): 
    16761686        """ 
    1677         Returns True if the group is monomial. A finite group is monomial 
     1687        Returns ``True`` if the group is monomial. A finite group is monomial 
    16781688        if every irreducible complex character is induced from a linear 
    16791689        character of a subgroup. 
    16801690         
    … …  
    16881698 
    16891699    def is_nilpotent(self): 
    16901700        """ 
    1691         Return True if this group is nilpotent. 
     1701        Return ``True`` if this group is nilpotent. 
    16921702         
    16931703        EXAMPLES:: 
    16941704         
    … …  
    17031713 
    17041714    def is_normal(self, other): 
    17051715        """ 
    1706         Return True if this group is a normal subgroup of other. 
     1716        Return ``True`` if this group is a normal subgroup of ``other``. 
    17071717         
    17081718        EXAMPLES:: 
    17091719         
    … …  
    17201730     
    17211731    def is_perfect(self): 
    17221732        """ 
    1723         Return True if this group is perfect. A group is perfect if it 
     1733        Return ``True`` if this group is perfect. A group is perfect if it 
    17241734        equals its derived subgroup. 
    17251735         
    17261736        EXAMPLES:: 
    … …  
    17361746 
    17371747    def is_pgroup(self): 
    17381748        """ 
    1739         Returns True if the group is a p-group. A finite group is a p-group 
    1740         if its order is of the form `p^n` for a prime integer p and 
    1741         a nonnegative integer n. 
     1749        Returns ``True`` if this group is a `p`-group. A finite group is 
     1750        a `p`-group if its order is of the form `p^n` for a prime integer 
     1751        `p` and a nonnegative integer `n`. 
    17421752         
    17431753        EXAMPLES:: 
    17441754         
    … …  
    17501760 
    17511761    def is_polycyclic(self): 
    17521762        r""" 
    1753         Return True if this group is polycyclic. A group is polycyclic if 
    1754         it has a subnormal series with cyclic factors. (For finite groups 
     1763        Return ``True`` if this group is polycyclic. A group is polycyclic if 
     1764        it has a subnormal series with cyclic factors. (For finite groups, 
    17551765        this is the same as if the group is solvable - see 
    1756         ``is_solvable``)].) 
     1766        ``is_solvable``.) 
    17571767         
    17581768        EXAMPLES:: 
    17591769         
    … …  
    17681778     
    17691779    def is_simple(self): 
    17701780        """ 
    1771         Returns True if the group is simple. A group is simple if it has no 
     1781        Returns ``True`` if the group is simple. A group is simple if it has no 
    17721782        proper normal subgroups. 
    17731783         
    17741784        EXAMPLES:: 
    … …  
    17811791 
    17821792    def is_solvable(self): 
    17831793        """ 
    1784         Returns True if the group is solvable. 
     1794        Returns ``True`` if the group is solvable. 
    17851795         
    17861796        EXAMPLES:: 
    17871797         
    … …  
    17931803     
    17941804    def is_subgroup(self,other): 
    17951805        """ 
    1796         Returns true if self is a subgroup of other. 
     1806        Returns ``True`` if ``self`` is a subgroup of ``other``. 
    17971807         
    17981808        EXAMPLES:: 
    17991809         
    … …  
    18121822         
    18131823    def is_supersolvable(self): 
    18141824        """ 
    1815         Returns True if the group is supersolvable. A finite group is 
     1825        Returns ``True`` if the group is supersolvable. A finite group is 
    18161826        supersolvable if it has a normal series with cyclic factors. 
    18171827         
    18181828        EXAMPLES:: 
    … …  
    18251835 
    18261836    def is_transitive(self): 
    18271837        """ 
    1828         Return True if self is a transitive group, i.e., if the action 
     1838        Return ``True`` if ``self`` is a transitive group, i.e., if the action 
    18291839        of self on [1..n] is transitive. 
    18301840         
    18311841        EXAMPLES:: 
    … …  
    18381848            False 
    18391849 
    18401850        Note that this differs from the definition in GAP, where 
    1841         IsTransitive returns whether the group is transitive on the 
     1851        ``IsTransitive`` returns whether the group is transitive on the 
    18421852        set of points moved by the group. 
    18431853 
    18441854        :: 
    … …  
    18531863     
    18541864    def normalizes(self,other): 
    18551865        r""" 
    1856         Returns True if the group other is normalized by the self. Wraps 
    1857         GAP's IsNormal function. 
     1866        Returns ``True`` if the group ``other`` is normalized by ``self``. 
     1867        Wraps GAP's ``IsNormal`` function. 
    18581868         
    1859         A group G normalizes a group U if and only if for every 
     1869        A group `G` normalizes a group `U` if and only if for every 
    18601870        `g \in G` and `u \in U` the element `u^g` 
    1861         is a member of U. Note that U need not be a subgroup of G. 
     1871        is a member of `U`. Note that `U` need not be a subgroup of `G`. 
    18621872         
    18631873        EXAMPLES:: 
    18641874         
    … …  
    18731883            sage: H.normalizes(G) 
    18741884            True 
    18751885         
    1876         In the last example, G and H are disjoint, so each normalizes the 
     1886        In the last example, `G` and `H` are disjoint, so each normalizes the 
    18771887        other. 
    18781888        """ 
    18791889        return self._gap_().IsNormal(other._gap_()).bool() 
    … …  
    18851895        Return the composition series of this group as a list of 
    18861896        permutation groups. 
    18871897         
    1888         EXAMPLES: These computations use pseudo-random numbers, so we set 
     1898        EXAMPLES: 
     1899 
     1900        These computations use pseudo-random numbers, so we set 
    18891901        the seed for reproducible testing. 
    18901902         
    18911903        :: 
    … …  
    19121924        Return the derived series of this group as a list of permutation 
    19131925        groups. 
    19141926         
    1915         EXAMPLES: These computations use pseudo-random numbers, so we set 
     1927        EXAMPLES: 
     1928 
     1929        These computations use pseudo-random numbers, so we set 
    19161930        the seed for reproducible testing. 
    19171931         
    19181932        :: 
    … …  
    19351949        Return the lower central series of this group as a list of 
    19361950        permutation groups. 
    19371951         
    1938         EXAMPLES: These computations use pseudo-random numbers, so we set 
     1952        EXAMPLES: 
     1953 
     1954        These computations use pseudo-random numbers, so we set 
    19391955        the seed for reproducible testing. 
    19401956         
    19411957        :: 
    … …  
    19551971 
    19561972    def molien_series(self): 
    19571973        r""" 
    1958         Returns the Molien series of a transtive permutation group. The 
     1974        Returns the Molien series of a transitive permutation group. The 
    19591975        function 
    19601976         
    19611977        .. math:: 
    19621978         
    1963                      M(x) = (1/|G|)\sum_{g\in G} det(1-x*g)^(-1)          
     1979                     M(x) = (1/|G|)\sum_{g\in G} \det(1-x*g)^{-1} 
    19641980         
    19651981         
    1966         is sometimes called the "Molien series" of G. GAP's 
     1982        is sometimes called the "Molien series" of `G`. GAP's 
    19671983        ``MolienSeries`` is associated to a character of a 
    1968         group G. How are these related? A group G, given as a permutation 
    1969         group on n points, has a "natural" representation of dimension n, 
    1970         given by permutation matrices. The Molien series of G is the one 
    1971         associated to that permutation representation of G using the above 
     1984        group `G`. How are these related? A group `G`, given as a permutation 
     1985        group on `n` points, has a "natural" representation of dimension `n`, 
     1986        given by permutation matrices. The Molien series of `G` is the one 
     1987        associated to that permutation representation of `G` using the above 
    19721988        formula. Character values then count fixed points of the 
    19731989        corresponding permutations. 
    19741990         
    … …  
    19982014        Return the normal subgroups of this group as a (sorted in 
    19992015        increasing order) list of permutation groups. 
    20002016         
    2001         The normal subgroups of `H = PSL(2,7)xPSL(2,7)` are 
     2017        The normal subgroups of `H = PSL(2,7) \cdot PSL(2,7)` are 
    20022018        `1`, two copies of `PSL(2,7)` and `H` 
    2003         itself, as the following example shows. EXAMPLES:: 
     2019        itself, as the following example shows. 
     2020 
     2021        EXAMPLES:: 
    20042022         
    20052023            sage: G = PSL(2,7) 
    20062024            sage: D = G.direct_product(G) 
    … …  
    20222040 
    20232041    def poincare_series(self, p=2, n=10): 
    20242042        """ 
    2025         Returns the Poincare series of G mod p (p must be a prime), for n1 
    2026         large. In other words, if you input a finite group G, a prime p, 
    2027         and a positive integer n, it returns a quotient of polynomials 
    2028         f(x)=P(x)/Q(x) whose coefficient of `x^k` equals the rank 
    2029         of the vector space `H_k(G,ZZ/pZZ)`, for all k in the 
    2030         range `1\leq k \leq n`. 
     2043        Returns the Poincare series of `G \mod p` (`p \geq 2` must be a 
     2044        prime), for `n` large. In other words, if you input a finite 
     2045        group `G`, a prime `p`, and a positive integer `n`, it returns a 
     2046        quotient of polynomials `f(x) = P(x) / Q(x)` whose coefficient of 
     2047        `x^k` equals the rank of the vector space 
     2048        `H_k(G, \mathbb{Z} / p \mathbb{Z})`, for all `k` in the 
     2049        range `1 \leq k \leq n`. 
    20312050         
    20322051        REQUIRES: GAP package HAP (in gap_packages-\*.spkg). 
    20332052         
    … …  
    20612080 
    20622081    def sylow_subgroup(self, p): 
    20632082        """ 
    2064         Returns a Sylow p-subgroups of the finite group G, where p is a 
    2065         prime. This is a p-subgroup of G whose index in G is coprime to p. 
    2066         Wraps the GAP function SylowSubgroup. 
     2083        Returns a Sylow `p`-subgroup of the finite group `G`, where `p` is a 
     2084        prime. This is a `p`-subgroup of `G` whose index in `G` is coprime to 
     2085        `p`. Wraps the GAP function ``SylowSubgroup``. 
    20672086         
    20682087        EXAMPLES:: 
    20692088         
    … …  
    20912110        Return the upper central series of this group as a list of 
    20922111        permutation groups. 
    20932112         
    2094         EXAMPLES: These computations use pseudo-random numbers, so we set 
     2113        EXAMPLES: 
     2114 
     2115        These computations use pseudo-random numbers, so we set 
    20952116        the seed for reproducible testing. 
    20962117         
    20972118        :: 
    … …  
    21102131 
    21112132class PermutationGroup_subgroup(PermutationGroup_generic): 
    21122133    """ 
    2113     Subgroup subclass of PermutationGroup_generic, so instance methods 
     2134    Subgroup subclass of ``PermutationGroup_generic``, so instance methods 
    21142135    are inherited. 
    21152136     
    21162137    EXAMPLES:: 
    … …  
    21332154        Initialization method for the 
    21342155        ``PermutationGroup_subgroup`` class. 
    21352156         
    2136         INPUTS: ambient - the ambient group from which to construct this 
    2137         subgroup gens - the generators of the subgroup from_group - True: 
    2138         subroup is generated from a Gap string representation of the 
    2139         generators check- True: checks if gens are indeed elements of the 
    2140         ambient group canonicalize - bool (default: True), if True sort 
    2141         generators and remove duplicates 
     2157        INPUTS: 
     2158 
     2159        - ``ambient`` - the ambient group from which to construct this 
     2160          subgroup 
     2161 
     2162        - ``gens`` - the generators of the subgroup 
     2163 
     2164        - ``from_group`` - ``True``: subgroup is generated from a Gap 
     2165          string representation of the generators (default: ``False``) 
     2166 
     2167        - ``check`` - ``True``: checks if ``gens`` are indeed elements of the 
     2168          ambient group 
     2169 
     2170        - ``canonicalize`` - boolean (default: ``True``); if ``True``, sort 
     2171          generators and remove duplicates 
    21422172         
    2143         EXAMPLES: An example involving the dihedral group on four elements. 
     2173        EXAMPLES: 
     2174 
     2175        An example involving the dihedral group on four elements. 
    21442176        `D_8` contains a cyclic subgroup or order four:: 
    21452177         
    21462178            sage: G = DihedralGroup(4) 
    … …  
    21882220 
    21892221    def __cmp__(self, other): 
    21902222        r""" 
    2191         Compare self and other. If self and other are in a common ambient 
    2192         group, then self = other precisely if self is contained in other. 
     2223        Compare ``self`` and ``other``. If ``self`` and ``other`` are in 
     2224        a common ambient group, then self = other precisely if ``self`` is 
     2225        contained in ``other``. 
    21932226         
    21942227        EXAMPLES:: 
    21952228         
    … …  
    22202253        Returns a string representation / description of the permutation 
    22212254        subgroup. 
    22222255         
    2223         EXAMPLES: An example involving the dihedral group on four elements, 
     2256        EXAMPLES: 
     2257 
     2258        An example involving the dihedral group on four elements, 
    22242259        `D_8`:: 
    22252260         
    22262261            sage: G = DihedralGroup(4) 
    … …  
    22372272 
    22382273    def _latex_(self): 
    22392274        r""" 
    2240         Return latex representation of this group. 
     2275        Return LaTeX representation of this group. 
    22412276         
    2242         EXAMPLES: An example involving the dihedral group on four elements, 
     2277        EXAMPLES: 
     2278 
     2279        An example involving the dihedral group on four elements, 
    22432280        `D_8`:: 
    22442281         
    22452282            sage: G = DihedralGroup(4) 
    … …  
    22562293         
    22572294    def ambient_group(self): 
    22582295        """ 
    2259         Return the ambient group related to self. 
     2296        Return the ambient group related to ``self``. 
    22602297         
    2261         EXAMPLES: An example involving the dihedral group on four elements, 
     2298        EXAMPLES: 
     2299 
     2300        An example involving the dihedral group on four elements, 
    22622301        `D_8`:: 
    22632302         
    22642303            sage: G = DihedralGroup(4) 
    … …  
    22762315        """ 
    22772316        Return the generators for this subgroup. 
    22782317         
    2279         EXAMPLES: An example involving the dihedral group on four elements, 
     2318        EXAMPLES: 
     2319 
     2320        An example involving the dihedral group on four elements, 
    22802321        `D_8`:: 
    22812322         
    22822323            sage: G = DihedralGroup(4)