diff options
Diffstat (limited to 'Doc/Zsh/contrib.yo')
| -rw-r--r-- | Doc/Zsh/contrib.yo | 192 |
1 files changed, 166 insertions, 26 deletions
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index f764eb7c6..35ce91575 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -862,7 +862,8 @@ sitem(SVK (tt(svk)))(uref(http://svk.bestpractical.com/)) endsitem() There is also support for the patch management system tt(quilt) -(uref(http://savannah.nongnu.org/projects/quilt)). See tt(Quilt Support) +(uref(http://savannah.nongnu.org/projects/quilt)). See +ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details. To load tt(vcs_info): @@ -872,6 +873,18 @@ example(autoload -Uz vcs_info) It can be used in any existing prompt, because it does not require any specific tt($psvar) entries to be available. +startmenu() +menu(vcs_info Quickstart) +menu(vcs_info Configuration) +menu(vcs_info Oddities) +menu(vcs_info Quilt Support) +menu(vcs_info API) +menu(vcs_info Variables) +menu(vcs_info Hooks) +menu(vcs_info Examples) +endmenu() + +texinode(vcs_info Quickstart)(vcs_info Configuration)()(Version Control Information) subsect(Quickstart) To get this feature working quickly (including colors), you can do the @@ -935,6 +948,7 @@ That means the detection of these systems is skipped em(completely). No wasted time there. +texinode(vcs_info Configuration)(vcs_info Oddities)(vcs_info Quickstart)(Version Control Information) subsect(Configuration) The tt(vcs_info) feature can be configured via tt(zstyle). @@ -944,11 +958,17 @@ example(:vcs_info:var(vcs-string):var(user-context):var(repo-root-name)) startitem() item(var(vcs-string))( -is one of: bf(git), bf(git-svn), bf(git-p4), bf(hg), bf(hg-git), -bf(hg-hgsubversion), bf(hg-hgsvn), bf(darcs), bf(bzr), bf(cdv), bf(mtn), -bf(svn), bf(cvs), bf(svk), bf(tla), bf(p4) or bf(fossil). When hooks are -active the hooks name is added after a `+'. (See bf(Hooks in vcs_info) -below.) +is one of: tt(git), tt(git-svn), tt(git-p4), tt(hg), tt(hg-git), +tt(hg-hgsubversion), tt(hg-hgsvn), tt(darcs), tt(bzr), tt(cdv), tt(mtn), +tt(svn), tt(cvs), tt(svk), tt(tla), tt(p4) or tt(fossil). +This is followed by `tt(.quilt-)var(quilt-mode)' in Quilt mode +(see ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details) +and by `tt(+)var(hook-name)' while hooks are active +(see ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) for details). + +COMMENT(users/20807) +Currently, hooks in quilt mode don't add the `tt(.quilt-)var(quilt-mode)' information. +This may change in the future. ) item(var(user-context))( is a freely configurable string, assignable by @@ -1056,17 +1076,17 @@ example(zstyle ':vcs_info:*' disable-patterns "${+LPAR()b+RPAR()HOME}/.zsh+LPAR( kindex(use-quilt) item(tt(use-quilt))( If enabled, the tt(quilt) support code is active in `addon' mode. -See tt(Quilt Support) for details. +See ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details. ) kindex(quilt-standalone) item(tt(quilt-standalone))( If enabled, `standalone' mode detection is attempted if no VCS is active -in a given directory. See tt(Quilt Support) for details. +in a given directory. See ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details. ) kindex(quilt-patch-dir) item(tt(quilt-patch-dir))( Overwrite the value of the tt($QUILT_PATCHES) environment variable. See -tt(Quilt Support) for details. +ifzman(bf(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) for details. ) kindex(quiltcommand) item(tt(quiltcommand))( @@ -1197,7 +1217,8 @@ is only used by tt(vcs_info)'s hooks system. ) kindex(hooks) item(tt(hooks))( -A list style that defines hook-function names. See bf(Hooks in vcs_info) +A list style that defines hook-function names. See ifzman(bf(Hooks in vcs_info))\ +ifnzman(noderef(vcs_info Hooks)) below for details. ) kindex(patch-format) @@ -1207,6 +1228,8 @@ item(tt(nopatch-format))( This pair of styles format the patch information used by the tt(%m) expando in formats and actionformats for the tt(git) and tt(hg) backends. The value is subject to certain tt(%)-expansions described below. +The expanded value is made available in the global tt(backend_misc) array as +tt(${backend_misc[patches]}) (also if a tt(set-patch-format) hook is used). ) kindex(get-unapplied) item(tt(get-unapplied))( @@ -1277,8 +1300,8 @@ A "misc" replacement. It is at the discretion of the backend to decide what this replacement expands to. The tt(hg) and tt(git) backends use this expando to display patch information. -tt(hg) sources patch information from the tt(mq) extensions; tt(git) from the -tt(rebase) command and from the and tt(stgit) extension. The tt(patch-format) +tt(hg) sources patch information from the tt(mq) extensions; tt(git) from in-progress +tt(rebase) and tt(cherry-pick) operations and from the tt(stgit) extension. The tt(patch-format) and tt(nopatch-format) styles control the generated string. The former is used when at least one patch from the patch queue has been applied, and the latter otherwise. @@ -1288,6 +1311,17 @@ to tt(mq) information). See the tt(get-mq) and tt(get-bookmarks) styles. Both of these styles may be enabled at the same time. If both are enabled, both resulting strings will be shown separated by a semicolon (that cannot currently be customized). + +The tt(quilt) `standalone' backend sets this expando to the same value as the +tt(%Q) expando. +) +item(tt(%Q))( +Quilt series information. +When quilt is used (either in `addon' mode or as a `standalone' backend), +this expando is set to quilt series' tt(patch-format) string. +The tt(set-patch-format) hook and tt(nopatch-format) style are honoured. + +See ifzman(tt(Quilt Support))ifnzman(noderef(vcs_info Quilt Support)) below for details. ) enditem() @@ -1321,6 +1355,7 @@ endsitem() Not all VCS backends have to support all replacements. For tt(nvcsformats) no replacements are performed at all, it is just a string. +texinode(vcs_info Oddities)(vcs_info Quilt Support)(vcs_info Configuration)(Version Control Information) subsect(Oddities) If you want to use the tt(%b) (bold off) prompt expansion in tt(formats), @@ -1331,7 +1366,14 @@ tt(branchformat), use tt(%%%%b). Sorry for this inconvenience, but it cannot be easily avoided. Luckily we do not clash with a lot of prompt expansions and this only needs to be done for those. +When one of the tt(gen-applied-string), tt(gen-unapplied-string), and +tt(set-patch-format) hooks is defined, +applying tt(%)-escaping (`tt(foo=${foo//'%'/%%})') to the interpolated values +for use in the prompt is the responsibility of those hooks (jointly); +when neither of those hooks is defined, tt(vcs_info) handles escaping by itself. +We regret this coupling, but it was required for backwards compatibility. +texinode(vcs_info Quilt Support)(vcs_info API)(vcs_info Oddities)(Version Control Information) subsect(Quilt Support) bf(Quilt) is not a version control system, therefore this is not implemented @@ -1346,13 +1388,22 @@ The tt(vcs_info) integration tries to support both ways of using quilt by having two slightly different modes of operation: `addon' mode and `standalone' mode). +Quilt integration is off by default; to enable it, set the tt(use-quilt) style, +and add tt(%Q) to your tt(formats) or tt(actionformats) style: +example(zstyle ':vcs_info:*' use-quilt true) + +Styles looked up from the Quilt support code include `tt(.quilt-)var(quilt-mode)' +in the var(vcs-string) part of the context, where var(quilt-mode) is either +tt(addon) or tt(standalone). +Example: tt(:vcs_info:git.quilt-addon:default:)var(repo-root-name). + For `addon' mode to become active tt(vcs_info) must have already detected a real version control system controlling the directory. If that is the case, a directory that holds quilt's patches needs to be found. That directory is configurable via the `tt(QUILT_PATCHES)' environment variable. If that variable exists its value is used, otherwise the value `tt(patches)' is assumed. The value from tt($QUILT_PATCHES) can be overwritten using the -tt(`quilt-patches') style. (Note: you can use tt(vcs_info) to keep the value +`tt(quilt-patches)' style. (Note: you can use tt(vcs_info) to keep the value of tt($QUILT_PATCHES) correct all the time via the tt(post-quilt) hook). When the directory in question is found, quilt is assumed to be active. To @@ -1366,8 +1417,10 @@ to know which patches of a series are not yet applied, you need to activate the tt(get-unapplied) style in the appropriate context. tt(vcs_info) allows for very detailed control over how the gathered -information is presented (see the below sections, bf(Styles) and bf(Hooks in -vcs_info)), all of which are documented below. Note there are a number of +information is presented (see +ifzman(the bf(Configuration) and bf(Hooks in vcs_info) sections)\ +ifnzman(noderef(vcs_info Configuration) and noderef(vcs_info Hooks))), +all of which are documented below. Note there are a number of other patch tracking systems that work on top of a certain version control system (like tt(stgit) for bf(git), or tt(mq) for bf(hg)); the configuration for systems like that are generally configured the same way as the bf(quilt) @@ -1421,6 +1474,7 @@ Note, if there is both a function and a variable by the name of tt(quilt-standalone), the function will take precedence. +texinode(vcs_info API)(vcs_info Variables)(vcs_info Quilt Support)(Version Control Information) subsect(Function Descriptions (Public API)) startitem() @@ -1429,7 +1483,8 @@ item(tt(vcs_info) [var(user-context)])( The main function, that runs all backends and assembles all data into tt(${vcs_info_msg_*_}). This is the function you want to call from tt(precmd) if you want to include up-to-date information in your prompt (see -tt(Variable description) below). If an argument is given, that string will be +ifzman(bf(Variable Description))ifnzman(noderef(vcs_info Variables)) +below). If an argument is given, that string will be used instead of tt(default) in the var(user-context) field of the style context. ) @@ -1438,7 +1493,8 @@ item(tt(vcs_info_hookadd))( Statically registers a number of functions to a given hook. The hook needs to be given as the first argument; what follows is a list of hook-function names to register to the hook. The `tt(+vi-)' prefix needs to be left out -here. See bf(Hooks in vcs_info) below for details. +here. See ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) +below for details. ) findex(vcs_info_hookdel) item(tt(vcs_info_hookdel))( @@ -1447,8 +1503,9 @@ first non-option argument; what follows is a list of hook-function names to un-register from the hook. If `tt(-a)' is used as the first argument, tt(all) occurrences of the functions are unregistered. Otherwise only the last occurrence is removed (if a function was registered to a hook -more than once) . The `tt(+vi-)' prefix needs to be left out here. See -bf(Hooks in vcs_info) below for details. +more than once). The `tt(+vi-)' prefix needs to be left out here. +See ifzman(bf(Hooks in vcs_info))ifnzman(noderef(vcs_info Hooks)) +below for details. ) findex(vcs_info_lastmsg) item(tt(vcs_info_lastmsg))( @@ -1473,6 +1530,7 @@ enditem() All functions named tt(VCS_INFO_*) are for internal use only. +texinode(vcs_info Variables)(vcs_info Hooks)(vcs_info API)(Version Control Information) subsect(Variable Description) startitem() @@ -1490,6 +1548,7 @@ enditem() All variables named tt(VCS_INFO_*) are for internal use only. +texinode(vcs_info Hooks)(vcs_info Examples)(vcs_info Variables)(Version Control Information) subsect(Hooks in vcs_info) Hooks are places in tt(vcs_info) where you can run your own code. That @@ -1597,10 +1656,11 @@ so far in the opposite order, which means that the first argument is the top-most patch and so forth. When setting tt(ret) to non-zero, the string in -tt(${hook_com[applied-string]}) will be used in the tt(%m) escape in -tt(formats) and tt(actionformats); it will be available in the global -tt(backend_misc) array as tt($backend_misc[patches]}); and it will be +tt(${hook_com[applied-string]}) will be available as tt(%p) in the tt(patch-format) and tt(nopatch-format) styles. +This hook is, in concert with tt(set-patch-format), responsible for +tt(%)-escaping that value for use in the prompt. +(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) ) item(tt(gen-unapplied-string))( Called in the tt(git) (with tt(stgit) or during rebase), and tt(hg) (with @@ -1614,6 +1674,9 @@ the patch next-in-line to be applied and so forth. When setting tt(ret) to non-zero, the string in tt(${hook_com[unapplied-string]}) will be available as tt(%u) in the tt(patch-format) and tt(nopatch-format) styles. +This hook is, in concert with tt(set-patch-format), responsible for +tt(%)-escaping that value for use in the prompt. +(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) ) item(tt(gen-mqguards-string))( Called in the tt(hg) backend when tt(guards-string) is generated; the @@ -1691,6 +1754,11 @@ controllable in addition to that. If tt(ret) is set to non-zero, the string in tt(${hook_com[patch-replace]}) will be used unchanged instead of an expanded format from tt(patch-format) or tt(nopatch-format). + +This hook is, in concert with the tt(gen-applied-string) or +tt(gen-unapplied-string) hooks if they are defined, responsible for +tt(%)-escaping the final tt(patch-format) value for use in the prompt. +(See ifzman(the bf(Oddities) section)ifnzman(noderef(vcs_info Oddities)).) ) item(tt(set-message))( Called each time before a `tt(vcs_info_msg_)var(N)tt(_)' message is set. @@ -1719,10 +1787,12 @@ tt(vcs_info). ) enditem() -If all of this sounds rather confusing, take a look at the bf(Examples) -section below and also in the tt(Misc/vcs_info-examples) file in the Zsh source. +If all of this sounds rather confusing, take a look at +ifzman(the bf(Examples) section below)ifnzman(noderef(vcs_info Examples)) +and also in the tt(Misc/vcs_info-examples) file in the Zsh source. They contain some explanatory code. +texinode(vcs_info Examples)()(vcs_info Hooks)(Version Control Information) subsect(Examples) Don't use tt(vcs_info) at all (even though it's in your prompt): @@ -1850,8 +1920,9 @@ subsect(Installation) You should make sure all the functions from the tt(Functions/Prompts) directory of the source distribution are available; they all begin with the string `tt(prompt_)' except for the special function`tt(promptinit)'. -You also need the `tt(colors)' function from tt(Functions/Misc). All of -these functions may already have been installed on your system; if not, +You also need the `tt(colors)' and `tt(add-zsh-hook)' functions from +tt(Functions/Misc). +All these functions may already be installed on your system; if not, you will need to find them and copy them. The directory should appear as one of the elements of the tt(fpath) array (this should already be the case if they were installed), and at least the function tt(promptinit) @@ -1905,6 +1976,75 @@ normally call a theme's setup function directly. ) enditem() +subsect(Utility Themes) + +startitem() +item(tt(prompt off))( +The theme `tt(off)' sets all the prompt variables to minimal values with +no special effects. +) +item(tt(prompt default))( +The theme `tt(default)' sets all prompt variables to the same state as +if an interactive zsh was started with no initialization files. +) +item(tt(prompt restore))( +The special theme `tt(restore)' erases all theme settings and sets prompt +variables to their state before the first time the `tt(prompt)' function +was run, provided each theme has properly defined its cleanup (see below). + +Note that you can undo `tt(prompt off)' and `tt(prompt default)' with +`tt(prompt restore)', but a second restore does not undo the first. +) +enditem() + +subsect(Writing Themes) + +The first step for adding your own theme is to choose a name for it, +and create a file `tt(prompt_var(name)_setup)' in a directory in your +tt(fpath), such as tt(~/myfns) in the example above. The file should +at minimum contain assignments for the prompt variables that your +theme wishes to modify. By convention, themes use tt(PS1), tt(PS2), +tt(RPS1), etc., rather than the longer tt(PROMPT) and tt(RPROMPT). + +The file is autoloaded as a function in the current shell context, so +it may contain any necessary commands to customize your theme, including +defining additional functions. To make some complex tasks easier, your +setup function may also do any of the following: + +startitem() +item(Assign tt(prompt_opts))( +The array tt(prompt_opts) may be assigned any of tt("bang"), tt("cr"), +tt("percent"), tt("sp"), and/or tt("subst") as values. The corresponding +setopts (tt(promptbang), etc.) are turned on, all other prompt-related +options are turned off. The tt(prompt_opts) array preserves setopts even +beyond the scope of tt(localoptions), should your function need that. +) +item(Modify precmd and preexec)( +Use of tt(add-zsh-hook) is recommended. The tt(precmd) and tt(preexec) +hooks are automatically adjusted if the prompt theme changes or is +disabled. +) +item(Declare cleanup)( +If your function makes any other changes that should be undone when the +theme is disabled, your setup function may call +example(prompt_cleanup var(command)) +where var(command) should be suitably quoted. If your theme is ever +disabled or replaced by another, var(command) is executed with tt(eval). +You may declare more than one such cleanup hook. +) +item(Define preview)( +Define or autoload a function tt(prompt_var(name)_preview) to display +a simulated version of your prompt. A simple default previewer is +defined by tt(promptinit) for themes that do not define their own. +This preview function is called by `tt(prompt -p)'. +) +item(Provide help)( +Define or autoload a function tt(prompt_var(name)_help) to display +documentation or help text for your theme. +This help function is called by `tt(prompt -h)'. +) +enditem() + texinode(ZLE Functions)(Exception Handling)(Prompt Themes)(User Contributions) sect(ZLE Functions) |