From d11e0456ded4a59d944a050978cd770a240dca2e Mon Sep 17 00:00:00 2001 From: Alex Cabal Date: Wed, 2 Dec 2020 13:29:50 -0600 Subject: [PATCH] Update step by step guide to include character-level git diff command --- www/contribute/producing-an-ebook-step-by-step.php | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/www/contribute/producing-an-ebook-step-by-step.php b/www/contribute/producing-an-ebook-step-by-step.php index 4b553b2b..36040d73 100644 --- a/www/contribute/producing-an-ebook-step-by-step.php +++ b/www/contribute/producing-an-ebook-step-by-step.php @@ -267,15 +267,20 @@ proceed to seal up my confession, I bring the life of that unhappy Henry Jekyll

  • Modernize spelling and hyphenation

    Many older works use outdated spelling and hyphenation that would distract a modern reader. (For example, “to-night” instead of “tonight”). se modernize-spelling automatically removes hyphens from words that used to be compounded, but aren’t anymore in modern English spelling.

    -

    Do run this tool on prose. Don’t run this tool on poetry.

    se modernize-spelling . +

    Do run this tool on prose. Don’t run this tool on poetry.

    + se modernize-spelling .

    After you run the tool, you must check what the tool did to confirm that each removed hyphen is correct. Sometimes the tool will remove a hyphen that needs to be included for clarity, or one that changes the meaning of the word, or it may result in a word that just doesn’t seem right. Re-introducing a hyphen is OK in these cases.

    Here’s a real-world example of where se modernize-spelling made the wrong choice: In The Picture of Dorian Gray chapter 11, Oscar Wilde writes:

    He possessed a gorgeous cope of crimson silk and gold-thread damask…

    se modernize-spelling would replace the dash in gold-thread so that it reads goldthread. Well goldthread is an actual word, which is why it’s in our dictionary, and why the script makes a replacement—but it’s the name of a type of flower, not a golden fabric thread! In this case, se modernize-spelling made an incorrect replacement, and we have to change it back.

    -

    git provides a handy way for us to visualize these differences:

    git difftool -

    After you’ve reviewed the changes that the tool made, do another commit. This commit is important, because it gives purists an avenue to revert modernizing changes to the original text.

    +

    git usually compares changes line-by-line, but since lines an ebook can be very long, a line-level comparison can make spotting small changes difficult. Intead of just doing git diff, try the following command to highlight changes at the character level:

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

    You can also enable color in your git output to make the output of that command more readable, and even assign it to a shortcut in your git configuration.

    +

    Alternatively, you can use an external diff GUI to review changes:

    + git difftool +

    After you’ve reviewed the changes that the tool made, create an “[Editorial]” commit. This commit is important, because it gives purists an avenue to revert modernizing changes to the original text.

    Note how we preface this commit with “[Editorial]”. Any change you make to the source text that can be considered a modernization or editorial change should be prefaced like this, so that the git history can be easily searched by people looking to revert changes.

    git commit -am "[Editorial] Modernize hyphenation and spelling"