关于新版本pandoc中citeproc模块的处理

[huangy10]

在较新的版本的 pandoc 上，pandoc-citeproc 这个 filter 已经被标注为 deprecated，citeproc 功能被直接整合进了 pandoc 里面，通过 extra 参数 --citeproc 启用。估建议在 README.md 的例子中注明这一点。

Reference:

• https://github.com/jgm/pandoc-citeproc
• https://github.com/jgm/citeproc

[Ritsuka314]

@huangy10 thanks for your constant feedbacks!

This might not be a fix as easy as just changing the read-me.
When pandoc-citeproc was a filter,
one can specify its position relative to other filters,
and this plugin can handle that.
With citeproc no longer a filter,
and specified as a dedicated flag --citeproc,
this says that this flag
"behaves like a filter and can be positioned relative to other filters as they appear on the command line".
I realized with our current configuration scheme we do not have the full ability to position --citeproc "relative to other filters".

Now this plugin forces --citeproc (which is specified as extra) to come after the filter specifications.
@huangy10: if we are just talking about you specifically for now, is this undesirable?
If so I guess I can also rework the plugin so instead the current configuration scheme
one can write something like

pandoc:
  - -filter
  - <filter name>
  - -citeproc
  - -M
  - <meta key>=<meta value>
  - -f
  - markdown-smart+<other extension specs>
  - -t
  - html-smart
  - --mathjax

This would give users complete freedom in specifying pandoc arguments.
Indeed this breaks backward compatibility,
but I trust for any pandoc user this is not a big issue but contrararily removes inconsistency between how arguments would be supplied to pandoc directly from command line and indirectly through this plugin.

Since, correct me if I'm wrong, this problem is not critical to you,
and I'm having a busy month ahead of me,
I'm not going to implement the changes above very soon.
@huangy10 let me know if the issue is urgent,
or better, submit your own pull request, if my proposal above makes sense to you.

[huangy10]

Thank you for your reply.

I just wanna say that README.md should be modified to inform other users about this change (I met some trouble about this issue when migrating to newer pandoc). Confusion may arise for new users. Since you are busy recently, I can submit a PR to make necessary modifications.

[Ritsuka314]

If your concern is merely that the example given in read-me could cause confusion, then I'm more inclined to simply remove the example, since I could not find a better example. Do you know if there is any other widely used pandoc filter other than citeproc that I can use as a replace?

[sosiristseng]

FYI, the following (kinda) works for recent versions of pandoc:

_config.yml

pandoc:
  filters:
  extra:
  - citeproc:
  - bibliography: "pathto.bib"
  - csl: "yourstyle.csl"
  template:
  meta:
  mathEngine:

However, the generated bibliography does not blend well with non-citation footnotes, e.g. [^1]. I'm still trying the correct recipe.

[Ritsuka314]

The way your _config.yml looks to me suggests that whatever you mean by "the generated bibliography does not blend well with non-citation footnotes" should not be caused by this plugin (and how it passes arguments to pandoc), since you did not specify any filters. That is just my guess though. I will take a test once I get some time in recent days.

[sosiristseng]

The way your _config.yml looks to me ...

Thank you for your prompt reply. I tried removing the filters: you mentioned. And the results were still the same. I'll try to give out as much information as I can.

Rendered result

The markdown file

---
title: First post
date: 2020-06-28 16:47:33
tags: ["test"]
categories: ["Test"]
sticky: 100
---

The stuff you'll see in the front page.

<!-- more -->

Set `sticky: 100` in the frontmatter to pin this post on top.

[@Julia-2017]

Test[^2]

---

[^2]: a footnote

Config

_config.yml

# Hexo Configuration
## Docs: https://hexo.io/docs/configuration.html
## Source: https://github.com/hexojs/hexo/

# Site
title: Site title
subtitle: Site subtitle
description: Site description
keywords:
author: Your name
language: en
timezone: ''

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: https://sosiristseng.github.io
root: /template-hexo-next/
permalink: :category/:title/
permalink_defaults:
pretty_urls:
  trailing_index: false # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: false # Set to false to remove trailing '.html' from permalinks

# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: code
i18n_dir: :lang
skip_render: ['code/**']

# Writing
new_post_name: :title.md # File name of new posts
default_layout: post
auto_spacing: true  # Similar to hexo-pangu
titlecase: false # Transform title into titlecase
external_link:
  enable: true # Open external links in new tab
  field: site # Apply to the whole site
  exclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: false
