Following [Best Practices](https://nix.dev/guides/best-practices#with-scopes),
`with` is a problematic language construction and should be avoided.
Usually it is employed like a "factorization": `[ X.A X.B X.C X.D ]` is written
`with X; [ A B C D ]`.
However, as shown in the link above, the syntatical rules of `with` are not so
intuitive, and this "distributive rule" is very selective, in the sense that
`with X; [ A B C D ]` is not equivalent to `[ X.A X.B X.C X.D ]`.
However, this factorization is still useful to "squeeze" some code, especially
in lists like `meta.maintainers`.
On the other hand, it becomes less justifiable in bigger scopes. This is
especially true in cases like `with lib;` in the top of expression and in sets
like `meta = with lib; { . . . }`.
That being said, this patch removes most of example code in the current
documentation.
The exceptions are, for now
- doc/functions/generators.section.md
- doc/languages-frameworks/coq.section.md
because, well, they are way more complicated, and I couldn't parse them
mentally - yet another reason why `with` should be avoided!
I believe it would be helpful to better explain how to use
`nuget-to-nix` for those who aren't familar with the .NET ecosystem as I
was personally stumped on how to use it.
This allows packages that require several dotnet versions to build (like
BeatSaberModManager) to properly depend on the dotnet-sdk specific deps.
This in turns avoids having to regenerate the deps of those packages
after each dotnet-sdk update.
This also changes nuget-to-nix to accept a file with a list of
exclusions instead of a folder.
Previously we had an assert that would complain when nugetDeps wasnt set,
which also didnt allow any passthru attributes (like fetch-deps) to be
build. That causes a cycle where you need nugetDeps to fetch the nuget
deps, but arent able to build the script to do so.
Sometimes I want to pass a different implementation of `mkNugetDeps`.
For example in private repos, it can be handy to use `__noChroot = true`
and bypass the deps.nix generation altogether. Or some Nuget packages
ship with ELF binaries that need to be patched, and that's best done as
soon as possible.
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.
Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist
While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.
The distinction between the inputs doesn't really make sense in the
mkShell context. Technically speaking, we should be using the
nativeBuildInputs most of the time.
So in order to make this function more beginner-friendly, add "packages"
as an attribute, that maps to nativeBuildInputs.
This commit also updates all the uses in nixpkgs.
