Use of typographic quotes or "smart quotes" in the Web Almanac

[tunetheweb]

Part of our editing process is to convert typographic (or so-called "smart" or "curly") quotes and apostrophe's to straight quotes (“ -> ", ” -> ", ‘ -> ', ’ -> ').

This has caught some authors by surprise so I want to make authors more aware of this, explain the reasoning, and also possibly open this up for discussion if we, as a project, want to change this. However I should caveat that last part, by saying that I do not believe now is the right time to make this change - we are all very busy trying to reach the finish line with less than a month to complete our chapters for the launch so do not believe we should be making this change before then for the reasons I'm about to give.

There are good reasons to use smart quotes (primarily, they look nicer), but there are also many good reasons not to use smart quotes. The Web Almanac uses the Google Developer Style Guide for the Web Almanac and it recommends straight quote marks and gives reasons for this:

Straight and curly quotation marks

Most typefaces support two forms of quotation marks and apostrophes: straight marks and curly, or typographic, marks. Some tools, like Google Docs, automatically convert straight quotation marks and apostrophes to the curly versions as you type. However, our guidance is to always use straight quotation marks and straight apostrophes, for these reasons:

• It's easy to get the direction of curly quotation marks (especially apostrophes) wrong. Using straight marks avoids this problem.
• Code requires straight marks.
• Many writers use coding tools (for example, Subversion) for working directly with markup. Because these tools do not produce curly marks by default, the writer must manually insert the marks, which is error prone.

I'm not sure if you've even noticed this, but if look at many of Google's technical posts (e.g. those on web.dev) they use straight quotes. Similarly I'm not sure how many of you noticed the convention we use, despite having (presumably) read the 2019 edition.

Some more reasons to use this to supplement those:

• GitHub (where most of this project is managed) doesn't make the differences the most obvious
• It's MUCH easier to edit for consistency – just do 4 search and replaces (“ -> ", ” -> ", ‘ -> ', ’ -> ') to convert to straight quotes, but much, much harder to go the other way around. Especially when we do include code in our markdown that cannot handle quotes.
• Using straight quotes may not look as nice, but is not wrong. However, using the wrong curly quote (e.g. opening quotes, when you meant to use closing quotes) is wrong. Similarly switching between smart and plain quotes in within a chapter, or even within the Almanac is inconsistent and so also the wrong thing to do.
• Not all authors may use (or even be aware!) of these smart quotes which makes the editing process much harder. We want authors to concentrate on their writing and not items like this. At the same time, putting this burden on editors (who often get squeezed right at the end as timelines slip) is a large effort for them.
• The chapter must be written in Markdown which is much better handled in a code editor than a word processor. Typing these quotes in GitHub and code editors (which do not auto-convert) is more difficult and time consuming.
• While we advise to start writing in Google Docs (which automatically converts to the appropriate smart quote), not everyone does, and even when they do, substantial changes and edits happen in GitHub through pull requests and the like.
• Many, many, many people touch each chapter. From Authors, Reviewers, Editors, Translators (in many languages) to those random typo corrections we receive (and encourage).
• If we want to change this, we would need to revisit all the 2019 chapters to maintain consistency. A quick search shows 94 lines with double quotes, and 440 lines with single quotes in the English chapters alone, but due to the way we include paragraphs on a single line there will likely be multiple instances per line (at least opening and closing quotes for the double quotes anyway!). That's a huge effort.
• The final point may be controversial to the typography people in our team, but IMHO as a native English speaker, this really isn't that important in English (we'll get to other languages in a bit).

Those are all good reasons for why we do what we do.

However, to present the arguments for the other side:

