270 lines
11 KiB
Plaintext
270 lines
11 KiB
Plaintext
*xml-plugin.txt* Help edit XML and SGML documents. #version#
|
|
|
|
XML Edit
|
|
|
|
A filetype plugin to help edit XML and SGML documents.
|
|
|
|
Version: 1.10.4
|
|
|
|
This script provides some convenience when editing XML (and some SGML
|
|
including HTML) formated documents. It allows you to jump to the beginning
|
|
or end of the tag block your cursor is in. '%' will jump between '<' and '>'
|
|
within the tag your cursor is in. When in insert mode and you finish a tag
|
|
(pressing '>') the tag will be completed. If you press '>' twice it will
|
|
complete the tag and place the cursor in the middle of the tags on it's own
|
|
line (helps with nested tags).
|
|
|
|
Usage: Place this file into your ftplugin directory. To add html support
|
|
Sym-link or copy this file to html.vim in your ftplugin directory. To activate
|
|
the script place 'filetype plugin on' in your |.vimrc| file. See |ftplugins|
|
|
for more information on this topic.
|
|
|
|
If the file edited is of type "html" and "xml_use_html" is defined then the
|
|
following tags will not auto complete:
|
|
<img>, <input>, <param>, <frame>, <br>, <hr>, <meta>, <link>, <base>, <area>
|
|
|
|
If the file edited is of type 'html' and 'xml_use_xhtml' is defined the above
|
|
tags will autocomplete the xml closing staying xhtml compatible.
|
|
ex. <hr> becomes <hr /> (see |xml-plugin-settings|)
|
|
|
|
NOTE: If you used the VIM 5.x version of this file (xmledit.vim) you'll need
|
|
to comment out the section where you called it. It is no longer used in the
|
|
VIM 6.x version.
|
|
|
|
To disable the plugin (especially for systems that include this plugin as part
|
|
of the distrobution) you can use the following line in your .vimrc:
|
|
>
|
|
let loaded_xmledit = 1
|
|
<
|
|
Known Bugs
|
|
|
|
- This script will modify registers ". and "x; register "" will be restored.
|
|
- < & > marks inside of a CDATA section are interpreted as actual XML tags
|
|
even if unmatched.
|
|
- Although the script can handle leading spaces such as < tag></ tag> it is
|
|
illegal XML syntax and considered very bad form.
|
|
- Placing a literal `>' in an attribute value will auto complete despite that
|
|
the start tag isn't finished. This is poor XML anyway you should use
|
|
> instead.
|
|
- The matching algorithm can handle illegal tag characters where as the tag
|
|
completion algorithm can not.
|
|
|
|
------------------------------------------------------------------------------
|
|
*xml-plugin-mappings*
|
|
Mappings
|
|
|
|
<LocalLeader> is a setting in VIM that depicts a prefix for scripts and
|
|
plugins to use. By default this is the backslash key `\'. See |mapleader|
|
|
for details.
|
|
|
|
<LocalLeader><Space>
|
|
Normal or Insert - Continue editing after the ending tag. This
|
|
option requires xml_jump_string to be set to function. When a tag
|
|
is completed it will append the xml_jump_string. Once this mapping
|
|
is ran it will delete the next xml_jump_string pattern to the right
|
|
of the curser and delete it leaving you in insert mode to continue
|
|
editing.
|
|
|
|
<LocalLeader>w
|
|
Normal - Will clear the entire file of left over xml_jump_string garbage.
|
|
* This will also happen automatically when you save the file. *
|
|
|
|
<LocalLeader>x
|
|
Visual - Place a custom XML tag to suround the selected text. You
|
|
need to have selected text in visual mode before you can use this
|
|
mapping. See |visual-mode| for details.
|
|
|
|
<LocalLeader>. or <LocalLeader>>
|
|
Insert - Place a literal '>' without parsing tag.
|
|
|
|
<LocalLeader>5 or <LocalLeader>%
|
|
Normal or Visual - Jump to the beginning or end tag.
|
|
|
|
<LocalLeader>d
|
|
Normal - Deletes the surrounding tags from the cursor. >
|
|
<tag1>outter <tag2>inner text</tag2> text</tag1>
|
|
^
|
|
< Turns to: >
|
|
outter <tag2>inner text</tag2> text
|
|
^
|
|
<
|
|
|
|
------------------------------------------------------------------------------
|
|
*xml-plugin-settings*
|
|
Options
|
|
|
|
(All options must be placed in your |.vimrc| prior to the |ftplugin|
|
|
command.)
|
|
|
|
xml_tag_completion_map
|
|
Use this setting to change the default mapping to auto complete a
|
|
tag. By default typing a literal `>' will cause the tag your editing
|
|
to auto complete; pressing twice will auto nest the tag. By using
|
|
this setting the `>' will be a literal `>' and you must use the new
|
|
mapping to perform auto completion and auto nesting. For example if
|
|
you wanted Control-L to perform auto completion instead of typing a
|
|
`>' place the following into your .vimrc: >
|
|
let xml_tag_completion_map = "<C-l>"
|
|
<
|
|
xml_tag_syntax_prefixes
|
|
Sets a pattern that is used to distinguish XML syntax elements that
|
|
identify xml tags. By default the value is 'html\|xml\|docbk'. This
|
|
means that all syntax items that start with "html", "xml" or "docbk" are
|
|
treated as XML tags. In case a completion is triggered after a syntax
|
|
element that does not match this pattern the end tag will not be inserted.
|
|
The pattern should match at the beginning of a syntax element name.
|
|
If you edit XSLT files you probably want to add "xsl" to the list (note
|
|
the single quotes): >
|
|
let xml_tag_syntax_prefixes = 'html\|xml\|xsl\|docbk'
|
|
<
|
|
xml_no_auto_nesting
|
|
This turns off the auto nesting feature. After a completion is made
|
|
and another `>' is typed xml-edit automatically will break the tag
|
|
accross multiple lines and indent the curser to make creating nested
|
|
tqags easier. This feature turns it off. Enter the following in your
|
|
.vimrc: >
|
|
let xml_no_auto_nesting = 1
|
|
<
|
|
xml_use_xhtml
|
|
When editing HTML this will auto close the short tags to make valid
|
|
XML like <hr /> and <br />. Enter the following in your vimrc to
|
|
turn this option on: >
|
|
let xml_use_xhtml = 1
|
|
<
|
|
xml_no_html
|
|
This turns off the support for HTML specific tags. Place this in your
|
|
.vimrc: >
|
|
let xml_no_html = 1
|
|
<
|
|
xml_jump_string
|
|
This turns off the support for continuing edits after an ending tag.
|
|
xml_jump_string can be any string how ever a simple character will
|
|
suffice. Pick a character or small string that is unique and will
|
|
not interfer with your normal editing. See the <LocalLeader>Space
|
|
mapping for more.
|
|
.vimrc: >
|
|
let xml_jump_string = "`"
|
|
<
|
|
------------------------------------------------------------------------------
|
|
Using With Other File Types *xml-plugin-filetypes*
|
|
|
|
This can be used with other file types besides XML. There are two ways to
|
|
accomplish this. The plugin can be used as is for other languages or with extra
|
|
features that are language specific via the callback method.
|
|
See |xml-plugin-callbacks| for more info.
|
|
|
|
The first method is simply to copy xml.vim or symbolically (or hard) link it
|
|
to the new file type. For example:
|
|
>
|
|
ftplugin/
|
|
|-xml.vim
|
|
|-php.vim -> xml.vim
|
|
`-xhtml.vim -> xml.vim
|
|
<
|
|
The second method expands on the idea of copying. It uses a callback method
|
|
which can extend the functionality of the tags for that language. For example
|
|
in an HTML document you might prefer your table tags to look like this:
|
|
>
|
|
<table cellpadding="0" cellspacing="0" border="0">
|
|
</table>
|
|
<
|
|
But by just linking html.vim to xml.vim you would have to type all that in
|
|
every time. The callback could allow you to type just <table> and it would add
|
|
the attributes for you. The example in |xml-plugin-html| shows how to do this
|
|
with HTML files.
|
|
------------------------------------------------------------------------------
|
|
*xml-plugin-callbacks*
|
|
Callback Functions
|
|
|
|
A callback function is a function used to customize features on a per tag
|
|
basis. For example say you wish to have a default set of attributes when you
|
|
type an empty tag like this:
|
|
You type: <tag>
|
|
You get: <tag default="attributes"></tag>
|
|
|
|
This is for any script programmers who wish to add xml-plugin support to
|
|
there own filetype plugins.
|
|
|
|
Callback functions receive one attribute variable which is the tag name. The
|
|
all must return either a string or the number zero. If it returns a string
|
|
the plugin will place the string in the proper location. If it is a zero the
|
|
plugin will ignore and continue as if no callback existed.
|
|
|
|
The following are implemented callback functions:
|
|
|
|
HtmlAttribCallback
|
|
This is used to add default attributes to html tag. It is intended
|
|
for HTML files only.
|
|
|
|
XmlAttribCallback
|
|
This is a generic callback for xml tags intended to add attributes.
|
|
|
|
*xml-plugin-html*
|
|
Callback Example
|
|
|
|
The following is an example of using XmlAttribCallback in your .vimrc
|
|
>
|
|
function XmlAttribCallback (xml_tag)
|
|
if a:xml_tag ==? "my-xml-tag"
|
|
return "attributes=\"my xml attributes\""
|
|
else
|
|
return 0
|
|
endif
|
|
endfunction
|
|
<
|
|
The following is a sample html.vim file type plugin you could use:
|
|
>
|
|
" Vim script file vim600:fdm=marker:
|
|
" FileType: HTML
|
|
" Maintainer: Devin Weaver <vim (at) tritarget.com>
|
|
" Location: http://www.vim.org/scripts/script.php?script_id=301
|
|
|
|
" This is a wrapper script to add extra html support to xml documents.
|
|
" Original script can be seen in xml-plugin documentation.
|
|
|
|
" Only do this when not done yet for this buffer
|
|
if exists("b:did_ftplugin")
|
|
finish
|
|
endif
|
|
" Don't set 'b:did_ftplugin = 1' because that is xml.vim's responsibility.
|
|
|
|
let b:html_mode = 1
|
|
|
|
if !exists("*HtmlAttribCallback")
|
|
function HtmlAttribCallback( xml_tag )
|
|
if a:xml_tag ==? "table"
|
|
return "cellpadding=\"0\" cellspacing=\"0\" border=\"0\""
|
|
elseif a:xml_tag ==? "link"
|
|
return "href=\"/site.css\" rel=\"StyleSheet\" type=\"text/css\""
|
|
elseif a:xml_tag ==? "body"
|
|
return "bgcolor=\"white\""
|
|
elseif a:xml_tag ==? "frame"
|
|
return "name=\"NAME\" src=\"/\" scrolling=\"auto\" noresize"
|
|
elseif a:xml_tag ==? "frameset"
|
|
return "rows=\"0,*\" cols=\"*,0\" border=\"0\""
|
|
elseif a:xml_tag ==? "img"
|
|
return "src=\"\" width=\"0\" height=\"0\" border=\"0\" alt=\"\""
|
|
elseif a:xml_tag ==? "a"
|
|
if has("browse")
|
|
" Look up a file to fill the href. Used in local relative file
|
|
" links. typeing your own href before closing the tag with `>'
|
|
" will override this.
|
|
let cwd = getcwd()
|
|
let cwd = substitute (cwd, "\\", "/", "g")
|
|
let href = browse (0, "Link to href...", getcwd(), "")
|
|
let href = substitute (href, cwd . "/", "", "")
|
|
let href = substitute (href, " ", "%20", "g")
|
|
else
|
|
let href = ""
|
|
endif
|
|
return "href=\"" . href . "\""
|
|
else
|
|
return 0
|
|
endif
|
|
endfunction
|
|
endif
|
|
|
|
" On to loading xml.vim
|
|
runtime ftplugin/xml.vim
|
|
<
|