Оформление документов

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

  • Документы должны создаваться в формате DocBook/XML 4.1.2;

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

    xmllint --valid --noout file.xml
                
    Документы, использующие для включения других документов технологию XML Inclusions, можно проверять командой
    xmllint --xinclude --postvalid --noout file.xml
                

  • Должны быть указаны автор, список ревизий, краткое описание изменений в ревизиях, дата;

  • Нужно использовать глобальные определения (ENTITIES), определяя их в начале документа, чтобы не загромождать его повторяющимися конструкциями. Глобальные определения можно легко изменить, если потребуется. Определения находятся в CVS в каталоге $CVSROOT/ent, в файлах с расширением ".ent". Нужно указывать относительный путь к файлу с определениями.

    Пример 3. Включение глобальных определений в документ

    <?xml version="1.0" encoding="cp1251"?>
    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                      "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
    [
    
    <!ENTITY % altent SYSTEM "../../ent/alt.ent">
    %altent;
    
    ]>
                  

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

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

Пожелания к оформлению документов:

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

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

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

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

  • Старайтесь заполнять тег <abstract> кратким описанием содержимого или назначения статьи;



Наш баннер
Вы можете установить наш баннер на своем сайте или блоге, скопировав этот код:
RSS новости