Unverified Commit aca44fe2 authored by Vincenzo Mantova's avatar Vincenzo Mantova Committed by GitHub
Browse files

texlive: document new texlive.withPackages interface (#265658)

parent 1dab6eb2
Loading
Loading
Loading
Loading
+40 −0
Original line number Diff line number Diff line
@@ -2,6 +2,46 @@

Since release 15.09 there is a new TeX Live packaging that lives entirely under attribute `texlive`.

## User's guide (experimental new interface) {#sec-language-texlive-user-guide-experimental}

Release 23.11 ships with a new interface that will eventually replace `texlive.combine`.

- For basic usage, use some of the prebuilt environments available at the top level, such as `texliveBasic`, `texliveSmall`. For the full list of prebuilt environments, inspect `texlive.schemes`.

- Packages cannot be used directly but must be assembled in an environment. To create or add packages to an environment, use
  ```nix
  texliveSmall.withPackages (ps: with ps; [ collection-langkorean algorithms cm-super ])
  ```
  The function `withPackages` can be called multiple times to add more packages.

  - **Note.** Within Nixpkgs, packages should only use prebuilt environments as inputs, such as `texliveSmall` or `texliveInfraOnly`, and should not depend directly on `texlive`. Further dependencies should be added by calling `withPackages`. This is to ensure that there is a consistent and simple way to override the inputs.

- `texlive.withPackages` uses the same logic as `buildEnv`. Only parts of a package are installed in an environment: its 'runtime' files (`tex` output), binaries (`out` output), and support files (`tlpkg` output). Moreover, man and info pages are assembled into separate `man` and `info` outputs. To add only the TeX files of a package, or its documentation (`texdoc` output), just specify the outputs:
  ```nix
  texlive.withPackages (ps: with ps; [
    texdoc # recommended package to navigate the documentation
    perlPackages.LaTeXML.tex # tex files of LaTeXML, omit binaries
    cm-super
    cm-super.texdoc # documentation of cm-super
  ])
  ```

- All packages distributed by TeX Live, which contains most of CTAN, are available and can be found under `texlive.pkgs`:
  ```ShellSession
  $ nix repl
  nix-repl> :l <nixpkgs>
  nix-repl> texlive.pkgs.[TAB]
  ```
  Note that the packages in `texlive.pkgs` are only provided for search purposes and must not be used directly.

- **Experimental and subject to change without notice:** to add the documentation for all packages in the environment, use
  ```nix
  texliveSmall.__overrideTeXConfig { withDocs = true; }
  ```
  This can be applied before or after calling `withPackages`.

  The function currently support the parameters `withDocs`, `withSources`, and `requireTeXPackages`.

## User's guide {#sec-language-texlive-user-guide}

- For basic usage just pull `texlive.combined.scheme-basic` for an environment with basic LaTeX support.