Аннотация
Управление ревизиями - это наиболее интересная функция Borges'а. Она позволяет отслеживать документы в двух направлениях:
Статус модуля (Раздел 4.1, «Жизненный цикл модуля»). Каждая независимая часть документа, называемая «модулем», имеет свой собственный жизненный цикл в Borges. Управление гранулированными модулями обеспечивает стандарты качества, позволяя создавать вам аккуратную информацию для слежения за проектом.
Актуальность перевода (Раздел 4.2, «Межязыковая синхронизация модуля»). Перевод документа имеет с этим нечто общее. Обновление переводов для постоянно изменяющегося оригинала часто напоминает ночной кошмар. Благодаря передовой системе, предоставляемой Borges'ом, существует возможность знать о любых переводах, нуждающихся в обновлении, и где именно находятся изменения. Эта система также гарантирует, что структура документа соблюдается во всех его переводах, позволяя в то же время переводчикам делать добавления с сохранением оригинальной структуры.
Благодаря этим утилитам, могут создаваться иерархические отчёты, предоставляющие всем существенную информацию слежения за проектом: менеджерам проектов, а также авторам модулей, переводчикам, участникам и др.
В дополнение к ревизиям модулей необходимо работать с ревизиями всего документа (например, когда выпускается новая версия документируемого продукта).
Модуль рождается, когда на него впервые делается ссылка в мастер-документе. Он достигает своей зрелости, когда для него заканчивается финальное языковое чтение корректуры. Между этими двумя этапами необходимо, чтобы модуль прошёл через каждое их следующих состояний[3]:
Написан. Когда редактор завершил написание оригинального модуля.
Переведён. Когда переводчик завершил перевод оригинального модуля на свой язык.
Техническое чтение корректуры. Когда технический эксперт прочитал модуль, и были учтены его замечания.
Педагогическое чтение корректуры. Когда специалист по образованию прочитал модуль, и были учтены его замечания.
Проверка орфографии. Когда модуль успешно прошёл проверку орфографии.
Языковое чтение корректуры. Когда квалифицированный носитель языка прочитал модуль, и были учтены его замечания.
После того, как модуль достиг своего последнего этапа, он считается законченным и готовым к публикации. Ниже представлена диаграмма, которая лучше демонстрирует процесс работы над оригинальным модулем и одним из его переводов.
Эта схема является иллюстрацией к информации, содержащейся в Раздел 1.1.5, «conf/repository.xml» и требует некоторого пояснения:
Как только оригинальный модуль проходит состояние презентационного чтения корректуры, в нём (пере)назначаются все автоматические ID, а также все его переводы. При этом автоматическая нумерация ID сбрасывается при переходе с одного релиза на другой.
После принятия решения об изменении старшего релиза больше не нужны состояния написания и перевода, потому что они должны быть выполнены только один раз. Вместо этого они заменяются этапами «Обновление» и «Синхронизация».
Этап «Синхронизация» может быть повторно активирован даже после того, как оригинал прошёл состояние «Презентационное чтение корректуры». Это позволяет обновляться переводам относительно оригинала, если впоследствии он будет изменяться. Этот процесс изображён на диаграмме пунктирными стрелками. См. Раздел 4.2, «Межязыковая синхронизация модуля». Обратите внимание, что этапы, следующие после перевода (проверка орфографии и языковое чтение корректуры), повторно не активируются, если они уже были выполнены.
Замечание
Это описание стандартного рабочего процесса, предлагаемого по умолчанию Borges'ом. Имеется возможность задать свой рабочий процесс, определив его в Раздел 1.1.5, «conf/repository.xml».
История модуля хранится в скрытом файле и не должна изменться вручную. Для этой цели существуют цели make, которые позаботятся обо всех задачах, связанных со статусом модуля.
Вот синтаксис команды, которая выполняет работу, связанную с заданием:
make <имя-модуля>.revision TYPE=<тип>
где <тип> является одним из следующих типов в соответствии с этапами, описанными выше:
Давайте представим, что вы только что изменили модуль intro-section.xml согласно замечаниям, сделанным педагогическим корректором. Команда, выполняемая в каталоге с файлом:
make intro-section.revision TYPE=pproof
Чтобы получить полную отдачу от возможностей Borges, рекомендуется, чтобы вы назначили все задачи на всех языках для всех модулей. Это гарантирует, что без присмотра не останется ни одной задачи, повышая тем самым эффективность проекта.
Эта операция выполняется сделующей командой:
make <имя-модуля>.revision TYPE=<тип>.todo AUTHOR=<ai>
где <ai> - инициалы автора, отвечающего за эту операцию. Например, если автор pp отвечает за языковое чтение корректуры модуля intro-section на испанском, вы должны выполнить:
make -C modules/es/ intro-section.revision TYPE=pproof.todo AUTHOR=pp
Чтобы обеспечить актуальность переводов относительно их оригиналов, необходимо отслеживать их изменения. Для отслеживания изменений в тексте, вообще говоря, существует только один метод: создание различий между двумя версиями. Однако он имеет один большой недостаток: когда изменения не являются значимыми для переводчика (написание и синтаксические изменения в противоположность смысловым изменениям), последний должен извлекать нужные крупицы из моря несущественной информации.
Для обеспечения чёткого выделения значимых изменений требуется участие человека. Поэтому изменение редактором значения параграфа должно чётко отразиться на этом параграфе путём увеличения соответствующего атрибута с ревизией. При этом система сможет выделить атомы в устаревшем переведённом модуле и известить об этом переводчика.
Вся система целиком зависит от воли авторов. Если они добросовестно добавляют ревизии, всё будет прекрасно. Опыт показывает, что несложно предупредить авторов о проблеме, чтобы затем всё работало идеально.
Когда модуль покидает этап pproof, он становится готовым для перевода. Затем система автоматически добавляет ID всем доступным атомам[4] в этом модуле. Давайте рассмотрим отдельный параграф в модуле passwords:
После того, как модуль прошёл этап pproof, наш параграф получил автоматический ID:
<para> <screen> root# head -c 6 /dev/urandom | mimencode</screen> При этом на консоль будут выведены пять случайных символов, пригодных для генерации пароля. Вы можете найти <command>mimencode</command> в пакете <filename>metamailer</filename>.</para>
Несмотря на техническое чтение корректуры, читатель заметил ошибку: должно быть прочитано шесть случайных символов, а не пять. Затем вы исправили ошибку и добавили ID ревизии:
<para revision="1"> <screen> root# head -c 6 /dev/urandom | mimencode</screen> При этом на консоль будут выведены шесть случайных символов, пригодных для генерации пароля. Вы можете найти <command>mimencode</command> в пакете <filename>metamailer</filename>.</para>
Позже вы обнаружили, что в имени пакета сделана ошибка - это не metamailer, а metamail. Даже хотя элемент filename не является атомом по умолчанию, вы можете присвоить ему ID и атрибут ревизии:
<para revision="1"> <screen> root# head -c 6 /dev/urandom | mimencode</screen> При этом на консоль будут выведены шесть случайных символов, пригодных для генерации пароля. Вы можете найти <command>mimencode</command> в пакете <filename revision="1">metamail</filename>.</para>
Это лучше, чем увеличивать ревизию параграфа до 2, т.к. переводчик непосредственно отметил изменение в элементе filename без необходимости поиска по всему параграфу.
Подсказка
Если вы хотите помочь переводчикам обнаружить небольшое изменение в большом куске текста, лучше заключить изменённое предложение в элемент phrase, добавив в этот уменьшенный элемент ID и ревизию...
Внимание
Часто случается так, что автор вынужден изменить структуру модуля, даже если он уже был переведён. В этом случае становится необходимым присвоить ID всем возможным новым элементам. Автор может назначить их вручную (позаботившись о том, чтобы ID не повторялись) или оставить системе переназначение всех ID в модуле, если было сделано слишком много изменений. Это делается при помощи следующей команды:
make <имя-модуля>.id
Понятно, что эта команда должна быть выполнена также и для переведённых модулей...
Аннотация
Мы будем говорить здесь скорее не о создании отчётов, а о том, как их читать и что делать с содержащейся в них информацей.
Всякий раз, когда переведённый модуль становится устаревшим относительно оригинала, соответствующая ячейка в таблице с отчётом по супердокументу становится красной (Рисунок 3.2, «Получение отчёта по супердокументу»). Если вы щёлкните по ячейке, вы получите подробный отчёт по модулю (Рисунок 3.3, «Образец отчёта по модулю»).
В этом отчёте под таблицей с историей ревизий находятся две ссылки:
Рисунок 3.4, «Изменения в ID/ревизиях»: отмечает атомы, отмечающие разницу между переводом и его оригиналом;
Рисунок 3.5, «Несинхронизированные элементы бок о бок»: представляет оригинальные и переведённые атомы, выводимые в виде синхронизаций бок о бок.
В этой таблице явным образом показываются атомы, изменённые в оригинале. Автор знает, что был изменён элемент с ID passwords-pa2 и был добавлен новый элемент metamail-pack.
Через эту страницу переводчик может открыть файл modules/fr/passwords.xml, найти элемент passwords-pa2 и синхронизировать его содержимое согласно тексту в HTML-отчёте. Естественно, также должны быть скопированы новый ID и атрибуты ревизии, чтобы система узнала о том, что атом был обновлён.
Когда выпускается новая версия программы или продукта, сопровождающая его документация также претерпевает большие изменения. В этом случае Borges предлагает функцию старшего релиза документов, позволяя вам перезапустить производственный цикл для существующих модулей.
Когда вы создавали свои документы, вы назначали им начальный номер релиза (см. Раздел 3.2.4, «Вставка нового документа»). Затем были выполнены все задачи по связанным модулям, и им был присвоен этот номер релиза. При увеличении номера релиза проекта будет создан новый набор заданий для каждого модуля этого проекта уже с новым номером релиза.
Всё это выполняется одной единственной командой:
make release REL=2.0
Замечание
Если присутствует много модулей и языков, этот процесс может занять длительное время.
Рекомендуется одновременно изменять номер релиза для всех документов одного проекта. В противном случае, если два документа с двумя разными номерами релизов используют один и тот же модуль, это приведёт к конфликту при создании отчётов. Тем не менее, если вы предпочитаете управлять раздельными номерами релизов документов, вы можете сделать это при помощи следующей команды:
make -C manuals/My_Manual/ release REL=2.0
Ниже представлена диаграмма, показывающая два разных HTML-отчёта, сгенерированных Borges'ом, и навигацию по ним.
Теперь мы рассмотрим, как создать каждый из этих отчётов, и как их читать.
Внимание
Чтобы отчёты были корректно сгенерированы, необходимо, чтобы были верными все исходные тексты на всех языках.
Создание этого отчёта на самом деле создаёт все другие отчёты, таким образом становится возможным просмотреть их, начиная со страницы с отчётом по всему проекту. Вам нужно просто выполнить следующую команду (в каталоге reports/ своего проекта):
make all
При этом будет создан файл index.html и вы должны просто открыть его в своём браузере. В качестве примера такого отчёта взгляните на Полный отчёт по руководствам Borges.
Полученная в результате страница сама прекрасно документирована, поэтому здесь мы её рассматривать не будем. Однако вы можете заметить, что в процессе копиляции также генерируются все черновые варианты супердокументов (см. «Ссылки на скомпилированные версии руководств»). Если вы хотите только сгенерировать отчёты без документов, выполните:
make index.html
Если вы хотите сгенерировать отчёт только по супердокументу (и все зависимые отчёты), выполните:
make master-report.html
в каталоге супердокумента (напр. в manuals/My_Doc/). Затем вы можете открыть в своём любимом браузере файл master-report.html. В качестве примера такого отчёта взгляните на Подробный отчёт о состоянии Borges-doc.
Таблица в этом отчёте содержит по одной строке на один модуль соответствующего супердокумента. Как минимум существуют три колонки:
Три возможных варианта содержимого этой ячейки:
Текущая задача для этого модуля на соответствующем для этой колонки языке. Если известен человек, отвечающий за эту задачу, он показывается в круглых скобках.
Если задача на данный момент не доступна, показывается текст «Pending».
«OK» означает, что для этого модуля выполнены все необходимые задачи.
Если ячейка с красным фоном, это означает, что этот перевод устарел по отношению к оригинальному модулю. См. Раздел 4.2.3, «Как переводчики синхронизируют модули».
Щелчок по тексту в этой ячейке покажет вам соответствующий Раздел 4.4.3, «Отчёт по модулю».
Нет необходимости создавать отчёт для одного отдельно взятого модуля, отчёты по всем модулям, имеющим отношение к супердокументу, генерируются при создании отчёта по супердокументу. Эта страница содержит простую историю ревизий модуля плюс возможные ссылки на более подробные отчёты diff, в случае если этот модуль не синхронизирован (см. Раздел 4.2.3, «Как переводчики синхронизируют модули»).
Когда переводчик обновляет модуль, он может быть заинтересован в быстром повторном создании отчёта по ID, чтобы проверить, всё ли в порядке. Для этого выполните команду:
make <имя-модуля>.ids.html LANG=<xx> manual=<супердокумент>
Например, чтобы получить отчёт по ID для модуля passwords на французском, являющегося частью супердокумента Borges-doc, вам нужно перейти в каталог modules/fr/ и выполнить:
make passwords.ids.html LANG=fr manual=Borges-doc
Затем просто откройте в своём браузере файл passwords.ids.html.