docs/org.eclipse.wst.xsl.doc/docbook/launching/launching.xml - sourceediting/webtools.sourceediting.xsl - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
           "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <chapter>
 	<?dbhtml filename="launching/launching.html" ?>
 	<title>XSL Launching and Debugging</title>
 	<para> XSL Tools adds support for XSL Launch and Debugging configurations. These allow you to setup XSL configurations
 		for various jobs, and to also debug xsl stylsheet transformations.</para>
 	<section id="XSLLaunch">
 		<?dbhtml filename="launching/launching.html" ?>
 		<title>XSL Launching</title>
 		<para>
 			In the Project Explorer, simply select the input XML file and the stylesheet(s) to transform it, and then right-click
 			and select
 			<emphasis>Run As > XSL Transformation</emphasis>
 			.
 		</para>
 		<mediaobject>
 			<imageobject>
 				<imagedata align="center" format="PNG" fileref="../images/launching/launchShortct.png" />
 			</imageobject>
 		</mediaobject>
 	</section>
 	<section id="XSLDebug">
 	    <?dbhtml filename="launching/debugging.html" ?>
 		<title>XSLT Debugging</title>
 		<para> XSL Tools provides a framework for XSLT processors to provide debugging support. The support provided is highly
 			dependent on the processors. XSL Tools comes with built in support for the Xalan 2.7.1 processor. Debugging is only
 			available for those processors that support the feature and plug into the extension point. The XSL Tools debugger
 			leverages the existing eclipse platform Debug View</para>
 		<para>
 			How the debugger acts will depend on the processor being used. Not all XSLT processors pass the same type of
 			information to the debugger. These differences will be noted in the
 			<xref linkend="XSLDebugProcessorSpecific" />
 			section.
 		</para>
 		<section id="DebugGettingStarted">
 			<?dbhtml filename="launching/debugging_gettingStarted.html" ?>
 			<title>Starting a Debug Session</title>
 			<para> Debugging is started the same way as launching an XSL Tranformation is done. Except that the debug
 				configuration is used instead of the normal launch configuration. If a debugging session is started on a processor
 				that does not support debugging, a dialog will ask if you want to switch to one of the supported debuggers.</para>
 			<note>
 				<title>Default JRE</title>
 				<para> The default JRE does not have built in support for debugging, even though it is based on Apache Xalan. It is
 					recommended to use Xalan or another processor provided by an adopter to do your transformations. The default
 					processor is known to have some issues that Xalan and other processors do not have.</para>
 			</note>
 		</section>
 		<section id="XSLDebugCommon">
 		<?dbhtml filename="launching/debugging_common.html" ?>
 			<title>Common Debugging Operations</title>
 			<para>
 				XSLT debugging is handled by the eclipse platforms debugging framework support as outlined in the
 				<ulink url="/help/topic/org.eclipse.platform.doc.isv/guide/debug_debug.htm">"Program Debug and Launch Support"</ulink>
 				. Common operations like stepping into (F5), stepping over (F6), pausing, running to a breakpoint, and relaunching
 				are supported. In addition to the standard Variable and Breakpoint views provided by the platform, there are some
 				XSLT specific views and functionality as well. All of these are common regardless of the particular XSLT debugger
 				being used.
 			</para>
 			<tip>
 				<title>Introduction to Eclipse Debugging</title>
 				<para>
 					<ulink url="http://www.mcs.vuw.ac.nz/courses/COMP205/2007T1/tools/eclipse/debugging/basics.shtml">Basic Debugging in Eclipse</ulink>
 					contains a good general introduction to the basic features provided by the Eclipse Debug view. XSL Tools leverages
 					many of these features and the same concepts apply to the XSL Tools debugger.
 				</para>
 			</tip>
 			<para> In addition to the standard features and functionality, the XSL Tools debugging support adds the following
 				additional items:</para>
 			<itemizedlist>
 				<listitem>
 					<para> Result View</para>
 				</listitem>
 				<listitem>
 					<para>XSLT specific Variables</para>
 				</listitem>
 				<listitem>
 					<para>XSLT Processor Specific Functionality</para>
 				</listitem>
 			</itemizedlist>
 			<section id="XSLDebugResultView">
 			<?dbhtml filename="launching/debugging_resultview.html" ?>
 				<title>Result View</title>
 				<para> The XSLT Debugger has a result view. This will show the output that the stylesheet has generated to the
 					current break point or since the last step command was issued.</para>
 				<mediaobject>
 					<imageobject>
 						<imagedata align="center" format="PNG" fileref="../images/launching/resultView.png" />
 					</imageobject>
 				</mediaobject>
 				<para> The result view is updated throughout the debugging process, and is useful to help see what output is
 					generated at specific points during a transformation.</para>
 			</section>
 			<section id="XSLDebugVariables">
 			<?dbhtml filename="launching/debugging_variablesview.html" ?>
 				<title>Variables View</title>
 				<para> The variables view will show all the local and global variables and params that are currently in scope. There
 					are two types of variables that can be views.</para>
 				<mediaobject>
 					<imageobject>
 						<imagedata align="center" format="PNG" fileref="../images/launching/nodesetVariable.png" />
 					</imageobject>
 				</mediaobject>
 				<itemizedlist>
 					<title>Variable Types</title>
 					<listitem>
 						<para>
 							<emphasis>String</emphasis>
 							- These contain text values. This could be strings of text, numbers, or other characters.
 						</para>
 					</listitem>
 					<listitem>
 						<para>
 							<emphasis>Nodesets</emphasis>
 							- Nodesets are represented in the variables view as expandable variables. They contain sequences of nodes. The
 							type of nodes are represented by icons for elements, attributes, text, comments or processing instructions.
 						</para>
 					</listitem>
 				</itemizedlist>
 				<note>
 					<title>Can I change the value of variables?</title>
 					<para> Currently the XSLT Debugger does not support changing the values or contents of a variable. All XSLT
 						variables are read only.</para>
 				</note>
 			</section>
 		</section>
 		<section id="XSLDebugProcessorSpecific">
 			<?dbhtml filename="launching/debugging_processors.html" ?>
 			<title>XSLT Processor Specific Support</title>
 			<para> Various XSLT processors provide various levels of debugging support. Many do not provide support for debugging
 				of stylesheets, and thus can't be used for debugging. XSL Tools provides basic support for Xalan, and can be used as
 				a guide for adopters on how to implement their own specific debugging support for other processors.</para>
 			<section id="XSLDebugXalan">
 				<title>XSL Debugging with Xalan</title>
 				<para> Xalan provides general stylesheet execution and evalation functionality. However there are a few things that
 					Xalan does not suppor that other processors do.</para>
 				<orderedlist>
 					<title>Xalan Debugging Issues</title>
 					<listitem>
 						<para>
 							<emphasis>Breakpoints</emphasis>
 							- Xalan does not support stopping at Global Variables or Parameters when a debugging session is started. It will
 							automatically start at the first template. Break points must be placed in templates to be honored. The reason for
 							this is that Xalan lazily initializes the variables only when they are first used.
 						</para>
 					</listitem>
 					<listitem>
 						<para>
 							<emphasis>XSLT Text elements</emphasis>
 							- Xalan does not send notifications of xsl:text elements. These are skipped over when debugging.
 						</para>
 					</listitem>
 					<listitem>
 						<para>
 							<emphasis>Built In Templates</emphasis>
 							- Xalan does provide notification when the built in templates are called, but currently the debugger does not
 							support or display stepping into these templates.
 						</para>
 					</listitem>
 				</orderedlist>
 			</section>
 		</section>
 	</section>
 </chapter>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
	<chapter>
	<?dbhtml filename="launching/launching.html" ?>
	<title>XSL Launching and Debugging</title>
	<para> XSL Tools adds support for XSL Launch and Debugging configurations. These allow you to setup XSL configurations
	for various jobs, and to also debug xsl stylsheet transformations.</para>
	<section id="XSLLaunch">
	<?dbhtml filename="launching/launching.html" ?>
	<title>XSL Launching</title>
	<para>
	In the Project Explorer, simply select the input XML file and the stylesheet(s) to transform it, and then right-click
	and select
	<emphasis>Run As > XSL Transformation</emphasis>
	.
	</para>
	<mediaobject>
	<imageobject>
	<imagedata align="center" format="PNG" fileref="../images/launching/launchShortct.png" />
	</imageobject>
	</mediaobject>
	</section>
	<section id="XSLDebug">
	<?dbhtml filename="launching/debugging.html" ?>
	<title>XSLT Debugging</title>
	<para> XSL Tools provides a framework for XSLT processors to provide debugging support. The support provided is highly
	dependent on the processors. XSL Tools comes with built in support for the Xalan 2.7.1 processor. Debugging is only
	available for those processors that support the feature and plug into the extension point. The XSL Tools debugger
	leverages the existing eclipse platform Debug View</para>
	<para>
	How the debugger acts will depend on the processor being used. Not all XSLT processors pass the same type of
	information to the debugger. These differences will be noted in the
	<xref linkend="XSLDebugProcessorSpecific" />
	section.
	</para>
	<section id="DebugGettingStarted">
	<?dbhtml filename="launching/debugging_gettingStarted.html" ?>
	<title>Starting a Debug Session</title>
	<para> Debugging is started the same way as launching an XSL Tranformation is done. Except that the debug
	configuration is used instead of the normal launch configuration. If a debugging session is started on a processor
	that does not support debugging, a dialog will ask if you want to switch to one of the supported debuggers.</para>
	<note>
	<title>Default JRE</title>
	<para> The default JRE does not have built in support for debugging, even though it is based on Apache Xalan. It is
	recommended to use Xalan or another processor provided by an adopter to do your transformations. The default
	processor is known to have some issues that Xalan and other processors do not have.</para>
	</note>
	</section>
	<section id="XSLDebugCommon">
	<?dbhtml filename="launching/debugging_common.html" ?>
	<title>Common Debugging Operations</title>
	<para>
	XSLT debugging is handled by the eclipse platforms debugging framework support as outlined in the
	<ulink url="/help/topic/org.eclipse.platform.doc.isv/guide/debug_debug.htm">"Program Debug and Launch Support"</ulink>
	. Common operations like stepping into (F5), stepping over (F6), pausing, running to a breakpoint, and relaunching
	are supported. In addition to the standard Variable and Breakpoint views provided by the platform, there are some
	XSLT specific views and functionality as well. All of these are common regardless of the particular XSLT debugger
	being used.
	</para>
	<tip>
	<title>Introduction to Eclipse Debugging</title>
	<para>
	<ulink url="http://www.mcs.vuw.ac.nz/courses/COMP205/2007T1/tools/eclipse/debugging/basics.shtml">Basic Debugging in Eclipse</ulink>
	contains a good general introduction to the basic features provided by the Eclipse Debug view. XSL Tools leverages
	many of these features and the same concepts apply to the XSL Tools debugger.
	</para>
	</tip>
	<para> In addition to the standard features and functionality, the XSL Tools debugging support adds the following
	additional items:</para>
	<itemizedlist>
	<listitem>
	<para> Result View</para>
	</listitem>
	<listitem>
	<para>XSLT specific Variables</para>
	</listitem>
	<listitem>
	<para>XSLT Processor Specific Functionality</para>
	</listitem>
	</itemizedlist>
	<section id="XSLDebugResultView">
	<?dbhtml filename="launching/debugging_resultview.html" ?>
	<title>Result View</title>
	<para> The XSLT Debugger has a result view. This will show the output that the stylesheet has generated to the
	current break point or since the last step command was issued.</para>
	<mediaobject>
	<imageobject>
	<imagedata align="center" format="PNG" fileref="../images/launching/resultView.png" />
	</imageobject>
	</mediaobject>
	<para> The result view is updated throughout the debugging process, and is useful to help see what output is
	generated at specific points during a transformation.</para>
	</section>
	<section id="XSLDebugVariables">
	<?dbhtml filename="launching/debugging_variablesview.html" ?>
	<title>Variables View</title>
	<para> The variables view will show all the local and global variables and params that are currently in scope. There
	are two types of variables that can be views.</para>
	<mediaobject>
	<imageobject>
	<imagedata align="center" format="PNG" fileref="../images/launching/nodesetVariable.png" />
	</imageobject>
	</mediaobject>
	<itemizedlist>
	<title>Variable Types</title>
	<listitem>
	<para>
	<emphasis>String</emphasis>
	- These contain text values. This could be strings of text, numbers, or other characters.
	</para>
	</listitem>
	<listitem>
	<para>
	<emphasis>Nodesets</emphasis>
	- Nodesets are represented in the variables view as expandable variables. They contain sequences of nodes. The
	type of nodes are represented by icons for elements, attributes, text, comments or processing instructions.
	</para>
	</listitem>
	</itemizedlist>
	<note>
	<title>Can I change the value of variables?</title>
	<para> Currently the XSLT Debugger does not support changing the values or contents of a variable. All XSLT
	variables are read only.</para>
	</note>
	</section>
	</section>
	<section id="XSLDebugProcessorSpecific">
	<?dbhtml filename="launching/debugging_processors.html" ?>
	<title>XSLT Processor Specific Support</title>
	<para> Various XSLT processors provide various levels of debugging support. Many do not provide support for debugging
	of stylesheets, and thus can't be used for debugging. XSL Tools provides basic support for Xalan, and can be used as
	a guide for adopters on how to implement their own specific debugging support for other processors.</para>
	<section id="XSLDebugXalan">
	<title>XSL Debugging with Xalan</title>
	<para> Xalan provides general stylesheet execution and evalation functionality. However there are a few things that
	Xalan does not suppor that other processors do.</para>
	<orderedlist>
	<title>Xalan Debugging Issues</title>
	<listitem>
	<para>
	<emphasis>Breakpoints</emphasis>
	- Xalan does not support stopping at Global Variables or Parameters when a debugging session is started. It will
	automatically start at the first template. Break points must be placed in templates to be honored. The reason for
	this is that Xalan lazily initializes the variables only when they are first used.
	</para>
	</listitem>
	<listitem>
	<para>
	<emphasis>XSLT Text elements</emphasis>
	- Xalan does not send notifications of xsl:text elements. These are skipped over when debugging.
	</para>
	</listitem>
	<listitem>
	<para>
	<emphasis>Built In Templates</emphasis>
	- Xalan does provide notification when the built in templates are called, but currently the debugger does not
	support or display stepping into these templates.
	</para>
	</listitem>
	</orderedlist>
	</section>
	</section>
	</section>
	</chapter>