Add a --markdown flag to GN to be able to output help in markdown.

tools/gn/standard_out.cc

Index: tools/gn/standard_out.cc
diff --git a/tools/gn/standard_out.cc b/tools/gn/standard_out.cc
index 69d443be368a22f37b8f1ca4eee2c6fe642dbaeb..3a731e67f6d958d30b187679f538bf2e3cf78c89 100644
--- a/tools/gn/standard_out.cc
+++ b/tools/gn/standard_out.cc
@@ -29,12 +29,19 @@ WORD default_attributes;
 #endif
 bool is_console = false;
 
+bool is_markdown = false;
+
 void EnsureInitialized() {
   if (initialized)
     return;
   initialized = true;
 
   const base::CommandLine* cmdline = base::CommandLine::ForCurrentProcess();
+  if (cmdline->HasSwitch(switches::kMarkdown)) {
+    // output help in Markdown's syntax, not color-highlighted.
+    is_markdown = true;
+  }
+
   if (cmdline->HasSwitch(switches::kNoColor)) {
     // Force color off.
     is_console = false;
@@ -60,14 +67,22 @@ void WriteToStdOut(const std::string& output) {
   size_t written_bytes = fwrite(output.data(), 1, output.size(), stdout);
   DCHECK_EQ(output.size(), written_bytes);
 }
-
 }  // namespace
 
 #if defined(OS_WIN)
 
 void OutputString(const std::string& output, TextDecoration dec) {
   EnsureInitialized();
-  if (is_console) {
+  DWORD written = 0;
+
+  if (is_markdown) {
+    // The markdown rendering turns "dim" text to italics and any

[brettw, 2015/04/17 00:01:53]

I think it would be better to replace this with:
  WriteMarkdownDecoration(dec);
and have that function implement the decoration checking and output, to avoid
all the duplication you have in here.

[Dirk Pranke, 2015/04/17 00:08:15]

Acknowledged.

+    // other colored text to bold.
+    if (dec == DECORATION_DIM)
+      ::WriteFile(hstdout, "*", 1), &written, nullptr);
+    else if (dec != DECORATION_NONE)
+      ::WriteFile(hstdout, "**", 2), &written, nullptr);
+  } else if (is_console) {
     switch (dec) {
       case DECORATION_NONE:
         break;
@@ -93,19 +108,31 @@ void OutputString(const std::string& output, TextDecoration dec) {
     }
   }
 
-  DWORD written = 0;
   ::WriteFile(hstdout, output.c_str(), static_cast<DWORD>(output.size()),
               &written, nullptr);
 
-  if (is_console)
+  if (is_markdown) {
+    if (dec == DECORATION_DIM)
+      ::WriteFile(hstdout, "*", 1), &written, nullptr);
+    else if (dec != DECORATION_NONE)
+      ::WriteFile(hstdout, "**", 2), &written, nullptr);
+  } else if (is_console) {
     ::SetConsoleTextAttribute(hstdout, default_attributes);
+  }
 }
 
 #else
 
 void OutputString(const std::string& output, TextDecoration dec) {
   EnsureInitialized();
-  if (is_console) {
+  if (is_markdown) {
+    // The markdown rendering turns "dim" text to italics and any
+    // other colored text to bold.
+    if (dec == DECORATION_DIM)
+      WriteToStdOut("*");
+    else if (dec != DECORATION_NONE)
+      WriteToStdOut("**");
+  } else if (is_console) {
     switch (dec) {
       case DECORATION_NONE:
         break;
@@ -129,13 +156,21 @@ void OutputString(const std::string& output, TextDecoration dec) {
 
   WriteToStdOut(output.data());
 
-  if (is_console && dec != DECORATION_NONE)
+  if (is_markdown) {
+    if (dec == DECORATION_DIM)
+      WriteToStdOut("*");
+    else if (dec != DECORATION_NONE)
+      WriteToStdOut("**");
+  } else if (is_console && dec != DECORATION_NONE) {
     WriteToStdOut("\e[0m");
+  }
 }
 
 #endif
 
 void PrintShortHelp(const std::string& line) {
+  EnsureInitialized();
+
   size_t colon_offset = line.find(':');
   size_t first_normal = 0;
   if (colon_offset != std::string::npos) {
@@ -162,19 +197,48 @@ void PrintShortHelp(const std::string& line) {
 }
 
 void PrintLongHelp(const std::string& text) {
+  EnsureInitialized();
+
   std::vector<std::string> lines;
   base::SplitStringDontTrim(text, '\n', &lines);
 
+  bool first_header = true;
+  bool in_body = false;
   for (const auto& line : lines) {
     // Check for a heading line.
     if (!line.empty() && line[0] != ' ') {
+      if (is_markdown) {
+        // GN's block-level formatting is converted to markdown as follows:
+        // * The first heading is treated as an H2.
+        // * Subsequent heading are treated as H3s.
+        // * Any other text is wrapped in a code block and displayed as-is.
+        //
+        // Span-level formatting (the decorations) is converted inside
+        // OutputString().
+        if (in_body) {
+          OutputString("```\n\n", DECORATION_NONE);
+          in_body = false;
+        }
+
+        if (first_header) {
+          OutputString("## ", DECORATION_NONE);
+          first_header = false;
+        } else {
+          OutputString("### ", DECORATION_NONE);
+        }
+      }
+
       // Highlight up to the colon (if any).
       size_t chars_to_highlight = line.find(':');
       if (chars_to_highlight == std::string::npos)
         chars_to_highlight = line.size();
+
       OutputString(line.substr(0, chars_to_highlight), DECORATION_YELLOW);
       OutputString(line.substr(chars_to_highlight) + "\n");
       continue;
+    } else if (!line.empty() && !in_body) {
+      OutputString("```\n", DECORATION_NONE);
+      in_body = true;
     }
 
     // Check for a comment.
@@ -191,5 +255,9 @@ void PrintLongHelp(const std::string& text) {
 
     OutputString(line + "\n", dec);
   }
+
+  if (is_markdown && in_body) {

[brettw, 2015/04/17 00:01:53]

No {}

[Dirk Pranke, 2015/04/17 00:08:16]

Acknowledged.

+    OutputString("\n```\n");
+  }
 }