# Highlight.js

Highlight.js нужен для подсветки синтаксиса в примерах кода в блогах, 
форумах и вообще на любых веб-страницах. Пользоваться им очень просто, 
потому что работает он автоматически: сам находит блоки кода, сам 
определяет язык, сам подсвечивает.

Автоопределением языка можно управлять, когда оно не справляется само (см. 
дальше "Эвристика").

## Подключение и использование

Скрипт подключается одним файлом и одним вызовом инициализирующей 
функции:

    <script type="text/javascript" src="highlight.js"></script>
    <script type="text/javascript">
      initHighlightingOnLoad();
    </script>

Автоматическое определение языков может работать довольно медленно, когда
в него включено много языков, а фрагменты кода обширны. Чтобы ускорить 
процесс, можно перечислить в вызове инициализирующей функции только те 
языки, которые используются в тексте:

    <script type="text/javascript">
      initHighlightingOnLoad('html', 'css');
    </script>

При вызов таким образом highlight.js динамически подгружает соответствующие
языковые файлы и таким образом весит меньше, чем с набором по умолчанию,
который включает все реализованные языки.

Дальше скрипт ищет на странице конструкции `<pre><code>...</code></pre>`, 
которые традиционно используются для написания кода, и код в них 
размечается на куски, помеченные разными значениями классов. Классам 
этим затем надо задать в стилях нужные цвета например так:

    .comment {
      color: gray;
    }

    .keyword {
      font-weight: bold;
    }

    .python .string {
      color: blue;
    }

    .html .atribute .value {
      color: green;
    }

Можно использовать sample.css из комплекта как стартовую точку для собственного 
стиля.

Полный список классов для разных языков приведен ниже ("Языки").

### Плагин к WordPress

Вообще, подключение highlight.js к блогу на [WordPress][wp] ничем не отличается
от подключения куда-либо еще. Однако он может быть подключен к блогу и как плагин.
Это удобно, если блог находится на общественном сервере, где вы не можете
свободно редактировать файлы, или просто если вы привыкли пользоваться плагинами.

Для установки плагина надо скопировать всю директорию с файлами highlight.js в 
директорию плагинов WordPress. После этого в панели плагинов его можно
будет включать и отключать. В меню Options также добавляется страничка
highlight.js, где можно настраивать список языков и CSS-стили. Удобно до одурения :-).

[wp]: http://wordpress.org/


## Экспорт

В файле export.html находится небольшая программка, которая показывает и дает 
скопировать непосредственно HTML-код подсветки для любого заданного фрагмента кода. 
Это может понадобится например на сайте, на котором нельзя подключить сам скрипт
highlight.js. 


## Языки

В списке приведены все языки, которые знает библиотека с классами, 
соответствующими различным синтаксическим частям.

Python:
    
  keyword          ключевое слово языка
  number           число
  string           строка (любого типа)
  comment          комментарий
  decorator        @-декоратор функции
  function         заголовок функции "def some_name(...):"
  class            заголовок класса "class SomeName(...):"
  title            название функции или класса внутри заголовка
  params           все, что в скобках внутри заголовка функции или класса

