descriptions for RMarkdown style chunk option specs

doc/src/chunk_options.md

@@ -1,43 +1,65 @@
-# Chunk Options
+# [Chunk Options](@id chunk-options)
 
-I've mostly followed [Knitr](http://yihui.name/knitr/options)'s naming for chunk options, but not all options are implemented.
-
-Options are separated using ";" and need to be valid Julia expressions. Example: markdown code chunk that saves and displays a 12 cm wide image and hides the source code:
-
-`julia; out_width="12cm"; echo=false`
-
-Weave currently supports the following chunk options with the following defaults:
+You can use chunk options to configure how each chunk is evaluated, rendered, etc.
+Most of the ideas came from [chunk options in RMarkdown](http://yihui.name/knitr/options).
 
 
-## Options for Code
+## Syntax
+
+Chunk options come after at the top of [code chunk](@ref code-chunks).
+There are two (slightly) different syntax to write them:
+- (Julia's toplevel expression) options are separated by semicolon (`;`)
+- (RMarkdown style) options are separated by comma (`,`)
+
+Let's take a look at examples. All the following code chunk header are valid,
+and so configured to hide the source code from generated output (`echo = false`)
+and displays figures with 12cm width (`out_width = "12cm"`):
+```md
+ ```julia; echo = false; out_width = "12cm"
+
+ ```{julia; echo = false; out_width = "12cm"}
+
+ ```julia, echo = false, out_width = "12cm"
+
+ ```{julia, echo = false, out_width = "12cm"}
+```
+
+
+## Weave Chunk Options
+
+Weave currently supports the following chunk options:
+we've mostly followed [RMarkdown's namings](http://yihui.name/knitr/options), but not all options are implemented.
+
+### Evaluation
+
+- `eval = true`: Evaluate the code chunk. If `false` the chunk won’t be executed.
+- `cache = false`: Cache results, depending on `cache` parameter on [`weave`](@ref) function.
+- `tangle = true`: Set tangle to `false` to exclude chunk from tangled code.
+
+### Rendering
 
 - `echo = true`: Echo the code in the output document. If `false` the source code will be hidden.
 - `results = "markup"`: The output format of the printed results. `"markup"` for literal block, `"hidden"` for hidden results, or anything else for raw output (I tend to use `"tex"` for Latex and `"rst"` for rest). Raw output is useful if you want to e.g. create tables from code chunks.
-- `eval = true`: Evaluate the code chunk. If `false` the chunk won’t be executed.
 - `term = false`: If `true` the output emulates a REPL session. Otherwise only stdout and figures will be included in output.
-- `label = nothing`: Chunk label, will be used for figure labels in Latex as `fig:label`.
 - `wrap = true`: Wrap long lines from output.
 - `line_width = 75`: Line width for wrapped lines.
-- `cache = false`: Cache results, depending on `cache` parameter on `weave` function.
 - `hold = false`: Hold all results until the end of the chunk.
-- `tangle = true`: Set tangle to `false` to exclude chunk from tangled code.
 
+### Figures
 
-## Options for Figures
-
+- `label = nothing`: Chunk label, will be used for figure labels in Latex as `fig:label`.
 - `fig_width = 6`: Figure width passed to plotting library.
 - `fig_height = 4`: Figure height passed to plotting library.
 - `out_width`: Width of saved figure in output markup e.g. `"50%"`, `"12cm"`, `0.5\linewidth`
 - `out_height`: Height of saved figure in output markup
 - `dpi = 96`: Resolution of saved figures.
 - `fig_cap`: Figure caption.
-- `label`: Chunk label, will be used for figure labels in Latex as fig:label
 - `fig_ext`: File extension (format) of saved figures.
 - `fig_pos = "!h"`: Figure position in Latex, e.g.: `"ht"`.
 - `fig_env = "figure"`: Figure environment in Latex.
 
 
-## Set Default Chunk Options
+## Default Chunk Options
 
 You can set the default chunk options (and `weave` arguments) for a document using `weave_options` key in YAML [Header Configuration](@ref).
 E.g. to set the default `out_width` of all figures you can use: