Citation Style Language 入門理解

💡 這篇文章將幫助你快速了解CSL的結構邏輯，以及常用參數和變數所代表的意義。

我先前在⟨自訂Zotero的引註格式⟩一文中提到，可以透過自訂CSL的方式完成自動引註。

但在台灣使用CSL有一個問題是，多數的學術研究都需要引用大量國內外的資料，也就是說，引用的文獻中，會同時存在中文、英文，甚至日文、德文、法文等多國語言，偏偏不同語言有不一樣的引註格式。

還好，這個問題在台灣已經有前輩pulipuli嘗試處理過，並且製作出可同時輸出中文及英文參考文獻的CSL Script。pulipuli前輩是以APA 6為藍本進行修改，但APA註腳(footnote)的格式過於簡略，不符合法律學門的引註習慣。

因此我決定踩著前人的肩膀，以Chicago Manual of Style 17th edition (full note)為藍本，自己修改一套可同時輸出中英文參考文獻的CSL樣式。由於我自身使用的需求，中文引註格式我以政大法學評論的格式為標準，加入Chicago樣式中。

以語言區分輸出格式並未被載入官方的CSL 1.0.2 Specification中，因此匯入Zotero等文獻軟體時，會出現非有效樣式的警告，但仍可正常引用、顯示。

以下簡單紀錄我理解CSL的過程，並將我開發的CSL樣式上傳至Github，造福更多為引註所苦的研究人員。如果有人願意贊助，或許我可以持續開發更多符合台灣各種學門的多語言CSL樣式。

Github 開源專案

政大芝加哥中英文樣式：Mandarin-NCCULR_Chicago_Gong.csl

CSL 1.0.2 Specification

碼農們都知道，當coding遇到問題時，一定先看看Stack Overflow上有沒有遇過一樣的問題，最好有現成的code可以複製貼上；或是把code丟給時下最流行的ChatGPT幫忙debug。但由於CSL屬於XML語言的一種，又是針對「引註」這個特定目的而生的語言，網路上的討論與資源相對少。因此除了模仿pulipuli前輩和Github上其他專案之外，免不了還是得自己看spec。

由於我只有少少的程式語言基礎，一開始就從spec著手有些不得要領，經過一連串的試錯後，我才大致理解CSL語言的架構，並能透過查找spec來解決問題。

宣告

前面提到，CSL屬於XML的一種，因此開頭必須進行XML的宣告。

<?xml version="1.0" encoding="utf-8"?>

主結構

Styles

接著便是CSL的主要內容，在「cs:style」中呈現。「cs:style」有幾種常用的參數：

1. class：用以表示內文中的引用格式，有「in-text」和「note」兩種，分別指在文中直接嵌入引用，或以註腳方式呈現。
2. version：表示CSL的版本，1.0以前的版本無法與1.0以後的版本相容。
3. initialize-with-hyphen：英語或拉丁語系的姓名通常可分為「family name(姓)」、「given name(名)」，而「given name(名)」可能不止一個單字，單字與單字之間是否要用「-」連接，如：Jean-Luc。
4. demote-non-dropping-particle：有些姓名可能還含有「name particles(中間名)」，然而根據語言的不同，有些中間名必須跟隨「family name(姓)」，而有些則是跟隨「given name(名)」。這會影響姓名簡寫，或參考文獻將姓氏移列在前時的呈現，如Vincent van Gogh的「van」即屬中間名。此參數分為三種，「never」會將必須跟隨姓的中間名前置，如van Gogh, Vincent、不跟隨姓的中間名留下，如Humboldt, Alexander von；「sort-only」效果與never相同，但排序時使用姓氏排序，如van Gogh, Vincent會以G排序；「display-and-sort」則是中間名均不跟隨姓，並以姓氏排序，如Gogh, Vincent van會以G排序。

<style xmlns="<http://purl.org/net/xbiblio/csl>" class="note" version="1.0" initialize-with=". " demote-non-dropping-particle="sort-only">

而「cs:style」下，有幾種常見的子元素：

1. info：必須為第一個出現的子元素，包含樣式名稱、開發者名稱等。
2. locale：可能出現多次，在不同語系時覆蓋一些原始設定，如可使用<terms>標籤指定在zh-TW語系時translator應縮寫為「譯」而非原始的「trans.」；或使用<date>標籤，指定year在文字模式時應顯示為「年」。
3. macro：類似函式的作用，可以想像成模組，用來描述各種欄位的規則，如author、publisher等，並可被其他macro呼叫組成更大的模組，最後拼成完整的引註規則。
4. citation：實際定義引註格式的區域，但習慣上會用一個大的macro包好，在citation欄位直接呼叫一次包好的macro即可。
5. bibliography：實際定義參考文獻的區域，與citation相同，習慣上會先用一個大的macro包好再呼叫，如要做出雙語言或多語言版本的參考文獻，就必須善用此技巧，以免bibliography過於肥大。

