Citations are being ignored if they are in sidebar, quotes

[shahryareiv]

Citation are being ignored if they reside in a sidebar or quote. For the quote, this:
[quote.epigraph, 'Arthur C. Clarke cite:[Clarke_2001_1968]', 2001: A Space Odyssey]
does not get translated, so a quotation cannot get its source identified.

[ProgramFan]

The new AST based processor does not yet handle sidebar or quotes. I will add them and make a new release. Thanks for reporting.

[ProgramFan]

It seems [quote.epigraph, 'Arthur C. Clarke cite:[Clarke_2001_1968]', 2001: A Space Odyssey] does not follow the sematics of quotes. Three parts of the quote block specification are block type (quote), attribution, and citetitle (see http://asciidoctor.org/docs/user-manual/#metadata-2). The last two are attributes of the block, which shall be plain texts.

From implementation point of view, I can substitute the citation with proper texts (but without hyperlinks). But I personally does not agree with the usage. If citations in quotes is really necessary, I would suggest put citations in the block title, instead of block attributes. For example:

.A Space Odyssey  cite:[Clarke_2001_1968]
[quote.epigraph, 'Arthur C. Clarke', 2001: A Space Odyssey]
This is the quote content.

If citations in block titles are wanted, I can implement them.

[shahryareiv]

Actually, If we consider popular style guides they usually put quote citations at the bottom, for example MLA suggestions here https://owl.english.purdue.edu/owl/resource/747/03/ or Chicago style here http://www.lmu.edu/Assets/Academic+Affairs+Division/Academic+Resource+Center/Chicago+Style+Quoting+and+Paraphrasing+Spring+2011.pdf

Also block attributes has the feature of being more than plain text. For example I use
[#somefigure,reftext='{fig} {chap-n}.{counter:fig-n}'] to create figure number per chapter. Still, I am not sure if it is the right way of writing an asciidoc document.

Here I mention Dan Allen @mojavelinux if he can give comment on Asciidoc style for quotes and attributes.

[mojavelinux]

[#somefigure,reftext='{fig} {chap-n}.{counter:fig-n}'] to create figure number per chapter.

While this certainly works, it's definitely far outside the spirit of AsciiDoc. AsciiDoc should declare the semantic information and an extension should sort how how to display, format and style it.

[shahryareiv]

@mojavelinux , Thanks for the comment, just any other comment on the placement of citations in quotations?

[mojavelinux]

I think we should follow the style guides as much as possible.

[ProgramFan]

Technologically, one can write things like [#somefigure,reftext='{fig} {chap-n}.{counter:fig-n}'] and asciidoctor's attribute substitution mechanism kicks in and replace the variables with their values. This shall be fine w.r.t. the style guide. But things like inline macros and inline markups in block attributes is completely another story. I guess it's up to the render backend to decide how to handle them, so it might not be the correct sematics. I don't quite understand the constraints of substitutions on block attributes, so please correct me if I were wrong. @mojavelinux

@shahryareiv, from the provided style guides, I would propose something like the following for quoting:

This is the famous quotes by Arthur C. Clarke (cite:[Clarke_2001_1968]):

[quote]
____
The content of the quote
____

The idea is to leave the quote body clean and add bibtex citations into the surrounding contexts, so readers can focus on the quote content first and refer to the source only if necessary.

[ProgramFan]

I am still considering whether to support citations in block titles/captions and section titles. The latter is considered a bad practice in the latex community. But it might be useful if one want to explain in more detail the contents of the block (such as figures, tables, etc.). Any comments? @mojavelinux @shahryareiv

[shahryareiv]

The example you mentioned above from the Asciidoctor manual, also populates attribute block:

.Gettysburg Address 
[[gettysburg]] 
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]     
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
____

I agree with you that leaving [quote] alone makes things more readable but then we would deviate from popular styles. Here I put two source and rendered samples one with your suggestion and with putting citation in the attribute line:

.Gettysburg Address (Linconln 1863)
[[gettysburg]] 
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]     
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
____


.Gettysburg Address 
[[gettysburg]] 
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg (Linconln 1863)]     
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...

Now we are engaged in a great civil war, testing whether
that nation, or any nation so conceived and so dedicated,
can long endure. ...
____

About the Latex, I guess there is a problem with "moving arguments" and they need to do \protect\cite{bibtexkey} and that is why it is not prefere (not sure about this anyway).

One more thing, is that we should find a way to defer these types of considerations to a center, i.e. asciidoctor core development. There might be other similar conversations in other extension development groups and we cannot unify them together. So extension development should be freed by converting anything/anywhere while asciidoctor prohibits the wrong practices in the first step.

[ProgramFan]

Now I understand the use case. Although one can write the citation texts directly in the attributes like above, one may want it produced automatically, and may need it linked with the bibliography further.

I experimented hyperlinks in quote attributes and asciidoctor converts them into markups before calling my extension. This means hyperlinks are eventually supported in quote attributes by asciidoctor. So it is possible for asciidoctor-bibtex to support hyperlinking citations in attributes to its bibliography item. The implementation is not staightforward, but I will add them anyway.

[ProgramFan]

Note that the core idea of asciidoctor-bibtex is bring bibtex to asciidoctor while adhering to asciidoctor's sematics. So citations in block attributes are only considered if asciidoctor supports inline macros in block attributes. So are there any rules for inline macros in block attributes? Does it support inline macros? Or in a restricted way? If so, what macros are allowed? @mojavelinux

[ProgramFan]

I tried to implement the feature and it turned out that I have to do it specially for quote block and convert the link to html in my extension. Even after all these tricks, the hyperlink still does not work in asciidoctor-pdf (however, it works correctly in the html backend). The code now lives in the cite-in-prose branch. It works only for citetitle in prose blocks. For example:

[quote, 'Arthur C. Clarke', A Space Odyssey (cite:[guo2009])]
____
This is a quote.
____

== Bibliography

bibliography::[]

results in

[ProgramFan]

This feature request does not follow the sematics of quote blocks, so I am still considering whether to merge it into master and make a new release. Please use the code in cite-in-prose branch for your needs.

[shahryareiv]

Thank! I just wonder if this limitation (citations in block quotes and also side-notes) also applies to "asciidoc -> asciidoc" transfer mode? I have used asciidoc-bib in "asciidoc -> asciidoc" mode before and it does not care about the placement of citations. Does asciidoctor-bib shares that piece or it has its own implementation?

[ProgramFan]

No. The asciidoc to asciidoc mode uses text substitution instead of AST
transformation. In fact, asciidoctor-bibtex 0.1.0 uses text substitution
for asciidoctor mode, too. You can use that version for your use case.

However, since the spirit of asciidoctor-bibtex is to respect the semantics
of asciidoc, I do not consider citations in quote citetitle a conforming
practice.
There are some restrictions currently on where you can place citations. For
example in table cells. So so you can stick to the old version until
everything is solved in a coherent manner.

2016年10月31日星期一，Shahryar notifications@github.com 写道：

Thank! I just wonder if this limitation (citations in block quotes and
also side-notes) also applies to "asciidoc -> asciidoc" transfer mode? I
have used asciidoc-bib in "asciidoc -> asciidoc" mode before and it does
not care about the placement of citations. Does asciidoctor-bib shares that
piece or it has its own implementation?

—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
#17 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAB-jBybPi0qm0TUhnVey2b959HtkOGsks5q5NRIgaJpZM4KgKCr
.

Zhang YANG (杨章)

Associate Professor, Ph.D.
Institute of Applied Physics and Computational Mathematics.
Addr: No. 2 East Fenghao Rd., 100094, Beijing, China.
Tel: 86-10-59872424 (Office) 86-18610310408 (Mobile)
Email: zyangmath@gmail.com OR yang_zhang@iapcm.ac.cn