Skip to content

Commit d1e6718

Browse files
abijazabijaz
authored
Update DocBook entity and reference naming to camelCase. (#55)
Convert all DocBook entity declarations and xref linkend references to camelCase convention across documentation files. Signed-off-by: Abdul Basit Ijaz <abdul.b.ijaz@intel.com>
1 parent 0303d26 commit d1e6718

19 files changed

+155
-155
lines changed

‎doc/src/INSTALL.sgml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2-
<!ENTITY stat_installation SYSTEM "stat_installation.sgml">
3-
<!ENTITY stat_dependencies SYSTEM "stat_dependencies.sgml">
2+
<!ENTITY statInstallation SYSTEM "stat_installation.sgml">
3+
<!ENTITY statDependencies SYSTEM "stat_dependencies.sgml">
44
]>
55
<book><title>Installing STAT</title>
6-
<chapter><title>Dependent Packages</title>&stat_dependencies</chapter>
7-
<chapter><title>Installation</title>&stat_installation</chapter>
6+
<chapter><title>Dependent Packages</title>&statDependencies</chapter>
7+
<chapter><title>Installation</title>&statInstallation</chapter>
88
</book>

‎doc/src/LICENSE.sgml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2-
<!ENTITY stat_license SYSTEM "stat_license.sgml">
2+
<!ENTITY statLicense SYSTEM "stat_license.sgml">
33
]>
44
<book><title>License</title>
5-
<chapter><title>License</title>&stat_license</chapter>
5+
<chapter><title>License</title>&statLicense</chapter>
66
</book>
77

‎doc/src/stat_man.sgml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
<!ENTITY % manpage "INCLUDE">
33
<!ENTITY % userguide "IGNORE">
44
<!ENTITY % llnluserguide "IGNORE">
5-
<!ENTITY stat_options SYSTEM "stat_options.sgml">
6-
<!ENTITY stat_example SYSTEM "stat_example.sgml">
7-
<!ENTITY stat_copyright SYSTEM "stat_copyright.sgml">
8-
<!ENTITY stat_description SYSTEM "stat_description.sgml">
5+
<!ENTITY statOptions SYSTEM "stat_options.sgml">
6+
<!ENTITY statExample SYSTEM "stat_example.sgml">
7+
<!ENTITY statCopyright SYSTEM "stat_copyright.sgml">
8+
<!ENTITY statDescription SYSTEM "stat_description.sgml">
99
]>
1010
<refentry>
1111
<refentryinfo>
@@ -44,15 +44,15 @@
4444
</refsynopsisdiv>
4545
<refsect1>
4646
<title>DESCRIPTION</title>
47-
&stat_description
47+
&statDescription
4848
</refsect1>
4949
<refsect1>
5050
<title>OPTIONS</title>
51-
&stat_options
51+
&statOptions
5252
</refsect1>
5353
<refsect1>
5454
<title>EXAMPLE</title>
55-
&stat_example
55+
&statExample
5656
</refsect1>
5757
<refsect1>
5858
<title>AUTHOR</title>
@@ -68,7 +68,7 @@
6868
</refsect1>
6969
<refsect1>
7070
<title>COPYRIGHT</title>
71-
&stat_copyright
71+
&statCopyright
7272
</refsect1>
7373
<refsect1>
7474
<title>SEE ALSO</title>

