release_history.txt

Release history
===============

[[Parent]]: remark.txt

This section summarizes the release history of Remark. Previous versions can be obtained through the given links. 

The versioning of Remark is given in the form x.y.z, where x, y, and z are integers. The x increments only for major changes, the y increments for feature changes, and the z increments for bug fixes or documentation updates. Whenever y is incremented, z is zeroed, and whenever x is incremented, both y and z are zeroed. The x, y, and z need not consist of a single digit, and, for example, 1.12.0 is a much later version than 1.1.3.

Remark 1.7.9
------------

Release date 01.01.2023.

[Original webpage][Remark-1.7.9]

[Remark-1.7.9]: http://kaba.hilvi.org/remark-1.7.9

### Libraries

* Fixed broken `codecs.open` call due to `U` flag no longer being supported.

Remark 1.7.8
------------

Release date 31.10.2021.

[Original webpage][Remark-1.7.8]

[Remark-1.7.8]: http://kaba.hilvi.org/remark-1.7.8

### Libraries

* Fixed broken library dependence to Markdown by downgrading its version.

Remark 1.7.7
------------

Release date 10.12.2019.

[Original webpage][Remark-1.7.7]

[Remark-1.7.7]: http://kaba.hilvi.org/remark-1.7.7

### CSS

* Changed font-urls to use https.

Remark 1.7.6
------------

Release date 09.10.2019.

[Original webpage][Remark-1.7.6]

[Remark-1.7.6]: http://kaba.hilvi.org/remark-1.7.6

### CSS

* Fixed erroneous CSS style setting for list-items.

Remark 1.7.5
------------

Release date 16.06.2017.

[Original webpage][Remark-1.7.5]

[Remark-1.7.5]: http://kaba.hilvi.org/remark-1.7.5

### Core

* Changed MathJax CDN, since MathJax's own CDN was shut down.

Remark 1.7.4
------------

Release date 09.03.2017.

[Original webpage][Remark-1.7.4]

[Remark-1.7.4]: http://kaba.hilvi.org/remark-1.7.4.2

### Core

* Made maximum file-size command-line option opt-in, rather than opt-out.
* Fixed a bug when providing invalid config file under Python 3.

### CSS

* Fixed a list-item displaying weirdly when containing a paragraph.

Remark 1.7.3
------------

Release date 29.10.2016.

[Original webpage][Remark-1.7.3]

[Remark-1.7.3]: http://kaba.hilvi.org/remark-1.7.3

### Core

* Fixed a bug where region-extension was too strict on what constitutes a value.
* Made reporting avoid extraneous newlines.
* Added support for Python 3.

Remark 1.7.2
------------

Release date 27.02.2016.

[Original webpage][Remark-1.7.2]

[Remark-1.7.2]: http://kaba.hilvi.org/remark-1.7.2

### Acknowledgements

* [Juho Lauri][] found the input-directory bug, and suggested to create a Hello-world example.

[Juho Lauri]: http://math.tut.fi/~laurij/

### Core

* Added a check that the input-directory really is a directory, and not a file.
* Added a debug-switch `-b`.
* Fixed a crash when specifying a non-existing input-directory.
* Fixed a bug where indentation macro merged with the following content, requiring an additional new-line.
* Fixed `dict()` and `[]` from being used as default-arguments; a known Python-trap.

### MathJax

* Changed equation numbering from `"all"` to `"AMS"`, since with `"all"` MathJax [did not render binomial coefficients correctly][MathJaxBinomialBug].

[MathJaxBinomialBug]: https://github.com/mathjax/MathJax/issues/1194

### CSS

* Enforced two columns for `DocChildren` list-items by setting `max-width: 50%`.
* Changed the color of level-4 headers.

### Documentation

* Added a Hello-world example to main page.

Remark 1.7.1
------------

Release date 13.05.2015.

[Original webpage][Remark-1.7.1]

[Remark-1.7.1]: http://kaba.hilvi.org/remark-1.7.1

### Acknowledgements

* Peter Krautzberger and Murray Bourne helped to diagnose the MathJax configuration-bug.

### MathJax

* Made MathJax to use `https` instead of `http`.
* Fixed a configuration bug which caused MathJax loading to fail sometimes.

Remark 1.7.0
------------

Release date 12.05.2015.

[Original webpage][Remark-1.7.0]

[Remark-1.7.0]: http://kaba.hilvi.org/remark-1.7.0

### Acknowledgments

* David P. Cervone helped to [debug MathJax rendering][MathJaxColors]. The lack of localization in the Pygments CSS-file caused it to leak into MathJax rendering.
* Waylan Limberg helped with understanding the html-stash internals in Python Markdown.

[MathJaxColors]: https://github.com/mathjax/MathJax/issues/1169

### Core

* Extended Markdown with mathematics.
* Extended Markdown with regions.
* Extended Markdown with scoped links.
* Extended Markdown with dashes, quotes, and ellipses --- using the SmartyPants extension.
* Fixed html title from containing extraneous escaping-characters.
* Removed the abbreviation extension, because it did not work well with regions.

### Mathematics

* Added support for Latex mathematics.

### Indentation macro

* Fixed the macro invocation from being too eager.

### Html macro

* Disabled Markdown expansion.
* Removed the production of extraneous `<span>` elements for empty lines.
* Wrapped the produced content into a `<div>` element.

### CSS

* Made the Pygments CSS more specific, so that it does not interfere with MathJax rendering.
* Made Example-div to scroll on overflow.
* Made Example-div to zero top- and bottom-margins of first- and last-child `<div>`s.

### Interface

* Added the option `-g` to generate the Markdown source for each file. This is useful for debugging.
* Added the option `-c` for specifying JSON configuration files.

### Dependencies

* Changed to use the latest Python Markdown. 
* Changed to use MathJax for improved parsing and rendering of mathematics.
* Added dependency to the `jsonschema` Python library, for JSON validation.
* Removed dependency to `ASCIIMathMLwFallback.js`.

Remark 1.6.5
------------

Release date 14.12.2014.

[Original webpage][Remark-1.6.5]

[Remark-1.6.5]: http://kaba.hilvi.org/remark-1.6.5

### Acknowledgements

* Programmed under funding from the [Finnish National Doctoral Programme in Mathematics and its Applications][GSMAA].

### CSS

* Changed to use the Open Sans font for prose.
* Changed to use the Inconsolata font for code, or Consolas if available (Windows).

### Example macro

* Wrapped the produced content into a `<div>` element.
* Separated the example from its surrounding by drawing a box around it.
* Removed the preceding and following texts.

### SourceChildren macro

* The title is now created only if it is non-empty.

### Documentation

* Changed to use the improved Example macro.

Remark 1.6.4
------------

Release date 13.12.2014.

[Original webpage][Remark-1.6.4]

[Remark-1.6.4]: http://kaba.hilvi.org/remark-1.6.4

### Acknowledgements

* Programmed under funding from the [Finnish National Doctoral Programme in Mathematics and its Applications][GSMAA].

### Core

* Added a viewport meta-tag so that html works nicely with tablets and phones.

### CSS

* Made CSS work nicely with tablets and phones.
* Changed to use flexboxes.
* Made list-based links block-based, for increased area.

### SourceChildren

* Made to output a list of links instead of sequential links.
* Added a div for CSS-styling.

Remark 1.6.3
------------

Release date 4.12.2014.

[Original webpage][Remark-1.6.3]

[Remark-1.6.3]: http://kaba.hilvi.org/remark-1.6.3

### Packaging

* Changed Markdown requirement from 2.0.0 to 2.0.

Remark 1.6.2
------------

Release date 23.11.2014.

[Original webpage][Remark-1.6.2]

[Remark-1.6.2]: http://kaba.hilvi.org/remark-1.6.2

### Acknowledgements

* Programmed under funding from the [Finnish National Doctoral Programme in Mathematics and its Applications][GSMAA].

### Macros

* Code: Fixed a crash when the lexer could not be guessed from content.

Remark 1.6.1
------------

Release date 18.04.2014.

[Original webpage][Remark-1.6.1]

[Remark-1.6.1]: http://kaba.hilvi.org/remark-1.6.1

### Acknowledgements

* Programmed under funding from the [Finnish National Doctoral Programme in Mathematics and its Applications][GSMAA].

### Interface

* Made minor improvements to output reporting.

### Style

* Made tables pretty when using the default CSS style.
* Made some minor tweaks to the default CSS style.

### Macros

* DocChildren: Grouped undescribed files in the same description-group.
* DocChildren: Fixed a bug which gave a bad-looking grouping in some cases.
* Code: Forced `.m` files to be identified as Matlab files when the type is not explicitly specified.

### Packaging

* Changed to use Setuptools, instead of Distribute.

Remark 1.6.0
------------

Release date 28.05.2013.

[Original webpage][Remark-1.6.0]

[Remark-1.6.0]: http://kaba.hilvi.org/remark-1.6.0

### Acknowledgements

* Programmed under funding from the [Finnish National Doctoral Programme in Mathematics and its Applications][GSMAA].

### Breaking changes

* Changed the command-line file inclusion to work by relative-paths of files, rather than by filenames. This breaks the inclusion of multiple files with the same filename, but in different directories; the old behavior can be recovered by changing `"filename.txt"` to `"*filename.txt"`. 
* Changed the location of the Remark command-line script from the `Remark` directory to the Remark root directory. This had to be done so that `pip` packaging works correctly. However, this is also a more natural location for the command-line script.

### Interface

* Added the option `-x` to exclude files by their
relative-paths. This helps in skipping build-files
and other inessential files in a typical build-environment.
* Added the option `-i` to include files by their
relative-paths. This is the same as simply listing
them; this option is for symmetry with the option `-x`.
* Added the option `-o` to read command-line options
from an option-file (if the file exists). The 
`remark_options` is implicitly included as an option-file.
* Added the option `-u` to list all those files in
the input directory which are neither included or
excluded (called unknown files). This helps to check
whether one has remembered to include all essential 
files into the documentation.
* Increased the default maximum number of lines for the 
tag-parsers from 100 to 200. In Matlab, the tags must be 
placed at the end of this function documentation to not 
interfere with the built-in help system. My own Matlab 
function documentation exceeded 100 lines, one being 
135 lines.

### Variables

* Added the `remark_version` as a predefined variable,
to aid in the documentation of Remark itself.

### Macros

* Added the ReadFile macro, to read plain-text files. This
generalizes the Body macro.
* Added the `type` variable in the Code macro so that the
type of the code can be specified explicitly.
* Made description grouping more effective in the 
SourceChildren macro.

### Style

* Restyled the default CSS file.

### Packaging

* Added a repository for Remark on BitBucket.
* Added an issue tracker for Remark on BitBucket.
* Made Remark installable from PyPI using `pip` and `easy_install`.
* Changed to use Pillow instead of PIL.

[GSMAA]: https://wiki.helsinki.fi/display/gsmaa

Remark 1.5.1
------------

Release date 31.10.2012

[Original webpage][Remark-1.5.1]

[Remark-1.5.1]: http://kaba.hilvi.org/remark-1.5.1

### Core

* Added a check for Python Markdown version 2.0, to prevent using Remark 
  with versions of Python Markdown (e.g. 2.2) that do not support Markdown 
  in html blocks.
* Fixed a regex-formation bug in `Dictionary_TagParser`, which caused the 
`Author` and `DocumentationOf` tags to not being parsed.

### Macros

* Gallery: Made the PIL import work also in the case where PIL is 
  installed in a directory named something else than PIL, as is the 
  case when installing PIL via `easy_install` 
  (bug credit: Germán Gómez-Herrero).

### Others

* Set the correct release date for Remark 1.5.0 in release history.
* Rewrote the installation documentation.

Remark 1.5.0
------------

Release date 30.09.2012

[Original webpage][Remark-1.5.0]

[Remark-1.5.0]: http://kaba.hilvi.org/remark-1.5.0

### Acknowledgements

* Germán Gómez-Herrero did extensive testing on Remark 1.5.0, and
came up with ideas for the ParentList and DocumentTree macros,
and support for long-UNC paths under Windows.

### Core

* Added support for long-UNC-paths under Windows.
* Added document-tags.
* Added a reporting system for more accurate error messages
and the ability to disable specific messages.
* Generalized indentation as a specific way to invoke a macro,
and made this macro selectable at runtime by the `indent` variable.
* Made Remark to copy a file only when the target file does not
exist _or_ the source file has been modified after the target file.
* Made Remark name links to code-files with their filenames, rather
than with their descriptions.
* Escaped Markdown meta-characters in path-based link-descriptions
(e.g. \_\_init\_\_.py instead of __init__.py).
* Fixed a crash in the handling of invalid utf-8 files by replacing 
invalid parts with the U+FFFD REPLACEMENT CHARACTER symbol.
* Removed predefined variables, and replaced them with document tags.
* Removed get-command.

### Interface

* Changed it so that all converted files need to be listed, rather
than just those which are to be copied.
* Added an option for listing all the file-extensions in the input
directory along with example files. This makes it easier to check
that one has remembered to include all necessary files.
* Added an option for generating only the modified files and their
parents for quick previews.
* Added an option for verbose mode, and moved successful output
from the normal mode to the verbose mode. This makes it easier
to spot warnings.
* Added an option for disabling specific warnings.
* Added an option for treating warnings as errors.
* Added the generation of a non-zero error-code when errors are present.
* Added an option for setting the maximum file-size to load.
* Added timing for the generation process.
* Added a warning about a description missing for a document-group.
* Added a warning about using a long relative-path where a shorter
suffix-path would have sufficed.
* Removed the option for a prologue file.

### Document types

* Generalized the concept of a document type not only to describe
the conversion by Remark syntax, but to completely abstract the
conversion process.
* Every document in the document tree now has a document type.
* Added the Copy document type, which simply copies the input file
to the output file. This is the default document type.

### Macros

* Added the ParentList macro to generate a list of parent documents.
* Added the DocumentTree macro to generate parts or all of the document tree.
* Added the Example macro to easily generate examples in Remark.
* Added the Equation macro to generate equations.
* Added the EquationSet macro to generate multiple equations.
* Gallery: Increased the default number of pixels in thumbnails.
* Gallery: Made the macro work also with vector-based images, such
as .svg.
* Gallery: Added support for multiple image formats, so as to
generate thumbnails for .svg from a pixel-based alternative image.
* Gallery: Made the thumbnail-names practically unique by appending a
suffix of the md5-hash of the relative-name.
* DocChildren and Index: Changed the listings to lists rather than 
tables for better CSS-styling. Added `class_name` variables.
* Renamed GenericCode macro to Code macro, and made GenericCode an 
alias of Code.

### Tag parsers

* Added the Dictionary_TagParser which uses a much more efficient
search algorithm than the previous Regex_TagParser (one regex for 
all tags, instead of one regex per each tag).
* Removed Empty_TagParser.
* Removed Regex_TagParser.

### Documentation

* Updated for better structure.
* Added installation instructions for 64-bit Windows's.
* Added the version number in the footer.

### Html and CSS

* Updated the CSS-style files.
* Made the generated html-boilerplate more standards-conforming.

### AsciiMathML

* Added support for online mimetex-rendering as a fallback when 
the browser does not support MathML.

### Highslide JS

* Upgraded to use Highslide JS 4.1.13.

### Others

* Changed to use the MIT license.

Remark 1.4.0
------------

Release date 01.06.2011.

[Original webpage][Remark-1.4.0]

[Remark-1.4.0]: http://kaba.hilvi.org/remark-1.4.0

### Core

* Fixed the handling of different kinds of newlines.
* Fixed a buggy library import.

### Interface

* Added the ability to invoke Remark from other directories.
* Added proper error messages for missing dependency libraries.

Remark 1.3.0
------------

Release date 17.03.2011.

