Improve rendering of the bibliography

[odrotbohm]

According to this ticket, apparently Bibtex doesn't generate idiomatic text structures for Asciidoctor to eventually render PDFs properly. To quote the most relevant section from the original ticket:

This is a problem that needs to be dealt with in asciidoctor-bibtex. It really shouldn't be creating multiple paragraphs. Instead, it should be constructing an unordered list with the bibliography role and letting the converter handle the formatting. It's important that extensions work in a way that is compatible with converters. Otherwise, the converters cannot properly format the document.

[mojavelinux]

To the maintainers, please @ me if you need help creating the idiomatic / semantic structure that the converters rely on for formatting this document element.

[ProgramFan]

I see. This behavior inherits from the orginal asciidoc-bib. I am looking into this issue.

[odrotbohm]

I am completely blank on the Ruby side of things but am happy to help testing changes.

[ProgramFan]

The problem here is that in numerical styles such as IEEE, we need to customize the list item header to be exactly [1]. This does not quite fit in the bibliography syntax in asciidoc. How can we resolve this?

[odrotbohm]

Shouldn't it be a matter of literally replacing the paragraphs with unordered list items and marking the entire list as [bibliography]? /cc @mojavelinux

[mojavelinux]

That's essentially it. Since this extension comes after block parsing, the unordered list does not have to use the bibliography syntax in AsciiDoc. It just needs to be an unordered list with the correct block style. I'll share some code that shows how this would be done.

[ProgramFan]

Thanks, Dan. My major concern is how to represent the bibliography list. Eventually, there are two cases:

1. For numerical csl styles like IEEE, the list is an ordered list with labels as [1].
2. For non-numerical csl styles like APA, the list is an unordered list without labels.

How can I represent case 1 in asciidoctor?

[odrotbohm]

I am of course lacking the insight into the implementation but as I understand it, the code currently renders something equivalent to <p>[1] …</p> and Dan is suggesting to change that to <ul>[1] …</ul>, right? I.e. the IEEE "label" currently is just plain text currently, not a semantic label of some sorts either?

[mojavelinux]

Currently, the bibliography list in AsciiDoc has to be an unordered list that uses a square marker. And all the converters recognize this requirement. If we need to be able to customize how a bibliography list is displayed using one of the other list types or styles, then that is something that needs to be addressed in AsciiDoc. It's not something an extension should be changing because then we'll have lost the integrity of the document semantics. I'd be happy to prototype support for a secondary list style on a bibliography list in Asciidoctor PDF.

[mojavelinux]

Here's an example of how to create a bibliography list from an extension:

require 'asciidoctor/pdf'

input = <<~EOS
= Document Title

[bibliography]
== Bibliography
EOS

Asciidoctor::Extensions.register do
  tree_processor do
    process do |doc|
      bibsect = doc.sections.last
      biblist = create_list bibsect, :ulist
      biblist.style = 'bibliography'
      biblist << (create_list_item biblist, 'text of bibliography item')
      bibsect << biblist
      nil
    end
  end
end

Asciidoctor.convert input, safe: :safe, backend: :pdf, to_file: 'out.pdf'

[mojavelinux]

In the interim of having support for customizing the list marker on an bibliography list (at least from the API), I could understand needing to implement the items as paragraphs as you do today. But at the very least, you should be passing attributes (namely the role) defined on the macro to those paragraphs so that the styling can be controlled. In other words:

[.text-left]
bibliography::references.bib[ieee]

The text-left role should be passed to the paragraphs the extension adds.