OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [docbook] DocBook Technical Committee Meeting Minutes: 18August 2010


I did not see an agenda yet for today's meeting, so I am replying to the minutes from the last meeting.

Attached is a description of creating a help system using an assembly.  This is in response to Open Action Item e.  I have also attached a ZIP of the XML source of the assembly that is presented in pieces in the write-up.  

I moved my description attribute content on resources to manifesttext elements, to deal with the L10N concerns.  I also found that the output element is no longer a valid child of the structure element, which it was when I was developing the original, and I assumed that was a coding error in the schema so I put it in anyway.

The compact spacing on the itemized list I used for part of the description did not work in the version of the transforms shipped with oXygen, so the list is not what I intended, but the content is there.  I suspect icons for admonitions will be missing.

Larry Rowland

-----Original Message-----
From: Bob Stayton [mailto:bobs@sagehill.net] 
Sent: Wednesday, August 18, 2010 4:27 PM
To: DocBook Technical Committee
Cc: docbook@lists.oasis-open.org
Subject: [docbook] DocBook Technical Committee Meeting Minutes: 18 August 2010

DocBook Technical Committee Meeting Minutes: 18 August 2010

The DocBook Technical Committee met on Wednesday, 18 August 2010 at
01:00p EDT (10:00a PDT, 17:00GMT, 18:00BST, 19:00CEST, 02:00JST+,
022:30p India+).

1. Roll call

Paul Grosso, Nancy Harrison, Scott Hudson, Gershon Joseph,
Jirka Kosek, Bob Stayton, Norm Walsh

Regrets: Dick Hamilton, Larry Rowland

2. Accepted the minutes [1] of the previous meeting.
3. Next meeting: 15 September 2010

This was changed to 22 September 2010.

4. Review of the agenda.

Add item 10b for API extension elements.

5. Review of open action items

  a.  Norm to develop a proposal for maintaining the DocBook websites.

  b.  Larry to render the current reltable example from
      Bob and Norm with the current assembly elements for

  c.  Jirka to further develop proposal for transclusion in DocBook.

  d.  Norm to release DocBook 5.1b2 and announce it more widely.

  e.  Larry to create a sample of @type in an assembly.

6.  Publishing Subcommittee report.

The second review period of the publishers schema passed
with no new issues.  The Committee resolved and approved
it as a Committe Specification.  

ACTION: Scott to pursue official OASIS publication as a Committee Spec.

7.  eLearning Subcommittee report.

They did not meet this month.  Still working on assembling use
cases so requirements can be developed.

8.  Reltables in modular DocBook.


9.  Transclusion in DocBook.

Please see Jirka's updated proposal and discussion thread. [2]

Jirka summarized the current proposal. Quite a bit of detail
was needed for the problem of duplicate ids when content is
included more than once. 

Gershon noted that the processing is complicated, but it is a
necessary complication to handle all the cases.

Norm asked about transformations from other vocabularies
during transclusion.  The Committee decided that was
out of scope, and should be done at the assembly level.

Next steps: Committee members will experiment with it for
a month. At the next meeting decide if we should include
it in the next DocBook 5 beta.

ACTION: Paul to consider implementation details.

ACTION: Jirka to email his open questions to the TC list.

10.  Release of DocBook 5.1 beta.

Norm completed the release of DocBook 5.1b2, but did not
announce it on the public docbook mailing lists.
He will correct that.

10b.  API extensions.

One project of the Google Summer of Code was developing
schema extensions for documenting programming APIs.
The developer asked the Committee about whether these should
be in the DocBook namespace, or a separate namespace?

The Committee felt that people are free to develop extensions
that make use of the DocBook namespace, because of the complications
in mixing namespaces.  However, the Committee wants to
distinguish between ad hoc extensions and those that are
reviewed and approved by the Committee as part of the
DocBook standard 11.

ACTION: Bob to write up a short policy statement about
the use of the DocBook namespace.

