#############################################################################
##
#W  display.xml
#Y  Copyright (C) 2011-14                                James D. Mitchell
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="TikzString">
  <ManSection>
    <Oper Name="TikzString" Arg="obj[, options]"/>
    <Returns>A string.</Returns>
    <Description>

      This function produces a graphical representation of the object
      <A>obj</A> using the <C>tikz</C> package for &LaTeX;.
      More precisely, this operation outputs a string containing a minimal
      &LaTeX; document which can be compiled using &LaTeX; to produce a picture
      of <A>obj</A>.
      <P/>

      Currently the following types of objects are supported:

      <List>
        <Mark>blocks</Mark>
        <Item>
          If <A>obj</A> is the left or right blocks of a bipartition, then
          <C>TikzString</C> returns a graphical representation of these blocks;
          see Section <Ref Sect = "section-blocks"/>.
        </Item>
        <Mark>bipartitions</Mark>
        <Item>
          If <A>obj</A> is a bipartition, then <C>TikzString</C> returns a
          graphical representation of <A>obj</A>.
          <P/>

          If the optional second argument <A>options</A> is a record with the
          component <C>colors</C> set to <K>true</K>, then the blocks of
          <A>f</A> will be colored using the standard <C>tikz</C> colors. Due
          to the limited number of colors available in <C>tikz</C> this option
          only works when the degree of <A>obj</A> is less than 20.
          See Chapter <Ref Chap = "Bipartitions and blocks"/> for more details
          about bipartitions.
        </Item>
        <Mark>pbrs</Mark>
        <Item>
          If <A>obj</A> is a <Ref Oper="PBR"/>, then <C>TikzString</C> returns a
          graphical representation <A>obj</A>; see Chapter <Ref Sect =
            "Partitioned binary relations (PBRs)"/>.
        </Item>
        <Mark>Cayley graphs</Mark>
        <Item>
          If <A>obj</A> is a <Ref Oper="Digraph" BookName="digraphs"/> in the
          category <Ref Filt="IsCayleyDigraph" BookName="digraphs"/>, then
          <C>TikzString</C> returns a picture of <A>obj</A>. No attempt is made
          whatsoever to produce a sensible picture of the digraph <A>obj</A>,
          in fact, the vertices are all given the same coordinates. Human
          intervention is required to produce a meaningful picture from the
          value returned by this method. It is intended to make the task of
          drawing such a Cayley graph more straightforward by providing
          everything except the final layout of the graph. Please use <Ref
            Oper="DotString"/> if you want an automatically laid out diagram of
          the digraph <A>obj</A>.
        </Item>
      </List>

      <Log><![CDATA[
gap> x := Bipartition([[1, 4, -2, -3], [2, 3, 5, -5], [-1, -4]]);;
gap> TikzString(RightBlocks(x));
"%tikz\n\\documentclass{minimal}\n\\usepackage{tikz}\n\\begin{documen\
t}\n\\begin{tikzpicture}\n  \\draw[ultra thick](5,2)circle(.115);\n  \
\\draw(1.8,5) node [top] {{$1$}};\n  \\fill(4,2)circle(.125);\n  \\dr\
aw(1.8,4) node [top] {{$2$}};\n  \\fill(3,2)circle(.125);\n  \\draw(1\
.8,3) node [top] {{$3$}};\n  \\draw[ultra thick](2,2)circle(.115);\n \
 \\draw(1.8,2) node [top] {{$4$}};\n  \\fill(1,2)circle(.125);\n  \\d\
raw(1.8,1) node [top] {{$5$}};\n\n  \\draw (5,2.125) .. controls (5,2\
.8) and (2,2.8) .. (2,2.125);\n  \\draw (4,2.125) .. controls (4,2.6)\
 and (3,2.6) .. (3,2.125);\n\\end{tikzpicture}\n\n\\end{document}"
gap> x := Bipartition([[1, 5], [2, 4, -3, -5], [3, -1, -2], [-4]]);;
gap> TikzString(x);
"%tikz\n\\documentclass{minimal}\n\\usepackage{tikz}\n\\begin{documen\
t}\n\\begin{tikzpicture}\n\n  %block #1\n  %vertices and labels\n  \\\
fill(1,2)circle(.125);\n  \\draw(0.95, 2.2) node [above] {{ $1$}};\n \
 \\fill(5,2)circle(.125);\n  \\draw(4.95, 2.2) node [above] {{ $5$}};\
\n\n  %lines\n  \\draw(1,1.875) .. controls (1,1.1) and (5,1.1) .. (5\
,1.875);\n\n  %block #2\n  %vertices and labels\n  \\fill(2,2)circle(\
.125);\n  \\draw(1.95, 2.2) node [above] {{ $2$}};\n  \\fill(4,2)circ\
le(.125);\n  \\draw(3.95, 2.2) node [above] {{ $4$}};\n  \\fill(3,0)c\
ircle(.125);\n  \\draw(3, -0.2) node [below] {{ $-3$}};\n  \\fill(5,0\
)circle(.125);\n  \\draw(5, -0.2) node [below] {{ $-5$}};\n\n  %lines\
\n  \\draw(2,1.875) .. controls (2,1.3) and (4,1.3) .. (4,1.875);\n  \
\\draw(3,0.125) .. controls (3,0.7) and (5,0.7) .. (5,0.125);\n  \\dr\
aw(2,2)--(3,0);\n\n  %block #3\n  %vertices and labels\n  \\fill(3,2)\
circle(.125);\n  \\draw(2.95, 2.2) node [above] {{ $3$}};\n  \\fill(1\
,0)circle(.125);\n  \\draw(1, -0.2) node [below] {{ $-1$}};\n  \\fill\
(2,0)circle(.125);\n  \\draw(2, -0.2) node [below] {{ $-2$}};\n\n  %l\
ines\n  \\draw(1,0.125) .. controls (1,0.6) and (2,0.6) .. (2,0.125);\
\n  \\draw(3,2)--(2,0);\n\n  %block #4\n  %vertices and labels\n  \\f\
ill(4,0)circle(.125);\n  \\draw(4, -0.2) node [below] {{ $-4$}};\n\n \
%lines\n\\end{tikzpicture}\n\n\\end{document}"
gap> TikzString(UniversalPBR(2));
"%latex\n\\documentclass{minimal}\n\\usepackage{tikz}\n\\begin{docume\
nt}\n\\usetikzlibrary{arrows}\n\\usetikzlibrary{arrows.meta}\n\\newco\
mmand{\\arc}{\\draw[semithick, -{>[width = 1.5mm, length = 2.5mm]}]}\
\n\\begin{tikzpicture}[\n  vertex/.style={circle, draw, fill=black, i\
nner sep =0.04cm},\n  ghost/.style={circle, draw = none, inner sep = \
0.14cm},\n  botloop/.style={min distance = 8mm, out = -70, in = -110}\
,\n  toploop/.style={min distance = 8mm, out = 70, in = 110}]\n\n  % \
vertices and labels\n  \\foreach \\i in {1,...,2} {\n    \\node [vert\
ex] at (\\i/1.5, 3) {};\n    \\node [ghost] (\\i) at (\\i/1.5, 3) {};\
\n  }\n\n  \\foreach \\i in {1,...,2} {\n    \\node [vertex] at (\\i/\
1.5, 0) {};\n    \\node [ghost] (-\\i) at (\\i/1.5, 0) {};\n  }\n\n  \
% arcs from vertex 1\n  \\arc (1) to (-2);\n  \\arc (1) to (-1);\n  \
\\arc (1) edge [toploop] (1);\n  \\arc (1) .. controls (1.06666666666\
66667, 2.125) and (0.93333333333333324, 2.125) .. (2);\n\n  % arcs fr\
om vertex -1\n  \\arc (-1) .. controls (1.0666666666666667, 0.875) an\
d (0.93333333333333324, 0.875) .. (-2);\n  \\arc (-1) edge [botloop] \
(-1);\n  \\arc (-1) to (1);\n  \\arc (-1) to (2);\n\n  % arcs from ve\
rtex 2\n  \\arc (2) to (-2);\n  \\arc (2) to (-1);\n  \\arc (2) .. co\
ntrols (0.93333333333333324, 2.125) and (1.0666666666666667, 2.125) .\
. (1);\n  \\arc (2) edge [toploop] (2);\n\n  % arcs from vertex -2\n \
 \\arc (-2) edge [botloop] (-2);\n  \\arc (-2) .. controls (0.9333333\
3333333324, 0.875) and (1.0666666666666667, 0.875) .. (-1);\n  \\arc \
(-2) to (1);\n  \\arc (-2) to (2);\n\n\\end{tikzpicture}\n\\end{docum\
ent}"]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotString">
  <ManSection>
    <Oper Name="DotString" Arg="S[, options]"/>
    <Returns>A string.</Returns>
    <Description>
      If the argument <A>S</A> is a semigroup, and the optional second argument
      <A>options</A> is a record, then this operation produces a graphical
      representation of the partial order of
      the &D;-classes of the semigroup <A>S</A> together with the eggbox
      diagram of each &D;-class. The output is in <C>dot</C> format (also known
      as <C>GraphViz</C>) format. For details about this file format, and
      information about how to display or edit this format see
      <URL>https://www.graphviz.org</URL>.
      <P/>

      The string returned by <C>DotString</C> can be written to a file using
      the command <Ref Func="FileString" BookName="GAPDoc"/>.
      <P/>

      The &D;-classes are shown as eggbox diagrams with &L;-classes as rows and
      &R;-classes as columns; group &H;-classes are shaded gray and contain an
      asterisk. The &L;-classes and &R;-classes within a &D;-class are arranged
      to correspond to the normalization of the principal factor given by <Ref
        Attr="NormalizedPrincipalFactor"/>.
      The &D;-classes are numbered according to their index in
      <C>GreensDClasses(<A>S</A>)</C>, so that an <C>i</C> appears next to the
      eggbox diagram of <C>GreensDClasses(<A>S</A>)[i]</C>. A line from one
      &D;-class to another indicates that the higher &D;-class is greater than
      the lower one in the &D;-order on <A>S</A>.
      <P/>

      If the optional second argument <A>options</A> is present, it can be used
      to specify some options for output.

      <List>
        <Mark>number</Mark>
        <Item>
          if <C><A>options</A>.number</C> is <K>false</K>, then the &D;-classes
          in the diagram are not numbered according to their index in the list
          of &D;-classes of <A>S</A>. The default value for this option is
          <K>true</K>.
        </Item>

        <Mark>maximal</Mark>
        <Item>
          if <C><A>options</A>.maximal</C> is <K>true</K>, then the structure
          description of the group &H;-classes is displayed; see
          <Ref Attr="StructureDescription" BookName="ref"/>. Setting
          this attribute to <K>true</K> can adversely affect the performance of
          <C>DotString</C>. The default value for this option is
          <K>false</K>.
        </Item>

        <Mark>normal</Mark>
        <Item>
          if <C><A>options</A>.normal</C> is <K>false</K>, then the &L;- and
          &R;-classes within each &D;-class arranged to correspond to <Ref
            Attr="PrincipalFactor"/>.  If <C><A>options</A>.normal</C> is
          <K>true</K>, they are instead arranged to correspond to <Ref
            Attr="NormalizedPrincipalFactor"/>. Setting this attribute to
          <K>false</K> may improve the performance of <C>DotString</C> as it
          avoids the computation of <Ref
            Attr="InjectionNormalizedPrincipalFactor"/>. The default value for
          this option is <K>true</K>.
        </Item>
      </List>
      <Log><![CDATA[
gap> S := FullTransformationMonoid(3);
<full transformation monoid of degree 3>
gap> DotString(S);
"//dot\ndigraph  DClasses {\nnode [shape=plaintext]\nedge [color=blac\
k,arrowhead=none]\n1 [shape=box style=invisible label=<\n<TABLE BORDE\
R=\"0\" CELLBORDER=\"1\" CELLPADDING=\"10\" CELLSPACING=\"0\" PORT=\"\
1\">\n<TR BORDER=\"0\"><TD COLSPAN=\"1\" BORDER = \"0\" > 1</TD></TR>\
<TR><TD BGCOLOR=\"gray\">*</TD></TR>\n</TABLE>>];\n2 [shape=box style\
=invisible label=<\n<TABLE BORDER=\"0\" CELLBORDER=\"1\" CELLPADDING=\
\"10\" CELLSPACING=\"0\" PORT=\"2\">\n<TR BORDER=\"0\"><TD COLSPAN=\"\
3\" BORDER = \"0\" > 2</TD></TR><TR><TD BGCOLOR=\"gray\">*</TD><TD BG\
COLOR=\"gray\">*</TD><TD BGCOLOR=\"white\"></TD></TR>\n<TR><TD BGCOLO\
R=\"gray\">*</TD><TD BGCOLOR=\"white\"></TD><TD BGCOLOR=\"gray\">*</T\
D></TR>\n<TR><TD BGCOLOR=\"white\"></TD><TD BGCOLOR=\"gray\">*</TD><T\
D BGCOLOR=\"gray\">*</TD></TR>\n</TABLE>>];\n3 [shape=box style=invis\
ible label=<\n<TABLE BORDER=\"0\" CELLBORDER=\"1\" CELLPADDING=\"10\"\
 CELLSPACING=\"0\" PORT=\"3\">\n<TR BORDER=\"0\"><TD COLSPAN=\"1\" BO\
RDER = \"0\" > 3</TD></TR><TR><TD BGCOLOR=\"gray\">*</TD></TR>\n<TR><\
TD BGCOLOR=\"gray\">*</TD></TR>\n<TR><TD BGCOLOR=\"gray\">*</TD></TR>\
\n</TABLE>>];\n1 -> 2\n2 -> 3\n }"
gap> FileString("t3.dot", DotString(S));
1040]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotStringDigraph">
  <ManSection>
    <Oper Name="DotString" Arg="digraph" Label="for a Cayley digraph"/>
    <Returns>A string.</Returns>
    <Description>
      If <A>digraph</A> is a <Ref Oper="Digraph" BookName="digraphs"/> in the
      category <Ref Filt="IsCayleyDigraph" BookName="digraphs"/>, then
      <C>DotString</C> returns a graphical representation of <A>digraph</A>. 
      The output is in <C>dot</C> format (also known
      as <C>GraphViz</C>) format. For details about this file format, and
      information about how to display or edit this format see
      <URL>https://www.graphviz.org</URL>.
      <P/>

      The string returned by <C>DotString</C> can be written to a file using
      the command <Ref Func="FileString" BookName="GAPDoc"/>.<P/>

      See also <Ref Oper="DotLeftCayleyDigraph"/> and <Ref
        Oper="TikzLeftCayleyDigraph"/>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotSemilatticeOfIdempotents">
  <ManSection>
    <Attr Name="DotSemilatticeOfIdempotents" Arg="S"/>
    <Returns>A string.</Returns>
    <Description>
      This function produces a graphical representation of the semilattice of
      the idempotents of an inverse semigroup <A>S</A> where the elements of
      <A>S</A> have a unique semigroup inverse accessible via <Ref
        Attr="Inverse" BookName="ref"/>. The idempotents are grouped by the
      &D;-class they belong to.
      <P/>

      The output is in <C>dot</C> format (also known as <C>GraphViz</C>) format.
      For details about this file format, and information about how to display
      or edit this format see <URL>https://www.graphviz.org</URL>. <P/>

      <Example><![CDATA[
gap> S := DualSymmetricInverseMonoid(4);
<inverse block bijection monoid of degree 4 with 3 generators>
gap> DotSemilatticeOfIdempotents(S);
"//dot\ngraph graphname {\n  node [shape=point]\nranksep=2;\nsubgraph \
cluster_1{\n15 \n}\nsubgraph cluster_2{\n5 11 14 12 13 8 \n}\nsubgraph\
 cluster_3{\n2 10 6 3 4 9 7 \n}\nsubgraph cluster_4{\n1 \n}\n2 -- 1\n3\
 -- 1\n4 -- 1\n5 -- 2\n5 -- 3\n5 -- 4\n6 -- 1\n7 -- 1\n8 -- 2\n8 -- 6\
\n8 -- 7\n9 -- 1\n10 -- 1\n11 -- 2\n11 -- 9\n11 -- 10\n12 -- 3\n12 -- \
6\n12 -- 9\n13 -- 3\n13 -- 7\n13 -- 10\n14 -- 4\n14 -- 6\n14 -- 10\n15\
 -- 5\n15 -- 8\n15 -- 11\n15 -- 12\n15 -- 13\n15 -- 14\n }"]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="TexString">
  <ManSection>
    <Oper Name="TexString" Arg="f[, n]"/>
    <Returns>A string.</Returns>
    <Description>
      This function produces a string containing LaTeX code for the
      transformation <A>f</A>. If the optional paramater <A>n</A> is used, then
      this is taken to be the degree of the transformation <A>f</A>, if the
      parameter <A>n</A> is not given, then <Ref Attr="DegreeOfTransformation"
        BookName="ref"/> is used by default. If <A>n</A> is less than the
      degree of <A>f</A>, then an error is given. 
      <P/>
      <Example><![CDATA[
gap> TexString(Transformation([6, 2, 4, 3, 6, 4]));
"\\begin{pmatrix}\n  1 & 2 & 3 & 4 & 5 & 6 \\\\\n  6 & 2 & 4 & 3 & 6 &\
 4\n\\end{pmatrix}"
gap> TexString(Transformation([1, 2, 1, 3]), 5);
"\\begin{pmatrix}\n  1 & 2 & 3 & 4 & 5 \\\\\n  1 & 2 & 1 & 3 & 5\n\\en\
d{pmatrix}"]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="TikzLeftCayleyDigraph">
  <ManSection>
    <Oper Name="TikzLeftCayleyDigraph" Arg="S"/>
    <Oper Name="TikzRightCayleyDigraph" Arg="S"/>
    <Returns>A string.</Returns>
    <Description>
      If <A>S</A> is a semigroup satisfying 
      <Ref Prop="CanUseFroidurePin"/>, then <C>TikzLeftCayleyDigraph</C>
      is simply short for <C>TikzString(LeftCayleyDigraph(<A>S</A>))</C>.<P/>

      <C>TikzRightCayleyDigraph</C> can be used to produce a tikz string for
      the right Cayley graph of <A>S</A>.<P/>

      See <Ref Oper="TikzString"/> for more details, and see also 
      <Ref Oper="DotLeftCayleyDigraph"/>.

      <Log><![CDATA[
gap> TikzLeftCayleyDigraph(Semigroup(IdentityTransformation));
"\\begin{tikzpicture}[scale=1, auto, \n  vertex/.style={c\
ircle, draw, thick, fill=white, minimum size=0.65cm},\n  \
edge/.style={arrows={-angle 90}, thick},\n  loop/.style={\
min distance=5mm,looseness=5,arrows={-angle 90},thick}]\n\
\n  % Vertices . . .\n  \\node [vertex] (a) at (0, 0) {};\
\n  \\node at (0, 0) {$a$};\n\n  % Edges . . .\n  \\path[\
->] (a) edge [loop]\n           node {$a$} (a);\n\\end{ti\
kzpicture}"
gap> TikzRightCayleyDigraph(Semigroup(IdentityTransformation));
"\\begin{tikzpicture}[scale=1, auto, \n  vertex/.style={c\
ircle, draw, thick, fill=white, minimum size=0.65cm},\n  \
edge/.style={arrows={-angle 90}, thick},\n  loop/.style={\
min distance=5mm,looseness=5,arrows={-angle 90},thick}]\n\
\n  % Vertices . . .\n  \\node [vertex] (a) at (0, 0) {};\
\n  \\node at (0, 0) {$a$};\n\n  % Edges . . .\n  \\path[\
->] (a) edge [loop]\n           node {$a$} (a);\n\\end{ti\
kzpicture}"]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotLeftCayleyDigraph">
  <ManSection>
    <Oper Name="DotLeftCayleyDigraph" Arg="S"/>
    <Oper Name="DotRightCayleyDigraph" Arg="S"/>
    <Returns>A string.</Returns>
    <Description>
      If <A>S</A> is a semigroup satisfying <Ref
        Prop="CanUseFroidurePin"/>, then <C>DotLeftCayleyDigraph</C> is
      simply short for <C>DotString(LeftCayleyDigraph(<A>S</A>))</C>.<P/>

      <C>DotRightCayleyDigraph</C> can be used to produce a dot string for
      the right Cayley graph of <A>S</A>.<P/>

      See <Ref Oper="DotString"/> for more details, and see also 
      <Ref Oper="TikzLeftCayleyDigraph"/>.

      <Log><![CDATA[
gap> DotLeftCayleyDigraph(Semigroup(IdentityTransformation));
"//dot\ndigraph hgn{\nnode [shape=circle]\n1 [label=\"a\"]\n1 -> 1\n}\
\n"
gap> DotRightCayleyDigraph(Semigroup(IdentityTransformation));
"//dot\ndigraph hgn{\nnode [shape=circle]\n1 [label=\"a\"]\n1 -> 1\n}\
\n"]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>
