h1. TEXTILE

p. *A Humane Web Text Generator*

p. A lightweight markup language that takes (almost) plaintext and converts it into well formed HTML.


h2. Branches

There are two main branches in the repository that will be of interest, both of which can be installed via the "Composer":https://getcomposer.org/ package management system.

|^=. "master":https://github.com/netcarver/textile/tree/master | Has a multi-file, namespaced, "PSR-0/1/2":https://github.com/php-fig/fig-standards/tree/master/accepted compliant version of textile. Releases from master are tagged v3.5.x |^=. _Requires PHP5.3+_ |
|^=. "2.5":https://github.com/netcarver/textile/tree/2.5       | Holds a single-file version of textile representing the v2.5.x releases. It is *not* PSR-0 compliant but attempts to follow PSR-1 and PSR-2 in other respects.               |^=. _Requires PHP5.0+_ |

*This is the documentation for the 2.5 branch*

Currently both branches are feature synchronised at the point they are tagged and new features and bugfixes will go into both branches (where possible) for the time being but this _will_ change at some point in the future.

From time to time other branches may be present in the repository. These represent transient development or hotfix branches and should not be used for live sites/projects.


h2. Installation & Usage

h3. Manual Install & Include

The only file that is necessary for the correct operation of Textile 2.* is @classTextile.php@ from the root directory. To use it, just grab the latest raw copy of "classTextile.php":https://raw.github.com/netcarver/textile/2.5/classTextile.php and save it into your project. Now you have the source file installed you'll need to include the file and create a parser...

bc.. include "classTextile.php"; // adjust path the if needed.
$parser = new Textile();

p. Then, for input that you control, pass it to @TextileThis()@. Like so...

bc. $output = $parser->textileThis( $trusted_input );

If you are using Textile to format user-supplied input, blog comments for instance, use a @TextileRestricted()@ call...

bc. $output = $parser->textileRestricted( $untrusted_input );


h3. Via Composer & Its Autoloader

To start using textile in your project you need to make your project depend upon netcarver/textile and have composer take care of the installation and autoloading of the code for you. If you don't already have a @composer.json@ file in the root of your projet create one and paste the following into it...

bc.. {
    "require": { "netcarver/textile": "2.5.*@dev" }
}

p. Then open a command line window, switch to thre root of your project and run @composer install@. Textile should be pulled into your project under a new @vendors/@ directory and an autoloader created for all the dependencies in your project. If you are already using Composer and have a @composer.json@ file, just add the "netcarver/textile..." part to your existing "requires" section and run @composer update@ from the command line. You should now be able to create and use a textile parser...

bc.. require 'vendor/autoload.php';
$parser = new Textile('xhtml');                  // Targetting XHTML
$out = $parser->textileThis('h1. Hello World!'); // $out now holds the XHTML version of the input.

p. Ok, now for a little more detail about setting up your parser.


h3. Doctypes

Currently, PHP Textile can target either XHTML or HTML5 output with XHTML being the default for backward compatibility. If you need HTML5 generation, just do...

bc. $parser = new Textile('html5');

...and you'll get @abbr@ instead of @acronym@ and if you use alignment markers on your images you'll have extra classes placed on them instead of xhtml's @align@ attribute.

h3. Setting alternate glyphs

From v2.5 on, you can no longer use the legacy 'txt_' defines to override the characters textile will use when doing typographic substitutions. If you need to setup textile to do non-standard typographic substitutions then you need to call @setSymbol('name', 'value');@ to setup the symbol table before you call @textileThis()@ or @textileRestricted()@.

If you wanted to override the symbol output for the one-half typographic substitution from the standard @&#189;@ to something using the fraction-slash you could do it like this...

bc.. $parser = new Textile('html5'); // adjust if you need a different doctype
$out = $parser
    ->setSymbol('half', '1&#8260;2')  // Redefine the half symbol to use the fraction-slash character
    ->textileThis($article)
    ;

p. The symbol names you can pass to @setSymbol()@ can be found "here":https://github.com/netcarver/textile/blob/582fb7e2af83bb043fe6dd3846220796c814f999/classTextile.php#L468.

h3. Prefixing relative image paths

From v2.5 onward you can explicitly setup a prefix that will be added to all relative image paths. This might be useful if your application only allows users to reference images from a certain location like, say, an images directory. The @setRelativeImagePrefix()@ method is now available to you for explicitly setting this if you need it.

bc.. $parser = new Textile('html5'); // target whatever doctype you need
$out = $parser
   ->setRelativeImagePrefix('prefix') // adjust 'prefix' as needed
   ->textileThis($article)            // format the article
   ;

p. Textpattern is one project that is known to use a relative image prefix.

h2. Getting In Contact

The textile project welcomes constructive input and bug reports from users. You can contact me in several ways. 

* "Open an issue":https://github.com/netcarver/textile/issues on the repository for a feature request or bug.
* If you are on IRC, feel free to drop into *#textile* on *freenode.net* ("webchat":http://webchat.freenode.net/?channels=#textile.)
* Use the generic "contact form":http://sitemonks.com/.

