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.
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 five
years
• Extensive expertise implementing DITA and CMS solutions for a wide
variety of organizations
• Responsible for internal training and mentoring for developers at Suite
Solutions
• Help companies get it right the first time
3. About Suite Solutions
Our Vision: Enable companies to engage their customers by providing quick
access 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. SuiteShare: Dynamic Publishing
Taking the Leap to a New Paradigm
• Variety of content: documentation, videos, how-to articles, safety
information, data sheets, marketing material
• Context filtering: quick, goal-oriented access to contextually relevant content
• Personalized docs: allow readers to assemble content on demand and
render to PDF for print and eBook for offline mobile access
• Audience Participation: allow your audience to add new content, comment
on existing content, express approval, and easily share knowledge with
others 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
6. Technical Architecture
Preprocessing
• Performed by the DITA Accelerator
• Greater efficiency, accuracy, and speed than the DITA-OT
pre-processing, overcoming known bugs and architectural constraints
Generation 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 to
leverage your existing XHTML customizations
SuiteHelp User Interface and Search Generation
• Performed by the DITA Accelerator
• Includes nav-bar, header, footer, breadcrumbs, and overall UI format
• Extensively customizable
7. SuiteHelp Process Flow
Using Native HTML5 Generation
Using DITA Open Toolkit XHTML Generation
Note: As of version 1.7.1 the DITA-OT is starting to support HTML5
8. Options for Generating HTML Topics
Native 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 (no
DITA Toolkit, Java, etc.)
• Higher performance
• Lowers barrier to entry: Knowledge of HTML and CSS are the only
prerequisites to customizing HTML5 output.
• significantly lower learning curve
• produce high-quality customized HTML5 output without requiring
practitioners skilled in languages such as ANT, XSL, XPath or Java
DITA 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.
10. Installing SuiteHelp with the DITA Toolkit
Unzip the SuiteHelp release package and copy the SuiteHelp plugin
folders into the DITA-OTplugins folder:
• suitehelp – contains suitehelp.exe and the core SuiteHelp presentation
files
• suitehelp-libs – contains ICU DLLs (Internationalization Components
for Unicode)
• suitehelp-customization – contains default SuiteHelp skin formatting
files
• 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. 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 DITA
Toolkit
Contains SuiteHelp plugins and license
XML Catalog file that references
the DTDs in the dtd directory
Contains DITA DTDs
Windows batch files for
running SuiteHelp
Location of temporary files
Location of DITA Source
Location of SuiteHelp output
12. Generating SuiteHelp Without the DITA
Toolkit
1. Sample batch files are provided to generate output.
2. Provide the relative location and name of your input ditamap file as the
second argument in suitehelp.bat
For example:
suitehelpsuitehelpexesuitehelp.exe --source
sourcetaskbook.ditamap
3. Set outputclass=“homepage” on one of the topicrefs in your input
ditamap. The generated index.html page will redirect to this file.
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. Generating SuiteHelp Output
Using the DITA Toolkit
• Using ANT
1. Run integrator: ant -f integrator.xml
2. Run the DITA Toolkit using the transtype: suitehelp
• Using Java
Call dost.jar, for example:
java -jar lib/dost.jar /transtype:suitehelp
/i:samples/taskbook.ditamap
Note: when you call dost.jar, integrator is run automatically
Note: when using Java, you may not add any SuiteHelp specific
parameters; therefore, we recommend using ANT
15. Generating SuiteHelp Output
Using the DITA Toolkit
• By default, HTML topics are generated using the DITA Toolkit style sheets
(dita2xhtml)
• To generate HTML topics using Native DITA Accelerator formatting
1. Open the configuration file in a text editor:
pluginssuitehelp-customizationsuitehelp-conf.xml
2. Remove the comments around the <classmap> element
<!-- Uncomment to use native DITA Accelerator Formatting
<classmap>classmap.yaml</classmap>
-->
16. Generating SuiteHelp Directly Using the
SuiteHelp Executable
Run 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 file
Example from suitehelp.bat:
suitehelpsuitehelpexesuitehelp.exe
--source sourcetaskbook.ditamap
--tempdir temp
--outdir output
--suitehelp-conf
suitehelpsuitehelp-customizationsuitehelp-conf.xml
17. Generating SuiteHelp Standalone
Using the DITA Toolkit
• Be sure the suitehelp-standalone plugin has been unzipped into your
plugins folder
• Generate SuiteHelp output
• SuiteHelp is packaged into a Standalone executable
18. Generating SuiteHelp Standalone
Using the SuiteHelp Executable
1. Generate SuiteHelp using suitehelp.bat
• Output from suitehelp.bat becomes input for suitehelp-standalone
2. Run suitehelp-standalonesuitehelp-inject.exe with the following
arguments
1. Location of templates directory
2. Location of output directory
3. Location and name of the resulting executable
3. Run suitehelp-standaloneupx.exe with the following argument to
compress the initial executable:
1. Location and name of the suitehelp-standalone executable
19. Generating SuiteHelp Standalone
Using the SuiteHelp Executable
Example from suitehelpstandalone.bat:
suitehelpsuitehelp-standalonesuitehelp-inject.exe
suitehelpsuitehelp-standalonetemplates
output
outputsuitehelp-standalone.exe
suitehelpsuitehelp-standaloneupx.exe
outputsuitehelp-standalone.exe
20. Verifying SuiteHelp Standalone
Generation
When generating SuiteHelp Standalone output, you should see the following
message 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. Generating SuiteHelp+
Using the DITA Toolkit
• Be sure the suitehelpplus plugin has been unzipped into your plugins
folder
• Generate SuiteHelp
• You should see a search-index.sqlite file in the output folder
Note:
• If both the suitehelpplus and suitehelp-standalone plugins are in the
plugins folder, both the search-index.sqlite and suitehelp.exe will be
generated if you generate SuiteHelp using the DITA Toolkit
22. Generating SuiteHelp+
Using the SuiteHelp Executable
1. Run suitehelp.bat
• Output from suitehelp.bat becomes input for suitehelpplus
2. Call suitehelpplusexecreate-index.exe with the following arguments:
1. Location and name of the resulting sqlite database
2. Location and name of input xml file
Note: The file names should not be changed. Use the values that are in
the suitehelpplus.bat file for these parameters.
Example (from suitehelpplus.bat):
suitehelpsuitehelpplusexecreate-index.exe
outputsearch-index.sqlite
tempsearchinfo.xml
23. Viewing SuiteHelp Output
From a File System Without a Webserver
From a Webserver
With SuiteHelp Plus
With SuiteHelp Standalone
24. Viewing SuiteHelp Output
From the File System Without a Webserver
• Navigate to the output directory.
• Open index.html in your browser
Note:
• In general, when viewing SuiteHelp without a web server, AJAX cannot
run, 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 and
other browsers, as IE behaves differently than other browsers
25. Viewing SuiteHelp Output
With a Webserver
To 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. Viewing SuiteHelp+ Output
SuiteHelp+ includes its own, light webserver that requires no prior
installation. To test your SuiteHelp+ output on your client computer:
• Copy the SuiteHelpServer.exe file from the suitehelpplus plugin folder
into 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. Viewing SuiteHelp Standalone
SuiteHelp Standalone is bundled with its own, light webserver that requires
no 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. Viewing Context Sensitive Help
There 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":
http://www.acme.com/suitehelp/index.html?context=mytopicid
29. Deploying SuiteHelp
SuiteHelp
• Copy all files from the output folder to the client or webserver
SuiteHelp Standalone
• Copy exe to client machine and launch
SuiteHelp+
• 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 such
as IIS, Apache, NGINX, etc.
30. Questions?
Feel free to be in contact: adenaf@suite-sol.com
Join the SuiteHelp Forum! www.suite-sol.com/forums
31. Keep in Touch!
For additional information, contact:
Joe Gelb
solutions@suite-sol.com
U.S. Office EMEA Office
(609) 360-0650 +972-2-993-8054
www.suite-sol.com