Remove _output.yml and keep all changes in index.Rmd

[liutiming]

Suggestion for improvement:

Thanks so much for this fantastic package. As someone who just created his first book from the bookdown-demo template, I think the following feature may reduce the newbie's learning curve:

1. Remove _output.yml so that the user only has to modify index.Rmd to finish necessary customization. The title of the toc and the edit link can be taken from arguments in the index.Rmd header i.e. (title and github-repo)
   • Reason: Take github-repo for example, if one person has edited that in the index.Rmd header, it will be very stressful to figure out why the edit link still directs them to the bookdown repo. I only figured this out by reading this slide. If the book title is too long for toc title, there can be an argument in index.Rmd heading for toc-title?
2. render_book() can take in the argument from index.Rmd header and automatically generate all output formats specified and then generate link for download (again remove the need to specify that in _output.yml).
3. continuing from 2: A more user friendly way may be to present each argument as a TRUE/FALSE option so that the user do not have to dig out what is the command name. (for example, one has to look up the documentation to realise it is not mobi_book to produce mobi and not word_document to produce docx files. Changing it to TRUE/FALSE or even providing a GUI later on will help a lot of users who just want to get the book published.
   • Reason: I understand why it is important to allow room for customization as seen from this pull request but I feel that should be more like exceptions rather than default. i.e. most users will probably want books to be generated once they have specified that they want it in the index.Rmd folder and then the download option will be available. Otherwise, it will take three manual steps (specify in index.Rmd, _output.yml, and then run render_book command for that specific format) to get to the ideal results. Basically, it is like turning on a computer and then one has to turn on the mic and speaker manually. Customization is hugely appreciated but the default option should be the most common use case.
4. In the same vein, publish_book() should render_book() for all formats by default, and take in the book's name for the name argument.
5. This might be a big more difficult but if there is a collaborative platform other than GitHub and allows people to edit markdown in its rendered form (e.g. visual editor from mediawiki) it really will help people who co-author books with non-programmers.

Really just my two cents. You have done a fantastic job! Thank you very much!

[cderv]

That is awesome feedbacks! Thank you !

About 1. , I believe this is related to #921 and something that should be rethink.

About 2., this is not the default, but if you provide output_format = "all" in rmarkdown::render_book it will render all the defined output. Did you know that or should it be better documented ?
By default, only the first format defined is used. We could think about changing the default but I don't know if rendering all output each time by default is a good idea. Also considering, you can do that in the IDE if desired by configuring the "Build book" button to "All Format" to render all by default with the button

About 3., you talk about a GUI, what do you wish to be more clearly presented ? the choice of output formats and their configuration ? Would an addin in the IDE be a good addition in your opinion ?

About 4., publish_book has the render argument that you can use to ask for a rendering. Currently, using "local" will only render the default output. This function is using the rsconnect 📦 , so I guess some improvement can be made there to render all if asked.
I am not sure publish_book should render by default all the format. I see the workflow as : (1) write the book and iterate by building locally an previewing the book (2) insure you have the expected result before publishing, (3) publish the version you have check locally. Do you have a different workflow ?

Customization is hugely appreciated but the default option should be the most common use case.

Rethinking our default behavior throughout the packages is something that we intend to look into. I strongly share your opinion. IMO the not-easy part is to know which is the "most common use case" 😄 .
So user's feedback is crucial - so very thank you for this !! Do not hesitate to keep them coming.

[liutiming]

Thanks so much for the prompt reply!

About 2., this is not the default, but if you provide output_format = "all" in rmarkdown::render_book it will render all the defined output. Did you know that or should it be better documented ?

wasn't aware of this... Yes I think definitely before we do any changes to the software, if we can include one chapter in the bookdown book that give a quick direction on how to produce a minimal customized book, that will be awesome.

Also considering, you can do that in the IDE if desired by configuring the "Build book" button to "All Format" to render all by default with the button

I am not sure how I can do that?

About 3., you talk about a GUI, what do you wish to be more clearly presented ? the choice of output formats and their configuration ? Would an addin in the IDE be a good addition in your opinion ?

yes that will be awesome. I guess just a tick box of what formats to be rendered will be good. Not sure how it will look like with the configurations but that will be great!

I am not sure publish_book should render by default all the format. I see the workflow as : (1) write the book and iterate by building locally an previewing the book (2) insure you have the expected result before publishing, (3) publish the version you have check locally. Do you have a different workflow ?

Ah ok basically it took a lot of reading to realise that you need to render all book formats before you publish them. Well I tend to think of it like git. If it is a simple vc use and you don't have many branches created, then in most cases I tend to write a customized function that groups git add, commit and push altogether.

So if a user wants to publish, why do we want to force them to render first, check all formats and then publish. Those who care about format will do it anyways. It is a bit like Microsoft word forcing you to go through all spelling checks before you can save a document if that makes sense.

[cderv]

if we can include one chapter in the bookdown book that give a quick direction on how to produce a minimal customized book, that will be awesome.

We could complement this one maybe ? https://bookdown.org/yihui/bookdown/usage.html

I am not sure how I can do that?

This is only mentioned here with not screenshot https://bookdown.org/yihui/bookdown/rstudio-ide.html

When you have set site: bookdown::bookdown_site in index.Rmd, RStudio will be able to discover the directory as a book source directory,11 and you will see a button Build Book in the Build pane. You can click the button to build the whole book in different formats, and if you click the Knit button on the toolbar, RStudio will automatically preview the current chapter, and you do not need to use preview_chapter() explicitly.

site: bookdown::bookdown_site is set by default in the template book. You can then go to the build pane and chose to build all or only one format

yes that will be awesome. I guess just a tick box of what formats to be rendered will be good. Not sure how it will look like with the configurations but that will be great!

Great ! Have you some more ideas in mind of what would be useful to you or others from what you experience ? If so, we welcome a new issue to describe the main features you would find useful in such an Addin. Otherwise, I'll open one from what I understand from our discussion. Having it in a separate issue will allow us to get some more feedbacks from others I believe.

Ah ok basically it took a lot of reading to realise that you need to render all book formats before you publish them. Well I tend to think of it like git. If it is a simple vc use and you don't have many branches created, then in most cases I tend to write a customized function that groups git add, commit and push altogether.
So if a user wants to publish, why do we want to force them to render first, check all formats and then publish. Those who care about format will do it anyways. It is a bit like Microsoft word forcing you to go through all spelling checks before you can save a document if that makes sense.

Same thoughts come in mind with your git example: I would not promote to do git add, git commit, git push because I find it prone to error. However, I see your point.
If such function would be more verbose by default when used interactively in the IDE, would that be useful to you ?
It would mean not changing the current default in the function, but if the function is used interactively, it would ask what you want to do with some confirmation. A bit like usethis interactivity in a way if you know it. It would allow to present to the user a set of option without needing to really know them before hand.
Do you think such thing would answer your case ?

Something like

> bookdown::publish_book()
--> Do you want to render before publishing ? 
1: All format
2: Only specific
3: Do not render and publish as-is
Selection: 

[liutiming]

The ideas here are great! thank you so much!