Материал из Tkabber Wiki

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

Если у вас есть какие-то предложения по оформлению, пожалуйста, свяжитесь либо с Bigote, либо с kostix, либо с lknight.

Для обсуждения работ на вики создана отдельная конференция xmpp:tkabber-wiki@confernce.jabber.ru. Вход на неё — по приглашению, то есть вам сначала надо выловить кого-нибудь из нас.

Итак, приступим.

Содержание

1 Если вы не работали с вики раньше
2 Теперь об оформлении
- 2.1 Для авторов новых статей
- 2.2 Переводчикам

Если вы не работали с вики раньше

Подробная и очень приличная справка по разметке WikiPedia. На той странице есть ссылки на более конкретные темы: "изображения", "как начать новую статью" и прочее. В качестве теоретической базы — идеальное место.
Для создания галерей, однако, удобнее воспользоваться ссылкой на соответствующий раздел MediaWiki, которая сразу показывает правильный пример кода (на wikipedia.org почему-то о галереях сказано вскользь, и работающий код не продемонстрирован, а чтобы вычислить его самому, надо или долго пробовать, или быть семи пядей во лбу ;))
Смотрите также документацию по настройке интерфейса и Мануал пользователя по использованию и настройке справочной системы.

Теперь об оформлении

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

Для авторов новых статей

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

Теперь о стилях.

Применение отбоя пробелом

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

выделения кусков кода:

namespace eval emoteicons { array set emoteicons {}
```
variable lasttext ""
variable lastX
variable lastY
```
}
выделения опций настроек, когда они встречаются в тексте статьи в первый раз:

::jidlink::transport(allowed,dtcp-active)
выделения пути к файлам, когда этот путь:
довольно длинный,
вводится в тексте статьи впервые,
хочется обратить на него особое внимание.

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

Применение HTML

Основные стили разметки уже встроены в вики, так что особой нужды в использовании тэгов HTML нет. Больше того: злоупотребление ими загрязняет исходный текст статей, затрудняет перевод и правку. Тем не менее, в некоторых случаях применение HTML вполне оправдано. Пример — это вот длинное тире (—), которое и должно по идее использоваться вместо популярного нынче дефиса -. Ещё один пример — стрелки → и ← (→ и ←), угловые скобки < и > (< и >), значок акцента ́, ставящийся следом за буквой, над которой хотим поставить ударение.

Если вам нужно оформить пропуск куска кода в примере, используйте спец-символ · — "·" Например:

proc a b {
    puts ouch!

    · · · · ·

    puts text
}

При использовании ссылок знаки препинания, "касающиеся" последнего слова в ссылке, из неё исключаются. Пример: В случае сомнений не забывайте о предварительном просмотре и о '''[[Sandbox|Песочнице]].''' → В случае сомнений не забывайте о предварительном просмотре и о Песочнице.

Применение тэга <tt>

JID авторов патчей, статей и просто хороших людей, а также конференций и прочих ресурсов выделяются с помощью тэга <tt>: xmpp:loginname@jabberserver.org, xmpp:conferencename@conference.jabberserver.org, rss@jabberserver.org. Если непосредственно после JID или ресурса идёт знак препинания, ставить его следует после закрывающего тэга </tt>.
Выделение опций настроек (например, ::jidlink::transport(allowed,dtcp-active)), когда они встречаются в тексте статьи во второй и более раз.

Применение жирного шрифта

В этой вики жирный шрифт используется для:

выделения путей до файлов, о которых идёт речь (например, ~/.tkabber/avatar.gif), когда не стоит нарушать текучесть предложения. При этом постарайтесь построить предложение так, чтобы к этому пути не примешивалась естественная пунктуация. Если же это невозможно, выключайте знаки препинания из выделения.
обозначения пути к какому-либо пункту Настроек Ткаббера или для ориентации в его меню (например, Настройки → File Transfer → Jidlink или Службы → Расширения → Шпионить за присутствием);
выделения ссылок на статьи данной вики (например, "О плагинах читайте эту статью.");
чтобы обратить внимание на какое-либо важное слово;
- обратите внимание, что в случае с выделенным "просто текстом", в отличие от кода или путей, знаки препинания включаются в выделение.
вопросы в ЧаВо — выделяются целиком, вместе со словом "Вопрос".

Применение наклонного шрифта

Наклонный шрифт в нашей вики применяется для выделения довольно длинных кусков текста в общем повествовании (одно предложение или часть сложносочинённого или сложноподчинённого предложения как минимум), то есть в случаях, когда жирный шрифт слишком обращает на себя внимание. В этом случае знаки пунктуации, завершающие выделенный текст, включаются в выделение. Если вам понадобилось акцентировать какое-либо слово в наклонном тексте, допустимо воспользоваться для этого жирным шрифтом. При этом знаки пунктуации, вплотную прилегающие к жирному слову, из выделения жирным включаются, если это обычное слово, и исключается, если это кусок кода или путь до файла: ~/.tkabber/config.tcl. (Понимаю, что на словах это выглядит запутанно — просмотрите код этой страницы, и вы всё поймёте. Или же просто присмотритесь к финальной точке предыдущего предложения — она обычная :)) Постарайтесь не злоупотреблять смешением стилей или близким соседством жирного и наклонного текста.

Если вам требуется выделить курсивом целый абзац или несколько предложений, лучше воспользоваться тэгом <cite>.

Применение CSS

На вики имеется возможность использовать в коде статей стили CSS. Имеющиеся стили можете посмотреть на специальной странице MediaWiki:Monobook.css. Редактировать её могут только админы вики, так что если у вас есть идеи по части оформления текста, для реализации которых нужно править стили, ловите Bigote.

Употребление смайликов в тексте

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

Употребление буквы "Ё"

Несмотря на мнения многих весьма известных людей, что буква "ё" в наше время должна использоваться лишь в случае смысловых неясностей (это рекомендует также и сайт gramota.ru), авторы подавляющего большинства статей этой вики считают, что эта буква незаслуженно обижена, и стараются реабилитировать её всеми доступными средствами, в том числе и с помощью этой вики. Если Вы в силу привычки пишете "е" вместо "ё", ничего страшного — мы потом всё поправим ;) Если же Вы непримиримый противник использования этой буквы в общедоступных для чтения и редактирования текстах, большая просьба сообщить об этом либо в Вашем профиле (Участник:Ваш_ник), либо в странице обсуждения написанной Вами статьи или в комментарии к ней (поле "краткое описание изменений"). Мы люди мирные, и ссориться по этому поводу не собираемся — в конце концов, информация превыше всего. Однако в этом случае просим и Вас не исправлять уже написанные буквы "ё" на "е" в статьях, написанных другими.

Ребята, давайте жить дружно. © Кот Леопольд ;)

Прочие элементы оформления

Вот такие вот "пули" очень удобно отбивают пункты списков.
Нумерованные списки, тоже могут пригодиться (обратите внимание, они могут быть и вложенными, как сейчас).

Подробнее о них читайте в статье о разметке Википедии.

Если нужно поставить ударение над гласной в русском слове, не используйте "эрзац-ударения" — акцентированные западноевропейские гласные (повторюсь, речь не идёт о "законных" случаях, когда употребляется иностранное слово). Для знака ударения в Unicode существует специальный символ U+0301. В коде HTML он записывается как ́ и ставится после "ударяемой" гласной: Тка́ббер → Тка́ббер. Очень подробно о различных символах, которые могут пригодиться при оформлении статей, написано в Википедии.

Если вам требуется вставить "подпись", например, как автора патча, введите в любом месте строки:

~~~ (заменится на [[Участник:Пупкин|Пупкин]])
~~~~ (заменится на [[Участник:Пупкин|Пупкин]] ЧЧ:ММ, число месяц год (MSD))

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

Песочница

Порезвиться с разметкой можно в Песочнице.

Переводчикам

OmegaT

Крайне рекомендую при переводе пользоваться какой-нибудь системой автоматизированного перевода типа OmegaT. Я сам пользуюсь этой программой, и могу сказать, что она очень облегчает работу переводчика (не путать с печально известным Промтом!) Системы CAT (Computer-Assisted Translation) не переводят текст автоматически, они лишь запоминают все переведённые фразы и затем, при полном или частичном совпадении какой-либо фразы оригинала предлагают запомненный перевод, который можно вставить и отредактировать. По-быстрому освоить OmegaT можно за пару вечеров — на сайте, а также в помощи к программе имеется быстрый старт. Да и вообще помощь довольно неплохая. Чтобы не изобретать велосипед, то есть, не создавать всем и каждому свою память перевода (это называется TM — Translation Memory), я буду выкладывать здесь на вики свой архив с TM, который у меня потихоньку накапливается в процессе перевода. В этом архиве, помимо файлов Омеги, имеется ещё скрытый каталог .git, где хранятся старые версии TM (на случай ~~ядерной войны~~ зависаний особо крупных статей). Вы можете воспользоваться неслабыми возможностями git по бэкапу текстовых данных, если установите его себе на компьютер. Теперь пара советов по использованию Омеги.

Я для перевода исходные файлы создаю в текстовом формате в кодировке utf-8, предлагаю так же поступать и вам. В качестве расширения я выбрал .utf8 (если не ошибаюсь, у Омеги уже есть настроенные фильтры для этого расширения, но на всякий случай я сейчас расскажу, как там чего настраивать).
Идите в меню Options → File filters..., выделите элемент Text Files и загляните сначала в Options. Там надо поставить (если не установлено) End Of Lines (могу соврать, у меня интерфейс испанский), тогда Омега будет делить текст на сегменты по предложениям, а не по пустым строчкам.
Нажав ОК, идите теперь в Edit. Там среди фильтров должен иметься один, отвечающий за utf-8. Если его нет, создайте новый по аналогии с имеющимися, только в качестве шаблона напишите *.utf8, ну и обе кодировки поставьте такими же. Можно работать и с Unicode. Тогда создайте новый фильтр с нужным вам расширением, в качестве кодировки укажите utf-16, ну и не забывайте исходным файлам ставить это расширение.
Ещё одна тонкость. При загрузке файлов проекта в окошке можно увидеть кнопку "Import Files From MediaWiki". Это очень удобная кнопка, но, к сожалению, с русскими названиями страниц это не сработает. Вы вводите в поле для URL ссылку на страницу, жмёте ОК, но в список файлов ничего не добавляется, хотя в каталоге source появляется пустой файл с русским именем. Поэтому лучше всего самому создать в sources нужный файл (для гарантии с английским именем и расширением utf8, не забыли?), открыть его в редакторе, открыть в нашей вики нужную статью на редактирование, скопировать весь исходный текст со всем форматированием и вставить его в файл. Теперь, если обновить проект, нажав F5, у вас появится новый файл, и вы можете начать работу.
Не забывайте периодически сохраняться (Ctrl-S) и создавать финальные документы (Ctrl-D) — мало ли что... У меня один раз гаркнулось часа 4 работы (именно работы, и дедлайн поджимал), и с тех пор я умный :) Для того и поставил git и настроил автокоммит в нём с помощью cron каждые 15 минут ;)

Если будут дополнительные вопросы по Омеге, их лучше задать в конфе <xmpp:translate@conference.jabber.ru>.

Для вышеописанных целей создан репозиторий на http://github.com, где и будет храниться весь перевод этой вики.

Перевод на родной язык

Когда вы переводите на родной язык, часто возникает проблема в использовании специфических терминов, относящихся к миру IT. С одной стороны, в русском языке уже давным-давно прижились транслитерации некоторых терминов, такие как "файл", "биндинг", а также адаптированные иностранные слова: "винт", "аська". С другой стороны, для некоторых вещей имеет смысл дать адекватный русский перевод, например, "список контактов" вместо "ростер" (хотя в этом конкретном случае можно поспорить). Какой вариант выбрать — решать вам, но в любом случае пострайтесь не ударяться в крайности. Глупо переводить "binding" как "привязка" — подавляющее большинство читателей вас попросту не поймёт. Но так же глупо транслитерировать какой-то термин только потому, что он иностранный. Часто вполне можно писать в статье по-русски, в самом начале дав исходный термин и расшифровав его. На нашей вики есть специальный раздел — Терминология, где вы можете проконсультироваться относительно непонятных слов, а также дополнить его, если считаете нужным.

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

Перевод на чужой язык

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

Не переводите каламбуры и шутливые фразы, которые мы тут иногда вкрапляем, если вы не уверены, что это прозвучит хорошо и адекватно на другом языке (попробуйте-ка перевести, скажем, на английский связку "Глоссарик — Словарий" ;)). Лучше просто передайте основную идею фразы (в нашем примере не заморачивайтесь и напишите Glossary). В конце концов, народ сюда приходит не за приколами, а в поисках информации. Вот и постарайтесь наиболее точно перевести информационную составляющую статьи. Но конечно же, если вы способны писать с юмором на другом языке (не обязательно переводить существующие шутки, можно придумывать свои), мы будем только "за" :)
Если есть возможность привлечь к вычитке готового перевода носителя языка, не упускайте её, даже если ваш знакомый слабо разбирается в Jabber и вообще далёк от компьютерной темы. В конце концов, код интернационален, но вот в обычном тексте можно наделать ошибок, не только грамматических, что может быть простительно, но и логических — а это хуже.
Вообще не пренебрегайте спелл-чекерами. Это справедливо даже в случае перевода на родной язык ;)
При переводе статей вики также следует помнить о правилах синтаксиса языка назначения. Например, во французском языке все знаки препинания, состоящие из двух элементов (двоеточие, точка с запятой, восклицательный и вопросительный знаки) отделяются от идущего перед ними слова пробелом. Вследствие этого отпадают вопросы по включению этих знаков в выделение жирным шрифтом.
Как следствие из предыдущего пункта, рекомендуем не придерживаться изложенных выше правил оформления, если они идут вразрез со стилистикой другого языка. Привести конкретный пример сложно, но если, допустим, вам кажется, что выделение курсивом смотрится на другом языке плохо (я вот понятия не имею, можно ли выделять курсивом японские иероглифы), придумайте другой способ акцентировать нужный фрагмент текста.

