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>
 		<figure
 			id="fig_XSLRun">
 			<title>XSLT Run/Debug</title>
 			<mediaobject>
 				<imageobject>
 					<imagedata
 						align="center"
 						format="PNG"
 						fileref="../images/launching/launchShortct.png" />
 				</imageobject>
 			</mediaobject>
 		</figure>
 		<note>
 			<title>Selecting only the XSL Stylesheet</title>
 			<para>
 				If only the XSL Stylesheet is selected then a dialog box will prompt you for the input file to use.
 			</para>
 		</note>
 		<para>
 			Launch can also be done through the Launch Configurations pages that are used for both debugging and normal transformations.
 			These configurations can be accessed through <emphasis>Run->Run Configurations</emphasis> menu bar option.
 		</para>
 		<section
 			id="XSLLaunchConfig">
 			<title>Launch Configuration</title>
 			<para>
 				Currently, XSL Tools only supports the launching of java based
 				processors through the Run and Debug framework. To this point, it
 				leverages and extends some of the support provided by the Java
 				launch configurations. XSL Tools does add it's own specific features
 				for launching.
 			</para>
 			<figure
 				id="fig_XSLLaunchConfig">
 				<title>Java XSLT Launch Configuration</title>
 				<mediaobject>
 					<imageobject>
 						<imagedata
 							align="center"
 							format="PNG"
 							fileref="../images/launching/XSLRunDebugConfigurations.png" />
 					</imageobject>
 				</mediaobject>
 			</figure>
 			<para>
 				The tabs Main, Output, and Processor control specifics for the XSLT processor and files to be run through
 				the transformation.
 			</para>
 			<note>
 				<title>XSLT Extensions</title>
 				<para>If the transformation needs or makes use of extension
 					functions then those jar files should be added to the Classpath tab
 					so that they are picked up during the transformation. Otherwise the
 					transformation will fail.</para>
 			</note>
 			<section id="XSLLaunch_Main">
 				<title>Main Tab</title>
 				<para>
 					As shown in <xref linkend="fig_XSLLaunchConfig"/>, the Main Tab is where the input XML file is specified.  If a particular
 					XML file is not shown in the available list when browsing the Workspace, make sure that it is added to under the XML Content
 					Type in the General preference page.  Standard eclipse launching variables can be used to specify the location of the input file.
 				</para>
 				<para>
 					A run configuration can also use a simple pipeline transformation.  Meaning that the output from one stylesheet is used as input
 					to the next stylesheet.   The Stylesheet input box can have one to many stylesheets specified.  At least one stylesheet is required
 					for a transformation.
 				</para>
 				<para>
 					The last optional item are parameters.   Stylesheets can have parameters passed into them to setup configuration information.  An
 					example would be the numerous parameters that can be set for a DocBook stylesheet transformation.   If the parameters are not
 					specified the defaults that are defined in the stylesheet will take precedence.
 				</para>
 			</section>
 			<section id="XSLLaunch_Output">
 				<title>Output Tab</title>
 				<para>
 					The Output Tab allows the specification of where the transformation should store the information.
 					This can be relative to the workspace or a physical location outside the workspace.
 				</para>
 			<figure
 				id="fig_XSLOutputTab">
 				<title>Java XSLT Launch Configuration</title>
 				<mediaobject>
 					<imageobject>
 						<imagedata
 							align="center"
 							format="PNG"
 							fileref="../images/launching/XSLOutputTab.png" />
 					</imageobject>
 				</mediaobject>
 			</figure>

 			</section>
 			<section id="XSLLaunch_Processor">
 				<title>Processor Tab</title>
 				<para>
 					The particular XSLT processor that will be used can be choosen from this tab. The
 					default is to use the system default processor or what ever processor you have
 					set as the default processor in the preference pages.
 				</para>
 				<figure
 					id="fig_XSLProcessorTab">
 					<title>Java XSLT Launch Configuration</title>
 					<mediaobject>
 						<imageobject>
 							<imagedata
 								align="center"
 								format="PNG"
 								fileref="../images/launching/XSLProcessorTab.png" />
 						</imageobject>
 					</mediaobject>
 				</figure>

 				<note>
 					<title>XSLT Debugging</title>
 					<para>
 						If you are setting up a launch configuration for debugging, do not choose
 						the JRE Default processor, you should choose either Xalan or another adopters
 						processor that supports debugging.
 					</para>
 				</note>
 				<para>
 					In addition, every processor has their own configuration options that can be specified.
 					This controls such items as indentation, handling of white space, etc.  Refer to your
 					processors documentation for the specific options available.
 				</para>
 			</section>
 		</section>
 	</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>
 		<figure id="fig_XSLDebug">
 			<title>XSLT Debugging</title>
 				<mediaobject>
 					<imageobject>
 						<imagedata
 							align="center"
 							format="PNG"
 							fileref="../images/launching/XSLDebugging.png" />
 					</imageobject>
 				</mediaobject>
 		</figure>
 		<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>
	<figure
	id="fig_XSLRun">
	<title>XSLT Run/Debug</title>
	<mediaobject>
	<imageobject>
	<imagedata
	align="center"
	format="PNG"
	fileref="../images/launching/launchShortct.png" />
	</imageobject>
	</mediaobject>
	</figure>
	<note>
	<title>Selecting only the XSL Stylesheet</title>
	<para>
	If only the XSL Stylesheet is selected then a dialog box will prompt you for the input file to use.
	</para>
	</note>
	<para>
	Launch can also be done through the Launch Configurations pages that are used for both debugging and normal transformations.
	These configurations can be accessed through <emphasis>Run->Run Configurations</emphasis> menu bar option.
	</para>
	<section
	id="XSLLaunchConfig">
	<title>Launch Configuration</title>
	<para>
	Currently, XSL Tools only supports the launching of java based
	processors through the Run and Debug framework. To this point, it
	leverages and extends some of the support provided by the Java
	launch configurations. XSL Tools does add it's own specific features
	for launching.
	</para>
	<figure
	id="fig_XSLLaunchConfig">
	<title>Java XSLT Launch Configuration</title>
	<mediaobject>
	<imageobject>
	<imagedata
	align="center"
	format="PNG"
	fileref="../images/launching/XSLRunDebugConfigurations.png" />
	</imageobject>
	</mediaobject>
	</figure>
	<para>
	The tabs Main, Output, and Processor control specifics for the XSLT processor and files to be run through
	the transformation.
	</para>
	<note>
	<title>XSLT Extensions</title>
	<para>If the transformation needs or makes use of extension
	functions then those jar files should be added to the Classpath tab
	so that they are picked up during the transformation. Otherwise the
	transformation will fail.</para>
	</note>
	<section id="XSLLaunch_Main">
	<title>Main Tab</title>
	<para>
	As shown in <xref linkend="fig_XSLLaunchConfig"/>, the Main Tab is where the input XML file is specified. If a particular
	XML file is not shown in the available list when browsing the Workspace, make sure that it is added to under the XML Content
	Type in the General preference page. Standard eclipse launching variables can be used to specify the location of the input file.
	</para>
	<para>
	A run configuration can also use a simple pipeline transformation. Meaning that the output from one stylesheet is used as input
	to the next stylesheet. The Stylesheet input box can have one to many stylesheets specified. At least one stylesheet is required
	for a transformation.
	</para>
	<para>
	The last optional item are parameters. Stylesheets can have parameters passed into them to setup configuration information. An
	example would be the numerous parameters that can be set for a DocBook stylesheet transformation. If the parameters are not
	specified the defaults that are defined in the stylesheet will take precedence.
	</para>
	</section>
	<section id="XSLLaunch_Output">
	<title>Output Tab</title>
	<para>
	The Output Tab allows the specification of where the transformation should store the information.
	This can be relative to the workspace or a physical location outside the workspace.
	</para>
	<figure
	id="fig_XSLOutputTab">
	<title>Java XSLT Launch Configuration</title>
	<mediaobject>
	<imageobject>
	<imagedata
	align="center"
	format="PNG"
	fileref="../images/launching/XSLOutputTab.png" />
	</imageobject>
	</mediaobject>
	</figure>

	</section>
	<section id="XSLLaunch_Processor">
	<title>Processor Tab</title>
	<para>
	The particular XSLT processor that will be used can be choosen from this tab. The
	default is to use the system default processor or what ever processor you have
	set as the default processor in the preference pages.
	</para>
	<figure
	id="fig_XSLProcessorTab">
	<title>Java XSLT Launch Configuration</title>
	<mediaobject>
	<imageobject>
	<imagedata
	align="center"
	format="PNG"
	fileref="../images/launching/XSLProcessorTab.png" />
	</imageobject>
	</mediaobject>
	</figure>

	<note>
	<title>XSLT Debugging</title>
	<para>
	If you are setting up a launch configuration for debugging, do not choose
	the JRE Default processor, you should choose either Xalan or another adopters
	processor that supports debugging.
	</para>
	</note>
	<para>
	In addition, every processor has their own configuration options that can be specified.
	This controls such items as indentation, handling of white space, etc. Refer to your
	processors documentation for the specific options available.
	</para>
	</section>
	</section>
	</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>
	<figure id="fig_XSLDebug">
	<title>XSLT Debugging</title>
	<mediaobject>
	<imageobject>
	<imagedata
	align="center"
	format="PNG"
	fileref="../images/launching/XSLDebugging.png" />
	</imageobject>
	</mediaobject>
	</figure>
	<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>