Documentation

ScML QC

Check the following to confirm the quality of a .scml file:

Metadata and Validation

File Name

Scribe default: [clientcode-project].scml.

Digital Hub Project Information

All available information should be present in the Hub record‘s Project Information tab.

This includes the following: Title, Publisher, BISAC Subject Codes, Print and E-book ISBNs, Creators and Contributors, and Extended Metadata (Additional Descriptive Data and Additional Titles).

Validating the File

Online validation: The Digital Hub should report no errors.

Local validation: The DTD validation tool in Sublime should report no errors.

Print Comparisons

Distinctive Elements and Character Details

Examples: sidebars, tables, letters, special character styles, and foreign characters,

Special Characters

Do special characters match those in the source?

Except for ampersands and less-than and greater-than signs (which must be HTML entities rather than literal characters), do not use both literal special characters and (decimal or hex) HTML entities in the same .scml file.

Review the stats in the Digital Hub to obtain a list of special characters.

Check the file for combining Unicode characters. There should be no combining Unicode, and ligatures should be converted to the corresponding individual letters.

If necessary, find special characters locally and run the second Find All search, then copy and paste the selected characters into a new document. Permute the file to sort by unique characters, removing duplicates.

Print-Specific Artifacts

Examples: The impression line (10 9 8 7 6 5 4 3 2 1); statements about where or by whom the book was printed; any references to fonts or the physical layout (“the image on the top right”).

Except for projects where the index should be linked or where there are credits for specific pages, references to page numbers within the publication should be modified (so they still make sense when published in a form without fixed page numbers) or commented out.

Examples: “see above” or “below”

For “continued” index entries, have the page IDs been retained and paragraphs recombined?

For “continued” table entries, have all page IDs been retained, duplicate table heads and table column heads removed, and content recombined into a single table?

Structure

Chapter Divisions

Each section (including the title page, dedication, copyright page, and table of contents) should be in its own <chapter id=""> division with a unique ID.

Composition

Structural Elements

See ScML documentation for a complete list of structural elements.

Contiguous elements of the same kind, such as stacked epigraphs or sidebars, should each have their own set of structure indicators.

Front Matter

ISBN(s)

If the ISBNs include hyphens, are they in the correct positions?

If necessary, the following expression can be used to replace en dashes or em dashes with hyphens: \1-\3-\5-\7-\9

Table of Contents

For an ePub, there must be a table of contents in the .scml file (even if the source does not have one).

Figures

Figure Callouts

Example: <img src="scr-example-fig0101.jpeg"/>

The figure structure indicators should enclose each group of figure elements (e.g., fig, figh, and figatr).

Figure file names should only use a file extension of a permitted type (.jpg, .jpeg, .png, or .svg).

Decorative Images and Logos

If a logo image is part of the title page, compose it as bkpub (or bkpub1, if necessary) rather than fig.

If a logo image is part of the copyright page, compose it as crtf (or a different crt style, if necessary) rather than fig.

Footnotes and Endnotes

There should be none.

Internal References

Check a selection of the following (or similar) terms, depending on the project: appendix, box, chapter, chart, example, exercise, figure, illustration, map, part, plate, page, section, see, and table.

Determine how extensively to link internal references based on the project requirements.

URLs

Scribe default: If a general site name is immediately followed by a more specific url, the general site does not require url tags.

The following search is inclusive and might find some abbreviations or file names in addition to URLs.

Examples: em dashes, en dashes, or spaces.

For these to work as links, they will need to be modified again after processing to ePub to include the full link path.

Indexes

Tabs, Ellipses, and Angle Brackets

Tabs

There should be no tabs in a file intended for conversion to ePub.

Ellipses

Note: Some projects may require a consistent treatment of ellipses while others may require variations be maintained.

Three Periods: If three periods in a row must be kept together with no visible space, have zero width nonbreaking spaces been added between the periods?

Spaced Periods: If ellipses consist of spaced periods, have regular nonbreaking spaces been added between the periods?

Ellipsis Character: If required for a project, has the ellipsis character (…) been used consistently?

In most cases, a nonbreaking space should precede the ellipsis to connect it to the preceding text. In some cases, a nonbreaking space should appear after the ellipsis to connect it to the text that follows.

Angle Brackets

Some instances may be correct.

Tag Use

Self-Closing and Unnecessary Tags

Examples: <p/>; <i></i>

Position of Tags and Spaces

Missing Spaces around Tags

Page IDs

If so, the link will not function on Kindle devices.

Replace with: \2\1

If so, move the page ID (including angle brackets) after the opening tag of the next paragraph and remove the line where the page ID was.

Spaces

Typesetter Spaces

The search is not exhaustive. In order to exclude ellipses, it skips any nonbreaking space next to a period.

Hyphen Spacing

Spaces around Punctuation

The following search is inclusive and might find some abbreviations, file names, or URLs in addition to dropped spaces.

Opening and Closing Spaces

Duplicate Spaces

Line Breaks, Small Caps, and Spelling

Unnecessary Line Breaks

Do a “case sensitive” search using the following expression. It is inclusive and might find some lines that correctly begin with lowercase letters.

Small Caps

Find all and paste into a new document to review results.

Spelling

Bible File Checks

For Bible .scml files, perform the following additional checks.

Tetragrammaton

Run the following Find All search, then copy and paste the results into a new document. Permute the file to sort by unique instances, removing duplicates.

Example: The tetr tags should not include "'s"

XBR References

Incorrect: 1 P<sm>eter</sm> <xbr t="1Pe 2:4">2:4</xbr>

Correct: <xbr t="1Pe 2:4">1 P<sm>eter</sm> 2:4</xbr>

The Meshach script often will miss book names and references in ancillary material that have a character style, and those will need to be linked using the Abednego script.

Single-Chapter Books

They should include a “1” in the chapter number position, so the verse number is not misinterpreted as a chapter number.

Example: It should result in <xref idref="v57001007">Philemon 7</xref> (rather than “idref="v57007001"”) for this verse.

In a duplicate of your .scml file, add chapter number to one-chapter books:

Find: (<xbr t=")(Ob|Phm|2Jn|3Jn|Jud|Pr Az|Bel|Sus|Pr Man|LJe)( )([0-9-]+")

Replace with: \1\2\31:\4

Note: LJe (Letter/Epistle of Jeremiah) can also be tagged as a chapter 6; do not change such a reference to chapter 1. For instance, <xbr t="LJe 6:63">Ep. Jer. 6:63</xbr> is legitimate and should not be changed to <xbr t="LJe 1:63">.