clav-sdl.1

   1 .Dd 2019-03-27
   2 .Dt CLAV-SDL 1
   3 .Os
   4 .Sh NAME
   5 .Nm clav-sdl
   6 .Nd Visualize quivers with SDL
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Oo
  10 .Fl v
  11 .Oc
  12 .Oo
  13 .Fl f
  14 .Ar filename
  15 .Oc
  16 .Sh DESCRIPTION
  17 .Nm
  18 is a graphical program to interact with quivers.  It is similar to
  19 Keller's Java applet, which is published at
  20 https://webusers.imj-prg.fr/~bernhard.keller/quivermutation/ , though
  21 .Nm
  22 handles extensions such as half-weight edges and fat vertices.
  23 .Sh OPTIONS
  24 .Bl -tag -width Ds
  25 .It Fl v
  26 Be verbose: print a message to stdout whenever a quiver is altered.
  27 This is the closest you'll get to an undo/redo feature.
  28 .It Fl f
  29 Start by opening file
  30 .Ar filename ,
  31 which is of the format written by
  32 .Nm
  33 and
  34 .Nm clav-cli .
  35 If this option is not provided, a rather uninteresting default quiver is loaded.
  36 .El
  37 .Sh INFORMATION
  38 While
  39 .Nm
  40 is running, it constantly displays the current quiver. Hovering
  41 over a vertex or an edge will display relevant information in the
  42 top right corner.
  43 .Pp
  44 For convenience, edges are classified by color into three types, depending
  45 on the specific edge weights they represent.
  46 .Pp
  47 .Bl -tag -width Ds
  48 .It black
  49 A black edge from vertex
  50 .Ar i
  51 to
  52 .Ar j
  53 has weights
  54 .Dl ε_{ij} = ± d_{j} / GCD(d_{i}, d_{j})
  55 .Dl ε_{ji} = ∓ d_{i} / GCD(d_{i}, d_{j})
  56 where the signs are determined by the arrow's direction.
  57 .It gray
  58 A gray edge has half the edge weights that it would have if it were black.
  59 .It red
  60 A red edge has any other weights.  In general, red edges are rare during
  61 .Sq interesting
  62 mutation sequences.
  63 .El
  64 .Sh CONTROL
  65 The following controls are available. To cancel an action when input is
  66 prompted for, press
  67 .Sq ESC .
  68 .Bl -tag -width Ds
  69 .It Click+Drag
  70 Clicking and dragging a vertex will reposition it onscreen. Clicking
  71 and dragging empty space will reposition the entire quiver.
  72 .It m
  73 To mutate
  74 .Po See
  75 .Xr clav 1
  76 for references
  77 .Pc at a vertex, press
  78 .Sq m ,
  79 then click on the vertex.
  80 .It v
  81 To create a new vertex, press
  82 .Sq v ,
  83 then click where it should be placed. You will probably want to rename
  84 it with
  85 .Sq r .
  86 .It d
  87 To delete an edge or a vertex, press
  88 .Sq d ,
  89 then click the edge or vertex which should be deleted.
  90 .It e
  91 To add an edge
  92 .Pq create a black edge if no edge is present, or add to an edge if one is present
  93 between two vertices, press
  94 .Sq e ,
  95 then click the start and end vertices.
  96 .It h
  97 As
  98 .Sq e ,
  99 but with half weight.
 100 .It f
 101 To increase the fatness of a vertex, press
 102 .Sq f ,
 103 then click the vertex.  This may change how edges of that vertex are
 104 calculated. The maximum fatness is system-dependent but
 105 .Sq interesting
 106 things tend to happen with low fatness.
 107 .It g
 108 As
 109 .Sq f ,
 110 but the vertex's fatness is decreased.  The minimum fatness is 1.
 111 .It r
 112 To rename a vertex, press
 113 .Sq r ,
 114 then click the vertex to be renamed. The new name will be prompted
 115 for. If the system has a unicode-compatible IME, entering unicode
 116 characters should work without issue.
 117 .It c
 118 To change the color of a vertex, press
 119 .Sq c ,
 120 then click the vertex. The color will then be prompted for. The
 121 following graphical color choosers are known and probed for
 122 .Pq in this order :
 123 .Bl -bullet -compact
 124 .It
 125 KDialog
 126 .It
 127 Qarma
 128 .It
 129 Yad
 130 .It
 131 Zenity
 132 .It
 133 Xdialog
 134 .El
 135 If none is found, the user may enter a color, in the form
 136 .Ar rrggbb
 137 where each of
 138 .Ar r ,
 139 .Ar b ,
 140 .Ar g
 141 are hexadecimal digits.
 142 .It Shift+m/v/d/e/h/f/g/r
 143 Holding shift while pressing one of the above buttons causes the
 144 action to loop until explicitly terminated. For example, pressing
 145 .Sq M ,
 146 then clicking a sequence of 9 vertices will mutate at that sequence
 147 more conveniently than pressing
 148 .Sq m
 149 9 times.
 150 .It s
 151 To save the current quiver, press
 152 .Sq s .
 153 Depending on which packages are installed on the system, the filename
 154 will be prompted for in one of a few ways. The following graphical file
 155 choosers are known and probed for
 156 .Pq in this order :
 157 .Bl -bullet -compact
 158 .It
 159 KDialog
 160 .It
 161 Qarma
 162 .It
 163 Yad
 164 .It
 165 Zenity
 166 .It
 167 Xdialog
 168 .El
 169 If none is found, the filename will be prompted for onscreen. This prompt
 170 is rather primitive, however.
 171 .It l
 172 To load a quiver
 173 .Pq and to discard the current quiver ,
 174 press
 175 .Sq l .
 176 A file will be prompted for in the same manner as the save dialog.
 177 .El
 178 .Sh EXAMPLES
 179 Example quivers may have been installed along with this program,
 180 typically in
 181 .Pa /usr/share/clav/ .
 182 .Sh SEE ALSO
 183 .Xr clav 1
 184 .Xr clav-cli 1
 185 .Sh BUGS
 186 Edge weights are, for performance reasons
 187 .Po see
 188 .Xr clav-mutation-find 1
 189 .Pc , stored as fractions with
 190 numerator and denominator in system-dependent ranges.  While it probably
 191 will not be an issue for
 192 .Sq interesting
 193 usage, causing edge weights to increase arbitrarily will eventually cause
 194 .Nm
 195 to compute an unrepresentable edge weight
 196 .Pq for example, 1/257 might be unrepresentable .
 197 In this situation,
 198 .Nm
 199 will not perform the mutation, rather than display incorrect
 200 results.
 201 .Sh AUTHORS
 202 .An S. Gilles Aq Mt sgilles@math.umd.edu