1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Cream :: a modern configuration of the Vim text editor</title>
<link href="favicon.ico" rel="Shortcut Icon">
<link href="style.css" rel="stylesheet" type="text/css">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<script src="mouseovers.js" type="text/javascript"></script>
</head>
<body>
<div align="center">
<div class="main">
<!-- header {{{1 -->
<div class="header">
<!-- Page Title -->
<div class="title">
<a class="logo" href="index.html"><b>Cream</b></a>
<span class="tagline">
<small>: :</small> <i>a modern configuration of the </i>Vim<i> text editor</i>
</span>
</div>
<!-- Search {{{ -->
<form class="searchform" method="GET" action="http://www.google.com/search">
<input type="hidden" name="sitesearch" value="cream.sourceforge.net">
<input type="submit" name="btnG" value="Find" class="searchbtn">
<input type="text" name="q" maxlength="255" value="" class="searchbox">
</form>
<!-- }}} -->
</div>
<!-- body {{{1 -->
<div
class="feat"
style="width:680px;"
>
<p class="sectitleright"><a class="sec" href="features.html"><b>features</b></a></p>
<h2>Frequently Asked Questions (FAQ)</h2>
<ul>
<li><a href="#0001">Where does the name "Cream" come from?</a></li>
</ul>
<h5>Using Cream</h5>
<ul>
<li><a href="#0101">How can I make tab keystrokes insert 4 spaces rather than the default tab character displayed as 8 spaces?</a></li>
<li><a href="#0102">Column Select doesn't seem to work for me.</a></li>
<li><a href="#0103">How can I start command mode for the occasional traditional Vim :command?</a></li>
<li><a href="#0105">How can I install Cream without having root access?</a></li>
<li><a href="#0106">How can I start Cream from gVim?</a></li>
<li><a href="#0107">How can I re-enable Vim 7's bracket highlighting?</a></li>
<li><a href="#0108">How do I manually create the Windows right-click "Edit with Cream/Vim" menu?</a></li>
<li><a href="#0109">How do I make Cream the default Windows application for text files?</a></li>
<li><a href="#0110">How do I make Cream the default Windows application for un-affiliated files?</a></li>
</ul>
<h5>Advanced Users</h5>
<ul>
<li><a href="#0201">How can I use my personal customizations with Cream?</a></li>
<li><a href="#0202">How can I use customizations to Cream system wide?</a></li>
<li><a href="#0202b">How are system-wide customizations loaded? Do user preferences override these global settings?</a></li>
<li><a href="#0203">I love everything except [feature x]. Is there any way I can turn it off?</a></li>
<li><a href="#0204">Do you ever plan on making Cream work (better) in terminal/console versions?</a></li>
<li><a href="#0205">Sometimes I want to just use just a subset of Cream, for example, can I turn off Cream's keystrokes?</i></a></li>
<li><a href="#0206">How do Vim and Vi behavior settings differ from Expert Mode?</a></li>
<li><a href="#0207">Is there a way I can use the Cream installed on my Windows partition with my GNU/Linux Vim?</a></li>
<li><a href="#0208">Tell me more about multiple users with a single installation, i.e., the optional $VIMINIT, $CREAM, $CREAM_BAK, $CREAM_SWP, and $CREAM_VIEW environmental variables.</a></li>
<li><a href="#0209">How can I prevent Cream from loading my Vim plugins?</a></li>
<li><a href="#0211">On startup I get: "Unable to use Cream bookmarking features, no compiled support for signs"</a></li>
<li><a href="#0212">How can I get the Unix/X11 behavior where the middle-mouse button pastes a selection?</a></li>
<li><a href="#0213">Is it possible to overwrite Cream settings per filetype?</a></li>
<li><a href="#0214">How do I use cream as my editor from Mutt?</a></li>
<li><a href="#0215">Why is Cream sluggish when editing on a distant network?</a></li>
<li><a href="#0216">How can I make the Esc key in Expert Mode always stay in normal mode (not toggle between Insert and Normal mode)?</a></li>
<li><a href="#0217">How can I make Expert Mode Cream start in normal mode?</a></li>
<li><a href="#0218">How can I use the Windows installer silently?</a></li>
<li><a href="#0219">How do I use custom color themes with Cream?</a></li>
</ul>
<h5>Developers</h5>
<ul>
<li><a href="#0301">Wouldn't it be cool if Cream had (my) mappings and functions for [ HTML | Perl | PHP | Python | Tex | C | C++ | Java ] built in?</a></li>
<li><a href="#0302">What's the deal with Add-ons?</a></li>
<li><a href="#0303">What are some guidelines to consider if I want to submit a patch to Cream?</a></li>
<li><a href="#0304">Are there any hidden functions or routines that you've made available in the project that might be useful if I wish to help contribute to Cream?</a></li>
<li><a href="#0305">How can I use CVS to get Cream?</a></li>
<li><a href="#0306">How can I write a mapping/menu item to do multiple or more complex things?</a></li>
</ul>
<p> </p>
<h2>Answers</h2>
<br>
<h5><a name="0001">Where does the name "Cream" come from?</a></h5>
<p>The name was inspired by the convergence of several ideas:</p>
<ul>
<li>The initial thought came from my coffee drinking habits as I usually don't prefer my coffee "black." It reminded me of my opinion of Vim at the time--despite its inherent sophistication--I needed something to soften it.</li>
<li>Cream also contains fat, and while effective in flavoring the drink, it also adds overhead to the digestive process. Likewise, our script configuration to Vim performance. Interestingly, in both cases, the effect is worth it by some measure of opinions, but generally less to those most sophisticated.</li>
<li>I was also firmly committed to keeping Cream as a configuration of Vim, never a fork or customization of that codebase. Vim has tremendous support and is (in association with it's ancestor Vi) nearly ubiquitous with text editing over the last 25 years. By selecting a name that referenced a host, I hoped to imply an effort of good faith in that regard.</li>
<li>"Vim" shares it's name with a European cleaning product. Since it is available in cream form, I thought it was humorous to be able to share in the same puns.</li>
<li>One of the definitions of "Cream" is "the best people or things in a group" which we thought a notable goal.</li>
<li>Cream can also be a soothing ointment for one's ails. From the time I began using GNU/Linux in 1999 to the time I began writing Cream in late 2001, there were no sophisticated graphical text editors for GNU/Linux, one of the more frustrating experiences I've had in computing.</li>
<li>And while I have very little interest in that seminal 1960s rock band, I do play a Fender Stratocaster.</li>
</ul>
<p> </p>
<h2>Using Cream</h2>
<br>
<h5><a name="0101">How can I make tab keystrokes insert spaces rather than the default tab character?</a></h5>
<p>Turn on Auto Wrap in the Settings menu. Auto Wrap also links line wrapping at the Wrap Width (also in Settings), but if you don't like this, just set your width to something high, like 9999.</p>
<p>Change your tab spacing with Tabstop Width under Preferences in the Settings menu.</p>
<br>
<h5><a name="0102">Column Select doesn't seem to work for me.</a></h5>
<p>You can start column mode with Alt+Shift+<i>motion key/mouse</i> or from the Edit >Column Select menu. Once in column mode, extend the selection by holding down the Shift key (and optionally, the Alt key) while using other motion keys. End the selection by using motion keys or mouse keys without Shift. Please see the <a href="keyboardshortcuts.html">Keyboard Shortcut</a> section "Column Mode" for more specifics.</p>
<br>
<h5><a name="0103">How can I start command mode for the occasional traditional Vim :command?</a></h5>
<p>Ctrl+L switches to normal mode along with it's alternative Ctrl+\,Ctrl+N.</p>
<p>Ctrl+B switches to normal mode for only a single command.</p>
<p>You can also select Expert Mode from the Settings menu to toggle between Normal and Insert mode with the Esc key.</p>
<br>
<h5><a name="0105">How can I install Cream without having root access?</a></h5>
<p>Create an environment variable $CREAM that points to wherever you put your Cream folder before using a revised startup command. You could put this in a single file, <tt>~/mycream.sh</tt>:</p>
<blockquote>
<tt>
#!/bin/sh<br>
<br>
CREAM=/home/mylogin/cream<br>
export CREAM<br>
<br>
gvim -U NONE -u "\$CREAM/creamrc" "$@"<br>
</tt>
</blockquote>
<br>
<br>
<h5><a name="0106">How can I start Cream from gVim?</a></h5>
<p>You can start Cream from within a regular session of gVim simply by entering:</p>
<blockquote>
<tt>
:source $VIMRUNTIME/cream/creamrc<br>
:doautoall VimEnter<br>
</tt>
</blockquote>
<br>
<br>
<h5><a name="0107">How can I re-enable Vim 7's bracket highlighting?</a></h5>
<p>Put these lines in your cream-user.vim:</p>
<blockquote>
<tt>
if exists("g:loaded_matchparen")<br>
unlet g:loaded_matchparen<br>
endif<br>
runtime plugin/matchparen.vim<br>
DoMatchParen<br>
</tt>
</blockquote>
<br>
<br>
<h5><a name="0108">How do I manually create the Windows right-click "Edit with Cream/Vim" menu?</a></h5>
<p>Create the registry entry <tt>HKEY_CLASSES_ROOT\*\Shell\Cream</tt> named "Edit with Cream/&Vim" with the command (all on one line):</p>
<blockquote>
<tt>
"C:\PROGRA~1\vim\vim71\gvim.exe" "-u" "C:\PROGRA~1\vim\vim71\cream\creamrc" "-U" "NONE" "--servername" "CREAM" "%1"
</tt>
</blockquote>
<p>Verify that the path is correct for your system. You might also change "%1" to "%*" to open more than one file at a time, although Windows usually gets this wrong and passes a single path with spaces as multiple strings that Vim interprets as multiple files.</p>
<br>
<h5><a name="0109">How do I make Cream the default Windows application for text files?</a></h5>
<p>Create the registry entry <tt>HKEY_CLASSES_ROOT\txtfile\shell\open</tt> with the same command as the previous item above.</p>
<br>
<h5><a name="0110">How do I make Cream the default Windows application for un-affiliated files?</a></h5>
<p>Create the registry entry <tt>HKEY_CLASSES_ROOT\Unknown\shell\Open</tt> with the same command as the previous item above.</p>
<p> </p>
<h2>Advanced Vim Users</h2>
<br>
<h5><a name="0201">How can I use my personal customizations with Cream?</a></h5>
<p>Beginning with Cream version 0.29, all user customizations belong under the user's home directory. By default this is <tt>$HOME/.cream/</tt> on either Windows or Linux, but enter <code>:echo g:cream_user</code> at the command line to see the actual path found. The files:</p>
<blockquote>
<p><tt>cream-user.vim</tt> -- loaded at the end of startup. We recommend that all customizations be placed here so they are able to over-ride any Cream settings if desired.</p>
<p><tt>cream-conf.vim</tt> -- loaded at the beginning of startup. This file can be used to condition variables affecting Cream startup, but this is recommended only for advanced users that are trying to add or counter-affect autocmds. See the distributed <tt>cream-conf.example.vim</tt> for more information.</p>
<p>All Vim files (<tt>*.vim</tt>) found in a subdirectory <tt>addons</tt> will be loaded.</p>
<p>User spelling dictionaries (<tt>cream-spell-dict-usr_?.vim</tt>) are placed in <tt>spelldicts</tt> and are referenced by spell check features.</p>
</blockquote>
<p>All files should be conforming Vim script and aware of Cream refinements of multi-platform considerations, Unicode flexibilities, and auto command events.</p>
<p><b>Advanced:</b> Set the user directory other than the default with an environmental variable <tt>$CREAM_USER</tt>. (Requires a trailing slash.)</p>
<br>
<h5><a name="0202">How can I use customizations to Cream system wide?</a></h5>
<p>Cream will source a file $CREAM/cream-user.vim just prior to sourcing the user's cream-user.vim mentioned above.</p>
<br>
<h5><a name="0202b">How are system-wide customizations loaded? Do user preferences override these global settings?</a></h5>
<p>Order of load is as follows:</p>
<ol>
<li><tt>$CREAM . "cream-conf.vim"</tt> [cream.vim] (If present, this may/should define and call a function named <tt>Cream_conf_override()</tt>. See cream-conf.example.vim.)</li>
<li><tt>g:cream_user . "cream-conf.vim"</tt> [cream.vim] (If present, this may/should define and call a function named <tt>Cream_conf_override()</tt> <i>which will overwrite the function of the same name in step 1 above</i>. See cream-conf.example.vim.)</li>
<li><tt>~/.cream/views/.viminfo</tt> [cream.vim]</li>
<li><tt>$CREAM . "cream-user.vim"</tt> [cream-autocmd.vim] (VimEnter event)</li>
<li><tt>g:cream_user . "cream-user.vim"</tt> [cream-autocmd.vim] (VimEnter event)</li>
<li><tt>Cream_conf_override()</tt> [cream-autocmd.vim] (BufEnter event. If and as defined in steps 1 and 2 above, this is called <b>with every buffer switch</b>.)</li>
</ol>
<p>Any setting or function found early will be active unless a later step overwrites it.</p>
<p>Make global settings as light as possible. Don't set personal preferences unless they are mandated for all editing. Even then, a personal preference set within a buffer will override anything else since no autocmd event will intervene. The user's cream-conf also takes precedence.</p>
<br>
<h5><a name="0203">I love everything except [feature x]. Is there any way I can turn it off?</a></h5>
<p>As described just above, Cream will load a user "cream-conf.vim" file that can be made by renaming the distributed "cream-conf.example.vim". It provides a few Power User options and over-rides documented items within that file that are not accessible via the menus. We strongly suggest using "cream-user.vim" instead, and refer you to cream-conf.vim only in cases where sophisticated autocommands or Cream loading needs to be shaped beyond what the menus provide.</p>
<br>
<h5><a name="0204">Do you ever plan on making Cream work (better) in terminal/console versions?</a></h5>
<p>We've tried but there are many limitations within terminals that restrict the feature set including keystrokes that some of our base functions rely upon. Along with menu, display, and platform inconsistencies, terminal support for Cream would be a severe subset of the project's efforts. We would like to offer this, but with such short resources, it appears unlikely that significant progress could be made on this front.</p>
<br>
<h5><a name="0205">Sometimes I want to just use just a subset of Cream, for example, can I turn off Cream's keystrokes?</a></h5>
<p>There are various ways of using more or less Cream in your Vim:</p>
<p><b>0.</b> Please read the comments above on using Ctrl+L (alternative Ctrl+\,Ctrl+N) and Ctrl+B to enter Normal mode two different ways.</p>
<p><b>1.</b> Select "Expert mode" from the Settings > Preferences menu. This maps the Esc key as a toggle between standard Cream behavior and Vim's normal mode. All of the Cream configuration is preserved, except the function of the Esc key and use of visual mode instead of select mode in most cases.</p>
<p><b>2.</b> Use one of the three alternate behaviors available in the Settings > Preferences > Behavior menu:</p>
<ul>
<li><b>Cream Lite:</b> Removes only the customized Cream mappings and insertmode. You get to keep everything else and still pretend you're using Vim. ;)</li>
<li><b>Vim:</b> Re-initializes the text editor, removing all of Cream's customizations to leave the default Vim editing behavior.</li>
<li><b>Vi:</b> Re-initializes the text editor with strict Vi editing behavior.</li>
</ul>
<p>Note these last two menu selections are not preserved session to session. However...</p>
<p><b>3.</b> Cream provides an advanced user configuration option (in the cream-conf.vim file) which can effectively maintain the above three behavioral settings each restart if you need this for some reason.</p>
<p><b>4.</b> Use both separately! As of version 0.29, Cream no longer alters any aspects of your Vim installation. Just use the Vim icon and the Cream icon to start separate, un-related sessions.</p>
<br>
<h5><a name="0206">How do Vim and Vi behavior settings differ from Expert Mode?</a></h5>
<p>When selecting one of these two behaviors, Vim is completely re-initialized to one of the text editor's two base behavior configurations (Vim or Vi). (You'll have to read Vim's manual for more.)</p>
<p>These behavior configurations differ from Expert Mode in that they completely unload Cream. Expert Mode merely provides a trapdoor to Normal mode without changing any of the extensive Cream setup to preserve settings, menus, statusline, or any of the other thousands of things we've tweaked.</p>
<br>
<h5><a name="0207">Is there a way I can use the Cream installed on my Windows partition with my GNU/Linux Vim?</a></h5>
<p>Yes, see the question above for initializing Vim without the default vimrc. Cream has been planned to work equally well on both Windows and GNU/Linux.</p>
<p>Note that we've experienced problems calling paths with spaces (ie "Program Files") and have been unable to work around by escaping them. You may have to use the 8.3 format for directory names ("PROGRA~1"). </p>
<br>
<h5><a name="0208">Tell me more about multiple users with a single installation, i.e., the optional $VIMINIT, $CREAM, $CREAM_BAK, $CREAM_SWP, and $CREAM_VIEW environmental variables.</a></h5>
<p>If installed per <a href="installation.html">instructions</a>, Cream does not require any specific environmental variables to be set. However, in some instances a user or system administrator may wish to use shell variables to control path locations or set up multiple users with a single installation. In such cases, the following optional environmental variables are available:</p>
<pre>
Writable?
$VIMINIT No <sup>1</sup>
Start Vim and over-ride default vimrc. Should
be in the form "source [path/filename]" and
point to Cream's vimrc.
$CREAM No <sup>1</sup>
Location for the general Cream files.
$CREAM_BAK Yes<sup>2</sup>
Location to place backup files.
$CREAM_SWP Yes<sup>3</sup>
Location to place swap files.
$CREAM_VIEW Yes
Location to place view and viminfo files.
(All retained preferences.)
$CREAM_USER Yes<sup>4</sup>
Location to place user dictionaries, user
scripts, user add-ons, etc. (See above.)
</pre>
<p>Notes:</p>
<blockquote>
<p><sup>1</sup>Neither $VIMINIT or $CREAM need to be writable (if specified) as long as Cream finds the path specified by $CREAM_VIEW writable.</p>
<p><sup>2</sup>Since a backup directory can always be discovered (each edited file's own path), it is not required.</p>
<p><sup>3</sup>The swapfile location defaults to that of backups unless specified here. Since both share security concerns equally, there is no additional overhead added by default.</p>
<p><sup>4</sup><tt>$CREAM_USER</tt> is currently found independently of the other variables.</p>
</blockquote>
<br>
<h5><a name="0209">How can I prevent Cream from loading my Vim plugins?</a></h5>
<p>Vim plugins will not be loaded (via <tt>:set noloadplugins</tt> control) if variable g:CREAM_NOVIMPLUGINS is set to "1", which must be put in cream-conf.</p>
<br>
<h5><a name="0211">On startup I get: "Unable to use Cream bookmarking features, no compiled support for signs"</a></h5>
<p>Use the "--with-features=big" configure option before you compile. This will enable the GUI, signs, dialogs and many other useful Vim features that Cream depends on. (And that Vim's developers have spent a lot of time developing!) Note that this is the typical configuration for <i>most</i> larger distributions, but certainly not all of them. For more information see <code>:help version</code> and <code>:help install</code>.</p>
<br>
<h5><a name="0212">How can I get the Unix/X11 behavior where the middle-mouse button pastes a selection?</a></h5>
<p>Cream now has this as an option, just use Settings > Preferences > Middle-Mouse Pastes.</p>
<br>
<h5><a name="0213">Is it possible to overwrite Cream settings per filetype?</a></h5>
<p>To overwrite Cream settings you can do the same thing Cream does to override Vim settings--load an autocmd that calls a function to change the settings.</p>
<p>In your cream-user file, create a function that handles your settings:</p>
<pre>
function! MySettings()
if &ft == "vim"
let &tabstop = 6
endif
(...other settings...)
endfunction
</pre>
<p>Then add an autocmd to call it that is activated whenever Cream/Vim starts, the current file is changed or made new:</p>
<pre>
autocmd BufEnter,BufNewFile * call MySettings()
</pre>
<br>
<h5><a name="0214">How do I use cream as my editor from Mutt? When I set cream as my editor in my .muttrc file, a reply opens Cream, but it's empty.</a></h5>
<p>You need to tell vim (and therefore by extension, gcream) not to fork and stay in the foreground with the "-f" flag. Therefore, from within your ~/.muttrc file, you'll want a line that looks something like:</p>
<blockquote>
<code>set editor = "cream -f"</code>
</blockquote>
<br>
<h5><a name="0215">Why is Cream sluggish when editing on a distant network?</a></h5>
<p>As of version 0.33, this issue has been mostly solved. On the outside chance you still experience this behavior, try to force the current directory to somewhere local by setting the <tt>g:CREAM_CWD</tt> variable in the cream-conf file. If that fails to fix the symptom, please <a href="contribute.html">let us know</a>.</p>
<br>
<h5><a name="0216">How can I make the Esc key in Expert Mode always stay in normal mode (not toggle between Insert and Normal mode)?</a></h5>
<p>Put</p>
<blockquote>
<code>nmap <Esc> <Nop></code>
</blockquote>
<p>in your cream-user.</p>
<br>
<h5><a name="0217">How can I make Expert Mode Cream start in normal mode?</a></h5>
<p>Put</p>
<blockquote>
<code>set noinsertmode</code>
</blockquote>
<p>in your cream-user.</p>
<h5><a name="0218">How can I use the Windows installer silently?</a></h5>
<p>The Windows installer has a few command line switches:</p>
<blockquote>
<table cellpadding="4" cellspacing="0" border="0">
<tr><td width="140"><tt>/S</tt></td>
<td>Silent install (all GUI or dialogs are avoided and the installer runs silently with the default settings)</td>
</tr>
<tr><td><tt>/CONTEXTMENU 1</tt></td>
<td>Forces installation of the context-sensitive right-click menu.</td>
</tr>
</table>
</blockquote>
<h5><a name="0219">How do I use custom color themes with Cream?</a></h5>
<p>Vim themes can not be used directly within Cream without a few minor adjustments to the theme and to the loading mechanism. Some variable settings are added (so that they can be retained across sessions) as well as a few custom highlighting groups (for custom Cream features).</p>
<p>You can usually cut/paste the obvious Cream additions in <tt>cream-colors-*</tt> into your own, starting with one that most closely matches the one you're adapting. Load it each session with by sourcing it in cream-user, or hack an update in <tt>cream-colors.vim</tt>. Better yet, send in a patch so that Cream can dynamically manage and load any themes found in a new subdirectory <tt>colors/</tt> !</p>
<p> </p>
<h2>Developers</h2>
<p><i>Please see also the ASCII document "DEVELOPER.txt" in the package for additional ad hoc developer information.</i></p>
<br>
<h5><a name="0301">Wouldn't it be cool if Cream had (my) mappings and functions for [ HTML | Perl | PHP | Python | Tex | C | C++ | Java ] built in?</a></h5>
<p>Why not just write a Cream Add-on that users can load from the menu? Please see the cream-templates.vim script we use to provide templates, too.</p>
<br>
<h5><a name="0302">What are Add-ons?</a></h5>
<p>Add-ons are essentially refined Vim plugins. Cream will autoload these (if placed in the <tt>$CREAM/addons</tt> subdirectory).</p>
<p>The point is to make modules more automatic and accessible, while at the same time modularizing the project by reducing out portions of "optional" functionality. We even debated dumping the entire Insert and Format menu stuff here, but decided to reserve them for necessities.</p>
<p>Recommended tips for authoring add-ons goes like this:</p>
<ul>
<li>Create a functional Vim script that is well-coordinated with Cream.</li>
<li>Make sure the add-on's function is accessible via a function call. Don't rely on simple statements because they won't be controlable.</li>
<li>At the top of the script, load the add-on with a statement like this:</li>
</ul>
<blockquote>
<tt>
" list as an add-on if Cream project in use<br>
if exists("$CREAM")<br>
call Cream_addon_list(<br>
\ '{name}', <br>
\ '{tag}', <br>
\ '{summary}', <br>
\ '{menu}', <br>
\ '{icall}'<br>
\ '{vcall}'<br>
\ )<br>
endif<br>
</tt>
</blockquote>
<p>where</p>
<ul>
<li><b>{name}</b> is the add-on's name</li>
<li><b>{tag}</b> is a short tag line description</li>
<li><b>{summary}</b> is a paragraph shorter than 512 characters, returns allowed</li>
<li><b>{menu}</b> the name as it should appear in a menu.
<ul>
<li>Accelerator "&" is accepted, but not advised due to potential conflicts.</li>
<li>Cream automatically handles spaces and slashes.</li>
<li>You can use a period to designate a submenu used by multiple items.</li>
<li>Cream will sort menu entries from all the loaded addons prior to placing them. Sorting is done based on the first two letters of the entry. (Vim has a 16-bit value limitation on menu priority and 26^2 * [1-26] puts us just to that limit.) Submenus are not sorted.</li>
</ul>
</li>
<li><b>{icall}</b> Insert mode function call or execute statement that Cream will run on menu select or key press. Optional: Use '<Nil>' to eliminate insertmode call/map. Requires valid visual mode call.</li>
<li><b>{vcall}</b> Visual mode (optional) functon call if the function behaves differently from Insert and Visual modes. If omitted, no visual mode mapping or menu is created. ('<Nil>' also accepted.) Note that a range will be passed to the visual call. Unless you've specifically designed the function to accept a range or are calling a command rather than a function, eliminate the range by preceding the function call with <tt><C-u></tt>.</li>
</ul>
<p>This call loads the values for selection of the addon in a dialog box, menu and allows it to be mapped to a "power key" combination which is retained across sessions.</p>
<p>Example:</p>
<blockquote>
<tt>
" register as a Cream add-on<br>
if exists("$CREAM")<br>
call Cream_addon_list(<br>
\ 'Cool Utility', <br>
\ 'Jumps through hoops at a single bound', <br>
\ 'This utility is a veritable one ring circus in a function. Use it to clean the dishes, take out the dog and romance that special someone in your life!', <br>
\ 'Cool Utility', <br>
\ 'call CoolUtility("i")'<br>
\ '<C-u>call CoolUtility("v")'<br>
\ )<br>
endif<br>
</tt>
</blockquote>
<br>
<h5><a name="0303">What are some guidelines to consider if I want to submit a patch to Cream?</a></h5>
<p>Hopefully, patches will respect the general goals of the project. Here are a few principles to consider:</p>
<ul>
<li>Licensed under the GPL or compatible license.</li>
<li>Vim script only. (Check the Vim mailing lists for patches to Vim itself.)</li>
<li>Simple. Remember, Cream is a usability project. Vim already does everything, we're just trying to make it simpler. If you provide twenty-three different options for the user, chances are he won't change any of them, it should JustWork™.</li>
<li>Not dependent on external apps or libraries. This includes perl, python, common shell commands, etc.</li>
<li>Multi-platform. If you must use some external OS call, write routines that handle both Unix and Windows 95-XP environments. See the Sort File add-on as an example of how hard this can be.</li>
<li>Unix file format. (Works on Windows, too, but not vice-versa.)</li>
<li>With a coding style similar to the remainder of the project. We <i>despise</i> Vim's shortcut language because it greatly reduces readability. While faster for Vim power users to type at the command line, Cream doesn't rely on typing so there is no reason to shorten names!</li>
<li>We like tabs. Honestly. (Ok, we'll accept spaces, but we may not be able to resist converting them. ;)</li>
</ul>
<br>
<h5><a name="0304">Are there any hidden functions or routines that you've made available in the project that might be useful if I wish to help contribute to Cream?</a></h5>
<p>Nothing too special, except for a developer menu, the playpen and a few add-ons. These can be exposed simply by uncommenting a line toward the top of cream.vim that looks like:</p>
<p><tt>let g:cream_dev = 1</tt></p>
<p>The menu makes jumping around the project files easier and the playpen is where some minor things are written and tested before becoming part of the project. The Add-ons Devel menu has a few functions that you won't find too helpful unless your specifically developing Vim or Cream.</p>
<br>
<h5><a name="0305">How can I use CVS to get Cream?</a></h5>
<p>CVS is a tool for advanced developers, and explaining it's use is far beyond the scope of our project. Feel free to browse the <a href="http://sourceforge.net/cvs/?group_id=43866">Cream CVS repository</a> or read more about this powerful tool in the free on-line <a href="http://cvsbook.red-bean.com/">CVS Book</a> (<a href="http://cvsbook.red-bean.com/cvsbook.html">direct link, 1st edition HTML</a>).</p>
<br>
<h5><a name="0306">How can I write a mapping/menu item to do multiple or more complex things?</a></h5>
<p>There is a simple strategy of writing vimscript that:</p>
<ul>
<li>Can handle complex tasks</li>
<li>Is portable across modes</li>
<li>Is portable independed of <tt>&insertmode</tt> settings</li>
<li>Avoids Vim's default preceding or following code in the general <tt>:amenu</tt> or <tt>:nmap</tt></li>
<li>Modularizes logic into distinct functions</li>
<li>Avoids embedding logic into menu item and keyboard map calls</li>
<li>Avoids conditional codes into menu item and keyboard map calls</li>
</ul>
<p>Use functions (<tt>:help functions</tt>) exclusively for all actions, and single line calls to them with all maps and menus:
<blockquote>
<pre>
function! MyFun()
" insert "Hi!" at the cursor
normal iHi!
endfunction
imap <F12> <C-o>:call MyFun()<CR>
</pre>
</blockquote>
<p>Any number of actions or logic can be put into the function. This blossoms once you realize that functions can call other functions and control options, menus, the statusline, call dialogs, etc.</p>
<p>In the example above, the mapping is a single-moded one, it does not use a general <tt>:nmap</tt> or <tt>:amenu</tt> command. Using these single-mode calls avoids the occasional bug caused by Vim's addition of preceding and trailing codes in the generalized <tt>:amenu</tt> and <tt>:nmap</tt> calls. (See a few paragraphs down in <tt>:help creating-menus</tt>.) Note how the mapping has an initial keyboard code to drop out of normal mode and call the function? For an <tt>imap</tt>, Ctrl+B leaves normal mode and the ":" enters the command line where the function is then entered literally and completed with an executing carriage return.</p>
<p>Another reason for single-mode calls is because <i>Vim's <tt>mode()</tt> function always returns "n" within a function.</i> It isn't possible to determine what mode the function was called from <i>after</i> the fact. By restricting the function call to a single mode, it clarifies the function's "point of view". During development this modal clarity is a great assist in avoiding vimscript bugs which creep in when the pre-function state is less obvious.</p>
<p>However, what about situations where a more complex function needs to react according to its called mode? As already alluded to, we need to somehow know the mode <i>before</i> entering the function. The trick is to <i>pass in the mode at the call.</i> Take the example:</p>
<blockquote>
<pre>
function! MyFun(mode)
if a:mode == "v"
" reselect selection
normal gv
...
elseif a:mode == "i"
...
endif
...
endfunction
imap <F12> <C-o>:call MyFun("i")<CR>
vmap <F12> :<C-u>call MyFun("v")<CR>
</pre>
</blockquote>
<p>The mode is passed from the map as an argument to the function. Remember that an <tt>imap</tt> can only be called from insert mode. Therefore the "i" in the a:mode variable will always indicate the insert mode call. Use of the "if" construct can then condition statements to mode, such as the <tt>normal gv</tt> statement in the example--since only useful to recover the visual selection at the moment the user pressed the vmap, it is restricted to cases where a:mode is "v".</p>
<p>Note above that the <tt>vmap</tt> visual mode call preceding sequence is different from an <tt>imap</tt>, since ":" from visual mode goes directly to the command line and Ctrl+U erases Vim's automatic addition of range symbols. These specifics are all handled in clear, literal fasion, there are no hidden codes to deal with.</p>
<p>The same principles can be used to make portable menu items in the same fashion:</p>
<blockquote>
<pre>
imenu 20.1 &MyMenu.InsertMode <C-o>:call MyFun("i")<CR>
vmenu 20.1 &MyMenu.VisualMode :<C-u>call MyFun("v")<CR>
</pre>
</blockquote>
<p>Simply developing a function library and integration of calls and returns makes this approach a very powerful scheme that avoids all the usual issues with basic mappings and menus. Which is why Cream was able to grow and mature so quickly once this strategy was adoped.</p>
</div>
<!-- footer {{{1 -->
<div class="footer">
© Copyright 2001-2011 by Steve Hall
<small>: :</small>
Site and project hosting by <a href="http://sourceforge.net/projects/cream"><img class="sflogo" src="http://sflogo.sourceforge.net/sflogo.php?group_id=43866&type=1" width="88" height="31" alt="Get Cream (for Vim) at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</div>
<!-- 1}}} -->
</div>
</div>
</body>
</html>
<!-- vim:foldmethod=marker
-->
|
