Change:
This issue tracks the conversion of from Docbook to CommonMark per . If you intend to work on this conversion, please comment below! in this issue that you intend to work on it. (Please also post if you stop working on it) a new branch of nixpkgs master. : change to . to . the contents from Docbook to . Use existing sections for inspiration. from the folder to build the manual. the manual on your computer at after running from folder: it looks good, submit a PR and reference this issue.
Hi I can look at this conversion.

Discussion:
<ins> # BEAM Languages (Erlang, Elixir & LFE) {#sec-beam} ## Introduction {#beam-introduction} In this document and related Nix expressions, we use the term, *BEAM*, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction. ## Structure {#beam-structure} All BEAM-related expressions are available via the top-level `beam` attribute, which includes: - `interpreters`: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (`beam.interpreters.erlangR19`, etc), Elixir (`beam.interpreters.elixir`) and LFE (`beam.interpreters.lfe`). - `packages`: a set of package builders (Mix and rebar3), each compiled with a specific Erlang/OTP version, e.g.  `beam.packages.erlangR19`. The default Erlang compiler, defined by `beam.interpreters.erlang`, is aliased as `erlang`. The default BEAM package set is defined by `beam.packages.erlang` and aliased at the top level as `beamPackages`. To create a package builder built with a custom Erlang version, use the lambda, `beam.packagesWith`, which accepts an Erlang/OTP derivation and produces a package builder similar to `beam.packages.erlang`. Many Erlang/OTP distributions available in `beam.interpreters` have versions with ODBC and/or Java enabled or without wx (no observer support). For example, there's `beam.interpreters.erlangR22_odbc_javac`, which corresponds to `beam.interpreters.erlangR22` and `beam.interpreters.erlangR22_nox`, which corresponds to `beam.interpreters.erlangR22`. ## Build Tools {#build-tools} ### Rebar3 {#build-tools-rebar3} We provide a version of Rebar3, under `rebar3`. We also provide a helper to fetch Rebar3 dependencies from a lockfile under `fetchRebar3Deps`. ### Mix & Erlang.mk {#build-tools-other} Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the `buildMix` and `buildErlangMk` derivations, respectively. ## How to Install BEAM Packages {#how-to-install-beam-packages} BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. To install any of those builders into your profile, refer to them by their attribute path `beamPackages.rebar3`: ```ShellSession $ nix-env -f "<nixpkgs>" -iA beamPackages.rebar3 ``` ## Packaging BEAM Applications {#packaging-beam-applications} ### Erlang Applications {#packaging-erlang-applications} #### Rebar3 Packages {#rebar3-packages} The Nix function, `buildRebar3`, defined in `beam.packages.erlang.buildRebar3` and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project. If a package needs to compile native code via Rebar3's port compilation mechanism, add `compilePort = true;` to the derivation. #### Erlang.mk Packages {#erlang-mk-packages} Erlang.mk functions similarly to Rebar3, except we use `buildErlangMk` instead of `buildRebar3`. #### Mix Packages {#mix-packages} Mix functions similarly to Rebar3, except we use `buildMix` instead of `buildRebar3`. Alternatively, we can use `buildHex` as a shortcut: ## How to Develop {#how-to-develop} ### Creating a Shell {#creating-a-shell} Usually, we need to create a `shell.nix` file and do our development inside of the environment specified therein. Just install your version of erlang and other interpreter, and then user your normal build tools.  As an example with elixir: ```nix { pkgs ? import "<nixpkgs"> {} }: with pkgs; let elixir = beam.packages.erlangR22.elixir_1_9; in mkShell { buildInputs = [ elixir ]; ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include"; } ``` #### Building in a Shell (for Mix Projects) {#building-in-a-shell} Using a `shell.nix` as described (see <xref linkend="creating-a-shell"/>) should just work. </ins>

