pkgs.writers: improve documentation on {makeScriptWriter,makeScriptWriterBin}

in

rec {

  /**

    A generic function that returns a derivation which, when beeing built outputs the script in an executable format.

    `makeScriptWriter` returns a derivation which creates an executable script.

    # Inputs

    config (AttrSet)

    : `interpreter` (String)

      : the interpreter to use for the script

      : the [interpreter](https://en.wikipedia.org/wiki/Shebang_(Unix)) to use for the script.

    : `check` (String)

      : A command to check the script. I.e. some linting check.

      : A command to check the script. For example, this could be a linting check.

    : `makeWrapperArgs` (Optional, [ String ], Default: [])

      : Arguments forwarded to (`makeWrapper`)[#fun-makeWrapper]

      : Arguments forwarded to (`makeWrapper`)[#fun-makeWrapper].

    `nameOrPath` (String)

    : The name of the script or the path to the script.

      When a `string` starting with "/" is passed, the script will be created at the specified path in $out.

      I.e. `"/bin/hello"` will create a script at `$out/bin/hello`.

      Any other `string` is interpreted as filename.

      It must be a simple unix filename starting with a letter, digit, dot, or underscore.

      Any other `string` is interpreted as a filename.

      It must be a [POSIX filename](https://en.wikipedia.org/wiki/Filename) starting with a letter, digit, dot, or underscore.

      Spaces or special characters are not allowed.

    `content` (String)

    This function is used as base implementation for other high-level writer functions.

    For example, `writeBash` can (roughly) be implemented as:

    ```nix

    writeBash = makeScriptWriter { interpreter = "${pkgs.bash}/bin/bash"; }

    ```

      name = last (builtins.split "/" nameOrPath);

      path = if nameIsPath then nameOrPath else "/bin/${name}";

      # The inner derivation which creates the executable under $out/bin (never at $out directly)

      # This is required in order to support wrapping, as wrapped programs consist of at least two files: the executable and the wrapper.

      # This is required in order to support wrapping, as wrapped programs consist of

      # at least two files: the executable and the wrapper.

      inner =

        pkgs.runCommandLocal name

          (

      '';

  /**

    This is a generic function that returns a derivation which, when built, compiles the given script into an executable format.

    `makeBinWriter` returns a derivation which compiles the given script into an executable format.

    :::{.note}

    This function is the base implementation for other compile language `writers`.

    i.e. `writeHaskell`, `writeRust`.

    This function is the base implementation for other compile language `writers`, such as `writeHaskell` and `writeRust`.

    :::

    # Inputs

      : The script that compiles the given content into an executable.

    : `strip` (Boolean, Default: true)

      : Whether to strip the executable or not.

      : Whether to [strip](https://nixos.org/manual/nixpkgs/stable/#ssec-fixup-phase) the executable or not.

    : `makeWrapperArgs` (Optional, [ String ], Default: [])

      : Arguments forwarded to (`makeWrapper`)[#fun-makeWrapper]

    : The name of the script or the path to the script.

      When a `string` starting with "/" is passed, the script will be created at the specified path in $out.

      I.e. `"/bin/hello"` will create a script at `$out/bin/hello`.

      For example, `"/bin/hello"` will create a script at `$out/bin/hello`.

      Any other `string` is interpreted as filename.

      It must be a simple unix filename starting with a letter, digit, dot, or underscore.

      Any other `string` is interpreted as a filename.

      It must be a [POSIX filename](https://en.wikipedia.org/wiki/Filename) starting with a letter, digit, dot, or underscore.

      Spaces or special characters are not allowed.

    # Examples