| 1 | = TracLinks = |
| 2 | = Trac-ссылки = |
| 3 | [[PageOutline]] |
| 4 | [[TranslatedPages(revision=0)]] |
| 5 | |
| 6 | TracLinks (Trac-ссылки) — одна из важнейших функций Trac, поскольку они допускают легкое добавление гиперссылок между различными сущностями в системе, такими как тикеты, отчеты, правки (changesets), страницы Wiki, этапы (milestones), и исходные файлы, в общем, везде где используется [wiki:WikiFormatting Wiki-форматирование]. |
| 7 | |
| 8 | Trac-ссылки обычно имеют форму '''type:id''' (где ''id'' представляет номер, имя или путь объекта), однако чаще используется краткая форма записи. |
| 9 | |
| 10 | == Где используются Trac-ссылки == |
| 11 | |
| 12 | Вы можете использовать [wiki:TracLinks Trac-ссылки] в: |
| 13 | |
| 14 | * Исходных кодах (Subversion), комментариях к коммитам |
| 15 | * Wiki-страницах |
| 16 | * Полных описаниях тикетов, отчетов и этапов |
| 17 | |
| 18 | и любые другие текстовые поля, явно поддерживающие [wiki:WikiFormatting Wiki-форматирование]. |
| 19 | |
| 20 | Примеры: |
| 21 | |
| 22 | * Тикеты (Tickets): '''!#1''' или '''!ticket:1''' |
| 23 | * Комментарии к тикетам: '''!comment:ticket:1:2''' |
| 24 | * Отчеты (Reports): '''!{1}''' или '''!report:1''' |
| 25 | * Правки (Changesets): '''![1]''' или '''!changeset:1''' |
| 26 | * Лог хранилища(Revision log): '''!r1:3''', '''![1:3]''' или '''!log:@1:3''', '''!log:trunk@1:3''' |
| 27 | * Сравнения (Diffs): (требуют [milestone:0.10 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''' |
| 28 | * Wiki-страницы: '''CamelCase''' или '''!wiki:CamelCase''' |
| 29 | * Родительская статья: '''![..]''' |
| 30 | * Этапы (Milestones): '''!milestone:1.0''' |
| 31 | * Приложение (Attachment): '''!attachment:ticket:944:attachment.1073.diff''' |
| 32 | * Файлы: '''!source:trunk/COPYING''' |
| 33 | * Конкретная редакция (правка) файла: '''!source:/trunk/COPYING@200''' |
| 34 | * Конкретная строка правки файла: '''!source:/trunk/COPYING@200#L25''' |
| 35 | |
| 36 | Покажут: |
| 37 | * Тикеты (Tickets): #1 или ticket:1 |
| 38 | * Комментарии к тикетам: comment:ticket:1:2 |
| 39 | * Отчеты (Reports): {1} или report:1 |
| 40 | * Правки (Changesets): [1] или changeset:1 |
| 41 | * Лог хранилища(Revision log): '''r1:3''', '''[1:3]''' или '''log:@1:3''', '''log:trunk@1:3''' |
| 42 | * Сравнения (Diffs): (требуют [milestone:0.10 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''' |
| 43 | * Wiki-страницы: CamelCase или wiki:CamelCase |
| 44 | * Родительская статья: '''[..]''' |
| 45 | * Этапы (Milestones): milestone:1.0 |
| 46 | * Приложение (Attachment): '''attachment:ticket:944:attachment.1073.diff''' |
| 47 | * Файлы: source:trunk/COPYING |
| 48 | * Конкретная редакция (правка) файла: source:/trunk/COPYING@200 |
| 49 | * Конкретная строка правки файла: source:/trunk/COPYING@200#L25 |
| 50 | |
| 51 | '''Внимание:''' Форма записи wiki:CamelCase используется нечасто, но может быть удобной для ссылок на страницы, имена которых не следуют правилам WikiPageNames, то есть состоят из одиночных слов, неалфавитных символов и т.д. См. WikiPageNames для более полной информации. |
| 52 | |
| 53 | Ссылки с использованием полного синтаксиса могут быть использованы также для указания названия ссылки вручную, например: |
| 54 | |
| 55 | {{{ |
| 56 | [ticket:1 Это ссылка на карточку номер 1]. |
| 57 | }}} |
| 58 | Отобразится: |
| 59 | |
| 60 | [ticket:1 Это ссылка на карточку номер 1]. |
| 61 | |
| 62 | Если альтернативный текст для ссылке не прописан, будет показан только идентификатор ссылки (часть после двоеточия): |
| 63 | |
| 64 | {{{ |
| 65 | [ticket:1] |
| 66 | }}} |
| 67 | Отобразится: [ticket:1] |
| 68 | |
| 69 | `wiki` — тип по умолчанию для подробной нотации ссылок, если часть "namespace" (тип ссылки) опущена (с версии 0.10), например: |
| 70 | {{{ |
| 71 | [SandBox the sandbox] |
| 72 | }}} |
| 73 | |
| 74 | Отобразится: [SandBox the sandbox] '' Sandbox - "песочница" (англ.) '' |
| 75 | |
| 76 | [wiki:TracLinks Trac-ссылки] — это очень простая идея, но позволяет легко создать актуальную сколь угодно сложную связную информационную структуру. На практике такой синтаксис является интуитивно простым в использовании, и мы (разработчики) находим "ссылки с названиями" (link trail) неплохим инструментов для облегчения понимания того, что происходит в проекте, и почему были сделаны конкретные изменения. |
| 77 | |
| 78 | == Расширенное использование [TracLinks Trac-ссылок] == |
| 79 | |
| 80 | === Относительные ссылки === |
| 81 | Для того, чтобы создать ссылку на некоторый "якорь" в статье, используйте '#': |
| 82 | {{{ |
| 83 | [#Relativelinks relative links] |
| 84 | }}} |
| 85 | Отобразится: |
| 86 | [#Relativelinks relative links] |
| 87 | |
| 88 | Примечание: когда вы перемещаете мышь над названием абзаца, '¶' символ будет отображен. Это ссылка в этой на этот абзац и можете использовать его, чтобы скопировать `#...` часть относительной ссылки на якорь. |
| 89 | |
| 90 | Для создания ссылки на SubWiki-статью просто используйте '/': |
| 91 | {{{ |
| 92 | WikiPage/SubWikiPage или ./SubWikiPage |
| 93 | }}} |
| 94 | |
| 95 | Для создания ссылки с SubWiki-статьи на родительскую, просто используйте '..': |
| 96 | {{{ |
| 97 | [..] |
| 98 | }}} |
| 99 | |
| 100 | Для ссылки с SubWiki-статьи на соседнюю по уровню статью, используйте '../': |
| 101 | {{{ |
| 102 | [../Sibling см. следующего "Брата"] |
| 103 | }}} |
| 104 | |
| 105 | ''(Изменения с 0.11)'' Заметьте, что в Trac 0.10, использовавшем например `[../newticket] могло работать для ссылки на /newticket верхнего уровня URL, но теперь в 0.11, останется на том же уровне (wiki namespace — пространство имен) и ссылается на страницу "брата". Смотри [#Server-relativelinks] по новому синтаксису. |
| 106 | |
| 107 | === InterWiki-ссылки (ссылки между различными Wiki-ресурсами в сети) === |
| 108 | |
| 109 | Свободно можно настроить альтернативные префиксы для отсылки к другим Web-приложениям. Определение таких префиксов а также корреспонденцию (трансляцию, соответствие) URL-ов Web-приложений задается в специальной Wiki-статье InterMapTxt. Заметьте, что тогда это могло бы быть использовано для создания ссылок на другие Trac-окружения (проекты), то есть более гибко связывать между собой различные проекты под управлением Trac. |
| 110 | |
| 111 | === InterTrac-ссылки === |
| 112 | |
| 113 | Это может выглядеть подобным InterWiki-ссылкам для указания гиперссылки на другие Trac-проекты. |
| 114 | |
| 115 | Любой тип Trac-ссылок может быть описан в одном Trac-окружении (проекте) и в действительности ссылаться на ресурсы, предоставляемые другим trac-окружением (проектом), в этом случае префикс ссылки должен совпадать с именем другого Trac-окружения и, как и в общем случае, отделен двоеточием. Такое Trac-окружение должно быть зарегистрировано под своим именем или псевдонимом (см. подробнее InterTrac). |
| 116 | |
| 117 | Главное преимущество InterTrac-ссылок перед InterWiki-ссылками в том, что форма записи обычных ссылок использует аналогичную нотацию. Например, ссылка на тикет может быть указана #T234 (если зарегистрирован псевдоним T для Trac), ссылка на правку может быть записана как [trac 1508]. |
| 118 | |
| 119 | === Относительные ссылки в пределах сервера (????) === |
| 120 | |
| 121 | Часто бывает полезным для указания объектов в вашем проекте, не подерживаемых механизмом Trac-ссылок, таких как статические ресурсы, `newticket`, расшаренный каталог /register на сервере и т.п. |
| 122 | |
| 123 | Для связки ресурсов внутри проекта, также можно использовать абсолютный путь из корневого каталога проекта, или относительную ссылку от URL текущей страницы (''появилось в 0.11''): |
| 124 | {{{ |
| 125 | [/newticket Create a new ticket] |
| 126 | [/ home] |
| 127 | }}} |
| 128 | Отобразится: [../newticket newticket][[comment(FIXME that's the 0.10 syntax)]] [/ home] |
| 129 | |
| 130 | Для ссылки на другой каталог сервера (вне окружения проекта), используйте '//location' синтаксис ссылок (''появилось в 0.11''): |
| 131 | {{{ |
| 132 | [//register Register Here] |
| 133 | }}} |
| 134 | Отобразится: [//register Register Here] |
| 135 | |
| 136 | === Употребление пробелов в Trac-ссылках === |
| 137 | Непосредственно после префикса Trac-ссылка принимает целью символы до первого пробела или все, "уложенные" в кавычки одинарные или двойные. |
| 138 | |
| 139 | Примеры: |
| 140 | * !wiki:"The whitespace convention" |
| 141 | * !attachment:'the file.txt' or |
| 142 | * !attachment:"the file.txt" |
| 143 | * !attachment:"ticket:123:the file.txt" |
| 144 | |
| 145 | '' Примеч. переводчика: для указания конкретной правки файла, номер правки должен быть тоже "уложен" в кавычки:'' |
| 146 | {{{source:"the main project file.prj@24"}}} |
| 147 | [source:"the main project file.prj@24"] |
| 148 | |
| 149 | === Запрет генерации Trac-ссылки === |
| 150 | Во избежание нежелательного создания !Trac-ссылки] вы можете предварять их символом '!' (знак восклицания). Например: |
| 151 | {{{ |
| 152 | !НеНадоСсылок. |
| 153 | ![42] никуда не ссылается. |
| 154 | }}} |
| 155 | |
| 156 | Покажет: |
| 157 | !НеНадоСсылок. |
| 158 | ![42] никуда не ссылается. |
| 159 | |
| 160 | === Trac-ссылки с параметром === |
| 161 | |
| 162 | Trac-ссылки указывающие на ресурсы, могут иметь более, чем один путь, который должен быть подставлен целью, в зависимости от некоторых параметров. Например, Wiki-статья может принимать параметры `version` (версия) или `format` (формат), отчет может использовать динамические переменные и т.п. |
| 163 | |
| 164 | Любая Trac-ссылка поддерживает произвольную расстановку параметров, записанных в том же виде, что и в соответствующем URL. Например: |
| 165 | - `wiki:WikiStart?format=txt` |
| 166 | - `ticket:1?version=1` |
| 167 | - `[/newticket?component=module1 create a ticket for module1]` |
| 168 | |
| 169 | == Каталог Trac-ссылок (?????? Reference) == |
| 170 | Следующие пункты детально описывают каждый тип ссылки, а также несколько примечаний, представляющих применение ссылок. |
| 171 | |
| 172 | === attachment: ссылки (Файл-приложение/аттачмент) === |
| 173 | Синтаксис для аттачментов: |
| 174 | * !attachment:the_file.txt создает ссылку на аттачмент the_file.txt для текущего объекта |
| 175 | * !attachment:wiki:MyPage:the_file.txt создает ссылку на аттачмент the_file.txt для Wiki-статьи !MyPage |
| 176 | * !attachment:ticket:753:the_file.txt создает ссылку на аттачмент the_file.txt для тикета 753 |
| 177 | |
| 178 | === query: ссылки === |
| 179 | |
| 180 | См. TracQuery#UsingTracLinks ([TranslationRu/TracQuery#ИспользованиеTracЗапросов]) и [#ticket:links]. |
| 181 | |
| 182 | === search: ссылки === |
| 183 | |
| 184 | См. TracSearch#SearchLinks ([TranslationRu/TracSearch#СсылкиНаРезультатыПоиска]) |
| 185 | |
| 186 | === ticket: ссылки === |
| 187 | Кроме очевидной формы `ticket:id`, можно указать список тикетов или даже диапазон вместо номера `id`. Такая запись генерирует гиперссылку на запрос с перечнем указанных тикетов. |
| 188 | |
| 189 | Примеры: |
| 190 | - `ticket:5000-6000` |
| 191 | - `ticket:1,150` |
| 192 | |
| 193 | ''(Появилось в Trac 0.11)'' |
| 194 | |
| 195 | === timeline: ссылки === |
| 196 | |
| 197 | Для задания ссылки на ленту времени нужно указать дату в формате ISO:8601. Дополнительно к дате может быть уточнено и время. Время предполагается UTC (Универсальное координированное время), однако можете указать и свое местное время, с часовым поясом, если не хотите вычислять UTC-время. |
| 198 | |
| 199 | Примеры: |
| 200 | - `timeline:2008-01-29` |
| 201 | - `timeline:2008-01-29T15:48` |
| 202 | - `timeline:2008-01-29T16:48Z+01` |
| 203 | |
| 204 | ''(Появилось в Trac 0.11)'' |
| 205 | |
| 206 | === wiki: ссылки === |
| 207 | |
| 208 | См. WikiPageNames ([translationRu/WikiPageNames]) и [#УпотреблениеПробеловВTracСсылках Употребление пробелов в Trac-ссылках]. |
| 209 | |
| 210 | === Cсылки на систему контроля версий === |
| 211 | ==== source: ссылки (Ссылки на исходные коды из хранилища) ==== |
| 212 | По умолчанию ссылки source:/some/path открывают браузер репозитория, если путь указывает на каталог. Иначе открывается просмотр истории изменений файла. Есть возможность ссылаться прямо на конкретную правку (ревизию) файла: |
| 213 | |
| 214 | - source:/some/file@123 — ссылка на правку 123 |
| 215 | - source:/some/file@head — сразу на крайнюю правку файла |
| 216 | |
| 217 | Если указан номер правки, можно даже указать конкретный номер строки: |
| 218 | - `source:/some/file@123#L10` |
| 219 | - `source:/tag/0.10@head#L10` |
| 220 | |
| 221 | Наконец, можно также выделить произвольный набор строк: |
| 222 | - `source:/some/file@123:10-20,100,103#L99` - подсветка строк с 10 по 20, и отдельно строк 100 и 103. |
| 223 | |
| 224 | ''(Появилось в 0.11)'' |
| 225 | |
| 226 | ==== export: ссылки ==== |
| 227 | |
| 228 | Для принудительной загрузки файла из репозитория вместо отображения его в браузере по умолчанию, используйте ссылку вида `export`. |
| 229 | Доступны несколько форм записи: |
| 230 | * `export:/some/file` - получить HEAD правку (крайнюю) указанного файла |
| 231 | * `export:123:/some/file` - получить правку № 123 указанного файла |
| 232 | * `export:/some/file@123` - получить правку № 123 указанного файла |
| 233 | |
| 234 | Это может быть очень полезным для отображения HTML документации с корректными стилями страниц и изображений, в случае, если были помещены в репозиторий. |
| 235 | |
| 236 | Если путь к директории хранилища включает конкретный файл, окно браузера репозитория будет отображать директорию (подобно результату `source:/some/dir`). |
| 237 | |
| 238 | ==== log: ссылки ==== |
| 239 | |
| 240 | `log:` ссылки используются для отображения конкретных элементов правок. В своей самой простой форме, это ссылки на крайнюю правку, заданную путем, но также может отображать произвольный набор правок. |
| 241 | |
| 242 | - `log:/` - Полный лог изменений, по всему дереву хранилища (/ - root), начиная с крайней правки HEAD и раньше |
| 243 | - `log:/trunk/tools` - Полный лог изменений `trunk/tools`, начиная с крайней правки HEAD и раньше |
| 244 | - `log:/trunk/tools@10000` - Изменения `trunk/tools`, вошедшие в правки, начиная с № 10000 и более старые |
| 245 | - `log:@20788,20791:20795` - Правки хранилища 20788 и диапазон правок с 20791 до 20795 |
| 246 | - `log:/trunk/tools@20788,20791:20795` - Изменения `trunk/tools`, вошедшие в правку 20788 и правки с 20791 по 20795. |
| 247 | |
| 248 | Есть также и короткая форма для указания ревизий: |
| 249 | - `[20788,20791:20795]` |
| 250 | - `[20788,20791:20795/trunk/tools]` |
| 251 | - `r20791:20795` (но не `r20788,20791:20795`и не `r20791:20795/trunk`) |
| 252 | |
| 253 | Наконец, заметьте, что во всех вышеуказанных примерах диапазоны правок могут указываться с одинаковым успехом как `x:y` так и `x-y`. |
| 254 | |
| 255 | |
| 256 | ---- |
| 257 | См. также: WikiFormatting, TracWiki, WikiPageNames, InterTrac, InterWiki |
| 258 | |
| 259 | (russian): TracTermsRu? |