16 Вывод

<!-- Category: top-level-element -->
<xsl:output
  method = "xml" | "html" | "text" | qname-but-not-ncname
  version = nmtoken
  encoding = string
  omit-xml-declaration = "yes" | "no"
  standalone = "yes" | "no"
  doctype-public = string
  doctype-system = string
  cdata-section-elements = qnames
  indent = "yes" | "no"
  media-type = string />

XSLT процессор может выводить конечное дерево в виде последовательности байтов, хотя и не обязан иметь такую возможность (см. [17 Соответствие спецификации]). Элемент xsl:output позволяет авторам стилей указывать, каким они хотят видеть конечное дерево при выводе. Если XSLT процессор выводит на печать конечное дерево, он должен делать это так, как задано элементом xsl:output, однако сам вывод процессор выполнять не обязан.

Элемент xsl:output можно использовать только как элемент верхнего уровня.

Атрибут method в xsl:output идентифицирует общий метод, который должен использоваться для вывода конечного дерева. Значением атрибута должно быть QName. Если QName не имеет префикса, то оно идентифицирует метод, описываемый данным документом, и должно соответствовать одному из трех названий: xml, html или text. Если QName имеет префикс, то такое QName приводится к расширенному имени, как описано в главе [2.4 Полные имена]. Расширенное имя идентифицирует метод вывода. Поведение в этом случае данный документ не описывает.

По умолчанию атрибут method выбирается следующим образом. Если

• корневой узел конечного дерева имеет элемент непосредственным потомком,

• расширенное имя первого элемента в конечном дереве, который является непосредственным потомком корневого узла (например, элемент документа) имеет локальную часть html (в любом сочетании верхних и нижних регистров) и нулевой URI пространства имен,

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

то тогда методом вывода по умолчанию является html. В противном случае таковым является xml. Метод вывода по умолчанию должен быть использован если нет элементов xsl:output, либо ни один элемент xsl:output не определяет значения атрибута method.

Остальные атрибуты в xsl:output определяют параметры для метода вывода. Разрешается использовать следующие атрибуты:

• version указывает версию метода вывода

• indent указывает, может ли XSLT процессор ставить дополнительные пробелы при выводе конечного дерева, атрибут должен иметь значение yes или no

• encoding указывает предпочтительную кодировку символов, которую XSLT процессор должен использовать чтобы представить последовательность символов в виде последовательности байтов. Значение атрибута должно обрабатываться независимо от используемого регистра. Значение атрибута должно состоять из символов из диапазона от #x21 до #x7E (т.е. печатных ASCII символов). Значением должно быть либо charset, зарегистрированный Internet Assigned Numbers Authority [IANA], [RFC2278], либо строка начинающаяся с X-

• media-type определяет тип среды (тип контента MIME) для данных, полученных при выводе конечного дерева. Параметр charset не должен указываться явно. Наоборот, параметр charset должен добавляется когда типом среды на верхнем уровне является text, причем в соответствии с той кодировкой символов, которая реально используется данным методом вывода

• doctype-system указывает системный идентификатор, который должен использоваться в декларации типа документа

• doctype-public указывает публичный идентификатор, который должен использоваться в декларации типа документа

• omit-xml-declaration указывает, должен ли XSLT процессор выводить декларацию XML, значением атрибута должно быть yes или no

• standalone указывает, должен ли XSLT процессор выводить декларацию одиночного документа. Значением атрибута должно быть yes или no

• cdata-section-elements определяет перечень названий элементов, чьи непосредственные потомки, являющиеся текстовыми узлами, должны печататься с помощью блоков CDATA

Детальная семантика каждого атрибута будет описана отдельно для каждого метода вывода, в котором он используется. Если семантика атрибута для метода вывода не описана, использовать ее для этого метода нельзя.

Стиль может содержать несколько элементов xsl:output, а также может включить или импортировать другие стили, также содержащие элементы xsl:output. Все элементы xsl:output, обнаруженные в стиле, объединяются в один эффективный элемент xsl:output. Для атрибута cdata-section-elements эффективное значение является объединением всех указанных значений. Для остальных атрибутов эффективным является значение, указанное с наивысшим приоритетом импорта. Если таких значений для атрибута было несколько, фиксируется ошибка. XSLT процессор может фиксировать такую ошибку. Если он этого не делает, то должен обрабатывать ошибку сам, используя то значение, которое в стиле было обнаружено последним. Значения атрибутов берутся по умолчанию после того, как были объединены элементы xsl:output, разные методы вывода по умолчанию могут иметь различные значения атрибута.

16.1 Метод вывода XML

Метод вывода xml выводит конечное дерево как корректную внешнюю общую разобранную сущность XML. Если корневой узел конечного дерева имеет непосредственным потомком только один узел элемента и не имеет непосредственными потомками текстовые узлы, то эта сущность также должна быть корректной сущностью документа XML. Если на сущность ссылается простой упаковщик XML документа, такой как

