Support --citeproc in reStructuredText
#9904
Labels
Comments
|
I think this makes a lot of sense; thanks for the comprehensive report. |
|
That was incredibly fast, thank you! If there's ever some future conflict with reST, or if sphinxcontrib-bibtex roles somehow go out of fashion, perhaps this can be revisited. But for now I think it's a great solution. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Describe your proposed improvement and the problem it solves.
Pandoc currently does not support bibliographic creation in reStructuredText with
--citeproc(#9901). Something like this was raised previously (#792), but was closed due to lack of intrinsic support in reStructuredText.The proposal of this issue to is revisit this topic and support a
:cite:role (e.g.:cite:`mueller1980`), and replace it with appropriate text based on a database provided by--bibliographyand formatting based on CSL. The default behavior would be to append the references at the end of the document, but.. bibliography::would allow for alternative placement of the references. Additionalbibliography::options, such as:all:, could also be supported.These extensions are currently supported by
sphinxcontrib-bibtexextension to Sphinx. AFAIK, this is currently the only way to produce LaTeX-like citations in Sphinx.Describe alternatives you've considered.
Native reST support
ReST supports a "Citation", but this is more suited for footnotes and hyperlinks rather than full bibliographic citations. This content often appears as written in the document, with minimal modification by the writer.
The following appears to be the status of bibliographic citation support in reST (https://docutils.sourceforge.io/docs/dev/todo.html#unimplemented-transforms). There seems to be little activity, with most forum discussions pointing to this page and soliciting for feedback.
The most recent comprehensive discussion that I could find was in 2011 and did not reach a resolution. However, metadata within the
[...]citation syntax was not well received. The current maintainer (Guenter M.) noted that bibliographic data could already be written explicitly (e.g.Mueller (1980)), and that roles (e.g.:cite:) and directives already exist to direct writers to format any text.While a native reST solution could still happen, the lack of progress in the last 10 or more years is not encouraging.
User roles
User-managed roles and directives can be crafted to emulate BibTeX-like operations, as in this Stack Overflow topic, but require additional markup in the file, and are limited to direct LaTeX output (as from
rst2latex). The output would also be largely uncoupled from pandoc.sphinxcontrib-bibtex
Sphinx is one of the most prominent reStructuredText writers.
sphinxcontrib-bibtexis an extension to Sphinx which enables LaTeX-like citations and bibliographies in Sphinx documentsion.sphinxcontrib-bibtexprovides a number of roles and directives to include and format bibliographic data, with most corresponding to equivalent LaTeX instructions. Most of this detail could be omitted and delegated to CSL.Proposal
Although something like
@muelleror[@mueller], withmuelleracting as a key to a bibliographic database, would be in close alignment with other formats, there is good reason to believe that this would be looked at unfavorably by the reST developers, and could conflict with future changes to[...]citation syntax.Adoption of new roles and directives
:cite:and.. bibliography::would not be inconsistent with the reST standard, which allows for writers to support new extensions. I don't think one needs to emulate the full set of extensions insphinxcontrib-bibtex, but these two constructs are natural choices which also match the existing--citeprocconstructs.The text was updated successfully, but these errors were encountered: