public/assets/plugins/ckeditor/plugins/codesnippet/lib/highlight/README.ru.md

   1 # Highlight.js\r
   2 \r
   3 Highlight.js нужен для подсветки синтаксиса в примерах кода в блогах,\r
   4 форумах и вообще на любых веб-страницах. Пользоваться им очень просто,\r
   5 потому что работает он автоматически: сам находит блоки кода, сам\r
   6 определяет язык, сам подсвечивает.\r
   7 \r
   8 Автоопределением языка можно управлять, когда оно не справляется само (см.\r
   9 дальше "Эвристика").\r
  10 \r
  11 \r
  12 ## Простое использование\r
  13 \r
  14 Подключите библиотеку и стиль на страницу и повесть вызов подсветки на\r
  15 загрузку страницы:\r
  16 \r
  17 ```html\r
  18 <link rel="stylesheet" href="styles/default.css">\r
  19 <script src="highlight.pack.js"></script>\r
  20 <script>hljs.initHighlightingOnLoad();</script>\r
  21 ```\r
  22 \r
  23 Весь код на странице, обрамлённый в теги `<pre><code> .. </code></pre>`\r
  24 будет автоматически подсвечен. Если вы используете другие теги или хотите\r
  25 подсвечивать блоки кода динамически, читайте "Инициализацию вручную" ниже.\r
  26 \r
  27 - Вы можете скачать собственную версию "highlight.pack.js" или сослаться\r
  28   на захостенный файл, как описано на странице загрузки:\r
  29   <http://highlightjs.org/download/>\r
  30 \r
  31 - Стилевые темы можно найти в загруженном архиве или также использовать\r
  32   захостенные. Чтобы сделать собственный стиль для своего сайта, вам\r
  33   будет полезен [CSS classes reference][cr], который тоже есть в архиве.\r
  34 \r
  35 [cr]: http://highlightjs.readthedocs.org/en/latest/css-classes-reference.html\r
  36 \r
  37 \r
  38 ## node.js\r
  39 \r
  40 Highlight.js можно использовать в node.js. Библиотеку со всеми возможными языками можно\r
  41 установить с NPM:\r
  42 \r
  43     npm install highlight.js\r
  44 \r
  45 Также её можно собрать из исходников с только теми языками, которые нужны:\r
  46 \r
  47     python3 tools/build.py -tnode lang1 lang2 ..\r
  48 \r
  49 Использование библиотеки:\r
  50 \r
  51 ```javascript\r
  52 var hljs = require('highlight.js');\r
  53 \r
  54 // Если вы знаете язык\r
  55 hljs.highlight(lang, code).value;\r
  56 \r
  57 // Автоопределение языка\r
  58 hljs.highlightAuto(code).value;\r
  59 ```\r
  60 \r
  61 \r
  62 ## AMD\r
  63 \r
  64 Highlight.js можно использовать с загрузчиком AMD-модулей.  Для этого его\r
  65 нужно собрать из исходников следующей командой:\r
  66 \r
  67 ```bash\r
  68 $ python3 tools/build.py -tamd lang1 lang2 ..\r
  69 ```\r
  70 \r
  71 Она создаст файл `build/highlight.pack.js`, который является загружаемым\r
  72 AMD-модулем и содержит все выбранные при сборке языки. Используется он так:\r
  73 \r
  74 ```javascript\r
  75 require(["highlight.js/build/highlight.pack"], function(hljs){\r
  76 \r
  77   // Если вы знаете язык\r
  78   hljs.highlight(lang, code).value;\r
  79 \r
  80   // Автоопределение языка\r
  81   hljs.highlightAuto(code).value;\r
  82 });\r
  83 ```\r
  84 \r
  85 \r
  86 ## Замена TABов\r
  87 \r
  88 Также вы можете заменить символы TAB ('\x09'), используемые для отступов, на\r
  89 фиксированное количество пробелов или на отдельный `<span>`, чтобы задать ему\r
  90 какой-нибудь специальный стиль:\r
  91 \r
  92 ```html\r
  93 <script type="text/javascript">\r
  94   hljs.configure({tabReplace: '    '}); // 4 spaces\r
  95   // ... or\r
  96   hljs.configure({tabReplace: '<span class="indent">\t</span>'});\r
  97 \r
  98   hljs.initHighlightingOnLoad();\r
  99 </script>\r
 100 ```\r
 101 \r
 102 \r
 103 ## Инициализация вручную\r
 104 \r
 105 Если вы используете другие теги для блоков кода, вы можете инициализировать их\r
 106 явно с помощью функции `highlightBlock(code)`. Она принимает DOM-элемент с\r
 107 текстом расцвечиваемого кода и опционально - строчку для замены символов TAB.\r
 108 \r
 109 Например с использованием jQuery код инициализации может выглядеть так:\r
 110 \r
 111 ```javascript\r
 112 $(document).ready(function() {\r
 113   $('pre code').each(function(i, e) {hljs.highlightBlock(e)});\r
 114 });\r
 115 ```\r
 116 \r
 117 `highlightBlock` можно также использовать, чтобы подсветить блоки кода,\r
 118 добавленные на страницу динамически. Только убедитесь, что вы не делаете этого\r
 119 повторно для уже раскрашенных блоков.\r
 120 \r
 121 Если ваш блок кода использует `<br>` вместо переводов строки (т.е. если это не\r
 122 `<pre>`), включите опцию `useBR`:\r
 123 \r
 124 ```javascript\r
 125 hljs.configure({useBR: true});\r
 126 $('div.code').each(function(i, e) {hljs.highlightBlock(e)});\r
 127 ```\r
 128 \r
 129 \r
 130 ## Эвристика\r
 131 \r
 132 Определение языка, на котором написан фрагмент, делается с помощью\r
 133 довольно простой эвристики: программа пытается расцветить фрагмент всеми\r
 134 языками подряд, и для каждого языка считает количество подошедших\r
 135 синтаксически конструкций и ключевых слов. Для какого языка нашлось больше,\r
 136 тот и выбирается.\r
 137 \r
 138 Это означает, что в коротких фрагментах высока вероятность ошибки, что\r
 139 периодически и случается. Чтобы указать язык фрагмента явно, надо написать\r
 140 его название в виде класса к элементу `<code>`:\r
 141 \r
 142 ```html\r
 143 <pre><code class="html">...</code></pre>\r
 144 ```\r
 145 \r
 146 Можно использовать рекомендованные в HTML5 названия классов:\r
 147 "language-html", "language-php". Также можно назначать классы на элемент\r
 148 `<pre>`.\r
 149 \r
 150 Чтобы запретить расцветку фрагмента вообще, используется класс "no-highlight":\r
 151 \r
 152 ```html\r
 153 <pre><code class="no-highlight">...</code></pre>\r
 154 ```\r
 155 \r
 156 \r
 157 ## Экспорт\r
 158 \r
 159 В файле export.html находится небольшая программка, которая показывает и дает\r
 160 скопировать непосредственно HTML-код подсветки для любого заданного фрагмента кода.\r
 161 Это может понадобится например на сайте, на котором нельзя подключить сам скрипт\r
 162 highlight.js.\r
 163 \r
 164 \r
 165 ## Координаты\r
 166 \r
 167 - Версия: 8.0\r
 168 - URL:    http://highlightjs.org/\r
 169 \r
 170 Лицензионное соглашение читайте в файле LICENSE.\r
 171 Список авторов и соавторов читайте в файле AUTHORS.ru.txt\r