Green Future
В помощь участникам сайта Как зарегистрироваться на сайте

REST

Техподдержка  2008-07-29 15:54

Для разметки статей на нашем сайте используется ReST - облегченный набор правил разметки текста. Это руководство - краткий справочник по языку ReST, достаточный для того, чтобы желаемым образом оформлять статьи. Руководство дополнено разделом про специальные макросы CMS DreamBot.

Руководство по использованию reStructuredText

Руководство по использованию reStructuredText

reStructuredText (ReST)- это легкий в использовании набор правил наглядной разметки текста, который сохраняет наглядность текста, но при этом позволяет отформатировать его для отображения в браузере, заменяя таким образом HTML.

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

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

Итак, рассмотрим создание типичных элементов оформления в документах формата ReST.

Что такое заголовок - объяснять не требуется. В зависимости от важности и вложенности, заголовки бывают нескольких уровней. Рекомендуется пользоваться лишь заголовками первого, второго и третьего уровней. Если вы хотите, чтобы текст был оформлен как заголовок первого уровня, его следует подчеркнуть символами =====, если второго уровня - символами -----, если третьего - символами ~~~~~, например:

Это заголовок первого уровня
============================

Это заголовок второго уровня
----------------------------

Это заголовок третьего уровня
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Заголовки должны отделяться от остального текста пустыми строками сверху и снизу.

Абзац, это кусок текста, ограниченный сверху и снизу пустыми строками. Обычно все абзацы располагаются на одном расстоянии от левой стороны документа, но если расстояние от края до какого-то одного блока текста превосходит расстояние до остльных, то этот текст оформляется как блок текста, сдвинутый относительно родительского на величину табуляции. Пример заголовка и трёх его абзацев (три стандартных, а один смещённый вправо относительно остальных):

Это заголовок первого уровня
============================

Это абзац текста, относящегося к заголовку
первого уровня.

Это ещё абзац текста, также относящийся к
заголовку первого уровня

    А этот абзац будет сдвинут относительно других
    на некоторое количество символов. Чтобы такого
    не было - внимательно следите за расстоянием
    от края до оформляемого текста.

Это последний абзац текста, также относящийся к
заголовку первого уровня

Повсеместно возникает необходимость выделять текст жирным шрифтом или курсивом. В ReST это деается очень просто. Если текст должен быть выведен курсивом, его необходимо заключить в символы , если жирным, то в символы *, например:

*Этот текст будет выведен курсивом*

**А этот текст будет выведен жирным шрифтом**

При необходимости вывести именно символ * так, чтобы он не вопринимался как элемент выделения, перед ним следует поставить обратный слэш или заключить в двойные обратные апострофы (на клавиатуре расположены на одной клавише со знаком ~), например так:

\*Этот текст будет выведен обычным шрифтом и будет окружён звездочками\*

``**Этот текст тоже будет окружён звездочками**``

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

После каждого элемента списка и перед каждым элементом списка должна быть пропущена пустая строка, иначе всё оформиться как обычный текст. Для оформления упорядоченных списков применяются следующие маркеры (обратите внимание на то, что после маркеров стоят точки - это необходимо):

1. и т.д. или 1) и т.д. или (1) и т.д. - арабские цифры

A. и т.д. - заглавные буквы латинского алфавита

a. и т.д. - строчные буквы латинского алфавита

I. и т.д. - большие римские цифры

i. и т.д. - маленькие римские цифры

Списки оформляются аналогично в зависимости от желаемого маркера, поэтому приведём пример оформления списка, элементы которого пронумерованы арабскими цифрами:

1) Это первый пункт

2) это второй пункт

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

* - жирный закрашенный круг

- - пустой круг

+ - закрашенный квадрат

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

1) Это первый пункт

    - это первый пункт подсписка

    - это второй пункт подсписка

2) это второй пункт

Обратите внимание, что каждый из пунктов сверху и снизу отделён от других пустой строкой.

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

это какой-то термин
а это определение термина или любая другая информация о нём, которую вы желаете донести до пользователей
это ещё какой-то термин
а это ещё информация

При необходимости термины можно выделять жирным шрифтом или курсивом как описано выше.

Любая ссылка в тексте (начинающаяся с указания протокола, например http) будет оформлена как ссылка и ничего специального для этого делать не надо. Хотите добавить в документ ссылку на проект DreamBot? Делайте это следующим образом:

Спасибо проекту DreamBot (http://dreambot.ru/) за всё

Если текст ссылки хочется спрятать, то конструкция будет более сложная:

Спасибо проекту `DreamBot <http://dreambot.ru/>`_ за всё

В этом тексте слово "DreamBot" будет накрыто ссылкой на

Изображения

Для включения в документ изображений используется специальная директива image. Её параметром является адрес изображения. Например, чтобы добавить на страницу логотип проекта DreamBot, нужно в коде ReST написать следующее:

image::http://dreambot.ru/@@/images/logo.gif

Ссылка может быть как на локальное изображение, так и на удалённое.

Макросы DreamBot

В CMS DreamBot разметка ReST доопределена несколькими макросами, позволяющими указать связи между документами и использовать другие сервисы CMS. Формат всех макросов примерно одинаковый: квадратные скобки, в которые заключен предикат и несколько параметров, разделенных двоеточием.

Макросы Wiki позволяют использовать в ReST аналог wiki-ссылок. Каждая такая ссылка ведет на другую статью, или, при отсутствии подходящей статьи, на форму ее создания. Если ссылке соответствует несколько статей, то при переходе показывается их список.

keyword

Макрос keyword используется для указания ссылки на статью словаря, параметры:

  1. ключевое слово,
  2. текст, который появится под ссылкой на статью словаря (если параметр не указан, то под ссылкой будет первый параметр).

В качестве ключевого слова используется одно из ключевых слов, указанных при создании статьи словаря. Пример:

[ keyword:rest ]

[ keyword:rest:язык разметки ReST ]
name

Макрос name используется для указания ссылок на другие статьи по их имени (т.е. полю title (заголовок)), параметры:

  1. имя статьи,
  2. текст, который появится под ссылкой на статью словаря (если параметр не указан, то под ссылкой будет первый параметр).

Пример:

[ name:Десять слов про ReST ]

[ name:Десять слов про ReST:язык разметки ReST ]

Заключение

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

Полезный сайт лучших советов для бизнесменов для нее.

Вложено:

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

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

Исходный код образца оформленной статьи позволяет легко использовать образец как основу своих статей.

Помощь Новости