Typst 템플릿용 양식

Typst 템플릿에는 표지, 정보 상자, 서명란 같은 자체 함수가 들어 있는 경우가 많습니다. 보고서를 쓰는 사람은 #info-box(title: "Supply risk", tone: "risk")[...]처럼 그 함수를 호출합니다. 템플릿을 관리한다면 각 함수의 인수를 한 번만 설명해 두면 됩니다. 그러면 비주얼 모드가 그 함수의 모든 호출을 양식으로 보여 줍니다. 레이블이 붙은 필드, 고정된 선택지를 위한 목록, 예/아니요를 위한 스위치입니다. 필드를 수정하면 .typ 파일에서 그 인수 하나만 다시 쓰이므로, 보고서는 똑같이 컴파일되는 평범한 Typst 소스로 남습니다.

읽는 사람에게 보이는 모습

자기 줄에 따로 쓴 호출은 카드가 됩니다. 카드 머리글에는 양식의 이름이 나오고, 요약을 지정했다면 상자의 제목 같은 짧은 요약도 나옵니다. 인수마다 레이블과 컨트롤이 있는 행이 하나씩 생깁니다.

#badge("review")처럼 문장 안에 있는 호출은 글줄 안의 칩이 됩니다. 칩을 클릭하면 같은 필드가 작은 팝오버에 열립니다.

텍스트 필드와 마크업 필드는 Enter(여러 줄 필드에서는 ⌘ Enter 또는 Ctrl Enter)를 누르거나 필드를 벗어나면 저장됩니다. Esc는 이전 값으로 되돌립니다. 목록과 스위치는 바로 저장됩니다. 변경 하나가 실행 취소 한 단계입니다.

커서를 호출 안으로 옮기면 다른 비주얼 모드 요소처럼 소스가 나타납니다. 카드의 소스에서 편집도 같은 일을 합니다.

양식을 선언하는 곳

양식을 선언하는 곳은 두 군데이며 형식은 같습니다.

• 패키지 안. 패키지의 typst.toml에 [tool.oleafly] 섹션을 추가합니다. Typst는 [tool.*] 섹션을 다른 도구용으로 남겨 두므로 패키지는 어디서나 그대로 설치되고 컴파일됩니다. @local 패키지와 Typst Universe의 @preview 패키지에서 쓸 수 있습니다.
• 프로젝트 안. 프로젝트 안에 일반 .typ 파일로 둔 템플릿은 프로젝트 맨 위에 oleafly-forms.toml을 만드세요. 이때 각 양식은 함수를 정의한 파일도 module로 지정합니다.

패키지 양식:

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
function = "info-box"
label = "Info box"
summary = "title"

  [[tool.oleafly.forms.fields]]
  arg = "title"
  kind = "text"
  label = "Heading"
  placeholder = "Short heading"
  required = true

  [[tool.oleafly.forms.fields]]
  arg = "tone"
  kind = "choice"
  label = "Tone"
  default = "note"
  options = [{ value = "note", label = "Note" }, { value = "risk", label = "Risk" }, "neutral"]

  [[tool.oleafly.forms.fields]]
  arg = 0
  kind = "content"
  label = "Text"

oleafly-forms.toml에 들어가는 프로젝트 양식:

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
module = "template/memo.typ"
function = "memo-header"
label = "Memo header"
fields = [
  { arg = "to", kind = "text", label = "To" },
  { arg = "subject", kind = "text", label = "Subject" },
]

키

schema = 1은 필수입니다. 이것이 없거나 다른 숫자인 파일은 무시됩니다.

각 [[tool.oleafly.forms]] 항목에는 다음이 있습니다.

키	필수	의미
function	예	함수의 이름으로, Typst 식별자 하나여야 합니다. 하이픈도 쓸 수 있습니다.
module	oleafly-forms.toml에서만	함수를 정의한 프로젝트 파일. 프로젝트 맨 위 폴더 기준이며 폴더 사이는 /로 구분합니다.
label	아니요	카드와 칩에 표시되는 양식 이름. 기본값은 함수 이름입니다.
summary	아니요	레이블 옆에 값이 표시되는 인수. 필드의 arg처럼 씁니다.
fields	예	필드 하나 이상.

각 필드에는 다음이 있습니다.

