#############################################################################
##
#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>
