• DevCenter
• Projects
• Emitting Sibling Children for Embedded Navigation

Emitting Sibling Children for Embedded Navigation

Description

I'm moving our Publisher 2003 for FrameMaker production to ePublisher and am running into difficulties in recreating the functionality of some macro customizations that we made as a response to usability-test results.

In what would otherwise be a topic containing only the title of the book, I generate a "mini nav" navigational structure that picks up the title of each chapter and displays it in a table along with summary information from the chapter's abstract. This is done in Publisher 2003 by a series of interconnected macros on several paragraph styles that append to a global variable. If it is defined, the variable is dumped by Normal.asp, then cleared so that it is only emitted in the topic containing the paragraph style "Abstract."

Constraints

For a variety of reasons, not least of which is that WWH is still not our primary delivery format, I cannot require our writers to make modifications to the FrameMaker source files. Therefore this solution will have to be entirely within the ePublisher stationery and depend upon existing paragraph stylenames.

The Challenge

In ePublisher, I need to be able to generate as part of each "book" level topic, a table like the following:

• Topics in this document

  Subject	Description
  Chapter 1	Some text from Chapter 1's abstract that describes what it's about.
  Chapter 2	Text from Chapter 2's abstract...

Where the cells in the left column contain chapter titles that are hyperlinks to the respective chapter-level topics and the cells in the right column contain the text of the respective chapter's abstract.

The Details

We author in Structured FrameMaker, and the relevant structure is something like the following:

<Manual>
 <Cover>                                  <!-- in cover.fm file -->
  <Booktitle>The Book's Title</Booktitle>
 </Cover>
 <Chapter>                                <!-- chapter1.fm file -->
  <Title>Chapter 1</Title>
   :
  <Abstract>Some text from Chapter 1's abstract that describes what it's about</Abstract>
  :
 </Chapter>
 <Chapter                                 <!-- chapter2.fm file -->
  <Title>Chapter 2</Title>
   :
  <Abstract>Text from Chapter 2's abstract...</Abstract>
  :
 </Chapter>
</Manual>

These elements map to the following paragraph styles:

Were I able to process each book according to its XML structure, I could do something like this (using Booktitle as a starting point for this example):

<xsl:template match="Booktitle">
 <xsl:element name="table">
  <xsl:element name="thead">
   <xsl:element name="td">Subject</xsl:element>
   <xsl:element name="td">Description</xsl:element>
  </xsl:element>
  <xsl:for-each select="../../Chapter | ../../Appendix | ../../About">
   <xsl:element name="tr">
    <xsl:element name="td">
     <xsl:element name="a">
      <xsl:attribute name="href">
       <xsl:text>MAGIC TO GET HREF TARGET HAPPENS HERE</xsl:text>
      </xsl:attribute>
      <xsl:value-of select="./Title"/>
     </xsl:element>
    </xsl:element>
    <xsl:element name="td">
     <xsl:value-of select="./Abstract"/>
    </xsl:element>
   </xsl:element>
  </xsl:for-each>
 </xsl:element>
</xsl:template>

Unfortunately I haven't managed to wrap my head around the ePublisher XSL transforms sufficiently as yet to understand how to successfully make queries using the .ifl/ID scheme. It seems as though I should be able to make some XQueries from within content.xsl with a test like <xsl:if test="$VarParagraph/@stylename='BookTitle'"></xsl:if>, but it's just not coming to me.

My relevant Publisher 2003 macros and a chunk of ASP are below. Hopefully this is enough to give the gist of what I need to duplicate. The double-slashed comments are an attempt to explain what's happening in each macro.

• Sample FrameMaker source documents: demo_fm_srcs.zip

• Sample WWH4 output: wwh4_demo.zip

Existing Publisher 2003 Macro/.asp code

// Macros in the paragraph styles below set up the body of a table to be called by Normal.asp
// with the following hidden expansion code. Note that the global variable is cleared after
// expansion:


// hidden expansion fragment from Normal.asp
<!-- begin chapter abstracts -->
$IF_EXISTS($GET_GLOBAL(Links_$PAGE(host,basename););,<blockquote>
<h2 class="pHeading5">Topics in This Document</h2><p/>
<table><tr bgcolor="#c0c0c0">
<td><div class="pCellHeading">Subject</div></td>
<td><div class="pCellHeading">Description</div></td></tr>
$GET_GLOBAL(Links_$PAGE(host,basename););</table></blockquote>,);
@SET_GLOBAL(Links_$PAGE(host,basename);,);
<!-- end chapter abstracts -->

// Publisher 2003 macro fragments

// At the beginning of each book, set up the global variables...
TitleofBook
$COMMENT(Following set_globals for tr bgcolor and tag
completion in cover page chapter list);
@SET_GLOBAL(tr_alternate_color,T);
@SET_GLOBAL(tr_closed,T);
@SET_GLOBAL(PageLevel0,$PAGE(host,basename););
@WRITELOG(============= set PageLevel0==$GET_GLOBAL(PageLevel0); ==========);


// This is the chapter title, which gets wrapped in an href in the left table column
Heading1
$COMMENT(SNPS mod - add chapter title links + abstracts to title page);\
@SET_GLOBAL(PageLevel1,$PAGE(host,basename););\

@SET_GLOBAL(Links_$GET_GLOBAL(PageLevel0);,$GET_GLOBAL(Links_$GET_GLOBAL(PageLev\
el0););\
@IF_EXISTS($GET_GLOBAL(tr_closed);,,</tr>);\
<tr align="left" valign="top"
@IF_EXISTS($GET_GLOBAL(tr_alternate_color);,
bgcolor="White"@SET_GLOBAL(tr_alternate_color,);,
bgcolor="#F0F0F0"@SET_GLOBAL(tr_alternate_color,T););>
<td><div class="pCellBody"><a href="$PAGE(html,
name);">$DATA(raw);</a></div></td>
@WRITELOG(MININAV - added link <a href="$PAGE(html,
name);">$DATA(raw);</a>););\
@SET_GLOBAL(tr_closed,);
@SET_GLOBAL(HeadLevel1,$PAGE(host,basename););

// This is the text of the abstract paragraph which appears in the right table column 
Abstract
$COMMENT(SNPS mod - add chapter title links + abstracts to title page);
@SET_GLOBAL(PageLevel1,$PAGE(host,basename););\
@SET_GLOBAL(Links_$GET_GLOBAL(PageLevel0);,$GET_GLOBAL(Links_$GET_GLOBAL(PageLev\
el0););
<td><div class="pCellBody">$DATA;</div></td></tr>);\
@SET_GLOBAL(tr_closed,T);


// Close the last TR (not all chapters contain abstracts) and finish up the global variable's content
BZOnConvertAllEnd
$COMMENT(SNPS mod - add chapter title links + abstracts to title page...
add final </tr> if it hasn't already been done);\
@SET_GLOBAL(PageLevel1,$PAGE(host,basename););\
@SET_GLOBAL(Links_$GET_GLOBAL(PageLevel0);,$GET_GLOBAL(Links_$GET_GLOBAL(PageLevel0););\
@IF_EXISTS($GET_GLOBAL(tr_closed);,,</tr>);\
);\
@SET_GLOBAL(tr_closed,);

Power Hour - February 2010

Overview

This wiki project was selected as the subject for the February 2010 Power Hour webinar. Cory met with us online, along with quite a few other users, where Ben and Jesse talked through different ways to tackle this issue. Ultimately, it was decided to leverage ePublisher's existing mini-TOC functionality and focus on adding abstract information to the TOC data file.

The session touched upon the following subjects:

• Format definition files (format.wwfmt)
• Files info (files.info)
• Layout of the Data directory
• Type based processing with stages
• Tracing a generated file back to the original .xsl stage through files.info and format.wwfmt
• Review of the TOC data collection pipeline

Project Results

We were able to modify the existing ePublisher format for WebWorks Help 5.0 and achieve something close to the requirements Cory initially outlined. Cory will conduct a further review with the project in his own environment to ensure the solution meets his specific needs.

The project was developed using an in development version of ePublisher 2010.1. It should remain compatible with ePublisher 2009.4 projects and transforms. It may be compatible with older ePublisher transform versions, though this has not been tested.

Session Recording

A recording of the session will be made available as soon as possible.

NOTE: Presently (as of 2010-03-02), the recording is not accessible from our webinar provider. The provider did report an issue with their recording servers. We do not yet know if the session was simply not recorded or if there is only a delay in access. In the future, we will consider using alternate recording options.