ePublisher Reports

Author:	Ben Allums
Version:	1.1.0
Date:	2006-02-13
Changes:	Since 1.2 Since 1.1 Since 1.0

Abstract

Reporting requirements for ePublisher series products.

Table of Contents

1 Introduction

Taking source documents and transforming them into a desired output format is the definition of the WebWorks family of products. In the past, this goal was limited to transforming source documents into stand-alone help systems, HTML pages, or custom user formats.

During the Publisher time-frame, customers began to use WebWorks products for a very different purpose. The primary focus was not to generate a set of files for deployment. Instead, WebWorks was used as a reporting tool. With only a textual log and red/blue messages, users were able to fashion reports for style compliance, external URLs, topic alias reports, etc. Over time, WebWorks introduced support for testing topic aliases directly from the Publisher GUI as well as useful accessibility reporting.

For ePublisher series products, WebWorks will deliever a common set of reporting facilities. These facilities will define standard report formats and provide a single user interface to enable rich interactions with reports.

1.1 Changes

1.1.1 Since 1.2

Added severity attribute to report entries per Zeid's feedback.
Modified report entry "Details" to work as the "Destination" entry.
Defined changes to .fti files to support GUI functions for generating a single report.

1.1.2 Since 1.1

Initial version of the common XML reports schema.
Questions regarding the common XML reports schema.

1.1.3 Since 1.0

Added baggage files to the list of possible new reports.
Report entry navigation options marked optional.
Added "navigate to URL" to the list of possible navigation options.
Created a Reports section to explicitly list every possible report and define their report entry attributes.

2 Publisher 2003 Reports

By examining the report capabilities of Publisher 2003 series products, it is possible to identify the minimum requirements for ePublisher series products.

2.1 Log Messages

The first report model for WebWorks products was the generation log. Publisher 2003 generated an unresolved cross-reference report by pushing errors to the log window. This simple report was cleared each time a generation was perform. The only way to insure a complete unresolved cross-reference report was to regenerate from scratch.

Model:

List of report entries.

2.2 HTML Files

The HTML file report model was used for "Topic Alias" and "External URL" reports. These reports were always complete. They enabled users to navigate to destinations in generated files.

Model:

List of report entries.
Navigation into generated output.

2.3 Source Document Files

For the WebWorks accessibility report, the "wwaccess" utility created documents (Word or FrameMaker) to hold report entries. Each report entry documented the reason and the associated location of the entry in the source document. Links were provided to further describe the report entry and to navigate to the related source document location.

Model:

List of report entries.
Description of report entry in source document.
Navigation to more information on report entries of a given type.
Navigation to the related source document location.

2.4 XML with Custom GUI

Publisher 2003 handles "Topic Alias" reports in two ways. One, by creating an HTML report. Second, by creating an XML repot. The Publisher 2003 GUI defined custom controls to parse the XML report. These custom controls allowed users to view a list of topic aliases and perform basic sort operations. Finally, the report UI enabled navigation to destinations in the generated output.

Model:

List of report entries.
UI to control the presentation order of log entries (sort controls).
Navigation to the related generated output location.

3 Reporting Requirements

Taken together, Publisher 2003 report implementations yield a set of baseline reports and event requirements.

3.1 List of Reports

Existing Publisher 2003 reports can be identified and categorized as follows:

Built-in reports

Generation events (message, warnings, errors)
Unresolved cross-references
Image issues (missing by-reference graphics, auto-size shapes)
Topics (topic aliases and testing UI)
External URLs
Accessibility issues

Custom reports

Style conformance

Possible new reports

Baggage files
Filename marker usage

3.2 Report Entries

Given the list of reports and existing report models, it is possible to derive report entry requirements.

Required

Entry type
Localized description
Additional information

Navigation (optional)

Navigate to related location in source document
Navigate to related location in output files
Navigate to specified URL

4 Reports

All possible reports and their entries are defined here.

4.1 Generation

Contains any messages, warnings, or errors that are not handled by any other report. Essentially, it is a catch all.

Entry types

Message
Warning
Error

Navigation

None.

4.2 Unresolved Cross-References

Reports missing source documents, link destinations, and/or baggage files.

Entry types

Missing source document
Missing link destination in source document
Missing baggage file

Navigation

Navigate to related location in source document.

4.3 Image Issues

Reports missing by reference graphics and auto-sized inline shapes.

Entry types

Missing by-reference graphic
Auto-sized shape

Navigation

