Skip to content

Commit

Permalink
Version 1.2
Browse files Browse the repository at this point in the history 
- major rewrite
- added a new buffer-local menu
- catered for autoload bundles
- performance optimisations
- several bug fixes and improvements
- dropped autocmds altogether
- reintroduced functions as an optional bundle category
- cleaned up configuration options
- added missing mapping types
- removed the 'occurrences' help option
- updated reference docs
  • Loading branch information
@mbadran @vim-scripts
mbadran authored and vim-scripts committed Jul 15, 2011
1 parent ac362d8 commit 8309464
Show file tree
Hide file tree
Showing 10 changed files with 897 additions and 668 deletions.
12 changes: 8 additions & 4 deletions README
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
This is a mirror of http://www.vim.org/scripts/script.php?script_id=3455

Headlights is a Vim plugin that creates a TextMate like Bundles menu.
Headlights adds a 'Bundles' menu to Vim, revealing your bundles (aka. plugins) and the features they provide.

Headlights sheds light on what plugins are installed and how to use them. It creates a menu for each plugin, scraping together docs, commands, mappings, abbreviations, functions, and script files.
Headlights creates a menu for each _currently loaded_ bundle, grouping together docs, commands, mappings, abbreviations, functions, and script files.

Combined with a powerful bundle manager like Vundle, Headlights will improve your Vim user experience.
Combined with a powerful bundle manager, Headlights will improve your Vim user experience -- nay, your quality of life.

Here, have a screenshot: https://github.com/mbadran/headlights/raw/master/headlights_ss.png

See the GitHub repository for more details: https://github.com/mbadran/headlights
For development activity, see the GitHub repository: https://github.com/mbadran/headlights

For further reading, see the Headlights help menu:

Bundles > a - i > headlights > Help
83 changes: 25 additions & 58 deletions README.mkd
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,23 @@
# If you use Vim, you need Headlights
![Headlights in Action][2]

- Do you find it difficult to keep track of what [Vim] [1] plugins (aka bundles) you've installed?
Headlights adds a `Bundles` menu to Vim, revealing your bundles (aka. plugins)
and the features they provide.

- Have you ever installed a plugin, only to get stuck when actually trying to use it?
Headlights creates a menu for each _currently loaded_ bundle, grouping
together docs, commands, mappings, abbreviations, functions, and script files.

- Do you rely on Google for reference more than plugin docs?
Combined with a powerful bundle manager, Headlights will improve your ~~Vim
user experience~~ quality of life.

If your answer to any of those questions is "Yes", "All the time!", or "Vim, is that like a scooter?" -- Headlights is for you.
Get Headlights
==============

# What is Headlights?
__NOTE:__ Headlights requires Vim 7+ compiled with Python 2.6+ support.

Headlights is a Vim plugin that creates a [TextMate] [2] like _Bundles_ menu.
The Recommended Way
-------------------

Headlights sheds light on what plugins are installed and how to use them. It creates a menu for each plugin, scraping together docs, commands, mappings, abbreviations, functions, and script files.

Combined with a powerful bundle manager like [Vundle] [3], Headlights will improve your ~~Vim user experience~~ quality of life.

Here, have a [screenshot] [4].

# How to install Headlights

NOTE: Headlights requires a graphical version of Vim with Python support.

## The Vundle Way
Using [Vundle] [3]:

1. Add the following line to the Vundle section in your `.vimrc`:

Expand All @@ -32,56 +27,28 @@ NOTE: Headlights requires a graphical version of Vim with Python support.

`BundleInstall`

## The manual way

1. Download the source archive from [GitHub] [5].

2. Expand the contents of the Headlights plugin directory into your `.vim/plugin/` directory.

3. Launch Vim.

# What to do when Headlights fails

Headlights is an ambitious plugin. It tries to handle any plugin, on any version of Vim, on any operating system. There are bound to be combinations that evade testing.
The Manual Way
--------------

If you encounter any errors, please let me know. You'll be helping improve Headlights and making history in the process.
1. [Download the latest package] [4].

Typically, you'll see an error when you launch Vim, which you can retrieve with the following Vim command:
2. Expand the archive into your `.vim` directory.

`messages`
3. Run the following Vim command:

At the very least, please email me the error message (mebadran AT gmail). But preferably, please take a couple of minutes to raise an issue.
`helptags ~/.vim/doc/`

## How to raise an issue
Further Reading
===============

1. Add the following line to your `.gvimrc`:
- Refer to the Headlights help menu:

`let g:headlights_debug = 1`

2. Launch Vim.

