You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
49 lines
2.4 KiB
49 lines
2.4 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Bibliography
|
||
|
|
////
|
||
|
|
|
||
|
|
AsciiDoc has basic support for bibliographies.
|
||
|
|
AsciiDoc doesn't concern itself with the structure of the bibliography entry itself, which is entirely freeform.
|
||
|
|
What it does is provide a way to make references to the entries from the same document and output the bibliography with proper semantics for processing by other toolchains (such as DocBook).
|
||
|
|
|
||
|
|
In order to reference a bibliography entry, you need to assign a _non-numeric_ label to the entry.
|
||
|
|
To assign this label, prefix the entry with the label enclosed in a pair of triple square brackets (e.g., `+[[[label]]]+`).
|
||
|
|
We call this a bibliography anchor.
|
||
|
|
Using this label, you can then reference the entry from anywhere above the bibliography in the same document using the normal cross reference syntax (e.g., `+<<label>>+`).
|
||
|
|
|
||
|
|
By default, the bibliography anchor and reference to the bibliography entry is converted to `[<label>]`, where <label> is the ID of the entry.
|
||
|
|
If you specify xreftext on the bibliography anchor (e.g., `+[[[label,xreftext]]]+`), the bibliography anchor and reference to the bibliography entry converts to `[<xreftext>]` instead.
|
||
|
|
|
||
|
|
If you want the bibliography anchor and reference to appear as a number, assign the number of the entry using the xreftext.
|
||
|
|
For example, `+[[[label,1]]]+` will be converted to `[1]`.
|
||
|
|
|
||
|
|
The bibliography entries themselves are declared as items in an unordered list.
|
||
|
|
You promote a normal unordered list to a bibliography list by adding the `bibliography` style.
|
||
|
|
However, to be conforming, bibliography lists must be contained inside a bibliography section.
|
||
|
|
A bibliography section is a section with the special `bibliography` style.
|
||
|
|
By adding the `bibliography` style to the section, you implicitly add it to each unordered list in that section.
|
||
|
|
|
||
|
|
WARNING: If the bibliography style is used on an unordered list outside of a bibliography section, the resulting behavior is undefined.
|
||
|
|
|
||
|
|
Let's consider an example.
|
||
|
|
|
||
|
|
.Bibliography with inbound references
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-biblio.adoc[tag=base]
|
||
|
|
----
|
||
|
|
|
||
|
|
This renders as:
|
||
|
|
|
||
|
|
|===
|
||
|
|
a|
|
||
|
|
include::ex-biblio.adoc[tag=base]
|
||
|
|
|===
|
||
|
|
|
||
|
|
If you want more advanced features such as automatic numbering and custom citation styles, try the {uri-org}/asciidoctor-bibtex[asciidoctor-bibtex] project.
|
||
|
|
|
||
|
|
TIP: To escape a bibliography anchor anywhere in the text, use the syntax `[\[[word]]]`.
|
||
|
|
This prevents the anchor from being matched as a bibliography anchor or a normal anchor.
|