학술지 포맷

개요

이 문서는 자체 학술지 커스텀 포맷을 만드는 가이드를 제공합니다. 보조 자료로 다음 학습 자료도 권장합니다.

  • quarto-journals GitHub 조직에 공개된 학술지 논문 포맷의 소스 코드

  • 새 학술지 포맷을 만들기 위한 GitHub 템플릿 리포지토리. 템플릿 리포지토리의 코드는 주석이 풍부하므로, 이 템플릿으로 새 리포지토리를 만들고 실험해 보는 것이 훌륭한 학습 방법입니다.

학술지 커스텀 포맷은 일반 Quarto 포맷(pdf, html 등)처럼 사용할 수 있습니다.

내장 포맷과 동일하게 format 키 아래에 커스텀 포맷을 지정할 수 있습니다. 예를 들면 다음과 같습니다.

----
title: "My Document"
format:
   acm-pdf: 
     toc: true
---

모든 커스텀 포맷은 기본 포맷 중 하나에서 파생되며, 기본 포맷 이름이 접미사로 붙습니다. 또한 서로 다른 기본 포맷에서 파생된 여러 변형을 제공할 수도 있습니다. 예를 들면 다음과 같습니다.

----
title: "My Document"
toc: true
format:
   acm-pdf: default
   acm-html: default
---

toc 옵션은 두 포맷에서 공유되므로 최상위로 옮겼습니다.

커스텀 포맷은 quarto render의 --to 인자와 함께 사용할 수도 있습니다. 예를 들면 다음과 같습니다.

Terminal
quarto render document.qmd --to acm-pdf

빠른 시작

여기서는 간단한 학술지 논문 포맷 확장을 만드는 방법을 설명합니다. 이를 위해 quarto create 명령을 사용합니다. VS Code, Positron, RStudio를 사용 중이라면 각 통합 터미널 창에서 quarto create를 실행하세요.

시작하려면 포맷을 만들 상위 디렉터리에서 quarto create extension journal을 실행합니다.

Terminal
$ quarto create extension journal
 ? Extension Name › aps

위와 같이 확장 이름을 입력하라는 프롬프트가 표시됩니다. 가상의 학술 협회를 의미하는 aps를 입력하고 Enter를 누르면 학술지 포맷 확장이 생성됩니다.

Creating extension at /Users/jjallaire/quarto/dev/aps:
  - Created README.md
  - Created template.qmd
  - Created _extensions/aps/aps.lua
  - Created _extensions/aps/styles.css
  - Created _extensions/aps/_extension.yml
  - Created _extensions/aps/header.tex
  - Created bibliography.bib

VS Code, Positron, RStudio에서 실행 중이라면 확장 프로젝트가 새 창으로 열립니다.

_extensions/aps/ 안의 파일 내용은 다음과 같습니다.

_extensions/aps/_extension.yml
title: Aps
author: J.J. Allaire
version: 1.0.0
quarto-required: ">=1.2.222"
contributes:
  formats:
    common:
      toc: true
      filters:
        - aps.lua
    pdf:
      include-in-header: header.tex
    html:
      css: styles.css

주요 _extension.yml 설정 파일은 이 학술지에서 사용할 출력 포맷을 정의합니다. 여기서는 pdf와 html 포맷을 정의했으며, Quarto 문서에서는 각각 aps-pdf, aps-html로 사용할 수 있습니다.

이 설정 파일은 학술지 논문 모양을 커스터마이즈하는 데 사용되는 여러 파일도 가리킵니다.

  • header.tex — 커스텀 LaTeX 헤더 지시문

  • styles.css — HTML 출력을 위한 커스텀 CSS

  • aps.lua — 다양한 커스텀 변환을 위한 Lua 필터

마지막으로 template.qmd는 이 포맷을 사용하는 사용자를 위한 기본 예제 논문을 제공합니다.

template.qmd
---
title: Aps Template
format:
  aps-pdf:
    keep-tex: true  
  aps-html: default
author:
  - name: Sarah Malloc
    affiliations:
      - name: An Organization
        department: The Department
        address: 1 Main St
        city: Boston
        country: USA
        postal-code: 02210-1022
      - A second affiliation
    orcid: 0000-0000-0000-0000
    email: sm@example.org
    url: https://example.org/
  - name: Eliza Dealloc
    affiliations:
      - Another Affiliation
abstract: |
  This document is a template demonstrating the Aps format.
keywords: [template, demo]
bibliography: bibliography.bib  
---

## Introduction {#sec-intro}

*TODO* Create a template that demonstrates the appearance, formatting, layout, and functionality of your format. Learn more about journal formats at <https://quarto.org/docs/journals/>.

포맷을 개발하려면 template.qmd를 렌더링/미리보기한 뒤 _extensions 디렉터리의 파일을 수정하세요(이 파일들이 변경되면 미리보기가 자동으로 갱신됩니다).

예시: ACM 포맷

