Merge pull request #98084 from turion/patch-5

agda.section.md: Fix header and enumeration

1 files changed, 22 insertions, 17 deletions

diff --git a/doc/languages-frameworks/agda.section.md b/doc/languages-frameworks/agda.section.md
index 9ce046d05b6f..5ba4e285f424 100644
--- a/doc/languages-frameworks/agda.section.md
+++ b/doc/languages-frameworks/agda.section.md
@@ -12,12 +12,13 @@ Agda can be installed from `agda`:
 $ nix-env -iA agda
 ```
 
-To use agda with libraries, the `agda.withPackages` function can be used. This function either takes:
-+ A list of packages,
-+ or a function which returns a list of packages when given the `agdaPackages` attribute set,
-+ or an attribute set containing a list of packages and a GHC derivation for compilation (see below).
+To use Agda with libraries, the `agda.withPackages` function can be used. This function either takes:
 
-For example, suppose we wanted a version of agda which has access to the standard library. This can be obtained with the expressions:
+* A list of packages,
+* or a function which returns a list of packages when given the `agdaPackages` attribute set,
+* or an attribute set containing a list of packages and a GHC derivation for compilation (see below).
+
+For example, suppose we wanted a version of Agda which has access to the standard library. This can be obtained with the expressions:
 
 ```
 agda.withPackages [ agdaPackages.standard-library ]
@@ -33,18 +34,19 @@ or can be called as in the [Compiling Agda](#compiling-agda) section.
 
 If you want to use a library in your home directory (for instance if it is a development version) then typecheck it manually (using `agda.withPackages` if necessary) and then override the `src` attribute of the package to point to your local repository.
 
-Agda will not by default use these libraries. To tell agda to use the library we have some options:
-- Call `agda` with the library flag:
+Agda will not by default use these libraries. To tell Agda to use the library we have some options:
+
+* Call `agda` with the library flag:
 ```
 $ agda -l standard-library -i . MyFile.agda
 ```
-- Write a `my-library.agda-lib` file for the project you are working on which may look like:
+* Write a `my-library.agda-lib` file for the project you are working on which may look like:
 ```
 name: my-library
 include: .
 depend: standard-library
 ```
-- Create the file `~/.agda/defaults` and add any libraries you want to use by default.
+* Create the file `~/.agda/defaults` and add any libraries you want to use by default.
 
 More information can be found in the [official Agda documentation on library management](https://agda.readthedocs.io/en/v2.6.1/tools/package-system.html).
 
@@ -60,12 +62,13 @@ agda.withPackages {
 ```
 
 ## Writing Agda packages
-To write a nix derivation for an agda library, first check that the library has a `*.agda-lib` file.
+To write a nix derivation for an Agda library, first check that the library has a `*.agda-lib` file.
 
 A derivation can then be written using `agdaPackages.mkDerivation`. This has similar arguments to `stdenv.mkDerivation` with the following additions:
-+ `everythingFile` can be used to specify the location of the `Everything.agda` file, defaulting to `./Everything.agda`. If this file does not exist then either it should be patched in or the `buildPhase` should be overridden (see below).
-+ `libraryName` should be the name that appears in the `*.agda-lib` file, defaulting to `pname`.
-+ `libraryFile` should be the file name of the `*.agda-lib` file, defaulting to `${libraryName}.agda-lib`.
+
+* `everythingFile` can be used to specify the location of the `Everything.agda` file, defaulting to `./Everything.agda`. If this file does not exist then either it should be patched in or the `buildPhase` should be overridden (see below).
+* `libraryName` should be the name that appears in the `*.agda-lib` file, defaulting to `pname`.
+* `libraryFile` should be the file name of the `*.agda-lib` file, defaulting to `${libraryName}.agda-lib`.
 
 ### Building Agda packages
 The default build phase for `agdaPackages.mkDerivation` simply runs `agda` on the `Everything.agda` file.
@@ -74,12 +77,14 @@ Additionally, a `preBuild` or `configurePhase` can be used if there are steps th
 `agda` and the Agda libraries contained in `buildInputs` are made available during the build phase.
 
 ### Installing Agda packages
-The default install phase copies agda source files, agda interface files (`*.agdai`) and `*.agda-lib` files to the output directory.
+The default install phase copies Agda source files, Agda interface files (`*.agdai`) and `*.agda-lib` files to the output directory.
 This can be overridden.
 
-By default, agda sources are files ending on  `.agda`, or literate agda files ending on `.lagda`, `.lagda.tex`, `.lagda.org`, `.lagda.md`, `.lagda.rst`. The list of recognised agda source extensions can be extended by setting the `extraExtensions` config variable.
+By default, Agda sources are files ending on `.agda`, or literate Agda files ending on `.lagda`, `.lagda.tex`, `.lagda.org`, `.lagda.md`, `.lagda.rst`. The list of recognised Agda source extensions can be extended by setting the `extraExtensions` config variable.
+
+## Adding Agda packages to Nixpkgs
 
-To add an agda package to `nixpkgs`, the derivation should be written to `pkgs/development/libraries/agda/${library-name}/` and an entry should be added to `pkgs/top-level/agda-packages.nix`. Here it is called in a scope with access to all other agda libraries, so the top line of the `default.nix` can look like:
+To add an Agda package to `nixpkgs`, the derivation should be written to `pkgs/development/libraries/agda/${library-name}/` and an entry should be added to `pkgs/top-level/agda-packages.nix`. Here it is called in a scope with access to all other Agda libraries, so the top line of the `default.nix` can look like:
 ```
 { mkDerivation, standard-library, fetchFromGitHub }:
 ```
@@ -103,4 +108,4 @@ mkDerivation {
 ```
 This library has a file called `.agda-lib`, and so we give an empty string to `libraryFile` as nothing precedes `.agda-lib` in the filename. This file contains `name: IAL-1.3`, and so we let `libraryName =  "IAL-1.3"`. This library does not use an `Everything.agda` file and instead has a Makefile, so there is no need to set `everythingFile` and we set a custom `buildPhase`.
 
-When writing an agda package it is essential to make sure that no `.agda-lib` file gets added to the store as a single file (for example by using `writeText`). This causes agda to think that the nix store is a agda library and it will attempt to write to it whenever it typechecks something. See [https://github.com/agda/agda/issues/4613](https://github.com/agda/agda/issues/4613).
+When writing an Agda package it is essential to make sure that no `.agda-lib` file gets added to the store as a single file (for example by using `writeText`). This causes Agda to think that the nix store is a Agda library and it will attempt to write to it whenever it typechecks something. See [https://github.com/agda/agda/issues/4613](https://github.com/agda/agda/issues/4613).