[Tracking] updating the Nixpkgs manual to a consistent style

[DanielSidhion]

The Nixpkgs manual has several different styles for documenting things depending on which section you're looking at. In an effort to keep it more consistent, I'm going through the manual and updating every file to use the same conventions. These conventions are documented in #278762.

As I go through the files, I may discover certain usages which might also be added to the conventions. Any additions will be discussed with the Nix documentation team during the documentation team meetings before being adopted.
Since additions may happen after certain files have been changed, I'm documenting which "version" of the conventions each file is at to make it easier to go back and apply newer versions to files that were changed with older versions.
This is a somewhat inefficient process, but it's what allows me to handle this bit by bit.

It's outside of the scope of this issue, but I can't help it: as I go through each file, I'm also updating the information in them to be more up to date.

I'm going through each file in the sequence below (paths are relative to /docs):

• ./preface.chapter.md
• ./contributing.md
• ./functions.md
• ./stdenv.md
• ./README.md
• ./development.md
• ./build-helpers.md
• ./lib.md
• ./using-nixpkgs.md
• ./build-helpers/testers.chapter.md
  • (v1) doc: add more details on testers.testVersion #275585
  • (v1) doc: migrate examples in testers chapter to admonitions #275791
• ./build-helpers/images/appimagetools.section.md
  • (v1) doc: update the appimageTools section content and examples #276029
• ./build-helpers/images/binarycache.section.md
  • (v1) doc: update mkBinaryCache section with admonitions and conventions #276821
• ./build-helpers/images/dockertools.section.md
  • (v3) doc: update content on dockerTools.buildImage and follow doc conventions #278956
  • (v3) doc: update content on dockerTools layered images and follow doc conventions #281491
  • (v3) doc: update dockerTools.pullImage content and use doc conventions #283106
  • (v3) doc: update dockerTools.exportImage content and use doc conventions #283392
  • (v3) doc: update environment helpers in dockerTools docs, add fakeNss section #285223
  • (v3) doc: update buildNixShellImage docs, add streamNixShellImage docs #286882
  • (v3) doc: update dockerTools to use long-form docker commands, improve wording #288414
• (to be moved to internal README) ./build-helpers/images/makediskimage.section.md
• ./build-helpers/images/ocitools.section.md
  • (v3) doc: update docs in ociTools, follow doc conventions #290886
• ./build-helpers/images/portableservice.section.md
  • (v3) doc: update docs for portableService, follow doc conventions #292267
• ./build-helpers/images/snaptools.section.md
  • snapTools: remove #293416
• ./build-helpers/images.md
• currently here ./build-helpers/fetchers.chapter.md
  • (v3) doc: improve fetchers overview, deduplicate readme content, follow doc conventions #297654
  • (v3) doc: document fetchurl more completely, follow doc conventions #300429
  • (v3) doc: update fetchzip docs, add examples and follow conventions #302692
• ./build-helpers/trivial-build-helpers.chapter.md
• ./build-helpers/special.md
• ./build-helpers/special/checkpoint-build.section.md
• ./build-helpers/special/fhs-environments.section.md
• ./build-helpers/special/makesetuphook.section.md
• ./build-helpers/special/mkshell.section.md
• ./build-helpers/special/vm-tools.section.md
• ./contributing/contributing-to-documentation.chapter.md
• ./contributing/coding-conventions.chapter.md
• ./contributing/quick-start.chapter.md
• ./contributing/reviewing-contributions.chapter.md
• ./contributing/submitting-changes.chapter.md
• ./contributing/vulnerability-roundup.chapter.md
• ./development/opening-issues.chapter.md
• ./functions/debug.section.md
• ./functions/generators.section.md
• ./functions/prefer-remote-fetch.section.md
• ./functions/nix-gitignore.section.md
• ./hooks/automake.section.md
• ./hooks/autoconf.section.md
• ./hooks/autopatchelf.section.md
• ./hooks/bmake.section.md
• ./hooks/breakpoint.section.md
• ./hooks/cmake.section.md
• ./hooks/gdk-pixbuf.section.md
• ./hooks/ghc.section.md
• ./hooks/gnome.section.md
• ./hooks/index.md
• ./hooks/installShellFiles.section.md
• ./hooks/libiconv.section.md
• ./hooks/libxml2.section.md
• ./hooks/meson.section.md
• ./hooks/mpi-check-hook.section.md
• ./hooks/ninja.section.md
• ./hooks/patch-rc-path-hooks.section.md
• ./hooks/perl.section.md
• ./hooks/pkg-config.section.md
• ./hooks/postgresql-test-hook.section.md
• ./hooks/python.section.md
• ./hooks/scons.section.md
• ./hooks/tetex-tex-live.section.md
• ./hooks/unzip.section.md
• ./hooks/validatePkgConfig.section.md
• ./hooks/waf.section.md
• ./hooks/xcbuild.section.md
• ./hooks/zig.section.md
• ./languages-frameworks/agda.section.md
• ./languages-frameworks/android.section.md
• ./languages-frameworks/beam.section.md
• ./languages-frameworks/bower.section.md
• ./languages-frameworks/chicken.section.md
• ./languages-frameworks/coq.section.md
• ./languages-frameworks/crystal.section.md
• ./languages-frameworks/cuda.section.md
• ./languages-frameworks/cuelang.section.md
• ./languages-frameworks/dart.section.md
• ./languages-frameworks/dhall.section.md
• ./languages-frameworks/dotnet.section.md
• ./languages-frameworks/emscripten.section.md
• ./languages-frameworks/gnome.section.md
• ./languages-frameworks/go.section.md
• ./languages-frameworks/haskell.section.md
• ./languages-frameworks/hy.section.md
• ./languages-frameworks/idris.section.md
• ./languages-frameworks/index.md
• ./languages-frameworks/ios.section.md
• ./languages-frameworks/java.section.md
• ./languages-frameworks/javascript.section.md
• ./languages-frameworks/julia.section.md
• ./languages-frameworks/lisp.section.md
• ./languages-frameworks/lua.section.md
• ./languages-frameworks/maven.section.md
• ./languages-frameworks/nim.section.md
• ./languages-frameworks/ocaml.section.md
• ./languages-frameworks/octave.section.md
• ./languages-frameworks/perl.section.md
• ./languages-frameworks/php.section.md
• ./languages-frameworks/pkg-config.section.md
• ./languages-frameworks/python.section.md
• ./languages-frameworks/qt.section.md
• ./languages-frameworks/r.section.md
• ./languages-frameworks/ruby.section.md
• ./languages-frameworks/rust.section.md
• ./languages-frameworks/swift.section.md
• ./languages-frameworks/texlive.section.md
• ./languages-frameworks/titanium.section.md
• ./languages-frameworks/vim.section.md
• ./module-system/module-system.chapter.md
• ./packages/cataclysm-dda.section.md
• ./packages/citrix.section.md
• ./packages/darwin-builder.section.md
• ./packages/dlib.section.md
• ./packages/eclipse.section.md
• ./packages/elm.section.md
• ./packages/emacs.section.md
• ./packages/etc-files.section.md
• ./packages/firefox.section.md
• ./packages/fish.section.md
• ./packages/fuse.section.md
• ./packages/ibus.section.md
• ./packages/index.md
• ./packages/kakoune.section.md
• ./packages/linux.section.md
• ./packages/locales.section.md
• ./packages/nginx.section.md
• ./packages/opengl.section.md
• ./packages/shell-helpers.section.md
• ./packages/steam.section.md
• ./packages/urxvt.section.md
• ./packages/weechat.section.md
• ./packages/xorg.section.md
• ./stdenv/cross-compilation.chapter.md
• ./stdenv/meta.chapter.md
• ./stdenv/multiple-output.chapter.md
• ./stdenv/platform-notes.chapter.md
• ./stdenv/stdenv.chapter.md
• ./using/configuration.chapter.md
• ./using/overlays.chapter.md
• ./using/overrides.chapter.md
• ./using/platform-support.chapter.md

Any help is appreciated to update other files, just try to pick something not being worked on yet.

---

Add a 👍 reaction to issues you find important.

[AndersonTorres]

Lemme know when you pick waf, scons and the like.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-01-15-documentation-team-meeting-notes-104/38305/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/making-packages-projects-available-to-nixos/38462/3

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/a-roadmap-for-the-documentation-ecosystem/42328/1