What to expect when you’re exporting

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:Screenshot from MS Word, showing that the first paragraph of an abstract is styled Normal instead of Abstract

  • 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.

Screenshot from MS Word, showing an eXtyles comment that reads "The table 'Table 3' is not cited in the text. Please add an in-text citation or delete the table."

Proof your tables

All tables should be whole:

  • No split tables (left)
    Screenshot from MS Word showing 2 tables that should be 1 table, with a large red X Screenshot of MS Word showing a correct table, with a large green check mark
  • No nested tables (left)
    Screenshot of MS Word showing a nested table, with a large red X Screenshot of MS Word showing a correct table, with a large green check mark

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.).

Screenshot from MS Word, showing non-printing characters such as tab and paragraph marks

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

Screenshot of the Update Document Information button on the eXtyles ribbon in MS Word

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):
    screenshot of a reference entry in XML markup, in MS Word
    screenshot of a reference entry in XML markup, in a text editor
  • 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:
    Screenshot from MS Word, showing a file 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!