Debug/see individual steps in yaml-knitr-pandoc-lua-tex toolchain

[baptiste]

Is there a way to get more information on the commands that are run by quarto? Specifically, with the previous Rmarkdown workflow I could see exactly what commands were passed to pandoc, which helped a bit debug individual steps in the toolchain (is it a Yaml option passed incorrectly? Is it a pandoc issue? Is it something that knitr produced? etc.)

As a specific example, I'm struggling to set the size of an image and keep the aspect ratio, for latex output. I suspect a combination of pandoc and quarto, but it's hard to tell what's happening.

![](penguins){width=100%}

gives me

\includegraphics[width=1\textwidth,height=\textheight]{penguins.pdf}

(and a stretched image)

while

![](penguins){width=100%,keepaspectratio}

produces

\includegraphics{penguins.pdf}

(this is mostly for the sake of concrete illustration, I'm also interested in the general toolchain debugging question)

[mcanouil]

There is a lot of pre-processiong done by Quarto, I am not sure all the logs are exposed and should be by default.
Although, Quarto CLI comes with many parameters (i.e., --log*, --debug, etc.), which you can use to debug:

quarto render --help 
#>
#>  Usage:   quarto render [input] [args...]
#>  Version: 1.0.37                         
#>                                          
#>
#>  Description:
#>
#>    Render input file(s) to various document types.
#>
#>  Options:
#>
#>    -h, --help                          - Show this help.           
#>    -t, --to                            - Specify output format(s). 
#>    -o, --output                        - Write output to FILE (use 
#>    --output-dir                        - Write project output to DI
#>    -M, --metadata                      - Metadata value (KEY:VALUE)
#>    --site-url                          - Override site-url for webs
#>    --execute                           - Execute code (--no-execute
#>    -P, --execute-param                 - Execution parameter (KEY:V
#>    --execute-params                    - YAML file with execution p
#>    --execute-dir                       - Working directory for code
#>    --execute-daemon                    - Keep Jupyter kernel alive 
#>    --execute-daemon-restart            - Restart keepalive Jupyter 
#>    --execute-debug                     - Show debug output for Jupy
#>    --use-freezer                       - Force use of frozen comput
#>    --cache                             - Cache execution output (--
#>    --cache-refresh                     - Force refresh of execution
#>    --no-clean                          - Do not clean project outpu
#>    --debug                             - Leave intermediate files i
#>    pandoc-args...                      - Additional pandoc command 
#>    --log                     <level>   - Path to log file          
#>    --log-level               <level>   - Log level (info, warning, 
#>    --log-format              <format>  - Log format (plain, json-st
#>    --quiet                             - Suppress console output.  
#>
#>  Commands:
#>
#>    help  [command]  - Show this help or the help of a sub-command.
#>
#>  Examples:
#>
#>    Render Markdown:    quarto render document.qmd                  
#>                        quarto render document.qmd --to html        
#>                        quarto render document.qmd --to pdf --toc   
#>    Render Notebook:    quarto render notebook.ipynb                
#>                        quarto render notebook.ipynb --to docx      
#>                        quarto render notebook.ipynb --to pdf --toc 
#>    Render w/ Metadata: quarto render document.qmd -M echo:false    
#>                        quarto render document.qmd -M code-fold:true
#>    Render to Stdout:   quarto render document.qmd --output -       

PS: It's more a "Q&A" discussion than a "general" discussion.

[baptiste]

Thanks – I think it might be helpful to offer the option to have the full pandoc command available for copy-paste in the logs; currently it looks like it's formatted for legibility (which is nice for normal use, but not as useful for debugging intermediate steps)

[jjallaire]

Full disclosure that the actual pandoc command is more complicated that what is shown (e.g. we implement some pandoc features like number-sections internally in our Lua filters so while number-sections: true appears in the printout we actually pass number-sections: false). That print-out is mostly informational to show the user how their metadata resolved/merged and note differences in pandoc defaults that our formats use. The actual pandoc command involves lists of filters and temporary include files (which are removed after render) so there isn't a practical way to preserve exactly the pandoc command and re-run it (as you can do e.g. for .tex).

All of that said, I have found it personally useful for debugging a number of times to show what's actually sent to pandoc so I do think a mode that prints all of this clearly (and/or writes it to a log dir) would be quite useful and something we should do sooner rather than later.