Bookdown newbie question

bookdown

#1

Hi,

I have just started to loot into porting a very large user manual into bookdown. From the beginning of the reference guide (https://bookdown.org/yihui/bookdown/theming.html), it seems that multiple Rmd files can be used: one per chapter.
My question is: can I break a chapter onto multiple Rmd files and merge the whole thing?


#2

yes, you can. just do it.


#3

Hi,

This generally works. There is one formatting problem though when one uses bibtext references in .Rmd files which are not chapters (## level and down): the html contains one to many resulting in References section showing with improper formatting and alignment.

I will submit a github issue.


#4

one way to break a chapter into multiple files is to use the child feature to pull in subchapter sections.

In the main chapter rmd you would include a chunk like this:

```{r child="chapter2-b.Rmd", echo=FALSE}

#5

Thanks @jdlong

This happens to solve the bibtext reference formatting problem...
A thing to consider though is that using this notation will combine the outputs of the chapter and child .Rmd files into a single html file. If there is a large amount of material to display, the html page can take a long time to load.


#6

This is a pretty unique edge case. You initially asked, "can I break a chapter onto multiple Rmd files and merge the whole thing?" but that's doesn't seem like what you want. What I think you want is nonlinear chapter numbering:

Ch 1a: intro part 1
Ch 1b: intro part2
Ch 2: some stuff
Ch 3a: long chapter part a
Ch 3b: long chapter part b
Ch 3c: long chapter part c

That's going to be hard as it breaks the chapter number paradigm completely.


#7

"This is a pretty unique edge case. "

I happen to work on a user manual with about 150+ Rmd files, 200,000 words, hundreds of images/screen captures... So I kind of jumped directly into the deep end of the bookdown pool :smiley:

"Can I break a chapter onto multiple Rmd files and merge the whole thing?"
I meant can I create a bookdown with multiples Rmd which are either chapter and subsections. So the answer provided by @dapeng is right and allows the structure you referenced (with each row being a Rmd and a gitbook html):

Ch 1a: intro part 1
Ch 1b: intro part2
Ch 2: some stuff
Ch 3a: long chapter part a
Ch 3b: long chapter part b
Ch 3c: long chapter part c

Overall, I would say that it is a matter of adapting the solution to the specific content and need of the book.


#8

Hey @pomchip I’m not sure if what you’re interested in doing is possible or not, but wanted to ask how wedded to that organizational format you were?

If you take a look at a lot of the bookdown books out there, including the authoritative guide to R Markdown, you’ll notice that there are part numbers in Roman numerals. Could you organize using parts and chapters instead of chapters and sub chapters?


#9

@chris.prener

I forgot I read that from the reference bookdown guide. What looks interesting to me is the alignment in TOC which saves a bit of real-estate...
Do you know if there is a way to restart the numbering of chapters in each part?


#10

Not that I’m aware - the chapter numbering has implications for how the html files are named and for cross referencing things like tables, so I think there are a couple reasons for not readjusting this numbering.

Are you ultimately going to be displaying this book online or as a pdf or both?


#11

One thought I just had @pomchip - check out the source for Kieran Healy’s visualization book - he has an appendix section at the end where the chapter numbering has been modified. That might give you some clues about possible changes you can make.


#12

Thanks @chris.prener

Kieran's github does not seem to include the source of his book... or I did not look at the right spot.


#13

hm I wonder if it was taken down - I could have sworn it was up beforehand. Sorry about that! At least you know some modifications are possible.

Re my other question - Are you ultimately going to be displaying this book online or as a pdf or both? This seems like a project better suited for LaTeX if the chapter numbering is so consequential.


#14

@Chris

I am still on the fence regarding the format. My preference, right now, is to use the html gitbook format because of the fairly large size of this document and how users would access to it. Also, I had to use pure html tags to create many tables with complex designs. My understanding is that the LaTeX/pdf output would simply ignore those. I could get a pdf by creating an epub which I, then, convert to pdf using Calibre. There is maybe a better way to go about that, but that's what I have right now :smiley:

I am not attached to a particular numbering style, as long as there is some form of resetting for the subsection numbering within chapters, which the #, ##, ### formats allow. My titles are a bit long, so gaining a bit of real-estate in the TOC would be nice (although not critical). I am considering removing numbering all together using {-#} tags...


#15

Maybe I'm confused (totally possible!) - you want to reset numbering within chapters for sections or within parts for chapters?