Концепции вики-вака-разметки

Эта довольно длинная статья о том, как появилась «вака-разметка», и почему она такая, какая она сейчас есть.

1. О вака-разметке

Если коротко, то вака-разметка — это особый способ форматирования текста, который старается при минимуме спецсимволов и минимальном визуальном искажении «исходного текста» получать после программного преобразования красивый HTML.

Возможностей вака-разметки хватает для полноценного оформления документов, больших и маленьких. Кроме традиционных модификаторов «курсива», «полужирного», «подчёркнутого» и «перечёркнутого» текста, здесь есть и разметка списков (в том числе и многоуровневых), заголовков, таблиц, картинок, выделение цитат и многое.

2. Принципы, положенные в основу

Хотя вака-разметка изначально досталась нам в наследство от проекта WakkaWiki, в её основе были чёткие принципы, которые и определили её дальнейший успех.

Таким образом, формирование правил разметки, хотя и происходило «историческим» путём, всё же руководствовалось небольшим набором принципов, которые помогли разметке остаться удобной и естественной.

Принципы были придуманы для того, чтобы достичь следующих целей:

• снизить вероятность «случайного срабатывания» (т.е. когда обычный текст воспринимается как какая-то часть разметки);
• добиться «интуитивной» и легко запоминаемой разметки;
• защитить окружение форматированного текста от возможных опечаток автора.

2.1. Семантика должна передаваться через синтаксис

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

• **жирный** — звёздочки для жирного текста, который выделяется из общей массы;
• //курсив// — курсив оформляется скошенными же линиями;
• --зачёркивание-- и __подчёркивание__ соответственно;
• списки выглядят так же, как мы привыкли писать подобные списки в текстовых полях ввода.

Здесь мы сразу отошли от классической вики-разметки с её «всего 5 апострофов с каждой стороны».

2.2. Парные символы

Как вы заметили, все приведённые выше примеры вака-разметки содержат парные символы. Благодаря этому принципу текст «просто вставленный из какого-нибудь другого редактора» не требует специальной предобработки — маловероятно, что в нём встретятся таким образом «спаренные» символы.

В разметке есть случаи, когда используются тройные, четверные символы (и даже последовательности из 5–6 подряд идущих символов) — они используются для выделения заголовков разного уровня. Чем больше символов, тем «глубже» уровень заголовка.

2.3. Разметка соприкасается с внутренним текстом

Не исключено, что вы из тех людей, что всегда пишут тире как «два минуса» (вот так: --). Во всяком случае, авторы явно из числа этих людей. И более того, существует великое множество текстов, содержащих двойной минус как в качестве тире, так и в других качествах.

Принцип, согласно которому разметка должна «соприкасаться» со внутренним текстом, позволяет избежать таких случайных превращений «простого текста» в текст с разметкой. Этот принцип введён не для всех правил разметки, но для тех, в которых отдельно стоящий парный символ может встречаться в «исходном тексте» (например, для зачёркивания).

Т.е. --вот так-- будет работать, а если -- мы сделаем так-- — то текст не зачёркнётся.

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

2.4. Перевод строки — завершение некоторого фрагмента текста

В отличие от, скажем, разметки OpenWiki, перевод строки в «исходном тексте» вака-разметки воспринимается буквально — как перевод строки (два перевода начнут новый абзац). Таким образом, мы принимаем, что перевод строки — это завершение некоторого законченного фрагмента текста, например предложения или даже абзаца.

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

• снизить вероятность «случайного срабатывания»;
• упростить восприятие разметки (ведь «начало» и «конец» выделения оказываются недалеко друг от друга);
• свести роль «шрифтового оформления» к выделению малых фрагментов текста — что положительно сказывается на восприятии результата.

2.5. «Сломанная» разметка не должна ломать HTML вокруг текста

Вышеизложенные принципы позволяют добиться решения одной очень важной задачи — «защиты» HTML вокруг отформатированного текста от возможных ошибок форматирования. Благодаря правилу «прилипания» мы почти всегда можем определить какая часть разметки является «началом», а какая «концом», а также вставлять сразу оба HTML-тага (или не вставлять ни одного). Для тех правил вака-разметки, которые не имеют столь легко достижимой «парности» должны быть предприняты все усилия, чтобы добиться «герметичности» результата. И, как мы видим, это удалось.

2.6. Должен быть способ написать в точности то, что я хочу написать

Любую разметку нужно уметь «экранировать» — т.е. делать так, чтобы при разборе правила разметки игнорировались и фрагмент текста проходил через форматирование неизменным. Эта статья — пример того, когда подобное «экранирование» необходимо.

2.7. Минимум переключения раскладки клавиатуры

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

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

Таким образом, исходный синтаксис ссылок [[WikiLink Textual description]] обрёл своего двойника ((ВикиСсылка Текст на ссылке)), которого можно использовать как на английской, так и на русской раскладке. Очень многие правила вики-разметки обладают этим ценным свойством.

