The eXtyles XML Export module is designed to produce valid, correct XML to the DTD or schema of your choice. XML Export is very good at what it does—but in any automated process, correct output depends to some extent on correct input! This means that problems in your Word file can create bigger problems in the exported XML.
The good news: Most eXtyles XML Export errors and warnings can be avoided or resolved within Word!
Inera’s Support team teaches a half-day workshop on the topic of XML export issues—nicknamed “What to Expect When You’re Exporting”—to which we can’t possibly do justice in a single blog post. To whet your appetite, we present some useful best practices for ensuring trouble-free eXtyles XML exports!
An ounce of prevention: Pre-export best practices
You can head off many of the most common eXtyles parsing errors and warnings by following these pre-export best practices.
Proof your paragraph styles
Use Word’s Draft view and style margin to answer these questions:
- Are the elements of your file in the correct order?
- Have any paragraph styles been used incorrectly?
- Are any paragraphs styled as Normal?
Setting Up Your Style Margin
To enable this feature in Word, follow these steps:
- From the View tab, select Draft.
- From the File tab, go to Options > Advanced > Display > Style area pane width in Draft and Outline views.
- Set the Style Area Width setting to your preferred width (1 inch is a good starting value).
Once the style margin is open, the style name of each paragraph is displayed to the left of your screen (only in Draft view). You can page or scroll through your document to review the styles applied to each paragraph. To close, dragging the vertical line all the way to the left edge of your Word window, or reset the value to 0 using the steps above.
Be sure you have run required Advanced Processes
In particular, you may encounter parsing errors if you have not run
- Citation Matching
- Author Processing
Pay attention to the comments eXtyles adds
Review all Comments added by eXtyles processes, and resolve them appropriately before exporting. Unresolved citation matching warnings about objects such as tables may lead to parsing errors, depending on your configuration.
Proof your tables
All tables should be whole:
- No split tables (left)
- No nested tables (left)
All tables should be present in the document.
Take charge of your document
What’s in your white space?
To help prevent and resolve parsing errors, make sure you can see what’s really going on in your Word files by showing nonprinting characters (paragraph marks, spaces, line breaks, Hidden text, etc.).
You can use the Hidden Text checker in eXtyles Cleanup to find and resolve hidden text in your Word file, both before editing and just before XML export.
Double-check the metadata in the Document Information dialog
Click Update Document Information
to answer the following questions:
- Is your metadata accurate?
- Are all the relevant fields filled in?
Warning: Stale Metadata
The Stale Metadata Warning feature in eXtyles will warn you before export if the metadata in your document was entered prior to the number of days you’ve specified.
Contact us to learn more about activating this feature in your configuration.
Danger, Will Robinson!: Post-export troubleshooting
If you have XML errors to resolve, the following best practices will help you find and fix the problems more easily:
- To locate and identify errors, view your XML in a text editor for clearer and more convenient navigation. eXtyles automatically opens exported XML files in Word (top), but can be customized to open them in a text editor of your choice (bottom, using Sublime2 as an example):
- To find errors and warnings quickly, search for character combinations used to indicate an XML comment or warning:
- <!
- <!–
- <!– Warning
- <!– Error
- Review Word styles in Draft view:
- Work with nonprinting characters showing to make sure you can see everything that’s going on in your Word file.
- When you find an error, always fix the Word file, not the XML! After fixing the Word file, re-export to get valid and correct XML. (If that doesn’t work, try fixing the Word file again.)
Automating Pre-Export Style Checks with Auto-Redact
With Enhanced Auto-Redact in eXtyles, we can set up rules that will warn you about specific situations involving misapplied styles—for example, when a References heading has been styled as Heading 1, or keywords have been styled as part of the abstract.
Contact us to discuss setting up Auto-Redact rules to speed up your pre-export checks!
What else should I know about XML exports?
There’s so much more to learn!
Could your organization benefit from an eXtyles XML Export Workshop? Contact us at [email protected] to learn more!