• It just looks nicer for those that do notice!
• We are primarily a written publication, rather than a coding website. We should strive for the best writing – including typography.
• We are an annual publication, so there are a limited chapters to manage here.
• We strive for excellence in just about every other way, from the experts we use, the data we scrutinise, the editing we do, the fast/accessible/quality website we build. So why not use the best quotes?
• We have typography experts involved who clearly care about this!
• We have allowed smart quotes in the translations. This is for several reasons: it's my opinion these are more important in other languages which make much more use of apostrophe's, accents and other typography, we are under much less time pressure for these, and a lot less hands touch these chapters (typical translation teams are 1,2 or even 3 people) who can all agree and monitor their own use of this.

I hope that explains a bit more background about this situation, it's pros and cons, and why we do what we do. I'm not 100% sure we've made the right decision here, and can see the arguments for both sides. However, I am also aware of the considerable effort to support this properly. I don't like to use my maintainer card often, but will raise it on this occasion, because we maintainers may feel the consequences of the issues expressed above well beyond the short-term pain of getting the English chapters live each year.

I'd be interested to hear other's opinions on this subject.

[rviscomi]

Whatever we chose, I think we'll need a linter or other automated system to detect and automatically convert one style to the other.

[rviscomi]

I've heard good things about https://github.com/markdown-it/markdown-it and its typographer setting to convert straight quotes to curly without affecting code blocks. Worth a look. I'd much prefer a tool that does the conversions for us than a linter that only complains when we get it wrong.

I'd be supportive of changing our standard to curly quotes between 2020 and 2021 editions. As a prerequisite to that, I would like to see a proof of concept of the build/linter tool's ability to convert straight quotes automatically. Asking around, I've also heard that when doing this it's best practice to author in straight quotes and defer to the tools to convert to the appropriate quote, since open/close are different in a curly world. Curious to hear whether all parties are amenable to that approach.

That still leaves us with the need for a tool to convert quotes in Jinja/HTML source files. Recommendations welcome.

[roryhewitt]

Very good idea. I personally HATE curly (I refuse to call them 'smart') quotes.

[jpamental]

