Merge pull request #3060 from smoe/docs_wording_20240807

docs: man/man1/*.adoc - review asciidoc formatting (smoe:docs_wording_20240807)

Author: petterreinholdtsen

docs/src/gcode/overview.adoc

@@ -175,16 +175,13 @@ digit is a single character between 0 and 9.
 ** an optional plus or minus sign, followed by
 ** zero to many digits, followed, possibly, by
 ** one decimal point, followed by
-** zero to many digits - provided that there is at least
-   one digit somewhere in the number.
+** zero to many digits - provided that there is at least one digit somewhere in the number.
 * There are two kinds of numbers:
 ** Integers, that does not have a decimal point,
 ** Decimals, that do have a decimal point.
-* Numbers may have any number of digits, subject to the limitation on
-  line length. Only about seventeen significant figures will be retained,
-  however (enough for all known applications).
-* A non-zero number with no sign but the first character is assumed to be
-  positive.
+* Numbers may have any number of digits, subject to the limitation on line length.
+  Only about seventeen significant figures will be retained, however (enough for all known applications).
+* A non-zero number with no sign but the first character is assumed to be positive.
 
 Notice that initial (before the decimal point and the first non-zero
 digit) and trailing (after the decimal point and the last non-zero
@@ -222,9 +219,9 @@ Syntax:: There are three kinds of syntactic appearance:
 * 'named local' - #<localvalue>
 * 'named global' - #<_globalvalue>
 
-Scope:: The scope of a parameter is either global, or local within a
-subroutine. Subroutine parameters and local named variables have local
-scope. Global named parameters and numbered parameters starting from
+Scope:: The scope of a parameter is either global, or local within a subroutine.
+Subroutine parameters and local named variables have local scope.
+Global named parameters and numbered parameters starting from
 number 31 are global in scope. RS274/NGC uses 'lexical scoping' -
 in a subroutine only the local variables defined therein, and any
 global variables are visible. The local variables of a
@@ -257,12 +254,9 @@ Intended Use::
   available for general-purpose storage of floating-point values, like
   intermediate results, flags etc, throughout program execution. They
   are read/write (can be assigned a value).
-* <<sub:subroutine-parameters,subroutine parameters>> - these are used to
-  hold the actual parameters passed to a subroutine.
-* <<sub:numbered-parameters,numbered parameters>> - most of these are used
-  to access offsets of coordinate systems.
-* <<sub:system-parameters,system parameters>> - used to determine the current
-  running version. They are read-only.
+* <<sub:subroutine-parameters,subroutine parameters>> - these are used to hold the actual parameters passed to a subroutine.
+* <<sub:numbered-parameters,numbered parameters>> - most of these are used to access offsets of coordinate systems.
+* <<sub:system-parameters,system parameters>> - used to determine the current running version. They are read-only.
 
 [[sub:numbered-parameters]]
 === Numbered Parameters(((Numbered Parameters)))
@@ -287,8 +281,7 @@ A parameter setting does not take
 effect until after all parameter values on the same line have been
 found. For example, if parameter 3 has been previously set to 15 and
 the line '#3=6 G1 X#3' is interpreted, a straight move to a point
-where X equals 15 will
-occur and the value of parameter 3 will be 6.
+where X equals 15 will occur and the value of parameter 3 will be 6.
 
 The '\#'  character takes precedence over other operations, so that, for
 example, '\#1+2' means the number found by adding 2 to the value of

docs/src/getting-started/getting-linuxcnc.adoc

@@ -331,7 +331,7 @@ uname -v
   document.
 
 . Add the LinuxCNC Archive Signing Key to your apt keyring by downloading
-  [the LinuxCNC installer script](https://www.linuxcnc.org/linuxcnc-install.sh)
+  [the LinuxCNC installer script](https://www.linuxcnc.org/linuxcnc-install.sh).
   You will need to make the script executable to run it:
 +
 ----
@@ -351,8 +351,8 @@ sudo ./linuxcnc-install.sh
   install, or alternatively on a fresh Install of Debian Bookworm 64-bit
   as described above.
 . You can add the LinuxCNC archive signing key and repository information
-  by downloading and running the installer script as described above. If
-  an RTAI kernel is detected it will stop before installing any packages.
+  by downloading and running the installer script as described above.
+  If an RTAI kernel is detected it will stop before installing any packages.
 . Update the package list from linuxcnc.org
 +
 ----
@@ -363,8 +363,7 @@ sudo apt-get update
 ----
 sudo apt-get install linuxcnc
 ----
-Reboot the machine, ensuring that the system boots from the new 5.4.258-rtai
-kernel.
+Reboot the machine, ensuring that the system boots from the new 5.4.258-rtai kernel.
 
 === Installing on Raspbian 12
 

docs/src/gui/qtvcp-widgets.adoc

@@ -181,7 +181,7 @@ It is based on PyQt's `QGridLayout`.
 image::images/qthalbar.png["QtVCP HalBar: Panel demonstrating the HAL Bar Level Indicator ",scale="25%"]
 
 This widget is used to indicate level or value, usually of a HAL s32/float pin. +
-you can also disable the HAL pin and use Qt signals or python commands to change the level. +
+You can also disable the HAL pin and use Qt signals or Python commands to change the level. +
 
 ==== Bar Properties:
 HalBar is a subclass of the Bar widget, so it inherits these properties  + 
@@ -1693,7 +1693,7 @@ It is based on PyQt's _QLabel_.
 //TODO StatusLabel widget capture/example
 
 This will display a label based on selectable status of the machine controller. +
-You can change how the status will be displayed by substituting python formatting code in the text template. You can also use rich text for different fonts/colors etc.
+You can change how the status will be displayed by substituting Python formatting code in the text template. You can also use rich text for different fonts/colors etc.
 
 .Selectable States
 These states are selectable:

docs/src/man/man1/iov2.1.adoc

@@ -95,7 +95,7 @@ Report bugs at https://github.com/LinuxCNC/linuxcnc/issues.
 
 == AUTHOR
 
-Derived from a work by Fred Proctor & Will Shackleford. 
+Derived from a work by Fred Proctor & Will Shackleford.
 Rework & adding v2 protocol support by Michael Haberler.
 
 == COPYRIGHT

docs/src/man/man1/linuxcncrsh.1.adoc

@@ -355,7 +355,7 @@ _jog joint_number_ | _axis_letter_ _<speed>_::
   With set, runs the opened program. If no StartLine is specified, runs
   from the beginning. If a StartLine is specified, start line, runs from
   that line. A start line of -1 runs in verify mode.
-  
+
 *pause*::
   With set, pause program execution.
 

docs/src/man/man1/mb2hal.1.adoc

@@ -6,75 +6,80 @@ mb2hal - HAL non-realtime component for Modbus
 
 == SYNOPSIS
 
-Default component name:::
+Default component name::
   loadusr -W mb2hal config=config_file.ini
-Custom component name: ::
+Custom component name::
   loadusr -Wn mymodule mb2hal config=config_file.ini
 
 == DESCRIPTION
 
-MB2HAL is a generic non-realtime HAL component to communicate with one
-or more Modbus devices. It supports Modbus RTU and Modbus TCP.
+MB2HAL is a generic non-realtime HAL component to communicate with one or more Modbus devices.
+It supports Modbus RTU and Modbus TCP.
 
-See http://linuxcnc.org/docs/html/drivers/mb2hal.html[] for more
-information.
+See http://linuxcnc.org/docs/html/drivers/mb2hal.html[] for more information.
 
 == PINS
 
 === fnct_01_read_coils:
 
-*mb2hal.m.n.bit bit out* +
-*mb2hal.m.n.bit-inv bit out*::
+*mb2hal.m.n.bit* bit out +
+*mb2hal.m.n.bit-inv* bit out
 
 === fnct_02_read_discrete_inputs:
 
-*mb2hal.m.n.bit bit out* +
-*mb2hal.m.n.bit-inv bit out*::
+*mb2hal.m.n.bit* bit out +
+*mb2hal.m.n.bit-inv* bit out
 
 === fnct_03_read_holding_registers:
 
-*mb2hal.m.n.float float out* +
-*mb2hal.m.n.int s32 out*::
+*mb2hal.m.n.float* float out +
+*mb2hal.m.n.int* s32 out
 
 === fnct_04_read_input_registers:
 
-*mb2hal.m.n.float float out* +
-*mb2hal.m.n.int s32 out*::
+*mb2hal.m.n.float* float out +
+*mb2hal.m.n.int* s32 out
 
 === fnct_05_write_single_coil:
 
-*mb2hal.m.n.bit bit in*::
+*mb2hal.m.n.bit* bit in::
   NELEMENTS needs to be 1 or PIN_NAMES must contain just one name.
 
 === fnct_06_write_single_register:
 
-*mb2hal.m.n.float float in* +
-*mb2hal.m.n.int s32 in*::
-  NELEMENTS needs to be 1 or PIN_NAMES must contain just one name. Both
-  pin values are added and limited to 65535 (UINT16_MAX). Use one and
-  let the other open (read as 0).
+*mb2hal.m.n.float* float in
+
+*mb2hal.m.n.int* s32 in::
+  NELEMENTS needs to be 1 or PIN_NAMES must contain just one name. +
+  Both pin values are added and limited to 65535 (UINT16_MAX).
+  Use one and let the other open (read as 0).
 
 === fnct_15_write_multiple_coils:
 
-*mb2hal.m.n.bit bit in*::
+*mb2hal.m.n.bit* bit in
 
 === fnct_16_write_multiple_registers:
 
-*mb2hal.m.n.float float in* +
-*mb2hal.m.n.int s32 in*::
-  Both pin values are added and limited to 65535 (UINT16_MAX). Use one
-  and let the other open (read as 0).
+*mb2hal.m.n.float* float in
+
+*mb2hal.m.n.int* s32 in::
+  Both pin values are added and limited to 65535 (UINT16_MAX).
+  Use one and let the other open (read as 0).
 
 === Each transaction
 
-*mb2hal.m.num_errors u32 in* Error counter
+*mb2hal.m.num_errors* u32 in::
+  Error counter
 
-m = HAL_TX_NAME or transaction number if not set, n = element number
-(NELEMENTS) +
-Example: +
-mb2hal.00.01.int (TRANSACTION_00, second register) +
-mb2hal.readStatus.01.bit (HAL_TX_NAME=readStatus, first bit)
 
+m = HAL_TX_NAME or transaction number if not set +
+n = element number (NELEMENTS)
+
+Example:
+....
+mb2hal.00.01.int (TRANSACTION_00, second register)
+mb2hal.readStatus.01.bit (HAL_TX_NAME=readStatus, first bit)
+....
 == AUTHOR
 
 Victor Rocco

docs/src/man/man1/mdi.1.adoc

@@ -11,19 +11,28 @@ instance
 
 == DESCRIPTION
 
-*mdi* sends G-code commands to LinuxCNC. The command starts an
-envirmonemt in which G-code commands are sent to the interpreter and
-machine feedback is displayed.
+*mdi* sends G-code commands to LinuxCNC.
+The command starts an envirmonemt in which G-code commands are sent to the interpreter and machine feedback is displayed.
 
 == USAGE
 
-send a single command and exit mdi m2 s1400
+send a single command and exit:
+....
+mdi m2 s1400
+....
 
-interactive session $mdi MDI> m3 s1000 MDI> G0 X100 MDI> ^Z $stopped
+interactive session
+....
+$mdi
+MDI> m3 s1000
+MDI> G0 X100
+MDI>` ^Z
+$stopped
+....
 
 == SEE ALSO
 
-linuxcnc(1)*
+*linuxcnc(1)*
 
 Much more information about LinuxCNC and HAL is available in the
 LinuxCNC and HAL User Manuals, found at /usr/share/doc/LinuxCNC/.