Open odrotbohm opened 3 years ago
To the maintainers, please @ me if you need help creating the idiomatic / semantic structure that the converters rely on for formatting this document element.
I see. This behavior inherits from the orginal asciidoc-bib. I am looking into this issue.
I am completely blank on the Ruby side of things but am happy to help testing changes.
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?
Shouldn't it be a matter of literally replacing the paragraphs with unordered list items and marking the entire list as [bibliography]
? /cc @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.
Thanks, Dan. My major concern is how to represent the bibliography list. Eventually, there are two cases:
[1]
.How can I represent case 1 in asciidoctor?
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?
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.
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'
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.
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: