search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
17.84k stars 1.62k forks source link

A few issues in the User Guide #2433

Closed StefanSalewski closed 4 weeks ago

StefanSalewski commented 1 month ago

Problem

Last night, I started reading the mdbook user guide. While most of it is fine, I noticed a few strange issues. Well, being a Rust beginner, and not a native speaker, some might not be real errors.

https://rust-lang.github.io/mdBook/guide/reading.html

Navigation The arrow buttons at the bottom of the page can be used to navigate to the previous or the next chapter.

For me, there are arrows at the left and right, but not at the bottom. Is this a feature of the most recent version, or just an outdated documentation. Or have I misundrstand it?

And: Repeating the wording is bad style, but perhaps that is a result of auto-generated test:

The arrow buttons at the bottom of the page can be used to navigate to the previous or the next chapter.

The left and right arrow keys on the keyboard can be used to navigate to the previous or the next chapter.

https://rust-lang.github.io/mdBook/guide/creating.html

book.toml In the root of your book, there is a book.toml file which contains settings for describing how to build your book. This is written in the TOML markup language.

This is an awkward wording. It should be something like

At the root of your book folder, there is a book.toml file that contains settings for configuring the build process of your book. This file is written in the TOML markup language.

Source files

All other files in the src directory will be included in the output. So if you have images or other static files, just include them somewhere in the src directory.

I really can not imagine that "All other files in the src directory will be included in the output." Should it be something like

All files in the src directory might be included in the output. So if you have images or other static files, just include them somewhere in the src directory.

Publishing a book

For more information about publishing and deploying, check out the Continuous Integration chapter for more.

Remove the trailing "for more".

Steps

Read the User Guide

Possible Solution(s)

Perhaps a native speaker can fix it.

Notes

OK, if you think it is just good enough, then I will close this issue in a few days.

Version

No response

StefanSalewski commented 7 hours ago

Well, perhaps I should reopen this issue again.

When reading the Bevy guide at https://bevyengine.org/learn/quick-start/introduction/ I got the feeling that

Navigation The arrow buttons at the bottom of the page can be used to navigate to the previous or the next chapter.

is a configuration option for mdbook, but than I realized that Bevy is using a different static site generator. So this seems to be really a bug in the documentation. And it would be fine if the other points could be addressed as well.

Replacing

The version published to crates.io will ever so slightly be behind the version hosted on GitHub.

by

"The version published on crates.io will be ever so slightly behind the version hosted on GitHub." might be an idea as well.