Docs: halshow docs doesn't appear in PDF documentation

docs/src/Master_Documentation.adoc

@@ -88,6 +88,8 @@ include::hal/basic-hal.adoc[]
 
 include::hal/twopass.adoc[]
 
+include::hal/tools.adoc[]
+
 include::hal/tutorial.adoc[]
 
 include::hal/hal-examples.adoc[]
@@ -110,8 +112,6 @@ include::hal/halmodule.adoc[]
 
 include::hal/canonical-devices.adoc[]
 
-include::hal/tools.adoc[]
-
 
 :leveloffset: 1
 = Hardware Drivers

docs/src/Submakefile

@@ -158,7 +158,6 @@ DOC_SRCS_EN := \
 	hal/general-ref.adoc \
 	hal/hal-examples.adoc \
 	hal/halmodule.adoc \
-	hal/halshow.adoc \
 	hal/haltcl.adoc \
 	hal/halui-examples.adoc \
 	hal/intro.adoc \

docs/src/gui/qtvcp-widgets.adoc

@@ -1527,7 +1527,7 @@ Enter any of these _case sensitive_ commands to load the respective program or a
   link:../hal/tools.html#sec:halmeter[`halmeter`] utility.
 *`HALSHOW`*::
   Starts LinuxCNC
-  link:../hal/halshow.html#cha:halshow[`halshow`] utility.
+  link:../hal/tutorial.html#sec:halshow[`halshow`] utility.
 *`HALSCOPE`*::
   Starts LinuxCNC
   link:../hal/tutorial.html#sec:tutorial-halscope[`halscope`] utility.

docs/src/hal/halscope.adoc

