Merge branch 'master' into patch-3

.github/workflows/rbe.yml

@@ -1,12 +1,19 @@
 name: CI
 on: [push, pull_request]
 
+env:
+  # Update the language picker in index.hbs to link new languages.
+  LANGUAGES:
+
 jobs:
   test:
     name: Run tests
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v4
+      with:
+        # We need the full history below.
+        fetch-depth: 0
 
     - name: Update rustup
       run: rustup self update
@@ -23,6 +30,10 @@ jobs:
         curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.15/mdbook-v0.4.15-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
         echo "$(pwd)/bin" >> ${GITHUB_PATH}
 
+    - name: Install mdbook-i18n-helpers
+      run: |
+        cargo install mdbook-i18n-helpers --locked --version 0.3.0
+
     - name: Report versions
       run: |
         rustup --version
@@ -41,6 +52,28 @@ jobs:
           https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
         sh linkcheck.sh --all rust-by-example
 
+    - name: Build all translations
+      run: |
+        for po_lang in ${{ env.LANGUAGES }}; do
+          POT_CREATION_DATE=$(grep --max-count 1 '^"POT-Creation-Date:' po/$po_lang.po | sed -E 's/".*: (.*)\\n"/\1/')
+          if [[ $POT_CREATION_DATE == "" ]]; then
+              POT_CREATION_DATE=now
+          fi
+
+          echo "::group::Building $po_lang translation as of $POT_CREATION_DATE"
+          rm -r src/
+          git restore --source "$(git rev-list -n 1 --before "$POT_CREATION_DATE" @)" src/
+
+          # Set language and adjust site URL. Clear the redirects
+          # since they are in sync with the source files, not the
+          # translation.
+          MDBOOK_BOOK__LANGUAGE=$po_lang \
+          MDBOOK_OUTPUT__HTML__SITE_URL=/rust-by-example/$po_lang/ \
+          MDBOOK_OUTPUT__HTML__REDIRECT='{}' \
+          mdbook build -d book/$po_lang
+          echo "::endgroup::"
+        done
+
     - name: Upload Artifact
       uses: actions/upload-artifact@v3
       with:

.gitignore

@@ -1,4 +1,6 @@
 book
 
+po/messages.pot
+
 # Auto-generated files from macOS
-.DS_Store
+.DS_Store

README.md

@@ -27,12 +27,37 @@ mdbook serve
 To be able to run the examples, you must be connected to the internet; you can
 read all content offline, however!
 
+The following warnings can be ignored safely.
+
+```
+[WARN] (mdbook::preprocess::cmd): The command wasn't found, is the "gettext" preprocessor installed?
+[WARN] (mdbook::preprocess::cmd):   Command: mdbook-gettext
+```
+
+### Using translated version
+
+If there is a translated resource in `po/` directory, it can be specified through `MDBOOK_BOOK__LANGUAGE` like below:
+
+```bash
+git clone https://github.com/rust-lang/rust-by-example
+cd rust-by-example
+cargo install mdbook
+MDBOOK_BOOK__LANGUAGE=ja mdbook build
+MDBOOK_BOOK__LANGUAGE=ja mdbook serve
+```
+
 ## Contributing
 
 Please see the [CONTRIBUTING.md] file for more details.
 
 [CONTRIBUTING.md]: https://github.com/rust-lang/rust-by-example/blob/master/CONTRIBUTING.md
 
