.title = Help for Heapy Profile Browser
.h2: Menus
.p
Click on the dotted line at the top of a menu to "tear it off":
a separate window containing the menu is created.

.dl
..dt
...h3: File Menu
..dd
...table
....tr
.....valign=top
.....th: New Profile Browser
.....td: Create a new browser window with the same file as the one
opened in the current window.
....tr
.....valign=top
.....th: Open Profile
.....td: Open a profile data file in the current window.
....tr
.....valign=top
.....th: Close Window
.....td: Close the current window (exits from Tk if it was the last browser window).
....tr
.....valign=top
.....th: Clear Cache
.....td: Clear the sample cache, releasing its memory. The cache will
be automatically filled again when needed.
......div: This command is a kind of temporary / experimental feature. I think
the cache handling should be made automatic and less memory consuming.

..dt
...h3: Pane Menu
..dd
...table
....tr
.....th: Show Control Panel
.....td: Show the control panel pane.
....tr
.....th: Show Graph
.....td: Show the graph pane.
....tr
.....th: Show Table
.....td: Show the table pane.

..dt
...h3: Graph Menu
..dd
...table
....tr
.....valign=top
.....th: Bars / Lines
.....td: Choose whether the graph should be displayed using bars or lines.
......div
When using bars, the sample value (size or count) for different kinds of
objects will be stacked on top of each other so the total
height represents the total value of a sample. When using
lines, each line represents the value for a single kind of object.
The 10 largest values are shown in each sample point. Each kind
has a particular color, choosen arbitrary but it is always the same
color for the same kind.
The remaing kinds, if any, are shown in black.
....tr
.....valign=top
.....th: Size / Count
.....td: Choose whether the graph should display the size of objects
of a particular kind or the number of objects of that kind.
......div
.......small
(Note that this affects only the graph, the table will still choose size or
kind as it were choosen in the table menu.)

..dt
...h3: Table Menu
..dd
...dt
....h4: Header submenu
...dd

This menu has a choice of header for each column of the table.  The
data of each column is determined by the header of that column, as
well as the headers of previous columns. So if you change the first
column header (A/B), the data in that column will change as well as
the data under the next header (Size/Count) and the ones that follow.

....table
.....tr
......valign=top
......th: A / B
......td: Use the sample at the A or B marker in the graph.
.......div

The kinds of objects shown in the table under this column
are taken from the 10 largest sample values at that point, in the same
order as they are shown in the graph. The ordering in the graph
depends on the choice of count or size in the graph menu.  However,
the table may show count or size independent from the choice in the
graph.

.....tr
......valign=top
......th: Size / Count
......td: Show the size or count of the kinds of objects in each row,
taken from those choosen in the A / B column.
.....tr
......valign=top
......th: %A:Tot / %B:Tot
......td: Show percentage of the Size / Count column, relative to the total
(size or count) at either the A or B sample point.

.....tr
......valign=top
......th
.......div: Cumul /
.......div: A-B / B-A
......td: Show either a cumulative sum of the Size / Count
column, or the difference A-B or B-A.
.......div: The cumulative sum is taken by summing from the first table
row down to the last row. 
.....tr
......valign=top
......th: %A:Tot / %B:Tot
......td: Show percentage of the previous field,
relative to either the A or B total.
.....tr
......valign=top
......th: Kind
......td: Shows the kind of objects. This is currently the only
alternative for this column. The kind shown corresponds to
the color shown in the A / B column. A special kind is
<Other> which summarizes the remaining data if there were
more than 10 different kinds in the sample.

...dt
....h4: Scrollbar submenu
...dd
....table
.....tr
......valign=top
......th: Auto / On / Off
......td: Choose a scrollbar mode. The usual setting is Auto
which shows the scrollbar only when needed.

..dt
...h3: Window Menu
..dd
This menu lists the names of all open windows.
Selecting one brings it to the top, deiconifying it if necessary.

..dt
...h3: Help Menu
..dd
...table
....tr
.....valign=top
.....th: About
.....td: Version, author, email, copyright.
....tr
.....valign=top
.....th: Help
.....td: Open this help window.

