가정하지 않는다고 적은 문서의 폴더 이름 2개와 novels.json

TL;DR

• 계약 문서가 아무것도 가정하지 않는다고 적은 같은 파일에서 실제 폴더 이름 두 개를 고정했다. 서른네 줄 떨어져 있었다
• 같은 문서에 답을 기억한다고 적혀 있었다. 기억할 주체가 없어서 매 세션 같은 질문이 다시 나갔다
• 사용자 폴더에 두는 접합점 파일 novels.json 하나로 둘 다 고쳤다. 찾는 단계는 6단계가 됐다
• 문서에 예시로 적은 이름은 규약이 된다. 예시를 적을 때는 그 자리에 이름 대신 관계를 적는다

증상

문서에 예로 적은 이름은 읽는 사람에게 규약으로 보인다.

여러 작품이 다시 쓰는 재료를 어디서 찾을지 규칙을 세웠다. 찾는 순서를 정했고 못 찾으면 묻기로 했다. 여기까지는 맞았다.

문서를 쓰다가 구조를 보여 주는 블록을 하나 그렸다. 작품 폴더가 이 이름이고 재료 폴더가 저 이름이다. 읽기 좋았다. 그래서 계약 문서 맨 앞에 그대로 넣었다.

반전

며칠 뒤 그 문서를 다시 읽었다. 한 줄이 이렇게 말하고 있었다. 이 플러그인은 어느 것도 가정하지 않는다.

그 문서 맨 앞 구조 블록에 폴더 이름 두 개가 박혀 있었다. 서른네 줄 떨어져 있어서 두 문장을 한 화면에서 같이 본 적이 없었다. 같은 파일 안의 모순인데 스크롤 한 번이 그것을 가렸다. 그 블록을 보고 따라 하는 사람의 기기에는 그 이름이 없다. 도구는 없는 곳을 찾고 못 찾은 것을 재료가 없다는 뜻으로 보고한다.

예시로 적었다고 생각했는데 읽는 쪽에는 규격으로 보인다. 이름을 적은 것이 아니라 약속을 적은 것이었다.

같은 문서에서 두 번째 것이 나왔다.

못 찾았으면 작가에게 한 번만 묻는다. 답을 기억한다

기억할 주체가 없다. 스킬 문서는 매 세션 처음부터 다시 읽히고 대화는 세션이 끝나면 사라진다. 그래서 한 번만 묻기로 한 그 질문이 매 세션 다시 나갔다. 쓰는 사람이 같은 답을 반복해서 적고 있었다. 질문이 까다로워서라고 생각했는데, 답을 아무 데도 안 적은 것이 원인이었다.

근거

두 결함의 뿌리가 같다. 이름과 답은 둘 다 사용자 쪽 값인데 도구 쪽 문서에 뒀다.

도구 쪽에 둔 값은 다음 갱신에서 낡는다. 이 플러그인은 판을 자주 올린다. 지금 적어 둔 경로를 다음 판에서 지워도, 그 문서를 보고 자기 설정에 옮겨 적은 사람에게는 옛 값이 남는다. 한 번 어긋나면 뒤로 갈수록 조용히 벌어진다.

기억 쪽도 같은 모양이다. 기억한다고 적으면 읽는 쪽은 어딘가에 남는 줄 안다. 어디에 남는지를 안 적으면 아무 데도 안 남는다. 문서가 주어 없는 동사를 쓰면 그 동사를 할 사람이 없는 것이다.

처리

접합점 파일 하나를 넣었다. 사용자가 만든 공통 폴더에 둔다.

{
  "kind": "novels-root",
  "version": "1.0",
  "material": "소재저장소폴더/소재창고폴더"
}

material 값이 낱말인 것도 같은 이유다. 이 글에 실제 폴더 이름을 적으면 읽는 쪽이 그 이름을 만든다.

이 파일이 두 가지를 한꺼번에 말한다. 여기가 작품 공통 폴더이고 재료 저장소는 이 경로에 있다. 그래서 찾는 규칙이 여섯 단계가 됐다.

1. 지금 폴더에서 위로 올라가며 접합점 파일을 찾는다
2. 있으면 재료 경로를 읽는다
3. 없으면 형제 저장소를 훑는다
4. 그것도 없으면 작가에게 묻는다
5. 답을 접합점 파일에 적는다. 다음부터 1번으로 돌아간다
6. 적어 둔 경로가 없는데 계속 필요하면 만들지 묻는다

보통은 2번에서 끝난다. 3번 아래는 처음 한 번만 지난다.

