Debugging and Error handling

Debugging and Error handling

• 1.
  Methods of Debuggingand Error Handling in the DITA Open Toolkit Processing Leora Betesh, Suite Solutions
• 2.
  Who am I?Bachelor’s in Computer Science 5+ years at UBS as computer programmer Early member of the Suite Solutions team PDF style sheet projects HTML style sheet projects CMS integration WebWorks xsl customization Dita -> MS Word transforms Intro to DITA-OT training seminar Belgium 2009
• 3.
  Who are we?Our Mission To increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes. Qualitative Advantage Content Lifecycle Implementation (CLI) is Suite Solutions’ comprehensive approach – from concept to publication – to maximizing the value of your information assets. Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business.
• 4.
  Clients and PartnersPrivate and Confidential Suite Solutions©2009
• 5.
  Main Topics Debugging Tips Redirect Output Mapping from code to output What is the value that has been assigned to my variable? Speed up debugging time Using the merged xml file Error Handling Error handling vs. debugging Why error handling? Methods of error handling
• 6.
  Debugging Topics
• 7.
  Sample error Thedita-ot build fail. There error looks like it has something to do with my content. How do I find the source of the error? What now? BUILD FAILED C:\DITA-OT1.5-webinar\samples\build_webinar.xml:31: The following error occurred while executing this line: C:\DITA-OT1.5-webinar\build.xml:30: The following error occurred while executing this line: C:\DITA-OT1.5-webinar\demo\fo\build.xml:174: The following error occurred while executing this line: C:\DITA-OT1.5-webinar\demo\fo\build.xml:297: The following error occurred while executing this line: C:\DITA-OT1.5-webinar\demo\fo\build.xml:234: java.io.FileNotFoundException: C:\D ITA-OT1.5-webinar\temp\sequence_MERGED.xml (The system cannot find the file spec ified)
• 8.
  Redirect output Redirectoutput to log file, find error at beginning of log Syntax C:\DITA-OT\samples>ant -f build_webinar.xml > log.txt Get log from CMS – all the DITA-OT messages will be included. To find an error in the log, look for the first error. Subsequent errors may result from the original error, so start at the beginning of the file looking for the first error.
• 9.
  Mapping from codeto output Where am I in the code? Which template am I in? Which xsl:when am I in? Which attribute set am I in? Which file am I in? XMetaL element id XMetaL creates ids with the element name as part of the id – to easily recognize which element I am in. < fo:block id =&quot;unique_26_Connect_42_ section _919F9F2C66A84E128C91C10F7D5A76A9&quot;> < fo:block id =&quot;unique_26_Connect_42_ p _827EF4C92D284C769404BD4991CCD45D&quot;> Create a dummy label in the attribute sets < xsl:attribute-set name =&quot;ul.li__label&quot;> <!-- added dummy attribute to find attribute-set in output --> < xsl:attribute name =&quot;test&quot;>ul.li__label</ xsl:attribute > </ xsl:attribute-set >
• 10.
  Mapping from codeto output Create a comment inside template: < xsl:template name =&quot;createFrontMatter&quot;> < xsl:comment >entered template createFrontMatter</ xsl:comment > Output: <!--entered template createFrontMatter--> Not only can I find where I am in the code, but also check values of variables and nodes. How can I output the value of a variable? Xsl:message – faster to find message Xsl:comment – more precise location in output
• 11.
  Mapping from codeto output Example: What is the value that has been assigned to my variable? Problem: getTrisoft map GUID, need to parse a few files. My output is not getting the correct value, but I don’t know at which part my code is failing. In addition, I am working on the CMS so I need to get back information in log file to troubleshoot the problem. < xsl:comment > ############################################### inputfolder=< xsl:value-of select =&quot;$inputfolder&quot;/> parentfolder=< xsl:value-of select =&quot;$parentfolder&quot;/> eventdatapath=< xsl:value-of select =&quot;$eventdatapath&quot;/> exportPath=< xsl:value-of select =&quot;$exportPath&quot;/> mapNamePath=< xsl:value-of select =&quot;$mapNamePath&quot;/> ############################################### </ xsl:comment >
• 12.
  Speed up debuggingtime Comment out parts of root template Example: I have a problem with the TOC. I will comment out everything but TOC. Note: Do not comment out createLayoutMasters – this is needed in any output. < xsl:template name =&quot;rootTemplate&quot;> < xsl:call-template name =&quot;validateTopicRefs&quot;/> < fo:root xsl:use-attribute-sets =&quot;__fo__root&quot;> < xsl:call-template name =&quot;createLayoutMasters&quot;/> < xsl:call-template name =&quot;createBookmarks&quot;/> < xsl:call-template name =&quot;createFrontMatter&quot;/> < xsl:call-template name =&quot;createToc&quot;/> <!-- <xsl:call-template name=&quot;createPreface&quot;/> --> < xsl:apply-templates /> < xsl:call-template name =&quot;createIndex&quot;/> </ fo:root > </ xsl:template >
• 13.
  Speed up debuggingtime Debugging Target Aryeh Sanders at Suite Solutions wrote an ant target to speed output generation while troubleshooting. Reduces output time by more than 50% Bypasses steps of clearing the temp directory and copying files to the temp directory. Assuming that your content hasn’t changed – only the xsl. Add the target to the top-level build.xml file and invoke the target from your project build file. Code is on the following two pages. Prerequisite for DITA-OT 1.5 If you are using DITA-OT 1.5 go open the file build-init.xml and edit line 83 – change the temp folder name to just temp: < property name =&quot;dita.temp.dir&quot; value =&quot;temp&quot;/>
• 14.
  Speed up debuggingtime Place this target into the top-level dita-ot build.xml: < target name =&quot;devel-pdf2&quot; depends =&quot;start-process, init-logger, check-arg, output-deprecated-msg, output-css-warn-message&quot;> < xmlpropertyreader file =&quot;${dita.temp.dir}${file.separator}dita.xml.properties&quot;/> < dirname property =&quot;dita.map.output.dir&quot; file =&quot;${output.dir}${file.separator}${user.input.file}&quot; /> < condition property =&quot;noConref&quot;>< equals arg1 =&quot;${conreflist}&quot; arg2 =&quot;&quot; /></ condition > < condition property =&quot;noMap&quot;>< equals arg1 =&quot;${fullditamaplist}&quot; arg2 =&quot;&quot; /></ condition > < condition property =&quot;noTopic&quot;>< equals arg1 =&quot;${fullditatopiclist}&quot; arg2 =&quot;&quot; /></ condition > < condition property =&quot;noImagelist&quot;>< equals arg1 =&quot;${imagelist}&quot; arg2 =&quot;&quot; /></ condition > < condition property =&quot;noHtmllist&quot;>< equals arg1 =&quot;${htmllist}&quot; arg2 =&quot;&quot; /></ condition > < condition property =&quot;noSubList&quot;>< equals arg1 =&quot;${subtargetslist}&quot; arg2 =&quot;&quot; /></ condition > < ant dir =&quot;${dita.dir}/demo/fo&quot; target =&quot;publish.map.pdf&quot;> < property name =&quot;caller.dir&quot; value =&quot;${basedir}&quot;/> </ ant > </ target >
• 15.
  Speed up debuggingtime Use this target in your project build file to invoke the development target. < target name =&quot;devel&quot;> < antcall target =&quot;devel-pdf2&quot;> < param name =&quot;transtype&quot; value =&quot;pdf&quot; /> < param name =&quot;args.input&quot; value =&quot;C:\DITA-OT\samples\hierarchy.ditamap&quot; /> </ antcall > </ target > Generate output the way your normally do.
• 16.
  Debugging use mergedxml file If you are using the pdf transform, all the topics will be merged into one xml file. Go to the temp directory and find the file MyMapName_merged.xml. Determine element hierarchy and class names Example: I am setting up an xpath statement and want to find all the preceding siblings of an element – check merged file to see which nodes will be included in this xpath selection. See what has made it into topicmerge Example: I set an outputclass on a topic and I want to see which node exactly got that outputclass attribute. Especially useful when setting up specializations The dita-ot adds the full class name to each element in the merged file. I can easily grab the class name I need to reference and see inheritance. < learningAssessmentbody class =&quot;- topic/body learningBase/learningBasebody learningAssessment/learningAssessmentbody “ … > (from learning specialization)
• 17.
  Debug using topic.foTry to fix the problem in topic.fo Example: problem with page masters. First header never appears. Look into the page-sequence-master <fo:page-sequence-master master-name=&quot;body-sequence&quot;> <fo:repeatable-page-master-alternatives> <fo:conditional-page-master-reference master-reference=&quot;body-first&quot; odd-or-even=&quot;odd&quot; page-position=&quot;first&quot;/> Correct problem in topic.fo and then will know where in the xsl to fix.
• 18.
  Error Handling
• 19.
  Error Handling Errorhandling vs. debugging. Debugging is for the developer to find the error in the program. Error handling is communicating to the user an error that was found in the input to the program.
• 20.
  Default error handlingFor example, the dita-ot relies on dtds that specify rules that the dita must conform with. Each element has a list of required and optional elements that it can contain. Order is significant. An error message will be generated by the toolkit if the DTD is not followed This is an example of error handling that is already built in to the toolkit.
• 21.
  Errors? So whatother type of errors might we need to handle? Example: I have a rule that the same topic cannot be inserted twice into the ditamap. Example: I have a rule that two topics may not have the same navtitle.
• 22.
  Error Handling OptionsError types: send a warning message that in a particular file there is an error force the build to fail for a more serious error. Draft vs. real mode. Draft – display file name in red with error element Non draft – fail build
• 23.
  Error Handling TipsCreate messages in an xml file. < messages > < message id =&quot;DOTAWEBINAR001F&quot; type =&quot;FATAL&quot;> < reason >A topic is referenced twice in the same ditamap.</ reason > < response >Please correct your ditamap or bookmap file.</ response > </ message > < message id =&quot;DOTAWEBINAR002W&quot; type =“WARN&quot;> < reason >Two topics have the same navtitle.</ reason > < response >Please correct your ditamap or bookmap file.</ response > </ message > </ messages > Plugin the xml file to the main dita-ot messages file: < feature extension =&quot;dita.xsl.messages&quot; value =&quot;messages.xml&quot; type =&quot;file&quot;/>
• 24.
   
• 25.
  End of Methodsof Error Handling and Debugging DITA Open Toolkit Processing Be in touch! [email_address] leora.betesh Let us know how we can help you…