Merge branch 'lukas/runtime_tools/dtrace_userguide/OTP-10155'

* lukas/runtime_tools/dtrace_userguide/OTP-10155:
  Add DTRACE and SYSTEMTAP howtos as User Guide

8 files changed, 87 insertions, 32 deletions

diff --git a/.gitignore b/.gitignore
index e64cc9ec81..3b0e21bde3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -86,6 +86,8 @@ lib/os_mon/priv/obj/win32/
 lib/runtime_tools/c_src/win32/
 lib/runtime_tools/priv/lib/
 lib/runtime_tools/priv/obj/
+lib/runtime_tools/doc/src/DTRACE.xml
+lib/runtime_tools/doc/src/SYSTEMTAP.xml
 lib/tools/bin/win32/
 lib/tools/c_src/win32/
 lib/tools/obj/win32/
diff --git a/HOWTO/DTRACE.md b/HOWTO/DTRACE.md
index 1d495b0eaf..b719c68c59 100644
--- a/HOWTO/DTRACE.md
+++ b/HOWTO/DTRACE.md
@@ -16,13 +16,13 @@ e.g. `foo_module:dtrace_probe("message goes here!")`.
 Goals
 -----
 
-1. Annotate as much of the Erlang VM as is practical.
+* Annotate as much of the Erlang VM as is practical.
    * The initial goal is to trace file I/O operations.
-2. Support all platforms that implement DTrace: OS X, Solaris,
-   and (I hope) FreeBSD and NetBSD.
-3. To the extent that it's practical, support SystemTap on Linux
-   via DTrace provider compatibility.
-4. Allow Erlang code to supply annotations.
+* Support all platforms that implement DTrace: OS X, Solaris,
+  and (I hope) FreeBSD and NetBSD.
+* To the extent that it's practical, support SystemTap on Linux
+  via DTrace provider compatibility.
+* Allow Erlang code to supply annotations.
 
 Supported platforms
 -------------------
@@ -43,10 +43,10 @@ is `--with-dynamic-trace=systemtap`
 Status
 ------
 
-As of R15B01, the dynamic trace code is included in the main OTP distribution,
+As of R15B01, the dynamic trace code is included in the OTP source distribution,
 although it's considered experimental. The main development of the dtrace code 
 still happens outside of Ericsson, but there is no need to fetch a patched 
-version of OTP to get the basic funtionality. 
+version of the OTP source to get the basic funtionality.
 
 Implementation summary
 ----------------------
@@ -66,9 +66,7 @@ following may be executed in a different Pthread:
 * `efile_drv` command execution (C code)
 * `efile_drv` status return (C code)
 
-**TODO: keep this description up-to-date.**
-
-Example output from `lib/dtrace/examples/efile_drv.d` while executing
+Example output from `lib/runtime_tools/examples/efile_drv.d` while executing
 `file:rename("old-name", "new-name")`:
 
     efile_drv enter tag={3,84} user tag some-user-tag | RENAME (12) | args: old-name new-name , 0 0 (port #Port<0.59>)
@@ -83,7 +81,7 @@ Example output from `lib/dtrace/examples/efile_drv.d` while executing
   these two numbers form a unique ID for the I/O operation.
 * `12` is the command number for the rename operation.  See the
   definition for `FILE_RENAME` in the source code file `efile_drv.c`
-  or the `BEGIN` section of the D script `lib/dtrace/examples/efile_drv.d`.
+  or the `BEGIN` section of the D script `lib/runtime_tools/examples/efile_drv.d`.
 * `old-name` and `new-name` are the two string arguments for the
   source and destination of the `rename(2)` system call.
   The two integer arguments are unused; the simple formatting code
@@ -101,8 +99,8 @@ So, where does the `some-user-tag` string come from?
 
 At the moment, the user tag comes from code like the following:
 
-    put(dtrace_utag, "some-user-tag"),
-    file:rename("old-name", "new-name").
+    dyntrace:put_tag("some-user-tag"),
+    file:rename("old-name", "new-name"),
 
 This method of tagging I/O at the Erlang level is subject to change.
 
diff --git a/HOWTO/SYSTEMTAP.md b/HOWTO/SYSTEMTAP.md
index 094b61f1c0..ce9c0b2f0c 100644
--- a/HOWTO/SYSTEMTAP.md
+++ b/HOWTO/SYSTEMTAP.md
@@ -11,24 +11,24 @@ introduction to Erlang DTrace support read [$ERL_TOP/HOWTO/DTRACE.md][].
 Requisites
 ----------
 
-* Linux Kernel with UTRACE support
-
-  check for UTRACE support in your current kernel:
+*   Linux Kernel with UTRACE support
+    
+    check for UTRACE support in your current kernel:
 
         # grep CONFIG_UTRACE /boot/config-`uname -r`
         CONFIG_UTRACE=y
 
-  Fedora 16 is known to contain UTRACE, for most other Linux distributions
-  a custom build kernel will be required.
-  Check Fedora's SystemTap documentation for additional required packages
-  (e.g. Kernel Debug Symbols)
-
-* SystemTap > 1.6
-
-  A the time of writing this, the latest released version of SystemTap is
-  version 1.6. Erlang's DTrace support requires a MACRO that was introduced
-  after that release. So either get a newer release or build SystemTap from
-  git yourself (see: http://sourceware.org/systemtap/getinvolved.html)
+    Fedora 16 is known to contain UTRACE, for most other Linux distributions
+    a custom build kernel will be required.
+    Check Fedora's SystemTap documentation for additional required packages
+    (e.g. Kernel Debug Symbols)
+
+*   SystemTap > 1.6
+  
+    A the time of writing this, the latest released version of SystemTap is
+    version 1.6. Erlang's DTrace support requires a MACRO that was introduced
+    after that release. So either get a newer release or build SystemTap from
+    git yourself (see: http://sourceware.org/systemtap/getinvolved.html)
 
 Building Erlang
 ---------------
diff --git a/lib/runtime_tools/doc/src/Makefile b/lib/runtime_tools/doc/src/Makefile
index d240b287c3..51d93df418 100644
--- a/lib/runtime_tools/doc/src/Makefile
+++ b/lib/runtime_tools/doc/src/Makefile
@@ -43,9 +43,11 @@ XML_APPLICATION_FILES = ref_man.xml
 XML_REF3_FILES = dbg.xml dyntrace.xml erts_alloc_config.xml
 XML_REF6_FILES = runtime_tools_app.xml
 
-XML_PART_FILES = part_notes.xml part_notes_history.xml
+XML_PART_FILES = part_notes.xml part_notes_history.xml part.xml
 XML_CHAPTER_FILES = notes.xml notes_history.xml
 
+GENERATED_XML_FILES = DTRACE.xml SYSTEMTAP.xml
+
 BOOK_FILES = book.xml
 
 XML_FILES = \
@@ -78,6 +80,11 @@ DVIPS_FLAGS +=
 # ----------------------------------------------------
 # Targets
 # ----------------------------------------------------
+$(XML_FILES): $(GENERATED_XML_FILES)
+
+%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml
+	$(ERL_TOP)/make/emd2exml $< $@
+
 $(HTMLDIR)/%.gif: %.gif
 	$(INSTALL_DATA) $< $@
 
diff --git a/lib/runtime_tools/doc/src/book.xml b/lib/runtime_tools/doc/src/book.xml
index 3f0dd7d55e..ad7d709644 100644
--- a/lib/runtime_tools/doc/src/book.xml
+++ b/lib/runtime_tools/doc/src/book.xml
@@ -34,6 +34,9 @@
   <preamble>
     <contents level="2"></contents>
   </preamble>
+  <parts lift="no">
+    <xi:include href="part.xml"/>
+  </parts>
   <applications>
     <xi:include href="ref_man.xml"/>
   </applications>
diff --git a/lib/runtime_tools/doc/src/dyntrace.xml b/lib/runtime_tools/doc/src/dyntrace.xml
index 9bcbdfc19a..f0149d0665 100644
--- a/lib/runtime_tools/doc/src/dyntrace.xml
+++ b/lib/runtime_tools/doc/src/dyntrace.xml
@@ -42,7 +42,7 @@
     </list>
       <p>Both building with dynamic trace probes and using them is experimental and unsupported by Erlang/OTP. It is included as an option for the developer to trace and debug performance issues in their systems.</p>
       <p>The original implementation is mostly done by Scott Lystiger Fritchie as an Open Source Contribution and it should be viewed as such even though the source for dynamic tracing as well as this module is included in the main distribution. However, the ability to use dynamic tracing of the virtual machine is a very valuable contribution which OTP has every intention to maintain as a tool for the developer.</p>
-      <p>How to write <c>d</c> programs or <c>systemtap</c> scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <c>DTRACE(.md)</c> and <c>SYSTEMTAP(.md)</c> files in the HOWTO folder in the Erlang source directory.</p>
+      <p>How to write <c>d</c> programs or <c>systemtap</c> scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <seealso marker="DTRACE">dtrace</seealso> and <seealso marker="SYSTEMTAP">systemtap</seealso> chapters in the Runtime Tools Users' Guide.</p>
   </description>
   <funcs>
     <func>
diff --git a/lib/runtime_tools/doc/src/part.xml b/lib/runtime_tools/doc/src/part.xml
new file mode 100644
index 0000000000..948d4a8020
--- /dev/null
+++ b/lib/runtime_tools/doc/src/part.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header>
+    <copyright>
+      <year>2012</year><year>2012</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Runtime Tools User's Guide</title>
+    <prepared>Lukas Larsson</prepared>
+    <docno></docno>
+    <date>2012-07-18</date>
+    <rev></rev>
+    <file>part.xml</file>
+  </header>
+  
+  <description>
+      <p><em>Runtime Tools</em></p>
+  </description>
+
+  <xi:include href="DTRACE.xml"/>
+  <xi:include href="SYSTEMTAP.xml"/>
+</part>
+          
+
+
+
diff --git a/make/emd2exml.in b/make/emd2exml.in
index 5bf7758be3..b677ef8ed4 100644
--- a/make/emd2exml.in
+++ b/make/emd2exml.in
@@ -266,8 +266,11 @@ parse(#state{code = true, type = blank, line = CB, code_blank = CBs} = S)  ->
 parse(#state{code = true,
 	     code_blank = CB,
 	     list_lvl = Lvl,
-	     type = {text, TxtLvl},
-	     line = Line} = S) when TxtLvl > Lvl ->
+	     type = {Type, TxtLvl},
+	     line = Line} = S) when TxtLvl > Lvl,
+				    (Type == text orelse 
+				     Type == uolist orelse
+				     Type == olist)  ->
     Data = code(strip_lvls(Lvl+1, Line)),
     parse(get_line(put_chars(S#state{code_blank = []},
 			    [strip_code_blank(Lvl+1, CB), Data])));