Documentation

Word Scribing

Use the Word Scribing procedure to check file integrity, apply styles, and review content.

Expectations and Best Practices

Word scribing can vary by manuscript and by the preferences of the person doing the work. Some people may prefer to use style galleries and find-and-replace while others may prefer to use keyboard shortcuts. The scribing procedure as presented is meant to guide users through the best default practices and provide information about the available tools both in and out of Word. In some cases, it is necessary to approach the file in a particular order, like running the Rendering tool before applying the paragraph styles. In other cases, a step can be done at any point, as long as it is done before the file is considered complete.

  • Work in Draft view unless otherwise indicated.
  • Activate the Styles pane to view the styles applied to selected text.
  • PC Only: When vetting files, click the Options button in the lower right of the Styles pane and enable Font formatting. Scroll through the list on the right for unique formatting that is unlikely to get caught during the course of scribing. This will commonly be displayed as a “+” with a description after the style name. When finished vetting, turn off the Font formatting option for a cleaner Styles pane menu.

Note: The cleanup actions are not all recommended for every project. For example, in math and legal texts, it is often advisable not to run the dashes cleanup. Additionally, some “errors” or nonstandard treatments may need to be retained to match the source material or represent an intentional choice by the author.

Vetting and SAI Preparation

SAI Version

Confirm that the current version of the SAI is installed.

  • The current SAI version number is listed on the Downloads page, or it can also be seen within the SAI. Go to User Options > View ReadMe and click “Check Online for SAI Updates.”
  • Add or update user settings such as keyboard shortcuts as needed.
  • Review the options available in the SAI toolbar and context menu.

Vetting, Specifications, and Initial File Checks

Identify publisher- or project-specific instructions and specifications.

  • Identify if the file must match its source material exactly, preserving any textual errors that may be discovered.
  • Identify which cleanup options may be required or helpful.

Scroll through the file.

Confirm all material is present or identified as TK.

Note the styles to be applied and potential issues. Plan for how to apply the styles.

Track changes must be turned off, with all changes accepted.

Note: If necessary, use the SAI Merge Documents tool to combine files. Before merging files, it is critical to render all character styles and convert list leaders to live text before merging; otherwise, rendering and list numbering information may be lost.

The file must be a .docx file. If it is not using this extension, go to File > Save As... and select File Format: Word Document (.docx).

Upload the .docx file to the Digital Hub. Note all file alerts and review the file stats in the Digital Hub.

  • Expect to see Non-ScML and Unstyled Content warnings in unscribed files.
  • Check for the presence of incorrect characters and unexpected styles.

Run the SAI’s Vet File tool.

  • Identify punctuation inconsistencies or special Word elements.
  • Note any hidden text.

Note: The SAI’s File Check tool may be run at this time, but it will mainly repeat information reported by the Digital Hub. This tool is primarily intended for users who do not have access to the Digital Hub.

Create or open one or more style galleries.

Use the Automatically Advance Cursor feature to move the cursor to the next group of similarly formatted paragraphs.

Add the styles that will be used in the scribing to the user-created style gallery. (Default style galleries cannot be changed.)

Note: Style galleries are saved independently from individual manuscripts. When possible, use available style galleries that contain all or most of the needed styles.

Prepare the File

Load ScML styles.

Review and resolve potential issues with embedded images, equations, and footnotes/endnotes.

Embedded Images

If the SAI’s Vet File tool reports that the file has embedded images, replace them with callouts.

Search for inline and wrapped images using Find > Graphics in the Navigation pane. If the file only has inline images, search for them using ^g. Switch from Draft view to Print layout view when searching for embedded images.

  • If there is only one or a few images, save the images individually and use Insert Image to add a callout.
  • If there are many embedded images, using the Digital Hub’s Retain MS Word Images setting may be the best option.
  • Note: If Retain MS Word Images is enabled, any graphics remaining in the Word file will be replaced with callouts during conversions through the Digital Hub, with the graphics saved into the project’s image assets. This setting should be considered a safety net and is disabled by default.

Word Equations

If there are Word equations (or expressions) in the file, apply the appropriate output settings per the project specification. If equations need to be converted using MathType, do so now.

If the equations meet the following criteria, use plain text:

  • Simple, single-line equations
  • Characters that have a single Unicode equivalent

To convert equations to plain text:

  • Search for equations using the Navigation pane. Skip any instances that cannot be recreated without MathType (e.g., square roots, polynomial fractions, single variables with both a superscript and a subscript attached).
  • Copy the equation to be converted and paste it without formatting (Ctrl+Shift+V) next to the original. Confirm all characters are present and have not moved significantly.
  • Apply the eq paragraph style.
  • Apply character styles to match the original as needed.

Note: Do not break up complicated equations, even if part of the equation could be represented as plain text. If one section needs to be handled using MathType, the entire equation must be handled this way.

See Word Equations for recommendations and instructions for working with MathType. Consult Scribe for assistance with this process, if needed.

Footnote/Endnote Mismatches

If the Digital Hub indicates a footnote or endnote mismatch:

  • Process the file to .sam or .scml to see if the counts resolve.
  • If the notes do not resolve, see Tracking Down Note Mismatches for methods of finding the missing or extra content.
  • Use the alerts tab of the Note Manager to identify footnote/endnote issues.

Apply Styles

Run initial cleanups to apply ScML character styles.

Note: Some users may find it beneficial to run these initial cleanups as part of the Vetting and SAI Preparation steps.

  • Run Scribe Group 1: Initial Prep from the Cleanup menu.
  • Use the Associate Styles option to convert non-ScML styles to ScML styles. If there are non-ScML character styles in the document that cannot be mapped to a single style and should not be retained, select the “Overwrite non-ScML character styles” option.
  • Run the cleanups for fields and, if necessary, list leaders.

Note: At any point, use the SAI’s Autoscribing or Find and Replace features when the text patterns in the file allow for it. Autoscribing options include scribing heads automatically based on the table of contents, scribing lists or embedded footnotes/endnotes that use Word’s built-in styles, and applying paragraph-specific character styles like fighn or dispk.

Note: If a file has multiple list sublevels, has several numbered list paragraphs (e.g., nlp), or has Word lists being used for nonlist text or specialized lists (e.g., sbbl), run the list leaders cleanup and scribe the lists manually. Otherwise, scribe the lists automatically using the Autoscribing option or by using the Refiner when indicated in the scribing procedure.

Scribe Non-p Paragraphs

Only scribe the paragraph styles that the Refiner cannot apply automatically.

Do not scribe the following:

  • p, pf, paft, or td paragraphs.
  • Paragraphs that use Word’s built-in list or note styles (“Endnote Text,” “Footnote Text,” or “List Paragraph”). These paragraphs will be changed to the appropriate style at a later step. Only scribe these elements if they have been used incorrectly in the file.

Do not scribe spacing variations (f, l, s, or o) for most elements. Identify only the structural aspects of the paragraphs. A later step will use the Refiner to add the spacing variations. Only articulate styles that require manual attention. This typically includes the following:

  • Copyright data
  • Stanza breaks in poetry
  • Certain elements in the Table of Contents, such as a Conclusion or Epilogue chapter that appears after the chapters associated with a Part
  • An a-head appearing at the beginning of the Notes window (scribe as ahaft)

Scribe all other non-p paragraphs, using the SAI’s Autoscribing features whenever possible.

  • Scribe the front matter.
  • Scribe the part titles, chapter titles, and heads.
  • Scribe the footnotes and endnotes.
  • Scribe the lists.
  • Scribe the remaining paragraph styles (e.g., senselines, block quotes, table column heads).
  • Scribe the space-break paragraphs (e.g., psec, psep, poetry stanza breaks).

Note: Issues may be seen when applying styles that would also be found by file review steps later in the process. Address issues (e.g., disconnected paragraphs) when noticed.

While scribing a document, the SAI provides tools and shortcuts to assist with scribing either linearly or by structural element.

Scribing Linearly: To proceed linearly, open the style gallery to be used. To automatically select, review, and scribe each non-p group of paragraphs in the body text, set the following Autoselect checkboxes under Automatically Advance Cursor:

  • Autoselect Next Paragraph Formatting Group
  • Skip ScML Paragraph
  • Skip Likely <p> Paragraph

Scribing by Structural Element: If a distinct element recurs throughout the document, use Word’s Find and Replace options to systematically tag several instances of the element at once. The SAI includes options to assist with finding content and applying ScML styles, including the following:

  • SAI Find and Replace: Find and replace expressions can be built, tested, and saved for future use.
  • Context Menu: Right-click on a paragraph and choose one of the options to automatically populate the formatting of a Word Find and Replace search. Use formatting information loaded into the Find window as a starting point when creating specific searches tailored to the particular manuscript.
  • Style Shortcut Drop-Down Menu: Use shortcuts to facilitate the use of shortcut keys and loading find and replace options into the Search window.

Scribe Figure Callouts

Use the SAI’s Insert Image tool to add figure callouts and, if available, short descriptions (alt text).

Scribe Special Character Styles

Apply character styles that require manual attention.

This may include the application of embedded head styles (hemb/chemb) that the tools identified as bold (b) or applying tetragrammaton (tetr) to text that was identified as small caps (sm).

If required, granular language tagging can be included by using the Language Scribing procedure.

If required, apply Accessibility Styles.

Structure Tags

Insert structure indicators where needed using the SAI’s Structure Indicators and Chapter Structure buttons.

Insert structure indicators to group or separate complex structures. Structure indicators do not need to be inserted for elements that follow the default behaviors of paragraph groups.

Cleanups

In the Cleanup menu, run Scribe Group 2: Pre-Refiner.

Check for incorrect usage of spaces, tabs, and soft returns. Note if this reflects intentional formatting to be maintained through unique styles (e.g., tabs or spaces showing how to align poetry).

  • Tabular data using tabs should be converted to tables.
  • The spacing after the number or bullet in list styles should be standardized as either a tab or a space.
  • Soft returns should be converted to hard returns or removed as unnecessary. No soft returns should remain in a scribed Word document.
  • Run the Space and Break Cleanup options (Spaces, Paragraphs, Tabs) as necessary.

Run the publisher- or project-specific cleanups for ellipses, ligatures, quotation marks, and dashes as required.

Select from the following:

  • Periods to ellipses / Ellipses to spaced periods / Periods to spaced periods
  • Latin ligatures to character pairs
  • Single quotation marks
  • Double quotation marks
  • Dashes
  • Soft returns to hard returns

Note: As changes are applied, it may be necessary to rerun cleanups (e.g., running the spaces cleanup after the ellipses cleanup).

Run the appropriate Punctuation Rendering option.

Run Vet File and review the results. Confirm that the file meets the publisher- or project-specific requirements.

Use the alerts tab of the Note Manager to identify footnote/endnote issues.

Note Numbering and Note Heads

If required, use the Note Manager to add Word section breaks and/or change global note numbering settings.

Adjust Note Numbering

  • Open the Note Manager tool.
  • Select Update footnote / endnote renumbering as required.
  • Select Numbering format to choose the set of markers to use throughout the document. Choose numbers, Roman numerals, letters, or symbols.
  • Change Numbering to Continuous or Restart each section depending on whether the numbering should continue throughout the document or restart at each chapter.
  • Change the Location of endnotes if required to insert them at the end of each section in the Word file.
  • If required, select the option to “Add period to ennum” or “Add period and tab to ennum.”

Add Note Heads

If the project requires a-heads in the note sections but does not yet include them, select Add a-heads for each chapter in the notes.

  • If there are a-heads in the notes section that should be removed before generating new ones, select Remove current a-heads.
  • Choose the number format for heads to use when a chapter contains both a chapter number and a chapter title.
  • Select Add section breaks before ScML chapter styles if the notes are to renumber by section or if adding heads to the document.

