From 3dffb26ff1fe27a4a1bb2e10abc46449ae17e4b5 Mon Sep 17 00:00:00 2001
From: Peter Odding <peter@peterodding.com>
Date: Sun, 19 May 2013 23:36:02 +0200
Subject: Apply hard wrapping to README.md
---
README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++-----------------
1 file changed, 68 insertions(+), 25 deletions(-)
diff --git a/README.md b/README.md
index 685d9c6..97d64b5 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,96 @@
# Miscellaneous auto-load Vim scripts
-The git repository at [github.com/xolox/vim-misc] [repository] contains Vim scripts that are used by most of the [Vim plug-ins I've written] [plugins] yet don't really belong with any single one of the plug-ins. Basically it's an extended standard library of Vim script functions that I wrote during the development of my Vim plug-ins.
+The git repository at [github.com/xolox/vim-misc] [repository] contains Vim
+scripts that are used by most of the [Vim plug-ins I've written] [plugins] yet
+don't really belong with any single one of the plug-ins. Basically it's an
+extended standard library of Vim script functions that I wrote during the
+development of my Vim plug-ins.
-The miscellaneous scripts are bundled with each of my plug-ins using git merges, so that a repository checkout of a plug-in contains everything that's needed to get started. This means the git repository of the miscellaneous scripts is only used to track changes in a central, public place.
+The miscellaneous scripts are bundled with each of my plug-ins using git
+merges, so that a repository checkout of a plug-in contains everything that's
+needed to get started. This means the git repository of the miscellaneous
+scripts is only used to track changes in a central, public place.
## How does it work?
Here's how I merge the miscellaneous scripts into a Vim plug-in repository:
-1. Let git know about the `vim-misc` repository by adding the remote GitHub repository:
+1. Let git know about the `vim-misc` repository by adding the remote GitHub
+ repository:
git remote add -f vim-misc https://github.com/xolox/vim-misc.git
-2. Merge the two directory trees without clobbering the `README.md` and/or `.gitignore` files, thanks to the selected merge strategy and options:
+2. Merge the two directory trees without clobbering the `README.md` and/or
+ `.gitignore` files, thanks to the selected merge strategy and options:
git checkout master
git merge --no-commit -s recursive -X ours vim-misc/master
git commit -m "Merge vim-misc repository as overlay"
-3. While steps 1 and 2 need to be done only once for a given repository, the following commands are needed every time I want to pull and merge the latest changes:
+3. While steps 1 and 2 need to be done only once for a given repository, the
+ following commands are needed every time I want to pull and merge the latest
+ changes:
git checkout master
git fetch vim-misc master
git merge --no-commit -s recursive -X ours vim-misc/master
git commit -m "Merged changes to miscellaneous scripts"
-## Why make things so complex?
-
-I came up with this solution after multiple years of back and forth between Vim Online users, the GitHub crowd and my own sanity:
-
-1. When I started publishing my first Vim plug-ins (in June 2010) I would prepare ZIP archives for Vim Online using makefiles. The makefiles would make sure the miscellaneous scripts were included in the uploaded distributions. This had two disadvantages: It lost git history and the repositories on GitHub were not usable out of the box, so [I got complaints from GitHub (Pathogen) users] [github-complaints].
-
-2. My second attempt to solve the problem used git submodules which seemed like the ideal solution until I actually started using them in March 2011: Submodules are not initialized during a normal `git clone`, you need to use `git clone --recursive` instead but Vim plug-in managers like [Pathogen] [pathogen] and [Vundle] [vundle] don't do this (at least [they didn't when I tried] [vundle-discussion]) so people would end up with broken checkouts.
-
-3. After finding out that git submodules were not going to solve my problems I searched for other inclusion strategies supported by git. After a while I came upon the [subtree merge strategy] [merge-strategy] which I started using in May 2011 and stuck with for more than two years (because it generally worked fine and seemed quite robust).
-
-4. In April 2013 the flat layout of the repository started bothering me because it broke my personal workflow, so I changed it to the proper directory layout of a Vim plug-in. Why did it break my workflow? Because I couldn't get my [vim-reload] [reload] plug-in to properly reload miscellaneous scripts without nasty hacks. Note to self: [Dropbox does not respect symbolic links] [dropbox-vote-350] and Vim doesn't like them either ([E746] [E746]).
-
-## Compatibility issues
-
-Regardless of the inclusion strategies discussed above, my current scheme has a flaw: If more than one of my plug-ins are installed in a Vim profile using [Pathogen] [pathogen] or [Vundle] [vundle], the miscellaneous autoload scripts will all be loaded from the subdirectory of one single plug-in.
-
-This means that when I break compatibility in the miscellaneous scripts, I have to make sure to merge the changes into all of my plug-ins. Even then, if a user has more than one of my plug-ins installed but updates only one of them, the other plug-ins (that are not yet up to date) can break (because of the backwards incompatible change).
-
-The `xolox#misc#compat#check()` function makes sure that incompatibilities are detected early so that the user knows which plug-in to update if incompatibilities arise.
+### Why make things so complex?
+
+I came up with this solution after multiple years of back and forth between Vim
+Online users, the GitHub crowd and my own sanity:
+
+1. When I started publishing my first Vim plug-ins (in June 2010) I would
+ prepare ZIP archives for Vim Online using makefiles. The makefiles would
+ make sure the miscellaneous scripts were included in the uploaded
+ distributions. This had two disadvantages: It lost git history and the
+ repositories on GitHub were not usable out of the box, so [I got complaints
+ from GitHub (Pathogen) users] [github-complaints].
+
+2. My second attempt to solve the problem used git submodules which seemed like
+ the ideal solution until I actually started using them in March 2011:
+ Submodules are not initialized during a normal `git clone`, you need to use
+ `git clone --recursive` instead but Vim plug-in managers like [Pathogen]
+ [pathogen] and [Vundle] [vundle] don't do this (at least [they didn't when I
+ tried] [vundle-discussion]) so people would end up with broken checkouts.
+
+3. After finding out that git submodules were not going to solve my problems I
+ searched for other inclusion strategies supported by git. After a while I
+ came upon the [subtree merge strategy] [merge-strategy] which I started
+ using in May 2011 and stuck with for more than two years (because it
+ generally worked fine and seemed quite robust).
+
+4. In April 2013 the flat layout of the repository started bothering me because
+ it broke my personal workflow, so I changed it to the proper directory
+ layout of a Vim plug-in. Why did it break my workflow? Because I couldn't
+ get my [vim-reload] [reload] plug-in to properly reload miscellaneous
+ scripts without nasty hacks. Note to self: [Dropbox does not respect
+ symbolic links] [dropbox-vote-350] and Vim doesn't like them either ([E746]
+ [E746]).
+
+### Compatibility issues
+
+Regardless of the inclusion strategies discussed above, my current scheme has a
+flaw: If more than one of my plug-ins are installed in a Vim profile using
+[Pathogen] [pathogen] or [Vundle] [vundle], the miscellaneous autoload scripts
+will all be loaded from the subdirectory of one single plug-in.
+
+This means that when I break compatibility in the miscellaneous scripts, I have
+to make sure to merge the changes into all of my plug-ins. Even then, if a user
+has more than one of my plug-ins installed but updates only one of them, the
+other plug-ins (that are not yet up to date) can break (because of the
+backwards incompatible change).
+
+The `xolox#misc#compat#check()` function makes sure that incompatibilities are
+detected early so that the user knows which plug-in to update if
+incompatibilities arise.
## Contact
-If you have questions, bug reports, suggestions, etc. the author can be contacted at <peter@peterodding.com>. The latest version is available at <http://peterodding.com/code/vim/misc> and <http://github.com/xolox/vim-misc>.
+If you have questions, bug reports, suggestions, etc. the author can be
+contacted at <peter@peterodding.com>. The latest version is available at
+<http://peterodding.com/code/vim/misc> and <http://github.com/xolox/vim-misc>.
## License
--
cgit v1.2.3