中文 Styles 仓库建设构想

[northword]

接续前讨论：redleafnew/Zotero_introduction#1 (comment) 与 https://github.com/orgs/zotero-cn/teams/developer/discussions/1/comments/3

当前已存在多为中文 CSL 维护者，为 CSL 中文生态做出了重要贡献。但也导致了存储库分布碎片化，不利于查找和持续性维护。

此议题讨论将多个 CSL 中文仓库合并的可行性，以及如果可行，该如何合并，合并后如何维护等相关问题。

[northword]

根据之前的讨论，我提出以下两种方案：

1. 不设置 zotero-cn/styles 仓库，目前几个主要仓库中，由韩老师维护的 redleafnew/Chinese-STD-GB-T-7714-related-csl 最为全面，最为活跃，因此可以将此仓库作为主要仓库进行维护，其余几个仓库以合适的方式将文件提交到该仓库。
2. 所有的样式都导入 zotero-cn/styles ，可以参考 https://zhuanlan.zhihu.com/p/350987211，https://blog.csdn.net/qq_14824885/article/details/113865296 或类似的方法，将几个仓库合并为一个仓库，被合并的仓库所有者为新仓库的 Maintainer 或 admin，可以具备新仓库的完全控制权。这样的问题在于无法保留 issue 和 pr。

我对 git 并不太熟悉，这只是我的个人想法，不清楚可行性，具体要看 @zepinglee @redleafnew @EdwardSaidZhou 您们的想法。

[redleafnew]

还要考虑很多人上不了github，最好能自动同步到gitee

[northword]

还要考虑很多人上不了github，最好能自动同步到gitee

是的，镜像到 gitee 是应该有的，这个在合并完成后配置一份 workflow 就可以实现。

[EdwardSaidZhou]

我支持统一纳入zotero styles仓库，镜像到gitee确实方面了很多不能上github的人

[zepinglee]

两种方案都差不多，因为 EdwardSaidZhou/CSL-Chinese-IR-CSSCI-Journals 中的 commit 信息比较有限。

还有需要考虑的是，redleafnew/Chinese-STD-GB-T-7714-related-csl 中的文件名都是以期刊英文全称命名（按照 CSL 官方样式），而且有编号作为前缀。如果要将 EdwardSaidZhou/CSL-Chinese-IR-CSSCI-Journals 合并进来的话，需要 @EdwardSaidZhou 修改文件名并进行编号。

[northword]

如下一条所说，我认为在这种类型的仓库中，相比于使用编号前缀来区分分类，文件夹分类是一种好的管理方式；

我们也可以维护一个单独的文件，也许可以是一个 yaml 文件，在里面记录所有样式的名称、分类、预览、参考标准、贡献者等，每次提交时将其信息渲染为带筛选的 html 。或者直接从 csl 文件里读取这些信息。
当然这个可能需要比较大的编程量，可行性有待评估。

[zepinglee]

我也不喜欢太喜欢编号前缀，主要是因为顺序比较混乱。比如

002gb-t-7714-2015-numeric-bilingual-no-uppercase-no-url-doi.csl
003gb-t-7714-2015-numeric-bilingual-no-url-doi.csl
007gb-t-7714-2015-numeric-bilingual-no-uppercase.csl
009gb-t-7714-2015-numeric-bilingual-no-uppercase-page-out.csl

但是征求一下 @redleafnew 的意见

[redleafnew]

我都可以，用编号的原因也是为了更好的分类，有更好的方法也行。

[northword]

这一条作为无论合并与否，合并到哪都适用的想法，关于 styles 仓库的目录组织。我同意 citation-style-language/styles#4473 的提议，将样式文件移入其单独的文件夹，而不是散落在仓库根目录，这样过长的文件列表导致用户忽略 README 和 Preview。

目录可以有以下几种方案：

