Skip to content

Mismatch in documentation #1804

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
glatavento opened this issue May 10, 2022 · 5 comments · Fixed by #1849
Closed

Mismatch in documentation #1804

glatavento opened this issue May 10, 2022 · 5 comments · Fixed by #1849
Assignees
Labels
A-Documentation Area: Documentation E-Easy Experience: Easy

Comments

@glatavento
Copy link

glatavento commented May 10, 2022

At the beginning of this page, the field used to represent author is book.author (requires a string)

```toml
[book]
title = "Example book"
author = "John Doe"
description = "The example book covers examples."
[rust]
edition = "2018"

but then changed to book.authors (requires a list):

### General metadata
This is general information about your book.
- **title:** The title of the book
- **authors:** The author(s) of the book
- **description:** A description for the book, which is added as meta

and it should be the latter one, according to the config parser

mdBook/src/config.rs

Lines 403 to 420 in 981b79b

/// Configuration options which are specific to the book and required for
/// loading it from disk.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case")]
pub struct BookConfig {
/// The book's title.
pub title: Option<String>,
/// The book's authors.
pub authors: Vec<String>,
/// An optional description for the book.
pub description: Option<String>,
/// Location of the book source relative to the book's root directory.
pub src: PathBuf,
/// Does this book support more than one language?
pub multilingual: bool,
/// The main language of the book.
pub language: Option<String>,
}

(please point out if I have misunderstood)

@glatavento glatavento changed the title Contradiction in documentation Mismatch in documentation May 10, 2022
@ehuss
Copy link
Contributor

ehuss commented May 10, 2022

Oops, good catch! Yea, the docs should be authors plural.

@ehuss ehuss added E-Easy Experience: Easy A-Documentation Area: Documentation labels May 10, 2022
@ehuss
Copy link
Contributor

ehuss commented May 11, 2022

Oh my! I wonder how that division happened. I would prefer to keep only a single field, and authors seems reasonable to me. Mdbook doesn't even use the field for anything, so it's probably not too important. If #1595 is addressed, then that should handle any warnings for unknown fields.

@FauconFan
Copy link
Contributor

@rustbot claim

@kg4zow
Copy link
Contributor

kg4zow commented Jul 9, 2022

Maybe leave them both in there, with author allowing a single string and authors taking an array of strings? And if both happen to be present, add the author value to the authors array before returning from the parser function?

... wow, it looks like you did the merge while I was typing this. 😁

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Documentation Area: Documentation E-Easy Experience: Easy
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants