<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="xml_serializers">
<chapterinfo>
	<copyright>
		<year>2007-2019</year>
		<holder>Colin Adams</holder>
	</copyright>
	<author>
		<firstname>Colin</firstname><surname>Adams</surname>
	</author>
	<email>colin@colina.demon.co.uk</email>
	<date>17 March 2019</date>
</chapterinfo>

<title>XML serializers</title>

<section>
<title>Serializing an <classname>XM_DOCUMENT</classname></title>

<para>
 To serialize an <classname>XM_DOCUMENT</classname>, you should use an <classname>XM_NODE_PROCESSOR</classname>
 to generate an event stream, and send this event stream into one of the serializers mentioned below.
</para>

<para>
 The convenience class <classname>XM_FORMATTER</classname> does this for you with the <classname>XM_PRETTY_PRINT_FILTER</classname> serializer.
</para>

</section>

<section>
<title>Event stream serializers</title>

<para>
 The following event-stream serializers are provided directly within Gobo:

<variablelist>

 <varlistentry>
  <term><classname>XM_PRETTY_PRINT_FILTER</classname></term>
  <listitem>
   <para>
    This provides basic pretty-printing of the body of an XML document. It does not add any indentation, so
    it is not all that pretty.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><classname>XM_INDENT_PRETTY_PRINT_FILTER</classname></term>
  <listitem>
   <para>
    This adds indentation to <classname>XM_PRETTY_PRINT_FILTER</classname>, so the output is more
    what you might expect from a pretty printer.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><classname>XM_NAMESPACE_PRETTY_PRINT_FILTER</classname></term>
  <listitem>
   <para>
    This prints <exmlsyntax>QNames</exmlsyntax> in Clark notation. The resulting output is not well-formed XML.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><classname>XM_DTD_PRETTY_PRINT_FILTER</classname></term>
  <listitem>
   <para>
    This prints DTD declarations. It does not generate a properly well-formed internal subset DTD, so should probably
    not be used for serialzing. It is rather meant as a debugging aid, i think.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term>XSLT 2.0 and XQuery 1.0 Serialization</term>
  <listitem>
   <para>
    The XSLT library includes a serializer that conforms to the <ulink url="http://www.w3.org/TR/xslt-xquery-serialization/">XSLT 2.0 and XQuery 1.0 Serialization specification</ulink>, and so gives
    you all the customizing power of an <ulink url="http://www.w3.org/TR/xslt20/#element-output">xsl:output</ulink> statement.
    It is not necessary to invoke the XSLT engine in order to use this serializer, although you do need to include the XPath and XSLT library
    clusters (just include the XSLT library.ecf in your system.ecf file).
   </para>
   <para>
    To see how to use the serializer, refer to <filename>${GOBO}/library/xslt/example/serializer/Readme.md</filename>, or to the documentation in 
    <link linkend="${library/xslt}/xslt_serializer">XSLT 2.0 Serializer</link>.
   </para>
  </listitem>
 </varlistentry>

</variablelist>

</para>

</section>

</chapter>
