changelog.rmu

# Rimu Markup Change Log

See the [Git commit log](https://github.com/srackham/rimu/commits/)
for more detailed information.


## Version 9.1.1 (2017-01-01)
- Allow multi-line default macro parameter values.
- Added _Change Log_ to documentation sidebar _Links_.
- URL captions syntax:

  * Do not allow `[` character in Markdown style URL captions ([use `[`
    entity instead]({tips}#url-captions)).
  * Allow `<` character in Rimu style URL captions.

- **FIXED**: _Rimu Tips_ documentation examples.


## Version 9.1.0 (2016-11-19)
- [Block Attributes]({reference}#block-attributes) can now be injected into
  [Block HTML elements]({reference}#block-html-elements).
- Added double-dollar (`$$1, $$2...`) macro parameters which expand quotes and
  replacements.  Double-dollar parameters are normally only necessary inside
  _Block HTML elements_.  See example in [Use macros to create
  tables]({tips}#use-macros-to-create-tables).
- Default parameter values can be specified in [parametrized
  macros]({reference}#macro-invocations) by appending `:default-value$` to the
  parameter name e.g. `$2:Ford$` will assign `Ford` to the `$2` parameter if it
  is blank or not specified in the macro invocation.
- **FIXED**: `rimuc`: The `.bordered` CSS tables class (available with the
  `--styled` option) no longer propagates to nested tables.


## Version 9.0.3 (2016-10-26)
- _Quote paragraphs_ are attached to list items in exactly the same way as
  _Indented paragraphs_ i.e. by being separated from the list item by a
  single blank line. Previously the Quote paragraph was attached if it
  followed the list item immediately (without a blank line) which was
  both surprising and inconsistent.
- Drop API  argument checks. They are redundant if the caller is
  written in TypeScript; if not then checking is the caller's
  responsibility.


## Version 9.0.2 (2016-10-07)
- Refactored codebase to compile with TypeScript `strictNullChecks` option.


## Version 9.0.1 (2016-10-02)
- Added the `--lang` option to `rimuc` command. This option sets the
  HTML tag's `lang` attribute value and is used in conjunction with
  the `--styled` option.
- Migrated codebase to TypeScript 2.


## Version 9.0.0 (2016-08-21)
- Added [`--styled-name`]({reference}#styled-names) option to `rimuc`
  along with built-in _classic_, _flex_ and _v8_ named styles. _flex_
  is an experimental mobile-first HTML5 + CSS3 layout based on CSS3
  flexboxes. _flex_ is currently tagged experimental because it is not
  fully functional in some older browsers (specifically Internet
  Explorer 11 and older).

- **BREAKING CHANGE**: If a [Division
  Block]({reference}#division-block) has no HTML attributes the
  `<div>` and `</div>` tags are not emitted.  Use this work-around if
  you want backward compatibility:

      // Redefine Division block so it always has at least one
      // attribute to ensure the div tags are always emitted.
      |division| = '<div class="dummy">|</div>'

- **BREAKING CHANGE**: The rimuc `--styled` option no longer uses
  Bootstrap for styling. If your existing documents rely on Bootstrap
  specific features you should specify the Rimu version 8 styling
  using the rimuc `--styled-name v8` option.

- **BREAKING CHANGE**: Space characters inside URLs are no longer
  tolerated as per [RFC 3986](http://tools.ietf.org/html/rfc3986/).
  This change impacts `<url>`, `<url|caption>`  and `[caption](url)`
  syntaxes. Instead of spaces use the `%20` space character encoding.
/*
  This reverses commit 5bc39ce (Rimu 4.0 May 2015), not sure why that
  was allowed (other than it's Markdown compatible).
*/

- If a _Quote paragraph_, _HTML block_ or _Multi-line Comment_ element
  immediately follows a [list item]({reference}#lists) without any
  intervening blank lines then it will be attached to the list item.

- Rimu documentation examples no longer use the `<style>` element
  `scoped` attribute as it has been [dropped from the HTML5
  specification]({tips}#scoped-css).


## Version 8.0.1 (2016-06-26)
- **FIXED**: `rimuc`: If a `.html` input file was encountered then
  all succeeding input files were ignored.
- Documentation updates.


## Version 8.0.0 (2016-06-25)
- Renamed `rimuc` `--toc` option to `--sidebar-toc`. The `--toc`
  option has been retained for backward compatibility.
- Added the `--dropdown-toc` option to `rimuc` command. This option
  generates a drop-down table of contents menu and is an alternative
  to the sidebar table of contents option. The
  [Playground]({playground}) page has been compiled using the
  drop-down menu, the others have a sidebar table of contents.
- Section headers with the `no-auto-toc` class are excluded from the
  auto-generated table of contents.
- Added the `--custom-toc` option to `rimuc` command. This option is
  used in conjunction with the `--sidebar-toc` and `--dropdown-toc`
  options. It inhibits the generation of the table of contents
  container element, leaving the user to include a custom TOC menu
  (the Rimu documentation uses this feature).
- Added the `line-breaks` CSS class for use with the `rimuc` command
  `--styled` option (see the [Controlling line
  breaks]({tips}#controlling-line-breaks) tip.
- Documented an [example letter]({tips}#an-example-letter) written in
  Rimu.
- Multiple [themes]({tips}#themes) can be specified using the `rimuc`
  `--theme` option.
-  The table of contents document title link (generated by the `rimuc`
   `--sidebar-toc` and `--dropdown-toc` options) navigates to the top
   of the document window (not the title header).
- Bug fixes.


## Version 7.3.0 (2016-04-15)
- The `rimuc` command now supports [named themes]({tips}#themes) with
  the new `--theme` option.  The following example styles the output
  using the built-in _graystone_ theme:

  rimuc --styled --theme graystone document.rmu


## Version 7.2.1 (2016-04-12)
- Documentation updates.
- Bug fixes.


## Version 7.2.0 (2016-04-06)
- Added `safeMode` bit-mask 8 (add 8 to `safeMode`) to unconditionally
  enable Macro Definitions. Allowing Macro Definitions is not
  intrinsically unsafe because their safety or otherwise is solely
  determined by the safety of their constituent elements.
- `safeMode` 5 generalized by incorporating it into a bit-mask (4).
- Bug fixes.


## Version 7.1.0 (2016-04-02)
- Added `"css-properties"` syntax to _Block Attributes_ element (a
  shortcut for the commonly used _Block Attributes_ `[style="..."]` idiom).
- Added  CSS text alignment classes `align-left`, `align-center`,
  `align-right` to the _rimuc_ `--styled` option.
- Added `page-break` and `no-page-break` CSS classes to the _rimuc_
  `--styled` option to allow printer page breaks to be specified.
- A new, stricter, _Safe Mode 5_ which skips _Block Attributes_ elements
  altogether which:

    1. Disables direct CSS control (via CSS classes or CSS properties).
    2. Disables HTML element ID creation (so you cannot override existing IDs).

- _rimuc_ command outputs error messages to `stderr` (not `stdout`).
- _rimuc_ command outputs rendered HTML even if there are errors (previously
  if an error occurred no HTML would be outputted which was surprising).
- _rimuc_ `--safeMode` and `--htmlReplacement` options have been
  deprecated and are superceded by standard lower case hyphenated
  option names `--safe-mode` and `--html-replacement`.


## Version 7.0.3 (2016-03-27)
- Documentation updates.


## Version 7.0.2 (2016-01-10)
- Documentation updates.


## Version 7.0.1 (2016-01-08)
- npm publication glitch -- did not pick up README. The "glitch"
  was subsequently found to be bogus.


## Version 7.0.0 (2016-01-08)
- **BREAKING CHANGE:** A single UMD formatted Rimu library file
  `rimu.js` (along with the minified version `rimu.min.js`) are now
  distributed instead of previous separate CommonJS and browser
  versions (`rimu-commonjs2.js`, `rimu-var.js`, `rimu-var.min.js`) so
  you will need to rename the latter in code that imports the Rimu
  library.
- Ported `rimuc` to TypeScript and added a test suite for `rimuc`.
- The Rimu `rimu.d.ts` ships with the npm package and is specified in
  `package.json` using the [TypeScript 1.6 typings for npm
  packages](https://github.com/Microsoft/TypeScript/wiki/Typings-for-npm-packages)
  feature. The upshot being that Rimu's TypeScript declarations are loaded
  automatically from the _rimu_ npm package when you import the Rimu
  library from a TypeScript source file:

          // Automatically loads node_modules/rimu/bin/rimu.d.ts
          import Rimu = require('rimu')

- Use Webpack to minify the Rimu library -- this reduced the minified
  `rimu.min.js` to 18.7KB (previously was 28.2KB).
- Upgrade all build tools to latest versions.


## Version 6.1.0 (2015-08-19)
- Allow macro invocations in _API Option_ element values.
- Allow _Quote_ elements in URL and and email address captions.
- Add `callback` API to `rimu.d.ts` type definitions file.
- Replaced _nodeunit_ with [Tape](https://github.com/substack/tape) for unit tests.


## Version 6.0.0 (2015-07-12)
Misspelled macro invocations are insidious and easily overlooked.  The
problem has finally been resolved with the introduction of an API
callback option that emits diagnostic messages.

The rule for macro expansion is now very simple: If a macro is not
defined its invocation is rendered verbatim.  The `rimuc` command
`--lint` option will emit an error if a macro is undefined (to
suppress these warnings escape the macro invocation with a backslash).

- Many of the examples in the Rimu documentation are now live -- you
  can edit them by clicking the _Edit_ icon. _Live edit_ is a good
  example of using Rimu macros to refactor repetitive chunks of code.

- Added `callback` API option. The `callback` function handles
  diagnostic events emitted by the `render()` API as it parses the
  Rimu source. Diagnostic events include:
  * Undefined macro invocation.
  * Unterminated Delimited Block.
  * Illegal and invalid block options.
  * Illegal Delimited Block name.
  * Illegal API Option name.
  * Deprecated existential macro invocation.

- Added `--lint` option to the `rimuc` command which checks the Rimu
  source for inconsistencies and errors.
- Added Existential macro definition syntax: `\{macro-name?} =
  'macro-value'` Existential macro definitions are only processed if
  the macro has not been defined and are useful for establishing
  default values.
- `rimuc` passes the contents of files with an `.html` extension
  directly to the output.  This allows `rimuc` to process HTML from
  other sources.
- The highlighting of broken fragments by `rimuc --styled` outputs has
  been removed -- it's in the wrong place, errors should be caught at
  compile-time and this feature will probably be added to a future
  version of the `rimuc` compiler.

Breaking changes:

- The `macroMode` option is no longer supported. It was introduced in
  version 5.0.0 and was a poorly thought-out attempt to tighten up on
  undefined macros -- the default _macroMode_ did make undefined macro
  invocations visible in the output but didn't really solve the problem.
  Worst of all, different modes had different rendering semantics.
  There is now a single semantic for undefined macro invocations (they
  are rendered verbatim) and are flagged as errors via the `render()`
  API `callback` option.

- Existential macro invocations (`\{name?default}`) no longer
  supported. This is because invoking an undefined macro is now
  considered an error.  You can specify default macro values using
  the new _Existential Macro Definition_ syntax. Legacy Existential
  invocations are rendered verbatim and the `rimuc` `--lint` option
  will emit a deprecation error.

- The previously undefined `\{--}` reserved macro is now set to an empty string
  when the `rimuc` `--styled` option is used so it still behaves the same
  with Inclusion and Exclusion macro invocations -- if you use it
  in other contexts you should explicitly set it: `\{--} = ''`.


## Version 5.4.0 (2015-06-28)
- Moved Rimu reference documentation from the _Rimu Playground_ into a
  separate updated _Reference_ manual.
- Restyled and simplified the _Playground_.
- Features added to the `rimuc` command `--styled` option (details in
  the new _Reference_ manual):
  * Now generates unique slug ids for top level `h1`, `h2` and `h3`
    headers irrespective of the `--toc` option (previously it was
    possible to generate non-unique slug ids).
  * It Highlights broken fragment URLs.


## Version 5.3.0 (2015-06-22)
Added `--title TITLE`, `--highlightjs`, `--mathjax`, `--toc`, `--section-numbers`
styling macro shortcut options to `rimuc`. The preceding example can now be
shortened to:

    rimuc --styled --toc README.md


## Version 5.2.0 (2015-06-20)
The `rimuc` command can now generate a table of contents: If the `--toc` macro is defined
and is not blank then the `rimuc` command `--styled` option generates a table of contents.
For example:

    rimuc --styled --prepend "{--toc}='yes'" README.md

Top-level `h1`, `h2` and `h3` HTML tags contribute to the table of contents.


## Version 5.1.0 (2015-06-13)
New features:

- You can append CSS class names to Delimited Block opening delimiter lines and they
  will be injected into the block's opening HTML tag (this is
  an alternative to using a _Block Attributes_ element and was
  added primarily for compatibility with Github Flavored Markdown's code block highlighting).
  For example:

        ``` javascript
        if (message) {
          console.error('Error: ' + message);
        }
        ```

- Underscores within words rendered verbatim and are not treated as
  underscore emphasis quotes (Github Flavored Markdown behaviour).
- Add `+` bulleted list ID (Markdown syntax).
- Lists can be terminated by two or more blank lines.
- Typographical nicities added to the
  [example .rimurc file](https://github.com/srackham/rimu/blob/master/examples/.rimurc).


## Version 5.0.0 (2015-06-07)
This version adds new API options, an _API Options_ element and more Markdown
compatibility. It also includes some breaking changes.

- Added `macroMode` API option to specify which macro invocations are processed.
- Added `reset` API option to reset the API to its default state.
- Added Markdown compatible double back-tick ````code quotes```` and double
  underline `__strong quotes__`.
- Added _API Option_ element to allow API options to be set in Rimu source.
- Bug fixes.
- Add `--macroMode` and `--htmlReplacement` options to `rimuc` command.
  The `--safe-mode` is renamed to `--safeMode` (`--safe-mode` still works but
  is deprecated).

Breaking changes:

- Changed default behavior of single-asterisk quote from strong to emphasis to align
  with Markdown. To reinstate old behavior use this quote definition: `* = '<strong>|</strong>'`.

- By default only defined and reserved macro invocations are expanded. Previously all macros
  were expanded which to often generated surprising results e.g. if the `text` macro
  was not explicitly defined then `$\{text}` would silently render `$`.
  To revert to the previous behaviour set the `macroMode` API option to `1`.

- Replacements are processed before quotes (previously they were processed after quotes).
  This is ensures quotes are not expanded inside URLs (notably underscores) and aligns
  with Markdown behaviour.
  If there are escaped quotes in URLs they will no longer be unescaped and you will need
  to remove them.

- The `render()` API only changes `options` that are explicitly specified.
  Previously, unspecified `options` were set to their default values which was
  surprising and potentially dangerous because it reset the `safeMode` to the default
  unsafe value of zero unless `safeMode` was explicitly specified otherwise.

- A backslash immediately preceding a closing _code_ quote is now rendered verbatim
  and does not escape the quote.


## Version 4.0.1 (2015-05-06)
Documentation updates (no functional changes).

- Use Markdown links and headers syntax in documentation.
  Most users will already know and use Markdown so this makes Rimu
  example source more familar and easier to assimilate.


## Version 4.0.0 (2015-05-05)
- Switched codebase from Internal to External (ES6 compatible) module
  syntax.
- Modules are bundled into deployable JavaScript libraries using Webpack.
- The single `rimu.js` compiled library file has been replaced by two separate
  library files:

    1. `rimu-var.js` for use in HTML _script_ tags.
    2. `rimu-commonjs2.js` for use with CommonJS (Node.js) applications.


## Version 3.3 (2015-01-12)
More Markdown compatible syntaxes added to Rimu core
(these syntaxes were previously added using custom definitions):

- Links: `[caption](url)`.
- Images: `![alt](url)`.
- Bold text: `**bold**`.
- Strikethrough text: `~~strikethrough~~` (GitHub Flavored Markdown).


## Version 3.2 (2015-01-07)
- Auto-encode (most) raw HTTP URLs as links.
- Added Markdown compatible Quote Paragraphs (paragraphs starting with `>`
  rendered inside a `<blockquote>` HTML element).
- Added backtick delimiter for code blocks - - backtick is now the normative
  code block delimiter (the older dash delimiter is deprecated but will never
  be dropped). backtick rationale:

    1. Consistency: aligned with use of backtick to quote inline code.
    2. Familarity: looks like a Github Flavored Markdown fenced code block.


## Version 3.0 (2013-10-28)
- Added _Delimited Block_ definitions.
- Enhanced and refined Macros.
- Many other enhancements, additions and documentation updates.
- _Indented Paragraphs_ and _Code Blocks_ no longer expand macro
  invocations by default. To reinstate old behavior use these delimited
  block definitions:

          |code| = '+macros'
          |indented| = '+macros'

- _Indented Paragraph_ emits same code as _Code Block_. To reinstate
  old behavior use this delimited block definition:

          |indented| = '<pre>|</pre>'

- Dropped the deprecated _+_ line-break, use the newer backslash
  line-break. To reinstate the old _+_ line-break use this replacement
  definition:

          /[\\ ]\+(\n|$)/g = '<br>$1'


## Version 2 (2013-07-26)
- Added Quote and Replacements definitions.
- A number of other enhancements, additions and documentation updates.