Cream :: a modern configuration of the Vim text editor

features

Frequently Asked Questions (FAQ)

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. At the time I began writing it, 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+O 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.

Will Cream ever have a "tabbed" multiple document interface (MDI)?

Vim 7 will support this feature and we intend to add this as soon as it is officially released.

A less glamorous but equally effective alternative is to use the Alt+W key combination to open the Window menu and display the open file list at its bottom. If you try this a few times, you may come to appreciate it's screen saving "retractableness" and never miss tabs again. (Hint: Remember that when the menu pops open you can use the Arrow Up key to go instantly to the bottom of the menu.)

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

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"
g:cream_user . "cream-conf.vim" (overwrites 1.)
$CREAM . "cream-user.vim" (VimEnter autocmd event)
g:cream_user . "cream-user.vim" (VimEnter autocmd event)
~/.cream/views/.viminfo
$CREAM . "cream-conf.vim" (BufEnter autocmd event)
g:cream_user . "cream-conf.vim" (BufEnter autocmd event.)

Any setting or function found early will be active unless a later step overwrites it. Also note that 7 will replace the entire behavior found in 6 since the file is structured as a single function whose name will overwrite the previously existing function of the same name.

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. Power to the people! :)

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+O 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". This can be accomplished either in cream-user or 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.

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. We're still in a fair amount of flux given Cream's immaturity at the moment, but 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.
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 any function calls or options 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).

Frequently Asked Questions (FAQ)

Using Cream

Advanced Users

Developers

Answers

Using Cream

Advanced Vim Users

Developers