doc/manual: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
This commit is contained in:
Robert Hensing 2023-01-03 11:21:21 +01:00 committed by Robert Hensing
parent fd2af69e60
commit fefa3a49ce
2 changed files with 12 additions and 6 deletions

View file

@ -250,16 +250,19 @@ The installer now supports a `--tarball-url-prefix` flag which _may_ have
solved this need? solved this need?
--> -->
### Checking the manual links ### Checking links in the manual
The build checks for broken internal links, but this happens late in the process, The build checks for broken internal links.
so `nix build .` is not suitable for iterating. To check the manual incrementally, run: This happens late in the process, so `nix build` is not suitable for iterating.
To build the manual incrementally, run:
```console ```console
make html -j $NIX_BUILD_CORES make html -j $NIX_BUILD_CORES
``` ```
When iterating on the makefile, run: In order to reflect changes to the [Makefile], clear all generated files before re-building:
[Makefile]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
```console ```console
rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
@ -267,4 +270,7 @@ rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/comman
If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory. If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
`mdbook-linkcheck` does not implement fragment checking yet. [`mdbook-linkcheck`] does not implement checking [URI fragments] yet.
[`mdbook-linkcheck`]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
[URI fragments]: https://en.m.wikipedia.org/wiki/URI_fragment

View file

@ -254,7 +254,7 @@ static RegisterPrimOp primop_import({
> >
> Unlike some languages, `import` is a regular function in Nix. > Unlike some languages, `import` is a regular function in Nix.
> Paths using the angle bracket syntax (e.g., `import` *\<foo\>*) > Paths using the angle bracket syntax (e.g., `import` *\<foo\>*)
> are normal path values. > are normal [path values](@docroot@/language/values.md#type-path).
A Nix expression loaded by `import` must not contain any *free A Nix expression loaded by `import` must not contain any *free
variables* (identifiers that are not defined in the Nix expression variables* (identifiers that are not defined in the Nix expression