clav-sdl.1

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