asciidoctor-bibtex 0.1.0 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +128 -0
- data/bin/asciidoctor-bibtex +3 -4
- data/lib/asciidoctor-bibtex/asciidoctor.rb +2 -1
- data/lib/asciidoctor-bibtex/bibextension.rb +111 -38
- data/lib/asciidoctor-bibtex/options.rb +45 -18
- data/lib/asciidoctor-bibtex/processor.rb +93 -56
- data/lib/asciidoctor-bibtex/version.rb +1 -1
- data/samples/biblio.bib +1 -1
- data/samples/sample-1.adoc +38 -0
- data/samples/{sample-2.txt → sample-2.adoc} +0 -0
- metadata +20 -38
- data/README.rdoc +0 -166
- data/samples/sample-1.txt +0 -23
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: b1b51427daaa173649801301b8eec0d06c9d1f33
|
4
|
+
data.tar.gz: 77424fb797d99b1f89f43b0f2f0120c62f9eb6fa
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: eb4354f3d0bb64ca209c47734697c82a57e5284f943b2c6d3187b873a8346532eed91c33746bc08375bd86ac699a8e549aa6c816b8f8cb841404bbb00417be94
|
7
|
+
data.tar.gz: c21d7fda35a0fa9f5b941efe31684d814403fc5c2df434cd2d01e34abf48e1e4e050fd37625ab9aa09b60916cf605faab1a8f2375ae159d32f66287873435a0f
|
data/README.md
ADDED
@@ -0,0 +1,128 @@
|
|
1
|
+
# asciidoctor-bibtex: add bibtex functionality to asciidoc
|
2
|
+
|
3
|
+
asciidoctor-bibtex is a fork of [asciidoc-bib](https://github.com/petercrlane/asciidoc-bib) It generates in-text references and a reference list for an asciidoc file, using a bibtex file as a source of citation information. However, asciidoctor-bibtex proposes a different citation and reference grammar, which resembles the bibtex grammar in LaTeX. The grammar follows asciidoc inline and block macro semantics.
|
4
|
+
|
5
|
+
## Why a fork
|
6
|
+
|
7
|
+
When I began switching from latex/word to asciidoc, I searched for an easy way to integrate bibtex like references into asciidoc. Then I came across asciidoc-bib, which nearly meet my needs. I can insert citations, generate automatically a complete reference list. But there are aspects in asciidoc-bib that are not pleasing to work with.
|
8
|
+
|
9
|
+
The first is the overriding of `[bibliography]`. Asciidoctor introduces `[xxx]` as an mechanism to customize block styles, roles, etc. `[bibliography]` is reserved for the bibliography section style. asciidoc-bib breaks it and there is no apparent way to fix it.
|
10
|
+
|
11
|
+
The second is the grammar inconsistency with the rest of asciidoc. The `[cite:xxx]` is actually an inline macro but it does not follow the grammar of inline macros. This makes asciidoc-bib not that confortable to write with since it breaks the semantic memory.
|
12
|
+
|
13
|
+
The last is asciidoc-bib does not support asciidoctor arguments and extensions. So I can not use asciidoctor-pdf with it.
|
14
|
+
|
15
|
+
To accommodate the above problems, I create this fork. This fork tries to be as consistent with asciidoctor as possible.
|
16
|
+
|
17
|
+
## Features
|
18
|
+
|
19
|
+
- bibtex-like syntax for adding a citation within text and placing bibliography
|
20
|
+
- formatting of references and reference list according to range of styles supported by citeproc-ruby
|
21
|
+
- supports some styling of citation text (page numbers, bracket placement)
|
22
|
+
- can be used as an asciidoctor extension
|
23
|
+
|
24
|
+
## Install
|
25
|
+
|
26
|
+
gem install asciidoctor-bibtex
|
27
|
+
|
28
|
+
Installs two executable programs:
|
29
|
+
|
30
|
+
- 'asciidoc-bibtex' for transforming source text into asciidoc
|
31
|
+
- 'asciidoctor-bibtex' uses asciidoctor extension for single-pass output
|
32
|
+
|
33
|
+
asciidoctor-bibtex depends on [bibtex-ruby](http://github.com/inukshuk/bibtex-ruby), [citeproc-ruby](http://github.com/inukshuk/citeproc-ruby) and [csl-styles](http://github.com/inukshuk/csl-styles). (Ensure 'ruby-dev' and 'libxslt1-dev' are installed, so the dependencies will compile.)
|
34
|
+
|
35
|
+
[asciidoctor](https://github.com/asciidoctor/asciidoctor) must also be installed for 'asciidoctor-bibtex' to work. asciidoctor version 1.5.2 or higher is required.
|
36
|
+
|
37
|
+
## Usage
|
38
|
+
|
39
|
+
There are three ways of using asciidoctor-bibtex.
|
40
|
+
|
41
|
+
The first is required if using _asciidoc_. 'asciidoc-bibtex' works by transforming an asciidoc document containing syntax to include citations and a bibliography. The transformed document will contain a complete reference and bibliography list where indicated, and can then be processed further by asciidoc's toolchain to produce a completed document.
|
42
|
+
|
43
|
+
The second is to use 'asciidoctor-bibtex' to transform your bibtex-enabled documents directly to any backend format supported by asciidoctor. It uses the asciidoctor extension mechanism to hook in the asciidoctor preprocessing process. It support all asciidoctor command-line options.
|
44
|
+
|
45
|
+
The third is to use asciidoctor-bibtex as an asciidoctor extension. It works the same way as the second approach. In addition, one can use other extensions together to provides even richer functionality.
|
46
|
+
|
47
|
+
Styles must be one of those supported by CSL: https://github.com/citation-style-language/styles
|
48
|
+
|
49
|
+
### Citation syntax
|
50
|
+
|
51
|
+
Syntax for inserting a citation is the following inline macro:
|
52
|
+
|
53
|
+
cite|citenp:[ref(pages)]
|
54
|
+
|
55
|
+
where '(pages)' is optional. The ref and optional pages may be repeated multiple times, separated by ','. A citation _must_ be complete on a single line of text.
|
56
|
+
|
57
|
+
Examples of "chicago-author-date" style:
|
58
|
+
|
59
|
+
`cite:[Lane12]` becomes "(Lane 2012)"
|
60
|
+
|
61
|
+
`citenp:[Lane12]` becomes "Lane (2012)"
|
62
|
+
|
63
|
+
`cite:[Lane12(59)]` becomes "(Lane 2012, 59)"
|
64
|
+
|
65
|
+
For *apa* (Harvard-like) style:
|
66
|
+
|
67
|
+
`cite:[Lane12]` becomes "(Lane, 2012)"
|
68
|
+
|
69
|
+
`citenp:[Lane12]` becomes "Lane (2012)"
|
70
|
+
|
71
|
+
`cite:[Lane12(59)]` becomes "(Lane, 2012, p.59)"
|
72
|
+
|
73
|
+
For *ieee*, a numeric style:
|
74
|
+
|
75
|
+
`cite:[Lane12,Lane11]` becomes "[1, 2]"
|
76
|
+
|
77
|
+
### Place bibliography in text
|
78
|
+
|
79
|
+
`bibliography::[]` on a line by itself.
|
80
|
+
|
81
|
+
### Processing Text: Asciidoctor
|
82
|
+
|
83
|
+
asciidoctor-bibtex [OPTIONS] filename
|
84
|
+
|
85
|
+
Looks for a bib file in current folder and in ~/Documents.
|
86
|
+
|
87
|
+
Outputs an html file, including all citations and references.
|
88
|
+
|
89
|
+
asciidoctor-bibtex support all command-line options of asciidoctor, for example, use the follow command to output docbook file:
|
90
|
+
|
91
|
+
asciidoctor-bibtex -b docbook filename
|
92
|
+
|
93
|
+
One may also use as an asciidoctor extension, for example:
|
94
|
+
|
95
|
+
asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf filename
|
96
|
+
|
97
|
+
Options are set through the command-line using the asciidoctor attributes
|
98
|
+
setting syntax:
|
99
|
+
|
100
|
+
> asciidoctor-bibtex -h
|
101
|
+
|
102
|
+
...
|
103
|
+
AsciidoctorBibtex related options:
|
104
|
+
|
105
|
+
-a bib-file=FILENAME Set BibTex filename (default: auto-find)
|
106
|
+
-a bib-style=STYLE Set BibTex items style (default: apa)
|
107
|
+
-a bib-numeric-order=<alphabetical|appearance>
|
108
|
+
Set citation order scheme (default: alphabetical)
|
109
|
+
-a bib-no-links=1 Do not use links (default: use links)
|
110
|
+
|
111
|
+
### Processing text: Asciidoc
|
112
|
+
|
113
|
+
asciidoc-bibtex filename.txt
|
114
|
+
|
115
|
+
Looks for a bib file in current folder and in ~/Documents.
|
116
|
+
|
117
|
+
Outputs a new file: filename-ref.txt which includes your references.
|
118
|
+
|
119
|
+
asciidoc-bibtex supports the same command-line options as asciidoc-bib. The only difference is the citation and bibliography syntex.
|
120
|
+
|
121
|
+
## License
|
122
|
+
|
123
|
+
The files within this project may be distributed under the terms of
|
124
|
+
the Open Works License: http://owl.apotheon.org
|
125
|
+
|
126
|
+
## Links
|
127
|
+
|
128
|
+
See https://github.com/petercrlane/asciidoc-bib for the original asciidoc-bib.
|
data/bin/asciidoctor-bibtex
CHANGED
@@ -35,11 +35,10 @@ if not (ARGV & ['-h', '--help']).empty?
|
|
35
35
|
puts ""
|
36
36
|
puts "AsciidoctorBibtex related options:"
|
37
37
|
puts ""
|
38
|
-
puts " -a
|
39
|
-
puts " -a
|
40
|
-
puts " -a
|
38
|
+
puts " -a bibtex-file=FILENAME Set BibTex filename (default: auto-find)"
|
39
|
+
puts " -a bibtex-style=STYLE Set BibTex items style (default: apa)"
|
40
|
+
puts " -a bibtex-order=<alphabetical|appearance>"
|
41
41
|
puts " Set citation order scheme (default: alphabetical)"
|
42
|
-
puts " -a bib-no-links=1 Do not use links (default: use links)"
|
43
42
|
puts ""
|
44
43
|
exit 0
|
45
44
|
end
|
@@ -2,5 +2,6 @@ require 'asciidoctor/extensions'
|
|
2
2
|
require_relative 'bibextension'
|
3
3
|
|
4
4
|
Asciidoctor::Extensions.register do
|
5
|
-
|
5
|
+
block_macro AsciidoctorBibtex::Asciidoctor::BibliographyBlockMacro
|
6
|
+
treeprocessor AsciidoctorBibtex::Asciidoctor::CitationProcessor
|
6
7
|
end
|
@@ -1,65 +1,138 @@
|
|
1
|
-
# Uses Asciidoctor extension mechanism to insert asciidoc-bib processing
|
2
|
-
# as a preprocessor step. This provides single-pass compilation of
|
3
|
-
# documents, including citations and references.
|
4
1
|
#
|
5
|
-
#
|
6
|
-
#
|
2
|
+
# Treeprocessor extension for asciidoctor
|
3
|
+
#
|
7
4
|
|
8
5
|
require 'asciidoctor'
|
9
6
|
require 'asciidoctor/extensions'
|
10
|
-
require 'asciidoctor/
|
11
|
-
|
7
|
+
require 'asciidoctor/reader'
|
8
|
+
require 'asciidoctor/parser'
|
9
|
+
require_relative 'styles'
|
10
|
+
require_relative 'filehandlers'
|
12
11
|
|
13
12
|
module AsciidoctorBibtex
|
14
13
|
module Asciidoctor
|
14
|
+
BibliographyBlockMacroPlaceholder = %(BIBLIOGRAPHY BLOCK MACRO PLACEHOLDER)
|
15
|
+
|
16
|
+
# This macro processor does only half the work. It just parse the macro
|
17
|
+
# and set bibtex file and style if found in the macro. The macro is then
|
18
|
+
# expanded to a special paragraph, which is then replaced with generated
|
19
|
+
# references by the treeprocessor.
|
20
|
+
class BibliographyBlockMacro < ::Asciidoctor::Extensions::BlockMacroProcessor
|
21
|
+
use_dsl
|
22
|
+
named :bibliography
|
23
|
+
positional_attributes :style
|
24
|
+
|
25
|
+
def process parent, target, attrs
|
26
|
+
# NOTE: bibtex-file and bibtex-style set by this macro shall be
|
27
|
+
# overridable by document attributes and commandline arguments. So we
|
28
|
+
# respect the convention here.
|
29
|
+
if target and not parent.document.attr? 'bibtex-file'
|
30
|
+
parent.document.set_attribute 'bibtex-file', target
|
31
|
+
end
|
32
|
+
if attrs.key? :style and not parent.document.attr? 'bibtex-style'
|
33
|
+
parent.document.set_attribute 'bibtex-style', attrs[:style]
|
34
|
+
end
|
35
|
+
create_paragraph parent, BibliographyBlockMacroPlaceholder, {}
|
36
|
+
end
|
37
|
+
end
|
15
38
|
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
options = Options.new
|
22
|
-
options.parse_attributes document.attributes
|
23
|
-
|
24
|
-
# -- read in all lines from reader, processing the lines
|
39
|
+
# This processor scans the document, generates a list of citations,
|
40
|
+
# replace each citation with correct text and the reference block macro
|
41
|
+
# placeholder with the final reference list. It relys on the block macro
|
42
|
+
# processor to generate the place holder.
|
43
|
+
class CitationProcessor < ::Asciidoctor::Extensions::Treeprocessor
|
25
44
|
|
26
|
-
|
27
|
-
|
45
|
+
def process document
|
46
|
+
bibtex_file = (document.attr 'bibtex-file').to_s
|
47
|
+
bibtex_style = ((document.attr 'bibtex-style') || 'ieee').to_s
|
48
|
+
bibtex_order = ((document.attr 'bibtex-order') || 'alphabetical').to_sym
|
49
|
+
bibtex_output = ((document.attr 'bibtex-output') || 'asciidoc').to_sym
|
28
50
|
|
29
|
-
|
30
|
-
|
31
|
-
|
51
|
+
if bibtex_file.empty?
|
52
|
+
bibtex_file = AsciidoctorBibtex::FileHandlers.find_bibliography "."
|
53
|
+
end
|
54
|
+
if bibtex_file.empty?
|
55
|
+
bibtex_file = AsciidoctorBibtex::FileHandlers.find_bibliography "#{ENV['HOME']}/Documents"
|
56
|
+
end
|
57
|
+
if bibtex_file.empty?
|
58
|
+
puts "Error: bibtex-file is not set and automatic search failed"
|
59
|
+
exit
|
32
60
|
end
|
33
61
|
|
34
|
-
|
62
|
+
bibtex = BibTeX.open bibtex_file
|
63
|
+
processor = Processor.new bibtex, true, bibtex_style, bibtex_order == :appearance, bibtex_output
|
64
|
+
|
65
|
+
prose_blocks = document.find_by {|b| b.content_model == :simple or b.context == :list_item}
|
66
|
+
prose_blocks.each do |block|
|
67
|
+
if block.context == :list_item
|
68
|
+
line = block.instance_variable_get :@text
|
69
|
+
processor.citations.add_from_line line
|
70
|
+
else
|
71
|
+
block.lines.each do |line|
|
72
|
+
processor.citations.add_from_line line
|
73
|
+
end
|
74
|
+
end
|
75
|
+
end
|
35
76
|
|
36
|
-
|
37
|
-
|
38
|
-
line.
|
77
|
+
prose_blocks.each do |block|
|
78
|
+
if block.context == :list_item
|
79
|
+
line = block.instance_variable_get :@text
|
80
|
+
processor.citations.retrieve_citations(line).each do |citation|
|
81
|
+
line.gsub!(citation.original, processor.complete_citation(citation))
|
82
|
+
end
|
83
|
+
block.instance_variable_set :@text, line
|
84
|
+
else
|
85
|
+
block.lines.each do |line|
|
86
|
+
processor.citations.retrieve_citations(line).each do |citation|
|
87
|
+
line.gsub!(citation.original, processor.complete_citation(citation))
|
88
|
+
end
|
89
|
+
end
|
39
90
|
end
|
40
91
|
end
|
41
92
|
|
42
|
-
|
93
|
+
references_asciidoc = []
|
94
|
+
if bibtex_output == :latex
|
95
|
+
references_asciidoc << %(+++\\bibliography{#{bibtex_file}}{}+++)
|
96
|
+
references_asciidoc << %(+++\\bibliographystyle{#{bibtex_style}}+++)
|
97
|
+
else
|
98
|
+
processor.cites.each do |ref|
|
99
|
+
references_asciidoc << processor.get_reference(ref)
|
100
|
+
references_asciidoc << ''
|
101
|
+
end
|
102
|
+
end
|
43
103
|
|
44
|
-
|
45
|
-
#
|
46
|
-
|
104
|
+
biblio_blocks = document.find_by do |b|
|
105
|
+
# for fast search (since most searches shall fail)
|
106
|
+
b.content_model == :simple and b.lines.size == 1 \
|
107
|
+
and b.lines[0] == BibliographyBlockMacroPlaceholder
|
47
108
|
end
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
109
|
+
biblio_blocks.each do |block|
|
110
|
+
block_index = block.parent.blocks.index do |b|
|
111
|
+
b == block
|
112
|
+
end
|
113
|
+
reference_blocks = parse_asciidoc block.parent, references_asciidoc
|
114
|
+
reference_blocks.reverse.each do |b|
|
115
|
+
block.parent.blocks.insert block_index, b
|
54
116
|
end
|
117
|
+
block.parent.blocks.delete_at block_index + reference_blocks.size
|
55
118
|
end
|
56
119
|
|
57
|
-
|
120
|
+
nil
|
121
|
+
end
|
58
122
|
|
59
|
-
|
123
|
+
# This is an adapted version of Asciidoctor::Extension::parse_content,
|
124
|
+
# where resultant blocks are returned as a list instead of attached to
|
125
|
+
# the parent.
|
126
|
+
def parse_asciidoc parent, content, attributes = {}
|
127
|
+
result = []
|
128
|
+
reader = ::Asciidoctor::Reader.new content
|
129
|
+
while reader.has_more_lines?
|
130
|
+
block = ::Asciidoctor::Parser.next_block reader, parent, attributes
|
131
|
+
result << block if block
|
132
|
+
end
|
133
|
+
result
|
60
134
|
end
|
61
135
|
|
62
|
-
BIBMACRO_FULL = /bibliography::(.*?)\[(\w+)?\]/
|
63
136
|
end
|
64
137
|
|
65
138
|
end
|
@@ -8,7 +8,7 @@ require 'optparse'
|
|
8
8
|
|
9
9
|
module AsciidoctorBibtex
|
10
10
|
class Options
|
11
|
-
attr_reader :bibfile, :filename, :links, :style
|
11
|
+
attr_reader :bibfile, :filename, :links, :style, :output
|
12
12
|
|
13
13
|
def initialize(program_name = 'asciidoc-bibtex')
|
14
14
|
@bibfile = ''
|
@@ -16,6 +16,7 @@ module AsciidoctorBibtex
|
|
16
16
|
@numeric_order = :alphabetical
|
17
17
|
@style = AsciidoctorBibtex::Styles.default_style
|
18
18
|
@program_name = program_name
|
19
|
+
@output = "asciidoc"
|
19
20
|
end
|
20
21
|
|
21
22
|
# Public: Parse options from commandline.
|
@@ -47,6 +48,9 @@ module AsciidoctorBibtex
|
|
47
48
|
opts.on("-s", "--style STYLE", "reference style") do |v|
|
48
49
|
@style = v
|
49
50
|
end
|
51
|
+
opts.on("--output-style OUTPUT_STYLE", "Output style (asciidoc or latex)") do |v|
|
52
|
+
@output = v
|
53
|
+
end
|
50
54
|
opts.on("-v", "--version", "show version") do |v|
|
51
55
|
puts "#{@program_name} version #{AsciidoctorBibtex::VERSION}"
|
52
56
|
exit!
|
@@ -86,30 +90,50 @@ module AsciidoctorBibtex
|
|
86
90
|
puts "Reading biblio: #{@bibfile}"
|
87
91
|
puts "Reference style: #{@style}"
|
88
92
|
puts "Numerical order: #{@numeric_order}"
|
93
|
+
puts "Output style: #{@output}"
|
89
94
|
end
|
90
95
|
|
91
96
|
# Public: Parse values given `attrs`
|
92
97
|
# This function is used by asciidoctor preprocessor to determine options
|
93
|
-
# from document attributes.
|
94
|
-
|
95
|
-
|
96
|
-
|
98
|
+
# from document attributes. According to the attribute preccedence rule,
|
99
|
+
# attrs_cli > attrs_src > default
|
100
|
+
def parse_attributes(attrs_cli, attrs_src)
|
101
|
+
if attrs_cli['bib-style']
|
102
|
+
@style = attrs_cli['bib-style']
|
103
|
+
elsif attrs_src['bib-style']
|
104
|
+
@style = attrs_src['bib-style']
|
97
105
|
end
|
98
|
-
if
|
99
|
-
@bibfile =
|
106
|
+
if attrs_cli['bib-file']
|
107
|
+
@bibfile = attrs_cli['bib-file']
|
108
|
+
elsif attrs_src['bib-file']
|
109
|
+
@bibfile = attrs_src['bib-file']
|
100
110
|
end
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
111
|
+
order = nil
|
112
|
+
if attrs_cli['bib-numeric-order']
|
113
|
+
order = attrs_cli['bib-numeric-order']
|
114
|
+
elsif attrs_src['bib-numeric-order']
|
115
|
+
order = attrs_src['bib-numeric-order']
|
116
|
+
end
|
117
|
+
if order == nil
|
118
|
+
@numeric_order = :appearance
|
119
|
+
elsif order == "appearance"
|
120
|
+
@numeric_order = :appearance
|
121
|
+
elsif order == "alphabetical"
|
122
|
+
@numeric_order = :alphabetical
|
123
|
+
else
|
124
|
+
raise RuntimeError.new "Unknown numeric order: #{order}"
|
110
125
|
end
|
111
|
-
if
|
126
|
+
if attrs_cli['bib-no-links']
|
112
127
|
@links = false
|
128
|
+
elsif attrs_src['bib-no-links']
|
129
|
+
@links = false
|
130
|
+
end
|
131
|
+
if attrs_cli['bib-output']
|
132
|
+
@output = attrs_cli['bib-output']
|
133
|
+
elsif attrs_src['bib-output']
|
134
|
+
@output = attrs_src["bib-output"]
|
135
|
+
else
|
136
|
+
@output = "asciidoc"
|
113
137
|
end
|
114
138
|
|
115
139
|
# unless specified by caller, try to find the bibliography
|
@@ -118,6 +142,9 @@ module AsciidoctorBibtex
|
|
118
142
|
if @bibfile.empty?
|
119
143
|
@bibfile = AsciidoctorBibtex::FileHandlers.find_bibliography "#{ENV['HOME']}/Documents"
|
120
144
|
end
|
145
|
+
elsif not File.file? @bibfile
|
146
|
+
puts "Error: bibliography file '#{@bibfile}' does not exist"
|
147
|
+
exit
|
121
148
|
end
|
122
149
|
if @bibfile.empty?
|
123
150
|
puts "Error: could not find a bibliography file"
|
@@ -131,6 +158,7 @@ module AsciidoctorBibtex
|
|
131
158
|
puts "Reading biblio: #{@bibfile}"
|
132
159
|
puts "Reference style: #{@style}"
|
133
160
|
puts "Numerical order: #{@numeric_order}"
|
161
|
+
puts "Output style: #{@output}"
|
134
162
|
end
|
135
163
|
|
136
164
|
def numeric_in_appearance_order?
|
@@ -138,4 +166,3 @@ module AsciidoctorBibtex
|
|
138
166
|
end
|
139
167
|
end
|
140
168
|
end
|
141
|
-
|
@@ -1,36 +1,40 @@
|
|
1
1
|
#
|
2
|
-
# Manage the current set of citations, the document settings,
|
2
|
+
# Manage the current set of citations, the document settings,
|
3
3
|
# and main operations.
|
4
4
|
#
|
5
5
|
|
6
6
|
module AsciidoctorBibtex
|
7
7
|
|
8
|
-
# Class used through utility method to hold data about citations for
|
9
|
-
# current document, and run the different steps to add the citations
|
8
|
+
# Class used through utility method to hold data about citations for
|
9
|
+
# current document, and run the different steps to add the citations
|
10
10
|
# and bibliography
|
11
11
|
class Processor
|
12
12
|
include ProcessorUtils
|
13
13
|
|
14
14
|
# Top-level method to include citations in given asciidoc file
|
15
15
|
def Processor.run options
|
16
|
-
processor = Processor.new BibTeX.open(options.bibfile), options.links, options.style, options.numeric_in_appearance_order
|
16
|
+
processor = Processor.new BibTeX.open(options.bibfile), options.links, options.style, options.numeric_in_appearance_order?, options.output, options.bibfile
|
17
17
|
processor.read_filenames options.filename
|
18
|
-
processor.read_citations
|
18
|
+
processor.read_citations
|
19
19
|
processor.add_citations
|
20
20
|
end
|
21
21
|
|
22
22
|
attr_reader :biblio, :links, :style, :citations
|
23
23
|
|
24
|
-
def initialize biblio, links, style, numeric_in_appearance_order = false
|
24
|
+
def initialize biblio, links, style, numeric_in_appearance_order = false, output = :asciidoc, bibfile = ""
|
25
25
|
@biblio = biblio
|
26
26
|
@links = links
|
27
27
|
@numeric_in_appearance_order = numeric_in_appearance_order
|
28
28
|
@style = style
|
29
29
|
@citations = Citations.new
|
30
30
|
@filenames = Set.new
|
31
|
+
@output = output
|
32
|
+
@bibfile = bibfile
|
31
33
|
|
32
|
-
|
33
|
-
|
34
|
+
if output != :latex
|
35
|
+
@citeproc = CiteProc::Processor.new style: @style, format: :html
|
36
|
+
@citeproc.import @biblio.to_citeproc
|
37
|
+
end
|
34
38
|
end
|
35
39
|
|
36
40
|
# Given an asciidoc filename, reads in all dependent files based on 'include::' statements
|
@@ -45,7 +49,7 @@ module AsciidoctorBibtex
|
|
45
49
|
if line.include?("include::")
|
46
50
|
line.split("include::").drop(1).each do |filetxt|
|
47
51
|
file = File.expand_path(filetxt.partition(/\s|\[/).first)
|
48
|
-
|
52
|
+
files_to_process << file unless @filenames.include?(file)
|
49
53
|
end
|
50
54
|
end
|
51
55
|
end
|
@@ -53,12 +57,12 @@ module AsciidoctorBibtex
|
|
53
57
|
end
|
54
58
|
|
55
59
|
# Scans each filename and extracts citations
|
56
|
-
def read_citations
|
60
|
+
def read_citations
|
57
61
|
@filenames.each do |file|
|
58
62
|
IO.foreach(file) do |line|
|
59
63
|
@citations.add_from_line line
|
60
64
|
end
|
61
|
-
end
|
65
|
+
end
|
62
66
|
end
|
63
67
|
|
64
68
|
# Read given text to add cites and biblio to a new file
|
@@ -66,15 +70,15 @@ module AsciidoctorBibtex
|
|
66
70
|
# If no author present, then use editor field.
|
67
71
|
# Links indicates if internal links to be added.
|
68
72
|
# Assumes @filenames has been set to list of filenames to process.
|
69
|
-
def add_citations
|
73
|
+
def add_citations
|
70
74
|
@filenames.each do |curr_file|
|
71
75
|
ref_filename = FileHandlers.add_ref(curr_file)
|
72
|
-
puts "Writing file:
|
76
|
+
puts "Writing file: #{ref_filename}"
|
73
77
|
output = File.new(ref_filename, "w")
|
74
78
|
|
75
79
|
IO.foreach(curr_file) do |line|
|
76
80
|
begin # catch any errors, and ensure the lines of text are written
|
77
|
-
case
|
81
|
+
case
|
78
82
|
when line.include?('include::')
|
79
83
|
output_include_line output, line
|
80
84
|
when (line =~ BIBMACRO_FULL) != nil
|
@@ -88,26 +92,31 @@ module AsciidoctorBibtex
|
|
88
92
|
end
|
89
93
|
|
90
94
|
output.close
|
91
|
-
end
|
95
|
+
end
|
92
96
|
end
|
93
97
|
|
94
98
|
# Output bibliography to given output
|
95
99
|
def output_bibliography output
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
103
|
-
|
100
|
+
if @output == :asciidoc
|
101
|
+
cites = if Styles.is_numeric?(@style) and @numeric_in_appearance_order
|
102
|
+
@citations.cites_used
|
103
|
+
else
|
104
|
+
sorted_cites
|
105
|
+
end
|
106
|
+
cites.each do |ref|
|
107
|
+
output.puts get_reference(ref)
|
108
|
+
output.puts
|
109
|
+
end
|
110
|
+
else
|
111
|
+
output.puts "++\\bibliography{#{@bibfile}}++"
|
112
|
+
output.puts "++\\bibliographystyle{#{@style}}++"
|
104
113
|
end
|
105
114
|
end
|
106
115
|
|
107
116
|
def output_include_line output, line
|
108
117
|
line.split("include::").drop(1).each do |filetxt|
|
109
118
|
ifile = filetxt.partition(/\s|\[/).first
|
110
|
-
file = File.expand_path ifile
|
119
|
+
file = File.expand_path ifile
|
111
120
|
# make sure included file points to the -ref version
|
112
121
|
line.gsub!("include::#{ifile}", "include::#{FileHandlers.add_ref(file)}")
|
113
122
|
end
|
@@ -125,38 +134,58 @@ module AsciidoctorBibtex
|
|
125
134
|
|
126
135
|
# Return the complete citation text for given cite_data
|
127
136
|
def complete_citation cite_data
|
128
|
-
|
129
|
-
|
130
|
-
|
131
|
-
|
132
|
-
|
133
|
-
|
134
|
-
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
139
|
-
|
140
|
-
|
141
|
-
|
142
|
-
|
143
|
-
puts "Unknown reference: #{cite.ref}"
|
144
|
-
cite_text = "#{cite.ref}"
|
137
|
+
|
138
|
+
if @output == :latex
|
139
|
+
result = '+++'
|
140
|
+
cite_data.cites.each do |cite|
|
141
|
+
# NOTE: xelatex does not support "\citenp", so we output all
|
142
|
+
# references as "cite" here.
|
143
|
+
# result << "\\" << cite_data.type
|
144
|
+
result << "\\" << 'cite'
|
145
|
+
if cite.pages != ''
|
146
|
+
result << "[p. " << cite.pages << "]"
|
147
|
+
end
|
148
|
+
result << "{" << "#{cite.ref}" << "},"
|
149
|
+
end
|
150
|
+
if result[-1] == ','
|
151
|
+
result = result[0..-2]
|
145
152
|
end
|
153
|
+
result << "+++"
|
154
|
+
return result
|
155
|
+
else
|
156
|
+
result = ''
|
157
|
+
ob, cb = '(', ')'
|
158
|
+
|
159
|
+
cite_data.cites.each_with_index do |cite, index|
|
160
|
+
# before all items apart from the first, insert appropriate separator
|
161
|
+
result << "#{separator} " unless index.zero?
|
162
|
+
|
163
|
+
# @links requires adding hyperlink to reference
|
164
|
+
result << "<<#{cite.ref}," if @links
|
165
|
+
|
166
|
+
# if found, insert reference information
|
167
|
+
unless biblio[cite.ref].nil?
|
168
|
+
item = biblio[cite.ref].clone
|
169
|
+
cite_text, ob, cb = make_citation item, cite.ref, cite_data, cite
|
170
|
+
else
|
171
|
+
puts "Unknown reference: #{cite.ref}"
|
172
|
+
cite_text = "#{cite.ref}"
|
173
|
+
end
|
146
174
|
|
147
|
-
|
148
|
-
|
149
|
-
|
150
|
-
|
175
|
+
result << cite_text.html_to_asciidoc
|
176
|
+
# @links requires finish hyperlink
|
177
|
+
result << ">>" if @links
|
178
|
+
end
|
151
179
|
|
152
|
-
|
153
|
-
|
154
|
-
|
155
|
-
|
180
|
+
unless @links
|
181
|
+
# combine numeric ranges
|
182
|
+
if Styles.is_numeric? @style
|
183
|
+
result = combine_consecutive_numbers result
|
184
|
+
end
|
156
185
|
end
|
157
|
-
end
|
158
186
|
|
159
|
-
|
187
|
+
return include_pretext result, cite_data, ob, cb
|
188
|
+
end
|
160
189
|
end
|
161
190
|
|
162
191
|
# Retrieve text for reference in given style
|
@@ -218,14 +247,14 @@ module AsciidoctorBibtex
|
|
218
247
|
|
219
248
|
if Styles.is_numeric? @style
|
220
249
|
"#{pretext}#{ob}#{result}#{cb}"
|
221
|
-
elsif cite_data.type == "cite"
|
250
|
+
elsif cite_data.type == "cite"
|
222
251
|
"#{ob}#{pretext}#{result}#{cb}"
|
223
|
-
else
|
252
|
+
else
|
224
253
|
"#{pretext}#{result}"
|
225
254
|
end
|
226
255
|
end
|
227
256
|
|
228
|
-
# Numeric citations are handled by computing the position of the reference
|
257
|
+
# Numeric citations are handled by computing the position of the reference
|
229
258
|
# in the list of used citations.
|
230
259
|
# Other citations are formatted by citeproc.
|
231
260
|
def make_citation item, ref, cite_data, cite
|
@@ -250,19 +279,27 @@ module AsciidoctorBibtex
|
|
250
279
|
elsif cite_data.type == "citenp"
|
251
280
|
cite_text.gsub!(item.year, "#{fc}#{item.year}#{page_str(cite)}#{lc}")
|
252
281
|
cite_text.gsub!(", #{fc}", " #{fc}")
|
253
|
-
else
|
282
|
+
else
|
254
283
|
cite_text << page_str(cite)
|
255
284
|
end
|
256
285
|
|
257
286
|
cite_text.gsub!(",", ",") if @links # replace comma
|
258
287
|
|
259
|
-
|
288
|
+
return cite_text, fc, lc
|
260
289
|
end
|
261
290
|
|
262
291
|
def sorted_cites
|
263
292
|
@citations.sorted_cites @biblio
|
264
293
|
end
|
265
294
|
|
295
|
+
def cites
|
296
|
+
if Styles.is_numeric?(@style) and @numeric_in_appearance_order
|
297
|
+
@citations.cites_used
|
298
|
+
else
|
299
|
+
sorted_cites
|
300
|
+
end
|
301
|
+
end
|
302
|
+
|
266
303
|
BIBMACRO_FULL = /bibliography::(.*?)\[(\w+)?\]/
|
267
304
|
end
|
268
305
|
end
|
data/samples/biblio.bib
CHANGED
@@ -0,0 +1,38 @@
|
|
1
|
+
= Sample of using asciidoctor-bibtex
|
2
|
+
:bibtex-file: biblio.bib
|
3
|
+
:bibtex-order: alphabetical
|
4
|
+
:bibtex-style: ieee
|
5
|
+
|
6
|
+
The bibliography is searched in the folder of the document, and then in
|
7
|
+
~/Documents.
|
8
|
+
|
9
|
+
Author-year references can use different styles such as: cite:[Lane12b] or
|
10
|
+
citenp:[Lane12a].
|
11
|
+
|
12
|
+
Page numbers can be added: cite:[Lane12a(89)] or citenp:[Lane12a(89-93)].
|
13
|
+
|
14
|
+
A bit of pretext can be included too: See cite:[Lane12a(89)]
|
15
|
+
|
16
|
+
We can include other files, which are also processed:
|
17
|
+
|
18
|
+
include::sample-2.adoc[]
|
19
|
+
|
20
|
+
To include the reference list, use the section template before title, to
|
21
|
+
prevent problems with a2x.
|
22
|
+
|
23
|
+
References can be inserted in lists, too:
|
24
|
+
|
25
|
+
1. See cite:[Lane12a].
|
26
|
+
2. See cite:[Anderson98].
|
27
|
+
3. See cite:[Anderson04].
|
28
|
+
|
29
|
+
Also works for unordered list:
|
30
|
+
|
31
|
+
* See cite:[Lane12a].
|
32
|
+
* See cite:[Anderson98].
|
33
|
+
* See cite:[Anderson04].
|
34
|
+
|
35
|
+
[sect2]
|
36
|
+
== Bibliography
|
37
|
+
|
38
|
+
bibliography::biblio.bib[ieee]
|
File without changes
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: asciidoctor-bibtex
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.2.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Zhang YANG
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2016-08-28 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bibtex-ruby
|
@@ -16,78 +16,60 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - "~>"
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: '4
|
20
|
-
- - ">="
|
21
|
-
- !ruby/object:Gem::Version
|
22
|
-
version: 4.0.11
|
19
|
+
version: '4'
|
23
20
|
type: :runtime
|
24
21
|
prerelease: false
|
25
22
|
version_requirements: !ruby/object:Gem::Requirement
|
26
23
|
requirements:
|
27
24
|
- - "~>"
|
28
25
|
- !ruby/object:Gem::Version
|
29
|
-
version: '4
|
30
|
-
- - ">="
|
31
|
-
- !ruby/object:Gem::Version
|
32
|
-
version: 4.0.11
|
26
|
+
version: '4'
|
33
27
|
- !ruby/object:Gem::Dependency
|
34
28
|
name: citeproc-ruby
|
35
29
|
requirement: !ruby/object:Gem::Requirement
|
36
30
|
requirements:
|
37
31
|
- - "~>"
|
38
32
|
- !ruby/object:Gem::Version
|
39
|
-
version: '1
|
40
|
-
- - ">="
|
41
|
-
- !ruby/object:Gem::Version
|
42
|
-
version: 1.0.5
|
33
|
+
version: '1'
|
43
34
|
type: :runtime
|
44
35
|
prerelease: false
|
45
36
|
version_requirements: !ruby/object:Gem::Requirement
|
46
37
|
requirements:
|
47
38
|
- - "~>"
|
48
39
|
- !ruby/object:Gem::Version
|
49
|
-
version: '1
|
50
|
-
- - ">="
|
51
|
-
- !ruby/object:Gem::Version
|
52
|
-
version: 1.0.5
|
40
|
+
version: '1'
|
53
41
|
- !ruby/object:Gem::Dependency
|
54
42
|
name: csl-styles
|
55
43
|
requirement: !ruby/object:Gem::Requirement
|
56
44
|
requirements:
|
57
45
|
- - "~>"
|
58
46
|
- !ruby/object:Gem::Version
|
59
|
-
version: '1
|
60
|
-
- - ">="
|
61
|
-
- !ruby/object:Gem::Version
|
62
|
-
version: 1.0.1.6
|
47
|
+
version: '1'
|
63
48
|
type: :runtime
|
64
49
|
prerelease: false
|
65
50
|
version_requirements: !ruby/object:Gem::Requirement
|
66
51
|
requirements:
|
67
52
|
- - "~>"
|
68
53
|
- !ruby/object:Gem::Version
|
69
|
-
version: '1
|
70
|
-
- - ">="
|
71
|
-
- !ruby/object:Gem::Version
|
72
|
-
version: 1.0.1.6
|
54
|
+
version: '1'
|
73
55
|
description: |
|
74
56
|
asciidoctor-bibtex is a fork of asciidoc-bib. It generates in-text references
|
75
|
-
and
|
76
|
-
|
77
|
-
|
78
|
-
`bibliography::[]` for reference list. It can be used
|
79
|
-
asciidoctor extension. See the README for more examples
|
80
|
-
The references are formatted using styles provided by
|
57
|
+
and reference lists for asciidoc files, using specified bibtex file as
|
58
|
+
ciatation source. The citation syntax follows asciidoc inline and block macro
|
59
|
+
idiom and resembles bibtex macros, with `cite:[bibref]` or `citenp:[bibref]`
|
60
|
+
for in-text citation and `bibliography::[]` for reference list. It can be used
|
61
|
+
standalone or as an asciidoctor extension. See the README for more examples
|
62
|
+
and further options. The references are formatted using styles provided by
|
63
|
+
CSL.
|
81
64
|
email: zyangmath@gmail.com
|
82
65
|
executables:
|
83
66
|
- asciidoctor-bibtex
|
84
67
|
- asciidoc-bibtex
|
85
68
|
extensions: []
|
86
|
-
extra_rdoc_files:
|
87
|
-
- README.rdoc
|
69
|
+
extra_rdoc_files: []
|
88
70
|
files:
|
89
71
|
- LICENSE.txt
|
90
|
-
- README.
|
72
|
+
- README.md
|
91
73
|
- bin/asciidoc-bibtex
|
92
74
|
- bin/asciidoctor-bibtex
|
93
75
|
- lib/asciidoctor-bibtex.rb
|
@@ -105,8 +87,8 @@ files:
|
|
105
87
|
- lib/asciidoctor-bibtex/styles.rb
|
106
88
|
- lib/asciidoctor-bibtex/version.rb
|
107
89
|
- samples/biblio.bib
|
108
|
-
- samples/sample-1.
|
109
|
-
- samples/sample-2.
|
90
|
+
- samples/sample-1.adoc
|
91
|
+
- samples/sample-2.adoc
|
110
92
|
homepage: https://github.com/ProgramFan/asciidoctor-bibtex
|
111
93
|
licenses:
|
112
94
|
- OWL
|
@@ -127,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
127
109
|
version: '0'
|
128
110
|
requirements: []
|
129
111
|
rubyforge_project:
|
130
|
-
rubygems_version: 2.
|
112
|
+
rubygems_version: 2.6.6
|
131
113
|
signing_key:
|
132
114
|
specification_version: 4
|
133
115
|
summary: asciidoctor-bibtex adds bibtex references to an asciidoc file.
|
data/README.rdoc
DELETED
@@ -1,166 +0,0 @@
|
|
1
|
-
= asciidoctor-bibtex: add bibtex functionality to asciidoc
|
2
|
-
|
3
|
-
asciidoctor-bibtex is a fork of
|
4
|
-
{asciidoc-bib}[https://github.com/petercrlane/asciidoc-bib] It generates in-text
|
5
|
-
references and a reference list for an asciidoc file, using a bibtex file as a
|
6
|
-
source of citation information. However, asciidoctor-bibtex proposes a
|
7
|
-
different citation and reference grammar, which resembles the bibtex grammar
|
8
|
-
in LaTeX. The grammar follows asciidoc inline and block macro semantics.
|
9
|
-
|
10
|
-
== Why a fork
|
11
|
-
|
12
|
-
When I began switching from latex/word to asciidoc, I searched for an easy way
|
13
|
-
to integrate bibtex like references into asciidoc. Then I came across
|
14
|
-
asciidoc-bib, which nearly meet my needs. I can insert citations, generate
|
15
|
-
automatically a complete reference list. But there are aspects in asciidoc-bib
|
16
|
-
that are not pleasing to work with.
|
17
|
-
|
18
|
-
The first is the overriding of `[bibliography]`. Asciidoctor introduces
|
19
|
-
`[xxx]` as an mechanism to customize block styles, roles, etc.
|
20
|
-
`[bibliography]` is reserved for the bibliography section style. asciidoc-bib
|
21
|
-
breaks it and there is no apparent way to fix it.
|
22
|
-
|
23
|
-
The second is the grammar inconsistency with the rest of asciidoc. The
|
24
|
-
`[cite:xxx]` is actually an inline macro but it does not follow the grammar of
|
25
|
-
inline macros. This makes asciidoc-bib not that confortable to write with
|
26
|
-
since it breaks the semantic memory.
|
27
|
-
|
28
|
-
The last is asciidoc-bib does not support asciidoctor arguments and
|
29
|
-
extensions. So I can not use asciidoctor-pdf with it.
|
30
|
-
|
31
|
-
To accommodate the above problems, I create this fork. This fork tries to be
|
32
|
-
as consistent with asciidoctor as possible.
|
33
|
-
|
34
|
-
== Features
|
35
|
-
|
36
|
-
- bibtex-like syntax for adding a citation within text and placing bibliography
|
37
|
-
- formatting of references and reference list according to range of styles supported by citeproc-ruby
|
38
|
-
- supports some styling of citation text (page numbers, bracket placement)
|
39
|
-
- can be used as an asciidoctor extension
|
40
|
-
|
41
|
-
== Install
|
42
|
-
|
43
|
-
> gem install asciidoctor-bibtex
|
44
|
-
|
45
|
-
Installs two executable programs:
|
46
|
-
|
47
|
-
- 'asciidoc-bibtex' for transforming source text into asciidoc
|
48
|
-
- 'asciidoctor-bibtex' uses asciidoctor extension for single-pass output
|
49
|
-
|
50
|
-
asciidoctor-bibtex depends on bibtex-ruby[http://github.com/inukshuk/bibtex-ruby],
|
51
|
-
citeproc-ruby[http://github.com/inukshuk/citeproc-ruby] and
|
52
|
-
csl-styles[http://github.com/inukshuk/csl-styles].
|
53
|
-
(Ensure 'ruby-dev' and 'libxslt1-dev' are installed, so the dependencies will
|
54
|
-
compile.)
|
55
|
-
|
56
|
-
asciidoctor[https://github.com/asciidoctor/asciidoctor] must also be installed
|
57
|
-
for 'asciidoctor-bibtex' to work. asciidoctor version 1.5.2 or higher is
|
58
|
-
required.
|
59
|
-
|
60
|
-
== Use
|
61
|
-
|
62
|
-
There are three ways of using asciidoctor-bibtex.
|
63
|
-
|
64
|
-
The first is required if using _asciidoc_.
|
65
|
-
'asciidoc-bibtex' works by transforming an asciidoc document containing syntax
|
66
|
-
to include citations and a bibliography. The transformed document will
|
67
|
-
contain a complete reference and bibliography list where indicated, and
|
68
|
-
can then be processed further by asciidoc's toolchain to produce a completed
|
69
|
-
document.
|
70
|
-
|
71
|
-
The second is to use 'asciidoctor-bibtex' to transform your bibtex-enabled
|
72
|
-
documents directly to any backend format supported by asciidoctor. It uses the
|
73
|
-
asciidoctor extension mechanism to hook in the asciidoctor preprocessing
|
74
|
-
process. It support all asciidoctor command-line options.
|
75
|
-
|
76
|
-
The third is to use asciidoctor-bibtex as an asciidoctor extension. It works
|
77
|
-
the same way as the second approach. In addition, one can use other extensions
|
78
|
-
together to provides even richer functionality.
|
79
|
-
|
80
|
-
Styles must be one of those supported by CSL: https://github.com/citation-style-language/styles
|
81
|
-
|
82
|
-
=== Citation syntax
|
83
|
-
|
84
|
-
Syntax for inserting a citation is the following inline macro:
|
85
|
-
|
86
|
-
cite|citenp:[ref(pages)]
|
87
|
-
|
88
|
-
where '(pages)' is optional. The ref and optional pages may be repeated
|
89
|
-
multiple times, separated by ','. A citation _must_ be complete on a single
|
90
|
-
line of text.
|
91
|
-
|
92
|
-
Examples of +chicago-author-date+ style:
|
93
|
-
|
94
|
-
[cite:[Lane12]] becomes "(Lane 2012)"
|
95
|
-
|
96
|
-
[citenp:[Lane12]] becomes "Lane (2012)"
|
97
|
-
|
98
|
-
[cite:[Lane12(59)]] becomes "(Lane 2012, 59)"
|
99
|
-
|
100
|
-
For +apa+ (Harvard-like) style:
|
101
|
-
|
102
|
-
[cite:[Lane12]] becomes "(Lane, 2012)"
|
103
|
-
|
104
|
-
[citenp:[Lane12]] becomes "Lane (2012)"
|
105
|
-
|
106
|
-
[cite:[Lane12(59)]] becomes "(Lane, 2012, p.59)"
|
107
|
-
|
108
|
-
For +ieee+, a numeric style:
|
109
|
-
|
110
|
-
[cite:[Lane12,Lane11]] becomes "[1, 2]"
|
111
|
-
|
112
|
-
=== Place bibliography in text
|
113
|
-
|
114
|
-
[bibliography::[]] on a line by itself.
|
115
|
-
|
116
|
-
=== Processing Text: Asciidoctor
|
117
|
-
|
118
|
-
> asciidoctor-bibtex [OPTIONS] filename
|
119
|
-
|
120
|
-
Looks for a bib file in current folder and in ~/Documents.
|
121
|
-
|
122
|
-
Outputs an html file, including all citations and references.
|
123
|
-
|
124
|
-
asciidoctor-bibtex support all command-line options of asciidoctor, for
|
125
|
-
example, use the follow command to output docbook file:
|
126
|
-
|
127
|
-
asciidoctor-bibtex -b docbook filename
|
128
|
-
|
129
|
-
One may also use as an asciidoctor extension, for example:
|
130
|
-
|
131
|
-
asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf filename
|
132
|
-
|
133
|
-
Options are set through the command-line using the asciidoctor attributes
|
134
|
-
setting syntax:
|
135
|
-
|
136
|
-
> asciidoctor-bibtex -h
|
137
|
-
|
138
|
-
...
|
139
|
-
AsciidoctorBibtex related options:
|
140
|
-
|
141
|
-
-a bib-file=FILENAME Set BibTex filename (default: auto-find)
|
142
|
-
-a bib-style=STYLE Set BibTex items style (default: apa)
|
143
|
-
-a bib-numeric-order=<alphabetical|appearance>
|
144
|
-
Set citation order scheme (default: alphabetical)
|
145
|
-
-a bib-no-links=1 Do not use links (default: use links)
|
146
|
-
|
147
|
-
=== Processing text: Asciidoc
|
148
|
-
|
149
|
-
> asciidoc-bibtex filename.txt
|
150
|
-
|
151
|
-
Looks for a bib file in current folder and in ~/Documents.
|
152
|
-
|
153
|
-
Outputs a new file: filename-ref.txt
|
154
|
-
which includes your references.
|
155
|
-
|
156
|
-
asciidoc-bibtex supports the same command-line options as asciidoc-bib. The
|
157
|
-
only difference is the citation and bibliography syntex.
|
158
|
-
|
159
|
-
== License
|
160
|
-
|
161
|
-
The files within this project may be distributed under the terms of
|
162
|
-
the Open Works License: http://owl.apotheon.org
|
163
|
-
|
164
|
-
== Links
|
165
|
-
|
166
|
-
See [https://github.com/petercrlane/asciidoc-bib] for the original asciidoc-bib.
|
data/samples/sample-1.txt
DELETED
@@ -1,23 +0,0 @@
|
|
1
|
-
= Sample of using asciidoc-bib =
|
2
|
-
|
3
|
-
The bibliography is searched in the folder of the document, and then
|
4
|
-
in ~/Documents.
|
5
|
-
|
6
|
-
Author-year references can use different styles such as: cite:[Lane12a] or
|
7
|
-
citenp:[Lane12a].
|
8
|
-
|
9
|
-
Page numbers can be added: cite:[Lane12a(89)] or citenp:[Lane12a(89-93)].
|
10
|
-
|
11
|
-
A bit of pretext can be included too: See cite:[Lane12a(89)]
|
12
|
-
|
13
|
-
We can include other files, which are also processed:
|
14
|
-
|
15
|
-
include::sample-2.txt[]
|
16
|
-
|
17
|
-
To include the reference list, use the section template before
|
18
|
-
title, to prevent problems with a2x.
|
19
|
-
|
20
|
-
[sect2]
|
21
|
-
== Bibliography ==
|
22
|
-
|
23
|
-
bibliography::[]
|