*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.5

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). It might also help with quickly commenting
out parts of your documents.

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 distribution) 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
  &gt; 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
            ^
<

<LocalLeader>c
        Visual - Wraps the current selection in comment tags and preserves
        existing comments by substituting placeholders. You need to have
        selected text in visual mode before you can use this mapping. See
        |visual-mode| for details. Visual block mode isn't supported yet.

        If you are in visual mode, comment tags will be placed before and after
        your selection. If you are in visual line mode, the comment tags will
        be placed on a new line before and after the selection.

        Note: This mapping might conflict with NERDCommenter or similar
        plugins. This plugin will not override any existing mappings, but you
        might want to disable them if the plugin load order is special. See
        |xml-plugin-settings| for the 'xml_no_comment_map' setting and how to
        use different keys. 

        Given the following XML: >
            <config>
                <!-- Global settings. -->
                <settings>
                    <!-- ignores case -->
                    <ic>true</ic>
                    <!-- shiftwidth -->
                    <sw>4</sw>
                </settings>
            </config>
<
        Example for commenting the "settings" ellement when in visual mode: >
            <config>
                <!-- Global settings. -->
                <!--<settings>
                    <!{1}** ignores case **{1}>
                    <ic>true</ic>
                    <!{1}** shiftwidth **{1}>
                    <sw>4</sw>
                </settings>-->
            </config>
<
        Example for commenting out the config element for the previous XML
        using visual line mode: >
            <!--
            <config>
                <!{1}** Global settings. **{1}>
                <!{1}**<settings>
                    <!{2}** ignores case **{2}>
                    <ic>true</ic>
                    <!{2}** shiftwidth **{2}>
                    <sw>4</sw>
                </settings>**{1}>
            </config>
            -->
<
        Uncommenting will restore the nested comments back to their original
        state.

<LocalLeader>u
        Visual - Removes the comment tags in the current selection and
        restores existing comments by substituting placeholders. You need to
        have selected text in visual mode before you can use this mapping. See
        |visual-mode| for details. Visual block mode isn't supported yet.

        Note: This mapping might conflict with NERDCommenter or similar
        plugins. This plugin will not override any existing mappings, but you
        might want to disable them if the plugin load order is special. See
        |xml-plugin-settings| for the 'xml_no_comment_map' setting and how to
        use different keys. 

------------------------------------------------------------------------------
                                                         *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_no_comment_map
        By default the XML plugin will conditionally map `<LocalLeader>c` and
        `<LocalLeader>u` but that first mapping might conflict with
        plugins like NERDCommenter. To disable the mappings or to define your
        own, place the following (or just the first line) into your .vimrc: >
            let xml_no_comment_map=1
            vmap <LocalLeader>xc <Plug>(XMLEditWrapComment)
            vmap <LocalLeader>xu <Plug>(XMLEditUnwrapComment)
<
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
<