asciidoctor 0.1.1 → 0.1.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (53) hide show
  1. checksums.yaml +7 -0
  2. data/Gemfile +1 -1
  3. data/LICENSE +2 -2
  4. data/README.adoc +461 -0
  5. data/asciidoctor.gemspec +27 -16
  6. data/compat/asciidoc.conf +139 -0
  7. data/lib/asciidoctor.rb +212 -69
  8. data/lib/asciidoctor/abstract_block.rb +41 -0
  9. data/lib/asciidoctor/abstract_node.rb +128 -81
  10. data/lib/asciidoctor/attribute_list.rb +5 -2
  11. data/lib/asciidoctor/backends/base_template.rb +16 -4
  12. data/lib/asciidoctor/backends/docbook45.rb +112 -42
  13. data/lib/asciidoctor/backends/html5.rb +206 -90
  14. data/lib/asciidoctor/block.rb +5 -5
  15. data/lib/asciidoctor/cli/invoker.rb +38 -34
  16. data/lib/asciidoctor/cli/options.rb +3 -3
  17. data/lib/asciidoctor/document.rb +115 -13
  18. data/lib/asciidoctor/helpers.rb +16 -0
  19. data/lib/asciidoctor/lexer.rb +486 -359
  20. data/lib/asciidoctor/path_resolver.rb +360 -0
  21. data/lib/asciidoctor/reader.rb +122 -23
  22. data/lib/asciidoctor/renderer.rb +1 -33
  23. data/lib/asciidoctor/section.rb +1 -1
  24. data/lib/asciidoctor/substituters.rb +103 -19
  25. data/lib/asciidoctor/version.rb +1 -1
  26. data/man/asciidoctor.1 +6 -6
  27. data/man/asciidoctor.ad +5 -3
  28. data/stylesheets/asciidoctor.css +274 -0
  29. data/test/attributes_test.rb +133 -10
  30. data/test/blocks_test.rb +302 -17
  31. data/test/document_test.rb +269 -6
  32. data/test/fixtures/basic-docinfo.html +1 -0
  33. data/test/fixtures/basic-docinfo.xml +4 -0
  34. data/test/fixtures/basic.asciidoc +4 -0
  35. data/test/fixtures/docinfo.html +1 -0
  36. data/test/fixtures/docinfo.xml +2 -0
  37. data/test/fixtures/include-file.asciidoc +22 -1
  38. data/test/fixtures/stylesheets/custom.css +3 -0
  39. data/test/invoker_test.rb +38 -6
  40. data/test/lexer_test.rb +64 -21
  41. data/test/links_test.rb +4 -0
  42. data/test/lists_test.rb +251 -12
  43. data/test/paragraphs_test.rb +225 -30
  44. data/test/paths_test.rb +174 -0
  45. data/test/reader_test.rb +89 -2
  46. data/test/sections_test.rb +518 -16
  47. data/test/substitutions_test.rb +121 -10
  48. data/test/tables_test.rb +53 -13
  49. data/test/test_helper.rb +2 -2
  50. data/test/text_test.rb +5 -5
  51. metadata +46 -50
  52. data/README.asciidoc +0 -296
  53. data/lib/asciidoctor/errors.rb +0 -5
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: c8a3cff3d36fc7c331d8fa58ec52d3de55c82a01
4
+ data.tar.gz: 4096f0425da556b1c4fb0c808fcf09f2c3848131
5
+ SHA512:
6
+ metadata.gz: 57e7391640b1677fb9d19ecde95af02a6cd53111613d0335e0618901a55dff080aa1bab1290a2f0d591de7ec5db7a8c9e198ba78b386d7c1a3f3b0a3ba5953f6
7
+ data.tar.gz: 6f6f8002274a90e950327b5ecd69d3a05d760f842acc9b70fdce6c17a55e039dcd1c293d06b565047b7c7557c128f375e6ba7d8f37c4e28318207fe6bc002a03
data/Gemfile CHANGED
@@ -1,2 +1,2 @@
1
- source :rubygems
1
+ source 'https://rubygems.org'
2
2
  gemspec
