Commit graph

11 commits

Author SHA1 Message Date
jade 748d8310fa Fix the pages in the manual for Lix
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 lix-project/lix#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: lix-project/lix#266
Change-Id: I5993c4603d7f026a887089fce77db08394362135
2024-05-05 16:11:01 -07:00
eldritch horrors 6a5f100b8b doc: fix build littering doc/
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
2024-05-05 16:13:27 +00:00
eldritch horrors 725f5cd358 docs: redo content generation for mdbook and manual
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
2024-04-11 13:32:06 +00:00
eldritch horrors 07ef9f9f5d docs: skip do custom include processing for mdbook
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
2024-04-09 02:09:36 +00:00
Qyriad c355354772 docs: replace sed invocation with an mdbook preprocessor for @docroot@
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
2024-04-04 21:43:19 +00:00
Robert Hensing be10c09d23 manual: Check links
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.
2023-01-10 22:30:41 +01:00
Robert Hensing 1437582ccd
doc/book.toml: Improve config (#7300)
* 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>
2022-12-20 16:29:32 +01:00
Jan Tojnar 26d1877d6e doc: Add redirects for the DocBook manual
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.
2022-05-26 18:17:21 +02:00
Jan Tojnar 3272afa17b doc: Port anchors preprocessor to jq script
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.
2022-05-26 18:17:21 +02:00
Jan Tojnar 4de84e095d doc: Introduce pre-processor for adding anchors to text
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}
2022-05-26 17:54:15 +02:00
Eelco Dolstra 8a97b11374
Improve margins between sections
The default CSS puts almost no space between sections, but a lot of
space between subsections. This flips that around.
2020-08-19 12:31:18 +02:00