Skip to content

Support --citeproc in reStructuredText #9904

Closed
@marshallward

Description

@marshallward

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 --bibliography and 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. Additional bibliography:: options, such as :all:, could also be supported.

These extensions are currently supported by sphinxcontrib-bibtex extension 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-bibtex is an extension to Sphinx which enables LaTeX-like citations and bibliographies in Sphinx documentsion.

sphinxcontrib-bibtex provides 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 @mueller or [@mueller], with mueller acting 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 in sphinxcontrib-bibtex, but these two constructs are natural choices which also match the existing --citeproc constructs.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions