Suite Labs: Generating SuiteHelp Output


Published on

SuiteHelp, the cross-platform, mobile-optimized help platform built upon the most recent web standards and technologies, including HTML5 and CSS3. In this webinar you will learn about the SuiteHelp technical architecture and the various options for generating and deploying SuiteHelp output.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Suite Labs: Generating SuiteHelp Output

  1. 1. Generating and Viewing SuiteHelpOutputAdena Frazer, Suite Solutions
  2. 2. Who am I?Adena Frazer• Background in Computer Science and Education• Early and senior member of the Suite Solutions team• Given many public and private training seminars over the past fiveyears• Extensive expertise implementing DITA and CMS solutions for a widevariety of organizations• Responsible for internal training and mentoring for developers at SuiteSolutions• Help companies get it right the first time
  3. 3. About Suite SolutionsOur Vision: Enable companies to engage their customers by providing quickaccess to relevant information• Help companies get it right the first time• XML-based Authoring/Publishing Solutions• Enterprise Intelligent Dynamic Content: SuiteShare• Consultancy, Systems Integration, Application Development• Cross-Industry Expertise• High Tech, Aerospace & Defense• Healthcare, Discrete Manufacturing• Blue Chip Customer Base• Hundreds of Person Years of Experience on Staff
  4. 4. SuiteShare: Dynamic PublishingTaking the Leap to a New Paradigm• Variety of content: documentation, videos, how-to articles, safetyinformation, data sheets, marketing material• Context filtering: quick, goal-oriented access to contextually relevant content• Personalized docs: allow readers to assemble content on demand andrender to PDF for print and eBook for offline mobile access• Audience Participation: allow your audience to add new content, commenton existing content, express approval, and easily share knowledge withothers on the KB and on social media• Modern User Experience: smooth transition between mobile and desktop• Activity often starts on mobile,moves to desktop, returns to mobile• Internet connection not always available
  5. 5. Main Topics Technical Architecture Installing SuiteHelp Generating SuiteHelp Output Viewing SuiteHelp Output Deploying SuiteHelp
  6. 6. Technical ArchitecturePreprocessing• Performed by the DITA Accelerator• Greater efficiency, accuracy, and speed than the DITA-OTpre-processing, overcoming known bugs and architectural constraintsGeneration of HTML Topics• Utilizes either of the following options:• Native DITA Accelerator formatting: Element mapping file, no XSL• DITA Open Toolkit style sheets (DITA2XHTML): allows you toleverage your existing XHTML customizationsSuiteHelp User Interface and Search Generation• Performed by the DITA Accelerator• Includes nav-bar, header, footer, breadcrumbs, and overall UI format• Extensively customizable
  7. 7. SuiteHelp Process FlowUsing Native HTML5 GenerationUsing DITA Open Toolkit XHTML GenerationNote: As of version 1.7.1 the DITA-OT is starting to support HTML5
  8. 8. Options for Generating HTML TopicsNative DITA Accelerator formatting• Produces HTML5, not XTHML(Note: As of version 1.7.1 the DITA-OT is starting to support HTML5)• No dependency on secondary applications or software: self-contained (noDITA Toolkit, Java, etc.)• Higher performance• Lowers barrier to entry: Knowledge of HTML and CSS are the onlyprerequisites to customizing HTML5 output.• significantly lower learning curve• produce high-quality customized HTML5 output without requiringpractitioners skilled in languages such as ANT, XSL, XPath or JavaDITA Open Toolkit style sheets (DITA2XHTML)• Allows you to reuse existing customizations• More accessibility to make complex functional changes to the content,such as switching order of elements, etc.
  9. 9. Installing SuiteHelp Using the DITA-OT Without the DITA-OT
  10. 10. Installing SuiteHelp with the DITA ToolkitUnzip the SuiteHelp release package and copy the SuiteHelp pluginfolders into the DITA-OTplugins folder:• suitehelp – contains suitehelp.exe and the core SuiteHelp presentationfiles• suitehelp-libs – contains ICU DLLs (Internationalization Componentsfor Unicode)• suitehelp-customization – contains default SuiteHelp skin formattingfiles• If you will be generating SuiteHelp Standalone:• Copy the suitehelp-standalone folder into your plugins folder• If you will be generating SuiteHelp+:• Copy the suitehelpplus folder into your plugins folder
  11. 11. Download and unzip the DITA Accelerator release package.It has the following structure:Note: The locations of these directories and files can be changed as needed.Installing SuiteHelp Without the DITAToolkitContains SuiteHelp plugins and licenseXML Catalog file that referencesthe DTDs in the dtd directoryContains DITA DTDsWindows batch files forrunning SuiteHelpLocation of temporary filesLocation of DITA SourceLocation of SuiteHelp output
  12. 12. Generating SuiteHelp Without the DITAToolkit1. Sample batch files are provided to generate output.2. Provide the relative location and name of your input ditamap file as thesecond argument in suitehelp.batFor example:suitehelpsuitehelpexesuitehelp.exe --sourcesourcetaskbook.ditamap3. Set outputclass=“homepage” on one of the topicrefs in your inputditamap. The generated index.html page will redirect to this file.
  13. 13. Generating SuiteHelp Output Using the DITA Toolkit DITA Open Toolkit style sheets (DITA2XHTML) Native DITA Accelerator formatting Directly with the SuiteHelp Executable With SuiteHelp Plus and SuiteHelp Standalone
  14. 14. Generating SuiteHelp OutputUsing the DITA Toolkit• Using ANT1. Run integrator: ant -f integrator.xml2. Run the DITA Toolkit using the transtype: suitehelp• Using JavaCall dost.jar, for example:java -jar lib/dost.jar /transtype:suitehelp/i:samples/taskbook.ditamapNote: when you call dost.jar, integrator is run automaticallyNote: when using Java, you may not add any SuiteHelp specificparameters; therefore, we recommend using ANT
  15. 15. Generating SuiteHelp OutputUsing the DITA Toolkit• By default, HTML topics are generated using the DITA Toolkit style sheets(dita2xhtml)• To generate HTML topics using Native DITA Accelerator formatting1. Open the configuration file in a text editor:pluginssuitehelp-customizationsuitehelp-conf.xml2. Remove the comments around the <classmap> element<!-- Uncomment to use native DITA Accelerator Formatting<classmap>classmap.yaml</classmap>-->
  16. 16. Generating SuiteHelp Directly Using theSuiteHelp ExecutableRun the suitehelp.exe with the following arguments:• source – path to the ditamap• tempdir – path to the temp folder• outdir – path to the output folder• suitehelp-conf – location of SuiteHelp configuration fileExample from suitehelp.bat:suitehelpsuitehelpexesuitehelp.exe--source sourcetaskbook.ditamap--tempdir temp--outdir output--suitehelp-confsuitehelpsuitehelp-customizationsuitehelp-conf.xml
  17. 17. Generating SuiteHelp StandaloneUsing the DITA Toolkit• Be sure the suitehelp-standalone plugin has been unzipped into yourplugins folder• Generate SuiteHelp output• SuiteHelp is packaged into a Standalone executable
  18. 18. Generating SuiteHelp StandaloneUsing the SuiteHelp Executable1. Generate SuiteHelp using suitehelp.bat• Output from suitehelp.bat becomes input for suitehelp-standalone2. Run suitehelp-standalonesuitehelp-inject.exe with the followingarguments1. Location of templates directory2. Location of output directory3. Location and name of the resulting executable3. Run suitehelp-standaloneupx.exe with the following argument tocompress the initial executable:1. Location and name of the suitehelp-standalone executable
  19. 19. Generating SuiteHelp StandaloneUsing the SuiteHelp ExecutableExample from suitehelpstandalone.bat:suitehelpsuitehelp-standalonesuitehelp-inject.exesuitehelpsuitehelp-standalonetemplatesoutputoutputsuitehelp-standalone.exesuitehelpsuitehelp-standaloneupx.exeoutputsuitehelp-standalone.exe
  20. 20. Verifying SuiteHelp StandaloneGenerationWhen generating SuiteHelp Standalone output, you should see the followingmessage in the log file:• You should see suitehelp-standalone.exe in the output directory• You can rename the exe file to a name suitable to your content, e.g.MyProduct-User-Guide.exe[exec] Ultimate Packer for eXecutables[exec] Copyright (C) 1996 - 2010[exec] UPX 3.07w Markus Oberhumer, Laszlo Molnar & John Reiser Sep 08th 2010[exec] File size Ratio Format Name[exec] ------------- ------ ----------- -----------[exec] 37658126 -> 28844046 76.59% win32/pe suitehelp-standalone.exe[exec] Packed 1 file.
  21. 21. Generating SuiteHelp+Using the DITA Toolkit• Be sure the suitehelpplus plugin has been unzipped into your pluginsfolder• Generate SuiteHelp• You should see a search-index.sqlite file in the output folderNote:• If both the suitehelpplus and suitehelp-standalone plugins are in theplugins folder, both the search-index.sqlite and suitehelp.exe will begenerated if you generate SuiteHelp using the DITA Toolkit
  22. 22. Generating SuiteHelp+Using the SuiteHelp Executable1. Run suitehelp.bat• Output from suitehelp.bat becomes input for suitehelpplus2. Call suitehelpplusexecreate-index.exe with the following arguments:1. Location and name of the resulting sqlite database2. Location and name of input xml fileNote: The file names should not be changed. Use the values that are inthe suitehelpplus.bat file for these parameters.Example (from suitehelpplus.bat):suitehelpsuitehelpplusexecreate-index.exeoutputsearch-index.sqlitetempsearchinfo.xml
  23. 23. Viewing SuiteHelp Output From a File System Without a Webserver From a Webserver With SuiteHelp Plus With SuiteHelp Standalone
  24. 24. Viewing SuiteHelp OutputFrom the File System Without a Webserver• Navigate to the output directory.• Open index.html in your browserNote:• In general, when viewing SuiteHelp without a web server, AJAX cannotrun, reducing the user experience• There will be no option to print all topics within a tree.• The screen will refresh after each click in the TOC, search, index,glossary• Position in the TOC, index and glossary are not remembered• Search results are not remembered• It is important to develop and test file system output with both IE andother browsers, as IE behaves differently than other browsers
  25. 25. Viewing SuiteHelp OutputWith a WebserverTo test your SuiteHelp output using Windows IIS:• Copy your output directory to c:inetpubwwwroot• Browse to http://localhost• You can deploy to an external webserver
  26. 26. Viewing SuiteHelp+ OutputSuiteHelp+ includes its own, light webserver that requires no priorinstallation. To test your SuiteHelp+ output on your client computer:• Copy the SuiteHelpServer.exe file from the suitehelpplus plugin folderinto your output folder:Example: C:DITA-OTpluginssuitehelpplusexewindows• A SuiteHelpServer.exe file is available for Windows, Linux and Mac• Double-click or otherwise launch the SuiteHelpServer.exe• Navigate to http://localhost:3000 in your browser• The search results should now include snippets:vs.
  27. 27. Viewing SuiteHelp StandaloneSuiteHelp Standalone is bundled with its own, light webserver that requiresno prior installation. To view SuiteHelp Standalone:• Double click on suitehelp-standalone.exe in the output directory.• Your browser should open and navigate to your SuiteHelp home page
  28. 28. Viewing Context Sensitive HelpThere are two steps to enabling context sensitivity:• Embed context IDs into the DITA topics• Use the <resourceid> element• Code the context name inside the id attribute.• View the topic• Use a query string parameter named "context".• For example: to open SuiteHelp to the topic whose context ID is"mytopicid":
  29. 29. Deploying SuiteHelpSuiteHelp• Copy all files from the output folder to the client or webserverSuiteHelp Standalone• Copy exe to client machine and launchSuiteHelp+• Copy all files from the output folder to the client or server• Launch SuiteHelpServer.exe• SuiteHelpServer can be run as a Windows service• If using a webserver, configure a reverse proxy• More details are available for deploying with particular webservers suchas IIS, Apache, NGINX, etc.
  30. 30. Questions?Feel free to be in contact: adenaf@suite-sol.comJoin the SuiteHelp Forum!
  31. 31. Keep in Touch!For additional information, contact:Joe Gelbsolutions@suite-sol.comU.S. Office EMEA Office(609) 360-0650