[NaCl SDK Docs] Only generate one top-level <section> element.

native_client_sdk/doc_generated/devguide/devcycle/debugging.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="debugging">
 <span id="devcycle-debugging"></span><h1 id="debugging"><span id="devcycle-debugging"></span>Debugging</h1>
 <p>This document describes tools and techniques you can use to debug, monitor,
 and measure your application&#8217;s performance.</p>
 <div class="contents local" id="table-of-contents" style="display: none">
 <p class="topic-title first">Table Of Contents</p>
 <ul class="small-gap">
 <li><p class="first"><a class="reference internal" href="#diagnostic-information" id="id2">Diagnostic information</a></p>
@@ skipping 22 matching lines @@
 </li>
 </ul>
 </li>
 <li><p class="first"><a class="reference internal" href="#debugging-with-other-tools" id="id16">Debugging with other tools</a></p>
 <ul class="small-gap">
 <li><a class="reference internal" href="#open-source-profiling-tools" id="id17">Open source profiling tools</a></li>
 </ul>
 </li>
 </ul>
 
-</div><section id="diagnostic-information">
-<h2 id="diagnostic-information">Diagnostic information</h2>
-<section id="viewing-process-statistics-with-the-task-manager">
+</div><h2 id="diagnostic-information">Diagnostic information</h2>
 <h3 id="viewing-process-statistics-with-the-task-manager">Viewing process statistics with the task manager</h3>
 <p>You can use Chrome&#8217;s Task Manager to display information about a Native Client
 application:</p>
 <ol class="arabic simple">
 <li>Open the Task Manager by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and choosing
 <strong>Tools &gt; Task manager</strong>.</li>
 <li>When the Task Manager window appears, verify that the columns displaying
 memory information are visible. If they are not, right click in the header
 row and select the memory items from the popup menu that appears.</li>
 </ol>
 <p>A browser window running a Native Client application will have at least two
 processes associated with it: a process for the app&#8217;s top level (the render
 process managing the page including its HTML and any JavaScript) and one or
 more processes for each instance of a Native Client module embedded in the page
 (each process running native code from one nexe file). The top-level process
 appears with the application&#8217;s icon and begins with the text &#8220;App:&#8221;. A Native
 Client process appears with a Chrome extension icon (a jigsaw puzzle piece
 <img alt="puzzle" src="/native-client/images/puzzle.png" />) and begins with the text &#8220;Native Client module&#8221; followed by the URL
 of its manifest file.</p>
 <p>From the Task Manager you can view the changing memory allocations of all the
 processes associated with a Native Client application. Each process has its own
 memory footprint. You can also see the rendering rate displayed as frames per
 second (FPS). Note that the computation of render frames can be performed in
 any process, but the rendering itself is always done in the top level
 application process, so look for the rendering rate there.</p>
-</section><section id="controlling-the-level-of-native-client-error-and-warning-messages">
 <h3 id="controlling-the-level-of-native-client-error-and-warning-messages">Controlling the level of Native Client error and warning messages</h3>
 <p>Native Client prints warning and error messages to stdout and stderr. You can
 increase the amount of Native Client&#8217;s diagnostic output by setting the
 following <a class="reference external" href="http://en.wikipedia.org/wiki/Environment_variable">environment variables</a>:</p>
 <ul class="small-gap">
 <li>NACL_PLUGIN_DEBUG=1</li>
 <li>NACL_SRPC_DEBUG=[1-255] (use a higher number for more verbose debug output)</li>
 <li>NACLVERBOSITY=[1-255]</li>
 </ul>
-</section></section><section id="basic-debugging">
 <h2 id="basic-debugging">Basic debugging</h2>
-<section id="writing-messages-to-the-javascript-console">
 <h3 id="writing-messages-to-the-javascript-console">Writing messages to the JavaScript console</h3>
 <p>You can send messages from your C/C++ code to JavaScript using the PostMessage
 call in the <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Pepper messaging system</em></a>. When the
 JavaScript code receives a message, its message event handler can call
 <a class="reference external" href="https://developer.mozilla.org/en/DOM/console.log">console.log()</a> to write
 the message to the JavaScript <a class="reference external" href="/devtools/docs/console-api">console</a> in
 Chrome&#8217;s Developer Tools.</p>
