/usr/share/doc/cream/html/faq.html is in cream 0.43-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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
-->
|