Статья, оформленная в **REST**
==============================

:Authors:
   Andrey Orlov

.. contents::

Рекомендуется, что бы каждая статья содержала небольшую вводную часть, далее
список разделов и заключение. Следует чувствовать разницу между вводной
частью и абстрактом.

Вводная часть
  Используется для краткого введения в проблему, описываемую в статье. Может
  содержать основные постулаты, небольшой исторический экскурс и т.п.

Абстракт
  Краткое содержание статьи. В идеале абстракт это независимое
  "произведение" позволяющее понять смысл статьи. Но абстракт может
  ограничиваться просто описанием содержимого статьи и ее назначения.

Нежелательно, что бы вводная часть дублировала абстракт. Также,
нежелательно, что бы статья без абстракта выглядела "урезанной": зачастую
статьи и абстракты пишут разные люди.

Эта статья является дополнением к описанию синтаксиса, данному в [1]_ .


Оформление текста
-----------------

Существует традиция выделения фрагментов текста. Достигнуть этого можно
несколькими способами. Можно выделить фрагмент текста **жирным шрифтом** или
*наклонным*. Используя такие способы выделения очень хорошо иметь в голове
строгие правила использования каждого вида выделения и следовать им.

Другой способ выделение фрагмента текста - оформления текста как "врезки".

  **Обычно, врезкой оформляют длинные цитаты или пояснения к тексту. При
  печати они выделяются отступом. Вся врезка целиком может быть выделена
  жирным или наклонным шрифтом.**

Есть и менее оригинальный способ выделения текста: текст оформляется как
"предварительно сформатированный". На самом деле, не рекомендуется
использовать "предварительно сформатированный текст" за исключением
специальных случаев::

  К таким случаям относятся:

     Отображение исходного кода программ

     Отображение специальных текстовых данных.

Как и в случае с инлайновым выделением, желательно иметь строгие правила
использования врезок и следовать им.

Структурные элементы текста
---------------------------

К структурным элемента текста относятся:

1. Списки перечислений,

2. Списки определений,

3. Разделы,

4. Таблицы.

Следует очень аккуратно относиться к использованию структурных элементов,
так чтобы их использование было оправдано. В то же время, в интернет лучше
читается сильно структурированный текст, чем сплошной.

Списки перечислений
~~~~~~~~~~~~~~~~~~~

Списки перечислений бывают:

* Нумерованные,

* Ненумерованные.

Относитесь к списку перечислений как к списку перечислений: каждый элемент
списка должен содержать законченный по смыслу тезис и только один. Нарушение
этого правила резко ухудщает читабельность текста. Разницы между
нумерованными и ненумерованными перечислениями я не вижу, но существует
традиция использование ссылок на элементы нумерованного списка.

Списки определений
~~~~~~~~~~~~~~~~~~

В отличие от списка перечислений, элементы списка определений могут
содержать объемный текст, важно, что бы этот текст подчинялся одной задаче -
описанию термина, вынесенного в заголовок. Вот пример удачного и неудачного
определения:

ReST
    Специальный язык разметки, позволяющий структурировать текст в обычном
    текстовом редакторе и легко преобразовывать его в форму HTML.

ST
    Zope2 часто использовал ST, на ST была даже написана книга по Zope2.

Отличие между двумя определениями очевидно: в первом случае это определние,
во втором - информация на вольную тему, с ним связанная.

В случае, когда тексты определений занимают значительный объем, удобно в
начале раздела привести список кратких определений, а затем в конце раздела
ввести несколько подразделов, по одному на каждое определений, содержащие
полную информацию по данному термину.

Разделы
~~~~~~~

Разделы - это привычная всем конструкция. Однако и для нее существуют
некоторые провила использования. Из них два самых главных это:

+ Никогда не использовать пустые разделы, т.е. разделы содержащие только
  подразделы, но без собственного текста;

+ Никогда не пытаться продолжить писать раздел после завершения текста
  подраздела.

Причина этих ограничений - невозможность или неудобство оформления разделов
с такими нарушениями средствами полиграфии.

Таблицы
~~~~~~~

Оформление таблиц в **ReST** - довольно нудное, хотя и возможное, занятие.
Таблица оформляется обычным выделеним клеток знаками "-", "=", "+" и "|". 
Это неудобно, но хорошо читается и в исходном тексте и в HTML:

+-------------+-------------------+
| Конструкция | Назначение        |
+=============+===================+
| \*\*        | **Жирный шрифт**  |
+-------------+-------------------+
| \*          | *Наклонный шрифт* |
+-------------+-------------------+

Использовать таблицы - хорошая идея, но все-таки оформление их в **ReST**
затруднено.

Ссылки
------

Ссылки существуют следующих видов:

Внешние ссылки
  Используются для ссылок на внешние ресурсы сайта,

Ссылки внутри статьи
  Наиболее употребительная ссылка такого рода - ссылка
  на элемент списка литературы,

WIKI-ссылки
  Это ссылки на другие статьи сайта, оформляются специальными
  макросамми.

Внешние ссылки
~~~~~~~~~~~~~~

Внешние ссылки - самая простая и безпроблемная часть сайта. Достаточно
ввести в тексте статьи URL и этот URL станет ссылкой. Все внешние ссылки
автоматически накрываются тегом nofollow, что является стандартной практикой
улучшения ранжирования в поисковых машинах.

Ссылки внутри статьи
~~~~~~~~~~~~~~~~~~~~

Основная особенность ссылок внутри статьи - они двунаправленные. Перейдя по
ссылке в какое-то место в статье, всегда можно вернуться назад. Это особенно
удобно при оформлении списка литературы, т.к. ссылки на его элементы
разбросаны по всему тексту и удобно читать его, имея возможность вернуться к
тому месту, где на на них ссылались. Список литературы приведен в конце этой
статьи.

WIKI-ссылки
~~~~~~~~~~~

WIKI-ссылки не являются частью **ReST**, но являются частью самой системы
**DreamBot**. Они оформляются при помощи специальных макросов, описанных в
документации на REST.

Рисунки
-------

Ссылки на рисунки могут быть внутренними и внешними. Проще всего иметь дело
со ссылками на внешние ресурсы, например, логотим нашего сайта:

.. image:: /@@/images/logo.jpg

В этом случае не требуется никаких дополнительных действий, достаточно
просто указать расположение ресурса. Сложнее обстоит дело с иллюстрациями к
статье. Для того, чтобы их использовать, внутри статьи должен быть создан
специальный объект-иллюстрация, на который и будет стоять ссылка. Такие
иллюстрации - первый шаг к построению фотогалереи.

.. image:: photo/@@smartimagecontainer/full/get

Но о фотогалереях речь пойдет в другом документе.

Заключение
----------

Эта статья написана, чтобы проиллюстрировать описание **ReST** [1]_ и
доступна в двух вариантах сформатированном [2]_ и нет [3]_. Поэтому читатель
легко может ознакомится со всеми конструкциями, использованными для
оформления. Авторы выражают надежду, что данный текст также является
неплохим руководством по логической разметке текста.


Список литературы
-----------------

.. [1] Описание ReST
.. [2] Сформатированная статья
.. [3] Исходный код образца оформленной статьи
.. [4] Оригинальное руководство по **ReST**: http://docutils.sourceforge.net/rst