Archive for the ‘Technical Communications’ Category

WebWorks Help and the MOTW

Monday, March 10th, 2008

Many of you who create online help for your products will run into this problem.

When Microsoft gained world domination sometime in AD 2002, every black hat larcenous computer criminal wannabe started gunning for Windows XP, which had just become the de facto world standard operating system. It’s still on 90% of the desktop machines out there.

Microsoft’s response was a flurry of disorganized activity, since the real problem was Internet Explorer’s habit of loading helpful ActiveX controls and BHOs. You can easily lock up a Windows system with a firewall or combined firewall and new application monitor like ZoneAlarm, but you can do little about a browser that serves as an open door for any malware wanting to impregnate it. Backward compatibility, you know. It’s a legitimate business reason and the purpose of this article isn’t to criticize it.

After the consequent security updates, Internet Explorer took a more rigorous approach to security zones. For the purposes of this article, we’re going to look at one of its most dramatic changes, which was to lock down the ability of the browser to load local HTML files, and secondarily, to cripple those from running JavaScript. If you try to load these pages, you get an annoying yellow bar at the top of the page requiring you to click OK to load the page.

Knowing that this would cause problems for many of us, and not least of all their own systems, Microsoft created a work-around called “Mark of the Web” or MOTW. This is a small token placed in the header between the DOCTYPE and the HTML open element:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "">
<!-- saved from url=(0014)about:internet -->

The MOTW format is a HTML comment with “saved from url=”, the number of characters of the URL to follow in parentheses, and then the URL, which can be either a domain, a specific page, or the sneaky work-around of a work-around above which is a generic field.

There are two of these work-arounds of the work-around (WOTW) that you can use. The first allows the HTML to be run in Internet Explorer’s Internet Zone:

<!-- saved from url=(0014)about:internet -->

The second will run the HTML in the Intranet Zone:

<!-- saved from url=(0014)http://localhost/ -->

For an explanation of security zones, see Setting Up Security Zones and How to use security zones in Internet Explorer.

Naturally, there are some problems with MOTW:

  • MOTW pages will not load HTML pages without MOTW.
  • MOTW pages will not load other types of files (PDFs, DOCs).
  • Every page must have the MOTW, which can be time consuming.
  • You have three alternatives (WOTW^2):

  • Build an HTML application instead of HTML files
  • Create a program that launches the browser and feeds it a default page that uses a meta refresh or JavaScript refresh to load the first page of your local site.
  • If you need to link non-HTML files from your MOTW’d pages, link first to an HTML file and use the EMBED or OBJECT tags to place your non-HTML content in that page.
  • It is the last of the three we’re going to focus on here, specifically, how to link to a PDF file from a MOTW-enabled HTML page. PDF files cannot have embedded MOTW, so any link to a PDF file does not work (in that icky way that Internet Explorer now forces on us, where no error message or indicator lets us know the click didn’t work; it’s the computational equivalent of the silent treatment).

    For each PDF file you have, create an HTML file that can EMBED it, following this template:

    <!-- saved from url=(0014)about:internet -->
    <html style="margin:0;padding:0;">
    <embed src="test.pdf" width="100%" height="100%"></embed>

    This will load the PDF inside the HTML window, and not trouble you further.

    Additional resources:

  • Local zone registry fix – edits your registry to allow HTML content in the local zone.
  • PDF embed script – run this script to create an embedding page for all PDF files in a directory
  • Manually merged help on WebWorks ePublisher Pro

    Wednesday, February 20th, 2008

    This blog post is more of a scribble with some valuable information that at least to me seemed hard to find. The short answer is that you follow the instructions in the WebWorks Help 3.0 guide, and do a bit of trial and error to update that format. The slightly longer answer is this list.

    Manually merged help can be created by taking two or more existing help systems (not their source files), and combining them with a little sleight of hand and the aid of a nifty little program called wwhelp5.exe, which is what indexes the content in each help system. Merging help systems allows them to share a table of contents, an index, and a search engine. You might use this approach if you have several projects, and your best customer orders three of them and wants them to share a help system.

    1. Create a new folder for your merged project, and copy every top-level folder which contains content (as opposed to code, a.k.a. the wwhdata and wwhelp folders) to the merged project folder.
    2. Go into one of your top-level folders which contains content, and copy the wwhelp folder, wwhelp folder, and index.html file, and paste them at the root of your merged project folder.
    3. In the root of your merged folder, go into the wwhelp folder, and open the file books.xml in a text editor.
      1. Find xml entries that look like <Book directory=”folder-name” >. Change these entries to point to your top level content folders, relative to the root (if your folder in the root is named EatingCrow, enter directory=”EatingCrow”).
      2. Find the text showbooks=”false” and change it to showbooks=”true.”
    4. In the root of your merged folder, go into the wwhdata folder, open the xml folder, and open the files.xml file in a text editor.
      1. Find xml entries that look like <Document title=”folder-title” href=”folder-pathname” />
      2. Change these to use the correct title (shows up in table of contents) and href to your top-level folders with content, but append this suffix to each /wwhdata/xml/files.xml.
    5. In each top level folder, open the wwhdata folder, open the common folder, and then open towwhdir.js in a text editor. Locate the line that reads { return “” } and replace it with return { “../” }
    6. Open a command window (Start->Run->”cmd”) and type a variation on this command:
      “C:\Program files\WebWorks\ePublisher Pro\Helpers\WebWorks\wwhelp5.exe -wwhdata “C:\path-to-merged-project\wwhdata” -wwhelp “C:\path-to-merged-project\wwhelp”

    That’s it. I apologize for the hasty nature of these notes, but they contain everything necessary to get a moderately experienced WWeP user up and running with this procedure.