File 3461-Improve-documentation-about-the-Erlang-she... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 3461-Improve-documentation-about-the-Erlang-shell.patch of Package erlang (Revision 8f54a1895f4b8ff59460801ed30cf276)

Currently displaying revision 8f54a1895f4b8ff59460801ed30cf276 , Show latest

From 8ae2eb10d775d7be1331381c48093375b4959900 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Tue, 12 Apr 2022 13:52:51 +0200
Subject: [PATCH] Improve documentation about the Erlang shell

---
 lib/kernel/doc/src/kernel_app.xml | 46 +++++++++++++++----------------
 lib/stdlib/doc/src/c.xml          | 29 +++++++++++++++++++
 lib/stdlib/doc/src/shell.xml      | 33 +++++++++++++++++++---
 lib/stdlib/doc/src/stdlib_app.xml | 14 +++++-----
 4 files changed, 88 insertions(+), 34 deletions(-)

diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml
index 4004956588..b99c6cc8ab 100644
--- a/lib/kernel/doc/src/kernel_app.xml
+++ b/lib/kernel/doc/src/kernel_app.xml
@@ -121,7 +121,7 @@
 application. For more information about configuration parameters,
 see file <seefile marker="app"><c>app(4)</c></seefile>.
 <taglist>
- <tag><c>distributed = [Distrib]</c></tag>
+ <tag><marker id="distributed"/><c>distributed = [Distrib]</c></tag>
 <item>
 Specifies which applications that are distributed and on which
 nodes they are allowed to execute. In this parameter:
@@ -158,7 +158,7 @@
 distribution connections. Using this option implies that the node
 also is <seecom marker="erts:erl#hidden"><c>-hidden</c></seecom>.
 </item>
- <tag><c>permissions = [Perm]</c></tag>
+ <tag><marker id="permissions"/><c>permissions = [Perm]</c></tag>
 <item>
 Specifies the default permission for applications when they
 are started. In this parameter:
@@ -261,7 +261,7 @@
 Specifies default options for <c>connect</c> sockets,
 see <seeerl marker="inet"><c>inet(3)</c></seeerl>.
 </item>
- <tag><c>inet_default_listen_options = [{Opt, Val}]</c></tag>
+ <tag><marker id="inet_default_listen_options"/><c>inet_default_listen_options = [{Opt, Val}]</c></tag>
 <item>
 Specifies default options for <c>listen</c> (and
 <c>accept</c>) sockets, see <seeerl marker="inet"><c>inet(3)</c></seeerl>.
@@ -290,20 +290,20 @@
 	 other distributed Erlang nodes.
 	 See <seemfa marker="gen_tcp#connect/4"><c>gen_tcp:connect/4</c></seemfa>.
 </item>
- <tag><c>inet_parse_error_log = silent</c></tag>
+ <tag><marker id="inet_parse_error_log"/><c>inet_parse_error_log = silent</c></tag>
 <item>
 If set, no log events are issued when erroneous lines are
 found and skipped in the various Inet configuration
 files.
 </item>
- <tag><c>inetrc = Filename</c></tag>
+ <tag><marker id="inetrc"/><c>inetrc = Filename</c></tag>
 <item>
 The name (string) of an Inet user configuration file. For details,
 	see section
 	<seeguide marker="erts:inet_cfg"><c>Inet Configuration</c></seeguide>
 	in the ERTS User's Guide.
 </item>
- <tag><c>net_setuptime = SetupTime</c></tag>
+ <tag><marker id="net_setuptime"/><c>net_setuptime = SetupTime</c></tag>
 <item>
 <marker id="net_setuptime"></marker>
 <c>SetupTime</c> must be a positive integer or floating point
@@ -422,7 +422,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 information.
 
 </item>
- <tag><c>shutdown_timeout = integer() | infinity</c></tag>
+ <tag><marker id="shutdown_timeout"/><c>shutdown_timeout = integer() | infinity</c></tag>
 <item>
 Specifies the time <c>application_controller</c> waits
 for an application to terminate during node shutdown. If the
@@ -431,7 +431,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 application. If this parameter is undefined, it defaults
 to <c>infinity</c>.
 </item>
