Работа над документацией GIMP

Главная Форумы Локализация Официальная документация Работа над документацией GIMP

В этой теме 13 ответов, 4 участника, последнее обновление  prokoudine 1 год, 11 мес. назад.

Просмотр 14 сообщений - с 1 по 14 (из 14 всего)
  • Автор
    Сообщения
  • #756

    prokoudine
    Хранитель

    Пользовательская документация в 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.

    #1017

    coyote
    Участник

    Поздравляю с открытием!
    и обидно однако что нигде в доке не указаны переводчики документации с прошлой реинкарнации gimp.ru

    #1018

    prokoudine
    Хранитель

    После переезда на новую инфраструктуру много чего покоцалось. Если мне ткнут пальцем, куда именно и кого добавить, я добавлю :)

    #1019

    Portnov
    Участник

    Доки переводить в *.po… как-то печально. Неужели на эту тему ничего умнее не изобретено?

    #1020

    coyote
    Участник

    prokoudine написал:
    После переезда на новую инфраструктуру много чего покоцалось. Если мне ткнут пальцем, куда именно и кого добавить, я добавлю :)

    не знаю имен, может объявятся если захотят =)

    #1021

    prokoudine
    Хранитель

    @portnov Почему печально? Это самый простой способ найти изменения в оригинале.

    @coyote К сожалению, вики на gimp.org, где мы раньше отмечались, кто и что делает, уже давно недоступно. Попробую на досуге через archive.org поискать.

    #1022

    coyote
    Участник

    prokoudine написал:
    @coyote К сожалению, вики на gimp.org, где мы раньше отмечались, кто и что делает, уже давно недоступно. Попробую на досуге через archive.org поискать.

    нашел кто делал самый первый перевод https://developer.berlios.de/project/memberlist.php?group_id=3391

    #1023

    Portnov
    Участник

    @prokoudine
    Просто gettext задуман никак не для перевода док. Выглядит такое его использование несколько странно. Хотя, конечно, если работает — то ладно…

    #1024

    prokoudine
    Хранитель

    @coyote А ведь и правда — Роксана когда-то заводила там проект. Вот же ж время летит.

    @portnov Я боюсь, что очень сложно найти вариант, который всех устроит. Даже у вики как наиболее общедоступного варианта есть просто уйма недочётов.

    #1025

    coyote
    Участник

    prokoudine написал:А ведь и правда — Роксана когда-то заводила там проект. Вот же ж время летит.

    Ужос, самому страшно =)

    Portnov написал:
    Просто gettext задуман никак не для перевода док. Выглядит такое его использование несколько странно. Хотя, конечно, если работает — то ладно…

    Да вполне удобно, попробуйте =))

    #1062

    prokoudine
    Хранитель

    Итого в авторах теперь значатся:

    Роксана Черноголова, 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., я теперь уже не расшифрую. Поправки по фамилиям и годам принимаются, естественно. Кроме того, начиная с Олега нет адресов электропочты (имеющиеся я тут не стал указывать, потому что спамеры не дремлют).

    #1063

    coyote
    Участник

    спасибо :)

    #3686

    22lab
    Участник

    Существуют и будут ли тут выкладываться сборки руководств в PDF c уроками по основным задачам для обычных пользователей по работе с программой?

    #3688

    prokoudine
    Хранитель

    Здравствуйте, более новые сборки в PDF выложим, но сначала нужно доработать перевод.

Просмотр 14 сообщений - с 1 по 14 (из 14 всего)

Для ответа в этой теме необходимо авторизоваться.