Refine in the Digital Hub

Upload the file to the Digital Hub.

Review the Digital Hub File Alerts. (It is expected to see an indication that non-ScML paragraph styles are present at this time.)

  • If there are any mismatches in en/enref/ennum or fn/fnref/fnnum counts, do not refine the document. Review the file and resolve any issues.
  • Warnings about hidden text, nested tables, or structure indicators should be addressed and resolved prior to Hub conversions to other file formats.

Convert to Refined MS Word document.

Download and review the refined file alongside the source.

Note: In a scribed manuscript, all paragraphs use a roman base font. If all instances of a paragraph style (other than the ser styles) render with a character style like i or b, use the SAI’s Change Base font tool to reverse the rendering.

If needed, internal queries, author queries, or typesetter notes can be added as Word comments using the SAI’s Insert Query feature. Queries will include straight quotes that will be listed as potentially incorrect characters in the Digital Hub warnings. Word comments are listed as non-ScML styles “annotation reference” and “annotation text.”

Scribing Quality Review

Methods for Reviewing Files

Upload to the Digital Hub. Review the stats and address any alerts and warnings as necessary.

Process to ePub 3. Review the .docx, .sam, and .scml stats and address any relevant alerts and warnings as necessary. Repeat this process until all issues have been handled (resolved or noted for follow-up).

Note: If processing multiple .docx files, they will be combined into a single .scml file in the Digital Hub.

Review the file using the Scribing QC Checklist and other project specifications.

Note: When scribing an index, combine the index with the full book as indicated in the Index Checking procedure.

Using Sublime, run Check 1: Text Patterns and Check 2: Titles, Phrases, Alt Text, and Indexes on the .scml file.

Use the files created by the conversion to ePub to discover potential errors through Hub stats, conversion alerts, and reviews in Kindle Previewer and Ace by DAISY.

Address any editorial considerations as required (fix or note instances as indicated by publisher- or project-specific instructions).

  • Mismatched punctuation (quotation marks, parentheses)
  • Double quotation marks inside double quotation marks
  • Missing punctuation from the end of bibliography entries
  • Incorrect letter casing of heads and titles
  • Potential errors found by reviewing titles/phrases using Scribe’s Sublime checks
  • Incorrect spacing around punctuation (extra spaces and missing spaces)
  • Invalid URLs
  • Hyperlinks applied to non-URL text (if keeping hyperlinks only as a reference to add citations in editorial steps, remove the url character style from this content).
  • Consistency of elements across a series

Note any content changes that were not done by cleanup tools (e.g., adding missing quotation marks).

Note the use of any pcust, ccust, and wl styles being used in the document, as well as any other styles being used in a nonstandard way (e.g., bq1f acting like bqf but including a first-line indent). The Word template will render each style in its default way, even if it will be presented differently when defined in InDesign or an ebook’s CSS.

Apply corrections or note potential errors as required.

  • If performing the scribing task, resolve all errors or note for follow-up as necessary.
  • If performing quality control, list all errors, queries, and suggested corrections.

Review the file and upload it to the Digital Hub, again processing it to ePub 3. Review the scribing and confirm all issues have been addressed.

Methods for Applying Changes

Determine the best environment in which to apply changes.

  • Apply changes to the .docx file.
  • Apply the changes directly into a .sam or .scml file and convert that file to .docx.

In all cases, upload the file to the Digital Hub and process to ePub 3 to confirm that the changes have not resulted in any new or unexpected errors. Check the relevant aspects in .sam, .scml, and .epub as needed.

Scribing QC Checklist

File Format and Naming

Files must be saved as .docx for use in the Digital Hub.

If multiple files, are they named to sort consecutively?

Track changes should be turned off.

SAI File Checks

Use the File Check tool and review Note Manager warnings.

Digital Hub and Sublime Text Checks

