asciidoctor 0.1.3 → 0.1.4

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 (73) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +387 -0
  3. data/README.adoc +358 -348
  4. data/asciidoctor.gemspec +30 -9
  5. data/bin/asciidoctor +3 -0
  6. data/bin/asciidoctor-safe +3 -0
  7. data/compat/asciidoc.conf +76 -4
  8. data/lib/asciidoctor.rb +174 -79
  9. data/lib/asciidoctor/abstract_block.rb +131 -101
  10. data/lib/asciidoctor/abstract_node.rb +108 -26
  11. data/lib/asciidoctor/attribute_list.rb +1 -1
  12. data/lib/asciidoctor/backends/_stylesheets.rb +204 -62
  13. data/lib/asciidoctor/backends/base_template.rb +11 -22
  14. data/lib/asciidoctor/backends/docbook45.rb +158 -163
  15. data/lib/asciidoctor/backends/docbook5.rb +103 -0
  16. data/lib/asciidoctor/backends/html5.rb +662 -445
  17. data/lib/asciidoctor/block.rb +54 -44
  18. data/lib/asciidoctor/cli/invoker.rb +41 -20
  19. data/lib/asciidoctor/cli/options.rb +66 -20
  20. data/lib/asciidoctor/debug.rb +1 -1
  21. data/lib/asciidoctor/document.rb +265 -100
  22. data/lib/asciidoctor/extensions.rb +443 -0
  23. data/lib/asciidoctor/helpers.rb +38 -6
  24. data/lib/asciidoctor/inline.rb +5 -5
  25. data/lib/asciidoctor/lexer.rb +532 -250
  26. data/lib/asciidoctor/{list_item.rb → list.rb} +33 -13
  27. data/lib/asciidoctor/path_resolver.rb +28 -2
  28. data/lib/asciidoctor/reader.rb +814 -455
  29. data/lib/asciidoctor/renderer.rb +128 -42
  30. data/lib/asciidoctor/section.rb +55 -41
  31. data/lib/asciidoctor/substituters.rb +380 -107
  32. data/lib/asciidoctor/table.rb +40 -30
  33. data/lib/asciidoctor/version.rb +1 -1
  34. data/man/asciidoctor.1 +32 -96
  35. data/man/{asciidoctor.ad → asciidoctor.adoc} +57 -48
  36. data/test/attributes_test.rb +200 -27
  37. data/test/blocks_test.rb +361 -22
  38. data/test/document_test.rb +496 -81
  39. data/test/extensions_test.rb +448 -0
  40. data/test/fixtures/basic-docinfo-footer.html +6 -0
  41. data/test/fixtures/basic-docinfo-footer.xml +8 -0
  42. data/test/fixtures/basic-docinfo.xml +3 -3
  43. data/test/fixtures/basic.asciidoc +1 -0
  44. data/test/fixtures/child-include.adoc +5 -0
  45. data/test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml +6 -0
  46. data/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml +1 -0
  47. data/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml +3 -0
  48. data/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml +5 -0
  49. data/test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim +6 -0
  50. data/test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim +3 -0
  51. data/test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim +5 -0
  52. data/test/fixtures/docinfo-footer.html +1 -0
  53. data/test/fixtures/docinfo-footer.xml +9 -0
  54. data/test/fixtures/docinfo.xml +1 -0
  55. data/test/fixtures/grandchild-include.adoc +3 -0
  56. data/test/fixtures/parent-include-restricted.adoc +5 -0
  57. data/test/fixtures/parent-include.adoc +5 -0
  58. data/test/invoker_test.rb +82 -8
  59. data/test/lexer_test.rb +21 -3
  60. data/test/links_test.rb +34 -2
  61. data/test/lists_test.rb +304 -7
  62. data/test/options_test.rb +19 -3
  63. data/test/paragraphs_test.rb +13 -0
  64. data/test/paths_test.rb +22 -0
  65. data/test/preamble_test.rb +20 -0
  66. data/test/reader_test.rb +1096 -644
  67. data/test/renderer_test.rb +152 -12
  68. data/test/sections_test.rb +417 -76
  69. data/test/substitutions_test.rb +339 -138
  70. data/test/tables_test.rb +109 -4
  71. data/test/test_helper.rb +79 -13
  72. data/test/text_test.rb +111 -11
  73. metadata +54 -18
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 83e440b38375e7aaf9706436000410fd3d80a205
4
- data.tar.gz: 3a6e68864dbce5fe5e845305972a49cca714b4ab
3
+ metadata.gz: 4823a22cab8ddb3e6109152db26c0f10a0efec3b
4
+ data.tar.gz: 697bd0c123fbdf19843dcc6e5f7dceef9a9c5f89
5
5
  SHA512:
