Приложение B. Содействие в работе над руководством

Приложение B. Содействие в работе над руководством

Русский перевод: Михаил Сгибнев

Эта информация может оказаться полезной как для профессионалов, так и для начинающих пользователей NetBSD. Так как популярность операционной системы растет, мы заинтересованы в появлении нового материала и улучшении уже существующего.

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

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

Если вы являетесь опытным пользователем, то пожалуйста, рассмотрите возможность написания новой главы или дополнения существующей.

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

Независимо от того, что именно вы хотите делать, свяжитесь с нами, дабы не получилось дублирования работы.

B.1. Перевод руководства

Если вы хотите перевести данное руководство, то, как уже говорилось, свяжитесь с нами по адресу или обратитесь к спискам рассылки . Возможно несколько сценариев:

  • кто-то уже переводит документацию на ваш язык и вы могли бы ему помочь;

  • никто не переводит документацию, но имеется несколько переведенных глав и вы можете продолжить переводить остальные;

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

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

B.1.1. Что необходимо для перевода

Если кратко, то вам необходимо:

  • исходные тексты руководства. Они входят в состав модуля «htdocs», который можно получить с (анонимного) сервера CVS также, как и «src» или «pkgsrc». Описание подробностей содержит Глава 26, Obtaining sources by CVS.

  • текстовый редактор, такой как vi или emacs.

Замечание

Не начинайте работу в формате HTML или каком-либо другом: используемым форматом является XML/DocBook, из него и происходит конвертация в другие форматы.

B.1.2. Работа с файлами в формате XML/DocBook

Работа над переводом руководства не требует знания XML/DocBook, так как в ходе вашей работы вы не изменяете существующее форматирование. Например, для перевода предыдущего абзаца необходимо выполнить:

  1. загрузить английский вариант главы ap-contrib.xml в текстовый редактор.

  2. найти необходимый абзац:

    <note>
     <para>
     don't start working with HTML or other formats:
     it will be very difficult to convert you work
     to SGML/DocBook, the format used by the NetBSD
     guide.
     </para>
    </note>
  3. добавить ваш перевод между тегами, сразу после английской версии. Теперь это выглядит примерно так:

    <note>
     <para>
     don't start working with HTML or other formats:
     it will be very difficult to convert you work
     to SGML/DocBook, the format used by the NetBSD
     guide.
     здесь ваш перевод
     здесь ваш перевод
     здесь ваш перевод
     </para>
    </note>
  4. удалить английский текст между тегами, оставив только перевод.

    <note>
     <para>
     здесь ваш перевод
     здесь ваш перевод
     здесь ваш перевод
     </para>
    </note>

Пожалуйста, при переводе используйте такое же форматирование, как и оригинального текста. Для примера смотрите Раздел B.3, «Шаблон документа XML/DocBook».

Вы, вероятно, столкнетесь с одной проблемой, связанной с начертанием символов национального алфавита (например «è»). Такие символы допускается использовать в документе, но лучше заменять их на XML сущности. Например, «è» запишется как «&egrave;». Конечно, в этом случае текст станет более тяжело читать и усложнится его редактирование, но использование редакторов с развитыми средствами работы с макросами, таких как vi или emacs, облегчит вам работу. Вы можете назначить соответствующим символам макросы, отредактировав файл конфигурации, например .exrc:

map! è &egrave;

Приложение C, С чего начать при работе с XML/DocBook объясняет, как установить необходимое программное обеспечение и сгенерировать файлы в HTML или каком-либо другом формате. Это особенно полезно, если вы хотите проверить правильность своей работы (к примеру, убедиться, что вы случайно не удалили какой-нибудь тег) или посмотреть, на что будет похож конечный результат. Однако в таких действиях нет необходимости при переводе документации. Если вы не хотите устанавливать себе соответствующее программное обеспечение, то вышлите исходный текст на , он будет проверен и конвертирован в соответствующий выходной формат.

B.2. Предоставление нового материала

Если вы хотите послать новый материал, который бы вы хотели увидеть в руководстве, то для этого есть несколько путей. Небольшое исправление проще всего отослать на . Если у Вас большой объем, например глава, то вы можете выбрать один из следующих форматов:

  • XML/DocBook; является предпочтительным форматом. Пожалуйста, получите исходные тексты руководства и используйте их в качестве образца.

  • простой текст; если форматирование документа достаточно простое, то преобразование в формат SGML не обязательно.

  • если у вас действительно отсутствует возможность использовать один из предыдущих форматов, документы могут приниматься и в каком-нибудь другом.

B.3. Шаблон документа XML/DocBook

Для этого руководства я использую стиль форматирования, похожий на программу. Приведем следующий пример:

<chapter id="chap-xxxxx">
 <title>Это заголовок главы</title>

 <para>
 Это текст параграфа. Это текст параграфа.
 Это текст параграфа. Это текст параграфа.
 Это текст параграфа.
 </para>

 <!-- ============================================================= -->

 <sect1>
 <title>Это заголовок раздела sect1</title>

 <para>
  Это текст параграфа. Это текст параграфа.
  Это текст параграфа. Это текст параграфа.
  Это текст параграфа.
 </para>

 <!-- ........................................................... -->

 <sect2>
  <title>Это заголовок раздела sect2</title>

  <para>
	Раздел sect2 размещен внутри раздела sect1.
  </para>
 </sect2>

 </sect1>

 <!-- ============================================================= -->

 <sect1>
 <title>Это еще один раздел sect1</title>

 <para>
  Маркированный список:
  <itemizedlist>
	<listitem>
	 <para>
	 текст
	 </para>
	</listitem>
	<listitem>
	 <para>
	 текст
	 </para>
	</listitem>
  </itemizedlist>
 </para>

 </sect1>
</chapter>

По умолчанию:

  • два пробела между уровнями вложенности

  • длина строк не больше 72 символов.

  • используйте разделительные линии между sect1/sect2.

Обновлено: 16.03.2015