Review of Requests for Enhancement

    To browse a specific RFE, enter the URL (on one line):


    RFEs to revisit for 6.0
      1907003  biblioid content model too broad  

    RFEs to be considered 
      1679665  Add better support for modular documentation  
      2820190  add a topic element  
      2820947  Ability to transclude text 
      2935829  Expand content model of sidebar 
      2964576  disallow table in entry  
      3035565  Allow sections at any level  

The only new item was 3035565.  Bob pointed out that this was
motivated by a need for modular source files, but pointed out
that the assembly mechanism would be better.  

ACTION: Bob to respond to the RFE.


[1] http://lists.oasis-open.org/archives/docbook-tc/201007/msg00031.html
[2] http://lists.oasis-open.org/archives/docbook-tc/201007/msg00041.html

Bob Stayton
Sagehill Enterprises

To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org

Title: Describing Help Systems with an Assembly

Describing Help Systems with an Assembly

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.


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.

The Resources

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 xml:id="task.build.doc">
      <manifesttext>Describe how to build a document.</manifesttext>
    <resource xml:id="pckg.intro" fileref="task-intro.xml">
      <manifesttext>Introduction to the packaging tasks.</manifesttext>
    <resource xml:id="task.package.book.pub">
      <manifesttext>Describe how to package a document for publication.</manifesttext>
    <resource xml:id="task.package.help">
      <manifesttext>Describe how to package a help system for submission to product
    <resource xml:id="task.package.l10n">
      <manifesttext>Describe how to package source files for localization.</manifesttext>
    <resource xml:id="screen.overview">
      <manifesttext>Introductory text for screens and menus section.</manifesttext>
    <resource xml:id="screen.build.doc">
      <manifesttext>Displayed when question mark icon on document build screen is
    <resource xml:id="screen.package">
      <manifesttext>Displayed when question mark icon on packaging screen is clicked.</manifesttext>
    <resource xml:id="glossary">
      <manifesttext>Glossary for help system.</manifesttext>
    <resource xml:id="help.on.help">
      <manifesttext>How to use the help system.</manifesttext>

Setting Up the Structure

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.

Standard Front End

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

      <output format="webhelp" file="sys-toc.html" renderas="topic"/>
      <!-- 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. -->
      <output format="webhelp" file="sys-index.html"/>
      <output format="pdf" suppress="true"/>
      <!-- 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 -->

Main Body of the Help System

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 resourceref="task.build.doc">
      <output format="webhelp" file="tsk-build-doc.html"/>
      <output format="pdf" renderas="section"/>
      <output format="webhelp" file="pckg-intro.html"/>
      <output format="pdf" renderas="chapter"/>
      <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 resourceref="task.package.help">
        <output format="webhelp" file="tsk-pckg-help.html"/>
        <output format="pdf" renderas="section"/>
      <module resourceref="task.package.l10n">
        <output format="webhelp" file="tsk-pckg-l10n.html"/>
        <output format="pdf" renderas="section"/>
      <output format="webhelp" file="scr-overvw.html"/>
      <output format="pdf" renderas="chapter"/>
      <module resourceref="screen.overview" contentonly="true"
      <module resourceref="screen.build.doc">
        <output format="webhelp" file="scr-build.html"/>
        <output format="pdf" renderas="section"/>
      <module resourceref="screen.package">
        <output format="webhelp" file="scr-package.html"/>
        <output format="pdf" renderas="section"/>

Standard Back End for the Help System

Once the main body of the help system is built, the standard back end components are added.

Example 5. Back End of Help System

      <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 resourceref="glossary">
      <output format="webhelp" file="sys-glossary.html"/>
      <!-- The help delivery system expects the glossary to be in a file named
      <output format="webhelp" suppress="true"/>
      <!-- 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 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. -->

What Happens

There are a couple of targets that are meaningful for building the document described by this structure.

Targets for Building the Help System


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 the PDF printable version


Build the help system and the printable version


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.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]