| Age | Commit message (Collapse) | Author |
|---|
|
This doesn't comprehensively fix everything outdated in the manual, or
make the manual greatly better, but it does note down where at least
jade noticed it was wrong, and it does fix all the instances of
referencing Nix to conform to the style guide to the best of our
ability.
A lot of things have been commented out for being wrong, and there are
three types of FIXME introduced:
- FIXME(Lix): generically Lix needs to fix it
- FIXME(Qyriad): re https://git.lix.systems/lix-project/lix/issues/215
- FIXME(meson): docs got outdated by meson changes and need rewriting
I did fix a bunch of it that I could, but there could certainly be
mistakes and this is definitely just an incremental improvement.
Fixes: https://git.lix.systems/lix-project/lix/issues/266
Change-Id: I5993c4603d7f026a887089fce77db08394362135
|
|
mdbook has the unfortunate habit of creating stub files for chapters it
can't find on disk. turn off this helpful feature as it masks errors in
the summary file, and fix a recently introduced instance of this error.
Change-Id: I10d86aac0489c9c494bd5c8a50047415f4d4b18d
|
|
manpages can be rendered using the markdown output of mdbook, the rest
of the manual can generated out of the main doc/manual source tree. we
still use lowdown to actually render manpages instead of eg mdbook-man
because lowdown does generate reasonably good manpages (though that is
also somewhat debatable, but they're a lot better than mdbook-man).
doing this not only lets us drastically simplify the lowdown pipeline,
but also remove all custom {{#include}} handling since now mdbook does
all of it, even for the manpage builds. even the lowdown wrapper isn't
entirely necessary because lowdown can take all wrapper arguments with
command line flags rather than bits of input file content.
This also implements running mdbook in Meson, in order to generate the
manpages. The mdbook outputs are also installed in the usual location.
Co-authored-by: Qyriad <qyriad@qyriad.me>
Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
|
|
mdbook already does include processing of its own, and the custom
processing code has always admitted as much. we don't need it for
the mdbook build at this point if we run our preprocessors in the
right order, and maybe we can even have mdbook to return complete
pages to us that we only have to pass to lowdown without any more
preprocessing of our own.
Change-Id: Icd978acbc3b1e215fee8f062c53ab2cb2a222ab1
|
|
We're not entirely clear on why the links preprocessor has to be done
*before* rather than after, but we assume it is probably that as a
builtin preprocessor it does some processing on the raw book source,
and not just the JSON data.
Also a real use for Python pattern matching? I know I was surprised too.
Change-Id: Ibe8b59e7b5bd5f357a655d8b4c5f0b0f58a67d6b
|
|
mdbook-linkcheck is not consistent about its warning setting.
It disables some warnings, but not the warnings about lack of
fragment checking support; hence the extra filtering.
|
|
* doc/book.toml: Improve config
- `title` value will be added to the HTML <title> - here</title>
- `git-repository-url` adds a link to the GitHub repo in the top right corner
- `edit-url-template` adds an edit link, inviting contributions
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
|
|
There are still many links to the old manual on the web and
having them end up on the Introduction page is a bad user experience.
|
|
Python is only pulled into the build closure by Mercurial, which might end up being removed.
Let’s port the script to jq, which is more likely to stay.
|
|
It is now possible to use the following syntax to insert anchors into the text:
[]{#anchor-name}
The anchor will allow linking to the location it is placed by appending #anchor-name to the URL.
Additionally, it is possible to create a link pointing to its own location by adding text between the square brackets:
[`--add-root`]{#opt-add-root}
|
|
The default CSS puts almost no space between sections, but a lot of
space between subsections. This flips that around.
|
