[plugins] added Linediff

1 files changed, 124 insertions, 0 deletions

diff --git a/doc/linediff.txt b/doc/linediff.txt
new file mode 100644
index 0000000..e6e21ed
--- /dev/null
+++ b/doc/linediff.txt
@@ -0,0 +1,124 @@
+==============================================================================
+CONTENTS                                      *linediff* *linediff-contents*
+
+    Installation...........................: |linediff-installation|
+    Usage..................................: |linediff-usage|
+    Commands...............................: |linediff-commands|
+    Internals..............................: |linediff-internals|
+    Issues.................................: |linediff-issues|
+
+
+==============================================================================
+INSTALLATION                                           *linediff-installation*
+
+There are several ways to install the plugin. The recommended one is by using
+Tim Pope's pathogen (http://www.vim.org/scripts/script.php?script_id=2332). In
+that case, you can clone the plugin's git repository like so:
+>
+    git clone git://github.com/AndrewRadev/linediff.vim.git ~/.vim/bundle/linediff
+<
+If your vim configuration is under git version control, you could also set up
+the repository as a submodule, which would allow you to update more easily.
+The command is (provided you're in ~/.vim):
+>
+    git submodule add git://github.com/AndrewRadev/linediff.vim.git bundle/linediff
+<
+
+Another way is to simply copy all the essential directories inside the ~.vim/
+directory: plugin, autoload, doc.
+
+==============================================================================
+USAGE                                                         *linediff-usage*
+
+The plugin provides a simple command, |:Linediff|, which is used to diff two
+separate blocks of text.
+
+A simple example:
+
+    def one
+      two
+    end
+
+    def two
+      three
+    end
+
+If we mark the first three lines, starting from "def one", in visual mode, and
+execute the |:Linediff| command, the signs "1-" will be placed at the start
+and at the end of the visual mode's range. Doing the same thing on the bottom
+half of the code, starting from "def two", will result in the signs "2-"
+placed there. After that, a new tab will be opened with the two blocks of code
+in vertical splits, diffed against each other.
+
+The two buffers are temporary, but when any one of them is saved, its original
+buffer is updated. Note that this doesn't save the original buffer, just
+performs the change. Saving is something you should do later.
+
+Executing the command |:LinediffReset| will delete the temporary buffers and
+remove the signs.
+
+Executing a new |:Linediff| will do the same as |:LinediffReset|, but will
+also initiate a new diff process.
+
+The statuslines of the two temporary buffers will be changed to contain:
+    - The original buffer
+    - The starting line of the selected segment
+    - The ending line of the selected segment
+
+If you're using a custom statusline and it contains "%f" (the current file's
+name), that token will simply be substituted by the above data. Otherwise, the
+entire statusline will be set to a custom one.
+
+==============================================================================
+COMMANDS                                                   *linediff-commands*
+
+                                              *:Linediff*
+:Linediff         The main interface of the plugin. Needs to be executed on a
+                  range of lines, which will be marked with a sign. On the
+                  selection of the second such range, the command will open a
+                  tab with the two ranges in vertically split windows and
+                  perform a diff on them. Saving one of the two buffers will
+                  automatically update the original buffer the text was taken
+                  from.
+
+                  When executed for a third time, a new line diff is
+                  initiated, and the current process is reset, much like the
+                  effect of |LinediffReset| would be.
+
+
+                                              *:LinediffReset*
+:LinediffReset    Removes the signs denoting the diffed regions and deletes
+                  the temporary buffers, used for the diff. The original
+                  buffers are untouched by this, which means that any updates
+                  to them, performed by the diff process will remain.
+
+==============================================================================
+INTERNALS                                                 *linediff-internals*
+
+When a block of text is diffed with the plugin, a "Differ" object is
+initialized with its relevant data. The differ contains information about the
+buffer number, filetype, start and end lines of the text, and a few other
+things. Almost all functions the plugin uses are scoped to this object in
+order to keep the interface simple. They're located under
+"autoload/linediff/differ.vim" and should be fairly understandable.
+
+Functions that are general-purpose utilities are placed in
+"autoload/linediff/util.vim".
+
+The two differ objects that are required for the two diff buffers are linked
+to each other out of necessity. If they originate from a single buffer,
+updating one would move the lines of the other, so that one would have to be
+updated as well. Apart from that, they have no interaction.
+
+==============================================================================
+ISSUES                                                       *linediff-issues*
+
+You shouldn't linediff two pieces of text that overlap. Not that anything
+horribly bad will happen, it just won't work as you'd hope to. I don't feel
+like it's a very important use case, but if someone requests sensible
+behaviour in that case, I should be able to get it working.
+
+To report any issues or offer suggestions, use the bugtracker of the github
+project at http://github.com/AndrewRadev/linediff.vim/issues
+
+vim:tw=78:sw=4:ft=help:norl: