Update installation instructions, include doc/tlv-mode.txt

.gitignore

@@ -0,0 +1 @@
+doc/tags

INSTALL.md

@@ -0,0 +1,13 @@
+# Installation instructions
+
+There are two ways to install the vim-tlv-mode plug-in and it's up to you which you prefer, both options are explained below. Please note that below are generic installation instructions while some Vim plug-ins may have external dependencies, please refer to the plug-in's [readme](README.md) for details.
+
+## Installation using a ZIP archive
+
+Unzip the most recent ZIP archive of the [vim-tlv-mode](http://peterodding.com/code/vim/downloads/tlv-mode.zip) plug-in inside your Vim profile directory (usually this is `~/.vim` on UNIX and `%USERPROFILE%\vimfiles` on Windows), restart Vim and execute the command `:helptags ~/.vim/doc` (use `:helptags ~\vimfiles\doc` instead on Windows).
+
+If you get warnings about overwriting existing files while unpacking the ZIP archive you probably don't need to worry about this because it's most likely caused by files like `README.md`, `INSTALL.md` and `addon-info.json`. If these files bother you then you can remove them after unpacking the ZIP archive, they are not required to use the plug-in.
+
+## Installation using a Vim plug-in manager
+
+If you prefer you can also use [Pathogen](http://www.vim.org/scripts/script.php?script_id=2332), [Vundle](https://github.com/gmarik/vundle) or a similar tool to install and update the [vim-tlv-mode](https://github.com/xolox/vim-tlv-mode) plug-in using a local clone of the git repository. This takes a bit of work to set up the first time but it makes updating much easier, and it keeps each plug-in in its own directory which helps to keep your Vim profile uncluttered.

README.md

@@ -18,11 +18,10 @@ stay tuned: As soon as TLV has been launched I will provide references here.*
 
 ## Install & first use
 
-Unzip the [most recent ZIP archive] [download-tlv-mode] of the *vim-tlv-mode* plug-in inside your Vim profile directory (usually this is `~/.vim` on UNIX and `%USERPROFILE%\vimfiles` on Windows), restart Vim and execute the command `:helptags ~/.vim/doc` (use `:helptags ~\vimfiles\doc` instead on Windows).
-
-If you prefer you can also use [Pathogen] [pathogen], [Vundle] [vundle] or a similar tool to install and update the *vim-tlv-mode* plug-in using a local clone of [the git repository] [github-tlv-mode].
-
-Now try it out: Edit a `*.tlv` file and inspect the syntax highlighting in `\TLV` code blocks! You can also play around with the smart indentation to get a feel for how it works.
+Please refer to the [installation instructions] [howto-install] available on
+GitHub. Once you've installed the plug-in try it out: Edit a `*.tlv` file and
+inspect the syntax highlighting in `\TLV` code blocks! You can also play around
+with the smart indentation to get a feel for how it works.
 
 ## Features
 
@@ -120,7 +119,6 @@ This software is licensed under the [MIT license] [mit].
 © 2015 Peter Odding &lt;<peter@peterodding.com>&gt;.
 
 
-[download-tlv-mode]: http://peterodding.com/code/vim/downloads/tlv-mode.zip
 [foldexpr]: http://vimdoc.sourceforge.net/htmldoc/options.html#'foldexpr'
 [github-tlv-mode]: https://github.com/xolox/vim-tlv-mode
 [homepage]: http://peterodding.com/code/vim/tlv-mode/
@@ -129,9 +127,8 @@ This software is licensed under the [MIT license] [mit].
 [m4]: http://en.wikipedia.org/wiki/M4_(computer_language)
 [m4_syntax]: https://code.google.com/p/vim/source/browse/runtime/syntax/m4.vim
 [mit]: http://en.wikipedia.org/wiki/MIT_License
-[pathogen]: http://www.vim.org/scripts/script.php?script_id=2332
 [sv]: http://en.wikipedia.org/wiki/SystemVerilog
 [sv_syntax]: https://code.google.com/p/vim/source/browse/runtime/syntax/systemverilog.vim
 [vim-online]: http://www.vim.org/scripts/script.php?script_id=5130
 [vim]: http://www.vim.org/
-[vundle]: https://github.com/gmarik/vundle
+[howto-install]: https://github.com/xolox/vim-tlv-mode/blob/master/INSTALL.md

addon-info.json

@@ -0,0 +1 @@
+{"vim_script_nr": 5130, "dependencies": {}, "homepage": "http://peterodding.com/code/vim/tlv-mode", "name": "vim-tlv-mode"}

autoload/tlv.vim

@@ -1,10 +1,10 @@
 " Vim auto-load script
 " Language: TLV (Transaction-Level Verilog)
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: March 30, 2015
+" Last Change: April 2, 2015
 " URL: https://github.com/xolox/vim-tlv-mode
 
-let g:tlv#version = '0.2'
+let g:tlv#version = '0.2.1'
 
 function! tlv#compiler_is_installed() " {{{1
   " Check if the TLV compiler is installed. Returns true (1) when the compiler

doc/tlv-mode.txt

@@ -0,0 +1,178 @@
+*tlv-mode.txt*  Transaction-Level Verilog support for Vim
+
+===============================================================================
+Contents ~
+
+ 1. Introduction                                        |tlv-mode-introduction|
+ 2. Install & first use                            |tlv-mode-install-first-use|
+ 3. Features                                                |tlv-mode-features|
+  1. File type detection                         |tlv-mode-file-type-detection|
+  2. Syntax highlighting                         |tlv-mode-syntax-highlighting|
+   1. Syntax highlighting of M4 macros |tlv-mode-syntax-highlighting-of-m4-macros|
+   2. Recommended color scheme included |tlv-mode-recommended-color-scheme-included|
+  3. Automatic (smart) indentation             |tlv-mode-automatic-indentation|
+  4. Automatic text folding                   |tlv-mode-automatic-text-folding|
+  5. Checking for syntax errors           |tlv-mode-checking-for-syntax-errors|
+ 4. Contact                                                  |tlv-mode-contact|
+ 5. License                                                  |tlv-mode-license|
+ 6. References                                            |tlv-mode-references|
+
+===============================================================================
+                                                        *tlv-mode-introduction*
+Introduction ~
+
+The _vim-tlv-mode_ plug-in adds support for Transaction-Level Verilog (TLV for
+short) to the Vim text editor. The plug-in is intended to provide everything
+needed to efficiently develop TLV code in Vim:
+
+- File type detection
+- Syntax highlighting (including an optional color scheme)
+- Automatic (smart) indentation
+- Automatic text folding
+- Checking for syntax errors (work in progress)
+
+Each of the features outlined above is discussed in more detail below.
+
+_Please note that Transaction-Level Verilog is in the process of being launched
+as this document is written so I can't provide any public references yet, but
+stay tuned: As soon as TLV has been launched I will provide references here._
+
+===============================================================================
+                                                   *tlv-mode-install-first-use*
+Install & first use ~
+
+Please refer to the installation instructions [1] available on GitHub. Once
+you've installed the plug-in try it out: Edit a '*.tlv' file and inspect the
+syntax highlighting in '\TLV' code blocks! You can also play around with the
+smart indentation to get a feel for how it works.
+
+===============================================================================
+                                                            *tlv-mode-features*
+Features ~
+
+-------------------------------------------------------------------------------
+                                                 *tlv-mode-file-type-detection*
+File type detection ~
+
+Transaction-Level Verilog files are detected in two complementary ways:
+
+1. Files with the '*.tlv' filename extension;
+2. Files whose first line consists of the mandatory file format line.
+
+If either of the two conditions above is met the file type detection kicks in.
+What this basically means is that you should never have to manually activate
+the file type or syntax highlighting; it will be done for you automatically.
+
+-------------------------------------------------------------------------------
+                                                 *tlv-mode-syntax-highlighting*
+Syntax highlighting ~
+
+The syntax highlighting mode differentiates between three types of code
+regions:
+
+1. The first type of region is marked at its start with the line '\SV',
+   these regions contain lines of SystemVerilog [2] code that are passed
+   through (unprocessed and uninterpreted) to the translated SystemVerilog
+   file. These regions are highlighted using Vim's SystemVerilog syntax
+   highlighting support [3] (included in Vim's runtime distribution as the
+   'systemverilog' file type).
+
+2. The second type of region is marked at its start with the line '\TLV',
+   these regions contain lines of Transaction-Level Verilog code. **This is
+   where the syntax highlighting for Transaction-Level Verilog code kicks in
+   and where most of the syntax highlighting logic of _vim-tlv-mode_ is
+   concentrated.**
+
+3. The third type of region is marked at its start with the line '\SV_plus',
+   these regions contain lines of SystemVerilog code with TLV signal
+   references.
+
+-------------------------------------------------------------------------------
+                                    *tlv-mode-syntax-highlighting-of-m4-macros*
+Syntax highlighting of M4 macros ~
+
+The TLV processing chain runs M4 [4] as an independent preprocessor before any
+other processing takes place so M4 macros can be used anywhere (although they
+are intended to provide functionality for '\TLV' and '\SV_plus' regions).
+Because of this the _vim-tlv-mode_ syntax script uses Vim's M4 syntax
+highlighting support [5] to highlight M4 macros embedded in TLV files.
+
+-------------------------------------------------------------------------------
+                                   *tlv-mode-recommended-color-scheme-included*
+Recommended color scheme included ~
+
+There is a recommended color scheme for editing Transaction-Level Verilog code
+and _vim-tlv-mode_ contains a Vim color scheme script called (you guessed it
+:-) _tlv_ that provides this recommended color scheme to Vim.
+
+Of course you are free to decide whether to use this color scheme or not, the
+choice is up to you. The syntax highlighting mode is intended to work well with
+other Vim color schemes as well.
+
+-------------------------------------------------------------------------------
+                                               *tlv-mode-automatic-indentation*
+Automatic (smart) indentation ~
+
+The _vim-tlv-mode_ plug-in uses Vim's |'indentexpr'| option to implement smart
+indentation (that understands TLV scope rules and knows to ignore line type
+characters) and automatically increases the indentation level as needed.
+
+-------------------------------------------------------------------------------
+                                              *tlv-mode-automatic-text-folding*
+Automatic text folding ~
+
+The _vim-tlv-mode_ plug-in uses Vim's |'foldexpr'| option to implement
+automatic text folding (that understands TLV scope rules and knows to ignore
+line type characters). This method of text folding is already a big improvement
+over indentation based folding (because that falls apart as soon as line type
+characters are introduced) but it's not perfect yet; I'd like to improve it
+further.
+
+-------------------------------------------------------------------------------
+                                          *tlv-mode-checking-for-syntax-errors*
+Checking for syntax errors ~
+
+To compile TLV code you need the 'sandpiper' compiler. When the _vim-tlv-mode_
+plug-in sees that you have the 'sandpiper' compiler installed it will
+automatically run the compiler every time you save a TLV file. If the compiler
+reports syntax warnings or errors a |location-list-window| pops up to show you
+an overview of compiler messages. When you click on a recognized line in the
+location list window you'll automatically jump to the line in the TLV file
+where the message was reported.
+
+Please note that this feature is still in development (not finished yet) so for
+now the automatic syntax checking is disabled by default. The to-do list in the
+file 'TODO.md' contains more details (refer to the version control repository
+on GitHub).
+
+===============================================================================
+                                                             *tlv-mode-contact*
+Contact ~
+
+If you have questions, bug reports, suggestions, etc. the author can be
+contacted at peter@peterodding.com. The latest version is available at
+peterodding.com/code/vim/tlv-mode [6] and github.com/xolox/vim-tlv-mode [7]. If
+you like the plug-in please vote for it on Vim Online [8].
+
+===============================================================================
+                                                             *tlv-mode-license*
+License ~
+
+This software is licensed under the MIT license [9]. © 2015 Peter Odding
+<peter@peterodding.com>.
+
+===============================================================================
+                                                          *tlv-mode-references*
+References ~
+
+[1] https://github.com/xolox/vim-tlv-mode/blob/master/INSTALL.md
+[2] http://en.wikipedia.org/wiki/SystemVerilog
+[3] https://code.google.com/p/vim/source/browse/runtime/syntax/systemverilog.vim
+[4] http://en.wikipedia.org/wiki/M4_(computer_language)
+[5] https://code.google.com/p/vim/source/browse/runtime/syntax/m4.vim
+[6] http://peterodding.com/code/vim/tlv-mode/
+[7] https://github.com/xolox/vim-tlv-mode
+[8] http://www.vim.org/scripts/script.php?script_id=5130
+[9] http://en.wikipedia.org/wiki/MIT_License
+
+vim: ft=help