你的CITATION.cff格式正確嗎？ 用CITATION.cff驗證工具來檢查吧！ / Is Your CITATION.cff Format Correct? Check It With the CITATION.cff Validator!
CITATION.cff是用於記錄供人引用資訊的一種YAML純文字格式。那要怎麼知道自己寫的CITATION.cff是否正確呢？我們可以用R套件cffr來驗證。我在Colab把它寫成了可以線上使用的CITATION.cff驗證工具了，讓我們一起來看看怎麼使用吧。
CITATION.cff is a plain text YAML format for recording citation information. How can you tell if your CITATION.cff is correct? We can use the R package cffr for validation. I've created an online CITATION.cff validator using Colab. Let's take a look at how to use it.
CITATION.cff的功能與格式 / Citation.cff's Function and Schema
https://carpentries.org/blog/2024/07/lesson-cffs/
CITATION.cff (Citation File Format) 檔案旨在提供一種人類和機器都能讀取的軟體引用資訊格式。藉由在軟體儲存庫的根目錄放置這個檔案，開發者可以清楚地告知使用者如何正確地引用他們的軟體(software)或資料集(dataset)，提升學術交流的效率和資料的正確性。這對於確保軟體開發者得到應有的認可，以及方便其他研究者追蹤和重現研究結果至關重要。CITATION.cff 的使用也提升了軟體的可搜尋性和可重複使用性，進而推動更開放和合作的科學研究生態。
CITATION.cff 檔案採用 YAML 1.2 格式，這是一種人類可讀且機器易於解析的純文字格式。檔案內容以鍵值對的形式呈現軟體的後設資料，例如軟體名稱 (title)、作者 (authors) 、版本 (version)、授權方式 (license)、程式碼儲存庫網址 (repository-code)等。這樣的格式讓使用者可以輕鬆地理解和更新引用資訊，同時也方便各種工具自動解析和轉換這些資訊，例如產生不同引用格式（MLA, APA, Chicago 等）的引用條目。
CITATION.cff線上產生器 / CFF initializer
https://citation-file-format.github.io/cff-initializer-javascript/
雖然CITATION.cff是可以讓人自由編寫的純文字檔案，但它背後還是有很多規範好的格式。為了讓大家更容易產生格式正確的CITATION.cff，你可以使用cffinit網站來創建檔案。
cffinit用表單形式帶大家一步一步填寫資料，同時也驗證你填寫的資料符合CFF的規範。填寫完成後，就可以直接下載它幫你創建好的CITATION.cff，真的是非常方便。
使用CITATION.cff / Using CITATION.cff
如果你已經準備好CITATION.cff，(1) 那你可以把它上傳到GitHub保存庫的根目錄底下。(2) 接著GitHub會分析你的CITATION.cff，並開啟「Cite the repository」的功能。(3) 最後其他人就可以用此功能取得引用此保存庫的APA或BibTeX格式。
cffr套件 / R Package: cffr
https://cran.r-project.org/web/packages/cffr/index.html
cffr 套件是一個專門為 R 語言使用者設計的工具，用於產生和驗證 CITATION.cff 檔案 (Citation File Format)，讓軟體的引用資訊更容易被讀取和使用。cffr 套件本來的用途是自動產生R套件的CITATION.cff，不過它還能驗證 CITATION.cff 檔案的有效性、解析CFF檔案中的各個組成部分（例如作者、額外引用等）等功能。而我們這篇就是使用cffr的驗證功能cff_validate()來檢查CITATION.cff是否符合規範。
CITATION.cff驗證工具 / CITATION.cff Validator
我使用Google Colab撰寫了R的筆記本(notebook)，讓使用者可以上傳多個CFF檔案，並直接使用cffr套件來驗證各個CFF檔案是否正確。
https://github.com/pulipulichen/Colab-CITATION.cff-Validator
筆記本跟相關檔案保存在GitHub。接下來我們會用這份筆記本與相關檔案來說明CITATION.cff驗證工具如何使用。
CFF範例檔案 / CFF Example Files
- CITATION_complete.cff：正確格式的CFF檔案
- CITATION_error.cff：錯誤格式的CFF檔案
我從cffr套件裡面借來了兩個CFF檔案。CITATION_complete.cff是正確的檔案，而CITATION_error.cff檔案裡面的內容則是有各種問題。就讓我們用這個兩個檔案作為例子，看看怎麼在Colab上使用CITATION.cff驗證工具吧。
操作說明 / Instruction
接下來我們來看看要怎麼使用CITATION.cff驗證工具。
首先請先進入以下網址：
在右上角的位置按「Sign in」，登入你的Google帳號。
(1) 打開左邊的的檔案側邊欄，(2) 等待「sample_data」資料夾出現。
按下上傳檔案的圖示，選擇你要檢查的CFF檔案上傳，例如「CITATION_complete.cff」。這份檔案只會保存在你帳號底下臨時創建的虛擬機器裡，其他人不能讀取。
第一次上傳的時候會出現警告訊息。這是為了提醒你，虛擬機器在斷線之後就會移除檔案，請不要用它來保存重要資料。按下「OK」後繼續下一步。
確認CFF檔案已經上傳上去。要注意不要上傳到「sample_data」裡面了。
(1) 在上方工具列進入「Runtime」，(2) 然後按下「Run all」。
第一次執行會跳出提示訊息。由於這份notebook是我創建的，並非官方認證的程式碼，執行時可能會有些風險。如果你覺得程式碼不安全的話，可以自行檢視或修改程式碼之後再執行。如果你覺得沒問題的話，按下「Run anyway」執行即可。
第一次執行要安裝cffr套件，需要花上比較多時間。執行完成後，右邊筆記本最下面就會出現驗證結果。如果CFF沒有問題的話，就會出現「/content/CITATION_complete.cff is valid.」的訊息。
錯誤訊息與修正 / Error Messages and Corrections
接下來我們換上傳CITATION_error.cff並執行驗證看看，結果會出現以下錯誤訊息：
✖ Oops! /content//CITATION_error.cff has the following errors:
* cff: has additional properties
* cff.authors.0: no schemas match
* cff.doi: referenced schema does not match
* cff.keywords.0: is the wrong type
* cff.license: referenced schema does not match
* cff.url: referenced schema does not match
/content//CITATION_error.cff is invalid.
你可以把這段錯誤訊息，連同有錯誤的CFF檔案，一起上傳到ChatGPT。
ChatGPT會跟你解釋錯誤的原因，並提供可能的修正方案。這對修正CFF有很大的幫助。
https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md
如果想要確認更多CFF格式的細節，請從「Guide to Citation File Format schema version 1.2.0」說明裡面找找線索吧。
結語 / Conclusion
https://github.com/pulipulichen/Colab-CITATION.cff-Validator/blob/main/CITATION.cff
CITATION.cff是用純文字的檔案構成。雖然可以讓人用文字編輯器自由編輯，但它本身還是要遵循YAML的規範，以及CFF所規範的特定欄位。
為了確定我編輯的CITATION.cff符合規範，我才利用了cffr套件創建了這個CITATION.cff驗證工具。而這個工具的確幫助我糾正了之前在創建CITATION.cff時很多填錯的地方，真是幫了大忙。
希望這個CITATION.cff驗證工具也能幫上你的忙，也藉此鼓勵大家建立容易讓其他人引用的CITATION.cff資訊吧。
這篇關於CITATION.cff驗證工具的介紹就到這裡了。文章最後要來問大家的是：你會怎麼引用別人的軟體呢？
- 1. 用網址引用。
- 2. 找找看有沒有已經發表的期刊或研討會論文，引用論文本身。
- 3. 參考CITATION.cff來引用。
- 4. 「轉載自網路」。
- 5. 什麼是引用？
- 6. 其他：歡迎在下面留言，分享你的看法吧！
