In #2153 I aimed to fix a link but broke it.
In this PR, I fix it and add
[`mdbook-linkcheck`](https://github.com/Michael-F-Bryan/mdbook-linkcheck)
to avoid future cases.
Some past fixes that could have been prevented, in addition to mine in
this PR:
* #811
* #2064
* #2146
Note:
`mdbook-linkcheck` may also check external links with a configuration
change.
It can be beneficial to check also external links from time to time. I
ran it here and found 3 broken links.
Maintainers - sorry for the lack of a preceding issue. We can discuss it
here.
Some remaining work is to fix the outdated internal links in the
translations, not done here.
Let me know what you think about the proposed contribution.
This PR completes #1502.
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 is a contribution of a Chromium section for Comprehensive Rust.
---------
Co-authored-by: Nicole L <dlegare.1001@gmail.com>
Co-authored-by: Martin Geisler <martin@geisler.net>
I hope the blog post can help shed more light on why we wrote the course
and how it has been used at Google.
I'm not sure if "Press" is the best title, but I hope to link other
articles later from this section at a later point.
In v2 of the course, I'd like to include an estimate of the time to be
spent on each segment in the Markdown file. I think a good place for
such metadata is in the frontmatter.
For review purposes, though, I just want to display that information.
So, this is a start at a new mdbook preprocessor that just separates out
the frontmatter and includes it in a `<pre>` block. Eventually, I'd like
to parse it and put the time in the speaker notes.
---------
Co-authored-by: Martin Geisler <martin@geisler.net>
The dprint formatter is a flexible system which will use sandboxed
WebAssembly formatters to format our code (mostly: it calls out to
`rustfmt` for Rust code).
A particularly interesting feature is that dprint can format Rust code
blocks in the Markdown files. However, before we turn that on, we need
to have a way to normalize the Markdown text as it is extracted[1].
That is so that the word put into the translations is kept after the
reformatting.
[1]: https://github.com/google/mdbook-i18n-helpers/issues/19
* Align outline with new spin-off course structure
With the new structure, the section on Android is a spin-off course
from the main 3-day course on Rust Fundamentals. The Bare-metal and
Concurrency days are spin-off courses in the same way.
* Explain new course structure
* Align Bare-Metal welcome page with other deep dives
* Merge Day 4 page into Course Structure page
* Remove Day 4 Welcome page
This aligns the Concurrency in Rust section with the Bare-Metal Rust
deep dive.
* Show subsections for Android deep dive
This aligns the Rust in Android section with the other deep dives.
* Clean up welcome page and README
We now cover async Rust and the course is no longer a four day course.
* Remove reference to the old Day 4
* Remove Day 4 references from exercises
The i18n-helpers are now available as a stand-alone crate:
https://crates.io/crates/mdbook-i18n-helpers.
Because we cache the Rust binaries in our GitHub workflows, I bumped
the cache prefix to ensure we use a clean cache. Otherwise, Cargo
won’t install the new binaries in mdbook-i18n-helpers because it sees
the old ones from this repository.
* Make i18n-helpers a requirement
* Skip mdbook-gettext for mdbook-xgettext
* Gettext finds PO file based on `book.language`
* Update workflow
No need to set `preprocessor.gettext.po-file`.
---------
Co-authored-by: Jooyung Han <jooyung@google.com>
