• DevCenter
• Projects
• WebWorksHelp
• AppleMacHelp

Notes on using WebWorks Help on a Mac

Notes on using WebWorks Help on a Mac

WebWorks Help was used to build a help file for software on the Apple Mac.

Note: This is an early draft and needs tidying up, and it's my first attempt at a wiki page, but it seems worth sharing.

Introduction

ePublisher was used to provide Help for the Apple Mac, OSX Mountain Lion and later.

The 'shell' for the help file was built as described in the two documents listed below.

It was tested with an app called HelpTester.app, essentially a mock help file able to capture emitted context IDs.

Format

After testing, WebWorks Help 5 (WWH5) was chosen as it could support context sensitive help via TopicAlias markers, and related topics popups.

The double pane format is not that frequently used on the Mac. However, ITunes uses it, so it is not unacceptable.

Of the other formats, Simple HTML was too plain, Dynamic HTML did not support Related Topics as we wished, and Reverb could not be used locally.

Background Information

The following Apple documents were used for information on Apple style:

Apple Publications Style Guide

https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf

Apple Help Programming Guide - User Experience: Help Technologies

http://developer.apple.com/library/mac/#documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_intro/user_assistance_intro.html%23//apple_ref/doc/uid/TP30000903

Fonts and Paragraph Styles

The frequently used Mac font Lucida Grande was chosen. This was present in Safari for Windows, up until version 3.2.3 released on May 12, 2009.

* Set a single font (here Lucida Grande) in Prototype 'Properties' - it is then inherited by all in the target. (For some reason setting it in Target Properties did not have the required effect.)

* Use the font family Sans Serif as an additional font. This acts as a fall back. Also add Helvetica and Arial as they are part of the standard set.

Note: If Lucida Sans is used as the substitute font, with no other font or family listed, the font on the Mac reverts to Times New Roman - the browser default font.

Header Icon

The header for each page in the Help file is preceeded by an image representing the program.

There are two possible solutions to this - either add a Bullet to the Heading paragraph styles, or add a Background

Image at the top left.

I found the Background Image solution to work better, as the image should be slightly larger than the text line.

* In Page Styles, set the Target Properties for Default as follows:

• Add an image (here called SystemLogo.png) to the Files Folder for the project Set Tiling to No repeat Set the Position to Custom settings such that it fits in front of the Heading. Set the Margin and the Padding on the Header styles such that they 'look right'.

Other Method

Add an image before all 'page break' Headers. Do this in Target Properties | Paragraph Styles | Bullet. Place the image used in the Files Folder for the project. (This is a quick and dirty solution. The image has to be the same height as the Heading - and this is not quite 'authentic').

We also made a custom Skin, as described in the WWH5 documentation, so that it would blend in with the Mac look.

Zapf Dingbats

Zapf Dingbats may well not be present on the Mac, so if you have used a Dingbat as a Character style for a bullet (etc.) replace it with a graphic. In Properties/HTML use Visibility:Hidden for the Character Style, then add a bullet in the form of a graphic.

XHTML vs. HTML 4.01

Mac Help ideally wants HTML 4.01, not XHTML, although the front page *should* be XHTML. However, we found that using the XHTML produced by ePublisher seemed to give no problems.

Implementing Context Sensitive Help

The Mac does not use the equivalent of a resource.h file, so the IDs for context sensitivity had to be embedded in the text of the help file.

An override was made to the file Content.xsl to do this. (The base text used was in version 2011.3. Unchanged as of 2012.2.)

This text:

• <xsl:template match="wwdoc:Marker" mode="wwmode:textrun">

  • <xsl:param name="ParamSplits" /> <xsl:param name="ParamCargo" /> <xsl:param name="ParamLinks" /> <xsl:param name="ParamSplit" />

was replaced with this text:

<xsl:template match="wwdoc:Marker[@name = 'TopicAlias']" mode="wwmode:textrun">

• <xsl:param name="ParamSplits" /> <xsl:param name="ParamCargo" /> <xsl:param name="ParamLinks" /> <xsl:param name="ParamSplit" />

  <html:a>

  • <xsl:attribute name="name">

    • <xsl:for-each select="./wwdoc:TextRun/wwdoc:Text">

      • <xsl:value-of select="@value" />

      </xsl:for-each>

    </xsl:attribute>

    <xsl:text> </xsl:text>

  </html:a>

The crucial change for the purposes of context sensitive help is: [@name = 'TopicAlias']

As a result of doing this, the name of the ID (here "EditNotes") is emitted as a link around a blank space, thus:

• <div class="Heading_3h"><a name="1192540">Notes<a name="EditNotes"> </a></a></div>

Inelegant it may be, but the Mac copes with it perfectly well.

Original idea for this at: http://wiki.webworks.com/DevCenter/Projects/WebWorksHelp/UsingTopicIdentifiers/Discussion

Use TopicAlias as for HTML Help.

Changes to Links

Color changes were made to links at the top of the file webworks.css to fit in with the Mac way of doing things.

Thus:

a:link:hover { color: #333399; text-decoration: underline;}

a:link { color: #333399; text-decoration: none;}