Version: 3.5
Author: Amit Gupta (Contact Me)
Plugin URI: http://blog.igeek.info/wp-plugins/igsyntax-hiliter/
Bug Reports & Support: http://wordpress.org/support/topic/10533
License: GNU GPL

1. INTRODUCTION
2. WHAT's NEW
3. INSTALLATION
4. UPGRADING
5. CONFIGURATION
6. QUICKTAGS
7. USAGE
8. IMPORTANT

1. INTRODUCTION
-----------------------------------------------------------------------------------------
This is a WordPress plugin(for versions 1.5 and above) for syntax hiliting of your code. This is an update to v3.1.1. It hilites ActionScript, ASP, C, C++, C#, CSS, Delphi, HTML, Java, JavaScript, MySQL, Perl, PHP, Python, Ruby, Smarty, SQL, Visual Basic, VB.NET, XML languages by default but supports all languages supported by GeSHi. This release has a new improved GeSHi Core(v1.0.7.6).

As from the v3.0, you don't have to open up the plugin file & mess with the settings if you want to configure the plugin. The iG:Syntax Hiliter is ready to go as soon as you activate the plugin. If you want to change the settings etc., then you will now have a new admin panel under the OPTIONS menu of your WP administration, so you can now configure iG:Syntax Hiliter in a GUI.

A new & much vaunted feature that has been added to this release is the ability to hilite the code in the comments. The readers of your blog can leave code in the comments using the same code tags and it will be hilited the same way you hilite the code in your posts. You can Enable/Disable this feature from the admin GUI of iG:Syntax Hiliter. For more on features, see the Changelog.

iG:Syntax Hiliter has not been tested for versions below WP1.5 & is in no way backwards compatible. If you are using an older version of WordPress(older than v1.5), then you are better off using the older version of iG:Syntax Hiliter. This version is not for you.

You are required to be a Level 8(or have an 'Administrator' role assigned in WordPress 2 and above) or above USER to Install & Configure iG:Syntax Hiliter.

2. WHAT's NEW
-----------------------------------------------------------------------------------------
v3.5
~~~~~~~~~~~~

1. BUGFIX:- BB Tags except the ones of iG:Syntax Hiliter are allowed. The language file's existence is checked before parsing the code. If the language file does not exist then the code is not parsed.
2. BUGFIX:- 'C' code hiliting is now fixed.
3. BUGFIX:- 'Plain Text' has been improved to strip the extra blank lines and spaces in Opera and FireFox.
4. The latest stable GeSHi core(v1.0.7.6).
5. NEW:- Code Hiliting for Comments has been implemented. This feature can be Enabled/Disabled from the admin interface for iG:Syntax Hiliter. The tags are same for hiliting the code.
6. NEW:- A cross-browser Colour Picker(tested in IE6, FireFox1.5 and Opera8.5) is now available to easily set the line colours displayed in the code box.
7. NEW:- A new type of view implemented for seeing "Plain Text" code. Besides opening the plain text code in a new window, you can have it displayed in the code box itself with an option to display the hilited HTML code back again. The "Plain Text" view type can be set in the admin interface.
8. The language file for Ruby that I created a while back is now bundled with the plugin and its also a part of the default GeSHi package.

v3.1
~~~~~~~~~~~~

1. BUGFIX:- Critical bug, which broke the plugin when the square brackets([ & ]) were used in the posts in places other than tags, has been fixed.
2. BUGFIX:- Another bug, which allowed any attribute in the tags besides the 'num' and also allowed any attribute value for it, affecting the processing. Now only the 'num' attribute is accepted and if you specify the 'num' attribute then its value must be a positive number otherwise your code won't be hilited. The 'num' attribute is optional and you can leave it out without any problems.
3. BUGFIX:- Fixed the unclosed <select> tags in the Plugin GUI code.
4. GeSHi BUGFIX:- Fixed a bug in GeSHi where the first line colour was not used when using FANCY LINE NUMBERS thus resulting in just one colour being used for the alternate lines.
5. There's a problem in WordPress due to which the starting delimiters of ASP, PHP were not displayed correctly, as whitespace was inserted between the '<' and the rest of the delimiter. This has been patched so that its displayed correctly, but its not saved in the database, so the database still contains the delimiters as formatted by WordPress.

