deprecate `options`, change to `weave_options`:

- avoid unexpected header stripping (`options` sounds too general)
- deprecated `options` support will be remove within ≥v0.11

doc/src/chunk_options.md

@@ -1,4 +1,4 @@
-# Chunk options
+# Chunk Options
 
 I've mostly followed [Knitr](http://yihui.name/knitr/options)'s naming for chunk options, but not all options are implemented.
 
@@ -9,7 +9,7 @@ Options are separated using ";" and need to be valid Julia expressions. Example:
 Weave currently supports the following chunk options with the following defaults:
 
 
-## Options for code
+## Options for Code
 
 - `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.
@@ -23,7 +23,7 @@ Weave currently supports the following chunk options with the following defaults
 - `tangle = true`: Set tangle to `false` to exclude chunk from tangled code.
 
 
-## Options for figures
+## Options for Figures
 
 - `fig_width = 6`: Figure width passed to plotting library.
 - `fig_height = 4`: Figure height passed to plotting library.
@@ -37,13 +37,14 @@ Weave currently supports the following chunk options with the following defaults
 - `fig_env = "figure"`: Figure environment in Latex.
 
 
-## Set default chunk options
+## Set Default Chunk Options
 
-You can set the default chunk options (and `weave` arguments) for a document using the YAML header `options` field. E.g. to set the default `out_width` of all figures you can use:
+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:
 
 ```yaml
 ---
-options:
+weave_options:
   out_width : 50%
 ---
 ```

doc/src/header.md

@@ -59,7 +59,7 @@ The example below sets `out_path` and `doctype` options and overwrites `term` an
 title : Header Example
 author : Shuhei Kadowaki
 date: 16th May 2020
-options:
+weave_options:
   out_path: relative/path/to/this/document
   doctype: github
   term: true
@@ -91,7 +91,7 @@ The header configurations can be format specific.
 Here is how to set different `out_path` for `md2html` and `md2pdf` and set `fig_ext` globally:
 ```yaml
 ---
-options:
+weave_options:
   md2html:
     out_path : html
   md2pdf:

examples/markdown_beamer.jmd

@@ -1,7 +1,7 @@
 ---
-title : A minimal beamer example using Weave markdown
-author : Matti Pastell
-options :
+title: A minimal beamer example using Weave markdown
+author: Matti Pastell
+weave_options:
     doctype : md2pdf
     out_path : pdf
     template : beamer.tpl

src/Weave.jl

@@ -5,7 +5,8 @@ using Highlights, Mustache, Requires
 
 const PKG_DIR = normpath(@__DIR__, "..")
 const TEMPLATE_DIR = normpath(PKG_DIR, "templates")
-const WEAVE_OPTION_NAME = "options" # TODO: rename to "weave_options"
+const WEAVE_OPTION_NAME = "weave_options"
+const WEAVE_OPTION_NAME_DEPRECATED = "options" # remove this when tagging v0.11
 
 function __init__()
     @require Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" include("plots.jl")
@@ -124,6 +125,10 @@ function weave(
     # overwrites options with those specified in header, that are needed for running document
     # NOTE: these YAML options can NOT be given dynamically
     weave_options = get(doc.header, WEAVE_OPTION_NAME, Dict())
+    if haskey(doc.header, WEAVE_OPTION_NAME_DEPRECATED)
+        @warn "Weave: `options` key is deprecated. Use `weave_options` key instead."
+        weave_options = get(doc.header, WEAVE_OPTION_NAME_DEPRECATED, Dict())
+    end
     if !isempty(weave_options)
         doctype = get(weave_options, "doctype", doctype)
         specific_options!(weave_options, doctype)

src/format.jl

@@ -98,6 +98,10 @@ function restore_header!(doc)
 
     # only strips Weave headers
     delete!(doc.header, WEAVE_OPTION_NAME)
+    if haskey(doc.header, WEAVE_OPTION_NAME_DEPRECATED)
+        @warn "Weave: `options` key is deprecated. Use `weave_options` key instead."
+        delete!(doc.header, WEAVE_OPTION_NAME_DEPRECATED)
+    end
     isempty(doc.header) && return
 
     # restore remained headers as `DocChunk`

src/reader/reader.jl

@@ -17,6 +17,14 @@ function WeaveDoc(source, informat = nothing)
             end
         end
     end
+    if haskey(header, WEAVE_OPTION_NAME_DEPRECATED)
+        @warn "Weave: `options` key is deprecated. Use `weave_options` key instead."
+        for key in keys(chunk_defaults)
+            if (val = get(header[WEAVE_OPTION_NAME_DEPRECATED], string(key), nothing)) !== nothing
+                chunk_defaults[key] = val
+            end
+        end
+    end
 
     return WeaveDoc(
         source,

test/documents/gadfly_formats_test.jnw

@@ -1,6 +1,6 @@
 ---
-options :
-  out_path : gadfly
+weave_options:
+  out_path: gadfly
 ---
 
 <<fig_cap="sin(x) function."; label="sin_fun"; fig_pos="ht">>=

test/documents/markdown_beamer.jmd

@@ -1,8 +1,8 @@
 ---
-title : A minimal beamer example using Weave markdown
-author : Matti Pastell
-options :
-    out_path : inline
+title: A minimal beamer example using Weave markdown
+author: Matti Pastell
+weave_options:
+    out_path: inline
 ---
 
 ```julia; echo=false

test/test_header.jl

@@ -5,7 +5,7 @@ using Weave: separate_header_text, parse_header, specific_options!
 @testset "header separation" begin
 
 header_body = """
-options:
+weave_options:
     foo: bar
 """
 
@@ -79,7 +79,7 @@ end
 
 header = parse_header("""
 ---
-options:
+weave_options:
     out_path: reports # should be overwrote
     md2html:
         out_path : html/