.
├─docs/        # 存放除此之外的一些文档
├─gb-7714/     # 可以考虑直接引用官方仓库（如果可行）
├─journal/     # 期刊所用的样式
├─others/      # 专著、自定义等
├─thsis/       # 学位论文用的样式
├─CHANGLOG.md  # 变更日志
├─PREVIEW.md   # 存放预览
└─README.md    # 存放项目说明，链接到预览和变更日志

其中“journal”、“thsis”、“others”也可以用“author-date”、“numeric”、“note”来代替。

再者，CSL 文档应引入 styles 库和 preview.md 的链接，如果可行，可以将 preview 直接嵌入文档（这并不是说把 preview.md 放在文档库 csl-doc-chinese 维护，这个记录预览的文件仍在 styles 仓库，只是 csl-doc-chinese 仓库在构建时，直接从 styles 仓库读取 preview 相关的内容并渲染。）

抛砖引玉，欢迎其他更好的想法加入。

[zepinglee]

这一条作为无论合并与否，合并到哪都适用的想法，关于 styles 仓库的目录组织。我同意 citation-style-language/styles#4473 的提议，将样式文件移入其单独的文件夹，而不是散落在仓库根目录，这样过长的文件列表导致用户忽略 README 和 Preview。

目录可以有以下几种方案：

其中“journal”、“thsis”、“others”也可以用“author-date”、“numeric”、“note”来代替。

我赞同，原本仓库文件数量不多时放在根目录确实影响不大。但目前仓库中已经有 56 个 csl 样式，感觉分子目录存放更合适。

再者，CSL 文档应引入 styles 库和 preview.md 的链接，如果可行，可以将 preview 直接嵌入文档（这并不是说把 preview.md 放在文档库 csl-doc-chinese 维护，这个记录预览的文件仍在 styles 仓库，只是 csl-doc-chinese 仓库在构建时，直接从 styles 仓库读取 preview 相关的内容并渲染。）

这个主意不错。我对构建网页不太熟，担心工作量可能有些大。

[northword]

这个主意不错。我对构建网页不太熟，担心工作量可能有些大。

如果 styles 仓库有一份维护相对良好的 preview.md 的话，在文档中引用的工作量应该不大，只是构建前复制这个文件就行，我回头测试一下。

难点在于如何维护 style 仓库的 preview。目前的方式就是手动维护，而我期望中的应该是类似于官方仓库提交 pr 就自动生成预览的方式，当有提交时，预览可以自动写入到一个文件，这样可以让所有的引用条目一致，方便对比。
最终渲染到网页会类似 zotero.org/style 这种可以悬浮预览。
但是工作量可能有一些大，因为我对这些也不熟悉，只能边学边搞。

对于自动化生成预览，我有一个粗糙的思路：
编写一个 Python 脚本，使用 xml 相关的库遍历仓库内的 csl 文件，读取 info 元素，参考官方仓库的方法生成预览，将 info 元素与预览写入 markdown 文件，通过静态页面生成器构建网页。

写入时，可以写成多个文件，按类别分开。
既可以写成现在这样预览直接出现在样式标题下的，也应该可以生成像 zotero 官方样式安装界面那样悬浮在标题上面显示预览的模式。

每一次提交后，通过 workflow 触发脚本运行。

读取到的数据可以分配一个 uuid，将信息写入一个文件或为每一个文件生成 uuid.md ，之后的 workflow 可以通过 files changed 只执行有更改的文件，提高效率。
这只是一个思路，目前不清楚可行性。

[ZMAlt]

编写一个 Python 脚本，使用 xml 相关的库遍历仓库内的 csl 文件，读取 info 元素，参考官方仓库的方法生成预览，将 info 元素与预览写入 markdown 文件，通过静态页面生成器构建网页。

如果 styles 和 CSL 中文文档 单独生成静态站的话，就比较容易一些。现在有些静态站是可以使用 csl 文件的，这样似乎可以直接生成预览。CSL 中文文档可以直接链接过去。

[northword]

