Как работать над страницами веб-сайта Debian

Общая информация

Требования к ресурсам

Если вы хотите работать над нашим веб-сайтом, будьте готовы сохранить по меньшей мере 250 МБ данных на диск. Это число отражает текущий размер архива исходного кода. Если вы (случайно) запустите пересборку всех страниц, то вам потребуется как минимум вдвое больше свободного места на диске. Если вы выполните частичное извлечение, вам потребуется намного меньше места, например для каталога english/ требуется примерно 50 МБ.

Частичное извлечение

Многие не хотят иметь всё CVS дерево webwml целиком на своей машине, что иногда приводит к сломанным сборкам и потере файлов, например в случае когда добавляется какой-то критичный файл, но полное обновление (cvs update) в этого каталога не производится. Проверяйте наличие всех требуемых файлов (таких как .wmlrc) до того, как пожаловаться нам на проблемы.

Что это за строчки, начинающиеся с `#'?

В WML строка, начинающаяся с `#' является комментарием. Такие комментарии предпочтительны перед обычными комментариями HTML, поскольку они не добавляются в сгенерированную страницу.

Пожалуйста, для получения дополнительной информации по использованию WML прочтите страницу использование WML.

Этикет редакторов

Могу ли я изменить эту страницу?

И да, и нет. Если вы нашли маленькую ошибку (например, опечатку), просто исправьте её.

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

Если вы находите что-то ужасным и требующим переделки, сообщите об этом в рассылку debian-www, чтобы мы могли это обсудить. Скорее всего мы с вами согласимся.

Если вы обнаружили проблему в шаблоне (т.е., в файле из каталога webwml/english/template/debian), пожалуйста, сначала внимательно оцените изменение, а уже потом вносите его, поскольку изменения шаблонов часто вызывает пересборку большой части сайта.

Добавляя новый каталог, добавляйте также Makefile!

При добавлении новых каталогов в CVS, следует быть внимательным. Если текущий каталог включён в список в файле ../Makefile, то вы должны создать Makefile в нём — в противном случае make выдаст сообщение об ошибке.

Используйте ясный и простой английский

Поскольку веб-страницы Debian читаются не только носителями английского языка и переводятся на другие языки, предпочтительнее писать ясно и на простом английском, избегая использование сленга, смайлов и непонятных идиом.

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

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

Поиск README

Некоторые каталоги содержат файл README, помогающий понять то, как организован этот каталог. Файлы README должны содержать любую специальную информацию, которая требуется для работы в этом каталоге.

Отделение изменений в содержании от изменений в форматировании

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

В общем случае избегайте случайных изменений форматирования. Изменение старых частей XHTML/XML-совместимых страниц не должно быть произведено в одном и том же исправлении с другими изменениями (новое с самого начала может и должно быть добавлено корректно).

Обновляйте переводы, если это возможно

Некоторые изменения не зависят от языка, используемого в файле WML, например изменения URL или встроенного кода Perl. Исправление опечаток также попадает в эту категорию, так как переводчики зачастую игнорируют их во время перевода. Благодаря таким независящим от языка изменениям, вы можете произвести одно и то же изменение во всех переведённых файлах, не зная других языков, и увеличить версию файла в заголовках translation-check.

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

Кроме того, чтобы убедиться, что эти изменения легко применить, вы можете использовать сценарий smart_change.pl из корневого каталога CVS-модуля webwml.

Использование smart_change.pl

smart_change.pl [параметры] оригинальный_файл

В настоящее время в качестве оригинального_файла разрешены только файлы из каталога /english/. smart_change.pl принимает следующие аргументы:

-s, --substitute=REGEXP
Определяет регулярное выражение Perl, применяемое к файлам с исходным кодом (может использоваться несколько раз). Например:
	  $> ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml
	  $> cvs diff -u */devel/index.wml | less
	  $> cvs ci -m "1.23: Updated oldurl to current location" */devel/index.wml
	
Первая команда производит изменение, вторая команда служит для проверки оригинального файла на английском языке и каждого перевода этого файла. Вам следует делать это для того, чтобы проверить действительные изменения до внесения изменений. Если всё выглядит так, как вы и ожидали, внесите ваши изменения при помощи третьей команды.
-l, --lang=STRING
Обработать этот язык (может использоваться несколько раз). Если язык не определён, будут обработаны все доступные языки.
-n, --no-bump
Не увеличивать версии в заголовках translation-check. Обычно, версия в каждом заголовке translation-check в актуальных переведённых файлах увеличивается на единицу, и остаётся нетронутой в тех файлах, которые не актуальны. Если используется этот параметр, ни один заголовок translation-check не будет изменён. Смотрите страницу поддержание переводов в актуальном состоянии или страницу объяснение заголовков translation-check.
-p, --previous
Показать предыдущее изменение CVS. Это полезно, когда изменения в файл на английском языке уже были внесены, а вы хотите проверить заголовки translation-check относительно предыдущей версии.
-h, --help
Отобразить краткую информацию об использовании.
-v, --verbose
Отображать подробные сообщения во время работы.

Ссылки

Эта ссылка не кажется мне правильной. Должен ли я изменить её?

