Updated 'src/crates-io/publishing.md'.

projects/art/Cargo.toml

@@ -1,8 +1,6 @@
 [package]
 name = "art"
 version = "0.1.0"
-edition = "2021"
+edition = "2024"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]

projects/art/src/kinds.rs

@@ -1,15 +0,0 @@
-/// RYB 颜色模型下的主要颜色。
-#[derive(Debug)]
-pub enum PrimaryColor {
-    Red,
-    Yellow,
-    Blue,
-}
-
-/// RYB 颜色模型下的次要颜色。
-#[derive(Debug)]
-pub enum SecondaryColor {
-    Orange,
-    Green,
-    Purple,
-}

projects/art/src/lib.rs

@@ -1,10 +1,36 @@
-//! # art
+//! # 美术
 //!
-//! 建模诸多美术概念的一个库。
+//! 用于建模美术概念的库。
-
-pub mod kinds;
-pub mod utils;
 
 pub use self::kinds::PrimaryColor;
 pub use self::kinds::SecondaryColor;
 pub use self::utils::mix;
+
+
+pub mod kinds {
+    /// 根据 RYB 颜色模型的原色。
+    pub enum PrimaryColor {
+        Red,
+        Yellow,
+        Blue,
+    }
+
+    /// 根据 RYB 颜色模型的间色。
+    #[derive(Debug)]
+    pub enum SecondaryColor {
+        Orange,
+        Green,
+        Purple,
+    }
+}
+
+pub mod utils {
+    use crate::kinds::*;
+
+    /// 等量组合两种原色以创建
+    /// 一种间色。
+    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
+        // --跳过代码--
+        SecondaryColor::Purple
+    }
+}

projects/art/src/utils.rs

@@ -1,9 +0,0 @@
-use crate::kinds::*;
-
-/// 结合两种等量的主要颜色，创建出
-/// 某种次要颜色。
-pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
-    // --跳过代码--
-    println! ("c1: {:?}, c2: {:?}", c1, c2);
-    SecondaryColor::Purple
-}

projects/art_user/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "art_user"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+art = { path = "../art" }

projects/art_user/src/main.rs

@@ -0,0 +1,10 @@
+use art::mix;
+use art::PrimaryColor;
+
+fn main() {
+    let red = PrimaryColor::Red;
+    let yellow = PrimaryColor::Yellow;
+    let result = mix(red, yellow);
+
+    println! ("{result:#?}");
+}

src/crates-io/publishing.md

@@ -122,44 +122,45 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; fini
 
 **清单 14-2**：`my_crate` 代码箱作为一个整体的文档
 
-请注意由于咱们是以 `//!` 而非 `///` 开始的这些注释，因此在以 `//!` 开始的最后一行后，并无任何代码的，咱们是在给包含此注释的程序项目，而非紧接着此注释的程序项目编写文档。在此示例中，那个程序项目就是 `src/lib.rs` 文件，为代码箱根。这些注释描述了整个代码箱。
+请注意，以 `//!` 开头的最后一行之后没有任何代码。由于我们以 `//!` 而不是 `///` 开始注释，因此我们是在给包含这种注释的程序项目，而非紧接着这种注释之后的程序项目编写文档。在这一情形下，该项目是 `src/lib.rs` 文件，是代码箱根。这些注释描述了整个代码箱。
 
-当咱们运行 `cargo doc --open` 时，这些注释将显示在 `cargo_features_demo` 代码箱文档的首页，he front page，位处代码箱公开项目的清单之上，如下图 14-02 中所示：
+当我们运行 `cargo doc --open` 时，这些注释将显示在 `my_crate` 代码箱文档的首页，在代码箱的公开项目列表上方，如下图 14-2 中所示：
 
+<a name="f_14-2"></a>
 ![渲染出的 `cargo_features_demo` 代码箱文档](../images/14-02.png)
 
-*图 14-02：渲染出的 `cargo_features_demo` 代码箱文档, 包括着将该代码箱作为整体描述的注释*
+**图 14-02**：`my_crate` 渲染后的文档, 包括作为整体描述该代码箱的注释
 
-程序项目里的文档注释，用于对描述代码箱及模组尤其有用。使用他们来解释容器，the container，的整体目标，有助于咱们的用户们理解代码箱的组织结构。
+项目内的文档注释对于描述代码箱及模组尤其有用。请使用他们说明容器的总体用途，以帮助咱们的用户理解代码箱的组织结构。
 
 
-## 导出便利的公开 API
+## 导出便捷的公开 API
 
