사용법

참고문헌과 Word

같은 원고에서 세 갈래로 나갈 수 있습니다. 어느 길이 맞는지는 "그 문서가 앞으로 어디서 고쳐지는가"로 정합니다.

#세 갈래

flowchart TB
  M["citekey로 쓴 원고"] --> Q{"문서를 계속 고칠 곳은?"}
  Q -->|"Obsidian"| A["참고문헌 구역<br>Insert or update references section"]
  Q -->|"한 번 내보내고 끝"| B["pandoc kit<br>citeproc이 글자로 그림"]
  Q -->|"Word에서 공저자와"| C["Word kit<br>Zotero 필드로 넘김"]
  A --> A1["노트 끝의 참고문헌"]
  B --> B1["정적 docx"]
  C --> C1["Word의 Zotero가 관리하는 docx"]
  %% @key: Q, C
  %% @aux: A1, B1, C1

#원고 준비

원고 노트의 frontmatter에 문서 정보와 스타일을 적습니다.

---
title: 카드 상자는 왜 소통 파트너가 되었나
author:
  - 홍길동
csl: apa
lang: ko-KR
---

• csl: 이 원고의 인용 스타일. Zotero에 설치된 스타일 ID(apa, chicago-note-bibliography 등)나 파일 이름(apa.csl)을 씁니다. 없으면 설정의 Bibliography style(기본 apa)을 씁니다.
• lang: 참고문헌 용어와 날짜의 로캘. ko-KR이면 "편", "역" 같은 한국어 용어를 씁니다. 없으면 설정의 Bibliography locale이나 스타일의 기본값을 씁니다.
• nocite: 본문에서 인용하지 않았지만 참고문헌에 넣을 키.

스타일은 명령 Choose bibliography style from installed styles로 Zotero에 설치된 목록에서 고를 수 있습니다. 고른 스타일은 Better BibTeX가 렌더링할 수 있는지 한 번 확인한 뒤 저장합니다.

#갈래 1: Obsidian 안의 참고문헌

Insert or update references section은 미리보기를 거쳐 노트 끝에 플러그인 소유의 참고문헌 블록을 씁니다. 처음 넣기 전에 노트를 백업합니다.

• 인용을 바꾼 뒤 같은 명령을 다시 실행하면 그 자리에서 갱신합니다.
• 블록을 손으로 고치면 그대로 둡니다. 여는 표식을 <!-- cmds-zotero-references:detached -->로 바꾸면 영구히 내 것이 됩니다.
• 순서는 Bibliography order로 정합니다. 기본은 스타일이 정한 순서이고, 처음 인용한 순서나 가나다순(알파벳순)으로 바꿀 수 있습니다.

Copy bibliography for current note는 같은 목록을 서식 있는 HTML과 일반 텍스트로 함께 클립보드에 넣습니다. Word나 Google Docs에 붙이면 기울임까지 살아 있습니다. 참고문헌 사이드바의 복사 단추도 같습니다.

#갈래 2: pandoc kit

Export pandoc kit for current note는 내보내기 폴더(기본 볼트 안 CMDS Zotero exports)에 노트마다 하위 폴더를 만들고 다음을 씁니다. 원래 노트는 바꾸지 않습니다.

pandoc 명령은 클립보드에 들어갑니다. 터미널에 붙여 넣고 실행하면 같은 폴더에 .docx가 생깁니다.

pandoc --defaults '/경로/CMDS Zotero exports/원고/defaults.yaml'

사본의 frontmatter에는 문서에 필요한 키(title, author, date, abstract, keywords, lang, nocite, 스타일 관련 키)만 남깁니다. pandoc은 그 밖의 frontmatter를 docx의 사용자 지정 문서 속성으로 넣어 파일과 함께 퍼뜨리기 때문입니다. 볼트의 tags, description, 세션 링크 같은 값은 볼트에 머뭅니다.

키트 파일을 손으로 고친 뒤 다시 내보내면 덮어쓰지 않고 <노트> 2 같은 새 폴더를 제안합니다.

#갈래 3: Word kit

Export Word kit with live Zotero citations for current note는 같은 내보내기 폴더에 <노트> (Word) 하위 폴더를 만듭니다. 이 키트로 만든 .docx의 인용은 글자가 아니라 Zotero 필드입니다. Word의 Zotero 탭에서 직접 넣은 인용과 같은 것이어서, 그다음부터는 Word에서 인용을 더하고, 고치고, 스타일을 바꿀 수 있습니다.

sequenceDiagram
  participant P as pandoc
  participant F as cmds-zotero-word.lua
  participant L as zotero.lua
  participant B as Better BibTeX
  participant W as Word
  P->>F: 정리한 원고
  F->>F: 문서 설정, 각주, 참고문헌 자리
  F->>L: citekey 인용
  L->>B: 인용한 항목 묻기
  B-->>L: 항목 정보
  L-->>P: Zotero 필드
  P-->>W: docx
  W->>B: Zotero 탭 Refresh
  B-->>W: 스타일대로 그린 인용과 참고문헌

#한 번만 하는 준비

1. pandoc 설치: macOS는 brew install pandoc 또는 pandoc.org의 설치 파일, Windows는 설치 파일(.msi)이나 winget install --id JohnMacFarlane.Pandoc. 2.17 이상이어야 합니다.
2. zotero.lua 넣기: Better BibTeX가 배포하는 pandoc 필터를 pandoc 필터 폴더에 넣습니다. 없으면 내보낼 때 보고 창이 이 줄을 다시 알려 줍니다.

