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

<#GAPDoc Label="Splash">
  <ManSection>
    <Func Name="Splash" Arg="str, [opts]"/>
    <Returns>Nothing.</Returns>
    <Description>
      This function attempts to convert the string <A>str</A> into a pdf
      document and open this document, i.e. to splash it all over your monitor.<P/>

      The string <A>str</A> must correspond to a valid <C>dot</C> or
      <C>LaTeX</C> text file and you must have have <C>GraphViz</C> and
      <C>pdflatex</C> installed on your computer.  For details about these file
      formats, see <URL>http://www.latex-project.org</URL> and
      <URL>http://www.graphviz.org</URL>.<P/>

      This function is provided to allow convenient, immediate viewing of the
      pictures produced by the function <Ref Attr="DotDigraph"/>.<P/>

      The optional second argument <A>opts</A> should be a record with
      components corresponding to various options, given below.

      <List>
        <Mark>path</Mark>
        <Item>
          this should be a string representing the path to the directory where
          you want <C>Splash</C> to do its work. The default value of this
          option is <C>"~/"</C>.
        </Item>

        <Mark>directory</Mark>
        <Item>
          this should be a string representing the name of the directory in
          <C>path</C> where you want <C>Splash</C> to do its work. This function
          will create this directory if does not already exist. <P/>

          The default value of this option is <C>"tmp.viz"</C> if the option
          <C>path</C> is present, and the result of
          <Ref Func="DirectoryTemporary" BookName="ref"/> is used otherwise.
        </Item>

        <Mark>filename</Mark>
        <Item>
          this should be a string representing the name of the file where
          <A>str</A> will be written.  The default value of this option is
          <C>"vizpicture"</C>.
        </Item>

        <Mark>viewer</Mark>
        <Item>
          this should be a string representing the name of the program which
          should open the files produced by <C>GraphViz</C> or <C>pdflatex</C>.
        </Item>

        <Mark>type</Mark>
        <Item>
          this option can be used to specify that the string <A>str</A> contains
          a &LaTeX; or <C>dot</C> document. You can specify this option in
          <A>str</A> directly by making the first line <C>"%latex"</C> or
          <C>"//dot"</C>.  There is no default value for this option, this
          option must be specified in <A>str</A> or in <A>opt.type</A>.
        </Item>

        <Mark>engine</Mark>
        <Item>
          this option can be used to specify the GraphViz engine to use
          to render a <C>dot</C> document. The valid choices are <C>"dot"</C>,
          <C>"neato"</C>, <C>"circo"</C>, <C>"twopi"</C>, <C>"fdp"</C>,
          <C>"sfdp"</C>, and <C>"patchwork"</C>. Please refer to the
          GraphViz documentation for details on these engines.
          The default value for this option is <C>"dot"</C>, and it
          must be specified in <A>opt.engine</A>.
        </Item>

        <Mark>filetype</Mark>
        <Item>
          this should be a string representing the type of file which
          <C>Splash</C> should produce. For &LaTeX; files, this option is
          ignored and the default value <C>"pdf"</C> is used.
        </Item>
      </List>

      This function was written by Attila Egri-Nagy and Manuel Delgado with some
      minor changes by J. D. Mitchell.<P/>

      <Log><![CDATA[
gap> Splash(DotDigraph(RandomDigraph(4)));
]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotDigraph">
  <ManSection>
    <Attr Name="DotDigraph" Arg="digraph"/>
    <Oper Name="DotVertexLabelledDigraph" Arg="digraph"/>
    <Returns>A string.</Returns>
    <Description>
      <C>DotDigraph</C> produces a graphical representation of the digraph
      <A>digraph</A>. Vertices are displayed as circles, numbered consistently
      with <A>digraph</A>. Edges are displayed as arrowed lines between
      vertices, with the arrowhead of each line pointing towards the range
      of the edge.<P/>

      <C>DotVertexLabelledDigraph</C> differs from <C>DotDigraph</C> 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/>

      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>http://www.graphviz.org</URL>. <P/>

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

      <Log><![CDATA[
gap> adj := List([1 .. 4], x -> [1, 1, 1, 1]);
[ [ 1, 1, 1, 1 ], [ 1, 1, 1, 1 ], [ 1, 1, 1, 1 ], [ 1, 1, 1, 1 ] ]
gap> adj[1][3] := 0;
0
gap> gr := DigraphByAdjacencyMatrix(adj);
<digraph with 4 vertices, 15 edges>
gap> FileString("dot/k4.dot", DotDigraph(gr));
154]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotSymmetricDigraph">
  <ManSection>
    <Attr Name="DotSymmetricDigraph" Arg="digraph"/>
    <Returns>A string.</Returns>
    <Description>
      This function produces a graphical representation of the symmetric
      digraph <A>digraph</A>. <C>DotSymmetricDigraph</C> will return an
      error if <A>digraph</A> is not a symmetric digraph. See
      <Ref Prop="IsSymmetricDigraph"/>.<P/>

      Vertices are displayed as circles, numbered consistently with
      <A>digraph</A>. Since <A>digraph</A> is symmetric, for every non-loop
      edge there is a complementary edge with opposite source and range.
      <C>DotSymmetricDigraph</C> displays each pair of complementary edges
      as a single line between the relevant vertices, with no arrowhead.<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>http://www.graphviz.org</URL>. <P/>

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

      <Log><![CDATA[
gap> star := Digraph([[2, 2, 3, 4], [1, 1], [1], [1, 4]]);
<multidigraph with 4 vertices, 9 edges>
gap> IsSymmetricDigraph(star);
true
gap> FileString("dot/star.dot", DotSymmetricDigraph(gr));
83]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotPartialOrderDigraph">
  <ManSection>
    <Attr Name="DotPartialOrderDigraph" Arg="digraph"/>
    <Returns>A string.</Returns>
    <Description>
      This function produces a graphical representation of a partial order
      digraph <A>digraph</A>. <C>DotPartialOrderDigraph</C> will return an error
      if <A>digraph</A> is not a partial order digraph. See <Ref
        Prop="IsPartialOrderDigraph"/>.<P/>

      Since <A>digraph</A> is a partial order, it is both reflexive and
      transitive. The output of <C>DotPartialOrderDigraph</C> is the
      <Ref Attr="DotDigraph"/> of the
      <Ref Oper="DigraphReflexiveTransitiveReduction"/> of <A>digraph</A>.<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>http://www.graphviz.org</URL>. <P/>

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

      <Log><![CDATA[
gap> poset := Digraph([[1, 4], [2], [2, 3, 4], [4]);
gap> IsPartialOrderDigraph(gr);
true
gap> FileString("dot/poset.dot", DotPartialOrderDigraph(gr));
83]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotPreorderDigraph">
  <ManSection>
    <Attr Name="DotPreorderDigraph" Arg="digraph"/>
    <Attr Name="DotQuasiorderDigraph" Arg="digraph"/>
    <Returns>A string.</Returns>
    <Description>
      This function produces a graphical representation of a preorder
      digraph <A>digraph</A>. <C>DotPreorderDigraph</C> will return an error
      if <A>digraph</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>digraph</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>digraph</A>.
      The output of <C>DotPreorderDigraph</C> displays the 
      <Ref Oper="DigraphReflexiveTransitiveReduction"/> of <A>Q</A> with
      vertices displayed as rounded rectangles labelled by all of the vertices
      of <A>digraph</A> in the corresponding strongly connected component. <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>http://www.graphviz.org</URL>. <P/>

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

      <Log><![CDATA[
gap> preset := Digraph([[1, 2, 4, 5], [1, 2, 4, 5], [3, 4], [4], [1, 2, 4, 5]);
gap> IsPreorderDigraph(gr);
true
gap> FileString("dot/preset.dot", DotProrderDigraph(gr));
83]]></Log>
    </Description>
  </ManSection>
<#/GAPDoc>
