===== Smarty Pants: Smart typographic punctuation =====
>>Working for 1.1.6.0 to 1.1.6.4
~&On large pages with some more than just a few comments, you might exceed PHP's available memory. Try setting the wikka.config.php option to 0, then. --MasinAlDujaili>>
//This page provides instructions on how to install a 3rd party formatting engine for smart typographic punctuation in WikkaWiki//

>>**See also**
~-UnderDevelopment
~-WantedFormatters
~-PreFormatter
~-[[ThirdPartyIntegration | Experimental 3rd party software integration in wikka]]
~-[[Docs:ThirdPartyInfo | 3rdparty software officially bundled with wikka]]
>>::c::

=== The functionality ===
[[http://www.michelf.com/projects/php-smartypants/ | PHP SmartyPants]] is a port to PHP (written by [[http://www.michelf.com/ | Michel Fortin]]) of the original [[http://daringfireball.net/projects/smartypants/ | SmartyPants]] written in Perl by John Gruber. SmartyPants is a free web publishing tool that translates plain ASCII punctuation characters into "smart" typographic punctuation HTML entities. SmartyPants can perform the following transformations:
~-Straight quotes ( " and ' ) and backticks-style quotes (`` ""''"") into curly quote HTML entities: “doublequotes” and ‘singlequotes’ ;
~-Dashes (##--## and ##""---""##) into en- and em-dash entities: – and — ;
~-Three consecutive dots (##...##) into an ellipsis entity (…).

SmartyPants does not modify characters within ##<pre>##, ##<code>##, ##<kbd>##, or ##<script>## tag blocks. Typically, these tags are used to display text where smart quotes and other "smart punctuation" would not be appropriate, such as source code or example markup.

==Known issues==
(from: http://daringfireball.net/projects/smartypants/)
One situation in which quotes will get curled the wrong way is when apostrophes are used at the start of leading contractions. For example:
’Twas the night before Christmas.
In the case above, SmartyPants will turn the apostrophe into an opening single-quote, when in fact it should be a closing one. I don't think this problem can be solved in the general case - every word processor I've tried gets this wrong as well. In such cases, it's best to use the proper HTML entity for closing single-quotes by hand.

Installing SmartyPants in Wikka is straightforward and it only requires setting some configuration options in the original code.

===The steps===

==1. Get the code==
Download the latest version of [[http://www.michelf.com/projects/php-smartypants/]]

==2. Copy it in the wikka directory==
Unzip the SmartyPants folder and move it into ##/3rdparty/plugins##

==3. Modify the [[Docs:ConfigurationOptions | Wikka configuration file]]==
Add the following lines to ##wikka.config.php##:

%%(php)
"typography" => "1",
"smartypants_path" => "3rdparty/plugins/smartypants",
%%

Make sure the smartypants path matches the path to the folder in which ##smartypants.php## can be found.

==4. Create a ##Typography()## method ==

Add the following function in ##wikka.php##, for example right after the ##GeSHi_Highlight()## function:

%%(php)
function Typography($text)
{
if (($this->GetConfigValue('typography') == 1) && file_exists($this->GetConfigValue('smartypants_path').'/smartypants.php'))
{
include_once($this->GetConfigValue('smartypants_path').'/smartypants.php');
$text = SmartyPants($text);
}
return $text;
}

%%

==5. Modify the formatter ==

Open ##./formatter/wakka.php##, scroll to the end of the file and add the following line, immediately before ##echo $text;##

%%(php)
$text = $this->Typography($text);
%%

==6. Set SmartyPants configuration options ==

In order to make SmartyPants consistently work with Wikka, you should set the following options in:
##3rdparty/plugins/smartypants/smartypants.php##

%%(php;27)
# Globals:
$sp_tags_to_skip = '<(/?)(?:pre|code|kbd|script|math|form)[\s>]';
%%

Make sure the ##$sp_tags_to_skip## pattern contains ##form## if you don't want punctuation to be parsed within forms. This is needed in case your Wikka runs beta extensions like GrabCodeHandler or MySkin, WikkaSkinEditor or WikkaSkinSelector.

//That's all folks...//

----
CategoryDevelopment3rdParty CategoryDevelopmentFormatters