v3.0
~~~~~~~~~~~~

1. NEW LICENSE:-- iG:Syntax Hiliter is now licensed under GNU GPL.
2. Complete re-write of the plugin resulting in reduction of code from 750+ lines to about 400 Lines.
3. New GeSHi Core(v1.0.7) which has some bug-fixes, please see GeSHi Website for its changelog.
4. New languages added are C#, Delphi, Smarty & VB.NET.
5. ASP language file structure updated & more keywords added.
6. Drag-n-Drop usage of new languages. The plugin now supports all languages that GeSHi(v1.0.7) supports. You just need to drop the language file in the "geshi" directory & use the filename as the tag for the language(like if file is "pascal.php", then the filename is "pascal" & the tags will be [pascal] & [/pascal]).
7. Language name which is displayed in the Code-Box can now be turned ON or OFF easily.
8. No more need to set the physical-path to the "geshi" directory if you are doing a default installation.
9. Plain-Text View of the code hilited in the code-box is now possible. This feature can be enabled/disabled easily in the Configuration Interface in WP Administration.
10. NO NEED TO EDIT THE PLUGIN FILE ANYMORE. You can now configure the plugin settings from a GUI located under the OPTIONS menu in your WP Administration(WP1.5 & above only).

v2.01
~~~~~~~~~~~~

1. BUGFIX:- Fixed a bug by removing a <br /> tag from the function pFix() which lead to closing of an unnecessary <p> tag making the code not xHTML valid(as per my desires).

v2.0 Final
~~~~~~~~~~~~

1. Implemented the new version of GeSHi core, v1.0.2 which has some bug fixes & which uses OL(Ordered Lists) for Line Numbering and supports starting of a Line Number from any given number.
2. The ASP(Active Server Pages) language file has been updated to the new Language File structure of GeSHi as well as more keywords added & hiliting is more effective now.
3. iG:Syntax Hiliter now also supports ActionScript, C, C++, JavaScript, Perl, Python, Visual Basic & XML.
4. The whole plugin has been re-written & all the hiliting code is now in a class. You can just use the class anywhere else too for hiliting the code. But to also use the Code Tags to wrap your code & then hilite them, you will need to use all other functions. You can remove the WP Filter calls at the end of the plugin & use the rest of the code as you want somewhere else.
5. BUGFIX:- The issue of multi-line comments not being hilited properly in v2.0 Preview has been sorted out.

v2.0 Preview
~~~~~~~~~~~~

