Cream :: a modern configuration of the Vim text editor

features

Frequently Asked Questions (FAQ)

Where does the name "Cream" come from?

Answers

Where does the name "Cream" come from?

The name was inspired by the convergence of several ideas:

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.
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.
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.
"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.
One of the definitions of "Cream" is "the best people or things in a group" which we thought a notable goal.
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.
And while I have very little interest in that seminal 1960s rock band, I do play a Fender Stratocaster.

Using Cream

How can I make tab keystrokes insert spaces rather than the default tab character?

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.

Change your tab spacing with Tabstop Width under Preferences in the Settings menu.

Column Select doesn't seem to work for me.

You can start column mode with Alt+Shift+motion key/mouse 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 Keyboard Shortcut section "Column Mode" for more specifics.

How can I start command mode for the occasional traditional Vim :command?

Ctrl+L switches to normal mode along with it's alternative Ctrl+\,Ctrl+N.

Ctrl+B switches to normal mode for only a single command.

You can also select Expert Mode from the Settings menu to toggle between Normal and Insert mode with the Esc key.

How can I install Cream without having root access?

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, ~/mycream.sh:

#!/bin/sh CREAM=/home/mylogin/cream export CREAM gvim -U NONE -u "\$CREAM/creamrc" "$@"

How can I start Cream from gVim?

You can start Cream from within a regular session of gVim simply by entering:

:source $VIMRUNTIME/cream/creamrc :doautoall VimEnter

How can I re-enable Vim 7's bracket highlighting?

Put these lines in your cream-user.vim:

if exists("g:loaded_matchparen") unlet g:loaded_matchparen endif runtime plugin/matchparen.vim DoMatchParen

How do I manually create the Windows right-click "Edit with Cream/Vim" menu?

Create the registry entry HKEY_CLASSES_ROOT\*\Shell\Cream named "Edit with Cream/&Vim" with the command (all on one line):

"C:\PROGRA~1\vim\vim71\gvim.exe" "-u" "C:\PROGRA~1\vim\vim71\cream\creamrc" "-U" "NONE" "--servername" "CREAM" "%1"

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.

How do I make Cream the default Windows application for text files?

Create the registry entry HKEY_CLASSES_ROOT\txtfile\shell\open with the same command as the previous item above.

How do I make Cream the default Windows application for un-affiliated files?

Create the registry entry HKEY_CLASSES_ROOT\Unknown\shell\Open with the same command as the previous item above.

Advanced Vim Users

How can I use my personal customizations with Cream?

Beginning with Cream version 0.29, all user customizations belong under the user's home directory. By default this is $HOME/.cream/ on either Windows or Linux, but enter :echo g:cream_user at the command line to see the actual path found. The files:

cream-user.vim -- 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.

cream-conf.vim -- 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 cream-conf.example.vim for more information.

All Vim files (*.vim) found in a subdirectory addons will be loaded.

User spelling dictionaries (cream-spell-dict-usr_?.vim) are placed in spelldicts and are referenced by spell check features.

All files should be conforming Vim script and aware of Cream refinements of multi-platform considerations, Unicode flexibilities, and auto command events.

Advanced: Set the user directory other than the default with an environmental variable $CREAM_USER. (Requires a trailing slash.)

How can I use customizations to Cream system wide?

Cream will source a file $CREAM/cream-user.vim just prior to sourcing the user's cream-user.vim mentioned above.

How are system-wide customizations loaded? Do user preferences override these global settings?

Order of load is as follows:

$CREAM . "cream-conf.vim" [cream.vim] (If present, this may/should define and call a function named Cream_conf_override(). See cream-conf.example.vim.)
g:cream_user . "cream-conf.vim" [cream.vim] (If present, this may/should define and call a function named Cream_conf_override() which will overwrite the function of the same name in step 1 above. See cream-conf.example.vim.)
~/.cream/views/.viminfo [cream.vim]
$CREAM . "cream-user.vim" [cream-autocmd.vim] (VimEnter event)
g:cream_user . "cream-user.vim" [cream-autocmd.vim] (VimEnter event)
Cream_conf_override() [cream-autocmd.vim] (BufEnter event. If and as defined in steps 1 and 2 above, this is called with every buffer switch.)

