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):
<section>
<title>
Часть 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/