Оформление

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

  • Документы должны создаваться в формате 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;

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

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

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