UverseWiki

Синтаксис вики-разметки

Table Of Contents
Синтаксис вики-разметки
  1. 1. Простое форматирование
  2. 2. Разрывы строк
  3. 3. Заголовки
    1. 3.1. Альтернативные режимы
      1. 3.1.1. Пример в режиме shifted
      2. 3.1.2. Пример в режиме extended
  4. 4. Отмена элементов разметки
    1. 4.1. Тильда
    2. 4.2. Многострочное экранирование
    3. 4.3. Форматтеры
  5. 5. Выравнивание текста
  6. 6. Отступы
    1. 6.1. Отступ и выравнивание
  7. 7. Стили абзацев
    1. 7.1. Стиль и выравнивание
    2. 7.2. Стиль и отступ
    3. 7.3. Стиль, отступ и выравнивание
  8. 8. Ссылки
    1. 8.1. Якорные ссылки
    2. 8.2. Адресация в ссылках
      1. 8.2.1. Интервики и цифрови́ки
      2. 8.2.2. Внешние ссылки
        1. 8.2.2.1. ((#fetchRemoteTitles Автозаглавие из <title>
      3. 8.2.3. Внутренние ссылки
        1. 8.2.3.1. Компоненты ссылки
        2. 8.2.3.2. Автозаглавие
        3. 8.2.3.3. …по частям пути
        4. 8.2.3.4. …по заглавию документа
        5. 8.2.3.5. …заменой окончания
  9. 9. Списки
  10. 10. Цитаты
  11. 11. Термины (определения)
  12. 12. Маркеры
  13. 13. Комментарии
  14. 14. Горизонтальные черты
  15. 15. Мнемоники
  16. 16. Якоря
    1. 16.1. Строчные якоря
    2. 16.2. Отключенные строчные якоря
    3. 16.3. Автогенерируемые якоря
      1. 16.3.1. Перегенерация якорей
  17. 17. Сноски
    1. 17.1. Строчные сноски
    2. 17.2. Блочные сноски
    3. 17.3. Сноски по номеру
    4. 17.4. Несколько ссылок
  18. 18. Форматтеры
    1. 18.1. Блочные форматтеры
      1. 18.1.1. WackoWiki
    2. 18.2. Строчные форматтеры
  19. 19. Действия
  20. 20. Параметры для форметтеров и действий
    1. 20.1. Поимённая передача
    2. 20.2. Позиционная передача
    3. 20.3. Флаги
      1. 20.3.1. По порядку или флаг?
  21. 21. Сцепление форматтеров и действий

Простое форматирование

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

**Жирный**, --зачёрк- нутый--, __подчёркнутый__,
//курсив//, ++маленький++, ^^св^^ерху.

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

Пара символов не может иметь пробел с обоих сторон:

Это ** уже не ** форматирование.

Это ** уже не ** форматирование.

Можно вкладывать стили друг в друга, придерживаясь вложенности:

  * правильно __вложенная **конструкция**__.
  * а --здесь ^^есть-- ошибка^^ - сначала
    закрывается %%--%%, а ^^ остаётся незакрытым.
  • правильно вложенная конструкция.
  • а --здесь ^^есть-- ошибка^^ — сначала закрывается --, а ^^ остаётся незакрытым.

Простое форматирование только однострочно (в отличие от, например, WackoWiki, где зачёркивание могло быть многострочным):

Строка **разбита на две -
поэтому** не форматируется.

Строка **разбита на две — поэтому** не форматируется.

Форматирование можно отменить тильдой:

~**Не жирный~**. **Жирный~** - и здесь продолжение.**

**Не жирный**. Жирный** — и здесь продолжение.

Разрывы строк

Есть 2 типа начать новую строку:

  1. «Мягкий» перевод строки — указывается как обычный разрыв строки в исходном тексте;
  2. Принудительный перевод строки — 3 и более дефиса подряд (---).

Настройка UWikiSettings->$noLineBreaksInsideParagraph задаёт, как трактуются мягкие переводы строк — по умолчанию она отключена, поэтому они учитываются:

Первая строка.
Вторая.
Ещё одна.

Первая строка.
Вторая.
Ещё одна.

Если же включить UWikiSettings->$noLineBreaksInsideParagraph, то мягкие переводы строк будут проигнорированы и автор может переносить текст в исходном документе как ему нравится:

Первая строка.
Та же самая строка.

Первая строка. Та же самая строка.

Принудительный разрыв строки (пробелы вокруг --- необязательны):

Первая строка.---Вторая строка.
Продолжение строки... один разрыв:------
два --- --- разрыва.

Или так: первая строка---
вторая строка.

Первая строка.
Вторая строка. Продолжение строки… один разрыв:
два

разрыва.

Или так: первая строка
вторая строка.

Не ставьте разрыв строки на отдельной строке — так обозначаются горизонтальные черты:

Разрыв --- строки
---
Горизонтальная черта - выше.

Разрыв
строки


Горизонтальная черта — выше.

Отменить разрыв строки можно тильдой:

Здесь был бы разрыв, ~--- если б не тильда.

Здесь был бы разрыв, --- если б не тильда.

Заголовки

Есть 6 уровней заголовков: 1 — самый верхний, должен быть одним-единственным в документе, ибо задаёт его заглавие (хотя технически можно использовать сколько угодно первых уровней, заглавием по прежнему будет считаться лишь первый), 2 — секция документа и т. д. до 6 — самого маленького.
Заголовки задаются с помощью «равно» — чем их больше, тем меньше уровень заголовка. Первый уровень имеет 2 «равно», шестой — 7. Кроме того, количество «равно» справа должно быть не больше их слева. Вдобавок, слева и справа от заголовка на строке не должно быть ничего, даже пробелов. И наконец между «равно» и текстом могут быть пробелы, которые игнорируются.

== Заголовок первого уровня ==
===Второго===
и так далее до...
======= Самый маленький =======

Второго

и так далее до… ======= Самый маленький =======

некоторые действия могут использовать заголовки для чего-то, например {{Оглавление}} генерирует содержание документа, которое, например, видно справа на этой странице.

Можно использовать любую строчную разметку внутри, включая форматтеры:

==== //Курсивный// текст; форматтер: %%(php) echo "Hello!";%% ==

Курсивный текст; форматтер: PHPecho "Hello!";

Можно также пропускать уровни заголовоков, хотя то же {{Оглавление}} будет выводить сообщение вместо таких пропусков:

==== Заголовок 3 ====
====== Заголовок 5 ==

Заголовок 3

Заголовок 5

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

Заглавие документа можно также задать с помощью Title.
Также полезно знать о настройке hideTitle, которая позволяет убрать заглавие документа из его вывода (полезно для программ, использующих UverseWiki для форматирования документов и выводящих заглавие в отдельное поле на странице).

Альтернативные режимы

Описанные выше правила соответствуют традиционным принципам работы заголовков — например, в WackoWiki. Однако существуют ещё несколько и задаются они с помощью настройки headingMode:

normal
Стандартный («традиционный») режим, описан выше.
shifted
Режим призван облегчить задание заголовков — так как на документ заголовок первого уровня всё равно всегда один (он задаёт его заглавие), то фактически используемые заголовки — с ===уровень 2=== по =======уровень 6==. В режиме shifted одно «равно» слева убирается, таким образом: ==уровень 2== до ======уровень 6==.
  • этот режим включается автоматически, если в документе используется Title.
  • в этом режиме заглавие документа больше невозможно задать заголовком — поэтому используйте его, когда заглавие либо задано с помощью Title, либо внешним источником (например, из базы данных).
extended
Идентичен режиму shifted, но делает возможным задать заглавие документа — им считается первый встреченный заголовок (==). Таким образом, первый заголовок == становится первым уровнем, а все последующие заголовки == — вторыми, при том, что для обоих используется одинаковый синтаксис — ==заголовок==.

Пример в режиме shifted

== Заголовок 2 ==
=== Заголовок 3 ===
И так далее до..
====== Заголовок 6 ======

Сравните это с режимом normal, как описано выше — доступных заголовков стало меньше на один, но для их задания был убран один знак «равно».

Пример в режиме extended

== Заглавие документа ==
== Секция (заголовок 2) ==
===Подсекция (уровень 3)===
И так далее до..
====== Заголовок 6 ======

Таким образом, режим идентичен режиму shifted — отличие лишь в том, что первый встреченный ==заголовок== становится не вторым, а первым уровнем, задавая заглавие для документа.
Можно сказать, что это комбинация режимов normal и shifted.

В режиме normal и «Заглавие документа», и «Секция (заголовок 2)» были бы первого уровня. В режиме shifted — оба второго. В этом режиметак же, кроме первого заголовка, который стал первым уровнем.

Отмена элементов разметки

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

  1. Тильда — отменяет одиночный тег. Если она стоит перед обычным текстом, то выводится как есть. Отменить тильду можно просто повторив её дважды.
    • не все элементы разметки могут быть отменены тильдой (например, почти никакие блочные вроде <[ цитат ]> не реагируют на тильду, и ~<[цитата]> хоть и не становится цитатой, но тильда убрана не будет).
  2. Пара кавычек ~"", поставленных по краям от строки. Отменить их (вывести ~"") можно, поставив перед кавычками одну тильду. Работает только внутри одной строки.
    • этой конструкцией можно отменять даже блочные элементы, в отличие от тильды.
  3. Форматтер (строчный или блочный) — внутри %% текст никак не обрабатывается (хотя это зависит от стиля, но в любом случае для обработки его как вики-разметки стиль «wacko» должен быть задан явно).
    • блочный %% — единственный способ отменить разметку (экранировать её) в многострочном тексте.

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

Тильда

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

  * отмена ~**форматирования~**.
  * отмена ++формати~**рования++.
  * отмена ~""многострочного **экранирования**~""
  * или так, исключив типографику: %%~""%%.
    (а вот ""как **без тильды**"").
  * на блочные тильда не действует:
    ~<[ Цитата ли? ]>
  • отмена **форматирования**.
  • отмена формати**рования.
  • отмена ""многострочного экранирования""
  • или так, исключив типографику: ~"". (а вот как **без тильды**).
  • на блочные тильда не действует: ~<[ Цитата ли? ]>

Многострочное экранирование

  ""1. Был бы список - ан-нет""
  1. Был бы список - ан-нет""

""<[Была бы цитата, но опять же нет.]>""
<[Была бы цитата, но опять же нет.]>

1. Был бы список — ан-нет

  1. Был бы список — ан-нет""

<[Была бы цитата, но опять же нет.]>

Была бы цитата, но опять же нет.

По понятным причинам внутри этого экранирования правило вложенности не работает:

  * **это - Некая ""формати**рованная"" фраза** -
    вся целиком жирная.
  * а вот как без %%~""%%:
    **Это - Некая ""формати**рованная"" фраза.**
  * это не зачёркивание: ~-- - но заметьте, что
    оно стало длинным тире из-за правил типографики.
  • это — Некая формати**рованная фраза — вся целиком жирная.
  • а вот как без ~"": Это — Некая формати**рованная фраза.
  • это не зачёркивание: — — но заметьте, что оно стало длинным тире из-за правил типографики.

Форматтеры

См. также раздел о форматтерах.

Однострочные:

  * вот разметка: %%**%% (не **жирная**).
  * а вот двойной процент: %%~%%%% -
    * без тильды выглядело бы так: %%%%%%,
    * а без форматтера - так: %%.
  * это не зачёркивание: ""--"" - но заметьте, что
    оно стало длинным тире из-за правил типографики.
  • вот разметка: ** (не жирная).
  • а вот двойной процент: %%
    • без тильды выглядело бы так: %%,
    • а без форматтера — так: %%.
  • это не зачёркивание: — — но заметьте, что оно стало длинным тире из-за правил типографики.

Многострочные:

%%
  +----------+-----------+-----------+
  | **Вики** | [BB-коды] | <HTML>    |
  +----------+-----------+-----------+
  | Класс!   | Неудобно. | Тяжело... |
  +----------+-----------+-----------+
%%

  Кстати, это не зачёркивание: %%--%% - и заметьте, что
оно **не** стало длинным тире из-за правил типографики,
как было бы при тильде или %%""%%: ~-- и ""--"".
+----------+-----------+-----------+
| **Вики** | [BB-коды] | <HTML>    |
+----------+-----------+-----------+
| Класс!   | Неудобно. | Тяжело... |
+----------+-----------+-----------+

Кстати, это не зачёркивание: -- — и заметьте, что оно не стало длинным тире из-за правил типографики, как было бы при тильде или "": — и —.

Выравнивание текста

Выравнивать текст можно с помощью "<<" и «>>», расположенных в начале и конце абзаца, хотя и необязательно на одной строке (абзац может быть многострочным).

>>Выравнивание по центру.<<
>>По правому краю.>>
<<По левому краю.<<

<< Выравнивание по ширине (justified)
многострочного абзаца. >>

Выравнивание по центру.

По правому краю.

По левому краю.

Выравнивание по ширине (justified) многострочного абзаца.

Не путайте выравнивание «>>» со строчной цитатой 2-го уровня:

>>Цитата
>>Выравнивание по центру<<
>>Снова цитата
  1. Цитата

Выравнивание по центру

  1. Снова цитата

Если нужно, то выравнивание можно отменить с помощью тильды:

~>>Больше не выравнивание.<<
>>Тоже, но здесь строка стала цитатой.~<<

>>Больше не выравнивание.<<

  1. Тоже, но здесь строка стала цитатой.~<<

В принципе, можно и так:

>>Выравнивание по~<<
правому краю.>>

Выравнивание по<< правому краю.

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

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

Отменять выравнивание сразу с обоих сторон обычно смысла не имеет, поэтому не работает:

~>>Текст~>>

Текст

См. также отмену строчных цитат.

Отступы

Абзац может иметь отступ — для его определения подсчитывается наименьшее количество пробелов в начале одной из строк абзаца и делится на 2.

  Обычный абзац, состоящий из двух
строк, первая просто выдвинута.

  Абзац, имеющий отступ
  первого уровня слева.

    Второго уровня.

    Здесь снова первый уровень,
  ибо меньшее число пробелов - 2.

Обычный абзац, состоящий из двух строк, первая просто выдвинута.

Абзац, имеющий отступ первого уровня слева.

Второго уровня.

Здесь снова первый уровень, ибо меньшее число пробелов — 2.

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

Отступ и выравнивание

И отступ, и выравнивание можно комбинировать:

  >>Выравнивание по правому краю,
    абзац с отступом первого уровня.<<

Выравнивание по правому краю,
абзац с отступом первого уровня.

Главное, чтобы пробелы были перед >> или << — так будет неправильно:

>>  Выравнивание ли это?
    Нет, вряд ли.        <<

Выравнивание ли это?
Нет, вряд ли.

Стили абзацев

Каждый абзац может иметь свой стиль — он задаётся с помощью точки и именем стиля в скобках за ней.

.(Внимание)
Пассажир //Пионеров//, пройдите
в вагон правого купе. Повторяю...

Пассажир Пионеров, пройдите в вагон правого купе. Повторяю…

Возможные стили и эффект от них зависит от конкретной темы оформления. Регистр стиля не важен. Имена стилей могут иметь альтернативные названия.

Необязательно оставлять имя стиля на своей строке — текст может идти сразу за скобками:

.(шёпотом) Тсс...

Тсс…

Абзацы, в отличие от выравнивания, не разбиваются стилями. Для сравнения:

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

А вот что происходит при выравнивании:
>>Первый абзац<<
>>Уже другой абзац!>>

Текст. .(Стиль) — обычное продолжение абзаца, а не второй абзац с другим стилем.

А вот что происходит при выравнивании:

Первый абзац

Уже другой абзац!

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

Первый абзац
1. Первый список

.(Style)
1. Первый элемент второго списка
2. Второй

Первый абзац 1. Первый список

1. Первый элемент второго списка 2. Второй

…тогда добавив к странице такие стили второй список будет выведен красным:

p.style { display: none; }
p.style + ol { color: red; }

Можно отменить задание стиля абзаца с помощью тильды — тогда скобки с точкой будут включены в его текст:

~.(стиль) Текст.

.(стиль) Текст.

Стиль и выравнивание

Их можно комбинировать, причём в этом случае можно опустить точку перед скобками:

>>(Внимание) Текст по центру.<<
Это совершенно тоже самое, что и с точкой, просто короче:
>>.(Внимание) Текст по центру.<<

Текст по центру.

Это совершенно тоже самое, что и с точкой, просто короче:

Текст по центру.

Стиль и отступ

Здесь всё тривиально — сначала идёт отступ, затем точка и скобки с именем стиля:

  .(Внимание) Отступ
  1-го уровня.

      .(стиль)
    Отступ 2-го
    уровня.

Отступ 1-го уровня.

.(стиль) Отступ 2-го уровня.

Стиль, отступ и выравнивание

Можно задать сразу всё (хотя необходимость одновременно и выравнивания, и отступа сомнительна) — сначала указывается отступ, затем выравнивание, а затем скобки с именем стиля (перед скобками может быть или не быть точка):

  >>(Внимание)
    Текст справа, отступ
    1-го уровня >>

    >>.(СТИЛЬ) Текст по центру,
    отступ второго уровня.<<

Текст справа, отступ
1-го уровня

Текст по центру, отступ второго уровня.

Ссылки

Ссылки задаются парой либо круглых, либо квадратных скобок. Ссылка кроме собственно страницы (локальной, URL, интервики и т. д.) может иметь также и название, которое будет отображаться в тексте вместо голого URL — название, как и в терминах и ассоциативных списках, отделяется от URL либо двойным «равно» ==, либо пробелом, если двойного «равно» не задано.

При ссылках на локальные страницы можно использовать относительные пути как в обычных путях файловых систем:

  • две точки — папка выше;
  • одна точка — текущая папка;
  • прямой или обратный слеш в начале адреса — ссылка на корень сайта (либо документации — зависит от настроек вики-процессора).

Часто «папки» на вики-сайте называют кластерами. В качестве разделителя пути можно использовать любой из слешей (прямой / или обратный \).

  * ((/ Главная страница)).
  * ((.. Содержимое верхнего кластера)).
  * [[..\WackoWiki Highlighters == Подсветчики WackoWiki]].

Естественно, пути на внешних сайтах остаются как есть:
  * ((http://google.com Внешняя ссылка)).
  * [[http://a-site/path\path\ Некий сайт]]

Естественно, пути на внешних сайтах остаются как есть:

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

  * ((. Начало раздела));
  * ((..\ Основная секция));
  * ((..\Classes Классы));

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

  * ((../../../../.. Всё выше и выше...));
  * ((../../../../../ А здесь расширение не добавлено)).

В зависимости от темы оформления ссылки на несуществующие страницы и кластеры могут выделяться по-другому:

  * ((Несуществующая_страница));
  * ((некая_страница#якорь));
  * ((Syntax Эта страница существует));
  * ((Syntax#Ссылки Она же, с якорем));
  * ((Несуществующий_кластер/));
  * ((несуществующая:интервики)).

Внутри названия ссылки можно использовать любую строчную вики-разметку:

  * ((. == Содержание //этого// кластера)).
  * [[http://php.net/function.substr %%substr()%%]]

Отменить создание ссылки можно тильдой:

  * ~((Не ссылка)), ~[[тоже не ссылка]].
  * ((Ссылка с названием со ~)) скобками)).
  • ((Не ссылка)), [[тоже не ссылка]].
  • .

Обратите внимание, что при включении документа в другой с помощью Include ссылки на вложенный документ будут скорректированы так, что они будут ссылаться не на его отдельную страницу, а на его включённую копию. Тоже самое касается и якорных ссылок.
Также, относительные ссылки во включённых документах корректируются так, что продолжают ссылаться на правильные страницы — относительно пути включённого, а не родительского, документа.

Якорные ссылки

Якоря ссылаются на конкретное положение на странице вместо ссылки на её верхнюю часть. Задаётся якорь через решётку #. Якорь можно указывать и для внешних, и внутренних адресов. При ссылке на якорь в текущем документе указывать страницу ни к чему — можно сразу начинать с # (см. также Адресация в ссылках). Для внутренних ссылок регистр символов в имени якорей не важен.
Названия для ссылок задаются как обычно — через двойное равно == или пробел.

  * ссылка на раздел "((#Форматтеры форматтеры))" тут же.
  * а вот - на якорь в другом локальном документе:
    ((../Classes/UWikiSettings#Static methods == Статические методы класса %%UWikiSettings%%)).
  * ((http://uverse.i-forge.net/doc/#bottom Внешняя ссылка с якорем))

Обратите внимание, что в зависимости от настройки UWikiSettings->$inlineAnchors поведение якорной ссылки изменяется — она может создавать строчный якорь вместо ссылки на документ, если заглавие ссылки не задано явно — см. раздел о якорях.

Адресация в ссылках

Ссылки могут указывать на внешний ресурс (когда указан протокол, например http://google.com) или на внутренний. Для обоих типов адресации существую свои правила адресации:

Интервики и цифрови́ки

Оба понятния обозначают краткие имена для адресации — вроде ярлыков на файлы. Интервики и цифрови́ки задаются в ссылке вместо адреса.

  * ((go:UverseWiki Искать UverseWiki в Гугле));
  * ((ВП:wiki==Спросить о "вики" у Википедии));
  * ((Codenet:#4444 Сообщение №4444 на CodeNet.ru)).

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

Интервики задаются в файле interwiki.conf, а цифрови́ки — в numberlinks.conf.

Внешние ссылки

Внешние ссылки — это URL, содержащие имя протокола, например: http://i-forge.net, file:///usr/local/etc/svn-repos. Для внешних ссылок, в отличии от внутренних, существует всего два правила генерации автозаглавия, если оно не было задано в ссылке явно:

  1. Получением его из тега <title> для удалённых HTML-страниц;
  2. Подстановкой имени домена: ((http://not-existing-domain.net))[not-existing-domain.net].
((#fetchRemoteTitles Автозаглавие из <title>

При не заданном явно отображаемом названии для вики-ссылки и если включена настройка UWikiSettings->$fetchRemoteTitles (по умолчанию включена), вики-процессор попытается получить удалённый документ и прочитать заглавие из его тега <title>, расположенном внутри тега <head>.

Если сервер отправит Content-Type в заголовках ответа, а также если установлен модуль iconv для PHP, то будет произведена конверсия заглавия в UTF-8. Если одно из условий не выполнено, iconv() вернула ошибку а также если полученное заглавие не находится в UTF-8, то этот метод не срабатывает и используются другие способы генерации автоназвания.

Вики-процессор будет читать не более первых 4-х Кб удалённой страницы (значение по умолачнию настройки UWikiSettings->$fetchRemoteTitlesMaxSize) — если <title> не был найден в этом интервале либо тег <head> закрылся, этот метод определения не срабатывает.

Примеры:

  * ((http://google.com))
  * ((http://uverse.i-forge.net))
  * ((http://not-existing-domain.net))
  * ((http://www.google.ru/intl/en_com/images/srpr/logo1w.png))

Внутренние ссылки

Компоненты ссылки

Локальные ссылки имеют три части (возьмём для примера адрес форум:99#1.1-2):

  • интервики — часть пути ссылки от его начала до первого двоеточия («:»). В нашем примере это «форум».
  • путь — часть пути ссылки после первого двоеточия (разделитель интервики), либо от её начала если интервики не задана, и до первого знака «#» (разделитель якоря). В нашем примере это «99».
  • якорь — часть пути ссылки после первого знака «#» и до её конца. В нашем примере это «1.1-2».

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

((гугл:поиск))              - задана интервики "гугл" и путь "поиск".
Наш ((форум:))              - задана только интервики "форум" без пути.
((/Главная#начало))         - задан путь "/Главная" и якорь "начало".

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

((гугл:поиск))              - пустое заглавие.
((гугл:поиск заглавие))     - заглавие указано, разделитель - пробел.
((гугл:поисковая фраза==))  - пустое заглавие.
См. ((Имя документа == здесь))  - пробелы вокруг "==" игнорируются.

Разделитель - двойное равно (==), путь ссылки - "поисковая фраза":
((гугл:поисковая фраза==название))
Автозаглавие

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

Заданное явно заглавие не изменяется и отображается как есть; пустое заглавие включает механизм автоподстановки:

…по частям пути

Пути локальных ссылок имеют 3 компонентаинтервики, путь и якорь. Каждый из них может отсутствовать, но как минимум один всегда есть.

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

Значимость частей пути в порядке убывания следующая:

  1. Якорь — если задан якорь, то он используется как название: ((Документ#якорь)) эквивалентно написанию ((Документ#якорь якорь)) или ((Документ#якорь==якорь)).
  2. Путь — если ссылка указывает на документ, то берётся его имя (либо по его заглавию, если он не часть интервики, либо имя его файла); если ссылка указывает на кластер, то либо заглавие кластера, либо последний компонент кластера.
    • примеры: ((ссылка/на/страницу))((ссылка/на/страницу==страницу)); ((ссылка/на/кластер/))((ссылка/на/страницу/кластер/==кластер)).
  3. Интервики — наконец, если ни якорь, ни путь не определены, то берётся имя интервики (без двоеточия за ним): ((гугл:)) эквивалентно ((гугл: гугл)) или ((гугл:==гугл)).
…по заглавию документа

При ссылках на локальный вики-документ (страницу или кластер) можно не указывать название для ссылки — в этом случае оно будет прочитано из документа (его заглавие), либо из заглавия файла-огловления кластера (см. This {{Action}} has wrong syntax and can't be executed.).

Этот метод работает только для существующих и доступных (по правам доступа) документов — если это не так, либо документ/оглавление не содержит заглавия, то используются другие способы получения автоназвания для ссылки.

Примеры:

  * ((Markers)), ((Line breaks==)) - по заглавию страницы.
  * ((.)), ((/Blog)) - по заглавию кластера.
  * ((Несуществующая_страница)), ((Неизвестный_формат.rar)).
…заменой окончания

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

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

Замена окончания делается с помощью значка «плюс» (+), поставленного внутри адреса. Проще всего его поведение объяснить на примерах:

  * См. раздел о ((#якор+и))ях.
    - Идентично написанию "...о ((#якори якорях))."
  * На нашей ((стен+а))е чего только не понаписано...
    - Идентично "На нашей ((стена стене))..."
  * Давайте ((игра+))ть!
    - Эквивалентно "Давайте ((игра играть))!"
  * Стреляйте, братец, там ваш ((враг+и)).
    - Тоже самое, что и "...ваш ((враги враг))."
  * ((#Якор+я))ная ссылка.
  * Ссылка на раздел с ((функция+:))ми.
    - Тоже самое, что и "...с ((функция: функциями))."
  • См. раздел о якорях.
    • Идентично написанию «…о якорях
  • На нашей стене чего только не понаписано…
    • Идентично «На нашей стене…»
  • Давайте играть!
  • Стреляйте, братец, там ваш враг.
    • Тоже самое, что и «…ваш враг
  • Якорная ссылка.
  • Ссылка на раздел с функциями.
    • Тоже самое, что и «…с функциями

Схематично это выглядит так: ((ссылка+окончание_ссылки))окончание_названия. Указано может быть либо окончание ссылки, либо названия, либо оба, но не ни одного. Кроме этого, окончание заменяется не обязательно в последнем слове — это может быть любое слово:

Это указано в описании ((Функци+и обработки строк))й.
- эквивалентно "((Функции обработки строк==Функций обработки строк))".

Это указано в описании обработки строкй. — эквивалентно «Функций обработки строк».

Слишком длинные окончания игнорируются во избежание ложных срабатываний — зависит от настройки UWikiSettings->$longestLinkEnding, по-умолчанию 3 символа. Наличие нескольких неэкранированных плюсиков также приводит к его игнорированию для всей ссылки:

  * рабочая ссылка с заменённым ((окончание+))м;
  * тоже рабочая ссылка с ((оконча+ние))м;
  * а у этой окончание уже не распознано: ((оконч+ание))м;
  * тоже самое здесь: ((окончание+))мммм.
  * ((Од+ин дв+а))три.

Замена окончаний работает только для внутренних адресов и ссылок без явно указанных названий:

  * ((http://google.co+m));
  * ((Ссылка Заголово+к)).
  * ((Ссылка == Заголово+к)).

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

  * ((Ссыл+ка==Ссылка));
  * ((Ссылка+ Ссылка)) - пробел также разделяет адрес и название;
  * ((Нек~+ая ссылк+а==))и.
  * ((Нек~+ая ссылка==)) - а здесь и так всего один плюсик.

Списки

Они задаются предельно наглядно и могут быть:

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

Пункт любого типа списка должен начинаться как минимум с двух пробелов.

**Упорядоченные** (пробел после точки обязателен):
  1. Цифровой;
  02. Цифровой с нулём впереди;
  iii. Римский в нижнем регистре;
  IV. Римский в верхнем;
  e. Латиница;
  F. Она же в верхнем.

Можно и со скобками вместо точек (пробел после
скобки по прежнему обязателен):
  1) Первый
  2) Второй

**Неупорядоченные** (пробел после маркера обязателен):
  * кружок
  # квадрат
  - диск

Упорядоченные (пробел после точки обязателен):

  1. Цифровой;
  2. Цифровой с нулём впереди;
  3. Римский в нижнем регистре;
  4. Римский в верхнем;
  5. Латиница;
  6. Она же в верхнем.

Можно и со скобками вместо точек (пробел после скобки по прежнему обязателен):

  1. Первый
  2. Второй

Неупорядоченные (пробел после маркера обязателен):

  • кружок
  • квадрат
  • диск

Ассоциативные списки задаются с помощью знака «равно» как маркер и либо двумя «равно» ==, либо пробелом (если нет ==) в качестве разделителя имени и значения: ассоциативные

  = Имя значение;
  = Заглавие (имя), содержащее пробел == значение.
Имя
значение;
Заглавие (имя), содержащее пробел
значение.

Ассоциативные списки отображаются через <dl> в HTML.

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

  1. Цифровой пункт;
  2. Второй;
  * диск - из неупорядоченного списка;
  4. Снова цифровой.
  1. Цифровой пункт;
  2. Второй;
  3. диск — из неупорядоченного списка;
  4. Снова цифровой.

Поддерживается неограниченная вложенность любых типов списков (здесь уже можно вкладывать ассоциативные списки в другие или другие в них):

  1. Начало;
    * Пункт;
    * Ещё один.
       = Ассоциация слова.
  2. Снова начало.
    i. Скажем по-римски...
    b. Затем по-латински...
      X. (--Сказали бы и по-гречески, если б в PHP нормально работал Юникод--)
      = Снова ассоциация == слов.
  1. Начало;
    • Пункт;
    • Ещё один.
      Ассоциация
      слова.
  2. Снова начало.
    1. Скажем по-римски…
    2. Затем по-латински…
      1. (Сказали бы и по-гречески, если б в PHP нормально работал Юникод)
      2. Снова ассоциация
        слов.

Можно пропускать уровни вложенности (браузеры обычно выводят маркеры всех пропущенных уровней слева от такого пункта):

  1. Внешний список;
    * средний.
      * внутренний.
  2. Снова внешний
      * сразу внутренний;
    * теперь средний.
      * и снова внутренний.
  3. И снова внешний.
  1. Внешний список;
    • средний.
      • внутренний.
  2. Снова внешний
      • сразу внутренний;
    • теперь средний.
      • и снова внутренний.
  3. И снова внешний.

Лекарство от длинных строк в списках — перенос линий внутри пункта списка с бо́льшим числом пробелов (т. е. отступом) слева приклеивает строки к предыдущему пункту; с меньшим — завершает список и начинает абзац.

  1. Все эти три строчки
     принадлежат к одному и
     тому же пункту - первому.
  2. Второй пункт того же списка.
  А здесь уже пошёл абзац.
  1. Все эти три строчки принадлежат к одному и тому же пункту — первому.
  2. Второй пункт того же списка.

А здесь уже пошёл абзац.

Цитаты

Цитаты бывают двух типов:

строчные
быстрое цитирование чего-то сказанного ранее — например, на форуме. Важно, чтобы знаки «>» были в начале строки, причём перед ними допускаются пробелы.
  • имеют 5 (UWikiSettings->$maxLineQuoteLevel) уровней «давности», обозначается количеством «>» в начале строки — чем их больше, тем старее фраза.
блочные
объёмные блоки, могущие содержать любое вики-форматирование, в том числе и вложенные блочные цитаты. Обрамляются тегами <[ и ]>, которые должны быть в начале и конце строки (или на разных строках) соответственно. Для <[ слева допускаются пробелы.
>> строчная цитата
> более поздняя цитата
Обычный текст.

<[ Блочная цитата с **разметкой** и ((/ ссылкой)). ]>

<[
  Блочная цитата. Список:
    1. Первый;
    2. Второй

  >> цитирование
  > ещё одно

  <[ Вложенная блочная цитата. ]>
]>
  1. строчная цитата
  2. более поздняя цитата

Обычный текст.

Блочная цитата с разметкой и ссылкой.

Блочная цитата. Список:

  1. Первый;
  2. Второй
  1. цитирование
  2. ещё одно

Вложенная блочная цитата.

Строчные цитаты можно отменить с помощью тильды:

~>>>Больше не цитата.

~>> Эта тоже.

~> И эта.

>>>Больше не цитата. >> Эта тоже. > И эта.

Термины (определения)

Термины, аббревиатуры, сокращения, названия — всё, до чего дотянется ваша фантазия. У них основная фишка состоит в двух моментах:

  1. У термина есть «слово» (или несколько слов — то есть сам термин) и «определение». Слово отображается в тексте, тогда как определение показывается как подсказка.
  2. Ко всем упоминаниям слова точно в таком же регистре после его определения автоматически будет добавлено определение, заданное при первом упоминании.
    • это случится даже для упоминаний до собственно задания определения.

Термин обрамляется (? слева и ?) справа. Наподобие пар имя-значение в ассоциативных списках, в терминах они тоже разделяются двумя «равно» == или пробелом, если внутри нет ==.
Понятно, что термины — однострочные.

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

Пример:

== Что такое Swack? ==
  Разметка для (?Swack "Швак", Object Wacko v1?) появилась
в процессе долгой переписки между **Proger_XP** и **Freeman**.
Название "Swack" родилось спонтанно как тема одного из письма -
как, впрочем, и (?Object Wacko == Модуль вики-разметки в UverseWiki?).
  Итак: Swack &&raquo; //Object Wacko// &&raquo; **UverseWiki**.

Разметка для Swack появилась в процессе долгой переписки между Proger_XP и Freeman. Название «Swack» родилось спонтанно как тема одного из письма — как, впрочем, и Object Wacko.
Итак: Swack » Object Wacko » UverseWiki.

Ещё раз повторим: регистр термина имеет значение:

Пожалуйста не путайте
(?MLHS Markup Language for Hyper Space?)
с mlhs - это совершенно разные вещи!

Пожалуйста не путайте MLHS с mlhs — это совершенно разные вещи!

Для уменьшения ложных срабатываний есть порог минимальной длины слова, короче которого термины не будут автозаменяться далее в тексте. Задаётся настройкой UWikiSettings->$minTermLengthToExpand, которая по умолчанию равна двум символам:

Буква (?А Заглавная буква "а"?) - первая в наших
рядах. После неё идёт цифра (?Зо "з" + "о"?)
"А вот и корова!" - сказал Зо, радостно теребя одуванчик.

Буква А — первая в наших рядах. После неё идёт цифра Зо «А вот и корова!» — сказал Зо, радостно теребя одуванчик.

Отменить создание термина, как обычно, можно тильдой:

  * (?Термин Описание?) - ~(?Не термин?).
  * А вот (?ещё такой хитрый ~?) термин?).
  • Термин — (?Не термин?).
  • А вот ещё.

Маркеры

В двух словах, выделенная маркером строка — просто участок текста, имеющий свой стиль, наподобии стилей абзацев в применении к фразам в строке.
Маркеры могут быть двух типов:

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

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

Возможные стили и эффект от них зависит от конкретной темы оформления. Регистр стиля не важен. Имена стилей могут иметь альтернативные названия.

На маркеры действует правило двух символов!! или ?? не могут быть обрамлены пробелами, а также они однострочны.
Если стиль в скобках не задан, то используется умолчательный (зависит от темы оформления). После скобок могут идти пробелы, которые игнорируются.

Примеры:

  * !!Выделенный!! текст. Текст !!(стиль) со стилем!!.
    * ??Не уверен...??   Или вот: ??(внимание)текст??.
  * Комбинация:  ??(стиль) Текст перед !!маркером!!??.
    * Или даже так: ??(стиль) !!(стиль)Текст.!!??
  • Выделенный текст. Текст со стилем.
    • Не уверен… Или вот: текст.
  • Комбинация: Текст перед маркером.
    • Или даже так: Текст.

Выделять маркером пустое место обычно смысла не имеет, однако это полезно для CSS. Например, если вы хотите выделить какой-то определённый форматтер, то это можно сделать так (тоже самое работает и для ??):

!!(style)!! %%formatted%% or
??(style)?? %%formatted%%

formatted or (style) formatted

…а затем добавить к вашей странице такой стиль (<kbd> — тег для умолчательного форматтера %%):

.style + kbd { color: red; }

Отменить маркер можно тильдой:

  * Ааааааах~!! Оооооох~!!
    * Без тильд:  Ааааааах!! Оооооох!!
  * Чё~?? Ты, э, того~??~!!
    * Без тильд:  Чё?? Ты, э, того??!!
      * (!! в конце игнорируется, ибо для
         него всё равно нет закрывающей пары)
  • Ааааааах!! Оооооох!!
    • Без тильд: Ааааааах Оооооох
  • Чё?? Ты, э, того??
    • Без тильд: Чё Ты, э, того!!
      • (!! в конце игнорируется, ибо для него всё равно нет закрывающей пары)

Комментарии

У сомнительного маркера есть ещё одна роль — он может обозначать комментарии, которые не видны читающему (хотя можно вывести документ в режиме черновика и они будут показаны).

Делается это установкой настройки UWikiSettings->$dubiousAsComments в True, либо передачей рендереру WackoDoc.exe параметра --dubious-as-comments. Режим черновика (показ комментариев) включается с помощью UWikiSettings->$showComments и --show-comments.

Естественно, что в режиме комментариев сомнительный маркер ?? перестаёт принимать имя стиля в скобках:

??(стиль) комментарий??

(стиль) комментарий

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

По умолчанию режим комментариев включен. В режиме чистовика комментарии скрываются.

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

??Этот будет просто строчным комментарием.??

А этот - многострочным:
??
  Copyleft (¢) 2010
  - **GLUE TRANSFORMATION** -
  All rights reversed.
??

Этот будет просто строчным комментарием.

А этот — многострочным:

Copyleft (¢) 2010
GLUE TRANSFORMATION
All rights reversed.

Горизонтальные черты

Пожалуй, самая простая часть разметки — 4 вида черт, каждые на вид могут отличаться — зависит от темы оформления.
Задаются тремя и более одинаковых символов из набора - + ~ =. Должны быть единственными на строке, но могут иметь пробелы в начале.

  ---
 =====
  ***
 ~~~~~




Отменить черту можно тильдой:

~----

----

Мнемоники

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

Мнемоники выглядят и действуют точно так же, как в HTML (&nbsp;) с единственным отличием — вместо одного & используется два. Все мнемоники определены в файле entities.conf — по умолчанию их там около 250 штук.

Имена мнемоник регистрозависимы.

//&&Epsilon;uphineus// &&epsilon;urestics &&egrave;mmerged.

Εuphineus εurestics èmmerged.

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

  * Что это? -> &&whatsthat;
  * Эпсилон обозначается так: ~&&epsilon; -> &&epsilon;
  • Что это? → &&whatsthat;
  • Эпсилон обозначается так: &&epsilon; → ε

Якоря

Якорь задаёт имя положению на странице, на которое можно затем точно сослаться — в противовес обычной ссылке без якоря, которая откроет страницу в её начале. Регистр имени якоря как при ссылках на него, так и при задании значения не имеет — имя якоря всегда преобразуется к нижнему регистру.
См. также Адресация в ссылках.

Якоря могут быть блочными — для этого конструкция, напоминающая якорную ссылку, помещается на отдельной строке, как здесь:

((#блочный_якорь))
А это - ссылка на ((#блочный_якорь блочный якорь)).

А это — ссылка на блочный якорь.

Блочные якоря могут содержать пробелы, что особенно удобно при ссылке без названия:

((#блочный_якорь))
А это - ссылка на ((#блочный якорь==)).

А это — ссылка на блочный якорь.

Кроме этого есть возможность создания строчных якорей, если включена настройка UWikiSettings->$inlineAnchors (по-умолчанию включена).

Строчные якоря

Это режим по умолчанию; задаётся настройкой UWikiSettings->$inlineAnchors. Якоря задаются как будто это ссылка без названия на якорь в текущем документе:

Якорь можно расположить прямо [((#здесь_якорь))] внутри строки.

Якорь можно расположить прямо [] внутри строки.

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

  * ((#здесь_якорь==)).

Замена окончания))= работает так, что если окончание указано, то название можно опустить, даже несмотря на то, что имя якоря как будто стоит само по себе:

  * ссылка на один из ((#якор+ь))ей.

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

Отключенные строчные якоря

Когда насройка UWikiSettings->$inlineAnchors отключена (по умолчанию она включена, поэтому действует режим строчных якорей), обработка ссылок изменяется так:

  • ссылки на якоря без явно указанного названия, как это: ((#ссылка)), трактуются как ссылки на якорь, определённый в текущем документе — в противоположность строчным якорям.
  • блочные якоря получают возможность содержать пробелы в своём имени — пример был указан в начале раздела.

Автогенерируемые якоря

Движок автоматически создаёт якоря для элементов, указанных в настройке UWikiSettings->$anchorize — по умолчанию это заголовки и абзацы. Имя якорей заголовов генерируется из содержимого этого заголовка, а имена якорей для других элементов — из их порядкового номера, считая от заголовка.

Якорь для заголовка составляется из «слов»словом здесь считается любая буква, цифра, точка, подчёркивание или дефис. Алгоритм таков:

  1. Содержимое заголовка (например, «Эт некая глава») приводится к нижнему регистру и разбивается на «слова»«эт», «некая» и «глава».
  2. Ищется уникальная последовательность слов, для которой ещё не зарегистрирован якорь — при этом, если добавленное в конец (после подчёркивания) слово короче 3-х символов (UWikiMinAnchorPieceLength), то за ним добавляется следующее, даже если полученная комбинация уже уникальна. Это сделано для исключения предлогов и тому подобных языковых конструкций, не несущих смысловой нагрузки.
  3. Если такую последовательность найти не получилось (все варианты уже заняты якорями), то, как последнее средство, в конец добавляется счётчик, начиная с 1, и увеличивается, пока мы, наконец, не найдём незанятое имя.
    • в нашем случае уникальная комбинация это «эт» и «некая» — имя якоря «эт_некая».
    • если же оба якоря «эт_некая» и «эт_некая_глава» были бы заняты, то мы бы получили якорь «эт_некая_глава_1».

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

== Заглавие ==
  Абзац 1.

=== Секция ==
  Абзац 2.

  1. Пункт 1.
  2. Пункт 2.

  Абзац 3.

Абзац 1.

Секция

Абзац 2.

  1. Пункт 1.
  2. Пункт 2.

Абзац 3.

Чтобы увидеть якорь просто наведите мышку на заголовок, абзац или строку.

См. также настройку UWikiSettings->$autoAnchorContractions, которая задаёт правила сокращения имён автосгенерированных якорей, а также позволяет отключить прибавление префикса определённого элемента к имени якоря (в примере выше якоря для абзацев не имеют префиксов, а якоря списков начинаются с «wacko_listitem_»).

Перегенерация якорей

Для улучшения качества генерируемых якорей есть ещё механизм перегенерации якорей для заголовков при обнаружении заголовка с похожим содержимым. Например, у нас есть 2 заголовка «Глава первая» и «Глава вторая». По алгоритму выше им якоря были бы такими:

  • «Глава первая» → якорь «глава»;
  • «Глава вторая» → якорь «глава_вторая».

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

  • «Глава первая» → якорь «глава_первая»;
  • «Глава вторая» → якорь «глава_вторая».

А если бы у нас была ещё одна «Глава вторая»:

  • «Глава первая» → якорь «глава_первая»;
  • «Глава вторая» → якорь «глава_вторая_1».
  • «Глава вторая» → якорь «глава_вторая_2».

Более жизненный пример, взятый из исходников документации нашей UverseWiki:

  • «Static Methods» → якорь «static methods»;
  • «Instance Methods» → якорь «instance methods».
  • «Static Variables» → якорь «static variables»;
  • «Instance Variables» → якорь «instanse variables».

Больше информации по теме — UWikiSettings->$anchorize.

Сноски

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

Строчные сноски

Задаются прямо в тексте и могут содержать любое строчное вики-форматирование.

<[
  Я говорил ему [[*автору - //прим. перев.//]],
  что основное действо будет происходить в
  одном из городков И. ((*как потом и случилось))...
]>

Я говорил ему [?], что основное действо будет происходить в одном из городков И. [?]

Как видно из примера, сноски задаются похожим на ссылки образом — круглыми или квадратными скобками, первый символ внутри которых — звёздочка.
После звёздочки (или звёздочек) могут идти пробелы, которые игнорируются как для блочных, так и для строчных сносок:

Первая ((*сноска)), и ((* тот же эффект)).

Первая [?], и [?].

В зависимости от настройки UWikiSettings->$inlineFootnotesAs можно задавать 3 вида отображения:

tooltip
как подсказка под [?] — режим по умолчанию, виден в примере выше;
expanded
раскрытие в строке внутри скобок: Текст ((*сноска)) текст => Текст (сноска) текст *;
  • в зависимости от темы оформления такие развёрнутые строчные сноски могут внешне отличаться от основного текста.
block
полностью повторять поведение обычной блочной сноски.
  • если UWikiSettings->$footnotesAtTheEnd включено, то она будет перемещена в конец докумета вместе с прочими сносками, если выключена, то появится после абзаца, где она задана.

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

Строчные сноски в режиме UWikiSettings->$inlineFootnotesAs = expanded:

<[
  Я говорил ему [[*автору - //прим. перев.//]],
  что основное действо будет происходить в
  одном из городков И. ((*как потом и случилось))...
]>

Я говорил ему (автору — прим. перев.), что основное действо будет происходить в одном из городков И. (как потом и случилось)

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

Отменить создание сноски можно тильдой:

Это ~((*не сноска)).

Это ((*не сноска)).

Блочные сноски

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

Блочные сноски состоят из двух частей:

  1. Ссылающегося фрагмента (обозначается как ссылка со звёздочками внутри);
    • например: предложение... ((*)) или предложение... [[*]].
    • по поводу нескольких звёздочек см. раздел сноски по номеру ниже.
  2. Собственно определения сноски.
    • внутри могут быть переводы строк.

Определение сноски задаётся так же, как задаются строчные сноски, но ((* должно быть в начале, а )) — в конце строки (а могут быть и на одной). Перед ((*, как обычно, могут быть пробелы.
Квадратные скобки в определении (типа [[*) работать не будут.

Предложение со ссылкой на сноску [[*]].
((*Определение сноски*))

Либо так [[*]]:
((*
  Определение
  сноски.
))

И всевозможные вариации [[*]]:
((*
  Определение
  сноски.      ))

**Строчная** сноски: [[* квадратные скобки]]

Предложение со ссылкой на сноску *.

Определение сноски*

Либо так *:

Определение сноски.

И всевозможные вариации *:

Определение сноски.

Строчная сноски: [?]

Не указывайте ссылок на сноску на отдельной строке без текста вокруг — она будет скрыта. Также блочная сноска может содержать любое форматирование.

Нормальная сноска ((*)). **Неправильная:**
((*))

Сноска((*)).
((*
  Любое форматирование:
    * списки;
      * ещё.
    * ещё.

  <[
    Цитата:, со списком:
      1. Первый;
      2. Второй.

    И с %%(php) "кодом";%%
  ]>

  %%(html)
    <title>Код прямо в сноске</title>
  %%
))

Нормальная сноска *. Неправильная:

Сноска*.

Любое форматирование:

  • списки;
    • ещё.
  • ещё.

Цитата:, со списком:

  1. Первый;
  2. Второй.

И с PHP"кодом";

<title>Код прямо в сноске</title>

Сноски по номеру

Выше были описаны ненумерованные сноски с одной звёздочкой — то есть ссылкой по порядку их определения:

Первая сноска((*)),
вторая[[*]], третья((*)).

((* Первая))
((*Вторая))
((*Третья))

Первая сноска*, вторая*, третья*.

Первая

Вторая

Третья

Однако можно ещё ссылаться по порядку, ставя несколько звёздочек подряд — до 9 штук, но т. к. одна звёздочка используется для ссылки по порядку определения, то номеров остаётся 8.
Кстати, сноски по номеру — единственный способ сослаться на одно определение несколько раз.

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

Вторая сноска((***)),
третья[[****]], первая((**)),
четвёртая - [[*****]].

((****Третья))
((** Первая))
((***Вторая))
((***** Четвёртая))

Вторая сноска*, третья*, первая*, четвёртая — *.

Третья

Первая

Вторая

Четвёртая

Это полезно, когда сноски часто добавляются, удаляются или передвигаются.

Главное, не смешивать ненумеровнные сноски (по одной звёздочке) и по номеру — иначе связь сносок и определений нарушится:

Сноска 2((**)), 1((*)) и 3((***)).
((* №1))
((** №2))
((*** №3?))

Сноска 2*, 1* и 3*.

№1

    №2

      №3?

      Естественно, что 8 номерных сносок даются не на целый документ — их можно использовать повторно, как только все сноски и определения связаны между собой:

      Вторая сноска((***)),
      третья[[****]], первая((**)),
      
        ((**** Третья))
        ((** Первая))
        ((*** Вторая))
      
      Теперь **уже другая** первая((**)),
      третья((****)) и вторая[[***]].
      
        ((** Первая))
        ((*** Вторая))
        ((**** Третья))

      Вторая сноска*, третья*, первая*,

      Третья

      Первая

      Вторая

      Теперь уже другая первая*, третья* и вторая*.

      Первая

      Вторая

      Третья

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

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

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

      Правильное* использование смешанной* адресации*.

      сноска

      ещё одна

      всё, на сноски больше ссылок нет

      Начался новый абзац* — уже с другой адресацией*, т. к. теперь нечему путаться.

      сноска

      ещё

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

      Если на сноску не была найдена ссылка, то она будет выведена как есть. Потерянная же ссылка останется звёздочкой. Если же определённая сноска №2-9 была переопределена по номеру, то будет оставлена первая с этим номером, а последующие будут считаться без ссылок на себя.

      Сноска №3 ((***)) - но для неё нет
      определения - потерянная сноска.
      
      А это - потерянное определение
      без ссылок на себя:
      ((** выводится как есть))

      Сноска №3 * — но для неё нет определения — потерянная сноска.

      А это — потерянное определение без ссылок на себя:

        выводится как есть

        Несколько ссылок

        Сноски по номеру позволяют сослаться на одно определение сноски из нескольких мест:

        Все эти сноски((**)) ссылаются на
        одно[[**]] и то же ((**)) место.
        
        ((** Сноска с тремя ссылками))
        
        Потерянная сноска ((**)) - её
        определение уже было сделано выше.

        Все эти сноски* ссылаются на одно* и то же * место.

        Сноска с тремя ссылками

        Потерянная сноска * — её определение уже было сделано выше.

        Форматтеры

        Форматтер (formatter) — это вставка в документ «инородного» содержимого, то есть имеющего формат, отличный от основного формата документа.
        Например, для страницы, что сейчас у вас перед глазами, основной формат (разметка) — вики. Однако ничто не мешает вставить пару-тройку листингов на HTML или Delphi — заметьте, без нарушения разметки (это был камень в огород BB-кода :)).

        Форматтерам можно передавать параметры, об этом подробнее здесь, а также они могут быть сцепленными.
        Ещё больше о форматтерах можно прочитать в документации. См. также раздел о действиях. Имена стилей могут иметь альтернативные названия.

        Блочные форматтеры

        Их ещё называют многострочными, хотя они могут состоять и из одной строки.

        Для его задания используется двойной процент %%, после которого в скобках может идти название языка или другое имя для типа текста, заключённого между %%. Оба %% должны быть на отдельных строках, причём перед ними допускаются пробелы.
        Если стиль опущен, то используется умолчательный — здесь это просто моноширный шрифт без вики- или какой-либо другой разметки. Регистр стиля не важен.

        %%
          Моноширный текст,
          **разметка** отключена.
        %%
        
        %%(html)
          <!DOCTYPE html>
          <html>
            <head>
              <style type="text/css">
              .myClass { font-family: "Consolas"; }
              </style>
        %%
        Моноширный текст,
        **разметка** отключена.
        
        <!DOCTYPE html>
        <html>
          <head>
            <style type="text/css">
            .myClass { font-family: "Consolas"; }
            </style>
        

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

        %%(отразить)
          %%(DELPHI)
            WriteLn('Hellold!');
          ~%%
        
          Обратите внимание на тильду сверху.
        %%
        %%(DELPHI)
          WriteLn('Hellold!');
        %%
        
        Обратите внимание на тильду сверху.
        WriteLn('Hellold!');
        

        Обратите внимание на тильду сверху.

        Во всех других случаях тильда внутри блока %% игнорируется полностью. Также можно задавать сколько угодно тильд в зависимости от уровня вложенности:

        %%(отразить)
          %%(отразить)
            %%(ini)
            [Section]
            ~~%%
          ~%%
        %%
        %%(отразить)
          %%(ini)
          [Section]
          ~%%
        %%
        %%(ini)
        [Section]
        %%
        [Section]
        

        WackoWiki

        UverseWiki поддерживает все подсветчики (highlighters) движка WackoWiki. Установить их можно простым копированием, как описано здесь. Например, вот wrapper_page оттуда:

        %%(wrapper_page wrapper_width=30)
          Очень узкая колонка
        %%
        Очень узкая колонка
        

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

        Строчные форматтеры

        С ними всё то же самое — задаются двойными процентами (%%) и могут иметь стиль в скобках.

        Отформатируем немного %%(XML) <XML>%%.
        Или просто %%текст **без разметки**%%.

        Отформатируем немного <XML>. Или просто текст **без разметки**.

        Как и с блочным форматтером, тильда внутри может отменить %%, а в других случаях игнорируется:

        Просто двойной процент: %%~%%%%.
        Или: %%(pascal) Format('%2.1f~%%');%%

        Просто двойной процент: %%. Или: Format('%2.1f%%');

        Не все форматтеры могут быть выведены в строчной форме, поэтому вместо них будет выведено предупреждение:

        Внимание! "%%(wrapper_page) текст%%"

        Внимание! «текст»

        Действия

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

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

        Формально действия могут быть строчными и блочными, хотя разделение это не такое сильное, как для форматтеров — обычно блочные действия (такие как {{Оглавление}}) и так не придёт в голову поставить внутрь строки; тоже самое наоборот.

        И те, и другие действия обрамляются двойными фигурными скобками: {{ слева и }} справа. Действиям можно передавать параметры, об этом подробнее здесь. Они также могут быть сцепленными.

        Теперь примеры (регистр букв в имени действия не важен):

        Действие %%Func%% генерирует ссылку на
        раздел в документации.
        Оно строчное: {{Func base->Parse}}
        
        Действие %%Оглавление%% делает очевидную
        вещь (кроме того, оно ещё очевидно блочное):
        {{Оглавление 2}}
        
        Картинка: {{Картинка /wiki/sandbox/media/uversewiki.png}}
        Картинка блочным действием, так как имеет подпись:
        {{Картинка /wiki/sandbox/media/objectwacko.png, ObjectWacko v1 "Swack"}}

        Действие Func генерирует ссылку на раздел в документации. Оно строчное: UWikiBase->Parse()

        Действие Оглавление делает очевидную вещь (кроме того, оно ещё очевидно блочное):

        1. 1. Простое форматирование
        2. 2. Разрывы строк
        3. 3. Заголовки
        4. 4. Отмена элементов разметки
        5. 5. Выравнивание текста
        6. 6. Отступы
        7. 7. Стили абзацев
        8. 8. Ссылки
        9. 9. Списки
        10. 10. Цитаты
        11. 11. Термины (определения)
        12. 12. Маркеры
        13. 13. Комментарии
        14. 14. Горизонтальные черты
        15. 15. Мнемоники
        16. 16. Якоря
        17. 17. Сноски
        18. 18. Форматтеры
        19. 19. Действия
        20. 20. Параметры для форметтеров и действий
        21. 21. Сцепление форматтеров и действий

        Картинка: /wiki/doc/ru/wiki/sandbox/media/uversewiki.png Картинка блочным действием, так как имеет подпись:

        /wiki/doc/ru/wiki/sandbox/media/objectwacko.png

        ObjectWacko v1 «Swack»

        Как и форматтеры, не всякое действие можно вставить внутрь строки:

        Оглавление трудно представить в
        одной строке: "{{ОГЛАВЛЕНИЕ}}"

        Оглавление трудно представить в одной строке: «1. Простое форматирование»

        Действие можно отменить с помощью тильды (вывести как текст):

        Просто текст: ~{{Func}}.

        Просто текст: {{Func}}.

        Параметры для форметтеров и действий

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

        • иметь имя — то есть передаваться поимённо;
        • иногда параметр без имени передаётся позиционно;
        • не иметь значения (только имя) — так называемый флаг.

        Поимённая передача

        Имя параметра, если оно есть, отделяется от значения знаком «равно»: {{Действие имя=значение}}. Несколько параметров: {{Действие имя=значение, имя2=другое значение}}.

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

        • {{действие "значение с = равно внутри"}};
        • {{действие "имя с , внутри" = "значение с = равно"}};
        • {{Действие имя="зна= че, ние"}}.

        Вокруг «=» можно ставить пробелы для большей читаемости — они игнорируются. То же самое относится и к пробелам после запятой.

        Форматтеры принимают параметры точно также:

        %%(wrapper_page wrapper_width=30)
          Ко лон ка
        %%
        Ко лон ка
        

        Если нужно передать действию параметр, содержащий его закрывающий тег (}}), то параметр можно экранировать тильдой: {{FormatDescription inherits={{Class $~}}, type=**$**}}.

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

        Оба варианта идентичны:
          * {{Description  тип=массив, значение% = "%%(php) array('value', ...)%%" }}
          * {{Description: тип=массив, значение% = "%%(php) array('value', ...)%%" }}

        Оба варианта идентичны:

        • тип
          массив
          значение
          "%%(php
        • тип
          массив
          значение
          "%%(php

        Позиционная передача

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

        • поимённо: {{Картинка file=photo.jpg, title=Наша фотка}};
        • позиционно: {{Картинка photo.jpg, Наша фотка}};
        • смешанно: {{Картинка photo.jpg, title=Наша фотка}}.

        **Первый же параметр, переданный с указанием имени, отменяет позиционную передачу для всех последующих.** Иными словами, так не работает: {{Картинка file=photo.jpg, Наша фотка}}.

        Ещё один пример — действие оглавления, которое имеет один параметр up to, задающий глубину включаемых в содержание заголовков:

        • {{Оглавление 2}} — включить заголовки до уровня 2;
        • {{Оглавление up to=2}} — абсолютно тоже самое, только в полной форме.

        Позиционная передача работает до первого переданного поимённо параметра — см. порядку или флаг?.

        Флаги

        Если параметр не имеет имени и не передаётся позиционно, то он считается флагом. Флаг — просто параметр, имеющий значение «1» (True). Обычно он что-то «включает».
        Для нас, пользователей, это ничего не меняет — просто другое смысловое название для такого типа праметров. Например:

        • {{Описание тип=строка, регистронезависимая}} — здесь регистронезависимаяфлаг.

        По порядку или флаг?

        Иногда может возникнуть ситуация, когда параметр, переданный без имени, может быть истолкован одновременно как переданный по позиции (1-й, 2-й, 3-й и т. д. аргумент), или как флаг (параметр со значением «1») — такие параметры всегда считаются переданными позиционно.

        Например, действие {{Вставить}} принимает позиционно 2 параметра:

        1. page — имя файла для вставки в документ;
        2. format — его разметка — «wiki» и т. д. (если опущен, используется разметка основного документа).

        А также 1 параметр по имени:

        1. isolate — это флаг.

        Тогда при вызове этого действия такой строкой: {{Вставить Секция, isolate}}isolate может быть трактован и как разметка (аргумент на 2-й позиции), и как флаг по имени isolate. Этот спор всегда решается в пользу позиционной передачи, поэтому чтобы isolate воспринялся как флаг, его нужно явно установить в 1: {{Вставить Секция, isolate=1}}.

        Для сравнения, если мы укажем разметку явно, то isolate будет считаться флагом, ибо все позиционные параметры уже были переданы: {{Вставить Секция, wiki, isolate}}.

        Заметьте, что позиционная передача работает до первого переданного поимённо параметра: {{Вставить page=Секция, isolate}} — здесь, несмотря на то, что ни один параметр не передан позиционно, первый параметр уже имеет имя, поэтому и isolate — флаг.

        Сцепление форматтеров и действий

        Одна из полезнейших возможностей разметки UverseWiki — комбинирование действий и форматтеров друг с другом. Например, форматтер Отражение (Mirror) форматирует переданный ему текст и размещает его в две колонки: слева — исходный, справа — отформатированный. По умолчанию он форматирует в вики, однако ничто не мешает задать любой другой существующий форматтер.
        Чем-то напоминает передачу по конвейеру в консоли (cat | grep).

        Для этого нужно разделить оба форматтера (хотя их может быть сколько угодно много) точкой с запятой:

        %%(отразить; java)
          import core.*;
          class { }
        %%
        import core.*;
        class { }
        import core.*;
        class { }
        

        Каждому форматтеру или действию можно передавать параметры как обычно:

        %%(If format=html; wrapper_box wrapper_align=right, wrapper_width=100)
          Содержимое...
        %%
        

        Здесь вдобавок демонстрируется комбинирование действия (If) и форматтера (wrapper_box). Хотя надо сказать, что чем меньше таких конструкций вам придётся употреблять, тем читабельнее будет документ.

        Также есть альтернативная форма сцепления — когда ни одному форматтеру не передаётся параметров — тогда можно их передать через запятую вместо точки с запятой:

        %%(отразить, CSS)
          #wrapper.wide { width: 90%; }
        %%
        #wrapper.wide { width: 90%; }
        #wrapper.wide { width: 90%; }