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

tools/gn/standard_out.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/standard_out.h"
 
 #include <vector>
 
 #include "base/command_line.h"
 #include "base/logging.h"
@@ skipping 11 matching lines @@
 namespace {
 
 bool initialized = false;
 
 #if defined(OS_WIN)
 HANDLE hstdout;
 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;
     return;
   }
 
 #if defined(OS_WIN)
   // On Windows, we can't force the color on. If the output handle isn't a
   // console, there's nothing we can do about it.
   hstdout = ::GetStdHandle(STD_OUTPUT_HANDLE);
   CONSOLE_SCREEN_BUFFER_INFO info;
   is_console = !!::GetConsoleScreenBufferInfo(hstdout, &info);
   default_attributes = info.wAttributes;
 #else
   if (cmdline->HasSwitch(switches::kColor))
     is_console = true;
   else
     is_console = isatty(fileno(stdout));
 #endif
 }
 
 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;
       case DECORATION_DIM:
         ::SetConsoleTextAttribute(hstdout, FOREGROUND_INTENSITY);
         break;
       case DECORATION_RED:
         ::SetConsoleTextAttribute(hstdout,
                                   FOREGROUND_RED | FOREGROUND_INTENSITY);
         break;
       case DECORATION_GREEN:
         // Keep green non-bold.
         ::SetConsoleTextAttribute(hstdout, FOREGROUND_GREEN);
         break;
       case DECORATION_BLUE:
         ::SetConsoleTextAttribute(hstdout,
                                   FOREGROUND_BLUE | FOREGROUND_INTENSITY);
         break;
       case DECORATION_YELLOW:
         ::SetConsoleTextAttribute(hstdout,
                                   FOREGROUND_RED | FOREGROUND_GREEN);
         break;
     }
   }
 
-  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;
       case DECORATION_DIM:
         WriteToStdOut("\e[2m");
         break;
       case DECORATION_RED:
         WriteToStdOut("\e[31m\e[1m");
         break;
       case DECORATION_GREEN:
         WriteToStdOut("\e[32m");
         break;
       case DECORATION_BLUE:
         WriteToStdOut("\e[34m\e[1m");
         break;
       case DECORATION_YELLOW:
         WriteToStdOut("\e[33m\e[1m");
         break;
     }
   }
 
   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) {
     OutputString("  " + line.substr(0, colon_offset), DECORATION_YELLOW);
     first_normal = colon_offset;
   }
 
   // See if the colon is followed by a " [" and if so, dim the contents of [ ].
   if (first_normal > 0 &&
       line.size() > first_normal + 2 &&
       line[first_normal + 1] == ' ' && line[first_normal + 2] == '[') {
     size_t begin_bracket = first_normal + 2;
     OutputString(": ");
     first_normal = line.find(']', begin_bracket);
     if (first_normal == std::string::npos)
       first_normal = line.size();
     else
       first_normal++;
     OutputString(line.substr(begin_bracket, first_normal - begin_bracket),
                  DECORATION_DIM);
   }
 
   OutputString(line.substr(first_normal) + "\n");
 }
 
 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.
     TextDecoration dec = DECORATION_NONE;
     for (const auto& elem : line) {
       if (elem == '#') {
         // Got a comment, draw dimmed.
         dec = DECORATION_DIM;
         break;
       } else if (elem != ' ') {
         break;
       }
     }
 
     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");
+  }
 }