refactor rendering documentation of options #7379
Conversation
this makes more obvious what the code produces, and the structure of the output easier to change
fricklerhandwerk
force-pushed
the
refactor-generate-options
branch
from
8103871
to
dfa27e6
Compare
doc/manual/generate-options.nix
Outdated
| let | ||
| inherit (optionsInfo.${name}) description documentDefault defaultValue aliases; | ||
| result = squash '' | ||
| - [`${name}`]{#conf-${name}} |
There was a problem hiding this comment.
We didn't use this kind of anchors because it doesn't render properly in the man page renderer
There was a problem hiding this comment.
Eh. lowdown is very minimal.
There was a problem hiding this comment.
@thufschmitt the same problem appears for nix-build (7708a34) and nix-store (a793863).
I feel an aversion to working around lacking tools and would prefer improving the tools, even if that's more expensive in the short term.
Anyways, fixed it by ugly workaround, for now.
There was a problem hiding this comment.
I feel an aversion to working around lacking tools and would prefer improving the tools, even if that's more expensive in the short term.
Yeah, I agree on the principle. But I also wouldn't want to touch that myself 😛
Now I wonder whether we could just accept that the man pages are somewhat broken and live with it…
There was a problem hiding this comment.
I always felt that the man pages were a substantial asset of Nix documentation, due to the fact that Nix is one of the tools that is highly capable of working offline. We should tend to it, but it is expensive indeed.
There was a problem hiding this comment.
The offline aspect is very important indeed. But the help pages (nix --help and friends) are not man pages and already provide most of these benefits. So maybe we should capitalize on that instead.
(Just to be clear: that maybe is a real maybe, not a rhetoric construct. I don't know what the best solution is)
There was a problem hiding this comment.
nix --help and man nix don't differ much technically except that the first one has fancy colors and apparently can't yet display information on nix.conf and other specific topics. Both are rendered by lowdown from the same sources.
There was a problem hiding this comment.
Oh indeed, I was somehow convinced that it was using something else than lowdown. Sorry for the confusion then.
this avoids incorrect rendering on the man pages, since `lowdown` neither parses the anchor syntax nor HTML. this should rather be fixed in lowdown, as adding more anchors would otherwise produce ever more noise and error-prone repetition.
this is a follow-up on e7dcacb. most links are relative and this should not be too much of a detriment.
this makes more obvious what the code produces, and the structure of the
output easier to change