@@ -0,0 +1,220 @@
+[[sec:tutorial-halscope]]
+== Halscope
+
+(((Tutorial Halscope)))
+The previous example generates some very interesting signals. But much
+of what happens is far too fast to see with halmeter. To take a closer
+look at what is going on inside the HAL, we want an oscilloscope.
+Fortunately HAL has one, called halscope.
+
+Halscope has two parts - a realtime part that reads the HAL signals, and a non-realtime part that provides the GUI and display. However, you don't need to worry about this because the non-realtime part will automatically load the realtime part when needed.
+
+With LinuxCNC running in a terminal you can start halscope with the following command.
+
+.Starting Halscope
+----
+halcmd loadusr halscope
+----
+
+If LinuxCNC is not running or the autosave.halscope file does not match
+the pins available in the current running LinuxCNC the scope GUI window
+will open, immediately followed by a 'Realtime function not linked'
+dialog that looks like the following figure. To change the sample rate
+left click on the samples box.
+
+[[fig:halscope-rt-function-not-linked]]
+.Realtime function not linked dialog
+image::images/halscope-01.png["Realtime function not linked dialog",align="center"]
+
+This dialog is where you set the sampling rate for the oscilloscope.
+For now we want to sample once per millisecond, so click on the 1.00 ms
+thread 'slow' and leave the multiplier at 1. We will also leave the
+record length at 4000 samples, so that we can use up to four channels
+at one time. When you select a thread and then click 'OK', the dialog
+disappears, and the scope window looks something like the following
+figure.
+
+[[fig:halscope-init-window]]
+.Initial scope window
+image::images/halscope-02.png["Initial scope window",align="center"]
+
+=== Hooking up the scope probes
+
+At this point, Halscope is ready to use. We have already selected a
+sample rate and record length, so the next step is to decide what to
+look at. This is equivalent to hooking 'virtual scope probes' to the
+HAL. Halscope has 16 channels, but the number you can use at any one
+time depends on the record length - more channels means shorter
+records, since the memory available for the record is fixed at
+approximately 16,000 samples.
+
+The channel buttons run across the bottom of the halscope screen.
+Click button '1', and you will see the 'Select Channel Source' dialog
+as shown in the following figure. This dialog is very similar to the
+one used by Halmeter. We would like to look at the signals we defined
+earlier, so we click on the 'Signals' tab, and the dialog displays all
+of the signals in the HAL (only two for this example).
+
+[[fig:halscope-channel-source-selection]]
+.Select Channel Source
+image::images/halscope-03.png["Select Channel Source",align="center"]
+
+To choose a signal, just click on it. In this case, we want channel 1
+to display the signal 'X-vel'. Click on the Signals tab then click on
+'X-vel' and the dialog closes and the channel is now selected.
+
+[[fig:halscope-source-signal-selection]]
+.Select Signal
+image::images/halscope-04.png["Select Signal",align="center"]
+
+The channel 1 button is pressed in, and channel number 1 and the name
+'X-vel' appear below the row of buttons. That display always indicates
+the selected channel - you can have many channels on the screen, but
+the selected one is highlighted, and the various controls like vertical
+position and scale always work on the selected one.
+
+[[fig:halscope]]
+.Halscope
+image::images/halscope-05.png["Halscope",align="center"]
+
+To add a signal to channel 2, click the '2' button. When the dialog
+pops up, click the 'Signals' tab, then click on 'Y-vel'. We also want
+to look at the square and triangle wave outputs. There are no signals
+connected to those pins, so we use the 'Pins' tab instead. For channel
+3, select `siggen.0.triangle` and for channel 4, select
+`siggen.0.square`.
+
+=== Capturing our first waveforms
+
+Now that we have several probes hooked to the HAL, it's time to
+capture some waveforms. To start the scope, click the 'Normal' button
+in the 'Run Mode' section of the screen (upper right). Since we have a
+4000 sample record length, and are acquiring 1000 samples per second,
+it will take halscope about 2 seconds to fill half of its buffer.
+During that time a progress bar just above the main screen will show
+the buffer filling. Once the buffer is half full, the scope waits for a
+trigger. Since we haven't configured one yet, it will wait forever. To
+manually trigger it, click the 'Force' button in the 'Trigger' section
+at the top right. You should see the remainder of the buffer fill, then
+the screen will display the captured waveforms. The result will look
+something like the following figure.
+
+[[fig:halscope-captured-owaveform]]
+.Captured Waveforms
+image::images/halscope-06.png["Captured Waveforms",align="center"]
+
+The 'Selected Channel' box at the bottom tells you that the purple
+trace is the currently selected one, channel 4, which is displaying the
+value of the pin `siggen.0.square`. Try clicking channel buttons 1
+through 3 to highlight the other three traces.
+
+=== Vertical Adjustments
+
+The traces are rather hard to distinguish since all four are on top of
+each other. To fix this, we use the 'Vertical' controls in the box to
+the right of the screen. These controls act on the currently selected
+channel. When adjusting the gain, notice that it covers a huge range -
+unlike a real scope, this one can display signals ranging from very
+tiny (pico-units) to very large (Tera-units). The position control
+moves the displayed trace up and down over the height of the screen
+only. For larger adjustments the offset button should be used.
+
+[[fig:halscope-vertical-adjustment]]
+.Vertical Adjustment
+image::images/halscope-07.png["Vertical Adjustment",align="center"]
+
+The large _Selected Channel_ button at the bottom indicates that channel 1 is
+currently selected channel and that it matches the _X-vel_ signal.
+Try clicking on the other channels to put their traces in evidence and
+to be able to move them with the _Pos_ cursor.
+
+=== Triggering
+
+Using the 'Force' button is a rather unsatisfying way to trigger the
+scope. To set up real triggering, click on the 'Source' button at the
+bottom right. It will pop up the 'Trigger Source' dialog, which is
+simply a list of all the probes that are currently connected. Select a
+probe to use for triggering by clicking on it. For this example we will
+use channel 3, the triangle wave as shown in the following figure.
+
+[[fig:halscope-trigger-source]]
+.Trigger Source Dialog
+image::images/halscope-08.png["Trigger Source Dialog",align="center"]
+
+After setting the trigger source, you can adjust the trigger level and
+trigger position using the sliders in the 'Trigger' box along the right
+edge. The level can be adjusted from the top to the bottom of the
+screen, and is displayed below the sliders. The position is the
+location of the trigger point within the overall record. With the
+slider all the way down, the trigger point is at the end of the record,
+and halscope displays what happened before the trigger point. When the
+slider is all the way up, the trigger point is at the beginning of the
+record, displaying what happened after it was triggered. The trigger
+point is visible as a vertical line in the progress box above the
+screen. The trigger polarity can be changed by clicking the button just
+below the trigger level display. It will then become _descendant_.
+Note that changing the trigger position stops the scope once the position
+has been adjusted, you relaunch the scope by clicking on the _Normal_
+button of _Run mode_ the group.
+
+Now that we have adjusted the vertical controls and triggering, the
+scope display looks something like the following figure.
+
+[[fig:halscope-waveforms-with-triggering]]
+.Waveforms with Triggering
+image::images/halscope-09.png["Waveforms with Triggering",align="center"]
+
+=== Horizontal Adjustments
+
+To look closely at part of a waveform, you can use the zoom slider at
+the top of the screen to expand the waveforms horizontally, and the
+position slider to determine which part of the zoomed waveform is visible.
+However, sometimes simply expanding the waveforms isn't enough and you need to increase the sampling rate.
+For example, we would like to look at the actual step pulses that are being generated in our example.
+Since the step pulses may be only 50 µs long, sampling at 1 kHz isn't fast enough.
+To change the sample rate, click on the button that displays the number
+of samples and sample rate to bring up the 'Select Sample Rate' dialog figure.
+For this example, we will click on the 50 µs thread, 'fast', which gives us a sample rate of about 20 kHz.
+Now instead of displaying about 4 seconds worth of data, one record is 4000 samples at 20 kHz, or about 0.20 seconds.
+
+[[fig:halscope-sample-rate-choice]]
+.Sample Rate Dialog
+image::images/halscope-10.png["Sample Rate Dialog",align="center"]
+
+=== More Channels
+
+Now let's look at the step pulses.
+Halscope has 16 channels, but for this example we are using only 4 at a time.
+Before we select any more channels, we need to turn off a couple.
+Clicking on a selected channel button (black border) will turn the channel off.
+So click on the channel 2 button, then click again on this button and the channel will turn off.
+Then click twice on channel 3 and do the same for channel 4.
+Even though the channels are turned off, they still remember what they
+are connected to, and in fact we will continue to use channel 3 as the trigger source.
+To add new channels, select channel 5, and choose pin `stepgen.0.dir`, then channel 6, and select `stepgen.0.step`.
+Then click run mode 'Normal' to start the scope, and adjust the horizontal zoom to 5 ms per division.
+You should see the step pulses slow down as the velocity command (channel 1) approaches zero,
+then the direction pin changes state and the step pulses speed up again.
+You might want toincrease the gain on channel 1 to about 20 milli per division to better see
+the change in the velocity command.
+The result should look like the following figure.
+
+[[fig:halscope-step-pulses]]
+.Step Pulses
+image::images/halscope-11.png["Step Pulses",align="center"]
+
+=== More samples
+
+If you want to record more samples at once, restart realtime and load
+halscope with a numeric argument which indicates the number of samples
+you want to capture.
+
+----
+halcmd loadusr halscope 80000
+----
+
+If the 'scope_rt' component was not already loaded, halscope will
+load it and request 80000 total samples, so that when sampling
+4 channels at a time there will be 20000 samples per channel.
+(If 'scope_rt' was already loaded, the numeric argument to
+halscope will have no effect).

