TracLinks

Trac-ссылки

TracLinks (Trac-ссылки) — одна из важнейших функций Trac, поскольку они допускают легкое добавление гиперссылок между различными сущностями в системе, такими как тикеты, отчеты, правки (changesets), страницы Wiki, этапы (milestones), и исходные файлы, в общем, везде где используется Wiki-форматирование.

Trac-ссылки обычно имеют форму type:id (где id представляет номер, имя или путь объекта), однако чаще используется краткая форма записи.

Где используются Trac-ссылки

Вы можете использовать Trac-ссылки в:

• Исходных кодах (Subversion), комментариях к коммитам
• Wiki-страницах
• Полных описаниях тикетов, отчетов и этапов

и любые другие текстовые поля, явно поддерживающие Wiki-форматирование.

Примеры:

• Тикеты (Tickets): #1 или ticket:1
• Комментарии к тикетам: comment:ticket:1:2
• Отчеты (Reports): {1} или report:1
• Правки (Changesets): [1] или changeset:1
• Лог хранилища(Revision log): r1:3, [1:3] или log:@1:3, log:trunk@1:3
• Сравнения (Diffs): (требуют 0.10): diff:@1:3, diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default или diff:trunk/trac@3538//sandbox/vc-refactoring@3539
• Wiki-страницы: CamelCase или wiki:CamelCase
• Родительская статья: [..]
• Этапы (Milestones): milestone:1.0
• Приложение (Attachment): attachment:ticket:944:attachment.1073.diff
• Файлы: source:trunk/COPYING
• Конкретная редакция (правка) файла: source:/trunk/COPYING@200
• Конкретная строка правки файла: source:/trunk/COPYING@200#L25

Покажут:

• Тикеты (Tickets): #1 или ticket:1
• Комментарии к тикетам: comment:ticket:1:2
• Отчеты (Reports): {1} или report:1
• Правки (Changesets): [1] или changeset:1
• Лог хранилища(Revision log): r1:3, [1:3] или log:@1:3, log:trunk@1:3
• Сравнения (Diffs): (требуют 0.10): diff:@1:3, diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default или diff:trunk/trac@3538//sandbox/vc-refactoring@3539
• Wiki-страницы: CamelCase или wiki:CamelCase
• Родительская статья: ..
• Этапы (Milestones): milestone:1.0
• Приложение (Attachment): attachment:ticket:944:attachment.1073.diff​
• Файлы: source:trunk/COPYING​
• Конкретная редакция (правка) файла: source:/trunk/COPYING@200​
• Конкретная строка правки файла: source:/trunk/COPYING@200#L25​

Внимание: Форма записи wiki:CamelCase используется нечасто, но может быть удобной для ссылок на страницы, имена которых не следуют правилам WikiPageNames, то есть состоят из одиночных слов, неалфавитных символов и т.д. См. WikiPageNames для более полной информации.

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

[ticket:1 Это ссылка на карточку номер 1].

Отобразится:

Это ссылка на карточку номер 1.

Если альтернативный текст для ссылке не прописан, будет показан только идентификатор ссылки (часть после двоеточия):

[ticket:1]

Отобразится: 1

wiki — тип по умолчанию для подробной нотации ссылок, если часть "namespace" (тип ссылки) опущена (с версии 0.10), например:

[SandBox the sandbox]

Отобразится: the sandbox Sandbox - "песочница" (англ.)

Trac-ссылки — это очень простая идея, но позволяет легко создать актуальную сколь угодно сложную связную информационную структуру. На практике такой синтаксис является интуитивно простым в использовании, и мы (разработчики) находим "ссылки с названиями" (link trail) неплохим инструментов для облегчения понимания того, что происходит в проекте, и почему были сделаны конкретные изменения.

Расширенное использование Trac-ссылок

Относительные ссылки

