tools/quickbook/doc/change_log.qbk

   1 [/
   2     Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
   3     Copyright 2010-2011 Daniel James
   4
   5     Distributed under the Boost Software License, Version 1.0.
   6     (See accompanying file LICENSE_1_0.txt or copy at
   7     http://www.boost.org/LICENSE_1_0.txt)
   8 ]
   9
  10 [chapter Change Log
  11     [quickbook 1.6]
  12     [compatibility-mode 1.5]
  13     [id quickbook.change_log]
  14     [source-mode teletype]
  15 ]
  16
  17 [heading:version_1_1 Version 1.1 - Boost 1.33.0]
  18
  19 * First version to be included in boost.
  20
  21 [heading:version_1_3 Version 1.3 - Boost 1.34.0 to 1.34.1]
  22
  23 * Quickbook file inclusion \[include\].
  24 * Better xml output (pretty layout). Check out the generated XML.
  25 * Regression testing facility: to make sure your document will always be
  26   compatible (full backward compatibility) regardless of changes to
  27   QuickBook.
  28 * Code cleanup and refactoring.
  29 * Allow phrase markup in the doc-info.
  30 * Preformatted code blocks via \`\`code\`\` (double ticks) allows code in tables
  31   and lists, for example.
  32 * Quickbook versioning; allows full backward compatibility. You have to add
  33   \[quickbook 1.3\] to the doc-info header to enable the new features. Without
  34   this, QuickBook will assume that the document is a pre-1.3 document.
  35 * Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
  36   Example:``
  37   [section x]
  38   blah...
  39   [endsect]``
  40 * Fully qualified section and headers. Subsection names are concatenated to the
  41   ID to avoid clashing. Example: `doc_name.sect_name.sub_sect_name.sub_sub_sect_name`
  42 * Better &nbsp; and whitespace handling in code snippets.
  43 * \[xinclude\] fixes up the relative path to the target XML file when
  44   input_directory is not the same as the output_directory.
  45 * Allow untitled tables.
  46 * Allow phrase markups in section titles.
  47 * Allow escaping back to QuickBook from code, code blocks and inline code.
  48 * Footnotes, with the \[footnote This is the footnote\] syntax.
  49 * Post-processor bug fix for escaped XML code that it does not recognize.
  50 * Replaceable, with the \[~replacement\] syntax.
  51
  52 [heading:version_1_4 Version 1.4 - Boost 1.35.0 to 1.40.0]
  53
  54 * Generic Headers
  55 * Code changes to allow full recursion (i.e. Collectors and push/pop functions)
  56 * Various code cleanup/maintenance
  57 * Templates!
  58 * \[conceptref\] for referencing BoostBook <concept> entities.
  59 * Allow escape of spaces. The escaped space is removed from the output. Syntax:
  60   `\ `.
  61 * Nested comments are now allowed.
  62 * Quickbook blocks can nest inside comments.
  63 * __import__ facility.
  64 * Callouts on imported code
  65 * Simple markups can now span a whole block.
  66 * __blurbs__, __admonitions__ and table cells (see __tables__) may now
  67   contain paragraphs.
  68 * `\n` and `[br]` are now deprecated.
  69 * __cond__. Ala C++ #ifdef.
  70 * Searching of included and imported files in an extensible search path with
  71   `--include-path` (`-I`) option.
  72
  73 [heading:version_1_5 Version 1.5 - Boost 1.41.0 to 1.42.0]
  74
  75 * Support multiple copyright entrys in document info.
  76 * Improved SVG support.
  77 * \[globalref\] for referencing BoostBook <global> entities.
  78 * Fail on error.
  79 * Fix crash for templates with too many arguments or trailing space.
  80 * Improved handling of unexpected characters in code blocks.
  81 * Improved handling of unmatched escape in code blocks.
  82 * Support for python snippets.
  83 * `teletype` source mode.
  84 * Use static scoping in templates, should be a lot more intuitive.
  85 * Accept a space between `section:` and the section id.
  86 * Support table ids.
  87
  88 [heading Version 1.5.1 - Boost 1.43.0]
  89
  90 * Improve the post processor's list of block elements. `table`, `entry` and
  91   `varlistentry` are treated as blocks. `replaceable` is treated as an inline
  92   element.
  93 * Check that `[section]` and `[endsect]` tags are balanced in templates.
  94 * Add unicode escape characters, eg. `\u03B1` for \u03B1.
  95 * Support UTF-8 files with a unicode byte order mark.
  96 * Disallow `[` in simple markup. Fixes some errors with mismatched punctuation.
  97 * Add command line flag to define macros at the command line,
  98   e.g. `quickbook "-D__italic_foo__=/foo/"`.
  99
 100 [heading Version 1.5.2 - Boost 1.44.0]
 101
 102 * Use the cygwin 1.7 API for better path handling.
 103 * Improved boostbook generation:
 104   * XML encode the documentation info correctly.
 105   * Avoid generating empty paragraphs.
 106   * No longer wraps block templates in paragraphs.
 107   * Warns if you use invalid doc_info members for docbook document types.
 108   * Fixes some other causes of invalid boostbook, although it still
 109     generates invalid boostbook in places.
 110 * Improved grammar:
 111   * Supports multiple categories in library doc_info.
 112   * No longer requires commas between authors in docinfo.
 113   * Allows empty document bodies.
 114   * A line containing only a comment is no longer interpreted as a
 115     paragraph break.
 116   * If a line starts with a comment, interpret it as a paragraph even if it's
 117     followed by whitespace or a list character.
 118   * Doesn't treat several consecutive blank lines as multiple paragraph breaks.
 119 * Fixes duplicate image attribute detection.
 120 * Fixes using code snippets more than once.
 121 * Early work on quickbook 1.6, available using the `[quickbook 1.6]` version switch,
 122   but liable to change in future versions.
 123   * When automatically generating ids for headers, use the quickbook
 124     source, rather than the generated docbook.
 125   * Fix id generation in included files. It wasn't correctly using the
 126     main document's documentation id.
 127   * Correctly restore the quickbook version switch after including a file
 128     with a different version.
 129
 130 [heading Version 1.5.3 - Boost 1.45.0]
 131
 132 * Fix command line flag for defining macros.
 133 * Fix a couple of issues with the code block parser:
 134   * A comment with no indentation will now end a code block.
 135   * Code blocks no longer have to be followed by a blank line.
 136 * Improved tracking of file position in templates and imported code blocks.
 137 * Better generated markup for callout lists.
 138 * In docbook, variable list entries can only have one `listitem`, so if an
 139   entry has multiple values, merge them into one `listitem`.
 140 * Support nested code snippets.
 141 * Support nested blocks in document info comments.
 142 * Revert xml escaping document info, it broke some documentation files
 143   (now a 1.6 feature).
 144 * Further work on quickbook 1.6, still not stable.
 145   * Allow heading to have ids, using the syntax: `[heading:id title]`.
 146   * XML escape documentation fields, with escapes to allow encoding unicode
 147     in ASCII.
 148
 149 [heading Version 1.5.4 - Boost 1.46.1]
 150
 151 Boost 1.46.0:
 152
 153 * Add support for `lang` attribute in documentation info.
 154 * Improved anchor implementation. Especially for using an anchor
 155   before a section or heading.
 156 * Fixed some more issues where lines containing comments were treated
 157   as blank lines.
 158 * Allow import, include and xinclude in conditional phrases. Will
 159   allow more block elements in a future version.
 160 * Rearrange the structure of the grammar.
 161 * Use filesystem 3. Remove cygwin 1.5 support.
 162
 163 Boost 1.46.1:
 164
 165 * Work around optimization bug in g++ 4.4 on 64 bit linux.
 166
 167 [heading Version 1.5.5 - Boost 1.47]
 168
 169 * Tweak anchor placement for titles.
 170 * Hard code the quickbook path into the quickbook testing tools. This
 171   means that they can be used from multiple locations.
 172 * Generate an id for boostbook `bridgehead` elements. This results in
 173   more consistent html, since docbook generates a random id if they
 174   don't have one.
 175 * Improved unicode support on windows. Unicode can now be used from the
 176   command line, and unicode filenames are supported. Unicode output is
 177   a bit weak.
 178 * Check for windows paths, and warn about them.
 179 * Fix relative path detection on windows.
 180 * Reverse deprecation of `[br]`, printing a single warning about
 181   generating invalid boostbook.
 182 * Fix handling empty category attributes.
 183 * Store data from the parser in a dynamic data structure.
 184   This simplifies the implementation and makes it easier to parse
 185   more complicated data structures.
 186 * Improved error messages for unknown doc info attributes.
 187 * Richer copyright syntax. Now understands:
 188   `[copyright 2001-2006, 2010 One person, 2008 Another person]`.
 189 * Fix delimeter checking for simple markup.
 190 * Allow more block elements to be nested.
 191 * Go back to using invalid markup for lists. It generates better html.
 192 * Better anchor placement for lists.
 193 * Pass-thru comments in code snippets.
 194 * Use relative paths for '''<code>__FILENAME__</code>''' macro.
 195 * Rewrite xinclude path generator so that it doesn't use deprecated
 196   filesystem functions.
 197 * Allow quickbook escapes inside comments in syntax highlighted code.
 198 * Quickbook 1.6:
 199   * Scope source mode changes to the file they're made in.
 200   * Explicit markup for lists. e.g.
 201     `[ordered_list [item1][item2]]` or
 202     `[itemized_list [item1][item2]]`.
 203
 204 [heading Version 1.5.6 - Boost 1.48]
 205
 206 * Xml encode escaped punctuation (eg. `\<` is correctly encodes to \<).
 207 * Rename duplicate generated ids.
 208 * Close open sections at end of document (still warns about them).
 209 * New anchor markup for headers, will hopefully generate better pdfs.
 210 * Remove some whitespace around code from post processed output.
 211
 212 [heading Version 1.5.7 - Boost 1.49]
 213
 214 * Several internal changes.
 215 * Some improved error messages.
 216 * Better handling of block templates expanded in a phrase context.
 217 * Avoids empty simple markup (i.e. \/\/ is not treated as an italic empty
 218   space.
 219 * Better anchor markup for headers, which should be better for printing
 220   - suggested by John Maddock.
 221 * Further improvements to the id generator.
 222 * If sections are left unopened at the end of a document, then close them
 223   in the generated markup.
 224 * Try to handle whitespace better at the beginning and end of code blocks.
 225 * Handle lists that come immediately after an anchor.
 226 * Make horizontal rules followed by multi-line comments a little more
 227   sensible.
 228 * Better support for empty ids and titles in docinfo.
 229 * Fix some minor regressions in SVG handling.
 230 * Better handling of invalid command line macros.
 231 * When auto-building quickbook, build the release version.
 232 * Lots of changes for 1.6:
 233   * Scope templates in included files.
 234   * Support import of templates and macros.
 235   * Including top level quickbook blocks from source files.
 236   * Use doc info blocks in included quickbook files.
 237   * Better handling of macros with the same name.
 238   * `block` element.
 239   * Better handling of significant punctuation (e.g. escapes, square brackets).
 240   * Support escapes in links, anchors, images, includes etc.
 241   * Improved table title syntax.
 242   * Paragraphs nested in lists.
 243   * New docinfo attributes:
 244     * `compatibility-mode` to make it possible to upgrade documents without
 245       breaking ids.
 246     * `xmlbase` for escaped `xi:include`s.
 247   * Allow some docinfo attributes to be used before, or without, a doc info
 248     block (`quickbook`, `compatibility-mode`, `source-mode`).
 249   * Only add explicit alt text to images.
 250   * Don't put 'inline' code blocks inside paragraphs.
 251
 252 [heading Version 1.5.8 - Boost 1.50]
 253
 254 * Write dependencies to a file, using `--output-deps`
 255   ([@https://svn.boost.org/trac/boost/ticket/6691 #6691]).
 256 * Fix handling of section tags in lists.
 257 * Fix indented code blocks in lists.
 258 * Fix handling UTF-8 code points in the syntax highlighter.
 259   Was treating each individual byte as a character.
 260   Still doesn't deal with combining code points.
 261 * Internal changes:
 262   * A lot of restructuring.
 263   * Stop using 'v3' filesystem paths and namespaces, it's now
 264     the default version.
 265   * Remove awkward intrusive reference counting implementation,
 266     avoids a gcc internal compiler error
 267     ([@http://svn.boost.org/trac/boost/ticket/6794 #6794]),
 268     but is also a cleaner implementation.
 269 * 1.6 changes:
 270   * Better handling of brackets in link values.
 271   * Improved handling of escaped characters in include paths.
 272 * Starting to develop 1.7:
 273   * Source mode for single entities.
 274   * Callouts in code blocks.
 275   * Escaped docbook in docinfo blocks.
 276   * Starting to implement calling templates from link values.
 277
 278 [heading Version 1.5.9 - Boost 1.54]
 279
 280 * When code blocks are indented using a mixture of tabs and spaces,
 281   convert indentation to spaces.
 282 * In the C++ systax highlighter, fix syntax highlighting for `#`, so that it's
 283   used for preprocessor statements at the start of a line, and as a 'special'
 284   character elsewhere
 285   ([@https://svn.boost.org/trac/boost/ticket/8510 #8510],
 286   [@https://svn.boost.org/trac/boost/ticket/8511 #8511]).
 287 * Add C++11 keywords to syntax highlighter
 288   ([@https://svn.boost.org/trac/boost/ticket/8541 #8541]).
 289 * Hidden options for formatting of `--output-deps`. Not really for public use
 290 * yet.
 291 * 1.6 changes:
 292   * Better template argument parsing, so that it understands things
 293     like escaped markup.
 294   * Support for using macros in the doc info block.
 295 * Internal changes:
 296   * Convert to use `boost::string_ref`.
 297   * Clean up the source map implementation (used to get the correct
 298     location for error messages in things like templates and snippets).
 299
 300 [heading Version 1.6.0 - Boost 1.55]
 301
 302 * Remove nested blocks in lists from 1.6, move to 1.7.
 303   (Can still nest block elements in lists though).
 304 * Don't break out of lists after a nested block element.
 305 * Check for errors when writing dependency files.
 306 * Improved markup for lists.
 307 * Make escaping templates with a punctuation identifier illegal.
 308   Escaping templates with an alphanumeric identifier is still fine.
 309 * Fix detection of code blocks at the start of a file.
 310 * XML encode the contents of the `__FILENAME__` macro.
 311 * 1.7 changes:
 312   * Make it an error to use an element in the wrong context.
 313   * Error if the body of a phrase element doesn't parse.
 314   * List markup in nested blocks.
 315   * Allow block elements in phrase templates.
 316   * Make it an error to put a paragraph break (i.e. a blank line)
 317     in a phrase template.
 318 * Internal changes:
 319   * Clean up the id manager implementation.
 320
 321 [heading Version 1.6.1]
 322
 323 * Better URI encoding of links.
 324 * Extra validation of attribute values.
 325 * 1.7 changes:
 326   * Improved source mode tagging:
 327     * Works for lists and paragraphs.
 328     * If the source mode is changed inside a tagged element, that change
 329       will now persist after the element.
 330     * Tagged sections will now use the source mode for the whole section.
 331   * Template calls from anchor, role and include elements.
 332   * Stricter handling of templates called in attribute values.
 333   * Glob support.