docs/src/hal/halshow.adoc

@@ -1,8 +1,8 @@
 :lang: en
 :toc:
 
-[[cha:halshow]]
-= Halshow
+[[sec:halshow]]
+== Halshow
 
 // Custom lang highlight
 // must come after the doc title, to work around a bug in asciidoc 8.6.6
@@ -20,7 +20,7 @@ When the configuration of LinuxCNC changes, so will the output of halshow be dif
 
 As we will soon see, this ability of HAL to document itself is one key to establish an effective CNC system.
 
-== Starting Halshow
+=== Starting Halshow
 
 Halshow is available
 
@@ -61,9 +61,9 @@ image::images/halshow-layout.png["Halshow Layout",align="center"]
 At the left of its display as shown in above figure is a tree view, resembling what you may have seen as file browsers.
 At the right is a tabbed notebook with tabs for show, watch and settings.
 
-== HAL Tree Area
+=== HAL Tree Area
 
-=== Filter Tree
+.Filter Tree
 
 Per default this entry filters the tree by pin names or tree-nodes by a regular expression.
 For example, entering "lim-sw" would filter the tree to the following:
@@ -81,7 +81,7 @@ joint.3.pos-lim-sw-in
 If you would like to display all `joint.0`-related, you have to click the settings icon and select "Full path".
 Pay attention to escape the regex special characters, so you have to enter "joint\.1\." to explicitly request the dot and not also find joint 10.
 
-=== Tree
+.Tree
 
 The tree shows all of the major parts of a HAL.
 In front of each is a small plus (+) or minus (-) sign in a box to expand or collapse the corresponding section of the tree.
