mirror of
https://github.com/Lastorder-DC/rhymix.git
synced 2026-01-27 23:29:57 +09:00
246 lines
8.2 KiB
Markdown
246 lines
8.2 KiB
Markdown
PHP SmartyPants
|
||
===============
|
||
|
||
PHP SmartyPants Lib 1.8.1 - 12 Dec 2016
|
||
|
||
by Michel Fortin
|
||
<https://michelf.ca/>
|
||
|
||
Original SmartyPants by John Gruber
|
||
<https://daringfireball.net/>
|
||
|
||
|
||
Introduction
|
||
------------
|
||
|
||
This is a library package that includes the PHP SmartyPants and its
|
||
sibling PHP SmartyPants Typographer with additional features.
|
||
|
||
SmartyPants is a free web typography prettifyier tool for web writers. It
|
||
easily translates plain ASCII punctuation characters into "smart" typographic
|
||
punctuation HTML entities.
|
||
|
||
PHP SmartyPants is a port to PHP of the original SmartyPants written
|
||
in Perl by John Gruber.
|
||
|
||
SmartyPants can perform the following transformations:
|
||
|
||
* Straight quotes (`"` and `'`) into “curly” quote HTML entities
|
||
* Backtick-style quotes (` ``like this'' `) into “curly” quote HTML
|
||
entities
|
||
* Dashes (`--` and `---`) into en- and em-dash entities
|
||
* Three consecutive dots (`...`) into an ellipsis entity
|
||
|
||
SmartyPants Typographer can perform additional transformations:
|
||
|
||
* French guillemets done using (`<<` and `>>`) into true « guillemets »
|
||
HTML entities.
|
||
* Comma-style quotes (` ,,like this`` ` or ` ''like this,, `) into their
|
||
curly equivalent.
|
||
* Replace existing spaces with non-break spaces around punctuation marks
|
||
where appropriate, can also add or remove them if configured to.
|
||
* Replace existing spaces with non-break spaces for spaces used as
|
||
a thousand separator and between a number and the unit symbol that
|
||
follows it (for most common units).
|
||
|
||
This means you can write, edit, and save using plain old ASCII straight
|
||
quotes, plain dashes, and plain dots, but your published posts (and
|
||
final HTML output) will appear with smart quotes, em-dashes, proper
|
||
ellipses, and proper no-break spaces (with Typographer).
|
||
|
||
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.
|
||
|
||
|
||
### Backslash Escapes ###
|
||
|
||
If you need to use literal straight quotes (or plain hyphens and
|
||
periods), SmartyPants accepts the following backslash escape sequences
|
||
to force non-smart punctuation. It does so by transforming the escape
|
||
sequence into a decimal-encoded HTML entity:
|
||
|
||
|
||
Escape Value Character
|
||
------ ----- ---------
|
||
\\ \ \
|
||
\" " "
|
||
\' ' '
|
||
\. . .
|
||
\- - -
|
||
\` ` `
|
||
|
||
|
||
This is useful, for example, when you want to use straight quotes as
|
||
foot and inch marks:
|
||
|
||
6\'2\" tall
|
||
|
||
translates into:
|
||
|
||
6'2" tall
|
||
|
||
in SmartyPants's HTML output. Which, when rendered by a web browser,
|
||
looks like:
|
||
|
||
6'2" tall
|
||
|
||
|
||
Requirements
|
||
------------
|
||
|
||
This library package requires PHP 5.3 or later.
|
||
|
||
Note: The older plugin/library hybrid package for PHP SmartyPants and
|
||
PHP SmartyPants Typographer is still will work with PHP 4.0.5 and later.
|
||
|
||
|
||
Usage
|
||
-----
|
||
|
||
This library package is meant to be used with class autoloading. For autoloading
|
||
to work, your project needs have setup a PSR-0-compatible autoloader. See the
|
||
included Readme.php file for a minimal autoloader setup. (If you don't want to
|
||
use autoloading you can do a classic `require_once` to manually include the
|
||
files prior use instead.)
|
||
|
||
With class autoloading in place, putting the 'Michelf' folder in your
|
||
include path should be enough for this to work:
|
||
|
||
use \Michelf\SmartyPants;
|
||
$html_output = SmartyPants::defaultTransform($html_input);
|
||
|
||
SmartyPants Typographer is also available the same way:
|
||
|
||
use \Michelf\SmartyPantsTypographer;
|
||
$html_output = SmartyPantsTypographer::defaultTransform($html_input);
|
||
|
||
If you are using PHP SmartyPants with another text filter function that
|
||
generates HTML such as Markdown, you should filter the text *after* the
|
||
the HTML-generating filter. This is an example with [PHP Markdown][pmd]:
|
||
|
||
use \Michelf\Markdown, \Michelf\SmartyPants;
|
||
$my_html = Markdown::defaultTransform($my_text);
|
||
$my_html = SmartyPants::defaultTransform($my_html);
|
||
|
||
To learn more about configuration options, see the full list of
|
||
[configuration variables].
|
||
|
||
[configuration variables]: https://michelf.ca/projects/php-smartypants/configuration/
|
||
[pmd]: https://michelf.ca/projects/php-markdown/
|
||
|
||
|
||
### Usage Without an Autoloader ###
|
||
|
||
If you cannot use class autoloading, you can still use include or require to
|
||
access the parser. To load the \Michelf\SmartyPants parser, do it this way:
|
||
|
||
require_once 'Michelf/SmartyPants.inc.php';
|
||
|
||
Or, if you need the \Michelf\SmartyPantsTypographer parser:
|
||
|
||
require_once 'Michelf/SmartyPantsTypographer.inc.php';
|
||
|
||
While the plain `.php` files depend on autoloading to work correctly, using the
|
||
`.inc.php` files instead will eagerly load the dependencies that would be loaded
|
||
on demand if you were using autoloading.
|
||
|
||
|
||
Algorithmic Shortcomings
|
||
------------------------
|
||
|
||
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 (`’` or `’`) by
|
||
hand.
|
||
|
||
|
||
Bugs
|
||
----
|
||
|
||
To file bug reports or feature requests (other than topics listed in the
|
||
Caveats section above) please send email to:
|
||
|
||
<michel.fortin@michelf.ca>
|
||
|
||
If the bug involves quotes being curled the wrong way, please send
|
||
example text to illustrate.
|
||
|
||
|
||
Version History
|
||
---------------
|
||
|
||
PHP SmartyPants Lib 1.8.1 (12 Dec 2016)
|
||
|
||
* Fixed an issue introduced in 1.8.0 where backtick quotes were broken.
|
||
|
||
|
||
PHP SmartyPants Lib 1.8.0 (13 Nov 2016)
|
||
|
||
* Can now set replacement characters for all transformations using
|
||
configuration variables, including ellipses and dashes.
|
||
|
||
* Relocated replacement quotes configuration variables from
|
||
`SmartyPantsTyppographer` to `SmartyPants`. Also relocated
|
||
`decodeEntitiesInConfiguration()` to follow the configuration variables.
|
||
|
||
* Added conversion of apostrophe and double quote to Hebrew Geresh
|
||
and Gershayim when the apostrophe or double quote is surrounded on
|
||
both sides by a Hebrew character. For instance:
|
||
|
||
input: צה"ל / צ'ארלס
|
||
output: צה״ל / צ׳ארלס
|
||
|
||
You can still put quotes around Hebrew words and they'll become curled
|
||
quotation marks (if that is enabled). This new transform only applies
|
||
in the middle of a word, and only to words in Hebrew.
|
||
|
||
|
||
PHP SmartyPants Lib 1.7.1 (16 Oct 2016)
|
||
|
||
* Fixing bug where `decodeEntitiesInConfiguration()` would cause the
|
||
configuration to set the space for units to an empty string.
|
||
|
||
|
||
PHP SmartyPants Lib 1.7.0 (15 Oct 2016)
|
||
|
||
* Made `public` some configuration variables that were documented
|
||
were documented as `public` but were actually `protected`.
|
||
|
||
* Added the `decodeEntitiesInConfiguration()` method on
|
||
`SmartyPantsTypographer` to quickly convert HTML entities in configuration
|
||
variables to their corresponding UTF-8 character.
|
||
|
||
|
||
PHP SmartyPants Lib 1.6.0 (10 Oct 2016)
|
||
|
||
This is the first release of PHP SmartyPants Lib. This package requires PHP
|
||
version 5.3 or later and is designed to work with PSR-0 autoloading and,
|
||
optionally with Composer. Here is a list of the changes since
|
||
PHP SmartyPants 1.5.1f:
|
||
|
||
* Plugin interface for Wordpress and Smarty is no longer present in
|
||
the Lib package. The classic package is still available if you need it:
|
||
<https://michelf.ca/projects/php-markdown/classic/>
|
||
|
||
* SmartyPants parser is now encapsulated in its own class, with methods and
|
||
configuration variables `public` and `protected` protection attributes.
|
||
This has been available in unreleased versions since a few years, but now
|
||
it's official.
|
||
|
||
* SmartyPants now works great with PSR-0 autoloading and Composer. If
|
||
however you prefer to more directly `require_once` the files, the
|
||
".inc.php" variants of the file will make sure everything is included.
|
||
|
||
* For those of you who cannot use class autoloading, you can now
|
||
include `Michelf/SmartyPants.inc.php` or
|
||
`Michelf/SmartyPantsTypographer.inc.php` (note the `.inc.php` extension)
|
||
to automatically include other files required by the parser.
|