relative_link: false
future: true
highlight:
  enable: true
  line_number: true
  auto_detect: false
  tab_replace: '    '
  wrap: true
  hljs: false

# Pandoc config (optional): https://github.com/wzpan/hexo-renderer-pandoc

# Home page setting
# path: Root path for your blogs index page. (default = '')
# per_page: Posts displayed per page. (0 = disable pagination)
# order_by: Posts order. (Order by date descending by default)
index_generator:
  path: ''
  per_page: 10
  order_by: -date

# Category & Tag
default_category: uncategorized
category_map:
tag_map:

# Metadata elements
## https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
meta_generator: true

# Date / Time format
## Hexo uses Moment.js to parse and display date
## You can customize the date format as defined in
## http://momentjs.com/docs/#/displaying/format/
date_format: YYYY-MM-DD
time_format: HH:mm:ss
updated_option: mtime

# Pagination
## Set per_page to 0 to disable pagination
per_page: 10
pagination_dir: page

# Include / Exclude file(s)
## include:/exclude: options only apply to the 'source/' folder
##
include:
exclude:
ignore:

# Plugins: https://hexo.io/plugins/
## Seach data generator plugin for Hexo
## https://github.com/theme-next/hexo-generator-searchdb
search:
  path: search.json
  field: all
  content: true
  format: striptags

# Themes: https://hexo.io/themes/
# Next theme: https://theme-next.js.org/
theme: next

# markdown-renderer-pandoc config: https://github.com/wzpan/hexo-renderer-pandoc

pandoc:
  extra:
  - citeproc:
  - bibliography: "julia.bib"
  - csl: "vancouver-brackets.csl"
  template:
  meta:
  mathEngine:

BibTex

% This article is the definitive citation for Julia.
@article{Julia-2017,
    title={Julia: A fresh approach to numerical computing},
    author={Bezanson, Jeff and Edelman, Alan and Karpinski, Stefan and Shah, Viral B},
    journal={SIAM {R}eview},
    volume={59},
    number={1},
    pages={65--98},
    year={2017},
    publisher={SIAM},
    doi={10.1137/141000671},
    url={https://epubs.siam.org/doi/10.1137/141000671}
}

% For more details on research related to Julia, see https://julialang.org/research

package.json

{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "hexo g",
    "clean": "hexo cl",
    "server": "hexo cl && hexo s -o --debug",
    "gzipper": "gzipper",
    "compress": "gzipper compress ./public --deflate --brotli"
  },
  "hexo": {
    "version": "5.4.0"
  },
  "dependencies": {
    "gzipper": "^5.0.0",
    "hexo": "^5.4.0",
    "hexo-generator-archive": "^1.0.0",
    "hexo-generator-category": "^1.0.0",
    "hexo-generator-index": "^2.0.0",
    "hexo-generator-searchdb": "^1.3.4",
    "hexo-generator-tag": "^1.0.0",
    "hexo-renderer-ejs": "^1.0.0",
    "hexo-renderer-pandoc": "^0.3.0",
    "hexo-renderer-stylus": "^2.0.1",
    "hexo-server": "^2.0.0",
    "hexo-theme-next": "^8.7.0",
    "hexo-word-counter": "^0.0.3"
  }
}

Style: Vancouver brackets

[huangy10]

@ sosiristseng Are you expecting that the references generated by bib file and footnotes to be placed in the same section?

[Ritsuka314]

@sosiristseng Your rendered result looks completely reasonable to me. So I guess @huangy10 is right: @sosiristseng you want references and footnote texts to be placed in the same list. Looking at Pandoc's code, I don't think this is possible. Moreover, it looks like Pandoc is suggesting bibliography items are ontologically distinctive from footnotes, which I find reasonable.

It might be possible to have bib items and footnotes in the same list, perhaps in the order of their first appeariences, by invoking a customized pandoc filter after calling citeproc (which involves my earlier discussion). However I envision that writing such a filter requires quite some consideration, for example, what if an author-year citation style is used? This could be one major reason to treat bib items and footnotes ontologically differently.

@huangy10 I just realized that I never tied up the end of our earlier discussion. Hopefully I will be able to find some time recently and quickly build a prototype.

[sosiristseng]

@RichardYan314 @huangy10 Yes, I thought pandoc would generate Markdown footnotes for citations. Thank you for pointing out that was not the case.

[Ritsuka314]

Please see the new readme.md for a new interface for passing arguments to pandoc.