diff options
| author | Lukas Larsson <lukas@erlang.org> | 2020-03-11 10:11:22 +0100 |
|---|---|---|
| committer | Lukas Larsson <lukas@erlang.org> | 2020-03-27 11:02:23 +0100 |
| commit | 0799c2b0e9ae5fce18d092a153fff884d1dd3912 (patch) | |
| tree | c7c72465bd01591a9163e5ad17cea92bf3be75ec /system | |
| parent | 6c6fe8e774f7cde6d158b450fd1ad6c3129dc22e (diff) | |
| download | erlang-0799c2b0e9ae5fce18d092a153fff884d1dd3912.tar.gz | |
otp: Convert all <seealso> to more specific variants
We add `seemfa`, `seeerl`, `seetype`, `seeapp`, `seecom`, `seecref`
, `seefile` and `seeguide` in order to make it easier to reason
about what each link points to without examining the target.
This information will then be embedded in the EEP-48 chunks for
usage by other tools.
The tool used can be found here:
https://gist.github.com/garazdawi/68527d92ae5b37c8f129bfbdfffdfa68
Diffstat (limited to 'system')
61 files changed, 700 insertions, 701 deletions
diff --git a/system/doc/design_principles/applications.xml b/system/doc/design_principles/applications.xml index 8f1969ff29..f576701051 100644 --- a/system/doc/design_principles/applications.xml +++ b/system/doc/design_principles/applications.xml @@ -40,18 +40,18 @@ that is, a component that can be started and stopped as a unit, and which can also be reused in other systems.</p> <p>To do this, create an - <seealso marker="#callback_module">application callback module</seealso>, + <seeguide marker="#callback_module">application callback module</seeguide>, and describe how the application is to be started and stopped.</p> <p>Then, an <em>application specification</em> is needed, which is put in an - <seealso marker="#appl_res_file">application resource file</seealso>. + <seeguide marker="#appl_res_file">application resource file</seeguide>. Among other things, this file specifies which modules the application consists of and the name of the callback module.</p> <p>If you use <c>systools</c>, the Erlang/OTP tools for packaging code - (see <seealso marker="release_structure">Releases</seealso>), + (see <seeguide marker="release_structure">Releases</seeguide>), the code for each application is placed in a separate directory following a pre-defined - <seealso marker="#app_dir">directory structure</seealso>.</p> + <seeguide marker="#app_dir">directory structure</seeguide>.</p> </section> <section> @@ -71,22 +71,22 @@ stop(State) as is to <c>stop</c>.</item> <item><c>StartType</c> is usually the atom <c>normal</c>. It has other values only in the case of a takeover or failover, see - <seealso marker="distributed_applications">Distributed Applications</seealso>. + <seeguide marker="distributed_applications">Distributed Applications</seeguide>. </item> <item><c>StartArgs</c> is defined by the key <c>mod</c> in the - <seealso marker="#appl_res_file">application - resource file</seealso>.</item> + <seeguide marker="#appl_res_file">application + resource file</seeguide>.</item> <item><c>stop/1</c> is called <em>after</em> the application has been stopped and is to do any necessary cleaning up. The actual stopping of the application, that is, the shutdown of the supervision tree, is handled automatically as described in - <seealso marker="#stopping">Starting and Stopping Applications</seealso>. + <seeguide marker="#stopping">Starting and Stopping Applications</seeguide>. </item> </list> <marker id="ch_app"></marker> <p>Example of an application callback module for packaging the supervision tree from - <seealso marker="sup_princ#ex">Supervisor Behaviour</seealso>:</p> + <seeguide marker="sup_princ#ex">Supervisor Behaviour</seeguide>:</p> <code type="none"> -module(ch_app). -behaviour(application). @@ -137,7 +137,7 @@ ch_app:start(normal, [])</code> ch_app:stop([])</code> <p>When using <c>systools</c>, the Erlang/OTP tools for packaging code (see Section - <seealso marker="release_structure">Releases</seealso>), the keys + <seeguide marker="release_structure">Releases</seeguide>), the keys <c>description</c>, <c>vsn</c>, <c>modules</c>, <c>registered</c>, and <c>applications</c> are also to be specified:</p> <code type="none"> @@ -167,7 +167,7 @@ ch_app:stop([])</code> and STDLIB.</item> </list> <note><p>For details about the syntax and contents of the application - resource file, see the <seealso marker="kernel:app">app</seealso> + resource file, see the <seefile marker="kernel:app">app</seefile> manual page in Kernel.</p></note> </section> @@ -180,14 +180,14 @@ ch_app:stop([])</code> <p>This can be useful to know, even if <c>systools</c> is not used, since Erlang/OTP is packaged according to the OTP principles and thus comes with a specific directory structure. The code server - (see the <seealso marker="kernel:code"><c>code(3)</c></seealso> manual + (see the <seeerl marker="kernel:code"><c>code(3)</c></seeerl> manual page in Kernel) automatically uses code from the directory with the highest version number, if more than one version of an application is present.</p> <section> <title>Directory Structure Guidelines for a Development Environment</title> <p>Any directory structure for development will suffice as long as the released directory structure - adhere to the <seealso marker="#app_dir_released">description below</seealso>, + adhere to the <seeguide marker="#app_dir_released">description below</seeguide>, but it is encouraged that the same directory structure also be used in a development environment. The version number should be omitted from the application directory name since this is an artifact of the release step. @@ -443,7 +443,7 @@ ok 2> <input>application:get_env(ch_app, file).</input> {ok,"testlog"}</pre> <p>If - <seealso marker="release_handling#sys">release handling</seealso> + <seeguide marker="release_handling#sys">release handling</seeguide> is used, exactly one system configuration file is to be used and that file is to be called <c>sys.config</c>.</p> <p>The values in the <c>.app</c> file and the values in a diff --git a/system/doc/design_principles/appup_cookbook.xml b/system/doc/design_principles/appup_cookbook.xml index 4f23c42c59..e3441d7483 100644 --- a/system/doc/design_principles/appup_cookbook.xml +++ b/system/doc/design_principles/appup_cookbook.xml @@ -55,7 +55,7 @@ belong to the STDLIB application and upgrading/downgrading normally requires an emulator restart.</p> <p>OTP thus provides no support for changing residence modules except - in the case of <seealso marker="#spec">special processes</seealso>.</p> + in the case of <seeguide marker="#spec">special processes</seeguide>.</p> </section> <section> @@ -64,7 +64,7 @@ extensions simple code replacement is sufficient.</p> <p><em>Example:</em> When adding a function to <c>ch3</c>, as described in the example in - <seealso marker="release_handling#appup">Release Handling</seealso>, + <seeguide marker="release_handling#appup">Release Handling</seeguide>, <c>ch_app.appup</c> looks as follows:</p> <code type="none"> {"2", @@ -72,7 +72,7 @@ [{"1", [{load_module, ch3}]}] }.</code> <p>OTP also supports changing the internal state of behaviour - processes, see <seealso marker="#int_state">Changing Internal State</seealso>.</p> + processes, see <seeguide marker="#int_state">Changing Internal State</seeguide>.</p> </section> <section> @@ -84,7 +84,7 @@ of the callback module. Thus, synchronized code replacement is used.</p> <p><em>Example:</em> Consider <c>gen_server</c> <c>ch3</c> from - <seealso marker="gen_server_concepts#ex">gen_server Behaviour</seealso>. + <seeguide marker="gen_server_concepts#ex">gen_server Behaviour</seeguide>. The internal state is a term <c>Chs</c> representing the available channels. Assume you want to add a counter <c>N</c>, which keeps track of the number of <c>alloc</c> requests @@ -130,7 +130,7 @@ code_change(_Vsn, Chs, _Extra) -> <title>Module Dependencies</title> <p>Assume that a module is extended by adding an interface function, as in the example in - <seealso marker="release_handling#appup">Release Handling</seealso>, + <seeguide marker="release_handling#appup">Release Handling</seeguide>, where a function <c>available/0</c> is added to <c>ch3</c>.</p> <p>If a call is added to this function, say in module <c>m1</c>, a runtime error could can occur during release upgrade if @@ -197,7 +197,7 @@ ch_app.appup: find the process.</p> </note> <p><em>Example:</em> Consider the example <c>ch4</c> in - <seealso marker="spec_proc#ex">sys and proc_lib</seealso>. + <seeguide marker="spec_proc#ex">sys and proc_lib</seeguide>. When started by a supervisor, the child specification can look as follows:</p> <code type="none"> @@ -236,13 +236,13 @@ system_code_change(Chs, _Module, _OldVsn, _Extra) -> (<c>ch4</c>).</item> <item>The third argument is <c>Vsn</c> or <c>{down,Vsn}</c>, as described for <c>gen_server:code_change/3</c> in - <seealso marker="#code_change">Changing Internal State</seealso>.</item> + <seeguide marker="#code_change">Changing Internal State</seeguide>.</item> </list> <p>In this case, all arguments but the first are ignored and the function simply returns the internal state again. This is enough if the code only has been extended. If instead the internal state is changed (similar to the example in - <seealso marker="#int_state">Changing Internal State</seealso>), + <seeguide marker="#int_state">Changing Internal State</seeguide>), this is done in this function and <c>{ok,Chs2}</c> returned.</p> </section> @@ -271,7 +271,7 @@ system_code_change(Chs, _Module, _OldVsn, _Extra) -> {update, Module, supervisor}</code> <p><em>Example:</em> To change the restart strategy of <c>ch_sup</c> (from - <seealso marker="sup_princ#ex">Supervisor Behaviour</seealso>) + <seeguide marker="sup_princ#ex">Supervisor Behaviour</seeguide>) from <c>one_for_one</c> to <c>one_for_all</c>, change the callback function <c>init/1</c> in <c>ch_sup.erl</c>:</p> <code type="none"> @@ -380,7 +380,7 @@ init(_Args) -> <title>Starting or Terminating a Process</title> <p>In a system structured according to the OTP design principles, any process would be a child process belonging to a supervisor, see - <seealso marker="#sup_add">Adding and Deleting Child Processes</seealso> + <seeguide marker="#sup_add">Adding and Deleting Child Processes</seeguide> in Changing a Supervisor.</p> </section> @@ -398,7 +398,7 @@ init(_Args) -> complicated to be made without restarting the processes, for example, if the supervisor hierarchy has been restructured.</p> <p><em>Example:</em> When adding a child <c>m1</c> to <c>ch_sup</c>, as in - <seealso marker="#sup_add">Adding and Deleting Child Processes</seealso> + <seeguide marker="#sup_add">Adding and Deleting Child Processes</seeguide> in Changing a Supervisor, an alternative to updating the supervisor is to restart the entire application:</p> <code type="none"> @@ -631,14 +631,14 @@ code_change(_OldVsn, State, port) -> It is executed before all other upgrade instructions. For more information about this instruction, see restart_new_emulator (Low-Level) in - <seealso marker="release_handling#restart_new_emulator_instr">Release Handling Instructions</seealso>. + <seeguide marker="release_handling#restart_new_emulator_instr">Release Handling Instructions</seeguide>. </p></item> <item><p><c>restart_emulator</c></p> <p>Used when a restart of the emulator is required after all other upgrade instructions are executed. For more information about this instruction, see restart_emulator (Low-Level) in - <seealso marker="release_handling#restart_emulator_instr">Release Handling Instructions</seealso>. + <seeguide marker="release_handling#restart_emulator_instr">Release Handling Instructions</seeguide>. </p></item> </list> <p>If an emulator restart is necessary and no upgrade instructions diff --git a/system/doc/design_principles/des_princ.xml b/system/doc/design_principles/des_princ.xml index 2bfb8eb3c7..76ac6a0c99 100644 --- a/system/doc/design_principles/des_princ.xml +++ b/system/doc/design_principles/des_princ.xml @@ -223,13 +223,13 @@ free(Ch, {Alloc, Free} = Channels) -> to the Erlang/OTP behaviour <c>gen_server</c>.</p> <p>The standard Erlang/OTP behaviours are:</p> <list type="bulleted"> - <item><p><seealso marker="gen_server_concepts">gen_server</seealso></p> + <item><p><seeguide marker="gen_server_concepts">gen_server</seeguide></p> <p>For implementing the server of a client-server relation</p></item> - <item><p><seealso marker="statem">gen_statem</seealso></p> + <item><p><seeguide marker="statem">gen_statem</seeguide></p> <p>For implementing state machines</p></item> - <item><p><seealso marker="events">gen_event</seealso></p> + <item><p><seeguide marker="events">gen_event</seeguide></p> <p>For implementing event handling functionality</p></item> - <item><p><seealso marker="sup_princ">supervisor</seealso></p> + <item><p><seeguide marker="sup_princ">supervisor</seeguide></p> <p>For implementing a supervisor in a supervision tree</p></item> </list> <p>The compiler understands the module attribute @@ -267,7 +267,7 @@ free(Ch, {Alloc, Free} = Channels) -> <p>An application with processes is easiest implemented as a supervision tree using the standard behaviours.</p> <p>How to program applications is described in - <seealso marker="applications">Applications</seealso>.</p> + <seeguide marker="applications">Applications</seeguide>.</p> </section> <section> @@ -275,7 +275,7 @@ free(Ch, {Alloc, Free} = Channels) -> <p>A <em>release</em> is a complete system made out from a subset of Erlang/OTP applications and a set of user-specific applications.</p> <p>How to program releases is described in - <seealso marker="release_structure">Releases</seealso>.</p> + <seeguide marker="release_structure">Releases</seeguide>.</p> <p>How to install a release in a target environment is described in the section about target systems in Section 2 System Principles.</p> </section> @@ -285,7 +285,7 @@ free(Ch, {Alloc, Free} = Channels) -> <p><em>Release handling</em> is upgrading and downgrading between different versions of a release, in a (possibly) running system. How to do this is described in - <seealso marker="release_handling">Release Handling</seealso>.</p> + <seeguide marker="release_handling">Release Handling</seeguide>.</p> </section> </chapter> diff --git a/system/doc/design_principles/distributed_applications.xml b/system/doc/design_principles/distributed_applications.xml index dee08d483a..99219cd5a5 100644 --- a/system/doc/design_principles/distributed_applications.xml +++ b/system/doc/design_principles/distributed_applications.xml @@ -123,7 +123,7 @@ <c>application:start(Application)</c> at <em>all of these nodes.</em></p> <p>A boot script (see - <seealso marker="release_structure">Releases</seealso>) + <seeguide marker="release_structure">Releases</seeguide>) can be used that automatically starts the application.</p> <p>The application is started at the first operational node that is listed in the list of nodes in the <c>distributed</c> @@ -164,7 +164,7 @@ Module:start(normal, StartArgs)</code> Module:start(normal, StartArgs)</code> <p>An exception is if the application has the <c>start_phases</c> key defined - (see <seealso marker="included_applications">Included Applications</seealso>). + (see <seeguide marker="included_applications">Included Applications</seeguide>). The application is then instead started by calling:</p> <code type="none"> Module:start({failover, Node}, StartArgs)</code> diff --git a/system/doc/design_principles/events.xml b/system/doc/design_principles/events.xml index e37b8b460d..b5c7d53ef5 100644 --- a/system/doc/design_principles/events.xml +++ b/system/doc/design_principles/events.xml @@ -208,7 +208,7 @@ terminate(_Args, Fd) -> function is needed. The event manager is automatically terminated by its supervisor. Exactly how this is done is defined by a - <seealso marker="sup_princ#shutdown">shutdown strategy</seealso> + <seeguide marker="sup_princ#shutdown">shutdown strategy</seeguide> set in the supervisor.</p> </section> diff --git a/system/doc/design_principles/gen_server_concepts.xml b/system/doc/design_principles/gen_server_concepts.xml index 06413a3d93..3afe4df983 100644 --- a/system/doc/design_principles/gen_server_concepts.xml +++ b/system/doc/design_principles/gen_server_concepts.xml @@ -31,7 +31,7 @@ </header> <marker id="gen_server"></marker> <p>This section is to be read with the - <seealso marker="stdlib:gen_server">gen_server(3)</seealso> + <seeerl marker="stdlib:gen_server">gen_server(3)</seeerl> manual page in <c>stdlib</c>, where all interface functions and callback functions are described in detail.</p> @@ -52,7 +52,7 @@ <title>Example</title> <p>An example of a simple server written in plain Erlang is provided in - <seealso marker="des_princ#ch1">Overview</seealso>. + <seeguide marker="des_princ#ch1">Overview</seeguide>. The server can be reimplemented using <c>gen_server</c>, resulting in this callback module:</p> <marker id="ex"></marker> @@ -208,7 +208,7 @@ handle_cast({free, Ch}, Chs) -> function is needed. The <c>gen_server</c> is automatically terminated by its supervisor. Exactly how this is done is defined by a - <seealso marker="sup_princ#shutdown">shutdown strategy</seealso> + <seeguide marker="sup_princ#shutdown">shutdown strategy</seeguide> set in the supervisor.</p> <p>If it is necessary to clean up before termination, the shutdown strategy must be a time-out value and the <c>gen_server</c> must diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml index 0bcd7dc1b2..3f2c6872f4 100644 --- a/system/doc/design_principles/release_handling.xml +++ b/system/doc/design_principles/release_handling.xml @@ -55,23 +55,23 @@ <section> <title>Release Handling Workflow</title> <p><em>Step 1</em>) A release is created as described in - <seealso marker="release_structure">Releases</seealso>.</p> + <seeguide marker="release_structure">Releases</seeguide>.</p> <p><em>Step 2</em>) The release is transferred to and installed at target environment. For information of how to install the first target system, see - <seealso marker="doc/system_principles:create_target">System Principles</seealso>.</p> + <seeguide marker="system/system_principles:create_target">System Principles</seeguide>.</p> <p><em>Step 3</em>) Modifications, for example, error corrections, are made to the code in the development environment.</p> <p><em>Step 4</em>) At some point, it is time to make a new version of release. The relevant <c>.app</c> files are updated and a new <c>.rel</c> file is written.</p> <p><em>Step 5</em>) For each modified application, an - <seealso marker="#appup">application upgrade file</seealso>, + <seeguide marker="#appup">application upgrade file</seeguide>, <c>.appup</c>, is created. In this file, it is described how to upgrade and/or downgrade between the old and new version of the application.</p> <p><em>Step 6</em>) Based on the <c>.appup</c> files, a - <seealso marker="#relup">release upgrade file</seealso> called + <seeguide marker="#relup">release upgrade file</seeguide> called <c>relup</c>, is created. This file describes how to upgrade and/or downgrade between the old and new version of the entire release.</p> <p><em>Step 7</em>) A new release package is made and transferred to @@ -95,7 +95,7 @@ <section> <title>Release Handling Aspects</title> - <p><seealso marker="appup_cookbook">Appup Cookbook</seealso>, + <p><seeguide marker="appup_cookbook">Appup Cookbook</seeguide>, contains examples of <c>.appup</c> files for typical cases of upgrades/downgrades that are normally easy to handle in runtime. However, many aspects can make release handling @@ -235,10 +235,10 @@ function <c>code_change</c>, passing the term <c>Extra</c> and some other information as arguments. See the manual pages for the respective behaviours and - <seealso marker="appup_cookbook#int_state">Appup Cookbook</seealso>.</p> + <seeguide marker="appup_cookbook#int_state">Appup Cookbook</seeguide>.</p> <p><c>update</c> with argument <c>supervisor</c> is used when changing the start specification of a supervisor. See - <seealso marker="appup_cookbook#sup">Appup Cookbook</seealso>.</p> + <seeguide marker="appup_cookbook#sup">Appup Cookbook</seeguide>.</p> <p>When a module is to be updated, the release handler finds which processes that are <em>using</em> the module by traversing the supervision tree of each running application @@ -418,11 +418,11 @@ </list> <p>For information about the syntax and contents of the <c>.appup</c> file, see the <c>appup(4)</c> manual page in SASL.</p> - <p><seealso marker="appup_cookbook">Appup Cookbook</seealso> + <p><seeguide marker="appup_cookbook">Appup Cookbook</seeguide> includes examples of <c>.appup</c> files for typical upgrade/downgrade cases.</p> <p><em>Example:</em> Consider the release <c>ch_rel-1</c> from - <seealso marker="release_structure#ch_rel">Releases</seealso>. + <seeguide marker="release_structure#ch_rel">Releases</seeguide>. Assume you want to add a function <c>available/0</c> to server <c>ch3</c>, which returns the number of available channels (when trying out the example, change in a copy of the original @@ -601,7 +601,7 @@ release_handler:remove_release(Vsn) => ok</code> <p><em>Step 1)</em> Create a target system as described in System Principles of the first version <c>"A"</c> of <c>ch_rel</c> from - <seealso marker="release_structure#ch_rel">Releases</seealso>. + <seeguide marker="release_structure#ch_rel">Releases</seeguide>. This time <c>sys.config</c> must be included in the release package. If no configuration is needed, the file is to contain the empty list:</p> @@ -619,7 +619,7 @@ release_handler:remove_release(Vsn) => ok</code> <p><em>Step 3)</em> In another Erlang shell, generate start scripts and create a release package for the new version <c>"B"</c>. Remember to include (a possible updated) <c>sys.config</c> and the <c>relup</c> file, - see <seealso marker="#relup">Release Upgrade File</seealso>.</p> + see <seeguide marker="#relup">Release Upgrade File</seeguide>.</p> <pre> 1> <input>systools:make_script("ch_rel-2").</input> ok diff --git a/system/doc/design_principles/release_structure.xml b/system/doc/design_principles/release_structure.xml index e8dfcad805..981886282a 100644 --- a/system/doc/design_principles/release_structure.xml +++ b/system/doc/design_principles/release_structure.xml @@ -40,11 +40,11 @@ subset of the Erlang/OTP applications. This is called a <em>release</em>.</p> <p>To do this, create a - <seealso marker="#res_file">release resource file</seealso> that + <seeguide marker="#res_file">release resource file</seeguide> that defines which applications are included in the release.</p> <p>The release resource file is used to generate - <seealso marker="#boot">boot scripts</seealso> and - <seealso marker="#pack">release packages</seealso>. A system + <seeguide marker="#boot">boot scripts</seeguide> and + <seeguide marker="#pack">release packages</seeguide>. A system that is transferred to and installed at another site is called a <em>target system</em>. How to use a release package to create a target system is described in System Principles.</p> @@ -75,7 +75,7 @@ the SASL application.</p> <marker id="ch_rel"></marker> <p><em>Example: </em> A release of <c>ch_app</c> from - <seealso marker="applications#ch_app">Applications</seealso> + <seeguide marker="applications#ch_app">Applications</seeguide> has the following <c>.app</c> file:</p> <code type="none"> {application, ch_app, @@ -169,8 +169,8 @@ ok</pre> <item>The <c>.rel</c> file</item> <item>The object code for all applications, structured according to the - <seealso marker="applications#app_dir">application directory - structure</seealso></item> + <seeguide marker="applications#app_dir">application directory + structure</seeguide></item> <item>The binary boot script renamed to <c>start.boot</c></item> </list> <pre> @@ -210,13 +210,13 @@ releases/ch_rel-1.rel</pre> <p>If a <c>relup</c> file and/or a system configuration file called <c>sys.config</c>, or a <c>sys.config.src</c>, is found, these files are also included in the release package. See - <seealso marker="release_handling#req">Release Handling</seealso>.</p> + <seeguide marker="release_handling#req">Release Handling</seeguide>.</p> <p>Options can be set to make the release package include source code and the ERTS binary as well.</p> <p>For information on how to install the first target system, using a release package, see System Principles. For information on how to install a new release package in an existing system, see - <seealso marker="release_handling">Release Handling</seealso>.</p> + <seeguide marker="release_handling">Release Handling</seeguide>.</p> </section> <section> diff --git a/system/doc/design_principles/spec_proc.xml b/system/doc/design_principles/spec_proc.xml index 729d9b3583..5296b20377 100644 --- a/system/doc/design_principles/spec_proc.xml +++ b/system/doc/design_principles/spec_proc.xml @@ -45,7 +45,7 @@ <p>The <c>sys</c> module has functions for simple debugging of processes implemented using behaviours. The <c>code_lock</c> example from - <seealso marker="statem#Example">gen_statem Behaviour</seealso> + <seeguide marker="statem#Example">gen_statem Behaviour</seeguide> is used to illustrate this:</p> <pre> Erlang/OTP 20 [DEVELOPMENT] [erts-9.0] [source-5ace45e] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:10] [hipe] [kernel-poll:false] @@ -113,9 +113,9 @@ ok <item>Be started in a way that makes the process fit into a supervision tree</item> <item>Support the <c>sys</c> - <seealso marker="#debug">debug facilities</seealso></item> + <seeguide marker="#debug">debug facilities</seeguide></item> <item>Take care of - <seealso marker="#msg">system messages</seealso>.</item> + <seeguide marker="#msg">system messages</seeguide>.</item> </list> <p>System messages are messages with a special meaning, used in the supervision tree. Typical system messages are requests for @@ -126,7 +126,7 @@ ok <section> <title>Example</title> <p>The simple server from - <seealso marker="des_princ#ch1">Overview</seealso>, + <seeguide marker="des_princ#ch1">Overview</seeguide>, implemented using <c>sys</c> and <c>proc_lib</c> so it fits into a supervision tree:</p> <marker id="ex"></marker> @@ -445,8 +445,8 @@ loop(...) -> -callback NameM(ArgM_1, ArgM_2, ..., ArgM_NM) -> ResM.</code> <p><c>NameX</c> are the names of the expected callbacks. <c>ArgX_Y</c> and <c>ResX</c> are types as they are described in - <seealso marker="doc/reference_manual:typespec">Types and - Function Specifications</seealso>. The whole syntax of the <c>-spec</c> + <seeguide marker="system/reference_manual:typespec">Types and + Function Specifications</seeguide>. The whole syntax of the <c>-spec</c> attribute is supported by the <c>-callback</c> attribute.</p> <p>Callback functions that are optional for the user of the behaviour to implement are specified by use of the diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml index 1dcec3310e..8158416fb1 100644 --- a/system/doc/design_principles/statem.xml +++ b/system/doc/design_principles/statem.xml @@ -32,7 +32,7 @@ <marker id="gen_statem Behaviour" /> <p> This section is to be read with the - <seealso marker="stdlib:gen_statem"><c>gen_statem(3)</c></seealso> + <seeerl marker="stdlib:gen_statem"><c>gen_statem(3)</c></seeerl> manual page in STDLIB, where all interface functions and callback functions are described in detail. </p> @@ -107,48 +107,48 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <item> Co-located callback code for each state, for all - <seealso marker="#Event Types and Event Content"> + <seeguide marker="#Event Types and Event Content"> <em>Event Types</em> - </seealso> + </seeguide> (such as <em>call</em>, <em>cast</em> and <em>info</em>) </item> <item> - <seealso marker="#Postponing Events"> + <seeguide marker="#Postponing Events"> Postponing Events - </seealso> + </seeguide> (a substitute for selective receive) </item> <item> - <seealso marker="#Inserted Events"> + <seeguide marker="#Inserted Events"> Inserted Events - </seealso> + </seeguide> (that is, events from the state machine to itself; for purely internal events in particular) </item> <item> - <seealso marker="#State Enter Calls"> + <seeguide marker="#State Enter Calls"> <em>State Enter Calls</em> - </seealso> + </seeguide> (callback on state entry co-located with the rest of each state's callback code) </item> <item> Easy-to-use time-outs - (<seealso marker="#State Time-Outs">State Time-Outs</seealso>, - <seealso marker="#Event Time-Outs">Event Time-Outs</seealso> + (<seeguide marker="#State Time-Outs">State Time-Outs</seeguide>, + <seeguide marker="#Event Time-Outs">Event Time-Outs</seeguide> and - <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso> + <seeguide marker="#Generic Time-Outs">Generic Time-Outs</seeguide> (named time-outs)) </item> </list> <p> If so, or if possibly needed in future versions, then you should consider using <c>gen_statem</c> over - <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>. + <seeerl marker="stdlib:gen_server"><c>gen_server</c></seeerl>. </p> <p> For simple state machines not needing these features - <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso> + <seeerl marker="stdlib:gen_server"><c>gen_server</c></seeerl> works just fine. It also has got smaller call overhead, but we are talking about something like 2 vs 3.3 microseconds @@ -185,10 +185,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <p> The <em>callback module</em> can be changed for a running server using any of the - <seealso marker="#Transition Actions">transition actions</seealso> - <seealso marker="stdlib:gen_statem#type-action"><c>{change_callback_module, NewModule}</c></seealso>, - <seealso marker="stdlib:gen_statem#type-action"><c>{push_callback_module, NewModule}</c></seealso> or - <seealso marker="stdlib:gen_statem#type-action"><c>pop_callback_module</c></seealso>. + <seeguide marker="#Transition Actions">transition actions</seeguide> + <seetype marker="stdlib:gen_statem#action"><c>{change_callback_module, NewModule}</c></seetype>, + <seetype marker="stdlib:gen_statem#action"><c>{push_callback_module, NewModule}</c></seetype> or + <seetype marker="stdlib:gen_statem#action"><c>pop_callback_module</c></seetype>. Note that this is a pretty esotheric thing to do... The origin for this feature is a protocol that after version negotiation branches off into quite different @@ -211,9 +211,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <taglist> <tag> - <seealso marker="stdlib:gen_statem#type-callback_mode"> + <seetype marker="stdlib:gen_statem#callback_mode"> <c>state_functions</c> - </seealso> + </seetype> </tag> <item> <p> @@ -221,9 +221,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> </item> <tag> - <seealso marker="stdlib:gen_statem#type-callback_mode"> + <seetype marker="stdlib:gen_statem#callback_mode"> <c>handle_event_function</c> - </seealso> + </seetype> </tag> <item> <p> @@ -239,27 +239,27 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <p> See the section - <seealso marker="#State Callback"><em>State Callback</em></seealso> + <seeguide marker="#State Callback"><em>State Callback</em></seeguide> that describes the event handling callback function(s). </p> <p> The <em>callback mode</em> is selected by implementing a mandatory callback function - <seealso marker="stdlib:gen_statem#Module:callback_mode/0"> + <seemfa marker="stdlib:gen_statem#Module:callback_mode/0"> <c>Module:callback_mode()</c> - </seealso> + </seemfa> that returns one of the <em>callback modes</em>. </p> <p> The - <seealso marker="stdlib:gen_statem#Module:callback_mode/0"> + <seemfa marker="stdlib:gen_statem#Module:callback_mode/0"> <c>Module:callback_mode()</c> - </seealso> + </seemfa> function may also return a list containing the <em>callback mode</em> and the atom <c>state_enter</c> in which case - <seealso marker="#State Enter Calls"> + <seeguide marker="#State Enter Calls"> <em>state enter calls</em> - </seealso> + </seeguide> are activated for the <em>callback mode</em>. </p> @@ -275,7 +275,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <p> The two - <seealso marker="#Callback Modes"><em>callback modes</em></seealso> + <seeguide marker="#Callback Modes"><em>callback modes</em></seeguide> give different possibilities and restrictions, with one common goal: to handle all possible combinations of events and states. @@ -310,9 +310,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> This mode works equally well when you want to focus on one event at the time or on one state at the time, but function - <seealso marker="stdlib:gen_statem#Module:handle_event/4"> + <seemfa marker="stdlib:gen_statem#Module:handle_event/4"> <c>Module:handle_event/4</c> - </seealso> + </seemfa> quickly grows too large to handle without branching to helper functions. </p> @@ -320,7 +320,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> The mode enables the use of non-atom states, for example, complex states or even hierarchical states. See section - <seealso marker="#Complex State">Complex State</seealso>. + <seeguide marker="#Complex State">Complex State</seeguide>. If, for example, a state diagram is largely alike for the client side and the server side of a protocol, you can have a state <c>{StateName,server}</c> or @@ -347,26 +347,26 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <tag><c>state_functions</c></tag> <item> The event is handled by:<br /> - <seealso marker="stdlib:gen_statem#Module:StateName/3"> + <seemfa marker="stdlib:gen_statem#Module:StateName/3"> <c>Module:StateName(EventType, EventContent, Data)</c> - </seealso> + </seemfa> <p> This form is the one mostly used in the - <seealso marker="#Example">Example</seealso> + <seeguide marker="#Example">Example</seeguide> section. </p> </item> <tag><c>handle_event_function</c></tag> <item> The event is handled by:<br /> - <seealso marker="stdlib:gen_statem#Module:handle_event/4"> + <seemfa marker="stdlib:gen_statem#Module:handle_event/4"> <c>Module:handle_event(EventType, EventContent, State, Data)</c> - </seealso> + </seemfa> <p> See section - <seealso marker="#One State Callback"> + <seeguide marker="#One State Callback"> <em>One State Callback</em> - </seealso> + </seeguide> for an example. </p> </item> @@ -376,20 +376,20 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> The other arguments are the <c>EventType</c> and the event dependent <c>EventContent</c>, both described in section - <seealso marker="#Event Types and Event Content">Event Types and Event Content</seealso>, + <seeguide marker="#Event Types and Event Content">Event Types and Event Content</seeguide>, and the current server <c>Data</c>. </p> <p> <em>State enter calls</em> are also handled by the event handler and have slightly different arguments. See section - <seealso marker="#State Enter Calls">State Enter Calls</seealso>. + <seeguide marker="#State Enter Calls">State Enter Calls</seeguide>. </p> <p> The <em>state callback</em> return values are defined in the description of - <seealso marker="stdlib:gen_statem#Module:StateName/3"> + <seemfa marker="stdlib:gen_statem#Module:StateName/3"> <c>Module:StateName/3</c> - </seealso> + </seemfa> in the <c>gen_statem</c> manual page, but here is a more readable list: </p> @@ -408,9 +408,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <p> See section - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>Transition Actions</em> - </seealso> + </seeguide> for a list of possible <em>transition actions</em>. </p> @@ -418,11 +418,11 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> If <c>NextState =/= State</c> this is a <em>state change</em> so the extra things <c>gen_statem</c> does are: the event queue is restarted from the oldest - <seealso marker="#Postponing Events">postponed event</seealso>, + <seeguide marker="#Postponing Events">postponed event</seeguide>, any current - <seealso marker="#State Time-Outs">state time-out</seealso> + <seeguide marker="#State Time-Outs">state time-out</seeguide> is cancelled, and a - <seealso marker="#State Enter Calls">state enter call</seealso> + <seeguide marker="#State Enter Calls">state enter call</seeguide> is performed, if enabled. </p> </item> @@ -456,9 +456,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <p> Same as the <c>keep_state</c> or <c>keep_state_and_data</c> values, and if - <seealso marker="#State Enter Calls"> + <seeguide marker="#State Enter Calls"> State Enter Calls - </seealso> + </seeguide> are enabled, repeat the <em>state enter call</em> as if this state was entered again. </p> @@ -487,9 +487,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <item> <p> Same as the <c>stop</c> values, but first execute the given - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition actions</em> - </seealso> + </seeguide> that may only be reply actions. </p> </item> @@ -500,25 +500,25 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <title>The First State</title> <p> To decide the first state the - <seealso marker="stdlib:gen_statem#Module:init/1"> + <seemfa marker="stdlib:gen_statem#Module:init/1"> <c>Module:init(Args)</c> - </seealso> + </seemfa> callback function is called before any - <seealso marker="#State Callback"><em>state callback</em></seealso> + <seeguide marker="#State Callback"><em>state callback</em></seeguide> is called. This function behaves like an <em>state callback</em> function, but gets its only argument <c>Args</c> from the <c>gen_statem</c> - <seealso marker="stdlib:gen_statem#start/3"> + <seemfa marker="stdlib:gen_statem#start/3"> <c>start/3,4</c> - </seealso> + </seemfa> or - <seealso marker="stdlib:gen_statem#start_link/3"> + <seemfa marker="stdlib:gen_statem#start_link/3"> <c>start_link/3,4</c> - </seealso> + </seemfa> function, and returns <c>{ok, State, Data}</c> or <c>{ok, State, Data, Actions}</c>. If you use the - <seealso marker="#Postponing Events"><c>postpone</c></seealso> + <seeguide marker="#Postponing Events"><c>postpone</c></seeguide> action from this function, that action is ignored, since there is no event to postpone. </p> @@ -533,7 +533,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <title>Transition Actions</title> <p> In the first section - (<seealso marker="#Event-Driven State Machines">Event-Driven State Machines</seealso>), + (<seeguide marker="#Event-Driven State Machines">Event-Driven State Machines</seeguide>), actions were mentioned as a part of the general state machine model. These general actions are implemented with the code that <em>callback module</em> @@ -546,152 +546,152 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> that a callback function can command the <c>gen_statem</c> engine to do after the callback function return. These are commanded by returning a list of - <seealso marker="stdlib:gen_statem#type-action">actions</seealso> + <seetype marker="stdlib:gen_statem#action">actions</seetype> in the - <seealso marker="stdlib:gen_statem#type-state_callback_result"> + <seetype marker="stdlib:gen_statem#state_callback_result"> return value - </seealso> + </seetype> from the - <seealso marker="stdlib:gen_statem#Module:StateName/3">callback function</seealso>. + <seemfa marker="stdlib:gen_statem#Module:StateName/3">callback function</seemfa>. These are the possible <em>transition actions</em>: </p> <taglist> <tag> - <seealso marker="stdlib:gen_statem#type-postpone"> + <seetype marker="stdlib:gen_statem#postpone"> <c>postpone</c> - </seealso> + </seetype> <br /> <c>{postpone, Boolean}</c> </tag> <item> If set postpone the current event, see section - <seealso marker="#Postponing Events">Postponing Events</seealso>. + <seeguide marker="#Postponing Events">Postponing Events</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-hibernate"> + <seetype marker="stdlib:gen_statem#hibernate"> <c>hibernate</c> - </seealso> + </seetype> <br /> <c>{hibernate, Boolean}</c> </tag> <item> If set hibernate the <c>gen_statem</c>, treated in section - <seealso marker="#Hibernation">Hibernation</seealso>. + <seeguide marker="#Hibernation">Hibernation</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-state_timeout"> + <seetype marker="stdlib:gen_statem#state_timeout"> <c>{state_timeout, Time, EventContent}</c> - </seealso> + </seetype> <br /> <c>{state_timeout, Time, EventContent, Opts}</c><br /> - <seealso marker="stdlib:gen_statem#type-timeout_update_action"> + <seetype marker="stdlib:gen_statem#timeout_update_action"> <c>{state_timeout, update, EventContent}</c> - </seealso> + </seetype> <br /> - <seealso marker="stdlib:gen_statem#type-timeout_cancel_action"> + <seetype marker="stdlib:gen_statem#timeout_cancel_action"> <c>{state_timeout, cancel}</c> - </seealso> + </seetype> </tag> <item> Start, update or cancel a state time-out, read more in sections - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#State Time-Outs">State Time-Outs</seealso>. + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#State Time-Outs">State Time-Outs</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-generic_timeout"> + <seetype marker="stdlib:gen_statem#generic_timeout"> <c>{{timeout, Name}, Time, EventContent}</c> - </seealso> + </seetype> <br /> <c>{{timeout, Name}, Time, EventContent, Opts}</c><br /> - <seealso marker="stdlib:gen_statem#type-timeout_update_action"> + <seetype marker="stdlib:gen_statem#timeout_update_action"> <c>{{timeout, Name}, update, EventContent}</c> - </seealso> + </seetype> <br /> - <seealso marker="stdlib:gen_statem#type-timeout_cancel_action"> + <seetype marker="stdlib:gen_statem#timeout_cancel_action"> <c>{{timeout, Name}, cancel}</c> - </seealso> + </seetype> </tag> <item> Start, update or cancel a generic time-out, read more in sections - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>. + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#Generic Time-Outs">Generic Time-Outs</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-event_timeout"> + <seetype marker="stdlib:gen_statem#event_timeout"> <c>{timeout, Time, EventContent}</c> - </seealso> + </seetype> <br /> <c>{timeout, Time, EventContent, Opts}</c><br /> <c>Time</c> </tag> <item> Start an event time-out, see more in sections - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>. + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#Event Time-Outs">Event Time-Outs</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-reply_action"> + <seetype marker="stdlib:gen_statem#reply_action"> <c>{reply, From, Reply}</c> - </seealso> + </seetype> </tag> <item> Reply to a caller, mentioned at the end of section - <seealso marker="#All State Events">All State Events</seealso>. + <seeguide marker="#All State Events">All State Events</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-action"> + <seetype marker="stdlib:gen_statem#action"> <c>{next_event, EventType, EventContent}</c> - </seealso> + </seetype> </tag> <item> Generate the next event to handle, see section - <seealso marker="#Inserted Events">Inserted Events</seealso>. + <seeguide marker="#Inserted Events">Inserted Events</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-action"> + <seetype marker="stdlib:gen_statem#action"> <c>{change_callback_module, NewModule}</c> - </seealso> + </seetype> </tag> <item> Change the - <seealso marker="#Callback Module"> + <seeguide marker="#Callback Module"> <em>callback module</em> - </seealso> + </seeguide> for the running server. This can be done during any <em>state transition</em>, whether it is a <em>state change</em> or not, but it can <i>not</i> be done from a - <seealso marker="#State Enter Calls"><em>state enter call</em></seealso>. + <seeguide marker="#State Enter Calls"><em>state enter call</em></seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-action"> + <seetype marker="stdlib:gen_statem#action"> <c>{push_callback_module, NewModule}</c> - </seealso> + </seetype> </tag> <item> Push the current <em>callback module</em> to the top of an internal stack of callback modules and set the new - <seealso marker="#Callback Module"> + <seeguide marker="#Callback Module"> <em>callback module</em> - </seealso> + </seeguide> for the running server. Otherwise like <c>{change_callback_module, NewModule}</c> above. </item> <tag> - <seealso marker="stdlib:gen_statem#type-action"> + <seetype marker="stdlib:gen_statem#action"> <c>pop_callback_module</c> - </seealso> + </seetype> </tag> <item> Pop the top module from the internal stack of callback modules and set it to be the new - <seealso marker="#Callback Module"> + <seeguide marker="#Callback Module"> <em>callback module</em> - </seealso> + </seeguide> for the running server. If the stack is empty the server fails. Otherwise like @@ -702,7 +702,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <p> For details, see the <c>gen_statem(3)</c> manual page for type - <seealso marker="stdlib:gen_statem#type-action"><c>action()</c></seealso>. + <seetype marker="stdlib:gen_statem#action"><c>action()</c></seetype>. You can, for example, reply to many callers, generate multiple next events, and set a time-out to use absolute instead of relative time @@ -712,22 +712,22 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> Among these <em>transition actions</em> only to reply to a caller is an immediate action. The others are collected and handled later during the <em>state transition</em>. - <seealso marker="#Inserted Events">Inserted Events</seealso> + <seeguide marker="#Inserted Events">Inserted Events</seeguide> are stored and inserted all together, and the rest set transition options where the last of a specific type override the previous. See the description of a <em>state transition</em> in the <c>gen_statem(3)</c> manual page for type - <seealso marker="stdlib:gen_statem#type-transition_option"><c>transition_option()</c></seealso>. + <seetype marker="stdlib:gen_statem#transition_option"><c>transition_option()</c></seetype>. </p> <p> The different - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#Inserted Events"><c>next_event</c></seealso> + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#Inserted Events"><c>next_event</c></seeguide> actions generate new events with corresponding - <seealso marker="#Event Types and Event Content"> + <seeguide marker="#Event Types and Event Content"> Event Types and Event Content - </seealso>. + </seeguide>. </p> </section> @@ -738,7 +738,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> <title>Event Types and Event Content</title> <p> Events are categorized in different - <seealso marker="stdlib:gen_statem#type-event_type"><em>event types</em></seealso>. + <seetype marker="stdlib:gen_statem#event_type"><em>event types</em></seetype>. Events of all types are for a given state handled in the same callback function, and that function gets <c>EventType</c> and <c>EventContent</c> as arguments. @@ -751,40 +751,40 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> </p> <taglist> <tag> - <seealso marker="stdlib:gen_statem#type-external_event_type"> + <seetype marker="stdlib:gen_statem#external_event_type"> <c>cast</c> - </seealso> + </seetype> </tag> <item> Generated by - <seealso marker="stdlib:gen_statem#cast/2"> + <seemfa marker="stdlib:gen_statem#cast/2"> <c>gen_statem:cast(ServerRef, Msg)</c> - </seealso> + </seemfa> where <c>Msg</c> becomes the <c>EventContent</c>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-external_event_type"> + <seetype marker="stdlib:gen_statem#external_event_type"> <c>{call,From}</c> - </seealso> + </seetype> </tag> <item> Generated by - <seealso marker="stdlib:gen_statem#call/2"> + <seemfa marker="stdlib:gen_statem#call/2"> <c>gen_statem:call(ServerRef, Request)</c> - </seealso> + </seemfa> where <c>Request</c> becomes the <c>EventContent</c>. <c>From</c> is the reply address to use when replying either through the <em>transition action</em> <c>{reply,From,Reply}</c> or by calling - <seealso marker="stdlib:gen_statem#reply/1"> + <seemfa marker="stdlib:gen_statem#reply/1"> <c>gen_statem:reply(From, Reply)</c> - </seealso> + </seemfa> from the <em>callback module</em>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-external_event_type"> + <seetype marker="stdlib:gen_statem#external_event_type"> <c>info</c> - </seealso> + </seetype> </tag> <item> Generated by any regular process message sent to @@ -792,56 +792,56 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> The process message becomes the <c>EventContent</c>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-timeout_event_type"> + <seetype marker="stdlib:gen_statem#timeout_event_type"> <c>state_timeout</c> - </seealso> + </seetype> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-timeout_action"> + <seetype marker="stdlib:gen_statem#timeout_action"> <c>{state_timeout,Time,EventContent}</c> - </seealso> + </seetype> state timer timing out. Read more in sections - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#State Time-Outs">State Time-Outs</seealso>. + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#State Time-Outs">State Time-Outs</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-timeout_event_type"> + <seetype marker="stdlib:gen_statem#timeout_event_type"> <c>{timeout,Name}</c> - </seealso> + </seetype> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-timeout_action"> + <seetype marker="stdlib:gen_statem#timeout_action"> <c>{{timeout,Name},Time,EventContent}</c> - </seealso> + </seetype> generic timer timing out. Read more in sections - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>. + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#Generic Time-Outs">Generic Time-Outs</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-timeout_event_type"> + <seetype marker="stdlib:gen_statem#timeout_event_type"> <c>timeout</c> - </seealso> + </seetype> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-timeout_action"> + <seetype marker="stdlib:gen_statem#timeout_action"> <c>{timeout,Time,EventContent}</c> - </seealso> + </seetype> (or its short form <c>Time</c>) event timer timing out. Read more in sections - <seealso marker="#Time-Outs">Time-Outs</seealso> and - <seealso marker="#Event Time-Outs">Event Time-Outs</seealso>. + <seeguide marker="#Time-Outs">Time-Outs</seeguide> and + <seeguide marker="#Event Time-Outs">Event Time-Outs</seeguide>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-event_type"> + <seetype marker="stdlib:gen_statem#event_type"> <c>internal</c> - </seealso> + </seetype> </tag> <item> Generated by <em>transition action</em> - <seealso marker="stdlib:gen_statem#type-action"><c>{next_event,internal,EventContent}</c></seealso>. + <seetype marker="stdlib:gen_statem#action"><c>{next_event,internal,EventContent}</c></seetype>. All <em>event types</em> above can also be generated using the <c>next_event</c> action: <c>{next_event,EventType,EventContent}</c>. @@ -858,9 +858,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre> The <c>gen_statem</c> behaviour can if this is enabled, regardless of <em>callback mode</em>, automatically - <seealso marker="stdlib:gen_statem#type-state_enter"> + <seetype marker="stdlib:gen_statem#state_enter"> call the state callback - </seealso> + </seetype> with special arguments whenever the state changes so you can write state enter actions near the rest of the <em>state transition</em> rules. @@ -876,13 +876,13 @@ StateName(EventType, EventContent, Data) -> <p> Since the <em>state enter call</em> is not an event there are restrictions on the allowed return value and - <seealso marker="#Transition Actions">State Transition Actions</seealso>. + <seeguide marker="#Transition Actions">State Transition Actions</seeguide>. You may not change the state, - <seealso marker="#Postponing Events">postpone</seealso> + <seeguide marker="#Postponing Events">postpone</seeguide> this non-event, - <seealso marker="#Inserted Events">insert any events</seealso>, + <seeguide marker="#Inserted Events">insert any events</seeguide>, or change the - <seealso marker="#Callback Module"><em>callback module</em></seealso>. + <seeguide marker="#Callback Module"><em>callback module</em></seeguide>. </p> <p> The first state that is entered @@ -893,7 +893,7 @@ StateName(EventType, EventContent, Data) -> You may repeat the <em>state enter call</em> using the <c>{repeat_state,...}</c> return value from the - <seealso marker="#State Callback">state callback</seealso>. + <seeguide marker="#State Callback">state callback</seeguide>. In this case <c>OldState</c> will also be equal to the current state. </p> <p> @@ -901,9 +901,9 @@ StateName(EventType, EventContent, Data) -> this can be a very useful feature, but it forces you to handle the <em>state enter calls</em> in all states. See also the - <seealso marker="#State Enter Actions"> + <seeguide marker="#State Enter Actions"> State Enter Actions - </seealso> + </seeguide> section. </p> </section> @@ -915,50 +915,50 @@ StateName(EventType, EventContent, Data) -> <title>Time-Outs</title> <p> Time-outs in <c>gen_statem</c> are started from a - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> during a state transition that is when exiting from the - <seealso marker="#State Callback"><em>state callback</em></seealso>. + <seeguide marker="#State Callback"><em>state callback</em></seeguide>. </p> <p> There are 3 types of time-outs in <c>gen_statem</c>: </p> <taglist> <tag> - <seealso marker="stdlib:gen_statem#type-state_timeout"> + <seetype marker="stdlib:gen_statem#state_timeout"> <c>state_timeout</c> - </seealso> + </seetype> </tag> <item> There is one - <seealso marker="#State Time-Outs">State Time-Out</seealso> + <seeguide marker="#State Time-Outs">State Time-Out</seeguide> that is automatically cancelled by a <em>state change</em>. </item> <tag> - <seealso marker="stdlib:gen_statem#type-generic_timeout"> + <seetype marker="stdlib:gen_statem#generic_timeout"> <c>{timeout, Name}</c> - </seealso> + </seetype> </tag> <item> There are any number of - <seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso> + <seeguide marker="#Generic Time-Outs">Generic Time-Outs</seeguide> differing by their <c>Name</c>. They have no automatic cancelling. </item> <tag> - <seealso marker="stdlib:gen_statem#type-event_timeout"> + <seetype marker="stdlib:gen_statem#event_timeout"> <c>timeout</c> - </seealso> + </seetype> </tag> <item> There is one - <seealso marker="#Event Time-Outs">Event Time-Out</seealso> + <seeguide marker="#Event Time-Outs">Event Time-Out</seeguide> that is automatically cancelled by any event. Note that - <seealso marker="#Postponing Events">postponed </seealso> + <seeguide marker="#Postponing Events">postponed </seeguide> and - <seealso marker="#Inserted Events">inserted</seealso> + <seeguide marker="#Inserted Events">inserted</seeguide> events cancel this time-out just as external events. </item> </taglist> @@ -969,13 +969,13 @@ StateName(EventType, EventContent, Data) -> </p> <p> All time-outs has got an <c>EventContent</c> that is part of the - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> that starts the time-out. Different <c>EventContent</c>s does not create different time-outs. The <c>EventContent</c> is delivered to the - <seealso marker="#State Callback"><em>state callback</em></seealso> + <seeguide marker="#State Callback"><em>state callback</em></seeguide> when the time-out expires. </p> <section> @@ -990,13 +990,13 @@ StateName(EventType, EventContent, Data) -> </p> <p> A more explicit way to cancel a timer is to use a - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> on the form - <seealso marker="stdlib:gen_statem#type-timeout_cancel_action"> + <seetype marker="stdlib:gen_statem#timeout_cancel_action"> <c>{TimeoutType, cancel}</c> - </seealso> + </seetype> which is a feature introduced in OTP 22.1. </p> </section> @@ -1006,20 +1006,20 @@ StateName(EventType, EventContent, Data) -> <p> While a time-out is running, its <c>EventContent</c> can be updated using a - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> on the form - <seealso marker="stdlib:gen_statem#type-timeout_update_action"> + <seetype marker="stdlib:gen_statem#timeout_update_action"> <c>{TimeoutType, update, NewEventContent}</c> - </seealso> + </seetype> which is a feature introduced in OTP 22.1. </p> <p> If this feature is used while no such <c>TimeoutType</c> is running then a time-out event is immediately delivered as when starting a - <seealso marker="#Time-Out Zero">Time-Out Zero</seealso>. + <seeguide marker="#Time-Out Zero">Time-Out Zero</seeguide>. </p> </section> <section> @@ -1032,9 +1032,9 @@ StateName(EventType, EventContent, Data) -> already enqueued, and before any not yet received external events. Note that some time-outs are automatically cancelled so if you for example combine - <seealso marker="#Postponing Events">postponing</seealso> + <seeguide marker="#Postponing Events">postponing</seeguide> an event in a <em>state change</em> with starting an - <seealso marker="#Event Time-Outs">event time-out</seealso> + <seeguide marker="#Event Time-Outs">event time-out</seeguide> with time <c>0</c> there will be no time-out event inserted since the event time-out is cancelled by the postponed event that is delivered due to the state change. @@ -1145,7 +1145,7 @@ start_link(Code) -> ]]></code> <p> <c>start_link</c> calls function - <seealso marker="stdlib:gen_statem#start_link/4"><c>gen_statem:start_link/4</c></seealso>, + <seemfa marker="stdlib:gen_statem#start_link/4"><c>gen_statem:start_link/4</c></seemfa>, which spawns and links to a new process, a <c>gen_statem</c>. </p> <list type="bulleted"> @@ -1160,7 +1160,7 @@ start_link(Code) -> Instead its pid must be used. The name can also be specified as <c>{global,Name}</c>, then the <c>gen_statem</c> is registered using - <seealso marker="kernel:global#register_name/2"><c>global:register_name/2</c></seealso> + <seemfa marker="kernel:global#register_name/2"><c>global:register_name/2</c></seemfa> in Kernel. </p> </item> @@ -1190,7 +1190,7 @@ start_link(Code) -> <p> The fourth argument, <c>[]</c>, is a list of options. For the available options, see - <seealso marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link/3</c></seealso>. + <seemfa marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link/3</c></seemfa>. </p> </item> </list> @@ -1201,7 +1201,7 @@ start_link(Code) -> where <c>State</c> is the initial state of the <c>gen_statem</c>, in this case <c>locked</c>; assuming that the door is locked to begin with. <c>Data</c> is the internal server data of the <c>gen_statem</c>. - Here the server data is a <seealso marker="stdlib:maps">map</seealso> + Here the server data is a <seeerl marker="stdlib:maps">map</seeerl> with key <c>code</c> that stores the correct button sequence, key <c>length</c> store its length, and key <c>buttons</c> that stores the collected buttons @@ -1215,28 +1215,28 @@ init(Code) -> {ok, locked, Data}. ]]></code> <p>Function - <seealso marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link</c></seealso> + <seemfa marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link</c></seemfa> is synchronous. It does not return until the <c>gen_statem</c> is initialized and is ready to receive events. </p> <p> Function - <seealso marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link</c></seealso> + <seemfa marker="stdlib:gen_statem#start_link/3"><c>gen_statem:start_link</c></seemfa> must be used if the <c>gen_statem</c> is part of a supervision tree, that is, started by a supervisor. Another function, - <seealso marker="stdlib:gen_statem#start/3"><c>gen_statem:start</c></seealso> + <seemfa marker="stdlib:gen_statem#start/3"><c>gen_statem:start</c></seemfa> can be used to start a standalone <c>gen_statem</c>, that is, a <c>gen_statem</c> that is not part of a supervision tree. </p> <p> Function - <seealso marker="stdlib:gen_statem#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso> + <seemfa marker="stdlib:gen_statem#Module:callback_mode/0"><c>Module:callback_mode/0</c></seemfa> selects the - <seealso marker="#Callback Modes"><c>CallbackMode</c></seealso> + <seeguide marker="#Callback Modes"><c>CallbackMode</c></seeguide> for the <em>callback module</em>, in this case - <seealso marker="stdlib:gen_statem#type-callback_mode"><c>state_functions</c></seealso>. + <seetype marker="stdlib:gen_statem#callback_mode"><c>state_functions</c></seetype>. That is, each state has got its own handler function: </p> <code type="erl"><![CDATA[ @@ -1253,7 +1253,7 @@ callback_mode() -> <title>Handling Events</title> <p>The function notifying the code lock about a button event is implemented using - <seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast/2</c></seealso>: + <seemfa marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast/2</c></seemfa>: </p> <code type="erl"><![CDATA[ button(Button) -> @@ -1356,7 +1356,7 @@ open(state_timeout, lock, Data) -> <p> You can restart, cancel or update a state time-out. See section - <seealso marker="#Time-Outs">Time-Outs</seealso> + <seeguide marker="#Time-Outs">Time-Outs</seeguide> for details. </p> </section> @@ -1430,7 +1430,7 @@ open(...) -> ... ; <p> This example uses - <seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call/2</c></seealso>, + <seemfa marker="stdlib:gen_statem#call/2"><c>gen_statem:call/2</c></seemfa>, which waits for a reply from the server. The reply is sent with a <c>{reply,From,Reply}</c> tuple in an action list in the <c>{keep_state, ...}</c> tuple @@ -1455,12 +1455,12 @@ open(...) -> ... ; <title>One State Callback</title> <p> If - <seealso marker="#Callback Modes"> + <seeguide marker="#Callback Modes"> <em>callback mode</em> - </seealso> + </seeguide> <c>handle_event_function</c> is used, all events are handled in - <seealso marker="stdlib:gen_statem#Module:handle_event/4"><c>Module:handle_event/4</c></seealso> + <seemfa marker="stdlib:gen_statem#Module:handle_event/4"><c>Module:handle_event/4</c></seemfa> and we can (but do not have to) use an event-centered approach where we first branch depending on event and then depending on state: @@ -1521,7 +1521,7 @@ handle_event( no stop function is needed. The <c>gen_statem</c> is automatically terminated by its supervisor. Exactly how this is done is defined by a - <seealso marker="sup_princ#shutdown">shutdown strategy</seealso> + <seeguide marker="sup_princ#shutdown">shutdown strategy</seeguide> set in the supervisor. </p> <p> @@ -1529,7 +1529,7 @@ handle_event( strategy must be a time-out value and the <c>gen_statem</c> must in function <c>init/1</c> set itself to trap exit signals by calling - <seealso marker="erts:erlang#process_flag/2"><c>process_flag(trap_exit, true)</c></seealso>: + <seemfa marker="erts:erlang#process_flag/2"><c>process_flag(trap_exit, true)</c></seemfa>: </p> <code type="erl"><![CDATA[ init(Args) -> @@ -1559,7 +1559,7 @@ terminate(_Reason, State, _Data) -> <p> If the <c>gen_statem</c> is not part of a supervision tree, it can be stopped using - <seealso marker="stdlib:gen_statem#stop/1"><c>gen_statem:stop</c></seealso>, + <seemfa marker="stdlib:gen_statem#stop/1"><c>gen_statem:stop</c></seemfa>, preferably through an API function: </p> <code type="erl"><![CDATA[ @@ -1585,16 +1585,16 @@ stop() -> <title>Event Time-Outs</title> <p> A time-out feature inherited from <c>gen_statem</c>'s predecessor - <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso>, + <seeerl marker="stdlib:gen_fsm"><c>gen_fsm</c></seeerl>, is an event time-out, that is, if an event arrives the timer is cancelled. You get either an event or a time-out, but not both. </p> <p> It is ordered by the - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> <c>{timeout,Time,EventContent}</c>, or just an integer <c>Time</c>, even without the enclosing actions list (the latter is a form inherited from <c>gen_fsm</c>. @@ -1634,7 +1634,7 @@ locked( <p> Note that an event time-out does not work well when you have for example a status call as in section - <seealso marker="#All State Events">All State Events</seealso>, + <seeguide marker="#All State Events">All State Events</seeguide>, or handle unknown events, since all kinds of events will cancel the event time-out. </p> @@ -1656,9 +1656,9 @@ locked( to the time-out in another, maybe cancel the time-out without changing states, or perhaps run multiple time-outs in parallel. All this can be accomplished with - <seealso marker="stdlib:gen_statem#type-generic_timeout">generic time-outs</seealso>. + <seetype marker="stdlib:gen_statem#generic_timeout">generic time-outs</seetype>. They may look a little bit like - <seealso marker="stdlib:gen_statem#type-event_timeout">event time-outs</seealso> + <seetype marker="stdlib:gen_statem#event_timeout">event time-outs</seetype> but contain a name to allow for any number of them simultaneously and they are not automatically cancelled. </p> @@ -1689,7 +1689,7 @@ open(cast, {button,_}, Data) -> ]]></code> <p> Specific generic time-outs can just as - <seealso marker="#State Time-Outs">state time-outs</seealso> + <seeguide marker="#State Time-Outs">state time-outs</seeguide> be restarted or cancelled by setting it to a new time or <c>infinity</c>. </p> @@ -1706,7 +1706,7 @@ open(cast, {button,_}, Data) -> <p> You can restart, cancel or update a generic time-out. See section - <seealso marker="#Time-Outs">Time-Outs</seealso> + <seeguide marker="#Time-Outs">Time-Outs</seeguide> for details. </p> </section> @@ -1719,12 +1719,12 @@ open(cast, {button,_}, Data) -> <p> The most versatile way to handle time-outs is to use Erlang Timers; see - <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/3,4</c></seealso>. + <seemfa marker="erts:erlang#start_timer/4"><c>erlang:start_timer/3,4</c></seemfa>. Most time-out tasks can be performed with the time-out features in <c>gen_statem</c>, but an example of one that cannot is if you should need the return value from - <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>, that is; the remaining time of the timer. + <seemfa marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seemfa>, that is; the remaining time of the timer. </p> <p> Here is how to accomplish the state time-out @@ -1761,7 +1761,7 @@ open(cast, {button,_}, Data) -> </p> <p> If you need to cancel a timer because of some other event, you can use - <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>. + <seemfa marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seemfa>. Note that no time-out message will arrive after this (because the timer has been explicitly canceled), unless you have already postponed one earlier (see the next section), so ensure that you do not accidentally postpone such messages. @@ -1769,7 +1769,7 @@ open(cast, {button,_}, Data) -> that is cancelling the timer, so you may have to read out such a message from the process mailbox, depending on the return value from - <seealso marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seealso>. + <seemfa marker="erts:erlang#cancel_timer/2"><c>erlang:cancel_timer(Tref)</c></seemfa>. </p> <p> Another way to handle a late time-out can be to not cancel it, @@ -1791,9 +1791,9 @@ open(cast, {button,_}, Data) -> </p> <p> Postponing is ordered by the - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> <c>postpone</c>. </p> <p> @@ -1816,10 +1816,10 @@ open(cast, {button,_}, Data) -> for example by having two more or less identical states to keep a boolean value, or by using a complex state (see section - <seealso marker="#Complex State">Complex State</seealso>) + <seeguide marker="#Complex State">Complex State</seeguide>) with - <seealso marker="#Callback Modes"><em>callback mode</em></seealso> - <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso>. + <seeguide marker="#Callback Modes"><em>callback mode</em></seeguide> + <seetype marker="stdlib:gen_statem#callback_mode"><c>handle_event_function</c></seetype>. If a change in the value changes the set of events that is handled, then the value should be kept in the State. Otherwise no postponed events will be retried @@ -1916,16 +1916,16 @@ do_unlock() -> behaviour (or from any <c>gen_*</c> behaviour), as the receive statement is within the <c>gen_*</c> engine itself. It must be there because all - <seealso marker="stdlib:sys"><c>sys</c></seealso> + <seeerl marker="stdlib:sys"><c>sys</c></seeerl> compatible behaviours must respond to system messages and therefore do that in their engine receive loop, passing non-system messages to the <em>callback module</em>. </p> <p> The - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> + </seeguide> <c>postpone</c> is designed to model selective receives. A selective receive implicitly postpones any not received events, but the <c>postpone</c> @@ -1951,13 +1951,13 @@ do_unlock() -> (described in the next section), especially if just one or a few states has got state enter actions, this is a perfect use case for the built in - <seealso marker="#State Enter Calls"><em>state enter calls</em></seealso>. + <seeguide marker="#State Enter Calls"><em>state enter calls</em></seeguide>. </p> <p> You return a list containing <c>state_enter</c> from your - <seealso marker="stdlib:gen_statem#Module:callback_mode/0"> + <seemfa marker="stdlib:gen_statem#Module:callback_mode/0"> <c>callback_mode/0</c> - </seealso> + </seemfa> function and the <c>gen_statem</c> engine will call your <em>state callback</em> once with an event <c>(enter, OldState, ...)</c> @@ -2000,9 +2000,9 @@ open(state_timeout, lock, Data) -> or <c>repeat_state_and_data</c> that otherwise behaves exactly like their <c>keep_state</c> siblings. See the type - <seealso marker="stdlib:gen_statem#type-state_callback_result"> + <seetype marker="stdlib:gen_statem#state_callback_result"> <c>state_callback_result()</c> - </seealso> + </seetype> in the reference manual. </p> </section> @@ -2016,14 +2016,14 @@ open(state_timeout, lock, Data) -> It can sometimes be beneficial to be able to generate events to your own state machine. This can be done with the - <seealso marker="#Transition Actions"> + <seeguide marker="#Transition Actions"> <em>transition action</em> - </seealso> - <seealso marker="stdlib:gen_statem#type-action"><c>{next_event,EventType,EventContent}</c></seealso>. + </seeguide> + <seetype marker="stdlib:gen_statem#action"><c>{next_event,EventType,EventContent}</c></seetype>. </p> <p> You can generate events of any existing - <seealso marker="stdlib:gen_statem#type-action">type</seealso>, + <seetype marker="stdlib:gen_statem#action">type</seetype>, but the <c>internal</c> type can only be generated through action <c>next_event</c>. Hence, it cannot come from an external source, so you can be certain that an <c>internal</c> event is an event @@ -2047,9 +2047,9 @@ open(state_timeout, lock, Data) -> </p> <p> A variant of this is to use a - <seealso marker="#Complex State">complex state</seealso> + <seeguide marker="#Complex State">complex state</seeguide> with - <seealso marker="#One State Callback"><em>one state callback</em></seealso>. + <seeguide marker="#One State Callback"><em>one state callback</em></seeguide>. The state is then modeled with for example a tuple <c>{MainFSMState,SubFSMState}</c>. </p> @@ -2333,9 +2333,9 @@ handle_event({call,From}, code_length, _State, #{length := Length}) -> <p> To avoid this, you can format the internal state that gets in the error log and gets returned from - <seealso marker="stdlib:sys#get_status/1"><c>sys:get_status/1,2</c></seealso> + <seemfa marker="stdlib:sys#get_status/1"><c>sys:get_status/1,2</c></seemfa> by implementing function - <seealso marker="stdlib:gen_statem#Module:format_status/2"><c>Module:format_status/2</c></seealso>, + <seemfa marker="stdlib:gen_statem#Module:format_status/2"><c>Module:format_status/2</c></seemfa>, for example like this: </p> <code type="erl"><![CDATA[ @@ -2360,7 +2360,7 @@ format_status(Opt, [_PDict,State,Data]) -> ]]></code> <p> It is not mandatory to implement a - <seealso marker="stdlib:gen_statem#Module:format_status/2"><c>Module:format_status/2</c></seealso> + <seemfa marker="stdlib:gen_statem#Module:format_status/2"><c>Module:format_status/2</c></seemfa> function. If you do not, a default implementation is used that does the same as this example function without filtering the <c>Data</c> term, that is, <c>StateData = {State,Data}</c>, @@ -2375,15 +2375,15 @@ format_status(Opt, [_PDict,State,Data]) -> <title>Complex State</title> <p> The <em>callback mode</em> - <seealso marker="stdlib:gen_statem#type-callback_mode"><c>handle_event_function</c></seealso> + <seetype marker="stdlib:gen_statem#callback_mode"><c>handle_event_function</c></seetype> enables using a non-atom state as described in section - <seealso marker="#Callback Modes">Callback Modes</seealso>, + <seeguide marker="#Callback Modes">Callback Modes</seeguide>, for example, a complex state term like a tuple. </p> <p> One reason to use this is when you have a state item that when changed should cancel the - <seealso marker="#State Time-Outs">state time-out</seealso>, + <seeguide marker="#State Time-Outs">state time-out</seeguide>, or one that affects the event handling in combination with postponing events. We will go for the latter and complicate the previous example @@ -2529,12 +2529,12 @@ terminate(_Reason, State, _Data) -> and the amount of heap memory all these servers need is a problem, then the memory footprint of a server can be mimimized by hibernating it through - <seealso marker="stdlib:proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>. + <seemfa marker="stdlib:proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seemfa>. </p> <note> <p> It is rather costly to hibernate a process; see - <seealso marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seealso>. + <seemfa marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seemfa>. It is not something you want to do after every event. </p> </note> @@ -2557,7 +2557,7 @@ handle_event(enter, _OldState, {open,_}, _Data) -> ]]></code> <p> The atom - <seealso marker="stdlib:gen_statem#type-hibernate"><c>hibernate</c></seealso> + <seetype marker="stdlib:gen_statem#hibernate"><c>hibernate</c></seetype> in the action list on the last line when entering the <c>{open,_}</c> state is the only change. If any event arrives in the <c>{open,_},</c> state, we @@ -2573,21 +2573,21 @@ handle_event(enter, _OldState, {open,_}, _Data) -> </p> <p> Another not uncommon scenario is to use the - <seealso marker="#Event Time-Outs">event time-out</seealso> + <seeguide marker="#Event Time-Outs">event time-out</seeguide> to trigger hibernation after a certain time of inactivity. There is also a server start option - <seealso marker="stdlib:gen_statem#type-enter_loop_opt"> + <seetype marker="stdlib:gen_statem#enter_loop_opt"> <c>{hibernate_after, Timeout}</c> - </seealso> + </seetype> for - <seealso marker="stdlib:gen_statem#start/3"><c>start/3,4</c></seealso>, - <seealso marker="stdlib:gen_statem#start_link/3"> + <seemfa marker="stdlib:gen_statem#start/3"><c>start/3,4</c></seemfa>, + <seemfa marker="stdlib:gen_statem#start_link/3"> <c>start_link/3,4</c> - </seealso> + </seemfa> or - <seealso marker="stdlib:gen_statem#enter_loop/4"> + <seemfa marker="stdlib:gen_statem#enter_loop/4"> <c>enter_loop/4,5,6</c> - </seealso> + </seemfa> that may be used to automatically hibernate the server. </p> <p> diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml index 321fa41e8d..7fb8ba39ea 100644 --- a/system/doc/design_principles/sup_princ.xml +++ b/system/doc/design_principles/sup_princ.xml @@ -30,7 +30,7 @@ <file>sup_princ.xml</file> </header> <p>This section should be read with the - <seealso marker="stdlib:supervisor">supervisor(3)</seealso> manual page + <seeerl marker="stdlib:supervisor">supervisor(3)</seeerl> manual page in STDLIB, where all details about the supervisor behaviour is given.</p> @@ -41,7 +41,7 @@ that it is to keep its child processes alive by restarting them when necessary.</p> <p>Which child processes to start and monitor is specified by a - list of <seealso marker="#spec">child specifications</seealso>. + list of <seeguide marker="#spec">child specifications</seeguide>. The child processes are started in the order specified by this list, and terminated in the reversed order.</p> </section> @@ -49,7 +49,7 @@ <section> <title>Example</title> <p>The callback module for a supervisor starting the server from - <seealso marker="gen_server_concepts#ex">gen_server Behaviour</seealso> + <seeguide marker="gen_server_concepts#ex">gen_server Behaviour</seeguide> can look as follows:</p> <marker id="ex"></marker> <code type="none"> @@ -73,10 +73,10 @@ init(_Args) -> {ok, {SupFlags, ChildSpecs}}.</code> <p>The <c>SupFlags</c> variable in the return value from <c>init/1</c> represents - the <seealso marker="#flags">supervisor flags</seealso>.</p> + the <seeguide marker="#flags">supervisor flags</seeguide>.</p> <p>The <c>ChildSpecs</c> variable in the return value - from <c>init/1</c> is a list of <seealso marker="#spec">child - specifications</seealso>.</p> + from <c>init/1</c> is a list of <seeguide marker="#spec">child + specifications</seeguide>.</p> </section> <section> @@ -94,13 +94,13 @@ sup_flags() = #{strategy => strategy(), % optional <list type="bulleted"> <item> <p><c>strategy</c> specifies - the <seealso marker="#strategy">restart - strategy</seealso>.</p> + the <seeguide marker="#strategy">restart + strategy</seeguide>.</p> </item> <item> <p><c>intensity</c> and <c>period</c> specify - the <seealso marker="#max_intensity">maximum restart - intensity</seealso>.</p> + the <seeguide marker="#max_intensity">maximum restart + intensity</seeguide>.</p> </item> </list> </section> @@ -146,8 +146,8 @@ SupFlags = #{strategy => Strategy, ...}</code> <section> <title>simple_one_for_one</title> - <p>See <seealso marker="#simple">simple-one-for-one - supervisors</seealso>.</p> + <p>See <seeguide marker="#simple">simple-one-for-one + supervisors</seeguide>.</p> </section> </section> @@ -350,7 +350,7 @@ child_spec() = #{id => child_id(), % mandatory the value shall be <c>dynamic</c>.</p> <p>This information is used by the release handler during upgrades and downgrades, see - <seealso marker="release_handling">Release Handling</seealso>.</p> + <seeguide marker="release_handling">Release Handling</seeguide>.</p> <p>The <c>modules</c> key is optional. If it is not given, it defaults to <c>[M]</c>, where <c>M</c> comes from the child's start <c>{M,F,A}</c>.</p> @@ -372,7 +372,7 @@ child_spec() = #{id => child_id(), % mandatory shutdown => brutal_kill}</code> <p>Example: A child specification to start the event manager from the chapter about - <seealso marker="events#mgr">gen_event</seealso>:</p> + <seeguide marker="events#mgr">gen_event</seeguide>:</p> <code type="none"> #{id => error_man, start => {gen_event, start_link, [{local, error_man}]}, @@ -444,7 +444,7 @@ init(_Args) -> supervisor:start_child(Sup, ChildSpec)</code> <p><c>Sup</c> is the pid, or name, of the supervisor. <c>ChildSpec</c> is a - <seealso marker="#spec">child specification</seealso>.</p> + <seeguide marker="#spec">child specification</seeguide>.</p> <p>Child processes added using <c>start_child/2</c> behave in the same way as the other child processes, with the an important exception: if a supervisor dies and is recreated, then @@ -464,7 +464,7 @@ supervisor:terminate_child(Sup, Id)</code> supervisor:delete_child(Sup, Id)</code> <p><c>Sup</c> is the pid, or name, of the supervisor. <c>Id</c> is the value associated with the <c>id</c> key in - the <seealso marker="#spec">child specification</seealso>.</p> + the <seeguide marker="#spec">child specification</seeguide>.</p> <p>As with dynamically added child processes, the effects of deleting a static child process is lost if the supervisor itself restarts.</p> diff --git a/system/doc/efficiency_guide/advanced.xml b/system/doc/efficiency_guide/advanced.xml index fe77ce8ea4..acf909b0fc 100644 --- a/system/doc/efficiency_guide/advanced.xml +++ b/system/doc/efficiency_guide/advanced.xml @@ -153,9 +153,9 @@ <cell>The maximum number of simultaneously alive Erlang processes is by default 262,144. This limit can be configured at startup. For more information, see the - <seealso marker="erts:erl#max_processes"><c>+P</c></seealso> + <seecom marker="erts:erl#max_processes"><c>+P</c></seecom> command-line flag in the - <seealso marker="erts:erl"><c>erl(1)</c></seealso> + <seecom marker="erts:erl"><c>erl(1)</c></seecom> manual page in ERTS.</cell> </row> <row> @@ -164,7 +164,7 @@ any pids, ports, references, or funs (Erlang data types) from Y on X, or if X and Y are connected. The maximum number of remote nodes simultaneously/ever known to a node is limited by the - <seealso marker="#atoms">maximum number of atoms</seealso> + <seeguide marker="#atoms">maximum number of atoms</seeguide> available for node names. All data concerning remote nodes, except for the node name atom, are garbage-collected.</cell> </row> @@ -173,9 +173,9 @@ <cell>The maximum number of simultaneously connected nodes is limited by either the maximum number of simultaneously known remote nodes, - <seealso marker="#ports">the maximum number of (Erlang) ports</seealso> + <seeguide marker="#ports">the maximum number of (Erlang) ports</seeguide> available, or - <seealso marker="#files_sockets">the maximum number of sockets</seealso> + <seeguide marker="#files_sockets">the maximum number of sockets</seeguide> available.</cell> </row> <row> @@ -226,9 +226,9 @@ <cell>The maximum number of simultaneously open Erlang ports is often by default 16,384. This limit can be configured at startup. For more information, see the - <seealso marker="erts:erl#max_ports"><c>+Q</c></seealso> + <seecom marker="erts:erl#max_ports"><c>+Q</c></seecom> command-line flag in the - <seealso marker="erts:erl"><c>erl(1)</c></seealso> manual page + <seecom marker="erts:erl"><c>erl(1)</c></seecom> manual page in ERTS.</cell> </row> <row> @@ -236,7 +236,7 @@ sockets</cell> <cell>The maximum number of simultaneously open files and sockets depends on - <seealso marker="#ports">the maximum number of Erlang ports</seealso> + <seeguide marker="#ports">the maximum number of Erlang ports</seeguide> available, as well as on operating system-specific settings and limits.</cell> </row> @@ -260,7 +260,7 @@ <cell><marker id="unique_integers"/>Unique Integers on a Runtime System Instance</cell> <cell> There are two types of unique integers both created using the - <seealso marker="erts:erlang#unique_integer/1">erlang:unique_integer()</seealso> + <seemfa marker="erts:erlang#unique_integer/1">erlang:unique_integer()</seemfa> BIF: <br/><br/> <em>1.</em> Unique integers created <em>with</em> the diff --git a/system/doc/efficiency_guide/binaryhandling.xml b/system/doc/efficiency_guide/binaryhandling.xml index d92da17390..4d124095e8 100644 --- a/system/doc/efficiency_guide/binaryhandling.xml +++ b/system/doc/efficiency_guide/binaryhandling.xml @@ -165,12 +165,12 @@ Bin4 = <<Bin1/binary,17>>, %% 5 !!! <list type="bulleted"> <item>Line 1 (marked with the <c>%% 1</c> comment), assigns - a <seealso marker="#heap_binary">heap binary</seealso> to + a <seeguide marker="#heap_binary">heap binary</seeguide> to the <c>Bin0</c> variable.</item> <item>Line 2 is an append operation. As <c>Bin0</c> has not been involved in an append operation, - a new <seealso marker="#refc_binary">refc binary</seealso> + a new <seeguide marker="#refc_binary">refc binary</seeguide> is created and the contents of <c>Bin0</c> is copied into it. The <em>ProcBin</em> part of the refc binary has its size set to the size of the data stored in the binary, while @@ -248,7 +248,7 @@ Bin = <<Bin1,...>> %% Bin1 will be COPIED <p>The same happens if you insert a binary into an Ets table, send it to a port using <c>erlang:port_command/2</c>, or pass it to - <seealso marker="erts:erl_nif#enif_inspect_binary">enif_inspect_binary</seealso> + <seecref marker="erts:erl_nif#enif_inspect_binary">enif_inspect_binary</seecref> in a NIF.</p> <p>Matching a binary will also cause it to shrink and the next append @@ -261,7 +261,7 @@ Bin = <<Bin1,...>> %% Bin1 will be COPIED ]]></code> <p>The reason is that a - <seealso marker="#match_context">match context</seealso> + <seeguide marker="#match_context">match context</seeguide> contains a direct pointer to the binary data.</p> <p>If a process simply keeps binaries (either in "loop data" or in the @@ -285,13 +285,13 @@ my_binary_to_list(<<H,T/binary>>) -> my_binary_to_list(<<>>) -> [].]]></code> <p>The first time <c>my_binary_to_list/1</c> is called, - a <seealso marker="#match_context">match context</seealso> + a <seeguide marker="#match_context">match context</seeguide> is created. The match context points to the first byte of the binary. 1 byte is matched out and the match context is updated to point to the second byte in the binary.</p> <p>At this point it would make sense to create a - <seealso marker="#sub_binary">sub binary</seealso>, + <seeguide marker="#sub_binary">sub binary</seeguide>, but in this particular example the compiler sees that there will soon be a call to a function (in this case, to <c>my_binary_to_list/1</c> itself) that immediately will diff --git a/system/doc/efficiency_guide/commoncaveats.xml b/system/doc/efficiency_guide/commoncaveats.xml index dd09e78e3f..35dd23aa9b 100644 --- a/system/doc/efficiency_guide/commoncaveats.xml +++ b/system/doc/efficiency_guide/commoncaveats.xml @@ -35,12 +35,12 @@ <section> <title>Timer Module</title> - <p>Creating timers using <seealso - marker="erts:erlang#send_after/3">erlang:send_after/3</seealso> + <p>Creating timers using <seemfa + marker="erts:erlang#send_after/3">erlang:send_after/3</seemfa> and - <seealso marker="erts:erlang#start_timer/3">erlang:start_timer/3</seealso>, + <seemfa marker="erts:erlang#start_timer/3">erlang:start_timer/3</seemfa>, is much more efficient than using the timers provided by the - <seealso marker="stdlib:timer">timer</seealso> module in STDLIB. + <seeerl marker="stdlib:timer">timer</seeerl> module in STDLIB. The <c>timer</c> module uses a separate process to manage the timers. That process can easily become overloaded if many processes create and cancel timers frequently (especially when using the @@ -61,7 +61,7 @@ <p>Therefore, converting arbitrary input strings to atoms can be dangerous in a system that runs continuously. If only certain well-defined atoms are allowed as input, - <seealso marker="erts:erlang#list_to_existing_atom/1">list_to_existing_atom/1</seealso> + <seemfa marker="erts:erlang#list_to_existing_atom/1">list_to_existing_atom/1</seemfa> can be used to guard against a denial-of-service attack. (All atoms that are allowed must have been created earlier, for example, by simply using all of them @@ -105,7 +105,7 @@ foo([_,_,_|_]=L) -> <section> <title>setelement/3</title> - <p><seealso marker="erts:erlang#setelement/3">setelement/3</seealso> + <p><seemfa marker="erts:erlang#setelement/3">setelement/3</seemfa> copies the tuple it modifies. Therefore, updating a tuple in a loop using <c>setelement/3</c> creates a new copy of the tuple every time.</p> diff --git a/system/doc/efficiency_guide/drivers.xml b/system/doc/efficiency_guide/drivers.xml index c99701eeba..2b6e22b980 100644 --- a/system/doc/efficiency_guide/drivers.xml +++ b/system/doc/efficiency_guide/drivers.xml @@ -74,7 +74,7 @@ client_port() -> <list type="bulleted"> <item><p>If the <c>Data</c> argument for - <seealso marker="erts:erlang#port_control/3">port_control/3</seealso> + <seemfa marker="erts:erlang#port_control/3">port_control/3</seemfa> is a binary, the driver will be passed a pointer to the contents of the binary and the binary will not be copied. If the <c>Data</c> argument is an iolist (list of binaries and lists), all binaries in @@ -91,7 +91,7 @@ client_port() -> <c>output</c> callback) in the driver. If a driver has an <c>outputv</c> callback, refc binaries passed in an iolist in the <c>Data</c> argument for - <seealso marker="erts:erlang#port_command/2">port_command/2</seealso> + <seemfa marker="erts:erlang#port_command/2">port_command/2</seemfa> will be passed as references to the driver.</p></item> </list> </section> @@ -107,9 +107,9 @@ client_port() -> <p>If you know that the binaries you return are always small, you are advised to use driver API calls that do not require a pre-allocated binary, for example, - <seealso marker="erts:erl_driver#driver_output">driver_output()</seealso> + <seecref marker="erts:erl_driver#driver_output">driver_output()</seecref> or - <seealso marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seealso>, + <seecref marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seecref>, using the <c>ERL_DRV_BUF2BINARY</c> format, to allow the runtime to construct a heap binary.</p> @@ -123,7 +123,7 @@ client_port() -> binary and then send it to an Erlang process in some way.</p> <p>Use - <seealso marker="erts:erl_driver#driver_alloc_binary">driver_alloc_binary()</seealso> + <seecref marker="erts:erl_driver#driver_alloc_binary">driver_alloc_binary()</seecref> to allocate a binary.</p> <p>There are several ways to send a binary created with @@ -131,16 +131,16 @@ client_port() -> <list type="bulleted"> <item>From the <c>control</c> callback, a binary can be returned if - <seealso marker="erts:erl_driver#set_port_control_flags">set_port_control_flags()</seealso> + <seecref marker="erts:erl_driver#set_port_control_flags">set_port_control_flags()</seecref> has been called with the flag value <c>PORT_CONTROL_FLAG_BINARY</c>.</item> <item>A single binary can be sent with - <seealso marker="erts:erl_driver#driver_output_binary">driver_output_binary()</seealso>.</item> + <seecref marker="erts:erl_driver#driver_output_binary">driver_output_binary()</seecref>.</item> <item>Using - <seealso marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seealso> + <seecref marker="erts:erl_driver#erl_drv_output_term">erl_drv_output_term()</seecref> or - <seealso marker="erts:erl_driver#erl_drv_send_term">erl_drv_send_term()</seealso>, + <seecref marker="erts:erl_driver#erl_drv_send_term">erl_drv_send_term()</seecref>, a binary can be included in an Erlang term.</item> </list> diff --git a/system/doc/efficiency_guide/listhandling.xml b/system/doc/efficiency_guide/listhandling.xml index 4f2497359d..9c498c9235 100644 --- a/system/doc/efficiency_guide/listhandling.xml +++ b/system/doc/efficiency_guide/listhandling.xml @@ -144,7 +144,7 @@ ok.]]></code> <section> <title>Deep and Flat Lists</title> - <p><seealso marker="stdlib:lists#flatten/1">lists:flatten/1</seealso> + <p><seemfa marker="stdlib:lists#flatten/1">lists:flatten/1</seemfa> builds an entirely new list. It is therefore expensive, and even <em>more</em> expensive than the <c>++</c> operator (which copies its left argument, but not its right argument).</p> @@ -157,10 +157,10 @@ ok.]]></code> so there is no reason to flatten the list before sending it to the port.</item> <item>When calling BIFs that accept deep lists, such as - <seealso marker="erts:erlang#list_to_binary/1">list_to_binary/1</seealso> or - <seealso marker="erts:erlang#iolist_to_binary/1">iolist_to_binary/1</seealso>.</item> + <seemfa marker="erts:erlang#list_to_binary/1">list_to_binary/1</seemfa> or + <seemfa marker="erts:erlang#iolist_to_binary/1">iolist_to_binary/1</seemfa>.</item> <item>When you know that your list is only one level deep, you can use - <seealso marker="stdlib:lists#append/1">lists:append/1</seealso>.</item> + <seemfa marker="stdlib:lists#append/1">lists:append/1</seemfa>.</item> </list> <section> @@ -218,8 +218,8 @@ ok.]]></code> <title>Recursive List Functions</title> <p>In section about myths, the following myth was exposed: - <seealso marker="myths#tail_recursive">Tail-Recursive Functions - are Much Faster Than Recursive Functions</seealso>.</p> + <seeguide marker="myths#tail_recursive">Tail-Recursive Functions + are Much Faster Than Recursive Functions</seeguide>.</p> <p>There is usually not much difference between a body-recursive list function and tail-recursive function that reverses diff --git a/system/doc/efficiency_guide/myths.xml b/system/doc/efficiency_guide/myths.xml index 778cd06c09..0ae12bcfec 100644 --- a/system/doc/efficiency_guide/myths.xml +++ b/system/doc/efficiency_guide/myths.xml @@ -121,7 +121,7 @@ vanilla_reverse([], Acc) -> In Erlang, you need to think a little more about how the strings are used and choose an appropriate representation. If you use regular expressions, use the - <seealso marker="stdlib:re">re</seealso> module in STDLIB + <seeerl marker="stdlib:re">re</seeerl> module in STDLIB instead of the obsolete <c>regexp</c> module.</p> </section> @@ -167,13 +167,13 @@ vanilla_reverse([], Acc) -> but not guaranteed to speed up the program.</p> <p>Doing too much work in each NIF call will - <seealso marker="erts:erl_nif#WARNING">degrade responsiveness - of the VM</seealso>. Doing too little work may mean that + <seecref marker="erts:erl_nif#WARNING">degrade responsiveness + of the VM</seecref>. Doing too little work may mean that the gain of the faster processing in the NIF is eaten up by the overhead of calling the NIF and checking the arguments.</p> <p>Be sure to read about - <seealso marker="erts:erl_nif#lengthy_work">Long-running NIFs</seealso> + <seecref marker="erts:erl_nif#lengthy_work">Long-running NIFs</seecref> before writing a NIF.</p> </section> </chapter> diff --git a/system/doc/efficiency_guide/processes.xml b/system/doc/efficiency_guide/processes.xml index 3b64c863ff..db05e6a3a8 100644 --- a/system/doc/efficiency_guide/processes.xml +++ b/system/doc/efficiency_guide/processes.xml @@ -101,9 +101,9 @@ loop() -> <p>In a system that use comparatively few processes, performance <em>might</em> be improved by increasing the minimum heap size using either the <c>+h</c> option for - <seealso marker="erts:erl">erl</seealso> or on a process-per-process + <seecom marker="erts:erl">erl</seecom> or on a process-per-process basis using the <c>min_heap_size</c> option for - <seealso marker="erts:erlang#spawn_opt/4">spawn_opt/4</seealso>.</p> + <seemfa marker="erts:erlang#spawn_opt/4">spawn_opt/4</seemfa>.</p> <p>The gain is twofold:</p> <list type="bulleted"> @@ -135,7 +135,7 @@ loop() -> <p>All data in messages between Erlang processes is copied, except for - <seealso marker="binaryhandling#refc_binary">refc binaries</seealso> + <seeguide marker="binaryhandling#refc_binary">refc binaries</seeguide> on the same Erlang node.</p> <p>When a message is sent to a process on another Erlang node, diff --git a/system/doc/efficiency_guide/profiling.xml b/system/doc/efficiency_guide/profiling.xml index 5ec1f1be6e..594d066df4 100644 --- a/system/doc/efficiency_guide/profiling.xml +++ b/system/doc/efficiency_guide/profiling.xml @@ -41,11 +41,11 @@ <p>Erlang/OTP contains several tools to help finding bottlenecks:</p> <list type="bulleted"> - <item><p><seealso marker="tools:fprof"><c>fprof</c></seealso> provides + <item><p><seeerl marker="tools:fprof"><c>fprof</c></seeerl> provides the most detailed information about where the program time is spent, but it significantly slows down the program it profiles.</p></item> - <item><p><seealso marker="tools:eprof"><c>eprof</c></seealso> provides + <item><p><seeerl marker="tools:eprof"><c>eprof</c></seeerl> provides time information of each function used in the program. No call graph is produced, but <c>eprof</c> has considerable less impact on the program it profiles.</p> @@ -53,16 +53,16 @@ <c>eprof</c>, <c>cprof</c> can be used to locate code parts that are to be more thoroughly profiled using <c>fprof</c> or <c>eprof</c>.</p></item> - <item><p><seealso marker="tools:cprof"><c>cprof</c></seealso> is the + <item><p><seeerl marker="tools:cprof"><c>cprof</c></seeerl> is the most lightweight tool, but it only provides execution counts on a function basis (for all processes, not per process).</p></item> - <item><p><seealso marker="runtime_tools:dbg"><c>dbg</c></seealso> is the + <item><p><seeerl marker="runtime_tools:dbg"><c>dbg</c></seeerl> is the generic erlang tracing frontend. By using the <c>timestamp</c> or <c>cpu_timestamp</c> options it can be used to time how long function calls in a live system take.</p></item> - <item><p><seealso marker="tools:lcnt"><c>lcnt</c></seealso> is used + <item><p><seeerl marker="tools:lcnt"><c>lcnt</c></seeerl> is used to find contention points in the Erlang Run-Time System's internal locking mechanisms. It is useful when looking for bottlenecks in interaction between process, port, ets tables and other entities @@ -71,7 +71,7 @@ </list> <p>The tools are further described in - <seealso marker="#profiling_tools">Tools</seealso>.</p> + <seeguide marker="#profiling_tools">Tools</seeguide>.</p> <p>There are also several open source tools outside of Erlang/OTP that can be used to help profiling. Some of them are:</p> @@ -95,29 +95,29 @@ For unknown reasons the Erlang Run-Time System failed to allocate memory to use. When this happens a crash dump is generated that contains information about the state of the system as it ran out of memory. Use the - <seealso marker="observer:cdv"><c>crashdump_viewer</c></seealso> to get a + <seecom marker="observer:cdv"><c>crashdump_viewer</c></seecom> to get a view of the memory is being used. Look for processes with large heaps or many messages, large ets tables, etc.</p> <p>When looking at memory usage in a running system the most basic function - to get information from is <seealso marker="erts:erlang#memory/0"><c> - erlang:memory()</c></seealso>. It returns the current memory usage - of the system. <seealso marker="tools:instrument"><c>instrument(3)</c></seealso> + to get information from is <seemfa marker="erts:erlang#memory/0"><c> + erlang:memory()</c></seemfa>. It returns the current memory usage + of the system. <seeerl marker="tools:instrument"><c>instrument(3)</c></seeerl> can be used to get a more detailed breakdown of where memory is used.</p> <p>Processes, ports and ets tables can then be inspecting using their respective info functions, i.e. - <seealso marker="erts:erlang#process_info_memory"><c>erlang:process_info/2 - </c></seealso>, - <seealso marker="erts:erlang#port_info_memory"><c>erlang:port_info/2 - </c></seealso> and - <seealso marker="stdlib:ets#info/1"><c>ets:info/1</c></seealso>. + <seeerl marker="erts:erlang#process_info_memory"><c>erlang:process_info/2 + </c></seeerl>, + <seeerl marker="erts:erlang#port_info_memory"><c>erlang:port_info/2 + </c></seeerl> and + <seemfa marker="stdlib:ets#info/1"><c>ets:info/1</c></seemfa>. </p> <p>Sometimes the system can enter a state where the reported memory from <c>erlang:memory(total)</c> is very different from the memory reported by the OS. This can be because of internal fragmentation within the Erlang Run-Time System. Data about how memory is allocated can be retrieved using - <seealso marker="erts:erlang#system_info_allocator"> - <c>erlang:system_info(allocator)</c></seealso>. + <seeerl marker="erts:erlang#system_info_allocator"> + <c>erlang:system_info(allocator)</c></seeerl>. The data you get from that function is very raw and not very plesant to read. <url href="http://ferd.github.io/recon/recon_alloc.html">recon_alloc</url> can be used to extract useful information from system_info @@ -141,13 +141,13 @@ <p>There are also some tools that can be used to get a view of the whole system with more or less overhead.</p> <list type="bulleted"> - <item><seealso marker="observer:observer"><c>observer</c></seealso> + <item><seeerl marker="observer:observer"><c>observer</c></seeerl> is a GUI tool that can connect to remote nodes and display a variety of information about the running system.</item> - <item><seealso marker="observer:etop"><c>etop</c></seealso> + <item><seeerl marker="observer:etop"><c>etop</c></seeerl> is a command line tool that can connect to remote nodes and display information similar to what the UNIX tool top shows.</item> - <item><seealso marker="runtime_tools:msacc"><c>msacc</c></seealso> + <item><seeerl marker="runtime_tools:msacc"><c>msacc</c></seeerl> allows the user to get a view of what the Erlang Run-Time system is spending its time doing. Has a very low overhead, which makes it useful to run in heavily loaded systems to get some idea of where @@ -183,7 +183,7 @@ <p>These questions are not always trivial to answer. Some benchmarks might be needed to back up your theory and to avoid making things slower if your theory is wrong. For details, see - <seealso marker="#benchmark">Benchmarking</seealso>.</p> + <seeguide marker="#benchmark">Benchmarking</seeguide>.</p> </section> <section> @@ -200,7 +200,7 @@ <p><c>fprof</c> is based on trace to file to minimize runtime performance impact. Using <c>fprof</c> is just a matter of calling a few library functions, see the - <seealso marker="tools:fprof">fprof</seealso> manual page in + <seeerl marker="tools:fprof">fprof</seeerl> manual page in Tools.</p> </section> @@ -210,7 +210,7 @@ <c>eprof</c> shows how much time has been used by each process, and in which function calls this time has been spent. Time is shown as percentage of total time and absolute time. For more - information, see the <seealso marker="tools:eprof">eprof</seealso> + information, see the <seeerl marker="tools:eprof">eprof</seeerl> manual page in Tools.</p> </section> @@ -223,7 +223,7 @@ (compared with <c>fprof</c>) and does not need to recompile any modules to profile (compared with <c>cover</c>). For more information, see the - <seealso marker="tools:cprof">cprof</seealso> manual page in + <seeerl marker="tools:cprof">cprof</seeerl> manual page in Tools.</p> </section> @@ -284,7 +284,7 @@ system as it is possible to limit the scope of what is profiled to be very small. For more information, see the - <seealso marker="runtime_tools:dbg">dbg</seealso> manual page in + <seeerl marker="runtime_tools:dbg">dbg</seeerl> manual page in Runtime Tools.</p> </section> @@ -301,7 +301,7 @@ show more contention points (and thus be more useful) on systems using many schedulers on many cores.</p> <p>For more information, see the - <seealso marker="tools:lcnt">lcnt</seealso> manual page in Tools.</p> + <seeerl marker="tools:lcnt">lcnt</seeerl> manual page in Tools.</p> </section> </section> @@ -322,7 +322,7 @@ <p>Benchmarks can measure wall-clock time or CPU time.</p> <list type="bulleted"> - <item><seealso marker="stdlib:timer#tc/3">timer:tc/3</seealso> measures + <item><seemfa marker="stdlib:timer#tc/3">timer:tc/3</seemfa> measures wall-clock time. The advantage with wall-clock time is that I/O, swapping, and other activities in the operating system kernel are included in the measurements. The disadvantage is that the @@ -331,7 +331,7 @@ be the minimum time that is possible to achieve under the best of circumstances.</item> - <item><seealso marker="erts:erlang#statistics/1">statistics/1</seealso> + <item><seemfa marker="erts:erlang#statistics/1">statistics/1</seemfa> with argument <c>runtime</c> measures CPU time spent in the Erlang virtual machine. The advantage with CPU time is that the results are more consistent from run to run. The disadvantage is that the time diff --git a/system/doc/general_info/deprecations_18.inc b/system/doc/general_info/deprecations_18.inc index cfcfda7174..04eaf990ea 100644 --- a/system/doc/general_info/deprecations_18.inc +++ b/system/doc/general_info/deprecations_18.inc @@ -1,9 +1,9 @@ <section> <title>erlang:now/0</title> <p>New time functionality and a new time API was introduced. For more information - see the <seealso marker="erts:time_correction">Time and Time Correction</seealso> + see the <seeguide marker="erts:time_correction">Time and Time Correction</seeguide> chapter in the ERTS User's guide and specifically the - <seealso marker="erts:time_correction#Dos_and_Donts">Dos and Donts</seealso> + <seeguide marker="erts:time_correction#Dos_and_Donts">Dos and Donts</seeguide> section on how to replace usage of <c>erlang:now/0</c>.</p> </section> diff --git a/system/doc/general_info/deprecations_22.inc b/system/doc/general_info/deprecations_22.inc index a8c168db8b..53da6df594 100644 --- a/system/doc/general_info/deprecations_22.inc +++ b/system/doc/general_info/deprecations_22.inc @@ -1,25 +1,25 @@ <section> <title>VxWorks Support</title> <p>Some parts of OTP has had limited VxWorks support, such as for - example <seealso marker="erl_interface:index"><c>erl_interface</c></seealso>. + example <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp>. This support is now deprecated and has also been scheduled for removal in OTP 23.</p> </section> <section> <title>Legacy parts of erl_interface</title> - <p>The old legacy <seealso marker="erl_interface:index"><c>erl_interface</c></seealso> + <p>The old legacy <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp> library (functions with prefix <c>erl_</c>) is deprecated as of OTP 22. These parts of <c>erl_interface</c> has been informally deprecated for a very long time. You typically want to replace the usage of the <c>erl_interface</c> library with the use of the <c>ei</c> library which also is part of the <c>erl_interface</c> application. The old legacy - <seealso marker="erl_interface:index"><c>erl_interface</c></seealso> + <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp> library has also been scheduled for removal in OTP 23.</p> </section> <section> <title>System Events</title> <p> The format of "System Events" as defined in the man page for - <seealso marker="stdlib:sys">sys</seealso> + <seeerl marker="stdlib:sys">sys</seeerl> has been clarified and cleaned up. Due to this, code that relied on the internal badly documented previous (before this change) format @@ -27,11 +27,11 @@ </p> <p> In the wake of this the function - <seealso marker="stdlib:sys#get_debug/3">sys:get_debug/3</seealso> + <seemfa marker="stdlib:sys#get_debug/3">sys:get_debug/3</seemfa> that returns data with undocumented and internal format (and therefore is practically useless) has been deprecated, and a new function - <seealso marker="stdlib:sys#get_log/1">sys:get_log/1</seealso> + <seemfa marker="stdlib:sys#get_log/1">sys:get_log/1</seemfa> has been added, that hopefully does what the deprecated function was intended for. </p> diff --git a/system/doc/general_info/deprecations_23.inc b/system/doc/general_info/deprecations_23.inc index f041522b65..63d6d4c8ed 100644 --- a/system/doc/general_info/deprecations_23.inc +++ b/system/doc/general_info/deprecations_23.inc @@ -1,16 +1,16 @@ <section> <title>Crypto Old API</title> - <p>The <seealso marker="crypto:new_api#the-old-api">Old API</seealso> is now deprecated + <p>The <seeguide marker="crypto:new_api#the-old-api">Old API</seeguide> is now deprecated and has also been - <seealso marker="scheduled_for_removal#otp-24">scheduled for removal</seealso>.</p> + <seeguide marker="scheduled_for_removal#otp-24">scheduled for removal</seeguide>.</p> <p>For replacement functions see the - <seealso marker="crypto:new_api#the-new-api">New API</seealso>.</p> + <seeguide marker="crypto:new_api#the-new-api">New API</seeguide>.</p> </section> <section> <title>http_uri</title> <p>Since OTP 21 the recommended module to handle URIs is - <seealso marker="stdlib:uri_string">uri_string</seealso>. The module + <seeerl marker="stdlib:uri_string">uri_string</seeerl>. The module http_uri does not provide a implementation that satisfies the RFC. </p> @@ -33,14 +33,14 @@ <title>pg2</title> <p> As of OTP 23, a new process group implementation - <seealso marker="kernel:pg">pg</seealso> is introduced. - <c>pg</c> is similar to <seealso marker="kernel:pg2">pg2</seealso>, + <seeerl marker="kernel:pg">pg</seeerl> is introduced. + <c>pg</c> is similar to <seeerl marker="kernel:pg2">pg2</seeerl>, but with much better scalability properties. However, the API and behavior are not compatible. </p> <p> <c>pg2</c> is now deprecated and has also been - <seealso marker="scheduled_for_removal#otp-24">scheduled for removal</seealso> + <seeguide marker="scheduled_for_removal#otp-24">scheduled for removal</seeguide> in OTP 24. </p> </section> @@ -49,9 +49,9 @@ <title>Distributed Disk Logs</title> <p> As of OTP 23, the distributed - <seealso marker="kernel:disk_log"><c>disk_log</c></seealso> + <seeerl marker="kernel:disk_log"><c>disk_log</c></seeerl> feature has been deprecated and it has also been - <seealso marker="scheduled_for_removal#otp-24">scheduled for removal</seealso> + <seeguide marker="scheduled_for_removal#otp-24">scheduled for removal</seeguide> in OTP 24. </p> </section> diff --git a/system/doc/general_info/deprecations_head.inc b/system/doc/general_info/deprecations_head.inc index f188028de9..7653dc44f9 100644 --- a/system/doc/general_info/deprecations_head.inc +++ b/system/doc/general_info/deprecations_head.inc @@ -33,7 +33,7 @@ <title>Introduction</title> <p>This document lists all deprecated functionality in Erlang/OTP. For more information regarding the strategy regarding - deprecations see the documentation of <seealso - marker="../system_principles/misc#deprecation">Support, - Compatibility, Deprecations, and Removal</seealso>.</p> + deprecations see the documentation of <seeguide + marker="system/system_principles:misc#deprecation">Support, + Compatibility, Deprecations, and Removal</seeguide>.</p> </section> diff --git a/system/doc/general_info/scheduled_for_removal_23.inc b/system/doc/general_info/scheduled_for_removal_23.inc index b29f1ff92f..692d51d09c 100644 --- a/system/doc/general_info/scheduled_for_removal_23.inc +++ b/system/doc/general_info/scheduled_for_removal_23.inc @@ -1,13 +1,13 @@ <section> <title>VxWorks Support</title> <p>Some parts of OTP has had limited VxWorks support, such as - <seealso marker="erl_interface:index"><c>erl_interface</c></seealso>. + <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp>. This support will be removed as of OTP 23. This limited support was formally deprecated as of OTP 22.</p> </section> <section> <title>Legacy parts of erl_interface</title> - <p>The old legacy <seealso marker="erl_interface:index"><c>erl_interface</c></seealso> + <p>The old legacy <seeapp marker="erl_interface:index"><c>erl_interface</c></seeapp> library (functions with prefix <c>erl_</c>) will be removed as of OTP 23. These parts of <c>erl_interface</c> has been informally deprecated for a very long time, and was formally deprecated in OTP 22. You typically diff --git a/system/doc/general_info/scheduled_for_removal_24.inc b/system/doc/general_info/scheduled_for_removal_24.inc index a708cbc244..6f450f45c3 100644 --- a/system/doc/general_info/scheduled_for_removal_24.inc +++ b/system/doc/general_info/scheduled_for_removal_24.inc @@ -1,15 +1,15 @@ <section> <title>Old Crypto API</title> - <p>The <seealso marker="crypto:new_api#the-old-api">Old API</seealso> will be + <p>The <seeguide marker="crypto:new_api#the-old-api">Old API</seeguide> will be removed as of OTP 24. The support was formally deprecated as of OTP 23.</p> <p>For replacement functions see the - <seealso marker="crypto:new_api#the-new-api">New API</seealso>.</p> + <seeguide marker="crypto:new_api#the-new-api">New API</seeguide>.</p> </section> <section> <title>pg2</title> <p> - <seealso marker="kernel:pg2">pg2</seealso> is as of - <seealso marker="deprecations#otp-23">OTP 23 deprecated</seealso> + <seeerl marker="kernel:pg2">pg2</seeerl> is as of + <seeguide marker="deprecations#otp-23">OTP 23 deprecated</seeguide> and will be removed in OTP 24. </p> </section> @@ -17,9 +17,9 @@ <title>Distributed Disk Logs</title> <p> The distributed - <seealso marker="kernel:disk_log"><c>disk_log</c></seealso> + <seeerl marker="kernel:disk_log"><c>disk_log</c></seeerl> feature is as of - <seealso marker="deprecations#otp-23">OTP 23 deprecated</seealso> + <seeguide marker="deprecations#otp-23">OTP 23 deprecated</seeguide> and will be removed in OTP 24. </p> </section> diff --git a/system/doc/general_info/scheduled_for_removal_25.inc b/system/doc/general_info/scheduled_for_removal_25.inc index 4c9c0b56c3..a3dd3a9571 100644 --- a/system/doc/general_info/scheduled_for_removal_25.inc +++ b/system/doc/general_info/scheduled_for_removal_25.inc @@ -1,7 +1,7 @@ <section> <title>http_uri</title> <p>Since OTP 21 the recommended module to handle URIs is - <seealso marker="stdlib:uri_string">uri_string</seealso>. The module + <seeerl marker="stdlib:uri_string">uri_string</seeerl>. The module <c>http_uri</c> does not provide a implementation that satisfies the RFC. Formally deprecated since OTP-23.</p> </section> diff --git a/system/doc/general_info/scheduled_for_removal_head.inc b/system/doc/general_info/scheduled_for_removal_head.inc index e245197014..cc64df776b 100644 --- a/system/doc/general_info/scheduled_for_removal_head.inc +++ b/system/doc/general_info/scheduled_for_removal_head.inc @@ -34,6 +34,6 @@ <p>This document list all functionality in Erlang/OTP that currently are scheduled for removal. For more information regarding the strategy regarding removal of functionality see the documentation of - <seealso marker="../system_principles/misc#removal">Support, Compatibility, - Deprecations, and Removal</seealso>.</p> + <seeguide marker="system/system_principles:misc#removal">Support, Compatibility, + Deprecations, and Removal</seeguide>.</p> </section> diff --git a/system/doc/getting_started/conc_prog.xml b/system/doc/getting_started/conc_prog.xml index 4374a59e04..76b36c8bd5 100644 --- a/system/doc/getting_started/conc_prog.xml +++ b/system/doc/getting_started/conc_prog.xml @@ -555,8 +555,8 @@ ping finished</pre> <p>This sort of problem can be solved easier by use of the facilities in OTP, which also provide methods for updating code on the fly and so on (see - <seealso marker="doc/design_principles:des_princ#otp design principles"> - OTP Design Principles</seealso>).</p> + <seeguide marker="system/design_principles:des_princ#otp design principles"> + OTP Design Principles</seeguide>).</p> </item> <item> <p>The first program contains some inadequacies diff --git a/system/doc/getting_started/intro.xml b/system/doc/getting_started/intro.xml index afae4e8c18..b945fada8d 100644 --- a/system/doc/getting_started/intro.xml +++ b/system/doc/getting_started/intro.xml @@ -37,8 +37,8 @@ Also, parts that are greatly simplified are indicated with *manual*. This means that a lot more information on the subject is to be found in the Erlang book or in - <seealso marker="doc/reference_manual:introduction#erlang ref manual"> - Erlang Reference Manual</seealso>.</p> + <seeguide marker="system/reference_manual:introduction#erlang ref manual"> + Erlang Reference Manual</seeguide>.</p> <section> <title>Prerequisites</title> @@ -64,8 +64,8 @@ <item>How to communicate with the outside world and software written in other languages (ports); this is described in - <seealso marker="doc/tutorial:introduction#interoperability tutorial"> - Interoperability Tutorial</seealso>.</item> + <seeguide marker="system/tutorial:introduction#interoperability tutorial"> + Interoperability Tutorial</seeguide>.</item> <item>Erlang libraries (for example, file handling).</item> <item>OTP and (in consequence) the Mnesia database.</item> <item>Hash tables for Erlang terms (ETS).</item> diff --git a/system/doc/getting_started/robustness.xml b/system/doc/getting_started/robustness.xml index 6932f0ca0f..cccacf4a65 100644 --- a/system/doc/getting_started/robustness.xml +++ b/system/doc/getting_started/robustness.xml @@ -30,7 +30,7 @@ <file>robustness.xml</file> </header> <p>Several things are wrong with the messenger example in - <seealso marker="conc_prog#ex">A Larger Example</seealso>. + <seeguide marker="conc_prog#ex">A Larger Example</seeguide>. For example, if a node where a user is logged on goes down without doing a logoff, the user remains in the server's <c>User_List</c>, but the client disappears. This @@ -141,12 +141,12 @@ after pong_timeout() -></code> bad match, trying to call a function that does not exist and so on) exits with an error, that is, has an <em>abnormal</em> exit. A process which executes - <seealso marker="erts:erlang#exit/1">exit(Reason)</seealso> + <seemfa marker="erts:erlang#exit/1">exit(Reason)</seemfa> where <c>Reason</c> is any Erlang term except the atom <c>normal</c>, also has an abnormal exit.</p> <p>An Erlang process can set up links to other Erlang processes. If a process calls - <seealso marker="erts:erlang#link/1">link(Other_Pid)</seealso> + <seemfa marker="erts:erlang#link/1">link(Other_Pid)</seemfa> it sets up a bidirectional link between itself and the process called <c>Other_Pid</c>. When a process terminates, it sends something called a <em>signal</em> to all the processes it has @@ -168,7 +168,7 @@ after pong_timeout() -></code> exits abnormally, all the processes in the transaction are killed. As it is often wanted to create a process and link to it at the same time, there is a special BIF, - <seealso marker="erts:erlang#spawn_link/1">spawn_link</seealso> + <seemfa marker="erts:erlang#spawn_link/1">spawn_link</seemfa> that does the same as <c>spawn</c>, but also creates a link to the spawned process.</p> <p>Now an example of the ping pong example using links to terminate @@ -227,7 +227,7 @@ Ping received pong</pre> <code type="none"> process_flag(trap_exit, true)</code> <p>There are several other process flags, see - <seealso marker="erts:erlang#process_flag/2">erlang(3)</seealso>. + <seemfa marker="erts:erlang#process_flag/2">erlang(3)</seemfa>. Changing the default behaviour of a process in this way is usually not done in standard user programs, but is left to the supervisory programs in OTP. diff --git a/system/doc/getting_started/seq_prog.xml b/system/doc/getting_started/seq_prog.xml index 2b0750ff80..7a6b355b8c 100644 --- a/system/doc/getting_started/seq_prog.xml +++ b/system/doc/getting_started/seq_prog.xml @@ -37,7 +37,7 @@ and Linux have many, Windows has the command prompt. Erlang has its own shell where bits of Erlang code can be written directly, and be evaluated to see what happens - (see the <seealso marker="stdlib:shell">shell(3)</seealso> + (see the <seeerl marker="stdlib:shell">shell(3)</seeerl> manual page in STDLIB). </p> <p>Start @@ -62,7 +62,7 @@ Eshell V5.9.1 (abort with ^G) that 2 + 5 is 7. If you make writing mistakes in the shell, you can delete with the backspace key, as in most shells. There are many more editing commands in the shell - (see <seealso marker="erts:tty">tty - A command line interface</seealso> in ERTS User's Guide).</p> + (see <seeguide marker="erts:tty">tty - A command line interface</seeguide> in ERTS User's Guide).</p> <p>(Notice that many line numbers given by the shell in the following examples are out of sequence. This is because this tutorial was written and code-tested in separate sessions).</p> @@ -72,7 +72,7 @@ Eshell V5.9.1 (abort with ^G) 2618.0</pre> <p>Notice the use of brackets, the multiplication operator "*", and the division operator "/", as in normal arithmetic (see - <seealso marker="doc/reference_manual:expressions">Expressions</seealso>).</p> + <seeguide marker="system/reference_manual:expressions">Expressions</seeguide>).</p> <p>Press Control-C to shut down the Erlang system and the Erlang shell.</p> <p>The following output is shown:</p> @@ -98,9 +98,9 @@ BREAK: (a)bort (c)ontinue (p)roc info (i)nfo (l)oaded that it is in the same directory as the one where you started <c>erl</c>). If you are lucky your editor has an Erlang mode that makes it easier for you to enter and format your code - nicely (see <seealso + nicely (see <seeguide marker="tools:erlang_mode_chapter">The Erlang mode for - Emacs</seealso> in Tools User's Guide), but you can manage + Emacs</seeguide> in Tools User's Guide), but you can manage perfectly well without. Here is the code to enter:</p> <code type="none"> -module(tut). @@ -130,7 +130,7 @@ double(X) -> written in files. Each file contains an Erlang <em>module</em>. The first line of code in the module is the module name (see - <seealso marker="doc/reference_manual:modules">Modules</seealso>):</p> + <seeguide marker="system/reference_manual:modules">Modules</seeguide>):</p> <code type="none"> -module(tut).</code> <p>Thus, the module is called <em>tut</em>. Notice @@ -217,7 +217,7 @@ mult(X, Y) -> in the functions in the code <c>N</c>, <c>X</c>, and <c>Y</c> are called variables. Variables must start with a capital letter (see - <seealso marker="doc/reference_manual:expressions">Variables</seealso>). + <seeguide marker="system/reference_manual:expressions">Variables</seeguide>). Examples of variables are <c>Number</c>, <c>ShoeSize</c>, and <c>Age</c>.</p> </section> @@ -226,7 +226,7 @@ mult(X, Y) -> <title>Atoms</title> <p>Atom is another data type in Erlang. Atoms start with a small letter (see - <seealso marker="doc/reference_manual:data_types">Atom</seealso>), + <seeguide marker="system/reference_manual:data_types">Atom</seeguide>), for example, <c>charles</c>, <c>centimeter</c>, and <c>inch</c>. Atoms are simply names, nothing else. They are not like variables, which can have a value.</p> @@ -504,8 +504,8 @@ blue(#{blue := SV, alpha := SA}, #{blue := DV, alpha := DA}) -> <p>First a macro <c>is_channel</c> is defined to help with the guard tests. This is only here for convenience and to reduce syntax cluttering. For more information about macros, see - <seealso marker="doc/reference_manual:macros"> - The Preprocessor</seealso>. + <seeguide marker="system/reference_manual:macros"> + The Preprocessor</seeguide>. </p> <code type="none"> new(R,G,B,A) when ?is_channel(R), ?is_channel(G), @@ -683,7 +683,7 @@ ok</pre> <p><c>print_temp</c> simply calls <c>io:format</c> in a similar way to what has been described above. Notice that ~-15w says to print the "term" with a field length (width) of 15 and left justify it. - (see the <seealso marker="stdlib:io#fwrite/1">io(3)</seealso>) manual page in STDLIB.</p> + (see the <seemfa marker="stdlib:io#fwrite/1">io(3)</seemfa>) manual page in STDLIB.</p> <p>Now <c>format_temps(Rest)</c> is called with the rest of the list as an argument. This way of doing things is similar to the loop constructs in other languages. (Yes, this is recursion, but do not @@ -756,7 +756,7 @@ list_max([Head|Rest], Result_so_far) -> <item>>= greater or equal</item> <item>=< less or equal</item> <item>/= not equal</item></list> - <p>(see <seealso marker="doc/reference_manual:expressions">Guard Sequences</seealso>).</p> + <p>(see <seeguide marker="system/reference_manual:expressions">Guard Sequences</seeguide>).</p> <p>To change the above program to one that works out the minimum value of the element in a list, you only need to write < instead of >. (But it would be wise to change @@ -863,7 +863,7 @@ reverse([], [3,2,1]) => manipulating lists, for example, for reversing them. So before writing a list-manipulating function it is a good idea to check if one not already is written for you - (see the <seealso marker="stdlib:lists">lists(3)</seealso> + (see the <seeerl marker="stdlib:lists">lists(3)</seeerl> manual page in STDLIB).</p> <p>Now let us get back to the cities and temperatures, but take a more structured approach this time. First let us convert the whole list @@ -1093,7 +1093,7 @@ a_equals_1_or_b_equals_7 <p>Notice that <c>tut9:test_if(33,33)</c> does not cause any condition to succeed. This leads to the run time error <c>if_clause</c>, here nicely formatted by the shell. See - <seealso marker="doc/reference_manual:expressions">Guard Sequences</seealso> + <seeguide marker="system/reference_manual:expressions">Guard Sequences</seeguide> for details of the many guard tests available.</p> <p><c>case</c> is another construct in Erlang. Recall that the <c>convert_length</c> function was written as:</p> @@ -1222,7 +1222,7 @@ Year rem 400 == 0 -> <c>trunc</c>. Only a few BIFs can be used in guards, and you cannot use functions you have defined yourself in guards. (see - <seealso marker="doc/reference_manual:expressions">Guard Sequences</seealso>) + <seeguide marker="system/reference_manual:expressions">Guard Sequences</seeguide>) (For advanced readers: This is to ensure that guards do not have side effects.) Let us play with a few of these functions in the shell:</p> <pre> diff --git a/system/doc/programming_examples/bit_syntax.xml b/system/doc/programming_examples/bit_syntax.xml index 4da53cfdb3..cc89f3a469 100644 --- a/system/doc/programming_examples/bit_syntax.xml +++ b/system/doc/programming_examples/bit_syntax.xml @@ -33,7 +33,7 @@ <section> <title>Introduction</title> <p>The complete specification for the bit syntax appears in the - <seealso marker="doc/reference_manual:expressions#bit_syntax">Reference Manual</seealso>.</p> + <seeguide marker="system/reference_manual:expressions#bit_syntax">Reference Manual</seeguide>.</p> <p>In Erlang, a Bin is used for constructing binaries and matching binary patterns. A Bin is written with the following syntax:</p> <code type="none"><![CDATA[ @@ -150,14 +150,14 @@ end.]]></code> </list> <p>Default values are used when specifications are missing. The default values are described in - <seealso marker="#Defaults">Defaults</seealso>.</p> + <seeguide marker="#Defaults">Defaults</seeguide>.</p> <p>The <c>Value</c> part is any expression, when used in binary construction. Used in binary matching, the <c>Value</c> part must be a literal or a variable. For more information about the <c>Value</c> part, see - <seealso marker="#Constructing Binaries and Bitstrings">Constructing Binaries and Bitstrings</seealso> + <seeguide marker="#Constructing Binaries and Bitstrings">Constructing Binaries and Bitstrings</seeguide> and - <seealso marker="#Matching Binaries">Matching Binaries</seealso>.</p> + <seeguide marker="#Matching Binaries">Matching Binaries</seeguide>.</p> <p>The <c>Size</c> part of the segment multiplied by the unit in <c>TypeSpecifierList</c> (described later) gives the number of bits for the segment. In construction, <c>Size</c> is any @@ -168,7 +168,7 @@ end.]]></code> <taglist> <tag>Type</tag> <item>The most commonly used types are <c>integer</c>, <c>float</c>, and <c>binary</c>. - See <seealso marker="doc/reference_manual:expressions#bit_syntax">Bit Syntax Expressions in the Reference Manual</seealso> for a complete description. + See <seeguide marker="system/reference_manual:expressions#bit_syntax">Bit Syntax Expressions in the Reference Manual</seeguide> for a complete description. </item> <tag>Signedness</tag> <item>The signedness specification can be either <c>signed</c> @@ -293,7 +293,7 @@ X:4/little-signed-integer-unit:8</code> an integer, or a floating point literal. Expressions are not allowed.</p> <p><c>Size</c> must be a - <seealso marker="doc/reference_manual:expressions#guard_expressions">guard expression</seealso>, which can use literals and previously bound variables. + <seeguide marker="system/reference_manual:expressions#guard_expressions">guard expression</seeguide>, which can use literals and previously bound variables. The following is not allowed:</p> <code type="none"><![CDATA[ foo(N, <<X:N,T/binary>>) -> diff --git a/system/doc/programming_examples/funs.xmlsrc b/system/doc/programming_examples/funs.xmlsrc index bb519be612..b6dc2da249 100644 --- a/system/doc/programming_examples/funs.xmlsrc +++ b/system/doc/programming_examples/funs.xmlsrc @@ -112,9 +112,9 @@ foreach(fun(Pid) -> Pid ! M end, L)</code> <section> <title>Syntax of Funs</title> - <p>Funs are written with the following syntax (see <seealso - marker="doc/reference_manual:expressions#funs">Fun Expressions - </seealso> for full description):</p> + <p>Funs are written with the following syntax (see <seeguide + marker="system/reference_manual:expressions#funs">Fun Expressions + </seeguide> for full description):</p> <code type="none"> F = fun (Arg1, Arg2, ... ArgN) -> ... diff --git a/system/doc/programming_examples/records.xml b/system/doc/programming_examples/records.xml index 074aa636b4..d74ce22e4e 100644 --- a/system/doc/programming_examples/records.xml +++ b/system/doc/programming_examples/records.xml @@ -92,7 +92,7 @@ person</pre> <p>This is because record definitions are only available at compile time, not at runtime. For details on records in the shell, see the - <seealso marker="stdlib:shell">shell(3)</seealso> + <seeerl marker="stdlib:shell">shell(3)</seeerl> manual page in STDLIB.</p> </section> diff --git a/system/doc/reference_manual/character_set.xml b/system/doc/reference_manual/character_set.xml index ef14bf1372..4d1380afb9 100644 --- a/system/doc/reference_manual/character_set.xml +++ b/system/doc/reference_manual/character_set.xml @@ -105,9 +105,9 @@ handle Unicode. The support was limited to string literals and comments. More about the usage of Unicode in Erlang source files - can be found in <seealso + can be found in <seeguide marker="stdlib:unicode_usage#unicode_in_erlang">STDLIB's User's - Guide</seealso>.</p> + Guide</seeguide>.</p> <p>From Erlang/OTP 20, atoms and function names are also allowed to contain Unicode characters outside the ISO-Latin-1 range. Module names, application names, and node names are still diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml index f5e5e74841..11b95be2b3 100644 --- a/system/doc/reference_manual/code_loading.xml +++ b/system/doc/reference_manual/code_loading.xml @@ -43,7 +43,7 @@ <c>.beam</c>. The compiler can also generate a binary which can be loaded directly.</p> <p>The compiler is located in the module <c>compile</c> (see the - <seealso marker="compiler:compile">compile(3)</seealso> manual page in + <seeerl marker="compiler:compile">compile(3)</seeerl> manual page in Compiler).</p> <pre> compile:file(Module) @@ -52,16 +52,16 @@ compile:file(Module, Options)</pre> both compiles and loads <c>Module</c>.</p> <p>There is also a module <c>make</c>, which provides a set of functions similar to the UNIX type Make functions, see the - <seealso marker="tools:make">make(3)</seealso> + <seeerl marker="tools:make">make(3)</seeerl> manual page in Tools.</p> <p>The compiler can also be accessed from the OS prompt, see the - <seealso marker="erts:erl">erl(1)</seealso> manual page in ERTS.</p> + <seecom marker="erts:erl">erl(1)</seecom> manual page in ERTS.</p> <pre> % erl -compile <input>Module1</input>...<input>ModuleN</input> % erl -make</pre> <p>The <c>erlc</c> program provides an even better way to compile modules from the shell, see the - <seealso marker="erts:erlc">erlc(1)</seealso> manual page in ERTS. + <seecom marker="erts:erlc">erlc(1)</seecom> manual page in ERTS. It understands a number of flags that can be used to define macros, add search paths for include files, and more.</p> @@ -74,7 +74,7 @@ compile:file(Module, Options)</pre> <title>Code Loading</title> <p>The object code must be <em>loaded</em> into the Erlang runtime system. This is handled by the <em>code server</em>, see the - <seealso marker="kernel:code">code(3)</seealso> + <seeerl marker="kernel:code">code(3)</seeerl> manual page in Kernel.</p> <p>The code server loads code according to a code loading strategy, which is either <em>interactive</em> (default) or @@ -82,8 +82,8 @@ compile:file(Module, Options)</pre> a <em>code path</em> and loaded when first referenced. In embedded mode, code is loaded at start-up according to a <em>boot script</em>. This is described in - <seealso marker="doc/system_principles:system_principles#code_loading"> - System Principles </seealso>.</p> + <seeguide marker="system/system_principles:system_principles#code_loading"> + System Principles </seeguide>.</p> </section> <section> diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml index 8e3e181303..35e2ce1c7a 100644 --- a/system/doc/reference_manual/data_types.xml +++ b/system/doc/reference_manual/data_types.xml @@ -99,7 +99,7 @@ phone_number <title>Bit Strings and Binaries</title> <p>A bit string is used to store an area of untyped memory.</p> <p>Bit strings are expressed using the - <seealso marker="expressions#bit_syntax">bit syntax</seealso>.</p> + <seeguide marker="expressions#bit_syntax">bit syntax</seeguide>.</p> <p>Bit strings that consist of a number of bits that are evenly divisible by eight, are called <em>binaries</em></p> <p><em>Examples:</em></p> @@ -111,8 +111,8 @@ phone_number 1> <input><<1:1,0:1>>.</input> <<2:2>></pre> <p>For more examples, - see <seealso marker="doc/programming_examples:bit_syntax"> - Programming Examples</seealso>.</p> + see <seeguide marker="system/programming_examples:bit_syntax"> + Programming Examples</seeguide>.</p> </section> <section> @@ -132,10 +132,10 @@ phone_number #Fun<erl_eval.6.39074546> 2> <input>Fun1(2).</input> 3</pre> - <p>Read more about funs in <seealso marker="expressions#funs"> - Fun Expressions</seealso>. For more examples, see - <seealso marker="doc/programming_examples:funs"> - Programming Examples</seealso>.</p> + <p>Read more about funs in <seeguide marker="expressions#funs"> + Fun Expressions</seeguide>. For more examples, see + <seeguide marker="system/programming_examples:funs"> + Programming Examples</seeguide>.</p> </section> <section> @@ -143,7 +143,7 @@ phone_number <p>A port identifier identifies an Erlang port.</p> <p><c>open_port/2</c>, which is used to create ports, returns a value of this data type.</p> - <p>Read more about ports in <seealso marker="ports">Ports and Port Drivers</seealso>.</p> + <p>Read more about ports in <seeguide marker="ports">Ports and Port Drivers</seeguide>.</p> </section> <section> @@ -179,7 +179,7 @@ loop() -> I am <0.58.0> who_are_you</pre> <p>Read more about processes in - <seealso marker="processes">Processes</seealso>.</p> + <seeguide marker="processes">Processes</seeguide>.</p> </section> <section> @@ -233,10 +233,10 @@ adam 6> <input>map_size(#{}).</input> 0</pre> <p>A collection of maps processing functions can be found in - <seealso marker="stdlib:maps"><c>maps</c></seealso> manual page + <seeerl marker="stdlib:maps"><c>maps</c></seeerl> manual page in STDLIB.</p> - <p>Read more about maps in <seealso marker="expressions#map_expressions"> - Map Expressions</seealso>.</p> + <p>Read more about maps in <seeguide marker="expressions#map_expressions"> + Map Expressions</seeguide>.</p> <note> <p>Maps are considered to be experimental during Erlang/OTP R17.</p> </note> @@ -283,7 +283,7 @@ a 7> <input>length([]).</input> 0</pre> <p>A collection of list processing functions can be found in - the <seealso marker="stdlib:lists">lists</seealso> manual + the <seeerl marker="stdlib:lists">lists</seeerl> manual page in STDLIB.</p> </section> @@ -311,7 +311,7 @@ a expressions are translated to tuple expressions during compilation. Therefore, record expressions are not understood by the shell unless special actions are taken. For details, see the - <seealso marker="stdlib:shell">shell(3)</seealso> manual + <seeerl marker="stdlib:shell">shell(3)</seeerl> manual page in STDLIB).</p> <p><em>Examples:</em></p> <pre> @@ -326,9 +326,9 @@ new(Name, Age) -> 1> <input>person:new(ernie, 44).</input> {person,ernie,44}</pre> <p>Read more about records in - <seealso marker="records">Records</seealso>. More examples can be - found in <seealso marker="doc/programming_examples:records"> - Programming Examples</seealso>.</p> + <seeguide marker="records">Records</seeguide>. More examples can be + found in <seeguide marker="system/programming_examples:records"> + Programming Examples</seeguide>.</p> </section> <section> diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml index b519609717..38cb99dd0d 100644 --- a/system/doc/reference_manual/distributed.xml +++ b/system/doc/reference_manual/distributed.xml @@ -41,17 +41,17 @@ when sending messages, and so on, using registered names.</p> <p>The distribution mechanism is implemented using TCP/IP sockets. How to implement an alternative carrier is described in the - <seealso marker="erts:alt_dist">ERTS User's Guide</seealso>.</p> + <seeguide marker="erts:alt_dist">ERTS User's Guide</seeguide>.</p> <warning> <p> Starting a distributed node without also specifying - <seealso marker="erts:erl#proto_dist"><c>-proto_dist inet_tls</c></seealso> + <seecom marker="erts:erl#proto_dist"><c>-proto_dist inet_tls</c></seecom> will expose the node to attacks that may give the attacker complete access to the node and in extension the cluster. When using un-secure distributed nodes, make sure that the network is configured to keep potential attackers out. - See the <seealso marker="ssl:ssl_distribution"> - Using SSL for Erlang Distribution</seealso> User's Guide + See the <seeguide marker="ssl:ssl_distribution"> + Using SSL for Erlang Distribution</seeguide> User's Guide for details on how to setup a secure distributed node. </p> </warning> @@ -92,7 +92,7 @@ dilbert@uab</pre> node B, and node B has a connection to node C, then node A also tries to connect to node C. This feature can be turned off by using the command-line flag <c>-connect_all false</c>, see the - <seealso marker="erts:erl">erl(1)</seealso> manual page in ERTS.</p> + <seecom marker="erts:erl">erl(1)</seecom> manual page in ERTS.</p> <p>If a node goes down, all connections to that node are removed. Calling <c>erlang:disconnect_node(Node)</c> forces disconnection of a node.</p> @@ -106,7 +106,7 @@ dilbert@uab</pre> started at every host where an Erlang node is started. It is responsible for mapping the symbolic node names to machine addresses. See the - <seealso marker="erts:epmd">epmd(1)</seealso> manual page in ERTS.</p> + <seecom marker="erts:epmd">epmd(1)</seecom> manual page in ERTS.</p> </section> <section> @@ -132,10 +132,10 @@ dilbert@uab</pre> <p>A <em>C node</em> is a C program written to act as a hidden node in a distributed Erlang system. The library <em>Erl_Interface</em> contains functions for this purpose. For more information about - C nodes, see the <seealso marker="erl_interface:ei_users_guide"> - Erl_Interface</seealso> application and - <seealso marker="doc/tutorial:introduction#interoperability tutorial"> - Interoperability Tutorial.</seealso>.</p> + C nodes, see the <seeguide marker="erl_interface:ei_users_guide"> + Erl_Interface</seeguide> application and + <seeguide marker="system/tutorial:introduction#interoperability tutorial"> + Interoperability Tutorial.</seeguide>.</p> </section> <section> @@ -175,7 +175,7 @@ dilbert@uab</pre> way, there is always a fully connected network. If there are nodes with different cookies, this method can be inappropriate and the command-line flag <c>-connect_all false</c> must be set, - see the <seealso marker="erts:erl">erl(1)</seealso> + see the <seecom marker="erts:erl">erl(1)</seecom> manual page in ERTS.</p> <p>The magic cookie of the local node is retrieved by calling <c>erlang:get_cookie()</c>.</p> @@ -184,8 +184,8 @@ dilbert@uab</pre> <section> <title>Distribution BIFs</title> <p>Some useful BIFs for distributed programming - (for more information, see the <seealso marker="erts:erlang"> - erlang(3)</seealso> manual page in ERTS:</p> + (for more information, see the <seeerl marker="erts:erlang"> + erlang(3)</seeerl> manual page in ERTS:</p> <table> <row> <cell align="left" valign="middle"><em>BIF</em></cell> @@ -249,8 +249,8 @@ dilbert@uab</pre> <section> <title>Distribution Command-Line Flags</title> <p>Examples of command-line flags used for distributed programming - (for more information, see the <seealso marker="erts:erl">erl(1) - </seealso> manual page in ERTS:</p> + (for more information, see the <seecom marker="erts:erl">erl(1) + </seecom> manual page in ERTS:</p> <table> <row> <cell align="left" valign="middle"><em>Command-Line Flag</em></cell> diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml index 68c96863f5..f53989489a 100644 --- a/system/doc/reference_manual/errors.xml +++ b/system/doc/reference_manual/errors.xml @@ -77,12 +77,12 @@ <title>Exceptions</title> <p>Exceptions are run-time errors or generated errors and are of three different classes, with different origins. The - <seealso marker="expressions#try">try</seealso> expression + <seeguide marker="expressions#try">try</seeguide> expression can distinguish between the different classes, whereas the - <seealso marker="expressions#catch">catch</seealso> + <seeguide marker="expressions#catch">catch</seeguide> expression cannot. They are described in - <seealso marker="expressions">Expressions - </seealso>.</p> + <seeguide marker="expressions">Expressions + </seeguide>.</p> <table> <row> <cell align="left" valign="middle"><em>Class</em></cell> @@ -105,7 +105,7 @@ <tcaption>Exception Classes.</tcaption> </table> <p>An exception consists of its class, an exit reason - (see <seealso marker="#exit_reasons">Exit Reason</seealso>), + (see <seeguide marker="#exit_reasons">Exit Reason</seeguide>), and a stack trace (which aids in finding the code location of the exception).</p> <p>The stack trace can be be bound to a variable from within @@ -166,17 +166,17 @@ <p>It is possible to prevent run-time errors and other exceptions from causing the process to terminate by using <c>catch</c> or - <c>try</c>, see <seealso marker="expressions"> - Expressions</seealso> about - <seealso marker="expressions#catch">catch</seealso> - and <seealso marker="expressions#try">try</seealso>.</p> + <c>try</c>, see <seeguide marker="expressions"> + Expressions</seeguide> about + <seeguide marker="expressions#catch">catch</seeguide> + and <seeguide marker="expressions#try">try</seeguide>.</p> </section> <section> <title>Error Handling Between Processes</title> <p>Processes can monitor other processes and detect process terminations, see - <seealso marker="processes#errors">Processes</seealso>.</p> + <seeguide marker="processes#errors">Processes</seeguide>.</p> </section> </section> @@ -251,8 +251,8 @@ <row> <cell align="left" valign="middle"><c>system_limit</c></cell> <cell align="left" valign="middle">A system limit has been reached. - See <seealso marker="doc/efficiency_guide:advanced"> - Efficiency Guide</seealso> for information about system limits. + See <seeguide marker="system/efficiency_guide:advanced"> + Efficiency Guide</seeguide> for information about system limits. </cell> </row> <tcaption>Exit Reasons</tcaption> diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 2b9d68e012..fd8f71ed89 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -37,8 +37,8 @@ separate sections: </p> <list type="bulleted"> - <item><p><seealso marker="macros">Preprocessor</seealso></p></item> - <item><p><seealso marker="records">Records</seealso></p></item> + <item><p><seeguide marker="macros">Preprocessor</seeguide></p></item> + <item><p><seeguide marker="records">Records</seeguide></p></item> </list> <section> @@ -82,7 +82,7 @@ Phone_number _ _Height</pre> <p>Variables are bound to values using - <seealso marker="patterns">pattern matching</seealso>. Erlang + <seeguide marker="patterns">pattern matching</seeguide>. Erlang uses <em>single assignment</em>, that is, a variable can only be bound once.</p> <p>The <em>anonymous variable</em> is denoted by underscore (_) and @@ -254,9 +254,9 @@ spawn(m, init, [])</code> <p>Notice that when calling a local function, there is a difference between using the implicitly or fully qualified function name. The latter always refers to the latest version of the module. - See <seealso marker="code_loading">Compilation and Code Loading - </seealso> and <seealso marker="functions#eval"> - Function Evaluation</seealso>.</p> + See <seeguide marker="code_loading">Compilation and Code Loading + </seeguide> and <seeguide marker="functions#eval"> + Function Evaluation</seeguide>.</p> <section> <title>Local Function Names Clashing With Auto-Imported BIFs</title> @@ -974,8 +974,8 @@ M4 = M3#{a := 2, b := 3}. % 'a' and 'b' was added in `M1` and `M2`.</code> <code>#{ K := V } = M</code> <p> Here <c>M</c> is any map. The key <c>K</c> must be a - <seealso marker="#guard_expressions">guard - expression</seealso>, with all variables already bound. + <seeguide marker="#guard_expressions">guard + expression</seeguide>, with all variables already bound. <c>V</c> can be any pattern with either bound or unbound variables. </p> @@ -1072,15 +1072,15 @@ handle_call(change, From, #{ state := start } = S) -> </p> <list> <item> - <seealso marker="erts:erlang#is_map/1">is_map/1</seealso> + <seemfa marker="erts:erlang#is_map/1">is_map/1</seemfa> in the <c>erlang</c> module </item> <item> - <seealso marker="erts:erlang#map_get/2">map_get/2</seealso> + <seemfa marker="erts:erlang#map_get/2">map_get/2</seemfa> in the <c>erlang</c> module </item> <item> - <seealso marker="erts:erlang#map_size/1">map_size/1</seealso> + <seemfa marker="erts:erlang#map_size/1">map_size/1</seemfa> in the <c>erlang</c> module </item> </list> @@ -1116,7 +1116,7 @@ Ei = Value | that is to evaluate to an integer.</p> <p>Used in a bit string matching, <c>Size</c> must be a - <seealso marker="#guard_expressions">guard expression</seealso> + <seeguide marker="#guard_expressions">guard expression</seeguide> that evaluates to an integer. All variables in the guard expression must be already bound.</p> @@ -1254,8 +1254,8 @@ Ei = Value | "<c><![CDATA[B =<<1>>]]></c>" which is a syntax error. The correct way is to write a space after '=': "<c><![CDATA[B= <<1>>]]></c>.</p> <p>More examples are provided in - <seealso marker="doc/programming_examples:bit_syntax"> - Programming Examples</seealso>.</p> + <seeguide marker="system/programming_examples:bit_syntax"> + Programming Examples</seeguide>.</p> </section> <section> @@ -1272,7 +1272,7 @@ end</pre> <p>A fun expression begins with the keyword <c>fun</c> and ends with the keyword <c>end</c>. Between them is to be a function declaration, similar to a - <seealso marker="functions#syntax">regular function declaration</seealso>, + <seeguide marker="functions#syntax">regular function declaration</seeguide>, except that the function name is optional and is to be a variable, if any.</p> <p>Variables in a fun head shadow the function name and both shadow @@ -1311,8 +1311,8 @@ fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end</pre> the code for the module in which it is defined. </p> <p>More examples are provided in - <seealso marker="doc/programming_examples:funs"> - Programming Examples</seealso>.</p> + <seeguide marker="system/programming_examples:funs"> + Programming Examples</seeguide>.</p> </section> <section> @@ -1334,7 +1334,7 @@ catch Expr</code> <c>Term</c> is returned.</p> <p><c>Reason</c> depends on the type of error that occurred, and <c>Stack</c> is the stack of recent function calls, see - <seealso marker="errors#exit_reasons">Exit Reasons</seealso>.</p> + <seeguide marker="errors#exit_reasons">Exit Reasons</seeguide>.</p> <p><em>Examples:</em></p> <pre> 1> <input>catch 1+2.</input> @@ -1372,7 +1372,7 @@ catch ExceptionBodyN end</code> <p>This is an enhancement of - <seealso marker="#catch">catch</seealso>. + <seeguide marker="#catch">catch</seeguide>. It gives the possibility to:</p> <list type="bulleted"> <item>Distinguish between different exception classes.</item> @@ -1433,7 +1433,7 @@ end</code> <p>If the evaluation of <c>Exprs</c> succeeds without an exception, the patterns <c>Pattern</c> are sequentially matched against the result in the same way as for a - <seealso marker="#case">case</seealso> expression, except that if + <seeguide marker="#case">case</seeguide> expression, except that if the matching fails, a <c>try_clause</c> run-time error occurs instead of a <c>case_clause</c>.</p> <p>Only exceptions occurring during the evaluation of <c>Exprs</c> can be @@ -1521,7 +1521,7 @@ end</code> <pre> (Expr)</pre> <p>Parenthesized expressions are useful to override - <seealso marker="#prec">operator precedences</seealso>, + <seeguide marker="#prec">operator precedences</seeguide>, for example, in arithmetic expressions:</p> <pre> 1> <input>1 + 2 * 3.</input> @@ -1591,8 +1591,8 @@ end</pre> 2> <input>[x || is_integer(x)].</input> []</pre> <p>More examples are provided in - <seealso marker="doc/programming_examples:list_comprehensions"> - Programming Examples.</seealso></p> + <seeguide marker="system/programming_examples:list_comprehensions"> + Programming Examples.</seeguide></p> </section> @@ -1635,8 +1635,8 @@ end</pre> <<X>> <= << 1,2,3 >> >>.</input> <<2,4,6>></pre> <p>More examples are provided in - <seealso marker="doc/programming_examples:bit_syntax"> - Programming Examples.</seealso></p> + <seeguide marker="system/programming_examples:bit_syntax"> + Programming Examples.</seeguide></p> </section> <section> diff --git a/system/doc/reference_manual/functions.xml b/system/doc/reference_manual/functions.xml index 863514ee78..948df872f7 100644 --- a/system/doc/reference_manual/functions.xml +++ b/system/doc/reference_manual/functions.xml @@ -61,7 +61,7 @@ Expr1, ..., ExprN</pre> <p>Valid Erlang expressions and guard sequences are described in - <seealso marker="expressions">Expressions</seealso>.</p> + <seeguide marker="expressions">Expressions</seeguide>.</p> <p><em>Example:</em></p> <pre> fact(N) when N>0 -> % first clause head @@ -155,7 +155,7 @@ loop(N) -> <p>The most commonly used BIFs belonging to <c>erlang(3)</c> are <em>auto-imported</em>. They do not need to be prefixed with the module name. Which BIFs that are auto-imported is specified in the - <seealso marker="erts:erlang">erlang(3)</seealso> module in ERTS. + <seeerl marker="erts:erlang">erlang(3)</seeerl> module in ERTS. For example, standard-type conversion BIFs like <c>atom_to_list</c> and BIFs allowed in guards can be called without specifying the module name.</p> diff --git a/system/doc/reference_manual/introduction.xml b/system/doc/reference_manual/introduction.xml index 69e52e0b37..6af58f59ed 100644 --- a/system/doc/reference_manual/introduction.xml +++ b/system/doc/reference_manual/introduction.xml @@ -44,21 +44,21 @@ <p>Information about implementation of Erlang can, for example, be found, in the following:</p> <list type="bulleted"> - <item><p><seealso marker="doc/system_principles:system_principles"> - System Principles</seealso></p> + <item><p><seeguide marker="system/system_principles:system_principles"> + System Principles</seeguide></p> <p>Starting and stopping, boot scripts, code loading, - <seealso marker="doc/system_principles:error_logging"> - logging</seealso>, - <seealso marker="doc/system_principles:create_target"> - creating target systems</seealso></p> + <seeguide marker="system/system_principles:error_logging"> + logging</seeguide>, + <seeguide marker="system/system_principles:create_target"> + creating target systems</seeguide></p> </item> - <item><p><seealso marker="doc/efficiency_guide:advanced"> - Efficiency Guide</seealso></p> + <item><p><seeguide marker="system/efficiency_guide:advanced"> + Efficiency Guide</seeguide></p> <p>Memory consumption, system limits</p> </item> <item><p>ERTS User's Guide</p> - <p><seealso marker="erts:crash_dump">Crash dumps</seealso>, - <seealso marker="erts:driver">drivers</seealso></p> + <p><seeguide marker="erts:crash_dump">Crash dumps</seeguide>, + <seeguide marker="erts:driver">drivers</seeguide></p> </item> </list> </section> @@ -87,7 +87,7 @@ <section> <title>Complete List of BIFs</title> <p>For a complete list of BIFs, their arguments and return values, - see <seealso marker="erts:erlang">erlang(3)</seealso> + see <seeerl marker="erts:erlang">erlang(3)</seeerl> manual page in ERTS.</p> </section> diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml index 8a8d5f3a4c..32efc635c3 100644 --- a/system/doc/reference_manual/macros.xml +++ b/system/doc/reference_manual/macros.xml @@ -58,9 +58,9 @@ <item>The directories given by the <c>include</c> option</item> </list> <p>For details, see the - <seealso marker="erts:erlc">erlc(1)</seealso> manual page + <seecom marker="erts:erlc">erlc(1)</seecom> manual page in ERTS and - <seealso marker="compiler:compile">compile(3)</seealso> + <seeerl marker="compiler:compile">compile(3)</seeerl> manual page in Compiler.</p> <p><em>Examples:</em></p> <pre> @@ -153,7 +153,7 @@ bar(X) -> <tag><c>?OTP_RELEASE</c></tag> <item>The OTP release that the currently executing ERTS application is part of, as an integer. For details, see - <seealso marker="erts:erlang#system_info/1"><c>erlang:system_info(otp_release)</c></seealso>. + <seemfa marker="erts:erlang#system_info/1"><c>erlang:system_info(otp_release)</c></seemfa>. This macro was introduced in OTP release 21.</item> </taglist> </section> diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml index 6f93198ec1..b8f20894b9 100644 --- a/system/doc/reference_manual/modules.xml +++ b/system/doc/reference_manual/modules.xml @@ -45,7 +45,7 @@ fact(N) when N>0 -> % beginning of function declaration fact(0) -> % | 1. % end of function declaration</pre> <p>For a description of function declarations, see - <seealso marker="functions">Function Declaration Syntax</seealso>.</p> + <seeguide marker="functions">Function Declaration Syntax</seeguide>.</p> </section> <section> @@ -64,7 +64,7 @@ fact(0) -> % | <p>Any module attribute can be specified. The attributes are stored in the compiled code and can be retrieved by calling <c>Module:module_info(attributes)</c>, or by using the module - <seealso marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seealso> + <seemfa marker="stdlib:beam_lib#chunks/2">beam_lib(3)</seemfa> in STDLIB.</p> <p>Several module attributes have predefined meanings. @@ -81,7 +81,7 @@ fact(0) -> % | <p>Module declaration, defining the name of the module. The name <c>Module</c>, an atom, is to be same as the file name minus the extension <c>.erl</c>. Otherwise - <seealso marker="code_loading#loading">code loading</seealso> does + <seeguide marker="code_loading#loading">code loading</seeguide> does not work as intended.</p> <p>This attribute is to be specified first and is the only mandatory attribute.</p> @@ -109,14 +109,14 @@ fact(0) -> % | <p>Compiler options. <c>Options</c> is a single option or a list of options. This attribute is added to the option list when - compiling the module. See the <seealso marker="compiler:compile"> - compile(3)</seealso> manual page in Compiler.</p> + compiling the module. See the <seeerl marker="compiler:compile"> + compile(3)</seeerl> manual page in Compiler.</p> </item> <tag><c>-vsn(Vsn).</c></tag> <item> <p>Module version. <c>Vsn</c> is any literal term and can be retrieved using <c>beam_lib:version/1</c>, see the - <seealso marker="stdlib:beam_lib#version/1">beam_lib(3)</seealso> + <seemfa marker="stdlib:beam_lib#version/1">beam_lib(3)</seemfa> manual page in STDLIB.</p> <p>If this attribute is not specified, the version defaults to the MD5 checksum of the module.</p> @@ -126,8 +126,8 @@ fact(0) -> % | <p>This attribute names a function that is to be run automatically when a module is loaded. For more information, see - <seealso marker="code_loading#on_load"> - Running a Function When a Module is Loaded</seealso>.</p> + <seeguide marker="code_loading#on_load"> + Running a Function When a Module is Loaded</seeguide>.</p> </item> </taglist> </section> @@ -161,8 +161,8 @@ behaviour_info(callbacks) -> Callbacks.</pre> extra type information can be used by tools to produce documentation or find discrepancies.</p> <p>Read more about behaviours and callback modules in - <seealso marker="doc/design_principles:spec_proc#behaviours"> - OTP Design Principles</seealso>.</p> + <seeguide marker="system/design_principles:spec_proc#behaviours"> + OTP Design Principles</seeguide>.</p> </section> <section> @@ -173,7 +173,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> -record(Record,Fields).</pre> <p>Record definitions are allowed anywhere in a module, also among the function declarations. - Read more in <seealso marker="records">Records</seealso>.</p> + Read more in <seeguide marker="records">Records</seeguide>.</p> </section> <section> @@ -185,7 +185,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> -include("SomeFile.hrl"). -define(Macro,Replacement).</pre> - <p>Read more in <seealso marker="macros">Preprocessor</seealso>.</p> + <p>Read more in <seeguide marker="macros">Preprocessor</seeguide>.</p> </section> <section> @@ -209,7 +209,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> <pre> -type my_type() :: atom() | integer(). -spec my_function(integer()) -> integer().</pre> - <p>Read more in <seealso marker="typespec">Types and Function specifications</seealso>. + <p>Read more in <seeguide marker="typespec">Types and Function specifications</seeguide>. </p> <p> The description is based on @@ -275,7 +275,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> <p>The list of attributes becomes empty if the module is stripped with the - <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso> + <seemfa marker="stdlib:beam_lib#strip/1">beam_lib(3)</seemfa> module (in STDLIB).</p> </item> @@ -284,7 +284,7 @@ behaviour_info(callbacks) -> Callbacks.</pre> <p>Returns a list of tuples with information about how the module was compiled. This list is empty if the module has been stripped with the - <seealso marker="stdlib:beam_lib#strip/1">beam_lib(3)</seealso> + <seemfa marker="stdlib:beam_lib#strip/1">beam_lib(3)</seemfa> module (in STDLIB).</p> </item> diff --git a/system/doc/reference_manual/patterns.xml b/system/doc/reference_manual/patterns.xml index 57b84b4dfc..e2363cfd0e 100644 --- a/system/doc/reference_manual/patterns.xml +++ b/system/doc/reference_manual/patterns.xml @@ -36,9 +36,9 @@ evaluating a function call, <c>case</c>- <c>receive</c>- <c>try</c>- expressions and match operator (=) expressions.</p> <p>In a pattern matching, a left-hand side - <seealso marker="expressions#pattern">pattern</seealso> is matched + <seeguide marker="expressions#pattern">pattern</seeguide> is matched against a right-hand side - <seealso marker="expressions#term">term</seealso>. If + <seeguide marker="expressions#term">term</seeguide>. If the matching succeeds, any unbound variables in the pattern become bound. If the matching fails, a run-time error occurs.</p> <p><em>Examples:</em></p> diff --git a/system/doc/reference_manual/ports.xml b/system/doc/reference_manual/ports.xml index e96eb428e2..623bfe34e2 100644 --- a/system/doc/reference_manual/ports.xml +++ b/system/doc/reference_manual/ports.xml @@ -30,10 +30,10 @@ <file>ports.xml</file> </header> <p>Examples of how to use ports and port drivers are provided in - <seealso marker="doc/tutorial:introduction#interoperability tutorial"> - Interoperability Tutorial</seealso>. + <seeguide marker="system/tutorial:introduction#interoperability tutorial"> + Interoperability Tutorial</seeguide>. For information about the BIFs mentioned, see the - <seealso marker="erts:erlang">erlang(3)</seealso> manual + <seeerl marker="erts:erlang">erlang(3)</seeerl> manual page in ERTS.</p> <section> @@ -65,11 +65,11 @@ system to leak memory, hang or crash.</p> </warning> <p>For information about port drivers, see the - <seealso marker="erts:erl_driver">erl_driver(4)</seealso> + <seecref marker="erts:erl_driver">erl_driver(4)</seecref> manual page in ERTS, - <seealso marker="erts:driver_entry">driver_entry(1)</seealso> + <seecref marker="erts:driver_entry">driver_entry(1)</seecref> manual page in ERTS, and - <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso> + <seeerl marker="kernel:erl_ddll">erl_ddll(3)</seeerl> manual page in Kernel.</p> </section> diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml index f656d0318e..2b68be4b31 100644 --- a/system/doc/reference_manual/processes.xml +++ b/system/doc/reference_manual/processes.xml @@ -93,7 +93,7 @@ spawn(Module, Name, Args) -> pid() execute terminates normally.</p> <p>A process terminates with an exit reason <c>{Reason,Stack}</c> when a run-time error occurs. See - <seealso marker="errors#exit_reasons">Exit Reasons</seealso>.</p> + <seeguide marker="errors#exit_reasons">Exit Reasons</seeguide>.</p> <p>A process can terminate itself by calling one of the following BIFs:</p> <list type="bulleted"> @@ -105,16 +105,16 @@ spawn(Module, Name, Args) -> pid() <c>exit/1</c> or <c>{Reason,Stack}</c> for the others.</p> <p>A process can also be terminated if it receives an exit signal with another exit reason than <c>normal</c>, see - <seealso marker="#errors">Error Handling</seealso>.</p> + <seeguide marker="#errors">Error Handling</seeguide>.</p> </section> <section> <title>Message Sending</title> <p>Processes communicate by sending and receiving messages. Messages are sent by using - the <seealso marker="expressions#send">send operator !</seealso> + the <seeguide marker="expressions#send">send operator !</seeguide> and received by calling - <seealso marker="expressions#receive">receive</seealso>.</p> + <seeguide marker="expressions#receive">receive</seeguide>.</p> <p>Message sending is asynchronous and safe, the message is guaranteed to eventually reach the recipient, provided that the recipient exists.</p> @@ -131,7 +131,7 @@ spawn(Module, Name, Args) -> pid() two processes. Repeated calls to <c>link(Pid)</c> have no effect.</p> <p>A link can be removed by calling the BIF <c>unlink(Pid)</c>.</p> <p>Links are used to monitor the behaviour of other processes, see - <seealso marker="#errors">Error Handling</seealso>.</p> + <seeguide marker="#errors">Error Handling</seeguide>.</p> </section> <section> @@ -144,16 +144,15 @@ spawn(Module, Name, Args) -> pid() program structures where some processes are supervising other processes, for example, restarting them if they terminate abnormally.</p> - <p>See <seealso marker= - "doc/design_principles:des_princ#otp design principles"> - OTP Design Principles</seealso> for more information about + <p>See <seeguide marker="system/design_principles:des_princ#otp design principles"> + OTP Design Principles</seeguide> for more information about OTP supervision trees, which use this feature.</p> <section> <title>Emitting Exit Signals</title> <p>When a process terminates, it terminates with an - <em>exit reason</em> as explained in <seealso marker="#term"> - Process Termination</seealso>. This exit reason is emitted in + <em>exit reason</em> as explained in <seeguide marker="#term"> + Process Termination</seeguide>. This exit reason is emitted in an <em>exit signal</em> to all linked processes.</p> <p>A process can also call the function <c>exit(Pid,Reason)</c>. This results in an exit signal with exit reason diff --git a/system/doc/reference_manual/records.xml b/system/doc/reference_manual/records.xml index 6b26e2c242..6b5ed82b99 100644 --- a/system/doc/reference_manual/records.xml +++ b/system/doc/reference_manual/records.xml @@ -34,11 +34,11 @@ Record expressions are translated to tuple expressions during compilation. Therefore, record expressions are not understood by the shell unless special actions are taken. For details, see the - <seealso marker="stdlib:shell">shell(3)</seealso> + <seeerl marker="stdlib:shell">shell(3)</seeerl> manual page in STDLIB.</p> <p>More examples are provided in - <seealso marker="doc/programming_examples:records"> - Programming Examples</seealso>.</p> + <seeguide marker="system/programming_examples:records"> + Programming Examples</seeguide>.</p> <section> <title>Defining Records</title> diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml index f517259a64..fa21733bd2 100644 --- a/system/doc/reference_manual/typespec.xml +++ b/system/doc/reference_manual/typespec.xml @@ -335,8 +335,8 @@ | #Erlang_Atom{Fields}</pre> <p> Records are extended to possibly contain type information. - This is described in <seealso marker="#typeinrecords"> - Type Information in Record Declarations</seealso>. + This is described in <seeguide marker="#typeinrecords"> + Type Information in Record Declarations</seeguide>. </p> </section> diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc index a69a02e40c..8ea4551630 100644 --- a/system/doc/system_principles/create_target.xmlsrc +++ b/system/doc/system_principles/create_target.xmlsrc @@ -67,8 +67,8 @@ module <c>target_system.erl</c>, which contains functions for creating and installing a target system. This module is used in the following examples. The source code of the module is listed - in <seealso marker="#listing of target system"> - Listing of target_system.erl</seealso></p> + in <seeguide marker="#listing of target system"> + Listing of target_system.erl</seeguide></p> <section> <marker id="create"/> @@ -76,7 +76,7 @@ <p>It is assumed that you have a working Erlang/OTP system structured according to the OTP design principles.</p> <p><em>Step 1.</em> Create a <c>.rel</c> file (see the - <seealso marker="sasl:rel">rel(4)</seealso> manual page in + <seefile marker="sasl:rel">rel(4)</seefile> manual page in SASL), which specifies the ERTS version and lists all applications that are to be included in the new basic target system. An example is the following <c>mysystem.rel</c> file:</p> @@ -298,7 +298,7 @@ os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FI {sasl, "2.4"}, {pea, "2.0"}]}.</code> <p><em>Step 2.</em> Create the application upgrade file (see the - <seealso marker="sasl:appup">appup(4)</seealso> manual page in + <seefile marker="sasl:appup">appup(4)</seefile> manual page in SASL) for Pea, for example:</p> <code type="none"> %% pea.appup @@ -311,7 +311,7 @@ os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FI <pre> os> <input>erl -pa /home/user/target_system/myapps/pea-2.0/ebin</input></pre> <p><em>Step 4.</em> Create the release upgrade file (see the - <seealso marker="sasl:relup">relup(4)</seealso> manual page in + <seefile marker="sasl:relup">relup(4)</seefile> manual page in SASL):</p> <pre> 1> <input>systools:make_relup("mysystem2",["mysystem"],["mysystem"], @@ -337,8 +337,8 @@ os> <input>erl -pa /home/user/target_system/myapps/pea-2.0/ebin</input></pre> <p>This part is done on the target node, and for this example we want the node to be running as an embedded system with the <c>-heart</c> option, allowing automatic restart of the node. - For more information, see <seealso marker="#start"> - Starting a Target System</seealso>.</p> + For more information, see <seeguide marker="#start"> + Starting a Target System</seeguide>.</p> <p>We add <c>-heart</c> to <c>bin/start</c>:</p> <code type="none"> #!/bin/sh @@ -393,8 +393,8 @@ heart: Tue Apr 1 12:15:11 2014: Executed "/usr/local/erl-target/bin/start /usr/ <c>heart</c>. This is always done when the upgrade involves a change of the applications ERTS, Kernel, STDLIB, or SASL. For more information, see - <seealso marker="upgrade"> - Upgrade when Erlang/OTP has Changed</seealso>. + <seeguide marker="upgrade"> + Upgrade when Erlang/OTP has Changed</seeguide>. </p> <p> The node is accessible through a new pipe: diff --git a/system/doc/system_principles/error_logging.xml b/system/doc/system_principles/error_logging.xml index 9cbf7a2e94..4844cf2002 100644 --- a/system/doc/system_principles/error_logging.xml +++ b/system/doc/system_principles/error_logging.xml @@ -43,13 +43,13 @@ Error in process <0.27.0> with exit value: {{badmatch,[1,2,3]},[{m,f,1},{shell,e the Kernel application.</p> <p>The exit reasons (such as <c>badarg</c>) used by the runtime system are described in - <seealso marker="doc/reference_manual:errors#exit_reasons"> - Errors and Error Handling</seealso>.</p> + <seeguide marker="system/reference_manual:errors#exit_reasons"> + Errors and Error Handling</seeguide>.</p> <p>For information about Logger and its user interface, see the - <seealso marker="kernel:logger">logger(3)</seealso> + <seeerl marker="kernel:logger">logger(3)</seeerl> manual page and - the <seealso marker="kernel:logger_chapter">Logging</seealso> + the <seeguide marker="kernel:logger_chapter">Logging</seeguide> section in the Kernel User's Guide. The system can be configured so that log events are written to file or to tty, or both. In addition, user-defined @@ -72,10 +72,10 @@ Error in process <0.27.0> with exit value: {{badmatch,[1,2,3]},[{m,f,1},{shell,e reports were only logged when the SASL application was running. This behaviour can, for backwards compatibility, be enabled by setting the Kernel configuration - parameter <seealso marker="kernel:kernel_app#logger_sasl_compatible"> - <c>logger_sasl_compatible</c></seealso> + parameter <seeapp marker="kernel:kernel_app#logger_sasl_compatible"> + <c>logger_sasl_compatible</c></seeapp> to <c>true</c>. For more information, see - <seealso marker="sasl:error_logging">SASL Error Logging</seealso> + <seeguide marker="sasl:error_logging">SASL Error Logging</seeguide> in the SASL User's Guide.</p> <pre> % <input>erl -kernel logger_level info</input> diff --git a/system/doc/system_principles/misc.xml b/system/doc/system_principles/misc.xml index 418f783399..0276da9c08 100644 --- a/system/doc/system_principles/misc.xml +++ b/system/doc/system_principles/misc.xml @@ -46,7 +46,7 @@ <title>Supported Releases</title> <p> In general, bugs are only fixed on the latest - <seealso marker="versions#releases_and_patches">release</seealso>, + <seeguide marker="versions#releases_and_patches">release</seeguide>, and new features are introduced in the upcoming release that is under development. However, when we, due to internal reasons, fix bugs on older releases, these will be available and announced as well. @@ -56,7 +56,7 @@ <c>maint</c> and the <c>master</c> branches in our <url href="https://github.com/erlang/otp">git repository</url>. The <c>maint</c> branch contains changes planned for the next - <seealso marker="versions#releases_and_patches">maintenance patch package</seealso> + <seeguide marker="versions#releases_and_patches">maintenance patch package</seeguide> on the latest OTP release and the <c>master</c> branch contain changes planned for the upcoming OTP release. </p> @@ -101,7 +101,7 @@ checksums in order to determine if it can load the code or not. Note that HiPE has some limitations. For more information see the documentation of the - <seealso marker="hipe:HiPE_app">HiPE</seealso> application. + <seeapp marker="hipe:HiPE_app">HiPE</seeapp> application. </p> </item> <tag>APIs</tag> diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml index c66ae786c2..d0c6f59807 100644 --- a/system/doc/system_principles/system_principles.xml +++ b/system/doc/system_principles/system_principles.xml @@ -41,19 +41,19 @@ Erlang/OTP 17 [erts-6.0] [hipe] [smp:8:8] Eshell V6.0 (abort with ^G) 1> </pre> <p><c>erl</c> understands a number of command-line arguments, see - the <seealso marker="erts:erl">erl(1)</seealso> manual page in + the <seecom marker="erts:erl">erl(1)</seecom> manual page in ERTS. Some of them are also described in this chapter.</p> <p>Application programs can access the values of the command-line arguments by calling the function <c>init:get_argument(Key)</c> or <c>init:get_arguments()</c>. See the - <seealso marker="erts:init">init(3)</seealso> manual page in + <seeerl marker="erts:init">init(3)</seeerl> manual page in ERTS.</p> </section> <section> <title>Restarting and Stopping the System</title> <p>The runtime system is halted by calling <c>halt/0,1</c>. For - details, see the <seealso marker="erts:erlang">erlang(3)</seealso> + details, see the <seeerl marker="erts:erlang">erlang(3)</seeerl> manual page in ERTS.</p> <p>The module <c>init</c> contains functions for restarting, rebooting, and stopping the runtime system:</p> @@ -61,7 +61,7 @@ Eshell V6.0 (abort with ^G) init:restart() init:reboot() init:stop()</pre> - <p>For details, see the <seealso marker="erts:init">init(3)</seealso> + <p>For details, see the <seeerl marker="erts:init">init(3)</seeerl> manual page in ERTS.</p> <p>The runtime system terminates if the Erlang shell is terminated.</p> @@ -82,8 +82,8 @@ init:stop()</pre> <pre> % <input>erl -boot start_all</input></pre> <p>If no boot script is specified, it defaults to - <c>ROOT/bin/start</c>, see <seealso marker="#default_boot_scripts"> - Default Boot Scripts</seealso>.</p> + <c>ROOT/bin/start</c>, see <seeguide marker="#default_boot_scripts"> + Default Boot Scripts</seeguide>.</p> <p>The command-line flag <c>-init_debug</c> makes the <c>init</c> process write some debug information while interpreting the boot script:</p> @@ -128,8 +128,8 @@ init:stop()</pre> <title>User-Defined Boot Scripts</title> <p>It is sometimes useful or necessary to create a user-defined boot script. This is true especially when running Erlang in - embedded mode, see <seealso marker="#code_loading"> - Code Loading Strategy</seealso>.</p> + embedded mode, see <seeguide marker="#code_loading"> + Code Loading Strategy</seeguide>.</p> <p>A boot script can be written manually. However, it is recommended to create a boot script by generating it from a release resource file <c>Name.rel</c>, using the function @@ -138,9 +138,9 @@ init:stop()</pre> principles. (The program does not have to be started in terms of OTP applications, but can be plain Erlang).</p> <p>For more information about <c>.rel</c> files, see - <seealso marker="doc/design_principles:release_handling"> - OTP Design Principles</seealso> and the - <seealso marker="sasl:rel">rel(4)</seealso> manual page in + <seeguide marker="system/design_principles:release_handling"> + OTP Design Principles</seeguide> and the + <seefile marker="sasl:rel">rel(4)</seefile> manual page in SASL.</p> <p>The binary boot script file <c>Name.boot</c> is generated from the boot script file <c>Name.script</c>, using the function @@ -201,35 +201,35 @@ init:stop()</pre> <cell align="left" valign="middle">Module</cell> <cell align="left" valign="middle"><c>.erl</c></cell> <cell align="left" valign="middle"> - <seealso marker="doc/reference_manual:modules"> - Erlang Reference Manual</seealso></cell> + <seeguide marker="system/reference_manual:modules"> + Erlang Reference Manual</seeguide></cell> </row> <row> <cell align="left" valign="middle">Include file</cell> <cell align="left" valign="middle"><c>.hrl</c></cell> <cell align="left" valign="middle"> - <seealso marker="doc/reference_manual:modules"> - Erlang Reference Manual</seealso></cell> + <seeguide marker="system/reference_manual:modules"> + Erlang Reference Manual</seeguide></cell> </row> <row> <cell align="left" valign="middle">Release resource file</cell> <cell align="left" valign="middle"><c>.rel</c></cell> <cell align="left" valign="middle"> - <seealso marker="sasl:rel">rel(4)</seealso> + <seefile marker="sasl:rel">rel(4)</seefile> manual page in SASL</cell> </row> <row> <cell align="left" valign="middle">Application resource file</cell> <cell align="left" valign="middle"><c>.app</c></cell> <cell align="left" valign="middle"> - <seealso marker="kernel:app">app(4)</seealso> + <seefile marker="kernel:app">app(4)</seefile> manual page in Kernel</cell> </row> <row> <cell align="left" valign="middle">Boot script</cell> <cell align="left" valign="middle"><c>.script</c></cell> <cell align="left" valign="middle"> - <seealso marker="sasl:script">script(4)</seealso> + <seefile marker="sasl:script">script(4)</seefile> manual page in SASL</cell> </row> <row> @@ -241,21 +241,21 @@ init:stop()</pre> <cell align="left" valign="middle">Configuration file</cell> <cell align="left" valign="middle"><c>.config</c></cell> <cell align="left" valign="middle"> - <seealso marker="kernel:config">config(4)</seealso> + <seefile marker="kernel:config">config(4)</seefile> manual page in Kernel</cell> </row> <row> <cell align="left" valign="middle">Application upgrade file</cell> <cell align="left" valign="middle"><c>.appup</c></cell> <cell align="left" valign="middle"> - <seealso marker="sasl:appup">appup(4)</seealso> + <seefile marker="sasl:appup">appup(4)</seefile> manual page in SASL</cell> </row> <row> <cell align="left" valign="middle">Release upgrade file</cell> <cell align="left" valign="middle"><c>relup</c></cell> <cell align="left" valign="middle"> - <seealso marker="sasl:relup">relup(4)</seealso> + <seefile marker="sasl:relup">relup(4)</seefile> manual page in SASL</cell> </row> <tcaption>File Types</tcaption> diff --git a/system/doc/system_principles/upgrade.xml b/system/doc/system_principles/upgrade.xml index c491bd855e..1a905befdf 100644 --- a/system/doc/system_principles/upgrade.xml +++ b/system/doc/system_principles/upgrade.xml @@ -83,10 +83,10 @@ <c>restart_emulator</c> has no effect as the <c>release_handler</c> will not execute them.</p> <p>For information about the release upgrade file, see the - <seealso marker="sasl:relup">relup(4)</seealso> manual page + <seefile marker="sasl:relup">relup(4)</seefile> manual page in SASL. For more information about upgrade instructions, see the - <seealso marker="sasl:appup">appup(4)</seealso> manual page + <seefile marker="sasl:appup">appup(4)</seefile> manual page in SASL.</p> </section> diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml index 83d8261a3c..c5efc1a6c0 100644 --- a/system/doc/system_principles/versions.xml +++ b/system/doc/system_principles/versions.xml @@ -39,7 +39,7 @@ <p>As of OTP release 17, the OTP release number corresponds to the major part of the OTP version. The OTP version as a concept was introduced in OTP 17. The version scheme used is described in detail in - <seealso marker="#version_scheme">Version Scheme</seealso>.</p> + <seeguide marker="#version_scheme">Version Scheme</seeguide>.</p> <p>OTP of a specific version is a set of applications of specific versions. The application versions identified by an OTP version corresponds to application versions that have been tested together @@ -57,15 +57,15 @@ <p>In an OTP source code tree, the OTP version can be read from the text file <c><OTP source root>/OTP_VERSION</c>. The absolute path to the file can be constructed by calling - <c>filename:join([</c><seealso marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seealso><c>, "OTP_VERSION"])</c>.</p> + <c>filename:join([</c><seemfa marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seemfa><c>, "OTP_VERSION"])</c>.</p> <p>In an installed OTP development system, the OTP version can be read from the text file <c><OTP installation root>/releases/<OTP release number>/OTP_VERSION</c>. The absolute path to the file can by constructed by calling - <c>filename:join([</c><seealso marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seealso><c>, "releases", </c><seealso marker="erts:erlang#system_info_otp_release"><c>erlang:system_info(otp_release)</c></seealso><c>, "OTP_VERSION"]).</c></p> + <c>filename:join([</c><seemfa marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seemfa><c>, "releases", </c><seeerl marker="erts:erlang#system_info_otp_release"><c>erlang:system_info(otp_release)</c></seeerl><c>, "OTP_VERSION"]).</c></p> <p>If the version read from the <c>OTP_VERSION</c> file in a development system has a <c>**</c> suffix, the system has been patched using the - <seealso marker="doc/installation_guide:OTP-PATCH-APPLY"><c>otp_patch_apply</c></seealso> + <seeguide marker="system/installation_guide:OTP-PATCH-APPLY"><c>otp_patch_apply</c></seeguide> tool. In this case, the system consists of application versions from multiple OTP versions. The version preceding the <c>**</c> suffix corresponds to the OTP version of the base system that @@ -73,7 +73,7 @@ other means than <c>otp_patch_apply</c>, the file <c>OTP_VERSION</c> can identify an incorrect OTP version.</p> <p>No <c>OTP_VERSION</c> file is placed in a - <seealso marker="create_target">target system</seealso> created + <seeguide marker="create_target">target system</seeguide> created by OTP tools. This since one easily can create a target system where it is hard to even determine the base OTP version. You can, however, place such a file there if you know the OTP version.</p> @@ -126,7 +126,7 @@ <section> <title>Application Version</title> <p>As of OTP 17.0 application versions use the same - <seealso marker="#version_scheme">version scheme</seealso> as the + <seeguide marker="#version_scheme">version scheme</seeguide> as the OTP version. Application versions part of a release candidate will however not have an <c>-rc<N></c> suffix as the OTP version. Also note that a major increment in an application version does not @@ -140,8 +140,8 @@ <title>Version Scheme</title> <note><p>The version scheme was changed as of OTP 17.0. This implies that application versions used prior to OTP 17.0 do not adhere to this - version scheme. <seealso marker="#otp_17_0_app_versions">A list of - application versions used in OTP 17.0</seealso> is included at the + version scheme. <seeguide marker="#otp_17_0_app_versions">A list of + application versions used in OTP 17.0</seeguide> is included at the end of this section</p></note> <p>In the normal case, a version is constructed as <c><Major>.<Minor>.<Patch></c>, @@ -234,7 +234,7 @@ OTP versions are based on the actual changes in the code and not based on whether the patch was planned or not. For more information see the - <seealso marker="#version_scheme">Version Scheme</seealso> + <seeguide marker="#version_scheme">Version Scheme</seeguide> section above. </p> </section> @@ -251,9 +251,9 @@ more than the version numbers are needed in order to construct the tree. The root of the tree is OTP version 17.0 which is when we introduced the new - <seealso marker="#version_scheme">version scheme</seealso>. The + <seeguide marker="#version_scheme">version scheme</seeguide>. The green versions are normal versions released on the main track. - Old <seealso marker="#releases_and_patches">OTP releases</seealso> + Old <seeguide marker="#releases_and_patches">OTP releases</seeguide> will be maintained for a while on <c>maint</c> branches that have branched off from the main track. Old <c>maint</c> branches always branch off from the main track when the next OTP release is diff --git a/system/doc/tutorial/c_port.xmlsrc b/system/doc/tutorial/c_port.xmlsrc index ff0997fb54..e9a85b2f1d 100644 --- a/system/doc/tutorial/c_port.xmlsrc +++ b/system/doc/tutorial/c_port.xmlsrc @@ -30,7 +30,7 @@ <file>c_port.xml</file> </header> <p>This section outlines an example of how to solve the example - problem in the <seealso marker="example">previous section</seealso> + problem in the <seeguide marker="example">previous section</seeguide> by using a port.</p> <p>The scenario is illustrated in the following figure:</p> <image file="../tutorial/port.gif"> diff --git a/system/doc/tutorial/c_portdriver.xmlsrc b/system/doc/tutorial/c_portdriver.xmlsrc index c4cf6daa3b..47bf34d3d5 100644 --- a/system/doc/tutorial/c_portdriver.xmlsrc +++ b/system/doc/tutorial/c_portdriver.xmlsrc @@ -30,7 +30,7 @@ <file>c_portdriver.xml</file> </header> <p>This section outlines an example of how to solve the example problem - in <seealso marker="example">Problem Example</seealso> + in <seeguide marker="example">Problem Example</seeguide> by using a linked-in port driver.</p> <p>A port driver is a linked-in driver that is accessible as a port from an Erlang program. It is a shared library (SO in UNIX, DLL in diff --git a/system/doc/tutorial/cnode.xmlsrc b/system/doc/tutorial/cnode.xmlsrc index b53bbfe550..bbea3e129a 100644 --- a/system/doc/tutorial/cnode.xmlsrc +++ b/system/doc/tutorial/cnode.xmlsrc @@ -30,8 +30,8 @@ <file>cnode.xml</file> </header> <p>The reader is referred to - <seealso marker="erl_interface:ei_users_guide"> - the erl_interface users guide</seealso> for information about how + <seeguide marker="erl_interface:ei_users_guide"> + the erl_interface users guide</seeguide> for information about how to create C nodes.</p> <!-- Commented out because it uses the removed erl_* functions. Should be updated to use ei_* functions instead. @@ -42,12 +42,12 @@ been removed as of OTP version 23. The <c>erl_*</c> functions are replaced by the <c>ei_*</c> functions in the erl_interface application. The reader is therefore referred to - <seealso marker="erl_interface:ei_users_guide"> - the erl_interface users guide</seealso> for information about how + <seeguide marker="erl_interface:ei_users_guide"> + the erl_interface users guide</seeguide> for information about how to create C nodes until this tutorial has got updated.</p></note> <p>This section outlines an example of how to solve the example - problem in <seealso marker="example">Problem Example</seealso> + problem in <seeguide marker="example">Problem Example</seeguide> by using a C node. Notice that a C node is not typically used for solving simple problems like this, a port is sufficient.</p> @@ -130,8 +130,8 @@ fd = erl_connect("e1@idril");</pre> (call <c>bind()</c> and <c>listen()</c>) listening to a certain port number <c>port</c>. It then publishes its name and port number with <c>epmd</c>, the Erlang port mapper - daemon. For details, see the <seealso - marker="erts:epmd">epmd</seealso> manual page in ERTS:</p> + daemon. For details, see the <seecom + marker="erts:epmd">epmd</seecom> manual page in ERTS:</p> <pre> erl_publish(port);</pre> <p>Now the C node server can accept connections from Erlang nodes:</p> diff --git a/system/doc/tutorial/erl_interface.xmlsrc b/system/doc/tutorial/erl_interface.xmlsrc index ce2dfa9d18..956e515ca7 100644 --- a/system/doc/tutorial/erl_interface.xmlsrc +++ b/system/doc/tutorial/erl_interface.xmlsrc @@ -31,9 +31,9 @@ </header> <p>This section outlines an example of how to solve the example - problem in <seealso marker="example">Problem Example</seealso> by + problem in <seeguide marker="example">Problem Example</seeguide> by using a port and Erl_Interface. It is necessary to read the port - example in <seealso marker="c_port">Ports</seealso> before reading + example in <seeguide marker="c_port">Ports</seeguide> before reading this section.</p> <section> @@ -42,8 +42,8 @@ with a C program over a plain port with home made encoding:</p> <codeinclude file="complex1.erl" type="erl"/> <p>There are two differences when using Erl_Interface on the C - side compared to the example in <seealso marker="c_port"> - Ports</seealso>, using only the plain port:</p> + side compared to the example in <seeguide marker="c_port"> + Ports</seeguide>, using only the plain port:</p> <list type="bulleted"> <item>As Erl_Interface operates on the Erlang external term format, the port must be set to use binaries.</item> @@ -87,7 +87,7 @@ end</pre> <codeinclude file="ei.c" type="c"/> <p>The following functions, <c>read_cmd()</c> and <c>write_cmd()</c>, from the <c>erl_comm.c</c> example in - <seealso marker="c_port">Ports</seealso> can still be + <seeguide marker="c_port">Ports</seeguide> can still be used for reading from and writing to the port: </p> <codeinclude file="erl_comm.c" type="c"/> diff --git a/system/doc/tutorial/nif.xmlsrc b/system/doc/tutorial/nif.xmlsrc index ccd49b228d..637b764c66 100644 --- a/system/doc/tutorial/nif.xmlsrc +++ b/system/doc/tutorial/nif.xmlsrc @@ -30,7 +30,7 @@ <file>nif.xml</file> </header> <p>This section outlines an example of how to solve the example - problem in <seealso marker="example">Problem Example</seealso> + problem in <seeguide marker="example">Problem Example</seeguide> by using Native Implemented Functions (NIFs).</p> <p>NIFs were introduced in Erlang/OTP R13B03 as an experimental feature. It is a simpler and more efficient way of calling C-code diff --git a/system/doc/tutorial/overview.xml b/system/doc/tutorial/overview.xml index c7bde25340..bb08839c9c 100644 --- a/system/doc/tutorial/overview.xml +++ b/system/doc/tutorial/overview.xml @@ -52,22 +52,22 @@ for Erlang-Erlang communication. It can also be used for communication between Erlang and C, if the C program is implemented as a C node, see - <seealso marker="#cnode">C and Java Libraries</seealso>.</p> + <seeguide marker="#cnode">C and Java Libraries</seeguide>.</p> <p><em>Where to read more:</em> Distributed Erlang and some distributed programming techniques are described in the Erlang book.</p> - <p>For more information, see <seealso - marker="doc/getting_started:conc_prog#Distributed Programming"> - Distributed Programming.</seealso></p> + <p>For more information, see <seeguide + marker="system/getting_started:conc_prog#Distributed Programming"> + Distributed Programming.</seeguide></p> <p>Relevant manual pages are the following:</p> <list type="bulleted"> - <item><seealso marker="erts:erlang">erlang</seealso> manual page in ERTS + <item><seeerl marker="erts:erlang">erlang</seeerl> manual page in ERTS (describes the BIFs)</item> - <item><seealso marker="kernel:global">global</seealso> manual page in Kernel</item> - <item><seealso marker="kernel:net_adm">net_adm</seealso> manual page in Kernel</item> - <item><seealso marker="kernel:pg">pg</seealso> manual page in Kernel</item> - <item><seealso marker="kernel:rpc">rpc</seealso> manual page in Kernel</item> - <item><seealso marker="stdlib:pool">pool</seealso> manual page in STDLIB</item> - <item><seealso marker="stdlib:slave">slave</seealso> manual page in STDLIB</item> + <item><seeerl marker="kernel:global">global</seeerl> manual page in Kernel</item> + <item><seeerl marker="kernel:net_adm">net_adm</seeerl> manual page in Kernel</item> + <item><seeerl marker="kernel:pg">pg</seeerl> manual page in Kernel</item> + <item><seeerl marker="kernel:rpc">rpc</seeerl> manual page in Kernel</item> + <item><seeerl marker="stdlib:pool">pool</seeerl> manual page in STDLIB</item> + <item><seeerl marker="stdlib:slave">slave</seeerl> manual page in STDLIB</item> </list> </section> @@ -109,13 +109,13 @@ "Miscellaneous Items" of the Erlang book. Linked-in drivers are described in Appendix E.</p> <p>The BIF <c>open_port/2</c> is documented in the - <seealso marker="erts:erlang">erlang</seealso> manual page in + <seeerl marker="erts:erlang">erlang</seeerl> manual page in ERTS.</p> <p>For linked-in drivers, the programmer needs to read the - <seealso marker="kernel:erl_ddll">erl_ddll</seealso> manual + <seeerl marker="kernel:erl_ddll">erl_ddll</seeerl> manual page in Kernel.</p> - <p><em>Examples:</em> Port example in <seealso marker="c_port"> - Ports</seealso>.</p> + <p><em>Examples:</em> Port example in <seeguide marker="c_port"> + Ports</seeguide>.</p> </section> </section> @@ -147,7 +147,7 @@ Term = binary_to_term(Binary)</pre> R5B, and earlier versions, the information is part of the Kernel application.</p> </section> <p><em>Examples:</em> Erl_Interface example in - <seealso marker="erl_interface">Erl_Interface</seealso>.</p> + <seeguide marker="erl_interface">Erl_Interface</seeguide>.</p> <marker id="cnode"></marker> <section> @@ -164,14 +164,14 @@ Term = binary_to_term(Binary)</pre> better choice than Erlang due to memory limitations or application characteristics, or both.</p> <p><em>Where to read more:</em> See the <c>ei_connect</c> part - of the <seealso marker="erl_interface">Erl_Interface</seealso> + of the <seeguide marker="erl_interface">Erl_Interface</seeguide> documentation. The programmer also needs to be familiar with - TCP/IP sockets, see Sockets in <seealso - marker="#sockets">Standard Protocols</seealso> and Distributed - Erlang in <seealso marker="#dist">Built-In - Mechanisms</seealso>.</p> - <p><em>Example:</em> C node example in <seealso marker="cnode"> - C Nodes</seealso>.</p> + TCP/IP sockets, see Sockets in <seeguide + marker="#sockets">Standard Protocols</seeguide> and Distributed + Erlang in <seeguide marker="#dist">Built-In + Mechanisms</seeguide>.</p> + <p><em>Example:</em> C node example in <seeguide marker="cnode"> + C Nodes</seeguide>.</p> </section> <section> @@ -220,9 +220,9 @@ Term = binary_to_term(Binary)</pre> detailed knowledge about the socket concept.</p> <p><em>When to use:</em> For programs running on the same or on another machine than the Erlang program.</p> - <p><em>Where to read more:</em> See the <seealso - marker="kernel:gen_tcp">gen_tcp</seealso> and the <seealso - marker="kernel:gen_udp">gen_udp</seealso> manual pages in + <p><em>Where to read more:</em> See the <seeerl + marker="kernel:gen_tcp">gen_tcp</seeerl> and the <seeerl + marker="kernel:gen_udp">gen_udp</seeerl> manual pages in Kernel.</p> </section> </section> |