-</section><section id="debugging-with-printf">
 <h3 id="debugging-with-printf">Debugging with printf</h3>
 <p>Your C/C++ code can perform inline printf debugging to stdout and stderr by
 calling fprintf() directly, or by using cover functions like these:</p>
 <pre class="prettyprint">
 #include &lt;stdio.h&gt;
 void logmsg(const char* pMsg){
   fprintf(stdout,&quot;logmsg: %s\n&quot;,pMsg);
 }
 void errormsg(const char* pMsg){
   fprintf(stderr,&quot;logerr: %s\n&quot;,pMsg);
 }
 </pre>
 <p>By default stdout and stderr will appear in Chrome&#8217;s stdout and stderr stream
 but they can also be redirected as described below.</p>
-<section id="redirecting-output-to-log-files">
 <h4 id="redirecting-output-to-log-files">Redirecting output to log files</h4>
 <p>You can redirect stdout and stderr to output files by setting these environment variables:</p>
 <ul class="small-gap">
 <li><code>NACL_EXE_STDOUT=c:\nacl_stdout.log</code></li>
 <li><code>NACL_EXE_STDERR=c:\nacl_stderr.log</code></li>
 </ul>
 <p>There is another variable, <code>NACLLOG</code>, that you can use to redirect Native
 Client&#8217;s internally-generated messages. This variable is set to stderr by
 default; you can redirect these messages to an output file by setting the
 variable as follows:</p>
 <ul class="small-gap">
 <li><code>NACLLOG=c:\nacl.log</code></li>
 </ul>
 <aside class="note">
 <strong>Note:</strong> If you set the NACL_EXE_STDOUT, NACL_EXE_STDERR, or NACLLOG
 variables to redirect output to a file, you must run Chrome with the
 <code>--no-sandbox</code> flag.  You must also be careful that each variable points to
 a different file.
 </aside>
-</section><section id="redirecting-output-to-the-javascript-console">
 <h4 id="redirecting-output-to-the-javascript-console">Redirecting output to the JavaScript console</h4>
 <p>You can also cause output from printf statements in your C/C++ code to be
 relayed to the JavaScript side of your application through the Pepper messaging
 system, where you can then write the output to the JavaScript console. Follow
 these steps:</p>
 <ol class="arabic">
 <li><p class="first">Set the NACL_EXE_STDOUT and NACL_EXE_STDERR environment variables as
 follows:</p>
 <ul class="small-gap">
 <li><p class="first">NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage</p>
@@ skipping 32 matching lines @@
 JavaScript, your handler will need to be more complex.</p>
 <p>Once you&#8217;ve implemented a message handler and set up the environment
 variables as described above, you can check the JavaScript console to see
 output that your Native Client module prints to stdout and stderr. Keep in
 mind that your module makes a call to PostMessage() every time it flushes
 stdout or stderr.  Your application&#8217;s performance will degrade considerably
 if your module prints and flushes frequently, or if it makes frequent Pepper
 calls to begin with (e.g., to render).</p>
 </li>
 </ol>
-</section></section><section id="logging-calls-to-pepper-interfaces">
 <h3 id="logging-calls-to-pepper-interfaces">Logging calls to Pepper interfaces</h3>
 <p>You can log all Pepper calls your module makes by passing the following flags
 to Chrome on startup:</p>
 <pre class="prettyprint">
 --vmodule=ppb*=4 --enable-logging=stderr
 </pre>
 <p>The <code>vmodule</code> flag tells Chrome to log all calls to C Pepper interfaces that
 begin with &#8220;ppb&#8221; (that is, the interfaces that are implemented by the browser
 and that your module calls). The <code>enable-logging</code> flag tells Chrome to log
 the calls to stderr.</p>
-</section><section id="debugging-with-visual-studio">
-<span id="visual-studio"></span><h3 id="debugging-with-visual-studio"><span id="visual-studio"></span>Debugging with Visual Studio</h3>
+<h3 id="debugging-with-visual-studio"><span id="visual-studio"></span>Debugging with Visual Studio</h3>
 <p>If you develop on a Windows platform you can use the <a class="reference internal" href="/native-client/devguide/devcycle/vs-addin.html"><em>Native Client Visual
 Studio add-in</em></a> to write and debug your code. The add-in defines new
 project platforms that let you run your module in two different modes: As a
 Pepper plugin and as a Native Client module. When running as a Pepper plugin
 you can use the built-in Visual Studio debugger. When running as a Native
 Client module Visual Studio will launch an instance of nacl-gdb for you and
 link it to the running code.</p>
