asciidoctor 0.1.4 → 1.5.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of asciidoctor might be problematic. Click here for more details.

Files changed (101) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +209 -25
  3. data/{LICENSE → LICENSE.adoc} +4 -3
  4. data/README.adoc +392 -395
  5. data/Rakefile +94 -137
  6. data/benchmark/benchmark.rb +127 -0
  7. data/benchmark/sample-data/mdbasics.adoc +334 -0
  8. data/bin/asciidoctor +5 -8
  9. data/bin/asciidoctor-safe +4 -8
  10. data/compat/asciidoc.conf +78 -11
  11. data/compat/font-awesome-3-compat.css +397 -0
  12. data/data/stylesheets/asciidoctor-default.css +399 -0
  13. data/data/stylesheets/coderay-asciidoctor.css +89 -0
  14. data/features/open_block.feature +92 -0
  15. data/features/pass_block.feature +66 -0
  16. data/features/step_definitions.rb +42 -0
  17. data/features/text_formatting.feature +55 -0
  18. data/features/xref.feature +116 -0
  19. data/lib/asciidoctor.rb +1155 -605
  20. data/lib/asciidoctor/abstract_block.rb +157 -71
  21. data/lib/asciidoctor/abstract_node.rb +150 -93
  22. data/lib/asciidoctor/attribute_list.rb +85 -90
  23. data/lib/asciidoctor/block.rb +51 -24
  24. data/lib/asciidoctor/callouts.rb +4 -7
  25. data/lib/asciidoctor/cli.rb +3 -0
  26. data/lib/asciidoctor/cli/invoker.rb +86 -76
  27. data/lib/asciidoctor/cli/options.rb +111 -61
  28. data/lib/asciidoctor/converter.rb +232 -0
  29. data/lib/asciidoctor/converter/base.rb +58 -0
  30. data/lib/asciidoctor/converter/composite.rb +66 -0
  31. data/lib/asciidoctor/converter/docbook45.rb +94 -0
  32. data/lib/asciidoctor/converter/docbook5.rb +684 -0
  33. data/lib/asciidoctor/converter/factory.rb +225 -0
  34. data/lib/asciidoctor/converter/html5.rb +1081 -0
  35. data/lib/asciidoctor/converter/template.rb +296 -0
  36. data/lib/asciidoctor/core_ext.rb +7 -0
  37. data/lib/asciidoctor/core_ext/object/nil_or_empty.rb +23 -0
  38. data/lib/asciidoctor/core_ext/string/chr.rb +6 -0
  39. data/lib/asciidoctor/core_ext/symbol/length.rb +6 -0
  40. data/lib/asciidoctor/document.rb +590 -304
  41. data/lib/asciidoctor/extensions.rb +1100 -308
  42. data/lib/asciidoctor/helpers.rb +109 -46
  43. data/lib/asciidoctor/inline.rb +16 -9
  44. data/lib/asciidoctor/list.rb +23 -15
  45. data/lib/asciidoctor/opal_ext.rb +4 -0
  46. data/lib/asciidoctor/opal_ext/comparable.rb +38 -0
  47. data/lib/asciidoctor/opal_ext/dir.rb +13 -0
  48. data/lib/asciidoctor/opal_ext/error.rb +2 -0
  49. data/lib/asciidoctor/opal_ext/file.rb +125 -0
  50. data/lib/asciidoctor/{lexer.rb → parser.rb} +646 -455
  51. data/lib/asciidoctor/path_resolver.rb +141 -77
  52. data/lib/asciidoctor/reader.rb +257 -187
  53. data/lib/asciidoctor/section.rb +12 -16
  54. data/lib/asciidoctor/stylesheets.rb +91 -0
  55. data/lib/asciidoctor/substitutors.rb +1548 -0
  56. data/lib/asciidoctor/table.rb +73 -57
  57. data/lib/asciidoctor/timings.rb +39 -0
  58. data/lib/asciidoctor/version.rb +1 -1
  59. data/man/asciidoctor.1 +22 -14
  60. data/man/asciidoctor.adoc +18 -10
  61. data/test/attributes_test.rb +314 -14
  62. data/test/blocks_test.rb +763 -118
  63. data/test/converter_test.rb +352 -0
  64. data/test/document_test.rb +518 -199
  65. data/test/extensions_test.rb +273 -103
  66. data/test/fixtures/asciidoc_index.txt +27 -13
  67. data/test/fixtures/basic-docinfo.xml +1 -1
  68. data/test/fixtures/chapter-a.adoc +3 -0
  69. data/test/fixtures/custom-backends/erb/html5/block_paragraph.html.erb +6 -0
  70. data/test/fixtures/docinfo.xml +1 -1
  71. data/test/fixtures/include-file.asciidoc +2 -0
  72. data/test/fixtures/master.adoc +5 -0
  73. data/test/invoker_test.rb +173 -61
  74. data/test/links_test.rb +97 -21
  75. data/test/lists_test.rb +181 -22
  76. data/test/options_test.rb +86 -2
  77. data/test/paragraphs_test.rb +47 -5
  78. data/test/{lexer_test.rb → parser_test.rb} +128 -57
  79. data/test/paths_test.rb +36 -1
  80. data/test/preamble_test.rb +25 -17
  81. data/test/reader_test.rb +404 -249
  82. data/test/sections_test.rb +623 -58
  83. data/test/substitutions_test.rb +609 -132
  84. data/test/tables_test.rb +198 -24
  85. data/test/test_helper.rb +101 -31
  86. data/test/text_test.rb +88 -31
  87. metadata +160 -64
  88. data/Gemfile +0 -12
  89. data/Guardfile +0 -18
  90. data/asciidoctor.gemspec +0 -143
  91. data/lib/asciidoctor/backends/_stylesheets.rb +0 -466
  92. data/lib/asciidoctor/backends/base_template.rb +0 -114
  93. data/lib/asciidoctor/backends/docbook45.rb +0 -774
  94. data/lib/asciidoctor/backends/docbook5.rb +0 -103
  95. data/lib/asciidoctor/backends/html5.rb +0 -1214
  96. data/lib/asciidoctor/renderer.rb +0 -259
  97. data/lib/asciidoctor/substituters.rb +0 -1083
  98. data/test/fixtures/asciidoc.txt +0 -105
  99. data/test/fixtures/ascshort.txt +0 -32
  100. data/test/fixtures/list_elements.asciidoc +0 -10
  101. data/test/renderer_test.rb +0 -162
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 4823a22cab8ddb3e6109152db26c0f10a0efec3b
4
- data.tar.gz: 697bd0c123fbdf19843dcc6e5f7dceef9a9c5f89
3
+ metadata.gz: 10ca6673e1f88d9011a0defff16ac3beac05131e
4
+ data.tar.gz: bbf18f407eb0f42a23a023d59c02c529f8a7ef70
5
5
  SHA512:
6
- metadata.gz: 06a29332c4eb1754fb86d0facbdefa0fdefd554791d949e2501e8df14f03fc2e4a7fc3685aa69ec5c0105854122970eb79e80a48e3b1d7b8fe586771dbb40ca6
7
- data.tar.gz: 0030da2c1b4632a249d3a2a47f17b1ffd5bbde8107f3fae802f868226a7c9b1419a5ffb31a96296e1b3ce416615cbaa0790a8444aa290a0fecf2385d5b51721f
6
+ metadata.gz: bbfcec179f5c590b233b0e0fbf08a38d16fb6f825ef2e102ad8b8ff00746836e08c75d8d7ead2c85954b46e1494c84637bb6a8099097536c9f147f531ef99a1a
7
+ data.tar.gz: 7e7faf993ab00f9b46923c88cebff59bb876d2c33f91f0fc037dce55b8443bf188cc8f27165ac4fff63a6f8866c73953892a21b71539a97d0120ef282ceb8c55
@@ -1,10 +1,206 @@
1
1
  = Asciidoctor Changelog
2
+ :uri-asciidoctor: https://github.com/asciidoctor/asciidoctor
3
+ :uri-asciidoc: http://asciidoctor.org/docs/what-is-asciidoc
4
+ :star: icon:star[role=red]
5
+ ifndef::icons[]
6
+ :star: ★
7
+ endif::[]
2
8
 
3
- http://asciidoctor.org[Asciidoctor] is an open source text processor and publishing toolchain for converting http://asciidoctor.org[AsciiDoc] markup into HTML, DocBook and custom formats.
9
+ {uri-asciidoctor}[Asciidoctor] is a _fast_, open source text processor and publishing toolchain for converting {uri-asciidoc}[AsciiDoc] content into HTML5, DocBook 5 (or 4.5) and other formats.
4
10
 
5
11
  This document provides a high-level view of the changes introduced in Asciidoctor by release.
6
12
  For a detailed view of what has changed, refer to the https://github.com/asciidoctor/asciidoctor/commits/master[commit history] on GitHub.
7
13
 
