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=
Review URL: https://codereview.chromium.org/1301423006
Cr-Original-Commit-Position: refs/heads/master@{#348282}
Cr-Mirrored-From: https://chromium.googlesource.com/chromium/src
Cr-Mirrored-Commit: e6168f049b38f70833fa2bf271e2955c3e2f1511
diff --git a/tools/gn/docs/reference.md b/tools/gn/docs/reference.md
index b81b3f6..a510d5a 100644
--- a/tools/gn/docs/reference.md
+++ b/tools/gn/docs/reference.md
@@ -2,7 +2,7 @@
*This page is automatically generated from* `gn help --markdown all`.
-## **--args**: Specifies build arguments overrides.
+## **\--args**: Specifies build arguments overrides.
```
See "gn help buildargs" for an overview of how build arguments work.
@@ -40,7 +40,7 @@
```
-## **--[no]color**: Forces colored output on or off.
+## **\--[no]color**: Forces colored output on or off.
```
Normally GN will try to detect whether it is outputting to a terminal
@@ -58,7 +58,7 @@
```
-## **--dotfile**: Override the name of the ".gn" file.
+## **\--dotfile**: Override the name of the ".gn" file.
```
Normally GN loads the ".gn"file from the source root for some basic
@@ -70,9 +70,9 @@
```
-## **--markdown**: write the output in the Markdown format.
+## **\--markdown**: write the output in the Markdown format.
-## **--[no]color**: Forces colored output on or off.
+## **\--[no]color**: Forces colored output on or off.
```
Normally GN will try to detect whether it is outputting to a terminal
@@ -97,7 +97,7 @@
```
-## **--root**: Explicitly specify source root.
+## **\--root**: Explicitly specify source root.
```
Normally GN will look up in the directory tree from the current
@@ -119,7 +119,7 @@
```
-## **--runtime-deps-list-file**: Save runtime dependencies for targets in file.
+## **\--runtime-deps-list-file**: Save runtime dependencies for targets in file.
```
--runtime-deps-list-file=<filename>
@@ -154,7 +154,7 @@
```
-## **--time**: Outputs a summary of how long everything took.
+## **\--time**: Outputs a summary of how long everything took.
```
Hopefully self-explanatory.
@@ -168,7 +168,7 @@
```
-## **--tracelog**: Writes a Chrome-compatible trace log to the given file.
+## **\--tracelog**: Writes a Chrome-compatible trace log to the given file.
```
The trace log will show file loads, executions, scripts, and writes.
@@ -194,7 +194,7 @@
```
-## **gn args <out_dir> [--list] [--short] [--args]**
+## **gn args <out_dir> [\--list] [\--short] [\--args]**
```
See also "gn help buildargs" for a more high-level overview of how
@@ -259,7 +259,7 @@
```
-## **gn check <out_dir> [<label_pattern>] [--force]**
+## **gn check <out_dir> [<label_pattern>] [\--force]**
```
"gn check" is the same thing as "gn gen" with the "--check" flag
@@ -309,7 +309,7 @@
```
-## **gn desc <out_dir> <target label> [<what to show>] [--blame]**
+## **gn desc <out_dir> <target label> [<what to show>] [\--blame]**
```
Displays information about a given labeled target for the given build.
@@ -474,7 +474,7 @@
```
-## **gn format [--dump-tree] [--in-place] [--stdin] BUILD.gn**
+## **gn format [\--dump-tree] [\--in-place] [\--stdin] BUILD.gn**
```
Formats .gn file to a standard format.
@@ -538,7 +538,7 @@
```
-## **gn ls <out_dir> [<label_pattern>] [--all-toolchains] [--as=...]**
+## **gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]**
```
[--type=...] [--testonly=...]
@@ -642,7 +642,7 @@
```
-## **gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* [--all]**
+## **gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* [\--all]**
```
[--all-toolchains] [--as=...] [--testonly=...] [--type=...]
@@ -4817,17 +4817,17 @@
```
-** --args**: Specifies build arguments overrides.
-** --color**: Force colored output.
-** --dotfile**: Override the name of the ".gn" file.
-** --markdown**: write the output in the Markdown format.
-** --nocolor**: Force non-colored output.
+** \--args**: Specifies build arguments overrides.
+** \--color**: Force colored output.
+** \--dotfile**: Override the name of the ".gn" file.
+** \--markdown**: write the output in the Markdown format.
+** \--nocolor**: Force non-colored output.
** -q**: Quiet mode. Don't print output on success.
-** --root**: Explicitly specify source root.
-** --runtime-deps-list-file**: Save runtime dependencies for targets in file.
-** --time**: Outputs a summary of how long everything took.
-** --tracelog**: Writes a Chrome-compatible trace log to the given file.
+** \--root**: Explicitly specify source root.
+** \--runtime-deps-list-file**: Save runtime dependencies for targets in file.
+** \--time**: Outputs a summary of how long everything took.
+** \--tracelog**: Writes a Chrome-compatible trace log to the given file.
** -v**: Verbose logging.
-** --version**: Prints the GN version number and exits.
+** \--version**: Prints the GN version number and exits.
```
diff --git a/tools/gn/standard_out.cc b/tools/gn/standard_out.cc
index 6d3960e..0c5b54f 100644
--- a/tools/gn/standard_out.cc
+++ b/tools/gn/standard_out.cc
@@ -8,7 +8,9 @@
#include "base/command_line.h"
#include "base/logging.h"
+#include "base/strings/string_piece.h"
#include "base/strings/string_split.h"
+#include "base/strings/string_util.h"
#include "build/build_config.h"
#include "tools/gn/switches.h"
@@ -124,7 +126,15 @@
}
}
- ::WriteFile(hstdout, output.c_str(), static_cast<DWORD>(output.size()),
+ std::string tmpstr = output;
+ if (is_markdown && dec == DECORATION_YELLOW) {
+ // https://code.google.com/p/gitiles/issues/detail?id=77
+ // Gitiles will replace "--" with an em dash in non-code text.
+ // Figuring out all instances of this might be difficult, but we can
+ // at least escape the instances where this shows up in a heading.
+ base::ReplaceSubstringsAfterOffset(&tmpstr, 0, "--", "\\--");
+ }
+ ::WriteFile(hstdout, tmpstr.c_str(), static_cast<DWORD>(tmpstr.size()),
&written, nullptr);
if (is_markdown) {
@@ -162,7 +172,15 @@
}
}
- WriteToStdOut(output.data());
+ std::string tmpstr = output;
+ if (is_markdown && dec == DECORATION_YELLOW) {
+ // https://code.google.com/p/gitiles/issues/detail?id=77
+ // Gitiles will replace "--" with an em dash in non-code text.
+ // Figuring out all instances of this might be difficult, but we can
+ // at least escape the instances where this shows up in a heading.
+ base::ReplaceSubstringsAfterOffset(&tmpstr, 0, "--", "\\--");
+ }
+ WriteToStdOut(tmpstr.data());
if (is_markdown) {
OutputMarkdownDec(dec);
