Escape "--" in markdown rendering for GN reference docs.

Escape "--" in markdown rendering for GN reference docs.

Gitiles has a "feature" in its markdown rendering engine where if it
encounters the string "--" in a non-code context it will replace it with
an em dash; this is usually undesirable in the GN documentation, where
we want to refer to command line flags like --args explicitly.

Working around this properly would likely require either a much more
complicated parser handling markdown output of strings to track context,
or updating the source text to somehow indicate what should be escaped
and what shouldn't, or both.

We can, however, probably achieve a reasonable compromise by making sure
that we don't escape the dashes when they are part of a header string,
since the rest of the GN reference markdown output shows up as code
blocks anyway.

R=brettw@chromium.org
BUG=

Committed: https://crrev.com/e6168f049b38f70833fa2bf271e2955c3e2f1511
Cr-Commit-Position: refs/heads/master@{#348282}

[Dirk Pranke, 2015-09-03 01:04:46]

This is kind of kludgey so I'm not sure if it's worth landing, but I thought I'd
post it to see what you think.

For reference, here is the current rendering of the reference page:

https://chromium.googlesource.com/chromium/src/+/master/tools/gn/docs/referen...

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc
File tools/gn/standard_out.cc (right):

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:138: StringPiece("\\--"));
Is this the best/easiest way to do a "replace all" in a string?

[brettw, 2015-09-04 18:04:30]

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc
File tools/gn/standard_out.cc (right):

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:134: if (is_markdown && dec==DECORATION_YELLOW) {
Need spaces around ==

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:135: std::string tmpstr = output;
Why not just do
  if (...) {
    base::ReplaceSubstringsAfterOffset(&output, ...);
  }
  ::WriteFile(...);

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:138: StringPiece("\\--"));
Sure, but you can remove the explicit StringPiece constructors and just type
"--"

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:181: if (is_markdown && dec==DECORATION_YELLOW) {
Ditto

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:182: std::string tmpstr = output;
Ditto

[Dirk Pranke, 2015-09-05 01:53:42]

WDYT?

I've fixed the other feedback, and provided an alternative to your suggestion.
Let me know if you think it's better or worse.

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc
File tools/gn/standard_out.cc (right):

https://codereview.chromium.org/1301423006/diff/1/tools/gn/standard_out.cc#ne...
tools/gn/standard_out.cc:135: std::string tmpstr = output;
On 2015/09/04 18:04:30, brettw wrote:
> Why not just do
>   if (...) {
>     base::ReplaceSubstringsAfterOffset(&output, ...);
>   }
>   ::WriteFile(...);

output is a const, so we can't modify it. 

I've uploaded a version that always makes the copy; I doubt the performance
matters in this case.

[brettw, 2015-09-09 19:32:22]

lgtm

https://codereview.chromium.org/1301423006/diff/20001/tools/gn/standard_out.cc
File tools/gn/standard_out.cc (right):

https://codereview.chromium.org/1301423006/diff/20001/tools/gn/standard_out.c...
tools/gn/standard_out.cc:130: if (is_markdown && dec==DECORATION_YELLOW) {
Spaces around ==

[Dirk Pranke, 2015-09-09 19:33:06]

https://codereview.chromium.org/1301423006/diff/20001/tools/gn/standard_out.cc
File tools/gn/standard_out.cc (right):

https://codereview.chromium.org/1301423006/diff/20001/tools/gn/standard_out.c...
tools/gn/standard_out.cc:130: if (is_markdown && dec==DECORATION_YELLOW) {
On 2015/09/09 19:32:22, brettw wrote:
> Spaces around ==

whoops, only fixed the one :(

[Dirk Pranke, 2015-09-10 23:10:37]

The CQ bit was checked by dpranke@chromium.org

[Dirk Pranke, 2015-09-10 23:10:37]

The patchset sent to the CQ was uploaded after l-g-t-m from brettw@chromium.org
Link to the patchset: https://codereview.chromium.org/1301423006/#ps40001
(title: "fix second dec==")

[commit-bot: I haz the power, 2015-09-10 23:11:01]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1301423006/40001
View timeline at
 https://chromium-cq-status.appspot.com/patch-timeline/1301423006/40001

[commit-bot: I haz the power, 2015-09-10 23:24:11]

Committed patchset #3 (id:40001)

[commit-bot: I haz the power, 2015-09-10 23:25:07]

Patchset 3 (id:??) landed as
https://crrev.com/e6168f049b38f70833fa2bf271e2955c3e2f1511
Cr-Commit-Position: refs/heads/master@{#348282}

[commit-bot: I haz the power, 2015-09-23 12:16:16]

Patchset 3 (id:??) landed as
https://crrev.com/e6168f049b38f70833fa2bf271e2955c3e2f1511
Cr-Commit-Position: refs/heads/master@{#348282}