[PATCH] Use new documentation infrastructure
- From: Dodji Seketeli <dodji seketeli org>
- To: Nemiver Development <nemiver-list gnome org>
- Subject: [PATCH] Use new documentation infrastructure
- Date: Sat, 18 Aug 2012 11:16:48 +0200
Hello,
This is a patch written by Javier Jardón to make Nemiver support the new
Yelp documentation system and thus achieve the GNOME goal
https://live.gnome.org/GnomeGoals/NewDocumentationInfrastructure.
His patch was attached to bugzilla at
https://bugzilla.gnome.org/show_bug.cgi?id=681703.
I have edited it to add a commit log compliant with our commit log rules
explained at https://bugzilla.gnome.org/show_bug.cgi?id=681703.
I've otherwise tested and applied it to the master branch.
Thank you Javier!
* Makefile.am: Don't reference gnome-doc-utils.make.
* configure.ac: Don't use GNOME_DOC_INIT. Use YELP_HELP_INIT.
* help/C/index.docbook: Rename help/C/nemiver.xml into this.
* help/Makefile.am: Update to drop the gnome-doc-utils variables
and use the yelp variables instead.
* help/nemiver.omf.in: Drop this.
---
Makefile.am | 9 +-
configure.ac | 2 +-
help/C/index.docbook | 907 ++++++++++++++++++++++++++++++++++++++++++++++++++
help/C/nemiver.xml | 907 --------------------------------------------------
help/Makefile.am | 18 +-
help/nemiver.omf.in | 10 -
6 files changed, 922 insertions(+), 931 deletions(-)
create mode 100644 help/C/index.docbook
delete mode 100644 help/C/nemiver.xml
delete mode 100644 help/nemiver.omf.in
diff --git a/Makefile.am b/Makefile.am
index b2e5efb..5ec1242 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -15,8 +15,7 @@ INSTALL \
COPYING \
COPYRIGHT \
$(headers) \
-$(INTLTOOL_FILES) \
-gnome-doc-utils.make
+$(INTLTOOL_FILES)
doc:
$(MAKE) -C docs doc
@@ -97,7 +96,5 @@ cat-announcement:
@echo "Last but not least, do not forget to bump up the micro"
@echo "version component to the next (odd) number and commit."
-DISTCLEANFILES = $(INTLTOOL_FILES:.in=) \
- gnome-doc-utils.make
-
-DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper
+DISTCLEANFILES = \
+ $(INTLTOOL_FILES:.in=)
diff --git a/configure.ac b/configure.ac
index ac139c4..91be1fd 100644
--- a/configure.ac
+++ b/configure.ac
@@ -122,7 +122,7 @@ AC_SUBST(nemiverlocaledir)
dnl ***************************
dnl Initialize GNOME doc utils
dnl ***************************
-GNOME_DOC_INIT
+YELP_HELP_INIT
dnl ***************************
dnl a list of enablexxx options
diff --git a/help/C/index.docbook b/help/C/index.docbook
new file mode 100644
index 0000000..f8154cf
--- /dev/null
+++ b/help/C/index.docbook
@@ -0,0 +1,907 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY appversion "0.5.0">
+<!ENTITY manrevision "2.0">
+<!ENTITY date "February 2008">
+<!ENTITY app "Nemiver">
+<!ENTITY appcmd "nemiver">
+<!ENTITY website "http://www.gnome.org/projects/nemiver/";>
+]>
+<!--
+(Do not remove this comment block.)
+Maintained by the GNOME Documentation Project
+http://developer.GNOME.org/projects/gdp
+Template version: 2.0 beta
+Template last modified Jan 30, 2002
+
+-->
+<!-- =============Document Header ============================= -->
+<?chunk-depth 2?>
+<article id="index" lang="en">
+ <!-- please do not change the id; for translations, change lang to -->
+ <!-- appropriate code -->
+ <articleinfo>
+ <title>&app; Manual</title>
+ <copyright>
+ <year>2008</year>
+ <holder>Jonathon Jongsma</holder>
+ </copyright>
+ <!-- translators: uncomment this:
+
+ <copyright>
+ <year>2003</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+
+ -->
+ <publisher role="maintainer">
+ <publishername>&app; Project</publishername>
+ </publisher>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="legal.xml"/>
+ <authorgroup>
+ <author>
+ <firstname>Jonathon</firstname>
+ <surname>Jongsma</surname>
+ <affiliation>
+ <orgname>GNOME</orgname>
+ </affiliation>
+ </author>
+ <!-- This is appropriate place for other contributors: translators,
+ maintainers, etc. Commented out by default.
+ <othercredit role="translator">
+ <firstname>Latin</firstname>
+ <surname>Translator 1</surname>
+ <affiliation>
+ <orgname>Latin Translation Team</orgname>
+ <address> <email>translator gnome org</email> </address>
+ </affiliation>
+ <contrib>Latin translation</contrib>
+ </othercredit>
+ -->
+ </authorgroup>
+ <!-- According to GNU FDL, revision history is mandatory if you are -->
+ <!-- modifying/reusing someone else's document. If not, you can omit it. -->
+ <revhistory>
+ <!-- Remember to remove the &manrevision; entity from the revision entries other
+ than the current revision. -->
+ <revision>
+ <revnumber>1.0</revnumber>
+ <date>2007</date>
+ <revdescription>
+ <para>Initial version</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>&manrevision;</revnumber>
+ <date>2008</date>
+ <revdescription>
+ <para>Updated for 0.5.0 Release</para>
+ </revdescription>
+ </revision>
+ </revhistory>
+ <releaseinfo> This manual describes version &appversion; of &app;.
+ </releaseinfo>
+ <legalnotice>
+ <title>Feedback</title>
+ <para>
+ To report a bug or make a suggestion regarding the
+ <application>&app;</application> application or this manual, see the
+ <ulink url="&website;" type="http">&app; Project website</ulink>.
+ </para>
+ <!-- Translators may also add here feedback address for translations -->
+ </legalnotice>
+ <abstract role="description">
+ <para>
+ &app; is a graphical debugger for the GNOME desktop environment.
+ </para>
+ </abstract>
+ </articleinfo>
+ <indexterm>
+ <primary>&app;</primary>
+ </indexterm>
+ <indexterm>
+ <primary>debugger</primary>
+ </indexterm>
+ <indexterm>
+ <primary>gdb</primary>
+ </indexterm>
+ <!-- ============= Document Body ============================= -->
+ <!-- ============= Introduction ============================== -->
+ <sect1 id="nemiver-sect-intro">
+ <title>Overview</title>
+ <para>
+ &app; is an ongoing effort to write a standalone graphical debugger that
+ integrates well in the GNOME desktop environment. It currently features a
+ backend which uses the well known GNU Debugger gdb to debug C / C++
+ programs.
+ </para>
+ <sect2 id="nemiver-sect-perspectives">
+ <title>Perspectives</title>
+ <para>
+ &app; is designed as a generic graphical
+ <interface>workbench</interface> and a plugin system that can offer
+ several different perspectives. Currently the only perspective
+ provided is a debugging perspective, but in the future, there may be
+ perspectives added for memory debugging with
+ <application>valgrind</application>, or for profiling tools such as
+ <application>oprofile</application>.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="nemiver-sect-getting-started">
+ <title>Getting Started</title>
+ <para>
+ This section explains how to start &app; and gives a basic overview of the
+ application.
+ </para>
+ <sect2 id="nemiver-sect-starting">
+ <title>Starting &app;</title>
+ <para>
+ You can start &app; in the following ways:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><guimenu>Applications</guimenu> menu</term>
+ <listitem>
+ <para>
+ Choose <menuchoice><guisubmenu>Programming</guisubmenu><guimenuitem>Nemiver Debugger</guimenuitem></menuchoice>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Command line</term>
+ <listitem>
+ <para>
+ Type <command>&appcmd;</command>, then press
+ <keycap>Return</keycap>.
+ </para>
+ <tip>
+ <title>Additional Command-line Options</title>
+ <para>
+ You can find a list of options that can be passed to &app; on the
+ command line by typing <command>&appcmd; --help-all</command>.
+ </para>
+ </tip>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ <sect2 id="nemiver-sect-window">
+ <title>The &app; window</title>
+ <para>
+ When you start &app;, you will see a window that looks very much like
+ the following:
+ </para>
+ <figure id="nemiver-window">
+ <title>&app; Window</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/main-window.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows &app; main window.</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+ <para>
+ The <application>&app;</application> window contains the following
+ elements:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Menubar</term>
+ <listitem>
+ <para>
+ The menus on the menubar contain all of the commands you need to
+ use <application>&app;</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Toolbar</term>
+ <listitem>
+ <para>
+ The toolbar contains the basic debugging actions that can be used
+ to run or step through the program being debugged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Source View Notebook</term>
+ <listitem>
+ <para>
+ When source files are open, this area will display source files of
+ the program being debugged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Status Notebook</term>
+ <listitem>
+ <para>
+ The Status notebook contains several tabs for displaying
+ information about the program being debugged. These include the
+ following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ Call Stack
+ </term>
+ <listitem>
+ <para>
+ Displays the current state of the call stack of the program
+ being debugged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Variables
+ </term>
+ <listitem>
+ <para>
+ Displays a list of all local variables and function
+ arguments, in addition to their values and types.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Target Terminal
+ </term>
+ <listitem>
+ <para>
+ If the program being debugged prints any output to the
+ terminal, it will be displayed in this tab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Breakpoints
+ </term>
+ <listitem>
+ <para>
+ This tab displays a list of all breakpoints that have been
+ set. You can view the source code of a particular
+ breakpoint by double-clicking an item in the list or by
+ right-clicking and selecting <menuchoice><guimenuitem>Go to
+ Source</guimenuitem></menuchoice> from the menu. In
+ addition, breakpoints can be deleted, enabled, or disabled
+ in this tab. For more information about breakpoints, see
+ <xref linkend="nemiver-sect-breakpoints"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Registers
+ </term>
+ <listitem>
+ <para>
+ This tab displays all of the CPU registers and their
+ values. For more information, see <xref linkend="nemiver-sect-registers"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ Memory
+ </term>
+ <listitem>
+ <para>
+ This tab displays a view of the current state of a specific
+ memory location. For more information, see <xref linkend="nemiver-sect-memory"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ <sect2 id="nemiver-sect-loading-program">
+ <title>Choosing a Program to Debug</title>
+ <para>There are several ways to begin debugging a program. Nemiver
+ allows you to load a local executable file, load a core file, attach
+ to a running process, or connect to a remote debugging server.
+ </para>
+ <sect3 id="nemiver-sect-starting-executable">
+ <title>Debugging an Executable Program</title>
+ <sect4>
+ <title>Using the Workbench</title>
+ <para>
+ To select an executable program to debug, select
+ <menuchoice><guimenu>
+ File
+ </guimenu><guimenuitem>
+ Execute...
+ </guimenuitem></menuchoice>, which should display the following dialog:
+ </para>
+ <figure id="nemiver-execute-dialog">
+ <title>Execute Dialog</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/execute-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows dialog for selecting an executable to run</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+ <para>
+ In this dialog, you can select the program to be debugged, any
+ arguments or options to be passed to the executable on the command line, the
+ working directory to run the executable in, and any Environment
+ Variables that should be set when the executable is being debugged.
+ </para>
+ </sect4>
+ <sect4>
+ <title>Using the Command Line</title>
+ <para>
+ To start an executable program to debug from the command line, simply
+ specify the name of the executable. You can either give an absolute
+ path to the executable, or if it is in the path, you can simply give
+ the basename of the executable. For example, if
+ <filename>/usr/bin</filename> is in your path, both of the following
+ are valid:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <command>&appcmd; /usr/bin/progname</command>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>&appcmd; progname</command>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <tip>
+ <title>Passing Options on the Command Line</title>
+ <para>
+ If you would like to pass command line options to the program that
+ you are debugging, you should enclose them in quotes to prevent
+ &app; from processing them:
+ <command>&appcmd; "prognam --arg1 --arg2"</command>.
+ </para>
+ </tip>
+ </sect4>
+ </sect3>
+ <sect3 id="nemiver-sect-attach">
+ <title>Attaching to a Running Program</title>
+ <sect4>
+ <title>Using the Workbench</title>
+ <para>
+ Select the menu item
+ <menuchoice><guimenu>
+ File
+ </guimenu><guimenuitem>
+ Attach to Running Program...
+ </guimenuitem></menuchoice>, which should display the following dialog:
+ </para>
+ <figure id="nemiver-attach-dialog">
+ <title>Attach Dialog</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/attach-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows dialog for attaching to a running program</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+ <para>
+ Select a process from the list and click
+ <guibutton>OK</guibutton> to start debugging the selected program.
+ There may be a lot of processes listed in the dialog, so you can
+ filter the list to only ones that that you are interested in by typing
+ some text into the text entry located just below the list.
+ </para>
+ </sect4>
+ <sect4>
+ <title>Using the Command Line</title>
+ <para>
+ To attach to a running program from the command line, use the
+ <option>--attach</option> option. The <option>--attach</option>
+ option accepts either a pid or a process name. So, for example, to
+ debug the running process <command>foo</command> which has a pid of
+ 1121, you could either type <command>&appcmd; --attach foo</command>
+ or <command>&appcmd; --attach 1121</command>.
+ </para>
+ </sect4>
+ </sect3>
+ <sect3 id="nemiver-sect-core-file">
+ <title>Loading a Core File</title>
+ <sect4>
+ <title>Using the Workbench</title>
+ <para>
+ Select the menu item
+ <menuchoice><guimenu>
+ File
+ </guimenu><guimenuitem>
+ Load Core File...
+ </guimenuitem></menuchoice>
+ to bring up the following dialog, which will let you load a core file:
+ </para>
+ <figure id="nemiver-load-core-dialog">
+ <title>Load Core File Dialog</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/load-core-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows dialog for loading a core file</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+ </sect4>
+ <sect4>
+ <title>Using the Command Line</title>
+ <para>
+ Core files cannot be loaded from the command line.
+ </para>
+ </sect4>
+ </sect3>
+ <sect3 id="nemiver-sect-remote">
+ <title>Remote Debugging</title>
+ <para>
+ &app; allows you to connect to a remote debugging server.
+ </para>
+ <sect4>
+ <title>Using the Workbench</title>
+ <para>
+ To connect to a remote debugging server, select
+ <menuchoice><guimenu>File</guimenu><guimenuitem>Connect to
+ Remote Target...</guimenuitem></menuchoice>
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/connect-remote-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Remote Debugging Dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ Select the executable to load and the location where any shared
+ libraries are located, and then fill in the details about
+ connecting to the remote server.
+ </para>
+ </sect4>
+ <sect4>
+ <title>Using the Command Line</title>
+ <para>
+ &app; does not provide a way to connect to a remote server using
+ the command line
+ </para>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id="nemiver-sect-using">
+ <title>Using &app;</title>
+ <para>
+ This section describes how to use &app; to debug your application.
+ </para>
+ <sect2 id="nemiver-sect-basic-debugging">
+ <title>Basic Debugging Actions</title>
+ <para>
+ The basic debugging actions are available on the main toolbar, in the
+ <guimenu>Debug</guimenu> menu, and as keyboard shortcuts.
+ The most common actions are listed below:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Continue</term>
+ <listitem>
+ <para>
+ Starts the program. The program will run until it hits a
+ breakpoint or until the program ends, unless it is interrupted
+ manually by the user by clicking <action>Stop</action>. This
+ action can be activated from the keyboard with
+ <keycap>F5</keycap>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Next</term>
+ <listitem>
+ <para>
+ Executes the next statement, and stops when it reaches the next
+ line in this file. Some debuggers may call this action "Step
+ Over". This action can be activated from the keyboard with
+ <keycap>F6</keycap>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Step</term>
+ <listitem>
+ <para>
+ Executes the next statement, stepping into the function if possible.
+ Some debuggers may call this action "Step In". This action can be
+ activated from the keyboard with <keycap>F7</keycap>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Step Out</term>
+ <listitem>
+ <para>
+ Finishes execution of the current function and stops when it
+ returns to the calling function. This action can be
+ activated from the keyboard with
+ <keycombo><keycap>Shift</keycap><keycap>F7</keycap></keycombo>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Restart</term>
+ <listitem>
+ <para>
+ Reloads the current executable and starts execution from the beginning.
+ This action can be activated from the keyboard with
+ <keycombo><keycap>Shift</keycap><keycap>F5</keycap></keycombo>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Stop</term>
+ <listitem>
+ <para>
+ Manually interrupt execution of the program. This action is only
+ available when the debugger is running the executable (e.g. after
+ a user has clicked <action>Continue</action>). This action can be
+ activated from the keyboard with <keycap>F9</keycap>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ By default, after loading an executable, &app; creates a breakpoint at
+ <function>main()</function>, so when execution reaches
+ <function>main()</function>, it will stop and wait for input. You can
+ then step through the program, examine variables (see <xref linkend="nemiver-sect-inspecting-variables"/>), or set additional
+ breakpoints (see <xref linkend="nemiver-sect-breakpoints"/>).
+ </para>
+ </sect2>
+ <sect2 id="nemiver-sect-inspecting-variables">
+ <title>Inspecting Variables</title>
+ <para>
+ &app; displays a list of all local variables in the
+ <interface>Variables</interface> tab of the
+ <interface>Status Notebook</interface>. If you'd like to examine a different variable (or even an arbitrary expression), you can use the <interface>Variable Inspector</interface>. To bring up the <interface>Variable Inspector</interface>, select
+ <menuchoice><guimenu>Debug</guimenu><guimenuitem>Inspect a Variable</guimenuitem></menuchoice>. When the variable inspector comes up, you'll see a
+ window that looks similar to the following:
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/variable-inspector.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Variable Inspector Dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ You can type any variable name or a simple expression (such as
+ <literal>pFoo->bar</literal>) into the input box, and if the variable is
+ valid and in scope, it will be display details about that expression.
+ </para>
+ <para>
+ Alternately, if you select the name of a variable in the
+ <interface>source editor</interface>, and then launch the
+ <interface>Variable Inspector</interface>, it will attempt to display
+ information about the selected variable name.
+ </para>
+ <tip>
+ <title>Keyboard Shortcut</title>
+ <para>
+ You can also start the <interface>Variable Inspector</interface> by
+ pressing <keycap>F12</keycap>.
+ </para>
+ </tip>
+ <para>
+ &app; will also let you display a list of all global variables in an application in a separate dialog. To display the <interface>Global Variables</interface> dialog, select
+ <menuchoice><guimenu>Debug</guimenu><guimenuitem>Show Global Variables</guimenuitem></menuchoice>
+ or press
+ <keycombo><keycap>Ctrl</keycap><keycap>G</keycap></keycombo>.
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/global-variables-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Global Variables Dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <warning>
+ <para>
+ For some programs (especially C++ programs), listing all of the
+ global variables may take a very long time.
+ </para>
+ </warning>
+ </sect2>
+ <sect2 id="nemiver-sect-breakpoints">
+ <title>Setting Breakpoints</title>
+ <para>
+ There are several different ways to set breakpoints in &app;. &app;
+ automatically sets a breakpoint at <function>main()</function> when you
+ first begin debugging a new executable. If you want to set additional
+ breakpoints you can do one of the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Click in the margin next to the line where you want the
+ breakpoint to be set</para>
+ </listitem>
+ <listitem>
+ <para>Place your cursor on a line where you want the breakpoint to be set and set the breakpoint by either selecting
+ <menuchoice><guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint at Cursor</guimenuitem></menuchoice>, or by pressing <keycap>F8</keycap>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Set a breakpoint at a specific function name or at a specific location in a file by selecting
+ <menuchoice><guimenu>Debug</guimenu><guimenuitem>Set Breakpoint...</guimenuitem></menuchoice> or by pressing
+ <keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo>. This will bring up a dialog that looks like the following:
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/set-breakpoint-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Set Breakpoint Dialog</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ You can specify a breakpoint at a particular location in a file, or
+ by function name. If there are more than one function with the same
+ name, &app; will display a list of all matching functions and ask
+ you to pick the one you want.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <sect3>
+ <title>Disabled Breakpoints</title>
+ <para>
+ Breakpoints can be either enabled or disabled. The debugger will stop
+ execution whenever it reaches an enabled breakpoint but will not be
+ affected by any breakpoints in the disabled state. This allows you to
+ temporarily remove a breakpoint without actually deleting it.
+ </para>
+ <para>
+ To disable or enable a breakpoint, click the checkbox next to the
+ breakpoint number you want to enable or disable in the
+ <interface>Breakpoints</interface> tab of the <interface>Status
+ Notebook</interface>. Alternately, you can press
+ <keycombo><keycap>Shift</keycap><keycap>F8</keycap></keycombo> to enable or disable a breakpoint that is set on the
+ line that the cursor is currently on.
+ </para>
+ <para>
+ The following figures show the difference between enabled and
+ disabled breakpoints in the source editor.
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/enabled-breakpoint.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Illustration of an enabled breakpoint</phrase>
+ </textobject>
+ <caption><para>Enabled Breakpoint</para></caption>
+ </mediaobject>
+ </screenshot>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/disabled-breakpoint.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Illustration of a disabled breakpoint</phrase>
+ </textobject>
+ <caption><para>Disabled Breakpoint</para></caption>
+ </mediaobject>
+ </screenshot>
+ </sect3>
+ <sect3>
+ <title>Opening Source Files</title>
+ <para>
+ Sometimes you don't know exactly the function name or line number
+ where you want a breakpoint to be set, so you must open a source file
+ to figure it out. You could just open arbitrary files from the
+ filesystem, but &app; can also provide a list of source files that
+ were used to build the executable and allow you to select from this
+ list. When you select
+ <menuchoice><guimenu>File</guimenu><guimenuitem>Open Source File...</guimenuitem></menuchoice>, the following window should be displayed:
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/open-files-target.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows dialog for opening source files</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ To select an arbitrary file from the filesystem, choose the
+ <guilabel>Select from Filesystem</guilabel> option. To select from a
+ list of files that produced the executable, choose <guilabel>Select
+ from Target Executable</guilabel>.
+ </para>
+ <warning>
+ <title>Determining Source Files for Dynamically Loaded Modules</title>
+ <para>
+ If the target executable loads modules at runtime (e.g. using
+ <function>dlopen()</function>), &app; will not be able to determine
+ which files were used to build these modules until they are actually
+ loaded.
+ </para>
+ </warning>
+ </sect3>
+ </sect2>
+ <sect2 id="nemiver-sect-advanced">
+ <title>Advanced Debugging</title>
+ <sect3 id="nemiver-sect-registers">
+ <title>Registers</title>
+ <para>
+ The register editing widget is located in the
+ <interface>Registers</interface> tab of the <interface>Status
+ Notebook</interface>. Alternately, you can press
+ <keycombo><keycap>Alt</keycap><keycap>F5</keycap></keycombo> to
+ jump directly to the correct tab.
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/registers-view.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>The Register Editing Widget</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ This widget shows the current values of all of the CPU
+ registers. You can edit the register values by clicking in the
+ <interface>Value</interface> column and entering a new value.
+ If the value for the register changed since the last time the
+ debugger stopped, it will be highlighted in red.
+ </para>
+ </sect3>
+ <sect3 id="nemiver-sect-memory">
+ <title>Memory</title>
+ <para>
+ The memory widget allows you to view a section of memory
+ directly. This enables you to get a lower-level view of what's
+ happening while your program is running.
+ </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/memory-view.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>The Memory Editing Widget</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ To display a segment of memory in the memory view widget, enter
+ a memory address in the <interface>Address</interface> field.
+ If the address is valid for the program being debugged, the
+ memory view will display the memory values starting at the
+ specified address. Memory values can be displayed in byte
+ format, word format (2 bytes), or long word format (4 bytes) by
+ choosing an option from the <interface>Group By</interface>
+ drop-down menu. The memory values will automatically be updated
+ as you step through the program.
+ </para>
+ <para>
+ In addition to viewing the memory values, you can also use the
+ memory widget to modify memory values. You can edit either the
+ hex byte representation (the left-hand section of the memory
+ widget), or the ASCII representation (the right-hand section of
+ the memory widget). All changes will be applied immediately.
+ </para>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id="nemiver-sect-sessions">
+ <title>Session Save and Restore</title>
+ <para>
+ &app; can save your debugging sessions for you so that you can resume
+ them at a later time. This includes saving information such as which
+ executable is being debugged, what environment variables are set, what
+ command-line options are passed to the executable, which files are open,
+ and which breakpoints are set so that you can get back to where you left
+ off last time as quickly as possible.
+ </para>
+ <sect2 id="nemiver-sect-saving-sessions">
+ <title>Saving Sessions</title>
+ <para>
+ &app; will save your session automatically on exit, so you don't even
+ have to worry about it. However, if you want to explicitly save the
+ session before closing &app;, you can do so by selecting
+ <menuchoice><guimenu>File</guimenu><guimenuitem>Save Session To Disk</guimenuitem></menuchoice>.
+ </para>
+ </sect2>
+ <sect2 id="nemiver-sect-resuming-sessions">
+ <title>Resuming Saved Sessions</title>
+ <sect3>
+ <title>Using the Workbench</title>
+ <para>
+ Select
+ <menuchoice><guimenu>File</guimenu><guimenuitem>Resume Saved Session...</guimenuitem></menuchoice>
+ and select a session from the list.
+ </para>
+ <figure id="nemiver-sessions-dialog">
+ <title>Session Dialog</title>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/sessions-dialog.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Shows dialog for resuming a saved session</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ </figure>
+ </sect3>
+ <sect3>
+ <title>From the Command Line</title>
+ <para>
+ If you know the session ID of the session you want to run, you can
+ start that debugging session from the command line. For example, if
+ you want to run session number 3, you can do so with the following
+ command:
+ <command>&appcmd; --session 3</command>.
+ </para>
+ </sect3>
+ </sect2>
+ </sect1>
+ <!-- This should be the last section in the manual -->
+ <sect1 id="nemiver-sect-about">
+ <title>About &app;</title>
+ <para><application>&app;</application> was written by Dodji Seketeli and
+ Jonathon Jongsma, with contributions from many others. To find more
+ information about &app;, please visit the <ulink url="&website;" type="http">&app; project website</ulink>.
+ </para>
+ <para>
+ To report a bug or make a suggestion regarding this application or this
+ manual, see the Feedback section of the <ulink url="ghelp:user-guide?feedback-bugs" type="help">GNOME User
+ Guide</ulink>.
+ </para>
+ <para>
+ This program is distributed under the terms of the GNU General Public
+ license as published by the Free Software Foundation; either version 2 of
+ the License, or (at your option) any later version. A copy of this license
+ can be found at this <ulink url="ghelp:gpl" type="help">link</ulink>, or
+ in the file COPYING included with the source code of this program.
+ </para>
+ </sect1>
+</article>
+<!--
+vim: ts=2 sw=2 et
+-->
diff --git a/help/C/nemiver.xml b/help/C/nemiver.xml
deleted file mode 100644
index f8154cf..0000000
--- a/help/C/nemiver.xml
+++ /dev/null
@@ -1,907 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
-<!ENTITY appversion "0.5.0">
-<!ENTITY manrevision "2.0">
-<!ENTITY date "February 2008">
-<!ENTITY app "Nemiver">
-<!ENTITY appcmd "nemiver">
-<!ENTITY website "http://www.gnome.org/projects/nemiver/";>
-]>
-<!--
-(Do not remove this comment block.)
-Maintained by the GNOME Documentation Project
-http://developer.GNOME.org/projects/gdp
-Template version: 2.0 beta
-Template last modified Jan 30, 2002
-
--->
-<!-- =============Document Header ============================= -->
-<?chunk-depth 2?>
-<article id="index" lang="en">
- <!-- please do not change the id; for translations, change lang to -->
- <!-- appropriate code -->
- <articleinfo>
- <title>&app; Manual</title>
- <copyright>
- <year>2008</year>
- <holder>Jonathon Jongsma</holder>
- </copyright>
- <!-- translators: uncomment this:
-
- <copyright>
- <year>2003</year>
- <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
- </copyright>
-
- -->
- <publisher role="maintainer">
- <publishername>&app; Project</publishername>
- </publisher>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="legal.xml"/>
- <authorgroup>
- <author>
- <firstname>Jonathon</firstname>
- <surname>Jongsma</surname>
- <affiliation>
- <orgname>GNOME</orgname>
- </affiliation>
- </author>
- <!-- This is appropriate place for other contributors: translators,
- maintainers, etc. Commented out by default.
- <othercredit role="translator">
- <firstname>Latin</firstname>
- <surname>Translator 1</surname>
- <affiliation>
- <orgname>Latin Translation Team</orgname>
- <address> <email>translator gnome org</email> </address>
- </affiliation>
- <contrib>Latin translation</contrib>
- </othercredit>
- -->
- </authorgroup>
- <!-- According to GNU FDL, revision history is mandatory if you are -->
- <!-- modifying/reusing someone else's document. If not, you can omit it. -->
- <revhistory>
- <!-- Remember to remove the &manrevision; entity from the revision entries other
- than the current revision. -->
- <revision>
- <revnumber>1.0</revnumber>
- <date>2007</date>
- <revdescription>
- <para>Initial version</para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>&manrevision;</revnumber>
- <date>2008</date>
- <revdescription>
- <para>Updated for 0.5.0 Release</para>
- </revdescription>
- </revision>
- </revhistory>
- <releaseinfo> This manual describes version &appversion; of &app;.
- </releaseinfo>
- <legalnotice>
- <title>Feedback</title>
- <para>
- To report a bug or make a suggestion regarding the
- <application>&app;</application> application or this manual, see the
- <ulink url="&website;" type="http">&app; Project website</ulink>.
- </para>
- <!-- Translators may also add here feedback address for translations -->
- </legalnotice>
- <abstract role="description">
- <para>
- &app; is a graphical debugger for the GNOME desktop environment.
- </para>
- </abstract>
- </articleinfo>
- <indexterm>
- <primary>&app;</primary>
- </indexterm>
- <indexterm>
- <primary>debugger</primary>
- </indexterm>
- <indexterm>
- <primary>gdb</primary>
- </indexterm>
- <!-- ============= Document Body ============================= -->
- <!-- ============= Introduction ============================== -->
- <sect1 id="nemiver-sect-intro">
- <title>Overview</title>
- <para>
- &app; is an ongoing effort to write a standalone graphical debugger that
- integrates well in the GNOME desktop environment. It currently features a
- backend which uses the well known GNU Debugger gdb to debug C / C++
- programs.
- </para>
- <sect2 id="nemiver-sect-perspectives">
- <title>Perspectives</title>
- <para>
- &app; is designed as a generic graphical
- <interface>workbench</interface> and a plugin system that can offer
- several different perspectives. Currently the only perspective
- provided is a debugging perspective, but in the future, there may be
- perspectives added for memory debugging with
- <application>valgrind</application>, or for profiling tools such as
- <application>oprofile</application>.
- </para>
- </sect2>
- </sect1>
- <sect1 id="nemiver-sect-getting-started">
- <title>Getting Started</title>
- <para>
- This section explains how to start &app; and gives a basic overview of the
- application.
- </para>
- <sect2 id="nemiver-sect-starting">
- <title>Starting &app;</title>
- <para>
- You can start &app; in the following ways:
- </para>
- <variablelist>
- <varlistentry>
- <term><guimenu>Applications</guimenu> menu</term>
- <listitem>
- <para>
- Choose <menuchoice><guisubmenu>Programming</guisubmenu><guimenuitem>Nemiver Debugger</guimenuitem></menuchoice>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Command line</term>
- <listitem>
- <para>
- Type <command>&appcmd;</command>, then press
- <keycap>Return</keycap>.
- </para>
- <tip>
- <title>Additional Command-line Options</title>
- <para>
- You can find a list of options that can be passed to &app; on the
- command line by typing <command>&appcmd; --help-all</command>.
- </para>
- </tip>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- <sect2 id="nemiver-sect-window">
- <title>The &app; window</title>
- <para>
- When you start &app;, you will see a window that looks very much like
- the following:
- </para>
- <figure id="nemiver-window">
- <title>&app; Window</title>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/main-window.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Shows &app; main window.</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- </figure>
- <para>
- The <application>&app;</application> window contains the following
- elements:
- </para>
- <variablelist>
- <varlistentry>
- <term>Menubar</term>
- <listitem>
- <para>
- The menus on the menubar contain all of the commands you need to
- use <application>&app;</application>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Toolbar</term>
- <listitem>
- <para>
- The toolbar contains the basic debugging actions that can be used
- to run or step through the program being debugged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Source View Notebook</term>
- <listitem>
- <para>
- When source files are open, this area will display source files of
- the program being debugged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Status Notebook</term>
- <listitem>
- <para>
- The Status notebook contains several tabs for displaying
- information about the program being debugged. These include the
- following:
- </para>
- <variablelist>
- <varlistentry>
- <term>
- Call Stack
- </term>
- <listitem>
- <para>
- Displays the current state of the call stack of the program
- being debugged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- Variables
- </term>
- <listitem>
- <para>
- Displays a list of all local variables and function
- arguments, in addition to their values and types.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- Target Terminal
- </term>
- <listitem>
- <para>
- If the program being debugged prints any output to the
- terminal, it will be displayed in this tab.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- Breakpoints
- </term>
- <listitem>
- <para>
- This tab displays a list of all breakpoints that have been
- set. You can view the source code of a particular
- breakpoint by double-clicking an item in the list or by
- right-clicking and selecting <menuchoice><guimenuitem>Go to
- Source</guimenuitem></menuchoice> from the menu. In
- addition, breakpoints can be deleted, enabled, or disabled
- in this tab. For more information about breakpoints, see
- <xref linkend="nemiver-sect-breakpoints"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- Registers
- </term>
- <listitem>
- <para>
- This tab displays all of the CPU registers and their
- values. For more information, see <xref linkend="nemiver-sect-registers"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- Memory
- </term>
- <listitem>
- <para>
- This tab displays a view of the current state of a specific
- memory location. For more information, see <xref linkend="nemiver-sect-memory"/>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- <sect2 id="nemiver-sect-loading-program">
- <title>Choosing a Program to Debug</title>
- <para>There are several ways to begin debugging a program. Nemiver
- allows you to load a local executable file, load a core file, attach
- to a running process, or connect to a remote debugging server.
- </para>
- <sect3 id="nemiver-sect-starting-executable">
- <title>Debugging an Executable Program</title>
- <sect4>
- <title>Using the Workbench</title>
- <para>
- To select an executable program to debug, select
- <menuchoice><guimenu>
- File
- </guimenu><guimenuitem>
- Execute...
- </guimenuitem></menuchoice>, which should display the following dialog:
- </para>
- <figure id="nemiver-execute-dialog">
- <title>Execute Dialog</title>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/execute-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Shows dialog for selecting an executable to run</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- </figure>
- <para>
- In this dialog, you can select the program to be debugged, any
- arguments or options to be passed to the executable on the command line, the
- working directory to run the executable in, and any Environment
- Variables that should be set when the executable is being debugged.
- </para>
- </sect4>
- <sect4>
- <title>Using the Command Line</title>
- <para>
- To start an executable program to debug from the command line, simply
- specify the name of the executable. You can either give an absolute
- path to the executable, or if it is in the path, you can simply give
- the basename of the executable. For example, if
- <filename>/usr/bin</filename> is in your path, both of the following
- are valid:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <command>&appcmd; /usr/bin/progname</command>
- </para>
- </listitem>
- <listitem>
- <para>
- <command>&appcmd; progname</command>
- </para>
- </listitem>
- </itemizedlist>
- <tip>
- <title>Passing Options on the Command Line</title>
- <para>
- If you would like to pass command line options to the program that
- you are debugging, you should enclose them in quotes to prevent
- &app; from processing them:
- <command>&appcmd; "prognam --arg1 --arg2"</command>.
- </para>
- </tip>
- </sect4>
- </sect3>
- <sect3 id="nemiver-sect-attach">
- <title>Attaching to a Running Program</title>
- <sect4>
- <title>Using the Workbench</title>
- <para>
- Select the menu item
- <menuchoice><guimenu>
- File
- </guimenu><guimenuitem>
- Attach to Running Program...
- </guimenuitem></menuchoice>, which should display the following dialog:
- </para>
- <figure id="nemiver-attach-dialog">
- <title>Attach Dialog</title>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/attach-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Shows dialog for attaching to a running program</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- </figure>
- <para>
- Select a process from the list and click
- <guibutton>OK</guibutton> to start debugging the selected program.
- There may be a lot of processes listed in the dialog, so you can
- filter the list to only ones that that you are interested in by typing
- some text into the text entry located just below the list.
- </para>
- </sect4>
- <sect4>
- <title>Using the Command Line</title>
- <para>
- To attach to a running program from the command line, use the
- <option>--attach</option> option. The <option>--attach</option>
- option accepts either a pid or a process name. So, for example, to
- debug the running process <command>foo</command> which has a pid of
- 1121, you could either type <command>&appcmd; --attach foo</command>
- or <command>&appcmd; --attach 1121</command>.
- </para>
- </sect4>
- </sect3>
- <sect3 id="nemiver-sect-core-file">
- <title>Loading a Core File</title>
- <sect4>
- <title>Using the Workbench</title>
- <para>
- Select the menu item
- <menuchoice><guimenu>
- File
- </guimenu><guimenuitem>
- Load Core File...
- </guimenuitem></menuchoice>
- to bring up the following dialog, which will let you load a core file:
- </para>
- <figure id="nemiver-load-core-dialog">
- <title>Load Core File Dialog</title>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/load-core-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Shows dialog for loading a core file</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- </figure>
- </sect4>
- <sect4>
- <title>Using the Command Line</title>
- <para>
- Core files cannot be loaded from the command line.
- </para>
- </sect4>
- </sect3>
- <sect3 id="nemiver-sect-remote">
- <title>Remote Debugging</title>
- <para>
- &app; allows you to connect to a remote debugging server.
- </para>
- <sect4>
- <title>Using the Workbench</title>
- <para>
- To connect to a remote debugging server, select
- <menuchoice><guimenu>File</guimenu><guimenuitem>Connect to
- Remote Target...</guimenuitem></menuchoice>
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/connect-remote-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Remote Debugging Dialog</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- Select the executable to load and the location where any shared
- libraries are located, and then fill in the details about
- connecting to the remote server.
- </para>
- </sect4>
- <sect4>
- <title>Using the Command Line</title>
- <para>
- &app; does not provide a way to connect to a remote server using
- the command line
- </para>
- </sect4>
- </sect3>
- </sect2>
- </sect1>
- <sect1 id="nemiver-sect-using">
- <title>Using &app;</title>
- <para>
- This section describes how to use &app; to debug your application.
- </para>
- <sect2 id="nemiver-sect-basic-debugging">
- <title>Basic Debugging Actions</title>
- <para>
- The basic debugging actions are available on the main toolbar, in the
- <guimenu>Debug</guimenu> menu, and as keyboard shortcuts.
- The most common actions are listed below:
- </para>
- <variablelist>
- <varlistentry>
- <term>Continue</term>
- <listitem>
- <para>
- Starts the program. The program will run until it hits a
- breakpoint or until the program ends, unless it is interrupted
- manually by the user by clicking <action>Stop</action>. This
- action can be activated from the keyboard with
- <keycap>F5</keycap>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Next</term>
- <listitem>
- <para>
- Executes the next statement, and stops when it reaches the next
- line in this file. Some debuggers may call this action "Step
- Over". This action can be activated from the keyboard with
- <keycap>F6</keycap>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Step</term>
- <listitem>
- <para>
- Executes the next statement, stepping into the function if possible.
- Some debuggers may call this action "Step In". This action can be
- activated from the keyboard with <keycap>F7</keycap>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Step Out</term>
- <listitem>
- <para>
- Finishes execution of the current function and stops when it
- returns to the calling function. This action can be
- activated from the keyboard with
- <keycombo><keycap>Shift</keycap><keycap>F7</keycap></keycombo>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Restart</term>
- <listitem>
- <para>
- Reloads the current executable and starts execution from the beginning.
- This action can be activated from the keyboard with
- <keycombo><keycap>Shift</keycap><keycap>F5</keycap></keycombo>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Stop</term>
- <listitem>
- <para>
- Manually interrupt execution of the program. This action is only
- available when the debugger is running the executable (e.g. after
- a user has clicked <action>Continue</action>). This action can be
- activated from the keyboard with <keycap>F9</keycap>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- By default, after loading an executable, &app; creates a breakpoint at
- <function>main()</function>, so when execution reaches
- <function>main()</function>, it will stop and wait for input. You can
- then step through the program, examine variables (see <xref linkend="nemiver-sect-inspecting-variables"/>), or set additional
- breakpoints (see <xref linkend="nemiver-sect-breakpoints"/>).
- </para>
- </sect2>
- <sect2 id="nemiver-sect-inspecting-variables">
- <title>Inspecting Variables</title>
- <para>
- &app; displays a list of all local variables in the
- <interface>Variables</interface> tab of the
- <interface>Status Notebook</interface>. If you'd like to examine a different variable (or even an arbitrary expression), you can use the <interface>Variable Inspector</interface>. To bring up the <interface>Variable Inspector</interface>, select
- <menuchoice><guimenu>Debug</guimenu><guimenuitem>Inspect a Variable</guimenuitem></menuchoice>. When the variable inspector comes up, you'll see a
- window that looks similar to the following:
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/variable-inspector.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Variable Inspector Dialog</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- You can type any variable name or a simple expression (such as
- <literal>pFoo->bar</literal>) into the input box, and if the variable is
- valid and in scope, it will be display details about that expression.
- </para>
- <para>
- Alternately, if you select the name of a variable in the
- <interface>source editor</interface>, and then launch the
- <interface>Variable Inspector</interface>, it will attempt to display
- information about the selected variable name.
- </para>
- <tip>
- <title>Keyboard Shortcut</title>
- <para>
- You can also start the <interface>Variable Inspector</interface> by
- pressing <keycap>F12</keycap>.
- </para>
- </tip>
- <para>
- &app; will also let you display a list of all global variables in an application in a separate dialog. To display the <interface>Global Variables</interface> dialog, select
- <menuchoice><guimenu>Debug</guimenu><guimenuitem>Show Global Variables</guimenuitem></menuchoice>
- or press
- <keycombo><keycap>Ctrl</keycap><keycap>G</keycap></keycombo>.
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/global-variables-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Global Variables Dialog</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <warning>
- <para>
- For some programs (especially C++ programs), listing all of the
- global variables may take a very long time.
- </para>
- </warning>
- </sect2>
- <sect2 id="nemiver-sect-breakpoints">
- <title>Setting Breakpoints</title>
- <para>
- There are several different ways to set breakpoints in &app;. &app;
- automatically sets a breakpoint at <function>main()</function> when you
- first begin debugging a new executable. If you want to set additional
- breakpoints you can do one of the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>Click in the margin next to the line where you want the
- breakpoint to be set</para>
- </listitem>
- <listitem>
- <para>Place your cursor on a line where you want the breakpoint to be set and set the breakpoint by either selecting
- <menuchoice><guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint at Cursor</guimenuitem></menuchoice>, or by pressing <keycap>F8</keycap>
- </para>
- </listitem>
- <listitem>
- <para>Set a breakpoint at a specific function name or at a specific location in a file by selecting
- <menuchoice><guimenu>Debug</guimenu><guimenuitem>Set Breakpoint...</guimenuitem></menuchoice> or by pressing
- <keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo>. This will bring up a dialog that looks like the following:
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/set-breakpoint-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Set Breakpoint Dialog</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- You can specify a breakpoint at a particular location in a file, or
- by function name. If there are more than one function with the same
- name, &app; will display a list of all matching functions and ask
- you to pick the one you want.
- </para>
- </listitem>
- </itemizedlist>
- <sect3>
- <title>Disabled Breakpoints</title>
- <para>
- Breakpoints can be either enabled or disabled. The debugger will stop
- execution whenever it reaches an enabled breakpoint but will not be
- affected by any breakpoints in the disabled state. This allows you to
- temporarily remove a breakpoint without actually deleting it.
- </para>
- <para>
- To disable or enable a breakpoint, click the checkbox next to the
- breakpoint number you want to enable or disable in the
- <interface>Breakpoints</interface> tab of the <interface>Status
- Notebook</interface>. Alternately, you can press
- <keycombo><keycap>Shift</keycap><keycap>F8</keycap></keycombo> to enable or disable a breakpoint that is set on the
- line that the cursor is currently on.
- </para>
- <para>
- The following figures show the difference between enabled and
- disabled breakpoints in the source editor.
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/enabled-breakpoint.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Illustration of an enabled breakpoint</phrase>
- </textobject>
- <caption><para>Enabled Breakpoint</para></caption>
- </mediaobject>
- </screenshot>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/disabled-breakpoint.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Illustration of a disabled breakpoint</phrase>
- </textobject>
- <caption><para>Disabled Breakpoint</para></caption>
- </mediaobject>
- </screenshot>
- </sect3>
- <sect3>
- <title>Opening Source Files</title>
- <para>
- Sometimes you don't know exactly the function name or line number
- where you want a breakpoint to be set, so you must open a source file
- to figure it out. You could just open arbitrary files from the
- filesystem, but &app; can also provide a list of source files that
- were used to build the executable and allow you to select from this
- list. When you select
- <menuchoice><guimenu>File</guimenu><guimenuitem>Open Source File...</guimenuitem></menuchoice>, the following window should be displayed:
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/open-files-target.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Shows dialog for opening source files</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- To select an arbitrary file from the filesystem, choose the
- <guilabel>Select from Filesystem</guilabel> option. To select from a
- list of files that produced the executable, choose <guilabel>Select
- from Target Executable</guilabel>.
- </para>
- <warning>
- <title>Determining Source Files for Dynamically Loaded Modules</title>
- <para>
- If the target executable loads modules at runtime (e.g. using
- <function>dlopen()</function>), &app; will not be able to determine
- which files were used to build these modules until they are actually
- loaded.
- </para>
- </warning>
- </sect3>
- </sect2>
- <sect2 id="nemiver-sect-advanced">
- <title>Advanced Debugging</title>
- <sect3 id="nemiver-sect-registers">
- <title>Registers</title>
- <para>
- The register editing widget is located in the
- <interface>Registers</interface> tab of the <interface>Status
- Notebook</interface>. Alternately, you can press
- <keycombo><keycap>Alt</keycap><keycap>F5</keycap></keycombo> to
- jump directly to the correct tab.
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/registers-view.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>The Register Editing Widget</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- This widget shows the current values of all of the CPU
- registers. You can edit the register values by clicking in the
- <interface>Value</interface> column and entering a new value.
- If the value for the register changed since the last time the
- debugger stopped, it will be highlighted in red.
- </para>
- </sect3>
- <sect3 id="nemiver-sect-memory">
- <title>Memory</title>
- <para>
- The memory widget allows you to view a section of memory
- directly. This enables you to get a lower-level view of what's
- happening while your program is running.
- </para>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/memory-view.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>The Memory Editing Widget</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- To display a segment of memory in the memory view widget, enter
- a memory address in the <interface>Address</interface> field.
- If the address is valid for the program being debugged, the
- memory view will display the memory values starting at the
- specified address. Memory values can be displayed in byte
- format, word format (2 bytes), or long word format (4 bytes) by
- choosing an option from the <interface>Group By</interface>
- drop-down menu. The memory values will automatically be updated
- as you step through the program.
- </para>
- <para>
- In addition to viewing the memory values, you can also use the
- memory widget to modify memory values. You can edit either the
- hex byte representation (the left-hand section of the memory
- widget), or the ASCII representation (the right-hand section of
- the memory widget). All changes will be applied immediately.
- </para>
- </sect3>
- </sect2>
- </sect1>
- <sect1 id="nemiver-sect-sessions">
- <title>Session Save and Restore</title>
- <para>
- &app; can save your debugging sessions for you so that you can resume
- them at a later time. This includes saving information such as which
- executable is being debugged, what environment variables are set, what
- command-line options are passed to the executable, which files are open,
- and which breakpoints are set so that you can get back to where you left
- off last time as quickly as possible.
- </para>
- <sect2 id="nemiver-sect-saving-sessions">
- <title>Saving Sessions</title>
- <para>
- &app; will save your session automatically on exit, so you don't even
- have to worry about it. However, if you want to explicitly save the
- session before closing &app;, you can do so by selecting
- <menuchoice><guimenu>File</guimenu><guimenuitem>Save Session To Disk</guimenuitem></menuchoice>.
- </para>
- </sect2>
- <sect2 id="nemiver-sect-resuming-sessions">
- <title>Resuming Saved Sessions</title>
- <sect3>
- <title>Using the Workbench</title>
- <para>
- Select
- <menuchoice><guimenu>File</guimenu><guimenuitem>Resume Saved Session...</guimenuitem></menuchoice>
- and select a session from the list.
- </para>
- <figure id="nemiver-sessions-dialog">
- <title>Session Dialog</title>
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="figures/sessions-dialog.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Shows dialog for resuming a saved session</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- </figure>
- </sect3>
- <sect3>
- <title>From the Command Line</title>
- <para>
- If you know the session ID of the session you want to run, you can
- start that debugging session from the command line. For example, if
- you want to run session number 3, you can do so with the following
- command:
- <command>&appcmd; --session 3</command>.
- </para>
- </sect3>
- </sect2>
- </sect1>
- <!-- This should be the last section in the manual -->
- <sect1 id="nemiver-sect-about">
- <title>About &app;</title>
- <para><application>&app;</application> was written by Dodji Seketeli and
- Jonathon Jongsma, with contributions from many others. To find more
- information about &app;, please visit the <ulink url="&website;" type="http">&app; project website</ulink>.
- </para>
- <para>
- To report a bug or make a suggestion regarding this application or this
- manual, see the Feedback section of the <ulink url="ghelp:user-guide?feedback-bugs" type="help">GNOME User
- Guide</ulink>.
- </para>
- <para>
- This program is distributed under the terms of the GNU General Public
- license as published by the Free Software Foundation; either version 2 of
- the License, or (at your option) any later version. A copy of this license
- can be found at this <ulink url="ghelp:gpl" type="help">link</ulink>, or
- in the file COPYING included with the source code of this program.
- </para>
- </sect1>
-</article>
-<!--
-vim: ts=2 sw=2 et
--->
diff --git a/help/Makefile.am b/help/Makefile.am
index 3ad4821..abee34f 100644
--- a/help/Makefile.am
+++ b/help/Makefile.am
@@ -1,9 +1,12 @@
-include $(top_srcdir)/gnome-doc-utils.make
-dist-hook: doc-dist-hook
-DOC_MODULE = nemiver
-DOC_ENTITIES =
-DOC_INCLUDES = legal.xml
-DOC_FIGURES = \
+@YELP_HELP_RULES@
+
+HELP_ID = nemiver
+
+HELP_FILES = \
+ index.docbook \
+ legal.xml
+
+HELP_MEDIA = \
figures/attach-dialog.png \
figures/execute-dialog.png \
figures/load-core-dialog.png \
@@ -18,4 +21,5 @@ DOC_FIGURES = \
figures/connect-remote-dialog.png \
figures/enabled-breakpoint.png \
figures/disabled-breakpoint.png
-DOC_LINGUAS = cs de el es fr gl oc sl sv zh_CN
+
+HELP_LINGUAS = cs de el es fr gl oc sl sv zh_CN
diff --git a/help/nemiver.omf.in b/help/nemiver.omf.in
deleted file mode 100644
index 1186d51..0000000
--- a/help/nemiver.omf.in
+++ /dev/null
@@ -1,10 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<omf>
- <resource>
- <subject category="GNOME|Applications|Programming"/>
- <type>User's Guide</type>
- <relation seriesid="1c69e3ee-ba1a-11db-88b7-b4e58dca62d0"/>
- <rights type="GNU FDL" license.version="1.1" holder="Jonathon Jongsma"/>
- </resource>
-</omf>
-
--
Dodji
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
