ПомощьПоПарсерам/ReStructuredText/RstPrimer
Rendering of reStructured text is not possible, please install Docutils.

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/