data/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License
2
2
 
3
- Copyright (c) Ryan Waldron
3
+ Copyright (c) Ryan Waldron and Dan Allen
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
18
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
19
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
20
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
- THE SOFTWARE.
21
+ THE SOFTWARE.
@@ -0,0 +1,461 @@
1
+ = Asciidoctor
2
+ :homepage: http://asciidoctor.org
3
+ :asciidoc: http://asciidoc.org
4
+ :sources: http://github.com/asciidoctor/asciidoctor
5
+ :issues: https://github.com/asciidoctor/asciidoctor/issues
6
+ :forum: http://discuss.asciidoctor.org
7
+ :org: http://github.com/asciidoctor
8
+ :contributors: https://github.com/asciidoctor/asciidoctor/graphs/contributors
9
+ :templates: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/backends
10
+ :gitscm-next: https://github.com/github/gitscm-next
11
+ :seed-contribution: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
12
+ :tilt: https://github.com/rtomayko/tilt
13
+ :freesoftware: http://www.fsf.org/licensing/essays/free-sw.html
14
+ :gist: https://gist.github.com
15
+ :fork: http://help.github.com/fork-a-repo/
16
+ :branch: http://learn.github.com/p/branching.html
17
+ :pr: http://help.github.com/send-pull-requests/
18
+ :license: https://github.com/asciidoctor/asciidoctor/blob/master/LICENSE
19
+ :idprefix:
20
+ :idseparator: -
21
+
22
+ {homepage}[Asciidoctor] is a pure Ruby processor for converting
23
+ {asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 4.5
24
+ and other formats. It's http://rubygems.org/gems/asciidoctor[published
25
+ as a RubyGem] and is available under the MIT open source license.
26
+
27
+ image::https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master[Build Status, link="https://travis-ci.org/asciidoctor/asciidoctor"]
28
+
29
+ Asciidoctor uses a set of built-in ERB templates to render the document
30
+ to HTML 5 or DocBook 4.5. We've matched the rendered output as close as
31
+ possible to the default output of the native Python processor. You can
32
+ override this behavior by providing {tilt}[Tilt]-compatible templates.
33
+ See <<usage,Usage>> for more details.
34
+
35
+ Asciidoctor currently works (read as 'tested') with Ruby 1.8.7, Ruby
36
+ 1.9.3, Ruby 2.0.0, JRuby 1.7.2 and Rubinius 1.2.4 (on Linux, Mac and
37
+ Windows). We expect it will work with other versions of Ruby as well and
38
+ would welcome help in testing it out.
39
+
40
+ The initial code from which Asciidoctor started emerged from the
41
+ {gitscm-next}[Git SCM site repo]. Refer to commit history of
42
+ {seed-contribution}[asciidoc.rb] to view the initial contributions and
43
+ individual contributors.
44
+
45
+ The source code can now be found in the {sources}[Asciidoctor source
46
+ repository] on GitHub.
47
+
48
+ == Installation
49
+
50
+ NOTE: We're working hard to make Asciidoctor a drop-in replacement for
51
+ AsciiDoc. We're very close, with over 700 tests that ensure
52
+ compatibility. The march is on towards full compliance and beyond.
53
+
54
+ To install the gem:
55
+
56
+ gem install asciidoctor
57
+
58
+ Or if you prefer bundler, add the asciidoctor gem to your Gemfile,
59
+
60
+ source 'https://rubygems.org'
61
+ gem 'asciidoctor'
62
+
63
+ then install it using bundler:
64
+
65
+ bundle install
66
+
67
+ If you're running Fedora, you can install the gem using yum:
68
+
69
+ sudo yum install rubygem-asciidoctor
70
+
71
+ The benefit of installing the gem via yum is that yum will also install
72
+ Ruby if it's not already on your machine.
73
+
74
+ == Usage
75
+
76
+ Asciidoctor has both a command line interface (CLI) and an API. The CLI
77
+ is a drop-in replacement for the +asciidoc.py+ command from the python
78
+ implementation. The API is intended for integration with other software
79
+ projects and is suitable for server-side applications, such as Rails,
80
+ Sinatra and GitHub.
81
+
82
+ === Command line interface (CLI)
83
+
84
+ After installing the +asciidoctor+ gem, the +asciidoctor+ commandline
85
+ interface should be available on your PATH. To invoke it, simply execute:
86
+
87
+ asciidoctor <asciidoc_file>
88
+
89
+ This will use the built-in defaults for options and create a new file in
90
+ the same directory as the input file, with the same base name, but with
91
+ the .html extension.
92
+
93
+ There are many other options available and full help is provided via:
94
+
95
+ asciidoctor --help
96
+
97
+ or in the http://asciidoctor.org/man/asciidoctor[man page].
98
+
99
+ There is also an +asciidoctor-safe+ command, which turns on safe mode by
100
+ default, preventing access to files outside the parent directory of the
101
+ source file. This mode is very similar to the safe mode of
102
+ +asciidoc.py+.
103
+
104
+ === Ruby API
105
+
106
+ To use Asciidoctor in your application, you first need to require the
107
+ gem:
108
+
109
+ require 'asciidoctor'
110
+
111
+ With that in place, you can start processing AsciiDoc documents.
112
+
113
+ .Loading a document
114
+ To parse a file into an +Asciidoctor::Document+ object:
115
+
116
+ doc = Asciidoctor.load_file('your_file.asciidoc')
117
+
118
+ You can get information about the document:
119
+
120
+ puts doc.doctitle
121
+ puts doc.attributes
122
+
123
+ More than likely, you want to just render the document.
124
+
125
+ .Rendering files
126
+ To render a file containing AsciiDoc markup to HTML 5:
127
+
128
+ Asciidoctor.render_file('your_file.asciidoc', :in_place => true)
129
+
130
+ The command will output to the file +your_file.html+ in the same
131
+ directory. You can render the file to DocBook 4.5 by setting the
132
+ +backend+ attribute to 'docbook':
133
+
134
+ Asciidoctor.render_file('your_file.asciidoc', :in_place => true,
135
+ :attributes => {'backend' => 'docbook'})
136
+
137
+ The command will output to the file +your_file.xml+ in the same
138
+ directory. (If you're on Linux, you can view the file using yelp).
139
+
140
+ .Rendering strings
141
+ To render an AsciiDoc-formatted string:
142
+
143
+ puts Asciidoctor.render('*This* is it.')
144
+
145
+ When rendering a string, the header and footer are excluded by default
146
+ to make Asciidoctor consistent with other lightweight markup engines
147
+ like Markdown. If you want the header and footer, just enable it using
148
+ the +:header_footer+ option:
149
+
150
+ puts Asciidoctor.render('*This* is it.', :header_footer => true)
151
+
152
+ Now you'll get a full HTML 5 file. As before, you can also produce
153
+ DocBook 4.5:
154
+
155
+ puts Asciidoctor.render('*This* is it.', :header_footer => true,
156
+ :attributes => {'backend' => 'docbook'})
157
+
158
+ If you don't like the output you see, you can change it. Any of it!
159
+
160
+ .Custom templates
161
+ Asciidoctor allows you to override the {templates}[built-in templates]
162
+ used to render almost any individual AsciiDoc element. If you provide a
163
+ directory of {tilt}[Tilt]-compatible templates, named in such a way that
164
+ Asciidoctor can figure out which template goes with which element,
165
+ Asciidoctor will use the templates in this directory instead of its
166
+ built-in templates for any elements for which it finds a matching
167
+ template. It will fallback to its default templates for everything else.
168
+
169
+ puts Asciidoctor.render('*This* is it.', :header_footer => true,
170
+ :template_dir => 'templates')
171
+
172
+ The Document and Section templates should begin with +document.+ and
173
+ +section.+, respectively. The file extension is used by Tilt to
174
+ determine which view framework it will use to use to render the
175
+ template. For instance, if you want to write the template in ERB, you'd
176
+ name these two templates +document.html.erb+ and +section.html.erb+. To
177
+ use Haml, you'd name them +document.html.haml+ and +section.html.haml+.
178
+
179
+ Templates for block elements, like a Paragraph or Sidebar, would begin
180
+ with +block_<style>.+. For instance, to override the default Paragraph
181
+ template with an ERB template, put a file named
182
+ +block_paragraph.html.erb+ in the template directory you pass to the
183
+ +Document+ constructor using the +:template_dir+ option.
184
+
185
+ For more usage examples, see the (massive) test suite.
186
+
187
+ == Differences from AsciiDoc
188
+
189
+ While Asciidoctor aims to be compliant with the AsciiDoc syntax, there
190
+ are some differences which are important to keep in mind. In some cases,
191
+ it's to enforce a rule we believe is too lax or ambiguous in AsciiDoc.
192
+ In other cases, it's a tradeoff for speed, smarter processing or a
193
+ feature we just haven't yet implemented. (You'll also notice that
194
+ Asciidoctor executes about 25x as fast as AsciiDoc).
195
+
196
+ Here are the known cases where Asciidoctor differs from AsciiDoc:
197
+
198
+ * Asciidoctor enables safe mode by default when using the API
199
+ (+SafeMode::SECURE+)
200
+
201
+ * Asciidoctor safe mode is even more safe than AsciiDoc's safe mode
202
+
203
+ * Asciidoctor enforces symmetric block delimiters (the length of start
204
+ and end delimiters for a block must match!)
205
+
206
+ * Section title underlines must be within 1 character of the length of
207
+ the title (AsciiDoc allows an offset of 3)
208
+
209
+ * Asciidoctor's default HTML backend matches AsciiDoc's HTML 5 backend
210
+ (whereas XHTML 1.1 is the default HTML backend in AsciiDoc)
211
+
212
+ * Asciidoctor adds viewport meta tag to +<head>+ to optimize mobile viewing
213
+
214
+ * Asciidoctor handles inline anchors more cleanly
215
+
216
+ ** AsciiDoc adds an +<a>+ tag in the line and that markup gets caught in
217
+ the generated id
218
+
219
+ ** Asciidoctor promotes the id of the anchor as the section id
220
+
221
+ * Asciidoctor strips XML entities from the section title before
222
+ generating the id (makes for cleaner section ids)
223
+
224
+ * Asciidoctor uses +<code>+ instead of +<span class="monospace">+ around
225
+ inline literal text in the HTML backend
226
+
227
+ * Asciidoctor does not wrap email next to author name in header in
228
+ angle brackets
229
+
230
+ * Asciidoctor allows email field to be a URL and renders it as such
231
+
232
+ * Asciidoctor is much more lenient about attribute list parsing (double
233
+ quotes are rarely needed, though you may want to keep them for
234
+ compatibility)
235
+
236
+ * Asciidoctor recognizes +opts+ as an alias for the +options+ attribute.
237
+
238
+ * Asciidoctor creates xref labels using the text from the linked section
239
+ title when rendering HTML to match how DocBook works
240
+
241
+ * Asciidoctor allows commas to be used in xref labels, whereas AsciiDoc
242
+ cuts off the label at the location of the first comma
243
+
244
+ * Asciidoctor removes indentation for non-literal paragraphs in a list
245
+ item
246
+ +
247
+ NOTE: In general, Asciidoctor handles whitespace much more intelligently
248
+ +
249
+
250
+ * In Asciidoctor, a horizontal ruler can have attributes
251
+
252
+ * Asciidoctor wraps +<col>+ elements in +<colgroup>+ in tables
253
+
254
+ * Asciidoctor uses +<code>+ around content in monospaced table cells
255
+
256
+ * Asciidoctor skips over line comments in tables, whereas AsciiDoc doesn't
257
+
258
+ * Asciidoctor uses its own API rather than a command line invocation to
259
+ handle table cells that have AsciiDoc content
260
+
261
+ * Asciidoctor supports resolving variables from parent document in table
262
+ cells with AsciiDoc content
263
+
264
+ * AsciiDoc doesn't carry over the doctype attribute passed from the
265
+ commandline when rendering AsciiDoc table cells, whereas Asciidoctor does
266
+
267
+ * Asciidoctor does not require commas between attributes with quoted
268
+ values in a block attribute list
269
+
270
+ * Asciidoctor strips the file extension from the target image when
271
+ generating alt text if no alt text is provided
272
+
273
+ * Asciidoctor reifies the toc in the header of the document instead of
274
+ relying on JavaScript to create it
275
+
276
+ * Asciidoctor sets CSS class on toc element, read from the +toc-class+
277
+ attribute; defaults to toc attribute name (+toc+ or +toc2+).
278
+
279
+ * Asciidoctor honors the id, title, role and levels attributes set on
280
+ the toc macro.
281
+
282
+ * Asciidoctor does not output two tocs with the same id.
283
+
284
+ * Asciidoctor is nice about using a section title syntax inside a
285
+ delimited block by simply ignoring it (AsciiDoc issues warnings)
286
+
287
+ * Asciidoctor honors the alternate style name "discrete" for a floating
288
+ title (i.e., +[discrete]+)
289
+
290
+ * Asciidoctor supports syntax highlighting of listing or literal blocks
291
+ that have the "source" style out of the box
292
+
293
+ ** Asciidoctor honors the source-highlighter values +coderay+ and
294
+ +highlightjs+, using CodeRay or highlight.js, respectively
295
+
296
+ ** Asciidoctor does not currently support Pygments for source
297
+ highlighting
298
+
299
+ * Asciidoctor sets these additional intrinsic attributes
300
+
301
+ +asciidoctor+::
302
+ indicates Asciidoctor is being used; useful for conditional
303
+ processing
304
+
305
+ +asciidoctor-version+::
306
+ indicates which version of Asciidoctor is in use
307
+
308
+ * Asciidoctor does not support deprecated tables (you don't want them
309
+ anyway)
310
+
311
+ * Use can set the extension for icons using the +icontype+ attribute
312
+ (AsciiDoc defaults to .png)
313
+
314
+ * AsciiDoc uses the +<blockquote>+ for the content and +<cite>+ tag for
315
+ attribution title in the HTML output for quote blocks, requiring some
316
+ additional styling to match AsciiDoc
317
+ +
318
+ blockquote.content { padding: 0; margin; 0 }
319
+ cite { color: navy; }
320
+ +
321
+
322
+ * Asciidoctor does not support the deprecated index term syntax (`++`
323
+ and `+++`)
324
+
325
+ * Asciidoctor does not yet ship w/ a stylesheet, must provide your own
326
+ using the +stylesheet+ attribute
327
+
328
+ * Asciidoctor introduces the +hardbreaks+ attribute, which inserts a
329
+ line break character after each line of wrapped text
330
+
331
+ * Asciidoctor introduces the +idseparator+ attribute to customize the
332
+ separator used in generated section ids (AsciiDoc hardcodes +_+)
333
+
334
+ * Asciidoctor does not support system evaluation macros
335
+
336
+ * Asciidoctor does not support displaying comments
337
+
338
+ * Asciidoctor properly calculates author initials if attribute reference
339
+ is used in name
340
+
341
+ * Asciidoctor allows the author and revision attributes to be referenced
342
+ in subsequent attribute entries in header (unlike AsciiDoc)
343
+
344
+ * Asciidoctor allows multiple authors to be defined, separated by
345
+ semicolon. In DocBook backend, the authors are listed in an
346
+ +<authorgroup>+ element.
347
+
348
+ * Asciidoctor allows the document id to be set using [[id]] above the
349
+ document header (adds id attribute to +<body>+ tag)
350
+
351
+ * Assigning value to the +listing-caption+ attribute will enable
352
+ automatic captions for listings (like examples, tables and figures)
353
+
354
+ * The +ifeval::[]+ macro is constrained for the strict purpose of
355
+ comparing values of attributes
356
+
357
+ * The +include::[]+ macro is converted to a link to the target document
358
+ when SafeMode is SECURE or greater (this makes for a friendly
359
+ experience on GitHub)
360
+
361
+ If there's a difference you don't see in this list, check the {issues}[issue
362
+ tracker] to see if it's an outstanding feature, or file an issue to report the
363
+ difference.
364
+
365
+ == Contributing
366
+
367
+ In the spirit of {freesoftware}[free software], 'everyone' is encouraged to
368
+ help improve this project.
369
+
370
+ Here are some ways *you* can contribute:
371
+
372
+ * by using alpha, beta, and prerelease versions
373
+ * by reporting bugs
374
+ * by suggesting new features
375
+ * by writing or editing documentation
376
+ * by writing specifications
377
+ * by writing code -- 'No patch is too small.'
378
+ ** fix typos
379
+ ** add comments
380
+ ** clean up inconsistent whitespace
381
+ ** write tests!
382
+ * by refactoring code
383
+ * by fixing {issues}[issues]
384
+ * by reviewing patches
385
+
386
+ == Submitting an Issue
387
+
388
+ We use the {issues}[GitHub issue tracker] associated with this project
389
+ to track bugs and features. Before submitting a bug report or feature
390
+ request, check to make sure it hasn't already been submitted. When
391
+ submitting a bug report, please include a {gist}[Gist] that includes any
392
+ details that may help reproduce the bug, including your gem version,
393
+ Ruby version, and operating system.
394
+
395
+ Most importantly, since Asciidoctor is a text processor, reproducing
396
+ most bugs requires that we have some snippet of text on which
397
+ Asciidoctor exhibits the bad behavior.
398
+
399
+ An ideal bug report would include a pull request with failing specs.
400
+
401
+ == Submitting a Pull Request
402
+
403
+ . {fork}[Fork the repository].
404
+ . {branch}[Create a topic branch].
405
+ . Add tests for your unimplemented feature or bug fix.
406
+ . Run +bundle exec rake+.
407
+ If your tests pass, return to step 3.
408
+ . Implement your feature or bug fix.
409
+ . Run +bundle exec rake+.
410
+ If your tests fail, return to step 5.
411
+ . Add documentation for your feature or bug fix.
412
+ . If your changes are not 100% documented, go back to step 7.
413
+ . Add, commit, and push your changes.
414
+ . {pr}[Submit a pull request].
415
+
416
+ == Supported Ruby Versions
417
+
418
+ This library aims to support the following Ruby implementations:
419
+
420
+ * Ruby 1.8.7
421
+ * Ruby 1.9.3
422
+ * Ruby 2.0.0
423
+ * JRuby 1.7.2
424
+ * Rubinius 1.2.4
425
+
426
+ If something doesn't work on one of these interpreters, it should be
427
+ considered a bug.
428
+
429
+ If you would like this library to support another Ruby version, you may
430
+ volunteer to be a maintainer. Being a maintainer entails making sure all
431
+ tests run and pass on that implementation. When something breaks on your
432
+ implementation, you will be personally responsible for providing patches
433
+ in a timely fashion. If critical issues for a particular implementation
434
+ exist at the time of a major release, support for that Ruby version may
435
+ be dropped.
436
+
437
+ == Resources
438
+
439
+ Project home page:: {homepage}
440
+
441
+ Source repository:: {sources}
442
+
443
+ Issue tracker:: {issues}
444
+
445
+ Mailinglist / forum:: {forum}
446
+
447
+ GitHub organization:: {org}
448
+
449
+ == Authors
450
+
451
+ *Asciidoctor* was written by Ryan Waldron, Dan Allen and
452
+ {contributors}[other contributors].
453
+
454
+ *AsciiDoc* was written by Stuart Rackham and has received contributions
455
+ from many other individuals.
456
+
457
+ == Copyright
458
+
459
+ Copyright (C) 2012-2013 Ryan Waldron and Dan Allen. See {license}[LICENSE] for details.
460
+
461
+ // vim: tw=72