[sysprof] help: add FAQ to help topics

[Christian Hergert <chergert src gnome org>]

commit 195b60201d9d3d503ed59b43b8cac5b7cb616948
Author: Alan Conway <aconway redhat com>
Date:   Thu Jun 15 12:20:51 2017 -0400

    help: add FAQ to help topics
    
     - Initial question "what does 'In file [heap]' mean?"
     - Also updated README with some quick-install tips for RPM based systems.

 README            |   20 ++++++++++++++++++++
 help/C/faq.page   |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 help/C/index.page |    4 ++++
 help/Makefile.am  |    1 +
 4 files changed, 71 insertions(+), 0 deletions(-)
---
diff --git a/README b/README
index c2ca903..6358d1d 100644
--- a/README
+++ b/README
@@ -22,3 +22,23 @@ Debugging symbols
 - The programs and libraries you want to profile should be compiled
   with -fno-omit-frame-pointer and have debugging symbols available,
   or you won't get much usable information.
+
+
+Building Sysprof
+----------------
+
+You need some packages installed. The package names may vary depending on your
+distribution, the following command works on Fedora 25:
+
+    sudo dnf install gcc make autoconf automake autopoint libtool ghc-gio
+
+Then do the following:
+
+    ./autogen.sh   # configure, generate makefiles etc.
+    make           # Build the code
+    make install   # Install (default prefix /usr/local)
+
+WARNING: `make install` will mostly install under the configured install prefix
+but installs systemd service configuration directly in the system default
+location `/usr/lib/systemd` so it won't work without root privileges, even if
+the install prefix is a user-owned directory.
diff --git a/help/C/faq.page b/help/C/faq.page
new file mode 100644
index 0000000..e2bc347
--- /dev/null
+++ b/help/C/faq.page
@@ -0,0 +1,46 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="faq">
+
+  <section id="what-does-heap-mean">
+    <info>
+      <link type="guide" xref="index#faq"/>
+    </info>
+    <title>What does "In file [heap]" mean?</title>
+
+    <p>This means that sysprof believes a function was called from somewhere in
+    the program's heap (where <code>malloc</code> allocates memory) rather than
+    the code section (where executable code normally lives.) There are several
+    possible explanations.
+    </p>
+
+    <section>
+      <title>JIT (Just in Time) compilers</title>
+
+      <p>Languages like Java can generate executable code while a program is
+      running and store it in the heap. Sysprof is accurately reporting the
+      situation in this case.</p>
+    </section>
+
+    <section>
+      <title>Optimizing compilers</title>
+
+      <p>C and C++ compilers can optimize away information needed to determine a
+      function's caller, so it is mistaken for [heap]. You can still tell how
+      often each function is called by the program, but not always from
+      where.</p>
+
+      <note>
+        <p>For gcc, the flag <code>-fno-omit-frame-pointer</code> will prevent
+        this optimization. The flag is not always needed, for example on x86_64
+        machines it is only needed with -O3 optimization.</p>
+      </note>
+
+      <note>
+        <p>To get the most detailed and accurate call tree from un-optimized
+        code, use these flags: <code>-ggdb -fno-omit-frame-pointer -O0</code></p>
+      </note>
+    </section>
+  </section>
+</page>
diff --git a/help/C/index.page b/help/C/index.page
index 56596f1..e0de392 100644
--- a/help/C/index.page
+++ b/help/C/index.page
@@ -15,4 +15,8 @@
     <title>Profiling</title>
   </section>
 
+  <section id="faq">
+    <title>Frequently Asked Questions</title>
+  </section>
+
 </page>
diff --git a/help/Makefile.am b/help/Makefile.am
index f14aeb2..564136e 100644
--- a/help/Makefile.am
+++ b/help/Makefile.am
@@ -10,6 +10,7 @@ HELP_FILES = \
        index.page \
        introduction.page \
        profiling.page \
+       faq.page \
        legal.xml
 
 # Translated languages