various edits to qmd example

_layouts/default.html

@@ -56,6 +56,7 @@ <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repo
         <nav>
           <a href="{{ "/" | absolute_url }}">Main content</a> |
           <a href="demo">demo (HTML) output (from Rmd source)</a> |
+          <a href="demo-q">demo (HTML) output (from qmd source)</a> |
           <a href="python-in-RStudio">Python chunks in RStudio</a> 
         </nav>
         </div>

demo.qmd → demo-q.qmd

@@ -49,9 +49,6 @@ quarto_render("demo.qmd", output_format = "pdf")
 Or in RStudio (version at least 2022.07), click on the 'Render' button and choose to knit to HTML, PDF, or Word (for R Markdown).
 
 
-
-
-
 # 2) Some basic Markdown formatting
 
 
@@ -77,7 +74,21 @@ Here's a displayed equation
 
 $$
 f_\theta(x) = \int f_\theta(y, x) dy.
-$$ 
+$$
+
+You can define LaTeX macros in a qmd file and then use them, like this:
+
+$$
+\newcommand{\trans}[1]{{#1}^\mathsf{T}} 
+$$
+
+```
+\newcommand{\trans}[1]{{#1}^\mathsf{T}}
+```
+
+$$
+A = \trans{X}Y
+$$
 
 # 4) Embedding R code
 
@@ -167,6 +178,17 @@ print("hi")
 mean(b)
 ```
 
+You can control which executable is used to execute a given chunk of code by  (particularly useful for Python and bash and for debugging), using the `engine.path` chunk option.
+
+```{python}
+#| echo: fenced
+#| eval: false
+#| engine.path: /usr/bin/python2
+a = 3
+print a
+```
+
+It's not uncommon to have various Python executables installed (different versions, in Conda/Mamba environments, etc.) on your system or to be unclear about which shell is being used to execute a shell chunk. Manually setting `engine.path` can help figure things out or work around problems.
 
 # 6) Embedding bash, Python, and Julia code
 
@@ -195,6 +217,16 @@ pwd  # result would be /tmp if state were preserved
 
 Inline bash code won't work: `bash wc demo.Rmd`, unlike with R code.
 
+If you are using the `jupyter` engine and want to have both bash and Python chunks in a document, or you don't want to have to install a bash Jupyter kernel, you can use ipython magic to run bash code within a Python chunk:
+
+```{python}
+#| eval: false
+!echo "hello from python"
+!pwd
+```
+
+One can also use `zsh` or other shell chunks, replacing the "bash" label with "zsh" or the other shell. 
+
 ## 6.2) Embedding Python code
 
 You can embed Python code. As with R, state is preserved so later chunks can use objects from earlier chunks. 
@@ -228,6 +260,19 @@ print(2)
 
 There is no facility for inline Python code: `python print(3+5)`
 
+To display code from a file of Python code, you can use functionality in the `inspect` module.
+This code would display the definition of `doubled()` from the `my_code` module.
+
+```{python}
+#| eval: false
+import my_code
+import inspect
+print(inspect.getsource(my_code.doubled))
+```
+
+
+This will work for functions and for class definitions.
+
 ## 6.3) Embedding Julia code
 
 You can embed Julia code. As with R and Python, state is preserved so later chunks can use objects from earlier chunks. 
@@ -252,15 +297,23 @@ There is no facility for inline Julia code: `julia print(3+5)`
 
 # 7) Reading code from an external file
 
-It's sometimes nice to draw code in from a separate file. Before invoking a chunk, we need to read the chunks from the source file, which contains the chunks tagged with some special formatting. Note that a good place for reading the source file via `read_chunk()` is in an initial setup chunk at the beginning of the document.
+It's sometimes nice to draw code in from a separate file. Before invoking a chunk, we need to read the chunks from the source file, which contains the chunks tagged with some special formatting.
+
+This only works with the `knitr` engine.
+
 
 ```{r}
 #| label: read-chunk
-#| echo: false
+#| echo: fenced
 library(knitr)
-read_chunk('demo.R')  ## contains external_chunk_1 and external_chunk_1
+read_chunk('demo.R')  ## contains external_chunk_1 and external_chunk_2 of R code
+read_chunk('demo.py')  ## contains external_chunk_3 of Python code
 ```
 
+Note that a good place for reading the source file via `read_chunk()` is in an initial setup chunk at the beginning of the document.
+
+Here are two R chunks whose code is in `demo.R`.
+
 ```{r}
 #| label: external_chunk_1
 ```
@@ -269,6 +322,25 @@ read_chunk('demo.R')  ## contains external_chunk_1 and external_chunk_1
 #| label: external_chunk_2
 ```
 
+And here is a Python chunk whose code is in `demo.py`.
+
+```{python}
+#| label: external_chunk_3
+```
+
+
+
+To display function or class definitions from a file of Python code, you can use functionality in the `inspect` module.
+This code would display the definition of `doubled()` from the `my_code` module.
+
+```{python}
+#| eval: false
+import my_code
+import inspect
+print(inspect.getsource(my_code.doubled))
+```
+
+
 # 8) Formatting of long lines of code and of output
 
 ## 8.1) R code

demo.py

@@ -0,0 +1,10 @@
+## The first chunk uses one format for indicating a chunk of code,
+## and the second uses the knitr style.
+
+## ---- external_chunk_3 ----
+a = [3,4,5]
+print(len(a))
+
+## @knitr external_chunk_4
+a = [3,4,5]
+print(len(a))

index.md

@@ -49,7 +49,7 @@ In [demo.Rmd](demo.Rmd), you'll see examples of embedding R, Python, and bash co
 
 ## 4 Quarto and qmd files
 
-Quarto is a somewhat new project meant to extend R Markdown to a more general purpose system that doesn't focus on R and that  also work with Jupyter notebooks. You can create `qmd` files that use the same syntax as R Markdown (`Rmd`) files or that use slightly modified syntax, as demonstrated in `demo.qmd`. Quarto also allows you to easily render output files from qmd, R Markdown, and Jupyter notebook files. And you can use Quarto to convert Jupyter notebooks to the qmd format. This is nice in part because qmd (like Rmd) is more easily handled by version control and with shell commands than the JSON format of .ipynb files.
+Quarto is a somewhat new project meant to extend R Markdown to a more general purpose system that doesn't focus on R and that  also work with Jupyter notebooks. You can create `qmd` files that use the same syntax as R Markdown (`Rmd`) files or that use slightly modified syntax, as demonstrated in [demo-q.qmd](demo-q.qmd). Quarto also allows you to easily render output files from qmd, R Markdown, and Jupyter notebook files. And you can use Quarto to convert Jupyter notebooks to the qmd format. This is nice in part because qmd (like Rmd) is more easily handled by version control and with shell commands than the JSON format of .ipynb files.
 
 ### Rendering engines
 
@@ -63,12 +63,14 @@ You can specify the engine by adding information to the YAML configuration infor
 engine: knitr
 ```
 
+One benefit of using the `knitr` engine is that output from a chunk is interleaved with the code of the chunk, whereas with the `jupyter` engine (as with a Jupyter notebook), all output from a chunk appears after the entire code chunk is displayed.
+
 ### Tools for developing qmd documents
 
 Here are a few approaches you can use to interactively develop your documents.
 
   1. **Text editor + quarto preview**: The most basic approach is to use your favorite text editor and run `quarto preview file.qmd` from the command line (including Windows cmd.exe or PowerShell). Assuming that you've done an initial rendering of the document, this will display the output in a browser window and update the output any time you save the qmd file.
-  2. **VS Code**: You can use VS Code with the Quarto extension. (If using Python chunks, you will probably also need the Python and Jupyter extensions). The extension will provide a "Run chunk" option above each chunk, and you can run individual lines using Shift+Enter (this may vary by operating system). You can also render from within VS Code and you'll see the results displayed in a pane within VS Code. Note that ith Python chunks, you may need to choose the Python interpreter that you want used - you can do this from the command pallette with "Python: select interpreter" or by clicking on the icon that shows the current Python interpreter.
+  2. **VS Code**: You can use VS Code with the Quarto extension. (If using Python chunks, you will probably also need the Python and Jupyter extensions). The extension will provide a "Run chunk" option above each chunk, and you can run individual lines using Shift+Enter (this may vary by operating system). You can also render from within VS Code and you'll see the results displayed in a pane within VS Code. Note that with Python chunks, you may need to choose the Python interpreter that you want used - you can do this from the command pallette with "Python: select interpreter" or by clicking on the icon that shows the current Python interpreter.
   3. **RStudio**: You can use RStudio to interact with qmd files in the same fashion as with Rmd files. You can run chunks or individual lines of code easily and render easily using the Render button.