Standard Ebooks

How to Review an Ebook Production for Publication

After an ebook production is completed, it must go through rounds of review before it is published to ensure the appropriate production quality is assured. Reviewers are assigned by the editor-in-chief, and may be a member of the editorial staff, or an experienced Standard Ebooks producer. Below is a helpful step-by-step checklist for reviewers of ebook productions. The checklist is by no means exhaustive, but serves as a good starting point for the proofreading process. Reviewers should keep in mind the standards enumerated in the Manual of Style, and note any discrepancies not listed below. Before any review steps, ensure the most recent version of the SE toolset is installed.

  1. Lint

    Run se lint . at the root of the project directory. If lint surfaces any nontrivial errors, you should direct the producer to fix the errors before proceeding. If there are false positives, the producer should create an se-lint-ignore.xml to suppress the false positives.

  2. Typogrify

    Run se typogrify . at the root of the project directory. The typogrify command is almost always correct, but sometimes not all changes it makes should be accepted. To go over the changes typogrify may have made, run the following git command to also highlight changes made to invisible or hard to differentiate Unicode characters:

    git diff -U0 --word-diff-regex=.

  3. Modernize spelling

    Run se modernize-spelling . at the root of the project directory. Note that this tool may not catch all archaic words. Prudent use of text editor spellcheckers can help picking up some of these. When in doubt, refer to the appropriate authority of spelling as noted in the Manual. Many words that are hyphenated in the past (e.g. to-morrow) are in modern times concatenated. However, these hyphens should all be retained in poetry . That said, obvious sound-alike spelling modernization should be made and accepted.

  4. Semanticate

    Run se semanticate . at the root of the project directory. Unlike se typogrify or se modernize-spelling, se semanticate is more prone to error or false positives. Judicious use of the git diff command listed in Step 1 would be needed to prevent and revert any unwanted changes.

  5. Clean

    Run se clean . at the root of the project directory. Ideally the producer of the ebook would have ran this multiple times during their production process. However, since changes may have been made since then by the producer and stylistic deviations may be been inadvertently introduced, this will clean those potential errors up. After each step so far, it is recommended to use the git diff commanded listed in Step 1 to review and record all changes that are needed.

  6. Check dashes and diacritics

    Run both se find-mismatched-dashes . and se find-mismatched-diacritics . at the root of the project directory. Neither of these tools will make actual changes to the project, but they will list words that have inconsistent application of dashes/diacritics. Check with the language authority listed in the Manual to decide on what recommendations should be made.

  7. Build title, table of contents, and images

    Run se build-title ., se build-toc . and se build-images . at the root of the project directory. No changes should be made by these tools if the producer correctly generated the title page, table of content, and image files. Any discrepancies can be highlighted and investigated via the git diff listed in Step 1.

  8. Review editorial commits

    Use the following git command to highlight all editorial commits:

    git log --pretty="format:%h: %s" --grep="\[Editorial\]"

    Once identified, these commits can be reviewed via:

    git diff "$COMMIT~" "$COMMIT";

    Alternatively, a graphical git client can be used instead.

  9. Review en dash uses

    Run the following command to check for incorrect en dash use:

    grep --recursive --line-number "[a-z]–[a-z]" .

    Note that the dash in between the two square bracket is an en dash (– U+2013), and not a hyphen. Check the Manual for the correct type of dashes to use in different cases. Alternatively, use your text editor's regular expression search to find potential incorrect usage instead of grep.

  10. Review miscurled quotes

    Run the following command to examine possible miscurled single quotes:

    se interactive-replace "(\s)‘([a-z])" "\1’\2" .

    Note the use of ‘ (left single-quotation mark, U+2018) and ’ (right single-quotation mark, U+2019) in the command above, and not ' or `. Using se interactive-replace is the safest as there are many potential false positive cases here that should not be change. Refer the the relevant section of the Manual. Note that sometimes this type of mistakes might be committed by se typogrify. For example:

    <p>He had pork ‘n’ beans for dinner</p>
    <p>He had pork ’n’ beans for dinner</p>

    Note the right single-quotation mark is applied twice under this situation. More cases like this is in the section of the Manual linked above.

  11. Check for punctuation outside quotation marks

    Run the following command to examine punctuation that might have to be moved inside quotation marks:

    se interactive-replace "([’”])([,.])" "\2\1" src/epub/text/*

    In general, periods and commas always go inside quotation marks, both single and double. For example:

    <p>He pronounced it “pleasure”, and as he said it he licked his lips.</p>
    <p>He pronounced it “pleasure,” and as he said it he licked his lips.</p>

    Note the right single-quotation mark is applied twice under this situation. More cases like this is in the section of the Manual linked above.

  12. Review capitalization

    As noted in the Manual text in call caps is rarely correct. Use the following command to check for instance of all caps:

    se xpath "//p//text()[re:test(., '[A-Z]{2,}') and not(contains(., 'OK') or contains(., 'SOS')) and not(parent::abbr or parent::var or parent::a or parent::*[contains(@epub:type, 'z3998:roman')])]" src/epub/text/*.xhtml

    If any such instances is found, check with the Manual for the correct capitalization style in all cases.

  13. Review era abbreviation elements

    Era abbreviations do not have punctuation in them unlike other common abbreviations (see Manual). Use the following command to check each of such cases:

    se interactive-replace "(<abbr epub:type=\"se:era[^\"]*?\">)(BC|AD)</abbr>\." "\1\2</abbr>" .

  14. Review italics and emphasis elements

    The <i> and <em> elements are not to be used interchangeably (see relevant section of the Manual here and here). Use the following command to check their usage in the production (alternatively, use the regular expression search function in a text editor):

    grep --recursive --line-number --extended-regexp "<i|<em" src/epub/text/*.xhtml

    Are there any <i> elements that lack semantics?

    grep --recursive --line-number "<i>" src/epub/text/*.xhtml

  15. Review XHTML file structure

    Do a final look through of each XHTML file for spelling, styling, and formatting discrepancies. Possible things to look out for:

    • Check that the correct semantics for elements are used. (e.g. correct usage of <blockquote>, no <div> blocks are used, etc.

    • If the book is in ”parts,” “books,” or “volumes”:

      • Do the chapters have the right filenames? (See Manual)

      • Does each chapter file include the wrapping <section> element for its corresponding part, for recomposition? (See Manual)

  16. Review local CSS

    Review the local.css file. Possible things to look out for:

    • Any styles that have no effect? (e.g., Setting text-indent: 0; on an element which already inherits that property from core.css)

    • Any unusual classes that can be converted to more clever selectors instead?

    • Any selectors that should use a different pattern according to previous standards? (e.g., setting small caps by targeting a valediction, instead of targeting epub:type="z3998:signature"

  17. Review colophon

    Review the colophon. Possible things to look out for:

    • Are names without links wrapped in <b epub:type="z3998:personal-name">?

    • Are abbreviated names wrapped in <abbr epub:type="z3998:given-name">?

  18. Review metadata

    Review all metadata including those in content.opf. See this section of the Manual for reference. Possible things to look out for:

    • Is author, translator(s), cover artist, etc. in the correct order and in expected style?

    • Check all links, such as author/work Wikipedia links, are correct by opening them in a browser. Sometimes se create-draft guesses the wrong Wikipedia link for a book or person with the same name as another book or person.

    • If the book has a subtitle, check that it is represented as expected. See here for reference.

    • Confirm that the long description of the book in the metadata was not copy and pasted from Wikipedia or other third-party sources.

    • Check that the short description of the book is valid (i.e. a single complete sentence.)

  19. Lint again

    Run a final se lint . check, and ensure it is silent. If any warnings and errors are produced, they must be noted and addressed.

  20. Test epub build

    Run the following command at the root of the project directory to ensure the epub builds:

    se build --check-only .

    Note all errors if they are produced by the command.

  21. Submit review comments

    Log all review notes and recommendations on the production's GitHub repository issue tracker, and inform the producer and the rest of the editorial team the review has been completed, with a short summary of the results of the review and changes that may be needed before publishing.