Работа над документацией GIMP
This topic contains 13 replies, has 4 voices, and was last updated by 
-
Posts
-
Пользовательская документация в GIMP является отдельным проектом, и у неё своя команда авторов. Все данные точно так же хранятся в репозитории Git, поэтому если вы хотите работать над ней, лучше всего пользоваться Linux или хотя бы Mac, поскольку в Windows вам гарантированы приключения, мало что общего имеющие с работой над документацией. В дальнейшем будем считать, что у вас установлен Linux.
Работа с Git
Если Git ещё не установлен, найдите его в менеджере пакетов вашего дистрибутива и установите. К примеру, в Ubuntu нужный пакет называется git-core. Существует не меньше полудюжины графических интерфейсов к Git. Нужны ли они вам — решайте сами.
Буквально пару слов о самой Git и системах контроля версий.
Системы контроля версия (VCS) нужны для совместной работы участников одной команды. Они позволяют хранить на сервере некоторые данные (исходный код, документацию, файлы с графикой и т.д.) таким образом, что в любой момент можно перейти к более ранней редакции файла, сделанной тем или иным участником команды.
У разных систем контроля версий разный подход к созданию версий. Одни (CVS) опираются на даты изменения, другие (SVN) просто назначают новый последовательный номер. VCS также позволяют создавать ответвления основного дерева, что позволяет работать над некоторыми изменениями, не трогая основное дерево.
Но практически везде действует общий основный принцип: новый файл сначала формально добавляется в репозиторий, и только потом непосредственно отправляется. Первая команда называется add, вторая — commit.
Git является распределённой системой контроля версий, т.е. если в централизованных системах свои ветки вы можете создавать только на сервере, в Git вы можете создавать их локально, на своём компьютере. Например, если вы надумали вносить очень много изменений в перевод или оригинал на английском, пока кто-то ещё активно работает с основной ветке, доступной всем, вы можете создать локальное ответвление (branch), пополняя изменениями из основной ветки, а по завершении своей работы влить изменения в основную ветку.
Поскольку Git предоставляет достаточно большую свободу в локальной работе над проектом, первоначальное скачивание данных называется клонированием репозитория.
Документация к GIMP, как и сам исходный код GIMP, хранится на сервере GNOME.
Если у вас есть учётная запись на сервере GNOME (её можно запросить), но для этого вам обычно нужно быть переводчиком или разработчиком одного из приложений), вы можете вносить изменения в основное дерево самостоятельно. Если учётной записи нет, вы можете склонировать репозиторий анонимно и просто отправлять файлы с изменениями одному из участников, имеющих доступ на запись в репозиторий. Например, мне :)
В последнем случае команда для клонирования репозитория выглядит так:
$ git clone git://git.gnome.org/gimp-help-2
Для обновления склонированного репозитория текущими данными с сервера выполняется команда
$ git pull –rebase
Если вы успели внести изменения, Git пожалуется, что один из файлов изменён. Существует несколько вариантов дальнейших действий:
1. Самый простой способ — запомнить изменения и повторно применить их после обновления клона
Запоминаем:
$ git stash
Обновляем клон:
$ git pull –rebase
Повторно применяем изменения:
$ git stash apply
Продолжаем работать.
2. Чуть более сложный и замороченный вариант — зафиксировать изменения в локальной копии с последующим созданием патча.
Фиксируем изменения:
$ git commit изменённый_файл -m “Комментарий к изменению на английском языке” –author “Имя Фамилия < адрес@почты>“
Создаём патч:
$ git format-patch origin/master
Результатом будем файл 0001-Текст-вашего-комментария.patch, содержащий внесённые в файл изменения. Набор таких файлов потом можно отправить координатору (мне). Замороченность этого варианта состоит в том, что координатору придётся применять несколько патчей и читать каждый их них отдельно, при том, что несколько патчей могут затрагивать изменения одного и того же файла.
Вместо указания файла можно поставить ключ -a, но при работе над документацией делать это не рекомендуется. Вы скоро поймёте, почему. Зато можно перечислить несколько файлов:
$ git commit изменённый_файл ещё_один_изменённый_файл -m “Комментарий к изменению на английском языке” –author “Имя Фамилия < адрес@почты>“
Именно так лучше всего формировать свои изменения перед отправкой их координатору перевода. Впрочем, можно отправить и файл PO целиком. Только не забудьте предварительно сжать его архиватором.
Как устроена документация
Предположим, вы только что склонировали репозиторий с документаций Git и теперь пытаетесь понять, что же вы такое склонировали.
Вся пользовательская документация GIMP пишется в Docbook/XML. Это позволяет при необходимости получать документацию в самых разных форматах — HTML, PDF, OpenDocument и так далее. Собственно текст хранится в каталоге src. Иллюстрации — в каталоге images.
Docbook/XML допускает создание модульных документов, т.е. документов, которые могут целиком состоять их других документов. Это возможность широко используется в документации GIMP, поэтому исходные файлы обычно очень маленькие. Тем не менее, при сборке HTML, PDF и файлов перевода всё равно создаются более крупные документы.
Для упрощения работы переводчиков вся работа ведётся над файлами PO. Изначально этот формат использовался для локализации приложений, но общий принцип оказался достаточно пригодным и для документации.
Суть формата PO вкратце можно свести к следующему. Это текстовый формат, содержащий заголовок со служебной информацией (дата последнего изменения, автор последнего изменения, язык перевода, кодировка текста) и последовательностью записей, каждая из которых выглядит примерно так:
#: src/key-reference.xml:9(refentrytitle)
#: src/key-reference.xml:12(refname)
#: src/key-reference.xml:18(title)
#: src/key-reference.xml:23(para)
msgid “Help”
msgstr “Справка”Файлы PO создаются из Docbook/XML путём выделения абзацев в записи, причём для удобства такие элементы разметки как
(тег абзаца) опускаются. У каждой записи может быть статус «переведена», «не переведена» и «изменилась». Так что если в оригинале изменился весь абзац, вам не нужно искать изменения глазами. Достаточно просто обновить файл PO, найти ближайшую запись со статусом “изменилась” (fuzzy) и обновить текст. Для удобного редактирования PO написано несколько приложений. Наиболее распространённые — poEdit (также работает в Windows), GTranslator (GNOME), Lokalize (KDE).
Обновление файлов PO с переводом по текущей версии документации на английском выполняется вручную из консоли, равно как и прочие действия. Перед тем, как что либо пытаться сделать, необходимо телодвижение в виде
$ ./autogen.sh
Эта команда создаст Makefile — файл, содержащий различные команды, позволяющие собирать документацию в разные форматы и обновлять файлы переводов.
Для обновления файлов переводов на русский язык введите команду
$ make po-ru
Вслед за этим среда сборки сама создаст из XML файлы шаблонов перевода (POT), а затем по этим шаблонам обновит существующие файлы с переводами.
Вносимые изменения лучше всего с некоторой периодичностью проверять на версии в HTML.
Для этого просто время от времени пересобирайте документацию:
$ make html-ru
На это уходит пара-тройка минут.
Сборка в PDF
Сборка в PDF выполняется при помощи dblatex (просто найдите этот пакет и установите его). Для переводов, где содержатся буквы помимо букв латинского алфавита, она пока не отлажена. Действующий способ всей книги таков:
$ dblatex -b xetex xml/ru/gimp.xml
Требует установленного пакета XeTeX.
Вместо xml/ru/gimp.xml можно указать другой файл, но тогда в полученном файле PDF не будет иллюстраций.
Порядок работы в команде
Перед тем как взяться за перевод, убедитесь, что над никто не работает. Чтобы коллизий не возникало, настоятельно прошу писать о своих планах. Это особенно важно потому, что некоторые файлы PO содержат перевод более чем одной главы (using.po, concepts.po).
В файлах PO обычно (не всегда) есть запись “translators-credits”, в которую при внесении изменений в перевод нужно добавить свою фамилию, адрес и год внесения изменения, например:
Владимир Ульянов
, 1917 Если в этой записи уже есть один или несколько переводчиков, в конце строки последнего из них вставьте n, нажмите клавишу ввода и с новой строки укажите себя, например:
Николай II
, 1917n
Владимир Ульянов, 1917 Патчи, создаваемые описанным выше способом (предпочтительный вариант), или просто изменённые файлы PO (не очень хороший, но приемлемый вариант), отправляются текущему координатору русской локализации Александру Прокудину (alexandre.prokoudine@gmail.com). Их также можно прикреплять к комментариям в форуме, предварительно сжав архиватором в .zip, .gz или .bz2.
Поздравляю с открытием!
и обидно однако что нигде в доке не указаны переводчики документации с прошлой реинкарнации gimp.ruПосле переезда на новую инфраструктуру много чего покоцалось. Если мне ткнут пальцем, куда именно и кого добавить, я добавлю :)
Доки переводить в *.po… как-то печально. Неужели на эту тему ничего умнее не изобретено?
prokoudine написал:
После переезда на новую инфраструктуру много чего покоцалось. Если мне ткнут пальцем, куда именно и кого добавить, я добавлю :)не знаю имен, может объявятся если захотят =)
prokoudine написал:
@coyote К сожалению, вики на gimp.org, где мы раньше отмечались, кто и что делает, уже давно недоступно. Попробую на досуге через archive.org поискать.нашел кто делал самый первый перевод https://developer.berlios.de/project/memberlist.php?group_id=3391
@prokoudine
Просто gettext задуман никак не для перевода док. Выглядит такое его использование несколько странно. Хотя, конечно, если работает – то ладно…prokoudine написал:А ведь и правда — Роксана когда-то заводила там проект. Вот же ж время летит.
Ужос, самому страшно =)
Portnov написал:
Просто gettext задуман никак не для перевода док. Выглядит такое его использование несколько странно. Хотя, конечно, если работает – то ладно…Да вполне удобно, попробуйте =))
Итого в авторах теперь значатся:
Роксана Черноголова, 2005, 2006, 2007
Виталий Ломов, 2006, 2007, 2008
Александр Прокудин, 2005, 2006, 2007, 2008, 2009, 2010
Олег Фритц, 2005, 2006, 2007
Сергей Блищавенко, 2005, 2006
Сергей Терлюк, 2005, 2006
Сергей Кораблин, 2005, 2006
Георгий Вортман, 2005, 2006
Григорий Бакунов, 2005Кто такой Maxim P., я теперь уже не расшифрую. Поправки по фамилиям и годам принимаются, естественно. Кроме того, начиная с Олега нет адресов электропочты (имеющиеся я тут не стал указывать, потому что спамеры не дремлют).
спасибо :)
Существуют и будут ли тут выкладываться сборки руководств в PDF c уроками по основным задачам для обычных пользователей по работе с программой?
Здравствуйте, более новые сборки в PDF выложим, но сначала нужно доработать перевод.
You must be logged in to reply to this topic.