How can I enable the file_scope option?

[jtbayly]

I just discovered that the feature I'm using to make basic numbered footnotes work has been disabled by default on upcoming versions of bookdown.

It appears that the functionality is still present in the code if only I could figure out how to enable it. Before, the instructions were for how to disable it:

This behavior can be toggled off by setting `options(bookdown.render.file_scope = FALSE)`.

Obviously, I want to set that option to TRUE. But I don't have the foggiest clue where/how to do this.

I tried putting things like file_scope: true in various files in various places, but I just can't get it to do anything.

[jtbayly]

I think I found the answer here and here.

Although @yihui says in the latter link

You can set this option in either your Rmd document or ~/.Rprofile .

This is apparently incorrect, according to @cderv. This can only be set as an environment variable, not in your Rmd document, meaning you have to put it in your profile or use a command to set it.

I know this might sound bitter, but man that's irritating. That makes at least 4 places now that I need to keep track of and set in order to get bookdown to work properly.

1. _bookdown.yml
2. _output.yml
3. index.Rmd
4. environment variables

And now that we've got environment variables coming into play, I'm pretty sure that means I can't put the settings into my book files. That in turn means that I can't share the book files with somebody and expect them to be able to build the book. I have to share the book files with them and give them instructions on how to set their environment variable before it will work. All just to have basic numbered footnotes working. Am I misunderstanding this?

[cderv]

@jtbayly

This can only be set as an environment variable

Not environment variable but R options. That is not the same. The former is .Renviron, the latter is .Rprofile. You can also set options just before rendering

options(bookdown.render.file_scope = FALSE)
bookdown::render_book("index.Rmd")

or using

withr::with_options(
    list(bookdown.render.file_scope = FALSE), 
    rmarkdown::render_book("index.Rmd")
)

I agree with you that there is a lot of places to configure for bookdown behaviour of format behavior. This would be to be simplify.

@jtbayly

I can't put the settings into my book files. That in turn means that I can't share the book files with somebody and expect them to be able to build the book. I have to share the book files with them and give them instructions on how to set their environment variable before it will work

You can put the setting in your rendering file (like _render.R or Makefile or other...)
but yes not in one of the project file. This is at the level of render like render arguments for now. (config_file for example)
Sharing such file to explain how to render is also a good idea IMO.

@jtbayly

All just to have basic numbered footnotes working.

Why footnotes numbering is not working for you ?
Take care that file scope from Pandoc can have side effect, like links not working accross files. That is why it has been deactivated by default in current dev versions. This need to be adressed.

[cderv]

@cderv

Why footnotes numbering is not working for you ?

I guess you mean restarting numbering at each chapter right ?

The behaviour in bookdown from a long time was to number from 1 to X in the whole book.

[jtbayly]

Thanks once again for helping out. I've not gotten around to making my own _render.R file yet, but I guess I'm going to have to, now.

@cderv

I guess you mean restarting numbering at each chapter right ?

Not quite. How they are (inconsistently) labeled on output is a separate issue (with a mostly workable solution).

I just want people working on the books not to have to worry about what footnotes are named between chapters. The way that most people are going to default to doing footnotes just doesn't work.

Right now if I have chapter one and name the footnotes 1, 2, and 3, when I work on chapter two, I cannot use those names anymore or the book will output the wrong footnotes on chapter two. I have to start with footnote 4. So if I go back and add a fourth footnote to chapter 1, that means I need to renumber every later footnote in the whole book, as opposed to just renumbering to the end of the chapter.

Or is there a way to use random, non-conflicting names for my footnotes automatically, or just a reasonable way to name them other than numbering that I haven't thought of? Inserting them inline without names makes the markdown very hard to read, and I don't even think it's possible if you have multi-paragraph footnotes.

[cderv]

@jtbayly

Or is there a way to use random, non-conflicting names for my footnotes automatically, or just a reasonable way to name them other than numbering that I haven't thought of?

Have you tried not using numbers ?
I believe you can use any identifier and not just number. See the [^longnote] example in the documentation https://pandoc.org/MANUAL.html#footnotes

You could also use two digits numbering for example

• Chapter 1 : [^10], [^11], ...
• Chapter 2 : [^20], [^21], ...

Dummy example that works: Try add this in one of the Rmd of a Demo book

Some footnote[^footnote] and an other[^21]


[^footnote]: Something

[^21]: Something else

Using this would allow to add some footnotes afterwards without thinking of the automatic numbering.

Would that answer your need ?

@jtbayly

Not quite. How they are (inconsistently) labeled on output is a separate issue (with a mostly workable solution).

Oh I saw that issue, yes this is a feature and what file scope should have provided but without the side effect would be better.

[jtbayly]

@cderv

Using this would allow to add some footnotes afterwards without thinking of the automatic numbering.

Would that answer your need ?

I like your idea of using chapter number followed by footnote number.

Using some non-numbers and some numbers is just asking for confusion when you go to edit footnote number 23, and it's actually labeled footnote 22 in the markdown... or footnote 20 and it's actually labeled "footnote" in the markdown. I'm trying to make this editing work possible for volunteers without a lot of technical skill. So I don't think that will work.

[cderv]

@jtbayly

Using some non-numbers and some numbers is just asking for confusion when you go to edit footnote number 23, and it's actually labeled footnote 22 in the markdown... or footnote 20 and it's actually labeled "footnote" in the markdown. I'm trying to make this editing work possible for volunteers without a lot of technical skill. So I don't think that will work.

Oh OK I see, you want the number seen on the output to be the same in the source input, and for this to be numbered by chapter. I understand now. Thanks for the clarification.

We should definitly see if this file scope option can provide that without side effect.

[yihui]

FYI if you use the visual Markdown editor, the footnotes will have unique and automatic IDs, so there is nothing you need to worry about. You may want to try that, instead of manually assigning IDs to footnotes.

[jtbayly]

The visual Markdown editor sounds nice, and I'm looking forward to trying it.

However, I doubt most of my editors will be using RStudio, since it is a very heavy application to install, and quite the learning curve just to edit some markdown files. However, I think @cderv's suggestion for how to manually assign numbers in a sensible way will work well for us.

I appreciate all the help.

[cderv]

@jtbayly

However, I doubt most of my editors will be using RStudio, since it is a very heavy application to install, and quite the learning curve just to edit some markdown files.

Out of curiosity, what tools do they use ?
The visual Markdown editor makes the experience to write Markdown file very smooth, and with great integration with R packages like bookdown: https://rstudio.github.io/visual-markdown-editing/

[jtbayly]

@cderv

Out of curiosity, what tools do they use ?

Good question. Dreamweaver, BBEdit, or whatever other text editor they are already comfortable with, along with the online editor on Github.

It seems to me that there are some problems with every visual editor, including the RStudio Preview version.

1. They don't support all of the features you are using in the code, so you have to drop into code mode to do what you want some of the time, anyway. Take the following code, for example:

   ("[non modo salutaria exercitia, et adjumenta pietatis, sed etiam *efficacia gratiæ instrumenta*]{lang=la}."

   There is no indication in the visual editor that a language code has been set on that text, much less an ability to set it. So I have to switch to code mode to even see whether it is there.

2. They will change your code to match their own rules, sometimes breaking things in the process, and sometimes just in a way you don't want.

   For example, we decided to use a backslash followed by a space to represent a non-breaking space in our texts for a couple of reasons. First, it's by far the easiest way to explain to a non-technical user how to insert a non-breaking space. Second, it's visually verifiable in every text editor, whereas an actual non-breaking space is sometimes indistinguishable from a regular space. For example, on Github, which is where the "edit" button at the top of the book takes you, non-breaking spaces are indistinguishable both in viewing and editing mode. It sort of makes sense to convert the backslash space to an actual non-breaking space, since RStudio handles just fine, but this code change is not welcome for us since we need to be able to verify on Github that the code is correct.

   Here's another example of code being changed in RStudio Preview. Our original code:

   "*[Præstat* igitur vere Deus quicquid signis promittit ac figurat; nec effectu suo carent signa, ut verax et fidelis probetur eorum Author]{lang=la}").—*Comment. in* Gal.

   Perhaps, ideally the first "*" should be inside the bracket, but it works fine as is. Switching to the visual editor in RStudio changes it to the following, which is broken:

   "[*Præstat\* igitur vere Deus quicquid signis promittit ac figurat; nec effectu suo carent signa, ut verax et fidelis probetur eorum Author*]{lang="la"}*").---*Comment. in\* Gal.

   We also settled on a naming convention for footnotes, but RStudio renames them all according to its own convention. We could switch to that naming convention, but then anybody editing outside of RStudio is going to have a much harder time working on footnotes.

Given these sorts of problems, when the new version of RStudio comes out, I will have to be very careful to not open any of our files in the visual editor mode.

Leaving aside the visual editor, though, our workflow is organized around Github and Travis CI, and I keep running into discrepancies between how things work locally vs on Travis. Thus, working in RStudio where you can build the book locally can actually become a liability since the built book might not be exactly what you are expecting when you push your changes to Github and it gets rebuilt on Travis. It is better in my experience to just push your changes and verify on the actual build in a couple of minutes.

Finally, RStudio cannot just be downloaded and run. You have to first download R, and install that, then you can install RStudio. But that almost certainly still won't allow you to build books locally without error. You'll probably be missing a font we use, and you'll have to download and install some LaTeX package, which probably means installing Brew... Or you could just git clone the project and edit the files in whatever you already have.

P.S. It's really disconcerting and a bit concerning to me that https://rstudio.github.io/visual-markdown-editing/ does not use bookdown. I'd really love to see you guys dogfood that, because some of the issues it solves, such as search working on mobile, make me very jealous.