6
- metadata.gz: ebd29c43ea544f14375e7c8f49c43bda1cfb99057cf819c2919679e32d3fd9c27c42459ac115decbd846e6e4349b2c094693e11e549dbb300c7815ab8500053a
7
- data.tar.gz: 19b9420012417f358e1433e3c38511a12b5bdbaf9c99f5487ea5829493d7271c2a9156afc78e377e36ff0678e000b49d6dc22e4d74a63919033bb4b4253d24e6
6
+ metadata.gz: 06a29332c4eb1754fb86d0facbdefa0fdefd554791d949e2501e8df14f03fc2e4a7fc3685aa69ec5c0105854122970eb79e80a48e3b1d7b8fe586771dbb40ca6
7
+ data.tar.gz: 0030da2c1b4632a249d3a2a47f17b1ffd5bbde8107f3fae802f868226a7c9b1419a5ffb31a96296e1b3ce416615cbaa0790a8444aa290a0fecf2385d5b51721f
@@ -0,0 +1,387 @@
1
+ = Asciidoctor Changelog
2
+
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.
4
+
5
+ This document provides a high-level view of the changes introduced in Asciidoctor by release.
6
+ For a detailed view of what has changed, refer to the https://github.com/asciidoctor/asciidoctor/commits/master[commit history] on GitHub.
7
+
8
+ == 0.1.4 (2013-09-05) - @mojavelinux
9
+
10
+ Performance::
11
+
12
+ * 15% increase in speed compared to 0.1.3
13
+
14
+ Enhancements::
15
+
16
+ * updated xref inline macro to support inter-document references (#417)
17
+ * added extension API for document processing (#79)
18
+ * added include directive processor extension (#100)
19
+ * added id and role shorthand for formatted (quoted) text (#517)
20
+ * added shorthand syntax for specifying block options (#481)
21
+ * added support for checklists in unordered list (#200)
22
+ * added support for inline style for unordered lists (#620)
23
+ * added DocBook 5 backend (#411)
24
+ * added docinfo option for footer (#486)
25
+ * added Pygments as source highlighter option (pygments) (#538)
26
+ * added icon inline macro (#529)
27
+ * recognize implicit table header row (#387)
28
+ * uri can be used in inline image (#470)
29
+ * add float attribute to inline image (#616)
30
+ * allow role to be specified on text enclosed in backticks (#419)
31
+ * added XML comment-style callouts for use in XML listings (#582)
32
+ * made callout bullets non-selectable in HTML output (#478)
33
+ * pre-wrap literal blocks, added nowrap option to listing blocks (#303)
34
+ * skip (retain) missing attribute references by default (#523)
35
+ * added attribute-missing attribute to control how a missing attribute is handled (#495)
36
+ * added attribute-undefined attribute to control how an undefined attribute is handled (#495)
37
+ * permit !name syntax for undefining attribute (#498)
38
+ * ignore front matter used by static site generators if skip-front-matter attribute is set (#502)
39
+ * sanitize contents of HTML title element in html5 backend (#504)
40
+ * support toc position for toc2 (#467)
41
+ * cli accepts multiple files as input (@lordofthejars) (#227)
42
+ * added Markdown-style horizontal rules and pass Markdown tests (#455)
43
+ * added float clearing classes (.clearfix, .float-group) (#602)
44
+ * don't disable syntax highlighting when explicit subs is used on listing block
45
+ * asciidoctor package now available in Debian Sid and Ubuntu Saucy (@avtobiff) (#216)
46
+
47
+ Compliance::
48
+
49
+ * embed CSS by default, copy stylesheet when linkcss is set unless copycss! is set (#428)
50
+ * refactor reader to track include stack (#572)
51
+ * made include directive resolve relative to current file (#572)
52
+ * track include stack to enforce maximum depth (#581)
53
+ * fixed greedy comment blocks and paragraphs (#546)
54
+ * enable toc and numbered by default in DocBook backend (#540)
55
+ * ignore comment lines when matching labeled list item (#524)
56
+ * correctly parse footnotes that contain a URL (#506)
57
+ * parse manpage metadata, output manpage-specific HTML, set docname and outfilesuffix (#488, #489)
58
+ * recognize preprocessor directives on first line of AsciiDoc table cell (#453)
59
+ * include directive can retrieve data from uri if allow-uri-read attribute is set (#445)
60
+ * support escaping attribute list that precedes formatted (quoted) text (#421)
61
+ * made improvements to list processing (#472, #469, #364)
62
+ * support percentage for column widths (#465)
63
+ * substitute attributes in docinfo files (#403)
64
+ * numbering no longer increments on unnumbered sections (#393)
65
+ * fixed false detection of list item with hyphen marker
66
+ * skip include directives when processing comment blocks
67
+ * added xmlns to root element in docbook45 backend, set noxmlns attribute to disable
68
+ * added a Compliance module to control compliance-related behavior
69
+ * added linkattrs feature to AsciiDoc compatibility file (#441)
70
+ * added level-5 heading to AsciiDoc compatibility file (#388)
71
+ * added new XML-based callouts to AsciiDoc compatibility file
72
+ * added absolute and uri image target matching to AsciiDoc compatibility file
73
+ * added float attribute on inline image macro to AsciiDoc compatibility file
74
+ * removed linkcss in AsciiDoc compatibility file
75
+ * fixed fenced code entry in compatibility file
76
+
77
+ Bug Fixes::
78
+
79
+ * lowercase attribute names passed to API (#508)
80
+ * numbered can still be toggled even when enabled in API (#393)
81
+ * allow JRuby Map as attributes (#396)
82
+ * don't attempt to highlight callouts when using CodeRay and Pygments (#534)
83
+ * correctly calculate line length in Ruby 1.8 (#167)
84
+ * write to specified outfile even when input is stdin (#500)
85
+ * only split quote attribution on first comma in Markdown blockquotes (#389)
86
+ * don't attempt to print render times when doc is not rendered
87
+ * don't recognize line with four backticks as a fenced code block (#611)
88
+
89
+ Improvements::
90
+
91
+ * upgraded Font Awesome to 3.2.1 (#451)
92
+ * improved the built-in CodeRay theme to match Asciidoctor styles
93
+ * link to CodeRay stylesheet if linkcss is set (#381)
94
+ * style the video block (title & margin) (#590)
95
+ * added Groovy, Clojure, Python and YAML to floating language hint
96
+ * only process callouts for blocks in which callouts are found
97
+ * added content_model to AbstractBlock, rename buffer to lines
98
+ * use Untitled as document title in rendered output if document has no title
99
+ * rename include-depth attribute to max-include-depth, set 64 as default value (#591)
100
+ * the tag attribute can be used on the include directive to identify a single tagged region
101
+ * output multiple authors in HTML backend (#399)
102
+ * allow multiple template directories to be specified, document in usage and manpage (#437)
103
+ * added option to cli to specify template engine (#406)
104
+ * added support for external video hosting services in video block macro (@xcoulon) (#587)
105
+ * strip leading separator(s) on section id if idprefix is blank (#551)
106
+ * customized styling of toc placed inside body content (#507)
107
+ * consolidate toc attribute so toc with or without toc-position can make sidebar toc (#618)
108
+ * properly style floating images (inline & block) (#460)
109
+ * add float attribute to inline images (#616)
110
+ * use ul list for TOC in HTML5 backend (#431)
111
+ * support multiple terms per labeled list item in model (#532)
112
+ * added role?, has_role?, option? and roles methods to AbstractNode (#423, 474)
113
+ * added captioned_title method to AbstractBlock
114
+ * honor showtitle attribute as alternate to notitle! (#457)
115
+ * strip leading indent from literal paragraph blocks assigned the style normal
116
+ * only process lines in AsciiDoc files
117
+ * emit message that tilt gem is required to use custom backends if missing (#433)
118
+ * use attributes for version and last updated messages in footer (#596)
119
+ * added a basic template cache (#438)
120
+ * include line info in several of the warnings (for lists and tables)
121
+ * print warning/error messages using warn (#556)
122
+ * lines are not preprocessed when peeking ahead for section underline
123
+ * introduced Cursor object to track line info
124
+ * fixed table valign classes, no underline on image link
125
+ * removed dependency on pending library, lock Nokogiri version to 1.5.10
126
+ * removed require rubygems line in asciidoctor.rb, add to cli if RUBY_VERSION < 1.9
127
+ * added tests for custom backends
128
+ * added test that shorthand doesn't clobber explicit options (#481)
129
+ * removed unnecessary monospace class from literal and listing blocks
130
+
131
+ Distribution Packages::
132
+
133
+ * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
134
+ * https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (rubygem-asciidoctor)]
135
+ * http://packages.debian.org/sid/asciidoctor[Debian (asciidoctor)]
136
+ * http://packages.ubuntu.com/saucy/asciidoctor[Ubuntu (asciidoctor)]
137
+
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
+ ::
142
+ https://github.com/asciidoctor/asciidoctor/compare/v0.1.3...v0.1.4[full diff]
143
+
144
+ == 0.1.3 (2013-05-30) - @mojavelinux
145
+
146
+ Performance::
147
+
148
+ * 10% increase in speed compared to 0.1.2
149
+
150
+ Enhancements::
151
+
152
+ * added support for inline rendering by setting doctype to inline (#328)
153
+ * added support for using font-based icons (#115)
154
+ * honor haml/slim/jade-style shorthand for id and role attributes (#313)
155
+ * support Markdown-style headings as section titles (#373)
156
+ * support Markdown-style quote blocks
157
+ * added section level 5 (maps to h6 element in the html5 backend) (#334)
158
+ * added btn inline macro (#259)
159
+ * added menu inline menu to identify a menu selection (@bleathem) (#173)
160
+ * added kbd inline macro to identify a key or key combination (@bleathem) (#172)
161
+ * support alternative quote forms (#196)
162
+ * added indent attribute to verbatim blocks (#365)
163
+ * added prettify source-highlighter (#202)
164
+ * link section titles (#122)
165
+ * introduce shorthand syntax for table format (#350)
166
+ * parse attributes in link when use-link-attrs attribute is set (#214)
167
+ * support preamble toc-placement (#295)
168
+ * exclude attribute div if quote has no attribution (#309)
169
+ * support attributes passed to API as string or string array (#289)
170
+ * allow safe mode to be set using string, symbol or int in API (#290)
171
+ * make level 0 section titles more prominent in TOC (#369)
172
+
173
+ Compliance::
174
+
175
+ * ~ 99.5% compliance with AsciiDoc
176
+ * drop line if target of include directive is blank (#376)
177
+ * resolve attribute references in target of include directive (#367)
178
+ * added irc scheme to link detection (#314)
179
+ * toc should honor numbered attribute (#341)
180
+ * added toc2 layout to default stylesheet (#285)
181
+ * consecutive terms in labeled list share same entry (#315)
182
+ * support set:name:value attribute syntax (#228)
183
+ * block title not allowed above document title (#175)
184
+ * assign caption even if no title (#321)
185
+ * horizontal dlist layout in docbook backend (#298)
186
+ * set doctitle attribute (#337)
187
+ * allow any backend to be specified in cli (@lightguard) (#320)
188
+ * support for abstract and partintro (#297)
189
+
190
+ Bug Fixes::
191
+
192
+ * fixed file path resolution on Windows (#330)
193
+ * fixed bad variable name that was causing crash, add test for it (#335)
194
+ * set proper encoding on input data (#308)
195
+ * don't leak doctitle into nested document (#382)
196
+ * handle author(s) defined using attributes (#301)
197
+
198
+ Improvements::
199
+
200
+ * added tests for all special sections (#80)
201
+ * added test for attributes defined as string or string array (@lightguard) (#291)
202
+
203
+ Distribution Packages::
204
+
205
+ * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
206
+ * https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Fedora (rubygem-asciidoctor)]
207
+
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
+ ::
214
+ https://github.com/asciidoctor/asciidoctor/compare/v0.1.2...v0.1.3[full diff]
215
+
216
+ == 0.1.2 (2013-04-25) - @mojavelinux
217
+
218
+ Performance::
219
+
220
+ * 28% increase in speed compared to 0.1.1, 32% increase compared to 0.1.0
221
+
222
+ Enhancements::
223
+
224
+ * new website at http://asciidoctor.org
225
+ * added a default stylesheet (#76)
226
+ * added viewport meta tag for mobile browsers (#238)
227
+ * set attributes based on safe mode (#244)
228
+ * added admonition name as style class (#265)
229
+ * removed hardcoded CSS, no one likes hardcoded CSS (#165)
230
+ * support multiple authors in document header (#223)
231
+ * include footnotes block in embedded document (#206)
232
+ * allow comma delimiter in include attribute values (#226)
233
+ * support including tagged lines (#226)
234
+ * added line selection to include directive (#226)
235
+ * Asciidoctor#render APIs return Document when document is written to file
236
+
237
+ Compliance::
238
+
239
+ * added AsciiDoc compatibility file to make AsciiDoc behave like Asciidoctor (#257)
240
+ * restore alpha-based xml entities (#211)
241
+ * implement video and audio block macros (#155)
242
+ * implement toc block macro (#269)
243
+ * correctly handle multi-part books (#222)
244
+ * complete masquerade functionality for blocks & paragraphs (#187)
245
+ * support explicit subs on blocks (#220)
246
+ * use code element instead of tt (#260)
247
+ * honor toc2 attribute (#221)
248
+ * implement leveloffset feature (#212)
249
+ * include docinfo files in header when safe mode < SERVER (#116)
250
+ * support email links and mailto inline macros (#213)
251
+ * question must be wrapped in simpara (#231)
252
+ * allow round bracket in link (#218)
253
+
254
+ Bug Fixes::
255
+
256
+ * trailing comma shouldn't be included in link (#280)
257
+ * warn if file in include directive doesn't exist (#262)
258
+ * negative case for inline ifndef should only affect current line (#241)
259
+ * don't compact nested documents (#217)
260
+ * nest revision info inside revision element (#236)
261
+
262
+ Distribution Packages::
263
+
264
+ * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
265
+
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
+ ::
272
+ https://github.com/asciidoctor/asciidoctor/compare/v0.1.1...v0.1.2[full diff]
273
+
274
+ == 0.1.1 (2013-02-26) - @erebor
275
+
276
+ Performance::
277
+
278
+ * 15% increase in speed compared to 0.1.0
279
+
280
+ Enhancements::
281
+
282
+ * migrated repository to asciidoctor organization on GitHub (#77)
283
+ * include document title when header/footer disabled and notitle attribute is unset (#103)
284
+ * honor GitHub-flavored Markdown fenced code blocks (#118)
285
+ * added :doctype and :backend keys to options hash in API (#163)
286
+ * added :to_dir option to the Asciidoctor#render API
287
+ * added option :header_only to stop parsing after reading the header
288
+ * preliminary line number tracking
289
+ * auto-select backend sub-folder containing custom templates
290
+ * rubygem-asciidoctor package now available in Fedora (#92)
291
+
292
+ Compliance::
293
+
294
+ * refactor reader, process attribute entries and conditional blocks while parsing (#143)
295
+ * support limited value comparison functionality of ifeval (#83)
296
+ * added support for multiple attributes in ifdef and ifndef directives
297
+ * don't attempt to embed image with uri reference when data-uri is set (#157)
298
+ * accomodate trailing dot in author name (#156)
299
+ * don't hardcode language attribute in html backend (#185)
300
+ * removed language from DocBook root node (#188)
301
+ * fixed revinfo line swallowing attribute entry
302
+ * auto-generate caption for listing blocks if listing-caption attribute is set
303
+ * support nested includes
304
+ * support literal and listing paragraphs
305
+ * support em dash shorthand at the end of a line
306
+ * added ftp support to link inline macro
307
+ * added support for the page break block macro
308
+
309
+ Bug Fixes::
310
+
311
+ * pass through image with uri reference when data-uri is set (#157)
312
+ * print message for failed arg (#152)
313
+ * normalize whitespace at the end of lines (improved)
314
+ * properly load custom templates and required libraries
315
+
316
+ Improvements::
317
+
318
+ * parse document header in distinct parsing step
319
+ * moved hardcoded english captions to attributes
320
+
321
+ Distribution Packages::
322
+
323
+ * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
324
+
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
+ ::
329
+ https://github.com/asciidoctor/asciidoctor/compare/v0.1.0...v0.1.1[full diff]
330
+
331
+ == 0.1.0 (2013-02-04) - @erebor
332
+
333
+ Enhancements::
334
+
335
+ * introduced Asciidoctor API (Asciidoctor#load and Asciidoctor#render methods) (#34)
336
+ * added SERVER safe mode level (minimum recommended security for serverside usage) (#93)
337
+ * added the asciidoctor commandline interface (cli)
338
+ * added asciidoctor-safe command, enables safe mode by default
339
+ * added man page for the asciidoctor command
340
+ * use blockquote tag for quote block content (#124)
341
+ * added hardbreaks option to preserve line breaks in paragraph text (#119)
342
+ * :header_footer option defaults to false when using the API, unless rendering to file
343
+ * added idseparator attribute to customized separator used in generated section ids
344
+ * do not number special sections (differs from AsciiDoc)
345
+
346
+ Compliance::
347
+
348
+ * use callout icons if icons are enabled, unless safe mode is SECURE
349
+ * added support for name=value@ attribute syntax passed via cli (#97)
350
+ * attr refs no longer case sensitive (#109)
351
+ * fixed several cases of incorrect list handling
352
+ * don't allow links to consume endlines or surrounding angled brackets
353
+ * recognize single quote in author name
354
+ * support horizontal labeled list style
355
+ * added support for the d cell style
356
+ * added support for bibliography anchors
357
+ * added support for special sections (e.g., appendix)
358
+ * added support for index term inline macros
359
+ * added support for footnote and footnoteref inline macros
360
+ * added auto-generated numbered captions for figures, tables and examples
361
+ * added counter inline macros
362
+ * added support for floating (discrete) section titles
363
+
364
+ Bug Fixes::
365
+
366
+ * fixed UTF-8 encoding issue by adding magic encoding line to ERB templates (#144)
367
+ * resolved Windows compatibility issues
368
+ * clean CRLF from end of lines (#125)
369
+ * enabled warnings when running tests, fixed warnings (#69)
370
+
371
+ Improvements::
372
+
373
+ * renamed iconstype attribute to icontype
374
+
375
+ Distribution Packages::
376
+
377
+ * http://rubygems.org/gems/asciidoctor[RubyGem (asciidoctor)]
378
+
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
+ ::
383
+ https://github.com/asciidoctor/asciidoctor/compare/v0.0.9...v0.1.0[full diff]
384
+
385
+ == Older releases (pre-0.0.1)
386
+
387
+ For information about older releases, refer to the https://github.com/asciidoctor/asciidoctor/tags[commit history] on GitHub.
@@ -1,10 +1,22 @@
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]>
2
3
  :awestruct-layout: base
3
4
  :homepage: http://asciidoctor.org
4
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
5
13
  :sources: https://github.com/asciidoctor/asciidoctor
14
+ :tests: https://github.com/asciidoctor/asciidoctor/tree/master/test
6
15
  :issues: https://github.com/asciidoctor/asciidoctor/issues
7
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
8
20
  :org: https://github.com/asciidoctor
9
21
  :contributors: https://github.com/asciidoctor/asciidoctor/graphs/contributors
10
22
  :templates: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/backends
@@ -16,395 +28,443 @@
16
28
  :fork: https://help.github.com/articles/fork-a-repo
17
29
  :branch: http://learn.github.com/p/branching.html
18
30
  :pr: https://help.github.com/articles/using-pull-requests
31
+ :changelog: https://github.com/asciidoctor/asciidoctor/blob/master/CHANGELOG.adoc
19
32
  :license: https://github.com/asciidoctor/asciidoctor/blob/master/LICENSE
20
33
  :idprefix:
21
34
  :idseparator: -
35
+ ifndef::safe-mode-name[]
22
36
 
23
- {homepage}[Asciidoctor] is a pure Ruby processor for converting
24
- {asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 4.5
25
- and other formats. It's http://rubygems.org/gems/asciidoctor[published
26
- as a RubyGem] and is available under the MIT open source license.
37
+ [float]
38
+ = Asciidoctor
39
+ endif::[]
40
+
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.
27
45
 
28
46
  ifndef::awestruct[]
29
- image::https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
47
+ *Project health:* image:https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
30
48
  endif::awestruct[]
31
49
 
32
- Asciidoctor uses a set of built-in ERB templates to render the document
33
- to HTML 5 or DocBook 4.5. We've matched the rendered output as close as
34
- possible to the default output of the native Python processor. You can
35
- override this behavior by providing {tilt}[Tilt]-compatible templates.
36
- See the <<usage>> section for more details.
37
-
38
- Asciidoctor currently works (read as 'tested') with Ruby 1.8.7, Ruby
39
- 1.9.3, Ruby 2.0.0, JRuby 1.7.4 and Rubinius nightly (on Linux, Mac and
40
- Windows). We expect it will work with other versions of Ruby as well and
41
- would welcome help in testing it out.
42
-
43
- The initial code from which Asciidoctor emerged was written by
44
- http://github.com/nickh[Nick Hengeveld] to process the git man pages for
45
- the {gitscm-next}[Git project site]. Refer to commit history of
46
- {seed-contribution}[asciidoc.rb] to view the initial contributions and
47
- contributors.
48
-
49
- The source code can now be found in the {sources}[Asciidoctor source
50
- repository] on GitHub.
51
-
52
- == Installation
53
-
54
- NOTE: We're working hard to make Asciidoctor a drop-in replacement for
55
- AsciiDoc. We're very close, with over 700 tests that ensure
56
- compatibility. The march is on towards full compliance and beyond.
57
-
58
- To install the gem:
59
-
60
- gem install asciidoctor
61
-
62
- Or if you prefer bundler, add the asciidoctor gem to your Gemfile,
63
-
64
- source 'https://rubygems.org'
65
- gem 'asciidoctor'
66
-
67
- then install it using bundler:
68
-
69
- bundle install
70
-
71
- If you're running Fedora, you can install the gem using yum:
72
-
73
- sudo yum install rubygem-asciidoctor
74
-
75
- The benefit of installing the gem via yum is that yum will also install
76
- Ruby if it's not already on your machine.
77
-
78
- == Usage
79
-
80
- Asciidoctor has both a command line interface (CLI) and an API. The CLI
81
- is a drop-in replacement for the +asciidoc.py+ command from the Python
82
- implementation. The API is intended for integration with other software
83
- projects and is suitable for server-side applications, such as Rails,
84
- Sinatra and GitHub.
85
-
86
- === Command line interface (CLI)
87
-
88
- After installing the +asciidoctor+ gem, the +asciidoctor+ commandline
89
- interface should be available on your PATH. To invoke it, simply execute:
90
-
91
- asciidoctor <asciidoc_file>
92
-
93
- This will use the built-in defaults for options and create a new file in
94
- the same directory as the input file, with the same base name, but with
95
- the .html extension.
96
-
97
- There are many other options available and full help is provided via:
98
-
99
- asciidoctor --help
100
-
101
- or in the http://asciidoctor.org/man/asciidoctor[man page].
102
-
103
- There is also an +asciidoctor-safe+ command, which turns on safe mode by
104
- default, preventing access to files outside the parent directory of the
105
- source file. This mode is very similar to the safe mode of
106
- +asciidoc.py+.
107
-
108
- === Ruby API
109
-
110
- To use Asciidoctor in your application, you first need to require the
111
- gem:
50
+ == AsciiDoc Processing
112
51
 
113
- require 'asciidoctor'
114
-
115
- With that in place, you can start processing AsciiDoc documents.
116
-
117
- .Loading a document
118
- To parse a file into an +Asciidoctor::Document+ object:
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.
119
57
 
120
- doc = Asciidoctor.load_file('your_file.asciidoc')
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.
121
61
 
122
- You can get information about the document:
62
+ == Operating Systems
123
63
 
124
- puts doc.doctitle
125
- puts doc.attributes
64
+ Asciidoctor works on Linux, Mac and Windows.
126
65
 
127
- More than likely, you want to just render the document.
66
+ == Dependency and Configuration Requirements
128
67
 
129
- .Rendering files
130
- To render a file containing AsciiDoc markup to HTML 5:
68
+ Asciidoctor requires one of the following implementations of Ruby:
131
69
 
132
- Asciidoctor.render_file('your_file.asciidoc', :in_place => true)
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_
133
75
 
134
- The command will output to the file +your_file.html+ in the same
135
- directory. You can render the file to DocBook 4.5 by setting the
136
- +backend+ attribute to 'docbook':
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.
137
78
 
138
- Asciidoctor.render_file('your_file.asciidoc', :in_place => true,
139
- :attributes => {'backend' => 'docbook'})
79
+ // QUESTION What is considered configuration information?
140
80
 
141
- The command will output to the file +your_file.xml+ in the same
142
- directory. (If you're on Linux, you can view the file using yelp).
81
+ // QUESTION What about other sub-projects of Asciidoctor that require Tilt?
143
82
 
144
- .Rendering strings
145
- To render an AsciiDoc-formatted string:
83
+ // TODO fill in this section and enable
84
+ //== List of files/directory structure
85
+ //
86
+ //Optional depending on the complexity of the project
146
87
 
147
- puts Asciidoctor.render('*This* is it.')
88
+ The latest source code is located in the {sources}[Asciidoctor git repository] on GitHub.
148
89
 
149
- When rendering a string, the header and footer are excluded by default
150
- to make Asciidoctor consistent with other lightweight markup engines
151
- like Markdown. If you want the header and footer, just enable it using
152
- the +:header_footer+ option:
90
+ == Installation
153
91
 
154
- puts Asciidoctor.render('*This* is it.', :header_footer => true)
92
+ Asciidoctor can be installed via the +gem+ command, bundler, or popular Linux package managers.
155
93
 
156
- Now you'll get a full HTML 5 file. As before, you can also produce
157
- DocBook 4.5:
94
+ === gem install
158
95
 
159
- puts Asciidoctor.render('*This* is it.', :header_footer => true,
160
- :attributes => {'backend' => 'docbook'})
96
+ To install Asciidoctor using the +gem+ command:
161
97
 
162
- If you don't like the output you see, you can change it. Any of it!
98
+ . Open a terminal
99
+ . Type the +gem+ command
163
100
 
164
- .Custom templates
165
- Asciidoctor allows you to override the {templates}[built-in templates]
166
- used to render almost any individual AsciiDoc element. If you provide a
167
- directory of {tilt}[Tilt]-compatible templates, named in such a way that
168
- Asciidoctor can figure out which template goes with which element,
169
- Asciidoctor will use the templates in this directory instead of its
170
- built-in templates for any elements for which it finds a matching
171
- template. It will fallback to its default templates for everything else.
101
+ $> gem install asciidoctor
172
102
 
173
- puts Asciidoctor.render('*This* is it.', :header_footer => true,
174
- :template_dir => 'templates')
103
+ === bundle install (Bundler)
175
104
 
176
- The Document and Section templates should begin with +document.+ and
177
- +section.+, respectively. The file extension is used by Tilt to
178
- determine which view framework it will use to use to render the
179
- template. For instance, if you want to write the template in ERB, you'd
180
- name these two templates +document.html.erb+ and +section.html.erb+. To
181
- use Haml, you'd name them +document.html.haml+ and +section.html.haml+.
105
+ To install Asciidoctor using bundler:
182
106
 
183
- Templates for block elements, like a Paragraph or Sidebar, would begin
184
- with +block_<style>.+. For instance, to override the default Paragraph
185
- template with an ERB template, put a file named
186
- +block_paragraph.html.erb+ in the template directory you pass to the
187
- +Document+ constructor using the +:template_dir+ option.
107
+ . Open your system Gemfile
108
+ . Add the +asciidoctor+ gem to your Gemfile using the following text
188
109
 
189
- For more usage examples, see the (massive) test suite.
110
+ source 'https://rubygems.org'
111
+ gem 'asciidoctor'
190
112
 
191
- == Differences from AsciiDoc
113
+ . Save the Gemfile
114
+ . Open a terminal
115
+ . Install the gem with bundler
192
116
 
193
- While Asciidoctor aims to be compliant with the AsciiDoc syntax, there
194
- are some differences which are important to keep in mind. In some cases,
195
- it's to enforce a rule we believe is too lax or ambiguous in AsciiDoc.
196
- In other cases, it's a tradeoff for speed, smarter processing or a
197
- feature we just haven't yet implemented. (You'll also notice that
198
- Asciidoctor executes about 25x as fast as AsciiDoc).
117
+ $> bundle install
199
118
 
200
- Here are the known cases where Asciidoctor differs from AsciiDoc:
119
+ === yum install (Fedora)
120
+
121
+ To install Asciidoctor on Fedora 17 or greater:
201
122
 
202
- * Asciidoctor enables safe mode by default when using the API
203
- (+SafeMode::SECURE+)
123
+ . Open a terminal
124
+ . Type the +yum+ command
125
+
126
+ $> sudo yum install rubygem-asciidoctor
204
127
 
205
- * Asciidoctor safe mode is even more safe than AsciiDoc's safe mode
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.
206
129
 
207
- * Asciidoctor enforces symmetric block delimiters (the length of start
208
- and end delimiters for a block must match!)
130
+ === apt-get install (Debian, Ubuntu)
131
+
132
+ To install Asciidoctor on Debian Sid or Ubuntu Saucy or greater:
209
133
 
210
- * Section title underlines must be within 1 character of the length of
211
- the title (AsciiDoc allows an offset of 3)
134
+ . Open a terminal
135
+ . Type the +apt-get+ command
136
+
137
+ $> sudo apt-get install asciidoctor
212
138
 
213
- * Asciidoctor's default HTML backend matches AsciiDoc's HTML 5 backend
214
- (whereas XHTML 1.1 is the default HTML backend in AsciiDoc)
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.
215
140
 
216
- * Asciidoctor adds viewport meta tag to +<head>+ to optimize mobile viewing
141
+ === Other installation options
217
142
 
218
- * Asciidoctor handles inline anchors more cleanly
143
+ * {toolchain}[Installing the Asciidoctor toolchain]
144
+ * {install-mac}[Installing Asciidoctor on Mac OS X]
219
145
 
220
- ** AsciiDoc adds an +<a>+ tag in the line and that markup gets caught in
221
- the generated id
146
+ == Upgrading
222
147
 
223
- ** Asciidoctor promotes the id of the anchor as the section id
148
+ If you have an earlier version of Asciidoctor installed, you can update it using the +gem+ command:
224
149
 
225
- * Asciidoctor strips XML entities from the section title before
226
- generating the id (makes for cleaner section ids)
150
+ $> gem update asciidoctor
227
151
 
228
- * Asciidoctor uses +<code>+ instead of +<span class="monospace">+ around
229
- inline literal text in the HTML backend
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:
230
156
 
231
- * Asciidoctor does not wrap email next to author name in header in
232
- angle brackets
157
+ $> gem cleanup asciidoctor
158
+ ====
233
159
 
234
- * Asciidoctor allows email field to be a URL and renders it as such
160
+ On Fedora, you can update it using:
235
161
 
236
- * Asciidoctor is much more lenient about attribute list parsing (double
237
- quotes are rarely needed, though you may want to keep them for
238
- compatibility)
162
+ $> sudo yum update rubygem-asciidoctor
239
163
 
240
- * Asciidoctor adds the type attribute on ordered lists to provide hint
241
- for numbering style when stylesheet is absent (such as in embedded mode)
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.
242
166
 
243
- * Asciidoctor recognizes +opts+ as an alias for the +options+ attribute.
167
+ On Debian or Ubuntu, you can update it using:
244
168
 
245
- * Asciidoctor creates xref labels using the text from the linked section
246
- title when rendering HTML to match how DocBook works
169
+ $> sudo apt-get upgrade asciidoctor
247
170
 
248
- * Asciidoctor allows commas to be used in xref labels, whereas AsciiDoc
249
- cuts off the label at the location of the first comma
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.
250
174
 
251
- * Asciidoctor removes indentation for non-literal paragraphs in a list
252
- item
253
- +
254
- NOTE: In general, Asciidoctor handles whitespace much more intelligently
255
- +
175
+ == Usage
256
176
 
257
- * Asciidoctor does not output an empty +<dd>+ for labeled list items
258
- that don't have a definition
177
+ If the Asciidoctor gem installed successfully, the +asciidoctor+ command line interface (CLI) will be available on your PATH.
178
+ To invoke it, execute:
259
179
 
260
- * In Asciidoctor, a horizontal ruler can have attributes
180
+ $> asciidoctor --version
181
+ Asciidoctor 0.1.4 [http://asciidoctor.org]
261
182
 
262
- * Asciidoctor wraps +<col>+ elements in +<colgroup>+ in tables
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.
263
185
 
264
- * Asciidoctor uses +<code>+ around content in monospaced table cells
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.
265
189
 
266
- * Asciidoctor skips over line comments in tables, whereas AsciiDoc doesn't
190
+ === Command line interface (CLI)
267
191
 
268
- * Asciidoctor uses its own API rather than a command line invocation to
269
- handle table cells that have AsciiDoc content
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:
270
194
 
271
- * Asciidoctor supports resolving variables from parent document in table
272
- cells with AsciiDoc content
195
+ asciidoctor <asciidoc_file>
273
196
 
274
- * AsciiDoc doesn't carry over the doctype attribute passed from the
275
- commandline when rendering AsciiDoc table cells, whereas Asciidoctor does
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.
276
198
 
277
- * Asciidoctor does not require commas between attributes with quoted
278
- values in a block attribute list
199
+ There are many other options available and full help is provided via:
279
200
 
280
- * Asciidoctor strips the file extension from the target image when
281
- generating alt text if no alt text is provided
201
+ asciidoctor --help
282
202
 
283
- * Asciidoctor reifies the toc in the header of the document instead of
284
- relying on JavaScript to create it
203
+ or in the {man}[man page].
285
204
 
286
- * Asciidoctor sets CSS class on toc element, read from the +toc-class+
287
- attribute; defaults to toc attribute name (+toc+ or +toc2+).
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+.
288
207
 
289
- * Asciidoctor honors the id, title, role and levels attributes set on
290
- the toc macro.
208
+ Additional documentation:
291
209
 
292
- * Asciidoctor does not output two TOCs with the same id.
210
+ * {render}[How do I render a document?]
211
+ * {factory}[How do I use the Asciidoctor stylesheet factory to produce custom themes?]
293
212
 
294
- * Asciidoctor is nice about using a section title syntax inside a
295
- delimited block by simply ignoring it (AsciiDoc issues warnings)
213
+ === Ruby API
296
214
 
297
- * Asciidoctor honors the alternate style name "discrete" for a floating
298
- title (i.e., +[discrete]+)
215
+ To use Asciidoctor in your application, you first need to require the gem:
299
216
 
300
- * Asciidoctor supports the +pass+ style on open blocks and paragraphs
217
+ require 'asciidoctor'
301
218
 
302
- * Asciidoctor supports syntax highlighting of listing, literal or open blocks
303
- that have the "source" style out of the box
219
+ With that in place, you can start processing AsciiDoc documents.
304
220
 
305
- ** Asciidoctor honors the source-highlighter values +coderay+ and
306
- +highlightjs+, using CodeRay or highlight.js, respectively
221
+ .Loading a document
222
+ To parse a file into an +Asciidoctor::Document+ object:
307
223
 
308
- ** Asciidoctor does not currently support Pygments for source
309
- highlighting
224
+ doc = Asciidoctor.load_file 'sample.adoc'
310
225
 
311
- ** Asciidoctor gracefully falls back to listing block if no source language
312
- is specified
226
+ You can get information about the document:
313
227
 
314
- * Asciidoctor sets these additional intrinsic attributes
228
+ puts doc.doctitle
229
+ puts doc.attributes
315
230
 
316
- +asciidoctor+::
317
- indicates Asciidoctor is being used; useful for conditional
318
- processing
231
+ More than likely, you will want to render the document.
319
232
 
320
- +asciidoctor-version+::
321
- indicates which version of Asciidoctor is in use
233
+ .Rendering files
234
+ --
235
+ To render a file containing AsciiDoc markup to HTML 5, use:
322
236
 
323
- * Asciidoctor does not support deprecated tables (you don't want them
324
- anyway)
237
+ Asciidoctor.render_file 'sample.adoc', :in_place => true
325
238
 
326
- * Use can set the extension for icons using the +icontype+ attribute
327
- (AsciiDoc defaults to .png)
239
+ The command will output to the file +sample.html+ in the same directory.
328
240
 
329
- * Asciidoctor uses the +<blockquote>+ for the content and +<cite>+ tag for
330
- attribution title in the HTML output for quote blocks, requiring some
331
- additional styling to match AsciiDoc
332
- +
333
- blockquote.content { padding: 0; margin; 0 }
334
- cite { color: navy; }
335
- +
241
+ You can render the file to DocBook 4.5 by setting the +:backend+ option to +'docbook'+:
336
242
 
337
- * Asciidoctor supports markdown-style blockquotes as well as a shorthand
338
- for a blockquote paragraph.
243
+ Asciidoctor.render_file 'sample.adoc', :in_place => true, :backend => 'docbook'
339
244
 
340
- * Asciidoctor supports markdown-style headings (section titles)
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
+ --
341
248
 
342
- * Asciidoctor does not support the deprecated index term syntax (`++`
343
- and `+++`)
249
+ .Rendering strings
250
+ --
251
+ To render an AsciiDoc-formatted string:
344
252
 
345
- * Asciidoctor includes a modern default stylesheet based on Foundation.
253
+ puts Asciidoctor.render '*This* is Asciidoctor.'
346
254
 
347
- * Asciidoctor links to, rather than embeds, the default stylesheet into
348
- the document by default (e.g., +linkcss+). To include the default
349
- stylesheet, you can either use the +copycss+ attribute to tell
350
- Asciidoctor to copy it to the output directory, or you can embed it
351
- into the document using the +linkcss!+ attribute. You can also provide
352
- your own stylesheet using the +stylesheet+ attribute.
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:
353
257
 
354
- * Asciidoctor introduces the +hardbreaks+ attribute, which inserts a
355
- line break character after each line of wrapped text
258
+ puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true
356
259
 
357
- * Asciidoctor introduces the +idseparator+ attribute to customize the
358
- separator used in generated section ids (AsciiDoc hardcodes +_+)
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'+:
359
262
 
360
- * Asciidoctor does not support system evaluation macros
263
+ puts Asciidoctor.render '*This* is Asciidoctor.', :doctype => 'inline'
361
264
 
362
- * Asciidoctor does not support displaying comments
265
+ As before, you can also produce DocBook 4.5:
363
266
 
364
- * Asciidoctor properly calculates author initials if attribute reference
365
- is used in name
267
+ puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true,
268
+ :backend => 'docbook'
366
269
 
367
- * Asciidoctor allows the author and revision attributes to be referenced
368
- in subsequent attribute entries in header (unlike AsciiDoc)
270
+ If you don't like the output you see, you can change it.
271
+ Any of it!
272
+ --
369
273
 
370
- * Asciidoctor allows multiple authors to be defined, separated by
371
- semicolon. In DocBook backend, the authors are listed in an
372
- +<authorgroup>+ element.
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.
373
279
 
374
- * Asciidoctor allows the document id to be set using [[id]] above the
375
- document header (adds id attribute to +<body>+ tag)
280
+ puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true,
281
+ :template_dir => 'templates'
376
282
 
377
- * Assigning value to the +listing-caption+ attribute will enable
378
- automatic captions for listings (like examples, tables and figures)
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+.
379
287
 
380
- * The +ifeval::[]+ macro is constrained for the strict purpose of
381
- comparing values of attributes
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.
382
290
 
383
- * The +include::[]+ macro is converted to a link to the target document
384
- when SafeMode is SECURE or greater (this makes for a friendly
385
- experience on GitHub)
291
+ For more usage examples, see the (massive) {tests}[test suite].
292
+ --
386
293
 
387
- * Asciidoctor supports up to 6 section levels (to cover all heading levels in
388
- HTML) whereas AsciiDoc stops at 5; note the 6 section level is only available
389
- using the single-line section title syntax
294
+ == Copyright and Licensing
390
295
 
391
- * Admonition block style is added to class of outer div in html5 backend
392
- in Asciidoctor
296
+ Copyright (C) 2012-2013 Dan Allen and Ryan Waldron.
297
+ Free use of this software is granted under the terms of the MIT License.
393
298
 
394
- * Admonition block caption can be overridden in Asciidoctor using the
395
- +caption+ block attribute
299
+ See the {license}[LICENSE] file for details.
396
300
 
397
- * Asciidoctor will parse attributes in link macros if the +linkattrs+
398
- attribute is set on the document.
301
+ == Authors
399
302
 
400
- If there's a difference you don't see in this list, check the {issues}[issue
401
- tracker] to see if it's an outstanding feature, or file an issue to report the
402
- difference.
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].
304
+
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!
337
+
338
+ == Changelog
339
+
340
+ === v0.1.4 (2013-09-05) - @mojavelinux
341
+
342
+ Performance::
343
+
344
+ * 15% increase in speed compared to 0.1.3
345
+
346
+ Enhancements::
347
+
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)
420
+
421
+ Improvements::
422
+
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.
403
464
 
404
465
  == Contributing
405
466
 
406
- In the spirit of {freesoftware}[free software], 'everyone' is encouraged to
407
- help improve this project.
467
+ In the spirit of {freesoftware}[free software], _everyone_ is encouraged to help improve this project.
408
468
 
409
469
  Here are some ways *you* can contribute:
410
470
 
@@ -413,7 +473,7 @@ Here are some ways *you* can contribute:
413
473
  * by suggesting new features
414
474
  * by writing or editing documentation
415
475
  * by writing specifications
416
- * by writing code -- 'No patch is too small.'
476
+ * by writing code -- _No patch is too small._
417
477
  ** fix typos
418
478
  ** add comments
419
479
  ** clean up inconsistent whitespace
@@ -422,22 +482,17 @@ Here are some ways *you* can contribute:
422
482
  * by fixing {issues}[issues]
423
483
  * by reviewing patches
424
484
 
425
- == Submitting an Issue
485
+ === Submitting an Issue
426
486
 
427
- We use the {issues}[GitHub issue tracker] associated with this project
428
- to track bugs and features. Before submitting a bug report or feature
429
- request, check to make sure it hasn't already been submitted. When
430
- submitting a bug report, please include a {gist}[Gist] that includes any
431
- details that may help reproduce the bug, including your gem version,
432
- Ruby version, and operating system.
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.
433
490
 
434
- Most importantly, since Asciidoctor is a text processor, reproducing
435
- most bugs requires that we have some snippet of text on which
436
- Asciidoctor exhibits the bad behavior.
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.
437
492
 
438
493
  An ideal bug report would include a pull request with failing specs.
439
494
 
440
- == Submitting a Pull Request
495
+ === Submitting a Pull Request
441
496
 
442
497
  . {fork}[Fork the repository].
443
498
  . {branch}[Create a topic branch].
@@ -452,54 +507,9 @@ If your tests fail, return to step 5.
452
507
  . Add, commit, and push your changes.
453
508
  . {pr}[Submit a pull request].
454
509
 
455
- == Supported Ruby Versions
456
-
457
- This library aims to support the following Ruby implementations:
458
-
459
- * Ruby 1.8.7
460
- * Ruby 1.9.3
461
- * Ruby 2.0.0
462
- * JRuby 1.7.4
463
- * Rubinius nightly
464
-
465
- If something doesn't work on one of these interpreters, it should be
466
- considered a bug.
467
-
468
- If you would like this library to support another Ruby version, you may
469
- volunteer to be a maintainer. Being a maintainer entails making sure all
470
- tests run and pass on that implementation. When something breaks on your
471
- implementation, you will be personally responsible for providing patches
472
- in a timely fashion. If critical issues for a particular implementation
473
- exist at the time of a major release, support for that Ruby version may
474
- be dropped.
475
-
476
- == Resources
477
-
478
- Project home page:: {homepage}
479
-
480
- Source repository:: {sources}
481
-
482
- Issue tracker:: {issues}
483
-
484
- Mailinglist / forum:: {forum}
485
-
486
- GitHub organization:: {org}
487
-
488
- == Authors
489
-
490
- *Asciidoctor* was written by https://github.com/mojavelinux[Dan Allen],
491
- https://github.com/erebor[Ryan Waldron],
492
- https://github.com/lightguard[Jason Porter], https://github.com/nickh[Nick
493
- Hengeveld] and {contributors}[other contributors].
494
-
495
- *AsciiDoc* was written by Stuart Rackham and has received contributions
496
- from many other individuals.
497
-
498
- == Copyright
499
-
500
- Copyright (C) 2012-2013 Dan Allen and Ryan Waldron. Free use of this
501
- software is granted under the terms of the MIT License.
502
-
503
- See the {license}[LICENSE] file for details.
510
+ === Supporting Additional Ruby Versions
504
511
 
505
- // vim: tw=72
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.