Navigate to related location in source document.

4.4 Topics

Reports list of topic aliases found in source document(s).

Entry types

Topic

Navigation

Navigate to related location in source document.
(Optional) Navigate to related location in output files. Only valid if output generated and there is a supported method to show the topic, i.e. HTML Help API or WWHelp API.

4.5 External URLs

List of URLs that point outside the local file system.

Entry types

ftp
http
https
mailto
Others?

Navigation

Navigate to related location in source document.
Navigate to specified URL (if possible)

4.6 Accessibiliy Issues

Validate source document (via WIF) to insure Section 508 compliance. This method would not validate output files.

Entry types

Missing image alt tag
Missing image map alt tag
Missing image long description
Missing image description links
Missing table summary

Navigation

Navigate to related location in source document.

4.7 Style Conformance

Insure all restricted name lists are obeyed for specified paragraph, character, marker, graphic, table, variable, cross-reference, and condition entities.

Entry types

Non-standard paragraph style
Non-standard character style
Non-standard marker style
Non-standard graphic style
Non-standard table style
Non-standard variable
Non-standard cross-reference
Non-standard condition

Navigation

Navigate to related location in source document.

4.8 Baggage Files

List of files referenced by source document(s) that would be copied if a project were generated.

Entry types

Missing baggage file (covered by unresolved cross-reference report?)
Baggage file

Navigation

Navigate to related location in source document.
Explore to baggage file

4.9 Filename Marker Usage

List of topic names used in source document(s).

Entry types

Filename
Duplicate filename

Navigation

Navigate to related location in source document
Navigate to related output file. May also include navigating to the related output location via a help API.

5 Reports Schema

Given the requirements for report entries, it is possible to define a common schema for all Redstone reports. Since this schema will be used for all reports and the report entries could be "mixed" into a single report, all entries will be defined with both a type and a context. The context indentifies the target report for a given report entry.

5.1 Schema Proposal

Namespace:

urn:WebWorks-Reports-Schema

Elements:

<Report>
<Entry>
<Source>
<Destination>
<Details>

Attributes:

<Report>

version

<Entry>

context
type

<Source>

documentID
ID

<Destination>

protocol

<Details>

A simple example:

<Report xmlns="urn:WebWorks-Reports-Schema" version="1.0">
 <Entry context="accessibility" type="image-alt-tag-missing">
  <Source documentID="2343423" ID="7878778" />
  <Destination protocol="wwhapi">
   <Context value="interesting" />
   <Topic value="conversation" />
  </Destination>
  <Details>
   What ever you like.
  </Details>
 </Entry>

 <Entry context="external-url" type="http">
  <Source documentID="B343423" ID="A878778" />
  <Destination protocol="uri">
   <Link xmlns="urn:WebWorks-Reports-URIEntry-Schema" value="http://www.webworks.com" />
  </Destination>
  <Details />
 </Entry>
</Report>

5.2 Questions

Should elements within the <Destination> namespace use the reports namespace "urn:WebWorks-Reports-Schema" or their very own.

Individual reports may do as they like.
Should the external URL report have unique types per protocol or just use "uri" for everything?

URL report will support "uri" and "file" to determine if a browser or Windows Explorer will be used to display the file.

6 Incorporating GUI Requirements

Zeid reviewed the 1.2.0 version of this document and suggested the following improvements.

6.1 Schema Proposal Refined

Report entry elements will define a severity attribute:

<Entry context="accessibility" type="image-alt-tag-missing" severity="warning">
 ..
</Entry>

<Destination> elements will use the @class attribute instead of @protocol to identify their contents. WebWorks will implement the following classes:

file:
  <Destination class="file">
   <File value="D:\\food court.txt" />
  </Destination>

uri:
  <Destination class="uri">
   <Link value="http://www.webworks.com/" />
  </Destination>

wwhelp5:
  <Destination class="wwhelp5">
   <BaseURI value="file://myhelp" />
   <Content value="blue" />
   <Topic value="moon" />
  </Destination>

Optional classes:

htmlhelp10:
  <Destination class="htmlhelp10">
   ... whatever HTML Help 1.0 requires ...
  </Destintation>

The <Detail> element will now work the same as the <Destination> element. This will allow complete step-by-step instructions for things like the Accessibility report or unique messages per report entry.

Both the <Destination> and <Detail> elements are optional. <Source> elements are always required.

6.2 FTI Hints