14
+ == 1.5.0 (2014-08-12) - @mojavelinux
15
+
16
+ Performance::
17
+
18
+ * 10% increase in speed compared to 0.1.4
19
+ * rewrite built-in converters in Ruby instead of ERB
20
+
21
+ Enhancements::
22
+
23
+ * {star} introduce new curved quote syntax (pass:["`double quotes`"], pass:['`single quotes`']) if compat-mode attribute not set (#1046)
24
+ * {star} add single curved quote replacement for pass:[`'] (#715)
25
+ * {star} use backtick (`) for monospaced text if compat-mode attribute not set (#714, #718)
26
+ * {star} use single and double plus (pass:[+], pass:[++]) for inline passthrough if compat-mode attribute not set (#714, #718)
27
+ * {star} disable single quotes as formatting marks for emphasized text if compat-mode attribute not set (#717)
28
+ * {star} enable compat-mode by default if document has atx-style doctitle
29
+ * {star} output phrase surrounded by # as marked text (i.e., <mark>) (#225)
30
+ * {star} add MathJax integration and corresponding blocks and macros (#492, #760)
31
+ * {star} switch to open source fonts (Open Sans, Noto Serif and Droid Sans Mono) in default stylesheet, major refinements to theme (#879)
32
+ * {star} embed remote images when data-uri and allow-uri-read attributes are set (#612)
33
+ * {star} support leveloffset on include directive and honor relative leveloffset values (#530)
34
+ * {star} switch default docbook backend to docbook5 (@bk2204) (#554)
35
+ * {star} added hide-uri-scheme attribute to hide uri scheme in automatic links (#800)
36
+ * {star} allow substitutions to be incrementally added & removed (#522)
37
+ * {star} add compatibility with Opal, add shim compat library, use compatibility regexp, require libraries properly (@mogztter) (#679, #836, #846)
38
+ * {star} output XHTML when backend is xhtml or xhtml5 (#494)
39
+ * {star} add shorthand subs and specialchars as an alias for specialcharacters (#579)
40
+ * {star} deprecate toc2 attribute in favor of position and placement values on toc attribute (e.g., toc=left) (#706)
41
+ * {star} add source map (file and line number) information to blocks (#861)
42
+ * {star} write to file by default if input is file (#907)
43
+ * {star} add -r and -I flags from ruby command to asciidoctor command for loading additional libraries (#574)
44
+ * support backslash (\) as line continuation character in the value of an attribute entry (#1022)
45
+ * disable subs on pass block by default (#737)
46
+ * add basic support for resolving xref target from reftext (#589)
47
+ * add time range anchor to video element (#886)
48
+ * match implicit URLs that use the file scheme (#853)
49
+ * added sectnumlevels to control depth of section numbering (#549)
50
+ * add hardbreaks option to block (#630)
51
+ * sub attributes in manname (e.g., pass:[{docname}])
52
+ * warn on reference to missing attribute if attribute-missing is "warn"
53
+ * only enable toc macro if toc is enabled and toc-placement attribute has the value macro (#706)
54
+ * add sectnums attribute as alternative alias to numbered attribute (#684)
55
+
56
+ Improvements::
57
+
58
+ * {star} don't select lines that contain a tag directive when including tagged lines, make tag regexp more strict (#1027)
59
+ * {star} use https scheme for assets by default
60
+ * {star} upgrade to Font Awesome 4.1 (@mogztter) (#752)
61
+ * {star} improve print styles, add print styles for book doctype (@leif81) (#997, #952)
62
+ * {star} add proper grid and frame styles for tables (@leif81) (#569)
63
+ * {star} use glyphs for checkboxes when not using font icons (#878)
64
+ * {star} prefer source-language attribute over language attribute for defining default source language (#888)
65
+ * {star} pass document as first argument to process method on Preprocessor
66
+ * don't parse link attributes when linkattrs is set unless text contains equal sign
67
+ * detect bare links, mark with bare class; don't repeat URL of bare link in print styles
68
+ * allow Treeprocessor#process method to replace tree (#1035)
69
+ * add AbstractNode#find_by method to locate nodes in tree (#862)
70
+ * add API for parsing title and subtitle (#1000)
71
+ * add use_fallback option to doctitle, document method
72
+ * constrain subscript & superscript markup (#564, #936)
73
+ * match cell specs when cell separator is customized (#985)
74
+ * use stylesheet to set default table width (#975)
75
+ * display nested elements correctly in toc (@kenfinnigan) (#967)
76
+ * add support for id attribute on links (@mogztter) (#935)
77
+ * add support for title attribute on links (@aslakknutsen)
78
+ * add -t flag to cli to control output of timing information (@mogztter) (#909)
79
+ * rewrite converter API (#778)
80
+ * rewrite extensions to support extension instances for AsciidoctorJ (#804)
81
+ * integrate thread_safe gem (#638)
82
+ * allow inline macro extensions that define a custom regexp to be matched (#792)
83
+ * make Reader#push_include work with default file, path and dir (@bk2204) (#743)
84
+ * honor custom outfilesuffix and introduce relfileprefix (#801)
85
+ * add author and copyright to meta in HTML5 backend (#838)
86
+ * output attribution in front of citetitle for quote and verse blocks
87
+ * recognize float style with shorthand syntax outside block (#818)
88
+ * honor background color in syntax highlighting themes (#813)
89
+ * print runtime environment in version output, support -v as version flag (#785)
90
+ * unwrap preamble if standalone (#533)
91
+ * drop leading & trailing blank lines in verbatim & raw content (#724)
92
+ * remove trailing endlines from source data (#727)
93
+ * add flag to cli to suppress warnings (#557)
94
+ * emit warning if tag(s) not found in include file (#639)
95
+ * use <th> element for vertical table headers instead of header class (@davidgamba) (#738)
96
+ * share select references between AsciiDoc-style cell & main document (#729)
97
+ * number chapters sequentially, always (#685)
98
+ * add vbar attribute, make brvbar resolve properly (#643)
99
+ * add implicit user-home attribute that resolves to user's home directory (#629)
100
+ * enable sidebar toc for small screens (#628)
101
+ * add square brackets around button in HTML output (#631)
102
+ * make language hover text work for all languages in listing block
103
+ * set background color on toc2 to cover scrolling content (@neher)
104
+ * make document parsing a discrete step, make Reader accessible as property on Document
105
+ * allow custom converter to set backend info such as outfilesuffix and htmlsyntax
106
+ * report an informative error message when a converter cannot be resolved (@mogztter)
107
+ * add conum class to b element when icons are disabled, make conum CSS selector more specific
108
+ * expose Document object to extension point IncludeProcessor (@aslakknutsen)
109
+ * style audioblock title, simplify rules for block titles
110
+ * alias :name_attributes to :positional_attributes in extension DSL
111
+ * upgrade to highlight.js 7.4 (and later 8.0) (@mogztter) (#756)
112
+
113
+ Compliance::
114
+
115
+ * only include xmlns in docbook45 backend if xmlns attribute is specified (#929)
116
+ * add xmlns attribute for xhtml output (@bk2204)
117
+ * warn if table without a body is converted to DocBook (#961)
118
+ * wrap <para> around admonition inside example block in DocBook 4.5 (#931)
119
+ * use <informalfigure> if block image doesn't have a title (#927)
120
+ * fix invalid docbook when adding role to formatted text (#956)
121
+ * move all compliance flags to Compliance module (#624)
122
+ * add compliance setting to control use of shorthand property syntax (#789)
123
+ * wrap top-level content inside preamble in DocBook backend when doctype is book (#971)
124
+ * escape special chars in image alt text (#972)
125
+ * set starting number in ordered list for docbook (@megathaum) (#925)
126
+ * match word characters in regular expressions as defined by Unicode (#892)
127
+ * put source language class names on child code element of pre element (#921)
128
+ * ignore case of attribute in conditional directives (#903)
129
+ * allow attribute entry to reset / reseed counter (#870)
130
+ * allow doctype to be set in AsciiDoc table cell (#863)
131
+ * match URL macro following entity (@jmbruel) (#819)
132
+ * handle BOM when normalizing source (#824)
133
+ * don't output revhistory if revdate is not set (#802)
134
+ * perform normal subs on verse content (#799)
135
+ * automatically wrap part intro content in partintro block, emit warning if part is invalid (#768)
136
+ * force encoding of docinfo content to UTF-8 (#773)
137
+ * add scaling & alignment attributes to block image in DocBook backend (#763)
138
+ * add support for pass:[anchor:<id>[<reftext>\]] macro (#531)
139
+ * substitute anchor and xref macros in footnotes (#676)
140
+ * remove all string mutation operations for compatibility with Opal (#735)
141
+ * honor reftext defined in embedded section title anchor (#697)
142
+ * allow spaces in reftext defined in block anchor (#695)
143
+ * use reftext of section or block in text of xref link (#693)
144
+ * number sections in appendix using appendix number (#683)
145
+ * unescape escaped square closing bracket in footnote text (#677)
146
+ * support quoted index terms that may contain commas (#597)
147
+ * don't assign role attribute if quoted text has no roles (#647)
148
+ * disallow quoted values in block and inline anchors
149
+ * add % to scaledwidth if no units given
150
+ * ignore block attribute with unquoted value None
151
+ * preserve entity references with 5 digits
152
+
153
+ Bug Fixes::
154
+
155
+ * resolve relative paths relative to base_dir in unsafe mode (#690)
156
+ * properly handle nested passthroughs (#1034)
157
+ * don't clobber outfilesuffix attribute if locked (#1024)
158
+ * correctly calculate columns if colspan used in first row of table (#924)
159
+ * pass theme to Pygments when pygments-css=style (#919)
160
+ * fallback to text lexer when using pygments for source highlighting (#987)
161
+ * only make special section if style is specified (#917)
162
+ * an unresolved footnote ref should not crash processor (#876)
163
+ * rescue failure to resolve ::Dir.home (#896)
164
+ * recognize Windows UNC path as absolute and preserve it (#806)
165
+ * adjust file glob to account for backslash in Windows paths (#805)
166
+ * don't match e-mail address inside URL (#866)
167
+ * test include directive resolves file with space in name (#798)
168
+ * return nil from Reader#push_include and Reader#pop_include methods (#745)
169
+ * fixed broken passthroughs caused by source highlighting (#720)
170
+ * copy custom stylesheet if linkcss is set (#300)
171
+ * honor list continuations for indented, nested list items (#664)
172
+ * fix syntax errors in converters (@jljouannic)
173
+ * fix iconfont-remote setting
174
+ * fix syntax error (target -> node.target) in Docbook 5 converter (@jf647)
175
+ * output and style HTML for toc macro correctly
176
+
177
+ Infrastructure::
178
+
179
+ * add Ruby 2.1 to list of supported platforms
180
+ * reenable rbx in Travis build
181
+ * switch tests to minitest (@ktdreyer)
182
+ * update RPM for Fedora Rawhide (@ktdreyer)
183
+ * refactor unit tests so they work in RubyMine (@cmoulliard)
184
+ * add preliminary benchmark files to repository (#1021)
185
+ * clean out old fixtures from test suite (#960)
186
+ * add initial Cucumber test infrastructure (#731)
187
+ * use gem tasks from Bundler in Rakefile (#654)
188
+ * build gemspec files using git ls-tree (#653)
189
+ * use in-process web server for URI tests
190
+ * update manpage to reflect updates in 1.5.0
191
+ * rework README (@mogztter) (#651)
192
+
193
+ Distribution Packages::
194
+
195
+ * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
196
+ * https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (rubygem-asciidoctor)]
197
+ * http://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)]
198
+ * http://packages.ubuntu.com/saucy/asciidoctor[Ubuntu (asciidoctor)]
199
+
200
+ https://github.com/asciidoctor/asciidoctor/issues?milestone=8&state=closed[issues resolved] |
201
+ https://github.com/asciidoctor/asciidoctor/releases/tag/v1.5.0[git tag] |
202
+ https://github.com/asciidoctor/asciidoctor/compare/v0.1.4...v1.5.0[full diff]
203
+
8
204
  == 0.1.4 (2013-09-05) - @mojavelinux
9
205
 
10
206
  Performance::
@@ -135,10 +331,8 @@ Distribution Packages::
135
331
  * http://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)]
136
332
  * http://packages.ubuntu.com/saucy/asciidoctor[Ubuntu (asciidoctor)]
137
333
 
138
- https://github.com/asciidoctor/asciidoctor/issues?milestone=7&state=closed[issues resolved]
139
- ::
140
- https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.4[git tag]
141
- ::
334
+ https://github.com/asciidoctor/asciidoctor/issues?milestone=7&state=closed[issues resolved] |
335
+ https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.4[git tag] |
142
336
  https://github.com/asciidoctor/asciidoctor/compare/v0.1.3...v0.1.4[full diff]
143
337
 
144
338
  == 0.1.3 (2013-05-30) - @mojavelinux
@@ -205,12 +399,9 @@ Distribution Packages::
205
399
  * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
206
400
  * https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (rubygem-asciidoctor)]
207
401
 
208
- http://asciidoctor.org/news/2013/05/31/asciidoctor-0-1-3-released[release notes]
209
- ::
210
- https://github.com/asciidoctor/asciidoctor/issues?milestone=4&state=closed[issues resolved]
211
- ::
212
- https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.3[git tag]
213
- ::
402
+ http://asciidoctor.org/news/2013/05/31/asciidoctor-0-1-3-released[release notes] |
403
+ https://github.com/asciidoctor/asciidoctor/issues?milestone=4&state=closed[issues resolved] |
404
+ https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.3[git tag] |
214
405
  https://github.com/asciidoctor/asciidoctor/compare/v0.1.2...v0.1.3[full diff]
215
406
 
216
407
  == 0.1.2 (2013-04-25) - @mojavelinux
@@ -263,12 +454,9 @@ Distribution Packages::
263
454
 
264
455
  * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
265
456
 
266
- http://asciidoctor.org/news/2013/04/25/asciidoctor-0-1-2-released[release notes]
267
- ::
268
- https://github.com/asciidoctor/asciidoctor/issues?milestone=3&state=closed[issues resolved]
269
- ::
270
- https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.2[git tag]
271
- ::
457
+ http://asciidoctor.org/news/2013/04/25/asciidoctor-0-1-2-released[release notes] |
458
+ https://github.com/asciidoctor/asciidoctor/issues?milestone=3&state=closed[issues resolved] |
459
+ https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.2[git tag] |
272
460
  https://github.com/asciidoctor/asciidoctor/compare/v0.1.1...v0.1.2[full diff]
273
461
 
274
462
  == 0.1.1 (2013-02-26) - @erebor
@@ -322,10 +510,8 @@ Distribution Packages::
322
510
 
323
511
  * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
324
512
 
325
- https://github.com/asciidoctor/asciidoctor/issues?milestone=1&state=closed[issues resolved]
326
- ::
327
- https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.1[git tag]
328
- ::
513
+ https://github.com/asciidoctor/asciidoctor/issues?milestone=1&state=closed[issues resolved] |
514
+ https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.1[git tag] |
329
515
  https://github.com/asciidoctor/asciidoctor/compare/v0.1.0...v0.1.1[full diff]
330
516
 
331
517
  == 0.1.0 (2013-02-04) - @erebor
@@ -376,10 +562,8 @@ Distribution Packages::
376
562
 
377
563
  * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
378
564
 
379
- https://github.com/asciidoctor/asciidoctor/issues?milestone=12&state=closed[issues resolved]
380
- ::
381
- https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.0[git tag]
382
- ::
565
+ https://github.com/asciidoctor/asciidoctor/issues?milestone=12&state=closed[issues resolved] |
566
+ https://github.com/asciidoctor/asciidoctor/releases/tag/v0.1.0[git tag] |
383
567
  https://github.com/asciidoctor/asciidoctor/compare/v0.0.9...v0.1.0[full diff]
384
568
 
385
569
  == Older releases (pre-0.0.1)
@@ -1,6 +1,6 @@
1
- The MIT License
2
-
3
- Copyright (C) 2012-2013 Dan Allen and Ryan Waldron
1
+ .The MIT License
2
+ ....
3
+ Copyright (C) 2012-2014 Dan Allen, Ryan Waldron and the Asciidoctor Project
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
21
  THE SOFTWARE.
22
+ ....
@@ -1,515 +1,512 @@
1
1
  = Asciidoctor
2
- Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Ryan Waldron <https://github.com/erebor[@erebor]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>
3
- :awestruct-layout: base
4
- :homepage: http://asciidoctor.org
5
- :asciidoc: http://asciidoc.org
6
- :gem: http://rubygems.org/gems/asciidoctor
7
- :toolchain: http://asciidoctor.org/docs/install-toolchain
8
- :install-mac: http://asciidoctor.org/docs/install-asciidoctor-macosx
9
- :render: http://asciidoctor.org/docs/render-documents
10
- :factory: http://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory
11
- :java: http://asciidoctor.org/docs/install-and-use-asciidoctor-java-integration
12
- :man: http://asciidoctor.org/man/asciidoctor
13
- :sources: https://github.com/asciidoctor/asciidoctor
14
- :tests: https://github.com/asciidoctor/asciidoctor/tree/master/test
15
- :issues: https://github.com/asciidoctor/asciidoctor/issues
16
- :forum: http://discuss.asciidoctor.org
17
- :irc: irc://irc.freenode.org/#asciidoctor
18
- :news: http://asciidoctor.org/news
19
- :docs: http://asciidoctor.org/docs
20
- :org: https://github.com/asciidoctor
21
- :contributors: https://github.com/asciidoctor/asciidoctor/graphs/contributors
22
- :templates: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/backends
23
- :gitscm-next: https://github.com/github/gitscm-next
24
- :seed-contribution: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
25
- :tilt: https://github.com/rtomayko/tilt
26
- :freesoftware: http://www.gnu.org/philosophy/free-sw.html
27
- :gist: https://gist.github.com
28
- :fork: https://help.github.com/articles/fork-a-repo
29
- :branch: http://learn.github.com/p/branching.html
30
- :pr: https://help.github.com/articles/using-pull-requests
31
- :changelog: https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc
32
- :license: https://github.com/asciidoctor/asciidoctor/blob/master/LICENSE
2
+ Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Ryan Waldron <https://github.com/erebor[@erebor]>
3
+ // settings:
4
+ :page-layout: base
33
5
  :idprefix:
6
+ ifdef::env-github[:idprefix: user-content-]
34
7
  :idseparator: -
35
- ifndef::safe-mode-name[]
36
-
37
- [float]
38
- = Asciidoctor
8
+ :source-language: ruby
9
+ :language: {source-language}
10
+ // URIs:
11
+ :uri-org: https://github.com/asciidoctor
12
+ :uri-repo: {uri-org}/asciidoctor
13
+ :uri-asciidoctorj: {uri-org}/asciidoctorj
14
+ :uri-asciidoctorjs: {uri-org}/asciidoctor.js
15
+ :uri-project: http://asciidoctor.org
16
+ :uri-docs: {uri-project}/docs
17
+ :uri-news: {uri-project}/news
18
+ :uri-manpage: {uri-project}/man/asciidoctor
19
+ :uri-issues: {uri-repo}/issues
20
+ :uri-contributors: {uri-repo}/graphs/contributors
21
+ :uri-rel-file-base: link:
22
+ :uri-rel-tree-base: link:
23
+ ifdef::awestruct-version[]
24
+ :uri-rel-file-base: {uri-repo}/blob/master/
25
+ :uri-rel-tree-base: {uri-repo}/tree/master/
39
26
  endif::[]
27
+ :uri-changelog: {uri-rel-file-base}CHANGELOG.adoc
28
+ :uri-contribute: {uri-rel-file-base}CONTRIBUTING.adoc
29
+ :uri-license: {uri-rel-file-base}LICENSE.adoc
30
+ :uri-tests: {uri-rel-tree-base}test
31
+ :uri-discuss: http://discuss.asciidoctor.org
32
+ :uri-irc: irc://irc.freenode.org/#asciidoctor
33
+ :uri-rubygem: http://rubygems.org/gems/asciidoctor
34
+ :uri-what-is-asciidoc: {uri-docs}/what-is-asciidoc
35
+ :uri-user-manual: {uri-docs}/user-manual
36
+ :uri-install-doc: {uri-docs}/install-toolchain
37
+ :uri-install-osx-doc: {uri-docs}/install-asciidoctor-macosx
38
+ :uri-render-doc: {uri-docs}/render-documents
39
+ :uri-themes-doc: {uri-docs}/produce-custom-themes-using-asciidoctor-stylesheet-factory
40
+ :uri-gitscm-repo: https://github.com/git/git-scm.com
41
+ :uri-prototype: {uri-gitscm-repo}/commits/master/lib/asciidoc.rb
42
+ :uri-freesoftware: https://www.gnu.org/philosophy/free-sw.html
43
+ :uri-foundation: http://foundation.zurb.com
44
+ :uri-tilt: https://github.com/rtomayko/tilt
45
+ :uri-ruby: https://ruby-lang.org
46
+ // images:
47
+ :screenshot-img: screenshot.png
48
+
49
+ {uri-project}[Asciidoctor] is a _fast_ text processor and publishing toolchain for converting {uri-what-is-asciidoc}[AsciiDoc] content to HTML5, DocBook 5 (or 4.5) and other formats.
50
+ Asciidoctor is written in {uri-ruby}[Ruby], packaged as a RubyGem and published to {uri-rubygem}[RubyGems.org].
51
+ The gem is also included in several Linux distributions, including Fedora, Debian and Ubuntu.
52
+ Asciidoctor is open source, {uri-repo}[hosted on GitHub] and released under the MIT license.
40
53
 
41
- {homepage}[Asciidoctor] is an open source text processor and publishing toolchain for transforming {asciidoc}[AsciiDoc] markup into HTML 5, DocBook 4.5 and 5.0 and other custom formats.
42
- Asciidoctor is written entirely in Ruby, packaged as a RubyGem and published to {gem}[RubyGems.org].
43
- There are also Fedora, Debian and Ubuntu packages available for installing Asciidoctor.
44
- Asciidoctor is released under the MIT license.
45
-
46
- ifndef::awestruct[]
47
- *Project health:* image:https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
48
- endif::awestruct[]
54
+ [TIP]
55
+ ====
56
+ You can run Asciidoctor on the JVM using JRuby.
57
+ To invoke the Asciidoctor API directly from Java and other JVM languages, use {uri-asciidoctorj}[AsciidoctorJ].
58
+ There are plugins available, based on AsciidoctorJ, that integrate the Asciidoctor processor into Apache Maven, Grade or Javadoc builds.
49
59
 
50
- == AsciiDoc Processing
60
+ Asciidoctor also runs in JavaScript.
61
+ We use http://opalrb.org[Opal] to transcompile the Ruby source to JavaScript to produce {uri-asciidoctorjs}[Asciidoctor.js], a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js.
62
+ Asciidoctor.js is used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.
63
+ ====
51
64
 
52
- Asciidoctor reads and parses AsciiDoc markup (from a file or string) and feeds the parsed result to a set of built-in templates to render the document as HTML 5, DocBook 4.5 or DocBook 5.0.
53
- Asciidoctor is a drop-in replacement for the original AsciiDoc processor.
54
- We've matched the output to that produced by the AsciiDoc Python processor as faithfully as possible.
55
- You can override the built-in templates, or produce a custom format, by pointing the processor at a set of template files written in a language supported by {tilt}[Tilt].
56
- See the <<usage>> section for more details.
65
+ ifdef::env-github[]
66
+ *Project health:* image:https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
67
+ endif::env-github[]
57
68
 
58
- NOTE: With few exceptions, Asciidoctor is compliant with the original AsciiDoc processor.
59
- Asciidoctor has well over 1,000 tests to ensure compatibility with the AsciiDoc syntax.
60
- We continue to work hard to ensure Asciidoctor continues to serve as a drop-in replacement for AsciiDoc.
69
+ == The Big Picture
61
70
 
62
- == Operating Systems
71
+ Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel.
72
+ Asciidoctor adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant out-of-the-box experience.
63
73
 
64
- Asciidoctor works on Linux, Mac and Windows.
74
+ image::{screenshot-img}[Preview of AsciiDoc source and corresponding rendered HTML]
65
75
 
66
- == Dependency and Configuration Requirements
76
+ == AsciiDoc Processing
67
77
 
68
- Asciidoctor requires one of the following implementations of Ruby:
78
+ Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree into a set of built-in templates to produce HTML5, DocBook 5 (or 4.5).
79
+ You have the option of writing your own converter or providing {uri-tilt}[Tilt]-supported templates to customize the generated output or produce alternative formats.
69
80
 
70
- * Ruby 1.8.7
71
- * Ruby 1.9.3
72
- * Ruby 2.0.0
73
- * JRuby 1.7.4
74
- * Rubinius 2.0 - _testing suspended until a release is available_
81
+ NOTE: Asciidoctor is a drop-in replacement for the original AsciiDoc Python processor (`asciidoc.py`).
82
+ The Asciidoctor test suite has {uri-tests}[> 1,500 tests] to ensure compatibility with the AsciiDoc syntax.
75
83
 
76
- We expect Asciidoctor to work with other versions of Ruby as well.
77
- We welcome your help testing those versions if you are interested in seeing them supported.
84
+ In addition to the standard AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., [x-]`icon:fire[]`) and UI elements (e.g., [x-]`button:[Save]`).
85
+ Asciidoctor also offers a modern, responsive theme based on {uri-foundation}[Foundation] to style the HTML5 output.
78
86
 
79
- // QUESTION What is considered configuration information?
87
+ == Requirements
80
88
 
81
- // QUESTION What about other sub-projects of Asciidoctor that require Tilt?
89
+ Asciidoctor works on Linux, OSX (Mac) and Windows and requires one of the following implementations of {uri-ruby}[Ruby]:
82
90
 
83
- // TODO fill in this section and enable
84
- //== List of files/directory structure
85
- //
86
- //Optional depending on the complexity of the project
91
+ * MRI (Ruby 1.8.7, 1.9.3, 2.0.0 & 2.1.2)
92
+ * JRuby 1.7 (Ruby 1.8 and 1.9 modes)
93
+ * Rubinius 2.2.x
94
+ * Opal (JavaScript)
87
95
 
88
- The latest source code is located in the {sources}[Asciidoctor git repository] on GitHub.
96
+ We welcome your help testing Asciidoctor on these and other platforms.
97
+ Refer to <<{idprefix}contributing,Contributing>> to learn how to get involved.
89
98
 
90
99
  == Installation
91
100
 
92
- Asciidoctor can be installed via the +gem+ command, bundler, or popular Linux package managers.
101
+ Asciidoctor can be installed using (a) the `gem install` command, (b) Bundler or (c) package managers for popular Linux distributions.
102
+
103
+ TIP: The benefit of using a Linux package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.
104
+ The drawback is that the package may not be available immediately after the release of the gem.
105
+ If you need the latest version, you can always fallback to using the `gem` command.
93
106
 
94
- === gem install
107
+ === (a) gem install
95
108
 
96
- To install Asciidoctor using the +gem+ command:
109
+ Open a terminal and type: (without the leading `$`)
97
110
 
98
- . Open a terminal
99
- . Type the +gem+ command
111
+ $ gem install asciidoctor
100
112
 
101
- $> gem install asciidoctor
113
+ If you want to install a pre-release version (e.g., a release candidate), use:
102
114
 
103
- === bundle install (Bundler)
115
+ $ gem install asciidoctor --pre
104
116
 
105
- To install Asciidoctor using bundler:
117
+ .Upgrading your installation
118
+ [TIP]
119
+ ====
120
+ If you have an earlier version of Asciidoctor installed, you can update it using:
106
121
 
107
- . Open your system Gemfile
108
- . Add the +asciidoctor+ gem to your Gemfile using the following text
122
+ $ gem upgrade asciidoctor
109
123
 
110
- source 'https://rubygems.org'
111
- gem 'asciidoctor'
124
+ If you install a new version of the gem using `gem install` instead of gem update, you'll have multiple versions installed.
125
+ If that's the case, use the following gem command to remove the old versions:
112
126
 
113
- . Save the Gemfile
114
- . Open a terminal
115
- . Install the gem with bundler
127
+ $ gem cleanup asciidoctor
128
+ ====
116
129
 
117
- $> bundle install
130
+ === (b) Bundler
118
131
 
119
- === yum install (Fedora)
120
-
121
- To install Asciidoctor on Fedora 17 or greater:
132
+ . Create a Gemfile in the root folder of your project (or the current directory)
133
+ . Add the `asciidoctor` gem to your Gemfile as follows:
134
+ +
135
+ [source]
136
+ ----
137
+ source 'https://rubygems.org'
138
+ gem 'asciidoctor'
139
+ # or specify the version explicitly
140
+ # gem 'asciidoctor', '1.5.0'
141
+ ----
122
142
 
123
- . Open a terminal
124
- . Type the +yum+ command
125
-
126
- $> sudo yum install rubygem-asciidoctor
143
+ . Save the Gemfile
144
+ . Open a terminal and install the gem using:
127
145
 
128
- The benefit of installing the gem via +yum+ is that the package manager will also install Ruby and RubyGems if not already on your machine.
146
+ $ bundle
129
147
 
130
- === apt-get install (Debian, Ubuntu)
131
-
132
- To install Asciidoctor on Debian Sid or Ubuntu Saucy or greater:
148
+ To upgrade the gem, specify the new version in the Gemfile and run `bundle` again.
149
+ Using `bundle update` is not recommended as it will also update other gems, which may not be the desired result.
133
150
 
134
- . Open a terminal
135
- . Type the +apt-get+ command
136
-
137
- $> sudo apt-get install asciidoctor
151
+ === (c) Linux package managers
138
152
 
139
- The benefit of installing the gem via +apt-get+ is that the package manager will also install Ruby and RubyGems if not already on your machine.
153
+ ==== Yum (Fedora 18 or greater)
140
154
 
141
- === Other installation options
155
+ To install the gem on Fedora 18 or greater using yum, open a terminal and type:
142
156
 
143
- * {toolchain}[Installing the Asciidoctor toolchain]
144
- * {install-mac}[Installing Asciidoctor on Mac OS X]
157
+ $ sudo yum install -y rubygem-asciidoctor
145
158
 
146
- == Upgrading
159
+ To upgrade the gem, use:
147
160
 
148
- If you have an earlier version of Asciidoctor installed, you can update it using the +gem+ command:
161
+ $ sudo yum update -y rubygem-asciidoctor
149
162
 
150
- $> gem update asciidoctor
163
+ TIP: Your Fedora system may be configured to automatically update packages, in which case no action is required by you to update the gem.
151
164
 
152
- [TIP]
153
- ====
154
- If you accidentally use +gem install+ instead of +gem update+ then you will have both versions installed.
155
- If you wish to remove the older version use the +gem+ command:
165
+ ==== apt-get (Debian Sid, Ubuntu Saucy or greater)
156
166
 
157
- $> gem cleanup asciidoctor
158
- ====
167
+ To install the gem on Debian or Ubuntu, open a terminal and type:
159
168
 
160
- On Fedora, you can update it using:
169
+ $ sudo apt-get install -y asciidoctor
161
170
 
162
- $> sudo yum update rubygem-asciidoctor
171
+ To upgrade the gem, use:
163
172
 
164
- TIP: Your Fedora system may be configured to automatically update packages, in which case no further action is required by you.
165
- Refer to the http://docs.fedoraproject.org[Fedora docs] if you are unsure.
173
+ $ sudo apt-get upgrade -y asciidoctor
166
174
 
167
- On Debian or Ubuntu, you can update it using:
175
+ TIP: Your Debian or Ubuntu system may be configured to automatically update packages, in which case no action is required by you to update the gem.
168
176
 
169
- $> sudo apt-get upgrade asciidoctor
177
+ === Other installation options
170
178
 
171
- NOTE: The Fedora, Debian and Ubuntu packages will not be available right away after a release of the RubyGem.
172
- It may take several weeks before the packages become available for a new release.
173
- If you need the latest version immediately, use the +gem install+ option.
179
+ * {uri-install-doc}[Installing the Asciidoctor toolchain]
180
+ * {uri-install-osx-doc}[Installing Asciidoctor on Mac OS X]
174
181
 
175
182
  == Usage
176
183
 
177
- If the Asciidoctor gem installed successfully, the +asciidoctor+ command line interface (CLI) will be available on your PATH.
178
- To invoke it, execute:
184
+ If the Asciidoctor gem installed successfully, the `asciidoctor` command line interface (CLI) will be available on your PATH.
185
+ To verify it's available, run the following in your terminal:
186
+
187
+ $ asciidoctor --version
179
188
 
180
- $> asciidoctor --version
181
- Asciidoctor 0.1.4 [http://asciidoctor.org]
189
+ You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.
182
190
 
183
- In addition to the CLI, Asciidoctor provides a Ruby API
184
- The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.
191
+ [.output]
192
+ ....
193
+ Asciidoctor 1.5.0 [http://asciidoctor.org]
194
+ Runtime Environment (ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux])
195
+ ....
185
196
 
186
- TIP: Asciidoctor also has a Java API that mirrors the Ruby API.
187
- The Java API calls through to the Ruby API using an embedded JRuby runtime.
188
- See the {java}[Asciidoctor Java integration project] for more information.
197
+ Asciidoctor also provides an API.
198
+ The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via {uri-asciidoctorj}[AsciidoctorJ]) and JavaScript (via {uri-asciidoctorjs}[Asciidoctor.js]).
189
199
 
190
200
  === Command line interface (CLI)
191
201
 
192
- Asciidoctor's CLI is a drop-in replacement for the +asciidoc.py+ command from the Python implementation.
193
- To invoke Asciidoctor from the CLI, execute:
202
+ The `asciidoctor` command allows you to invoke Asciidoctor from the command line (i.e., a terminal).
194
203
 
195
- asciidoctor <asciidoc_file>
204
+ The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory.
205
+ The name of the generated HTML file is derived from the source file by changing its file extension to `.html`.
196
206
 
197
- This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the +.html+ extension.
207
+ $ asciidoctor README.adoc
198
208
 
199
- There are many other options available and full help is provided via:
209
+ You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:
200
210
 
201
- asciidoctor --help
211
+ $ asciidoctor --help
202
212
 
203
- or in the {man}[man page].
213
+ For instance, to write the file to a different directory, use:
204
214
 
205
- There is also an +asciidoctor-safe+ command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file.
206
- This mode is very similar to the safe mode of +asciidoc.py+.
215
+ $ asciidoctor -D output README.adoc
207
216
 
208
- Additional documentation:
217
+ The `asciidoctor` {uri-manpage}[man page] provides a complete reference of the command line interface.
209
218
 
210
- * {render}[How do I render a document?]
211
- * {factory}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
219
+ Refer to the following resources to learn more about how to use the `asciidoctor` command.
220
+
221
+ * {uri-render-doc}[How do I convert a document?]
222
+ * {uri-themes-doc}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
212
223
 
213
224
  === Ruby API
214
225
 
215
226
  To use Asciidoctor in your application, you first need to require the gem:
216
227
 
217
- require 'asciidoctor'
218
-
219
- With that in place, you can start processing AsciiDoc documents.
220
-
221
- .Loading a document
222
- To parse a file into an +Asciidoctor::Document+ object:
228
+ [source]
229
+ require 'asciidoctor'
223
230
 
224
- doc = Asciidoctor.load_file 'sample.adoc'
231
+ You can then convert an AsciiDoc source file to an HTML file using:
225
232
 
226
- You can get information about the document:
233
+ [source]
234
+ Asciidoctor.convert_file 'README.adoc', to_file: true, safe: 'safe'
227
235
 
228
- puts doc.doctitle
229
- puts doc.attributes
236
+ WARNING: When using Asciidoctor via the API, the default safe mode is `:secure`.
237
+ In secure mode, several core features are disabled, including the `include` directive.
238
+ If you want to enable these features, you'll need to explicitly set the safe mode to `server` (recommended) or `safe`.
230
239
 
231
- More than likely, you will want to render the document.
240
+ You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:
232
241
 
233
- .Rendering files
234
- --
235
- To render a file containing AsciiDoc markup to HTML 5, use:
242
+ [source]
243
+ ----
244
+ content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
245
+ Asciidoctor.convert content, safe: 'safe'
246
+ ----
236
247
 
237
- Asciidoctor.render_file 'sample.adoc', :in_place => true
248
+ If you want the full HTML document, enable the `header_footer` option as follows:
238
249
 
239
- The command will output to the file +sample.html+ in the same directory.
250
+ [source]
251
+ ----
252
+ content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
253
+ html = Asciidoctor.convert content, header_footer: true, safe: 'safe'
254
+ ----
240
255
 
241
- You can render the file to DocBook 4.5 by setting the +:backend+ option to +'docbook'+:
256
+ If you need access to the parsed document, you can split the conversion into discrete steps:
242
257
 
243
- Asciidoctor.render_file 'sample.adoc', :in_place => true, :backend => 'docbook'
258
+ [source]
259
+ ----
260
+ content = '_Zen_ in the art of writing http://asciidoctor.org[AsciiDoc].'
261
+ document = Asciidoctor.load content, header_footer: true, safe: 'safe'
262
+ puts document.doctitle
263
+ html = document.convert
264
+ ----
244
265
 
245
- The command will output to the file +sample.xml+ in the same directory.
246
- (If you're on Linux, you can view the file using yelp).
247
- --
266
+ Keep in mind, if you don't like the output Asciidoctor produces, _you can change it!_
267
+ Asciidoctor supports custom {uri-tilt}[Tilt]-supported templates, which to allow you customize the output piecemeal, or custom converters, which give you 100% control over the output.
248
268
 
249
- .Rendering strings
250
- --
251
- To render an AsciiDoc-formatted string:
269
+ For more information about how to use the API or to customize the output, see the {uri-user-manual}[user manual].
252
270
 
253
- puts Asciidoctor.render '*This* is Asciidoctor.'
254
-
255
- When rendering a string, the header and footer are excluded by default to make Asciidoctor consistent with other lightweight markup engines like Markdown.
256
- If you want the header and footer, just enable it using the +:header_footer+ option:
271
+ == Contributing
257
272
 
258
- puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true
273
+ In the spirit of {uri-freesoftware}[free software], _everyone_ is encouraged to help improve this project.
274
+ If you discover errors or omissions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix.
275
+ New contributors are always welcome!
259
276
 
260
- Now you'll get a full HTML 5 file.
261
- If you only want the inline markup to be processed, set the +:doctype+ option to +'inline'+:
277
+ Here are some ways *you* can contribute:
262
278
 
263
- puts Asciidoctor.render '*This* is Asciidoctor.', :doctype => 'inline'
279
+ * by using prerelease (alpha, beta or preview) versions
280
+ * by reporting bugs
281
+ * by suggesting new features
282
+ * by writing or editing documentation
283
+ * by writing specifications
284
+ * by writing code -- _No patch is too small._
285
+ ** fix typos
286
+ ** add comments
287
+ ** clean up inconsistent whitespace
288
+ ** write tests!
289
+ * by refactoring code
290
+ * by fixing {uri-issues}[issues]
291
+ * by reviewing patches
264
292
 
265
- As before, you can also produce DocBook 4.5:
293
+ The {uri-contribute}[Contributing] guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.
266
294
 
267
- puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true,
268
- :backend => 'docbook'
295
+ == Getting Help
269
296
 
270
- If you don't like the output you see, you can change it.
271
- Any of it!
272
- --
297
+ The Asciidoctor project is developed to help you easily write and publish your content.
298
+ But we can't do that without your feedback!
299
+ We encourage you to ask questions and discuss any aspects of the project on the discussion list, Twitter or IRC.
273
300
 
274
- .Custom templates
275
- --
276
- Asciidoctor allows you to override the {templates}[built-in templates] used to render almost any individual AsciiDoc element.
277
- If you provide a directory of {tilt}[Tilt]-compatible templates, named in such a way that Asciidoctor can figure out which template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any elements for which it finds a matching template.
278
- It will fallback to its default templates for everything else.
301
+ Mailing list:: {uri-discuss}
302
+ Twitter (Chat):: #asciidoctor hashtag
303
+ IRC (Chat):: {uri-irc}[#asciidoctor] on FreeNode IRC
279
304
 
280
- puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true,
281
- :template_dir => 'templates'
305
+ Further information and documentation about Asciidoctor can be found on the project's website.
282
306
 
283
- The Document and Section templates should begin with +document.+ and +section.+, respectively.
284
- The file extension is used by Tilt to determine which view framework it will use to use to render the template.
285
- For instance, if you want to write the template in ERB, you'd name these two templates +document.html.erb+ and +section.html.erb+.
286
- To use Haml, you'd name them +document.html.haml+ and +section.html.haml+.
307
+ Home:: {uri-project}
308
+ News:: {uri-news}
309
+ Docs:: {uri-docs}
287
310
 
288
- Templates for block elements, like a Paragraph or Sidebar, would begin with +block_<style>.+.
289
- For instance, to override the default Paragraph template with an ERB template, put a file named +block_paragraph.html.erb+ in the template directory you pass to the +Document+ constructor using the +:template_dir+ option.
311
+ The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.
290
312
 
291
- For more usage examples, see the (massive) {tests}[test suite].
292
- --
313
+ Source repository (git):: {uri-repo}
314
+ Issue tracker:: {uri-issues}
315
+ Asciidoctor organization on GitHub:: {uri-org}
293
316
 
294
317
  == Copyright and Licensing
295
318
 
296
- Copyright (C) 2012-2013 Dan Allen and Ryan Waldron.
319
+ Copyright (C) 2012-2014 Dan Allen, Ryan Waldron and the Asciidoctor Project.
297
320
  Free use of this software is granted under the terms of the MIT License.
298
321
 
299
- See the {license}[LICENSE] file for details.
322
+ See the {uri-license}[LICENSE] file for details.
300
323
 
301
324
  == Authors
302
325
 
303
- *Asciidoctor* was written by https://github.com/mojavelinux[Dan Allen], https://github.com/erebor[Ryan Waldron], https://github.com/lightguard[Jason Porter], https://github.com/nickh[Nick Hengeveld] and {contributors}[other contributors].
326
+ *Asciidoctor* is lead by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] and has received contributions from {uri-contributors}[many other individuals] in Asciidoctor's awesome community.
327
+ The project was initiated in 2012 by https://github.com/erebor[Ryan Waldron] and based on {uri-prototype}[a prototype] written by https://github.com/nickh[Nick Hengeveld].
304
328
 
305
- The initial code from which Asciidoctor emerged was written by http://github.com/nickh[Nick Hengeveld] to process the git man pages for the {gitscm-next}[Git project site].
306
- Refer to the commit history of {seed-contribution}[asciidoc.rb] to view the initial contributions.
307
-
308
- *AsciiDoc* was written by Stuart Rackham and has received contributions from many other individuals.
309
-
310
- // TODO fill in this section and enable
311
- //== Thanks, acknowledgements, and credits
312
-
313
- == Contact and Help
314
-
315
- The Asciidoctor project is developed to help you sucessfully write and publish your content.
316
- But we can't do that without your feedback!
317
- We encourage you to ask questions and discuss any aspects of the project on the mailing list or IRC.
318
-
319
- Mailing list:: {forum}
320
- Chat:: {irc}[#asciidoctor] on FreeNode IRC
321
-
322
- Further information and documentation about Asciidoctor can be found on the project's website.
323
-
324
- Home:: {homepage}
325
- News:: {news}
326
- Docs:: {docs}
327
-
328
- The Asciidoctor organization on GitHub hosts the project's source code, issue tracker, and sub-projects.
329
-
330
- Source repository (git):: {sources}
331
- Issue tracker (GitHub):: {issues}
332
- Asciidoctor organization (GitHub):: {org}
333
-
334
- If you discover errors or ommisions in the source code, documentation, or website content, please don't hesitate to submit an issue or open a pull request with a fix.
335
- The <<contributing>> section provides information on how to create, style, and submit issues, feature requests, code, and documentation to the Asciidoctor Project.
336
- New contributors are always welcome!
329
+ *AsciiDoc* was started by Stuart Rackham and has received contributions from many other individuals in the AsciiDoc community.
337
330
 
338
331
  == Changelog
339
332
 
340
- === v0.1.4 (2013-09-05) - @mojavelinux
333
+ === 1.5.0 (2014-08-12) - @mojavelinux
341
334
 
342
335
  Performance::
343
336
 
344
- * 15% increase in speed compared to 0.1.3
337
+ * 10% increase in speed compared to 0.1.4
338
+ * rewrite built-in converters in Ruby instead of ERB
345
339
 
346
340
  Enhancements::
347
341
 
348
- * updated xref inline macro to support inter-document references (#417)
349
- * added extension API for document processing (#79)
350
- * added include directive processor extension (#100)
351
- * added id and role shorthand for formatted (quoted) text (#517)
352
- * added shorthand syntax for specifying block options (#481)
353
- * added support for checklists in unordered list (#200)
354
- * added support for inline style for unordered lists (#620)
355
- * added DocBook 5 backend (#411)
356
- * added docinfo option for footer (#486)
357
- * added Pygments as source highlighter option (pygments) (#538)
358
- * added icon inline macro (#529)
359
- * recognize implicit table header row (#387)
360
- * uri can be used in inline image (#470)
361
- * add float attribute to inline image (#616)
362
- * allow role to be specified on text enclosed in backticks (#419)
363
- * added XML comment-style callouts for use in XML listings (#582)
364
- * made callout bullets non-selectable in HTML output (#478)
365
- * pre-wrap literal blocks, added nowrap option to listing blocks (#303)
366
- * skip (retain) missing attribute references by default (#523)
367
- * added attribute-missing attribute to control how a missing attribute is handled (#495)
368
- * added attribute-undefined attribute to control how an undefined attribute is handled (#495)
369
- * permit !name syntax for undefining attribute (#498)
370
- * ignore front matter used by static site generators if skip-front-matter attribute is set (#502)
371
- * sanitize contents of HTML title element in html5 backend (#504)
372
- * support toc position for toc2 (#467)
373
- * cli accepts multiple files as input (@lordofthejars) (#227)
374
- * added Markdown-style horizontal rules and pass Markdown tests (#455)
375
- * added float clearing classes (.clearfix, .float-group) (#602)
376
- * don't disable syntax highlighting when explicit subs is used on listing block
377
- * asciidoctor package now available in Debian Sid and Ubuntu Saucy (@avtobiff) (#216)
378
-
379
- Compliance::
380
-
381
- * embed CSS by default, copy stylesheet when linkcss is set unless copycss! is set (#428)
382
- * refactor reader to track include stack (#572)
383
- * made include directive resolve relative to current file (#572)
384
- * track include stack to enforce maximum depth (#581)
385
- * fixed greedy comment blocks and paragraphs (#546)
386
- * enable toc and numbered by default in DocBook backend (#540)
387
- * ignore comment lines when matching labeled list item (#524)
388
- * correctly parse footnotes that contain a URL (#506)
389
- * parse manpage metadata, output manpage-specific HTML, set docname and outfilesuffix (#488, #489)
390
- * recognize preprocessor directives on first line of AsciiDoc table cell (#453)
391
- * include directive can retrieve data from uri if allow-uri-read attribute is set (#445)
392
- * support escaping attribute list that precedes formatted (quoted) text (#421)
393
- * made improvements to list processing (#472, #469, #364)
394
- * support percentage for column widths (#465)
395
- * substitute attributes in docinfo files (#403)
396
- * numbering no longer increments on unnumbered sections (#393)
397
- * fixed false detection of list item with hyphen marker
398
- * skip include directives when processing comment blocks
399
- * added xmlns to root element in docbook45 backend, set noxmlns attribute to disable
400
- * added a Compliance module to control compliance-related behavior
401
- * added linkattrs feature to AsciiDoc compatibility file (#441)
402
- * added level-5 heading to AsciiDoc compatibility file (#388)
403
- * added new XML-based callouts to AsciiDoc compatibility file
404
- * added absolute and uri image target matching to AsciiDoc compatibility file
405
- * added float attribute on inline image macro to AsciiDoc compatibility file
406
- * removed linkcss in AsciiDoc compatibility file
407
- * fixed fenced code entry in compatibility file
408
-
409
- Bug Fixes::
410
-
411
- * lowercase attribute names passed to API (#508)
412
- * numbered can still be toggled even when enabled in API (#393)
413
- * allow JRuby Map as attributes (#396)
414
- * don't attempt to highlight callouts when using CodeRay and Pygments (#534)
415
- * correctly calculate line length in Ruby 1.8 (#167)
416
- * write to specified outfile even when input is stdin (#500)
417
- * only split quote attribution on first comma in Markdown blockquotes (#389)
418
- * don't attempt to print render times when doc is not rendered
419
- * don't recognize line with four backticks as a fenced code block (#611)
342
+ * introduce new curved quote syntax (pass:["`double quotes`"], pass:['`single quotes`']) if compat-mode attribute not set (#1046)
343
+ * add single curved quote replacement for pass:[`'] (#715)
344
+ * use backtick (pass:[`]) for monospaced text if compat-mode attribute not set (#714, #718)
345
+ * use single and double plus (pass:[+], pass:[++]) for inline passthrough if compat-mode attribute not set (#714, #718)
346
+ * disable single quotes as formatting marks for emphasized text if compat-mode attribute not set (#717)
347
+ * enable compat-mode by default if document has atx-style doctitle
348
+ * output phrase surrounded by # as marked text (i.e., <mark>) (#225)
349
+ * add MathJax integration and corresponding blocks and macros (#492, #760)
350
+ * switch to open source fonts (Open Sans, Noto Serif and Droid Sans Mono) in default stylesheet, major refinements to theme (#879)
351
+ * embed remote images when data-uri and allow-uri-read attributes are set (#612)
352
+ * support leveloffset on include directive and honor relative leveloffset values (#530)
353
+ * switch default docbook backend to docbook5 (@bk2204) (#554)
354
+ * added hide-uri-scheme attribute to hide uri scheme in automatic links (#800)
355
+ * allow substitutions to be incrementally added & removed (#522)
356
+ * add compatibility with Opal, add shim compat library, use compatibility regexp, require libraries properly (@mogztter) (#679, #836, #846)
357
+ * output XHTML when backend is xhtml or xhtml5 (#494)
358
+ * add shorthand subs and specialchars as an alias for specialcharacters (#579)
359
+ * deprecate toc2 attribute in favor of position and placement values on toc attribute (e.g., toc=left) (#706)
360
+ * add source map (file and line number) information to blocks (#861)
361
+ * write to file by default if input is file (#907)
362
+ * add -r and -I flags from ruby command to asciidoctor command for loading additional libraries (#574)
363
+ * support backslash (\) as line continuation character in the value of an attribute entry (#1022)
364
+ * disable subs on pass block by default (#737)
365
+ * add basic support for resolving xref target from reftext (#589)
366
+ * add time range anchor to video element (#886)
367
+ * match implicit URLs that use the file scheme (#853)
368
+ * added sectnumlevels to control depth of section numbering (#549)
369
+ * add hardbreaks option to block (#630)
370
+ * sub attributes in manname (e.g., pass:[{docname}])
371
+ * warn on reference to missing attribute if attribute-missing is "warn"
372
+ * only enable toc macro if toc is enabled and toc-placement attribute has the value macro (#706)
373
+ * add sectnums attribute as alternative alias to numbered attribute (#684)
420
374
 
421
375
  Improvements::
422
376
 
423
- * upgraded Font Awesome to 3.2.1 (#451)
424
- * improved the built-in CodeRay theme to match Asciidoctor styles
425
- * link to CodeRay stylesheet if linkcss is set (#381)
426
- * style the video block (title & margin) (#590)
427
- * added Groovy, Clojure, Python and YAML to floating language hint
428
- * only process callouts for blocks in which callouts are found
429
- * added content_model to AbstractBlock, rename buffer to lines
430
- * use Untitled as document title in rendered output if document has no title
431
- * rename include-depth attribute to max-include-depth, set 64 as default value (#591)
432
- * the tag attribute can be used on the include directive to identify a single tagged region
433
- * output multiple authors in HTML backend (#399)
434
- * allow multiple template directories to be specified, document in usage and manpage (#437)
435
- * added option to cli to specify template engine (#406)
436
- * added support for external video hosting services in video block macro (@xcoulon) (#587)
437
- * strip leading separator(s) on section id if idprefix is blank (#551)
438
- * customized styling of toc placed inside body content (#507)
439
- * consolidate toc attribute so toc with or without toc-position can make sidebar toc (#618)
440
- * properly style floating images (inline & block) (#460)
441
- * add float attribute to inline images (#616)
442
- * use ul list for TOC in HTML5 backend (#431)
443
- * support multiple terms per labeled list item in model (#532)
444
- * added role?, has_role?, option? and roles methods to AbstractNode (#423, 474)
445
- * added captioned_title method to AbstractBlock
446
- * honor showtitle attribute as alternate to notitle! (#457)
447
- * strip leading indent from literal paragraph blocks assigned the style normal
448
- * only process lines in AsciiDoc files
449
- * emit message that tilt gem is required to use custom backends if missing (#433)
450
- * use attributes for version and last updated messages in footer (#596)
451
- * added a basic template cache (#438)
452
- * include line info in several of the warnings (for lists and tables)
453
- * print warning/error messages using warn (#556)
454
- * lines are not preprocessed when peeking ahead for section underline
455
- * introduced Cursor object to track line info
456
- * fixed table valign classes, no underline on image link
457
- * removed dependency on pending library, lock Nokogiri version to 1.5.10
458
- * removed require rubygems line in asciidoctor.rb, add to cli if RUBY_VERSION < 1.9
459
- * added tests for custom backends
460
- * added test that shorthand doesn't clobber explicit options (#481)
461
- * removed unnecessary monospace class from literal and listing blocks
462
-
463
- See the {changelog}[CHANGELOG.adoc] file for a list of changes in older releases as well as for the upcoming release.
464
-
465
- == Contributing
377
+ * don't select lines that contain a tag directive when including tagged lines, make tag regexp more strict (#1027)
378
+ * use https scheme for assets by default
379
+ * upgrade to Font Awesome 4.1 (@mogztter) (#752)
380
+ * improve print styles, add print styles for book doctype (@leif81) (#997, #952)
381
+ * add proper grid and frame styles for tables (@leif81) (#569)
382
+ * use glyphs for checkboxes when not using font icons (#878)
383
+ * prefer source-language attribute over language attribute for defining default source language (#888)
384
+ * pass document as first argument to process method on Preprocessor
385
+ * don't parse link attributes when linkattrs is set unless text contains equal sign
386
+ * detect bare links, mark with bare class; don't repeat URL of bare link in print styles
387
+ * allow Treeprocessor#process method to replace tree (#1035)
388
+ * add AbstractNode#find_by method to locate nodes in tree (#862)
389
+ * add API for parsing title and subtitle (#1000)
390
+ * add use_fallback option to doctitle, document method
391
+ * constrain subscript & superscript markup (#564, #936)
392
+ * match cell specs when cell separator is customized (#985)
393
+ * use stylesheet to set default table width (#975)
394
+ * display nested elements correctly in toc (@kenfinnigan) (#967)
395
+ * add support for id attribute on links (@mogztter) (#935)
396
+ * add support for title attribute on links (@aslakknutsen)
397
+ * add -t flag to cli to control output of timing information (@mogztter) (#909)
398
+ * rewrite converter API (#778)
399
+ * rewrite extensions to support extension instances for AsciidoctorJ (#804)
400
+ * integrate thread_safe gem (#638)
401
+ * allow inline macro extensions that define a custom regexp to be matched (#792)
402
+ * make Reader#push_include work with default file, path and dir (@bk2204) (#743)
403
+ * honor custom outfilesuffix and introduce relfileprefix (#801)
404
+ * add author and copyright to meta in HTML5 backend (#838)
405
+ * output attribution in front of citetitle for quote and verse blocks
406
+ * recognize float style with shorthand syntax outside block (#818)
407
+ * honor background color in syntax highlighting themes (#813)
408
+ * print runtime environment in version output, support -v as version flag (#785)
409
+ * unwrap preamble if standalone (#533)
410
+ * drop leading & trailing blank lines in verbatim & raw content (#724)
411
+ * remove trailing endlines from source data (#727)
412
+ * add flag to cli to suppress warnings (#557)
413
+ * emit warning if tag(s) not found in include file (#639)
414
+ * use <th> element for vertical table headers instead of header class (@davidgamba) (#738)
415
+ * share select references between AsciiDoc-style cell & main document (#729)
416
+ * number chapters sequentially, always (#685)
417
+ * add vbar attribute, make brvbar resolve properly (#643)
418
+ * add implicit user-home attribute that resolves to user's home directory (#629)
419
+ * enable sidebar toc for small screens (#628)
420
+ * add square brackets around button in HTML output (#631)
421
+ * make language hover text work for all languages in listing block
422
+ * set background color on toc2 to cover scrolling content (@neher)
423
+ * make document parsing a discrete step, make Reader accessible as property on Document
424
+ * allow custom converter to set backend info such as outfilesuffix and htmlsyntax
425
+ * report an informative error message when a converter cannot be resolved (@mogztter)
426
+ * add conum class to b element when icons are disabled, make conum CSS selector more specific
427
+ * expose Document object to extension point IncludeProcessor (@aslakknutsen)
428
+ * style audioblock title, simplify rules for block titles
429
+ * alias :name_attributes to :positional_attributes in extension DSL
430
+ * upgrade to highlight.js 7.4 (and later 8.0) (@mogztter) (#756)
466
431
 
467
- In the spirit of {freesoftware}[free software], _everyone_ is encouraged to help improve this project.
468
-
469
- Here are some ways *you* can contribute:
470
-
471
- * by using alpha, beta, and prerelease versions
472
- * by reporting bugs
473
- * by suggesting new features
474
- * by writing or editing documentation
475
- * by writing specifications
476
- * by writing code -- _No patch is too small._
477
- ** fix typos
478
- ** add comments
479
- ** clean up inconsistent whitespace
480
- ** write tests!
481
- * by refactoring code
482
- * by fixing {issues}[issues]
483
- * by reviewing patches
484
-
485
- === Submitting an Issue
486
-
487
- We use the {issues}[issue tracker on GitHub] associated with this project to track bugs and features.
488
- Before submitting a bug report or feature request, check to make sure it hasn't already been submitted.
489
- When submitting a bug report, please include a {gist}[Gist] that includes any details that may help reproduce the bug, including your gem version, Ruby version, and operating system.
490
-
491
- Most importantly, since Asciidoctor is a text processor, reproducing most bugs requires that we have some snippet of text on which Asciidoctor exhibits the bad behavior.
492
-
493
- An ideal bug report would include a pull request with failing specs.
494
-
495
- === Submitting a Pull Request
432
+ Compliance::
496
433
 
497
- . {fork}[Fork the repository].
498
- . {branch}[Create a topic branch].
499
- . Add tests for your unimplemented feature or bug fix.
500
- . Run +bundle exec rake+.
501
- If your tests pass, return to step 3.
502
- . Implement your feature or bug fix.
503
- . Run +bundle exec rake+.
504
- If your tests fail, return to step 5.
505
- . Add documentation for your feature or bug fix.
506
- . If your changes are not 100% documented, go back to step 7.
507
- . Add, commit, and push your changes.
508
- . {pr}[Submit a pull request].
434
+ * only include xmlns in docbook45 backend if xmlns attribute is specified (#929)
435
+ * add xmlns attribute for xhtml output (@bk2204)
436
+ * warn if table without a body is converted to DocBook (#961)
437
+ * wrap <para> around admonition inside example block in DocBook 4.5 (#931)
438
+ * use <informalfigure> if block image doesn't have a title (#927)
439
+ * fix invalid docbook when adding role to formatted text (#956)
440
+ * move all compliance flags to Compliance module (#624)
441
+ * add compliance setting to control use of shorthand property syntax (#789)
442
+ * wrap top-level content inside preamble in DocBook backend when doctype is book (#971)
443
+ * escape special chars in image alt text (#972)
444
+ * set starting number in ordered list for docbook (@megathaum) (#925)
445
+ * match word characters in regular expressions as defined by Unicode (#892)
446
+ * put source language class names on child code element of pre element (#921)
447
+ * ignore case of attribute in conditional directives (#903)
448
+ * allow attribute entry to reset / reseed counter (#870)
449
+ * allow doctype to be set in AsciiDoc table cell (#863)
450
+ * match URL macro following entity (@jmbruel) (#819)
451
+ * handle BOM when normalizing source (#824)
452
+ * don't output revhistory if revdate is not set (#802)
453
+ * perform normal subs on verse content (#799)
454
+ * automatically wrap part intro content in partintro block, emit warning if part is invalid (#768)
455
+ * force encoding of docinfo content to UTF-8 (#773)
456
+ * add scaling & alignment attributes to block image in DocBook backend (#763)
457
+ * add support for pass:[anchor:<id>[<reftext>\]] macro (#531)
458
+ * substitute anchor and xref macros in footnotes (#676)
459
+ * remove all string mutation operations for compatibility with Opal (#735)
460
+ * honor reftext defined in embedded section title anchor (#697)
461
+ * allow spaces in reftext defined in block anchor (#695)
462
+ * use reftext of section or block in text of xref link (#693)
463
+ * number sections in appendix using appendix number (#683)
464
+ * unescape escaped square closing bracket in footnote text (#677)
465
+ * support quoted index terms that may contain commas (#597)
466
+ * don't assign role attribute if quoted text has no roles (#647)
467
+ * disallow quoted values in block and inline anchors
468
+ * add % to scaledwidth if no units given
469
+ * ignore block attribute with unquoted value None
470
+ * preserve entity references with 5 digits
509
471
 
510
- === Supporting Additional Ruby Versions
472
+ Bug Fixes::
511
473
 
512
- If you would like this library to support another Ruby version, you may volunteer to be a maintainer.
513
- Being a maintainer entails making sure all tests run and pass on that implementation.
514
- When something breaks on your implementation, you will be expected to provide patches in a timely fashion.
515
- If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.
474
+ * resolve relative paths relative to base_dir in unsafe mode (#690)
475
+ * properly handle nested passthroughs (#1034)
476
+ * don't clobber outfilesuffix attribute if locked (#1024)
477
+ * correctly calculate columns if colspan used in first row of table (#924)
478
+ * pass theme to Pygments when pygments-css=style (#919)
479
+ * fallback to text lexer when using pygments for source highlighting (#987)
480
+ * only make special section if style is specified (#917)
481
+ * an unresolved footnote ref should not crash processor (#876)
482
+ * rescue failure to resolve ::Dir.home (#896)
483
+ * recognize Windows UNC path as absolute and preserve it (#806)
484
+ * adjust file glob to account for backslash in Windows paths (#805)
485
+ * don't match e-mail address inside URL (#866)
486
+ * test include directive resolves file with space in name (#798)
487
+ * return nil from Reader#push_include and Reader#pop_include methods (#745)
488
+ * fixed broken passthroughs caused by source highlighting (#720)
489
+ * copy custom stylesheet if linkcss is set (#300)
490
+ * honor list continuations for indented, nested list items (#664)
491
+ * fix syntax errors in converters (@jljouannic)
492
+ * fix iconfont-remote setting
493
+ * fix syntax error (target -> node.target) in Docbook 5 converter (@jf647)
494
+ * output and style HTML for toc macro correctly
495
+
496
+ Infrastructure::
497
+
498
+ * add Ruby 2.1 to list of supported platforms
499
+ * reenable rbx in Travis build
500
+ * switch tests to minitest (@ktdreyer)
501
+ * update RPM for Fedora Rawhide (@ktdreyer)
502
+ * refactor unit tests so they work in RubyMine (@cmoulliard)
503
+ * add preliminary benchmark files to repository (#1021)
504
+ * clean out old fixtures from test suite (#960)
505
+ * add initial Cucumber test infrastructure (#731)
506
+ * use gem tasks from Bundler in Rakefile (#654)
507
+ * build gemspec files using git ls-tree (#653)
508
+ * use in-process web server for URI tests
509
+ * update manpage to reflect updates in 1.5.0
510
+ * rework README (@mogztter) (#651)
511
+
512
+ Refer to the {uri-changelog}[CHANGELOG] for a complete list of changes in older releases.