doc/mp_cookbook.txt

   1 Minimum Profit cookbook
   2 =======================
   3
   4 This document includes some recipes for the Minimum Profit text editor.
   5
   6 Executing MPSL code
   7 -------------------
   8
   9 There are three ways of executing MPSL inside the editor.
  10
  11 From the command line
  12 ~~~~~~~~~~~~~~~~~~~~~
  13
  14 The first one is from the command line using the -e switch:
  15
  16  mp-5 -e 'mp.config.word_wrap = 75;'
  17
  18 This command opens the editor and immediately executes an assignation to
  19 the mp.config.word_wrap variable, giving it a value of 75 (this operation
  20 have activated word wrapping on column 75). Take note that the leading
  21 semicolon is mandatory. Several sentences can be given:
  22
  23  mp-5 -e 'mp.config.word_wrap = 75; mp.ispell(1); mp.alert("Hello!");'
  24
  25 Word wrapping is set, ispell is activated (if supported) and a greeting
  26 message is given. As seen, any valid MPSL program can be given here.
  27
  28 Using the 'eval' action
  29 ~~~~~~~~~~~~~~~~~~~~~~~
  30
  31 The 'eval' action is on the menu as the "Edit/Execute MPSL code..." entry.
  32 This action asks for a string of MPSL code to be executed. The return
  33 value will be returned as an alert message.
  34
  35 Using the 'eval_doc' action
  36 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  37
  38 The 'eval_doc' in on the menu as the "Edit/Execute document as MPSL". This
  39 action will take the contents of the currently active document and pass it
  40 directly to the MPSL engine.
  41
  42 Using different encodings
  43 -------------------------
  44
  45 By default, MP reads and writes files using the current locale for
  46 character set conversions. This way, if you run it in an UTF-8
  47 environment, you don't have to do anything special, just open and save
  48 your files. But, if you need to read or write files using different
  49 encodings (for example, if your locale encoding is ISO-8859-1 and you need
  50 to read UTF-8 files), you can use the encoding() function. This function
  51 receives an encoding string as argument; after calling it, all I/O
  52 operations will use that encoding. To get back to 'normal' (i.e., default
  53 local encoding), just call it without arguments, or with a NULL one.
  54
  55 This snippet will convert a file named 'text' to UTF-8:
  56
  57  local d = mp.open('text'); encoding('utf-8'); mp.save(d); mp.close();
  58
  59 Spellchecking
  60 -------------
  61
  62 Spellchecking is done under Unix-like systems by piping the words of the
  63 current document to the external command *ispell*, so it must be installed,
  64 correctly configured and with properly installed dictionary files to be
  65 useful. To activate spell checking, the mp.ispell() function must be called
  66 with a boolean argument telling if spellchecking is wanted or not.
  67
  68 By default, the command to be executed is "ispell -a". If you have it in a
  69 non-standard path, or want to use a different program as *aspell*, you can
  70 change it by changing the configuration variable mp.config.ispell_cmd.
  71
  72 Note: if you happen to use an UTF-8 locale, the ispell program doesn't
  73 work correctly. Either use aspell, or change the command configuration
  74 variable to "ispell -a -Tutf8".
  75
  76 Disabling syntax highlighting for slow machines
  77 -----------------------------------------------
  78
  79 Syntax highlighting in Minimum Profit 5.x can be a CPU hog on embedded or
  80 small systems. An easy way to disable it is to set mp.syntax to an empty
  81 hash:
  82
  83         /* disable all syntax highlighting */
  84         mp.syntax = {};
  85
  86 Creating a print dialog
  87 -----------------------
  88
  89 Minimum Profit 5.x lacks a print command, but it's easy to create one by
  90 using its powerful scripting language (MPSL) and some external commands
  91 used as pipes. The following example will create a dialog that will ask for
  92 some printing options and print the current document, optionally with
  93 preview. The external programs `paps', `psnup', `psselect' and `gv' must be
  94 installed and accesible with the current path.
  95
  96 Copy this subroutine in an empty document and execute the menu option
  97 "Edit / Execute document as MPSL". Hopefully, the script will compile
  98 without errors and the new function my_print() will be created inside MP's
  99 machine:
 100
 101  sub my_print(doc) {
 102
 103         local r = mp.form( [
 104                 {
 105                         'label'         => 'Page range (empty: all):',
 106                         'type'          => 'text'
 107                 },
 108                 {
 109                         'label'         => 'Pages per page:',
 110                         'type'          => 'text',
 111                         'value'         => 1
 112                 },
 113                 {
 114                         'label'         => 'Preview?',
 115                         'type'          => 'checkbox'
 116                 }
 117         ]);
 118
 119         if (r != NULL) {
 120                 local cmd = []; /* empty array */
 121                 local f;
 122
 123                 /* first program is the text to PostScript converter */
 124                 push(cmd, 'paps');
 125
 126                 /* select range using psselect, if available */
 127                 if (r[0] != '')
 128                         push(cmd, 'psselect -p' ~ r[0]);
 129
 130                 /* select pages-in-page using psnup */
 131                 if (r[1] > 1)
 132                         push(cmd, 'psnup -' ~ r[1]);
 133
 134                 /* preview using gv? */
 135                 if (r[2])
 136                         push(cmd, 'gv -');
 137                 else
 138                         push(cmd, 'lpr');
 139
 140                 local c = join('|', cmd);
 141
 142                 /* now pipe */
 143                 if ((f = popen(c, "w")) != NULL) {
 144                         foreach (local l, doc.txt.lines)
 145                                 write(f, l ~ "\n");
 146
 147                         if (pclose(f) != 0)
 148                                 f = NULL;
 149                 }
 150
 151                 if (f == NULL)
 152                         mp.alert("Error '" ~ ERRNO ~ "' piping to '" ~ c ~ "'");
 153         }
 154  }
 155
 156 The code should be self-explaining (I hope): a call to mp.form()
 157 creates a dialog box asking for the following printing options: a page
 158 range suitable for the `psselect' utility, a number of n-up pages for
 159 `psnup' (it's cool to avoid wasting paper by printing two pages into one)
 160 and a preview checkbox. If the dialog box is validated, the return values
 161 are used to construct an array of commands to pipe to. They are finally
 162 joined into one string using the '|' separator to build a command that
 163 will be used as a writable pipe.
 164
 165 To test the new code, hit the Escape key (twice if using the Curses
 166 interface) and type the following:
 167
 168         my_print(mp.active());
 169
 170 This is fine, but it would be much better if this new operation would be
 171 accesible from a hotkey or a menu option.
 172
 173 In any of those two cases, an editor 'action' must be created. Actions are
 174 special functions that live in the `mp.actions' name space, and accept a
 175 document as the only argument. Optionally, actions have a description,
 176 a human-readable string:
 177
 178         mp.actions.my_print = sub(d) { my_print(d); };
 179         mp.actdesc.my_print = "Print...";
 180
 181 This is just one way of creating it, by using an anonymous subroutine;
 182 another way would be:
 183
 184         sub mp.actions.my_print(d) { my_print(d); }
 185
 186 or even
 187
 188         mp.actions.my_print = my_print;
 189
 190 Because the my_print() and the action itself use the same number of
 191 arguments.
 192
 193 If you want to bind this action to ctrl-p, it's also easy:
 194
 195         mp.keycodes['ctrl-p'] = 'my_print';
 196
 197 Execute that and, from now on, every hit to `ctrl-p' will invoke my_print()
 198 on the current document.
 199
 200 To add it to the menu, the mp.menu array must be patched. This is less
 201 straightforward because the menu structure is a bit more complicated: it's
 202 an array of two-element arrays, where the zeroth element is the menu bar
 203 ("File", "Edit", and so on) and the first one is itself another array, this
 204 time of action names.
 205
 206 We want for our print option to live in the first menu bar ("File"), just
 207 above the last option, which is "Exit". The ins() MPSL library function
 208 inserts an element in a given position of an array, with negative
 209 subscripts starting from the end, so the following code will do:
 210
 211         ins(mp.menu[0][1], '-', -2);
 212         ins(mp.menu[0][1], 'my_print', -2);
 213
 214 The '-' special option creates a menu separator.
 215
 216 The menu is not automatically rebuilt, so a call to the mp.update_ui()
 217 function is also needed:
 218
 219         mp.update_ui();
 220
 221 Take note that on current version the GTK version doesn't rebuild its
 222 menu when calling mp.update_ui() (it's bug #1150).
 223
 224 This examples show the easy expandability of the new MP 5.x version.
 225
 226 I'm sure all this is fascinating, but everything will be lost on exit; the
 227 way to make this changes permanent is to add all that code to the personal
 228 configuration file, which is nothing more than an MPSL source code file
 229 that is compiled and parsed on startup. It's called .mp.mpsl, on Unix/Linux
 230 systems live in $HOME and on Win32 in the "My Documents" folder. The "File
 231 / Edit configuration file" menu option gives easy access to it.
 232
 233 ----
 234 Angel Ortega <angel@triptico.com>