키	필수	의미
arg	예	이름 있는 인수는 이름("title"), 위치 인수는 숫자(0이 첫 번째)입니다. 뒤에 붙는 [...] 블록은 괄호 안의 인수들 다음의 위치 인수로 칩니다.
kind	예	text, content, choice, number, toggle 중 하나.
label	예	필드의 레이블.
help	아니요	필드 아래에 표시되는 짧은 안내.
placeholder	아니요	빈 필드에 표시되는 회색 텍스트.
required	아니요	true이면 빈 필드를 누락으로 표시하고 지우기 버튼을 숨깁니다. Oleafly는 인수를 스스로 추가하지 않습니다.
default	아니요	인수를 생략했을 때 함수가 사용하는 값. 표시만 되고 소스에 쓰이지는 않습니다.

종류와 추가 키:

• text는 Typst 문자열을 씁니다. 더 큰 상자를 쓰려면 multiline = true를 추가하세요.
• content는 Typst 마크업을 편집하고 [...] 블록으로 씁니다. 문자열 인수는 문자열로 남습니다.
• choice에는 options가 필요합니다. 문자열 목록이거나, 레이블이 값과 다를 때는 { value, label } 테이블입니다. 값은 문자열로 쓰입니다.
• number는 integer, min, max, step을 받습니다. 숫자에는 단위가 없습니다.
• toggle은 true 또는 false를 씁니다.

양식이 적용되는 호출

Oleafly는 보고서 파일 최상위에 있는 #import와 #let 줄을 따라갑니다.

• #import "@local/acme-report:0.1.0" as acme는 #acme.info-box(...)를 양식으로 만듭니다.
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge는 #info-box(...)와 #badge(...)를 양식으로 만듭니다.
• #import "@local/acme-report:0.1.0": *는 패키지가 선언한 모든 함수를 양식으로 만듭니다.
• #import "template/memo.typ": memo-header는 module이 template/memo.typ인 프로젝트 양식과 일치합니다. 경로는 보고서가 있는 폴더 기준으로 읽고, /로 시작하면 프로젝트 맨 위 폴더 기준으로 읽습니다.

패키지 버전은 정확히 일치해야 합니다. 파일 뒤쪽에 같은 이름의 #let이 있으면 그 지점부터는 그것이 양식을 대체합니다. 패키지를 다시 import하는 다른 파일을 거쳐 닿는 호출은 소스 텍스트 그대로 남습니다.

table이나 figure처럼 비주얼 모드가 이미 그리는 Typst 요소와 이름이 같은 함수는 이름만으로 호출하면 내장 모양을 그대로 유지합니다. #acme.table(...)이나 이름을 바꾼 import에는 여전히 양식이 적용됩니다.

읽기 전용으로 표시되는 필드

일부 인수는 양식에서 안전하게 편집할 수 없습니다. 그 행에는 이유와 함께 소스가 표시되고, 소스에서 편집을 누르면 소스로 이동합니다.

• 소스에서 계산됨: 값이 title: data.title 같은 식입니다.
• 다른 종류의 값으로 작성됨: 예를 들어 양식은 텍스트를 기대하는데 숫자가 들어 있는 경우입니다.
• 선택지에 없는 값: options에 없는 값입니다.
• 전개 인수로 설정됨: ..args가 있는 호출은 양식에서 볼 수 없는 값을 넘기므로 모든 필드가 읽기 전용입니다.

필드를 들어갈 자리에 추가할 수 없을 때, 예를 들어 빠진 인수 뒤의 위치 인수라면 양식이 그렇게 알려 주고 소스에서 추가를 제안합니다.

정의의 실수

Oleafly에서 oleafly-forms.toml이나 프로젝트에 포함한 패키지의 typst.toml을 열면 문제마다 해당 줄에 표시가 나타납니다. 알 수 없는 종류, 빠진 레이블, 중복된 양식, 프로젝트 밖을 가리키는 module 등입니다. 잘못된 양식은 제외되고 나머지는 계속 작동합니다. 256 KB보다 큰 파일은 읽지 않습니다.

템플릿 공유

Oleafly는 컴파일러가 쓰는 것과 같은 폴더에서 패키지 양식을 읽습니다. @local 패키지가 없는 공동 저자에게는 평범한 소스만 보이고 오류는 나지 않습니다. 프로젝트의 모든 사람과 양식을 공유하려면 Typst 패키지 대화 상자를 열고 프로젝트 폴더의 패키지 사용을 켠 다음 패키지를 프로젝트에 포함을 선택하세요. 그러면 패키지와 그 양식이 프로젝트의 typst-packages 폴더에 담겨 함께 이동합니다(Typst 프로젝트 참고).