add DocStringExtensions in Project.toml + some more in groups.md

Project.toml

@@ -5,6 +5,7 @@ version = "0.3.0"
 
 [deps]
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 GAP = "c863536a-3901-11e9-33e7-d5cd0df7b904"
 Hecke = "3e1990a7-5d81-5526-99ce-9ba3ff248f21"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"

docs/src/Groups/groups.md

@@ -13,7 +13,7 @@ Pages = ["groups.md"]
 # Groups
 
 
-Julia supports the following types of groups:
+Oscar supports the following types of groups:
 
 * `PermGroup` = groups of permutations
 * `MatrixGroup` = groups of matrices
@@ -22,7 +22,23 @@ Julia supports the following types of groups:
 * `DirectProductOfGroups` = direct product of two groups
 * `AutomorphismGroup` = group of automorphisms over a group
 
-## Permutations groups
+
+## Subgroups
+
+The subgroup of a group `G` generated by the elements `x,y,...` are defined by the following instruction:
+
+* `sub(G, [x,y,...])` ;
+* `sub(x,y,...)`.
+
+This function returns two objects: a group `H`, that is the subgroup of `G` generated by the elements `x,y,...`, and the embedding homomorphism of `H` into `G`. The object `H` has the same type of `G`, and it has no memory of the "parent" group `G`: it is an independent group.
+```@repl oscar
+G = symmetric_group(4);
+H = sub(G,[cperm([1,2,3]),cperm([2,3,4])]);
+H[1] == alternating_group(4)
+```
+
+
+## Permutation groups
 
 Permutation groups can be defined as symmetric groups, alternating groups or their subgroups.
 ```@repl oscar
@@ -43,19 +59,19 @@ Every permutation group `G` is identified by a degree, that corresponds ideally
 
 Permutations in Oscar are displayed as products of disjoint cycles, as in GAP. A permutation can be defined in different ways.
 
-* `perm(L)`: here, ``L`` is a vector ``[a_1, ... , a_n]`` containing one time each number from ``1`` to ``n`` for a certain positive integer ``n``. The output is the permutation over the set ``{1, ... , n}`` sending ``i`` into ``a_i`` for every ``i``. Example:
+* `perm(L)`: here, `L` is a vector ``[a_1, ... , a_n]`` containing one time each number from ``1`` to ``n`` for a certain positive integer ``n``. The output is the permutation over the set ``\{1, ... , n\}`` sending ``i`` into ``a_i`` for every ``i``. Example:
 ```@repl oscar
 perm([2,4,6,1,3,5])
 ```
 
 
-* `cperm(L1,L_2,...)`: here, the ``L_i`` are vectors of integers. Each vector is read as a cycle (e.g. the vector ``[1,2,3]`` corresponds to the cycle ``(1,2,3)``) and the output is the product of all the cycles. Each vector ``L_i`` need to contain all different numbers, but they are not required to be disjoint. Example:
+* `cperm(L1,L2,...)`: here, the `L1`, `L2`, etc. are vectors of integers. Each vector is read as a cycle (e.g. the vector ``[1,2,3]`` corresponds to the cycle ``(1,2,3)``) and the output is the product of all the cycles. Each of these vectors need to contain all different numbers, but at the moment they are not required to be disjoint. Example:
 ```@repl oscar
 cperm([1,2,3],[4,5,6])
 cperm([1,2],[2,3])
 ```
 
-Every permutation has always a permutation group as a parent. If a permutation is defined as above, the default parent is `Sym(n)`, where ``n`` is the highest moved point. It is possible to set another parent group for `perm` and `cperm` by adding the group at the begin of the list of arguments.
+Every permutation has always a permutation group as a parent. If a permutation is defined as above, the default parent is `Sym(n)`, where `n` is the highest moved point. It is possible to set another parent group for `perm` and `cperm` by adding the group at the begin of the list of arguments.
 ```@repl oscar
 G = symmetric_group(5);
 x = cperm([1,2]);
@@ -76,13 +92,25 @@ parent(x)
 parent(y)
 ```
 
+The function `listperm` works in the opposite way with respect to `perm`: given a permutation `x`, it returns the vector `[x(1), ... , x(n)]`, where `n` is the degree of `parent(x)`. In the example above, we would get
+```@repl oscar
+(x,y) = (cperm([1,2,3]), cperm(symmetric_group(5),[1,2,3])) # hide
+listperm(x)
+listperm(y)
+```
+
+
+#### Permutations as functions
 A permutation can be viewed as a function on the set `{1,...,n}`, hence it can be evaluated on integers.
 ```@repl oscar
 x = cperm([1,2,3,4,5]);
 x(2)
 ```
 This works also if the argument is not in the range `1:n`; in such a case, the output coincides with the input.
 
+!!! note
+    The multiplication between permutations works from the left to the right. So, if `x` and `y` are permutations and `n` is an integer, then `(x*y)(n) = (y(x(n))`, NOT `x(y(n))`.
+