Just chiming in supporting proper apostrophes and quotation marks! I would think that adapting the process to a linting tool that handles it would be the best approach. I worked on a module for Drupal that has used different PHP libraries to handle it (or perhaps go one better and insert HTML entities that would display properly for any user's preferences). As much as I feel like there should be better typography overall in any kind of publication, I understand the difficulties faced in producing it and want to find a solution that's sustainable.

[svgeesus]

Code requires straight marks.

That is a total strawman, no-one suggests using typographic quotes for code.

[svgeesus]

Smart quotes is a technology which auto-corrects straight quotes (for example in wordprocessors), and sometimes gets it wrong (such as converting code).

The actual result is typographic quotes.

[tunetheweb]

Code requires straight marks.

That is a total strawman, no-one suggests using typographic quotes for code.

The point is this does happen when people are typing code snippets or HTML markup, they want to include in Google Docs or Word draft before converting to Markdown. It is far easier to do a global find and replace to correct any instances of this error, than to go through each quote in 22 chapters to ensure the correct ones were used. So I don't think this is a straw man argument at all, nor what I am suggesting — the fact we have code and writing intertwined makes using typographical quotes an extra challenge for us.

Smart quotes is a technology which auto-corrects straight quotes (for example in wordprocessors), and sometimes gets it wrong (such as converting code).

The actual result is typographic quotes.

Updated the issue and first comment. Though I think a lot of laymen (and women!) know them as smart quotes though even if you are technically correct (which is, of course, the best kind of correct! 😉)

[svgeesus]

Ah, a misunderstanding. My point was not that this doesn't happen by accident - clearly it does with over-zealous word processors - but rather, they no-one was suggesting that code snippets be made syntactically incorrect by using typographic quotes.

Which is also why I drew the distinction between the often inaccurate conversion technology, and the end result. Thanks for updating the issue title!

So, in terms of next year, I suggest:

1. The wordprocessor to markdown converter change typographic quotes to straight quotes, to avoid any showing up in code
2. A post-processing step changes straight quotes in prose to typographic quotes.

[tunetheweb]

Yeah that’s pretty much what we decided upon. Probably keeping the markdown with straight quotes but replacing with typographical quotes when converting to HTML as part of the site build process. In which case we can automatically apply this to all existing years. Rick’s suggested one library in #1485 (comment) so could look at that one or others when we someone gets a chance.

[LeaVerou]

Dropping correct quotes because people get them wrong sounds like suggesting we use the pipe symbol instead of parentheses because people may mess up their opening and closing parens.

I hope you reconsider, at least as part of the build process.

[tunetheweb]

We are open source so any contributions are welcome for those that feel strongly about this. Either to automate this (ideally), or alternatively to volunteer to edit the 173 (and counting) pages we have across 10 languages, to switch them to typographical quotes.

[LeaVerou]

@bazzadp Many Markdown converters do this automatically anyway. I suspect there are plugins available for those that don't. Which one do you use?

[tunetheweb]

We use Showdown which unfortunately does not offer this natively so it’s not as simple as adding a config.

@rviscomi suggested an alternative above which does support this, but not seen what’s involved in moving to this, or running it after Showndown:

I've heard good things about https://github.com/markdown-it/markdown-it and its typographer setting to convert straight quotes to curly without affecting code blocks. Worth a look. I'd much prefer a tool that does the conversions for us than a linter that only complains when we get it wrong.

Btw, personally I think we should have typographic quotes (we aim for excellence in everything else about this publication!), but my priority is in getting the last two chapters finished, and the unedited chapters edited ( which takes far more effort than most realise!) as those are more immediate problems as content is missing or potentially incorrect.

So, for me, this is lower down the priority queue for now. Also, it’s been a heck of a last month or two so a break is also higher priority on this for some of us. But if someone does want to take this on then I’d be supportive of that and help in any way I can.

[tunetheweb]

Good news everyone - I just merged and released the fix for this. Typographist of the project can breath a little easier! 😀

[jpamental]

It looks fantastic Barry. Thank you so much! Can’t wait to dig in and check out the solution and see how I can incorporate it in other static site build projects. Jason

…

On Jan 30, 2021, at 11:51 AM, Barry Pollard ***@***.***> wrote:  Good news everyone - I just merged and released the fix for this. Typographist of the project can breath a little easier! 😀 — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[tunetheweb]

I ended up using the smartypants library. Doesn’t look like it’s massively comprehensive to be honest but it had three key attributes others didn’t:

• It didn’t convert HTML attribute quotes (some did!)
• It ignored <code> and similar elements.
• it ignored comments

The last one was particularly important for us as we had some Jinja macros (e.g. for our figure) that it didn’t recognise as HTML so tried to convert those arguments. By temporarily sticking them in an HTML comment for the conversion, we were able to handle them.

So the code itself is quite small (basically this, which is called as part of our site build), but difficulty was in going through all instances checking it hadn’t broken anything and dealing with some markup issues in all the chapters to try to ensure it was used everywhere.

But pleasing that it’s relatively simple and hopefully not going to be a complete pain to maintain.

[jpamental]

That’s great. Same library used in the Typogrify module for Drupal, which works really well. Thanks again for making it happen! Jason

…

On Jan 30, 2021, at 12:19 PM, Barry Pollard ***@***.***> wrote:  I ended up using the smartypants library. Doesn’t look like it’s massively comprehensive to be honest but it had three key attributes others didn’t: It didn’t convert HTML attribute quotes (some did!) It ignored <code> and similar elements. it ignored comments The last one was particularly important for us as we had some Jinja macros (e.g. for our figure) that it didn’t recognise as HTML so tried to convert those arguments. By temporarily sticking them in an HTML comment for the conversion, we were able to handle them. So the code itself is quite small (basically this, which is called as part of our site build), but difficulty was in going through all instances checking it hadn’t broken anything and dealing with some markup issues in all the chapters to try to ensure it was used everywhere. But pleasing that it’s relatively simple and hopefully not going to be a complete pain to maintain. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.