‎doc/src/stat_overview.sgml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
<para>
2-
STAT, the Stack Trace Analysis Tool, helps isolate bugs by gathering stack traces from each individual process of a parallel application and merging them into a global, yet compact representation. Each stack trace, as depicted in <xref linkend="merged_traces">, captures the function calling sequence of an individual process. The nodes are labeled with the function names and the directed edges show the function calling sequence from caller to callee. STAT's stack trace merging process forms a call graph prefix tree, which can be seen in <xref linkend="merged_traces">. The prefix tree groups together traces from different processes that have the same calling sequence and labels the edges with the count and set of tasks that exhibited that calling sequence. Nodes in the prefix tree that are visited by the same set of tasks are given the same color, providing the user with a quick means of identifying the various process equivalence classes.
2+
STAT, the Stack Trace Analysis Tool, helps isolate bugs by gathering stack traces from each individual process of a parallel application and merging them into a global, yet compact representation. Each stack trace, as depicted in <xref linkend="mergedTraces">, captures the function calling sequence of an individual process. The nodes are labeled with the function names and the directed edges show the function calling sequence from caller to callee. STAT's stack trace merging process forms a call graph prefix tree, which can be seen in <xref linkend="mergedTraces">. The prefix tree groups together traces from different processes that have the same calling sequence and labels the edges with the count and set of tasks that exhibited that calling sequence. Nodes in the prefix tree that are visited by the same set of tasks are given the same color, providing the user with a quick means of identifying the various process equivalence classes.
33
</para>
4-
<figure id="merged_traces">
4+
<figure id="mergedTraces">
55
<title>A single stack trace (left) and a STAT merged call prefix tree (right)</title>
66
<mediaobject><imageobject>
77
<imagedata fileref="figs/trace_and_merge.png">
88
</imageobject></mediaobject>
99
</figure>
1010
<para>
11-
STAT merges stack traces into 2D spatial and 3D spatial-temporal call prefix trees. The 2D spatial call prefix tree (<xref linkend="prefix_tree_2d">) represents a single snapshot of the entire application. The 3D spatial-temporal call prefix tree (<xref linkend="prefix_tree_3d">) takes a series of snapshots from the application over time and is useful for analyzing time-varying behavior.
11+
STAT merges stack traces into 2D spatial and 3D spatial-temporal call prefix trees. The 2D spatial call prefix tree (<xref linkend="prefixTree2d">) represents a single snapshot of the entire application. The 3D spatial-temporal call prefix tree (<xref linkend="prefixTree3d">) takes a series of snapshots from the application over time and is useful for analyzing time-varying behavior.
1212
</para>
13-
<figure id="prefix_tree_2d">
13+
<figure id="prefixTree2d">
1414
<title>A 2D spatial call prefix tree</title>
1515
<mediaobject><imageobject>
1616
<imagedata scale="50" fileref="figs/bgl4k_2d.png">
1717
</imageobject></mediaobject>
1818
</figure>
19-
<figure id="prefix_tree_3d">
19+
<figure id="prefixTree3d">
2020
<title>A 3D spatial call prefix tree</title>
2121
<mediaobject><imageobject>
2222
<imagedata scale="50" fileref="figs/bgl4k_3d.png">
@@ -26,9 +26,9 @@ STAT merges stack traces into 2D spatial and 3D spatial-temporal call prefix tre
2626
Stack traces based on function names only provide a high-level overview of the application's execution. However, for certain bugs this view may be too coarse-grained so STAT is also capable of gathering stack traces with more fine-grained information. In particular, STAT can also record the program counter of each frame or with the appropriate debug information compiled into the application (i.e., with the "-g" compiler flag), STAT can gather the source file and line number of each stack frame. Both of these refinements can further delineate processes and refine the process equivalence classes.
2727
</para>
2828
<para>
29-
In addition, line number information can be fed into a static code analysis engine to derive the logical temporal order of the MPI tasks <xref linkend="to_example">. This analysis traverses from the root of the tree towards the leaves, at each step analyzing the control flow of the source code and sorting sibling nodes by the amount of execution progress made through the code. For straight-line code, this simply means that one task has made more progress if it has executed past the point of another task, i.e., if it has a greater line number. This ordering is partial since two tasks in different branches of an if-else are incomparable. In cases where the program points being compared are within a loop, STAT can extract the loop ordering variable from the application processes and further delineate tasks by execution progress. This analysis is useful for identifying the culprit in a deadlocked or livelocked application, where the problematic task has often either made the least or most progress through the code, leaving the remaining tasks stuck in a barrier or blocked pending a message. Note, this feature is still a prototype.
29+
In addition, line number information can be fed into a static code analysis engine to derive the logical temporal order of the MPI tasks <xref linkend="toExample">. This analysis traverses from the root of the tree towards the leaves, at each step analyzing the control flow of the source code and sorting sibling nodes by the amount of execution progress made through the code. For straight-line code, this simply means that one task has made more progress if it has executed past the point of another task, i.e., if it has a greater line number. This ordering is partial since two tasks in different branches of an if-else are incomparable. In cases where the program points being compared are within a loop, STAT can extract the loop ordering variable from the application processes and further delineate tasks by execution progress. This analysis is useful for identifying the culprit in a deadlocked or livelocked application, where the problematic task has often either made the least or most progress through the code, leaving the remaining tasks stuck in a barrier or blocked pending a message. Note, this feature is still a prototype.
3030
</para>
31-
<figure id="to_example">
31+
<figure id="toExample">
3232
<title>STAT's temporal ordering analysis engine indicates that task 1 has made the least progress. In this example, task 1 is stuck in a compute cycle, while the other tasks are blocked in MPI communication, waiting for task 1.</title>
3333
<mediaobject><imageobject>
3434
<imagedata scale="50" fileref="figs/stat_to_example.png">

‎doc/src/stat_quickstart.sgml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
2-
<!ENTITY stat_auspice SYSTEM "stat_auspice.sgml">
3-
<!ENTITY stat_license SYSTEM "stat_license.sgml">
4-
<!ENTITY stat_copyright SYSTEM "stat_copyright.sgml">
5-
<!ENTITY stat_whentouse SYSTEM "stat_whentouse.sgml">
6-
<!ENTITY statgui_tutorial SYSTEM "statgui_tutorial.sgml">
2+
<!ENTITY statAuspice SYSTEM "stat_auspice.sgml">
3+
<!ENTITY statLicense SYSTEM "stat_license.sgml">
4+
<!ENTITY statCopyright SYSTEM "stat_copyright.sgml">
5+
<!ENTITY statWhentouse SYSTEM "stat_whentouse.sgml">
6+
<!ENTITY statguiTutorial SYSTEM "statgui_tutorial.sgml">
77
]>
88

99
<book>
@@ -30,15 +30,15 @@
3030
</bookinfo>
3131
<preface>
3232
<title>Disclaimer</title>
33-
<section><title>Auspice</title>&stat_auspice</section>
34-
<section><title>License</title>&stat_license</section>
33+
<section><title>Auspice</title>&statAuspice</section>
34+
<section><title>License</title>&statLicense</section>
3535
</preface>
3636
<chapter>
3737
<title>When To Use</title>
38-
&stat_whentouse
38+
&statWhentouse
3939
</chapter>
4040
<chapter>
4141
<title>Using the STAT GUI</title>
42-
&statgui_tutorial
42+
&statguiTutorial
4343
</chapter>
4444
</book>

0 commit comments

Comments
 (0)