Improve sample --defaults file in MANUAL.txt.

MANUAL.txt

@@ -1427,102 +1427,152 @@ of options.  Here is a sample defaults file demonstrating all of
 the fields that may be used:
 
 ``` yaml
-tab-stop: 8
-preserve-tabs: yes
-standalone: true
-table-of-contents: true
-# toc is a synonym for table-of-contents
 from: markdown+emoji
-# reader is a synonym for from
+# reader: may be used instead of from:
 to: html5
-# writer is a synonym for to
-shift-heading-level-by: 1
-template: leter
+# writer: may be used instead of to:
+
+# leave blank for output to stdout:
+output-file:
+# leave blank for input from stdin:
+input-files:
+- preface.md
+- content.md
+
+template: letter
+standalone: true
+self-contained: false
+
+# note that structured variables may be specified:
 variables:
   documentclass: book
   classoptions:
     - twosides
     - draft
+
+# metadata values specified here are parsed as literal
+# string text, not markdown:
 metadata:
   author:
   - Sam Smith
   - Julie Liu
-metadata-files: []
-# you may also use metadata-file with a single value
-output-file: -
-input-files:
-- preface.md
-- content.md
+metadata-files:
+- boilerplate.yaml
+# or you may use metadata-file: with a single value
+
+# Note that these take files, not their contents:
+include-before-body: []
+include-after-body: []
+include-in-header: []
+resource-path: ["."]
+
+# filters will be assumed to be lua filters if they have
+# the .lua extension, and json filters otherwise.  But
+# the filter type can also be specified explicitly, as shown:
+filters:
+- pandoc-citeproc
+- wordcount.lua
+- type: json
+  path: foo.lua
+
+file-scope: false
+
+data-dir:
+
+# ERROR, WARNING, or INFO
+verbosity: INFO
+log-file: log.json
+
+# citeproc, natbib, or biblatex
+cite-method: citeproc
+# part, chapter, section, or default:
+top-level-division: chapter
+abbreviations:
+
+pdf-engine: pdflatex
+pdf-engine-opts:
+- "-shell-escape"
+# you may also use pdf-engine-opt: with a single option
+# pdf-engine-opt: "-shell-escape"
+
+# auto, preserve, or none
+wrap: auto
+columns: 78
+dpi: 72
+
+extract-media: mediadir
+
+table-of-contents: true
+toc-depth: 2
 number-sections: false
+# a list of offsets at each heading level
 number-offset: [0,0,0,0,0,0]
+# toc: may also be used instead of table-of-contents:
+shift-heading-level-by: 1
 section-divs: true
-incremental: false
-self-contained: false
-html-q-tags: false
+identifier-prefix: foo
+title-prefix: ""
+strip-empty-paragraphs: true
+# lf, crlf, or native
+eol: lf
+strip-comments: false
+indented-code-classes: []
+ascii: true
+default-image-extension: ".jpg"
+
+# either a style name of a style definition file:
 highlight-style: pygments
 syntax-definitions:
 - c.xml
-# may also use syntax-definition: with a single value
-top-level-division: chapter
+# or you may use syntax-definition: with a single value
+listings: false
+
+reference-doc: myref.docx
+
+# method is plain, webtex, gladtex, mathml, mathjax, katex
+# you may specify a url with webtex, mathjax, katex
 html-math-method:
   method: mathjax
   url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
-abbreviations: []
-reference-doc: myref.docx
+# none, references, or javascript
+email-obfuscation: javascript
+
+tab-stop: 8
+preserve-tabs: true
+
+incremental: false
+slide-level: 2
+
 epub-subdirectory: EPUB
 epub-metadata: meta.xml
 epub-fonts:
 - foobar.otf
 epub-chapter-level: 1
 epub-cover-image: cover.jpg
-toc-depth: 2
-dump-args: false
-ignore-args: false
-verbosity: INFO
-trace: false
-log-file: log.json
-fail-if-warnings: false
+
 reference-links: true
-reference-location: paragraph
-dpi: 72
-wrap: auto
-columns:78
-filters:
-- pandoc-citeproc
-- wordcount.lua
-- type: json
-  path: foo.lua
-email-obfuscation: javascript
-identifier-prefix: foo
-strip-empty-paragraphs: true
-indented-code-classes: []
-data-dir: null
-cite-method: citeproc
-listings: false
-pdf-engine: pdflatex
-pdf-engine-opts: []
-# can also use this with a single option:
-pdf-engine-opt:
-slide-level: 2
+# block, section, or document
+reference-location: block
 setext-headers: true
-ascii: true
-default-image-extension: ".jpg"
-extract-media: mediadir
-track-changes: false
-file-scope: false
-title-prefix: ""
+
+# accept, reject, or all
+track-changes: accept
+
+html-q-tags: false
 css:
 - site.css
+
+# none, all, or best
 ipynb-output: best
-# Note that these take files, not their contents:
-include-before-body: []
-include-after-body: []
-include-in-header: []
-resource-path: ["."]
+
+# A list of two-element lists
 request-headers:
 - ["User-Agent", "Mozilla/5.0"]
-eol: lf
-strip-comments: false
+
+fail-if-warnings: false
+dump-args: false
+ignore-args: false
+trace: false
 ```
 
 # Templates