[Discussion] Change configuration file to toml instead of json

[azerupi]

In the beginning I choose json for the configuration file because it is what gitbook uses and I wanted to have maximum compatibility. Today I am less concerned about compatibility, the configurations exposed will not be the same anyways. And thus, another configuration format could make more sense?

Toml is quite popular for configuration files in the Rust community and it may be easier and clearer for the user to use.

Quick example:

{
    "title": "Example book",
    "author": "Name here",
    "destination": "/book",
    "source": "/src"
}

vs.

title = "Example book"
author = "Name here"

[paths]
destination = "/book"
source = "/src"

I like toml better because it offers a better structure and is cleaner, but I would like to hear what others think about this.

[azerupi]

After thinking a little bit about this, I think this is a good idea. Configuration files could look something like this in the future:

title = "An awesome book"
language = "en"
description = """
This is an awesome book that you should read!
"""

source = "/src"
output = "/book"

[[authors]]
name = "John Doe"

[multilingual]
languages = [
    {name="English", code="en", default=true},
    {name="French", code="fr"},
]

[[plugins]]
name = "MathJax"
enable = true

[[plugins]]
name = "rust-playpen"
enable = true

I haven't yet used TOML so I am not sure this example is 100% valid TOML.

[Croydon]

I don't know anything about TOML, but the project page states that it is unstable atm.
And I'm also not sure if this has any relevance at all for this case, but JSON is more accessible from any other language ect.

[azerupi]

Thanks for your feedback, really appreciate it! :)

I don't know anything about TOML, but the project page states that it is unstable atm

Interesting, I didn't even notice that.

It's used by Cargo and other Rust projects and has a good implementation in Rust. It should be stable enough for my needs here, I am not to worried about this.

JSON is more accessible from any other language

That's true, JSON is widely known by developers. It has been adopted by a lot of node / JavaScript projects for configuration files, but it was never really meant to be used that way.

I used it for the configuration file because I was mostly copying GitBook, but it doesn't feel like the most elegant solution to me.

TOML has kind of become the de facto configuration file format for Rust projects. It's dead simple to write and read by humans.

Also I would like to think that non-developers could use this tool too, so the easier the better 😉

[azerupi]

What it will look like

Here is how I envision the new configuration file:

book.toml

title = "mdBook"
description = """
This is a command line utility to generate books from markdown files
"""

[[author]]
name = "Mathieu David"
email = "[email protected]"
# other fields could be added

[source]
path = "src/"

# "outputs" is a table where each entry is the identifier of a renderer 
# containing the configuration options for that renderer
[outputs]
html = { path = "book/" }
pdf = { path = "pdf/mdBook.pdf" }
# OR alternatively
# [outputs.html]
# path = "book/"
#
# [outputs.pdf]
# path = "pdf/mdBook.pdf"

[languages]
en = { name = "English", default = true }
fr = { name = "Français" }
# OR alternatively
# [languages.en]
# name = "English"
# default = true
#
# [languages.fr]
# name = "Français"

[plugins]
syntax-highlighting = { enabled = true, default_language = "rust" }
code-line-hiding = { enabled = true, hide_pattern = "#" }
rust-playpen = { enabled = true }
# OR alternatively
# [plugins.syntax-highlighting]
# enabled = true
# default_language = "rust"
# 
# [plugins.code-line-hiding]
# ...

If there is an error in the TOML or something is / seems inconvenient, please do give feedback!

I will update here if I change the "spec"

[mkpankov]

Hi,

I'd like to point out that meta-information is specific to language of the book. That is, it should be possible to translate author name, book title, description in translated version. Besides, there's one field missing - translator's name. It's going to be different from author's name in all cases, I believe.

That said, I propose factoring out meta-information fields to language-specific sections. By default, if not specified, meta-information could be retrieved from "default" meta-information.

[azerupi]

That's a good point. I didn't consider that. I don't want to make the configuration overly complex for simple books that only have one author and one language. But supporting complex books should be handled correctly too. So if you have alternative designs and enhancements, feel free to post them!

[mkpankov]

I propose adding metadata section to each language section, except for default. Default language's metadata are the metadata. They are used if nothing translated is available. It could look like below.

title = "mdBook"
description = """
This is a command line utility to generate books from markdown files
"""

[[author]]
name = "Mathieu David"
email = "[email protected]"
# other fields could be added
...

[languages]
en = { name = "English", default = true }
ru = { name = "Русский" }

[languages.ru.metadata]
title = "Название книги" # default is original title
description = "Описание книги" # default is original description
author = "Имя Фамилия" # default is original author
translator = "Имя Фамилия" # default is empty (don't show)
...

[azerupi]

That seems pretty good to me and very flexible for the future, I like it.

Except that author / translator should probably be arrays of tables, for when there are multiple maintainers and you want to specify contact information etc.

author = [
    { name = "...", email = "..." },
    { name = "...", email = "..." }
]

[mkpankov]

I agree about multiple authors.

[gambhiro]

+1 for toml. It is also approachable by someone not having written code before. Json is for machines, it's hard to write by hand even with a good editor.

[azerupi]

TOML configuration support has been added since a while I think, but I am keeping this issue open because it contains a lot of discussion for future improvements.

[Michael-F-Bryan]

I believe the concerns raised in this issue were fixed in #457, so this should be safe to close.