Differentiate pandoc-args vs. quarto pandoc

[jidanni]

What would you like to do?

Report an issue on quarto.org

Description

These seem confusing.

$ quarto render help|grep pandoc
  pandoc-args... - Additional pandoc command line arguments.
$ quarto pandoc help
...

It would be best to mention on each one something about the difference
with the other.

Don't put the answer below. Put it in the code that prints the messages.Thanks.

[cderv]

I am sorry but I don't understand what you expect here.

quarto --help | grep pandoc
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.

❯ quarto --help | grep render
  render     [input] [args...]     - Render files or projects to various document types.

So quarto pandoc is to run pandoc directly using embeded version (this is for advanced usage or testing with same pandoc version as quarto render will use)
quarto render is to render a quarto document.

So when you call quarto render --help you can args for rendering the pandoc document. And quarto render takes options that quarto will catch, and others pandoc CLI supported arguments too which will be passed to pandoc CLI when quarto calls it. Which we document by Additional pandoc command line arguments.

Full doc this clear to me too

❯ quarto pandoc help

Usage:   quarto pandoc [args...]
Version: 1.9.37

Description:

  Run the version of Pandoc embedded within Quarto.

  You can pass arbitrary command line arguments to quarto pandoc (they will
  be passed through unmodified to Pandoc)

Options:

  -h, --help              - Show this help.
  --log         <file>    - Path to log file
  --log-level   <level>   - Log level (debug, info, warning, error, critical)
  --log-format  <format>  - Log format (plain, json-stream)
  --quiet                 - Suppress console output.
  --profile               - Active project profile(s)

Commands:

  help  [command]  - Show this help or the help of a sub-command.

Examples:

  Render markdown to HTML:    quarto pandoc document.md --to html --output document.html
  List Pandoc output formats: quarto pandoc --list-output-formats

So what is your suggestion to make this clearer ? I am asking genuinely because I don't see exactly what to add.

Thank you

[jidanni]

It seems the user --can --just --add --some --arguments

And some of them will be grabbed by quatro, and the remainder passed to Pandoc.

Well no wonder it's all a blur.

So maybe do --arg1 --arg2 --pandoc --arg3 --arg4

where only --arg3 and --arg4 will get passed to Pandoc.

Or maybe it's too late and people's scripts will break.

Yes, I suppose
$ quatro pandoc --arg1 ...
will cause all args to be sent to Pandoc, and none to quarto.

[cderv]

I am really sorry, however I really don't see what you are suggesting we should write. Please do not hesitate to share with me direct suggestion for this.

$ quatro pandoc --arg1 ...
will cause all args to be sent to Pandoc, and none to quarto.

Yes this is expected as quarto pandoc is called which is equivalent to calling bare pandoc, just the one used by quarto internally. So nothing is passed to quarto in this case.