*timestamp.vim*		Plugin for automated time stamping

Description:~

When a file is written, and the filename matches |timestamp_automask|, this
plugin will search the first and last |timestamp_modelines| lines of your
file. If it finds the regexp |timestamp_regexp| then it will replace it with a
timestamp. The timestamp is computed by first doing a |token_substitution| on
|timestamp_rep| and passing the result to |strftime()|. 

The plugin tries to stay out of your way, and make the change as transparent
as possible. All your history (search, command, etc) and the jump list is
unaltered, except the undo history (which possibly contains an additional
change).

All the default variables and actions can be changed by buffer / global vim
variables. See |timestamp_examples| for two simple examples.

The plugin and its documentation file can be installed as described under
|add-global-plugin| and |add-local-help|. Do not forget to run |:helptags|.

------------------------------------------------------------------------------
Options and Specifications:~
							
1. Timestamp Regexp format:				*timestamp_regexp*

If the regexp |timestamp_regexp| is found in the first and last
|timestamp_modelines| lines of your file it is replaced by a timestamp (see
|timestamp_rep|). The default is set to >

    \v\C%(<%(Last %([cC]hanged?|modified)|Modified)\s*:\s+)@<=\a+ \d{2} \a+ \d{4} \d{2}:\d{2}:\d{2}%(\s+[AP]M)?%(\s+\a+)?|TIMESTAMP

which will EITHER match 'TIMESTAMP' or a time (in the format of
strftime("%c")) FOLLOWED by a 'Last changed:', 'Last modified:', 'Modified:'.
(Spaces before and after the : don't matter). For instance, if you create a
new file and want to stamp it with a creation date and a last modified date,
make the first few lines: >

    Created  : TIMESTAMP
    Modified : TIMESTAMP

When you first write the file, these lines will change to: >

    Created  : Thu 26 Feb 2004 03:15:54 PM CST
    Modified : Thu 26 Feb 2004 03:15:54 PM CST

On subsequent writes of the file, the first line will remain unchanged and the
second will be stamped with the time of writing.

To change this value, either set g:timestamp_regexp in your {.vimrc} or set
b:timestamp_regexp for the buffer in question. NOTE: This global variable must
be set before the plugin is loaded. HOWEVER the buffer local variable can be
set at any time.

NOTE: Forward slashes are automatically escaped.

NOTE: The first line (beginning with "Created:") is optional.

NOTE: If you find that on subsequent writes of the file, the second line is
also unchanged, it is probably because the time returned by strftime is NOT is
the format above. Common reasons for this are if there is a leading 0 or
timezone missing, or if the day / month in your language has accented
characters. If you are using version 1.20 and higher and still have this
problem, please report it to me. As a temporary fix, you can put the line >

    let timestamp_regexp = '\v\C%(<Last %([cC]hanged?|[Mm]odified):\s+)@<=.*$'

in your .vimrc. This however has the disadvantage of eating all the text after
the colon in any timestamp line.

NOTE: Windows Users. If you find that the timezone is in full form instead of
abbriviated (i.e. 'Chicago Standard Time' instead of 'CST') then look at >

    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt__tzset.asp

for details on how to change it (thanks to Shishir Ramam for pointing this
out). If you preffer using the full form timezone, then add the line >

    let s:timestamp_regexp = s:getValue('\v\C%(<Last %([cC]hanged?|[mM]odified)\s*:\s+)@<=\a+ \d{2} \a+ \d{4} \d{2}:\d{2}:\d{2} %[AP]M%(\a|\s)*|TIMESTAMP', 'g:timestamp_regexp')

to your .vimrc. You could also just remove the '%Z' from |timestamp_rep| if
you don't want the timezone at all.

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

2. Timestamp Replacement format:			*timestamp_rep*

The timestamp is computed by first doing a |token_substitution| on
|timestamp_rep| and passing the result to |strftime()|.

Default: '%a %d %b %Y %I:%M:%S %p %Z'
    [On Linux systems this is equivalent to the preferd date and time
    representation for the current locale.]

To change this value, either set g:timestamp_rep in your {.vimrc} or set
b:timestamp_rep for the buffer in question. NOTE: This global variable must be
set before the plugin is loaded. HOWEVER the buffer local variable can be set
at any time.

NOTE: Forward slashes are automatically escaped.
------------------------------------------------------------------------------

TOKEN SUBSTITUTION                                        *token_substitution*

Before being passed to |strftime()|, |timestamp_rep| undergoes the following
substitutions:

    Token	Substitution~
    #f		|timestamp_filename|
    #h		|timestamp_hostname|
    #H		|timestamp_Hostname|
    #u		|timestamp_username|
    #i		|timestamp_userid|

							  *timestamp_filename*
    The "#f" token is replaced by the filename of the current buffer (without
    leading path components).

							  *timestamp_Hostname*
    The #H token is replaced by the full hostname  of the current vim process.
   
    If the variable |timestamp_UseSystemCalls| is set, the default value of
    the hostname will be obtained from the output of the command 'hostname
    -f'. If that fails, (or |timestamp_UseSystemCalls| is not set), the value
    of the $HOSTNAME or $HOST variables will be used. If they are both empty,
    then the value of the |hostname()| function will be used.

    If the default value is incorrect, or you want to use a different value,
    simply set the global variable 'g:timestamp_Hostname', or the buffer local
    variable 'b:timestamp_Hostname' to the desired value. NOTE: This global
    variable must be set before the plugin is loaded, however the buffer local
    variable can be set at any time.

							  *timestamp_hostname*
    The #h is the same as the #H token, but with the domain name stripped.
    User defined values can be specified using the variables
    g:timestamp_hostname or b:timestamp_hostname. See the note above about
    global / local variables.

							  *timestamp_username*
    The #u token will be replaced by the user name.
    
    The default value of the user name will be obtained from $USER or $LOGNAME
    environment variables. If both are empty (undefined) and the variable
    |timestamp_UseSystemCalls| is set, then the output of the command 'id -un'
    will be used.

    If the default value is incorrect, or you want to use a different value,
    simply set the global variable 'g:timestamp_username', or the buffer local
    variable 'b:timestamp_username' to the desired value. NOTE: The global
    variable must be set before the plugin is loaded, however the buffer local
    variable can be set at any time.

							    *timestamp_userid*
    The #i token will be replaced by the userid.

    The default vaule is obtained from the "id -un" command. If that fails,
    the default value is obtained by searching the password file for the
    username obtained above. NOTE: This is done only when the vim variable
    |timestamp_UseSystemCalls| is set.

    A different value can be specified by setting the global variable
    g:timestamp_userid or the buffer local variable b:timestamp_userid to the
    desired value. NOTE: The global variable must be set before the plugin is
    loaded, however the buffer local variable can be set at any time. NOTE:
    When looking up the user in the password file, the buffer local variable
    b:timestamp_username is ignored.

						    *timestamp_UseSystemCalls*
    If the variable |timestamp_UseSystemCalls| is set, then system calls are
    made to determine the default values of |timestamp_Hostname|,
    |timestamp_userid| and |timestamp_username|. These generally cause about a
    half a second delay (on my super slow AMD K6-2) in the plugin
    initialisation, hence they are disabled by default. If you would like this
    plugin to use system calls to obtain the default values of Hostname,
    username and userid, then set the variable |timestamp_UseSystemCalls| in
    your {.vimrc}. NOTE: The environment variables / corresponding global
    variables will still be read when this variable is unset. Only the system
    commands (like 'id -un') will not be made.

    If you define any of the global variables |timestamp_Hostname|,
    |timestamp_username| or |timestamp_userid|, then the corresponding system
    call will not be made (regardless of the value of
    |timestamp_UseSystemCalls|). Thus if you want to avoid only some
    particular system calls, you can do it by setting the corresponding global
    variable.

    NOTE: In version 1.17 and up, these initialisations are no longer done on
    Vim startup, but done the first time the plugin is actually needed. So
    regardless of the global defaults, Vim startup will still be fast as
    always. On my ancient slow home computer (AMD K6-2 500mHz) avoiding the
    system calls saves me about half a second the first time I write a file.
    If you use these features, and want the system defaults, half a second per
    vim session might not be too much of a price to pay. 

------------------------------------------------------------------------------
    
4. Timestamp Auto command Mask				*timestamp_automask*

By default, the plugin installs an "autocommand BufWrite" for all files. So it
uses '*' as {pat} (see |:autocmd|). The user can overrule this behaviour by
defining g:timestamp_automask with the desired value, e.g.: >

    :let g:timestamp_automask = "*.html"

to limit timestamping to html files. NOTE: This global variable has to be set
BEFORE the plugin is loaded.

NOTE: If you compiled Vim without autocommands, this plugin will not work.

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

5. timestamp_modelines					*timestamp_modelines*

The number of lines searched for the |timestamp_regexp| is controlled by the
|timestamp_modelines| variable. By default this will be equal to the
'modelines' option. To specify a different value, set the global vim variable
'g:timestamp_modelines'. NOTE: This global variable has to be set BEFORE the
plugin is loaded. HOWEVER the buffer local variable can be set at any time.

If this is set to to '%' all lines in the file will be searched for the regexp
|timestamp_regexp|. NOTE: This may be more than you want.
------------------------------------------------------------------------------

6. Examples:						*timestamp_examples*

  1. No case matching, short format timestamps: >

	let g:timestamp_regexp = '\v\c%(last %(changed?|modified):\s+)@<=\d{4} \a{3} \d{2}'
	let g:timestamp_rep = '%Y %b %d'

<    Result: >
	" Last change: 2004 Feb 26

< 2. Match case, with filename, username and hostname in html comments: >

	augroup TimeStampHtml
	    au filetype html let b:timestamp_regexp = '\v\C%(\<!-- Timestamp:\s{-1,})@<=.{-}%(\s*--\>)@='
	    au filetype html let b:timestamp_rep = '%a %d/%m/%Y %r #u@#h:#f'
	augroup END

<    Result: >
	<!-- Timestamp: Thu 26/02/2004 05:49:33 PM gautam@math:timestamp.txt -->
------------------------------------------------------------------------------

7. Change History					*timestamp_history*

Version 1.20:~
  Optionally ignore AM/PM in timestamp by default (some systems don't produce
  it). Thanks to Fabian Holler for pointing this out.

Version 1.19:~
  Timestamps are only written when writing the timestamp will cause a change.
  E.g. if your timestamp format is of the form 2006-05-18, then the first time
  you write a file on a particular day will update the timestamp. Future
  writes will cause no change to the timestamp, and hence the timestamp is not
  updated. This preserves the undo history better.

Version 1.18:~
  Made timestamping work with zipped files (by using the |BufWritePre|
  autocommand, instead of |BufWrite|). Also preserves your jump / changelist.

Version 1.17:~
  Reduce Vim's initial load time significantly. On my system, Vim with
  timestamp-1.16 loads in about 1.1 seconds. With timestamp-1.17, it loads in
  only 0.3 seconds! The system calls to initialise the uid / username were
  taking time. Calls to these functions have been disabled by default, and
  further postponed untill the are necessary (and not on Vim startup). These
  calls can be enabled by setting the variable |timestamp_UseSystemCalls|.

Version 1.16:~
  Made all g:timestamp_* variables also available as buffer local variables
  except for g:timestamp_automask. Thanks to Lars Wilke for doing this. Also
  fixed default values for |timestamp_hostname|, |timestamp_Hostname|,
  |timestamp_userid| and |timestamp_username|. Thanks again to Lars Wilke for
  testing on various platforms.

Version 1.15:~
  Modified the default timestamp regexp to support timestamps in other
  languages by default. This only works if the day and month names in your
  language do not use accented characters. If accented characters are present
  you should set the default timestamp regexp in your .vimrc. English users
  should not notice any difference.

Version 1.14:~
  Now also works in compatible mode.

Version 1.13:~
  Removed unwanted code for preserving cursor location. With use of setline
  and getline this is no longer necessary. A bug caused timestamp.vim to make
  changes in all lines in the |timestamp_modelines| range. Corrected the code
  so that now changes are made only when there is a timestamp in a particular
  line. This makes undoing changes a lot easier.

Version 1.12:~
  Some Micro$oft machines don't support the timezone ('%Z'). Made the timezone
  optional in the default settings. The script (with default settings) should
  now work on both Linux / Window$ machines. Thanks to Krall Ed-P27726 for
  testing this.

Version 1.11:~
  Minor bug fix. The format of strftime("%c") is not standard among all
  systems / locales. Changed the default value of "timestamp_rep" from "%c" to
  the full expanded version. This should be more robust.

Version 1.1:~
  Does not modify any marks or the search history list. Tries to make
  timestamping as "transparent" as possible.

Version 1.0:~
  Original fork of "timstamp.vim". See |timestamp_differences| for a list of
  differences.

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

8. Differences From Timstamp:				*timestamp_differences*

This script is based on "timstamp.vim" originally written by Guido Van Hoecke
<Guido@VanHoecke.org>. There are many differences:

  1. Note the extra E in the name (timEstamp).

  2. Some bug fixes.

  3. Splits the pattern and replacement into two separate variables.

  4. Allows buffer local variables to replace the timestamp controls.

  5. Removed support for multiple timestamps (I thought this was wasteful,
     besides allowing buffer local variables to control timestamps makes this
     unnecessary. Timestamps for particular filetypes can be set by buffer
     local variables in filetype plugins)

  6. timstamp_* variables are no longer present. Use |timestamp_regexp| for
     the search pattern, and |timestamp_rep| for the replacement.
     |timestamp_rep| is substituted for filenames and then passed to
     |strftime()|.

  7. Removed the language setting. |strftime()| should provide this in your
     favourite language (provided your locale is set correctly)

  8. By default the timestamp regexps will NOT match everything after a
     "Last changed" or "Last modified". It will match exactly a time after
     each of those expressions! Hence a line like >

     		<i>Last changed: Tue 17 Feb 2004 04:18:40 PM CST</i>

<    will get replaced with >

     		<i>Last changed: Wed 18 Feb 2004 05:14:16 PM CST</i>

<    Note that the final </i> is left unchanged!

  9. To create a new timestamp in a file, put a line of the form
  
  		Last changed: TIMESTAMP (other optional stuff)

     in your file. The TIMESTAMP will get replaced with a timestamp. This
     only works with the default regexp. If you change that you're on your
     own

 10. To check the entire file, set timestamp_modelines to '%' (instead of the
     unintuitive '$' as before)
------------------------------------------------------------------------------
>
 Maintainer	: Gautam Iyer <gi1242@users.sourceforge.net>
 Modified	: Thu 21 Jun 2007 04:08:38 PM CDT
 vim: set ft=help tw=78: