Document in more places that `output-dir` will be deleted

[petrelharp]

The output directory is (usually) completely deleted (see eg #13623). In the related issue #13892, @mcanouil said

See quarto render --help .

However, quarto render --help does not actually say anything about this rather important point. Currently, this is what it says:

  --output-dir                        - Write output to DIR (path is input/project relative)

and I propose changing this to, perhaps:

  --output-dir                        - Write output to DIR, which is first deleted if it exists (path is input/project relative)

This misses some subtlety, of course.

I'm currently trying to find where in the docs it actually says that the directory will be deleted. I'm sure it says it somewhere, but it's a bit hard to find. I would suggest adding this VERY IMPORTANT caveat to all the places it discusses output-dir.

For instance, on project options:

Same thing on project options for websites:

Similarly, this fact is not mentioned on the Output Path section for books.

Tangentially, this is not mentioned either in at least this place in TPG.

[petrelharp]

I'm happy to do a quick PR for this if there's not opposition.

[mcanouil]

It's indeed not mentioned in --output-dir but is in --no-clean.

--no-clean                          - Do not clean project output-dir prior to render

---

Important

Accessibility: To improve accessibility, please add alternative text to your screenshots. This helps all users, including those using screen readers, to understand the context of the images. A brief description can make a big difference! See Good Alt Text, Bad Alt Text — Making Your Content Perceivable.

[petrelharp]

Good point, but (a) this is easy to miss, and (b) this is not as unambiguous as I think this ought to be (what does "clean" mean?). Like, if I just want to know about --output-dir then I will not find out this fact. If I very carefully read every line in (short!) help, and think about it, then I would pick up on the fact that the --no-clean implies that the output-dir gets "cleaned", and then wonder what "clean" means sufficiently to go experiment with it.

[mcanouil]

My comment was not to say it's not needed to improve the help and documentation. It was only to explain where it was as a reply to the very beginning of your issue.

However, quarto render --help does not actually say anything about this rather important point.

[mcanouil]

If you are willing to make PRs:

• The website (guides): https://github.com/quarto-dev/quarto-web
• The website (reference pages):

  quarto-cli/src/resources/schema/project.yml

  Lines 25 to 27 in 9c6d652

  	output-dir:
  	path:
  	description: "Output directory"

• The CLI:

  quarto-cli/src/command/render/cmd.ts

  Line 40 in 9c6d652

  "Write output to DIR (path is input/project relative)",

[petrelharp]

Related: it looks like there is no way to specify --no-clean in the YAML? Or am I missing something?

[mcanouil]

Indeed, there isn't.