From fa6a0226d7d8ad656f58d6373782ac7b3aaf2e3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 21 Aug 2024 14:15:09 +0200 Subject: [PATCH] Improve formatting of man pages Update the description of executables to improve the formatting of man pages. While at it, do other minor improvements. --- erts/doc/references/epmd_cmd.md | 18 +-- erts/doc/references/erl_cmd.md | 110 ++++++++++-------- erts/doc/references/erlc_cmd.md | 4 +- erts/doc/references/erlsrv_cmd.md | 6 +- erts/doc/references/escript_cmd.md | 14 ++- lib/dialyzer/doc/references/typer_cmd.md | 2 +- lib/diameter/doc/references/diameterc_cmd.md | 68 ++++++----- lib/edoc/doc/references/edoc_cmd.md | 6 +- .../doc/references/erl_call_cmd.md | 12 +- 9 files changed, 134 insertions(+), 106 deletions(-) diff --git a/erts/doc/references/epmd_cmd.md b/erts/doc/references/epmd_cmd.md index 58767ae6d0bc..ebb121a560bc 100644 --- a/erts/doc/references/epmd_cmd.md +++ b/erts/doc/references/epmd_cmd.md @@ -23,18 +23,20 @@ Erlang Port Mapper Daemon ## Description -- ```text - epmd [-d|-debug] [DbgExtra...] [-address Addresses] +The `epmd` command be used to start the port mapper daemon: + +```text +epmd [-d|-debug] [DbgExtra...] [-address Addresses] [-port No] [-daemon] [-relaxed_command_check] - ``` +``` - Starts the port mapper daemon. +It can also be used to communicate with a running port mapper daemon: -- ```text - epmd [-d|-debug] [-port No] [-names|-kill|-stop Name] - ``` - Communicates with a running port mapper daemon. +```text +epmd [-d|-debug] [-port No] [-names|-kill|-stop Name] +``` + This daemon acts as a name server on all hosts involved in distributed Erlang computations. When an Erlang node starts, the node has a name and it obtains an diff --git a/erts/doc/references/erl_cmd.md b/erts/doc/references/erl_cmd.md index 41edffcd2f4d..88c576e98f32 100644 --- a/erts/doc/references/erl_cmd.md +++ b/erts/doc/references/erl_cmd.md @@ -19,16 +19,21 @@ limitations under the License. --> # erl +Start the Erlang runtime system. + +## Description + The `erl` program starts an Erlang runtime system. The exact details (for example, whether `erl` is a script or a program and which other programs it calls) are system-dependent. > #### Note {: .info } > -> If you are running Erlang/OTP 25 or earlier on Windows to start an Erlang -> system with full shell support you should use `werl.exe`. See the -> [Erlang/OTP 25 documentation](https://www.erlang.org/docs/25/man/werl) for -> details on how to do that. +> If you are using Erlang/OTP 25 or earlier on Windows and want to +> start an Erlang system with full shell support, you should use +> `werl.exe`. See the [Erlang/OTP 25 +> documentation](https://www.erlang.org/docs/25/man/werl) for details +> on how to do that. ## erl @@ -420,7 +425,8 @@ described in the corresponding application documentation. > > The connecting node needs to have a proper shell with terminal emulation. > This means that UNIX users must use an Erlang compiled with terminal - > capabilities and Windows users must use [`werl(1)`](werl_cmd.md). + > capabilities and before Erlang/OTP 25 Windows users must use + > [`werl`](werl_cmd.md). - **`-rsh Program`** - Specifies an alternative to `ssh` for starting a slave node on a remote host; see `m:slave`. @@ -512,10 +518,10 @@ the following flags: - **`+A size`{: #async_thread_pool_size }** - Sets the number of threads in async thread pool. Valid range is 1-1024. The async thread pool is used by - linked-in drivers to handle work that may take a very long time. Since OTP 21 - there are very few linked-in drivers in the default Erlang/OTP distribution - that uses the async thread pool. Most of them have been migrated to dirty IO - schedulers. Defaults to 1. + linked-in drivers to handle work that may take a very long time. + Since OTP 21, the default Erlang/OTP distribution includes few + linked-in drivers that use the async thread pool. Most of them have + been migrated to dirty IO schedulers. Defaults to 1. - **`+B [c | d | i]`** - Option `c` makes `Ctrl-C` interrupt the current shell instead of invoking the emulator break handler. Option `d` (same as specifying @@ -525,10 +531,6 @@ the following flags: If option `c` is used with `oldshell` on Unix, `Ctrl-C` will restart the shell process rather than interrupt it. - Notice that on Windows, this flag is only applicable for `werl`, not `erl` - (`oldshell`). Notice also that `Ctrl-Break` is used instead of `Ctrl-C` on - Windows. - - **`+c true | false`{: #+c }** - Enables or disables [time correction](time_correction.md#time-correction): @@ -576,7 +578,7 @@ the following flags: operations and performance for read operations. Each group consumes 64 bytes in each counter. - Notice that a runtime system using decentralized counter groups benefits from + Note that a runtime system using decentralized counter groups benefits from [binding schedulers to logical processors](erl_cmd.md#%2Bsbt), as the groups are distributed better between schedulers with this option. @@ -797,7 +799,7 @@ the following flags: The value used in runtime can be inspected by calling [`erlang:system_info(async_dist)`](`m:erlang#system_info_async_dist`). -- **[](){: #%2Bpc } `+pc Range`{: #printable_character_range }** +- **[](){: #%2Bpc } `+pc Range`{: #printable_character_range }** - Sets the range of characters that the system considers printable in heuristic detection of strings. This typically affects the shell, debugger, and `io:format` functions (when `~tp` is used in the format string). @@ -816,28 +818,34 @@ the following flags: See also `io:printable_range/0` in STDLIB. -- **[](){: #%2BP } `+P Number`{: #max_processes }** +- **[](){: #%2BP } `+P Number`{: #max_processes }** - Sets the maximum number of simultaneously existing processes for this system if a `Number` is passed as value. Valid range for `Number` is - `[1024-134217727]` + `[1024-134217727]`. - _NOTE_: The actual maximum chosen may be much larger than the `Number` passed. - Currently the runtime system often, but not always, chooses a value that is a - power of 2. This might, however, be changed in the future. The actual value - chosen can be checked by calling - [erlang:system_info(process_limit)](`m:erlang#system_info_process_limit`). + > #### Note {: .info } + > + > The actual maximum chosen may be much larger than the `Number` + > passed. Currently the runtime system often, but not always, + > chooses a value that is a power of 2. This might, however, be + > changed in the future. The actual value chosen can be checked by + > calling + > [erlang:system_info(process_limit)](`m:erlang#system_info_process_limit`). The default value is `1048576` -- **[](){: #%2BQ } `+Q Number`{: #max_ports }** +- **[](){: #%2BQ } `+Q Number`{: #max_ports }** - Sets the maximum number of simultaneously existing ports for this system if a - Number is passed as value. Valid range for `Number` is `[1024-134217727]` + Number is passed as value. Valid range for `Number` is `[1024-134217727]`. - _NOTE_: The actual maximum chosen may be much larger than the actual `Number` - passed. Currently the runtime system often, but not always, chooses a value - that is a power of 2. This might, however, be changed in the future. The - actual value chosen can be checked by calling - [erlang:system_info(port_limit)](`m:erlang#system_info_port_limit`). + > #### Note {: .info } + > + > The actual maximum chosen may be much larger than the actual + > `Number` passed. Currently the runtime system often, but not + > always, chooses a value that is a power of 2. This might, however, + > be changed in the future. The actual value chosen can be checked + > by calling + > [`erlang:system_info(port_limit)`](`m:erlang#system_info_port_limit`). The default value used is normally `65536`. However, if the runtime system is able to determine maximum amount of file descriptors that it is allowed to @@ -853,9 +861,9 @@ the following flags: The distribution mechanism is not backward compatible by default. This flag sets the emulator in compatibility mode with an earlier Erlang/OTP release `ReleaseNumber`. The release number must be in the range - `-2..`. This limits the emulator, making it - possible for it to communicate with Erlang nodes (as well as C- and Java - nodes) running that earlier release. + `-2` through ``. This limits the emulator, + making it possible for it to communicate with Erlang nodes (as well as C + and Java nodes) running that earlier release. > #### Note {: .info } > @@ -863,7 +871,7 @@ the following flags: > system is of the same Erlang/OTP release, or from two different Erlang/OTP > releases X and Y, where _all_ Y nodes have compatibility mode X. -- **`+r`** - Forces ETS memory block to be moved on realloc. +- **`+r`** - Forces ETS memory blocks to be moved on reallocation. - **`+rg ReaderGroupsLimit`{: #+rg }** - Limits the number of reader groups used by read/write locks optimized for read operations in the Erlang runtime @@ -929,7 +937,7 @@ the following flags: - The number of dirty CPU scheduler threads online cannot exceed the number of normal scheduler threads online. - For details, see the [`+S`](erl_cmd.md#%2BS) and [`+SP`](erl_cmd.md#%2BSP). By + For details, see [`+S`](erl_cmd.md#%2BS) and [`+SP`](erl_cmd.md#%2BSP). By default, the number of dirty CPU scheduler threads created equals the number of normal scheduler threads created, and the number of dirty CPU scheduler threads online equals the number of normal scheduler threads online. @@ -1110,24 +1118,26 @@ the following flags: `+scl false` is similar to [`+sub true`](erl_cmd.md#%2Bsub), but `+sub true` also balances scheduler utilization between schedulers. - - **`+sct CpuTopology`{: #+sct }** - \* - ` = integer(); when 0 =< =< 65535` - - - ` = -` - - ` = | ` - - ` = , | ` - - ` = L` - - ` = T | t` - - ` = C | c` - - ` = P | p` - - ` = N | n` - - ` = | ` - - `CpuTopology = : | ` - - Sets a user-defined CPU topology. The user-defined CPU topology overrides + - **`+sct CpuTopology`{: #+sct }** - Sets a user-defined CPU topology. + The user-defined CPU topology overrides any automatically detected CPU topology. The CPU topology is used when [binding schedulers to logical processors](erl_cmd.md#%2Bsbt). + ``` + = integer(); when 0 =< =< 65535 + = - + = | + = , | + = L + = T | t + = C | c + = P | p + = N | n + = | + + CpuTopology = : | + ``` + Uppercase letters signify real identifiers and lowercase letters signify fake identifiers only used for description of the topology. Identifiers passed as real identifiers can be used by the runtime system when trying to @@ -1226,7 +1236,7 @@ the following flags: > #### Note {: .info } > > Reading CPU topology slows down startup when starting many parallel - > instances of ERTS on systems with large amount of cores, using this flag + > instances of ERTS on systems with large amount of cores; using this flag > might speed up execution in such scenarios. - **`+sfwi Interval`{: #+sfwi }** - Sets scheduler-forced wakeup interval. All diff --git a/erts/doc/references/erlc_cmd.md b/erts/doc/references/erlc_cmd.md index 56f4a5502088..08b73df9adc3 100644 --- a/erts/doc/references/erlc_cmd.md +++ b/erts/doc/references/erlc_cmd.md @@ -90,8 +90,8 @@ The following flags are supported: special feature `all` can be used to disable all non permanent features. - **`-list-features`** - [](){: #list-features } List short descriptions of the - current configurable [features](`e:system:features.md#features`). Non - configurable features, i.e., those with a status of `rejected` or `permanent` + current configurable [features](`e:system:features.md#features`). + Non-configurable features (those with status `rejected` or `permanent`) will not be shown. - **`-describe-feature `** - [](){: #describe-feature } Show long diff --git a/erts/doc/references/erlsrv_cmd.md b/erts/doc/references/erlsrv_cmd.md index 240441fe13f5..0933d2703b79 100644 --- a/erts/doc/references/erlsrv_cmd.md +++ b/erts/doc/references/erlsrv_cmd.md @@ -29,7 +29,7 @@ embedded systems to start without any user needing to log on. The emulator started in this way can be manipulated through the Windows services applet in a manner similar to other services. -Notice that `erlsrv` is not a general service utility for Windows, but designed +Note that `erlsrv` is not a general service utility for Windows, but designed for embedded Erlang systems. `erlsrv` also provides a command-line interface for registering, changing, @@ -102,7 +102,7 @@ The following parameters can be specified for each Erlang service: - **`low`** - Can be used if interactive performance is not to be affected by the emulator process. - - **`default` (the default>** + - **`default`** - The default priority. - **`SName or Name`** - Specifies the short or long node name of the Erlang emulator. The Erlang services are always distributed. Default is to use the @@ -348,7 +348,7 @@ Although the options are described in a Unix-like format, the case of the options or commands is not relevant, and both character "/" and "-" can be used for options. -Notice that the program resides in the emulator's `bin` directory, not in the +Note that the program resides in the emulator's `bin` directory, not in the `bin` directory directly under the Erlang root. The reasons for this are the subtle problem of upgrading the emulator on a running system, where a new version of the runtime system should not need to overwrite existing (and diff --git a/erts/doc/references/escript_cmd.md b/erts/doc/references/escript_cmd.md index 1c9c5d09509f..63ca23ad5c76 100644 --- a/erts/doc/references/escript_cmd.md +++ b/erts/doc/references/escript_cmd.md @@ -19,6 +19,16 @@ limitations under the License. --> # escript +Run a script written in Erlang. + +## Synopsis + +``` +script-name [arg1 arg2...] +``` + +## Description + `escript` provides support for running short Erlang programs without having to compile them first, and an easy way to retrieve the command-line arguments. `escript`s are created by either writing them by hand or using `escript:create/2`. @@ -26,7 +36,7 @@ compile them first, and an easy way to retrieve the command-line arguments. escripts are run by directly invoking them (does not work on Windows): ```text -script-name.escript [arg1 arg2...] +script-name [arg1 arg2...] ``` or by calling the `escript` program (works on all platforms): @@ -188,7 +198,7 @@ application to be available. > #### Change {: .info } > -> Before the Erlang/OTP 27 the script would be interpreted by default. +> Before Erlang/OTP 27 the script would be interpreted by default. ## Precompiled escripts diff --git a/lib/dialyzer/doc/references/typer_cmd.md b/lib/dialyzer/doc/references/typer_cmd.md index 3b5402acbacb..245abc9bd0f4 100644 --- a/lib/dialyzer/doc/references/typer_cmd.md +++ b/lib/dialyzer/doc/references/typer_cmd.md @@ -19,7 +19,7 @@ limitations under the License. --> # typer -TypEr is a **TYP**e annotator for **ER**lang programs. +Type annotator for Erlang programs. ## Description diff --git a/lib/diameter/doc/references/diameterc_cmd.md b/lib/diameter/doc/references/diameterc_cmd.md index d5ed9c4bf130..75f23749a518 100644 --- a/lib/diameter/doc/references/diameterc_cmd.md +++ b/lib/diameter/doc/references/diameterc_cmd.md @@ -19,7 +19,13 @@ limitations under the License. --> # diameterc -diameterc \[] +Compile a diameter dictionary to Erlang source. + +## Synopsis + +``` +diameterc [] +``` ## Description @@ -30,52 +36,52 @@ messages and AVPs. The module `m:diameter_make` provides an alternate compilation interface. -## USAGE +# USAGE -- **diameterc \[] ** - Compile a single dictionary file to Erlang - source. Valid options are as follows. +Compile a single dictionary file to Erlang +source. Valid options are as follows. - - **\-i ** - Prepend the specified directory to the code path. Use to - point at beam files compiled from inherited dictionaries, - `[@inherits](diameter_dict.md#inherits)` in a dictionary file creating a - beam dependency, not an erl/hrl dependency. +- **\-i ** - Prepend the specified directory to the code path. Use to + point at beam files compiled from inherited dictionaries, + `[@inherits](diameter_dict.md#inherits)` in a dictionary file creating a + beam dependency, not an erl/hrl dependency. - Multiple `-i` options can be specified. + Multiple `-i` options can be specified. - - **\-o ** - Write generated source to the specified directory. Defaults - to the current working directory. +- **\-o ** - Write generated source to the specified directory. Defaults + to the current working directory. - - **\-E** +- **\-E** - Suppress `.erl` file generation. - - **\-H** - Suppress erl and hrl generation, respectively. +- **\-H** - Suppress `.hrl` file generation. - - **\--name ** +- **\--name ** - Name the output module. - - **\--prefix ** - Transform the input dictionary before compilation, - setting `[@name](diameter_dict.md#name)` or - `[@prefix](diameter_dict.md#prefix)` to the specified string. +- **\--prefix ** - Transform the input dictionary before compilation, + setting `[@name](diameter_dict.md#name)` or + `[@prefix](diameter_dict.md#prefix)` to the specified string. - - **\--inherits ** - Transform the input dictionary before compilation, - appending `[@inherits](diameter_dict.md#inherits)` of the specified string. +- **\--inherits ** - Transform the input dictionary before compilation, + appending `[@inherits](diameter_dict.md#inherits)` of the specified string. - Two forms of `--inherits` have special meaning: + Two forms of `--inherits` have special meaning: - ```text - --inherits - - --inherits Prev/Mod - ``` + ```text + --inherits - + --inherits Prev/Mod + ``` - The first has the effect of clearing any previous inherits, the second of - replacing a previous inherits of `Prev` to one of `Mod`. This allows the - semantics of the input dictionary to be changed without modifying the file - itself. + The first has the effect of clearing any previous inherits, the second of + replacing a previous inherits of `Prev` to one of `Mod`. This allows the + semantics of the input dictionary to be changed without modifying the file + itself. - Multiple `--inherits` options can be specified. + Multiple `--inherits` options can be specified. -## EXIT STATUS +# EXIT STATUS Returns 0 on success, non-zero on failure. -## SEE ALSO +# SEE ALSO `m:diameter_make`, [diameter_dict(4)](diameter_dict.md) diff --git a/lib/edoc/doc/references/edoc_cmd.md b/lib/edoc/doc/references/edoc_cmd.md index b31e75b05c5f..577c00f74e6c 100644 --- a/lib/edoc/doc/references/edoc_cmd.md +++ b/lib/edoc/doc/references/edoc_cmd.md @@ -17,13 +17,13 @@ limitations under the License. %CopyrightEnd% --> -# edoc_cmd +# edoc -EDoc command line interface EScript. +Generate documentation as HTML or EEP-48 doc chunks. ## Description -This script is a command line entry point to both `edoc:application/2` and +This program is a command line entry point to both `edoc:application/2` and `edoc:files/2` functions. It also allows to generate just the EEP-48 doc chunks (using the `-chunks` flag) instead of the complete HTML documentation. diff --git a/lib/erl_interface/doc/references/erl_call_cmd.md b/lib/erl_interface/doc/references/erl_call_cmd.md index 91dc85f23493..466949e38710 100644 --- a/lib/erl_interface/doc/references/erl_call_cmd.md +++ b/lib/erl_interface/doc/references/erl_call_cmd.md @@ -24,7 +24,7 @@ Call/start a distributed Erlang node. ## Description `erl_call` makes it possible to start and/or communicate with a distributed -Erlang node. It is built upon the `Erl_Interface` library as an example +Erlang node. It is built on the `Erl_Interface` library as an example application. Its purpose is to use a Unix shell script to interact with a distributed Erlang node. It performs all communication with the Erlang _rex server_, using the standard Erlang RPC facility. It does not require any special @@ -58,9 +58,9 @@ Each option flag is described below with its name, type, and meaning. - **`-address [Hostname:]Port`** - (One of `-n`, `-name`, `-sname` or `-address` is required.) `Hostname` is the hostname of the machine that is running the - peer node that `erl_call` shall communicate with. The default hostname is the + peer node that `erl_call` will communicate with. The default hostname is the hostname of the local machine. `Port` is the port number of the node that - `erl_call` shall communicate with. The `-address` flag cannot be combined with + `erl_call` will communicate with. The `-address` flag cannot be combined with any of the flags `-n`, `-name`, `-sname` or `-s`. The `-address` flag is typically useful when one wants to call a node that is @@ -77,7 +77,7 @@ Each option flag is described below with its name, type, and meaning. Erlang node in question. - **`-e`** - (_Optional._) Reads a sequence of Erlang expressions, separated by - comma (,) and ended with a full stop (.), from `stdin` until EOF (Control-D). + comma (`,`) and ended with a full stop (`.`), from `stdin` until EOF (Control-D). Evaluates the expressions and returns the result from the last expression. Returns `{ok,Result}` on success. @@ -91,9 +91,9 @@ Each option flag is described below with its name, type, and meaning. The printed data is UTF-8 encoded. - This option is only relevant together with the option `-a` or `-e`. + This option is only relevant combined with the `-a` or `-e` option. - See the documentation of [the I/O protocol](`e:stdlib:io_protocol.md`), for + See the documentation of [the I/O protocol](`e:stdlib:io_protocol.md`) for more information about the group leader concept. > #### Note {: .info }