<del> <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-beam"> <title>BEAM Languages (Erlang, Elixir &amp; LFE)</title> <section xml:id="beam-introduction"> <title>Introduction</title> <para> In this document and related Nix expressions, we use the term, <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction. </para> </section> <section xml:id="beam-structure"> <title>Structure</title> <para> All BEAM-related expressions are available via the top-level <literal>beam</literal> attribute, which includes: </para> <itemizedlist> <listitem> <para> <literal>interpreters</literal>: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir (<literal>beam.interpreters.elixir</literal>) and LFE (<literal>beam.interpreters.lfe</literal>). </para> </listitem> <listitem> <para> <literal>packages</literal>: a set of package builders (Mix and rebar3), each compiled with a specific Erlang/OTP version, e.g. <literal>beam.packages.erlangR19</literal>. </para> </listitem> </itemizedlist> <para> The default Erlang compiler, defined by <literal>beam.interpreters.erlang</literal>, is aliased as <literal>erlang</literal>. The default BEAM package set is defined by <literal>beam.packages.erlang</literal> and aliased at the top level as <literal>beamPackages</literal>. </para> <para> To create a package builder built with a custom Erlang version, use the lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation and produces a package builder similar to <literal>beam.packages.erlang</literal>. </para> <para> Many Erlang/OTP distributions available in <literal>beam.interpreters</literal> have versions with ODBC and/or Java enabled or without wx (no observer support). For example, there's <literal>beam.interpreters.erlangR22_odbc_javac</literal>, which corresponds to <literal>beam.interpreters.erlangR22</literal> and <literal>beam.interpreters.erlangR22_nox</literal>, which corresponds to <literal>beam.interpreters.erlangR22</literal>. </para> </section> <section xml:id="build-tools"> <title>Build Tools</title> <section xml:id="build-tools-rebar3"> <title>Rebar3</title> <para> We provide a version of Rebar3, under <literal>rebar3</literal>. We also provide a helper to fetch Rebar3 dependencies from a lockfile under <literal>fetchRebar3Deps</literal>. </para> </section> <section xml:id="build-tools-other"> <title>Mix &amp; Erlang.mk</title> <para> Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the <literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations, respectively. </para> </section> </section> <section xml:id="how-to-install-beam-packages"> <title>How to Install BEAM Packages</title> <para> BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. To install any of those builders into your profile, refer to them by their attribute path <literal>beamPackages.rebar3</literal>: </para> <screen> <prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.rebar3 </screen> </section> <section xml:id="packaging-beam-applications"> <title>Packaging BEAM Applications</title> <section  xml:id="packaging-erlang-applications"> <title>Erlang Applications</title> <section xml:id="rebar3-packages"> <title>Rebar3 Packages</title> <para> The Nix function, <literal>buildRebar3</literal>, defined in <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project. </para> <para> If a package needs to compile native code via Rebar3's port compilation mechanism, add <literal>compilePort = true;</literal> to the derivation. </para> </section> <section xml:id="erlang-mk-packages"> <title>Erlang.mk Packages</title> <para> Erlang.mk functions similarly to Rebar3, except we use <literal>buildErlangMk</literal> instead of <literal>buildRebar3</literal>. </para> </section> <section xml:id="mix-packages"> <title>Mix Packages</title> <para> Mix functions similarly to Rebar3, except we use <literal>buildMix</literal> instead of <literal>buildRebar3</literal>. </para> <para> Alternatively, we can use <literal>buildHex</literal> as a shortcut: </para> </section> </section> </section> <section xml:id="how-to-develop"> <title>How to Develop</title> <section xml:id="creating-a-shell"> <title>Creating a Shell</title> <para> Usually, we need to create a <literal>shell.nix</literal> file and do our development inside of the environment specified therein. Just install your version of erlang and other interpreter, and then user your normal build tools. As an example with elixir: </para> <programlisting> { pkgs ? import &quot;&lt;nixpkgs&quot;&gt; {} }: with pkgs; let elixir = beam.packages.erlangR22.elixir_1_9; in mkShell { buildInputs = [ elixir ]; ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include"; } </programlisting> <section xml:id="building-in-a-shell"> <title>Building in a Shell (for Mix Projects)</title> <para> Using a <literal>shell.nix</literal> as described (see <xref linkend="creating-a-shell"/>) should just work. </para> </section> </section> </section> </section> </del>

</para> <xi:include href="agda.section.xml" /> <xi:include href="android.section.xml" /> <del> <xi:include href="beam.xml" /> </del> <ins> <xi:include href="beam.section.xml" /> </ins> <xi:include href="bower.xml" /> <xi:include href="coq.xml" /> <xi:include href="crystal.section.xml" />