Перевод меню

В нашей вики редактировать меню можно лишь администраторам проекта. Свяжитесь либо с Bigote, либо с Lknight.

Локализация Ткаббера

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

(!) Сделать: Перевести бы её на русский да здесь выложить...)

Обновляем существующие сообщения

Сначала надо установить самую последнюю версию Ткаббера с svn-репозитория.
- Установите, если у вас нет, клиент subversion;
- создайте рабочий каталог, например, ~/tkabber-svn, и перейдите в него cd tkabber-svn;
- затем в терминале наберите
```
svn co https://svn.xmpp.ru/repos/tkabber/trunk .
```
(Сие означает: "получить содержимое транка проекта Ткаббер в текущий каталог".) * Если у вас выскочила ошибка "svn: SSL is not supported", наберите ту же команду, только вместо https напишите http. * В результате описанных заклинаний у вас в рабочем каталоге появится два подкаталога: tkabber и tkabber-plugins — собственно программа и её плагины.
Начинаем работу (в примере даётся итальянский язык, вам надо ставить свой). * cd tkabber

* tclsh ./contrib/extract-translations/extract.tcl . msgs/it.msg >../it.msg

* tclsh ./contrib/extract-translations/extract.tcl . -v msgs/it.msg >../it.msg.1

Файл it.msg содержит непереведённые строки,
файл it.msg.1 — лишние (которые были переведены ранее, но потом были исключены из оригинальной английской версии).
1. Переводим.
Редактор годится любой, лишь бы он корректно работал с UTF-8.
Сначала ознакомьтесь с существующим текстом перевода msgs/it.msg, чтобы знать, как устроен файл, как выглядят строки сообщений.
Вот пример такой строки:
- ::msgcat::mcset it "Select" "Seleziona"
- ::msgcat::mcset — по этому началу вы распознаете сообщение;
- it — язык;
- "Select" — английская версия сообщения;
- "Seleziona" — итальянский перевод.
Что трогать не надо:
- %s — Ткаббер превращает этот дуэт символов в ник собеседника или название комнаты ("Send file to %s" "Invia il file a %s");
- \n — символ перевода строки, \t — табуляции ("\n\tClient: %s" "\n\tProgramma: %s");
- Если строка содержит знак $, удалите или закоменнтируйте её — последовательности вида $foo означают раскрытие переменной в время выполнения программы и их перевод бессмыслен, так как реально переводятся те строки, которые эта переменная будет содержать, и они скорее всего содержатся где-то в других местах файла сообщений.
В начале файла добавьте в комментарии ваше имя и контактную информацию на случай того, если кто-то найдёт в переводе ошибки и захочет вас о них известить.
Завершив перевод, потестируйте его хотя бы на предмет того, запустится ли Ткаббер с этим файлом. Пропишите в конфиге строчку ::msgcat::mclocale it и запустите Ткаббер. Если на старте выскочила ошибка, просмотрите её внимательно, и если она относится к файлу, который вы только что перевели, то скорее всего, вы чего-то там либо не дописали, либо написали лишнего, например, воткнули или стёрли символ кавычек. В сообщении об ошибке обычно говорится, в какой строке файла следует её искать.
Если всё работает нормально, сообщите о проделанной работе авторам программы, лучше всего teo (xmpp:sgolovan@nes.ru) и вышлите ему готовый файл, чтобы проверил всё перед включением обновлённого перевода в транк. Вообще неплохо было бы прежде чем садиться за перевод, проконсультироваться с ним: вдруг уже кто-то этим языком занимается?

Создание новой версии

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

Что ещё переводить?

Кроме файла сообщений ваш_язык.msg неплохо бы создать файл ресурсов BWidget — ваш_язык.rc, если его ещё нет. Говоря простыми словами, в этом файле лежат названия кнопок и прочих элементов интерфейса Ткаббера. В каталоге msgs уже имеются русская и польская версии, которые могут служить в качестве образца для оформления.
Разнообразные плагины тоже имеют свои сообщения. Скачайте с svn-репозитория свежие плагины: svn co http://svn.xmpp.ru/repos/tkabber/trunk/tkabber-plugins tkabber-plugins и посмотрите — в каждом плагине имеется свой каталог msgs. Вперёд и с песней! ;)
В установочном директории Ткаббера есть каталог trans, где находятся сообщения, используемые новым плагином "Remote Control" ("Удалённое управление"). На данный момент является основной (и единственной) русская версия, но надеемся, что в ближайшем будущем файл будет переведён на английский и таким образом станет доступен для перевода на многие другие языки. Формат файла похожий, за исключением начала строки сообщения: ::trans::trset ru

Tkabber Wiki