[Original webpage][Remark-1.3.0]

[Remark-1.3.0]: http://kaba.hilvi.org/remark-1.3.0

### Core

* Added reference links, i.e. the `DocumentationOf` tag
which uses as documentation the documentation of another
file.
* Made document search to look for a file in all directories,
in case a hierarchical search upwards does not find the file.
* Updated the layout of link tables.

### Other

* Updated the default css file.

Remark 1.2.0
------------

Release date 11.03.2010.

[Original webpage][Remark-1.2.0]

[Remark-1.2.0]: http://kaba.hilvi.org/remark-1.2.0

### Acknowledgements

* Remark 1.2.0 was programmed under funding from 
the [Finnish Foundation for Technology Promotion][TES].

[TES]: http://www.kolumbus.fi/tes/ 

### Core

 * Allowed free positioning of Remark macros. 
 * Added the ability to invoke macros via inline parameters.
 * Added explicit control over parameter and output
 expansion behavior in macro invocation.
 * Allowed local variables for macros.
 * Added `set_outer`, `add_outer`, and `outer` commands to 
 set, append, and retrieve variables at outer scopes, respectively.
 * Allowed parameter passing for variables to turn
 them into user-defined text transformations. 
 * Variables can now be retrieved simply by their name,
 rather than having to use `get`. 
 * Added `set_many` command to set variables easily.
 * Fixed a bug in `filesToCopy` pattern matching:
 a file was copied only if it matched all patterns.
  
### Macros

 * Added FileLink macro to generate links with the link 
 description set to the filename of the target.
 * Added the implicit file searching algorithm for pure 
 filenames into various macros. 
 * DocChildren and Index macros now use 2 or 3 columns to 
 list the items if there are more than 7 of them.
 * Added Html macro to embed html directly.
 * Added Gallery macro to generate image galleries.
 * Added Verbatim macro to reinterpret text as
 verbatim content.
 * Added DirectoryLink macro to generate links to
 the containing directories of files.
 * Added Copy macro to copy the input without changes.
 * Added Ref macro to return the relative filenames of 
 the output documents.
 * Removed SkipExpansion macro. Its effect can
 be obtained with the Copy macro.

### Interface

 * Added the option to merge a prologue file to the
 beginning of each document template.

### Additional dependencies

 * Dependence to _Python Imaging Library_ via Gallery macro.
 * Optional dependence to _Highslide_ javascript library
 via Gallery macro.

Remark 1.1.0
------------

Release date 23.01.2010.

[Original webpage][Remark-1.1.0]

[Remark-1.1.0]: http://kaba.hilvi.org/remark-1.1.0

### Acknowledgements

* Remark 1.1.0 was programmed under funding from 
the [Finnish Foundation for Technology Promotion][TES].

### Core

 * Non-converted files are now copied only if they match
 a filename-pattern specified at the command line (filesToCopy arguments).
 * Tag-parsers now only read at most 100 lines from a file
 (configurable via the option -l). This speeds up the parsing of
 tags.

### Interface

 * Added option-parsing to console interface.

Remark 1.0.1
------------

Release date 13.01.2010.

[Original webpage][Remark-1.0.1]

[Remark-1.0.1]: http://kaba.hilvi.org/remark-1.0.1

### Acknowledgements

* Remark 1.0.1 was programmed under funding from 
the [Finnish Foundation for Technology Promotion][TES].

### Core

 * Bug-fix: some directories were written in Windows-style 
 backslashes into the html files depending on which OS was
 used to run Remark.

Remark 1.0.0
------------

Release date 13.01.2010. 

### Acknowledgements

* Remark 1.0.0 was preceded by a similar implementation called _LightMark_ 
programmed by [Juho Hämäläinen][Juho]. The ideas gathered and tested 
in that implementation was the basis on which Remark was built. He 
should be attributed the idea of using Markdown for writing the 
documentation.

* Remark 1.0.0 was programmed under funding from 
the [Finnish Foundation for Technology Promotion][TES].

[Juho]: http://jusa.hilvi.org