1[/ 2 Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler 3 Copyright 2012-2013 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[section:1_7 Quickbook 1.7] 11 12[section:context_error Error for elements used in incorrect context] 13 14Previously if you used an element in the wrong context it would just be 15unprocessed, which was surprising. People often didn't realise that their 16element hadn't been processed. So now it's an error. 17 18[endsect:context_error] 19 20[section:phrase_parse_error Error for invalid phrase elements] 21 22If the body of a phrase element didn't parse, it would be just used 23unprocessed. Now change it to be a hard error. 24 25[endsect:phrase_parse_error] 26 27[section:source_mode Source mode for single entities] 28 291.7 introduces a new `!` element type for setting the source mode of a single 30entity without changing the source mode otherwise. This can be used for 31code blocks and other elements. For example: 32 33``` 34[!c++] 35 void foo() {}; 36 37[!python]``\`\`\`\ ``def foo():``\`\`\`\ `` 38``` 39 40It can also be used to set the source mode for elements: 41 42``` 43[!teletype][table 44 [[code][meaning]] 45 [[`+`][addition]] 46] 47``` 48 49When used before a section, it sets the source mode for the whole section. 50 51If it appears at the beginning of a paragraph, it will be used for the 52whole paragraph only if there's a newline, eg. 53 54``` 55[!c++] 56A declaration `void foo();` and a definition `void foo() {}`. 57``` 58 59[endsect:source_mode] 60 61[section:callouts Callouts in code blocks] 62 63Currently callouts can only be used in code snippets. 1.7 adds 64support in normal code blocks. The same syntax is used as in 65code snippets, the callout descriptions appear immediately 66after the code block. 67 68[endsect:callouts] 69 70[section:escaped_docinfo_attributes Escaped docbook in docinfo blocks] 71 72Quickbook docinfo attributes will probably never be as rich as docbook 73attributes. To allow more flexible markup that is not supported by quickbook, 74escaped docbook can be included in the docinfo block: 75 76``` 77[article Some article 78[quickbook 1.7] 79'''<author> 80 <firstname>John</firstname> 81 <surname>Doe</surname> 82 <email>john.doe@example.com</email> 83</author>''' 84] 85``` 86 87The escaped docbook is always placed at the end of the docinfo block, 88so it shouldn't be assumed that it will interleave with markup generated from 89quickbook. A mixture 90of quickbook and docbook attributes for the same information will not work 91well. 92 93[endsect:escaped_docinfo_attributes] 94 95[section:listparagraphs Pargraphs in lists] 96 97Paragraphs and block elements can now be used in lists: 98 99[pre 100* Para 1 101 102 Para 2 103 * Nested Para 1 104 105 Nested Para 2 106 107 Code block 108 Para 3 109] 110 111generates: 112 113* Para 1 114 115 Para 2 116 * Nested Para 1 117 118 Nested Para 2 119 120 Code block 121 Para 3 122 123[endsect:listparagraphs] 124 125[section:templates_in_attributes Templates in some attributes] 126 127There's support for calling templates in link values, anchors, roles and 128includes. This is sometimes a bit of a change, especially in places where 129spaces are currently allowed, so I might try using a slightly different 130grammar where required. I think I also need to add some validation, since 131the parser can allow more symbols than some of the old ones. 132 133[endsect:templates_in_attributes] 134 135[section:list_markup_in_tables List Markup in Nested Blocks] 136 137Can now place list markup in nested blocks, e.g in tables, variables lists etc. 138Unfortunately indented code blocks are more tricky, because the contents of 139these blocks are often indented already. It seemed easier to just not support 140indented code blocks in this context than to try to work out sensible actions 141for the edges cases. If you want to use code blocks in this context, you should 142still be able to use explicit markup. 143 144[endsect:list_markup_in_tables] 145 146[section:phrase_block_templates Allow block elements in phrase templates] 147 148Block elements can now be used in phrase templates, but paragraphs breaks aren't 149allowed, so this is an error: 150 151 [template paras[] Something or other. 152 153 Second paragraph.] 154 155If a phrase template only contains block elements, then it's practically 156indistinguishable from a block template. So you'll get the same output from: 157 158 [template foo[] [blurb Blah, blah, blah]] 159 160as: 161 162 [template foo[] 163 [blurb Blah, blah, blah] 164 ] 165 166If a phrase template has phrase content mixed with block elements, it'll generate 167output as if it was expanded inline. 168 169[endsect:phrase_block_templates] 170 171[section:glob Including multiple files with Globs] 172 173One can now include multiple files at once using a glob pattern for the 174file reference: 175 176 [include sub/*/*.qbk] 177 [include include/*.h] 178 179All the matching files, and intermediate irectories, will match and be 180included. The glob pattern can be "\*" for matching zero or more characters, 181"?" for matching a single character, "\[<c>-<c>\]" to match a character class, 182"\[\^<char>-<char>\]" to exclusive match a character class, "\\\\" to escape 183a glob special character which is then matched, and anything else is matched 184to the character. 185 186[note Because of the escaping in file references the "\\\\" glob escape is 187a double "\\"; i.e. and escaped back-slash.] 188 189[endsect:glob] 190 191[endsect:1_7] 192