CMDS Zotero0.6.6

더 알기

설계 원칙

기능 목록보다 원칙을 알면 처음 보는 상황에서도 플러그인이 무엇을 할지 짐작할 수 있습니다. 여섯 가지 모두 "연구자의 글과 서재를 잃지 않는다"는 한 가지 목표에서 나왔습니다.

flowchart TB
  Z["Zotero 서재"] -.->|"읽기만"| P["CMDS Zotero"]
  P -->|"표식 안만 갱신"| M["관리 구역"]
  P -.->|"건드리지 않음"| U["내가 쓴 문장"]
  P -.->|"처음 한 번만"| F["frontmatter"]
  P -->|"켰을 때만"| X["볼트 밖, pandoc, Hookmark"]
  %% @key: U
  %% @aux: X
플러그인이 쓸 수 있는 곳은 좁고, 쓰지 않는 곳은 넓습니다.

1. Zotero는 읽기만 합니다

서지의 정본은 하나여야 합니다. 플러그인이 Zotero의 태그나 키를 고치기 시작하면, Zotero와 볼트 중 어느 쪽이 맞는지 아무도 모르게 됩니다. 그래서 CMDS Zotero는 Better BibTeX의 로컬 창구로 읽기만 하고, Zotero 설정, 데이터베이스, citekey, 컬렉션, 태그를 바꾸지 않습니다. 서지를 고치고 싶으면 Zotero에서 고치고, 노트는 그것을 따라옵니다.

2. 이름이 아니라 정체로 찾습니다

citekey는 사람에게 편한 이름일 뿐, 바뀌고 겹칠 수 있습니다. 노트 파일 이름도 사람이 바꿉니다. 플러그인은 그래서 항목을 라이브러리와 item key로, 노트를 그 안의 zoteroID와 소유 표식으로 알아봅니다.

이 원칙이 만드는 행동은 모두 "짐작하지 않기"입니다. 키가 겹치면 묻고, 키가 바뀌면 예전 키로 표시하고, 노트가 옮겨 가면 따라가고, 인덱스가 불완전하면 "없음"이라고 말하지 않습니다. 첫 검색 결과를 정답으로 고르는 일은 하지 않습니다.

3. 사람의 문장이 이깁니다

문헌 노트는 기계가 채우는 부분과 사람이 생각하는 부분이 한 파일에 섞여 있습니다. 둘이 다투면 사람이 이겨야 합니다.

  • 플러그인은 표식 안의 관리 구역만 갱신하고, 그것도 마지막으로 쓴 내용의 지문이 맞을 때만 합니다.
  • 사람이 고친 구역은 보존하고 매번 묻습니다. 영구히 가져가려면 Detach합니다.
  • frontmatter는 처음 한 번만 만들고 그다음부터는 사용자 소유입니다.
  • Zotero에서 지운 주석의 블록도 지우지 않습니다. 그 아래 써 둔 생각이 있을 수 있습니다.
  • 다른 플러그인이 만든 노트는 덮어쓰지 않고, 넘겨받을 때도 내 글은 그대로 둡니다.

4. 쓰기 전에 보여 줍니다

볼트를 바꾸는 명령은 거의 모두 미리보기나 검토 목록을 먼저 보여 줍니다. 적용을 누르기 전에는 아무것도 쓰지 않고, Cancel은 정말로 아무것도 바꾸지 않습니다. 되돌리기 어려운 쓰기(노트 재생성, frontmatter 고치기, 참고문헌 구역 처음 넣기) 앞에는 백업을 남기고, 쓰는 순간 노트가 그사이 바뀌지 않았는지 다시 확인합니다. 에이전트도 같은 규칙을 따라, --apply 없이는 미리보기만 합니다.

5. 위험한 것은 기본 꺼짐입니다

볼트 밖에 파일을 쓰는 일, 다른 프로그램(pandoc, Hookmark)을 실행하는 일, 붙여 넣은 링크를 인용으로 바꾸는 일은 편하지만 사용자가 예상하지 못하면 놀랍습니다. 그래서 모두 선택 설정이고 기본은 꺼짐입니다. 켰을 때도 셸을 거치지 않고, 시간 제한을 두고, 정해진 프로그램만 실행합니다. 실습 키트에 설정 파일을 넣지 않은 이유도 같습니다. 처음 쓰는 사람은 가장 조심스러운 상태에서 시작합니다.

6. 넘기는 시점은 사람이 정합니다

Obsidian 원고와 Word 문서를 양방향으로 맞추는 도구는 결국 어느 한쪽의 수정을 잃습니다. CMDS Zotero는 그 길을 택하지 않았습니다. 원고는 Obsidian에서 생각이 무르익을 때까지 쓰고, 공저자나 투고처에 보내는 순간 Word로 한 번 넘깁니다. 넘긴 뒤에는 Word 문서가 정본이고, 인용은 여전히 같은 Zotero 항목을 가리키므로 Word의 Zotero가 이어서 관리합니다. 한 방향이라 예측할 수 있고, 같은 원고로 몇 번이든 다시 넘길 수 있습니다.

데이터와 개인정보

  • 플러그인은 같은 컴퓨터의 Better BibTeX에만 요청합니다. 텔레메트리, 자체 HTTP 서버, 자동 업데이트는 없습니다.
  • 볼트에 쓰는 것: 설정, 인덱스, 문헌 노트, 그림 주석 사본, 요청한 내보내기 키트, .cmds-zotero/ 아래의 비공개 파일(참고문헌 캐시, 노트 지도, 백업, PDF 텍스트 캐시). 이 폴더에는 .gitignore를 먼저 만들어 git에 올라가지 않게 합니다.
  • 볼트 밖에서 읽는 것: Zotero 캐시의 주석 이미지(가져올 때 복사), Zotero 데이터 폴더의 스타일 파일, 등록한 다른 볼트의 노트 지도. 모두 읽기만 합니다.
  • 볼트 밖에 쓰는 것: 선택 설정을 켰을 때의 내보내기 키트와 pandoc이 만드는 .docx뿐입니다.
  • 인덱스와 노트 지도에는 서지, 개인 경로, 주석이 들어갈 수 있습니다. 공개 저장소에 올리지 않습니다.
  • 진단 명령은 볼트가 git 저장소이면 비공개 파일이 무시되는지 알리려고 git을 읽기 전용으로 실행합니다.

이 원칙들이 나온 곳

CMDS Zotero는 CMDSPACE의 지식 관리 체계에서 실제로 논문을 읽고, 강의를 준비하고, 원고를 쓰며 만든 도구입니다. 한 번 잃어버린 메모는 다시 쓰기 어렵다는 경험이 위의 여섯 가지를 정했습니다. 소스와 변경 기록, 문제 신고는 GitHub 저장소에 있습니다.