10.1.1. Регистр букв

Метки вводятся в нижнем регистре, <para>, а не <PARA>.

Текст, который появится в контексте SGML, обычно пишется в верхнем регистре, <!ENTITY...> и <!DOCTYPE...>, но не <!entity...> и <!doctype...>.

10.1.2. Акронимы

Акронимы обычно должны расшифровываться при первом появлении в книге, например: "Network Time Protocol (NTP)." После определения акронима, обычно используется только он, (а не термин целиком, если только в данном случае использование полного термина не предпочтительнее). Обычно акронимы определяются только один раз во всей книге. Но если желаете, вы можете определять их в каждой главе.

Первые три раза акроним должен помещаться внутри тегов <acronym>, с атрибутом role, где определен полный термин. Это позволяет создавать ссылку на глоссарий, и выводить полное описание при наведении на термин курсора мыши.

10.1.3. Отступы

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

Открывающие метки увеличивают отступ на 2 пробела. Закрывающие метки в свою очередь уменьшают отступ на 2 пробела. Заменяйте начальные пробелы символами табуляции, насколько это возможно. Не используйте пробелы перед символами табуляции, и не добавляйте дополнительных пробелов в конце строки. Содержимое элементов должно иметь отступ в два пробела, если содержимое превышает по размеру одну строку.

Например, исходный код этого раздела выглядит примерно так:

+--- This is column 0
V
<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Отступы</title>

      <para>Каждый файл начинается с отступа в колонке 0,
    <emphasis>независимо</emphasis> от отступа файла, который может
    включать этот файл.</para>

      <para>Каждая открывающая метка увеличивает отступ на 2 пробела, а каждая
    закрывающая метка уменьшает его на 2 пробела.  Заменяйте начальные
    пробелы символами табуляции, насколько это возможно.  Не используйте
    пробелы перед символами табуляции, и не добавляйте дополнительных
    пробелов в конце строки.  Содержимое элементов должно иметь отступ в
    два пробела, если содержимое превышает по размеру одну строку.</para>

      ...   
    </sect2>
  </sect1>
</chapter>

Если для редактирования файлов вы используете Emacs или XEmacs, то должен быть автоматически загружен sgml-mode, а локальные переменные Emacs в конце каждого файла должны заставить включить эти стили.

Пользователи Vim могут использовать следующие команды для конфигурации:

augroup sgmledit
  autocmd FileType sgml set formatoptions=cq2l " Special formatting options
  autocmd FileType sgml set textwidth=70       " Wrap lines at 70 columns
  autocmd FileType sgml set shiftwidth=2       " Automatically indent
  autocmd FileType sgml set softtabstop=2      " Tab key indents 2 spaces
  autocmd FileType sgml set tabstop=8          " Replace 8 spaces with a tab
  autocmd FileType sgml set autoindent         " Automatic indentation
augroup END

10.1.4. Стиль меток

<article>
  <articleinfo>
    <title>NIS</title>

    <pubdate>Октябрь 1999</pubdate>

    <abstract>
      <para>...
    ...
    ...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

10.1.5. Изменения, затрагивающие только количество пробелов

При коммите изменений не вносите изменения в содержимое одновременно с изменениями в форматировании.

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

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

10.1.6. Непрерываемые пробелы

Старайтесь избегать переводов строк там, где они могут выглядеть некрасиво или делают неудобным отслеживание смысла фразы. Переводы строк зависят от ширины выбранного формата вывода. В частности, чтение HTML документации в текстовом навигаторе может привести к появлению плохо сформатированных абзацев, как например:

Data capacity ranges from 40 MB to 15GB.  Hardware compression ...

Общая сущность &nbsp; запрещает перенос строки между частями относящимися друг к другу. Используйте прерываемые пробелы в подобных случаях:

• между цифрами и величинами:

  57600 bps
  

• между названием программы и номером версии:

  FreeBSD 4.7
  

• между многословными названиями (используйте осторожно, когда применяете это правило к фразам содержащим 3-4 и более слов. Например: ''The FreeBSD Brazilian Portuguese Documentation Project''):

  Sun Microsystems