## Please edit system and help pages ONLY in the master wiki! ## For more information, please see MoinMoin:MoinDev/Translation. ##master-page:HelpOnParsers/ReStructuredText/RstPrimer ##master-date:2009-12-04 15:08:46 #acl -All:write Default #format rst #language ru ReStructuredText для Начинающих ================================== :Author: Richard Jones :Version: $Revision: 1.17 $ :Copyright: This document has been placed in the public domain. .. contents:: Нижеследующий текст содержит ссылки вида "(quickref__)". Это относительные ссылки на руководство пользователя `Quick reStructuredText`_. Если эти ссылки не работают, можно обращаться к `master quick reference`_. __ .. _Quick reStructuredText: quickref.html .. _master quick reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html Структура ----------- Для начала стоит отметить, что название "Structured Text" ("Структурированный Текст") не слишком удачно. На самом деле, это больше напоминает "Relaxed Text"("Нестрогий Текст"), в котором используются устойчивые обороты. Эти обороты интерпртируются HTML-конвертером и получается "Очень Структурированный Текст", который может использоваться веб-браузером. Базовый распознаваемый паттерн --- **параграф** (quickref__). Это кусок текста, отделённый пустыми строками(одной достаточно). У параграфов должны быть одинаковые отступы, то есть, количество пробелов в левом верхнем углу. Параграфы, начинающиеся с отступа, превращаются в параграфы-цитаты, с отступом. Например: Это параграф. Весьма короткий. Этот параграф превратится в блок текста с отступом, обычно используемый для цитирования другого текста. А это ещё один. Превратится в: Это параграф. Весьма короткий. Этот параграф превратится в блок текста с отступом, обычно используемый для цитирования другого текста. А это ещё один. __ quickref.html#paragraphs Текстовые стили ---------------- (quickref__) __ quickref.html#inline-markup Внутри параграфов или других частей текста можно дополнительно выделять текст *курсивом*, используя "``*курсив*``" или **жирным**, используя "``**жирным**``". Если нужно моноширное начертание, используются "````двойные обратные кавычки````". Обратите внимание, что внутри двойных обратных кавычек дальнейших махинаций уже не производится --- звёздочки "``*``" и т. д. оставляются в покое. Если какой-то из "специальных символов" надо использовать в тексте, обычно все получится хорошо -- reStructuredText достаточно интеллектуален. Например, эта * звёздочка прекрасно обрабатывается. Если нужно, чтобы текст, \*обособленный звёздочками* **не** выделялся курсивом, необходимо обозначить, что звёздочка не используется как специальный символ. Это можно сделать, поставив непосредственно перед ней обратный слэш, вот так "``\*``" (quickref__), или окружив её двойными обратными кавычками(inline literals), вот так:: ``\*`` __ quickref.html#escaping Списки ------- Списки пунктов бывают трех видов: **нумерованные**, **ненумерованные**, **определения**. В любом случае, можно делать сколько угодно параграфов, подспсиков, и т.д., пока левый край параграфа или чего угодно другого имеет тот же отступ, что и первая строка пункта. Списки всегда должны начинаться в новом параграфе, то есть, после пустой строки. **нумерованные** списки (числа, буквы или римские цифры; quickref__) __ quickref.html#enumerated-lists Начинайте пункт с цифры или буквы с последующей точкой ".", правой скобкой ")" или окруженной скобками "( )", смотря что удобней. Все нижеследующие формы распознаются:: 1. числа A. большие буквы и оно продолжается на нескольких строчках даже два параграфа и всё такое! a. маленькие буквы 3. с вложенным спсиком, начинающимся с другого числа 4. всё же, убедитесь, что числа идут в правильной последовательности! I. большие римские цифры i. маленький римские цифры (1) снова числа 1) и снова **ненумерованные** списки (quickref__) __ quickref.html#bullet-lists Точно так же, как и нумерованные списки, новый пункт начинается с новой строки и символа-буллита -- "-", "+" или "*":: * буллит с использованием "*" - вложенный список с использованием "-" + ещё один вложенный список - ещё один пункт Превратится в: * буллит с использованием "*" - вложенный список с использованием "-" + ещё один вложенный список - ещё один пункт **definition** lists (quickref__) __ quickref.html#definition-lists В отличие от остальных двух случаев, списки-определения стостоят из термина и определения этого термина. Формат списков-определений следующий:: what Списки-определения ассоциируют термин с определением. *how* Термин -- это однострочная фраза.Определение -- это один или несколько параграфов или текстовых элементов, с отступами относительно термина. Пустые строки между термином и определением не разрешены. Превратится в: what Списки-определения ассоциируют термин с определением. *how* Термин -- это однострочная фраза.Определение -- это один или несколько параграфов или текстовых элементов, с отступами относительно термина. Пустые строки между термином и определением не разрешены. Преформатирование (примеры) ----------------------------- (quickref__) __ quickref.html#literal-blocks Чтобы просто вставить кусок преформатированного текста, который-никто-не-будет-трогать, завершите предыдущий параграф "``::``". Перформатированный блок завершится, когда текст вернётся на уровень отступа, который был у параграфа предшествующего преформатированному блоку. Пример:: Пробел, новые строки, пустые строки, и все виды разметок ( *такая* или \такая) в подобных блоках сохраняются. Внимание, я изменил отступ (но недостаточно) пример завершён В результате получится: Пример:: Пробел, новые строки, пустые строки, и все виды разметок ( *такая* или \такая) в подобных блоках сохраняются. Внимание, я изменил отступ (но недостаточно) пример завершён Обратите внимание, что если параграф состоит только из "``::``", то он не отображается. :: :: Это преформатированный текст, а последний параграф, состоящий из "::" --- удалён. В результате: :: Это преформатированный текст, а последний параграф, состоящий из "::" --- удалён. Разделы ------------- (quickref__) __ quickref.html#section-structure Чтобы разбить длинный текст на разделы, используйте **заголовки разделов**. Это строка текста(одно или несколько слов) с обрамлением: просто подчеркиванием, или отчеркиванием сверху и снизу, состоящим из минусов "``-----``", знаков равно "``======``", тильд "``~~~~~~``" или любых других неалфавитных символов: ``= - ` : ' " ~ ^ _ * + # < >``, которые Вам нравятся. Подчеркивание отличается от отчеркивания сверху и снизу, состоящего из тех же символов. Подчеркивание/отчеркивание должны быт не корче самого заголовка. Будьте последовательны, така как одинаково обрамлённые разделы будут на одном уровне. :: Часть 1 Заголовок ================= Раздел 1.1 Заголовок --------------------- Глава 1.1.1 Заголовок ~~~~~~~~~~~~~~~~~~~~~~ Раздел 1.2 Заголовок ---------------------- Часть 2 Заголовок ==================== Превратится в следующую структуру(проиллюстрируем на упрощённом псевдо-XML):
Часть 1 Заголовок <section> <title> Раздел 1.1 Заголовок <section> <title> Глава 1.1.1 Заголовок <section> <title> Раздел 1.2 Заголовок <section> <title> Часть 2 Заголовок (В псевдо-XML для указания вложенности используются отступы и нет закрывающих тэгов. Нет возможности продемонстрировать обработанный результат, как в других примерах, потому что разделов не существует внутри двойных кавычек. Для конкретного примера, сравните структуру разделов этого исходного текста этого документа и его же в обработанном виде.) Обратите внимание, что на заголовки разделов можно ссылаться, просто используя их название. Чтобы сослаться на заголовок Списки_, мне достаточно написать "``Списки_``". Если заголовок содержит пробел(ы), как, например, `текстовые стили`_, то нужно обрамить заголовок кавычками: "```текстовые стили`_``". Заголовок / Подзаголовок `````````````````````````` Название документа отличается от названий разделов, и может быть оформлено по другому (например, HTML writer по умолчанию показывает его как отцентированный заголовок). Чтобы выделить название заголовок документа в reStructuredText, используйте уникальный стиль обрамления в начале документа. Чтобы выделить подзаговок, используюте другой ункальный стиль обрамления сразу же после заголовка. Для примера:: ================ Заголовок ================ ----------------- Подзаголовок ---------------- Название Раздела ================== ... Обратите внимание, что и для "Заголовка" и для "Названия раздела" используются знаки равно, ноэто два различных и независмых стиля. Текст отчёркнутых сверху и снизу заголовков (а не просто подчеркнутых) может быть вставлен для эстетики. Изображения -------------- (quickref__) __ quickref.html#directives Чтобы вставить в документ изображение, используйте директиву ``image``. Например:: .. image:: images/biohazard.png Результат: .. image:: images/biohazard.png ``images/biohazard.png`` --- это имя файла с изображением, которое надо включить в документ. На изображение не накладывается никаких ограничений(ни на формат, ни на размер, ни на что-либо ещё). Если изображение будет вставлять в HTML и есть желание указать дополнительную информацию, можно написать так: .. image:: images/biohazard.png :height: 100 :width: 200 :scale: 50 :alt: alternate text Более подробную информацию см. в `image directive documentation`__ . __ ../../ref/rst/directives.html#images Что Дальше? ------------ Это пособие для начинающих описывает наиболее широкоиспользуемые возможности reStructuredText, но их намного больше. Руководство пользователя `Quick reStructuredText`_ будет хорошим продолжением. За детальными подробностями стоит обратится к `reStructuredText Markup Specification`_ [#]_. .. [#] Если относительная ссылка не работает, попробуйте обратится к основному документу: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. .. _reStructuredText Markup Specification: ../../ref/rst/restructuredtext.html .. _post a message: mailto:docutils-users@lists.sourceforge.net .. _Docutils-Users mailing list: http://lists.sourceforge.net/lists/listinfo/docutils-users .. _Docutils project web site: http://docutils.sourceforge.net/