View source for Разметка

Имеется также ((/Doc/Deutsch/Markup Deutsch)), ((/Doc/English/Markup English)), ((/Doc/Francophone/Markup Franзais @@en))  и  ((/Doc/Espanol/Markup Spanish)).

Эта довольно длинная статья о том, как появилась "вака-разметка", и почему она такая, какая она сейчас есть. Если вы не знаете, что такое "вака-разметка" и, тем более, что такое "вики", вам стоит подробнее ознакомиться с сайтом проекта WackoWiki и прочитать тут пару статей ((/Doc/Russian документации)), в особенности статью про ((WikiKoncepcii вики-концепции)).

{{toc numerate=1}}

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

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

Вака-разметка используется в вики-движке ((http://wackowiki.org WackoWiki)) и в других проектах разных разработчиков. Для того, чтобы внедрить вака-разметку в вашем проекте, вам достаточно скачать и встроить в ваш проект следующие компоненты:
  * ((/Dev/Projects/WackoFormatter вака-форматтер)), php-класс, превращающий вака-разметку в HTML;
  * ((/Dev/Projects/WikiEdit визуальный редактор)) для вики-текстов. Это необязательное, но чрезвычайно удобное дополнение к вака-форматтеру.

Исходный текст этой статьи написан в формате вака-разметки и ((!/source доступен для просмотра)).


=== Принципы, положенные в основу ===
Хотя вака-разметка изначально досталась (?нам Нам -- авторам, разработчикам WackoWiki (прим. авторов, разработчиков WackoWiki)?) в наследство от проекта ((/Doc/Russian/WakkaWiki WakkaWiki)) (ранее размещавшегося по адресу ~http://wakkawiki.de, но сейчас недоступного), в её основе были чёткие принципы, которые и определили её дальнейший успех.

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

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

==== Семантика должна передаваться через синтаксис ====
В основе любой вики-разметки лежит принцип (?WYTIWYG What You Think Is What You Get?), поэтому каждое правило вака-разметки старается своим оформлением (синтаксисом) отражать смысл (семантику). Поскольку в вака-разметке всё оформление делается средствами простого текста -- символами, которые можно набрать с клавиатуры, то мы старались подобрать такие комбинации, которые бы отражали смысл:
  * ##""**жирный**""## -- звёздочки для жирного текста, который **выделяется** из общей массы;
  * ##""//курсив//""## -- курсив оформляется //скошенными же линиями//;
  * ##""--зачёркивание--""## и ##""__подчёркивание__""## соответственно;
  * списки выглядят так же, как мы привыкли писать подобные списки в текстовых полях ввода.
Здесь мы сразу отошли от ((http://c2.com/cgi/wiki?TextFormattingExamples классической)) вики-разметки с её "всего 5 апострофов с каждой стороны".

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

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

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

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

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

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


==== Перевод строки -- завершение некоторого фрагмента текста ====
В отличие от, скажем, разметки ((http://openwiki.com OpenWiki)), перевод строки в "исходном тексте" вака-разметки воспринимается буквально -- как перевод строки (два перевода начнут новый абзац). Таким образом, мы принимаем, что перевод строки -- это завершение некоторого законченного фрагмента текста, например, предложения или даже абзаца.

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

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

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

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

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

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



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

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

==== Однострочная разметка ====
Однострочной разметкой стали все те правила, которые использовали символы, часто употребляемые в "простых текстах", и которые касались какого-то "местного" оформления текста:
  * **жирный**, //курсив//, __подчёркивание__
  * ++мелкий++ и ##моноширинный## текст
  * заголовки (просто не имеющие смысла при разбиении на строки)
  * ссылки (тексту которых тоже лучше оставаться "короткими")
  * возведение в ^^степень^^ и vvиндексыvv (которые работают лишь в пределах одного слова)


==== Многострочная разметка ====
Остальные правила разметки работают на больших фрагментах строк. Это разрешено главным образом потому, что их оформление часто применяют к большим фрагментам текста.
<[
Это, например, --зачёркивание.
Или-- цитирование, которое захватывает весь абзац.
]>
==== Экранирование разметки ====
Экранирование реализуется двумя способами:
  * экранирование блока с помощью "парных символов" ##~""##;
  * escaping (введение специального символа перед экранируемой последовательностью) с помощью символа ##~~## (тильда).
Первый способ позволяет сравнительно легко "запретить" разметку большого куска текста, а второй удобно применять, когда нужно экранировать лишь одно-два слова или даже один "парный символ". Кроме того, экранирование тильдой позволяет нам отображать и парные двойные кавычки, как это сделано в примере выше.

Если вы откроете ((!/source исходный текст)) статьи, то обнаружите, что экранирование разметки встречается там очень часто -- иначе мы бы не смогли привести ни одного примера разметки в своём непреобразованном виде.

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

Для установки ссылки с подписью есть два тега, имеющие несколько вариантов использования:
  * ##""((URL Текстовое описание))""##
  * ##""[[URL Текстовое описание]]""## -- то же, только менее удобно
  * ##""((Вики Ссылка C Пробелами == Текстовое описание))""## -- позволяет вставлять пробелы в "левую часть" вики-ссылки (так же работает и на квадратных скобках)

((/Doc/Russian/VikiImja Концепция вики-ссылок)) позволяет вставлять ссылки "внутри сайта" более просто и вака-разметка это тоже учитывает. Все ссылки, которые не являются "внутренними", сразу оформляются как "внешние", то же происходит и с email-адресами.

Подписи к картинкам расставляются очень похоже на подписи к ссылкам:
  * ##""((picture.jpg Подпись))""## -- способ задания title картинки
  * ##""((URL small_picture.jpg))""## -- способ поставить ссылку с картинки


==== Списковые структуры ====
Как наиболее естественно для человека писать списки, нумерованные и ненумерованные, а так же вложенные?
#||
||%%(php)**Наверное, как-то так:**
  * элемент списка-1
  * элемент списка-2
  * Подсписок
    * элемент подсписка-1
    * элемент подсписка-2
  * продолжение списка
 
  1. Нумерованный список раз
  2. Второй элемент
    1. так же и с вложенным
    6. нумерация может и сбиться
%%|

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

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

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

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

==== Разметка таблиц ====
Таблицы -- одно из самых больных мест любой разметки. Наилучшим решением оказался набор правил, разметка которого имитирует вертикальные линии сетки таблицы. Это легче, чем рисовать дефисами, плюсами и вертикальными линиями всю сетку, и одновременно даёт вполне читаемую в "исходном тексте" таблицу. Подробнее о разметке таблиц можно прочитать в ((/Doc/Russian/WackoSintaksis синтаксисе вака-разметки)). Там же есть и примеры.

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

=== Развитие разметки ===
Во-первых, выше рассмотрены далеко не все правила вака-разметки, а лишь самые основные. Если вам чего-то не хватает -- посмотрите сперва ((/Doc/Russian/WackoSintaksis более полную документацию)). Если же становится ясно, что существующих правил не хватает -- разметку стоит расширять. Так появилось большинство правил нашей разметки.

==== Когда стоит изменять существующую разметку? ====
Никогда.

Именно так, если речь идёт не о введении новых правил, а о изменении существующих. Изменение поведения разметки, которое кажется полезным вам, может существенно помешать остальным людям, привыкшим работать с такой разметкой. Представьте, если бы на некоторых сайтах ##""<b>""## стало работать как ##""<a>""## и наоборот.

Конечно, если в рамках вашего конкретного проекта какое-то правило существенно мешает -- тогда можно подумать о его замене. Заменяя/удаляя правило, задумайтесь о том, как это воспримут все те, кто привыкли к стандартной вака-разметке!

==== Когда стоит вводить новые сущности разметки? ====
Как можно реже.

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

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

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

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

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

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

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

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

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

Эта концепция -- способ легко расширить разметку, при этом:
  * не задействуя дополнительных "парных символов";
  * не разбираясь в деталях работы вака-форматтера.

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

В теле вака-разметки использование "действия" выглядит так ##""{{changes page="/Dev"}}""## -- используется "парный символ" ##""{{""## с указанием имени "действия" и дополнительных параметров.

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

Именно через "действия" в ((http://wackowiki.org WackoWiki)) реализована значительная часть функциональности по работе с документами (построение каталога, списков последних изменений/комментариев, поиск).

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

==== Interwiki -- модификация разметки ссылок ====
Существует также способ расширить синтаксис разметки ссылок, введя в него дополнительные правила вида ##""((repository:address))""## или ##""((repository:address Текст на ссылке))""##. Адрес в таком случае указывается как два фрагмента "хранилище" и "имя в этом хранилище". Например, для ((http://livejournal.com LiveJournal)) адреса будут выглядеть как-то так: ##""((lj:mendokusee))""##, а для ссылки на перевод английского слова можно будет писать ##""((lingvo:fascinating))""##.

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

Тем не менее, есть и другие способы реализации аналогичной модификации. На разных сайтах используются следующие форматы разметки:
  * ##""[[ljuser romochka]]""## ([[http://ilyabirman.ru/meanwhile/wikihelp источник]])
  * ##""[[xpointUser280 Владимир Палант]]""## ([[http://xpoint.ru/help/formatting.xhtml источник]])
  * ##""[[php ereg_replace]]""## ссылка на документацию ([[http://xpoint.ru/help/formatting.xhtml источник]])

Вариант interwiki (ссылки через двоеточие) кажется нам более правильным хотя бы потому, что используется во множестве систем и является стандартом де-факто. Кроме того interwiki не вызывает конфликта с обычной разметкой ##""[[Link Description]]""##.

=== Технические детали ===
Эта статья -- не то место, где вы сможете в деталях разобраться, как работает ((/Dev/Projects/WackoFormatter вака-форматтер)), однако, некоторые основные моменты стоит назвать.

Во-первых, сам по себе форматтер построен на "регулярных выражениях" (а именно Perl Compatible Regular Expressions) и работает по принципу "рекурсивного разбора". Это означает, что он старается разбить текст на "самые крупные" фрагменты разметки, а потом использует себя же для разбора внутри них. Это, в свою очередь, значит, что нельзя вкладывать одинаковые правила разметки: например, вот так -- ##""**пример **вложенной** разметки**""## работать не будет. Но, согласитесь, это и не нужно.

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

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

Если вам интересны более глубокие аспекты функционирования форматтера -- добро пожаловать в ((/Dev/Projects/WackoFormatter код форматтера)).

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

Если у вас возникли вопросы -- не стесняйтесь задавать их в комментариях или лично авторам статьи.

С уважением, ((/Org/Team команда WackoWiki)) и авторы статьи:
  * ((user:KusoMendokusee Кусо Мендокуси));
  * ((user:RomanIvanov Роман Иванов)).

=== Ссылки ===
  1. ((http://wackowiki.org The WackoWiki Project))
  2. ((/Dev/Projects/WackoFormatter Форматтер)) для описываемой разметки
  3. ((/Dev/Projects/WikiEdit Визуальный редактор)) для описываемой разметки
  4. ((http://web.archive.org/web/20050211022800/http://www.wakkawiki.de/WakkaWiki WakkaWiki)) -- исторические корни WackoWiki ++(возможно, недоступно)++
  5. ((https://web.archive.org/web/20060202001402/http://openwiki.com/ OpenWiki)) -- ещё одни исторические корни вака-разметки
  6. ((/Doc/Russian/WikiKoncepcii Описание вики-концепций))
  7. ((/Doc/Russian/WackoSintaksis Синтаксис вака-разметки))
  8. ((http://c2.com/cgi/wiki?TextFormattingExamples Примеры классической разметки)) на c2.com
  9. ((/Doc/Russian/VikiImja Что такое ВикиИмя)) -- концепция вики-ссылок
  10. ((https://yandex.ru/support/connect-wiki/basic-markup.html Яндекс.Вики: Оформление страниц - Базовое форматирование))


----
original is located at: ((/Doc/Russian/razmetka))