Образец оформленной статьи
2008-08-04 02:13Эта статья написана, преимущественно, как образец статьи с использованием ReST. Она содержит все конструкции, описанные в статье про синтаксис ReST, а также некоторые другие: менее очевидные, но тоже полезные. Авторы полагают, что любая статья ресурса должна выглядеть примерно так, как эта: т.е. иметь примерно такую структуру и содержать практически все перечилсенные в ней конструкции. Сам текст представляет собой краткие рекомендации по оформлению статей.
Статья содержит логотип (обратите внимание, это рисунок слева) и пару иллюстраций. Пожалуйста, не путайте одно с другим: логотип это элемент оформления статьи, который вносится чтобы обеспечить ее узнаваемость, а иллюстрация - это смысловое содержание статьи.
Статья, оформленная в REST
| Authors: | Andrey Orlov |
|---|
Рекомендуется, что бы каждая статья содержала небольшую вводную часть, далее список разделов и заключение. Следует чувствовать разницу между вводной частью и абстрактом.
- Вводная часть
- Используется для краткого введения в проблему, описываемую в статье. Может содержать основные постулаты, небольшой исторический экскурс и т.п.
- Абстракт
- Краткое содержание статьи. В идеале абстракт это независимое "произведение" позволяющее понять смысл статьи. Но абстракт может ограничиваться просто описанием содержимого статьи и ее назначения.
Нежелательно, что бы вводная часть дублировала абстракт. Также, нежелательно, что бы статья без абстракта выглядела "урезанной": зачастую статьи и абстракты пишут разные люди.
Эта статья является дополнением к описанию синтаксиса, данному в [1] .
Оформление текста
Существует традиция выделения фрагментов текста. Достигнуть этого можно несколькими способами. Можно выделить фрагмент текста жирным шрифтом или наклонным. Используя такие способы выделения очень хорошо иметь в голове строгие правила использования каждого вида выделения и следовать им.
Другой способ выделение фрагмента текста - оформления текста как "врезки".
Обычно, врезкой оформляют длинные цитаты или пояснения к тексту. При печати они выделяются отступом. Вся врезка целиком может быть выделена жирным или наклонным шрифтом.
Есть и менее оригинальный способ выделения текста: текст оформляется как "предварительно сформатированный". На самом деле, не рекомендуется использовать "предварительно сформатированный текст" за исключением специальных случаев:
К таким случаям относятся: Отображение исходного кода программ Отображение специальных текстовых данных.
Как и в случае с инлайновым выделением, желательно иметь строгие правила использования врезок и следовать им.
Структурные элементы текста
К структурным элемента текста относятся:
- Списки перечислений,
- Списки определений,
- Разделы,
- Таблицы.
Следует очень аккуратно относиться к использованию структурных элементов, так чтобы их использование было оправдано. В то же время, в интернет лучше читается сильно структурированный текст, чем сплошной.
Списки перечислений
Списки перечислений бывают:
- Нумерованные,
- Ненумерованные.
Относитесь к списку перечислений как к списку перечислений: каждый элемент списка должен содержать законченный по смыслу тезис и только один. Нарушение этого правила резко ухудщает читабельность текста. Разницы между нумерованными и ненумерованными перечислениями я не вижу, но существует традиция использование ссылок на элементы нумерованного списка.
Списки определений
В отличие от списка перечислений, элементы списка определений могут содержать объемный текст, важно, что бы этот текст подчинялся одной задаче - описанию термина, вынесенного в заголовок. Вот пример удачного и неудачного определения:
- ReST
- Специальный язык разметки, позволяющий структурировать текст в обычном текстовом редакторе и легко преобразовывать его в форму HTML.
- ST
- Zope2 часто использовал ST, на ST была даже написана книга по Zope2.
Отличие между двумя определениями очевидно: в первом случае это определние, во втором - информация на вольную тему, с ним связанная.
В случае, когда тексты определений занимают значительный объем, удобно в начале раздела привести список кратких определений, а затем в конце раздела ввести несколько подразделов, по одному на каждое определений, содержащие полную информацию по данному термину.
Разделы
Разделы - это привычная всем конструкция. Однако и для нее существуют некоторые провила использования. Из них два самых главных это:
- Никогда не использовать пустые разделы, т.е. разделы содержащие только подразделы, но без собственного текста;
- Никогда не пытаться продолжить писать раздел после завершения текста подраздела.
Причина этих ограничений - невозможность или неудобство оформления разделов с такими нарушениями средствами полиграфии.
Таблицы
Оформление таблиц в ReST - довольно нудное, хотя и возможное, занятие. Таблица оформляется обычным выделеним клеток знаками "-", "=", "+" и "!". Это неудобно, но хорошо читается и в исходном тексте и в HTML:
| Конструкция | Назначение |
|---|---|
| ** | Жирный шрифт |
| * | Наклонный шрифт |
Использовать таблицы - хорошая идея, но все-таки оформление их в ReST затруднено.
Ссылки
Ссылки существуют следующих видов:
- Внешние ссылки
- Используются для ссылок на внешние ресурсы сайта,
- Ссылки внутри статьи
- Наиболее употребительная ссылка такого рода - ссылка на элемент списка литературы,
- WIKI-ссылки
- Это ссылки на другие статьи сайта, оформляются специальными макросамми.
Внешние ссылки
Внешние ссылки - самая простая и безпроблемная часть сайта. Достаточно ввести в тексте статьи URL и этот URL станет ссылкой. Чуть более сложно оформляются фрагменты текста, накрытые ссылкой, сравните, например:
- Прямая ссылка на ;
- Текст, накрытый ссылкой на .
За редким исключением, второй способ оформления ссылок существенно болеее предпочтителен. Все внешние ссылки автоматически накрываются тегом nofollow, что является стандартной практикой улучшения ранжирования в поисковых машинах.
Ссылки внутри статьи
Основная особенность ссылок внутри статьи - они двунаправленные. Перейдя по ссылке в какое-то место в статье, всегда можно вернуться назад. Это особенно удобно при оформлении списка литературы, т.к. ссылки на его элементы разбросаны по всему тексту и удобно читать его, имея возможность вернуться к тому месту, где на на них ссылались. Список литературы приведен в конце этой статьи.
WIKI-ссылки
WIKI-ссылки не являются частью ReST, но являются частью самой системы DreamBot. Они оформляются при помощи специальных макросов, описанных в документации на REST.
Рисунки
Ссылки на рисунки могут быть внутренними и внешними. Проще всего иметь дело со ссылками на внешние ресурсы, например, логотим нашего сайта:
В этом случае не требуется никаких дополнительных действий, достаточно просто указать расположение ресурса. Сложнее обстоит дело с иллюстрациями к статье. Для того, чтобы их использовать, внутри статьи должен быть создан специальный объект-иллюстрация, на который и будет стоять ссылка. Такие иллюстрации - первый шаг к построению фотогалереи.
Но о фотогалереях речь пойдет в другом документе.
Заключение
Эта статья написана, чтобы проиллюстрировать описание ReST [1] и доступна в двух вариантах сформатированном [2] и нет [3]. Поэтому читатель легко может ознакомится со всеми конструкциями, использованными для оформления. Авторы выражают надежду, что данный текст также является неплохим руководством по логической разметке текста.
Список литературы
| [1] | (1, 2) Описание ReST |
| [2] | Сформатированная статья |
| [3] | Исходный код образца оформленной статьи |
| Оригинальное руководство по |
Интересный рассказ про создание статьи на основе REST, Но почему изложено такое узкое подмножество синтаксиса статьи?