<commit_before>Luminous - a Syntax Highlighter for PHP
=======================================

Luminous is an accurate and style-able syntax highlighter for PHP which supports 
a bunch of common languages and output to HTML and LaTeX.

##Links:

+ [Demo](http://luminous.asgaard.co.uk/)
+ [Supported language list](http://luminous.asgaard.co.uk/luminous/supported.php)
+ [Documentation (on the github wiki)](https://github.com/markwatkinson/luminous/wiki)


Installation
============
Extract your tarball, zip, whatever, into some directory where it's going to be
used (i.e. probably your web-server).  We'll assume it's called `luminous/'

Quick Usage 
===========

First, if you're going to use caching, which you probably are, create a 
directory called luminous/cache and give it 777 permissions. Then include 
luminous/luminous.php and away you go!

    <?php 
    require_once 'luminous/luminous.php';
    echo luminous::head_html(); // outputs CSS includes, intending to go in <head>
    echo luminous::highlight('c', 'printf("hello world\n");');
    ?>

Useful examples can be found in luminous/examples/. If you have problems,
check that luminous/examples/example.php works.

A Polite Warning
================

Luminous is now pretty slow. This isn't likely to change. The code is
mostly well structured and the profiler just says it's slow because it's doing
a lot. This isn't going to matter to you if you're just highlighting snippets,
but if you intend to highlight arbitrarily large user input/files then you 
might want to look into some kind of scheduling. Note that highlighting is 
cached by default.


User's API reference
====================

We don't currently have a useful documentation manager, so I'm afraid this
will have to do for now.

The two main highlighting functions are:
  
    luminous::highlight($language, $source, $cache=true)
    luminous::highlight_file($language, $path, $cache=true)
  
Note that $language can be a language code (open supported.php in a browser 
to see a list of what you have available), or your own instance of
LuminousScanner.

    luminous::head_html()
  
This will output several link and script tags. It tries to determine the
correct path to the luminous/ directory relative to the document root, but 
may fail. In this case, you can override it to set it manually. The settings:
'theme', 'relative-root', 'include-javascript' and 'include-jquery' affect
this.

##Themes

    luminous::themes(); 
    luminous::theme_exists($theme_name);

themes() returns a list of themes present in the style/ directory. Use this <commit_msg>readme improvements<commit_after>Luminous - a Syntax Highlighter for PHP
=======================================

Luminous is an accurate and style-able syntax highlighter for PHP which supports 
a bunch of common languages and output to HTML and LaTeX.

##Links:

+ [Demo](http://luminous.asgaard.co.uk/)
+ [Supported language list](http://luminous.asgaard.co.uk/luminous/supported.php)
+ [Documentation (on the github wiki)](https://github.com/markwatkinson/luminous/wiki)


Installation
============
Extract your tarball, zip, whatever, into some directory where it's going to be
used (i.e. probably your web-server).  We'll assume it's called `luminous/'

Quick Usage 
===========

First, if you're going to use caching, which you probably are, create a 
directory called luminous/cache and give it 777 permissions. Then include 
luminous/luminous.php and away you go!

    <?php 
    require_once 'luminous/luminous.php';
    echo luminous::head_html(); // outputs CSS includes, intending to go in <head>
    echo luminous::highlight('c', 'printf("hello world\n");');
    ?>

Useful examples can be found in luminous/examples/. If you have problems,
check that luminous/examples/example.php works.

A Polite Warning
================

A few things you should bear in mind:

+ Highlighted output is *massive*, expect around 10x the size, so you really
do want to be using gzip (it's very gzippable).
+ Luminous is now pretty slow. This isn't likely to change. The code is
mostly well structured and the profiler just says it's slow because it's doing
a lot, and I'm not going to start messing with the structure to favour 
performance because as anyone who has tried that knows, that's the first step
towards code that can only be described as 'a mess'.
+ Memory usage is also pretty obscene right now. This might go down in future
if I find any way of profiling it. 

Note that the last two are irrelevant for most use cases because Luminous
features transparent caching, and if your inputs are at most a few KB (e.g.
snippets on a blog), then they're too small to run up much performance 
penalty. However they are very important considerations if you are highlighting 
arbitrarily sized user input.

If any of these things bothers you, you've got a few options: 

1. use an old version of Luminous. The 
[0.5 branch](http://code.google.com/p/luminous) works much faster (but for 
complex languages, not as well)
2. Use GeSHi, although I tried this one once; look where it got us ;)
3. Rewrite your project in Python

I recommend option 3.


User's API reference
====================

We don't currently have a useful documentation manager, so I'm afraid this
will have to do for now.

The two main highlighting functions are:
  
    luminous::highlight($language, $source, $cache=true)
    luminous::highlight_file($language, $path, $cache=true)
  
Note that $language can be a language code (open supported.php in a browser 
to see a list of what you have available), or your own instance of
LuminousScanner.

    luminous::head_html()
  
This will output several link and script tags. It tries to determine the
correct path to the luminous/ directory relative to the document root, but 
may fail. In this case, you can override it to set it manually. The settings:
'theme', 'relative-root', 'include-javascript' and 'include-jquery' affect
this.

##Themes

    luminous::themes(); 
    luminous::theme_exists($theme_name);

themes() returns a list of themes present in the style/ directory. Use this 
{'fraction_non_alphanumeric': 0.10650499754219236, 'fraction_numerical': 0.002293953793216451, 'mean_word_length': 4.368513632365875, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6354838', 'n_tokens_mistral': 1796, 'n_tokens_neox': 1614, 'n_words': 800}