1. Implemented the new version of GeSHi core, v1.0.1 which has some bug fixes including the extra quote(")
   bug that broke the xHTML validation of the code.
2. I've created a new language file for ASP(Active Server Pages) which has been added to this release & will
   also be a part of the next GeSHi release.
3. Line numbering is now done through Ordered Lists(<OL>) & the code is xHTML compliant.
4. Auto-Formatting disabled for posts that contain the iG:Syntax Hiliter code tags so that your code is good for copy-paste operations.

v1.1
~~~~~~~~~~~~

1. Implemented the line numbering of code.
2. The code box is now of fixed dimensions without word-wrap & with scrollbars(if required).

v1.0
~~~~~~~~~~~~

1. hilites code between the special tags, all of them differently.
2. Uses GeSHi for syntax hiliting.
3. Supports HTML, CSS, PHP, JAVA & SQL codes.

3. INSTALLATION
-----------------------------------------------------------------------------------------

Installation is fairly easy. Just follow the steps:-

1. Extract the contents of iG_Syntax_Hiliter.zip. In the contents extracted, there's a directory called ig_syntax hiliter plugin. Upload its contents as they are to your WP plugins directory.
   CAUTION:- Don't upload the ig_syntax hiliter plugin directory, upload its contents only.
2. Go to the Plugins page in your WP Administration.
3. Activate iG:Syntax Hiliter. It'll auto-install on activation.
   CAUTION:- You need to be a Level 8(or above) user(or have the "Administrator" role assigned to you if you are using WordPress 2 or above) otherwise the plugin will be activated but won't be installed & this will result in malfunctioning of your blog.
4. That's all, your iG:Syntax Hiliter plugin is installed. Did you expect more? ;)

4. UPGRADING
-----------------------------------------------------------------------------------------
Upgrading from an old version? No problem, its as easy as popping a candy in your mouth.

UPGRADING from v3.x
~~~~~~~~~~~~~~~~~~~~
Just deactivate your plugin, delete the syntax_hilite.php file & ig_syntax hiliter plugin directory and follow the INSTALLATION process again. That's quite easy!!


UPGRADING from v2.1 or lower
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
DEACTIVATE the iG:Syntax Hiliter plugin from the plugin management page & then REMOVE THE FOLLOWING FILES & DIRECTORY:-

1. geshi directory
2. geshi.php
3. syntax_hilite.php

5. CONFIGURATION
-----------------------------------------------------------------------------------------
Configuring iG:Syntax Hiliter is a piece of cake. No more the painful way of opening the plugin file in a text-editor & changing the variable values. Just log on to your WP Admin section & make way to the Options page. There you'll see the tab called iG:Syntax Hiliter in the sub-menu.
CAUTION:- You need to be a Level 8(or above) user(or have the "Administrator" role assigned to you if you are using WordPress 2 or above) to access the iG:Syntax Hiliter configuration page.

When you click the iG:Syntax Hiliter configuration page, you are offered 9 configuration settings which you can set to your liking, but lets go through each of them.

1. Show Plain Text Code Option:- This setting lets you set the Plain Text view of code ON or OFF. This setting is enabled by default.
    
2. Show Plain Text Code In:- This setting lets you decide how to display the Plain Text view of code. Selecting the "In CodeBox" option will allow you to toggle between the plain text & hilited code in the code box itself while selecting "New Window" will display the plain text code in a new window.
    
3. Show Language Name:- This setting allows you to display the name of the Language whose code is hilited in a particular code-box. So each code-box will have its language name at its top. This setting is enabled by default.
    
4. Hilite Code in Comments:- This setting allows you to Enable/Disable hiliting of code posted within the code tags in your comments. If this is enabled, the code posted in the comments will be hilited as it is in the posts.
    
5. Show Line Numbers:- This setting when enabled, displays line numbers along with each line of code in the code-box. Line numbers along with code looks great, are a great help when refering some code from a code-box and also helps in debugging. If you still don't want Line Numbers with your code, then you can turn it OFF. This setting is enabled by default.
    
6. Show Fancy Line Numbers:- Plain Line Numbers along with the code look really dull, no? Well, that's why this setting is there. You can have alternate Line Numbers coloured, just enable this setting. This setting is enabled by default.
    
7. Line Colour 1:- This setting is for specifying the first colour for Line Numbers. This setting accepts a hexadecimal colour code which is always applied, regardless whether you have Fancy Line Numbers enabled or not. This setting is pre-configured by default.
    
8. Line Colour 2:- This setting is specifying the second colour for Line Numbers. This setting accepts a hexadecimal colour code which is applied only when you have Fancy Line Numbers enabled. This setting is pre-configured by default.
   One thing to keep in mind is that if you leave a setting unchanged, then it remains that way & if you don't provide any value for a setting(Line Colour 1 and Line Colour 2) then the current values are preserved & no changes are made. So in other words you can't delete a setting by not providing a value for it.
   
   CAUTION:- Keep in mind that you are to provide a hexadecimal code for the Line Colour 1 and Line Colour 2. If you provide any other text in the option box, that will be saved as it is overwriting the current value. The plugin & WordPress can & probably will malfunction because of this and you'll be responsible for that.
   
   If Javascript is enabled in your browser then you'll see a small icon next to the colour value fields. Clicking them will open a colour picker which you can use to select the colour you want to set for that line colour box. This colour picker requires Javascript and has been tested for cross-browser support in IE6, FireFox1.5 and Opera8.5. If you don't see the icon then you don't have javascript enabled in your browser.
    
9. RESET DEFAULT SETTINGS:- If you've messed up the plugin settings or because of any other reason want to restore the plugin to the default settings with which it came, you can do so now by clicking this button. If you've Javascript enabled in your browser then you'll get a confirmation dialog before resetting the plugin options, else the plugin options will be reset to default without any confirmation.

6. QUICKTAGS
-----------------------------------------------------------------------------------------
This is optional & not required to use the plugin, but to make your life easier, you can use the iG:Syntax Hiliter Quicktags.

1. Open quicktags.js in your wp-admin directory. If you are using WordPress 2.x then you'll find the quicktags.js in "wp-includes/js/" directory.
2. After these lines of code starting on line # 126
   
   edButtons[edButtons.length] =
   new edButton('ed_more'
   ,'more'
   ,'<!--more-->'
   ,''
   ,'t'
   ,-1
   );
   
   
   add the following lines
   
   
   //----- Start iG:Syntax Hiliter Plugin's Quick Tags -----

   edButtons[edButtons.length] =
   new edButton('ed_shAS'
   ,'ActionScript'
   ,'[as]'
   ,'[/as]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shASP'
   ,'ASP'
   ,'[asp]'
   ,'[/asp]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shC'
   ,'C'
   ,'[c]'
   ,'[/c]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shCPP'
   ,'C++'
   ,'[cpp]'
   ,'[/cpp]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shCSHARP'
   ,'C#'
   ,'[csharp]'
   ,'[/csharp]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shCSS'
   ,'CSS'
   ,'[css]'
   ,'[/css]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shDELPHI'
   ,'DELPHI'
   ,'[delphi]'
   ,'[/delphi]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shHTML'
   ,'HTML'
   ,'[html]'
   ,'[/html]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shJAVA'
   ,'JAVA'
   ,'[java]'
   ,'[/java]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shJS'
   ,'JavaScript'
   ,'[js]'
   ,'[/js]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shMySQL'
   ,'MySQL'
   ,'[mysql]'
   ,'[/mysql]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shPERL'
   ,'PERL'
   ,'[perl]'
   ,'[/perl]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shPHP'
   ,'PHP'
   ,'[php]'
   ,'[/php]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shPYTHON'
   ,'PYTHON'
   ,'[python]'
   ,'[/python]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shRuby'
   ,'RUBY'
   ,'[ruby]'
   ,'[/ruby]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shSMARTY'
   ,'SMARTY'
   ,'[smarty]'
   ,'[/smarty]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shSQL'
   ,'SQL'
   ,'[sql]'
   ,'[/sql]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shVB'
   ,'Visual Basic'
   ,'[vb]'
   ,'[/vb]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shVBNET'
   ,'VB.NET'
   ,'[vbnet]'
   ,'[/vbnet]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shXML'
   ,'XML'
   ,'[xml]'
   ,'[/xml]'
   ,''
   );

   edButtons[edButtons.length] =
   new edButton('ed_shCode'
   ,'CODE'
   ,'[code]'
   ,'[/code]'
   ,''
   );

   //----- End iG:Syntax Hiliter Plugin's Quick Tags -----
3. Save the file & exit.
4. Now there will be 21 new buttons added to your post editor toolbar namely:
   ActionScript, ASP, C, C++, C#, CSS, DELPHI, HTML, JAVA, JavaScript, MySQL, PERL, PHP, PYTHON, RUBY, SMARTY, SQL, Visual Basic, VB.NET, XML & CODE for wrapping their respective tags.

7. USAGE
-----------------------------------------------------------------------------------------
Using this syntax highlighter is fairly easy. There are basically 19 sets of tags(by default).

[as] & [/as]
[asp] & [/asp]
[c] & [/c]
[cpp] & [/cpp]
[csharp] & [/csharp]
[css] & [/css]
[delphi] & [/delphi]
[html] & [/html]
[java] & [/java]
[js] & [/js]
[mysql] & [/mysql]
[perl] & [/perl]
[php] & [/php]
[python] & [/python]
[ruby] & [/ruby]
[smarty] & [/smarty]
[sql] & [/sql]
[vb] & [/vb]
[vbnet] & [/vbnet]
[xml] & [/xml]
[code] & [/code]

The [as] & [/as] tags are for hiliting ActionScript Code. You have to place your
ActionScript code in between them.
The [asp] & [/asp] tags are for hiliting ASP Code.
The [c] & [/c] tags are for hiliting C Code.
The [cpp] & [/cpp] tags are for hiliting C++ Code.
The [csharp] & [/csharp] tags are for hiliting C# Code.
The [css] & [/css] tags are for hiliting CSS Code.
The [delphi] & [/delphi] tags are for hiliting Delphi Code.
The [html] & [/html] tags are for hiliting HTML Code.
The [java] & [/java] tags are for hiliting JAVA Code.
The [js] & [/js] tags are for hiliting JavaScript Code.
The [mysql] & [/mysql] tags are for hiliting MySQL specific SQL.
The [perl] & [/perl] tags are for hiliting Perl Code.
The [php] & [/php] tags are for hiliting PHP Code.
The [python] & [/python] tags are for hiliting Python Code.
The [ruby] & [/ruby] tags are for hiliting Ruby Code.
The [smarty] & [/smarty] tags are for hiliting Smarty Code.
The [sql] & [/sql] tags are for hiliting SQL Code.
The [vb] & [/vb] tags are for hiliting Visual Basic Code. TIP:- You can use the [vb] & [/vb] tags for hiliting VBScript Code too.
The [vbnet] & [/vbnet] tags are for hiliting VB.NET Code.
The [xml] & [/xml] tags are for hiliting XML Code.
The [code] & [/code] tags are for hiliting generic Code that isn't one of the
already mentioned ones.

Suppose following is your PHP Code:
 

Similarly, you can use other tags.

You can specify the number from which the Line Numbering of your code should start. This is specifically helpful when you are pointing out a code snippet from a larger module. So how do you specify the number to start the numbering from?? Its easy, you just set the value of the num attribute in a code tag. So, if my PHP code is

and I'll get the Line Numbers from 23 instead of 1. You can use this attribute in all the tags. But remember, do not enclose the number in quotes.



NEW FEATURE:-
COMMENT CODE HILITING: The code in comments can now be hilited the same way it is in posts. You can turn this option on or off as per your wishes, see Configuration for more details.
PLAIN TEXT OPTIONS: The Plain Text code can now be displayed in two ways, either in the codebox itself or in a new window. This is configurable in the admin interface of the plugin, see Configuration for more details.
COLOUR PICKER: You don't have to remember the hexadecimal colour codes to set the line colours. A colour picker is now available that lets you choose a colour of your choice and lets you set its colour depth etc.

8. IMPORTANT
-----------------------------------------------------------------------------------------
Do not forget to close the tags, as your code will not be hilited if you don't close your tags. Also, DON'T NEST TAGS. Nesting of tags don't work, so don't try it. It'll ruin your output.
Also, this plugin has problems when you are using it with text-formatting plugins like Textile 1 & 2 or Markdown etc. So be careful when you use them along with this plugin.

Also a WYSIWYG editor(like the one bundled with WP2.x) will probably mess up your code when you paste it in the editor. So if you are having that issue, then please don't report it as a bug or anything, its not a bug on the part of this plugin.

NOTE:- For fast results & less load on your server, you can try out the WP-Cache plugin by Ricardo Galli which caches the WP output to a file, so that WP doesn't hit the database on every page load, thus increasing your website's performance.

KNOWN ISSUES:-
Due to the way WordPress handles the excerpts, if you don't specify an excerpt for your posts, then any code in the excerpts generated by WordPress will not be hilited but it'll have the language name(if you have it enabled in the configuration) and it'll have the Plain Text link(if you have it enabled in the configuration) which won't work. So it does look like a bit screwed up. There are only 2 ways out of this at present, either you don't use excerpts on any page, like archives, search, category pages etc. or you specify the excerpt of posts which have any code in them.

That's all of the important stuff. Enjoy!!