- <tag><c>sync_nodes_mandatory = [NodeName]</c></tag>
+ <tag><marker id="sync_nodes_mandatory"/><c>sync_nodes_mandatory = [NodeName]</c></tag>
 <item>
 Specifies which other nodes that must be alive
 for this node to start properly. If some node in the list
@@ -439,7 +439,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 start either. If this parameter is undefined, it defaults to
 <c>[]</c>.
 </item>
- <tag><c>sync_nodes_optional = [NodeName]</c></tag>
+ <tag><marker id="sync_nodes_optional"/><c>sync_nodes_optional = [NodeName]</c></tag>
 <item>
 Specifies which other nodes that can be alive
 for this node to start properly. If some node in this list
@@ -447,7 +447,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 anyway. If this parameter is undefined, it defaults to
 the empty list.
 </item>
- <tag><c>sync_nodes_timeout = integer() | infinity</c></tag>
+ <tag><marker id="sync_nodes_timeout"/><c>sync_nodes_timeout = integer() | infinity</c></tag>
 <item>
 Specifies the time (in milliseconds) that this node
 waits for the mandatory and optional nodes to start. If
@@ -455,7 +455,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 performed. This option ensures that <c>global</c> is
 synchronized.
 </item>
- <tag><c>start_distribution = true | false</c></tag>
+ <tag><marker id="start_distribution"/><c>start_distribution = true | false</c></tag>
 <item>
 Starts all distribution services, such as <c>rpc</c>,
 <c>global</c>, and <c>net_kernel</c> if the parameter is
@@ -463,7 +463,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 for systems who want to disable all distribution functionality.
 Defaults to <c>true</c>.
 </item>
- <tag><c>start_dist_ac = true | false</c></tag>
+ <tag><marker id="start_dist_ac"/><c>start_dist_ac = true | false</c></tag>
 <item>
 Starts the <c>dist_ac</c> server if the parameter is
 <c>true</c>. This parameter is to be set to <c>true</c> for
@@ -472,7 +472,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 undefined, the server is started if parameter
 <c>distributed</c> is set.
 </item>
- <tag><c>start_boot_server = true | false</c></tag>
+ <tag><marker id="start_boot_server"/><c>start_boot_server = true | false</c></tag>
 <item>
 Starts the <c>boot_server</c> if the parameter is <c>true</c>
 (see <seeerl marker="erl_boot_server"><c>erl_boot_server(3)</c></seeerl>).
@@ -480,7 +480,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 	 using this service.
 Defaults to <c>false</c>.
 </item>
- <tag><c>boot_server_slaves = [SlaveIP]</c></tag>
+ <tag><marker id="boot_server_slaves"/><c>boot_server_slaves = [SlaveIP]</c></tag>
 <item>
 If configuration parameter <c>start_boot_server</c> is
 <c>true</c>, this parameter can be used to initialize
@@ -492,7 +492,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 	<c>'150.236.16.70', "150,236,16,70", {150,236,16,70}</c>.
 Defaults to <c>[]</c>.
 </item>
- <tag><c>start_disk_log = true | false</c></tag>
+ <tag><marker id="start_disk_log"/><c>start_disk_log = true | false</c></tag>
 <item>
 Starts the <c>disk_log_server</c> if the parameter is
 <c>true</c> (see <seeerl marker="disk_log"><c>disk_log(3)</c></seeerl>).
@@ -500,7 +500,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 	 using this service.
 Defaults to <c>false</c>.
 </item>
