====================
Общий стиль перевода
====================

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

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

Непереводимые фрагменты необходимо воспроизводить в точности так же, как
в оригинале (например, использовать длинные названия команд: "checkout",
а не "co").

Используйте букву "ё" там, где это необходимо.


=======================
Руководство по разметке
=======================

- В работе с книгой используется Docbook Lite DTD от O'Reilly &
  Associates. Копия DTD имеется в хранилище и также доступна по адресу
  ftp://ftp.oreilly.com/pub/dblite/.

- Перед публикацией *всегда* следует выполнять проверку правильности
  разметки xml. Не следует помещать в хранилище файл, не проходящий
  такую проверку. Подробнее см. файл README.

- Фрагменты, содержащие вывод на экране и программный код, не должны
  использовать строки длиннее, чем 78 символов. В качестве символа
  продолжения строки следует использовать обратную косую черту ('\').

- Используйте — а не дефис, где это необходимо.

- Если в DTD имеется сущность, определённая для обозначения того или
  иного специального символа, используйте сущность, а не символ
  напрямую, например — вместо --.

- В разметке следует использовать правильные отступы (2 символа), за
  исключением блоков <screen></screen>, которые выравниваются по левому
  краю. Текстовые узлы должны начинаться непосредственно после
  открывающего тэга и заканчиваться закрывающим тэгом, без лишних
  переносов строк. Например:

<chapter id="svn-ch-pi">
<title>Tips</title>

  <!-- ================================================================= -->
  <!-- ======================== SECTION 1 ============================== -->
  <!-- ================================================================= -->
  <sect1 id="svn-ch-pi-sect-1">
    <title>Flornthorple Plathering</title>

    <para>The real key to <firstterm>Plathering</firstterm> is to start with
       a good glab. A good glab provides a solid thorpy foundation.</para>

    <sect2 id="svn-ch-pi-sect-1.1">
      <title>Cross-blather</title>

      <para>Cross-blather tends to create a hoopy pile of crandy. You
        can avoid this by using the cross-blather avoid
        command.</para>

      <screen>
$ cb-avoid
Avoiding blather......... Done
$
</screen> <!-- Note the closing tag at the left-most column? -->

    </sect2>

  </sect1>

</chapter>

============================================
Отслеживание изменений в оригинальном тексте
============================================

- Для отслеживания изменений в оригинальном (английском) тексте книги мы
  применяем метод разработанный норвежским переводчиком Ойвином Хольмом
  [Øyvind A. Holm <sunny@sunbase.org>]. "Норвежский метод" использует
  принцип реализованный в Subversion для внесения изменений. Собственно
  говоря, ничего нового в сам механизм слияния Subversion не привнесла, так
  как для отражения изменений использует единый формат записи различий
  (unified diff). Смотри: http://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html#Detailed%20Unified

  При внесении изменений в целевой файл на основении diff-файлов алгоритм
  ищет место, куда изменения были внесены. Зная о том что алгоритм
  руководствуется он номерами строк И несколькими (обычно хватает трех)
  неизмененными строками до и после блока измененных строк "викинги" этим
  воспользовались.

  Полагаясь на приципом "Ничего не удалять, только добавлять." при переводе
  они стараются как можно меньше влиять на оригинальный текст, что бы не
  сбивать с толку алгоритм наложения изменений. Так как книга оформлена при
  помощи языка DocBook (облегченная версия используемая издательством
  O'Reilly), а следовательно это XML, добавление в код сток вида
===
<!-- @ENGLISH {{{
@ENGLISH }}} -->
===
  позволяет исключить оригинальный текст из последующей обработки не удаляя
  его физически. Если кто не понял, то это слегка модифицированные теги
  блока комментариев испольуемые в XML. Сразу за блоком "закомментаренного"
  оригинала следует его перевод. При этом, все использемые в оригинале теги
  DocBook используются и в переводе.

  Обратите внимание, на два важных правила:
  1) Oбрамляемый тегами комментариев текст не должен нарушать "правильность
     XML". То есть с точки зрения правил XML, файл должен оставаться
     "wellformed".
  2) Чем больше строк оригинального текста будет обрамлено за раз, тем
     проще будет жизнь у алгоритма наложения изменений! Так что,
     НЕ МЕЛЬЧИТЕ когда делаете перевод!

  BTW, в оригинальном тексте могут встречаться последовательности из двух
  дефисов вида
===
--
===
  В большинстве случаев, они возникают при описании параметров передаваемых
  программе командной строки. Вот пример:
===
        <varlistentry>
          <term><option>--auto-props</option></term>
          <listitem>
            <para>Enables auto-props, overriding the
              <literal>enable-auto-props</literal> directive in the
              <filename>config</filename> file.</para>
          </listitem>
        </varlistentry>
===
  В таком случае, для выполнения первого правила, приходится идти на
  хитрости. Хитростей бывают двух видов: норвежская и наша.

  "Варяги" разрывают последовательность двух дефисов Unicode-сущностью:
===
&#64738;
===
  мотивируя это тем, что этот символ находиться в "private use" Unicode
  area. Смотри: http://www.unicode.org/charts/PDF/UE000.pdf

  Наша хитрость того же плана, но в качестве "разделителя" используется
  вот такая последовательность:
===
-><!-
===
  Будучи вставленной между уже существующими в оригинальном тексте
  дефисами, она образует открывающий и закрывающий тег комментариев.

======
Разное
======

- Всё, что требует внимания, или должно быть исправлено, должно быть
  помечено с помощью ###TODO, чтобы такие места можно было легко найти.
  Кроме того, не стесняйтесь добавлять своё имя в комментариях, чтобы
  можно было вести обсуждение непосредственно в коде.


$Id$
vim: set tw=72 nowrap et sw=2 ts=2 sts=2 fo+=2w fenc=utf8 :