docs: clean up markdown

docs: clean up markdown

The automated conversion missed/mangled links and images.
It also included Unicode quotes in some places where normal
quotes make more sense.  Gitiles will render them as either
automatically depending on context.

[vapier, 2016-06-29 15:51:05]

vapier@chromium.org changed reviewers:
+ andybons@chromium.org, mseaborn@chromium.org

[vapier, 2016-06-29 15:51:06]

sample rendering can be viewed here:
https://chromium.googlesource.com/breakpad/breakpad/+/2116d76fa77e4c8997cddde...

[Bons, 2016-06-29 17:22:16]

https://codereview.chromium.org/2103273003/diff/1/docs/client_design.md
File docs/client_design.md (left):

https://codereview.chromium.org/2103273003/diff/1/docs/client_design.md#oldco...
docs/client_design.md:48: collect additional data about the program’s state,
quit the program, launch a
Why are you replacing the smart quotes with dumb ones?

[vapier, 2016-06-29 17:56:40]

https://codereview.chromium.org/2103273003/diff/1/docs/client_design.md
File docs/client_design.md (left):

https://codereview.chromium.org/2103273003/diff/1/docs/client_design.md#oldco...
docs/client_design.md:48: collect additional data about the program’s state,
quit the program, launch a
smart quotes are an abomination ;).

they don't really belong in plain text files when the vast majority of content
is otherwise ASCII (as it is with all the breakpad docs).

that said, gitiles has no problem rendering them as "smart" quotes when it makes
sense.

[vapier, 2016-06-29 17:57:30]

Description was changed from

==========
docs: clean up markdown

The automated conversion missed links and images.
==========

to

==========
docs: clean up markdown

The automated conversion missed/mangled links and images.
It also included Unicode quotes in some places where normal
quotes make more sense.  Gitiles will render them as either
automatically depending on context.
==========

[Mark Mentovai, 2016-06-29 18:07:39]

mark@chromium.org changed reviewers:
+ mark@chromium.org

[Mark Mentovai, 2016-06-29 18:07:40]

Seems like this is UTF-8.

Certainly in documentation, why not get with the program and be typographically
correct?

[Bons, 2016-06-29 18:09:12]

On 2016/06/29 17:56:40, vapier wrote:
> https://codereview.chromium.org/2103273003/diff/1/docs/client_design.md
> File docs/client_design.md (left):
> 
>
https://codereview.chromium.org/2103273003/diff/1/docs/client_design.md#oldco...
> docs/client_design.md:48: collect additional data about the program’s state,
> quit the program, launch a
> smart quotes are an abomination ;).
> 
> they don't really belong in plain text files when the vast majority of content
> is otherwise ASCII (as it is with all the breakpad docs).
> 
> that said, gitiles has no problem rendering them as "smart" quotes when it
makes
> sense.

Could you extrapolate on your claim that they’re an “abomination”? Is there a
technical reason why dumb quotes make more sense aside from gitiles rendering
them in the right context?

Proper unicode should be supported no matter what. If there’s a problem with
having valid utf-8 characters then that should be addressed.

[vapier, 2016-06-29 18:34:08]

i see no context where it's necessary to use ’ (U+2019) over ' (U+0027), or
“...” (U+201C & U+201D) over "..." (U+0027).
- they're a pita to type (you're telling me i need to set up a new keyboard
mapping in order to edit docs?)
- they're already used inconsistently in the docs
- they're a pain to keep in sync (i have to remember to start with “ and end
with ”, and make sure my editor/terminal can *clearly* render them as distinct
bytes)
- they screw with copy & paste (code & shell use the ASCII ' and ", not the
extended Unicode codepoints)
- they're a waste of space (three bytes instead of one)

as for "typographically correct", that's a matter of opinion.  U+0027 is an
Apostrophe and U+0027 is a Quotation Mark which is what we want here.  if
anything, Right Single Quotation Mark is *not* an apostrophe.

this isn't about being UTF-8 clean (we already are, and i'll be the first to
argue against anyone who doesn't want to support Unicode).  it's about ease of
editing the docs and using the code.  i see no upsides here.

[Mark Mentovai, 2016-06-29 18:44:13]

vapier wrote:
> i see no context where it's necessary to use ’ (U+2019) over ' (U+0027), or
> “...” (U+201C & U+201D) over "..." (U+0027).
> - they're a pita to type (you're telling me i need to set up a new keyboard
> mapping in order to edit docs?)

I personally find it straightforward to type these on the same layout I use for
everything else, but nobody’s telling you that you have to type them.

> - they're already used inconsistently in the docs

Why should we migrate in your preferred direction instead of someone else’s?

> - they're a pain to keep in sync (i have to remember to start with “ and end
> with ”,

Again, you don’t have to use them if you don’t want to. It shouldn’t offend you
that others have used them.

> and make sure my editor/terminal can *clearly* render them as distinct
> bytes)

I don’t think that there’s anything to make sure of here. Who can’t handle UTF-8
in 2016?

> - they screw with copy & paste (code & shell use the ASCII ' and ", not the
> extended Unicode codepoints)

Smart quotes aren’t used in contexts where you might want to paste them into a
terminal. We’re talking about docs. Prose. Even in docs, code examples and
things intended to be pasted into shells use what’s appropriate for the intended
context.

> - they're a waste of space (three bytes instead of one)

That’s just a reach.

> as for "typographically correct", that's a matter of opinion.  U+0027 is an
> Apostrophe and U+0027 is a Quotation Mark which is what we want here.  if
> anything, Right Single Quotation Mark is *not* an apostrophe.

http://www.unicode.org/charts/PDF/U0000.pdf
0027 ' APOSTROPHE
• 2019 ’  is preferred for apostrophe

http://www.unicode.org/charts/PDF/U2000.pdf
2019 ’ RIGHT SINGLE QUOTATION MARK
• this is the preferred character to use for
apostrophe

[Bons, 2016-06-29 18:52:15]

On 2016/06/29 18:44:13, Mark Mentovai wrote:
> vapier wrote:
> > i see no context where it's necessary to use ’ (U+2019) over ' (U+0027), or
> > “...” (U+201C & U+201D) over "..." (U+0027).
> > - they're a pita to type (you're telling me i need to set up a new keyboard
> > mapping in order to edit docs?)
> 
> I personally find it straightforward to type these on the same layout I use
for
> everything else, but nobody’s telling you that you have to type them.
> 
> > - they're already used inconsistently in the docs
> 
> Why should we migrate in your preferred direction instead of someone else’s?
> 
> > - they're a pain to keep in sync (i have to remember to start with “ and end
> > with ”,
> 
> Again, you don’t have to use them if you don’t want to. It shouldn’t offend
you
> that others have used them.
> 
> > and make sure my editor/terminal can *clearly* render them as distinct
> > bytes)
> 
> I don’t think that there’s anything to make sure of here. Who can’t handle
UTF-8
> in 2016?
> 
> > - they screw with copy & paste (code & shell use the ASCII ' and ", not the
> > extended Unicode codepoints)
> 
> Smart quotes aren’t used in contexts where you might want to paste them into a
> terminal. We’re talking about docs. Prose. Even in docs, code examples and
> things intended to be pasted into shells use what’s appropriate for the
intended
> context.
> 
> > - they're a waste of space (three bytes instead of one)
> 
> That’s just a reach.
> 
> > as for "typographically correct", that's a matter of opinion.  U+0027 is an
> > Apostrophe and U+0027 is a Quotation Mark which is what we want here.  if
> > anything, Right Single Quotation Mark is *not* an apostrophe.
> 
> http://www.unicode.org/charts/PDF/U0000.pdf
> 0027 ' APOSTROPHE
> • 2019 ’  is preferred for apostrophe
> 
> http://www.unicode.org/charts/PDF/U2000.pdf
> 2019 ’ RIGHT SINGLE QUOTATION MARK
> • this is the preferred character to use for
> apostrophe

If people want to use them in their docs outside the context of anything that
would be pasted into a terminal, then they should be free to do so without
having a cleanup CL change that. You are welcome to keep using plain quotes, but
please don’t revert others‘ use of proper typographical conventions, regardless
of whether they are consistent across the docs.

The broken link and image changes look good to me, but please revert any changes
to quotes.

[vapier, 2016-06-29 18:52:34]

that doesn't really make sense.  docs, like code, should be consistent.  telling
people "you don't have to use them if you don't want to" guarantees
inconsistency.

the standard US keyboard layout only has ' and ".  to type any other character
means you have to use a diff layout (ugh), customize your layout to include
access to those chars (ugh), or copy & paste by hand the chars (ugh).  i don't
know if the US codebase is a majority, but i think it's safe to say they're
either the largest or second largest population.

i've listed a number of downsides.  conversely, i don't think you've listed any
upsides.

[Bons, 2016-06-29 19:06:41]

On 2016/06/29 18:52:34, vapier wrote:
> that doesn't really make sense.  docs, like code, should be consistent. 
telling
> people "you don't have to use them if you don't want to" guarantees
> inconsistency.
> 
> the standard US keyboard layout only has ' and ".  to type any other character
> means you have to use a diff layout (ugh), customize your layout to include
> access to those chars (ugh), or copy & paste by hand the chars (ugh).  i don't
> know if the US codebase is a majority, but i think it's safe to say they're
> either the largest or second largest population.
> 
> i've listed a number of downsides.  conversely, i don't think you've listed
any
> upsides.

If authors want to use proper and correct typographical conventions then they
should be free to do so.

They don’t violate the Google Markdown Style Guide —
https://github.com/google/styleguide/tree/gh-pages/docguide

I don’t see a compelling argument against smart quote inconsistency. Again, you
don’t have to use them just like you can use -- instead of —. The point is that
if I use the latter I shouldn’t have to worry about someone reverting it because
it’s easier to type for them.

[vapier, 2016-06-29 19:16:20]

authors don't need to care -- the gitiles rendering will deal with them.  "it's
ok to be inconsistent" has never been acceptable in style guidelines, and docs
should not be a special snowflake.  it just makes it worse for people who are
maintaining or reading the docs.