Парсер ReStructuredText

ReStructuredText — это легкий для чтения синтаксис разметки текста, парсер для которого включен в состав МойнМойн. Он удобен для документирования программ непосредственно в исходном коде (как docstrings в Python), для быстрого создания простых веб-страниц и для автономных документов. ReStructuredText допускает расширяемость при применении в конкретных прикладных областях. ReStructuredText — это переработка и переосмысление легковесных систем разметки текста StructuredText и Setext.

Новички в Вики часто считают разметку ReStructuredText более естественной и простой для изучения, чем разметка, используемая в МойнМойн по умолчанию.

Установка

Для того, чтобы получить возможность использовать эту разметку, необходимо установить пакет Python docutils, который используется в МойнМойн для поддержки ReStructuredText.

Необходимая версия пакета docutils зависит от версии МойнМойн.

Если этот текст — часть Вашей инсталляции МойнМойн, вероятно, у Вас установлен МойнМойн версии 1.5 или более новой, для которой (по состоянию на январь 2006) требуется docutils версии 0.4.0 или более новой, или новейший вариант (snapshot) версии 0.3.10. Если МойнМойн используется под Linux, пакет docutils, вероятно, уже доступен в составе Вашего дистрибутива Linux. Так, например, в Debian GNU/Linux достаточно просто набрать apt-get install python-docutils. В других дистрибутивах Linux могут использоваться иные варианты установки пакетов, см. документацию к Вашему дистрибутиву Linux.

Парсер в МойнМойн

Парсер поддерживает те же возможности, что и редактор docutils HTML writer. Однако, некоторые особенности были немного изменены для улучшения взаимодействия с МойнМойн. Отличия перечислены ниже.

Использование ReST в МойнМойн

Пример

Это *очень* простой пример. Если Вы видите две звездочки, окружающие слово "очень" в предыдущем предложении, это означает, что модуль docutils установлен неверно (или не установлен вообще). Если модуль docutils установлен, слово "очень" должно отображаться курсивом, а весь этот абзац — отображаться не в специальном формате, используемом для исходного кода программ, а как обычная часть страницы.

Неопределенные ссылки

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

{{{#!rst
Это ссылка на страницу МойнМойн с именем SecondPage_.
}}}

Это ссылка на страницу МойнМойн с именем SecondPage_.

Вышеприведенный пример содержит reStructuredText ссылку на "SecondPage". В обычной ситуации такая ссылка вызвала бы в парсере docutils ошибку "ссылка на неизвестный объект", так как в документе нет части с именем "SecondPage". Но в парсере МойнМойн cсылка "SecondPage_" вместо генерации ошибки создает ссылку на страницу МойнМойн с именем "SecondPage".

Поддержка специфичных для МойнМойн схем ссылок

Спецефичные для МойнМойн схемы ссылок поддерживаются, если они указываются в reStructuredText-гиперссылке явным образом. Например:

{{{#!rst
Это ссылка на страницу attachment__.

__ attachment:Attachment.zip
}}}

Это ссылка на страницу attachment__.

__ attachment:Attachment.zip

Вышеприведенный пример создает ссылку на вложение с названием Attachment.zip. Если на странице нет вложения, ссылка будет заменена на стандартный текст МойнМойн с приглашением загрузить вложение. Поддерживаются следующие стандартные схемы ссылок МойнМойн:

• wiki:

• attachment:

• inline:

• drawing:

Включённые изображения

Директивы изображений docutils, не являющиеся URL-ами, преобразуются в ссылки МойнМойн inline:. Это обеспечивает желаемый результат — вставку изображения в документ. Если вложения с изображением не существует, будет отображено стандартное приглашение МойнМойн для загрузки нового вложения. Например:

{{{#!rst
Это фотография, которую я сделал вчера |image|

.. |image| image:: Yesterday.jpg
}}}

Это фотография, которую я сделал вчера |image|

.. |image| image:: Yesterday.jpg

В вышеприведенном примере будет выполнена вставка изображения "Yesterday.jpg" вместо |image|.

Экспериментальные возможности

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

Поддержка включения

Директива включения reStructuredText поддерживается с некоторыми ограничениями. Эта директива позволяет включать в страницу вики-страницы из той же вики(не считая вложений). Включаемые страницы должны быть оформлены с использованием разметки reStructuredText (страницы в вики-разметке приведут к получению неверно отформатированных документов). Например, нижеприведенный код вставит верхний и нижний колонтитулы, окружающие содержимое страницы.

{{{#!rst
.. include:: header

Текст самого документа.

.. include:: footer
}}}

Количество включаемых документов ограничено десятью. Это сделано для защиты от DoS атак, использующих рекурсивные директивы включения.

Поддержка Макро

Парсер reStructuredText в МойнМойн добавляет новую, специфичную для МойнМойн директиву макро. Эта директива позволяет получить доступ к макрокоммандам МойнМойн из документа reStructuredText. Например:

{{{#!rst
Использование макрокомманды поиска заголовков для вставки поля поиска по заголовкам страниц.

.. macro:: <<TitleSearch>>
}}}

Использование макро поиска заголовков для вставки поля поиска по заголовкам страниц.

.. macro:: <<TitleSearch>>

Известные проблемы

• Docutils и МойнМойн используют разные наборы CSS-директив. Некоторые директивы совпадают, некоторые — нет. Например, директива заметки не отображается с любым особым форматированием. Эта проблема особенно актуальна при использовании темы с панелью справа вместе с директивой боковой панели docutils (sidebar). Боковая панель docutils заменяет боковую панель МойнМойн. На данный момент рекомендуется не использовать директиву боковой панели в МойнМойн.

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

Ссылки

• reStructuredText

• Quick Reference

• Docutils

• A ReStructuredText Primer