-</section><section id="debugging-with-nacl-gdb">
-<span id="using-gdb"></span><h3 id="debugging-with-nacl-gdb"><span id="using-gdb"></span>Debugging with nacl-gdb</h3>
+<h3 id="debugging-with-nacl-gdb"><span id="using-gdb"></span>Debugging with nacl-gdb</h3>
 <p>The Native Client SDK includes a command-line debugger that you can use to
 debug Native Client modules. The debugger is based on the GNU debugger <a class="reference external" href="http://www.gnu.org/software/gdb/">gdb</a>, and is located at
 <code>toolchain/&lt;platform&gt;_x86_newlib/bin/x86_64-nacl-gdb</code> (where <em>&lt;platform&gt;</em>
 is the platform of your development machine: <code>win</code>, <code>mac</code>, or
 <code>linux</code>).</p>
 <p>Note that this same copy of GDB can be used to debug any NaCl program,
 whether built using newlib or glibc for x86-32, x86-64 or ARM.  In the SDK,
 <code>i686-nacl-gdb</code> is an alias for <code>x86_64-nacl-gdb</code>, and the <code>newlib</code>
 and <code>glibc</code> toolchains both contain the same version of GDB.</p>
-<section id="debugging-pnacl-pexes-with-pepper-35">
-<span id="debugging-pnacl-pexes"></span><h4 id="debugging-pnacl-pexes-with-pepper-35"><span id="debugging-pnacl-pexes"></span>Debugging PNaCl pexes (with Pepper 35+)</h4>
+<h4 id="debugging-pnacl-pexes-with-pepper-35"><span id="debugging-pnacl-pexes"></span>Debugging PNaCl pexes (with Pepper 35+)</h4>
 <p>If you want to use GDB to debug a program that is compiled with the PNaCl
 toolchain, you must have a copy of the pexe from <strong>before</strong> running
 <code>pnacl-finalize</code>. The <code>pnacl-finalize</code> tool converts LLVM bitcode
 to the stable PNaCl bitcode format, but it also strips out debug
 metadata, which we need for debugging. In this section we&#8217;ll give the
 LLVM bitcode file a <code>.bc</code> file extension, and the PNaCl bitcode file
 a <code>.pexe</code> file extension. The actual extension should not matter, but
 it helps distinguish between the two types of files.</p>
 <p><strong>Note</strong> unlike the finalized copy of the pexe, the non-finalized debug copy
 is not considered stable. This means that a debug copy of the PNaCl
@@ skipping 28 matching lines @@
 your local web server serves files from.</p>
 <p>When you run Chrome with <code>--enable-nacl-debug</code>, Chrome will translate
 and run the <code>debug_version.bc</code> instead of <code>release_version.pexe</code>.
 Once the debug version is loaded, you are ready to <a class="reference internal" href="#running-nacl-gdb"><em>run nacl-gdb</em></a></p>
 <p>Whether you publish the NMF file containing the debug URL to the release
 web server, is up to you. One reason to avoid publishing the debug URL
 is that it is only guaranteed to work for the Chrome version that matches
 the SDK version. Developers who may have left the <code>--enable-nacl-debug</code>
 flag turned on may end up loading the debug copy of your application
 (which may or may not work, depending on their version of Chrome).</p>
-</section><section id="debugging-pnacl-pexes-with-older-pepper-toolchains">
 <h4 id="debugging-pnacl-pexes-with-older-pepper-toolchains">Debugging PNaCl pexes (with older Pepper toolchains)</h4>
 <p>If you want to use GDB to debug a program that is compiled with the PNaCl
 toolchain, you must convert the <code>pexe</code> file to a <code>nexe</code>.  (You can skip
 this step if you are using the GCC toolchain, or if you are using
 pepper 35 or later.)</p>
 <ul class="small-gap">
 <li>Firstly, make sure you are passing the <code>-g</code> <a class="reference internal" href="/native-client/devguide/devcycle/building.html#compile-flags"><em>compile option</em></a> to <code>pnacl-clang</code> to enable generating debugging info.
 You might also want to omit <code>-O2</code> from the compile-time and link-time
 options.</li>
 <li><p class="first">Secondly, use <code>pnacl-translate</code> to convert your <code>pexe</code> to one or more