<style xmlns="<http://purl.org/net/xbiblio/csl>" class="note" version="1.0" initialize-with=". " demote-non-dropping-particle="sort-only">
<info>
  <title>．．．</title>
  <title-short>．．．</title-short>
  <id><http://www.zotero.org/styles/．．．></id>
  <link href="<http://www.zotero.org/styles/．．．>" rel="self"/>
  <link href="<http://www.zotero.org/styles/bluebook-law-review>" rel="template"/>
  <author>
    <name>Gong Y.B.</name>
    <email>．．．</email>
  </author>
  <category citation-format="note"/>
  <category field="law"/>
  <updated>2023-12-06T00:48:17+00:00</updated>
  <rights license="<http://creativecommons.org/licenses/by-sa/3.0/>">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
</info>
<locale xml:lang="en">
  <date form="text" delimiter=" ">
    <date-part name="day"/>
    <date-part name="month" form="numeric"/>
    <date-part name="year"/>
  </date>
  <terms>
    <term name="accessed">last visited</term>
    <term name="page" form="short">p</term>
  </terms>
</locale>
<locale xml:lang="zh">
  <date form="text">
    <date-part name="year" form="numeric" suffix="年" range-delimiter="-"/>
    <date-part name="month" form="numeric" suffix="月" range-delimiter="-"/>
    <date-part name="day" form="numeric" suffix="日" range-delimiter="-"/>
  </date>
  <terms>
    <term name="accessed">最後瀏覽日</term>
    <term name="editor" form="short">编</term>
    <term name="translator" form="short">譯</term>
    <term name="page" form="short">頁</term>
  </terms>
</locale>
<locale>
  <style-options punctuation-in-quote="false"/>
  <terms>
    <term name="page-range-delimiter">-</term>
  </terms>
</locale>

<macro name="author-zh">
  <names variable="author">
    <name delimiter="、" delimiter-precedes-et-al="never"/>
    <substitute>
      <names variable="editor" suffix="編"/>
    </substitute>
  </names>
</macro>

<citation et-al-min="3" et-al-use-first="1" et-al-subsequent-min="3" et-al-subsequent-use-first="1">
  <layout suffix="。" delimiter="，">
    <!-- 直接呼叫包好的macro "citation-layout-zh" -->
    <text macro="citation-layout-zh"/>
  </layout>
</citation>

<bibliography second-field-align="flush" name-as-sort-order="all" et-al-min="0" et-al-use-first="6">
  <layout suffix="。">
    <text macro="citation-number"/>
    <!-- 直接呼叫包好的macro "source-bib-zh" -->
    <text macro="source-bib-zh"/>
  </layout>
</bibliography>
</style>

Types

基本上在style中就已經定義完所有引用與參考文獻的格式了，但在定義的過程中，我們需要根據文獻的種類而有不同格式定義，如書籍和期刊文章的引註格式就有所不同。以下是CSL中常用的幾種文獻類型：

Variables

在定義的過程中，我們需要取用資料庫中的欄位資料，以決定引註中應該出現哪些欄位資料、出現的順序等。以下是CSL中常見的變數與對應的欄位名稱：

另外還有一些不是直接對應資料庫欄位的變數，通常是經過欄位資料計算而來。

結語

由於沒有太深厚的程式基礎，一開始直接啃spec非常辛苦，也不得要領。借助各種教學文章、試誤與觀察他人專案的方式，才漸漸摸懂了CSL語言的結構，以及該如何寫出符合引註規範的CSL Script。

但搞懂CSL語言還不夠，要編寫一份CSL Script，最困難的莫過於將文字敘述的引註規則（如Bluebook）轉化為程式邏輯，再透過上面的變數以及語法一一實現。與法律相同，寫法不會只有一種，也可能隱藏著一些bug，必須實際使用才能發現，因此往後必定還會有各種更新維護，更別提引註規則可能也會變更。

我研究CSL的初衷在於希望減少重複、繁瑣的事情，並專注於研究上，不是花一堆時間一直複製貼上作者、期刊名、頁數。雖然初期學習、開發的時間可能多過於用老方法慢慢複製貼上，但一旦開發完成，往後在整理引註與參考文獻就是三秒鐘完成。希望我這個side-project可以幫助到同樣從事研究的人，在研究路上少浪費一點力氣。