Any setting or function found early will be active unless a later step overwrites it.

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.

I love everything except [feature x]. Is there any way I can turn it off?

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.

Do you ever plan on making Cream work (better) in terminal/console versions?

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.

Sometimes I want to just use just a subset of Cream, for example, can I turn off Cream's keystrokes?

There are various ways of using more or less Cream in your Vim:

0. Please read the comments above on using Ctrl+L (alternative Ctrl+\,Ctrl+N) and Ctrl+B to enter Normal mode two different ways.

1. 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.

2. Use one of the three alternate behaviors available in the Settings > Preferences > Behavior menu:

Cream Lite: Removes only the customized Cream mappings and insertmode. You get to keep everything else and still pretend you're using Vim. ;)
Vim: Re-initializes the text editor, removing all of Cream's customizations to leave the default Vim editing behavior.
Vi: Re-initializes the text editor with strict Vi editing behavior.

Note these last two menu selections are not preserved session to session. However...

3. 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.

4. 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.

How do Vim and Vi behavior settings differ from Expert Mode?

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.)

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.

Is there a way I can use the Cream installed on my Windows partition with my GNU/Linux Vim?

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.

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").

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.

If installed per instructions, 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:

                                                  Writable?
 $VIMINIT                                           No ¹
   Start Vim and over-ride default vimrc. Should
   be in the form "source [path/filename]" and
   point to Cream's vimrc.

 $CREAM                                             No ¹
   Location for the general Cream files.

 $CREAM_BAK                                         Yes²
   Location to place backup files.

 $CREAM_SWP                                         Yes³
   Location to place swap files.

 $CREAM_VIEW                                        Yes
   Location to place view and viminfo files.
   (All retained preferences.)

 $CREAM_USER                                        Yes⁴
   Location to place user dictionaries, user
   scripts, user add-ons, etc. (See above.)

Notes:

¹Neither $VIMINIT or $CREAM need to be writable (if specified) as long as Cream finds the path specified by $CREAM_VIEW writable.

²Since a backup directory can always be discovered (each edited file's own path), it is not required.

³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.

⁴$CREAM_USER is currently found independently of the other variables.

How can I prevent Cream from loading my Vim plugins?

Vim plugins will not be loaded (via :set noloadplugins control) if variable g:CREAM_NOVIMPLUGINS is set to "1", which must be put in cream-conf.

On startup I get: "Unable to use Cream bookmarking features, no compiled support for signs"

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 most larger distributions, but certainly not all of them. For more information see :help version and :help install.

How can I get the Unix/X11 behavior where the middle-mouse button pastes a selection?

Cream now has this as an option, just use Settings > Preferences > Middle-Mouse Pastes.

Is it possible to overwrite Cream settings per filetype?

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.

In your cream-user file, create a function that handles your settings:

    function! MySettings()
        if &ft == "vim"
            let &tabstop = 6
        endif
        (...other settings...)
    endfunction

Then add an autocmd to call it that is activated whenever Cream/Vim starts, the current file is changed or made new:

    autocmd BufEnter,BufNewFile * call MySettings()

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.

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:

set editor = "cream -f"

Why is Cream sluggish when editing on a distant network?

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 g:CREAM_CWD variable in the cream-conf file. If that fails to fix the symptom, please let us know.

How can I make the Esc key in Expert Mode always stay in normal mode (not toggle between Insert and Normal mode)?

Put

nmap <Esc> <Nop>

in your cream-user.

How can I make Expert Mode Cream start in normal mode?

Put

set noinsertmode

in your cream-user.

How can I use the Windows installer silently?

The Windows installer has a few command line switches:

/S Silent install (all GUI or dialogs are avoided and the installer runs silently with the default settings)

/CONTEXTMENU 1 Forces installation of the context-sensitive right-click menu.

How do I use custom color themes with Cream?

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).

You can usually cut/paste the obvious Cream additions in cream-colors-* 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 cream-colors.vim. Better yet, send in a patch so that Cream can dynamically manage and load any themes found in a new subdirectory colors/ !

Developers

Please see also the ASCII document "DEVELOPER.txt" in the package for additional ad hoc developer information.

