From 51fd5661ecb855d61e7167588bb9122a2add343e Mon Sep 17 00:00:00 2001 From: gryf Date: Sun, 18 Jul 2010 21:53:11 +0200 Subject: [PATCH] Added documentation for surround, changed F5 key assignment and added functions for generating html out of reSt file. --- doc/surround.txt | 222 +++++++++++++++++++++++++++++++++++++++ ftplugin/rst/commons.vim | 91 +++++++++++++++- 2 files changed, 311 insertions(+), 2 deletions(-) create mode 100644 doc/surround.txt diff --git a/doc/surround.txt b/doc/surround.txt new file mode 100644 index 0000000..4387fa2 --- /dev/null +++ b/doc/surround.txt @@ -0,0 +1,222 @@ +*surround.txt* Plugin for deleting, changing, and adding "surroundings" + +Author: Tim Pope *surround-author* +License: Same terms as Vim itself (see |license|) + +This plugin is only available if 'compatible' is not set. + +INTRODUCTION *surround* + +This plugin is a tool for dealing with pairs of "surroundings." Examples +of surroundings include parentheses, quotes, and HTML tags. They are +closely related to what Vim refers to as |text-objects|. Provided +are mappings to allow for removing, changing, and adding surroundings. + +Details follow on the exact semantics, but first, consider the following +examples. An asterisk (*) is used to denote the cursor position. + + Old text Command New text ~ + "Hello *world!" ds" Hello world! + [123+4*56]/2 cs]) (123+456)/2 + "Look ma, I'm *HTML!" cs" Look ma, I'm HTML! + if *x>3 { ysW( if ( x>3 ) { + my $str = *whee!; vlllls' my $str = 'whee!'; + +While a few features of this plugin will work in older versions of Vim, +Vim 7 is recommended for full functionality. + +MAPPINGS *surround-mappings* + +Delete surroundings is *ds* . The next character given determines the target +to delete. The exact nature of the target is explained in |surround-targets| +but essentially it is the last character of a |text-object|. This mapping +deletes the difference between the "i"nner object and "a"n object. This is +easiest to understand with some examples: + + Old text Command New text ~ + "Hello *world!" ds" Hello world! + (123+4*56)/2 ds) 123+456/2 +
Yo!*
dst Yo! + +Change surroundings is *cs* . It takes two arguments, a target like with +|ds|, and a replacement. Details about the second argument can be found +below in |surround-replacements|. Once again, examples are in order. + + Old text Command New text ~ + "Hello *world!" cs"' 'Hello world!' + "Hello *world!" cs" Hello world! + (123+4*56)/2 cs)] [123+456]/2 + (123+4*56)/2 cs)[ [ 123+456 ]/2 +
Yo!*
cst

Yo!

+ +*ys* takes a valid Vim motion or text object as the first object, and wraps +it using the second argument as with |cs|. (Unfortunately there's no good +mnemonic for "ys".) + + Old text Command New text ~ + Hello w*orld! ysiw) Hello (world)! + +As a special case, *yss* operates on the current line, ignoring leading +whitespace. + + Old text Command New text ~ + Hello w*orld! yssB {Hello world!} + +There is also *yS* and *ySS* which indent the surrounded text and place it +on a line of its own. + +In visual mode, a simple "s" with an argument wraps the selection. This is +referred to as the *vS* mapping, although ordinarily there will be +additional keystrokes between the v and s. In linewise visual mode, the +surroundings are placed on separate lines and indented. In blockwise visual +mode, each line is surrounded. + +A "gS" in visual mode, known as *vgS* , behaves similarly. In linewise visual +mode, the automatic indenting is surpressed. In blockwise visual mode, this +enables surrounding past the end of the like with 'virtualedit' set (there +seems to be no way in Vim Script to differentiate between a jagged end of line +selection and a virtual block selected past the end of the line, so two maps +were needed). + +Additionally, there is a legacy "s" or *vs* mapping which is basically the +same as |vS|. Due to popular demand of wanting to use "s" as Vim does to mean +replacing the selection (also available as "c"), this mapping is going away. +If you were one of these people and would like to disable "s" with the current +release, indicate this to surround.vim by assigning the "s" mapping to +something else. +> + xmap s Vsurround +< + *i_CTRL-G_s* *i_CTRL-G_S* +Finally, there is an experimental insert mode mapping on s and . +Beware that the latter won't work on terminals with flow control (if you +accidentally freeze your terminal, use to unfreeze it). The mapping +inserts the specified surroundings and puts the cursor between them. If, +immediately after the mapping and before the replacement, a second or +carriage return is pressed, the prefix, cursor, and suffix will be placed on +three separate lines. S (not s) also exhibits this behavior. + +TARGETS *surround-targets* + +The |ds| and |cs| commands both take a target as their first argument. The +possible targets are based closely on the |text-objects| provided by Vim. +In order for a target to work, the corresponding text object must be +supported in the version of Vim used (Vim 7 adds several text objects, and +thus is highly recommended). All targets are currently just one character. + +Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves +and their counterparts. If the opening mark is used, contained whitespace is +also trimmed. The targets b, B, r, and a are aliases for ), }, ], and > +(the first two mirror Vim; the second two are completely arbitrary and +subject to change). + +Three quote marks, ', ", `, represent themselves, in pairs. They are only +searched for on the current line. + +A t is a pair of HTML or XML tags. See |tag-blocks| for details. Remember +that you can specify a numerical argument if you want to get to a tag other +than the innermost one. + +The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|, +respectively. These are special in that they have nothing to delete, and +used with |ds| they are a no-op. With |cs|, one could consider them a +slight shortcut for ysi (cswb == ysiwb, more or less). + +A p represents a |paragraph|. This behaves similarly to w, W, and s above; +however, newlines are sometimes added and/or removed. + +REPLACEMENTS *surround-replacements* + +A replacement argument is a single character, and is required by |cs|, |ys|, +and |vs|. Undefined replacement characters (with the exception of alphabetic +characters) default to placing themselves at the beginning and end of the +destination, which can be useful for characters like / and |. + +If either ), }, ], or > is used, the text is wrapped in the appropriate pair +of characters. Similar behavior can be found with (, {, and [ (but not <), +which append an additional space to the inside. Like with the targets above, +b, B, r, and a are aliases for ), }, ], and >. To fulfill the common need for +code blocks in C-style languages, (which is really ) adds braces on +lines separate from the content. + +If t or < is used, Vim prompts for an HTML/XML tag to insert. You may specify +attributes here and they will be stripped from the closing tag. End your +input by pressing or >. If is used, the tags will appear on lines +by themselves. + +A deprecated replacement of a LaTeX environment is provided on \ and l. The +name of the environment and any arguments will be input from a prompt. This +will be removed once a more fully functional customization system is +implemented. The following shows the resulting environment from +csp\tabular}{lc +> + \begin{tabular}{lc} + \end{tabular} +< +CUSTOMIZING *surround-customizing* + +The following adds a potential replacement on "-" (ASCII 45) in PHP files. +(To determine the ASCII code to use, :echo char2nr("-")). The carriage +return will be replaced by the original text. +> + autocmd FileType php let b:surround_45 = "" +< +This can be used in a PHP file as in the following example. + + Old text Command New text ~ + print "Hello *world!" yss- + +Additionally, one can use a global variable for globally available +replacements. +> + let g:surround_45 = "<% \r %>" + let g:surround_61 = "<%= \r %>" +< +Advanced, experimental, and subject to change: One can also prompt for +replacement text. The syntax for this is to surround the replacement in pairs +of low numbered control characters. If this sounds confusing, that's because +it is (but it makes the parsing easy). Consider the following example for a +LaTeX environment on the "l" replacement. +> + let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\1}" +< +When this replacement is used, the user is prompted with an "environment: " +prompt for input. This input is inserted between each set of \1's. +Additional inputs up to \7 can be used. + +Furthermore, one can specify a regular expression substitution to apply. +> + let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\r}.*\r\1}" +< +This will remove anything after the first } in the input when the text is +placed within the \end{} slot. The first \r marks where the pattern begins, +and the second where the replacement text begins. + +Here's a second example for creating an HTML
. The substitution cleverly +prompts for an id, but only adds id="" if it is non-blank. You may have to +read this one a few times slowly before you understand it. +> + let g:surround_{char2nr("d")} = "\r
" +< +Inputting text replacements is a proof of concept at this point. The ugly, +unintuitive interface and the brevity of the documentation reflect this. + +Finally, It is possible to always append a string to surroundings in insert +mode (and only insert mode). This is useful with certain plugins and mappings +that allow you to jump to such markings. +> + let g:surround_insert_tail = "<++>" +< +ISSUES *surround-issues* + +Vim could potentially get confused when deleting/changing occurs at the very +end of the line. Please report any repeatable instances of this. + +Do we need to use |inputsave()|/|inputrestore()| with the tag replacement? + +Indenting is handled haphazardly. Need to decide the most appropriate +behavior and implement it. Right now one can do :let b:surround_indent = 1 +(or the global equivalent) to enable automatic re-indenting by Vim via |=|; +should this be the default? + + vim:tw=78:ts=8:ft=help:norl: diff --git a/ftplugin/rst/commons.vim b/ftplugin/rst/commons.vim index dca77d4..6efdd62 100644 --- a/ftplugin/rst/commons.vim +++ b/ftplugin/rst/commons.vim @@ -1,4 +1,91 @@ +" Some common settings for all reSt files set textwidth=80 -set formatoptions+=tn set makeprg=rst2html.py\ %\ %.html -map :make +set spell +set smartindent +set autoindent +set formatoptions+=w + +map :call Rst2Blogger() + +" Simple function, that translates reSt text into html with specified format, +" suitable to copy and paste into blogger post. +fun! Rst2Blogger() +python << EOF +from docutils import core +from docutils.writers.html4css1 import Writer, HTMLTranslator +import vim + +class NoHeaderHTMLTranslator(HTMLTranslator): + def __init__(self, document): + HTMLTranslator.__init__(self,document) + self.head_prefix = ['','','','',''] + self.body_prefix = [] + self.body_suffix = [] + self.stylesheet = [] + self.head = [] + self.meta = [] + self.generator = ('') + self.initial_header_level = 2 + self.section_level = 2 + + def visit_document(self, node): + pass + + def depart_document(self, node): + pass + + def visit_section(self, node): + pass + + def depart_section(self, node): + pass + +_w = Writer() +_w.translator_class = NoHeaderHTMLTranslator + +def blogify(string): + return core.publish_string(string,writer=_w) + +bufcontent = "\n".join(vim.current.buffer) +name = vim.current.buffer.name +if name.lower().endswith(".rst"): + name = name[:-4] + ".html" + vim.command('new') + + vim.current.buffer[:] = blogify(bufcontent).split("\n") + vim.command('saveas %s' % name) + vim.command('bd') +else: + print "This is not reSt file. File should have '.rst' extension." + +EOF +endfun + +" This is similar to that above, but creates full html document +fun! Restify() +python << EOF +from docutils import core +from docutils.writers.html4css1 import Writer, HTMLTranslator +import vim + +_w = Writer() +_w.translator_class = HTMLTranslator + +def reSTify(string): + return core.publish_string(string,writer=_w) + +bufcontent = "\n".join(vim.current.buffer) +name = vim.current.buffer.name +if name.lower().endswith(".rst"): + name = name[:-4] + ".html" + vim.command('new') + + vim.current.buffer[:] = reSTify(bufcontent).split("\n") + vim.command('saveas %s' % name) + vim.command('bd') +else: + print 'To nie jest plik reSt!' + +EOF +endfun