docs: Restructure autorate documentation

.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
         name: Install additional packages
         run: |
           apt-get update
-          apt-get install -y texinfo
+          apt-get install -y texinfo install-info
 
       - name: Build
         shell: bash

Makefile

@@ -38,6 +38,7 @@ docs: doc/info/emqttb.info doc/html/index.html
 
 doc/info/emqttb.info: $(TEXINFO)
 	texi2any -I doc/lee --info -o $@ $<
+	install-info $@ doc/info/dir
 
 doc/html/index.html: $(TEXINFO)
 # -c MATHJAX_CONFIGURATION="$(MATHJAX_OPTS)"

bin/emqttb

@@ -6,18 +6,14 @@ RUNNER_ROOT_DIR="{{ runner_root_dir }}"
 RUNNER_ESCRIPT_DIR="{{ runner_escript_dir }}"
 ERTS_VSN="{{ erts_vsn }}"
 
-ERTS_PATH=$RUNNER_ROOT_DIR/erts-$ERTS_VSN/bin
+ERTS_PATH="${RUNNER_ROOT_DIR}/erts-${ERTS_VSN}/bin"
+
+export INFOPATH="${INFOPATH}:${RUNNER_ROOT_DIR}/doc/info"
 
 ulimit -n $(ulimit -Hn)
 
 help() {
-    local file
-    file="${RUNNER_ROOT_DIR}/doc/info/emqttb.info"
-    if command -v emacs; then
-        emacs -eval "(info \"${file}\")"
-    else
-        info "${file}" "${@}"
-    fi
+    info emqttb "${@}"
 }
 
 if [ $# -eq 2 ] && [ $1 = "--help" ]; then

doc/src/autorate_descr.texi

@@ -0,0 +1,46 @@
+When the loadgen creates too much traffic, the system may get overloaded.
+In this case, the test usually has to be restarted all over again with different parameters.
+This can be very expensive in man-hours and computing resources.
+
+In order to prevent that, emqttb can tune some parameters (such as message publishing interval)
+automatically using
+@url{https://controlguru.com/integral-reset-windup-jacketing-logic-and-the-velocity-pi-form/,PI controller}.
+
+The following formula is used for the error function:
+
+@math{e=(a_{SP} - a_{PV}) a_{coeff}}
+
+@node Autoscale
+@section Autoscale
+
+A special autorate controlling the rate of spawning new clients is implicitly created for each client group.
+Its name usually follows the pattern @code{%scenario%/conn_interval}.
+
+By default, the number of pending (unacked) connections is used as the process variable.
+Number of pending connections is a metric that responds very fast to target overload, so it makes a reasonable default.
+
+For example the following command can automatically adjust the rate of connections:
+
+@example
+./emqttb --pushgw @@conn -I 10ms -N 5_000 \
+   @@a -a conn/conninterval -V 1000 --setpoint 10
+@end example
+
+@node SCRAM
+@section SCRAM
+
+Normally, autorate adjusts the control variable gradually.
+However, sometimes the system under test becomes overloaded suddenly, and in this case slowly decreasing the pressure may not be efficient enough.
+To combat this situation, @code{emqttb} has "SCRAM" mechanism, that immediately resets the control variable to a @ref{value/autorate/_/scram/override,configured safe value}.
+This happens when the value of process variable exceeds a @ref{value/autorate/_/scram/threshold,certain threshold}.
+
+SCRAM mode remains in effect until the number of pending connections becomes less than @math{\frac{t h}{100}}
+where @math{t} is threshold, and @math{h} is @ref{value/autorate/_/scram/hysteresis,hystersis}.
+
+@node Autorate List
+@section List of autorate variables
+@include autorate.texi
+
+@node Metrics List
+@section List of metrics
+@include metric.texi

doc/src/emqttb.texi

@@ -3,6 +3,12 @@
 @setfilename emqttb.info
 @settitle EMQTTB
 @c %**end of header
+
+@dircategory EMQTTB: an MQTT load generator.
+@direntry
+* EMQTTB: (emqttb).
+@end direntry
+
 @copying
 A scriptable autotuning MQTT load generator.
 
@@ -32,33 +38,51 @@ Copyright @copyright{} 2022-2025 EMQ Technologies Co., Ltd. All Rights Reserved.
   @insertcopying
 @end ifnottex
 
-@include intro.texi
+@node Introduction
+@chapter Introduction
+  @include intro.texi
 
 @node Invokation
 @chapter Invokation
-  @node CLI
-  @section CLI Arguments
-  @lowersections
-    @include cli_param.texi
-  @raisesections
-
-  @node OS Environment Variables
-  @section OS Environment Variables
-  @lowersections
-    @include os_env.texi
-  @raisesections
+EMQTTB executable accepts named CLI arguments (such as @option{--foo} or -f positional arguments and actions. Actions are special CLI arguments that start with @@ character (e.g. @option{@@pub}). Actions correspond to different load-generation scenarios, such as @option{@@pub} and @option{@@sub}, client group configurations (@option{@@g}) and autorates (@option{@@g}).
 
-@node All Values
-@chapter All Configurable Values
-  @include value.texi
+Each CLI action defines its own scope of named and positional CLI arguments. Positional arguments are always specified after named arguments within the scope. There is also a global scope of arguments that don’t belong to any action. Global arguments are specified before the very first action.
+
+Example:
+
+@example
+emqttb --foo --bar 1 positional1 positional2 @@action1 --foo 1 positional1 @@action2 ...
+       |___________| |_____________________|          |_________________|
+       |regular args    positional args    |            action1 scope
+       |___________________________________|
+                 global scope
+@end example
+
+Flag negation:
+
+Boolean flag arguments can be set to false by adding @code{no-} prefix, for example @option{--no-pushgw}.
+
+Short boolean flags can be set to false using @code{+} sigil instead of @code{-}.
+
+@node CLI
+@section CLI Arguments
+@lowersections
+  @include cli_param.texi
+@raisesections
+
+@node OS Environment Variables
+@section OS Environment Variables
+@lowersections
+  @include os_env.texi
+@raisesections
 
 @node Autorate
-@chapter List of autorate variables
-  @include autorate.texi
+@chapter Autorate
+  @include autorate_descr.texi
 
-@node Metrics
-@chapter List of metrics
-  @include metric.texi
+@node All Values
+@chapter All Configurable Values
+  @include value.texi
 
 @node Index
   @unnumbered Index

doc/src/intro.texi

@@ -1,5 +1,15 @@
-@node Introduction
-@chapter Introduction
+@node Concepts
+@section Concepts: Worker, Group, Scenario...
+
+@b{Worker} is a process that corresponds to a single MQTT client.
+
+@b{Behavior} is a callback module containing functions that workers run in a loop.
+
+@b{Group} is a supervised colletion of workers running the same behavior and sharing the same configuration. Group manager controls the number of workers, restarts failed workers and implements ramp up/down logic.
+
+@b{Scenario} is a callback module that creates several worker groups and manupulates group configuration using autorate.
+
+@b{Autorate} a process that adjusts group parameters (such as number of workers in the group, or worker configuration) based on constants or dynamic parameters, e.g. available RAM or CPU load, observed latency and so on.
 
 @node Topic Patterns
 @section Topic Patterns

doc/src/schema.texi

@@ -30,49 +30,6 @@
 
 @end macro
 
-@macro doc-autorate
-  When the loadgen creates too much traffic, the system may get overloaded.
-  In this case, the test usually has to be restarted all over again with different parameters.
-  This can be very expensive in man-hours and computing resources.
-
-  In order to prevent that, emqttb can tune some parameters (such as message publishing interval)
-  automatically using
-  @url{https://controlguru.com/integral-reset-windup-jacketing-logic-and-the-velocity-pi-form/,PI controller}.
-
-  The following formula is used for the error function:
-
-  @math{e=(a_{SP} - a_{PV}) a_{coeff}}
-
-  @heading Autoscale
-  @cindex autoscale
-
-  A special autorate controlling the rate of spawning new clients is implicitly created for each client group.
-  Its name usually follows the pattern @code{%scenario%/conn_interval}.
-
-
-  By default, the number of pending (unacked) connections is used as the process variable.
-  Number of pending connections is a metric that responds very fast to target overload, so it makes a reasonable default.
-
-  For example the following command can automatically adjust the rate of connections:
-
-  @example
-  ./emqttb --pushgw @@conn -I 10ms -N 5_000 \
-     @@a -a conn/conninterval -V 1000 --setpoint 10
-  @end example
-
-@end macro
-
-@macro doc-scram
-  Normally, autorate adjusts the control variable gradually.
-  However, sometimes the system under test becomes overloaded suddenly, and in this case slowly decreasing the pressure may not be efficient enough.
-  To combat this situation, @code{emqttb} has "SCRAM" mechanism, that immediately resets the control variable to a @ref{value/autorate/_/scram/override,configured safe value}.
-  This happens when the value of process variable exceeds a @ref{value/autorate/_/scram/threshold,certain threshold}.
-
-  SCRAM mode remains in effect until the number of pending connections becomes less than @math{\frac{t h}{100}}
-  where @math{t} is threshold, and FIXME @math{h} is @ref{value/autorate/_/scram/hysteresis,hystersis}.
-
-@end macro
-
 @macro doc-interval
   Supported units:
 

src/conf/emqttb_conf_model.erl

@@ -282,7 +282,7 @@ model() ->
    , autorate =>
        {[map, cli_action],
         #{ oneliner     => "Autorate configuration"
-         , doc          => "@doc-autorate"
+         , doc          => "@xref{Autorate}\n"
          , cli_operand  => "a"
          , key_elements => [[id]]
          },

src/framework/emqttb_autorate.erl

@@ -131,7 +131,7 @@ model() ->
         #{ oneliner    => "ID of the autorate configuration"
          , doc         => "Autorate identifier.
                            This value must be equal to one of the elements returned by @code{emqttb @@ls autorate} command.
-                           Full list is also available in FIXME <<autorate>>
+                           Full list is also available in @ref{Autorate List}.
                            "
          , type        => atom()
          , default     => default
@@ -144,7 +144,7 @@ model() ->
          , doc         => "This parameter specifies ID of the metric that senses pressure on the SUT and serves as the process variable (PV).
                            Its value must be equal to one of the metric IDs returned by @code{emqttb @@ls metric} command.
 
-                           Full list can be also found in FIXME <<metrics>>.
+                           Full list can be also found in @ref{Metrics List}.
                            "
          , type        => lee:model_key()
          , cli_operand => "pvar"
@@ -223,7 +223,7 @@ model() ->
        #{ enabled =>
             {[value, cli_param],
              #{ oneliner    => "Enable SCRAM"
-              , doc         => "@doc-scram"
+              , doc         => "@xref{SCRAM}\n"
               , type        => boolean()
               , default     => false
               , cli_operand => "olp"