references variable in templates

[jgm]

Aditya Mahajan suggests on pandoc-discuss:

Is it possible to change the way bibliography is handled? Can you add
a $if(bibliography)$ check for the template file, and a $references$
tag for the list of references. Then, I can use the following in my
ConTeXt template:

$if(bibliography)$
%\subject{References}
\setupindenting[no]
\setupwhitespace[small]

$references$
$endif$

This may also circumvent the need to explicitly write #References in
the markdown file (but I don't know how other writers would handle
this).

[jgm]

Instead of using two variables, I'd probably just use one, references. The default templates (for all writers) could just include:

$if(references)$
$references$
$endif$

This could be customized if desired, and writers could opt to include a subject heading in the template rather than at the end of the document.

[adityam]

Of course, using one variable is better.

[jgm]

This change would not be easy, since currently the bibliography is added in the readers. The types of the reader functions would have to be changed to return a pair (Pandoc, [Block]). So this probably has to go on the back burner for now.

[jgm]

I just realized that the new metadata changes make it possible to add this feature without further API changes. (Though I'm not positive this is a good way to do it.) One could simply add a new references metadata field in the reader, containing the bibliography. Then templates could simply include a references variable wherever they like. If I'm not mistaken, minimal changes would be required!

[jgm]

The one potential drawback I see is that, in formats that print some representation of all of the metadata (e.g. reST, markdown), you'd get an extra copy of the bibliography in the metadata, which seems undesirable.

Perhaps this could be avoided by adding a special case for references.

[mmirate]

Actually, for non-reused bibliographic databases, wouldn't the ability to specify the bibliography inline with the document be considered a feature?

[jgm]

Experimented with implementing this, but found some rough edges. (This approach is difficult for epub, OPML, and some other formats.) My work is preserved in the branch issue771, but I think for now I'll stick to the present system.

[ousia]

Experimented with implementing this, but found some rough edges. (This approach is difficult for epub, OPML, and some other formats.) My work is preserved in the branch issue771, but I think for now I'll stick to the present system.

@jgm, how about enabling a # references title in a similar way to the proposals for TOC (#1612) and footnotes (#1720)?

This is much easier to use for the final user. And I think way more powerful.

[jgm]

Injecting the bibliography under a header with a special id (say, references) would indeed be easier technically than handling it with a template.

[ousia]

Injecting the bibliography under a header with a special id (say, references) would indeed be easier technically than handling it with a template.

@jgm, excuse me, but I can’t refrain from asking: are header with special titles technically easier to implement than variables in templates?

[lierdakil]

Somewhat relevant pandoc-discuss thread: https://groups.google.com/forum/#!topic/pandoc-discuss/HxmpFK-Ydus

---

To answer @ousia, not necessarily, no. But for some particular cases, like epub, template is actually a section template, and not a document template (since epub is basically a collection of html pages). So this becomes a bit more difficult if handled with a template variable -- after all, we don't need references in every section.

[alick]

@lierdakil "after all, we don't need references in every section." It might not be the case where pandoc focuses on, but it is common for books to have references after each chapter. In latex chapterbib and biblatex can handle this.

[lierdakil]

Let me rephrase this then: we don't need ALL references in every section.
Because pandoc-citeproc does not handle the use-case you are talking about,
and it would be extremely hard to make it to.

And pandoc does have support for biblatex for latex/pdf output. And it's
completely separate feature, not discussed here.

2015-04-10 11:50 GMT+03:00 Alick Zhao [email protected]:

@lierdakil https://github.com/lierdakil "after all, we don't need
references in every section." It might not be the case where pandoc focuses
on, but it is common for books to have references after each chapter. In
latex chapterbib and biblatex can handle this.

—
Reply to this email directly or view it on GitHub
#771 (comment).

[sergiocorreia]

Since we are already using pandoc-citeproc to construct the references, can we just have another filter that deals with this issue, instead of having it as a Pandoc problem? EG:

pandoc doc.md -F pandoc-citeproc -F pandoc-move-references

Now, what would be the best approach? append the references after a header with references id, or is there a better alternative? (If it's the former, I already have a sketch of a filter, from my pre-panflute days)

[nsbgn]

What @sergiocorreia suggests is similar to the approach I took when I ran into this problem. I made a $references$ variable accessible from within the template (since I didn't need to export to EPUB or other formats where using a template would be problematic):

import panflute as pf

def prepare(doc):
    doc.references = None

def action(el, doc):
    if isinstance(el, pf.Div) and el.identifier == "refs":
        doc.references = list(el.content)
        return []

def finalize(doc):
    if doc.references:
        doc.metadata["references"] = pf.MetaBlocks(*doc.references) 
    del doc.references

if __name__ == "__main__":
    pf.toJSONFilter(action, prepare, finalize)

This works fine, and I think inserting after specific headers is reasonable for a more general approach.

[jgm]

Pandoc-citeproc already allows you to insert a div with id refs, and in this case puts the references there.

Can this issue be closed, or is there something I'm missing?

[adityam]

Yes, I agree that this can be closed.

[joundso]

Pandoc-citeproc already allows you to insert a div with id refs, and in this case puts the references there.
Can this issue be closed, or is there something I'm missing?

In case someone is looking for a quick copy & paste example:

This is some text [@item1]

This is more text [@item2]

# References

<div id="refs"></div>

# appendix

Source: https://stackoverflow.com/a/44294306