macOS, Linux:

mkdir -p ~/.local/share/pandoc/filters && curl -fsSL -o ~/.local/share/pandoc/filters/zotero.lua https://retorque.re/zotero-better-bibtex/exporting/zotero.lua

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:APPDATA\pandoc\filters" | Out-Null; Invoke-WebRequest -Uri https://retorque.re/zotero-better-bibtex/exporting/zotero.lua -OutFile "$env:APPDATA\pandoc\filters\zotero.lua"

3. Zotero Word 플러그인: Zotero 쪽 준비를 따릅니다.
4. 스타일: 원고의 csl 스타일이 Zotero에 설치되어 있어야 합니다. Zotero 밖의 .csl 파일을 가리키면 이유를 알리고 거절합니다.

#매번 하는 순서

1. Zotero를 켠 채로 명령 Export Word kit with live Zotero citations for current note를 실행합니다.
2. 보고 창을 읽고 닫습니다. pandoc 명령이 클립보드에 들어 있습니다.
3. 터미널(Windows는 PowerShell)에 붙여 넣고 실행합니다. Zotero가 모르는 citekey가 있으면 pandoc이 그 이름을 알려 주고, 그 인용은 [@key] 글자로 남습니다.
4. 생긴 .docx를 Word로 엽니다.
5. Word의 Zotero 탭에서 Refresh를 누릅니다. 인용과 참고문헌이 원고의 스타일로 채워집니다.
6. 스타일을 바꾸려면 Zotero 탭의 Document Preferences에서 고릅니다. 각주 스타일(예: Chicago notes and bibliography)로 바꾸면 인용이 각주로 옮겨갑니다.

#키트의 필터가 하는 일

Better BibTeX의 zotero.lua만으로도 인용은 Zotero 필드가 됩니다. 하지만 .docx에는 문서 설정과 참고문헌 필드를 쓰지 않아, Word가 처음에 스타일을 묻고 참고문헌은 손으로 넣어야 합니다. 키트의 cmds-zotero-word.lua가 그 빈자리를 채웁니다.

• 문서 설정: 스타일, 로캘, 각주 여부를 Zotero가 읽는 문서 속성(ZOTERO_PREF_1…n)으로 미리 적습니다. 첫 Refresh가 묻지 않고 원고의 스타일을 씁니다.
• 각주 스타일: 원고의 스타일이 각주식이면 본문 인용을 뒤따르는 문장부호 다음의 각주로 옮깁니다. 내가 직접 쓴 각주 속의 인용은 그 자리에 둡니다.
• 참고문헌 자리: 참고문헌 구역이 있던 곳(::: {#refs})에 참고문헌 필드를 둡니다. 구역이 없으면 원고 끝에 References 제목과 함께 둡니다. 참고문헌이 없는 스타일이면 두지 않습니다.

#선택 설정 세 가지

설정 → Bibliography and references에 있습니다. 모두 기본 꺼짐입니다. 볼트 밖에 쓰거나 다른 프로그램을 띄우는 일이라 사용자가 고른 경우에만 합니다.

Pandoc path를 비워 두면 /opt/homebrew/bin, /usr/local/bin 같은 흔한 설치 폴더(Windows는 %LOCALAPPDATA%\Pandoc, C:\Program Files\Pandoc)를 찾고, 그다음 시스템 검색 경로를 봅니다. macOS의 Obsidian은 터미널의 PATH를 보지 못하므로 이 순서가 필요합니다.

#Windows에서

• pandoc 필터 폴더는 %APPDATA%\pandoc\filters입니다. 보고 창이 그곳에 zotero.lua를 넣는 PowerShell 줄을 보여 줍니다.
• 복사되는 명령은 큰따옴표를 씁니다.
• pandoc을 설치한 뒤에는 PowerShell을 새로 열어야 명령을 찾습니다.
• Hookmark는 macOS 전용입니다. 켜 두어도 Windows에서는 연결하지 않고 그렇다고 알립니다.
• Windows는 자동 테스트로 확인했고, 실제 Word 환경 검증은 macOS에서 했습니다.

#한국어 원고에서

• 그림 바로 다음 줄에 쓴 캡션은 그림과 한 문단이 됩니다. 그림과 캡션 사이에 빈 줄을 하나 둡니다.
• pandoc의 기본 Word 서식은 동아시아 글자를 중국어로 표시해 Word가 맞춤법을 중국어로 검사합니다. 한국어가 기본인 참조 문서를 한 번 만들어 두면 해결됩니다. pandoc -o reference.docx --print-default-data-file reference.docx로 꺼낸 뒤 Word에서 기본 스타일의 언어와 글꼴을 한국어로 바꾸고, defaults.yaml에 reference-doc: 줄을 더합니다.
• lang은 참고문헌의 용어(편, 역, et al.)와 날짜 형식을 정합니다. 문헌의 언어가 아니라 투고처 양식이 요구하는 언어에 맞춥니다.

#그 밖의 내보내기

• Copy CSL-JSON for cited sources: 현재 노트가 인용한 문헌의 CSL-JSON을 복사합니다.
• Write pandoc bibliography sidecar for current note: 같은 내용을 .cmds-zotero/bibliography/<노트>.json에 저장하고, frontmatter에 넣을 bibliography: 줄을 알려 줍니다. pandoc을 직접 다루는 사람을 위한 길입니다.
• 키트의 동작은 저장소의 pandoc DOCX 안내에 단계별로 있습니다.