Из-за того, как настроены веб-серверы (с использованием согласования содержания), вам не следует менять какие-либо внутренние ссылки. В действительности, мы советуем этого не делать. Если вам кажется, что ссылка некорректна, то перед тем как изменить её, напишите в рассылку debian-www.

Исправление ссылок

Если вы обнаружили ссылку на внешний веб-сайт, которая ведёт на перенаправление (301, 302, <meta> перенаправление или страница сообщает Эта страница переехала.) сообщите об этом в рассылку debian-www.

Если вы обнаружили сломанную ссылку (404, 403 или ссылка ведёт не на ту страницу, которая предполагается ссылкой), исправьте её и сообщите в рассылку debian-www об этом, чтобы переводчики знали о вашем изменении. Ещё лучше исправить ссылку во всех переводах и обновить заголовки translation-check, если это возможно.

Отделение текста от данных

Что это за файлы foo.def и foo.data?

Чтобы упростить процесс актуализации переводов, на некоторых страницах мы отделяем общие части (данные) от текстовых частей (текста). Переводчикам нужно скопировать и перевести текстовые части таких страниц, общие части будут добавлены автоматически.

Понять это поможет пример. В создании страницы со списком продавцов участвуют несколько файлов из каталога CD/vendors:

index.wml:
Текст верхней части страницы продавцов находится в этом файле. Переведённая копия этого файла должна быть помещена в каждый языковой каталог.
vendors.CD.def:
Этот файл содержит все части текста, которые требуются для каждого пункта в списке продавцов. Переводы добавляются в <язык>/po/vendors.xy.po.
vendors.CD:
Этот файл содержит действительные пункты списка продавцов, которые не зависят от языка, поэтому переводчику не нужно трогать этот файл.

Когда один из людей из группы cdvendors@debian.org добавляет нового продавца, они добавляют его в файл debiancd.db, конвертируют файл в формат WML как vendors.CD (используя getvendors.pl), и затем позволяют WML и сценариям make делать свою работу. Все переводы перестраиваются, используя существующий переведённый текст, но с данными о новом продавце. (Обновленный перевод без усилий!)

Добавление новой страницы

Добавить новые страницы на сайт Debian очень просто. Вся работа по корректировке заголовка и нижнего колонтитула производится с использованием WML. Всё, что вам нужно сделать, это добавить строку в верхнюю часть нового файла на подобие следующей:

#use wml::debian::template title="НАЗВАНИЕ СТРАНИЦЫ"

за которой следует тело с содержимым. Все страницы должны использовать файл шаблона wml::debian::template, если они не используют какой-то конкретный шаблон, созданный специально для этого раздела, например для раздела новостей или раздела безопасности.

Имеющиеся шаблоны позволяют определять переменные, которые будут изменять созданные страницы. Это позволяет избегать создания разных шаблонов для каждой ситуации и облегчает внесение изменений. В настоящее время доступны следующие переменные (указаны и их цели):

BARETITLE="true"
Удаляет часть "Debian --", которая обычно ставится перед всеми тегами <title>.
NOHEADER="true"
Удаляет изначальный заголовок со страницы. Изменённый заголовок может, конечно, быть включён в тело с содержимым.
NOMIRRORS="true"
Удаляет выпадающий список зеркал со страницы. Обычно не рекомендуется использовать это за исключением нескольких страниц.
NOHOMELINK="true"
Удаляет ссылку на главную страницу Debian, которая обычно помещается в нижней части страницы.
NOLANGUAGES="true"
Удаляет ссылки на версии на других языках, которые обычно помещаются в нижней части страницы.
GEN_TIME="true"
Устанавливает дату получившихся файлов в значение timestamp создаваемых файлов, а не timestamp исходных файлов.
NOCOPYRIGHT="true"
Удаляет сообщение о копирайте в нижней части страницы.

Заметьте, что вы можете использовать любую строку в качестве значения этих переменных: true, yes, foo, выбор не имеет значения.

Примером использования этого являются страницы переносов на другие архитектуры, которые имеют свои собственные заголовки. В ports/arm/index.wml используется следующее:

#use wml::debian::template title="Перенос ARM" NOHEADER="yes"

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

Если вы создаёте страницу, которая генерируется при помощи сценария или имеет мало текста, попробуйте использовать теги <gettext>, чтобы облегчить задачу поддержания переводов в актуальном состоянии.

Добавление других файлов

Если вы хотите выделить некоторые части вашей страницы в специальный файл (который затем будет включён в ваш главный файл), используйте расширение .src, если содержание вашего файла должно быть переведено, поскольку так изменения в вашем добавляемом файле будут отслеживаться так же как и в обычном файле .wml. Если вы используете какое-либо другое расширение, например .inc, переводчики не будут узнавать о ваших обновлениях, и страницы на разных языках могут иметь разное содержание.

Добавление нового каталога

Внимание: не создавайте каталог с именем install. Это сбивает с толку make, и страницы в этом каталоге не будут обновляться автоматически.

Внизу приведён аннотированный пример добавления нового каталога на веб-сайт.

   mkdir foo
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

Отредактируйте Makefile в родительском каталоге и добавьте каталог, который вы только что создали в переменную SUBS. Это действие добавит ваш каталог для сборки, когда будет выполнена команда make.

Наконец, внесите все сделанные изменения в репозиторий при помощи команды

  cvs commit Makefile foo