1# Highlight.js
2
3Highlight.js нужен для подсветки синтаксиса в примерах кода в блогах,
4форумах и вообще на любых веб-страницах. Пользоваться им очень просто,
5потому что работает он автоматически: сам находит блоки кода, сам
6определяет язык, сам подсвечивает.
7
8Автоопределением языка можно управлять, когда оно не справляется само (см.
9дальше "Эвристика").
10
11## Подключение и использование
12
13В загруженном архиве лежит файл "highlight.pack.js" -- полная сжатая версия
14библиотеки для работы. Все несжатые исходные файлы также есть в пакете, поэтому
15не стесняйтесь в них смотреть!
16
17Скрипт подключается одним файлом и одним вызовом инициализирующей
18функции:
19
20    <script type="text/javascript" src="highlight.pack.js"></script>
21    <script type="text/javascript">
22      hljs.initHighlightingOnLoad();
23    </script>
24
25Также вы можете заменить символы TAB ('\x09'), используемые для отступов, на
26фиксированное количество пробелов или на отдельный `<span>`, чтобы задать ему
27какой-нибудь специальный стиль:
28
29    <script type="text/javascript">
30      hljs.tabReplace = '    '; // 4 spaces
31      // ... or
32      hljs.tabReplace = '<span class="indent">\t</span>';
33
34      hljs.initHighlightingOnLoad();
35    </script>
36
37Несмотря на то, что highlight.pack.js уже содержит только те языки, которые вы
38собираетесь использовать, иногда возникает нужда еще больше оганичить набор языков,
39используемых на странице. Это достигается перечислением их имен при инициализации:
40
41    <script type="text/javascript">
42      hljs.initHighlightingOnLoad('html', 'css');
43    </script>
44
45Полный список классов для разных языков приведен ниже ("Языки").
46
47Дальше скрипт ищет на странице конструкции `<pre><code>...</code></pre>`,
48которые традиционно используются для написания кода, и код в них
49размечается на куски, помеченные разными значениями классов. Классам
50этим затем надо задать в стилях нужные цвета например так:
51
52    .comment {
53      color: gray;
54    }
55
56    .keyword {
57      font-weight: bold;
58    }
59
60    .python .string {
61      color: blue;
62    }
63
64    .html .atribute .value {
65      color: green;
66    }
67
68В комплекте с highlight.js идут несколько стилевых тем в директории styles,
69которые можно использовать напрямую или как основу для собственных экспериментов.
70
71
72### Плагин к WordPress
73
74Вообще, подключение highlight.js к блогу на [WordPress][wp] ничем не отличается
75от подключения куда-либо еще. Однако он может быть подключен к блогу и как плагин.
76Это удобно, если блог находится на общественном сервере, где вы не можете
77свободно редактировать файлы, или просто если вы привыкли пользоваться плагинами.
78
79Для установки плагина надо скопировать всю директорию с файлами highlight.js в
80директорию плагинов WordPress. После этого в панели плагинов его можно
81будет включать и отключать. В меню Options также добавляется страничка
82highlight.js, где можно настраивать список языков и CSS-стили. Удобно до одурения :-).
83
84[wp]: http://wordpress.org/
85
86
87## Экспорт
88
89В файле export.html находится небольшая программка, которая показывает и дает
90скопировать непосредственно HTML-код подсветки для любого заданного фрагмента кода.
91Это может понадобится например на сайте, на котором нельзя подключить сам скрипт
92highlight.js.
93
94
95## Языки
96
97В списке приведены все языки, которые знает библиотека с классами,
98соответствующими различным синтаксическим частям. В скобках после
99названий языков указаны идентификаторы языков, используемые в качестве
100классов элемента `<code>`.
101
102Python ("python"):
103
104  keyword          ключевое слово языка
105  built_in         стандартные значения (None, False, True и Ellipsis)
106  number           число
107  string           строка (любого типа)
108  comment          комментарий
109  decorator        @-декоратор функции
110  function         заголовок функции "def some_name(...):"
111  class            заголовок класса "class SomeName(...):"
112  title            название функции или класса внутри заголовка
113  params           все, что в скобках внутри заголовка функции или класса
114
115Результаты профайлинга Питона ("profile"):
116
117  number           число
118  string           строка
119  builtin          встроенная функция в строке результата
120  filename         имя файла в строке результата
121  summary          итоговые результаты профилирования
122  header           заголовок таблицы результатов
123  keyword          название колонки в заголовке
124  function         название функции в строке результата (включая скобки)
125  title            само название функци в строке результата (без скобок)
126
127Ruby ("ruby"):
128
129  keyword          ключевое слово языка
130  string           строка
131  subst            внутристроковая подстановка (#{...})
132  comment          комментарий
133  function         заголовок функции "def ..."
134  class            заголовок класса "class ..."
135  title            название функции или класса внутри заголовка
136  parent           название родительского класса
137  symbol           символ
138  instancevar      переменная класса
139
140Perl ("perl"):
141
142  keyword          ключевое слово языка
143  comment          комментарий
144  number           число
145  string           строка
146  regexp           регулярное выражение
147  sub              заголовок процедуры (от "sub" до "{")
148  variable         переменная, начинающаяся с "$", "%", "@"
149  operator         оператор
150  pod              документация (plain old doc)
151
152PHP ("php"):
153
154  keyword          ключевое слово языка
155  number           число
156  string           строка (любого типа)
157  comment          комментарий
158  phpdoc           параметры phpdoc в комментарии
159  variable         переменная, начинающаяся с "$"
160  preprocessor     метки препроцессора: "<?php" and "?>"
161
162XML ("xml"):
163
164  tag              любой открывающий или закрывающий тег от "<" до ">"
165  comment          комментарий
166  pi               инструкции обработки (<? ... ?>)
167  cdata            раздел CDATA
168  attribute        атрибут
169  value            значение атрибута
170
171HTML ("html"):
172
173  keyword          тег языка HTML
174  tag              любой открывающий или закрывающий тег от "<" до ">"
175  comment          комментарий
176  doctype          объявление <!DOCTYPE ... >
177  attribute        атрибут внутри тега со значением или без
178  value            значение атрибута
179
180CSS ("css"):
181
182  keyword          тег языка HTML в селекторах или свойство CSS в правилах
183  id               #some_name в селекторах
184  class            .some_name в селекторах
185  at_rule          @-rule до первого "{" или ";"
186  attr_selector    селектор атрибутов (квадатные скобоки в a[href^=http://])
187  pseudo           псевдо-классы и элементы (:after, ::after и т.д.)
188  comment          комментарий
189  rules            все от "{" до "}"
190  value            значение свойства внутри правила, все от ":" до ";" или
191                   до конца блока правил
192  number           число внутри значения
193  string           строка внутри значения
194  hexcolor         шестнадцатеричный цвет (#FFFFFF) внутри значения
195  function         CSS-функция внутри значения
196  params           все от "(" до ")" внутри функции
197
198Django ("django"):
199
200  keyword          тег HTML в HTML, встроенные шаблонные теги и фильтры в шаблонах
201  tag              любой открывающий или закрывающий тег от "<" до ">"
202  comment          комментарий
203  doctype          объявление <!DOCTYPE ... >
204  attribute        атрибут внутри тега со значением или без
205  value            значение атрибута
206  template_tag     шаблонный тег {% .. %}
207  variable         шаблонная переменная {{ .. }}
208  template_comment шаблонный комментарий, и {# .. #}, и {% comment %}
209  filter           фильтр от "|" до следующего фильтра или до конца тега
210  argument         аргумент фильтра
211
212Javascript ("javascript"):
213
214  keyword          ключевое слово языка
215  comment          комментарий
216  number           число
217  literal          специальное слово: "true", "false" и "null"
218  string           строка
219  regexp           регулярное выражение
220  function         заголовок функции
221  title            название функции внутри заголовка
222  params           все, что в скобках внутри заголовка функции
223
224VBScript ("vbscript"):
225
226  keyword          ключевое слово языка
227  comment          комментарий
228  number           число
229  string           строка
230  built_in         встроенная функция
231
232Delphi ("delphi"):
233
234  keyword          ключевое слово языка
235  comment          комментарий (любого типа)
236  number           число
237  string           строка
238  function         заголовок функции, процедуры, конструктора или деструктора
239  title            название функции, процедуры, конструктора или деструктора
240                   внутри заголовка
241  params           все, что в скобках внутри заголовка функций
242  class            тело класса от "= class" до "end;"
243
244Java ("java"):
245
246  keyword          ключевое слово языка
247  number           число
248  string           строка
249  comment          комментарий
250  annotaion        аннотация
251  javadoc          javadoc-комментарии
252  class            заголовок класса от "class" до "{"
253  title            название класса внутри заголовка
254  params           все, что в скобках внутри заголовка класса
255  inheritance      слова "extends" и "implements" внутри заголовка класса
256
257C++ ("cpp"):
258
259  keyword          ключевое слово языка
260  built_in         тип из стандартной библиотеки (включая STL)
261  number           число
262  string           строка и одиночный символ
263  comment          комментарий
264  preprocessor     директива препроцессора
265  stl_container    инстанцирование STL-контейнеров ("vector<...>")
266
267C# ("cs"):
268
269  keyword          ключевое слово языка
270  number           число
271  string           строка (включая @"..")
272  comment          комментарий
273  xmlDocTag        тег в xmldoc ("///", "<!--", "-->", "<..>")
274
275RenderMan RSL ("rsl"):
276
277  keyword          ключевое слово языка
278  number           число
279  string           строка
280  comment          комментарий
281  preprocessor     директива препроцессора
282  shader           ключевое слово шейдеров
283  shading          ключевое слово затенений
284  built_in         встроенная функция
285
286RenderMan RIB ("rib"):
287
288  keyword          ключевое слово языка
289  number           число
290  string           строка
291  comment          комментарий
292  commands         команда
293
294Maya Embedded Language ("mel"):
295
296  keyword          ключевое слово языка
297  number           число
298  string           строка
299  comment          комментарий
300  variable         переменная
301
302SQL ("sql"):
303
304  keyword          ключевое слово (в основном из SQL'92 и SQL'99)
305  number           число
306  string           строка (любого типа: "..", '..', `..`)
307  comment          комментарий
308  aggregate        агрегатная функция
309
310Smalltalk ("smalltalk"):
311
312  keyword          ключевое слово
313  number           число
314  string           строка
315  comment          комментарий
316  symbol           символ
317  array            массив
318  class            имя класса
319  char             буква
320  localvars        блок локальных переменных
321
322Lisp ("lisp"):
323
324  keyword          ключевое слово
325  number           число
326  string           строка
327  comment          комментарий
328  variable         переменная
329  literal          b, t и nil
330  list             неквотированный список
331  title            первый символ неквотированного списка
332  body             остаток неквотированного списка
333  quoted_list      квотированный список: и "(quote .. )", и "'(..)"
334
335Ini ("ini"):
336
337  title            заголовок секции
338  value            значение настройки любого типа
339  string           строка
340  number           число
341  keyword          ключевое слово булевского значения
342
343Apache ("apache"):
344
345  keyword          ключевое слово
346  number           число
347  comment          комментарий
348  literal          "On" и "Off"
349  sqbracket        переменная в rewrite'ах "%{..}"
350  cbracket         опции в rewrite'ах "[..]"
351  tag              начало и конец раздела конфига
352
353DOS ("dos"):
354
355  keyword          ключевое слово
356  flow             команда .bat-файла
357  stream           специальные файлы DOS ("con", "prn", ...)
358  winutils         некоторые (см. dos.js за списком)
359  envvar           переменная окружения
360
361Bash ("bash"):
362
363  keyword          ключевое слово
364  string           строка
365  number           число
366  comment          комментарий
367  literal          специальное слово: "true" и "false"
368  variable         переменная
369  shebang          заголовок интерпретатора скрипта
370
371Diff ("diff"):
372
373  header           заголовок файла
374  chunk            заголовок куска внутри файла
375  addition         добавленные строки
376  deletion         удаленные строки
377  change           измененные строки
378
379Axapta ("axapta"):
380
381  keyword          ключевое слово языка
382  number           число
383  string           строка
384  comment          комментарий
385  class            заголовок класса от "class" до "{"
386  title            название класса внутри заголовка
387  params           все, что в скобках внутри заголовка класса
388  inheritance      слова "extends" и "implements" внутри заголовка класса
389  preprocessor     директива препроцессора
390
3911С ("1c"):
392
393  keyword          ключевое слово языка
394  number           число
395  date             дата
396  string           строка
397  comment          комментарий
398  function         заголовок функции или процедуры
399  title            название функции внутри заголовка
400  params           все, что в скобках внутри заголовка функции
401  preprocessor     директива препроцессора
402
403AVR ассемблер ("avrasm"):
404
405  keyword          ключевое слово языка
406  built_in         предопределенный регистр
407  number           число
408  string           строка
409  comment          комментарий
410  label            метка
411  preprocessor     директива препроцессора
412  localvars        подстановка в .macro
413
414Parser3 ("parser3"):
415
416  keyword          ключевое слово языка
417  number           число
418  comment          комментарий
419  variable         переменная, начинающаяся с "$"
420  preprocessor     директива препроцессора
421  title            пользовательское имя, начинающееся с "@"
422
423
424## Эвристика
425
426Определение языка, на котором написан фрагмент, делается с помощью
427довольно простой эвристики: программа пытается расцветить фрагмент всеми
428языками подряд, и для каждого языка считает количество подошедших
429синтаксически конструкций и ключевых слов. Для какого языка нашлось больше,
430тот и выбирается.
431
432Это означает, что в коротких фрагментах высока вероятность ошибки, что
433периодически и случается. Чтобы указать язык фрагмента явно, надо написать
434его название в виде класса к элементу `<code>`:
435
436    <pre><code class="html">...</code></pre>
437
438Можно использовать рекомендованные в HTML5 названия классов:
439"language-html", "language-php". Также можно назначать классы на элемент
440`<pre>`.
441
442Чтобы запретить расцветку фрагмента вообще, используется класс "no-highlight":
443
444    <pre><code class="no-highlight">...</code></pre>
445
446## Координаты
447
448Версия: 5.7
449URL:    http://softwaremaniacs.org/soft/highlight/
450Автор:  Иван Сагалаев (Maniac@SoftwareManiacs.Org)
451
452Лицензионное соглашение читайте в файле LICENSE.
453Список соавторов читайте в файле AUTHORS.ru.txt
454