Render pdf one file at a time

[memeplex]

Description

When I'm working on a pdf project, I would like to quickly preview the current chapter/section. I assume this means that I need to render just a small piece of the entire project, so I split the project in many small files to begin with. Now, I've read about Incremental rendering and Render targets but I'm not sure whether I'm understanding what they bring to the table, specially for a pdf project.

For example, suppose this is my project config:

project:
  type: book

book:
  title: "mybook"
  chapters:
    - index.qmd
    - chapter1.qmd
    - chapter2.qmd

format:
  pdf:
    keep-tex: true

If I run quarto render chapter1.qmd --to pdf both chapters are included in the generated tex file.

If I add:

project:
  ...
  render:
    - chapter1.qmd

to the config and run quarto render --to pdf again both chapters are included.

The only way I found to work on a file by file basis is to comment out all other documents in the chapters section.

Is this right or am I missing something?

Thanks.

[danieltomasz]

#7762 (reply in thread)

[memeplex]

Thanks, I'd read that and it's indeed useful and better than what I'm doing right now, but I still would like to understand why the render: ... option is not leaving the other files out.

[memeplex]

Anyway, how do you merge your profile? According to https://quarto.org/docs/projects/quarto-projects.html#metadata-merging:

objects and arrays are merged rather than simply overwriting each other

The example there is clear in that regard:

bibliography:
  - refs.bib

+ 

bibliography:
  - proj.bib

= 

bibliography:
  - refs.bib
  - proj.bib

In https://quarto.org/docs/projects/profiles.html#overview it says:

Profile specific config is merged with the top-level _quarto.yml.

Since I have a superset of the documents I would like to render in _quarto.yml, how would I manage to filter some of them out by using a profile?

Or perhaps you do it the other way around and the profile is for the full output?

[danieltomasz]

@memeplex render leaving the other files out, but as your other question go, you are actually merging your yaml from your chapter file and your yaml profile.
If you temporarily add another definition of project to your yaml of the chapter file, you will observe that only that chapter is rendered (quarto always look for _quarto.yml nearest in the hierarchy of catalogues, sometimes it might be several folders aways, and then it is merged with your file yaml)

[danieltomasz]

only ways to avoid using default _quarto.yml (if exist within your project) and stop it from merging is to use of another profile (it could be event dummy empty profile)

[danieltomasz]

Profiles arent merged if they are on the same level, only files + profiles

[s2t2]

I am also thinking that quarto render /path/to/my/file.qmd --to pdf should only render the specific file I mentioned. I am also confused why all the chapters in my book are getting rendered.

[danieltomasz]

https://quarto.org/docs/projects/quarto-projects.html#project-metadata

[mcanouil]

@danieltomasz accessibility: please reformat your links, they are ineligible to everyone.
If you intend to quote some of the documentation, do so as you would in Markdown and add the link with a meaningful link text.

[mcanouil]

@s2t2 Books in LaTeX are a single document format. You might think chapters are independent but they are not.
Everything is put together in one single file for LaTeX to be able to render it.

If you intend to get single output for chapters, you need to use Quarto profiles to use default type project, which then (when activated) would allow you to do what you want while also allowing to render your whole book.
But even with this trick, you won't get your single chapter as a book on its own.

[s2t2]

It would seem the differences between desired and actual behavior and capabilities might warrant consideration for an improved, more intuitive user experience.

[cderv]

To clarify a little the behavior:

PDF Books are indeed single file output, so Quarto needs to know about the other chapter to be able to render one. The render target is driven by the chapter in the book, coupled with the projet option.

Quarto tries to be helpful and clever but no re-running execution on preview and incremental render. This means that first time a document is rendered for a book there is an internal freeze state saved (in .quarto), which allows next render of a chapter to be quicker, while style rendering the document to get correct references , and all other cross chapter things right. quarto preview will be the same thing.

Explicit freeze option in Quarto YAML will have same behavior but you'll get the freeze folder, which is another way to handle this. But in this case freeze will be used for quarto render of the project, which is different.

Internal mechanism is really to speed the rendering for working on a single document. And this what also allows to work in Preview mode efficiently: https://quarto.org/docs/books/#book-preview

If this does not suit you, the project profile tricks allow you to switch to the default project and single-file render. In this context, the other file does not matter to render another.

I let you try it:

• First time your render a chapter, all of them will be rendered and executed
• Next render /preview of a single chapter, it should be quicker as saved state will be used.

Then doing a quarto render for the project will not use saved state, and all should be reexecuted.

Hope it helps understand.