1
0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-04-05 18:15:49 +02:00

Revert "Update README.md with mdbook-pandoc install" (#1998)

Reverts google/comprehensive-rust#1975

Using `mdbook-pandoc` requires more than just installing the `mdbook`
plugin: it requires

- A whole LaTeX installation
- A Pandoc installation
- Some fonts

This is essentially why the output is configured as optional in
`book.toml`: the assumption is that people won't have `mdbook-pandoc`
installed without the necessary supporting tools.

@henrif75, I assume you added this because you didn't like the warning
`mdbook build` prints:

```
% mdbook build
2024-04-16 10:45:56 [WARN] (mdbook::book): The output.html.curly-quotes field has been renamed to output.html.smart-punctuation.
Use the new name in book.toml to remove this warning.
2024-04-16 10:45:56 [INFO] (mdbook::book): Book building has started
2024-04-16 10:45:57 [INFO] (mdbook::book): Running the exerciser backend
2024-04-16 10:45:57 [INFO] (mdbook::renderer): Invoking the "exerciser" renderer
2024-04-16 10:45:57 [INFO] (mdbook::book): Running the html backend
2024-04-16 10:45:58 [INFO] (mdbook::book): Running the pandoc backend
2024-04-16 10:45:58 [INFO] (mdbook::renderer): Invoking the "pandoc" renderer
2024-04-16 10:45:58 [WARN] (mdbook::renderer): The command `mdbook-pandoc` for backend `pandoc` was not found, but was marked as optional.
```

I don't have the necessary dependencies on my local system and this is
what I get after installing `mdbook-pandoc`:

```
2024-04-16 10:47:30 [INFO] (mdbook::renderer): Invoking the "pandoc" renderer
Unable to run `pandoc -v`: No such file or directory (os error 2)
2024-04-16 10:47:30 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2024-04-16 10:47:30 [ERROR] (mdbook::utils): Error: Rendering failed
2024-04-16 10:47:30 [ERROR] (mdbook::utils): 	Caused By: The "pandoc" renderer failed
```

This also means that `mdbook serve` doesn't work unless all dependencies
are installed.

As an alternative, we could remove the `output.pandoc` settings from the
`book.toml` file and use a small shell script to add them when needed.

We actually have the same problem for the `mdbook-xgettext` output
format which generates the POT files: we only want to run this
occasionally. This is currently done by overriding `output` from the
command line using the `MDBOOK_OUTPUT` environment variable:

```shell
MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot", "granularity": 0}}' \
  mdbook build -d po
```

It's a bit ugly and it results in people missing/forgetting some of the
configuration options we want them to use (the `granularity` setting).
So I would like to move this configuration to the `book.toml` file — but
I'm reluctant since I don't think we need to generate POT files on every
build (it takes ~1 second and would slow down `mdbook serve`).

Cc @max-heller in case you have ideas here.
This commit is contained in:
Martin Geisler 2024-04-16 22:26:47 +02:00 committed by GitHub
parent b76af9c710
commit 963c6979ed
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -69,7 +69,6 @@ cargo install --locked mdbook-svgbob
cargo install --locked mdbook-i18n-helpers
cargo install --locked --path mdbook-exerciser
cargo install --locked --path mdbook-course
cargo install --locked mdbook-pandoc
```
Run