Использование HTML на веб-страницах Debian

Настоящая страница является черновиком.

Предисловие

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

Некоторые общие советы

Для новых страниц или переводов существует следующий список общих советов:

не используйте длинных строк
Строки в файлах wml и других файлах должны умещаться в окно обычного терминала. Это упрощает редактирование в vi, улучшает поиск и упрощает перевод. Также это важно потому, что разрешать конфликты в длинных строках немного сложнее.
по возможности помещайте теги на отдельные строки
Большинство тегов HTML можно поместить на отдельные строки. Некоторые из таких тегов — <div>, <p>, <table>, <ul>. Для облегчения работы переводчиков следует помещать на отдельные строки все теги, которые можно разместить таким образом. В противном случае переводчики могут случайно удалить теги и забыть восстановить их после перевода.
не используйте пробелы или переносы строк в строчных тегах
Некоторые теги создают символ пробела, если поместить их на отдельные строки. Одним из таких тегов является тег <q> для небольших цитирований и кавычек. Вы можете лишь отделить такие теги только как целую строку вместе с содержимым. Либо в дальнейшем в HTML-странице может появиться пробел между содержимым и тегом. Между словами в этих тегах вы можете вставлять столько переносов строк или пробелов, сколько пожелаете.

Сокращения и акронимы

Для сокращений и акронимов следует использовать HTML-тег <acronym>. Имеется две причины, почему использование тега <abbr> не рекомендуется: Во-первых, не все браузеры поддерживают этот тег. Во-вторых, существуют противоречащие определения того, что такое акроним и что такое сокращение.

Акроним добавляется на страницу следующим синтаксисом: <acronym lang="код языка" title="Полное определение акронима">АКРОНИМ</acronym>. Атрибут title содержит произносимые слова целиком. Если акроним составлен из первых букв слов, эти буквы в атрибуте title должны быть строчным. Атрибут lang нужен только, если акроним или сокращение относится к иностранному языку.

В шаблонах wml содержится набор готовых акронимов, для использования на вашей странице вам нужно добавить строку использования acronyms в файл wml. Например, тег wml для DD (разработчик Debian) — <acronym_DD />.

Цитирование и кавычки

Для разных языков существуют разные правила цитирования и кавычек. Если у вас имеется короткое строчное цитирование, то вам следует использовать тег <q>. Отрисовка содержимого управляется языком CSS. Теги <q> не должны содержать пробелы или символы переноса строк между открывающим или закрывающим тегом и содержимым.

Для более длинных цитирований используется тег <blockquote>. Тег <blockquote> охватывает один или больше параграфов текста, которые помечены <p>. Пожалуйста, не используйте теги <blockquote> для центрирования блока текста, не являющегося цитированием. Блоки цитирования существуют исключительно для цитат и в дальнейшем будут отрисованы специфическим кодом CSS.

В HTML имеется также тег <cite>. Тег <cite> не используется для цитирования самого текста. Он используется для указания источника цитаты. Это может быть имя человека, слова которого цитируются. Тег добавляется в качестве атрибута к тегу <blockquote> как URL.

Названия программ и код

Для названий программ и компьютерного кода существует тег <code>. Браузеры обычно знают об отображении кода и названий программ, но отрисовка также может быть изменена CSS. Использовать вместо этого тега тег <tt> не будет хорошей идеей, поскольку последний ничего не говорит о содержимом.

Примеры вывода компьютера

Для отображения вывода компьютера на экране существует специальный тег <samp>. Если у вас имеется более большой блок вывода компьютера, вам следует также заглянуть в файл CSS, возможно для этого имеется специальный класс.

Ввод с клавиатуры

Если у вас имеются примеры, в которых пользователь должен набрать что-то на клавиатуре, используйте тег <kbd>. См. также главу о переменных о том, как помечать изменяемые части при вводе.

Переменные

Иногда необходимо выделить переменный ввод, например специальный IP-адрес или имя пользователя, который передаётся программе из командной строки. Для такого переменного ввода используется тег <var>.

Заранее отформатированное содержание

Тег <pre> используется только для заранее отформатированного текста. Длина строки, проблемы и другие нюансы будут сохранены. Этот тег не может содержать большинство других тегов HTML.

Изображения

Если нужно добавить изображения на страницу, нет необходимости добавлять неправильный атрибут border=0. Но если это возможно, следует добавить размер изображения и атрибут alt. Размер, если он отсутствует, добавляется wml, но для этого требуется время при компиляции. Атрибут alt должен содержать что-то, что сообщает пользователям, использующим браузер lynx, и слепым людям, что находится на этом изображении.

Ссылки

Если вы хотите в документации поставить ссылку на страницу на https://www.debian.org, то используйте переменные, определённые для каждого языка в файле .wmlrc. Например, URL в теге
<a href="https://www.debian.org/devel/website/htmlediting">htmlediting</a>
следует заменить на переменную DEVEL следующим образом: <a href="$(DEVEL)/website/htmlediting">htmlediting</a>.