Commit Graph

12 Commits

Author SHA1 Message Date
Anderson Torres
e671d3bbbd Nix docs: remove with lib; from example code
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!
2024-03-06 11:40:09 -03:00
Benedikt Tissot
b28200aa23
texlive: document LuaLaTeX font cache (#280080)
lualatex assumes a writeable font cache relative to `$HOME`, for nix this has two implications.
First, the cache might diverge from the nix store if users use LuaLaTeX.
Second, `$HOME` needs to be set to a writable path in derivations.
2024-01-12 09:47:35 -06:00
Vincenzo Mantova
631eca2e96 texlive: document simpler way to build custom packages 2023-11-20 00:56:40 +00:00
Vincenzo Mantova
aca44fe219
texlive: document new texlive.withPackages interface (#265658) 2023-11-07 14:39:42 -05:00
Vincenzo Mantova
a06e07539e texlive: document new texlive.pkgs attribute 2023-10-07 18:49:19 +01:00
Vincenzo Mantova
01af940407 texlive.combine: include packages with man pages by default 2023-07-29 18:31:17 +02:00
Vincenzo Mantova
57b2634ac1 texlive.combine: document how to create custom packages with pkgs and tlDeps attributes 2023-04-02 13:00:52 +01:00
Colin Arnott
bac379f30a
doc: use sri hash syntax
The nixpkgs manual contains references to both sri hash and explicit
sha256 attributes. This is at best confusing to new users. Since the
final destination is exclusive use of sri hashes, see nixos/rfcs#131,
might as well push new users in that direction gently.

Notable exceptions to sri hash support are builtins.fetchTarball,
cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and
fetchCrate. None, other than builtins.fetchTarball, are fundamentally
incompatible, but all currently accept explicit sha256 attributes as
input. Because adding backwards compatibility is out of scope for this
change, they have been left intact, but migration to sri format has been
made for any using old hash formats.

All hashes have been manually tested to be accurate, and updates were
only made for missing upstream artefacts or bugs.
2022-12-04 06:12:18 +00:00
Léo Gaspard
174c3e1741 nixpkgs/manual: add an explicit mention of CTAN so google can index 2022-03-24 14:14:05 +01:00
Jan Tojnar
6ecc641d08
doc: prepare for commonmark
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.
2021-06-07 06:34:59 +02:00
Ryan Mulligan
b8344f9e5c doc: explicit Markdown anchors for top-level headings; remove metadata
I used the existing anchors generated by Docbook, so the anchor part
should be a no-op. This could be useful depending on the
infrastructure we choose to use, and it is better to be explicit than
rely on Docbook's id generating algorithms.

I got rid of the metadata segments of the Markdown files, because they
are outdated, inaccurate, and could make people less willing to change
them without speaking with the author.
2021-01-01 10:02:57 -08:00
Lucas Eduardo
543f084d62
doc: TeX Live to CommonMark
* converted texlive doc to markdown

Signed-off-by: GitHub <noreply@github.com>

* Remove frontmatter (suggestion)

Co-authored-by: Ryan Mulligan <ryan@ryantm.com>

* Add anchor (suggestion)

Co-authored-by: Ryan Mulligan <ryan@ryantm.com>

* apply suggestions from @ryantm

Signed-off-by: GitHub <noreply@github.com>

* fix nesting of codeblocks into list items as suggested by @jtojnar

Signed-off-by: GitHub <noreply@github.com>

* add anchors for subtopics as said by @jtojnar

Signed-off-by: GitHub <noreply@github.com>

Co-authored-by: Ryan Mulligan <ryan@ryantm.com>
2020-12-02 21:15:18 -08:00