编写一个 Python 脚本，使用 xml 相关的库遍历仓库内的 csl 文件，读取 info 元素，参考官方仓库的方法生成预览，将 info 元素与预览写入 markdown 文件，通过静态页面生成器构建网页。

生成预览的可能方案：通过 citeproc-node 生成引文和书目的 html ，写入文件。

citeproc-node 文档及库：

• https://www.zotero.org/support/dev/citation_styles/citeproc-node
• https://github.com/zotero/citeproc-js-server

citeproc-node 使用 json 语法的 csl 文件 。
库中提供了一个 py 脚本将 xml 语法的 csl 转换为 json 语法的 csl，(这个脚本还有不能读取 gbk 的 bug，解决)

然后运行 citeproc-js-server ，会创建一个转换的服务器，向服务器提供条目信息，就可以返回引文和引文列表。
但是很奇怪，当响应格式为 html 时，即便按 文档 配置了 citations=1 ，都没能输出引文；而响应格式为 json 时就可以，似乎是有 bug 。

先放在这里做个记录，之后再琢磨琢磨。

[northword]

刚刚仔细看了一下这个项目，原来是在 citeproc-js 的基础上的服务器端程序。不过我自己开发 csl 时其实是用 node 在本地跑生成 markdown/html 格式（https://github.com/zepinglee/csl-development），可以作为参考。https://github.com/redleafnew/Chinese-STD-GB-T-7714-related-csl/blob/main/README.md 中由我填写的示例基本都是用这个工具生成的。

收到，我这段时间琢磨一下。

在 styles 仓库 有个基于这个服务器端的例子，虽然还非常不完善。

这段时间文章返修一直在补实验，都没顾得上搞这些🌚🌚

[northword]

不过我自己开发 csl 时其实是用 node 在本地跑生成 markdown/html 格式（https://github.com/zepinglee/csl-development），可以作为参考。https://github.com/redleafnew/Chinese-STD-GB-T-7714-related-csl/blob/main/README.md 中由我填写的示例基本都是用这个工具生成的。

@zepinglee 想向您请教一个小问题，关于 CSL 规范中 second-field-align 这一选项对输出的影响，规范说这个显示效果是由调用程序实现，但是具体的，悬挂或序号后空格多少字符也是由调用程序自己决定嘛，有什么约定俗成或规范嘛？————如果是做这种预览的话，就由我们自己定？

---

另一个疑惑

当 CSL 中未设置该项时，该选项值为默认值 False ，citeproc 输出的内容为：(对于某一条，以GB顺序编码为例)

  <div class="csl-entry">
    [1]MALONE K. Chapters on Chaucer[M]. Baltimore: Johns Hopkins Press, 1951.
  </div>

当该选项已配置，无论配置为 flush 还是 margin，输出均为：

  <div class="csl-entry">
    <div class="csl-left-margin">[1]</div><div class="csl-right-inline">MALONE K. Chapters on Chaucer[M]. Baltimore: Johns Hopkins Press, 1951.</div>
  </div>

未包含长度/宽度信息，我注意到您在 csl-development 仓库直接把 <div class="csl-left-margin">[1]</div><div class="csl-right-inline"> 格式化为了 序号+空格 ，这样岂不是不能体现出是 flush 还是 margin?

还是说，我们预览其实可以不管这个，毕竟这个格式可以在 WORD 书目样式里调整。

[zepinglee]

@zepinglee 想向您请教一个小问题，关于 CSL 规范中 second-field-align 这一选项对输出的影响，规范说这个显示效果是由调用程序实现，但是具体的，悬挂或序号后空格多少字符也是由调用程序自己决定嘛，有什么约定俗成或规范嘛？————如果是做这种预览的话，就由我们自己定？

缩进的量一般不用空格数量控制，而是用 html/css 控制具体长度。比如 Zotero 的“Create bibliography from item”导出 html 格式是：

  <div class="csl-entry" style="clear: left; ">
    <div class="csl-left-margin" style="float: left; padding-right: 0.5em;text-align: right; width: 1em;">[1]</div>
    <div class="csl-right-inline" style="margin: 0 .4em 0 1.5em;">陈登原, 国史旧闻, vol. 第 1 卷. 北京: 中华书局, 2000, p. 29.</div>
  </div>

