Справка/ВикиСинтаксис/Концепции-вики-синтаксиса

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


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


Оглавление документа

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. Списковые структуры

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

**Наверное, как-то так:**
  * элемент списка-1
  * элемент списка-2
  * Подсписок
    * элемент подсписка-1
    * элемент подсписка-2
  * продолжение списка
  
  1. Нумерованный список раз
  2. Второй элемент
    1. так же и с вложенным
    6. нумерация может и сбиться

Что хочется получить:

  • элемент списка-1
  • элемент списка-2
  • Подсписок
    • элемент подсписка-1
    • элемент подсписка-2
  • продолжение списка

  1. Нумерованный список раз 
  2. Второй элемент
    1. так же и с вложенным
    2. нумерация может и сбиться

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


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


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


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

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

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 реализована значительная часть функциональности по работе с документами (построение каталога, списков последних изменений/комментариев, поиск).


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


 
Подразделы
Раздел не содержит подстраниц.


Комменты