.h2: Panes
.p
There are 3 panes in the main window shown by default.
At the top is the Control Panel, at the
bottom left the Graph and at the bottom right the Table.

.dl
..dt
...h3: Control Panel Pane
...p
This contains controls for the graph and the markers.
It also has a quick-exit button and a collect button.
..dd
...dl
....dt
.....h4: X / Y axis control
....dd

The two frames in the Control Panel having an X or Y button in the
top left corner control each axis of the graph. The X, horizontal, axis
shows the sample point. The Y axis shows either the size or count, as
choosen in the Graph menu.

.....table
......tr
.......valign=top
.......th: X / Y Button
.......td: Brings up a menu, currently containing
some buttons that can also be accessed directly in the panel.
......tr
.......valign=top
.......th: Grid button
.......td: Select if the graph should show grid lines.
......tr
.......valign=top
.......th: Range buttons
........div: - / +
.......td: Change the range that is shown in the displayed portion
of the graph. For each time + or - is pressed the range will be
stepped up or down in the sequence (1, 2, 5) and multiples thereoff.
......tr
.......valign=top
.......th: Range field
.......td: The current range is shown here, and a new range can be entered
by writing to this field and pressing Enter. The format is an integer
that may be followed by a multiplier, K, M, G, or T, meaning that the value
is multipled by 1000, 1E6, 1E9, or 1E12 respectively. The maximum range is 1T.

....dt
.....h4: A / B sample control
....dd
Each of the frames showing A or B in the top left corner
controls one of the sample markers. The current position is
shown in the bottom left corner.
.....small
(This is currently not an entry field - TODO - but the
marker may be moved long distances by directly dragging
it in the Graph frame.)

.....table
......tr
.......valign=top
.......th: - / + 
.......td: Step the marker one step to the left (-) or to the right (+).
........div
The table will be updated to show new data if it was set to show
such data that were dependent on the marker moved.
........div
The graph will show the new marker position. If the marker was outside
of the displayed portion of the graph, the graph will scroll so the
marker becomes visible.
......tr
.......valign=top
.......th: Track button
.......td:

Press to set the marker to the last sample in the file and stay at the
end as new samples are added. (New samples are periodically read from
the end of the file when auto-collect is selected via the Collect
button.)

........div: Tracking is turned off when the marker is manually moved.

....dt
.....h4: Exit button
....dd: Exits the program, a shortcut for the Exit command in the File menu.
....dt
.....h4: Collect button
....dd: When selected, the browser will collect new samples
from the current file, and will continue to do this periodically.
.....div
......small: Currently it will check the file for new data once a second.

..dt
...h3: Graph Pane
..dd

This pane shows the currently visible portion of the sample file.  It
can be scrolled via an horizontal scrollbar.  The two markers are
shown as buttons labeled A and B above the graph and with lines
extending down in the graph. Markers can be moved by the mouse.

...p
How to move the markers is hopefully quite self evident when tried
out but I wrote up some details about it anyway.
...h4: Marker movement details
...p
Holding down the mouse button and moving the mouse moves the
underlying marker. Klicking the mouse button over a marker without
moving the mouse, selects the marker. While it is selected any
movement of the mouse within the graph will move the marker with it.
Klicking again anywhere in the graph will deselect the marker.  If the
marker can be moved, the cursor will be an arrow indicating the
direction it can be moved, left or right or both.  If the marker can
not be moved in any direction, the cursor will show a circle or disc.
The marker can not move outside the available samples. Moving the
mouse outside of the graph also restricts the movement of the mouse,
even if the mouse button is pressed. This is intentional so that the
marker can be moved longer distances than the mouse can move. Moving
the mouse to the right of the graph, the marker can only be moved to
the right - moving back the mouse will not move the marker back until
the mouse enters the graph area again.  Similarly for the left
side. Above or below the graph, the mouse will not move the marker at
all but will show a circle to indicate that the mouse may be
'recirculated' to move back into the graph.

..dt
...h3: Table Pane
..dd

This pane shows a table based on the configuration set
in the Table menu. The sample number and time stamp
show in the header.
