display.xml

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

<#GAPDoc Label="DotDigraph">
  <ManSection>
    <Attr Name="DotDigraph" Arg="D"/>
    <Attr Name="DotSymmetricDigraph" Arg="D"/>
    <Returns>A string.</Returns>
    <Description>
      <B>WARNING!</B> As of v2.0.0 of &Digraphs; these functions are
      deprecated in favour of:
      <List>
          <Item><Ref Attr="GraphvizDigraph"/></Item>
          <Item><Ref Attr="GraphvizGraph"/></Item>
      </List>
      <Ref Attr="GraphvizDigraph"/> and <Ref Attr="GraphvizGraph"/> return
      mutable &GAP; objects representing graphviz objects, which provide a
      more flexible means of tailoring pictures of graphs and digraphs to your
      needs. The function <C>DotDigraph</C> is synonymous with
      <C>AsString(GraphvizDigraph(<A>D</A>))</C>. It is also possible to use
      <Ref Func="Splash" BookName="graphviz"/> directly on the graphviz objects
      returned by the function <Ref Oper="GraphvizDigraph"/>, i.e.
      <C>Splash(GraphvizDigraph(<A>D</A>))</C> does precisely the same thing as
      <C>Splash(DotDigraph(<A>D</A>))</C>.
      </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GraphvizDigraph">
  <ManSection>
    <Attr Name="GraphvizDigraph" Arg="D"/>
    <Attr Name="GraphvizGraph" Arg="D"/>
    <Returns>A &graphviz; object.</Returns>
    <Description>
      <Ref Attr="GraphvizDigraph"/> and <Ref Attr="GraphvizGraph"/> return
      mutable &GAP; objects representing graphviz objects, which provide a
      flexible means of tailoring pictures of graphs and digraphs to your
      needs.
      <P/>

      <C>GraphvizDigraph</C> and <C>GraphvizGraph</C> produce &graphviz;
      objects representing the digraph <A>D</A>. Vertices are displayed as
      circles, numbered consistently with <A>D</A>. For <C>GraphvizDigraph</C>,
      edges are displayed as arrowed lines between vertices, with the arrowhead
      of each line pointing towards the range of the edge. For
      <C>GraphvizGraph</C>, edges are displayed without an arrowhead.
      <P/>

      See the &graphviz; package documentation for more details.
      <P/>

      See also <Ref Func="Splash" BookName="graphviz"/>

      <Example><![CDATA[
gap> D := CompleteDigraph(IsMutable, 4);
<mutable digraph with 4 vertices, 12 edges>
gap> gv := GraphvizGraph(D);
<graphviz graph hgn with 4 nodes and 6 edges>
gap> AsString(gv);
"//dot\ngraph hgn {\n\tnode [shape=circle] \n\t1\n\t2\n\t3\n\t4\n\t2 -\
- 1\n\t3 -- 1\n\t3 -- 2\n\t4 -- 1\n\t4 -- 2\n\t4 -- 3\n}\n"
gap> DigraphRemoveEdge(D, 1, 3);
<mutable digraph with 4 vertices, 11 edges>
gap> gv := GraphvizDigraph(D);
<graphviz digraph hgn with 4 nodes and 11 edges>
gap> AsString(gv);
"//dot\ndigraph hgn {\n\tnode [shape=circle] \n\t1\n\t2\n\t3\n\t4\n\t1\
 -> 2\n\t1 -> 4\n\t2 -> 1\n\t2 -> 3\n\t2 -> 4\n\t3 -> 1\n\t3 -> 2\n\t3\
 -> 4\n\t4 -> 1\n\t4 -> 2\n\t4 -> 3\n}\n"
]]></Example>
      </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotVertexLabelledDigraph">
  <ManSection>
    <Attr Name="DotVertexLabelledDigraph" Arg="D"/>
    <Returns>A string.</Returns>
    <Description>
      <B>WARNING!</B> As of v2.0.0 of &Digraphs; this function is
      deprecated in favour of:
      <List>
          <Item><Ref Attr="GraphvizVertexLabelledDigraph"/></Item>
      </List>
      </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GraphvizVertexLabelledDigraph">
  <ManSection>
    <Attr Name="GraphvizVertexLabelledDigraph" Arg="D"/>
    <Attr Name="GraphvizVertexLabelledGraph" Arg="D"/>
    <Returns>A &graphviz; object.</Returns>
    <Description>
        <C>GraphvizVertexLabelledDigraph</C> and
        <C>GraphvizVertexLabelledGraph</C> differ from <Ref
        Attr="GraphvizDigraph"/> and <Ref Attr="GraphvizGraph"/>only in that
        the values in <Ref Oper="DigraphVertexLabels"/> are used to label the
        vertices in the produced picture rather than the numbers <C>1</C> to
        the number of vertices of the digraph.<P/>

      See the &graphviz; package documentation for more details.
      <P/>

      See also <Ref Func="Splash" BookName="graphviz"/>

      <!-- TODO example -->
      </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotColoredDigraph">
  <ManSection>
    <Oper Name="DotVertexColoredDigraph" Arg="D, colors"/>
    <Oper Name="DotSymmetricVertexColoredDigraph" Arg="digraph, colors"/>
    <Oper Name="DotEdgeColoredDigraph" Arg="D, colors"/>
    <Oper Name="DotSymmetricEdgeColoredDigraph" Arg="digraph, colors"/>
    <Oper Name="DotColoredDigraph" Arg="D, vert_colors, edge_colors"/>
    <Oper Name="DotSymmetricColoredDigraph" Arg="digraph, vert_colors, edge_colors"/>
    <Returns>A string.</Returns>
    <Description>
      <B>WARNING!</B> As of v2.0.0 of &Digraphs; these functions are
      deprecated in favour of:
      <List>
          <Item><Ref Oper="GraphvizVertexColoredDigraph"/></Item>
          <Item><Ref Oper="GraphvizVertexColoredGraph"/></Item>
          <Item><Ref Oper="GraphvizEdgeColoredDigraph"/></Item>
          <Item><Ref Oper="GraphvizEdgeColoredGraph"/></Item>
          <Item><Ref Oper="GraphvizColoredDigraph"/></Item>
          <Item><Ref Oper="GraphvizColoredGraph"/></Item>
      </List>
      These functions return mutable &GAP; objects representing graphviz
      objects, which provide a more flexible means of tailoring pictures of
      graphs and digraphs to your needs. The <C>Dot</C> variants of these
      functions are synonymous with, for example,
      <C>AsString(GraphvizDigraph(<A>D</A>))</C>. It is also possible to use
      <Ref Func="Splash" BookName="graphviz"/> directly on the graphviz objects
      returned by the <C>Graphviz</C> variants of these functions, i.e.
      <C>Splash(GraphvizDigraph(<A>D</A>))</C> does precisely the same thing as
      <C>Splash(DotDigraph(<A>D</A>))</C>.
    </Description>
  </ManSection>
 <#/GAPDoc>