@@ -93,7 +93,7 @@ _Expand All_, _Collapse All_; _Expand Pins_, _Expand Parameters_, _Expand Signal
 _Reload tree view_ is useful when new components are loaded during runtime and should be displayed.
 
 
-== HAL Show Area
+=== HAL Show Area
 
 [[fig:halshow-show-tab]]
 .Halshow: Show Tab
@@ -126,7 +126,7 @@ The Show area allows to add pins from selected text by using the right-click men
 All valid pins that are enclosed in the selection are added to the Watch tab.
 ****
 
-== Watch Tab Area
+=== Watch Tab Area
 
 Clicking the watch tab produces a blank canvas.
 You can add signals and pins to this canvas and watch their values.
@@ -182,7 +182,7 @@ The context menu allows further:
 image::images/halshow-5.png["Halshow: Watch Tab Context Menu",align="center"]
 
 
-== Command Entry
+=== Command Entry
 
 In the lower part is an entry box to test HAL commands.
 The commands you enter here and the effect that they have on the running HAL are not saved.
@@ -206,7 +206,7 @@ An error message from halcmd will be shown when these commands are not properly
 If you are not certain how to set up a proper command, you'll need to read again the documentation on halcmd and the specific modules that you are working with.
 
 [[sec:halshow-settings]]
-== Settings
+=== Settings
 
 .New in 2.9
 ****
@@ -222,7 +222,7 @@ The further settings should be self-explaining.
 image::images/halshow-settings.png["Halshow Settings",align="center"]
 
 
-== Example/Tutorial
+=== Example/Tutorial
 
 Let's use this editor to add a differential module to a HAL and connect it to axis position so that we could see the rate of change in position, i.e., acceleration.
 We first need to load a HAL component named ddt, add it to the servo thread, then connect it to the position pin of a joint.

docs/src/hal/tools.adoc

@@ -12,6 +12,8 @@
 
 (((HAL Tools)))
 
+For most of the tools, a more detailed description can be found in the chapter <<cha:hal-tutorial,HAL Tutorial>>
+
 [[sec:halcmd]]
 == Halcmd
 
@@ -40,7 +42,7 @@ usage, and is a good tutorial for `halcmd`.
 == Halmeter
 
 (((Halmeter)))
-Halmeter is a 'voltmeter' for the HAL.
+`halmeter` is like a voltmeter for the HAL.
 It lets you look at a pin, signal, or parameter, and displays the current value of that item.
 It is pretty simple to use.
 Start it by typing `halmeter` in an X windows shell.
@@ -66,7 +68,7 @@ And finally, if you specify an item to display, you can add `-s` before the `pin
 The item name will be displayed in the title bar instead of under the value, and there will be no buttons.
 Useful when you want a lot of meters in a small amount of screen space.
 
-Refer to <<sec:tutorial-halmeter,Halmeter Tutorial>> section for more information.
+In the <<sec:tutorial-halmeter,Halmeter Tutorial>> you will find for more information.
 
 `halmeter` can be loaded from a terminal or from AXIS. `halmeter` is faster than `halshow` at displaying values.
 `halmeter` has two windows, one to pick the pin, signal, or parameter to monitor and one that displays the value.
@@ -89,12 +91,14 @@ image::images/hal-meter02.png["Halmeter watch window"]
 
 == Halshow
 
-`halshow` (<<cha:halshow,complete usage description>>) can be started from the command line
-to show details for selected components, pins, parameters, signals, functions, and threads of a running HAL.
+`halshow` shows the values of chosen pins, parameters or signals of a running HAL. It further provides buttons to also modify those items.
 The WATCH tab provides a continuous display of selected pin, parameters, and signal items.
 The File menu provides buttons to save the watch items to a watch list and to load an existing watch list.
 The watch list items can also be loaded automatically on startup.
-For command line usage:
+
+More detailed information can be found in the section <<sec:halshow,Halshow>> in the tutorial chapter.
+
+It can be started from the command line:
 
 ----
 halshow --help
@@ -111,7 +115,7 @@ Notes:
 ----
 
 .Halshow Watch Tab
-image::images/halshow-4.png["Halshow Watch Tab",align="center"]
+image::images/halshow-4.png["Halshow Watch Tab"]
 
 A watchfile created using the 'File/Save Watch List' menu item is formatted as a single line with tokens "pin+", "param+", "sig=+",
 followed by the appropriate pin, param, or signal name.