Linguist 0.4 README
===================

== 0 Description ==

Linguist is an extension for Visual Studio 2010 allowing customizable syntax highlighting
based on file names. Support for new languages may be easily added using regular expressions
to identify the various language elements and language elements may be customized using
different fonts, point sizes, colors, and font styles (e.g. bold and italic). The built-in
languages include C#, C++, C, Python, Makefiles, patch files, etc. 

To install the extension close studio and double-click the `Linguist.vsix` file. To uninstall the extension
select the Extension Manager... item from Studio's Tool menu, select Linguist, and press the
Uninstall button. To upgrade the extension uninstall the old version and install the new version.

To check for newer versions of the extension visit https://github.com/jesse99/Linguist[github]. The
software is distributed under the terms of the MIT.X11 licensing agreement (see Licence.txt).

== 1 Operation ==

When the extension starts up for the first time it will create standard and custom directories 
inside `%LOCALAPPDATA%\Linguist` or `%USERPROFILE%\AppData\Local\Linguist` (typically this will
be something like `C:\Users\<user name>\AppData\Local\Linguist`). The standard directory will contain the built-in 
language and style files. The custom directory will be empty. When the extension starts up again
old or missing files in the standard directory will be added or updated.

Files within the custom directory can be used to define new languages or to override
files within the standard directory. Errors are written to a `Log.txt` file in the AppData directory.

Language and style files are written using a simple line-oriented file format. Lines that start
with a `#` are comments. Lines with only white space are ignored. Fields start with an identifier,
followed by a colon, followed by arbitrary text. Identifiers start with a letter followed by alpha-numeric
characters, underscrores, and dashes.

Testing source code changes with the solution is quite simple: make your change, press F5, and a special instance
of Studio will launch with the new version of the extension active. Breakpoints may be used
normally.

== 2 Style File ==

The Styles.field file is used to define how to render the various language elements. For example
the default style for Makefile targets is:

 * *Name:* target
 * *ForeColor:* DarkGreen
 * *PointSize:* 14
 * *Bold:* true
 
The following fields can be used within a style file:

 * *Name:* the name of the language element (this is the only required field).
 * *FontName:* the name of a font, e.g. Consolas or Verdana.
 * *PointSize:* the font size, e.g. 12.
 * *ForeColor:* an http://en.wikipedia.org/wiki/Web_colors#X11_color_names[X11 color] name (Red), a hex color (#FF0000), or a decimal color 255,0,0.
 * *BackColor:* an http://en.wikipedia.org/wiki/Web_colors#X11_color_names[X11 color] name (White), a hex color (#FFFFFF), or a decimal color 255,255,255.
 * *Bold:* true if the element should be in bold, and false otherwise.
 * *Italic:* true if the element should be italicized, and false otherwise.

The default element is special and applies to all text within a document. Other elements override
any styles used by the default element. Changes to Styles.field files require a restart of Studio
to take effect.

== 3 Language Files ==

Language files are used to define the language elements used by the language. The language
elements are matched using globs and the elements are matched using .NET http://msdn.microsoft.com/en-us/library/hs600312.aspx[regular expressions].
The regexen are
compiled using RegexOptions.IgnorePatternWhitespace | RegexOptions.Multiline (so dot does not match new line characters).
If parenthesis are used within a regular expression they must be non-grouping (i.e. (?: pattern)).

Here is an example:

 * *Language:* ini
 * *Globs:* *.ini
 
 * *Comment:* \x23 .* $
 * *Preprocess:* ^ \[ [a-zA-Z] [a-zA-Z0-9_ ]* \]
 
The following fields can be used within a language file:

 * *Language:* the name of the language, e.g. makefile.
 * *Globs:* space separated list of file name globs where the meta-characters are * and ?, e.g.
 Makefile *.mk.
 * *Element:* the name of a language element followed by the associated regular expression.
 The name may be Attribute, Command, Comment, Default, DiffLoc, Emphasis, Header1, Header2, Header3, Header4, Header5, Italic, Keyword, 
Keyword2, Markup, 
Method, Monospace, NewText, Number, OldText, Preprocess, Region, ShellVariable, String, Target, Type, or Type2.

Changes to language files in the custom directory take effect while Studio is running (although you may have to scroll
to see them).


jesse9jones@gmail.com
