diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/Zsh/contrib.yo | 157 |
1 files changed, 155 insertions, 2 deletions
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo index 819ae6a98..cf1bada4b 100644 --- a/Doc/Zsh/contrib.yo +++ b/Doc/Zsh/contrib.yo @@ -13,6 +13,7 @@ startmenu() menu(Utilities) menu(Prompt Themes) menu(ZLE Functions) +menu(MIME functions) menu(Other Functions) endmenu() @@ -344,7 +345,7 @@ normally call a theme's setup function directly. ) enditem() -texinode(ZLE Functions)(Other Functions)(Prompt Themes)(User Contributions) +texinode(ZLE Functions)(MIME Functions)(Prompt Themes)(User Contributions) sect(ZLE Functions) subsect(Widgets) @@ -955,7 +956,159 @@ whether the tt(widget) style is used. ) enditem() -texinode(Other Functions)()(ZLE Functions)(User Contributions) +texinode(MIME Functions)(Other Functions)(ZLE Functions)(User Contributions) +sect(MIME Functions) + +Three functions are available to provide handling of files recognised by +extension, for example to dispatch a file tt(text.ps) when executed as a +command to an appropriate viewer. + +startitem() +xitem(tt(zsh-mime-setup [-flv])) +item(tt(zsh-mime-handler))( +These two functions use the files tt(~/.mime.types) and tt(/etc/mime.types), +which associate types and extensions, as well as tt(~/.mailcap) and +tt(/etc/mailcap) files, which associate types and the programs that +handle them. These are provided on many systems with the Multimedia +Internet Mail Extensions. + +To enable the system, the function tt(zsh-mime-setup) should be +autoloaded and run. This allows files with extensions to be treated +as executable; such files be completed by the function completion system. +The function tt(zsh-mime-handler) should not need to be called by the +user. + +The system works by setting up suffix aliases with `tt(alias -s)'. +Suffix aliases already installed by the user will not be overwritten. + +Repeated calls to tt(zsh-mime-setup) do not override the existing +mapping between suffixes and executable files unless the option tt(-f) +is given. Note, however, that this does not override existing suffix +aliases assigned to handlers other than tt(zsh-mime-handler). +Calling tt(zsh-mime-setup) with the option tt(-l) lists the existing +mapping without altering it. Calling tt(zsh-mime-setup) with the option +tt(-v) causes verbose output to be shown during the setup operation. + +The system respects the tt(mailcap) flags tt(needsterminal) and +tt(copiousoutput), see manref(mailcap)(4). + +The functions use the following styles, which are defined with the +tt(zstyle) builtin command (\ +ifzman(see zmanref(zshmodules))\ +ifnzman(noderef(The zsh/zutil Module))). They should be defined +before tt(zsh-mime-setup) is run. The contexts used all +start with tt(:mime:), with additional components in some cases. +It is recommended that a trailing tt(*) (suitably quoted) be appended +to style patterns in case the system is extended in future. Some +examples are given below. +startitem() +item(mime-types)( +A list of files in the format of tt(~/.mime.types) and +tt(/etc/mime.types) to be read during setup, replacing the default list +which consists of those two files. The context is tt(:mime:). +) +item(mailcap)( +A list of files in the format of tt(~/.mailcap) and +tt(/etc/mailcap) to be read during setup, replacing the default list +which consists of those two files. The context is tt(:mime:). +) +item(handler)( +Specifies a handler for a suffix; the suffix is given by the context as +tt(:mime:.)var(suffix)tt(:), and the format of the handler is exactly +that in tt(mailcap). Note in particular the `tt(.)' and trailing colon +to distinguish this use of the context. This overrides any handler +specified by the tt(mailcap) files. If the handler requires a terminal, +the tt(flags) style should be set to include the word tt(needsterminal), +or if the output is to be displayed through a pager (but not if the +handler is itself a pager), it should include tt(copiousoutput). +) +item(flags)( +Defines flags to go with a handler; the context is as for the +tt(handler) style, and the format is as for the flags in tt(mailcap). +) +item(pager)( +If set, will be used instead of tt($PAGER) or tt(more) to handle +suffixes where the tt(copiousoutput) flag is set. The context is +as for tt(handler), i.e. tt(:mime:.)var(suffix)tt(:) for handling +a file with the given var(suffix). +) +enditem() + +Examples: + +example(zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap +zstyle ':mime:.txt' handler less %s +zstyle ':mime:.txt' flags needsterminal) + +When tt(zsh-mime-setup) is subsequently run, it will look for +tt(mailcap) entries in the two files given. Files of suffix tt(.txt) +will be handled by running `tt(less) var(file.txt)'. The flag +tt(needsterminal) is set to show that this program must run attached to a +terminal. + +As there are several steps to dispatching a command, the following +should be checked if attempting to execute a file by extension +tt(.)var(ext) does not have the expected effect. +starteit() +eit()( +The command `tt(alias -s) var(ext)' should show +`tt(ps=zsh-mime-handler)'. If it shows something else, another suffix +alias was already installed and was not overwritten. If it shows +nothing, no handler was installed: this is most likely because no +handler was found in the tt(.mime.types) and tt(mailcap) combination for +tt(.ext) files. In that case, appropriate handling should be added to +tt(~/.mime.types) and tt(mailcap). +) +eit()( +If the extension is handled by tt(zsh-mime-handler) but the file is +not opened correctly, either the handler defined for the type is +incorrect, or the flags associated with it are in appropriate. Running +tt(zsh-mime-setup -l) will show the handler and, if there are any, the +flags. A tt(%s) in the handler is replaced by the file (suitably quoted +if necessary). Check that the handler program listed lists and can +be run in the way shown. Also check that the flags tt(needsterminal) or +tt(copiousoutput) are set if the handler needs to be run under a +terminal; the second flag is used if the output should be sent to a pager. +An example of a suitable tt(mailcap) entry for such a program is: + +example(text/html; /usr/bin/lynx '%s'; needsterminal) +) +endeit() +) +item(tt(pick-web-browser))( +This function is separate from the two MIME functions described above +and can be assigned directly to a suffix: + +example(autoload -U pick-web-browser +alias -s html=pick-web-browser) + +It is provided as an intelligent front end to dispatch a web browser. +It will check if an X Windows display is available, and if so +if there is already a browser running which can accept a remote +connection. In that case, the file will be displayed in that browser; +you should check explicitly if it has appeared in the running browser's +window. Otherwise, it will start a new browser according to a builtin +set of preferences. + +Alternatively, tt(pick-web-browser) can be run as a zsh script. + +Two styles are available to customize the choice of browsers: +tt(x-browsers) when running under the X Windows System, and +tt(tty-browsers) otherwise. These are arrays in decreasing order +of preference consiting of the command name under which to start the +browser. They are looked up in the context tt(:mime:) (which may +be extended in future, so appending `tt(*)' is recommended). For +example, + +example(zstyle ':mime:*' x-browsers opera konqueror netscape) + +specifies that tt(pick-web-browser) should first look for a runing +instance of Opera, Konqueror or Netscape, in that order, and if it +fails to find any should attempt to start Opera. +) +enditem() + +texinode(Other Functions)()(MIME Functions)(User Contributions) sect(Other Functions) There are a large number of helpful functions in the tt(Functions/Misc) |