3. Правила формирования разметки

Применяя эти принципы, мы развивали и совершенствовали изначальный набор правил, внимательно изучая разные вики-движки. Если бы я посмел хвастаться, я бы сказал, что итоговая вака-разметка вобрала в себя всё самое лучшее из разных правил разметки, оставшись стройной и простой. Хотя, чёрт возьми! В итоге нашей работы вака-разметка вобрала в себя всё самое лучшее из разных правил разметки, оставшись стройной и простой.

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

3.1. «Однострочная разметка»

Однострочной разметкой стали все те правила, которые использовали символы, частоупотребляемые в «простых текстах», и которые касались какого-то «местного» оформления текста:

• жирный, курсив, подчёркивание
• мелкий и моноширинный текст
• заголовки (просто не имеющие смысла при разбиении на строки)
• ссылки (тексту которых тоже лучше оставаться «короткими»)
• возведение в^{степень} и _{индексы} (которые работают лишь в пределах одного слова)

3.2. «Многострочная разметка»

Остальные правила разметки работают на больших фрагментах строк. Это разрешено главным образом потому, что их оформление часто применяют к большим фрагментам текста.

Это, например, зачёркивание.
Или цитирование, которое захватывает весь абзац.

3.3. Экранирование разметки

Экранирование реализуется двумя способами:

• экранирование блока с помощью «парных символов» "";
• escaping (введение специального символа перед экранируемой последовательностью) с помощью символа ~ (тильда).

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

3.4. Ссылки и изображения

Вака-разметка, обнаружив в тексте URL, автоматически превращает его в ссылку. Если понятно, что URL указывает на «картинку» (например, заканчивается на .jpg или .gif) — в отформатированный текст вставляется изображение с помощью тага <img>. Это удобно, потому что позволяет, не особенно задумываясь, вставлять ссылки из буфера обмена, получая вполне качественный результат.

Для простановки ссылки с подписью есть два тага, имеющие несколько вариантов использования:

• ((URL Текстовое описание))
• [[URL Текстовое описание]] — то же, только менее удобно
• ((Вики Ссылка C Пробелами == Текстовое описание)) — позволяет вставлять пробелы в «левую часть» вики-ссылки (так же работает и на квадратных скобках)

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

Подписи к картинкам расставляются очень похоже на подписи к ссылкам:

• ((picture.jpg Подпись)) — способ задания title картинки
• ((URL small_picture.jpg)) — способ поставить ссылку с картинки

3.5. Списковые структуры

Как наиболее естественно для человека писать списки, нумерованные и ненумерованные, а так же вложенные?

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

Отступ выбран равным в два символа исходя из принципа «парных символов», которые в обычных текстах почти не встречаются. Некоторые другие вики-форматы используют пять-шесть пробелов — можно представить себе, как будет выглядеть третий уровень вложенности в <textarea>!

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

Нумерация в нумерованных списках проставляется автоматически, что позволяет спокойно удалять пункты, добавлять новые и переносить их в иерархии. Если вам нужен нумерованный список, начинающийся с тройки, начните его 1.#3 Вот так.

3. Именно так.

3.6. Разметка таблиц

Таблицы — одно из самых больных мест любой разметки. Наилучшим решением оказался набор правил, разметка которого имитирует вертикальные линии сетки таблицы. Это легче, чем рисовать дефисами, плюсами и вертикальными линиями всю сетку, и одновременно даёт вполне читаемую в «исходном тексте» таблицу.

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

4. Сложные преобразования и сервис-функции

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

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

4.1. Концепция форматтеров-хайлайтеров (highlighters)

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

В теле вака-разметки использование хайлайтера выглядит так %%(html)<div class="test">testdiv</div>...%% — т.е. используется «парный символ» %% с указанием в круглых скобках, какой функции-хайлайтеру передать то, что внутри.

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

Как правило, этот синтаксис используется для разнообразной «расцветки» текста — для подсветки синтаксиса, оформления ICQ-логов и email, вставки каких-то произвольных блоков текста.

Эта концепция — способ легко расширить разметку, при этом:

• не задействуя дополнительных «парных символов»;
• не разбираясь в деталях работы вака-форматтера.

4.2. Концепция акшнов-действий (actions)

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

В теле вака-разметки использование «действия» выглядит так {{RecentChanges for="kuso@npj"}} — используется «парный символ» {{ с указанием имени «действия» и дополнительных параметров.

Разработчик пишет эти функции точно так же, как он пишет и «хайлайтеры».

Именно через «действия» в WackoWiki Very Quick Start реализована значительная часть функциональности по работе с документами (построение каталога, списков последних изменений/комментариев, поиск).

Эта концепция — способ «встроить» в документ какую-то сложную функциональность, при этом так же не влезая в детали работы вака-форматтера.