<!DOCTYPE doc [
<!ENTITY e SYSTEM "entity-URI">
]>
<doc>&e;</doc>

где entity-URI - URI данной сущности, то документ упаковщика в целом должен быть корректным XML документом, отвечающим требованиям Рекомендации для Пространства имен XML [XML Names]. Кроме того, вывод должен быть таким, чтобы если путем разбора этого упаковщика как XML документа построить новое дерево как было описано в главе [3 Модель данных], а затем изъять элемент документа и поставить его непосредственного потомка вместо непосредственного потомка корневого узла, то новое дерево будет таким же как конечное дерево за следующими возможными исключениями:

• В двух деревьях может отличаться порядок следования атрибутов.

• Новое дерево может содержать узлы пространства имен, которые не были представлены в конечном дереве.

  Замечание: В ходе вывода конечного дерева как XML XSLT процессору может потребоваться добавить декларации пространства имен.

Если XSLT процессор генерирует декларацию типа документа на основании атрибута doctype-system, то приведенные выше требования относятся и к сущности, в которой изъята сгенерированная декларация типа документа.

Атрибут version указывает версию XML, которая должна использоваться для вывода конечного дерева. Если XSLT процессор не поддерживает указанную версию XML, должна использоваться та версия XML, которую он поддерживает. Версия вывода в декларации XML (если декларация XML выводится) должна соответствовать той версии XML, которую процессор использует для вывода конечного дерева. Значение атрибута version должно соответствовать сценарию VersionNum из Рекомендации XML [XML]. Значение по умолчанию - 1.0.

Атрибут encoding указывает предпочтительную кодировку, которая должна использоваться при выводе конечного дерева. XSLT процессоры должны поддерживать значения UTF-8 и UTF-16. Для других значений, если XSLT процессор не поддерживает соответствующую кодировку, он должен фиксировать ошибку. Если же он этого не делает, то вместо указанной кодировки должен использовать UTF-8 или UTF-16. XSLT процессор не должен пользоваться кодировкой, название которой не соответствует сценарию EncName из Рекомендации XML [XML]. Если атрибут encoding не указан, XSLT процессор должен использовать UTF-8 или UTF-16. Есть вероятность, что в конечном дереве обнаружится символ, который нельзя представить в кодировке, которую XSLT процессор использует для вывода. В таком случае, если данный символ был обнаружен в контексте, где XML распознает ссылки на символы (то есть, в значении узла атрибута или узла текста), то этот символ следует представить в виде ссылки на символ. В противном случае (например, если символ был обнаружен в названии элемента) XSLT процессор должен фиксировать ошибку.

Если атрибут indent имеет значение yes, то метод вывода xml в дополнение к пробельным символам в конечном дереве может показывать собственные пробельные символы (возможно потому, что пробельные символы будут удалены из исходного документа или из стиля) с тем, чтобы получить более красивый результат. Если атрибут indent имеет значение no, какие-либо дополнительные пробельные символы появляться не должны. Значением атрибута по умолчанию является no. Для размещения дополнительных пробельных символов метод вывода xml должен использовать такой алгоритм, который гарантирует, что когда пробельные символы изъяты из вывода с помощью процедуры, описанной в главе [3.4 Удаление пробельных символов], а список элементов, сохраняющих пробельные символы, ограничивается лишь xsl:text, результат будет таким же, как если дополнительные пробельные символы не использовались.

Замечание: Для тех типов документов, которые содержат элементы со смешанным содержимым, использовать indent="yes" обычно небезопасно.

Атрибут cdata-section-elements содержит список QName (разделенных пробельными символами). Каждый QName приводится к расширенному имени с помощью деклараций пространства имен, в области действия которых находится элемент xsl:output с данным QName. Если имеется пространство имен по умолчанию, то оно используется для тех QName, которые своего префикса не имеют. Расширение выполняется до того, как несколько элементов xsl:output будут объединены в один эффективный элемент xsl:output. Если членом данного переченя является расширенное имя родителя текстового узла, то сам текстовый узел должен быть представлен в виде блока CDATA. Например,

<xsl:output cdata-section-elements="example"/>

приведет к тому, что фиксированный конечный элемент, записанный в стиле как

<example>&lt;foo></example>

или

<example><![CDATA[<foo>]]></example>

будет представлен как

<example><![CDATA[<foo>]]></example>

Если текстовый узел содержит последовательность символов ]]>, то текущий открытый блок CDATA будет закрыт сразу после ]], а перед > будет открыт новый блок CDATA. Например, фиксированный конечный элемент, записанный в стиле как

<example>]]&gt;</example>

будет представлен в виде