+在发布代码箱时，公开 API 的结构属于主要考量。相比咱们自己，使用代码箱的人对代码箱结构的没有那么熟悉，当咱们的代码箱有着庞大的模组层次结构时，他们可能在找到他们打算使用的部分时遇到困难。
 
-在咱们发布代码箱时，公开 API 的结构是主要的考量。相比与咱们，使用咱们代码箱的人们对代码箱结构的没有那么熟悉，并在咱们的代码箱有着大型模组层次结构时，难于找到他们打算使用的部分。
+在第 7 章中，咱们介绍了怎样使用 `pub` 关键字构造项目为公开，以及怎样以 `use` 关键字带入项目到作用域。然而，在开发代码箱时对咱们有意义的组织结构（模组树），对于咱们的用户可能并不方便。咱们可能打算组织咱们的结构为包含多个级别的层次结构，但后来打算使用某个咱们定义在层次结构深处的类型的人，可能在找出该类型是否存在时遇到麻烦。他们可能还会因为不得不输入 `my_crate::some_module::another_module::UsefulType;`，而不是输入 `use my_crate::UsefulType;` 而感到恼火。
 
-在第 7 章中，咱们曾讲到过怎样使用 `pub` 关键字把一些程序项目构造为公开，与怎样使用 `use` 关键字，把程序项目带入到作用域。但是，咱们在开发某个代码箱时，对咱们有意义的组织结构（模组树），对于咱们的用户则可能不那么便利。咱们会打算把代码箱结构组织为包含多个级别的层次，但随后某个想要使用定义在层次结构深处类型的人，就可能在找出那个类型是否存在上遇到麻烦。他们可能还会对必须敲入 `use cargo_features_demo::some_module::another_module::UsefulType;`，而非敲入 `use cargo_features_demo::UsefulType;` 而感到恼火。
+好消息是，当组织结构 *不* 便于其他人在另一库中使用时，咱们不必调整咱们的内部组织结构：相反，咱们可以通过使用 `pub use` 重新导出程序项目，以构造一种不同于咱们的私有组织结构的公开组织结构。所谓 *重新导出*，会取位于一处的某个公开程序项目，并构造其为在另一处公开，就像他被定义在另一处一样。
 
-可喜的是，若代码箱组织结构 *不* 便于其他人在另一库中使用，咱们不必重新调整代码箱的内部组织：相反，咱们可通过使用 `pub use`，重新导出程序项目，而构造出一种不同于咱们私有组织结构的公开组织结构。重新导出，re-export，会取一处的公开程序项目，而在另一处将其构造为公开，就跟这个项目是在那另一处被定义过一样。
+例如，假设我们出于建模美术概念目的，构造了一个名为 `art` 的库。这个库内有两个模组：包含两个名为 `PrimaryColor` 与 `SeccondaryColor` 枚举的 `kinds` 模组，和包含名为 `mix` 函数的 `utils` 模组，如下清单 14-3 中所示：
-
-比如说，咱们构造了用于建模美术概念的一个名为 `art` 的库。这个库里有两个模组：包含了两个名为 `PrimaryColor` 与 `SeccondaryColor` 枚举的 `kinds` 模组，与包含了名为 `mix` 函数的 `utils` 模组，如下清单 14-3 中所示：
 
+<a name="listing_14-3"></a>
 文件名：`src/lib.rs`
 
 ```rust
-//! # art
+//! # 美术
 //!
-//! 建模诸多美术概念的一个库。
+//! 用于建模美术概念的库。
 
 pub mod kinds {
-    /// RYB 颜色模型下的主要颜色。
+    /// 根据 RYB 颜色模型的原色。
     pub enum PrimaryColor {
         Red,
         Yellow,
         Blue,
     }
 
-    /// RYB 颜色模型下的次要颜色。
+    /// 根据 RYB 颜色模型的间色。
     pub enum SecondaryColor {
         Orange,
         Green,
@@ -170,8 +171,8 @@ pub mod kinds {
 pub mod utils {
     use crate::kinds::*;
 
-    /// 结合两种等量的主要颜色，创建出
+    /// 等量组合两种原色以创建
-    /// 某种次要颜色。
+    /// 一种间色。
     pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
         // --跳过代码--
         SecondaryColor::Purple
@@ -179,19 +180,20 @@ pub mod utils {
 }
 ```
 