<#GAPDoc Label="GraphvizColoredDigraph">
  <ManSection>
    <Oper Name="GraphvizVertexColoredDigraph" Arg="D, colors"/>
    <Oper Name="GraphvizVertexColoredGraph" Arg="D, colors"/>
    <Oper Name="GraphvizEdgeColoredDigraph" Arg="D, colors"/>
    <Oper Name="GraphvizEdgeColoredGraph" Arg="D, colors"/>
    <Oper Name="GraphvizColoredDigraph" Arg="D, vert_colors, edge_colors"/>
    <Oper Name="GraphvizColoredGraph" Arg="D, vert_colors, edge_colors"/>
    <Returns>A &graphviz; object.</Returns>
    <Description>
      These operations produce colored &graphviz; objects representing the
        digraph <A>D</A> according to the specified colors. For all of these
        functions valid colors are strings containing:
      <List>
          <Mark>RGB</Mark>
          <Item>
              An RGB color code consisting of 6 hexadecimal digits preceded by
              a <C>#</C>. For example, <C>#ff00ff</C>.
          </Item>
          <Mark>GraphViz 2.4.11 X11 Color Scheme</Mark>
          <Item>
              One of the color strings specified at:
              <URL>http://graphviz.org/doc/info/colors.html</URL>
          </Item>
      </List>

      <C>GraphvizVertexColoredDigraph</C> and <C>GraphvizVertexColoredGraph</C>
      requires its argument <A>colors</A> to be a list of length equal to the
      number of vertices of <A>D</A> consisting of strings representing colors
      as described above.
      <P/>

      <C>GraphvizEdgeColoredDigraph</C> and <C>GraphvizEdgeColoredGraph</C>
      requires its argument <A>colors</A> to be a list of lists with the same
      shape of the out-neighbours of the digraph <A>D</A> consisting of strings
      representing colors as described above.
      <P/>

      <C>GraphvizColoredDigraph</C> and <C>GraphvizColoredGraph</C> requires
      its arguments:
      <List>
          <Mark><A>vert_colors</A></Mark>
          <Item>
            to represent vertex colors as described for
              <C>GraphvizVertexColoredDigraph</C>;
          </Item>
          <Mark><A>edge_colors</A></Mark>
          <Item>
            to represent edge colors as described for
              <C>GraphvizEdgeColoredDigraph</C>;
          </Item>
      </List>

      See the &graphviz; package documentation for more details.
      <P/>

      See also <Ref Func="Splash" BookName="graphviz"/>
      <Example><![CDATA[
gap> D := Digraph([[2], [1, 3], [2]]);
<immutable digraph with 3 vertices, 4 edges>
gap> vert_colors := ["blue", "pink", "purple"];;
gap> edge_colors := [["green"], ["green", "red"], ["red"]];;
gap> GraphvizVertexColoredDigraph(D, vert_colors);
<graphviz digraph hgn with 3 nodes and 4 edges>
gap> GraphvizVertexColoredGraph(D, vert_colors);
<graphviz graph hgn with 3 nodes and 2 edges>
gap> GraphvizEdgeColoredDigraph(D, edge_colors);
<graphviz digraph hgn with 3 nodes and 4 edges>
gap> GraphvizEdgeColoredGraph(D, edge_colors);
<graphviz graph hgn with 3 nodes and 2 edges>
gap> GraphvizColoredDigraph(D, vert_colors, edge_colors);
<graphviz digraph hgn with 3 nodes and 4 edges>
gap> GraphvizColoredGraph(D, vert_colors, edge_colors);
<graphviz graph hgn with 3 nodes and 2 edges>
]]></Example>
    </Description>
  </ManSection>
 <#/GAPDoc>

