Что такое ReStructuredText текст?
ReStructuredText - это легкий для чтения, WYSIWYG (what-you-see-is-what-you-get) языка разметки текста и соответствующий парсер. Он удобен для документирования программ непосредственно в исходном коде (как docstrings в Python), для быстрого создания простых веб-страниц и для автономных документов. ReStructuredText допускает расширяемость при применении в конкретных прикладных областях . ReStructuredText --- это переработка и переосмысление легковесных систем разметки текста StructuredText и Setext.
Новички в Вики часто считают разметку ReStructuredText более естественной и простой для изучения, чем разметка, используемая в MoinMoin по умолчанию.
Парсер ReStructuredText
Установка
Для того, чтобы получить возможность использовать эту разметку, необходимо установить пакет Python docutils, который обеспечивает в MoinMoin поддержку ReStructuredText.
Необходимая версия пакета docutils зависит от версии MoinMoin. Если этот текст --- часть Вашей инсталляции MoinMoin, вероятно у Вас установлен MoinMoin версии 1.5 или более новой, для которой (по состоянию на Январь 2006) требуется docutils версии 0.4.0 или более новой, или новейший вариант (snapshot) версии 0.3.10. Если MoinMoin используется под Linux, пакет docutils весьма вероятно уже доступен в составе Вашего дистрибутива Linux. Так например в Debian GNU/Linux достаточно просто набрать apt-get install python-docutils. В других дистрибутивах Linux могут использоваться иные варианты установки пакетов, читайте документацию к Вашему дистрибутиву Linux.
Парсер в MoinMoin
Парсер поддерживает те же возможности, что и редактор docutils HTML writer. Однако, некоторые особенности были немного изменены для улучшения взаимодействия с MoinMoin. Отличия перечислены ниже.
Использование ReST в MoinMoin
Пример
Это *очень* простой пример. Если Вы видите две звездочки, окружающие слово "очень" в предыдущем предложении, это означает, что модуль docutils установлен неверно (или не установлен вообще). Если модуль docutils установлен, слово "очень" должно отображаться курсивом, а весь этот абзац --- отображаться не в специальном формате, используемом для исходного кода программ, а как обычная часть страницы.
Неопределенные ссылки
Неопределенные ссылки используются для создания вики-ссылок. В обычной ситуации, неопределенная ссылка приводит к ошибке в reStructuredText документе. Но, чтобы обеспечить поведение, аналогичное Вики, неопределенные ссылки создают ссылки на вики-страницы, используя имя такой ссылки в качестве имени этой вики-страницы. Например:
{{{#!rst
Это ссылка на страницу MoinMoin с именем SecondPage_.
}}}Это ссылка на страницу MoinMoin с именем SecondPage_.
Вышеприведенный пример содержит reStructuredText ссылку на "SecondPage". В обычной ситуации такая ссылка вызвала бы в парсере docutils ошибку "ссылка на неизвестный объект", так как в документе нет части с именем "SecondPage". Но в парсере MoinMoin cсылка "SecondPage_" вместо генерации ошибки создает ссылку на страницу MoinMoin с именем "SecondPage".
Поддержка специфичных для MoinMoin схем ссылок
Спецефичные для MoinMoin схемы ссылок поддерживаются, если они указываются в reStructuredText-гиперссылке явным образом. Например:
{{{#!rst
Это ссылка на страницу attachment__.
__ attachment:Attachment.zip
}}}Это ссылка на страницу attachment__. __ attachment:Attachment.zip
Вышеприведенный пример создает ссылку на вложение с названием Attachment.zip. Если на странице нет вложения, ссылка будет заменена на стандартный текст MoinMoin с приглашением загрузить вложение. Поддерживаются следующие стандартные схемы ссылок MoinMoin:
wiki:
attachment:
inline:
drawing:
Включённые изображения
Директивы изображений docutils, не являющиеся URL-ами, преобразуются в ссылки MoinMoin inline:. Это обеспечивает желаемый результат --- вставку изображения в документ. Если вложения с изображением не существует, будет отображено стандартное приглашение MoinMoin для загрузки нового вложения. Например:
{{{#!rst
Это фотография, которую я сделал вчера |image|
.. |image| image:: Yesterday.jpg
}}}Это фотография, которую я сделал вчера |image| .. |image| image:: Yesterday.jpg
В вышеприведенном примере будет выполнена вставка изображения "Yesterday.jpg" вместо |image|.
Экспериментальные возможности
Директивы включения и макроса на данный момент имеют статус экспериментальных, так как не были тщательно протестированы. Предположительно, они работают задуманным образом, но пока широко не использовались.
Поддержка включения
Директива включения reStructuredText поддерживается с некоторыми ограничениями. Эта директива позволяет включать в страницу вики-страницы из той же вики(не считая вложений). Включаемые страницы должны быть оформлены с использованием разметки reStructuredText (страницы в вики-разметке приведут к получению неверно отформатированных документов). Например, нижеприведенный код вставит верхний и нижний колонтитулы, окружающие содержимое страницы.
{{{#!rst
.. include:: header
Текст самого документа.
.. include:: footer
}}}Количество включаемых документов ограничено десятью. Это сделано для защиты от DoS атак, использующих рекурсивные директивы включения.
Поддержка Макро
Парсер reStructuredText в MoinMoin добавляет новую, специфичную для MoinMoin директиву макро. Эта директива позволяет получить доступ к макрокоммандам MoinMoin из документа reStructuredText. Например:
{{{#!rst
Использование макрокомманды поиска заголовков для вставки поля поиска по заголовкам страниц.
.. macro:: <<TitleSearch>>
}}}Использование макро поиска заголовков для вставки поля поиска по заголовкам страниц. .. macro:: <<TitleSearch>>
Известные проблемы
Docutils и MoinMoin используют разные наборы css директив. Некоторые директивы совпадают, некоторые нет. Например, директива заметки не отображается с любым особым форматированием. Эта проблема особенно актуальна при использовании темы с панелью справа вместе с директивой боковой панели docutils (sidebar). Боковая панель docutils заменяет боковую панель MoinMoin. На данный момент рекомендуется не использовать директиву боковой панели в MoinMoin.
- Возможности, связанные с получением внешних URL и файлов с локальных дисков не поддерживаются парсером в целях обеспечения локальной безопасности. Кроме того необработанные роли и другие возможности, которые могут дать пользователю возможность выводить необработанный HTML код, также запрещены.