Для того, чтобы создать ссылку на некоторый "якорь" в статье, используйте '#':

 [#Relativelinks relative links]

Отобразится:

relative links

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

Для создания ссылки на SubWiki-статью просто используйте '/':

 WikiPage/SubWikiPage или ./SubWikiPage

Для создания ссылки с SubWiki-статьи на родительскую, просто используйте '..':

  [..]

Для ссылки с SubWiki-статьи на соседнюю по уровню статью, используйте '../':

  [../Sibling см. следующего "Брата"]

(Изменения с 0.11) Заметьте, что в Trac 0.10, использовавшем например `newticket могло работать для ссылки на /newticket верхнего уровня URL, но теперь в 0.11, останется на том же уровне (wiki namespace — пространство имен) и ссылается на страницу "брата". Смотри #Server-relativelinks по новому синтаксису.

InterWiki-ссылки (ссылки между различными Wiki-ресурсами в сети)

Свободно можно настроить альтернативные префиксы для отсылки к другим Web-приложениям. Определение таких префиксов а также корреспонденцию (трансляцию, соответствие) URL-ов Web-приложений задается в специальной Wiki-статье InterMapTxt. Заметьте, что тогда это могло бы быть использовано для создания ссылок на другие Trac-окружения (проекты), то есть более гибко связывать между собой различные проекты под управлением Trac.

InterTrac-ссылки

Это может выглядеть подобным InterWiki-ссылкам для указания гиперссылки на другие Trac-проекты.

Любой тип Trac-ссылок может быть описан в одном Trac-окружении (проекте) и в действительности ссылаться на ресурсы, предоставляемые другим trac-окружением (проектом), в этом случае префикс ссылки должен совпадать с именем другого Trac-окружения и, как и в общем случае, отделен двоеточием. Такое Trac-окружение должно быть зарегистрировано под своим именем или псевдонимом (см. подробнее InterTrac).

Главное преимущество InterTrac-ссылок перед InterWiki-ссылками в том, что форма записи обычных ссылок использует аналогичную нотацию. Например, ссылка на тикет может быть указана #T234 (если зарегистрирован псевдоним T для Trac), ссылка на правку может быть записана как [trac 1508].

Относительные ссылки в пределах сервера (????)

Часто бывает полезным для указания объектов в вашем проекте, не подерживаемых механизмом Trac-ссылок, таких как статические ресурсы, newticket, расшаренный каталог /register на сервере и т.п.

Для связки ресурсов внутри проекта, также можно использовать абсолютный путь из корневого каталога проекта, или относительную ссылку от URL текущей страницы (появилось в 0.11):

[/newticket Create a new ticket]
[/ home]

Отобразится: newticket home

Для ссылки на другой каталог сервера (вне окружения проекта), используйте 'location' синтаксис ссылок (появилось в 0.11):

[//register Register Here]

Отобразится: Register Here

Употребление пробелов в Trac-ссылках

Непосредственно после префикса Trac-ссылка принимает целью символы до первого пробела или все, "уложенные" в кавычки одинарные или двойные.

Примеры:

• wiki:"The whitespace convention"
• attachment:'the file.txt' or
• attachment:"the file.txt"
• attachment:"ticket:123:the file.txt"

Примеч. переводчика: для указания конкретной правки файла, номер правки должен быть тоже "уложен" в кавычки: source:"the main project file.prj@24" the main project file.prj@24

Запрет генерации Trac-ссылки

Во избежание нежелательного создания !Trac-ссылки] вы можете предварять их символом '!' (знак восклицания). Например:

 !НеНадоСсылок.
 ![42] никуда не ссылается.

Покажет:

НеНадоСсылок. [42] никуда не ссылается.

Trac-ссылки с параметром

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

Любая Trac-ссылка поддерживает произвольную расстановку параметров, записанных в том же виде, что и в соответствующем URL. Например:

• wiki:WikiStart?format=txt
• ticket:1?version=1
• [/newticket?component=module1 create a ticket for module1]

Каталог Trac-ссылок (?????? Reference)

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

attachment: ссылки (Файл-приложение/аттачмент)

Синтаксис для аттачментов:

• attachment:the_file.txt создает ссылку на аттачмент the_file.txt для текущего объекта
• attachment:wiki:MyPage:the_file.txt создает ссылку на аттачмент the_file.txt для Wiki-статьи MyPage
• attachment:ticket:753:the_file.txt создает ссылку на аттачмент the_file.txt для тикета 753

query: ссылки

См. TracQuery#UsingTracLinks ([TranslationRu/TracQuery#ИспользованиеTracЗапросов]) и #ticket:links.

search: ссылки

См. TracSearch#SearchLinks ([TranslationRu/TracSearch#СсылкиНаРезультатыПоиска])

ticket: ссылки

Кроме очевидной формы ticket:id, можно указать список тикетов или даже диапазон вместо номера id. Такая запись генерирует гиперссылку на запрос с перечнем указанных тикетов.

Примеры:

• ticket:5000-6000
• ticket:1,150

(Появилось в Trac 0.11)

timeline: ссылки

Для задания ссылки на ленту времени нужно указать дату в формате ​ISO:8601. Дополнительно к дате может быть уточнено и время. Время предполагается UTC (Универсальное координированное время), однако можете указать и свое местное время, с часовым поясом, если не хотите вычислять UTC-время.

Примеры:

• timeline:2008-01-29
• timeline:2008-01-29T15:48
• timeline:2008-01-29T16:48Z+01

(Появилось в Trac 0.11)

wiki: ссылки

См. WikiPageNames ([translationRu/WikiPageNames]) и Употребление пробелов в Trac-ссылках.

Cсылки на систему контроля версий

source: ссылки (Ссылки на исходные коды из хранилища)

По умолчанию ссылки source:/some/path открывают браузер репозитория, если путь указывает на каталог. Иначе открывается просмотр истории изменений файла. Есть возможность ссылаться прямо на конкретную правку (ревизию) файла:

• source:/some/file@123 — ссылка на правку 123
• source:/some/file@head — сразу на крайнюю правку файла

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

• source:/some/file@123#L10
• source:/tag/0.10@head#L10

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

• source:/some/file@123:10-20,100,103#L99 - подсветка строк с 10 по 20, и отдельно строк 100 и 103.

(Появилось в 0.11)

export: ссылки

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

• export:/some/file - получить HEAD правку (крайнюю) указанного файла
• export:123:/some/file - получить правку № 123 указанного файла
• export:/some/file@123 - получить правку № 123 указанного файла

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

Если путь к директории хранилища включает конкретный файл, окно браузера репозитория будет отображать директорию (подобно результату source:/some/dir).

log: ссылки

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

• log:/ - Полный лог изменений, по всему дереву хранилища (/ - root), начиная с крайней правки HEAD и раньше
• log:/trunk/tools - Полный лог изменений trunk/tools, начиная с крайней правки HEAD и раньше
• log:/trunk/tools@10000 - Изменения trunk/tools, вошедшие в правки, начиная с № 10000 и более старые
• log:@20788,20791:20795 - Правки хранилища 20788 и диапазон правок с 20791 до 20795
• log:/trunk/tools@20788,20791:20795 - Изменения trunk/tools, вошедшие в правку 20788 и правки с 20791 по 20795.

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

• [20788,20791:20795]
• [20788,20791:20795/trunk/tools]
• r20791:20795 (но не r20788,20791:20795и не r20791:20795/trunk)

Наконец, заметьте, что во всех вышеуказанных примерах диапазоны правок могут указываться с одинаковым успехом как x:y так и x-y.

---

См. также: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki

(russian): TracTermsRu?