3. Find the Headlights debug log in the `Bundles > debug` menu (or wherever you've defined your Headlights root menu).

4. Upload the debug log to the Web (for eg. [Pastebin] [6]).

5. Raise a new [issue] [7] for the error, referencing the debug log.

(When you're done, remove the debug line from your `.gvimrc`.)

I also welcome any [pull requests] [8], so feel free to contribute.
`Bundles > a - i > headlights > Help`

[1]: http://www.vim.org/

[2]: http://macromates.com/
[2]: https://github.com/mbadran/headlights/raw/master/headlights_ss.png

[3]: https://github.com/gmarik/vundle

[4]: https://github.com/mbadran/headlights/raw/master/headlights_ss.png

[5]: https://github.com/mbadran/headlights/archives/master

[6]: http://pastebin.com/

[7]: https://github.com/mbadran/headlights/issues

[8]: http://help.github.com/fork-a-repo/
[4]: https://github.com/mbadran/headlights/archives/master
205 changes: 205 additions & 0 deletions doc/headlights.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
*headlights.txt* Know Thy Bundles


@@@@@@ @@@@@@
@@!-#@@@ @@!#-@@@
@!@#-!@! H·E·A·D·L·I·G·H·T·S @!@-#!@!
!!:-#!!! !!:#-!!!
: :. : : :. :


==============================================================================
CONTENTS *headlights*

1. Introduction _______________________________________ |headlights-intro|
2. Options __________________________________________ |headlights-options|
3. Issues ____________________________________________ |headlights-issues|
4. About ______________________________________________ |headlights-about|
5. Changelog ______________________________________ |headlights-changelog|
6. TODO ________________________________________________ |headlights-todo|
7. License __________________________________________ |headlights-license|

==============================================================================
INTRODUCTION *headlights-intro*

Headlights adds a 'bundles' menu [1] to Vim, revealing your bundles (aka.
plugins) and the features they provide.

Headlights creates a menu for each currently loaded [2] bundle, grouping
together docs, commands, mappings, abbreviations, functions, and script files.

Combined with a powerful bundle manager, Headlights will improve your Vim user
experience -- nay, your quality of life.

------------------------------------------------------------------------------

[1]: Headlights is inspired by TextMate's Bundles menu.

[2]: Headlights mirrors Vim's 'scriptnames' command, revealing only the
bundles that are currently loaded. This is fast because it avoids file
system access, but the trade off is that autoload bundles are not
revealed until they are, well, autoloaded. (This is acceptable.)

==============================================================================
OPTIONS *headlights-options*

Note: For performance reasons, only 'commands' and 'mappings' are enabled by
default. See |headlights-issues| for details.

*headlights_use_plugin_menu*

Reuse the conventional 'plugin' menu instead of creating a new one: >

let g:headlights_use_plugin_menu = 1
<
Default value: 0

*headlights_show_files*

Create menus for bundle script files: >

let g:headlights_show_files = 1
<
Default value: 0

*headlights_show_commands*

Create menus for bundle commands: >

let g:headlights_show_commands = 1
<
Default value: 1

*headlights_show_mappings*

Create menus for bundle mappings: >

let g:headlights_show_mappings = 1
<
Default value: 1

*headlights_show_abbreviations*

Create menus for bundle abbreviations: >

let g:headlights_show_abbreviations = 1
<
Default value: 0

*headlights_show_functions*

Create menus for global bundle functions: >

let g:headlights_show_functions = 1
<
Default value: 0

*headlights_debug_mode*

Enable debug mode and create menus to access the log file: >

let g:headlights_debug_mode = 1
<
Default value: 0 (1 in the event of a Headlights exception)

Note: If you manually enable this option, remember to disable it after
troubleshooting, or log files will be generated very time you enter a buffer,
impacting performance and disk space.

==============================================================================
ISSUES *headlights-issues*

When |headlights_debug_mode| is enabled -- either because you enabled it or
because a critical error occurred -- a 'debug' menu will appear under the
Headlights menu. This will give you access to the Headlights debug log, which
has all the information needed to troubleshoot any problems.

In the event of a problem, please raise a new project issue at:

<https://github.com/mbadran/headlights/issues>

Be sure to reference the debug log. You can upload it to a paste service like
<http://pastebin.com>.

Lastly, I welcome any pull requests, so feel free to Fork, Fix, Send.

A NOTE ON PERFORMANCE

Headlights can slow Vim down when a large number of bundles are loaded, or
when hardware resources are limited. Because of this, most configuration
options are disabled by default.

If you experience slowness when launching Vim or switching buffers, disable
some or all configuration options, and consider troubleshooting further or
raising a project issue.

==============================================================================
ABOUT *headlights-about*

Project development is hosted at <https://github.com/mbadran/headlights>.

Official releases are tagged with their version numbers, and simultaneously
hosted at Vim.org:

<http://www.vim.org/scripts/script.php?script_id=3455>

Send feedback and untold riches to mebadran _AT_ gmail.

==============================================================================
7. Changelog *headlights-changelog*

1.2
- major rewrite
- added a new buffer-local menu
- catered for autoload bundles
- performance optimisations
- several bug fixes and improvements
- dropped autocmds altogether
- reintroduced functions as an optional bundle category
- cleaned up configuration options
- added missing mapping types
- removed the 'occurrences' help option
- updated reference docs

1.1
- streamlined the menu layout
- fixed the debug mode feature
- added a debug menu for debug mode
- added an 'occurrences' help option (:helpgrep)
- moved vim plugins/bundles to their own menu (runtime)
- fixed several minor issues
- refactored and cleaned up code

1.0
- initial release

==============================================================================
TODO *headlights-todo*

- the bundles menu currently gets out of order when autoload bundles are
handled. this is because the menu is not entirely reset -- only new items
are added below. to fix this, either provide a command to redo all the
menus, have a periodic on timeout fix, or change the menu layout to submenus
only (which is uglier and less convenient).

- group bundles by parent. vim does not currently do this, nor does
headlights. install syntastic for an example.

headlights can identify associated bundles if they share a common path, but
this requires some checks, and a 'parent' field will probably have to be
added to bundles. this may impact performance, and it should be optional.

- more performance optimisation on the default settings

- more testing, especially for linux and windows

MAYBE

- add a new bundle category: highlight (:verbose highlight)

- bring back autocmds as an optional bundle category (:verbose autocmd)

==============================================================================
9. License *headlights-license*

Headlights is released in the public domain.
Binary file removed headlights_ss.png
View file
Binary file not shown.
Loading

0 comments on commit 8309464

Please sign in to comment.