<#GAPDoc Label="DotPartialOrderDigraph">
  <ManSection>
    <Attr Name="DotPartialOrderDigraph" Arg="digraph"/>
    <Returns>A string.</Returns>
    <Description>
      <B>WARNING!</B> As of v2.0.0 of &Digraphs; these functions are
      deprecated in favour of:
      <List>
          <Item><Ref Oper="GraphvizPartialOrderDigraph"/></Item>
      </List>
      This function return a mutable &GAP; object representing a graphviz
      object, which provides a more flexible means of tailoring pictures of
      graphs and digraphs to your needs. The <C>Dot</C> variants of these
      functions are synonymous with, for example,
      <C>AsString(GraphvizDigraph(<A>D</A>))</C>. It is also possible to use
      <Ref Func="Splash" BookName="graphviz"/> directly on the graphviz objects
      returned by the <C>Graphviz</C> variants of these functions, i.e.
      <C>Splash(GraphvizDigraph(<A>D</A>))</C> does precisely the same thing as
      <C>Splash(DotDigraph(<A>D</A>))</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GraphvizPartialOrderDigraph">
  <ManSection>
    <Attr Name="GraphvizPartialOrderDigraph" Arg="D"/>
    <Returns>A &graphviz; object.</Returns>
    <Description>
      This function produces a &graphviz; object representing a partial order
      digraph <A>D</A>. <C>GraphvizPartialOrderDigraph</C> will return an
      error if <A>D</A> is not a partial order digraph. See <Ref
      Prop="IsPartialOrderDigraph"/>.<P/>

      Since <A>D</A> is a partial order, it is both reflexive and
      transitive. The output of <C>GraphvizPartialOrderDigraph</C> is the
      <Ref Attr="GraphvizDigraph"/> of the
      <Ref Oper="DigraphReflexiveTransitiveReduction"/> of <A>D</A>.<P/>

      See the &graphviz; package documentation for more details.
      <P/>

      See also <Ref Func="Splash" BookName="graphviz"/>
      <Example><![CDATA[
gap> D := Digraph([[1, 4], [2], [2, 3, 4], [4]]);
<immutable digraph with 4 vertices, 7 edges>
gap> IsPartialOrderDigraph(D);
true
gap> GraphvizPartialOrderDigraph(D);
<graphviz digraph hgn with 4 nodes and 3 edges>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotPreorderDigraph">
  <ManSection>
    <Attr Name="DotPreorderDigraph" Arg="digraph"/>
    <Attr Name="DotQuasiorderDigraph" Arg="digraph"/>
    <Returns>A string.</Returns>
    <Description>
      <B>WARNING!</B> As of v2.0.0 of &Digraphs; these functions are
      deprecated in favour of:
      <List>
          <Item><Ref Oper="GraphvizPreorderDigraph"/></Item>
          <Item><Ref Oper="GraphvizQuasiorderDigraph"/></Item>
      </List>
      These functions return mutable &GAP; objects representing graphviz
      objects, which provide a more flexible means of tailoring pictures of
      graphs and digraphs to your needs. The <C>Dot</C> variants of these
      functions are synonymous with, for example,
      <C>AsString(GraphvizDigraph(<A>D</A>))</C>. It is also possible to use
      <Ref Func="Splash" BookName="graphviz"/> directly on the graphviz objects
      returned by the <C>Graphviz</C> variants of these functions, i.e.
      <C>Splash(GraphvizDigraph(<A>D</A>))</C> does precisely the same thing as
      <C>Splash(DotDigraph(<A>D</A>))</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GraphvizPreorderDigraph">
  <ManSection>
    <Attr Name="GraphvizPreorderDigraph" Arg="D"/>
    <Attr Name="GraphvizQuasiorderDigraph" Arg="D"/>
    <Returns>A &graphviz; object.</Returns>
    <Description>
      These functions produce &graphviz; objects representing a preorder
      digraph <A>D</A>. These function will give an error
      if <A>D</A> is not a preorder digraph. See <Ref
        Prop="IsPreorderDigraph"/>.<P/>

      A preorder digraph is reflexive and transitive but in general it is
      not anti-symmetric and may have strongly connected components
      containing more than one vertex. The <Ref Oper="QuotientDigraph"/>
      <A>Q</A> obtained by forming the quotient of <A>D</A> by the
      partition of its vertices into the strongly connected components
      satisfies <Ref Prop="IsPartialOrderDigraph"/>. Thus every vertex of
      <A>Q</A> corresponds to a strongly connected component of <A>D</A>.
      The output of <C>GraphvizPreorderDigraph</C> displays the
      <Ref Oper="DigraphReflexiveTransitiveReduction"/> of <A>Q</A> with
      vertices displayed as rounded rectangles labelled by all of the vertices
      of <A>D</A> in the corresponding strongly connected component.
      <P/>

      See the &graphviz; package documentation for more details.
      <P/>

      See also <Ref Func="Splash" BookName="graphviz"/>

      <Example><![CDATA[
gap> D := Digraph([[1, 2, 4, 5], [1, 2, 4, 5], [3, 4], [4],
> [1, 2, 4, 5]]);
<immutable digraph with 5 vertices, 15 edges>
gap> IsPreorderDigraph(D);
true
gap> GraphvizPreorderDigraph(D);
<graphviz digraph graphname with 3 nodes and 2 edges>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotHighlightedDigraph">
  <ManSection>
      <Oper Name="DotHighlightedDigraph"
          Arg="digraph, verts [, color1, color2]"/>
    <Returns>A string.</Returns>
    <Description>
      <B>WARNING!</B> As of v2.0.0 of &Digraphs; these functions are
      deprecated in favour of:
      <List>
          <Item><Ref Oper="GraphvizHighlightedDigraph"/></Item>
          <Item><Ref Oper="GraphvizHighlightedGraph"/></Item>
      </List>
      These functions return mutable &GAP; objects representing graphviz
      objects, which provide a more flexible means of tailoring pictures of
      graphs and digraphs to your needs. The <C>Dot</C> variants of these
      functions are synonymous with, for example,
      <C>AsString(GraphvizDigraph(<A>D</A>))</C>. It is also possible to use
      <Ref Func="Splash" BookName="graphviz"/> directly on the graphviz objects
      returned by the <C>Graphviz</C> variants of these functions, i.e.
      <C>Splash(GraphvizDigraph(<A>D</A>))</C> does precisely the same thing as
      <C>Splash(DotDigraph(<A>D</A>))</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="GraphvizHighlightedDigraph">
  <ManSection>
      <Oper Name="GraphvizHighlightedDigraph"
          Arg="D, verts [, color1, color2]"/>
      <Oper Name="GraphvizHighlightedGraph"
          Arg="D, verts [, color1, color2]"/>
    <Returns>A &graphviz; object.</Returns>
    <Description>
      These functions produce &graphviz; objects representing the digraph
      <A>D</A>, where the vertices in the list <A>verts</A>, and edges
      between them, are drawn with color <A>color1</A> and all other vertices
      and edges in <A>D</A> are drawn with color <A>color2</A>. If
      <A>color1</A> and <A>color2</A> are not given, then these functions
      use <C>\"black\"</C> and <C>\"grey\"</C> respectively.
      <P/>

      See <Ref Attr="GraphvizDigraph"/> and <Ref Attr="GraphvizGraph"/>
      for more details on the output.

      <Example><![CDATA[
gap> D := Digraph([[2, 3], [2], [1, 3]]);
<immutable digraph with 3 vertices, 5 edges>
gap> GraphvizHighlightedDigraph(D, [1, 2], "red", "black");
<graphviz digraph with 3 nodes and 5 edges>
gap> D := DigraphSymmetricClosure(D);
<immutable symmetric digraph with 3 vertices, 6 edges>
gap> GraphvizHighlightedGraph(D, [1, 2], "red", "black");
<graphviz graph with 3 nodes and 2 edges>]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>