@@ skipping 28 matching lines @@
 <li>Copy the <code>nexe</code> and <code>nmf</code> files to the location that your local web
 server serves files from.</li>
 </ul>
 <aside class="note">
 <strong>Note:</strong> If you know whether Chrome is using the x86-32 or x86-64
 version of the NaCl sandbox on your system, you can translate the
 <code>pexe</code> once to a single x86-32 or x86-64 <code>nexe</code>.  Otherwise, you
 might find it easier to translate the <code>pexe</code> to both <code>nexe</code>
 formats as described above.
 </aside>
-</section><section id="running-nacl-gdb">
-<span id="id1"></span><h4 id="running-nacl-gdb"><span id="id1"></span>Running nacl-gdb</h4>
+<h4 id="running-nacl-gdb"><span id="id1"></span>Running nacl-gdb</h4>
 <p>Before you start using nacl-gdb, make sure you can <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>build</em></a> your
 module and <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>run</em></a> your application normally. This will verify
 that you have created all the required <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>application parts</em></a> (.html, .nmf, and .nexe files, shared
 libraries, etc.), that your server can access those resources, and that you&#8217;ve
 configured Chrome correctly to run your application.  The instructions below
 assume that you are using a <a class="reference internal" href="/native-client/devguide/devcycle/running.html#web-server"><em>local server</em></a> to run your
 application; one benefit of doing it this way is that you can check the web
 server output to confirm that your application is loading the correct
 resources. However, some people prefer to run their application as an unpacked
 extension, as described in <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>Running Native Client Applications</em></a>.</p>
@@ skipping 199 matching lines @@
 <dt><code>help &lt;command&gt;</code></dt>
 <dd>print documentation for the specified gdb &lt;command&gt;</dd>
 <dt><code>quit</code></dt>
 <dd>quit gdb</dd>
 </dl>
 <p>See the <a class="reference external" href="http://sourceware.org/gdb/current/onlinedocs/gdb/#toc_Top">gdb documentation</a> for a
 comprehensive list of gdb commands. Note that you can abbreviate most commands
 to just their first letter (<code>b</code> for break, <code>c</code> for continue, and so on).</p>
 <p>To interrupt execution of your module, press &lt;Ctrl-c&gt;. When you&#8217;re done
 debugging, close the Chrome window and type <code>q</code> to quit gdb.</p>
-</section></section></section><section id="debugging-with-other-tools">
 <h2 id="debugging-with-other-tools">Debugging with other tools</h2>
 <p>If you cannot use the <a class="reference internal" href="#visual-studio"><em>Visual Studio add-in</em></a>, or you want
 to use a debugger other than nacl-gdb, you must manually build your module as a
 Pepper plugin (sometimes referred to as a &#8220;<a class="reference external" href="http://www.chromium.org/nativeclient/getting-started/getting-started-background-and-basics#TOC-Trusted-vs-Untrusted">trusted</a>&#8221;
 or &#8220;in-process&#8221; plugin).  Pepper plugins (.DLL files on Windows; .so files on
 Linux; .bundle files on Mac) are loaded directly in either the Chrome renderer
 process or a separate plugin process, rather than in Native Client. Building a
 module as a trusted Pepper plugin allows you to use standard debuggers and
 development tools on your system, but when you&#8217;re finished developing the
 plugin, you need to port it to Native Client (i.e., build the module with one
 of the toolchains in the NaCl SDK so that the module runs in Native Client).
 For details on this advanced development technique, see <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin">Debugging a Trusted
 Plugin</a>.
 Note that starting with the <code>pepper_22</code> bundle, the NaCl SDK for Windows
 includes pre-built libraries and library source code, making it much easier to
 build a module into a .DLL.</p>
-<section id="open-source-profiling-tools">
 <h3 id="open-source-profiling-tools">Open source profiling tools</h3>
 <p>For the brave-hearted there are open source tools at <a class="reference external" href="http://www.chromium.org/nativeclient">Chromium.org</a> that describe how to do profiling on
 <a class="reference external" href="https://sites.google.com/a/chromium.org/dev/nativeclient/how-tos/profiling-nacl-apps-on-64-bit-windows">64-bit Windows</a>
 and <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/limited-profiling-with-oprofile-on-x86-64">Linux</a>
 machines.</p>
-</section></section></section>
+</section>
 
 {{/partials.standard_nacl_article}}