Оформление

Обязательные требования к оформлению документов:

• Документы должны создаваться в формате DocBook/XML актуальной версии (в данный момент используется версия 4.2);

• Документы должны соответствовать правилам XML и указанного DTD, проверить это можно командой

  xmllint --noout --noent --xinclude --postvalid file.xml

  В CVS эту команду выполняет цель check (make check). Указанные аргументы отключают вывод содержимого документа, заменяют сущности (entities) их значениями, включают обработку включений (XML Inclusions), и после всего этого проверяют валидность документа;

• Должны быть заполнены теги author (автор), revhistory (список ревизий, в каждой должны быть номер, дата и описание), abstract (аннотация). Дату желательно указывать на английском языке, пометив тег date атрибутом lang="en";

• Крайне желательно использовать теги section вместо sect1, sect2 и т.д. — это упрощает изменения документа;

• В корневом теге документа должен быть указан атрибут lang, указывающий язык документа. Для русского языка это lang="ru";

• При написании документов нужно использовать букву ё, её замена на е недопустима;

• Если в создании документа принимал участие кто-либо кроме автора (например, оформитель документа в DocBook), должен быть заполнен тег othercredit с описанием участия;

• Для часто повторяющихся конструкций или терминов нужно использовать сущности (entities);

• Документы могут создаваться в любой кодировке, поддерживаемой стандартом XML, при этом нужно указывать «официальное» название кодировки. Например, windows-1251, а не cp1251;

• В документах нельзя использовать символы, которых нет в стандарте языка XML, например, кавычки-ёлочки, длинное тире и т.д., пользуйтесь определениями символов (character entities) для их указания. Например, нужно указывать сущность — для указания длинного тире ( — );

• В документах не должно быть явного форматирования, например, выделений текста символами кавычек или знаков < — пользуйтесь соответствующими тегами, например, для кавычек тегом quote, для указания тега достаточно просто sgmltag;

• Желательно следить за тем, чтобы в теги попадали те слова, которые к эти тегам относятся, например, не нужно писать внутри тегов точку (в конце предложения);

• В заголовках статей и разделов точки в конце ставить не нужно;

• В списках в конце перечислений нужно ставить точку с запятой;