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.
- checksums.yaml +4 -4
- data/CHANGELOG.adoc +387 -0
- data/README.adoc +358 -348
- data/asciidoctor.gemspec +30 -9
- data/bin/asciidoctor +3 -0
- data/bin/asciidoctor-safe +3 -0
- data/compat/asciidoc.conf +76 -4
- data/lib/asciidoctor.rb +174 -79
- data/lib/asciidoctor/abstract_block.rb +131 -101
- data/lib/asciidoctor/abstract_node.rb +108 -26
- data/lib/asciidoctor/attribute_list.rb +1 -1
- data/lib/asciidoctor/backends/_stylesheets.rb +204 -62
- data/lib/asciidoctor/backends/base_template.rb +11 -22
- data/lib/asciidoctor/backends/docbook45.rb +158 -163
- data/lib/asciidoctor/backends/docbook5.rb +103 -0
- data/lib/asciidoctor/backends/html5.rb +662 -445
- data/lib/asciidoctor/block.rb +54 -44
- data/lib/asciidoctor/cli/invoker.rb +41 -20
- data/lib/asciidoctor/cli/options.rb +66 -20
- data/lib/asciidoctor/debug.rb +1 -1
- data/lib/asciidoctor/document.rb +265 -100
- data/lib/asciidoctor/extensions.rb +443 -0
- data/lib/asciidoctor/helpers.rb +38 -6
- data/lib/asciidoctor/inline.rb +5 -5
- data/lib/asciidoctor/lexer.rb +532 -250
- data/lib/asciidoctor/{list_item.rb → list.rb} +33 -13
- data/lib/asciidoctor/path_resolver.rb +28 -2
- data/lib/asciidoctor/reader.rb +814 -455
- data/lib/asciidoctor/renderer.rb +128 -42
- data/lib/asciidoctor/section.rb +55 -41
- data/lib/asciidoctor/substituters.rb +380 -107
- data/lib/asciidoctor/table.rb +40 -30
- data/lib/asciidoctor/version.rb +1 -1
- data/man/asciidoctor.1 +32 -96
- data/man/{asciidoctor.ad → asciidoctor.adoc} +57 -48
- data/test/attributes_test.rb +200 -27
- data/test/blocks_test.rb +361 -22
- data/test/document_test.rb +496 -81
- data/test/extensions_test.rb +448 -0
- data/test/fixtures/basic-docinfo-footer.html +6 -0
- data/test/fixtures/basic-docinfo-footer.xml +8 -0
- data/test/fixtures/basic-docinfo.xml +3 -3
- data/test/fixtures/basic.asciidoc +1 -0
- data/test/fixtures/child-include.adoc +5 -0
- data/test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml +6 -0
- data/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml +1 -0
- data/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml +3 -0
- data/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml +5 -0
- data/test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim +6 -0
- data/test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim +3 -0
- data/test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim +5 -0
- data/test/fixtures/docinfo-footer.html +1 -0
- data/test/fixtures/docinfo-footer.xml +9 -0
- data/test/fixtures/docinfo.xml +1 -0
- data/test/fixtures/grandchild-include.adoc +3 -0
- data/test/fixtures/parent-include-restricted.adoc +5 -0
- data/test/fixtures/parent-include.adoc +5 -0
- data/test/invoker_test.rb +82 -8
- data/test/lexer_test.rb +21 -3
- data/test/links_test.rb +34 -2
- data/test/lists_test.rb +304 -7
- data/test/options_test.rb +19 -3
- data/test/paragraphs_test.rb +13 -0
- data/test/paths_test.rb +22 -0
- data/test/preamble_test.rb +20 -0
- data/test/reader_test.rb +1096 -644
- data/test/renderer_test.rb +152 -12
- data/test/sections_test.rb +417 -76
- data/test/substitutions_test.rb +339 -138
- data/test/tables_test.rb +109 -4
- data/test/test_helper.rb +79 -13
- data/test/text_test.rb +111 -11
- metadata +54 -18
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4823a22cab8ddb3e6109152db26c0f10a0efec3b
|
|
4
|
+
data.tar.gz: 697bd0c123fbdf19843dcc6e5f7dceef9a9c5f89
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 06a29332c4eb1754fb86d0facbdefa0fdefd554791d949e2501e8df14f03fc2e4a7fc3685aa69ec5c0105854122970eb79e80a48e3b1d7b8fe586771dbb40ca6
|
|
7
|
+
data.tar.gz: 0030da2c1b4632a249d3a2a47f17b1ffd5bbde8107f3fae802f868226a7c9b1419a5ffb31a96296e1b3ce416615cbaa0790a8444aa290a0fecf2385d5b51721f
|
data/CHANGELOG.adoc
ADDED
|
@@ -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.
|
data/README.adoc
CHANGED
|
@@ -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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-
|
|
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
|
-
|
|
62
|
+
== Operating Systems
|
|
123
63
|
|
|
124
|
-
|
|
125
|
-
puts doc.attributes
|
|
64
|
+
Asciidoctor works on Linux, Mac and Windows.
|
|
126
65
|
|
|
127
|
-
|
|
66
|
+
== Dependency and Configuration Requirements
|
|
128
67
|
|
|
129
|
-
|
|
130
|
-
To render a file containing AsciiDoc markup to HTML 5:
|
|
68
|
+
Asciidoctor requires one of the following implementations of Ruby:
|
|
131
69
|
|
|
132
|
-
|
|
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
|
-
|
|
135
|
-
|
|
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
|
-
|
|
139
|
-
:attributes => {'backend' => 'docbook'})
|
|
79
|
+
// QUESTION What is considered configuration information?
|
|
140
80
|
|
|
141
|
-
|
|
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
|
-
|
|
145
|
-
|
|
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
|
-
|
|
88
|
+
The latest source code is located in the {sources}[Asciidoctor git repository] on GitHub.
|
|
148
89
|
|
|
149
|
-
|
|
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
|
-
|
|
92
|
+
Asciidoctor can be installed via the +gem+ command, bundler, or popular Linux package managers.
|
|
155
93
|
|
|
156
|
-
|
|
157
|
-
DocBook 4.5:
|
|
94
|
+
=== gem install
|
|
158
95
|
|
|
159
|
-
|
|
160
|
-
:attributes => {'backend' => 'docbook'})
|
|
96
|
+
To install Asciidoctor using the +gem+ command:
|
|
161
97
|
|
|
162
|
-
|
|
98
|
+
. Open a terminal
|
|
99
|
+
. Type the +gem+ command
|
|
163
100
|
|
|
164
|
-
|
|
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
|
-
|
|
174
|
-
:template_dir => 'templates')
|
|
103
|
+
=== bundle install (Bundler)
|
|
175
104
|
|
|
176
|
-
|
|
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
|
-
|
|
184
|
-
|
|
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
|
-
|
|
110
|
+
source 'https://rubygems.org'
|
|
111
|
+
gem 'asciidoctor'
|
|
190
112
|
|
|
191
|
-
|
|
113
|
+
. Save the Gemfile
|
|
114
|
+
. Open a terminal
|
|
115
|
+
. Install the gem with bundler
|
|
192
116
|
|
|
193
|
-
|
|
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
|
-
|
|
119
|
+
=== yum install (Fedora)
|
|
120
|
+
|
|
121
|
+
To install Asciidoctor on Fedora 17 or greater:
|
|
201
122
|
|
|
202
|
-
|
|
203
|
-
|
|
123
|
+
. Open a terminal
|
|
124
|
+
. Type the +yum+ command
|
|
125
|
+
|
|
126
|
+
$> sudo yum install rubygem-asciidoctor
|
|
204
127
|
|
|
205
|
-
|
|
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
|
-
|
|
208
|
-
|
|
130
|
+
=== apt-get install (Debian, Ubuntu)
|
|
131
|
+
|
|
132
|
+
To install Asciidoctor on Debian Sid or Ubuntu Saucy or greater:
|
|
209
133
|
|
|
210
|
-
|
|
211
|
-
|
|
134
|
+
. Open a terminal
|
|
135
|
+
. Type the +apt-get+ command
|
|
136
|
+
|
|
137
|
+
$> sudo apt-get install asciidoctor
|
|
212
138
|
|
|
213
|
-
|
|
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
|
-
|
|
141
|
+
=== Other installation options
|
|
217
142
|
|
|
218
|
-
*
|
|
143
|
+
* {toolchain}[Installing the Asciidoctor toolchain]
|
|
144
|
+
* {install-mac}[Installing Asciidoctor on Mac OS X]
|
|
219
145
|
|
|
220
|
-
|
|
221
|
-
the generated id
|
|
146
|
+
== Upgrading
|
|
222
147
|
|
|
223
|
-
|
|
148
|
+
If you have an earlier version of Asciidoctor installed, you can update it using the +gem+ command:
|
|
224
149
|
|
|
225
|
-
|
|
226
|
-
generating the id (makes for cleaner section ids)
|
|
150
|
+
$> gem update asciidoctor
|
|
227
151
|
|
|
228
|
-
|
|
229
|
-
|
|
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
|
-
|
|
232
|
-
|
|
157
|
+
$> gem cleanup asciidoctor
|
|
158
|
+
====
|
|
233
159
|
|
|
234
|
-
|
|
160
|
+
On Fedora, you can update it using:
|
|
235
161
|
|
|
236
|
-
|
|
237
|
-
quotes are rarely needed, though you may want to keep them for
|
|
238
|
-
compatibility)
|
|
162
|
+
$> sudo yum update rubygem-asciidoctor
|
|
239
163
|
|
|
240
|
-
|
|
241
|
-
|
|
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
|
-
|
|
167
|
+
On Debian or Ubuntu, you can update it using:
|
|
244
168
|
|
|
245
|
-
|
|
246
|
-
title when rendering HTML to match how DocBook works
|
|
169
|
+
$> sudo apt-get upgrade asciidoctor
|
|
247
170
|
|
|
248
|
-
|
|
249
|
-
|
|
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
|
-
|
|
252
|
-
item
|
|
253
|
-
+
|
|
254
|
-
NOTE: In general, Asciidoctor handles whitespace much more intelligently
|
|
255
|
-
+
|
|
175
|
+
== Usage
|
|
256
176
|
|
|
257
|
-
|
|
258
|
-
|
|
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
|
-
|
|
180
|
+
$> asciidoctor --version
|
|
181
|
+
Asciidoctor 0.1.4 [http://asciidoctor.org]
|
|
261
182
|
|
|
262
|
-
|
|
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
|
-
|
|
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
|
-
|
|
190
|
+
=== Command line interface (CLI)
|
|
267
191
|
|
|
268
|
-
|
|
269
|
-
|
|
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
|
-
|
|
272
|
-
cells with AsciiDoc content
|
|
195
|
+
asciidoctor <asciidoc_file>
|
|
273
196
|
|
|
274
|
-
|
|
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
|
-
|
|
278
|
-
values in a block attribute list
|
|
199
|
+
There are many other options available and full help is provided via:
|
|
279
200
|
|
|
280
|
-
|
|
281
|
-
generating alt text if no alt text is provided
|
|
201
|
+
asciidoctor --help
|
|
282
202
|
|
|
283
|
-
|
|
284
|
-
relying on JavaScript to create it
|
|
203
|
+
or in the {man}[man page].
|
|
285
204
|
|
|
286
|
-
|
|
287
|
-
|
|
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
|
-
|
|
290
|
-
the toc macro.
|
|
208
|
+
Additional documentation:
|
|
291
209
|
|
|
292
|
-
*
|
|
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
|
-
|
|
295
|
-
delimited block by simply ignoring it (AsciiDoc issues warnings)
|
|
213
|
+
=== Ruby API
|
|
296
214
|
|
|
297
|
-
|
|
298
|
-
title (i.e., +[discrete]+)
|
|
215
|
+
To use Asciidoctor in your application, you first need to require the gem:
|
|
299
216
|
|
|
300
|
-
|
|
217
|
+
require 'asciidoctor'
|
|
301
218
|
|
|
302
|
-
|
|
303
|
-
that have the "source" style out of the box
|
|
219
|
+
With that in place, you can start processing AsciiDoc documents.
|
|
304
220
|
|
|
305
|
-
|
|
306
|
-
|
|
221
|
+
.Loading a document
|
|
222
|
+
To parse a file into an +Asciidoctor::Document+ object:
|
|
307
223
|
|
|
308
|
-
|
|
309
|
-
highlighting
|
|
224
|
+
doc = Asciidoctor.load_file 'sample.adoc'
|
|
310
225
|
|
|
311
|
-
|
|
312
|
-
is specified
|
|
226
|
+
You can get information about the document:
|
|
313
227
|
|
|
314
|
-
|
|
228
|
+
puts doc.doctitle
|
|
229
|
+
puts doc.attributes
|
|
315
230
|
|
|
316
|
-
|
|
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
|
-
|
|
321
|
-
|
|
233
|
+
.Rendering files
|
|
234
|
+
--
|
|
235
|
+
To render a file containing AsciiDoc markup to HTML 5, use:
|
|
322
236
|
|
|
323
|
-
|
|
324
|
-
anyway)
|
|
237
|
+
Asciidoctor.render_file 'sample.adoc', :in_place => true
|
|
325
238
|
|
|
326
|
-
|
|
327
|
-
(AsciiDoc defaults to .png)
|
|
239
|
+
The command will output to the file +sample.html+ in the same directory.
|
|
328
240
|
|
|
329
|
-
|
|
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
|
-
|
|
338
|
-
for a blockquote paragraph.
|
|
243
|
+
Asciidoctor.render_file 'sample.adoc', :in_place => true, :backend => 'docbook'
|
|
339
244
|
|
|
340
|
-
|
|
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
|
-
|
|
343
|
-
|
|
249
|
+
.Rendering strings
|
|
250
|
+
--
|
|
251
|
+
To render an AsciiDoc-formatted string:
|
|
344
252
|
|
|
345
|
-
|
|
253
|
+
puts Asciidoctor.render '*This* is Asciidoctor.'
|
|
346
254
|
|
|
347
|
-
|
|
348
|
-
|
|
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
|
-
|
|
355
|
-
line break character after each line of wrapped text
|
|
258
|
+
puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true
|
|
356
259
|
|
|
357
|
-
|
|
358
|
-
|
|
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
|
-
|
|
263
|
+
puts Asciidoctor.render '*This* is Asciidoctor.', :doctype => 'inline'
|
|
361
264
|
|
|
362
|
-
|
|
265
|
+
As before, you can also produce DocBook 4.5:
|
|
363
266
|
|
|
364
|
-
|
|
365
|
-
|
|
267
|
+
puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true,
|
|
268
|
+
:backend => 'docbook'
|
|
366
269
|
|
|
367
|
-
|
|
368
|
-
|
|
270
|
+
If you don't like the output you see, you can change it.
|
|
271
|
+
Any of it!
|
|
272
|
+
--
|
|
369
273
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
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
|
-
|
|
375
|
-
|
|
280
|
+
puts Asciidoctor.render '*This* is Asciidoctor.', :header_footer => true,
|
|
281
|
+
:template_dir => 'templates'
|
|
376
282
|
|
|
377
|
-
|
|
378
|
-
|
|
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
|
-
|
|
381
|
-
|
|
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
|
-
|
|
384
|
-
|
|
385
|
-
experience on GitHub)
|
|
291
|
+
For more usage examples, see the (massive) {tests}[test suite].
|
|
292
|
+
--
|
|
386
293
|
|
|
387
|
-
|
|
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
|
-
|
|
392
|
-
|
|
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
|
-
|
|
395
|
-
+caption+ block attribute
|
|
299
|
+
See the {license}[LICENSE] file for details.
|
|
396
300
|
|
|
397
|
-
|
|
398
|
-
attribute is set on the document.
|
|
301
|
+
== Authors
|
|
399
302
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
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],
|
|
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 --
|
|
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
|
-
|
|
485
|
+
=== Submitting an Issue
|
|
426
486
|
|
|
427
|
-
We use the {issues}[
|
|
428
|
-
|
|
429
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|