asciidoctor 0.1.1 → 0.1.2

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 (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
@@ -1,296 +0,0 @@
1
- Asciidoctor
2
- ===========
3
- :asciidoctor: http://asciidoctor.org
4
- :asciidoctor-source: http://github.com/asciidoctor/asciidoctor
5
- :asciidoc: http://asciidoc.org
6
- :gitscm-next: https://github.com/github/gitscm-next
7
- :asciidoctor-seed: https://github.com/github/gitscm-next/commits/master/lib/asciidoc.rb
8
- :templates: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/backends
9
- :tilt: https://github.com/rtomayko/tilt
10
- :freesoftware: http://www.fsf.org/licensing/essays/free-sw.html
11
- :issues: https://github.com/asciidoctor/asciidoctor/issues
12
- :gist: https://gist.github.com
13
- :fork: http://help.github.com/fork-a-repo/
14
- :branch: http://learn.github.com/p/branching.html
15
- :pr: http://help.github.com/send-pull-requests/
16
- :license: https://github.com/asciidoctor/asciidoctor/blob/master/LICENSE
17
- :idprefix:
18
-
19
- {asciidoctor}[Asciidoctor] is a pure Ruby processor for converting
20
- {asciidoc}[AsciiDoc] source files and strings into HTML 5, DocBook 4.5
21
- and other formats. It's
22
- http://rubygems.org/gems/asciidoctor[published as a RubyGem] and is
23
- available under the MIT open source license.
24
-
25
- image::https://travis-ci.org/asciidoctor/asciidoctor.png?branch=master["Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor"]
26
-
27
- Asciidoctor uses a set of built-in ERB templates to render the document
28
- to HTML 5 or DocBook 4.5. We've matched the rendered output as close as
29
- possible to the default output of the native Python processor. You can
30
- override this behavior by providing {tilt}[Tilt]-compatible templates.
31
- See the xref:usage[Usage section] for more details.
32
-
33
- Asciidoctor currently works (read as 'tested') with Ruby 1.8.7, Ruby
34
- 1.9.3 and JRuby 1.7.2 (on Linux, Mac and Windows). We expect it will
35
- work with other versions of Ruby as well and would welcome help in
36
- testing it out.
37
-
38
- The initial code from which Asciidoctor started emerged from the
39
- {gitscm-next}[Git SCM site repo]. Refer to commit history of
40
- {asciidoctor-seed}[asciidoc.rb] to view the initial contributions and
41
- individual contributors.
42
-
43
- The source code can now be found in the {asciidoctor-source}[Asciidoctor
44
- source repository] on GitHub.
45
-
46
- == Installation
47
-
48
- NOTE: We are working hard to make Asciidoctor a drop-in replacement for
49
- AsciiDoc. We're very close, with nearly 600 tests that ensure
50
- compatibility. The march is on towards full compliance and beyond.
51
-
52
- To install the gem:
53
-
54
- gem install asciidoctor
55
-
56
- Or if you prefer bundler:
57
-
58
- bundle install asciidoctor
59
-
60
- == Usage
61
-
62
- Asciidoctor has both a command line interface (CLI) and an API. The
63
- CLI is a drop-in replacement for the `asciidoc.py` command from the
64
- python implementation. The API is intended for integration with other
65
- software projects and is suitable for server-side applications, such
66
- as Rails, Sinatra and GitHub.
67
-
68
- === Command line interface (CLI)
69
-
70
- After installing the `asciidoctor` gem, the `asciidoctor` commandline
71
- interface should be available on your PATH after installing the gem.
72
- To invoke it, simply execute:
73
-
74
- asciidoctor <asciidoc_file>
75
-
76
- This will use the built-in defaults for options and create a new file
77
- in the same directory as the input file, with the same base name, but
78
- with the .html extension.
79
-
80
- There are many other options available and full help is provided via:
81
-
82
- asciidoctor --help
83
-
84
- or in the http://asciidoctor.org/man/asciidoctor[man page].
85
-
86
- There is also an `asciidoctor-safe` command, which turns on safe mode
87
- by default, preventing access to files outside the parent directory of
88
- the source file. This mode is very similar to the safe mode of `asciidoc.py`.
89
-
90
- === Ruby API
91
-
92
- To use Asciidoctor in your application, you first need to require the
93
- gem:
94
-
95
- require 'asciidoctor'
96
-
97
- With that in place, you can start processing AsciiDoc documents.
98
-
99
- .Loading a document
100
- To parse a file into an `Asciidoctor::Document` object:
101
-
102
- doc = Asciidoctor.load_file('your_file.asciidoc')
103
-
104
- You can get information about the document:
105
-
106
- puts doc.doctitle
107
- puts doc.attributes
108
-
109
- More than likely, you want to just render the document.
110
-
111
- .Rendering files
112
- To render a file containing AsciiDoc markup to HTML 5:
113
-
114
- Asciidoctor.render_file('your_file.asciidoc', :in_place => true)
115
-
116
- The command will output to the file `your_file.html` in the same
117
- directory. You can render the file to DocBook 4.5 by setting the
118
- `backend` attribute to 'docbook':
119
-
120
- Asciidoctor.render_file('your_file.asciidoc', :in_place => true,
121
- :attributes => {'backend' => 'docbook'})
122
-
123
- The command will output to the file `your_file.xml` in the same
124
- directory. (If you're on Linux, you can view the file using yelp).
125
-
126
- .Rendering strings
127
- To render an AsciiDoc-formatted string:
128
-
129
- puts Asciidoctor.render('*This* is it.')
130
-
131
- When rendering a string, the header and footer are excluded by default
132
- to make Asciidoctor consistent with other lightweight markup engines
133
- like Markdown. If you want the header and footer, just declare it as
134
- an option:
135
-
136
- puts Asciidoctor.render('*This* is it.', :header_footer => true)
137
-
138
- Now you'll get a full HTML 5 file. As before, you can also produce
139
- DocBook 4.5:
140
-
141
- puts Asciidoctor.render('*This* is it.', :header_footer => true,
142
- :attributes => {'backend' => 'docbook'})
143
-
144
- If you don't like the output you see, you can change it. Any of it!
145
-
146
- .Custom templates
147
- Asciidoctor allows you to override the {templates}[built-in templates]
148
- used to render almost any individual AsciiDoc element. If you provide a
149
- directory of {tilt}[Tilt]-compatible templates, named in such a way that
150
- Asciidoctor can figure out which template goes with which element,
151
- Asciidoctor will use the templates in this directory instead of its
152
- built-in templates for any elements for which it finds a matching
153
- template. It will fallback to its default templates for everything else.
154
-
155
- puts Asciidoctor.render('*This* is it.', :header_footer => true,
156
- :template_dir => 'templates')
157
-
158
- The Document and Section templates should begin with `document.` and
159
- `section.`, respectively. The file extension is used by Tilt to
160
- determine which view framework it will use to use to render the
161
- template. For instance, if you want to write the template in ERB, you'd
162
- name these two templates `document.html.erb` and `section.html.erb`. To
163
- use Haml, you'd name them `document.html.haml` and `section.html.haml`.
164
-
165
- Templates for block elements, like a Paragraph or Sidebar, would begin
166
- with `block_<style>.`. For instance, to override the default Paragraph
167
- template with an ERB template, put a file named
168
- `block_paragraph.html.erb` in the template directory you pass to the
169
- `Document` constructor using the `template_dir` option.
170
-
171
- For more usage examples, see the (massive) test suite.
172
-
173
- == Differences from AsciiDoc
174
-
175
- While Asciidoctor aims to be compliant with the AsciiDoc syntax, there are some differences which are important to keep in mind. In some cases, it's to enforce a rule we believe is too lax or ambiguous in AsciiDoc. In other cases, it's a tradeoff for speed, smarter processing or a feature we just haven't yet implemented. (You'll also notice that Asciidoctor is about 20x faster than AsciiDoc).
176
-
177
- Here are the known cases where Asciidoctor differs from AsciiDoc:
178
-
179
- * In Asciidoctor, safe mode is on by default when using the API (safe mode level SECURE),
180
- * Asciidoctor safe mode is even more safe than AsciiDoc's safe mode
181
- * Asciidoctor enforces symmetric block delimiters (the length of start and end delimiters for a block must match)
182
- * Section title underlines must be within +/- 1 of the length of the title (AsciiDoc is +/- 3)
183
- * Asciidoctor's default HTML backend matches AsciiDoc's HTML 5 backend (whereas XHTML 1.1 is the default HTML backend in AsciiDoc)
184
- * Asciidoctor handles inline anchors more cleanly
185
- ** AsciiDoc adds an `<a>` tag in the line and that markup gets caught in the generated id
186
- ** Asciidoctor promotes the id of the anchor as the section id
187
- * Asciidoctor strips XML entities from the section title before generating the id (makes for cleaner section ids)
188
- * Asciidoctor use `<tt>` instead of `<span class="monospace">` around inline literal text in the HTML backend
189
- * Asciidoctor is much more lenient about attribute list parsing (double quotes are rarely needed)
190
- * Asciidoctor creates xref labels using the text from the linked section title when rendering HTML to match how DocBook works
191
- * Asciidoctor allows commas to be used in xref labels, whereas AsciiDoc cuts off the label at the location of the first comma
192
- * Asciidoctor removes indentation for non-literal paragraphs in a list item
193
- ** In general, Asciidoctor handles whitespace much more intelligently
194
- * In Asciidoctor, a ruler can have attributes
195
- * Asciidoctor skips over line comments in tables, whereas AsciiDoc does not
196
- * Asciidoctor uses its own API rather than a command line invocation to handle table cells that have AsciiDoc content
197
- * Asciidoctor supports resolving variables from parent document in table cells with AsciiDoc content
198
- * AsciiDoc doesn't carry over the doctype attribute passed from the commandline when rendering AsciiDoc content cells, whereas Asciidoctor does
199
- * Asciidoctor strips the file extension from the target image when generating alt text if no alt text is provided
200
- * Asciidoctor reifies the toc in the header of the document instead of relying on JavaScript to create it
201
- * Asciidoctor is nice about using a section title syntax inside a delimited block by simply ignoring it (AsciiDoc issues warnings)
202
- * Asciidoctor honors the alternate style name "discrete" for a floating title (i.e., [discrete])
203
- * Asciidoctor supports syntax highlighting of listing or literal blocks that have the "source" style out of the box
204
- ** Asciidoctor honors the source-highlighter values `coderay` and `highlightjs`, using CodeRay or highlight.js, respectively
205
- ** Asciidoctor does not currently support Pygments for source highlighting
206
- * Asciidoctor sets these additional intrinsic attributes
207
- `asciidoctor`:: indicates Asciidoctor is being used; useful for conditional processing
208
- `asciidoctor-version`:: indicates which version of Asciidoctor is in use
209
- * Asciidoctor does not support deprecated tables (you don't want them anyway)
210
-
211
- If there's a difference you don't see in this list, check the {issues}[issue tracker] to see if it's an outstanding feature, or file an issue to report the difference.
212
-
213
- == Contributing
214
-
215
- In the spirit of {freesoftware}[free software], 'everyone' is
216
- encouraged to help improve this project.
217
-
218
- Here are some ways *you* can contribute:
219
-
220
- * by using alpha, beta, and prerelease versions
221
- * by reporting bugs
222
- * by suggesting new features
223
- * by writing or editing documentation
224
- * by writing specifications
225
- * by writing code -- 'No patch is too small.'
226
- ** fix typos
227
- ** add comments
228
- ** clean up inconsistent whitespace
229
- ** write tests!
230
- * by refactoring code
231
- * by fixing {issues}[issues]
232
- * by reviewing patches
233
-
234
- == Submitting an Issue
235
-
236
- We use the {issues}[GitHub issue tracker] associated with this project
237
- to track bugs and features. Before submitting a bug report or feature
238
- request, check to make sure it hasn't already been submitted. When
239
- submitting a bug report, please include a {gist}[Gist] that includes
240
- any details that may help reproduce the bug, including your gem
241
- version, Ruby version, and operating system.
242
-
243
- Most importantly, since Asciidoctor is a text processor, reproducing
244
- most bugs requires that we have some snippet of text on which
245
- Asciidoctor exhibits the bad behavior.
246
-
247
- An ideal bug report would include a pull request with failing specs.
248
-
249
- == Submitting a Pull Request
250
-
251
- . {fork}[Fork the repository].
252
- . {branch}[Create a topic branch].
253
- . Add tests for your unimplemented feature or bug fix.
254
- . Run `bundle exec rake`. If your tests pass, return to step 3.
255
- . Implement your feature or bug fix.
256
- . Run `bundle exec rake`. If your tests fail, return to step 5.
257
- . Add documentation for your feature or bug fix.
258
- . If your changes are not 100% documented, go back to step 7.
259
- . Add, commit, and push your changes.
260
- . {pr}[Submit a pull request].
261
-
262
- == Supported Ruby Versions
263
-
264
- This library aims to support the following Ruby implementations:
265
-
266
- * Ruby 1.8.7
267
- * Ruby 1.9.3
268
- * JRuby 1.7.2
269
- * Rubinius 1.2.4
270
-
271
- If something doesn't work on one of these interpreters, it should be
272
- considered a bug.
273
-
274
- If you would like this library to support another Ruby version, you
275
- may volunteer to be a maintainer. Being a maintainer entails making
276
- sure all tests run and pass on that implementation. When something
277
- breaks on your implementation, you will be personally responsible for
278
- providing patches in a timely fashion. If critical issues for a
279
- particular implementation exist at the time of a major release,
280
- support for that Ruby version may be dropped.
281
-
282
- == Authors
283
-
284
- *Asciidoctor* was written by Ryan Waldron, Dan Allen and
285
- https://github.com/asciidoctor/asciidoctor/graphs/contributors[other
286
- contributors].
287
-
288
- *AsciiDoc* was written by Stuart Rackham and has received
289
- contributions from many other individuals.
290
-
291
- == Copyright
292
-
293
- Copyright (C) 2012 Ryan Waldron.
294
- See {license}[LICENSE] for details.
295
-
296
- // vim: tw=72
@@ -1,5 +0,0 @@
1
- # Base project exception
2
- module Asciidoctor
3
- class ProjectError < StandardError; end
4
- end
5
-