Wouldn't it be cool if Cream had (my) mappings and functions for [ HTML | Perl | PHP | Python | Tex | C | C++ | Java ] built in?

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.

What are Add-ons?

Add-ons are essentially refined Vim plugins. Cream will autoload these (if placed in the $CREAM/addons subdirectory).

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.

Recommended tips for authoring add-ons goes like this:

Create a functional Vim script that is well-coordinated with Cream.
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.
At the top of the script, load the add-on with a statement like this:

" list as an add-on if Cream project in use if exists("$CREAM") call Cream_addon_list( \ '{name}', \ '{tag}', \ '{summary}', \ '{menu}', \ '{icall}' \ '{vcall}' \ ) endif

where

{name} is the add-on's name
{tag} is a short tag line description
{summary} is a paragraph shorter than 512 characters, returns allowed
{menu} the name as it should appear in a menu.
- Accelerator "&" is accepted, but not advised due to potential conflicts.
- Cream automatically handles spaces and slashes.
- You can use a period to designate a submenu used by multiple items.
- 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.
{icall} 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.
{vcall} 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 <C-u>.

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.

Example:

" register as a Cream add-on if exists("$CREAM") call Cream_addon_list( \ 'Cool Utility', \ 'Jumps through hoops at a single bound', \ '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!', \ 'Cool Utility', \ 'call CoolUtility("i")' \ '<C-u>call CoolUtility("v")' \ ) endif

What are some guidelines to consider if I want to submit a patch to Cream?

Hopefully, patches will respect the general goals of the project. Here are a few principles to consider:

Licensed under the GPL or compatible license.
Vim script only. (Check the Vim mailing lists for patches to Vim itself.)
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™.
Not dependent on external apps or libraries. This includes perl, python, common shell commands, etc.
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.
Unix file format. (Works on Windows, too, but not vice-versa.)
With a coding style similar to the remainder of the project. We despise 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!
We like tabs. Honestly. (Ok, we'll accept spaces, but we may not be able to resist converting them. ;)

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?

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:

let g:cream_dev = 1

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.

How can I use CVS to get Cream?

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 Cream CVS repository or read more about this powerful tool in the free on-line CVS Book (direct link, 1st edition HTML).

How can I write a mapping/menu item to do multiple or more complex things?

There is a simple strategy of writing vimscript that:

Can handle complex tasks
Is portable across modes
Is portable independed of &insertmode settings
Avoids Vim's default preceding or following code in the general :amenu or :nmap
Modularizes logic into distinct functions
Avoids embedding logic into menu item and keyboard map calls
Avoids conditional codes into menu item and keyboard map calls

Use functions (:help functions) exclusively for all actions, and single line calls to them with all maps and menus:

function! MyFun()
    " insert "Hi!" at the cursor
    normal iHi!
endfunction
imap <F12> <C-o>:call MyFun()<CR>

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.

In the example above, the mapping is a single-moded one, it does not use a general :nmap or :amenu command. Using these single-mode calls avoids the occasional bug caused by Vim's addition of preceding and trailing codes in the generalized :amenu and :nmap calls. (See a few paragraphs down in :help creating-menus.) Note how the mapping has an initial keyboard code to drop out of normal mode and call the function? For an imap, 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.

Another reason for single-mode calls is because Vim's mode() function always returns "n" within a function. It isn't possible to determine what mode the function was called from after 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.

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 before entering the function. The trick is to pass in the mode at the call. Take the example:

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>

The mode is passed from the map as an argument to the function. Remember that an imap 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 normal gv 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".

Note above that the vmap visual mode call preceding sequence is different from an imap, 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.

The same principles can be used to make portable menu items in the same fashion:

imenu 20.1 &MyMenu.InsertMode <C-o>:call MyFun("i")<CR>
vmenu 20.1 &MyMenu.VisualMode :<C-u>call MyFun("v")<CR>

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.

`/S`	Silent install (all GUI or dialogs are avoided and the installer runs silently with the default settings)
`/CONTEXTMENU 1`	Forces installation of the context-sensitive right-click menu.

Frequently Asked Questions (FAQ)

Using Cream

Advanced Users

Developers

Answers

Using Cream

Advanced Vim Users

Developers