Skip to content

Latest commit

 

History

History
208 lines (149 loc) · 6.2 KB

index_bib.adoc

File metadata and controls

208 lines (149 loc) · 6.2 KB

Index and bibliography

An index and bibliography are included in the main priv and unpriv docs. You can develop your own index and bibliography for your stand alone document, but if it is to be merged into the main docs, you must merge the index and bibliography as well.

Index markers

There are two types of index terms in AsciiDoc:

A flow index term. appears in the flow of text (a visible term) and in the index. This type of index term can only be used to define a primary entry:

indexterm2:[<primary>] or ((<primary>))

A concealed index term. a group of index terms that appear only in the index. This type of index term can be used to define a primary entry as well as optional secondary and tertiary entries:

indexterm:[<primary>, <secondary>, <tertiary>]

--or--

(((<primary>, <secondary>, <tertiary>)))
The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)), (1)
was to carry Excalibur (((Sword, Broadsword, Excalibur))). (2)
That is why I am your king. Shut up! Will you shut up?!
Burn her anyway! I'm not a witch.
Look, my liege! We found them.

indexterm2:[Lancelot] was one of the Knights of the Round Table. (3)
indexterm:[knight, Knight of the Round Table, Lancelot] (4)

  1. The double parenthesis form adds a primary index term and includes the term in the generated output.

  2. The triple parenthesis form allows for an optional second and third index term and does not include the terms in the generated output (a concealed index term).

  3. The inline macro indexterm2\:[primary] is equivalent to the double parenthesis form.

  4. The inline macro indexterm:\[primary, secondary, tertiary]` is equivalent to the triple parenthesis form.

If you’re defining a concealed index term (the indexterm macro), and one of the terms contains a comma, you must surround that segment in double quotes so the comma is treated as content. For example:

I, King Arthur.
indexterm:[knight, "Arthur, King"]

I, King Arthur.

--or--

I, King Arthur.
(((knight, "Arthur, King")))

I, King Arthur.

Bibliography and references

There are two ways of handling bibliographies:

  • By using the automated features provided by asciidoctor-bibtex[] (preferred).

  • Creating manual entries to which you can create links from the text in the body of your document (deprecated).

You can add bibliographic entries to the last appendix that you create in a book document.

Creating an automated bibliography with asciidoctor-bibtex

Asciidoctor-bibtex enables options that allow for establishing a single source of bibliographic entries that we can use for RISC-V specifications. As an added benefit we can make use of existing bibtex files.

For asciidoctor-bibtex to work, install the Ruby gems as documented in the docs-templates README file.

The doc header file in the docs-templates repo contains the following attributes for the purpose of implementing a bibliography using asciidoctor-bibtex:

:bibtex-file: resources/references.bib
:bibtex-order: alphabetical
:bibtex-style: apa

The repo also contains a version of the riscv-spec.bib file for asciidoctor-bibtex to use while building the bibliography.

When you run asciidoctor-bibtex as part of the build, it searches for the bibtex file first in the folder and subfolders of the document header, and then in \~/Documents."

Within your text, add author-year references following this pattern:

 cite:[riscvtr(12)]

with the result, cite:[riscvtr(12)]

Add age numbers (locators) following this pattern:

cite:[Kim-micro2005(45)]

with the result: cite:[Kim-micro2005(45)]

Add pretext following this pattern:

cite:See[Kim-micro2005(45)]

with the result: cite:See[Kim-micro2005(45)]

It’s possible to include other files, which are also processed.

Caution

To prevent problems with other appendices, keep the index as the second-to-last appendix and the bibliography as the last appendix in your list of included chapter sections within the book-header file.

Citations must be contained within a single line.

The bibliography section of the book must be set up as follows, to receive the entries during the build:

== Bibliography

bibliography::[]
Warning
 When using the automated option, do not manually add entries to the bibliography.adoc file.

The following examples are json-formatted bibliographic entries:

@book{Lane12a,
	author = {P. Lane},
	title =	 {Book title},
	publisher = {Publisher},
	year =	 {2000}
}

@book{Lane12b,
	author = {K. Mane and D. Smith},
	title =	 {Book title},
	publisher = {Publisher},
	year =	 {2000}
}

@article{Anderson04,
	author = {J. R. Anderson and D. Bothell and M. D. Byrne and S. Douglass and C. Lebiere and Y. L. Qin},
	title = {An integrated theory of the mind},
	journal = {Psychological Review},
	volume = {111},
	number = {4},
	pages = {1036--1060},
	year = {2004}
}

Manual bibliography procedures (deprecated)

While the automated procedure and use of the RISC-V bibtex file is preferred, it is also possible to manually create and reference a bibliography.

Text with markup that will generate links:

_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.

Links from within text to bibliographic entries:

[[bibliography]]
== References

* [[[pp]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
From Journeyman to Master. Addison-Wesley. 1999.
* [[[gof,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides.
Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.

Text that links to bibliography:

_The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.