asciidoctor 1.5.4 → 1.5.5
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 +72 -5
- data/CONTRIBUTING.adoc +3 -3
- data/Gemfile +23 -0
- data/README-fr.adoc +416 -0
- data/README-jp.adoc +395 -0
- data/README-zh_CN.adoc +414 -0
- data/README.adoc +134 -72
- data/asciidoctor.gemspec +49 -0
- data/data/locale/attributes.adoc +470 -0
- data/data/stylesheets/asciidoctor-default.css +6 -5
- data/lib/asciidoctor.rb +22 -19
- data/lib/asciidoctor/abstract_block.rb +20 -10
- data/lib/asciidoctor/abstract_node.rb +3 -14
- data/lib/asciidoctor/cli/invoker.rb +5 -4
- data/lib/asciidoctor/cli/options.rb +1 -1
- data/lib/asciidoctor/converter/docbook5.rb +1 -1
- data/lib/asciidoctor/converter/factory.rb +1 -5
- data/lib/asciidoctor/converter/html5.rb +36 -31
- data/lib/asciidoctor/converter/manpage.rb +14 -9
- data/lib/asciidoctor/converter/template.rb +8 -4
- data/lib/asciidoctor/core_ext.rb +7 -6
- data/lib/asciidoctor/core_ext/{string → 1.8.7/string}/chr.rb +1 -1
- data/lib/asciidoctor/core_ext/1.8.7/string/limit.rb +28 -0
- data/lib/asciidoctor/core_ext/{symbol → 1.8.7/symbol}/length.rb +1 -1
- data/lib/asciidoctor/core_ext/nil_or_empty.rb +23 -0
- data/lib/asciidoctor/core_ext/string/limit.rb +10 -0
- data/lib/asciidoctor/document.rb +33 -26
- data/lib/asciidoctor/extensions.rb +16 -16
- data/lib/asciidoctor/helpers.rb +1 -1
- data/lib/asciidoctor/list.rb +3 -0
- data/lib/asciidoctor/parser.rb +47 -43
- data/lib/asciidoctor/path_resolver.rb +3 -1
- data/lib/asciidoctor/reader.rb +15 -14
- data/lib/asciidoctor/section.rb +2 -2
- data/lib/asciidoctor/stylesheets.rb +2 -1
- data/lib/asciidoctor/substitutors.rb +44 -46
- data/lib/asciidoctor/table.rb +41 -38
- data/lib/asciidoctor/version.rb +1 -1
- data/man/asciidoctor.1 +11 -4
- data/man/asciidoctor.adoc +7 -1
- data/test/attributes_test.rb +52 -0
- data/test/blocks_test.rb +8 -8
- data/test/document_test.rb +13 -1
- data/test/extensions_test.rb +38 -0
- data/test/invoker_test.rb +15 -0
- data/test/lists_test.rb +78 -53
- data/test/manpage_test.rb +15 -0
- data/test/paths_test.rb +3 -0
- data/test/reader_test.rb +2 -2
- data/test/sections_test.rb +10 -0
- data/test/substitutions_test.rb +12 -6
- data/test/tables_test.rb +76 -2
- metadata +16 -45
- data/lib/asciidoctor/core_ext/object/nil_or_empty.rb +0 -23
- data/test/fixtures/asciidoc_index.txt +0 -521
- data/test/fixtures/basic-docinfo-footer.html +0 -6
- data/test/fixtures/basic-docinfo-footer.xml +0 -8
- data/test/fixtures/basic-docinfo.html +0 -1
- data/test/fixtures/basic-docinfo.xml +0 -4
- data/test/fixtures/basic.asciidoc +0 -5
- data/test/fixtures/chapter-a.adoc +0 -3
- data/test/fixtures/child-include.adoc +0 -5
- data/test/fixtures/circle.svg +0 -8
- data/test/fixtures/custom-backends/erb/html5/block_paragraph.html.erb +0 -6
- data/test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml +0 -6
- data/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml +0 -1
- data/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml +0 -3
- data/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml +0 -5
- data/test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim +0 -6
- data/test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim +0 -3
- data/test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim +0 -5
- data/test/fixtures/custom-docinfodir/basic-docinfo.html +0 -1
- data/test/fixtures/custom-docinfodir/docinfo.html +0 -1
- data/test/fixtures/docinfo-footer.html +0 -1
- data/test/fixtures/docinfo-footer.xml +0 -9
- data/test/fixtures/docinfo.html +0 -1
- data/test/fixtures/docinfo.xml +0 -3
- data/test/fixtures/dot.gif +0 -0
- data/test/fixtures/encoding.asciidoc +0 -13
- data/test/fixtures/grandchild-include.adoc +0 -3
- data/test/fixtures/hello-asciidoctor.pdf +0 -0
- data/test/fixtures/include-file.asciidoc +0 -24
- data/test/fixtures/include-file.xml +0 -5
- data/test/fixtures/master.adoc +0 -5
- data/test/fixtures/parent-include-restricted.adoc +0 -5
- data/test/fixtures/parent-include.adoc +0 -5
- data/test/fixtures/sample.asciidoc +0 -26
- data/test/fixtures/stylesheets/custom.css +0 -3
- data/test/fixtures/subs-docinfo.html +0 -2
- data/test/fixtures/subs.adoc +0 -7
- data/test/fixtures/tip.gif +0 -0
- data/test/test_helper.rb +0 -399
data/test/manpage_test.rb
CHANGED
@@ -200,4 +200,19 @@ T}
|
|
200
200
|
.TE'
|
201
201
|
end
|
202
202
|
end
|
203
|
+
|
204
|
+
context 'Environment' do
|
205
|
+
test 'should use SOURCE_DATE_EPOCH as modified time of input file and local time' do
|
206
|
+
old_source_date_epoch = ENV.delete 'SOURCE_DATE_EPOCH'
|
207
|
+
begin
|
208
|
+
ENV['SOURCE_DATE_EPOCH'] = '1234123412'
|
209
|
+
output = Asciidoctor.convert SAMPLE_MANPAGE_HEADER, :backend => :manpage, :header_footer => true
|
210
|
+
assert_match(/Date: 2009-02-08/, output)
|
211
|
+
assert_match(/^\.TH "COMMAND" "1" "2009-02-08" "Command 1.2.3" "Command Manual"$/, output)
|
212
|
+
ensure
|
213
|
+
ENV['SOURCE_DATE_EPOCH'] = old_source_date_epoch if old_source_date_epoch
|
214
|
+
end
|
215
|
+
end
|
216
|
+
end
|
217
|
+
|
203
218
|
end
|
data/test/paths_test.rb
CHANGED
@@ -43,7 +43,10 @@ context 'Path Resolver' do
|
|
43
43
|
test 'target with relative path appended to start path' do
|
44
44
|
assert_equal 'assets/images', @resolver.web_path('images', 'assets')
|
45
45
|
assert_equal '/assets/images', @resolver.web_path('images', '/assets')
|
46
|
+
#assert_equal '/assets/images/tiger.png', @resolver.web_path('tiger.png', '/assets//images')
|
46
47
|
assert_equal './assets/images', @resolver.web_path('images', './assets')
|
48
|
+
assert_equal '/theme.css', @resolver.web_path('theme.css', '/')
|
49
|
+
assert_equal '/css/theme.css', @resolver.web_path('theme.css', '/css/')
|
47
50
|
end
|
48
51
|
|
49
52
|
test 'target with path relative to current directory appended to start path' do
|
data/test/reader_test.rb
CHANGED
@@ -455,11 +455,11 @@ preamble
|
|
455
455
|
end
|
456
456
|
|
457
457
|
context 'Include Stack' do
|
458
|
-
test 'PreprocessorReader#push_include method should return
|
458
|
+
test 'PreprocessorReader#push_include method should return reader' do
|
459
459
|
reader = empty_document.reader
|
460
460
|
append_lines = %w(one two three)
|
461
461
|
result = reader.push_include append_lines, '<stdin>', '<stdin>'
|
462
|
-
|
462
|
+
assert_equal reader, result
|
463
463
|
end
|
464
464
|
|
465
465
|
test 'PreprocessorReader#push_include method should put lines on top of stack' do
|
data/test/sections_test.rb
CHANGED
@@ -51,6 +51,16 @@ context 'Sections' do
|
|
51
51
|
assert_equal '_sectionone', sec.id
|
52
52
|
end
|
53
53
|
|
54
|
+
test 'synthetic id separator can be set to blank when idprefix is blank' do
|
55
|
+
sec = block_from_string(":idprefix:\n:idseparator:\n\n== Section One")
|
56
|
+
assert_equal 'sectionone', sec.id
|
57
|
+
end
|
58
|
+
|
59
|
+
test 'synthetic id separator is removed from beginning of id when idprefix is blank' do
|
60
|
+
sec = block_from_string(":idprefix:\n:idseparator: _\n\n== +Section One")
|
61
|
+
assert_equal 'section_one', sec.id
|
62
|
+
end
|
63
|
+
|
54
64
|
test 'synthetic ids can be disabled' do
|
55
65
|
sec = block_from_string(":sectids!:\n\n== Section One\n")
|
56
66
|
assert sec.id.nil?
|
data/test/substitutions_test.rb
CHANGED
@@ -655,15 +655,15 @@ context 'Substitutions' do
|
|
655
655
|
test 'an image macro with an inline SVG image should be converted to an svg element' do
|
656
656
|
para = block_from_string('image:circle.svg[Tiger,100,opts=inline]', :safe => Asciidoctor::SafeMode::SERVER, :attributes => { 'imagesdir' => 'fixtures', 'docdir' => ::File.dirname(__FILE__) })
|
657
657
|
result = para.sub_macros(para.source).gsub(/>\s+</, '><')
|
658
|
-
assert_match(/<svg
|
659
|
-
refute_match(/<svg
|
660
|
-
refute_match(/<svg
|
661
|
-
refute_match(/<svg
|
658
|
+
assert_match(/<svg\s[^>]*width="100px"[^>]*>/, result)
|
659
|
+
refute_match(/<svg\s[^>]*width="500px"[^>]*>/, result)
|
660
|
+
refute_match(/<svg\s[^>]*height="500px"[^>]*>/, result)
|
661
|
+
refute_match(/<svg\s[^>]*style="width:500px;height:500px"[^>]*>/, result)
|
662
662
|
end
|
663
663
|
|
664
664
|
test 'an image macro with an inline SVG image should be converted to an svg element even when data-uri is set' do
|
665
665
|
para = block_from_string('image:circle.svg[Tiger,100,opts=inline]', :safe => Asciidoctor::SafeMode::SERVER, :attributes => { 'data-uri' => '', 'imagesdir' => 'fixtures', 'docdir' => ::File.dirname(__FILE__) })
|
666
|
-
assert_match(/<svg
|
666
|
+
assert_match(/<svg\s[^>]*width="100px">/, para.sub_macros(para.source).gsub(/>\s+</, '><'))
|
667
667
|
end
|
668
668
|
|
669
669
|
test 'an image macro with an SVG image should not use an object element when safe mode is secure' do
|
@@ -1500,11 +1500,17 @@ foo — '
|
|
1500
1500
|
end
|
1501
1501
|
|
1502
1502
|
test 'preserves entity references' do
|
1503
|
-
input = '& © ✔ •'
|
1503
|
+
input = '& © ✔ 😀 • 😀'
|
1504
1504
|
result = render_embedded_string input, :doctype => :inline
|
1505
1505
|
assert_equal input, result
|
1506
1506
|
end
|
1507
1507
|
|
1508
|
+
test 'only preserves named entities with two or more letters' do
|
1509
|
+
input = '& &a; >'
|
1510
|
+
result = render_embedded_string input, :doctype => :inline
|
1511
|
+
assert_equal '& &a; >', result
|
1512
|
+
end
|
1513
|
+
|
1508
1514
|
test 'replaces punctuation' do
|
1509
1515
|
para = block_from_string %(John's Hideout is the Whites`' place... foo\\'bar)
|
1510
1516
|
assert_equal "John’s Hideout is the Whites’ place…​ foo'bar", para.sub_replacements(para.source)
|
data/test/tables_test.rb
CHANGED
@@ -191,6 +191,22 @@ A | here| a | there
|
|
191
191
|
assert_css 'table colgroup col[width]', output, 0
|
192
192
|
end
|
193
193
|
|
194
|
+
test 'explicit table width is used even when autowidth option is specified' do
|
195
|
+
input = <<-EOS
|
196
|
+
[%autowidth,width=75%]
|
197
|
+
|=======
|
198
|
+
|A |B |C
|
199
|
+
|a |b |c
|
200
|
+
|1 |2 |3
|
201
|
+
|=======
|
202
|
+
EOS
|
203
|
+
output = render_embedded_string input
|
204
|
+
assert_css 'table', output, 1
|
205
|
+
assert_css 'table[style*="width"]', output, 1
|
206
|
+
assert_css 'table colgroup col', output, 3
|
207
|
+
assert_css 'table colgroup col[width]', output, 0
|
208
|
+
end
|
209
|
+
|
194
210
|
test 'first row sets number of columns when not specified' do
|
195
211
|
input = <<-EOS
|
196
212
|
|====
|
@@ -362,6 +378,21 @@ A | here| a | there
|
|
362
378
|
assert_css 'table > tgroup > tbody > row', output, 3
|
363
379
|
end
|
364
380
|
|
381
|
+
test 'table with landscape orientation in DocBook' do
|
382
|
+
['orientation=landscape', '%rotate'].each do |attrs|
|
383
|
+
input = <<-EOS
|
384
|
+
[#{attrs}]
|
385
|
+
|===
|
386
|
+
|Column A | Column B | Column C
|
387
|
+
|===
|
388
|
+
EOS
|
389
|
+
|
390
|
+
output = render_embedded_string input, :backend => 'docbook'
|
391
|
+
assert_css 'informaltable', output, 1
|
392
|
+
assert_css 'informaltable[orient="land"]', output, 1
|
393
|
+
end
|
394
|
+
end
|
395
|
+
|
365
396
|
test 'table with implicit header row' do
|
366
397
|
input = <<-EOS
|
367
398
|
|===
|
@@ -384,6 +415,27 @@ A | here| a | there
|
|
384
415
|
assert_css 'table > tbody > tr', output, 2
|
385
416
|
end
|
386
417
|
|
418
|
+
test 'table with implicit header row when other options set' do
|
419
|
+
input = <<-EOS
|
420
|
+
[%autowidth]
|
421
|
+
|===
|
422
|
+
|Column 1 |Column 2
|
423
|
+
|
424
|
+
|Data A1
|
425
|
+
|Data B1
|
426
|
+
|===
|
427
|
+
EOS
|
428
|
+
output = render_embedded_string input
|
429
|
+
assert_css 'table', output, 1
|
430
|
+
assert_css 'table[style*="width"]', output, 0
|
431
|
+
assert_css 'table > colgroup > col', output, 2
|
432
|
+
assert_css 'table > thead', output, 1
|
433
|
+
assert_css 'table > thead > tr', output, 1
|
434
|
+
assert_css 'table > thead > tr > th', output, 2
|
435
|
+
assert_css 'table > tbody', output, 1
|
436
|
+
assert_css 'table > tbody > tr', output, 1
|
437
|
+
end
|
438
|
+
|
387
439
|
test 'no implicit header row if second line not blank' do
|
388
440
|
input = <<-EOS
|
389
441
|
|===
|
@@ -425,9 +477,9 @@ A | here| a | there
|
|
425
477
|
assert_css 'table > tbody > tr', output, 3
|
426
478
|
end
|
427
479
|
|
428
|
-
test 'no implicit header row if
|
480
|
+
test 'no implicit header row if noheader option is specified' do
|
429
481
|
input = <<-EOS
|
430
|
-
[
|
482
|
+
[%noheader]
|
431
483
|
|===
|
432
484
|
|Column 1 |Column 2
|
433
485
|
|
@@ -671,6 +723,28 @@ d|9 2+>|10
|
|
671
723
|
assert_xpath '(//row)[2]/entry[@nameend]', output, 0
|
672
724
|
end
|
673
725
|
|
726
|
+
test 'assigns unique column names for table with implicit column count and colspans in first row' do
|
727
|
+
input = <<-EOS
|
728
|
+
|====
|
729
|
+
| 2+| Node 0 2+| Node 1
|
730
|
+
|
731
|
+
| Host processes | Core 0 | Core 1 | Core 4 | Core 5
|
732
|
+
| Guest processes | Core 2 | Core 3 | Core 6 | Core 7
|
733
|
+
|====
|
734
|
+
EOS
|
735
|
+
|
736
|
+
output = render_embedded_string input, :backend => 'docbook'
|
737
|
+
assert_xpath '//colspec', output, 5
|
738
|
+
(1..5).each do |n|
|
739
|
+
assert_xpath %((//colspec)[#{n}][@colname="col_#{n}"]), output, 1
|
740
|
+
end
|
741
|
+
assert_xpath '(//row)[1]/entry', output, 3
|
742
|
+
assert_xpath '((//row)[1]/entry)[1][@namest]', output, 0
|
743
|
+
assert_xpath '((//row)[1]/entry)[1][@namend]', output, 0
|
744
|
+
assert_xpath '((//row)[1]/entry)[2][@namest="col_2"][@nameend="col_3"]', output, 1
|
745
|
+
assert_xpath '((//row)[1]/entry)[3][@namest="col_4"][@nameend="col_5"]', output, 1
|
746
|
+
end
|
747
|
+
|
674
748
|
test 'ignores cell with colspan that exceeds colspec' do
|
675
749
|
input = <<-EOS
|
676
750
|
[cols="1,1"]
|
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: asciidoctor
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.5.
|
4
|
+
version: 1.5.5
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Dan Allen
|
@@ -13,7 +13,7 @@ authors:
|
|
13
13
|
autorequire:
|
14
14
|
bindir: bin
|
15
15
|
cert_chain: []
|
16
|
-
date: 2016-
|
16
|
+
date: 2016-10-05 00:00:00.000000000 Z
|
17
17
|
dependencies:
|
18
18
|
- !ruby/object:Gem::Dependency
|
19
19
|
name: asciimath
|
@@ -211,8 +211,9 @@ dependencies:
|
|
211
211
|
- - "~>"
|
212
212
|
- !ruby/object:Gem::Version
|
213
213
|
version: 5.3.0
|
214
|
-
description:
|
215
|
-
|
214
|
+
description: A fast, open source text processor and publishing toolchain, written
|
215
|
+
in Ruby, for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other
|
216
|
+
formats.
|
216
217
|
email:
|
217
218
|
- dan.j.allen@gmail.com
|
218
219
|
executables:
|
@@ -226,11 +227,17 @@ extra_rdoc_files:
|
|
226
227
|
files:
|
227
228
|
- CHANGELOG.adoc
|
228
229
|
- CONTRIBUTING.adoc
|
230
|
+
- Gemfile
|
229
231
|
- LICENSE.adoc
|
232
|
+
- README-fr.adoc
|
233
|
+
- README-jp.adoc
|
234
|
+
- README-zh_CN.adoc
|
230
235
|
- README.adoc
|
231
236
|
- Rakefile
|
237
|
+
- asciidoctor.gemspec
|
232
238
|
- bin/asciidoctor
|
233
239
|
- bin/asciidoctor-safe
|
240
|
+
- data/locale/attributes.adoc
|
234
241
|
- data/stylesheets/asciidoctor-default.css
|
235
242
|
- data/stylesheets/coderay-asciidoctor.css
|
236
243
|
- features/open_block.feature
|
@@ -257,9 +264,11 @@ files:
|
|
257
264
|
- lib/asciidoctor/converter/manpage.rb
|
258
265
|
- lib/asciidoctor/converter/template.rb
|
259
266
|
- lib/asciidoctor/core_ext.rb
|
260
|
-
- lib/asciidoctor/core_ext/
|
261
|
-
- lib/asciidoctor/core_ext/string/
|
262
|
-
- lib/asciidoctor/core_ext/symbol/length.rb
|
267
|
+
- lib/asciidoctor/core_ext/1.8.7/string/chr.rb
|
268
|
+
- lib/asciidoctor/core_ext/1.8.7/string/limit.rb
|
269
|
+
- lib/asciidoctor/core_ext/1.8.7/symbol/length.rb
|
270
|
+
- lib/asciidoctor/core_ext/nil_or_empty.rb
|
271
|
+
- lib/asciidoctor/core_ext/string/limit.rb
|
263
272
|
- lib/asciidoctor/document.rb
|
264
273
|
- lib/asciidoctor/extensions.rb
|
265
274
|
- lib/asciidoctor/helpers.rb
|
@@ -281,43 +290,6 @@ files:
|
|
281
290
|
- test/converter_test.rb
|
282
291
|
- test/document_test.rb
|
283
292
|
- test/extensions_test.rb
|
284
|
-
- test/fixtures/asciidoc_index.txt
|
285
|
-
- test/fixtures/basic-docinfo-footer.html
|
286
|
-
- test/fixtures/basic-docinfo-footer.xml
|
287
|
-
- test/fixtures/basic-docinfo.html
|
288
|
-
- test/fixtures/basic-docinfo.xml
|
289
|
-
- test/fixtures/basic.asciidoc
|
290
|
-
- test/fixtures/chapter-a.adoc
|
291
|
-
- test/fixtures/child-include.adoc
|
292
|
-
- test/fixtures/circle.svg
|
293
|
-
- test/fixtures/custom-backends/erb/html5/block_paragraph.html.erb
|
294
|
-
- test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml
|
295
|
-
- test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml
|
296
|
-
- test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml
|
297
|
-
- test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml
|
298
|
-
- test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim
|
299
|
-
- test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim
|
300
|
-
- test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim
|
301
|
-
- test/fixtures/custom-docinfodir/basic-docinfo.html
|
302
|
-
- test/fixtures/custom-docinfodir/docinfo.html
|
303
|
-
- test/fixtures/docinfo-footer.html
|
304
|
-
- test/fixtures/docinfo-footer.xml
|
305
|
-
- test/fixtures/docinfo.html
|
306
|
-
- test/fixtures/docinfo.xml
|
307
|
-
- test/fixtures/dot.gif
|
308
|
-
- test/fixtures/encoding.asciidoc
|
309
|
-
- test/fixtures/grandchild-include.adoc
|
310
|
-
- test/fixtures/hello-asciidoctor.pdf
|
311
|
-
- test/fixtures/include-file.asciidoc
|
312
|
-
- test/fixtures/include-file.xml
|
313
|
-
- test/fixtures/master.adoc
|
314
|
-
- test/fixtures/parent-include-restricted.adoc
|
315
|
-
- test/fixtures/parent-include.adoc
|
316
|
-
- test/fixtures/sample.asciidoc
|
317
|
-
- test/fixtures/stylesheets/custom.css
|
318
|
-
- test/fixtures/subs-docinfo.html
|
319
|
-
- test/fixtures/subs.adoc
|
320
|
-
- test/fixtures/tip.gif
|
321
293
|
- test/invoker_test.rb
|
322
294
|
- test/links_test.rb
|
323
295
|
- test/lists_test.rb
|
@@ -331,7 +303,6 @@ files:
|
|
331
303
|
- test/sections_test.rb
|
332
304
|
- test/substitutions_test.rb
|
333
305
|
- test/tables_test.rb
|
334
|
-
- test/test_helper.rb
|
335
306
|
- test/text_test.rb
|
336
307
|
homepage: http://asciidoctor.org
|
337
308
|
licenses:
|
@@ -1,23 +0,0 @@
|
|
1
|
-
# A core library extension that defines the method nil_or_empty? as an alias to
|
2
|
-
# optimize checks for nil? or empty? on common object types such as NilClass,
|
3
|
-
# String, Array and Hash.
|
4
|
-
|
5
|
-
class NilClass
|
6
|
-
alias :nil_or_empty? :nil? unless respond_to? :nil_or_empty?
|
7
|
-
end
|
8
|
-
|
9
|
-
class String
|
10
|
-
alias :nil_or_empty? :empty? unless respond_to? :nil_or_empty?
|
11
|
-
end
|
12
|
-
|
13
|
-
class Array
|
14
|
-
alias :nil_or_empty? :empty? unless respond_to? :nil_or_empty?
|
15
|
-
end
|
16
|
-
|
17
|
-
class Hash
|
18
|
-
alias :nil_or_empty? :empty? unless respond_to? :nil_or_empty?
|
19
|
-
end
|
20
|
-
|
21
|
-
class Numeric
|
22
|
-
alias :nil_or_empty? :nil? unless respond_to? :nil_or_empty?
|
23
|
-
end
|
@@ -1,521 +0,0 @@
|
|
1
|
-
AsciiDoc Home Page
|
2
|
-
==================
|
3
|
-
// Web page meta data.
|
4
|
-
:keywords: AsciiDoc, DocBook, EPUB, PDF, ebooks, slideshow, slidy, man page
|
5
|
-
:description: AsciiDoc is a text document format for writing notes, +
|
6
|
-
documentation, articles, books, ebooks, slideshows, +
|
7
|
-
web pages, man pages and blogs. AsciiDoc files can be +
|
8
|
-
translated to many formats including HTML, PDF, EPUB, +
|
9
|
-
man page.
|
10
|
-
|
11
|
-
|
12
|
-
.{revdate}: AsciiDoc {revnumber} Released
|
13
|
-
************************************************************************
|
14
|
-
Read the link:CHANGELOG.html[CHANGELOG] for release highlights and a
|
15
|
-
full list of all additions, changes and bug fixes. Changes are
|
16
|
-
documented in the updated link:userguide.html[User Guide]. See the
|
17
|
-
link:INSTALL.html[Installation page] for downloads and and
|
18
|
-
installation instructions.
|
19
|
-
|
20
|
-
'Stuart Rackham'
|
21
|
-
************************************************************************
|
22
|
-
|
23
|
-
Introduction
|
24
|
-
------------
|
25
|
-
{description}
|
26
|
-
|
27
|
-
AsciiDoc is highly configurable: both the AsciiDoc source file syntax
|
28
|
-
and the backend output markups (which can be almost any type of
|
29
|
-
SGML/XML markup) can be customized and extended by the user.
|
30
|
-
|
31
|
-
AsciiDoc is free software and is licenced under the terms of the 'GNU
|
32
|
-
General Public License version 2' (GPLv2).
|
33
|
-
|
34
|
-
TIP: The pages you are reading were written using AsciiDoc, to view
|
35
|
-
the corresponding AsciiDoc source click on the *Page Source* menu item
|
36
|
-
in the left hand margin.
|
37
|
-
|
38
|
-
|
39
|
-
Overview and Examples
|
40
|
-
---------------------
|
41
|
-
You write an AsciiDoc document the same way you would write a
|
42
|
-
normal text document, there are no markup tags or weird format
|
43
|
-
notations. AsciiDoc files are designed to be viewed, edited and
|
44
|
-
printed directly or translated to other presentation formats using
|
45
|
-
the asciidoc(1) command.
|
46
|
-
|
47
|
-
The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and
|
48
|
-
DocBook markups. DocBook can be post-processed to presentation
|
49
|
-
formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript
|
50
|
-
using readily available Open Source tools.
|
51
|
-
|
52
|
-
Example Articles
|
53
|
-
~~~~~~~~~~~~~~~~
|
54
|
-
- This XHTML version of the
|
55
|
-
link:asciidoc.css-embedded.html[AsciiDoc User Guide]
|
56
|
-
was generated by AsciiDoc from
|
57
|
-
link:asciidoc.txt[this AsciiDoc file].
|
58
|
-
|
59
|
-
- Here's the link:asciidoc.html[same document] created by first
|
60
|
-
generating DocBook markup using AsciiDoc and then converting the
|
61
|
-
DocBook markup to HTML using 'DocBook XSL Stylesheets'.
|
62
|
-
|
63
|
-
- The User Guide again, this time a
|
64
|
-
link:chunked/index.html[chunked version].
|
65
|
-
|
66
|
-
- AsciiDoc generated this link:article-standalone.html[stand-alone
|
67
|
-
HTML file] containing embedded CSS, JavaScript and images from this
|
68
|
-
link:article.txt[AsciiDoc article template] with this command:
|
69
|
-
|
70
|
-
asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
|
71
|
-
|
72
|
-
- The same link:article.txt[AsciiDoc article template] generated
|
73
|
-
link:article-html5-toc2.html[this HTML 5] (the 'toc2' attribute puts
|
74
|
-
a table of contents in the left margin) from this command:
|
75
|
-
|
76
|
-
asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt
|
77
|
-
|
78
|
-
- The same link:article.txt[AsciiDoc article template] produced
|
79
|
-
this link:article.html[HTML file] and this
|
80
|
-
link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc.
|
81
|
-
|
82
|
-
[[X7]]
|
83
|
-
Example Books
|
84
|
-
~~~~~~~~~~~~~
|
85
|
-
AsciiDoc markup supports all the standard DocBook frontmatter and
|
86
|
-
backmatter sections (dedication, preface, bibliography, glossary,
|
87
|
-
index, colophon) plus footnotes and index entries.
|
88
|
-
|
89
|
-
- This link:book.txt[AsciiDoc book] produced link:book.html[this HTML
|
90
|
-
file] using the 'DocBook XSL Stylesheets'.
|
91
|
-
- The link:asciidoc.pdf[PDF formatted AsciiDoc User Guide] was
|
92
|
-
generated from asciidoc(1) DocBook output.
|
93
|
-
- The link:asciidoc.epub[EPUB formatted AsciiDoc User Guide] was
|
94
|
-
generated using link:a2x.1.html[a2x].
|
95
|
-
- This link:book.epub[EPUB formatted book skeleton] was generated
|
96
|
-
using link:a2x.1.html[a2x].
|
97
|
-
- This link:book-multi.txt[multi-part AsciiDoc book] produced
|
98
|
-
link:book-multi.html[this HTML file] using the 'DocBook XSL
|
99
|
-
Stylesheets'.
|
100
|
-
|
101
|
-
Example UNIX Man Pages
|
102
|
-
~~~~~~~~~~~~~~~~~~~~~~
|
103
|
-
HTML formatted AsciiDoc man pages
|
104
|
-
link:asciidoc.1.css-embedded.html[with stylesheets] and
|
105
|
-
link:asciidoc.1.html[without stylesheets] were generated by AsciiDoc
|
106
|
-
from link:asciidoc.1.txt[this file].
|
107
|
-
|
108
|
-
This link:asciidoc.1[roff formatted man page] was generated from
|
109
|
-
asciidoc(1) DocBook output using `xsltproc(1)` and DocBook XSL
|
110
|
-
Stylesheets.
|
111
|
-
|
112
|
-
[[X8]]
|
113
|
-
Example Slideshows
|
114
|
-
~~~~~~~~~~~~~~~~~~
|
115
|
-
The http://www.w3.org/Talks/Tools/Slidy2/[Slidy] backend generates
|
116
|
-
HTML slideshows that can be viewed in any web browser. What's nice is
|
117
|
-
that you can create completely self contained slideshows including
|
118
|
-
embedded images.
|
119
|
-
|
120
|
-
- Here is the link:slidy.html[slidy backend documentation] slideshow
|
121
|
-
and here is it's link:slidy.txt[AsciiDoc source].
|
122
|
-
- An link:slidy-example.html[example slidy slideshow] and the
|
123
|
-
link:slidy-example.txt[AsciiDoc source].
|
124
|
-
|
125
|
-
Example Web Site
|
126
|
-
~~~~~~~~~~~~~~~~
|
127
|
-
The link:README-website.html[AsciiDoc website] is included in the
|
128
|
-
AsciiDoc distribution (in `./examples/website/`) as an example website
|
129
|
-
built using AsciiDoc. See `./examples/website/README-website.txt`.
|
130
|
-
|
131
|
-
More examples
|
132
|
-
~~~~~~~~~~~~~
|
133
|
-
- See below: <<X6,'Documents written using AsciiDoc'>>.
|
134
|
-
- Example link:newtables.html[Tables].
|
135
|
-
|
136
|
-
|
137
|
-
eBook Publication
|
138
|
-
-----------------
|
139
|
-
The two most popular open eBook formats are
|
140
|
-
http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF.
|
141
|
-
The AsciiDoc link:a2x.1.html[a2x] toolchain wrapper makes it easy to
|
142
|
-
link:publishing-ebooks-with-asciidoc.html[publish EPUB and PDF eBooks
|
143
|
-
with AsciiDoc]. See also <<X7,example books>> and
|
144
|
-
link:epub-notes.html[AsciiDoc EPUB Notes]).
|
145
|
-
|
146
|
-
|
147
|
-
Blogpost weblog client
|
148
|
-
----------------------
|
149
|
-
http://srackham.wordpress.com/blogpost-readme/[blogpost] is a
|
150
|
-
command-line weblog client for publishing AsciiDoc documents to
|
151
|
-
http://wordpress.org/[WordPress] blog hosts. It creates and updates
|
152
|
-
weblog posts and pages directly from AsciiDoc source documents.
|
153
|
-
|
154
|
-
|
155
|
-
Source code highlighter
|
156
|
-
-----------------------
|
157
|
-
AsciiDoc includes a link:source-highlight-filter.html[source code
|
158
|
-
highlighter filter] that uses
|
159
|
-
http://www.gnu.org/software/src-highlite/[GNU source-highlight] to
|
160
|
-
highlight HTML outputs. You also have the option of using the
|
161
|
-
http://pygments.org/[Pygments] highlighter.
|
162
|
-
|
163
|
-
|
164
|
-
[[X3]]
|
165
|
-
Mathematical Formulae
|
166
|
-
---------------------
|
167
|
-
You can include mathematical formulae in AsciiDoc XHTML documents using
|
168
|
-
link:asciimathml.html[ASCIIMathML] or link:latexmathml.html[LaTeXMathML]
|
169
|
-
notation.
|
170
|
-
|
171
|
-
The link:latex-filter.html[AsciiDoc LaTeX filter] translates LaTeX
|
172
|
-
source to an image that is automatically inserted into the AsciiDoc
|
173
|
-
output documents.
|
174
|
-
|
175
|
-
AsciiDoc also has 'latexmath' macros for DocBook outputs -- they are
|
176
|
-
documented in link:latexmath.pdf[this PDF file] and can be used in
|
177
|
-
AsciiDoc documents processed by `dblatex(1)`.
|
178
|
-
|
179
|
-
|
180
|
-
Editor Support
|
181
|
-
--------------
|
182
|
-
- An AsciiDoc syntax highlighter for the Vim text editor is included in the
|
183
|
-
AsciiDoc distribution (see the 'Vim Syntax Highlighter' appendix in
|
184
|
-
the 'AsciiDoc User Guide' for details).
|
185
|
-
+
|
186
|
-
.Syntax highlighter screenshot
|
187
|
-
image::images/highlighter.png[height=400,caption="",link="images/highlighter.png"]
|
188
|
-
|
189
|
-
- Dag Wieers has implemented an alternative Vim syntax file for
|
190
|
-
AsciiDoc which can be found here
|
191
|
-
http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.
|
192
|
-
- David Avsajanishvili has written a source highlighter for AsciiDoc
|
193
|
-
files for http://projects.gnome.org/gtksourceview/[GtkSourceView]
|
194
|
-
(used by http://projects.gnome.org/gedit/[gedit] and a number of
|
195
|
-
other applications). The project is hosted here:
|
196
|
-
https://launchpad.net/asciidoc-gtk-highlight
|
197
|
-
- AsciiDoc resources for the Emacs editor can be found on the
|
198
|
-
http://www.emacswiki.org/emacs/AsciiDoc[AsciiDoc page] at the
|
199
|
-
http://www.emacswiki.org/emacs/EmacsWiki[Emacs Wiki].
|
200
|
-
- Christian Zuckschwerdt has written a
|
201
|
-
https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle]
|
202
|
-
for AsciiDoc.
|
203
|
-
|
204
|
-
|
205
|
-
Try AsciiDoc on the Web
|
206
|
-
-----------------------
|
207
|
-
Andrew Koster has written a Web based application to interactively
|
208
|
-
convert and display AsciiDoc source:
|
209
|
-
http://andrewk.webfactional.com/asciidoc.php
|
210
|
-
|
211
|
-
|
212
|
-
[[X2]]
|
213
|
-
External Resources and Applications
|
214
|
-
-----------------------------------
|
215
|
-
Here are resources that I know of, if you know of more drop me a line
|
216
|
-
and I'll add them to the list.
|
217
|
-
|
218
|
-
- Check the link:INSTALL.html#X2[installation page] for packaged versions
|
219
|
-
of AsciiDoc.
|
220
|
-
- Alex Efros has written an HTML formatted
|
221
|
-
http://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using
|
222
|
-
Asciidoc.
|
223
|
-
- Thomas Berker has written an
|
224
|
-
http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet] in Open
|
225
|
-
Document and PDF formats.
|
226
|
-
- The http://www.wikimatrix.org/[WikiMatrix] website has an excellent
|
227
|
-
http://www.wikimatrix.org/syntax.php[web page] that compares the
|
228
|
-
various Wiki markup syntaxes. An interesting attempt at Wiki markup
|
229
|
-
standardization is http://www.wikicreole.org/[CREOLE].
|
230
|
-
- Franck Pommereau has written
|
231
|
-
http://www.univ-paris12.fr/lacl/pommereau/soft/asciidoctest.html[Asciidoctest],
|
232
|
-
a program that doctests snippets of Python code within your Asciidoc
|
233
|
-
documents.
|
234
|
-
- The http://remips.sourceforge.net/[ReMIPS] project website has been
|
235
|
-
built using AsciiDoc.
|
236
|
-
- Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets
|
237
|
-
Notes].
|
238
|
-
- Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki]
|
239
|
-
plugin for AsciiDoc which he uses to render
|
240
|
-
http://mowson.org/karl[his website]. The plugin is available
|
241
|
-
http://www.mowson.org/karl/colophon/[here] and there is some
|
242
|
-
discussion of the ikiwiki integration
|
243
|
-
http://ikiwiki.info/users/KarlMW/discussion/[here].
|
244
|
-
- Glenn Eychaner has
|
245
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/bf04b55628efe214[reworked
|
246
|
-
the Asciidoc plugin for ikiwiki] that was created by Karl Mowson,
|
247
|
-
the source can be downloaded from
|
248
|
-
http://dl.dropbox.com/u/11256359/asciidoc.pm
|
249
|
-
- David Hajage has written an AsciiDoc package for the
|
250
|
-
http://www.r-project.org/[R Project] (R is a free software
|
251
|
-
environment for statistical computing). 'ascii' is available on
|
252
|
-
'CRAN' (just run `install.packages("ascii")` from R). Briefly,
|
253
|
-
'ascii' replaces R results in AsciiDoc document with AsciiDoc
|
254
|
-
markup. More information and examples here:
|
255
|
-
http://eusebe.github.com/ascii/.
|
256
|
-
- Pascal Rapaz has written a Python script to automate AsciiDoc
|
257
|
-
website generation. You can find it at
|
258
|
-
http://www.rapazp.ch/opensource/tools/asciidoc.html.
|
259
|
-
- Jared Henley has written
|
260
|
-
http://jared.henley.id.au/software/awb/documentation.html[AsciiDoc
|
261
|
-
Website Builder]. 'AsciiDoc Website Builder' (awb) is a python
|
262
|
-
program that automates the building of of a website written in
|
263
|
-
AsciiDoc. All you need to write is the AsciiDoc source plus a few
|
264
|
-
simple configuration files.
|
265
|
-
- Brad Adkins has written
|
266
|
-
http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen], a
|
267
|
-
web site generation and deployment tool that allows you write your
|
268
|
-
web site content in AsciiDoc. The
|
269
|
-
http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen web
|
270
|
-
site] is managed using 'AsciiDocGen'.
|
271
|
-
- Filippo Negroni has developed a set of tools to facilitate 'literate
|
272
|
-
programming' using AsciiDoc. The set of tools is called
|
273
|
-
http://eweb.sourceforge.net/[eWEB].
|
274
|
-
- http://vanderwijk.info/2009/4/23/full-text-based-document-generation-using-asciidoc-and-ditaa[Ivo's
|
275
|
-
blog] describes a http://ditaa.sourceforge.net/[ditaa] filter for
|
276
|
-
AsciiDoc which converts http://en.wikipedia.org/wiki/ASCII_art[ASCII
|
277
|
-
art] into graphics.
|
278
|
-
- http://github.com/github/gollum[Gollum] is a git-powered wiki, it
|
279
|
-
supports various formats, including AsciiDoc.
|
280
|
-
- Gregory Romé has written an
|
281
|
-
http://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin]
|
282
|
-
for the http://www.redmine.org/[Redmine] project management
|
283
|
-
application.
|
284
|
-
- Paul Hsu has started a
|
285
|
-
http://github.com/paulhsu/AsciiDoc.CHT.userguide[Chinese translation
|
286
|
-
of the AsciiDoc User Guide].
|
287
|
-
- Dag Wieers has written
|
288
|
-
http://dag.wieers.com/home-made/unoconv/[UNOCONV]. 'UNOCONV' can
|
289
|
-
export AsciiDoc outputs to OpenOffice export formats.
|
290
|
-
- Ed Keith has written http://codeextactor.berlios.de/[Code
|
291
|
-
Extractor], it extracts code snippets from source code files and
|
292
|
-
inserts them into AsciiDoc documents.
|
293
|
-
- The http://csrp.iut-blagnac.fr/jmiwebsite/home/[JMI website] hosts
|
294
|
-
a number of extras for AsciiDoc and Slidy written by Jean-Michel
|
295
|
-
Inglebert.
|
296
|
-
- Ryan Tomayko has written an number of
|
297
|
-
http://tomayko.com/src/adoc-themes/[themes for AsciiDoc] along with
|
298
|
-
a http://tomayko.com/src/adoc-themes/hacking.html[script for
|
299
|
-
combining the CSS files] into single CSS theme files for AsciiDoc
|
300
|
-
embedded CSS documents.
|
301
|
-
- Ilya Portnov has written a
|
302
|
-
https://gitorious.org/doc-building-system[document building system
|
303
|
-
for AsciiDoc], here is
|
304
|
-
http://iportnov.blogspot.com/2011/03/asciidoc-beamer.html[short
|
305
|
-
article in Russian] describing it.
|
306
|
-
- Lex Trotman has written
|
307
|
-
https://github.com/elextr/codiicsa[codiicsa], a program that
|
308
|
-
converts DocBook to AsciiDoc.
|
309
|
-
- Qingping Hou has written http://houqp.github.com/asciidoc-deckjs/[an
|
310
|
-
AsciiDoc backend for deck.js].
|
311
|
-
http://imakewebthings.github.com/deck.js/[deck.js] is a JavaScript
|
312
|
-
library for building modern HTML presentations (slideshows).
|
313
|
-
- The guys from O'Reilly Media have posted an
|
314
|
-
https://github.com/oreillymedia/docbook2asciidoc[XSL Stylesheet to
|
315
|
-
github] that converts DocBook to AsciiDoc.
|
316
|
-
- Lex Trotman has written
|
317
|
-
https://github.com/elextr/flexndex[flexndex], an index generator
|
318
|
-
tool that be used with AsciiDoc.
|
319
|
-
- Michael Haberler has created a
|
320
|
-
https://code.google.com/p/asciidoc-diag-filter/[blockdiag filter for
|
321
|
-
Asciidoc] which embeds http://blockdiag.com/[blockdiag] images in
|
322
|
-
AsciiDoc documents.
|
323
|
-
- Dan Allen has written a
|
324
|
-
https://github.com/mojavelinux/asciidoc-bootstrap-docs-backend[Bootstrap
|
325
|
-
backend] for AsciiDoc.
|
326
|
-
- Steven Boscarine has written
|
327
|
-
https://github.com/StevenBoscarine/JavaAsciidocWrapper[Maven wrapper for AsciiDoc].
|
328
|
-
- Christian Goltz has written
|
329
|
-
https://github.com/christiangoltz/shaape[Shaape], an Ascii art to
|
330
|
-
image converter for AsciiDoc.
|
331
|
-
- Eduardo Santana has written an
|
332
|
-
https://github.com/edusantana/asciidoc-highlight[Asciidoc Highlight
|
333
|
-
for Notepad++].
|
334
|
-
- http://www.geany.org/[Geany] 1.23 adds document structure support
|
335
|
-
for AsciiDoc.
|
336
|
-
|
337
|
-
Please let me know if any of these links need updating.
|
338
|
-
|
339
|
-
|
340
|
-
[[X6]]
|
341
|
-
Documents written using AsciiDoc
|
342
|
-
--------------------------------
|
343
|
-
Here are some documents I know of, if you know of more drop me a line
|
344
|
-
and I'll add them to the list.
|
345
|
-
|
346
|
-
- The book http://practicalunittesting.com/[Practical Unit Testing] by
|
347
|
-
Tomek Kaczanowski was
|
348
|
-
https://groups.google.com/group/asciidoc/browse_frm/thread/4ba13926262efa23[written
|
349
|
-
using Asciidoc].
|
350
|
-
|
351
|
-
- The book http://oreilly.com/catalog/9781449397296[Programming iOS 4]
|
352
|
-
by Matt Neuburg was written using AsciiDoc. Matt has
|
353
|
-
http://www.apeth.net/matt/iosbooktoolchain.html[written an article]
|
354
|
-
describing how he used AsciiDoc and other tools to write the book.
|
355
|
-
|
356
|
-
- The book
|
357
|
-
http://oreilly.com/catalog/9780596155957/index.html[Programming
|
358
|
-
Scala] by Dean Wampler and Alex Payne (O'Reilly) was
|
359
|
-
http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written
|
360
|
-
using Asciidoc].
|
361
|
-
|
362
|
-
- The http://www.ncfaculty.net/dogle/fishR/index.html[fishR] website
|
363
|
-
has a number of
|
364
|
-
http://www.ncfaculty.net/dogle/fishR/bookex/AIFFD/AIFFD.html[book
|
365
|
-
examples] written using AsciiDoc.
|
366
|
-
|
367
|
-
- The Neo4j graph database project uses Asciidoc, and the output is
|
368
|
-
published here: http://docs.neo4j.org/. The build process includes
|
369
|
-
live tested source code snippets and is described
|
370
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here].
|
371
|
-
|
372
|
-
- http://frugalware.org/[Frugalware Linux] uses AsciiDoc for
|
373
|
-
http://frugalware.org/docs[documentation].
|
374
|
-
- http://www.cherokee-project.com/doc/[Cherokee documentation].
|
375
|
-
|
376
|
-
- Henrik Maier produced this professional User manual using AsciiDoc:
|
377
|
-
http://www.proconx.com/assets/files/products/modg100/UMMBRG300-1101.pdf
|
378
|
-
|
379
|
-
- Henrik also produced this folded single page brochure format
|
380
|
-
example:
|
381
|
-
http://www.proconx.com/assets/files/products/modg100/IGMBRG300-1101-up.pdf
|
382
|
-
+
|
383
|
-
See this
|
384
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc
|
385
|
-
discussion group thread] for details.
|
386
|
-
|
387
|
-
- The
|
388
|
-
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git
|
389
|
-
User's Manual].
|
390
|
-
- 'Git Magic' +
|
391
|
-
http://www-cs-students.stanford.edu/~blynn/gitmagic/ +
|
392
|
-
http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c
|
393
|
-
- 'CouchDB: The Definitive Guide' +
|
394
|
-
http://books.couchdb.org/relax/ +
|
395
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4
|
396
|
-
- 'Ramaze Manual' +
|
397
|
-
http://book.ramaze.net/ +
|
398
|
-
http://github.com/manveru/ramaze-book/tree/master
|
399
|
-
- Some documentation about git by Nico Schottelius (in German)
|
400
|
-
http://nico.schotteli.us/papers/linux/git-firmen/.
|
401
|
-
- The http://www.netpromi.com/kirbybase_ruby.html[KirbyBase for Ruby]
|
402
|
-
database management system manual.
|
403
|
-
- The http://xpt.sourceforge.net/[*Nix Power Tools project] uses
|
404
|
-
AsciiDoc for documentation.
|
405
|
-
- The http://www.wesnoth.org/[Battle for Wesnoth] project uses
|
406
|
-
AsciiDoc for its http://www.wesnoth.org/wiki/WesnothManual[Manual]
|
407
|
-
in a number of different languages.
|
408
|
-
- Troy Hanson uses AsciiDoc to generate user guides for the
|
409
|
-
http://tpl.sourceforge.net/[tpl] and
|
410
|
-
http://uthash.sourceforge.net/[uthash] projects (the HTML versions
|
411
|
-
have a customised contents sidebar).
|
412
|
-
- http://volnitsky.com/[Leonid Volnitsky's site] is generated using
|
413
|
-
AsciiDoc and includes Leonid's matplotlib filter.
|
414
|
-
- http://www.weechat.org/[WeeChat] uses AsciiDoc for
|
415
|
-
http://www.weechat.org/doc[project documentation].
|
416
|
-
- http://www.clansuite.com/[Clansuite] uses AsciiDoc for
|
417
|
-
http://www.clansuite.com/documentation/[project documentation].
|
418
|
-
- The http://fc-solve.berlios.de/[Freecell Solver program] uses
|
419
|
-
AsciiDoc for its
|
420
|
-
http://fc-solve.berlios.de/docs/#distributed-docs[distributed
|
421
|
-
documentation].
|
422
|
-
- Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO
|
423
|
-
protocol decoding] documentation is written using AsciiDoc.
|
424
|
-
- Dwight Schauer has written an http://lxc.teegra.net/[LXC HOWTO] in
|
425
|
-
AsciiDoc.
|
426
|
-
- The http://www.rowetel.com/ucasterisk/[Free Telephony Project]
|
427
|
-
website is generated using AsciiDoc.
|
428
|
-
- Warren Block has http://www.wonkity.com/~wblock/docs/[posted a
|
429
|
-
number of articles written using AsciiDoc].
|
430
|
-
- The http://code.google.com/p/waf/[Waf project's] 'Waf Book' is
|
431
|
-
written using AsciiDoc, there is an
|
432
|
-
http://waf.googlecode.com/svn/docs/wafbook/single.html[HTML] and a
|
433
|
-
http://waf.googlecode.com/svn/docs/wafbook/waf.pdf[PDF] version.
|
434
|
-
- The http://www.diffkit.org/[DiffKit] project's documentation and
|
435
|
-
website have been written using Asciidoc.
|
436
|
-
- The http://www.networkupstools.org[Network UPS Tools] project
|
437
|
-
http://www.networkupstools.org/documentation.html[documentation] is
|
438
|
-
an example of a large documentation project written using AsciiDoc.
|
439
|
-
- http://www.archlinux.org/pacman/[Pacman], the
|
440
|
-
http://www.archlinux.org/[Arch Linux] package manager, has been
|
441
|
-
documented using AsciiDoc.
|
442
|
-
- Suraj Kurapati has written a number of customized manuals for his
|
443
|
-
Open Source projects using AsciiDoc:
|
444
|
-
|
445
|
-
* http://snk.tuxfamily.org/lib/detest/
|
446
|
-
* http://snk.tuxfamily.org/lib/ember/
|
447
|
-
* http://snk.tuxfamily.org/lib/inochi/
|
448
|
-
* http://snk.tuxfamily.org/lib/rumai/
|
449
|
-
|
450
|
-
- The http://cxxtest.com/[CxxTest] project (unit testing for C++
|
451
|
-
language) has written its User Guide using AsciiDoc.
|
452
|
-
|
453
|
-
Please let me know if any of these links need updating.
|
454
|
-
|
455
|
-
|
456
|
-
DocBook 5.0 Backend
|
457
|
-
-------------------
|
458
|
-
Shlomi Fish has begun work on a DocBook 5.0 `docbook50.conf` backend
|
459
|
-
configuration file, you can find it
|
460
|
-
http://bitbucket.org/shlomif/asciidoc[here]. See also:
|
461
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9
|
462
|
-
|
463
|
-
|
464
|
-
[[X1]]
|
465
|
-
LaTeX Backend
|
466
|
-
-------------
|
467
|
-
An experimental LaTeX backend was written for AsciiDoc in 2006 by
|
468
|
-
Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn't
|
469
|
-
think this was doable due to AsciiDoc's SGML/XML bias). Owning to to
|
470
|
-
other commitments, Benjamin was unable to maintain this backend.
|
471
|
-
Here's link:latex-backend.html[Benjamin's original documentation].
|
472
|
-
Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX
|
473
|
-
backend.
|
474
|
-
|
475
|
-
In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to
|
476
|
-
Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated
|
477
|
-
`latex.conf` file shipped with AsciiDoc version 8.4.4. The backend
|
478
|
-
still has limitations and remains experimental (see
|
479
|
-
link:latex-bugs.html[Geoff's notes]).
|
480
|
-
|
481
|
-
It's probably also worth pointing out that LaTeX output can be
|
482
|
-
generated by passing AsciiDoc generated DocBook through `dblatex(1)`.
|
483
|
-
|
484
|
-
|
485
|
-
Patches and bug reports
|
486
|
-
-----------------------
|
487
|
-
Patches and bug reports are are encouraged, but please try to follow
|
488
|
-
these guidelines:
|
489
|
-
|
490
|
-
- Post bug reports and patches to the
|
491
|
-
http://groups.google.com/group/asciidoc[asciidoc discussion list],
|
492
|
-
this keeps things transparent and gives everyone a chance to
|
493
|
-
comment.
|
494
|
-
- The email subject line should be a specific and concise topic
|
495
|
-
summary. Commonly accepted subject line prefixes such as '[ANN]',
|
496
|
-
'[PATCH]' and '[SOLVED]' are good.
|
497
|
-
|
498
|
-
=== Bug reports
|
499
|
-
- When reporting problems please illustrate the problem with the
|
500
|
-
smallest possible example that replicates the issue (and please test
|
501
|
-
your example before posting). This technique will also help to
|
502
|
-
eliminate red herrings prior to posting.
|
503
|
-
- Paste the commands that you executed along with any relevant
|
504
|
-
outputs.
|
505
|
-
- Include the version of AsciiDoc and the platform you're running it
|
506
|
-
on.
|
507
|
-
- If you can program please consider writing a patch to fix the
|
508
|
-
problem.
|
509
|
-
|
510
|
-
=== Patches
|
511
|
-
- Keep patches small and atomic (one issue per patch) -- no patch
|
512
|
-
bombs.
|
513
|
-
- If possible test your patch against the current trunk.
|
514
|
-
- If your patch adds or modifies functionality include a short example
|
515
|
-
that illustrates the changes.
|
516
|
-
- Send patches in `diff -u` format, inline inside the mail message is
|
517
|
-
usually best; if it is a very long patch then send it as an
|
518
|
-
attachment.
|
519
|
-
- Include documentation updates if you're up to it; otherwise insert
|
520
|
-
'TODO' comments at relevant places in the documentation.
|
521
|
-
|