<example><![CDATA[]]]]><![CDATA[>]]></example>

Если текстовый узел содержит символ, который невозможно представить в той кодировке символов, которая используется для вывода конечного дерева, перед таким символом текущий открытый блок CDATA должен быть закрыт, сам символ должен быть представлен как ссылка на символ или сущность, затем должен быть открыт новый блок CDATA для остальных символов в текстовом узле.

Блоки CDATA не должны использоваться за исключением тех текстовых узлов, где атрибут cdata-section-elements явно требует вывода с помощью блоков CDATA.

Метод вывода xml должен предоставить декларацию XML, если атрибут omit-xml-declaration не имеет значения yes. Декларация XML должна содержать и информацию о версии, и декларацию кодировки. Если указан атрибут standalone, то должна быть включена декларация одиночного документа с тем же значением, какое было у атрибута standalone. В противном случае декларация одиночного документа быть не должно. Тем самым гарантируется, что будут присутствовать и декларация XML (допустимая в начале сущности документа) и декларация текста (допустимая в начале внешней общей разобранной сущности).

Если указан атрибут doctype-system, метод вывода xml должен ставить декларацию типа документа непосредственно перед первым элементом. Имя, следующее за <!DOCTYPE, должно быть названием этого первого элемента. Если к тому же указан атрибут doctype-public, то метод вывода xml за PUBLIC должен сперва поставить публичный идентификатор, а затем системный идентификатор. В противном случае, за SYSTEM должен следовать системный идентификатор. Внутренний набор декларации должен быть пуст. Если атрибут doctype-system не указан, атрибут doctype-public следует игнорировать.

Для метода вывода xml можно использовать атрибут media-type. Значением по умолчанию для атрибута media-type является text/xml.

16.2 Метод вывода HTML

Метод вывода html представляет конечное дерево в виде HTML. Например,

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="html"/> 
 <xsl:template match="/">
  <html>
   <xsl:apply-templates/>
  </html>
</xsl:template>

...

</xsl:stylesheet>

Атрибут version показывает версию HTML. Значением по умолчанию является 4.0, означающее, что результат должен быть выведен как HTML документ, отвечающий Рекомендации HTML 4.0 [HTML].

Метод вывода html не должен представлять элемент, иначе чем метод xml, если расширенное имя этого элемента имеет ненулевой URI пространства имен. Элемент, чье расширенное имя имеет ненулевой URI пространства имен, должен быть представлен как XML. Если расширенное имя элемента имеет нулевой URI пространства имен, но локальная часть этого имени как название элемента HTML не распознается, этот элемент должен быть представлен как непустой встроенный элемент, такой как span.

Метод вывода html для пустых элементов не должен показывать конечный тэг. В HTML 4.0 пустыми элементами являются area, base, basefont, br, col, frame, hr, img, input, isindex, link, meta и param. Например, элемент, указанный в стиле как <br/> или <br></br>, должен быть представлен как <br>.

Метод вывода html должен распознавать названия HTML элементов независимо от регистра. Например, все элементы с названиями br, BR и Br должны распознаваться как HTML элемент br и показываться без закрывающего тэга.

Метод вывода html не должен выполнять маскирование содержимого элементов script и style. Например, фиксированный конечный элемент, записанный в стиле как

<script>if (a &lt; b) foo()</script>

или

<script><![CDATA[if (a < b) foo()]]></script>

должен быть представлен как

<script>if (a < b) foo()</script>

Метод вывода html не должен маскировать символы <, встретившиеся в значении атрибутов.

Если атрибут indent имеет значение yes, то метод вывода html, показывая конечное дерево, может добавлять или, наоборот, удалять пробельные символы ровно до тех пор, пока это не влияет на то, как HTML-агент пользователя будет отображать результат вывода. По умолчанию атрибут имеет значение yes.

В значении атрибутов URI метод вывода html должен маскировать символы, не относящиеся к набору ASCII, используя метод, рекомендованный в главе B.2.1 Рекомендации HTML 4.0.

Метод вывода html может показать любой символ, воспользовавшись ссылкой на сущность символа, если таковая определена в той версии HTML, которую использует данный метод вывода.

Инструкции обработки метод вывода html должен завершать символом >, а не комбинацией ?>.

Булевы атрибуты (то есть, такие атрибуты, которым разрешено иметь только одно значение - название самого атрибута) метод вывода html должен показывать в минимизированной форме. Например, начальный тэг, записанный в стиле как

<OPTION selected="selected">

должен быть представлен в виде

<OPTION selected>

В значении атрибута метод вывода html не должен маскировать символ &, сразу за которым следует символ { (см. главу B.7.1 в Рекомендации HTML 4.0). Например, начальный тэг, записанный в стиле как

<BODY bgcolor='&amp;{{randomrbg}};'>

должен быть представлен в виде

<BODY bgcolor='&{randomrbg};'>

Атрибут encoding указывает, какая должна использоваться предпочтительная кодировка. Если имеется элемент HEAD, то метод вывода html сразу после начального элемента HEAD должен добавить элемент META, указывающий реально используемую кодировку символов. Например,

<HEAD> 
<META http-equiv="Content-Type" content="text/html; charset=EUC-JP">
...

Может оказаться, что конечное дерево содержит символ, который невозможно представить в той кодировке, которую XSLT процессор использует для вывода. В этом случае, если символ встретился в таком контексте, где HTML распознает ссылки на символы, то этот символ должен быть представлен ссылкой на сущность символа или десятичной числовой ссылкой на символ. В противном случае (например, в элементе script, style или в комментарии), XSLT процессор должен фиксировать ошибку.

Если указаны атрибуты doctype-public или doctype-system, метод вывода html непосредственно перед первым элементом должен представить декларацию типа документа. Именем, следующим за <!DOCTYPE, должно быть HTML или html. Если указан атрибут doctype-public, метод вывода должен представить PUBLIC, за которым следует указанный публичный идентификатор. Если дополнительно указан атрибут doctype-system, то перед публичным идентификатором должен быть показан указанный системный идентификатор. Если указан атрибут doctype-system, но не было атрибута doctype-public, метод вывода должен представить SYSTEM, за которым следует указанный системный идентификатор.

Для метода вывода html можно использовать атрибут media-type. По умолчанию подразумевается значение text/html.

16.3 Метод вывода Text

Метод вывода text представляет конечное дерево, показывая строковое значение каждого текстового узла в конечном дереве, причем в том порядке, как они следуют в документе, и без какого-либо маскирования.

Для метода вывода text можно использовать атрибут media-type. Значением по умолчанию для атрибута media-type является text/plain.

Атрибут encoding указывает кодировку, которую метод вывода text должен использовать для преобразования последовательностей символов в последовательности байтов. Значение по умолчанию для этого атрибута зависит от системы. Если в конечном дереве есть символ, который невозможно представить в той кодировке, которую XSLT процессор использует для вывода, XSLT процессор должен фиксировать ошибку.

16.4 Запрет маскирования при выводе

Обычно метод вывода xml, представляя текстовые узлы, маскирует & и < (а также, возможно, и другие символы). Тем самым обеспечивается вывод корректного XML документа. Иногда однако бывает удобно иметь возможность показывать почти, но не совсем корректный документ XML. Например, вывод может содержать некорректные разделы, которые будут преобразованы в корректный XML последующей процедурой, не связанной с XML. По этой причине XSLT предоставляет механизм запрета маскирования при выводе. Элементы xsl:value-of или xsl:text могут содержать атрибут disable-output-escaping, который может иметь значения yes или no. По умолчанию подразумевается значение no. Если значение атрибута yes, текстовый узел, полученный обработкой элемента xsl:value-of или xsl:text, должен быть представлен без маскирования. Например,

<xsl:text disable-output-escaping="yes">&lt;</xsl:text>

должен сгенерировать единственный символ <.

Если маскирование при выводе было запрещено для текстового узла, который используется где-либо еще кроме текстового узла в конечном дереве, фиксируется ошибка. Таким образом, будет ошибкой запретить маскирование для элемента xsl:value-of или xsl:text, который используется для получения строкового значения к комментарию, инструкции обработки или узлу атрибута. Ошибкой будет также преобразование фрагмента конечного дерева в число или строку, если в этом фрагменте содержится текстовый узел, для которого было запрещено маскирование. В обоих случаях XSLT процессор может фиксировать ошибку. Если он этого не делает, то должен обработать ошибку сам, игнорируя атрибут disable-output-escaping.

Атрибут disable-output-escaping можно использовать и для метода вывода html, и для метода вывода xml. Метод вывода text игнорирует атрибут disable-output-escaping, поскольку при выводе не делает какого-либо маскирования.

XSLT процессор сможет запретить маскирование только если он контролирует, как будет представлено конечное дерево. А так может быть не всегда. Например, вместо показа конечное дерево может быть использовано как исходное дерево для другой XSLT трансформации. Маскирование при выводе XSLT процессор поддерживать не обязан. Если xsl:value-of или xsl:text указывают, что маскирование при выводе должно быть запрещено, а XSLT процессор такого режима не поддерживает, то процессор может фиксировать ошибку. Если же он этого не делает, то должен обработать ошибку сам, не отменяя маскирование при выводе.

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

Поскольку запрет на маскирование при выводе может работать не на всех XSLT процессорах и может создавать XML документы, которые будут некорректны, то этот режим должен использоваться только тогда, когда нет других альтернатив.

Назад | Содержание | Вперед