Revisions to release notes

Author: mDuo13

releasenotes.md

@@ -8,7 +8,7 @@ Dactyl v0.10.0 contains two significant breaking changes: a new header ID formul
 
 ### Header ID Formula
 
-The default formula for header IDs has changed slightly. In cases where your content links to anchors by the header's ID, you may need to update your links to use the header's ID under the new formula.
+The default formula for header IDs has changed slightly. Most headers in English documents have the same IDs as before, but headers may have different IDs in certain edge cases, especially for headers with non-English text. In cases where your content contains an anchor link to a header whose ID has changed, you must update your links to use the header's ID under the new formula.
 
 The new formula more closely matches GitHub's formula for header IDs. In particular:
 
@@ -26,16 +26,16 @@ The `xrefs` filter now raises an error if you link to a page without providing l
 
 Previously the filter would silently provide link text based on other attributes of the page, such as its markdown filename. This is usually not what you want the final output to have.
 
-To continue building despite these types of errors, pass `--bypass_errors` when running `dactyl_build`. Preferably, fix the xrefs so the referenced pages can have
+To continue building despite these types of errors, pass `--bypass_errors` when running `dactyl_build`. Preferably, fix the xrefs so the referenced pages have proper names.
 
 
 ## New Features
 
 ### Frontmatter Improvements
 
-Dactyl improves the handling of Jekyll-style frontmatter as introduced in v0.9.0. Frontmatter is metadata at the start of a Markdown file, surrounded by a pair of `---` lines. Now you can provide any of a page's fields in the frontmatter instead of in the Dactyl config file, except for the path to the file itself.
+Dactyl v0.10.0 improves the handling of Jekyll-style frontmatter. Frontmatter is metadata at the start of a Markdown file, surrounded by a pair of `---` lines. Now you can provide any of a page's fields in the frontmatter instead of in the Dactyl config file, except for the path to the file itself.
 
-In cases where the config file and the frontmatter specify the same fields for a given file, the config file takes precedence.
+In cases where the config file and the frontmatter specify conflicting values for a field, the config file takes precedence.
 
 Example of a page with frontmatter:
 
@@ -66,7 +66,31 @@ Managing a hierarchy of documents is a common problem, so the new version of Dac
 
 Add the **`parent` field** to a page's metadata to define a "parent" for the current page. The value of the `parent` field should be **the exact value of the parent page's `html` field.** If a page doesn't have an explicitly-specified `html` value, you must use the automatically generated value for the parent.
 
-As a best practice, set all your "first level" pages to have your `cover_page` as their parent.
+Example:
+
+```yaml
+- md: some-parent-page.md
+  html: parent.html
+
+- md: first-child-page.md
+  html: child1.html
+  parent: parent.html
+
+- md: grandchild.md
+  html: grandchild.html
+  parent: child1.html
+
+- md: child2.md
+  html: child2.html
+  parent: parent.html
+```
+
+This creates a conceptual hierarchy like this:
+
+- `parent.html`
+    - `child1.html`
+        - `grandchild.html`
+    - `child2.html`
 
 After loading pages, Dactyl provides the following additional fields in each page's metadata, which are available to the preprocessor, filters, and templates:
 
@@ -75,19 +99,20 @@ After loading pages, Dactyl provides the following additional fields in each pag
 | `children`       | List     | A list of pages that claim this page as a parent. Each page in the list is provided as a reference, so you can read its metadata including following its own children. |
 | `is_ancestor_of` | Function | A function you can use to check whether a given page is the direct or indirect parent of another given page. Provide the exact `html` of the page you want to check for as the single argument to this function. |
 
-Dactyl does not enforce a strict tree-like hierarchy of parents/children. It is up to the templates to use these fields to provide appropriate navigation elements based on the hierarchy these fields represent. [Example of template for printing page hierarchy tree.](https://github.com/mDuo13/dactyl-starter-kit/blob/master/template/template-tree-nav.html)
+This conceptual hierarchy does not affect the paths where output files are written. (It would be sensible to choose output `html` paths to reflect this hierarchy, though.) Also, Dactyl does not enforce a strict tree-like hierarchy of parents/children. It is up to the templates to use these fields to provide appropriate navigation elements based on the hierarchy these fields represent. [Example of template for printing page hierarchy tree.](https://github.com/mDuo13/dactyl-starter-kit/blob/master/template/template-tree-nav.html)
 
 **Caution:** It is possible to create infinite loops. Do not make a page its own direct or indirect parent. Doing so is likely to result in a `RecursionError` when trying to build.
 
+
 ### Other New Fields
 
-In addition to the new page fields added for page hierarchy, Dactyl now provides certain fields to every page based on the results of parsing that page. (Previously, Dactyl only provided these fields when building ElasticSearch JSON formats.) Now, Dactyl provides those fields to every page after parsing that page's content Markdown. The fields are:
+In addition to the new page fields added for page hierarchy, Dactyl now provides certain fields to every page based on the results of parsing that page. Previously, Dactyl only provided these fields when building ElasticSearch JSON formats. Now, Dactyl provides these fields to every page after parsing that page's content Markdown. These fields are:
 
 | Field       | Value      | Description                                       |
 |:------------|:-----------|:--------------------------------------------------|
 | `blurb`     | String     | An excerpt from the start of the page, if available, generally consisting of the first paragraph of body text. |
 | `plaintext` | String     | The entire body text of the page, stripped of any formatting. |
-| `headermap` | Dictionary | A mapping of header text to those headers' unique IDs. |
+| `headermap` | Dictionary | A mapping, where the keys are the headers' plain text (formatting removed) and the values are those headers' unique IDs. |
 
 Because these fields are derived from the content's HTML output, they are **not available** to the preprocessor, nor in filter functions `filter_markdown()` or `filter_html()`. They **are available** to `filter_soup()` functions and when rendering HTML templates.
 
@@ -97,7 +122,7 @@ If a page already has a `blurb` field defined in its metadata, Dactyl leaves the
 
 Dactyl already provided templates with a string containing the HTML for a list of header-based anchors in the current page, in the `page_toc` variable. (This variable, and its legacy alias `sidebar_content`, continue to be available.) However, to provide an opportunity to customize the markup of how the in-page anchors are presented, Dactyl now also provides a `headers` field, which you can use to generate a more customized table of contents. (For example, if you are using Bootstrap, you can use this to provide the classes necessary to make Scrollspy work properly.)
 
-The `headers` field is a **list of headers** in the document, derived from `<h1>` through `<h6>` elements. Each header is a dictionary with the following fields:
+The `headers` field is a **list of headers** in the document, derived from `<h1>` through `<h6>` elements. **Each header** in the list is a dictionary with the following fields:
 
 | Field   | Value   | Description                                              |
 |:--------|:--------|:---------------------------------------------------------|
@@ -164,14 +189,16 @@ In future releases, Dactyl may use the `prefix` field for more conveniences arou
 
 ### Internationalization Improvements
 
-Dactyl now supports `{% trans %}Text to be translated {% endtrans %}` syntax in templates.
+Dactyl now supports `{% trans %}Text to be translated{% endtrans %}` syntax in templates.
 
-Support for locale files is ***experimental*** and the details are likely to change in a future version of Dactyl. To use translated values for these strings, add the following field to a **target definition**:
+To use translated values for these strings, add the following field to a **target definition**:
 
 | Field         | Value  | Description                                         |
 |:--------------|:-------|:----------------------------------------------------|
 | `locale_file` | String | Path to a (binary) `.mo` file containing translated strings for this target's locale/language. |
 
+Support for locale files is ***experimental*** and the details are likely to change in a future version of Dactyl.
+
 You can use [Babel](http://babel.pocoo.org/) to extract strings from templates and to compile the translations into a `.mo` file. For an example, see <https://github.com/mDuo13/dactyl-starter-kit/blob/master/locale/README.md>.
 
 
@@ -187,8 +214,8 @@ However, OpenAPI spec parsing should still be considered experimental.
 
 ## Bug Fixes and Other Cleanup
 
-- `--skip_preprocessor` (when using a config file) again. It has been broken since v0.40.0.
+- `--skip_preprocessor` (when using a config file) works again. It had been broken since v0.40.0.
 - `--bypass_errors` can now bypass errors that occurred when running a filter.
-- Removed some extraneous whitespace in the default tables of contents ("In this page" area).
+- Removed some extraneous whitespace in the default tables of contents `{{page_toc}}`.
 - Improved the clarity of log messages.
 - New unit tests.