+## Translating
+
+Please see the [TRANSLATING.md] file for more details.
+
+[TRANSLATING.md]: https://github.com/rust-lang/rust-by-example/blob/master/TRANSLATING.md
+
 ## Translations to other languages
 
 * [Bulgarian](https://github.com/kberov/rust-by-example-bg)

TRANSLATING.md

@@ -0,0 +1,85 @@
+# Rust by Example translation guidelines
+
+Please see the [CONTRIBUTING.md] file for general contribution guidelines.
+This file describes about the translation workflow.
+
+[CONTRIBUTING.md]: https://github.com/rust-lang/rust-by-example/blob/master/CONTRIBUTING.md
+
+## Translation workflow
+
+### Preparation
+
+RBE uses [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers) as a translation framework.
+The following tools are required.
+
+* GNU gettext utilities ( `msgmerge` and `msgcat` )
+* mdbook-i18n-helpers ( `cargo install mdbook-i18n-helpers` )
+
+### Creating and Updating Translations
+
+Please see the [mdbook-i18n-helpers USAGE](https://github.com/google/mdbook-i18n-helpers/blob/main/i18n-helpers/USAGE.md) file for the detailed usage of mdbook-i18n-helpers.
+The summarized command list is below:
+
+#### Generating a message template
+
+The generated message templete `po/messages.pot` is required to create or update translations.
+
+```bash
+MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' \
+  mdbook build -d po
+```
+
+#### Creating a new translation resource
+
+`xx` is [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code.
+
+```bash
+msginit -i po/messages.pot -l xx -o po/xx.po
+```
+
+#### Updating the exising translation resource
+
+```bash
+msgmerge --update po/xx.po po/messages.pot
+```
+
+### Editing translation resources
+
+After generating a translation resource `po/xx.po`, you can write translation messages in `msgstr` entry of `po/xx.po`.
+To build a translated book, the following command can be used.
+
+```bash
+MDBOOK_BOOK__LANGUAGE=xx mdbook build
+MDBOOK_BOOK__LANGUAGE=xx mdbook serve
+```
+
+### Add a language entry
+
+Please add a language entry in `.github/workflows/rbe.yml` and `theme/index.hbs` like below:
+
+* `rbe.yml`
+
+```yml
+env:
+  # Update the language picker in index.hbs to link new languages.
+  LANGUAGES: xx yy zz
+```
+
+* `index.hbs`
+
+```html
+<ul id="language-list" class="theme-popup" aria-label="Languages" role="menu">
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="en">English</a>
+  </button></li>
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="xx">XX language</a>
+  </button></li>
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="yy">YY language</a>
+  </button></li>
+  <li role="none"><button role="menuitem" class="theme">
+      <a id="zz">ZZ language</a>
+  </button></li>
+</ul>
+```

book.toml

@@ -13,6 +13,15 @@ enable = true
 
 [output.html]
 git-repository-url = "https://github.com/rust-lang/rust-by-example"
+additional-css = [
+  "theme/css/language-picker.css",
+]
 
 [rust]
 edition = "2021"
+
+[build]
+extra-watch-dirs = ["po"]
+
+[preprocessor.gettext]
+after = ["links"]

src/meta/doc.md

@@ -80,7 +80,7 @@ Used to inline docs, instead of linking out to separate page.
 pub use bar::Bar;
 
 /// bar docs
-mod bar {
+pub mod bar {
     /// the docs for Bar
     pub struct Bar;
 }

src/meta/playground.md

@@ -39,15 +39,22 @@ button that says "Run", which opens the code sample up in a new tab in Rust
 Playground. This feature is enabled if you use the `#[doc]` attribute called
 [`html_playground_url`][html-playground-url].
 
+```
+#![doc(html_playground_url = "https://play.rust-lang.org/")]
+//! ```
+//! println!("Hello Wolrd");
+//! ```
+```
+
 ### See also:
 
 - [The Rust Playground][rust-playground]
-- [rust-playground][rust-playground]
+- [The Rust Playground On Github][rust-playground-github]
 - [The rustdoc Book][rustdoc-book]
 
 [rust-playground]: https://play.rust-lang.org/
-[rust-playground]: https://github.com/integer32llc/rust-playground/
+[rust-playground-github]: https://github.com/integer32llc/rust-playground/
 [mdbook]: https://github.com/rust-lang/mdBook
 [official-rust-docs]: https://doc.rust-lang.org/core/
 [rustdoc-book]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html
-[html-playground-url]: https://doc.rust-lang.org/rustdoc/the-doc-attribute.html#html_playground_url
+[html-playground-url]: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#html_playground_url

src/std_misc/ffi.md

@@ -8,6 +8,16 @@ attribute containing the name of the foreign library.
 use std::fmt;
 
 // this extern block links to the libm library
+#[cfg(target_family = "windows")]
+#[link(name = "msvcrt")]
+extern {
+    // this is a foreign function
+    // that computes the square root of a single precision complex number
+    fn csqrtf(z: Complex) -> Complex;
+
+    fn ccosf(z: Complex) -> Complex;
+}
+#[cfg(target_family = "unix")]
 #[link(name = "m")]
 extern {
     // this is a foreign function

src/std_misc/process/pipe.md

@@ -6,7 +6,7 @@ process via pipes.
 
 ```rust,ignore
 use std::io::prelude::*;
-use std::process::{Command, Stdio};
+use std::process::Stdio;
 
 static PANGRAM: &'static str =
 "the quick brown fox jumped over the lazy dog\n";

src/testing/unit_testing.md

@@ -199,7 +199,7 @@ test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 Tests can be marked with the `#[ignore]` attribute to exclude some tests. Or to run
 them with command `cargo test -- --ignored`
 
-```rust
+```rust,ignore
 pub fn add(a: i32, b: i32) -> i32 {
     a + b
 }

theme/css/language-picker.css

@@ -0,0 +1,13 @@
+#language-list {
+  left: auto;
+  right: 10px;
+}
+
+[dir="rtl"] #language-list {
+  left: 10px;
+  right: auto;
+}
+
+#language-list a {
+  color: inherit;
+}