-*清单 14-3：有着组织到 `kinds` 与 `utils` 两个模组中的一些程序项目的 `art` 库*
+**清单 14-3**：`art` 库，有着组织在 `kinds` 与 `utils` 两个模组中的程序项目
 
-下图 14-03 展示了由 `cargo doc` 产生出的该代码箱文档首页，看起来的样子：
+下图 14-03 展示了由 `cargo doc` 生成的这个代码箱的文档的首页的样子：
 
+<a name="f_14-3"></a>
 ![列出 `kinds` 与 `utils` 两个模组的 `art` 代码箱文档首页](../images/14-03.png)
 
-*图 14-3：列出 `kinds` 与 `utils` 两个模组的 `art` 代码箱文档首页*
+**图 14-3**：`art` 库的文档的首页，列出了 `kinds` 与 `utils` 两个模组
 
+请注意，`PrimaryColor` 与 `SecondaryColor` 两个类型并未在首页上列出，`mix` 函数也如此。我们必须点击 `kinds` 与 `utils` 才能看到他们。
 
-请注意 `PrimaryColor` 与 `SecondaryColor` 两个类型，及 `mix` 函数都未在首页上列出。要看到他们，咱们必须点击 `kinds` 与 `utils`。
+依赖于这个库的另一代码箱将需要 `use` 语句，带入 `art` 中的项目到作用域，指定当前定义的模组结构。下面清单 14-4 展示了一个代码箱示例，使用 `art` 代码箱中的 `PrimaryColor` 与 `mix` 两个程序项目：
-
-依赖于这个库的另一代码箱，将需要把程序项目从 `art` 带入到作用域的 `use` 语句，与指明当前定义的模组结构。下面清单 14-4 给出了用到 `art` 代码箱中 `PrimaryColor` 与 `mix` 两个程序项目的代码箱示例：
 
+<a name="listing_14-4"></a>
 文件名：`src/main.rs`
 
 ```rust
@@ -205,23 +207,24 @@ fn main() {
 }
 ```
 
-*清单 14-4：用到 `art` 代码箱以内部组织结构导出程序项目的代码箱*
+**清单 14-4**：使用 `art` 代码箱的项目的代码箱，`art` 代码箱的内部组织结构已导出
 
