Update Loupe fixtures
authorGreg Hurrell <greg@hurrell.net>
Mon, 13 Jun 2016 14:20:15 +0000 (07:20 -0700)
committerGreg Hurrell <greg@hurrell.net>
Mon, 13 Jun 2016 14:20:15 +0000 (07:20 -0700)
tests/fixtures/integration/loupe/golden/ast.golden
tests/fixtures/integration/loupe/golden/markdown.golden
tests/fixtures/integration/loupe/golden/plaintext.golden
tests/fixtures/integration/loupe/input/autoload/loupe/private.vim
tests/fixtures/integration/loupe/input/plugin/loupe.vim

index b50fb6cff1ba250d23deced0810acec54aa60832..ba376076976241b80fd1c8293974efd6fe309657 100644 (file)
 Project
-  [ Project
+  [ DocBlock
+      [ PluginAnnotation "loupe" "Loupe plug-in for Vim"
+      , TOC
+          [ "Intro"
+          , "Installation"
+          , "Overrides"
+          , "Related"
+          , "Website"
+          , "License"
+          , "Development"
+          , "Authors"
+          , "History"
+          , "Mappings"
+          , "Options"
+          ]
+      ]
+  , HeadingAnnotation "Intro"
+  , Blockquote
+      [ Paragraph
+          [ Plaintext "\"loupe"
+          , Whitespace
+          , Plaintext "(noun)"
+          , BreakTag
+          , Plaintext "a"
+          , Whitespace
+          , Plaintext "small"
+          , Whitespace
+          , Plaintext "magnifying"
+          , Whitespace
+          , Plaintext "glass"
+          , Whitespace
+          , Plaintext "used"
+          , Whitespace
+          , Plaintext "by"
+          , Whitespace
+          , Plaintext "jewelers"
+          , Whitespace
+          , Plaintext "and"
+          , Whitespace
+          , Plaintext "watchmakers.\""
+          ]
+      ]
+  , LinkTargets [ "loupe-features" ]
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "enhances"
+      , Whitespace
+      , Plaintext "Vim's"
+      , Whitespace
+      , Link "search-commands"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "four"
+      , Whitespace
+      , Plaintext "ways:"
+      ]
+  , SubheadingAnnotation
+      "1. Makes the currently selected match easier to see"
+  , Paragraph
+      [ Plaintext "When"
+      , Whitespace
+      , Plaintext "searching"
+      , Whitespace
+      , Plaintext "using"
+      , Whitespace
+      , Link "/"
+      , Plaintext ","
+      , Whitespace
+      , Link "?"
+      , Plaintext ","
+      , Whitespace
+      , Link "star"
+      , Plaintext ","
+      , Whitespace
+      , Link "#"
+      , Plaintext ","
+      , Whitespace
+      , Link "n"
+      , Plaintext ","
+      , Whitespace
+      , Link "N"
+      , Whitespace
+      , Plaintext "or"
+      , Whitespace
+      , Plaintext "similar,"
+      , Whitespace
+      , Plaintext "it"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "be"
+      , Whitespace
+      , Plaintext "hard"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "see"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "\"current\""
+      , Whitespace
+      , Plaintext "match"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "among"
+      , Whitespace
+      , Plaintext "all"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "matches"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "'hlsearch'"
+      , Whitespace
+      , Plaintext "highlights."
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "makes"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "currently"
+      , Whitespace
+      , Plaintext "selected"
+      , Whitespace
+      , Plaintext "match"
+      , Whitespace
+      , Plaintext "easier"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "see"
+      , Whitespace
+      , Plaintext "by:"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext "Applying"
+          , Whitespace
+          , Plaintext "a"
+          , Whitespace
+          , Plaintext "different"
+          , Whitespace
+          , Link ":highlight"
+          , Whitespace
+          , Plaintext "group"
+          , Whitespace
+          , Plaintext "(by"
+          , Whitespace
+          , Plaintext "default,"
+          , Whitespace
+          , Link "hl-IncSearch"
+          , Plaintext ")"
+          , Whitespace
+          , Plaintext "to"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "match"
+          , Whitespace
+          , Plaintext "under"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "cursor."
+          ]
+      , ListItem
+          [ Plaintext "Keeping"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "matching"
+          , Whitespace
+          , Plaintext "line"
+          , Whitespace
+          , Plaintext "centered"
+          , Whitespace
+          , Plaintext "within"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "window"
+          , Whitespace
+          , Plaintext "when"
+          , Whitespace
+          , Plaintext "jumping"
+          , Whitespace
+          , Plaintext "between"
+          , Whitespace
+          , Plaintext "matches"
+          , Whitespace
+          , Plaintext "with"
+          , Whitespace
+          , Link "n"
+          , Whitespace
+          , Plaintext "and"
+          , Whitespace
+          , Link "N"
+          , Plaintext "."
+          ]
+      ]
+  , SubheadingAnnotation "2. Applies sane pattern syntax by default"
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "makes"
+      , Whitespace
+      , Plaintext "\"very"
+      , Whitespace
+      , Plaintext "magic\""
+      , Whitespace
+      , Plaintext "("
+      , Link "/\\v"
+      , Plaintext ")"
+      , Whitespace
+      , Plaintext "syntax"
+      , Whitespace
+      , Plaintext "apply"
+      , Whitespace
+      , Plaintext "by"
+      , Whitespace
+      , Plaintext "default"
+      , Whitespace
+      , Plaintext "when"
+      , Whitespace
+      , Plaintext "searching."
+      , Whitespace
+      , Plaintext "This"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "true"
+      , Whitespace
+      , Plaintext "even"
+      , Whitespace
+      , Plaintext "if"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "initiate"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "via"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "novel"
+      , Whitespace
+      , Plaintext "means,"
+      , Whitespace
+      , Plaintext "such"
+      , Whitespace
+      , Plaintext "as"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "visual"
+      , Whitespace
+      , Plaintext "selection"
+      , Whitespace
+      , Plaintext "or"
+      , Whitespace
+      , Plaintext "with"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "complicated"
+      , Whitespace
+      , Link ":range"
+      , Whitespace
+      , Plaintext "prefix."
+      ]
+  , Paragraph
+      [ Plaintext "This"
+      , Whitespace
+      , Plaintext "means"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "use"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "pattern"
+      , Whitespace
+      , Plaintext "syntax"
+      , Whitespace
+      , Plaintext "closer"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "familiar"
+      , Whitespace
+      , Plaintext "regular"
+      , Whitespace
+      , Plaintext "expression"
+      , Whitespace
+      , Plaintext "syntax"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "languages"
+      , Whitespace
+      , Plaintext "such"
+      , Whitespace
+      , Plaintext "as"
+      , Whitespace
+      , Plaintext "Perl,"
+      , Whitespace
+      , Plaintext "Ruby,"
+      , Whitespace
+      , Plaintext "JavaScript"
+      , Whitespace
+      , Plaintext "(indeed,"
+      , Whitespace
+      , Plaintext "most"
+      , Whitespace
+      , Plaintext "other"
+      , Whitespace
+      , Plaintext "modern"
+      , Whitespace
+      , Plaintext "languages"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "support"
+      , Whitespace
+      , Plaintext "regular"
+      , Whitespace
+      , Plaintext "expressions)."
+      ]
+  , SubheadingAnnotation
+      "3. Provides a shortcut to remove search highlighting"
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "maps"
+      , Whitespace
+      , Plaintext "<leader>n"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "quickly"
+      , Whitespace
+      , Plaintext "remove"
+      , Whitespace
+      , Plaintext "all"
+      , Whitespace
+      , Plaintext "'hlsearch'"
+      , Whitespace
+      , Plaintext "highlighting"
+      , Whitespace
+      , Plaintext "(although"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "provide"
+      , Whitespace
+      , Plaintext "an"
+      , Whitespace
+      , Plaintext "alternative"
+      , Whitespace
+      , Plaintext "mapping"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "your"
+      , Whitespace
+      , Plaintext "choosing"
+      , Whitespace
+      , Plaintext "or"
+      , Whitespace
+      , Plaintext "suppress"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "feature"
+      , Whitespace
+      , Plaintext "entirely)."
+      ]
+  , SubheadingAnnotation
+      "4. Sensible defaults for search-related features"
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "provides"
+      , Whitespace
+      , Plaintext "reasonable"
+      , Whitespace
+      , Plaintext "defaults"
+      , Whitespace
+      , Plaintext "for"
+      , Whitespace
+      , Plaintext "most"
+      , Whitespace
+      , Plaintext "search-related"
+      , Whitespace
+      , Plaintext "Vim"
+      , Whitespace
+      , Plaintext "settings"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "provide"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "good"
+      , Whitespace
+      , Plaintext "\"out"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "box\""
+      , Whitespace
+      , Plaintext "experience."
+      , Whitespace
+      , Plaintext "For"
+      , Whitespace
+      , Plaintext "more"
+      , Whitespace
+      , Plaintext "details,"
+      , Whitespace
+      , Plaintext "or"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "see"
+      , Whitespace
+      , Plaintext "how"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "override"
+      , Whitespace
+      , Plaintext "Loupe's"
+      , Whitespace
+      , Plaintext "settings,"
+      , Whitespace
+      , Plaintext "see"
+      , Whitespace
+      , Link "loupe-overrides"
+      , Plaintext "."
+      ]
+  , HeadingAnnotation "Installation"
+  , Paragraph
+      [ Plaintext "To"
+      , Whitespace
+      , Plaintext "install"
+      , Whitespace
+      , Plaintext "Loupe,"
+      , Whitespace
+      , Plaintext "use"
+      , Whitespace
+      , Plaintext "your"
+      , Whitespace
+      , Plaintext "plug-in"
+      , Whitespace
+      , Plaintext "management"
+      , Whitespace
+      , Plaintext "system"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "choice."
+      ]
+  , Paragraph
+      [ Plaintext "If"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "don't"
+      , Whitespace
+      , Plaintext "have"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "\"plug-in"
+      , Whitespace
+      , Plaintext "management"
+      , Whitespace
+      , Plaintext "system"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "choice\","
+      , Whitespace
+      , Plaintext "I"
+      , Whitespace
+      , Plaintext "recommend"
+      , Whitespace
+      , Plaintext "Pathogen"
+      , Whitespace
+      , Plaintext "(https://github.com/tpope/vim-pathogen)"
+      , Whitespace
+      , Plaintext "due"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "its"
+      , Whitespace
+      , Plaintext "simplicity"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "robustness."
+      , Whitespace
+      , Plaintext "Assuming"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "have"
+      , Whitespace
+      , Plaintext "Pathogen"
+      , Whitespace
+      , Plaintext "installed"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "configured,"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "want"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "install"
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "into"
+      , Whitespace
+      , Code "~/.vim/bundle"
+      , Plaintext ","
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "do"
+      , Whitespace
+      , Plaintext "so"
+      , Whitespace
+      , Plaintext "with:"
+      ]
+  , Fenced
+      [ "git clone https://github.com/wincent/loupe.git ~/.vim/bundle/loupe"
+      ]
+  , Paragraph
+      [ Plaintext "Alternatively,"
+      , Whitespace
+      , Plaintext "if"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "use"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "Git"
+      , Whitespace
+      , Plaintext "submodule"
+      , Whitespace
+      , Plaintext "for"
+      , Whitespace
+      , Plaintext "each"
+      , Whitespace
+      , Plaintext "Vim"
+      , Whitespace
+      , Plaintext "plug-in,"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "could"
+      , Whitespace
+      , Plaintext "do"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "following"
+      , Whitespace
+      , Plaintext "after"
+      , Whitespace
+      , Code "cd"
+      , Plaintext "-ing"
+      , Whitespace
+      , Plaintext "into"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "top-level"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "your"
+      , Whitespace
+      , Plaintext "Git"
+      , Whitespace
+      , Plaintext "superproject:"
+      ]
+  , Fenced
+      [ "git submodule add https://github.com/wincent/loupe.git ~/vim/bundle/loupe"
+      , "git submodule init"
+      ]
+  , Paragraph
+      [ Plaintext "To"
+      , Whitespace
+      , Plaintext "generate"
+      , Whitespace
+      , Plaintext "help"
+      , Whitespace
+      , Plaintext "tags"
+      , Whitespace
+      , Plaintext "under"
+      , Whitespace
+      , Plaintext "Pathogen,"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "do"
+      , Whitespace
+      , Plaintext "so"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "inside"
+      , Whitespace
+      , Plaintext "Vim"
+      , Whitespace
+      , Plaintext "with:"
+      ]
+  , Fenced [ ":call pathogen#helptags()" ]
+  , HeadingAnnotation "Overrides"
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "sets"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "number"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "search-related"
+      , Whitespace
+      , Plaintext "Vim"
+      , Whitespace
+      , Plaintext "settings"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "reasonable"
+      , Whitespace
+      , Plaintext "defaults"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "order"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "provide"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "good"
+      , Whitespace
+      , Plaintext "\"out"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "box\""
+      , Whitespace
+      , Plaintext "experience:"
+      ]
+  , IndentAnnotation
+  , LinkTargets [ "loupe-history-override" ]
+  , Paragraph [ Plaintext "'history'" ]
+  , Paragraph
+      [ Plaintext "Increased"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "1000,"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "increase"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "number"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "previous"
+      , Whitespace
+      , Plaintext "searches"
+      , Whitespace
+      , Plaintext "remembered."
+      , Whitespace
+      , Plaintext "Note"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "only"
+      , Whitespace
+      , Plaintext "applies"
+      , Whitespace
+      , Plaintext "this"
+      , Whitespace
+      , Plaintext "setting"
+      , Whitespace
+      , Plaintext "if"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "current"
+      , Whitespace
+      , Plaintext "value"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "'history'"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "less"
+      , Whitespace
+      , Plaintext "than"
+      , Whitespace
+      , Plaintext "1000."
+      ]
+  , LinkTargets [ "loupe-hlsearch-override" ]
+  , Paragraph [ Plaintext "'hlsearch'" ]
+  , Paragraph
+      [ Plaintext "Turned"
+      , Whitespace
+      , Plaintext "on"
+      , Whitespace
+      , Plaintext "(when"
+      , Whitespace
+      , Plaintext "there"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "previous"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "pattern,"
+      , Whitespace
+      , Plaintext "highlight"
+      , Whitespace
+      , Plaintext "all"
+      , Whitespace
+      , Plaintext "its"
+      , Whitespace
+      , Plaintext "matches)."
+      ]
+  , LinkTargets [ "loupe-incsearch-override" ]
+  , Paragraph [ Plaintext "'incsearch'" ]
+  , Paragraph
+      [ Plaintext "Turned"
+      , Whitespace
+      , Plaintext "on"
+      , Whitespace
+      , Plaintext "(while"
+      , Whitespace
+      , Plaintext "typing"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "command,"
+      , Whitespace
+      , Plaintext "show"
+      , Whitespace
+      , Plaintext "where"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "pattern"
+      , Whitespace
+      , Plaintext "matches,"
+      , Whitespace
+      , Plaintext "as"
+      , Whitespace
+      , Plaintext "it"
+      , Whitespace
+      , Plaintext "was"
+      , Whitespace
+      , Plaintext "typed"
+      , Whitespace
+      , Plaintext "so"
+      , Whitespace
+      , Plaintext "far)."
+      ]
+  , LinkTargets [ "loupe-ignorecase-override" ]
+  , Paragraph [ Plaintext "'ignorecase'" ]
+  , Paragraph
+      [ Plaintext "Turned"
+      , Whitespace
+      , Plaintext "on"
+      , Whitespace
+      , Plaintext "(to"
+      , Whitespace
+      , Plaintext "ignore"
+      , Whitespace
+      , Plaintext "case"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "patterns)."
+      ]
+  , LinkTargets [ "loupe-shortmess-override" ]
+  , Paragraph [ Plaintext "'shortmess'" ]
+  , Paragraph
+      [ Plaintext "Adds"
+      , Whitespace
+      , Plaintext "\"s\","
+      , Whitespace
+      , Plaintext "which"
+      , Whitespace
+      , Plaintext "suppresses"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "display"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "\"search"
+      , Whitespace
+      , Plaintext "hit"
+      , Whitespace
+      , Plaintext "BOTTOM,"
+      , Whitespace
+      , Plaintext "continuing"
+      , Whitespace
+      , Plaintext "at"
+      , Whitespace
+      , Plaintext "TOP\""
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "\"search"
+      , Whitespace
+      , Plaintext "hit"
+      , Whitespace
+      , Plaintext "TOP,"
+      , Whitespace
+      , Plaintext "continuing"
+      , Whitespace
+      , Plaintext "at"
+      , Whitespace
+      , Plaintext "BOTTOM\""
+      , Whitespace
+      , Plaintext "messages."
+      ]
+  , LinkTargets [ "loupe-smartcase-override" ]
+  , Paragraph [ Plaintext "'smartcase'" ]
+  , Paragraph
+      [ Plaintext "Turned"
+      , Whitespace
+      , Plaintext "on"
+      , Whitespace
+      , Plaintext "(overrides"
+      , Whitespace
+      , Plaintext "'ignorecase',"
+      , Whitespace
+      , Plaintext "making"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "pattern"
+      , Whitespace
+      , Plaintext "case-sensitive"
+      , Whitespace
+      , Plaintext "whenever"
+      , Whitespace
+      , Plaintext "it"
+      , Whitespace
+      , Plaintext "containers"
+      , Whitespace
+      , Plaintext "uppercase"
+      , Whitespace
+      , Plaintext "characters)."
+      ]
+  , DedentAnnotation
+  , Paragraph
+      [ Plaintext "To"
+      , Whitespace
+      , Plaintext "override"
+      , Whitespace
+      , Plaintext "any"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "these"
+      , Whitespace
+      , Plaintext "choices,"
+      , Whitespace
+      , Plaintext "you"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "place"
+      , Whitespace
+      , Plaintext "overrides"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "an"
+      , Whitespace
+      , Link "after-directory"
+      , Whitespace
+      , Plaintext "(ie."
+      , Whitespace
+      , Code "~/.vim/after/plugin/loupe.vim"
+      , Plaintext ")."
+      , Whitespace
+      , Plaintext "For"
+      , Whitespace
+      , Plaintext "example:"
+      ]
+  , Fenced
+      [ " \" Override Loupe's 'history' setting from 1000 to 10000."
+      , " set history=10000"
+      , ""
+      , " \" Reset Loupe's 'incsearch' back to Vim default."
+      , " set incsearch&vim"
+      , ""
+      , " \" Remove unwanted 's' from 'shortmess'."
+      , " set shortmess-=s"
+      ]
+  , HeadingAnnotation "Related"
+  , Paragraph
+      [ Plaintext "Just"
+      , Whitespace
+      , Plaintext "as"
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "aims"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "improve"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "within-file"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "experience,"
+      , Whitespace
+      , Plaintext "Ferret"
+      , Whitespace
+      , Plaintext "does"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "same"
+      , Whitespace
+      , Plaintext "for"
+      , Whitespace
+      , Plaintext "multi-file"
+      , Whitespace
+      , Plaintext "searching"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "replacing:"
+      ]
+  , List
+      [ ListItem [ Plaintext "https://github.com/wincent/ferret" ] ]
+  , HeadingAnnotation "Website"
+  , Paragraph
+      [ Plaintext "The"
+      , Whitespace
+      , Plaintext "official"
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "source"
+      , Whitespace
+      , Plaintext "code"
+      , Whitespace
+      , Plaintext "repo"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "at:"
+      ]
+  , List
+      [ ListItem [ Plaintext "http://git.wincent.com/loupe.git" ] ]
+  , Paragraph
+      [ Plaintext "A"
+      , Whitespace
+      , Plaintext "mirror"
+      , Whitespace
+      , Plaintext "exists"
+      , Whitespace
+      , Plaintext "at:"
+      ]
+  , List
+      [ ListItem [ Plaintext "https://github.com/wincent/loupe" ] ]
+  , Paragraph
+      [ Plaintext "Official"
+      , Whitespace
+      , Plaintext "releases"
+      , Whitespace
+      , Plaintext "are"
+      , Whitespace
+      , Plaintext "listed"
+      , Whitespace
+      , Plaintext "at:"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext "http://www.vim.org/scripts/script.php?script_id=5215"
+          ]
+      ]
+  , HeadingAnnotation "License"
+  , Paragraph
+      [ Plaintext "Copyright"
+      , Whitespace
+      , Plaintext "2015-present"
+      , Whitespace
+      , Plaintext "Greg"
+      , Whitespace
+      , Plaintext "Hurrell."
+      , Whitespace
+      , Plaintext "All"
+      , Whitespace
+      , Plaintext "rights"
+      , Whitespace
+      , Plaintext "reserved."
+      ]
+  , Paragraph
+      [ Plaintext "Redistribution"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "use"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "source"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "binary"
+      , Whitespace
+      , Plaintext "forms,"
+      , Whitespace
+      , Plaintext "with"
+      , Whitespace
+      , Plaintext "or"
+      , Whitespace
+      , Plaintext "without"
+      , Whitespace
+      , Plaintext "modification,"
+      , Whitespace
+      , Plaintext "are"
+      , Whitespace
+      , Plaintext "permitted"
+      , Whitespace
+      , Plaintext "provided"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "following"
+      , Whitespace
+      , Plaintext "conditions"
+      , Whitespace
+      , Plaintext "are"
+      , Whitespace
+      , Plaintext "met:"
+      ]
+  , Paragraph
+      [ Plaintext "1."
+      , Whitespace
+      , Plaintext "Redistributions"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "source"
+      , Whitespace
+      , Plaintext "code"
+      , Whitespace
+      , Plaintext "must"
+      , Whitespace
+      , Plaintext "retain"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "above"
+      , Whitespace
+      , Plaintext "copyright"
+      , Whitespace
+      , Plaintext "notice,"
+      , Whitespace
+      , Plaintext "this"
+      , Whitespace
+      , Plaintext "list"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "conditions"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "following"
+      , Whitespace
+      , Plaintext "disclaimer."
+      ]
+  , Paragraph
+      [ Plaintext "2."
+      , Whitespace
+      , Plaintext "Redistributions"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "binary"
+      , Whitespace
+      , Plaintext "form"
+      , Whitespace
+      , Plaintext "must"
+      , Whitespace
+      , Plaintext "reproduce"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "above"
+      , Whitespace
+      , Plaintext "copyright"
+      , Whitespace
+      , Plaintext "notice,"
+      , Whitespace
+      , Plaintext "this"
+      , Whitespace
+      , Plaintext "list"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "conditions"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "following"
+      , Whitespace
+      , Plaintext "disclaimer"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "documentation"
+      , Whitespace
+      , Plaintext "and/or"
+      , Whitespace
+      , Plaintext "other"
+      , Whitespace
+      , Plaintext "materials"
+      , Whitespace
+      , Plaintext "provided"
+      , Whitespace
+      , Plaintext "with"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "distribution."
+      ]
+  , Paragraph
+      [ Plaintext "THIS"
+      , Whitespace
+      , Plaintext "SOFTWARE"
+      , Whitespace
+      , Plaintext "IS"
+      , Whitespace
+      , Plaintext "PROVIDED"
+      , Whitespace
+      , Plaintext "BY"
+      , Whitespace
+      , Plaintext "THE"
+      , Whitespace
+      , Plaintext "COPYRIGHT"
+      , Whitespace
+      , Plaintext "HOLDERS"
+      , Whitespace
+      , Plaintext "AND"
+      , Whitespace
+      , Plaintext "CONTRIBUTORS"
+      , Whitespace
+      , Plaintext "\"AS"
+      , Whitespace
+      , Plaintext "IS\""
+      , Whitespace
+      , Plaintext "AND"
+      , Whitespace
+      , Plaintext "ANY"
+      , Whitespace
+      , Plaintext "EXPRESS"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "IMPLIED"
+      , Whitespace
+      , Plaintext "WARRANTIES,"
+      , Whitespace
+      , Plaintext "INCLUDING,"
+      , Whitespace
+      , Plaintext "BUT"
+      , Whitespace
+      , Plaintext "NOT"
+      , Whitespace
+      , Plaintext "LIMITED"
+      , Whitespace
+      , Plaintext "TO,"
+      , Whitespace
+      , Plaintext "THE"
+      , Whitespace
+      , Plaintext "IMPLIED"
+      , Whitespace
+      , Plaintext "WARRANTIES"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "MERCHANTABILITY"
+      , Whitespace
+      , Plaintext "AND"
+      , Whitespace
+      , Plaintext "FITNESS"
+      , Whitespace
+      , Plaintext "FOR"
+      , Whitespace
+      , Plaintext "A"
+      , Whitespace
+      , Plaintext "PARTICULAR"
+      , Whitespace
+      , Plaintext "PURPOSE"
+      , Whitespace
+      , Plaintext "ARE"
+      , Whitespace
+      , Plaintext "DISCLAIMED."
+      , Whitespace
+      , Plaintext "IN"
+      , Whitespace
+      , Plaintext "NO"
+      , Whitespace
+      , Plaintext "EVENT"
+      , Whitespace
+      , Plaintext "SHALL"
+      , Whitespace
+      , Plaintext "THE"
+      , Whitespace
+      , Plaintext "COPYRIGHT"
+      , Whitespace
+      , Plaintext "HOLDERS"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "CONTRIBUTORS"
+      , Whitespace
+      , Plaintext "BE"
+      , Whitespace
+      , Plaintext "LIABLE"
+      , Whitespace
+      , Plaintext "FOR"
+      , Whitespace
+      , Plaintext "ANY"
+      , Whitespace
+      , Plaintext "DIRECT,"
+      , Whitespace
+      , Plaintext "INDIRECT,"
+      , Whitespace
+      , Plaintext "INCIDENTAL,"
+      , Whitespace
+      , Plaintext "SPECIAL,"
+      , Whitespace
+      , Plaintext "EXEMPLARY,"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "CONSEQUENTIAL"
+      , Whitespace
+      , Plaintext "DAMAGES"
+      , Whitespace
+      , Plaintext "(INCLUDING,"
+      , Whitespace
+      , Plaintext "BUT"
+      , Whitespace
+      , Plaintext "NOT"
+      , Whitespace
+      , Plaintext "LIMITED"
+      , Whitespace
+      , Plaintext "TO,"
+      , Whitespace
+      , Plaintext "PROCUREMENT"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "SUBSTITUTE"
+      , Whitespace
+      , Plaintext "GOODS"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "SERVICES;"
+      , Whitespace
+      , Plaintext "LOSS"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "USE,"
+      , Whitespace
+      , Plaintext "DATA,"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "PROFITS;"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "BUSINESS"
+      , Whitespace
+      , Plaintext "INTERRUPTION)"
+      , Whitespace
+      , Plaintext "HOWEVER"
+      , Whitespace
+      , Plaintext "CAUSED"
+      , Whitespace
+      , Plaintext "AND"
+      , Whitespace
+      , Plaintext "ON"
+      , Whitespace
+      , Plaintext "ANY"
+      , Whitespace
+      , Plaintext "THEORY"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "LIABILITY,"
+      , Whitespace
+      , Plaintext "WHETHER"
+      , Whitespace
+      , Plaintext "IN"
+      , Whitespace
+      , Plaintext "CONTRACT,"
+      , Whitespace
+      , Plaintext "STRICT"
+      , Whitespace
+      , Plaintext "LIABILITY,"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "TORT"
+      , Whitespace
+      , Plaintext "(INCLUDING"
+      , Whitespace
+      , Plaintext "NEGLIGENCE"
+      , Whitespace
+      , Plaintext "OR"
+      , Whitespace
+      , Plaintext "OTHERWISE)"
+      , Whitespace
+      , Plaintext "ARISING"
+      , Whitespace
+      , Plaintext "IN"
+      , Whitespace
+      , Plaintext "ANY"
+      , Whitespace
+      , Plaintext "WAY"
+      , Whitespace
+      , Plaintext "OUT"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "THE"
+      , Whitespace
+      , Plaintext "USE"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "THIS"
+      , Whitespace
+      , Plaintext "SOFTWARE,"
+      , Whitespace
+      , Plaintext "EVEN"
+      , Whitespace
+      , Plaintext "IF"
+      , Whitespace
+      , Plaintext "ADVISED"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "THE"
+      , Whitespace
+      , Plaintext "POSSIBILITY"
+      , Whitespace
+      , Plaintext "OF"
+      , Whitespace
+      , Plaintext "SUCH"
+      , Whitespace
+      , Plaintext "DAMAGE."
+      ]
+  , HeadingAnnotation "Development"
+  , SubheadingAnnotation "Contributing patches"
+  , Paragraph
+      [ Plaintext "Patches"
+      , Whitespace
+      , Plaintext "can"
+      , Whitespace
+      , Plaintext "be"
+      , Whitespace
+      , Plaintext "sent"
+      , Whitespace
+      , Plaintext "via"
+      , Whitespace
+      , Plaintext "mail"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "greg@hurrell.net,"
+      , Whitespace
+      , Plaintext "or"
+      , Whitespace
+      , Plaintext "as"
+      , Whitespace
+      , Plaintext "GitHub"
+      , Whitespace
+      , Plaintext "pull"
+      , Whitespace
+      , Plaintext "requests"
+      , Whitespace
+      , Plaintext "at:"
+      , Whitespace
+      , Plaintext "https://github.com/wincent/loupe/pulls"
+      ]
+  , SubheadingAnnotation "Cutting a new release"
+  , Paragraph
+      [ Plaintext "At"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "moment"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "release"
+      , Whitespace
+      , Plaintext "process"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "manual:"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext "Perform"
+          , Whitespace
+          , Plaintext "final"
+          , Whitespace
+          , Plaintext "sanity"
+          , Whitespace
+          , Plaintext "checks"
+          , Whitespace
+          , Plaintext "and"
+          , Whitespace
+          , Plaintext "manual"
+          , Whitespace
+          , Plaintext "testing"
+          ]
+      , ListItem
+          [ Plaintext "Update"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Link "loupe-history"
+          , Whitespace
+          , Plaintext "section"
+          , Whitespace
+          , Plaintext "of"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "documentation"
+          ]
+      , ListItem
+          [ Plaintext "Verify"
+          , Whitespace
+          , Plaintext "clean"
+          , Whitespace
+          , Plaintext "work"
+          , Whitespace
+          , Plaintext "tree:"
+          ]
+      ]
+  , Fenced [ "git status" ]
+  , List
+      [ ListItem
+          [ Plaintext "Tag"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "release:"
+          ]
+      ]
+  , Fenced [ "git tag -s -m \"$VERSION release\" $VERSION" ]
+  , List
+      [ ListItem
+          [ Plaintext "Publish"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "code:"
+          ]
+      ]
+  , Fenced
+      [ "git push origin master --follow-tags"
+      , "git push github master --follow-tags"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext "Produce"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Plaintext "release"
+          , Whitespace
+          , Plaintext "archive:"
+          ]
+      ]
+  , Fenced [ "git archive -o loupe-$VERSION.zip HEAD -- ." ]
+  , List
+      [ ListItem
+          [ Plaintext "Upload"
+          , Whitespace
+          , Plaintext "to"
+          , Whitespace
+          , Plaintext "http://www.vim.org/scripts/script.php?script_id=5215"
+          ]
+      ]
+  , HeadingAnnotation "Authors"
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "written"
+      , Whitespace
+      , Plaintext "and"
+      , Whitespace
+      , Plaintext "maintained"
+      , Whitespace
+      , Plaintext "by"
+      , Whitespace
+      , Plaintext "Greg"
+      , Whitespace
+      , Plaintext "Hurrell"
+      , Whitespace
+      , Plaintext "<greg@hurrell.net>."
+      ]
+  , Paragraph
+      [ Plaintext "The"
+      , Whitespace
+      , Plaintext "original"
+      , Whitespace
+      , Plaintext "idea"
+      , Whitespace
+      , Plaintext "for"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Link "g:LoupeHighlightGroup"
+      , Whitespace
+      , Plaintext "feature"
+      , Whitespace
+      , Plaintext "was"
+      , Whitespace
+      , Plaintext "taken"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "Damian"
+      , Whitespace
+      , Plaintext "Conway's"
+      , Whitespace
+      , Plaintext "Vim"
+      , Whitespace
+      , Plaintext "set-up:"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext
+              "https://github.com/thoughtstream/Damian-Conway-s-Vim-Setup/blob/master/plugin/hlnext.vim"
+          ]
+      ]
+  , Paragraph
+      [ Plaintext "Which"
+      , Whitespace
+      , Plaintext "he"
+      , Whitespace
+      , Plaintext "discussed"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "his"
+      , Whitespace
+      , Plaintext "\"More"
+      , Whitespace
+      , Plaintext "Instantly"
+      , Whitespace
+      , Plaintext "Better"
+      , Whitespace
+      , Plaintext "Vim\""
+      , Whitespace
+      , Plaintext "presentation"
+      , Whitespace
+      , Plaintext "at"
+      , Whitespace
+      , Plaintext "OSCON"
+      , Whitespace
+      , Plaintext "2013:"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext "https://www.youtube.com/watch?v=aHm36-na4-4" ]
+      ]
+  , HeadingAnnotation "History"
+  , SubheadingAnnotation "1.0 (28 December 2015)"
+  , List
+      [ ListItem
+          [ Plaintext "Renamed"
+          , Whitespace
+          , Plaintext "the"
+          , Whitespace
+          , Link "<Plug>LoupeClearHighlight"
+          , Whitespace
+          , Plaintext "mapping"
+          , Whitespace
+          , Plaintext "to"
+          , Whitespace
+          , Link "<Plug>(LoupeClearHighlight)"
+          , Plaintext "."
+          ]
+      ]
+  , SubheadingAnnotation "0.1 (5 July 2015)"
+  , List
+      [ ListItem
+          [ Plaintext "Initial"
+          , Whitespace
+          , Plaintext "release,"
+          , Whitespace
+          , Plaintext "extracted"
+          , Whitespace
+          , Plaintext "from"
+          , Whitespace
+          , Plaintext "my"
+          , Whitespace
+          , Plaintext "dotfiles"
+          , Whitespace
+          , Plaintext "(https://github.com/wincent/wincent)."
+          ]
+      ]
+  , Project
       [ Unit
           [ FunctionDeclaration
               { functionBang = True
@@ -155,7 +1872,8 @@ Project
               , functionArguments = ArgumentList []
               , functionAttributes = [ "abort" ]
               , functionBody =
-                  [ LetStatement
+                  [ Empty
+                  , LetStatement
                       { letLexpr = "l:highlight"
                       , letValue = "get(g:, 'LoupeHighlightGroup', 'IncSearch')"
                       }
@@ -288,4 +2006,432 @@ Project
           , UnletStatement { unletBang = False , unletBody = "s:cpoptions" }
           ]
       ]
+  , MappingsAnnotation
+  , MappingAnnotation "<Plug>(LoupeClearHighlight)"
+  , Paragraph
+      [ Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "maps"
+      , Whitespace
+      , Plaintext "<leader>n"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Link "<Plug>(LoupeClearHighlight)"
+      , Plaintext ","
+      , Whitespace
+      , Plaintext "which"
+      , Whitespace
+      , Plaintext "clears"
+      , Whitespace
+      , Plaintext "all"
+      , Whitespace
+      , Plaintext "visible"
+      , Whitespace
+      , Plaintext "highlights"
+      , Whitespace
+      , Plaintext "(like"
+      , Whitespace
+      , Link ":nohighlight"
+      , Whitespace
+      , Plaintext "does)."
+      , Whitespace
+      , Plaintext "To"
+      , Whitespace
+      , Plaintext "use"
+      , Whitespace
+      , Plaintext "an"
+      , Whitespace
+      , Plaintext "alternative"
+      , Whitespace
+      , Plaintext "mapping"
+      , Whitespace
+      , Plaintext "instead,"
+      , Whitespace
+      , Plaintext "create"
+      , Whitespace
+      , Plaintext "a"
+      , Whitespace
+      , Plaintext "different"
+      , Whitespace
+      , Plaintext "one"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "your"
+      , Whitespace
+      , Link ".vimrc"
+      , Whitespace
+      , Plaintext "instead"
+      , Whitespace
+      , Plaintext "using"
+      , Whitespace
+      , Link ":nmap"
+      , Plaintext ":"
+      ]
+  , Fenced
+      [ "\" Instead of <leader>n, use <leader>x."
+      , "nmap <leader>x <Plug>(LoupeClearHighlight)"
+      ]
+  , Paragraph
+      [ Plaintext "Note"
+      , Whitespace
+      , Plaintext "that"
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "will"
+      , Whitespace
+      , Plaintext "not"
+      , Whitespace
+      , Plaintext "try"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Plaintext "up"
+      , Whitespace
+      , Plaintext "its"
+      , Whitespace
+      , Plaintext "<leader>n"
+      , Whitespace
+      , Plaintext "mapping"
+      , Whitespace
+      , Plaintext "if"
+      , Whitespace
+      , Plaintext "any"
+      , Whitespace
+      , Plaintext "of"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "following"
+      , Whitespace
+      , Plaintext "are"
+      , Whitespace
+      , Plaintext "true:"
+      ]
+  , List
+      [ ListItem
+          [ Plaintext "A"
+          , Whitespace
+          , Plaintext "mapping"
+          , Whitespace
+          , Plaintext "for"
+          , Whitespace
+          , Plaintext "<leader>n"
+          , Whitespace
+          , Plaintext "already"
+          , Whitespace
+          , Plaintext "exists."
+          ]
+      , ListItem
+          [ Plaintext "An"
+          , Whitespace
+          , Plaintext "alternative"
+          , Whitespace
+          , Plaintext "mapping"
+          , Whitespace
+          , Plaintext "for"
+          , Whitespace
+          , Link "<Plug>(LoupeClearHighlight)"
+          , Whitespace
+          , Plaintext "has"
+          , Whitespace
+          , Plaintext "already"
+          , Whitespace
+          , Plaintext "been"
+          , Whitespace
+          , Plaintext "set"
+          , Whitespace
+          , Plaintext "up"
+          , Whitespace
+          , Plaintext "from"
+          , Whitespace
+          , Plaintext "a"
+          , Whitespace
+          , Link ".vimrc"
+          , Plaintext "."
+          ]
+      , ListItem
+          [ Plaintext "The"
+          , Whitespace
+          , Plaintext "mapping"
+          , Whitespace
+          , Plaintext "has"
+          , Whitespace
+          , Plaintext "been"
+          , Whitespace
+          , Plaintext "suppressed"
+          , Whitespace
+          , Plaintext "by"
+          , Whitespace
+          , Plaintext "setting"
+          , Whitespace
+          , Link "g:LoupeClearHighlightMap"
+          , Whitespace
+          , Plaintext "to"
+          , Whitespace
+          , Plaintext "1"
+          , Whitespace
+          , Plaintext "in"
+          , Whitespace
+          , Plaintext "your"
+          , Whitespace
+          , Link ".vimrc"
+          , Plaintext "."
+          ]
+      ]
+  , OptionsAnnotation
+  , OptionAnnotation
+      "g:LoupeHighlightGroup" "string" (Just "IncSearch")
+  , Paragraph
+      [ Plaintext "Specifies"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Link ":highlight"
+      , Whitespace
+      , Plaintext "group"
+      , Whitespace
+      , Plaintext "used"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "emphasize"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "match"
+      , Whitespace
+      , Plaintext "currently"
+      , Whitespace
+      , Plaintext "under"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "cursor"
+      , Whitespace
+      , Plaintext "for"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "current"
+      , Whitespace
+      , Plaintext "search"
+      , Whitespace
+      , Plaintext "pattern."
+      , Whitespace
+      , Plaintext "Defaults"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "\"IncSearch\""
+      , Whitespace
+      , Plaintext "(ie."
+      , Whitespace
+      , Link "hl-IncSearch"
+      , Plaintext ")."
+      , Whitespace
+      , Plaintext "For"
+      , Whitespace
+      , Plaintext "example:"
+      ]
+  , Fenced [ "let g:LoupeHighlightGroup='Error'" ]
+  , Paragraph
+      [ Plaintext "To"
+      , Whitespace
+      , Plaintext "prevent"
+      , Whitespace
+      , Plaintext "any"
+      , Whitespace
+      , Plaintext "special"
+      , Whitespace
+      , Plaintext "highlighting"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "being"
+      , Whitespace
+      , Plaintext "applied,"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Plaintext "this"
+      , Whitespace
+      , Plaintext "option"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "\"\""
+      , Whitespace
+      , Plaintext "(ie."
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "empty"
+      , Whitespace
+      , Plaintext "string)."
+      ]
+  , OptionAnnotation "g:LoupeLoaded" "any" Nothing
+  , Paragraph
+      [ Plaintext "To"
+      , Whitespace
+      , Plaintext "prevent"
+      , Whitespace
+      , Plaintext "Loupe"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "being"
+      , Whitespace
+      , Plaintext "loaded,"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Link "g:LoupeLoaded"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "any"
+      , Whitespace
+      , Plaintext "value"
+      , Whitespace
+      , Plaintext "in"
+      , Whitespace
+      , Plaintext "your"
+      , Whitespace
+      , Link ".vimrc"
+      , Plaintext "."
+      , Whitespace
+      , Plaintext "For"
+      , Whitespace
+      , Plaintext "example:"
+      ]
+  , Fenced [ "let g:LoupeLoaded=1" ]
+  , OptionAnnotation "g:LoupeClearHighlightMap" "boolean" (Just "1")
+  , Paragraph
+      [ Plaintext "Controls"
+      , Whitespace
+      , Plaintext "whether"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Plaintext "up"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Link "<Plug>(LoupeClearHighlight)"
+      , Whitespace
+      , Plaintext "mapping."
+      , Whitespace
+      , Plaintext "To"
+      , Whitespace
+      , Plaintext "prevent"
+      , Whitespace
+      , Plaintext "any"
+      , Whitespace
+      , Plaintext "mapping"
+      , Whitespace
+      , Plaintext "from"
+      , Whitespace
+      , Plaintext "being"
+      , Whitespace
+      , Plaintext "configured,"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "0:"
+      ]
+  , Fenced [ "let g:LoupeClearHighlightMap=0" ]
+  , OptionAnnotation "g:LoupeVeryMagic" "boolean" (Just "1")
+  , Paragraph
+      [ Plaintext "Controls"
+      , Whitespace
+      , Plaintext "whether"
+      , Whitespace
+      , Plaintext "\"very"
+      , Whitespace
+      , Plaintext "magic\""
+      , Whitespace
+      , Plaintext "pattern"
+      , Whitespace
+      , Plaintext "syntax"
+      , Whitespace
+      , Plaintext "("
+      , Link "/\\v"
+      , Plaintext ")"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "applied"
+      , Whitespace
+      , Plaintext "by"
+      , Whitespace
+      , Plaintext "default."
+      , Whitespace
+      , Plaintext "To"
+      , Whitespace
+      , Plaintext "disable,"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "0:"
+      ]
+  , Fenced [ "let g:LoupeVeryMagic=0" ]
+  , OptionAnnotation "g:LoupeCenterResults" "boolean" (Just "1")
+  , Paragraph
+      [ Plaintext "Controls"
+      , Whitespace
+      , Plaintext "whether"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "match's"
+      , Whitespace
+      , Plaintext "line"
+      , Whitespace
+      , Plaintext "is"
+      , Whitespace
+      , Plaintext "vertically"
+      , Whitespace
+      , Plaintext "centered"
+      , Whitespace
+      , Plaintext "within"
+      , Whitespace
+      , Plaintext "the"
+      , Whitespace
+      , Plaintext "window"
+      , Whitespace
+      , Plaintext "when"
+      , Whitespace
+      , Plaintext "jumping"
+      , Whitespace
+      , Plaintext "(via"
+      , Whitespace
+      , Link "n"
+      , Plaintext ","
+      , Whitespace
+      , Link "N"
+      , Whitespace
+      , Plaintext "etc)."
+      , Whitespace
+      , Plaintext "To"
+      , Whitespace
+      , Plaintext "disable,"
+      , Whitespace
+      , Plaintext "set"
+      , Whitespace
+      , Plaintext "to"
+      , Whitespace
+      , Plaintext "0:"
+      ]
+  , Fenced [ "let g:LoupeCenterResults=0" ]
   ]
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..919dd944202e9fb9909be3e04fc557fc08f0cb71 100644 (file)
@@ -0,0 +1,258 @@
+# loupe<a name="loupe-loupe" href="#user-content-loupe-loupe"></a>
+
+## Intro<a name="loupe-intro" href="#user-content-loupe-intro"></a>
+
+> "loupe (noun)<br />a small magnifying glass used by jewelers and watchmakers."
+
+<p align="right"><a name="loupe-features" href="#user-content-loupe-features"><code>loupe-features</code></a></p>
+Loupe enhances Vim's <strong>`search-commands`</strong> in four ways:
+
+### 1. Makes the currently selected match easier to see<a name="loupe-1-makes-the-currently-selected-match-easier-to-see" href="#user-content-loupe-1-makes-the-currently-selected-match-easier-to-see"></a>
+
+When searching using <strong>`/`</strong>, <strong>`?`</strong>, <strong>`star`</strong>, <strong>`#`</strong>, <strong>`n`</strong>, <strong>`N`</strong> or similar, it can be hard to see the "current" match from among all the matches that 'hlsearch' highlights. Loupe makes the currently selected match easier to see by:
+
+- Applying a different <strong>`:highlight`</strong> group (by default, <strong>`hl-IncSearch`</strong>) to the match under the cursor.
+- Keeping the matching line centered within the window when jumping between matches with <strong>`n`</strong> and <strong>`N`</strong>.
+
+### 2. Applies sane pattern syntax by default<a name="loupe-2-applies-sane-pattern-syntax-by-default" href="#user-content-loupe-2-applies-sane-pattern-syntax-by-default"></a>
+
+Loupe makes "very magic" (<strong>`/\v`</strong>) syntax apply by default when searching. This is true even if you initiate a search via a novel means, such as from a visual selection or with a complicated <strong>`:range`</strong> prefix.
+
+This means that you can use a pattern syntax closer to the familiar regular expression syntax from languages such as Perl, Ruby, JavaScript (indeed, most other modern languages that support regular expressions).
+
+### 3. Provides a shortcut to remove search highlighting<a name="loupe-3-provides-a-shortcut-to-remove-search-highlighting" href="#user-content-loupe-3-provides-a-shortcut-to-remove-search-highlighting"></a>
+
+Loupe maps <leader>n to quickly remove all 'hlsearch' highlighting (although you can provide an alternative mapping of your choosing or suppress the feature entirely).
+
+### 4. Sensible defaults for search-related features<a name="loupe-4-sensible-defaults-for-search-related-features" href="#user-content-loupe-4-sensible-defaults-for-search-related-features"></a>
+
+Loupe provides reasonable defaults for most search-related Vim settings to provide a good "out of the box" experience. For more details, or to see how to override Loupe's settings, see <strong>[`loupe-overrides`](#user-content-loupe-overrides)</strong>.
+
+## Installation<a name="loupe-installation" href="#user-content-loupe-installation"></a>
+
+To install Loupe, use your plug-in management system of choice.
+
+If you don't have a "plug-in management system of choice", I recommend Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and robustness. Assuming that you have Pathogen installed and configured, and that you want to install Loupe into `~/.vim/bundle`, you can do so with:
+
+```
+git clone https://github.com/wincent/loupe.git ~/.vim/bundle/loupe
+```
+
+Alternatively, if you use a Git submodule for each Vim plug-in, you could do the following after `cd`-ing into the top-level of your Git superproject:
+
+```
+git submodule add https://github.com/wincent/loupe.git ~/vim/bundle/loupe
+git submodule init
+```
+
+To generate help tags under Pathogen, you can do so from inside Vim with:
+
+```
+:call pathogen#helptags()
+```
+
+## Overrides<a name="loupe-overrides" href="#user-content-loupe-overrides"></a>
+
+Loupe sets a number of search-related Vim settings to reasonable defaults in order to provide a good "out of the box" experience:
+
+<p align="right"><a name="loupe-history-override" href="#user-content-loupe-history-override"><code>loupe-history-override</code></a></p>
+'history'
+
+Increased to 1000, to increase the number of previous searches remembered. Note that Loupe only applies this setting if the current value of 'history' is less than 1000.
+
+<p align="right"><a name="loupe-hlsearch-override" href="#user-content-loupe-hlsearch-override"><code>loupe-hlsearch-override</code></a></p>
+'hlsearch'
+
+Turned on (when there is a previous search pattern, highlight all its matches).
+
+<p align="right"><a name="loupe-incsearch-override" href="#user-content-loupe-incsearch-override"><code>loupe-incsearch-override</code></a></p>
+'incsearch'
+
+Turned on (while typing a search command, show where the pattern matches, as it was typed so far).
+
+<p align="right"><a name="loupe-ignorecase-override" href="#user-content-loupe-ignorecase-override"><code>loupe-ignorecase-override</code></a></p>
+'ignorecase'
+
+Turned on (to ignore case in search patterns).
+
+<p align="right"><a name="loupe-shortmess-override" href="#user-content-loupe-shortmess-override"><code>loupe-shortmess-override</code></a></p>
+'shortmess'
+
+Adds "s", which suppresses the display of "search hit BOTTOM, continuing at TOP" and "search hit TOP, continuing at BOTTOM" messages.
+
+<p align="right"><a name="loupe-smartcase-override" href="#user-content-loupe-smartcase-override"><code>loupe-smartcase-override</code></a></p>
+'smartcase'
+
+Turned on (overrides 'ignorecase', making the search pattern case-sensitive whenever it containers uppercase characters).
+
+To override any of these choices, you can place overrides in an <strong>`after-directory`</strong> (ie. `~/.vim/after/plugin/loupe.vim`). For example:
+
+```
+ " Override Loupe's 'history' setting from 1000 to 10000.
+ set history=10000
+
+ " Reset Loupe's 'incsearch' back to Vim default.
+ set incsearch&vim
+
+ " Remove unwanted 's' from 'shortmess'.
+ set shortmess-=s
+```
+
+## Related<a name="loupe-related" href="#user-content-loupe-related"></a>
+
+Just as Loupe aims to improve the within-file search experience, Ferret does the same for multi-file searching and replacing:
+
+- https://github.com/wincent/ferret
+
+## Website<a name="loupe-website" href="#user-content-loupe-website"></a>
+
+The official Loupe source code repo is at:
+
+- http://git.wincent.com/loupe.git
+
+A mirror exists at:
+
+- https://github.com/wincent/loupe
+
+Official releases are listed at:
+
+- http://www.vim.org/scripts/script.php?script_id=5215
+
+## License<a name="loupe-license" href="#user-content-loupe-license"></a>
+
+Copyright 2015-present Greg Hurrell. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## Development<a name="loupe-development" href="#user-content-loupe-development"></a>
+
+### Contributing patches<a name="loupe-contributing-patches" href="#user-content-loupe-contributing-patches"></a>
+
+Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/loupe/pulls
+
+### Cutting a new release<a name="loupe-cutting-a-new-release" href="#user-content-loupe-cutting-a-new-release"></a>
+
+At the moment the release process is manual:
+
+- Perform final sanity checks and manual testing
+- Update the <strong>[`loupe-history`](#user-content-loupe-history)</strong> section of the documentation
+- Verify clean work tree:
+
+```
+git status
+```
+
+- Tag the release:
+
+```
+git tag -s -m "$VERSION release" $VERSION
+```
+
+- Publish the code:
+
+```
+git push origin master --follow-tags
+git push github master --follow-tags
+```
+
+- Produce the release archive:
+
+```
+git archive -o loupe-$VERSION.zip HEAD -- .
+```
+
+- Upload to http://www.vim.org/scripts/script.php?script_id=5215
+
+## Authors<a name="loupe-authors" href="#user-content-loupe-authors"></a>
+
+Loupe is written and maintained by Greg Hurrell <greg@hurrell.net>.
+
+The original idea for the <strong>`g:LoupeHighlightGroup`</strong> feature was taken from Damian Conway's Vim set-up:
+
+- https://github.com/thoughtstream/Damian-Conway-s-Vim-Setup/blob/master/plugin/hlnext.vim
+
+Which he discussed in his "More Instantly Better Vim" presentation at OSCON 2013:
+
+- https://www.youtube.com/watch?v=aHm36-na4-4
+
+## History<a name="loupe-history" href="#user-content-loupe-history"></a>
+
+### 1.0 (28 December 2015)<a name="loupe-10-28-december-2015" href="#user-content-loupe-10-28-december-2015"></a>
+
+- Renamed the <strong>`<Plug>LoupeClearHighlight`</strong> mapping to <strong>[`<Plug>(LoupeClearHighlight)`](#user-content-plugloupeclearhighlight)</strong>.
+
+### 0.1 (5 July 2015)<a name="loupe-01-5-july-2015" href="#user-content-loupe-01-5-july-2015"></a>
+
+- Initial release, extracted from my dotfiles (https://github.com/wincent/wincent).
+
+## Mappings<a name="loupe-mappings" href="#user-content-loupe-mappings"></a>
+
+### `<Plug>(LoupeClearHighlight)`<a name="loupe-plugloupeclearhighlight" href="#user-content-loupe-plugloupeclearhighlight"></a>
+
+Loupe maps <leader>n to <strong>[`<Plug>(LoupeClearHighlight)`](#user-content-plugloupeclearhighlight)</strong>, which clears all visible highlights (like <strong>`:nohighlight`</strong> does). To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
+
+```
+" Instead of <leader>n, use <leader>x.
+nmap <leader>x <Plug>(LoupeClearHighlight)
+```
+
+Note that Loupe will not try to set up its <leader>n mapping if any of the following are true:
+
+- A mapping for <leader>n already exists.
+- An alternative mapping for <strong>[`<Plug>(LoupeClearHighlight)`](#user-content-plugloupeclearhighlight)</strong> has already been set up from a <strong>`.vimrc`</strong>.
+- The mapping has been suppressed by setting <strong>`g:LoupeClearHighlightMap`</strong> to 1 in your <strong>`.vimrc`</strong>.
+
+## Options<a name="loupe-options" href="#user-content-loupe-options"></a>
+
+<p align="right"><a name="gloupehighlightgroup" href="#user-content-gloupehighlightgroup"><code>g:LoupeHighlightGroup</code></a></p>
+### `g:LoupeHighlightGroup` (string, default: IncSearch)<a name="loupe-gloupehighlightgroup-string-default-incsearch" href="#user-content-loupe-gloupehighlightgroup-string-default-incsearch"></a>
+
+Specifies the <strong>`:highlight`</strong> group used to emphasize the match currently under the cursor for the current search pattern. Defaults to "IncSearch" (ie. <strong>`hl-IncSearch`</strong>). For example:
+
+```
+let g:LoupeHighlightGroup='Error'
+```
+
+To prevent any special highlighting from being applied, set this option to "" (ie. the empty string).
+
+<p align="right"><a name="gloupeloaded" href="#user-content-gloupeloaded"><code>g:LoupeLoaded</code></a></p>
+### `g:LoupeLoaded` (any, default: none)<a name="loupe-gloupeloaded-any-default-none" href="#user-content-loupe-gloupeloaded-any-default-none"></a>
+
+To prevent Loupe from being loaded, set <strong>`g:LoupeLoaded`</strong> to any value in your <strong>`.vimrc`</strong>. For example:
+
+```
+let g:LoupeLoaded=1
+```
+
+<p align="right"><a name="gloupeclearhighlightmap" href="#user-content-gloupeclearhighlightmap"><code>g:LoupeClearHighlightMap</code></a></p>
+### `g:LoupeClearHighlightMap` (boolean, default: 1)<a name="loupe-gloupeclearhighlightmap-boolean-default-1" href="#user-content-loupe-gloupeclearhighlightmap-boolean-default-1"></a>
+
+Controls whether to set up the <strong>[`<Plug>(LoupeClearHighlight)`](#user-content-plugloupeclearhighlight)</strong> mapping. To prevent any mapping from being configured, set to 0:
+
+```
+let g:LoupeClearHighlightMap=0
+```
+
+<p align="right"><a name="gloupeverymagic" href="#user-content-gloupeverymagic"><code>g:LoupeVeryMagic</code></a></p>
+### `g:LoupeVeryMagic` (boolean, default: 1)<a name="loupe-gloupeverymagic-boolean-default-1" href="#user-content-loupe-gloupeverymagic-boolean-default-1"></a>
+
+Controls whether "very magic" pattern syntax (<strong>`/\v`</strong>) is applied by default. To disable, set to 0:
+
+```
+let g:LoupeVeryMagic=0
+```
+
+<p align="right"><a name="gloupecenterresults" href="#user-content-gloupecenterresults"><code>g:LoupeCenterResults</code></a></p>
+### `g:LoupeCenterResults` (boolean, default: 1)<a name="loupe-gloupecenterresults-boolean-default-1" href="#user-content-loupe-gloupecenterresults-boolean-default-1"></a>
+
+Controls whether the match's line is vertically centered within the window when jumping (via <strong>`n`</strong>, <strong>`N`</strong> etc). To disable, set to 0:
+
+```
+let g:LoupeCenterResults=0
+```
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..b6abbd7ea5bff42f06aab9ae7cc3dea13752e799 100644 (file)
@@ -0,0 +1,316 @@
+*loupe.txt*                      Loupe plug-in for Vim                     *loupe*
+
+CONTENTS                                                        *loupe-contents*
+
+1. Intro          |loupe-intro|
+2. Installation   |loupe-installation|
+3. Overrides      |loupe-overrides|
+4. Related        |loupe-related|
+5. Website        |loupe-website|
+6. License        |loupe-license|
+7. Development    |loupe-development|
+8. Authors        |loupe-authors|
+9. History        |loupe-history|
+10. Mappings      |loupe-mappings|
+11. Options       |loupe-options|
+
+INTRO                                                              *loupe-intro*
+
+    "loupe (noun)
+    a small magnifying glass used by jewelers and watchmakers."
+
+
+                                                                *loupe-features*
+Loupe enhances Vim's |search-commands| in four ways:
+
+1. Makes the currently selected match easier to see ~
+
+When searching using |/|, |?|, |star|, |#|, |n|, |N| or similar, it can be hard to see
+the "current" match from among all the matches that 'hlsearch' highlights.
+Loupe makes the currently selected match easier to see by:
+
+- Applying a different |:highlight| group (by default, |hl-IncSearch|) to the
+  match under the cursor.
+- Keeping the matching line centered within the window when jumping between
+  matches with |n| and |N|.
+
+2. Applies sane pattern syntax by default ~
+
+Loupe makes "very magic" (|/\v|) syntax apply by default when searching. This
+is true even if you initiate a search via a novel means, such as from a
+visual selection or with a complicated |:range| prefix.
+
+This means that you can use a pattern syntax closer to the familiar regular
+expression syntax from languages such as Perl, Ruby, JavaScript (indeed,
+most other modern languages that support regular expressions).
+
+3. Provides a shortcut to remove search highlighting ~
+
+Loupe maps <leader>n to quickly remove all 'hlsearch' highlighting (although
+you can provide an alternative mapping of your choosing or suppress the
+feature entirely).
+
+4. Sensible defaults for search-related features ~
+
+Loupe provides reasonable defaults for most search-related Vim settings to
+provide a good "out of the box" experience. For more details, or to see how
+to override Loupe's settings, see |loupe-overrides|.
+
+INSTALLATION                                                *loupe-installation*
+
+To install Loupe, use your plug-in management system of choice.
+
+If you don't have a "plug-in management system of choice", I recommend
+Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
+robustness. Assuming that you have Pathogen installed and configured, and
+that you want to install Loupe into `~/.vim/bundle`, you can do so with:
+>
+    git clone https://github.com/wincent/loupe.git ~/.vim/bundle/loupe
+<
+Alternatively, if you use a Git submodule for each Vim plug-in, you could do
+the following after `cd`-ing into the top-level of your Git superproject:
+>
+    git submodule add https://github.com/wincent/loupe.git ~/vim/bundle/loupe
+    git submodule init
+<
+To generate help tags under Pathogen, you can do so from inside Vim with:
+>
+    :call pathogen#helptags()
+<
+OVERRIDES                                                      *loupe-overrides*
+
+Loupe sets a number of search-related Vim settings to reasonable defaults in
+order to provide a good "out of the box" experience:
+
+
+                                                        *loupe-history-override*
+'history'
+
+Increased to 1000, to increase the number of previous searches remembered.
+Note that Loupe only applies this setting if the current value of 'history'
+is less than 1000.
+
+
+                                                       *loupe-hlsearch-override*
+'hlsearch'
+
+Turned on (when there is a previous search pattern, highlight all its
+matches).
+
+
+                                                      *loupe-incsearch-override*
+'incsearch'
+
+Turned on (while typing a search command, show where the pattern matches, as
+it was typed so far).
+
+
+                                                     *loupe-ignorecase-override*
+'ignorecase'
+
+Turned on (to ignore case in search patterns).
+
+
+                                                      *loupe-shortmess-override*
+'shortmess'
+
+Adds "s", which suppresses the display of "search hit BOTTOM, continuing at
+TOP" and "search hit TOP, continuing at BOTTOM" messages.
+
+
+                                                      *loupe-smartcase-override*
+'smartcase'
+
+Turned on (overrides 'ignorecase', making the search pattern case-sensitive
+whenever it containers uppercase characters).
+
+To override any of these choices, you can place overrides in an
+|after-directory| (ie. `~/.vim/after/plugin/loupe.vim`). For example:
+>
+     " Override Loupe's 'history' setting from 1000 to 10000.
+     set history=10000
+
+     " Reset Loupe's 'incsearch' back to Vim default.
+     set incsearch&vim
+
+     " Remove unwanted 's' from 'shortmess'.
+     set shortmess-=s
+<
+RELATED                                                          *loupe-related*
+
+Just as Loupe aims to improve the within-file search experience, Ferret does
+the same for multi-file searching and replacing:
+
+- https://github.com/wincent/ferret
+
+WEBSITE                                                          *loupe-website*
+
+The official Loupe source code repo is at:
+
+- http://git.wincent.com/loupe.git
+
+A mirror exists at:
+
+- https://github.com/wincent/loupe
+
+Official releases are listed at:
+
+- http://www.vim.org/scripts/script.php?script_id=5215
+
+LICENSE                                                          *loupe-license*
+
+Copyright 2015-present Greg Hurrell. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+DEVELOPMENT                                                  *loupe-development*
+
+Contributing patches ~
+
+Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
+at: https://github.com/wincent/loupe/pulls
+
+Cutting a new release ~
+
+At the moment the release process is manual:
+
+- Perform final sanity checks and manual testing
+- Update the |loupe-history| section of the documentation
+- Verify clean work tree:
+>
+    git status
+<
+- Tag the release:
+>
+    git tag -s -m "$VERSION release" $VERSION
+<
+- Publish the code:
+>
+    git push origin master --follow-tags
+    git push github master --follow-tags
+<
+- Produce the release archive:
+>
+    git archive -o loupe-$VERSION.zip HEAD -- .
+<
+- Upload to http://www.vim.org/scripts/script.php?script_id=5215
+
+AUTHORS                                                          *loupe-authors*
+
+Loupe is written and maintained by Greg Hurrell <greg@hurrell.net>.
+
+The original idea for the |g:LoupeHighlightGroup| feature was taken from
+Damian Conway's Vim set-up:
+
+-
+
+  https://github.com/thoughtstream/Damian-Conway-s-Vim-Setup/blob/master/plugin/hlnext.vim
+
+Which he discussed in his "More Instantly Better Vim" presentation at OSCON
+2013:
+
+- https://www.youtube.com/watch?v=aHm36-na4-4
+
+HISTORY                                                          *loupe-history*
+
+1.0 (28 December 2015) ~
+
+- Renamed the |<Plug>LoupeClearHighlight| mapping to
+  |<Plug>(LoupeClearHighlight)|.
+
+0.1 (5 July 2015) ~
+
+- Initial release, extracted from my dotfiles
+  (https://github.com/wincent/wincent).
+
+MAPPINGS                                                        *loupe-mappings*
+
+
+                                                   *<Plug>(LoupeClearHighlight)*
+Loupe maps <leader>n to |<Plug>(LoupeClearHighlight)|, which clears all
+visible highlights (like |:nohighlight| does). To use an alternative mapping
+instead, create a different one in your |.vimrc| instead using |:nmap|:
+>
+    " Instead of <leader>n, use <leader>x.
+    nmap <leader>x <Plug>(LoupeClearHighlight)
+<
+Note that Loupe will not try to set up its <leader>n mapping if any of the
+following are true:
+
+- A mapping for <leader>n already exists.
+- An alternative mapping for |<Plug>(LoupeClearHighlight)| has already been
+  set up from a |.vimrc|.
+- The mapping has been suppressed by setting |g:LoupeClearHighlightMap| to 1
+  in your |.vimrc|.
+
+OPTIONS                                                          *loupe-options*
+
+
+                                                         *g:LoupeHighlightGroup*
+|g:LoupeHighlightGroup|                              string (default: IncSearch)
+
+Specifies the |:highlight| group used to emphasize the match currently under
+the cursor for the current search pattern. Defaults to "IncSearch" (ie.
+|hl-IncSearch|). For example:
+>
+    let g:LoupeHighlightGroup='Error'
+<
+To prevent any special highlighting from being applied, set this option to
+"" (ie. the empty string).
+
+
+                                                                 *g:LoupeLoaded*
+|g:LoupeLoaded|                                              any (default: none)
+
+To prevent Loupe from being loaded, set |g:LoupeLoaded| to any value in your
+|.vimrc|. For example:
+>
+    let g:LoupeLoaded=1
+<
+
+                                                      *g:LoupeClearHighlightMap*
+|g:LoupeClearHighlightMap|                                  boolean (default: 1)
+
+Controls whether to set up the |<Plug>(LoupeClearHighlight)| mapping. To
+prevent any mapping from being configured, set to 0:
+>
+    let g:LoupeClearHighlightMap=0
+<
+
+                                                              *g:LoupeVeryMagic*
+|g:LoupeVeryMagic|                                          boolean (default: 1)
+
+Controls whether "very magic" pattern syntax (|/\v|) is applied by default. To
+disable, set to 0:
+>
+    let g:LoupeVeryMagic=0
+<
+
+                                                          *g:LoupeCenterResults*
+|g:LoupeCenterResults|                                      boolean (default: 1)
+
+Controls whether the match's line is vertically centered within the window
+when jumping (via |n|, |N| etc). To disable, set to 0:
+>
+    let g:LoupeCenterResults=0
+<
index bae7bb5eb674c5b4f5552f31f2f8ca355cc2261b..c14a7c9ea78683eafd1eb8f666a60f4d8505f996 100644 (file)
@@ -100,8 +100,18 @@ endfunction
 
 " Apply highlighting to the current search match.
 function! loupe#private#hlmatch() abort
-  " When g:loupeHighlight is set (and it is set to "IncSearch" by default), use
-  " that highlight group to make the current search result stand out.
+  ""
+  " @option g:LoupeHighlightGroup string IncSearch
+  " Specifies the |:highlight| group used to emphasize the match currently under
+  " the cursor for the current search pattern. Defaults to "IncSearch" (ie.
+  " |hl-IncSearch|). For example:
+  "
+  " ```
+  " let g:LoupeHighlightGroup='Error'
+  " ```
+  "
+  " To prevent any special highlighting from being applied, set this option to
+  " "" (ie. the empty string).
   let l:highlight=get(g:, 'LoupeHighlightGroup', 'IncSearch')
   if empty(l:highlight)
     return
index f3991218e74cdc18d1454255542930b777f54839..befb973145a137ac5afcd6376dfad04d292297e3 100644 (file)
@@ -1,8 +1,261 @@
 " Copyright 2015-present Greg Hurrell. All rights reserved.
 " Licensed under the terms of the BSD 2-clause license.
 
-" Provide users with means to prevent loading, as recommended in `:h
-" write-plugin`.
+""
+"
+" @plugin loupe Loupe plug-in for Vim
+"
+" # Intro
+"
+" > "loupe (noun)<br>
+" > a small magnifying glass used by jewelers and watchmakers."
+"
+"                                                               *loupe-features*
+" Loupe enhances Vim's |search-commands| in four ways:
+"
+" ## 1. Makes the currently selected match easier to see
+"
+" When searching using |/|, |?|, |star|, |#|, |n|, |N| or similar, it can be
+" hard to see the "current" match from among all the matches that 'hlsearch'
+" highlights. Loupe makes the currently selected match easier to see by:
+"
+" - Applying a different |:highlight| group (by default, |hl-IncSearch|) to the
+"   match under the cursor.
+" - Keeping the matching line centered within the window when jumping between
+"   matches with |n| and |N|.
+"
+" ## 2. Applies sane pattern syntax by default
+"
+" Loupe makes "very magic" (|/\v|) syntax apply by default when searching. This
+" is true even if you initiate a search via a novel means, such as from a visual
+" selection or with a complicated |:range| prefix.
+"
+" This means that you can use a pattern syntax closer to the familiar regular
+" expression syntax from languages such as Perl, Ruby, JavaScript (indeed, most
+" other modern languages that support regular expressions).
+"
+" ## 3. Provides a shortcut to remove search highlighting
+"
+" Loupe maps <leader>n to quickly remove all 'hlsearch' highlighting (although
+" you can provide an alternative mapping of your choosing or suppress the
+" feature entirely).
+"
+" ## 4. Sensible defaults for search-related features
+"
+" Loupe provides reasonable defaults for most search-related Vim settings to
+" provide a good "out of the box" experience. For more details, or to see how to
+" override Loupe's settings, see |loupe-overrides|.
+"
+"
+" # Installation
+"
+" To install Loupe, use your plug-in management system of choice.
+"
+" If you don't have a "plug-in management system of choice", I recommend
+" Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
+" robustness. Assuming that you have Pathogen installed and configured, and that
+" you want to install Loupe into `~/.vim/bundle`, you can do so with:
+"
+" ```
+" git clone https://github.com/wincent/loupe.git ~/.vim/bundle/loupe
+" ```
+"
+" Alternatively, if you use a Git submodule for each Vim plug-in, you could do
+" the following after `cd`-ing into the top-level of your Git superproject:
+"
+" ```
+" git submodule add https://github.com/wincent/loupe.git ~/vim/bundle/loupe
+" git submodule init
+" ```
+"
+" To generate help tags under Pathogen, you can do so from inside Vim with:
+"
+" ```
+" :call pathogen#helptags()
+" ```
+"
+" # Overrides
+"
+" Loupe sets a number of search-related Vim settings to reasonable defaults in
+" order to provide a good "out of the box" experience:
+"
+" @indent
+"                                                        *loupe-history-override*
+"   'history'
+"
+"   Increased to 1000, to increase the number of previous searches remembered.
+"   Note that Loupe only applies this setting if the current value of 'history'
+"   is less than 1000.
+"
+"                                                       *loupe-hlsearch-override*
+"   'hlsearch'
+"
+"   Turned on (when there is a previous search pattern, highlight all its
+"   matches).
+"
+"                                                      *loupe-incsearch-override*
+"   'incsearch'
+"
+"   Turned on (while typing a search command, show where the pattern matches, as
+"   it was typed so far).
+"
+"                                                     *loupe-ignorecase-override*
+"   'ignorecase'
+"
+"   Turned on (to ignore case in search patterns).
+"
+"                                                      *loupe-shortmess-override*
+"   'shortmess'
+"
+"   Adds "s", which suppresses the display of "search hit BOTTOM, continuing at
+"   TOP" and "search hit TOP, continuing at BOTTOM" messages.
+"
+"                                                      *loupe-smartcase-override*
+"   'smartcase'
+"
+"   Turned on (overrides 'ignorecase', making the search pattern case-sensitive
+"   whenever it containers uppercase characters).
+"
+" @dedent
+"
+" To override any of these choices, you can place overrides in an
+" |after-directory| (ie. `~/.vim/after/plugin/loupe.vim`). For example:
+"
+" ```
+" " Override Loupe's 'history' setting from 1000 to 10000.
+" set history=10000
+"
+" " Reset Loupe's 'incsearch' back to Vim default.
+" set incsearch&vim
+"
+" " Remove unwanted 's' from 'shortmess'.
+" set shortmess-=s
+" ```
+"
+" # Related
+"
+" Just as Loupe aims to improve the within-file search experience, Ferret does
+" the same for multi-file searching and replacing:
+"
+" - https://github.com/wincent/ferret
+"
+" # Website
+"
+" The official Loupe source code repo is at:
+"
+" - http://git.wincent.com/loupe.git
+"
+" A mirror exists at:
+"
+" - https://github.com/wincent/loupe
+"
+" Official releases are listed at:
+"
+" - http://www.vim.org/scripts/script.php?script_id=5215
+"
+"
+" # License
+"
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+"
+" Redistribution and use in source and binary forms, with or without
+" modification, are permitted provided that the following conditions are met:
+"
+" 1. Redistributions of source code must retain the above copyright notice,
+"    this list of conditions and the following disclaimer.
+"
+" 2. Redistributions in binary form must reproduce the above copyright notice,
+"    this list of conditions and the following disclaimer in the documentation
+"    and/or other materials provided with the distribution.
+"
+" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+" POSSIBILITY OF SUCH DAMAGE.
+"
+"
+" # Development
+"
+" ## Contributing patches
+"
+" Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
+" at: https://github.com/wincent/loupe/pulls
+"
+" ## Cutting a new release
+"
+" At the moment the release process is manual:
+"
+" - Perform final sanity checks and manual testing
+" - Update the |loupe-history| section of the documentation
+" - Verify clean work tree:
+"
+" ```
+" git status
+" ```
+"
+" - Tag the release:
+"
+" ```
+" git tag -s -m "$VERSION release" $VERSION
+" ```
+"
+" - Publish the code:
+"
+" ```
+" git push origin master --follow-tags
+" git push github master --follow-tags
+" ```
+"
+" - Produce the release archive:
+"
+" ```
+" git archive -o loupe-$VERSION.zip HEAD -- .
+" ```
+"
+" - Upload to http://www.vim.org/scripts/script.php?script_id=5215
+"
+" # Authors
+"
+" Loupe is written and maintained by Greg Hurrell <greg@hurrell.net>.
+"
+" The original idea for the |g:LoupeHighlightGroup| feature was taken from
+" Damian Conway's Vim set-up:
+"
+" - https://github.com/thoughtstream/Damian-Conway-s-Vim-Setup/blob/master/plugin/hlnext.vim
+"
+" Which he discussed in his "More Instantly Better Vim" presentation at OSCON
+" 2013:
+"
+" - https://www.youtube.com/watch?v=aHm36-na4-4
+"
+" # History
+"
+" ## 1.0 (28 December 2015)
+"
+" - Renamed the |<Plug>LoupeClearHighlight| mapping to
+"   |<Plug>(LoupeClearHighlight)|.
+"
+" ## 0.1 (5 July 2015)
+"
+" - Initial release, extracted from my dotfiles
+"   (https://github.com/wincent/wincent).
+
+""
+" @option g:LoupeLoaded any
+"
+" To prevent Loupe from being loaded, set |g:LoupeLoaded| to any value in your
+" |.vimrc|. For example:
+"
+" ```
+" let g:LoupeLoaded=1
+" ```
 if exists('g:LoupeLoaded') || &compatible || v:version < 700
   finish
 endif
@@ -24,13 +277,42 @@ set ignorecase   " Ignore case when searching.
 set shortmess+=s " Don't echo search wrap messages.
 set smartcase    " Case-sensitive search if search string includes a capital letter.
 
-" Map <leader>n to clear search highlighting.
+""
+" @option g:LoupeClearHighlightMap boolean 1
+"
+" Controls whether to set up the |<Plug>(LoupeClearHighlight)| mapping. To
+"  prevent any mapping from being configured, set to 0:
+"
+" ```
+" let g:LoupeClearHighlightMap=0
+" ```
 let s:map=get(g:, 'LoupeClearHighlightMap', 1)
 if s:map
   if !hasmapto('<Plug>(LoupeClearHighlight)') && maparg('<leader>n', 'n') ==# ''
     nmap <silent> <unique> <leader>n <Plug>(LoupeClearHighlight)
   endif
 endif
+
+""
+" @mapping <Plug>(LoupeClearHighlight)
+"
+" Loupe maps <leader>n to |<Plug>(LoupeClearHighlight)|, which clears all
+" visible highlights (like |:nohighlight| does). To use an alternative mapping
+" instead, create a different one in your |.vimrc| instead using |:nmap|:
+"
+" ```
+" " Instead of <leader>n, use <leader>x.
+" nmap <leader>x <Plug>(LoupeClearHighlight)
+" ```
+"
+" Note that Loupe will not try to set up its <leader>n mapping if any of the
+" following are true:
+"
+" - A mapping for <leader>n already exists.
+" - An alternative mapping for |<Plug>(LoupeClearHighlight)| has already been set
+"   up from a |.vimrc|.
+" - The mapping has been suppressed by setting |g:LoupeClearHighlightMap| to 1
+"   in your |.vimrc|.
 nnoremap <silent> <Plug>(LoupeClearHighlight)
       \ :nohlsearch<CR>
       \ :call loupe#private#clear_highlight()<CR>
@@ -45,8 +327,15 @@ cabbrev <silent> <expr> nohlsear (getcmdtype() == ':' && getcmdpos() == 9 ? 'noh
 cabbrev <silent> <expr> nohlsearc (getcmdtype() == ':' && getcmdpos() == 10 ? 'nohlsearc <bar> call loupe#private#clear_highlight()<CR>' : 'nohlsearc')
 cabbrev <silent> <expr> nohlsearch (getcmdtype() == ':' && getcmdpos() == 11 ? 'nohlsearch <bar> call loupe#private#clear_highlight()<CR>' : 'nohlsearch')
 
-" When g:LoupeVeryMagic is true (and it is by default), make Vim's regexen more
-" Perl-like.
+""
+" @option g:LoupeVeryMagic boolean 1
+"
+" Controls whether "very magic" pattern syntax (|/\v|) is applied by default.
+" To disable, set to 0:
+"
+" ```
+" let g:LoupeVeryMagic=0
+" ```
 function s:MagicString()
   let s:magic=get(g:, 'LoupeVeryMagic', 1)
   return s:magic ? '\v' : ''
@@ -60,8 +349,15 @@ if !empty(s:MagicString())
   cnoremap <expr> / loupe#private#very_magic_slash()
 endif
 
-" When g:LoupeCenterResults is true (and it is by default), remain vertically
-" centered when moving to next/previous search.
+""
+" @option g:LoupeCenterResults boolean 1
+"
+" Controls whether the match's line is vertically centered within the window
+" when jumping (via |n|, |N| etc). To disable, set to 0:
+"
+" ```
+" let g:LoupeCenterResults=0
+" ```
 let s:center=get(g:, 'LoupeCenterResults', 1)
 let s:center_string=s:center ? 'zz' : ''