Ruby:
    
  keyword          ключевое слово языка
  string           строка
  subst            внутристроковая подстановка (#{...})
  comment          комментарий
  function         заголовок функции "def ..."
  class            заголовок класса "class ..."
  title            название функции или класса внутри заголовка
  symbol           символ

Perl:
    
  keyword          ключевое слово языка
  comment          комментарий
  number           число
  string           строка
  regexp           регулярное выражение
  sub              заголовок процедуры (от "sub" до "{")
  variable         переменная, начинающаяся с "$", "%", "@"
  operator         оператор
  pod              документация (plain old doc)

PHP:
    
  keyword          ключевое слово языка
  number           число
  string           строка (любого типа)
  comment          комментарий
  phpdoc           параметры phpdoc в комментарии
  variable         переменная, начинающаяся с "$"

XML:
    
  tag              любой открывающий или закрывающий тег от "<" до ">"
  comment          комментарий
  pi               инструкции обработки (<?php ... ?>)
  cdata            раздел CDATA
  attribute        атрибут
  value            значение атрибута

HTML:
    
  keyword          тег языка HTML
  tag              любой открывающий или закрывающий тег от "<" до ">"
  comment          комментарий
  doctype          объявление <!DOCTYPE ... >
  attribute        атрибут внутри тега со значением или без
  value            значение атрибута

CSS:
    
  keyword          тег языка HTML в селекторах или свойство CSS в правилах
  id               #some_name в селекторах
  class            .some_name в селекторах
  attr_selector    селектор атрибутов (квадатные скобоки в a[href^=http://])
  comment          комментарий
  rules            все от "{" до "}"
  value            значение свойства внутри правила, все от ":" до ";" или
                   до конца блока правил

Django:

  keyword          тег HTML в HTML, встроенные шаблонные теги и фильтры в шаблонах
  tag              любой открывающий или закрывающий тег от "<" до ">"
  comment          комментарий
  doctype          объявление <!DOCTYPE ... >
  attribute        атрибут внутри тега со значением или без
  value            значение атрибута
  template_tag     шаблонный тег {% .. %}
  variable         шаблонная переменная {{ .. }}
  template_comment шаблонный комментарий, и {# .. #}, и {% comment %}
  filter           фильтр от "|" до следующего фильтра или до конца тега
  argument         аргумент фильтра

Javascript:
    
  keyword          ключевое слово языка
  comment          комментарий
  number           число
  literal          специальное слово: "true", "false" и "null"
  string           строка
  regexp           регулярное выражение
  function         заголовок функции
  title            название функции внутри заголовка
  params           все, что в скобках внутри заголовка функции

VBScript:
    
  keyword          ключевое слово языка
  comment          комментарий
  number           число
  string           строка
  built_in         встроенная функция

Delphi:
    
  keyword          ключевое слово языка
  comment          комментарий (любого типа)
  number           число
  string           строка
  function         заголовок функции, процедуры, конструктора или деструктора
  title            название функции, процедуры, конструктора или деструктора
                   внутри заголовка
  params           все, что в скобках внутри заголовка функций
  class            тело класса от "= class" до "end;"

Java:
    
  keyword          ключевое слово языка
  number           число
  string           строка
  comment          комментарий
  annotaion        аннотация
  javadoc          javadoc-комментарии
  class            заголовок класса от "class" до "{"
  title            название класса внутри заголовка
  params           все, что в скобках внутри заголовка класса
  inheritance      слова "extends" и "implements" внутри заголовка класса

C++:
    
  keyword          ключевое слово языка
  number           число
  string           строка и одиночный символ
  comment          комментарий
  preprocessor     директива препроцессора

RenderMan (RSL):
    
  keyword          ключевое слово языка
  number           число
  string           строка
  comment          комментарий
  preprocessor     директива препроцессора
  shader           ключевое слово шейдеров
  shading          ключевое слово затенений
  built_in         встроенная функция

RenderMan (RIB):
    
  keyword          ключевое слово языка
  number           число
  string           строка
  comment          комментарий
  commands         команда

SQL:
    
  keyword          ключевое слово (в основном из SQL'92 и SQL'99)
  number           число
  string           строка (любого типа: "..", '..', `..`)
  comment          комментарий
  aggregate        агрегатная функция

Smalltalk:

  keyword          ключевое слово
  number           число
  string           строка
  comment          комментарий
  symbol           символ
  array            массив
  class            имя класса
  char             буква
  localvars        блок локальных переменных

Axapta:
    
  keyword          ключевое слово языка
  number           число
  string           строка
  comment          комментарий
  class            заголовок класса от "class" до "{"
  title            название класса внутри заголовка
  params           все, что в скобках внутри заголовка класса
  inheritance      слова "extends" и "implements" внутри заголовка класса
  preprocessor     директива препроцессора

1С:

  keyword          ключевое слово языка
  number           число
  string           строка
  comment          комментарий
  function         заголовок функции или процедуры
  title            название функции внутри заголовка
  params           все, что в скобках внутри заголовка функции
  preprocessor     директива препроцессора


## Эвристика

Определение языка, на котором написан фрагмент, делается с помощью 
довольно простой эвристики: программа пытается расцветить фрагмент всеми
языками подряд, и для каждого языка считает количество подошедших 
синтаксически конструкций и ключевых слов. Для какого языка нашлось больше,
тот и выбирается.

Это означает, что в коротких фрагментах высока вероятность ошибки, что
периодически и случается. Чтобы указать язык фрагмента явно, надо написать
его название в виде класса к элементу `<code>`:

    <pre><code class="html">...</code></pre>
    
Чтобы запретить расцветку фрагмента вообще, используется класс "no-highlight":

    <pre><code class="no-highlight">...</code></pre>

## Координаты

Версия: 3.5
URL:    http://softwaremaniacs.org/soft/highlight/
Автор:  Иван Сагалаев (Maniac@SoftwareManiacs.Org)

Лицензионное соглашение читайте в файле LICENSE.
Список соавторов читайте в файле AUTHORS.ru.txt