另外 Word 中这里会插入一个制表符，这样用户可以通过设置制表符宽度和悬挂缩进宽度以实现对齐的效果。

另一个疑惑

当 CSL 中未设置该项时，该选项值为默认值 False ，citeproc 输出的内容为：(对于某一条，以GB顺序编码为例)

  <div class="csl-entry">
    [1]MALONE K. Chapters on Chaucer[M]. Baltimore: Johns Hopkins Press, 1951.
  </div>

当该选项已配置，无论配置为 flush 还是 margin，输出均为：

  <div class="csl-entry">
    <div class="csl-left-margin">[1]</div><div class="csl-right-inline">MALONE K. Chapters on Chaucer[M]. Baltimore: Johns Hopkins Press, 1951.</div>
  </div>

我看了一下 citeproc-js 的实现，发现其中似乎无法区分 flush 和 margin。

未包含长度/宽度信息，我注意到您在 csl-development 仓库直接把 <div class="csl-left-margin">[1]</div><div class="csl-right-inline"> 格式化为了 序号+空格 ，这样岂不是不能体现出是 flush 还是 margin?

还是说，我们预览其实可以不管这个，毕竟这个格式可以在 WORD 书目样式里调整。

那个主要是为了照顾 markdown 的显示。因为 md 中 html 的 style 属性无效，所以不能像正常 html 一样显示对齐效果。所以我就只能把其中改成一个大空格了（em space）。

[northword]

原来是这样，明白了，谢谢！

citeproc-js 可以区分 flush 和 margin，是在 make_bibliography 返回值的第 0 项里有一个 key 为 second-field-align 键值对，不过确实无法从输出的 html 上直接区分。

[zepinglee]

citeproc-js 可以区分 flush 和 margin，是在 make_bibliography 返回值的第 0 项里有一个 key 为 second-field-align 键值对，不过确实无法从输出的 html 上直接区分。

原来是这样，我忽略第 0 项的参数。

[zepinglee]

我有个想法，每个样式单独保存在一个目录，其中再保存用于示例展示和开发测试的 CSL-JSON 信息，比如 test-cites.json 和 test-data.json 。这样可以更好地展示官方示例的效果。比如《法学引注手册》样式中规定了法律条文和司法案例的格式，但是其他的样式（如 GB/T 7714）的示例中很少有法律专业的文献，所以特定的文献更适合用于展示示例。

另外一个好处是，可以用于开发 csl 时每次修改后展示结果的变化，有些类似单元测试。比如在每次 commit 后由 github action bot 对每个 style 跑一遍测试，如果有修改则由 bot commit 一次信息。

[redleafnew]

我都可以，但我这些东西都不了解。

[northword]

最初我也这么想，但是这样的话，每个文件夹下都有一个示例数据，然而很多样式其实是可以共用一个示例数据的，这样就会造成大量冗余。

或许也可以用一个专门的文件夹存放示例数据，在一个文件内指定样式应用哪个示例数据。
不过这样就是比同一文件夹存放麻烦了一些，算是各有优劣。

或者就是，每个样式一个文件夹，如果该样式下没有示例数据，就用默认的，如果有，就用文件夹下的。

[zepinglee]

或者就是，每个样式一个文件夹，如果该样式下没有示例数据，就用默认的，如果有，就用文件夹下的。

我比较倾向于这个方案，目前 csl-development 也是这么做的。另外这 8 个示例是从 GB/T 7714 的官方示例中挑选出来的，比较有代表性，可以用作默认示例。

https://github.com/zepinglee/csl-development/blob/c929a646ac9d95ba0504959876cfc3ddafc5317e/gbt7714-cites-numeric.json#L3-L28