README

   1 congif
   2 ======
   3
   4 This is  an experimental tool  that generates GIF animations  of console
   5 sessions.  Like  scriptreplay(1),  it  reads the  output  of  script(1),
   6 including timing information. Unlike  scriptreplay(1), congif parses the
   7 session dialogue and encodes it as a GIF animation that can be viewed on
   8 graphical programs (e.g. web browsers).
   9
  10
  11 Limitations
  12 -----------
  13
  14 Only dialogues generated  for the Linux console can  be correctly parsed
  15 by congif.  This means that  if your  $TERM environment variable  is not
  16 "linux" then  it probably won't  work. You  can manually set  $TERM when
  17 calling script(1), but  then your terminal may not  work correctly while
  18 the session is recorded. It's  recommended that you record your sessions
  19 on  the  Linux  console  itself,  or on  a  terminal  emulator  that  is
  20 compatible with console_codes(4).
  21
  22 congif needs  to know  the terminal  size used  during the  execution of
  23 script(1) and this size must be constant per session (i.e. if you resize
  24 the terminal while recording a  session, congif won't work). By default,
  25 congif assumes  that the terminal  size of the  session is equal  to the
  26 current terminal size. Use the options -w  and -h if you need to specify
  27 a different size.
  28
  29
  30 Building
  31 --------
  32
  33 A C99 compiler is needed. There are no library dependencies.
  34
  35 $ make
  36
  37
  38 Usage
  39 -----
  40
  41 congif [options] timings dialogue
  42
  43     timings:       File generated by script(1)'s -t option
  44     dialogue:      File generated by script(1)'s regular output
  45
  46     options:
  47       -o output    File name of GIF output
  48       -m maxdelay  Maximum delay, as in scriptreplay(1)
  49       -d divisor   Speedup, as in scriptreplay(1)
  50       -l count     GIF loop count (0 = infinite loop)
  51       -f font      File name of MBF font to use
  52       -h lines     Terminal height
  53       -w columns   Terminal width
  54       -c on|off    Show/hide cursor
  55       -q           Quiet mode (don't show progress bar)
  56       -v           Verbose mode (show parser logs)
  57
  58
  59 Fonts
  60 -----
  61
  62 For  simplicity, congif  uses a  custom font  format, MBF.  The font
  63 misc-fixed [1], included in this distribution, is used by default.
  64
  65 For  more  information on  the  MBF  format,  see the  mbf-util  [2]
  66 project. It  includes a  bdf2mbf tool that  converts fonts  from the
  67 popular BDF format to the MBF format.
  68
  69
  70 Examples
  71 --------
  72
  73 Recording a session:
  74 $ script -t 2> foo.t foo.d
  75
  76 Generating a GIF file with defaults (creates "con.gif"):
  77 $ congif foo.t foo.d
  78
  79 Generating a faster version:
  80 $ congif -d3 -m1 -o fast.gif foo.t foo.d
  81
  82
  83 Copying
  84 -------
  85
  86 All of the source code and documentation for congif is released into the
  87 public domain and provided without warranty of any kind.
  88
  89
  90 Links
  91 -----
  92
  93 [1] http://www.cl.cam.ac.uk/~mgk25/ucs-fonts.html
  94 [2] https://github.com/lecram/mbf-util