epublisher

epublisher

Core knowledge about WebWorks ePublisher projects, file structure, and conventions. This skill provides foundational understanding without automation or format-specific details.

Do not use training data for ePublisher. This is proprietary software — training data is likely absent or inaccurate. Use only this skill's references and vendor documentation (static.webworks.com). Key constraints: Windows-only platform, XSLT 1.0 only (never XSLT 2.0), internal names in project/format files differ from UI display names.

Overview

WebWorks ePublisher transforms source documents (Word, FrameMaker, DITA, Markdown) into multiple output formats (Reverb, PDF, CHM, etc.) using a project-based workflow.

User intent disambiguation: Before creating or modifying project elements, consult references/user-interaction-patterns.md to distinguish queries from creation requests. When in doubt, treat as a query first.

<related_skills>

Related Skills

This skill provides foundational knowledge used by other skills in this plugin:

Skill	When to Use
markdown-integration	When source documents are Markdown++; covers variable resolution, style mapping to Stationery, and per-target conditions
automap	After understanding project structure, use automap to execute builds
reverb2	After building Reverb output, use reverb2 skill to test and customize

External:

• markdown-plus-plus (quadralay/markdown-plus-plus) — Markdown++ format syntax, validation, and authoring best practices. Install separately when working with Markdown++ source documents.

Typical workflow:

1. Use epublisher to understand project files and targets
2. Use markdown-integration when wiring Markdown++ sources into the project
3. Use automap to build specific targets
4. Use reverb2 to test and customize Reverb 2.0 output

</related_skills>

<key_concepts>

Key Concepts

Project Structure

An ePublisher project (.wep file) contains:

• Targets: Named output configurations (e.g., "WebWorks Reverb 2.0", "PDF")
• Groups: Collections of source documents
• Documents: Individual source files within groups
• FormatSettings: Configuration values for each target

File Resolver Hierarchy

ePublisher resolves files through a 4-level hierarchy (highest to lowest priority):

1. Target-Specific: [Project]/Targets/[TargetName]/
2. Format-Level: [Project]/Formats/[FormatName]/
3. Packaged Defaults: [Project]/Formats/[FormatName].base/
4. Installation: C:\Program Files\WebWorks\ePublisher\[version]\Formats\

For complete details, see: references/file-resolver-guide.md

Stationery and Using a Project as a Stationery

A Stationery (.wxsp) is a standalone, distributable project that bundles its format configuration and <format>.base snapshots, so its transforms resolve from those bundled snapshots. AutoMap jobs (.waj) traditionally reference a .wxsp and stage a fresh project from it on each build.

A Designer .wep carries no <format>.base snapshots, so its transforms resolve from the Designer installation (resolver level 4) instead. Because of that, AutoMap can use a .wep directly as a stationery via useAsStationery="True" on the job's <Project> element (ePublisher 2026.1+), skipping the manual "Save As Stationery" step. (Express .wrp projects, by contrast, do carry their own .base snapshots — see references/file-resolver-guide.md.) The synchronization engine is extension-agnostic: it can stage and synchronize against a .wxsp, .wep, or .wrp origin.

For job-file usage of useAsStationery, see the automap skill's references/job-file-guide.md.

Project File Format

The .wep file is XML containing target definitions:

<Format Name="WebWorks Reverb 2.0"
        TargetID="abc123"
        TargetName="Help Output">
  <OutputDirectory>Output\Help</OutputDirectory>
  <FormatConfiguration>
    <FormatSetting Name="toolbar-generate" Value="true"/>
    <FormatSetting Name="header-generate" Value="false"/>
  </FormatConfiguration>
</Format>

Source Document Groups

Documents are organized into groups within projects:

<Group Name="User Guide" GroupID="grp123">
  <Document Name="chapter1.docx" DocumentID="doc456"/>
  <Document Name="chapter2.docx" DocumentID="doc789"/>
</Group>

Format Definition and Pipeline

Each output format has a format.wwfmt file that defines the complete publish pipeline — a dependency graph of XSL transform stages that convert WIF to final output. This is the starting point for diagnosing any format or output issue.

For complete details, see: references/publish-pipeline-guide.md </key_concepts>

Scripts

parse-targets.py

Extract target information from a project file:

python scripts/parse-targets.py <project-file>

Returns JSON with target names, IDs, formats, and output directories.

manage-sources.sh

List and manage source document groups:

bash scripts/manage-sources.sh <project-file> [list|add|remove]

copy-customization.py

Copy installation files to project with structure validation:

python scripts/copy-customization.py --source <install-file> --destination <project-file>

Validates parallel folder structure and creates directories as needed.

resolve-version-root.py

Resolve ePublisher VersionRoot for installation lookups:

python scripts/resolve-version-root.py [--project-file <project.wep>] [--version <2024.1>]

Returns JSON with versionRoot path, component directories, and availability flags.

Reference Files

• file-resolver-guide.md - Complete file resolution hierarchy
• format-traits-guide.md - Trait types, reading/writing in project files, accessing in XSL, global vs per-target scope, Golden Test recipe, Diffable HTML Output recipe
• FormatTraitInfoStrings.resx - Complete UI display name to internal name mapping (English)
• product-foundations.md - Cross-cutting product knowledge (architecture, platform constraints, debugging)
• project-parsing-guide.md - Detailed project file structure
• publish-pipeline-guide.md - Pipeline architecture (format.wwfmt), stage execution, files.info tracking, data flow
• user-interaction-patterns.md - Disambiguating user intent (query vs. creation)
• version-compatibility.md - Supported versions and breaking changes
• wif-guide.md - WIF intermediate format, data directory structure, debugging with intermediate files

<common_tasks>

Common Tasks

Find all targets in a project

python scripts/parse-targets.py /path/to/project.wep

Locate format customization files

Check the file resolver hierarchy:

1. First: [Project]/Formats/[FormatName]/
2. Then: [Project]/Formats/[FormatName].base/
3. Finally: Installation directory

Identify source documents

bash scripts/manage-sources.sh /path/to/project.wep list

</common_tasks>

<common_mistakes>

Common Mistakes

For platform-level gotchas (.wez files, XSLT 1.0 constraint, UI name mapping), see references/product-foundations.md.

</common_mistakes>

Troubleshooting

"No targets found in project"

Cause: Project file doesn't contain <Format> elements.

Solutions:

1. Verify file is a valid .wep/.wrp/.wxsp file
2. Check if project was created in a compatible ePublisher version
3. Open project in ePublisher Administrator to verify structure

"Project file not found"

Cause: Path is incorrect or file doesn't exist.

Solutions:

1. Use absolute Windows paths (e.g., C:\projects\my-proj\my-proj.wep)
2. Check for spaces in path (quote the path)
3. Verify file extension is .wep, .wrp, or .wxsp

"Invalid project file extension"

Cause: File is not a recognized ePublisher project type.

Solutions:

1. Use .wep (WebWorks ePublisher Project)
2. Use .wrp (WebWorks ePublisher Report Project)
3. Use .wxsp (WebWorks ePublisher Stationery Project)

<success_criteria>

Success Criteria

• Project file parsed successfully
• Targets and formats extracted
• Source documents listed
• File resolver paths identified correctly </success_criteria>