doc/info/README.update_examples

   1
   2 Perl script `update_examples' is intended to update
   3 examples in the Maxima texinfo documentation.
   4
   5 `update_examples' is a filter - it reads standard input
   6 and direst result to standard output:
   7
   8 ./update_examples < original.texi > updated.texi
   9
  10 The script scans input texinfo file for
  11 constructions of the form:
  12
  13 @c ===beg===
  14 @c expand((x+y)^2);
  15 @c factor(%);
  16 @c ===end===
  17 @example
  18 (%i1) expand((x+y)^2);
  19                           2            2
  20 (%o1)                    y  + 2 x y + x
  21 (%i2) factor(%);
  22                                    2
  23 (%o2)                       (y + x)
  24
  25 @end example
  26
  27 Lines between `@c ===beg===' and `@c ===end==='
  28 are Maxima commands (without leftmost `@c ').
  29 The script extracts this commands, passes them to
  30 Maxima and inserts resulting output between
  31 `@example' and `@end example'.
  32
  33 Maxima commands between `@c ===beg===' and `@c ===end==='
  34 must obey some simple rules:
  35
  36
  37 1. Each command must begin at 4th column right
  38    after `@c ' without extra spaces between `@c '
  39    and the command:
  40
  41 @c expand((x+y)^2);     - is right
  42
  43 @c  expand((x+y)^2);    - is wrong
  44
  45
  46 2. If command spans several lines then second and
  47    all subsequent lines must have alt least one
  48    extra space between `@c ' and the command.
  49
  50 Wrong:
  51
  52 @c (x +
  53 @c y +
  54 @c z)^3;
  55
  56 Right:
  57
  58 @c (x +
  59 @c  y +
  60 @c  z)^3;
  61
  62
  63 Examples without preceding `@c ===beg==='/`@c ===end==='
  64 remain unchanged.
  65
  66 By default `update_examples' calls local Maxima
  67 script `../../maxima-local' but this can be changed
  68 by setting MAXIMA_EXAMPLE_COMMAND environment
  69 variable.
  70
  71 The environment variable STRIP_TOPDIR controls
  72 which path is stripped out of the output (load,
  73 batch commands).  If the variable isn't set then
  74 anything above /maxima/doc/info is stripped.
  75
  76 IMPORTANT: `update_examples' script works only
  77 in combination with special Maxima initialization
  78 file `maxima-init.lisp'.  This init file ensures
  79 that output is no more than 65 characters wide
  80 by setting `linel:65;' and helps to identify
  81 Maxima prompts.
  82
  83
  84 Vadim V. Zhytnikov  <vvzhy@mail.ru>
  85
  86 Jan 12, 2005
  87