- <tag><c>start_pg = true | false</c></tag>
+ <tag><marker id="start_pg"/><c>start_pg = true | false</c></tag>
 <item>
 <marker id="start_pg"></marker>
 Starts the default <c>pg</c> scope server (see
@@ -509,7 +509,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 <c>true</c> in an embedded system that uses this service.
 Defaults to <c>false</c>.
 </item>
- <tag><c>start_timer = true | false</c></tag>
+ <tag><marker id="start_timer"/><c>start_timer = true | false</c></tag>
 <item>
 Starts the <c>timer_server</c> if the parameter is
 <c>true</c> (see <seeerl marker="stdlib:timer"><c>timer(3)</c></seeerl>).
@@ -517,7 +517,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 	 using this service.
 Defaults to <c>false</c>.
 </item>
- <tag><c>shell_history = enabled | disabled | module()</c></tag>
+ <tag><marker id="shell_history"/><c>shell_history = enabled | disabled | module()</c></tag>
 <item>
 Specifies whether shell history should be logged to disk
 between usages of <c>erl</c> (<c>enabled</c>), not logged
@@ -528,25 +528,25 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 called every time new line is entered in the shell. By default
 logging is disabled.
 </item>
- <tag><c>shell_history_drop = [string()]</c></tag>
+ <tag><marker id="shell_history_drop"/><c>shell_history_drop = [string()]</c></tag>
 <item>
 Specific log lines that should not be persisted. For
 example <c>["q().", "init:stop()."]</c> will allow to
 ignore commands that shut the node down. Defaults to
 <c>[]</c>.
 </item>
- <tag><c>shell_history_file_bytes = integer()</c></tag>
+ <tag><marker id="shell_history_file_bytes"/><c>shell_history_file_bytes = integer()</c></tag>
 <item>
 How many bytes the shell should remember. By default, the
 value is set to 512kb, and the minimal value is 50kb.
 </item>
- <tag><c>shell_history_path = string()</c></tag>
+ <tag><marker id="shell_history_path"/><c>shell_history_path = string()</c></tag>
 <item>
 Specifies where the shell history files will be stored.
 defaults to the user's cache directory as returned by
 <c>filename:basedir(user_cache, "erlang-history")</c>.
 </item>
- <tag><c>shutdown_func = {Mod, Func}</c></tag>
+ <tag><marker id="shutdown_func"/><c>shutdown_func = {Mod, Func}</c></tag>
 <item>
 Where:
 <list type="bulleted">
@@ -560,7 +560,7 @@ MaxT = NetTickTime + NetTickTime / NetTickIntensity</code>
 return as soon as possible for <c>application_controller</c>
 to terminate properly.
 </item>
- <tag><c>source_search_rules = [DirRule] | [SuffixRule] </c></tag>
+ <tag><marker id="source_search_rules"/><c>source_search_rules = [DirRule] | [SuffixRule] </c></tag>
 <item>
 	<marker id="source_search_rules"></marker>
 Where:
diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml
index 9d61999043..84b3aa8739 100644
--- a/lib/stdlib/doc/src/c.xml
+++ b/lib/stdlib/doc/src/c.xml
@@ -197,6 +197,35 @@
 </desc>
 </func>
 
+ <func>
+ <name name="hcb" arity="1" since="OTP 23.0"/>
+ <fsummary>Module help information</fsummary>
+ <type name="h_return"/>
+ <desc>
+ Print the callback documentation for <c>Module</c>
+ </desc>
+ </func>
+
+ <func>
+ <name name="hcb" arity="2" since="OTP 23.0"/>
+ <fsummary>Function help information</fsummary>
+ <type name="h_return"/>
+ <type name="hcb_return"/>
+ <desc>
+ Print the callback documentation for all <c>Module:Callback</c>s (regardless of arity).
+ </desc>
+ </func>
+
+ <func>
+ <name name="hcb" arity="3" since="OTP 23.0"/>
+ <fsummary>Function help information</fsummary>
+ <type name="h_return"/>
+ <type name="hcb_return"/>
+ <desc>
+ Print the callback documentation for <c>Module:Callback/Arity</c>.
+ </desc>
+ </func>
+
 <func>
 <name name="ht" arity="1" since="OTP 23.0"/>
 <fsummary>Type help information</fsummary>
diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml
index 1e943261f5..928d2686b6 100644
--- a/lib/stdlib/doc/src/shell.xml
+++ b/lib/stdlib/doc/src/shell.xml
@@ -39,16 +39,26 @@
 
 The shell is a user interface program
 for entering expression sequences. The expressions are
- evaluated and a value is returned.
- A history mechanism saves previous commands and their
+ evaluated and a value is returned. The shell provides an Emacs like set of
+ shortcuts for editing the text of the current line. See <seeguide marker="erts:tty">
+ tty - A Command-Line Interface</seeguide> in the ERTS User's Guide
+ for a list of all available shortcuts.
+
+ A history mechanism saves previous commands and their
 values, which can then be incorporated in later commands.
 How many commands and results to save can be determined by the user,
 either interactively, by calling
 <seemfa marker="#history/1"><c>history/1</c></seemfa> and
 <seemfa marker="#results/1"><c>results/1</c></seemfa>,
 or by setting the application configuration
- parameters <c>shell_history_length</c> and
- <c>shell_saved_results</c> for the STDLIB application.
+ parameters <seeapp marker="STDLIB_app#shell_history_length">
+ <c>shell_history_length</c></seeapp> and
+ <seeapp marker="STDLIB_app#shell_saved_results"><c>shell_saved_results</c></seeapp>
+ for the STDLIB application. The shell history can be saved to disk by
+ setting the application configuration parameter
+ <seeapp marker="kernel:kernel_app#shell_history"><c>shell_history</c></seeapp>
+ for the Kernel application.
+ 
 
 The shell uses a helper process for evaluating commands
 to protect the history mechanism from exceptions. By
@@ -168,6 +178,21 @@
 <item>
 Evaluates <c>shell_default:help()</c>.
 </item>
+ <tag><c>h(Module, Function)</c></tag>
+ <item>
+ Print the documentation for <c>Module:Function</c> in the shell
+ if available.
+ </item>
+ <tag><c>ht(Module, Type)</c></tag>
+ <item>
+ Print the documentation for <c>Module:Type</c> in the shell
+ if available.
+ </item>
+ <tag><c>hcb(Module, Callback)</c></tag>
+ <item>
+ Print the documentation for <c>Module:Callback</c> in the shell
+ if available.
+ </item>
 <tag><c>c(Mod)</c></tag>
 <item>
 Evaluates <c>shell_default:c(Mod)</c>. This compiles and
diff --git a/lib/stdlib/doc/src/stdlib_app.xml b/lib/stdlib/doc/src/stdlib_app.xml
index 298fbb4b91..26229fd255 100644
--- a/lib/stdlib/doc/src/stdlib_app.xml
+++ b/lib/stdlib/doc/src/stdlib_app.xml
@@ -43,26 +43,26 @@
 <seefile marker="kernel:app"><c>app(4)</c></seefile> module in Kernel.
 
 <taglist>
- <tag><c>shell_esc = icl | abort</c></tag>
+ <tag><marker id="shell_esc"/><c>shell_esc = icl | abort</c></tag>
 <item>
 Can be used to change the behavior of the Erlang shell when
 ^G is pressed.
 </item>
- <tag><c>restricted_shell = module()</c></tag>
+ <tag><marker id="restricted_shell"/><c>restricted_shell = module()</c></tag>
 <item>
 Can be used to run the Erlang shell in restricted mode.
 </item>
- <tag><c>shell_catch_exception = boolean()</c></tag>
+ <tag><marker id="shell_catch_exception"/><c>shell_catch_exception = boolean()</c></tag>
 <item>
 Can be used to set the exception handling of the evaluator process of
 Erlang shell.
 </item>
- <tag><c>shell_history_length = integer() >= 0</c></tag>
+ <tag><marker id="shell_history_length"/><c>shell_history_length = integer() >= 0</c></tag>
 <item>
 Can be used to determine how many commands are saved by the Erlang
 shell.
 </item>
- <tag><c>shell_prompt_func = {Mod, Func} | default</c></tag>
+ <tag><marker id="shell_prompt_func"/><c>shell_prompt_func = {Mod, Func} | default</c></tag>
 <item>
 where
 <list type="bulleted">
@@ -71,12 +71,12 @@
 </list>
 Can be used to set a customized Erlang shell prompt function.
 </item>
- <tag><c>shell_saved_results = integer() >= 0</c></tag>
+ <tag><marker id="shell_saved_results"/><c>shell_saved_results = integer() >= 0</c></tag>
 <item>
 Can be used to determine how many results are saved by the Erlang
 shell.
 </item>
- <tag><c>shell_strings = boolean()</c></tag>
+ <tag><marker id="shell_strings"/><c>shell_strings = boolean()</c></tag>
 <item>
 Can be used to determine how the Erlang shell outputs lists of
 integers.
-- 
2.34.1

Places

File 3461-Improve-documentation-about-the-Erlang-shell.patch of Package erlang (Revision 8f54a1895f4b8ff59460801ed30cf276)

Places