Convert the .docx to ePub 3 in the Digital Hub. This will produce .sam, .scml, and .epub files.

Confirm that all characters use unique Unicode entities.

Confirm that all alerts/warnings will be addressed or do not apply to the current stage of the project.

Run Check 1: Text Patterns and Check 2: Titles, Phrases, Alt Text, and Indexes on the .scml file.

Note: Some searches will result in false positives.

Note: Errors may be discovered through Hub stats, conversion alerts, and reviews in Kindle Previewer and Ace by DAISY.

If Kindle Previewer’s Run Quality Checks tool indicates any dead URLs, have they been noted or addressed per the project specification?

Extraneous Comments and Tags

Remove Word comments that have been resolved through scribing.

Self-closing tags can often be disregarded in Word scribing, with the exception of <fnref/>, <enref/>, <fnnum/>, and <ennum/>.

Paragraphs

There should be no empty paragraphs.

Disconnected paragraphs should be combined.

Unique paragraphs must be broken by hard returns, not soft returns.

Titles and Heads

Are all titles and heads using the proper case?

If a cover image is available, does the text in the file match the text used on the cover?

Do the heads match the TOC?

Check formatting, head level, spelling.

Structure Indicators

ScML Usage

Every paragraph must use an ScML style.

Every character style variation must use an ScML style (e.g., i and b for italic and bold text).

The proper articulation must be used.

Space breaks and indentation must be indicated through ScML styles.

Front matter and back matter style variations must be used and correspond between the TOC and body sections.

Have paragraph-specific character styles been applied as needed?

Has the url style been applied as needed?

Custom and nonstandard ScML style usage must be noted.

Footnotes and Endnotes

Endnotes associated with tables should be table notes.

The counts for en/enref/ennum or fn/fnref/fnnum should match.

If a note paragraph is missing or TK, a query note should be added in its place.

Accessibility Styles

Check the Language Scribing and Accessibility style requirements.

Figures and Images

Is alt text present and accurate?

Are the corresponding figure heads or captions placed properly and formatted consistently?

Tables and Tabs

All tables should be in table format, with paragraph styles applied to each line.

For tabbed lines, only one tab should be used between each separated element (as in TOCs and lists).

If the project is ebook-only, all tabs should be converted to spaces or deleted as appropriate.

Troubleshooting

Tracking Down Note Mismatches

If the number of en/enref/ennum or fn/fnref/fnnum do not match even after processing to .sam or .scml, this indicates one of the following scenarios:

  • There is extra content, or a style has been applied where it should not be.
  • There is missing content, or a style has not been applied where it should be.

Note: If the number of instances of the ennum style is exactly double or triple the number of enrefs, this is likely due to an issue with the underlying XML of the .docx file. It will typically resolve to match when processed to .sam or .scml, in which case no further action is needed. Though less common, it is also possible that there are multiple ennum and enref errors that could lead to the counts matching despite being applied incorrectly.

Examples shown refer to endnotes. Perform these checks in a .sam file.

Check for self-closing tags. If the enref or ennum character styles are applied to spaces, the result will be a self-closing tag (<enref/> or <ennum/>) that is included in the style counts.

Compare lists of enref and ennum.

With regular expressions turned on in Sublime, do a “find all” search for:

  • <enref>([0-9]+)
  • <ennum>([0-9]+)

Copy and paste the results into two columns of an excel file. Compare the two columns to identify where the numbers do not match, and then identify their location within the scribed file.

Isolate extra tags by removing expected patterns.

If the number of en paragraphs does not match the number of ennum, search for “<en><ennum>” and delete all instances. Search individually for any remaining instances of <en> or <ennum> to identify where there are missing or extra styles.

Rendering Issues in Word

If a Word document has ScML styles applied but does not render as defined by the Scribe Word Template, this may indicate that the .docx file is corrupted in some way. This can typically be solved by processing the file to .sam and then back to .docx in the Digital Hub. The Word document created by the Digital Hub from the .sam source will use only default settings for rendering, with no additional overrides.