위의 빠른 시작은 매우 단순한 학술지 논문 포맷을 만듭니다. 여기서는 quarto-journals에서 제공하는 ACM 포맷이라는 더 복잡한 예제를 살펴봅니다.

예제를 진행하기 전에, 예제에서 활용되는 기초를 다루는 다음 문서를 먼저 살펴보는 것을 권장합니다.

포맷 구성 요소

ACM 확장의 소스 코드 리포지토리는 다음과 같습니다.

.gitignore
.quartoignore
LICENSE
README.md
bibliography.bib
template.qmd
_extensions/
  acm/
    _extension.yml
    acm_proc_article-sp.cls
    sensys-abstract.cls
    include-in-header.tex
    acm-sig-proceedings.csl
    partials/
      doc-class.tex
      title.tex
      before-bib.tex

당분간 _extensions 디렉터리 위쪽의 파일은 건너뛰겠습니다(이 파일들은 확장의 일부라기보다 문서와 시작 템플릿을 제공하며, 사용 방법은 아래에서 설명합니다).

  • _extensions 디렉터리에는 하나 이상의 확장이 들어 있으며, 이 경우 acm 포맷 확장이 포함되어 있습니다.

  • _extension.yml 파일은 포맷 확장을 선언하고, 해당 포맷으로 만든 논문의 기본 메타데이터와 옵션을 제공합니다(아래에서 자세히 살펴봅니다).

  • acm_proc_article-sp.cls와 sensys-abstract.cls 파일은 ACM에서 사용하는 LaTeX 클래스 파일입니다.

  • include-in-header.tex 파일에는 ACM 논문 프리앰블에 포함되는 표준 내용이 들어 있습니다.

  • acm-sig-proceedings.csl은 ACM 표준에 맞춰 인용과 참고문헌을 렌더링할 수 있게 하는 Citation Style Language(CSL) 파일입니다.

  • partials 디렉터리에는 표준 Pandoc LaTeX 템플릿의 일부를 덮어쓰는 .tex 파일이 들어 있습니다(partials에 대한 자세한 내용은 논문 템플릿을 참고하세요).

_extension.yml 내용은 다음과 같습니다.

title: ACM Journal Format
author: Charles Teague
version: 0.1.0
quarto-required: ">=1.2.0"
contributes:
  format:
    common:
      csl: acm-sig-proceedings.csl
      number-sections: true
    pdf:
      shift-heading-level-by: -1
      template-partials:
        - partials/before-bib.tex
        - partials/doc-class.tex
        - partials/title.tex
      include-in-header:
        - include-in-header.tex

보시다시피 _extensions/acm 폴더의 많은 파일이 여기서 참조됩니다. 또한 pdf 포맷에 대한 옵션이 여러 개 선언되어 있지만, common에 선언된 옵션도 있습니다. 이 옵션들은 pdf에 적용될 뿐 아니라 추후 다른 포맷 변형(예: HTML)이 개발될 때도 적용됩니다.

포맷 템플릿

이제 _extensions 디렉터리 밖의 파일로 돌아가 보겠습니다. LICENSE와 README.md 파일은 모든 확장에 포함하는 것이 좋은 문서를 제공합니다. .gitignore 파일은 선택된 파일을 버전 관리에서 제외합니다. 나머지 파일은 사용자가 포맷을 쉽게 시작할 수 있도록 하는 템플릿을 제공합니다.

template.qmd가 포함된 커스텀 포맷은 다음과 같은 명령으로 시작할 수 있습니다.

Terminal
quarto use template quarto-journals/acm

ACM 템플릿에 포함된 파일은 다음과 같습니다.

  • template.qmd는 포맷 사용을 위한 시작 템플릿입니다. 템플릿의 YAML 문서 옵션은 다음과 같습니다.

    ---
title: Short Paper
author:
  - name: Alice Anonymous
    email: alice@example.com
    affiliation: Some Institute of Technology
  - name: Bob Security
    email: bob@example.com
    affiliation: Another University
abstract: |
  This is the abstract.
  It consists of two paragraphs.
format:
  acm-pdf: 
    keep-tex: true  
bibliography: bibliography.bib
---

  • bibliography.bib는 template.qmd에서 참조하는 샘플 참고문헌입니다.

여기서 사용한 저자 정보 스키마는 비교적 단순합니다. 더 정교한 저자 정보 스키마는 저자 및 소속 문서를 참고하세요.

template.qmd와 함께 다른 파일을 포함하면 그 파일들도 복사됩니다. 기본적으로 Quarto는 확장 템플릿을 복사할 때 일반적인 GitHub 리포지토리 파일을 제외합니다. 여기에는 .로 시작하는 파일/디렉터리(예: .gitignore), README.md, LICENSE 등이 포함됩니다. 원한다면 리포지토리 루트에 .quartoignore 파일을 두고, 각 줄에 무시할 파일 패턴을 glob으로 작성할 수 있습니다(.gitignore 문법과 동일).

형식 배포

