#############################################################################
##
#W  freeinverse.xml
#Y  Copyright (C) 2011-14                                   Julius Jonusas
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################

<#GAPDoc Label="FreeInverseSemigroup" >
<ManSection>
  <Func Name = "FreeInverseSemigroup" Arg = "rank[, name]"
    Label="for a given rank"/>
  <Func Name = "FreeInverseSemigroup" Arg = "name1, name2, ..."
    Label="for a list of names"/>
  <Func Name = "FreeInverseSemigroup" Arg = "names"
    Label="for various names"/>
  <Returns>
    A free inverse semigroup.
  </Returns>
  <Description>
    Returns a free inverse semigroup on <A>rank</A> generators, where
    <A>rank</A> is a positive integer. If <A>rank</A> is not
    specified, the number of <A>names</A> is used. If <C>S</C> is a
    free inverse semigroup, then the generators can be accessed by
    <C>S.1</C>, <C>S.2</C> and so on.
<Example><![CDATA[
gap> S := FreeInverseSemigroup(7);
<free inverse semigroup on the generators
[ x1, x2, x3, x4, x5, x6, x7 ]>
gap> S := FreeInverseSemigroup(7, "s");
<free inverse semigroup on the generators
[ s1, s2, s3, s4, s5, s6, s7 ]>
gap> S := FreeInverseSemigroup("a", "b", "c");
<free inverse semigroup on the generators [ a, b, c ]>
gap> S := FreeInverseSemigroup(["a", "b", "c"]);
<free inverse semigroup on the generators [ a, b, c ]>
gap> S.1;
a
gap> S.2;
b]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeInverseSemigroupCategory">
  <ManSection>
    <Filt Name = "IsFreeInverseSemigroupCategory" Arg = "obj" Type = "Category"/>
    <Description>
      Every free inverse semigroup in &GAP; created by <Ref Oper =
      "FreeInverseSemigroup" Label = "for a given rank"/> belongs to the category
      <C>IsFreeInverseSemigroup</C>. Basic operations for a free inverse
      semigroup are: <Ref Attr = "GeneratorsOfInverseSemigroup" BookName = "ref"/>
      and <Ref Attr = "GeneratorsOfSemigroup" BookName = "ref"/>. Elements of a
      free inverse semigroup belong to the category <Ref
      Filt = "IsFreeInverseSemigroupElement"/>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeInverseSemigroup">
  <ManSection>
    <Prop Name="IsFreeInverseSemigroup" Arg="S" />
    <Returns> <K>true</K> or <K>false</K> </Returns>
    <Description>
      Attempts to determine whether the given semigroup <A>S</A> is a free
      inverse semigroup.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeInverseSemigroupElement">
  <ManSection>
    <Filt Name="IsFreeInverseSemigroupElement" Type='Category'/>
    <Description>
      Every element of a free inverse semigroup belongs to the category
      <C>IsFreeInverseSemigroupElement</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsFreeInverseSemigroupElementCollection">
  <ManSection>
    <Filt Name="IsFreeInverseSemigroupElementCollection"  Type='Category'/>
    <Description>
      Every collection of elements of a free inverse semigroup belongs to the
      category <C>IsFreeInverseSemigroupElementCollection</C>. For example,
      every free inverse semigroup belongs to
      <C>IsFreeInverseSemigroupElementCollection</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="CanonicalForm" >
  <ManSection>
    <Attr Name = "CanonicalForm" Arg = "w"
      Label = "for a free inverse semigroup element" />
    <Returns> A string. </Returns>
    <Description>
      Every element of a free inverse semigroup has a unique canonical form.
      If <A>w</A> is such an element, then <C>CanonicalForm</C> returns the
      canonical form of <A>w</A> as a string.
<Example><![CDATA[
gap> S := FreeInverseSemigroup(3);
<free inverse semigroup on the generators [ x1, x2, x3 ]>
gap> x := S.1; y := S.2;
x1
x2
gap> CanonicalForm(x ^ 3 * y ^ 3);
"x1x1x1x2x2x2x2^-1x2^-1x2^-1x1^-1x1^-1x1^-1x1x1x1x2x2x2"]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="MinimalWord" >
  <ManSection>
    <Attr Name = "MinimalWord" Arg = "w"
      Label = "for free inverse semigroup element" />
    <Returns>
      A string.
    </Returns>
    <Description>
      For an element <A>w</A> of a free inverse semigroup <C>S</C>,
      <C>MinimalWord</C> returns a word of minimal length equal to <A>w</A> in
      <C>S</C> as a string.<P/>

      Note that there maybe more than one word of minimal length which is equal
      to <A>w</A> in <C>S</C>.
<Example><![CDATA[
gap> S := FreeInverseSemigroup(3);
<free inverse semigroup on the generators [ x1, x2, x3 ]>
gap> x := S.1;
x1
gap> y := S.2;
x2
gap> MinimalWord(x ^ 3 * y ^ 3);
"x1*x1*x1*x2*x2*x2"]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>
