docs: fix halshow page didn't appear in PDF docs

This moves the halshow docs page to the hal-tutorial to be included in the PDF documentation. It was only accessible as HTML via a link from HAL Tools page before.

Author: hansu

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/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.

docs/src/hal/tutorial.adoc

@@ -836,6 +836,7 @@ time, you can just start more halmeters. The halmeter window was
 intentionally made very small so you could have a lot of them on the
 screen at once.
 
+include::halshow.adoc[]
 include::halscope.adoc[]
 // vim: set syntax=asciidoc:
 

docs/src/plasma/qtplasmac.adoc

@@ -1217,7 +1217,7 @@ To return the *EXIT WARNING MESSAGE* text to the last saved value press the *REL
 
 Some standard LinuxCNC utilities are provided as an aid in the diagnosis of issues that may arise:
 
-- link:../hal/halshow.html#cha:halshow[Halshow]
+- link:../hal/tutorial.html#sec:halshow[Halshow]
 - link:../hal/tutorial.html#sec:tutorial-halscope[Halscope]
 - link:../hal/tutorial.html#sec:tutorial-halmeter[Halmeter]
 - link:../man/man1/emccalib.1.html[Calibration]