To support GUI requirements for on-demand reports and locking controls, .fti files will add the following:

A @parent attribute can be used instead of a @group attribute. This allows the GUI to nest the attribute underneath the parent for display and lock-down control.
The @parent attribute takes priority over @group attributes. If @parent is defined, @group is not processed.
The @pipeline attribute ties a group to a defined format pipeline. This enables the GUI to communicate to the engine a minimal amount of work to perform.

Taken together, these changes would restructure an .fti from:

<!-- Accessibility -->
<!--               -->
<Setting name="accessibility-report" group="accessibility" default="false">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-alt-tags" group="accessibility" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-map-alt-tags" group="accessibility" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-long-descriptions" group="accessibility" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-table-summaries" group="accessibility" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-d-links" group="accessibility" default="false">
 <SettingClass name="boolean" />
</Setting>

to:

<!-- Accessibility -->
<!--               -->
<Setting name="accessibility-report" group="accessibility" default="false" pipeline="Accessible">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-alt-tags" parent="accessibility-report" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-map-alt-tags" parent="accessibility-report" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-long-descriptions" parent="accessibility-report" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-table-summaries" parent="accessibility-report" default="true">
 <SettingClass name="boolean" />
</Setting>
<Setting name="accessibility-image-d-links" parent="accessibility-report" default="false">
 <SettingClass name="boolean" />
</Setting>

These changes allow the GUI to determine on-demand pipelines within a format.

7 Post Meeting Changes

During review, Zeid suggested the <Source> element include a @path attribute back to the source document. Additionally, it was recognized that the <Description>/<Message> element was missing.

Here is an updated example:

<Report xmlns="urn:WebWorks-Reports-Schema" version="1.0">
 <Entry context="accessibility" type="image-alt-tag-missing" severity="warning">
  <Description>
   Image missing alternative text.
  </Description>
  <Source path="C:\Documents and Settings\user\Desktop\Great Idea.fm" documentID="2343423" id="7878778" />
  <Destination protocol="wwhelp">
   <BaseURI value="file://myhelp" />
   <Context value="interesting" />
   <Topic value="conversation" />
  </Destination>
  <Details protocol="wwhelp">
   <BaseURI value="file://application/help" />
   <Context value="fix" />
   <Topic value="me" />
  </Details >
 </Entry>

 <Entry context="external-url" type="http" severity="message">
  <Message>
   Link to external URL http://www.webworks.com.
  </Message>
  <Source path="C:\Documents and Settings\user\Desktop\Great Idea.fm" documentID="B343423" id="A878778" />
  <Destination protocol="uri">
   <Link value="http://www.webworks.com" />
  </Destination>
 </Entry>
</Report>

8 Futher Discussions

Zeid and I discussed various ways to inform the GUI of available reports and to hint the engine has to how to perform conversions which exclude certain pipelines:

<Pipeline name="Accessibility" stringid="access" action="true" actiongroup="reports" skippable="true" >
  <ActionGroups>
    <ActionGroup name="reports" stringid="report_id_group" />
  </ActionGroups>
</Pipeline>

Part of the goal here is to allow the Preview to become just another stage in the pipeline and therefore allow it to use the same WIF document as the normal generation process.

9 Tasks

The Format schema will be extended to include Tasks. Each Task will be implemented via a particular Pipeline. In the Engine runtime, transforms will be able to ask if a particular Pipeline was a primary task pipeline or a dependant task pipeline. This will enable a user to specify certain reports, say Accessibility, to not be generated during "Generate All", but still enable it if directly requested. Further, this would enable a "Preview" pipeline to live within the format itself and therefore share WIF files with the normal generation process.

The Format schema will include:

<Format>
 <Tasks>
  <TaskGroup name="reports" stringid="reports">
   <Task name="styles_report" stringid="styles_report" />
  </TaskGroup>
 </Tasks>

 <Pipeline name="StylesReport" task="styles_report">
  ...
 </Pipeline>
</Format>

Per discussions with Zeid:

<Format>
 <TaskGroups>
  <TaskGroup name="reports" stringid="reports">
   <Task name="styles_report" stringid="styles_report" pipeline="StylesReport" />
  </TaskGroup>
 </TaskGroups>

 <!-- No changes to existing pipelines -->
 <!--                                  -->
 <Pipeline name="StylesReport">
  ...
 </Pipeline>
</Format>

We like it!

DevCenter/Documentation/Reports_Design (last edited 2008-02-13 06:18:22 by localhost)