Merge remote-tracking branch 'adambard/master'

1 files changed, 188 insertions, 112 deletions

diff --git a/ru-ru/markdown-ru.html.markdown b/ru-ru/markdown-ru.html.markdown
index eb8e4881..f71435ea 100644
--- a/ru-ru/markdown-ru.html.markdown
+++ b/ru-ru/markdown-ru.html.markdown
@@ -2,55 +2,77 @@
 language: markdown
 contributors:
     - ["Dan Turkel", "http://danturkel.com/"]
+    - ["Jacob Ward", "http://github.com/JacobCWard/"]
+translators:
     - ["Pirogov Alexey", "http://twitter.com/alex_pir"]
+    - ["Andre Polykanine", https://github.com/Oire"]
 filename: markdown-ru.md
 lang: ru-ru
 ---
 
 Язык разметки Markdown создан Джоном Грубером (англ. John Gruber)
-и Аароном Шварцем (англ. Aaron H. Swartz) в 2004 году.
+в 2004 году.
 Авторы задавались целью создать максимально удобочитаемый
 и удобный в публикации облегчённый язык разметки,
 пригодный для последующего преобразования в HTML
 (а также и в другие форматы).
 
+Также реализации Markdown варьируют в зависимости от парсера.
+В этом руководстве будет указано, какие функции универсальны для языка,
+а какие зависят от конкретного парсера.
+
+- [HTML-элементы](#html-elements)
+- [Заголовки](#headings)
+- [Простейшая стилизация текста](#simple-text-styles)
+- [Абзацы](#paragraphs)
+- [Списки](#lists)
+- [Блоки кода](#code-blocks)
+- [Горизонтальный разделитель](#horizontal-rule)
+- [Ссылки](#links)
+- [Изображения](#images)
+- [Разное](#miscellany)
+
+## HTML-элементы
+Markdown является надмножеством HTML, поэтому любой HTML-файл является
+корректным документом Markdown.
+
  ```markdown
-<!-- Markdown является надмножеством HTML, поэтому любой HTML-файл является
-валидным документом Markdown, что позволяет использовать напрямую
+<!-- Это позволяет использовать напрямую
 любые элементы HTML-разметки, такие, например, как этот комментарий.
   Встроенные в документ HTML-элементы не затрагиваются парсером Markdown
-и попадают в итоговый HTML без изменений. Однако, следует понимать,
+и попадают в итоговый HTML без изменений. Однако следует понимать,
 что эта же особенность не позволяет использовать разметку Markdown внутри
 HTML-элементов -->
 
-<!-- Ещё одна особенность формата Markdown состоит в том, что поддерживаемые
-возможности разметки зависят от конкретной реализации парсера. В данном
-руководстве возможности, поддерживаемые лишь определёнными парсерами,
-сопровождаются соответствующими примечаниями. -->
-
-<!-- Заголовки -->
+## Заголовки 
 
-<!-- HTML-элементы от <h1> до <h6> размечаются очень просто:
+HTML-элементы от <h1> до <h6> размечаются очень просто:
 текст, который должен стать заголовком, предваряется
-соответствующим количеством символов "#": -->
+соответствующим количеством символов "#":
+
+```markdown
 # Это заголовок h1
 ## Это заголовок h2
 ### Это заголовок h3
 #### Это заголовок h4
 ##### Это заголовок h5
 ###### Это заголовок h6
+```
+Markdown позволяет размечать заголовки <h1> и <h2> ещё одним способом:
 
-<!-- Markdown позволяет размечать заголовки <h1> и <h2> ещё одним способом: -->
+```markdown
 Это заголовок h1
 ================
 
 А это заголовок h2
 ------------------
+```
 
-<!-- Простейшая стилизация текста -->
+## Простейшая стилизация текста
 
-<!-- Текст легко сделать полужирным и/или курсивным: -->
+Текст легко сделать полужирным и/или курсивным:
 
+```markdown
 *Этот текст будет выведен курсивом.*
 _Так же, как этот._
 
@@ -60,44 +82,58 @@ __И этот тоже.__
 ***Полужирный курсив.***
 **_И тут!_**
 *__И даже здесь!__*
+```
 
-<!-- В Github Flavored Markdown (версии Markdown, использующейся в Github,
-для рендеринга Markdown-документов) текст можно сделать зачёркнутым: -->
+В Github Flavored Markdown, стандарте, который используется в Github,
+текст также можно сделать зачёркнутым:
 
+```markdown
 ~~Зачёркнутый текст.~~
+```
+
+## Абзацы
+
+Абзацами являются любые строки, следующие друг за другом.
+Разделяются же абзацы одной или несколькими пустыми строками:
 
-<!-- Абзацами являются любые строки, следующие друг за другом.
-Разделяются же абзацы одной или несколькими пустыми строками: -->
+```markdown
+Это абзац. Я печатаю в абзаце, разве это не прикольно?
 
-Это абзац. Всё предельно просто.
+А тут уже абзац №2.
+Эта строка всё ещё относится к абзацу №2!
 
-А тут уже параграф №2.
-Эта строка всё ещё относится к параграфу №2!
 
+О, а вот это уже абзац №3!
+```
 
-О, а вот это уже параграф №3!
+Для вставки принудительных переносов можно завершить абзац двумя дополнительными пробелами:
 
-<!-- Для вставки принудительных переносов можно использовать HTML-тэг <br/>: -->
+```markdown
+Эта строка завершается двумя пробелами (выделите, чтобы увидеть!).  
 
-Принудительный <br/> перенос!
+Над этой строкой есть <br />!
+```
 
-<!-- Цитаты размечаются с помощью символа ">": -->
+Цитаты размечаются с помощью символа «>»:
 
+```markdown
 > Это цитата. В цитатах можно
-> принудительно переносить строки, вставляя ">" в начало каждой следующей строки. А можно просто оставлять достаточно длинными, и такие длинные строки будут перенесены автоматически.
+> принудительно переносить строки, вставляя «>» в начало каждой следующей строки. А можно просто оставлять их достаточно длинными, и такие длинные строки будут перенесены автоматически.
 > Разницы между этими двумя подходами к переносу строк нет, коль скоро
-> каждая строка начинается с символа ">"
+> каждая строка начинается с символа «>»
 
 > А ещё цитаты могут быть многоуровневыми:
 >> как здесь
 >>> и здесь :)
 > Неплохо?
+```
 
-<!-- Списки -->
-<!-- Маркированные списки размечаются вставкой в начало каждого элемента
-одного из символов "*", "+" или "-":
-(символ должен быть одним и тем же для всех элементов) -->
+## Списки
+Маркированные списки размечаются вставкой в начало каждого элемента
+одного из символов «*», «+» или «-»:
+(символ должен быть одним и тем же для всех элементов)
 
+```markdown
 * Список,
 * Размеченный
 * Звёздочками
@@ -113,167 +149,207 @@ __И этот тоже.__
 - Список,
 - Размеченный
 - Дефисами
+```
 
-<!-- В нумерованных списках каждая строка начинается
-с числа и точки вслед за ним: -->
+В нумерованных списках каждая строка начинается
+с числа и точки вслед за ним:
 
+```markdown
 1. Первый элемент
 2. Второй элемент
 3. Третий элемент
+```
 
-<!-- Заметьте, нумеровать элементы корректно необязательно. Достаточно указать
-любое число в начале каждого элемента и рендер пронумерует элементы сам!
-Правда, злоупотреблять этим не стоит :) -->
+Заметьте, нумеровать элементы корректно необязательно. Достаточно указать
+любое число в начале каждого элемента, и парсер пронумерует элементы сам!
+Правда, злоупотреблять этим не стоит :)
 
+```markdown
 1. Первый элемент
 1. Второй элемент
 1. Третий элемент
-<!-- (Этот список будет отрендерен так же, как и предыдущий!) -->
+```
+(Этот список будет отображён так же, как и предыдущий!)
 
-<!-- Списки могут быть вложенными: -->
+Списки могут быть вложенными:
 
+```markdown
 1. Введение
 2. Начало работы
 3. Примеры использования
     * Простые
     * Сложные
 4. Заключение
+```
+
+Можно даже делать списки задач. Блок ниже создаёт HTML-флажки. 
 
-<!-- Блоки с исходным кодом -->
-<!-- Фрагменты исходного кода выделяются очень просто - каждая строка блока должна иметь отступ в четыре пробела либо в один символ табуляции -->
+```markdown
+Для отметки флажка используйте «x»
+- [ ] Первая задача
+- [ ] Вторая задача
+Этот флажок ниже будет отмечен
+- [x] Задача была завершена
+```
 
+## Блоки кода
+
+Фрагменты исходного кода (обычно отмечаемые тегом `<code>`) выделяются просто:
+каждая строка блока должна иметь отступ в четыре пробела либо в один символ табуляции.
+
+```markdown
     Это код,
-    причём - многострочный
+    причём многострочный
+```
 
-<!-- Дополнительные отступы в коде следует делать с помощью четырёх пробелов: -->
+Вы также можете делать дополнительные отступы, добавляя символы табуляции
+или по четыре пробела:
 
+```markdown
     my_array.each do |item|
         puts item
     end
+```
 
-<!-- Иногда бывает нужно вставить фрагмент кода прямо в строку текста,
+Иногда бывает нужно вставить фрагмент кода прямо в строку текста,
 не выделяя код в блок. Для этого фрагменты кода нужно обрамлять
-символами "`": -->
+символами «`»:
 
-Например, можно выделить имя функции `go_to()` прямо посреди текста.
+```markdown
+Ваня даже не знал, что делает функция `go_to()`!
+```
 
-<!-- Github Flavored Markdown позволяет указать для блока кода синтаксис оного.
-В этом случае синтаксис внутри блока будет подсвечен. Пример: -->
+В Github Flavored Markdown для блоков кода можно использовать
+специальный синтаксис:
 
-\`\`\`ruby <!-- Только нужно будет убрать символы "\", оставив лишь "```ruby" -->
+<pre>
+<code class="highlight">&#x60;&#x60;&#x60;ruby
 def foobar
-    puts "Hello world!"
+    puts "Привет, мир!"
 end
-\`\`\` <!-- И здесь тоже backslashes нужно убрать, т.е. оставить "```" -->
+&#x60;&#x60;&#x60;</code></pre>
 
-<-- Обратите внимание: фрагмент, указанный выше, не предваряется отступами,
-поскольку Github сам в состоянии определить границы блока - по строкам "```" -->
+Во фрагменте, приведённом выше, отступ не требуется.
+Кроме того, Github подсветит синтаксис языка, указанного после \`\`\`
 
-<!-- Горизонтальный разделитель (<hr />) -->
-<!-- Разделители добавляются вставкой строки из трёх и более
-(одинаковых) символов "*" или "-": -->
+## Горизонтальный разделитель
 
+Разделители (`<hr>`) добавляются вставкой строки из трёх и более
+(одинаковых) символов «*» или «-», с пробелами или без них:
+
+```markdown
 ***
 ---
-- - - <!-- между символами допустимы пробелы -->
+- - -
 ****************
+```
+
+## Ссылки
 
-<!-- Ссылки -->
-<!-- Одной из сильных сторон Markdown можно смело считать то,
+Одной из сильных сторон Markdown можно смело считать то,
 как просто размечаются гиперссылки. Для создания ссылки укажите
 текст ссылки, заключив его в квадратные скобки,
-и сразу после - url, заключенный в "круглые" -->
+и сразу после — URL-адрес, заключенный в круглые
 
+```markdown
 [Ссылка!](http://test.com/)
+```
+Также для ссылки можно указать всплывающую подсказку (`title`), используя
+кавычки внутри круглых скобок:
 
-<!-- Также для ссылки можно указать всплывающую подсказку: -->
-
+```markdown
 [Ссылка!](http://test.com/ "Ссылка на Test.com")
+```
+Относительные пути тоже возможны:
 
-<!-- В url можно использовать относительные пути: -->
-
+```markdown
 [Перейти к музыке](/music/).
+```
 
-<!-- Markdown позволяет размечать ссылку в виде сноски: -->
+Markdown также позволяет размечать ссылку в виде сноски:
 
-[Здесь][link1] высможете узнать больше!
-А можно кликнуть [сюда][foobar], если очень хочется.
+<pre><code class="highlight">&#x5b;<span class="nv">Щёлкните эту ссылку</span>][<span class="ss">link1</span>] для подробной информации!
+&#x5b;<span class="nv">Также посмотрите эту ссылку,</span>][<span class="ss">foobar</span>] если хотите.
 
-<!-- где-нибудь внизу -->
-[link1]: http://test.com/ "Круто!"
-[foobar]: http://foobar.biz/ "Тоже хорошо!"
+&#x5b;<span class="nv">link1</span>]: <span class="sx">http://test.com/</span> <span class="nn">"Круто!"</span>
+&#x5b;<span class="nv">foobar</span>]: <span class="sx">http://foobar.biz/</span> <span class="nn">"Нормально!"</span></code></pre>
 
-<!-- Примечания:
-- Подсказка может быть заключена в одинарные кавычки вместо двойных,
-  а также в круглые скобки.
-- Сноска может находиться в любом месте документа и может иметь
-идентификатор (далее ID) произвольной длины,
-лишь бы это ID был уникальным. -->
+`Title` также может быть в одинарных кавычках или круглых скобках, а также
+отсутствовать вовсе. Ссылки на сноски могут быть в любом месте документа,
+а идентификаторы могут быть какими угодно, лишь бы они были уникальными.
 
-<!-- Также при разметке ссылок-сносок можно опустить ID,
-если текст ссылки уникален в пределах документа: -->
+Существует также неявное именование, когда ссылка является идентификатором.
 
-Ссылка на [Google][].
+<pre><code class="highlight">&#x5b;<span class="nv">Это</span>][] ссылка.
 
-[google]: http://google.com/
+&#x5b;<span class="nv">это</span>]: <span class="sx">http://thisisalink.com/</span></code></pre>
 
-<!-- Правда, эта возможность не очень распространена. -->
+Правда, эта возможность не очень распространена.
 
-<!-- Изображения -->
-<!-- Разметка изображений очень похожа на разметку ссылок.
-Нужно всего лишь добавить "!" перед ссылкой! -->
+## Изображения
+Разметка изображений очень похожа на разметку ссылок.
+Нужно всего лишь добавить перед ссылкой восклицательный знак!
 
+```markdown
 ![Альтернативный текст для изображения](http://imgur.com/myimage.jpg "Подсказка")
+```
+Изображения тоже могут быть оформлены, как сноски.
 
-<!-- Изображения тоже могут быть оформлены, как сноски: -->
-
-![Альтернативный текст][myimage]
-
-![То же изображение ещё раз][myimage]
-
-[myimage]: relative/urls/cool/image.jpg "подсказка"
+<pre><code class="highlight">!&#x5b;<span class="nv">Это альтернативный текст.</span>][<span class="ss">myimage</span>]
 
-<!-- Ещё немного ссылок: -->
-<!-- Автоссылки -->
+&#x5b;<span class="nv">myimage</span>]: <span class="sx">relative/urls/cool/image.jpg</span> <span class="nn">"Если нужна подсказка, её можно добавить"</span></code></pre>
+## Разное
+### Автоссылки
 
+```markdown
 Ссылка вида <http://testwebsite.com/> эквивалентна
 [http://testwebsite.com/](http://testwebsite.com/)
+```
 
-<!-- Автоссылки для адресов электронной почты -->
+### Автоссылки для адресов электронной почты
 
+```markdown
 <foo@bar.com>
+```
+
+### Экранирование символов
 
-<!-- Экранирование символов -->
+```markdown
+Я хочу напечатать *текст, заключённый в звёздочки*, но я не хочу,
+чтобы он был курсивным. Тогда я делаю так:
+\*Текст, заключённый в звёздочки\*
+```
 
-<!-- Может потребоваться вставить спецсимвол в текст "как есть",
-т.е. защитить его от обработки парсером.
-Такой символ должен быть "экранирован" с помощью обратной косой черты
-(символа "\"): -->
+### Клавиши на клавиатуре
+В Github Flavored Markdown для представления клавиш на клавиатуре
+вы можете использовать тег `<kbd>`.
 
-\*текст, заключённый в звёздочки!\*
+```markdown
+Ваш компьютер завис? Попробуйте нажать
+<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd>
+```
 
-<!-- Таблицы -->
-<!-- Таблицы официально поддерживаются только в Github Flavored Markdown,
+### Таблицы
+Таблицы официально поддерживаются только в GitHub Flavored Markdown,
 да и синтаксис имеют не слишком удобный.
-Но если очень нужно, размечайте таблицы так: -->
+Но если очень нужно, размечайте таблицы так:
 
+```markdown
 | Столбец 1    | Столбец 2    | Столбец 3    |
 | :----------- | :----------: | -----------: |
 | Выравнивание | Выравнивание | Выравнивание |
 | влево        | по центру    | вправо       |
+```
+Или более компактно
 
-<!-- Или более компактно -->
-
-Колонка 1|Колонка 2|Колонка 3
+```markdown
+Столбец 1|Столбец 2|Столбец 3
 :--|:-:|--:
 Выглядит|это|страшновато...
-
-<!-- Ну вот и всё! -->
-
 ```
 
-За более подробной информацией обращайтесь к [статье](http://daringfireball.net/projects/markdown/syntax) Джона Грубера о синтаксисе Markdown.
+Ну вот и всё!
 
-Также часто бывает полезной отличная ["шпаргалка"](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) по Markdown от Adam Pritchard.
+За более подробной информацией обращайтесь к [статье](http://daringfireball.net/projects/markdown/syntax) Джона Грубера о синтаксисе Markdown.
 
-Если вдруг встретите ошибки в переводе или же захотите его дополнить, делайте pull requests - авторы всегда рады обратной связи!
+Также часто бывает полезной отличная ["шпаргалка"](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) по Markdown от Адама Притчарда.