flowchart TD
  A["현재 폴더에서 위로 올라간다"] --> B{"novels.json 이 있나"}
  B -->|있다| C["material 경로를 읽는다. 끝"]
  B -->|없다| D["형제 저장소를 훑는다"]
  D -->|못 찾음| E["작가에게 묻는다"]
  E --> F["답을 novels.json 에 적는다"]
  F -.다음 세션.-> A

그림의 점선이 이 판에서 더한 것이다. 전에는 그 선이 없어서 매번 A 에서 다시 시작했다.

이름을 novels-root 로 적어 둔 것은 그 파일이 무엇인지 파일 자신이 말하게 하려는 것이다. 사용자가 폴더 이름을 바꿔도 이 값은 안 바뀐다. 버전 칸을 둔 이유도 같다. 나중에 칸이 늘면 읽는 쪽이 옛 파일과 새 파일을 갈라야 한다.

중심은 5번이다. 기억이 아니라 기록이다. 대화를 잃어도 파일은 남는다.

이 파일을 플러그인이 만들지 않는다. 작가가 원할 때 만든다. 안 만들면 없는 채로 다음 단계로 간다. 플러그인이 못 쓰는 파일이라서 갱신이 그 값을 건드리지 못한다. 그래서 값이 오래 산다.

폴더 이름 기본값도 두지 않았다. 기본값은 그 이름이 없는 기기에서 빈 곳을 가리킨다. 비어 있다는 것을 정상으로 읽고 조용히 지나가는 쪽이, 모른다고 말하고 멈추는 쪽보다 나쁘다.

검증

계약 문서에서 이름을 지우고 관계만 남겼다. 작품 저장소는 여러 개이고 재료 저장소는 보통 하나이며 둘은 다른 저장소다. 같은 폴더에 나란히 있어도 별개다.

고친 분량은 계약 문서 쪽이 53줄, 스킬 문서 쪽이 21줄이다. 새로 만든 코드는 없다. 이 판에서 바뀐 것은 전부 문서이고 바뀐 것은 무엇을 적지 않기로 했는가다.

이 점검은 사람이 했다. 검사가 잡아 줄 수 있는 모양이 아니다. 문서에 적힌 폴더 이름이 예시인지 규격인지는 글자만 봐서 안 갈린다. 같은 문단에 가정하지 않는다는 문장이 있다는 사실도 기계는 모순으로 읽지 못한다.

지우고 나니 다음 질문이 바로 왔다. 작품은 그러면 어디서 찾나.

작품 저장소에는 이미 설정 파일이 있다. 다만 그것은 작품 하나에 대한 설정이지 그 위를 가리키지 않는다. 거기에 상위 경로를 하나 더 붙이면 층이 둘이 되고 두 곳이 같은 것을 말하다가 갈라진다. 그래서 접합점을 작품이 아니라 그 위에 뒀다. 위에서 한 번 훑는 것이 작품마다 훑는 것보다 싸다. 작품이 열 개여도 한 번이다.

개선

단계 수는 하나 늘었다. 대신 2번에서 끝나는 경우가 대부분이고 늘어난 5번이 다음번 1번을 성립시킨다.

남은 것

• 접합점 파일이 있는 집과 없는 집이 갈린다. 없는 쪽이 정상이고 두 번 묻지 않는다. 다만 없는 쪽에서 몇 단계를 더 지나는지는 안 쟀다
• 이 파일의 형식을 규격으로 못 박지 않았다. 못 박으면 그 규격이 두 번째 정본이 된다. 대신 읽는 쪽이 매번 구조를 추측하는 비용이 남는다
• README.md 의 구조 표에 같은 이름 셋이 그대로 있다. 계약 문서만 고쳤다. 설치하려는 사람이 먼저 여는 쪽은 README 라서 순서가 거꾸로다. 거기는 구조를 보여 주는 자리이기도 해서, 이름을 빼고도 구조가 읽히게 쓰는 법을 아직 못 찾았다
• 사용자가 이 파일을 직접 고쳐 깨뜨렸을 때 어떻게 알릴지는 안 정했다
• 접합점이 가리키는 경로가 나중에 사라지는 경우를 안 다룬다. 폴더를 옮기면 파일은 남고 경로만 틀린다. 그때 다시 묻는 것과 조용히 형제 저장소를 훑는 것 중 어느 쪽이 맞는지 아직 안 정했다

다음부터

문서에 구조를 보여 주려고 실제 이름을 적을 때는 그 자리에 이름 대신 관계를 적고 이름은 사용자가 가진 파일이 들게 한다. 예시로 적은 이름도 읽는 쪽에는 규격으로 보이고 도구 쪽 문서에 둔 사용자 값은 다음 갱신에서 조용히 낡는다.