Table of Contents
This article covers the use of an assembly to describe the hierarchical relationship among pages in a help system, and particularly the use of the type attribute on assemblies to carry information beyond the simple structure of a document. This does not address content reuse, which is covered elsewhere.
| Note | |
|---|---|
This is a very simplified example, but based on a real system. |
This is the help system for a simple documentation build system that has two Web-based screens that allow the user to build documents (books rendered into PDF and chunked HTML and help systems that are delivered with products using a Webhelp type system).
There are four tasks supported by the system. Two screens of help are provided for the screens in the user interface, and the help system organization has to comply with documentation standards.
Help System Structure
Each entry in this list represents a node (HTML page) in the help system.
ToC
Index
Overview (Welcome)
Tasks
Building Documents
Packaging Books for Publication
Packaging Help for Submitting to Product Builds
Packaging Documents (Books and Help) for Localization
Screens and Menus
Document Build Screen
Document Packaging Screen
Printable Version (PDF)
Glossary
Help on Help
In addition to being delivered using Webhelp, a printable version of the help system is delivered with the help system in the form of a PDF generated by walking the structure of the help system. However, the PDF follows the conventions of printed books, putting the index at the back of the book, and does not include the help on help content.
In addition to the files for the Webhelp HTML and Javascript, supplementary files are delivered to allow merging with other help systems and to support integration of the help on screens with the product help buttons. Some of the HTML files are expected to have standard names.
The following example assumes that the Webhelp transform has been extended to support non-chunked generation of the system by passing in a topic for each page to be rendered. The navigational structure will be derived from the assembly.
A very simple set of resources is specified for the help system. The file names are immaterial, and all the referenced file resources are presumed to be topics except the glossary, which is a glossary element (and usually derived from a glossary database).
Example 1. Resources for a Help System
<resources xml:base="some/path">
<manifesttext>Resources for help system.</manifesttext>
<resource xml:id="overview" fileref="overview.xml">
<manifesttext>Overview of help system.</manifesttext>
</resource>
<resource xml:id="task.build.doc">
<manifesttext>Describe how to build a document.</manifesttext>
</resource>
<resource xml:id="pckg.intro" fileref="task-intro.xml">
<manifesttext>Introduction to the packaging tasks.</manifesttext>
</resource>
<resource xml:id="task.package.book.pub">
<manifesttext>Describe how to package a document for publication.</manifesttext>
</resource>
<resource xml:id="task.package.help">
<manifesttext>Describe how to package a help system for submission to product
build.</manifesttext>
</resource>
<resource xml:id="task.package.l10n">
<manifesttext>Describe how to package source files for localization.</manifesttext>
</resource>
<resource xml:id="screen.overview">
<manifesttext>Introductory text for screens and menus section.</manifesttext>
</resource>
<resource xml:id="screen.build.doc">
<manifesttext>Displayed when question mark icon on document build screen is
clicked.</manifesttext>
</resource>
<resource xml:id="screen.package">
<manifesttext>Displayed when question mark icon on packaging screen is clicked.</manifesttext>
</resource>
<resource xml:id="glossary">
<manifesttext>Glossary for help system.</manifesttext>
</resource>
<resource xml:id="help.on.help">
<manifesttext>How to use the help system.</manifesttext>
</resource>
</resources>
The First few lines of the structure set up the general things about the help system:
Example 2. Defining the Basics of the Help System
<structure type="help.system">
<title>XIDI Build System Help</title>
<titleabbrev>XIDI Help</titleabbrev>
<output format="pdf" file="sys-book.pdf" renderas="book"/>
<!-- The PDF output will be rendered into a file expected by the help
system for the printable version of the help system. -->
<output format="webhelp" chunk="false" renderas="topic"/>
<!-- The webhelp output will NOT be chunked and the default render
(wherever a file name is specified) is as a topic. IF the
renderas on an output that is a child of structure is not treated as
a default for specified files, a renderas has to be added to each of
the webhelp output statements in the modules that specify a file. -->
The type attribute provides information
to the render system so that the auxiliary files for merging and
integration are built in addition to the Webhelp system.
The output element for pdf specifies the name of the file to use and
tells the render system to render a book.
The output element for webhelp suppresses chunking and sets the
default value for the webhelp output statements that do not have a
renderas attribute.
By convention, the first two pages in the help system are the table of contents and the index. However, in the book, the index goes in the back.
Example 3. The Front End
<module>
<output format="webhelp" file="sys-toc.html" renderas="topic"/>
<toc/>
<!-- By convention, there is a ToC at the beginning of a help system and
of the PDF of the help system. The delivery system expects the file
to be named sys-toc.html. -->
</module>
<module>
<output format="webhelp" file="sys-index.html"/>
<output format="pdf" suppress="true"/>
<index/>
<!-- By convention, there is an index at the beginning of a help system
but it is expected to be at the end of a book. The delivery system
expects the file to be named sys-index.html -->
</module>
The main content of the help system is broken into an overview (Which can have lower-level topics below the main overview topic), task descriptions, which may be grouped together or appear at the top level if they are considered important enough to the user, and a set of help pages for screens.
Each task description has a task element with a summary, prerequisites, the procedure, and lists of related topics and tasks. Help on screens always includes standard information such as how to navigate to the screen and what tasks the screen is used to accomplish. In complex systems, screens can be grouped together to deal with things like Wizards and related screens and dialogs.
Example 4. Middles Section of Help System
<module resourceref="overview">
<output format="webhelp" file="overview.html"/>
<output format="pdf" renderas="chapter"/>
</module>
<module resourceref="task.build.doc">
<output format="webhelp" file="tsk-build-doc.html"/>
<output format="pdf" renderas="section"/>
</module>
<module>
<output format="webhelp" file="pckg-intro.html"/>
<output format="pdf" renderas="chapter"/>
<title>Packaging</title>
<module resourceref="pckg.intro" contentonly="true" omittitles="true"/>
<module resourceref="task.package.book.pub">
<output format="webhelp" file="tsk-pckg-book-pub.html"/>
<output format="pdf" renderas="section"/>
</module>
<module resourceref="task.package.help">
<output format="webhelp" file="tsk-pckg-help.html"/>
<output format="pdf" renderas="section"/>
</module>
<module resourceref="task.package.l10n">
<output format="webhelp" file="tsk-pckg-l10n.html"/>
<output format="pdf" renderas="section"/>
</module>
</module>
<module>
<output format="webhelp" file="scr-overvw.html"/>
<output format="pdf" renderas="chapter"/>
<title>Screens</title>
<module resourceref="screen.overview" contentonly="true"
omittitles="true"/>
<module resourceref="screen.build.doc">
<output format="webhelp" file="scr-build.html"/>
<output format="pdf" renderas="section"/>
</module>
<module resourceref="screen.package">
<output format="webhelp" file="scr-package.html"/>
<output format="pdf" renderas="section"/>
</module>
</module>
Once the main body of the help system is built, the standard back end components are added.
Example 5. Back End of Help System
<module>
<output format="webhelp"/>
<!-- No file, just want the link in the navigation. -->
<output format="pdf" suppress="true"/>
<!-- Nothing in PDF. -->
<title xmlns:ns1="http://www.w3.org/1999/xlink" ns1:href="sys-book.pdf">Printable Version (PDF)</title>
</module>
<module resourceref="glossary">
<output format="webhelp" file="sys-glossary.html"/>
<!-- The help delivery system expects the glossary to be in a file named
sys-glossary.html.-->
</module>
<module>
<output format="webhelp" suppress="true"/>
<index/>
<!-- By conventions, the index is at the back of a book, but it has
already been presented at the front of the help system. -->
</module>
<module resourceref="help.on.help">
<output format="webhelp" file="help-on-help.html"/>
<output format="pdf" suppress="true"/>
<!-- By convention help on how to use the help system is not included in
the printable version of the help system and is stock, pulled from a
library. -->
</module>
</structure>There are a couple of targets that are meaningful for building the document described by this structure.
Targets for Building the Help System
- build.help
Builds a help system with the following:
Webhelp files, including search index XML files for merging with other help systems Properties files for integrating into product - build.pdf
Build the PDF printable version
- build.all
Build the help system and the printable version
| Note | |
|---|---|
Without a type attribute specifying that the structure is a help system, the auxiliary files would not be built, and the Webhelp transform would likely not be configured correctly to handle topics as the item to be rendered for each HTML page. |