*preamble.txt*	Folding preamble comments		         *preamble* *Preamble*

Author:         Mel Davis <ZZmeldavisZZ@ZZsignals.selfip.orgZZ> (remove 'Z's)
Last Change:    Nov 2, 2014

Plugin Version: 0.1

Requires:
    Vim:        7.2 and above (not tested on earlier versions)
    Plugins:    none

==============================================================================
CONTENTS~

    1. Purpose
    2. What it does
    3. Interface
    4. Options
    5. Installation
    6. Copyright
    7. ChangeLog

==============================================================================
PURPOSE~

This plugin will automatically fold long preambles, such as GPL copyright
notices, located at the head of source files.  You may find it helpful if,
like me, you use syntax folding infrequently.

Very often, I read third-party library sources and examples, such as Nokia's
Qt library, various GNU utilities, and many others.  I want to see the
functions and read the comments but not the 50 lines of licensing and
copyright notices that head every file. Because these are third-party
sources, I do not want to modify the files to include Vim fold markers.

==============================================================================
WHAT IT DOES~

This plugin does not use fold markers and does not modify files.
It adds the fold by changing the foldmethod to "manual" and inserting a
manual fold.

If the foldmethod is 'syntax', the plugin will do nothing except try to
close the fold on line 1, if one exists.  No fold is created and the
foldmethod is not changed.

The preamble has to start at the top of the file, but may be preceded by
empty lines.  It will consist of leading blank lines followed by lines
with comments starting in column one. The preamble will stop at the first line
not having a comment in the first column.

Note: If the preamble uses 'c' style comments without a border of characters
in column 1 the preamble will not be folded.


==============================================================================
INTERFACE~

Preamble#Enable(filetypes)                          *Preamble#Enable*

    * Enables automatic preamble folding for specified file types.
    * If filetypes = "*", the plugin is enabled for all file types.
    * An empty string will disable the plugin.

Preamble#Fold()                                     *Preamble#Fold*

    * If a fold at line 1 already exists, it will close it and return.
    * When foldmethod is not 'syntax', it will change the foldmethod
      to 'manual' and create a manual fold.


==============================================================================
OPTIONS~

All options have default values, which the user can change both globally and
on a per buffer basis.  The buffer options may be helpful when used along
with some other plugins such as "project" by Aric Blumer.

Prefix the options below with either 'g:' or 'b:'. Buffer options take
precedence over global.

------------------------------------------------------------------------------
                                                 *preamble_min_lines*

preamble_min_lines:  Sets the minimum size of a preamble.

    Type:       Integer
    Default:    25

    If the preamble size is less, no fold will be created.

------------------------------------------------------------------------------
                                                 *preamble_max_lines*

preamble_max_lines:  Sets the maximum size of a preamble.

    Type:       Integer
    Default:    150

    The plugin will not scan beyond this row in the source file.
    If the preamble is longer than max_lines, the behavior is
    determined by the |preamble_fold_partial| option.

------------------------------------------------------------------------------
                                                 *preamble_fold_partial*

preamble_fold_partial:  Permits the folding of partial preambles
                        when their length exeeds max lines.

    Type:       Integer
    Default:    0

    If this option is non-zero, the first 'max-lines' of a
    too-long preamble will be folded. Otherwise, no fold will be
    created.
------------------------------------------------------------------------------
                                                 *preamble_disable_thisbuffer*

b:preamble_disable_thisbuffer:  Disables preamble folding
                                for the buffer.

    Type:       Integer

   This option is only available for buffers.  Set to a
   non-zero value to disable preamble folding for this buffer.
   To disable plugin globally, call |Preamble#Enable| with an
   empty string.  This option may be helpful when used with
   other plugins such as "project" by Aric Blumer.


==============================================================================
INSTALLATION~

Files installed:
    autoload/Preamble.vim
    doc/Preamble.txt

Examples of .vimrc additions: >
    call Preamble#Enable('cpp,java')    # to enable
    let g:preamble_min_lines=35         # if you want other than default
<

==============================================================================
COPYRIGHT~

Public domain.

==============================================================================
CHANGELOG~

01/04/2010  Initial release

vim:tw=78:sw=4:ft=help:norl: