crowbook/ChangeLog.md

ChangeLog
=========

unreleased
----------
* **Breaking change for users**: removed `tex.short` option, replaced
  by a more generic `tex.class` (default being `book`).
* Renamed options. Using the old name will print a deprecation warning
  but will still work for a while.
  * `temp_dir` -> `crowbook.temp_dir`
  * `zip.command` -> `crowbook.zip.command`
  * `verbose` -> `crowbook.verbose`
  * `html.display_chapter` -> `html_single.one_chapter`
  * `numbering` -> `rendering.num_depth`
  * `numbering_template` -> `rendering.chapter_template`
  * `display_toc` -> `rendering.inline_toc`
  * `toc_name` -> `rendering.inline_toc.name`
  * `enable_yaml_blocks` -> `input.yaml_blocks`
  * `use_initials` -> `rendering.initials`
  * `autoclean` -> `input.autoclean`
* New options:
  * More metadata: `license`, `version` and `date`. These metadata are
    not treated by the renderers, but they are exported to the
    templates: `{{{metadata}}}` allows to access the content. If they
    are present, a `has_metadata` is also set to true, allowing to do
    something like `{{{title}}} {{#has_version}}version {{{version}}}
    {{/has_version}}`.
  * Yet more metadata: it is possible to add custom metadata by
    prefixing it with `metadata.`. They will then be accessible in the
    templates, with dots ('.') replaced by underscores ('_'). E.g.,
    with `metadata.foo: bar` you can access it in your templates with
    `{{{metadata_foo}}}`.
* Rendering:
  * Metadata can now contain Markdown and will be rendered by the
    renderers. This might not be a good idea for common fields
    (e.g. "title"), though. Use with caution.
  * HTML:
    * `html.top` and `hstml.footer` are now considered as templates, so
      you can use some `{{{metadata}}}` in it.
  * LaTeX:
    * If `tex.class` is set to `article`, chapters will be displayed as
      `\sections` since `article` class doesn't handle chapters.
    * Except if `tex.class` is set to `book`, margins are now
      symmetrical. 
* Bugfixes:
  * `import_config` only import options from another book file that
    are not equal to the default ones and that haven't already been
    set by the caller. E.g., `author: foo` then `import_config:
    bar.book` won't erase the author previously set.
* Crowbook program:
  * Still working to improve error messages.
  * Display an error message when mustache can't compile a template,
    instead of panicking.
* Internal/API:
  * Added static methods to `Logger` to allows displaying messages
    more easily/prettily.
  * Reduce pubic API's surface so less changes will need to be
    considered breaking in the future. 

0.8.0 (2016-09-19)
------------------
This release adds support for syntax higlighting in code blocks,
customized top and footer blocks for HTML rendering, and the special
`import_config` option that allows to import options from another book
file. It also provides (hopefully) better error messages.

* New options:
  * `import_config`is not really an option, but allows to import
    another configuration file, useful if you share a same set of
    options between multiple books.
  * `use_initials` (set to false by default) makes Crowbook use
    initials ("lettrines") at start of each chapter. Support is still
    experimental.
  * `html.highlight_code` (set to true by default) allows syntax
    highlighting for code blocks, using highlight.js.
  * `html.higlight.css` and `html.highlight.js` can be used to provide
    other themes (default is default.css) and an highlight.js build
    that support other languages.
   * `html.footer` allows to specify custom footer. If not set,
     `html.crowbook_link` allows to disable "Generated by Crowbook"
     message.
   * `html.top` allows to specify a custom header that will be
     displayed at the top of HTML file(s).
* Deprecated options:
  * `side_notes` has been renamed `html.side_notes`.
* Crowbook program:
  * All output formats are now rendered concurrently.
  * Better error messages. Crowbook now tries to give more information
  when displaying an error, with the file name where a problem was
  found, and, in some cases, the line. It also tries to detect errors
  (such as files not found) sooner.
  * Some "warning" messages have also been "moved" to error messages, to
  make sure they are displayed even when crowbook isn't runned with
  `--verbose`.
* Rendering:
  * Hidden chapter now produce empty `\chapter*{}` and `<h1>` in LaTeX
    and HTML. This allow to delimit a chapter break even if nothing is
    displayed.
* Bugfixes:
  * Navigation menu of standalone HTML didn't include a call to
    javascript when `html.display_chapter` was set to true, meaning it
    didn't display the chapter correctly.
  * Implementations of `Image` and `StandaloneImage` were reversed in
    LaTeX.
  * `StandaloneImage` urls were not adjusted (meanning that running
    `crowbook` from another directory failed).
  * Image paths are now found correctly in HtmlDir rendering
    even if `crowbook` is called from another directory (same fix
    as 0.6's for Epub and LaTeX, which was forgotten for HtmlDir).
* Internal/API:
  * In order to have better error messages, there was a need to
    refactor the `Error` type, and make more methods return
    `Result<X>` instead of `X`. The API is, therefore, quite modified.
  * Added a `Renderer` trait used by the various renderers.
  * Removed some methods from public API.

0.7.0 (2016-09-11)
------------------
This releases renders images differently when they are on a standalone
paragraph or inside a paragraph.

* Internal/API:
  * `Token` has a new variant, `StandaloneImage`. This is used to
    distinguish an image that is alone in a paragraph of an image that
    is inlined alongside text.
  * `Parser.parse` method now distingues between `Image` and
    `StandaloneImage`. Currently, an image is considered "standalone"
    if it is the sole element of a paragraph, even if it is among a
    link.
  * `Token` has a new `is_image` method.
* Rendering:
  * Standalone images are now rendered differently than inline images
    (80% of width VS original size) in HTML/EPUB and LaTeX.

0.6.0 (2016-09-09)
------------------
* Deprecated options:
  * `nb_char`: since it was only used for french cleaner and for
    typography reasons it's better to use different non breaking
    spaces according to context, this option was not really useful
    anymore.
* Rendering:
  * Images are now displayed at 80% width of the page.
* Bugfixes:
  * Image paths are now found correctly in LaTeX and EPUB rendering
    even if `crowbook` is called from another directory.
  * Fixed a bug in `French` cleaner when a string to clean ended by a
    non-breaking space (space was doubled with a breaking one).
  * LaTeX/PDF:
    * "Autocleaning" is now also activated (for french at least) for
      LaTeX rendering, since it doesn't correctly insert non-breaking
      spaces for e.g. '«' or '»'.
    * Fixed escaping of `--` to `-{}-` to avoid tex ligatures.
  * HTML/EPUB:
    * `html.display_chapter` now defaults to `false` (e.g., by default
      the HTML displays the entirety of a book).
    * Fixed rendering of lists when `lang` is set to `fr`.
    * Links are now HTML-escaped, fixing errors in XHTML (for EPUB
      rendering) when links contained '&' character.
    

0.5.1 (2016-04-14)
------------------
Mostly rendering fixes:
* Epub:
  * Fix a validation problem when book contained hidden chapters.
* French cleaner:
  * Use semi-cadratine space instead of cadratine
  space for dialogs.
  * Use non-narrow non-breaking spapce instead of
  narrow one for ':', '«' and '»' (following
  https://fr.wikipedia.org/wiki/Espace_ins%C3%A9cable#En_France).
* HTML:
  * Add viewport meta tags.
  * Standalone HTML:
    * Don't display the button to display chapter and
    the previous/next chapter link if `html.display_chapter` is set to
    `false`.
    * Fix chapter displaying when some chapters are not
    numbered.
  * Multi-files HTML:
    * Fix previous/next chapter display to make it consistent with
      standalone HTML.


0.5.0 (2016-04-02)
------------------
* Crowbook now requires Rustc 1.7.0.
* It is now possible to render HTML in multiple files:
     * `output.html_dir` will activate this renderer, and specify in
       which directory to render these files;
     * `html_dir.css` allows to override the CSS for this rendering;
     * `html_dir.index.html` allows to specify a template for the
       `index.html` page;
     * `html_dir.chapter.html` allows to specify a template for the
       chapters pages.
* New book options:
    * `tex.short`: if set to true, the LaTeX renderer will use
      `article` instead of `book` as document class, and will use the
      default `\maketitle` command for article. This option is by
      default set to false, except when Crowbook is called with
      `--single`.
    * `enable_yaml_blocks`: parsing YAML blocks is no longer activated
      by default, except when using `--single`. This is because you
      might want to have e.g. multiple short stories using YAML blocks
      to set their titles and so on, *and* a separate `.book` file to
      render a book as a collection of short stories. In this case,
      you wouldn't want the displayed title or the
      output.pdf/html/epub files be redefined by the short stories .md
      files.
    * `html.print_css`: allows to specify a stylesheet for media print
    * `html.display_chapter`: displays one chapter at a time in
      standalone HTML
    * `html.script`: allows to specify a custom javascript file for
    standalone HTML
    * `html_dir.script`: same thing for multipage HTML
    * `resources.base_path`: by default, Crowbook resolves local links in
      markdown files relatively to the markdown file. This option
      allows to resolve them relatively to a base path. This option
      comes with two variants, `resources.base_path.images` and
      `resources.base_path.links`, which only activate it for respectively
      images tags and links tags. These two options are ignored when
      `base_path` is set. There is also `resources.base_path.files`
      which specify where additional files (see below) should be read,
      but this is one is set to `.` (i.e.,  the directory where the
      `.book` file is) by default.
    * `resources.files`: indicate a (whitespace-separated) list of
      files that should be embedded. Currently only used with the EPUB
      renderer.
    * `resources.out_path`: indicate where `resources.files` should be
      copied in the final document. Default to `data`, meaning that
      files will be placed in a `data` directory in the EPUB.
* Rendering:
    * Templates can now use localized strings according to the `lang`
      option 
    * Standalone HTML now includes locale files using base64.
    * Standalone HTML displays one chapter at a time, thouht it can be
      changed via a button in the menu.
    * HTML/EPUB: default CSS now uses the `lang` value do determine
      how to display lists (currently the only difference is it uses
      "–" when `lang` is set to "fr" and standard bullets for other
      languages).
* Bugfixes:
    * Fixed a bug of filename "resolution" when Crowbook was called
      with `--single` (e.g., `crowbook -s tests/test.md` would
      previously try to load `tests/tests/test.md).
    * Epub renderer now uses the `mime_guess` library to guess the
      mime type based on extension, which should fix the mime type
      guessed for a wide range of extensions (e.g., svg).
* Internal/API:
    * The `Book::new`, `new_from_file`, and `new_from_markdown_file`
      take an additional `options` parameter. To create a book with
      default options, set it to `&[]`.



0.4.0 (2016-03-01)
------------------
* Crowbook now internally uses a true YAML parser, `yaml_rust`, for its
  options. Since the "old" Crowbooks's config format was similar, but
  had some subtle differences, this is somewhat of a breaking change:
    * strings should now be escaped with "" in some cases (e.g. if it
      contains special characters). On the other hand, it *allows* to
      optionally escape a string with these quotes, which wasn't
      possible until then and might be useful in some cases.
    * multiline strings now follow the YAML format, instead of the
      previous "YAML-ish" format. This can impact the way newlines are
      added at the end of a multiline string. See
      e.g. [this link](http://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines)
      for the various ways to include mulitiline strings in Yaml.
* Crowbook now parses YAML blocks (delimited by two lines with "---")
  in Markdown files, ignoring keys that it doesn't recognize. This
  allows crowbook to be compatible(-ish) with Markdown that contains
  YAML blocks for Jekyll or Pandoc.
* New option `--single` allows to give Crowbook a single Markdown file
  (which can contain options within an inline YAML block) instead of a
  book configuration file. This is useful for e.g. short stories.
* Enhanced the way debugging/warning/info messages are handled and
displayed:
    * Added a `--debug` option to the binary.
    * Internal: added a `Logger` struct.
    * Different levels of information (debug/warning/info/error) get
      different colours.
* Bugfixes:
    * Crowbook no longer crashes when called with the `--to` argument
      if it can't create a file. 


0.3.0 (2016-02-27)
------------------
* Crowbook now tries to convert local links. That is, if you link to a
  Markdown file that is used in the book.
  (e.g. [README.md](README.md)), it *should* link to an appropriate
  inner reference inside the book.
* Latex renderer now supports (local) images.
* Epub renderer now embed (local) images in the EPUB file.
* Some changes to the HTML/Epub stylesheets.
* Internal (or usage as a library):
    * Crowbook no longer changes current directory, which worked in
      the binary but could cause problem if library was used in
      multithreaded environment (e.g. in `cargo test`).
    * More modules and methods are now private.
    * Improved documentation.
    * Added more unit tests.
* Bugfixes: 
    * Epub renderer now correctly renders unnumbered chapter without a
      number in its toc.ncx file



0.2.2 (2016-02-25)
------------------
* Bugfixes:
    * French cleaner now correctly replaces space after — (in
      e.g. dialogs) with "em space".


0.2.1 (2016-02-25)
------------------
* Bugfixes:
    * HTML/Epub rendering no longer incorrectly increment chapter
      count for unnumbered chapters.
    * Latex: makes what is possible to avoid orverflowing the page.
* Minor changes:
    * Latex: improvement of the default way URLs are displayed.
      

0.2.0 (2016-02-25) 
------------------
* Command line arguments:
    * New argument `--print-template` now allows to print a built-in
      template to stdout. 
    * New argument `--list-options` prints out all valid
      options in a config file (or in `set`), their type and default
      value.
    * New argument `--set` allows to define or override whatever
      option set in a book configuration.
    * `--create` can now be used without specifying a `BOOK`, printing
      its result on `stdout`.
* Configuration file:
    * Added support for multiline strings in `.book` files, with
      either '|' (preserving line returns) or '>' (transforming line
      returns in spaces) 
    * New option `display_toc` allows to display the table of contents
      (whose name, at least for HTML, is specified by `toc_name`) in
      HTML and PDF documents.
    * Option `numbering` now takes an int instead of a boolean,
      allowing to specify the maximum level to number (e.g. `1`:
      chapters only, `2`: chapters and sectino, ..., `6`: everything).
* Rendering: 
    * Added support for numbering all headers, not just level-1 (e.g.,
      having a subsection numbered `2.3.1`).
    * Tables and Footnotes are now implemented for HTML/Epub and LaTeX
    output.
* Internal:
    * Refactored `Book` to use an HashMap of `BookOption`s instead of
      having like 42 fields.


0.1.0 (2016-02-21)
------------------
* initial release