-> **注**：使用本地未发布代码箱的方法，是在 `Cargo.toml` 的 `[dependencies]` 小节中，列出要使用的本地未发布代码箱。参见 [How to use a local unpublished crate?](https://stackoverflow.com/a/33025972)
+> **译注**：使用本地未发布代码箱的方法，是在 `Cargo.toml` 的 `[dependencies]` 小节中，列出要使用的本地未发布代码箱。参见 [How to use a local unpublished crate?](https://stackoverflow.com/a/33025972)
+>
+> 文件：`Cargo.toml`
+>
+> ```toml
+> // --跳过代码--
+>
+> [dependencies]
+> art = { path = "../art" }
+> ```
 
-文件：`Cargo.toml`
+清单 14-4 中使用 `art` 代码箱的代码的作者，必须搞清楚 `PrimaryColor` 位于 `kinds` 模组中，而 `mix` 位于 `utils` 模组中。`art` 代码箱的模组结构（即模组树），相比使用他的人，对于编写 `art` 代码箱的开发者更为密切。对于试图了解怎样使用 `art` 代码箱的人来说，这一内部组织结构并未包含任何有用信息，反而会造成混淆，因为使用他的开发者必须弄清楚在哪里去查看，并且必须在 `use` 语句中指定模组名字。
 
-```toml
+为了移除公开 API 中的内部组织结构，我们可以修改 [清单 14-3](#listing_14-3) 中 `art` 代码箱的代码，为添加一些 `pub use` 语句，以在顶层重新导出程序项目，如下清单 14-5 中所示：
-// --跳过代码--
-
-[dependencies]
-art = { path = "../art" }
-```
-
-清单 14-4 中用到 `art` 代码箱代码的作者，不得不搞清楚 `PrimaryColor` 是在 `kinds` 模组中，及 `mix` 函数是在 `utils` 模组中。`art` 代码箱的模组结构（即模组树），相比于用到该代码箱的开发者，与在 `art` 代码箱上编写代码的开发者要更为密切。对于试图搞清楚怎样使用 `art` 代码箱的人来说，其内部组织结构并未包含任何有用信息，而因为要用到他的开发者，不得不搞明白要在那里去查看，且必须在 `use` 语句中指明那些模组名字，这反而会造成混乱。
-
-要从公开 API 中移除内部组织结构，咱们可把清单 14-3 中 `art` 代码箱的代码，修改为添加一些 `pub use` 语句，来在顶层处重导出程序项目，to re-export the items at the top level，如下清单 14-5 中所示：
 
+<a name="listing_14-5"></a>
 文件名：`src/lib.rs`
 
 ```rust
@@ -233,20 +236,27 @@ pub use self::kinds::PrimaryColor;
 pub use self::kinds::SecondaryColor;
 pub use self::utils::mix;
 
-pub mod kinds;
+pub mod kinds {
-pub mod utils;
+    // -- 跳过代码 --
+}
+
+pub mod utils {
+    // -- 跳过代码 --
+}
 ```
 
-*清单 14-5：添加 `pub use` 语句来重导出程序项目*
+**清单 14-5**：添加 `pub use` 语句以重新导出程序项目
 
-如下图 14-04 中所示，`cargo doc` 为此代码箱所产生出的 API 文档，现在将在首页上列出并链接到重导出项，从而令到 `PrimaryColor` 与 `SecondaryColor` 两个类型及 `mix` 函数更易于找到。
+如下图 14-04 中所示，`cargo doc` 对这个代码箱生成的 API 文档，现在将在首页上列出并链接到重导出项，从而让 `PrimaryColor` 与 `SecondaryColor` 两个类型以及 `mix` 函数更容易找到。
 
+<a name="f_14-4"></a>
 ![列出了重导出项目的 `art` 代码箱文档首页](../images/14-04.png)
 
-*图 14-4：列出重导出项的 `art` 代码箱文档首页*
+**图 14-4**：`art` 代码箱文档的首页，列出了重新导出项目
 
-`art` 代码箱的用户，依然可以像清单 14-4 中所演示的那样，发现及使用清单 14-3 的内部结构，或者他们可使用清单 14-5 中更为便利的结构，如下清单 14-6 中所示：
+`art` 代码箱的用户仍然可以如同 [清单 14-4](#listing_14-4) 中演示的那样，看到并使用 [清单 14-3](#listing_14-3) 中的内部结构，或者他们可使用清单 14-5 中的更方便的结构，如下清单 14-6 中所示：
 
+<a name="listing_14-6"></a>
 文件名：`src/main.rs`
 
 ```rust
@@ -260,11 +270,11 @@ fn main() {
 }
 ```
 
-*清单 14-6：使用着 `art` 代码箱重导出项的程序*
+**清单 14-6**：使用 `art` 代码箱中重新导出项目的程序
 
-其中有许多嵌套模组的情形下，以 `pub use` 在顶层重导出类型，可在用到该代码箱的人的体验方面，造成显著不同。`pub use` 的另一常见用途则是，为将依赖代码箱的定义构造为咱们自己代码箱公开 API 的一部分，而重导出当前代码箱中某个依赖的定义。
+在存在许多嵌套模组的情形下，以 `pub use` 在顶层重新导出类型，可以对使用代码箱的人的体验造成显著差异。`pub use` 的另一个常见用途是重新导出当前代码箱中的依赖项的定义，以使该代码箱的定义，成为咱们的代码箱的公开 API 的一部分。
 
-创建出有用的公开 API 结构，与其说是一门科学，不如说是一门艺术，而咱们可不断迭代，来找到对用户运作最佳的 API。选择 `pub use` 会给到咱们在内部组织代码箱方式上的灵活性，并解除了内部结构与呈现给代码箱用户的组织结构的耦合。请查看咱们曾安装的代码箱代码，来发现他们的内部结构，是否不同于其公开 API。
+创建有用的公开 API 结构，与其说是一门科学，不如说是一门艺术，而咱们可不断迭代，找到最适合用户的 API。选择 `pub use` 赋予了咱们在内部组织代码箱方式上的灵活性，并解耦了内部结构与呈现给用户的结构。请查看咱们已安装的一些代码箱的代码，看看发现他们的内部结构是否与其公开 API 有所不同。
 
 
 ## 建立 Crates.io 帐号