형식 확장은 두 가지 방식으로 배포할 수 있습니다.

  1. _extensions 디렉터리에 형식과 template.qmd(둘러싼 디렉터리 이름과 일치하도록 자동 변경됨)를 함께 포함하는 템플릿

  2. 템플릿 스캐폴딩이 없는 순수 형식(기존 문서나 프로젝트에 형식을 추가할 때 유용)

위에서 acm 예시에 해당하는 파일이 있는 GitHub 저장소가 있다면, 사용자는 아래와 같이 확장과 템플릿을 설치할 수 있습니다(quarto-journals는 저장소를 호스팅하는 GitHub 조직).

Terminal
quarto use template quarto-journals/acm

이 방식은 바로 동작하는 문서를 제공하므로 형식을 시작하는 데 선호됩니다. 기존 프로젝트를 사용하는 경우 형식만 설치할 수도 있습니다.

Terminal
quarto add quarto-journals/acm

확장은 GitHub 저장소 대신 단순 gzip 아카이브로도 묶어 배포할 수 있습니다. 자세한 내용은 확장 배포 문서를 참고하세요.

여러 형식

하나의 형식 확장이 여러 출력 형식을 지원할 수 있습니다. 예를 들어 확장이 html과 pdf 출력을 대상으로 할 수 있습니다. 여러 형식을 지원하려면 contributes / format 키에 기본 형식을 추가합니다.

contributes:
  format:
    html:
      # html-specific options
    pdf:
      # pdf-specific options

공통 메타데이터

형식 확장이 대상일 때 모든 출력 형식에 공통으로 적용될 메타데이터가 있다면 common 키 아래에 둘 수 있습니다. 예:

contributes:
  format:
    common:
      filters:
        - filter.lua
      shortcodes:
        - quarto-ext/fancy-text
    html:
      # html-specifc
    pdf:
      # pdf-specifc

형식 리소스

일반적으로 형식 확장 디렉터리 안에 다른 파일과 리소스를 두고, _extension.yml 메타데이터 파일에서 상대 경로로 참조하면 됩니다. 이러한 상대 경로는 확장의 메타데이터가 렌더링된 문서 메타데이터와 병합될 때 올바르게 처리됩니다.

문서 렌더링 과정에서 입력 디렉터리에 복사되어야 하는 리소스가 있다면(예: LaTeX 참고문헌의 bst 파일 또는 LaTeX 템플릿에서 참조되는 로고 파일 등), 파일 경로 목록인 format-resources를 제공할 수 있습니다1. 이 파일들은 문서가 렌더링될 때 렌더링 중인 입력이 있는 디렉터리로 복사됩니다. 예:

contributes:
  format:
    pdf:
      format-resources:
        - plos2015.bst

확장 임베딩

형식 확장에서 다른 확장을 사용하고 싶은 경우가 있습니다. 이는 가능하지만, 사용자 정의 형식 안에서 확장을 사용하려면 올바르게 임베딩되도록 특수 명령줄 플래그로 추가해야 합니다.

Terminal
quarto create extension format:pdf myformat
cd myformat
quarto add quarto-ext/fancy-text --embed myformat

예를 들어, fancy-text 확장(\(\LaTeX\)와 BibTEX 단어에 대한 특수 서식을 제공)를 jss 사용자 정의 형식 사용자에게 제공하려면 다음과 같이 합니다.

Terminal
quarto add quarto-ext/fancy-text --embed jss

그러면 다음과 같은 결과가 생성됩니다.

Output
quarto-journals/jss
└── _extensions
    └── jss
        ├── _extensions
        │   └── quarto-ext
        │       └── fancy-text
        └── partials

이렇게 하면 _extensions 폴더 안의 jss 확장에 quarto-ext/fancy-text 확장이 추가됩니다. 확장을 임베딩하면 사용자가 이미 설치한 다른 버전의 확장과 충돌할 가능성 없이 사용할 수 있습니다.

더 알아보기

추가로 도움이 될 만한 자료는 다음과 같습니다.

  • quarto-journals GitHub 조직에 공개된 학술지 논문 포맷 소스 코드

  • 새 학술지 포맷을 만들기 위한 GitHub 템플릿 리포지토리. 템플릿 리포지토리의 코드는 주석이 풍부하므로, 이 템플릿으로 새 리포지토리를 만들고 실험해 보는 것이 훌륭한 학습 방법입니다.

  • 학술지용 논문 템플릿 제작에 대한 심층 설명(템플릿을 구성하는 partials 사용법 포함)

  • 저자 및 소속 표현 및 렌더링을 위한 스키마와 옵션 정리

Footnotes

  1. 이는 Pandoc이 생성한 LaTeX를 PDF로 변환하는 추가 단계가 있는 PDF 기반 형식에서 가장 흔합니다. LaTeX가 간접적으로 참조하는 파일이 있다면 발견 가능해야 하며, 보통 LaTeX 입력이 있는 디렉터리로 복사해야 합니다.↩︎