기술 문서 작성

시각 모드는 수식, 인용, 상호 참조, 각주, 임베디드 코드, LaTeX 등 기술 문서 작성에 자주 사용되는 Quarto 기능을 폭넓게 지원합니다. 이 문서는 이러한 기능을 더 자세히 설명합니다.

수식

LaTeX 수식은 표준 Pandoc 마크다운 문법으로 작성합니다(편집기는 문법을 자동으로 인식하고 수식으로 처리합니다). 수식을 직접 편집하지 않을 때는 렌더링된 수식으로 표시됩니다:

R Studio 시각적 편집기에서 열린 RMarkdown 문서. 첫 번째 섹션 제목은 'Inline Math'이며, 인라인 수학 텍스트가 포함된 두 줄의 텍스트가 표시됩니다. 두 번째 섹션 제목은 'Display Math'이며, 두 개의 $ 문자가 있는 줄, 아래의 LaTeX 수식, 그리고 다시 두 개의 $ 문자가 있는 줄이 있습니다. 그 아래에 수식의 렌더링 결과가 표시됩니다.

위와 같이 키보드나 마우스로 수식을 선택하면 수식의 LaTeX를 편집할 수 있습니다. 입력하는 동안 아래에 미리보기가 표시됩니다.

상호 참조

상호 참조는 그림, 표, 수식 등 다양한 대상에 대한 번호와 하이퍼링크를 제공하여 문서 탐색을 더 쉽게 만들어 줍니다.

상호 참조 가능한 엔터티에는 레이블(고유 식별자)과 캡션(설명)이 필요합니다. 예를 들어 다음과 같은 상호 참조 가능한 그림이 있습니다:

![Elephant](elephant.png){#fig-elephant}

캡션(“Elephant”)과 레이블(#fig-elephant)이 있어 이 그림을 참조할 수 있습니다. 이를 통해 문서의 다른 위치에서 다음과 같이 참조할 수 있습니다:

See @fig-elephant for an illustration.

HTML로 렌더링하면 다음과 같이 보입니다:

코끼리의 선 그림. 아래 중앙에 'Figure 1: Elephant'가 표시됩니다. 그 아래 왼쪽에는 'See fig. 1 for an illustration' 문장이 있습니다.

상호 참조 생성과 표시를 사용자 정의하는 방법은 상호 참조 문서를 참고하세요.

Insert -> Cross Reference… 명령으로 상호 참조를 삽입할 수 있습니다:

R Studio의 'Insert Cross Reference' 창. 왼쪽에 'All Types', 'Sections', 'Figures', 'Tables', 'Equations', 'Listings', 'Theorems' 옵션이 세로로 배치되어 있습니다. 오른쪽 상단의 검색 바에는 'fig-env'가 입력되어 있습니다. 그 아래에는 검색 결과 목록이 있으며, 각 항목은 '@fig-env*' 형태의 제목, 왼쪽 아이콘, 오른쪽의 파일명, 아래의 주변 텍스트를 포함합니다.

상호 참조 레이블의 접두사를 입력(예: @fig-env)하면 자동 완성으로 선택할 수도 있습니다:

R Studio 시각적 편집기에서 열린 문서. '@fig-env' 텍스트가 파란색으로 강조되어 있고, 아래에 검색 결과가 표시된 팝업이 있습니다. 각 결과는 '@fig-env*' 형태의 제목, 왼쪽 아이콘, 오른쪽의 파일명, 아래의 주변 텍스트를 포함합니다.

하이퍼링크와 마찬가지로, 선택된 상호 참조에 나타나는 팝업 링크를 클릭해 해당 위치로 이동할 수 있습니다:

R Studio 시각적 편집기에서 열린 문서. '@fig-break-point' 텍스트가 파란색으로 강조되어 있고, 아래에 연결 대상이 표시된 팝업이 있습니다. 팝업에는 파란색 밑줄의 'fig-break-point', 그 아래의 문장, 그리고 파일명 'a5-debug.qmd'가 연한 회색으로 표시됩니다.

IDE의 전역 검색을 사용해 상호 참조로 직접 이동할 수도 있습니다:

RStudio IDE 상단 부분. 중앙 상단의 검색 바에 'fig-en'이 입력되어 있고 아래에 검색 결과가 표시됩니다. 각 결과는 'fig-en*' 형태의 제목과 왼쪽 아이콘, 오른쪽의 파일 위치를 포함합니다.

각주

Insert -> Footnote 명령(또는 ⇧⌘ F7 단축키)으로 각주를 삽입할 수 있습니다. 각주 편집은 본문 바로 아래의 패널에서 이루어집니다:

R Studio 시각적 편집기에서 열린 마크다운 문서. 세 단락이 있고, 마지막 문장 끝에 위첨자 '1'이 표시됩니다. 이 '1'은 파란색 상자로 둘러싸여 있습니다. 세 단락 아래에 구분선이 있고, 그 아래에 '1'로 표시된 단락이 있습니다.

기본적으로 각주는 등장한 블록 바로 아래에 마크다운으로 작성됩니다. 이 동작은 편집기 옵션에서 사용자 정의할 수 있습니다.

임베디드 코드

Quarto 문서에 포함하는 소스 코드는 표시용일 수도 있고, 렌더링 과정에서 Jupyter나 Knitr가 실행할 수도 있습니다. 코드는 인라인 또는 블록 형태일 수 있습니다.

코드 표시

코드를 실행하지 않고 표시만 하려면 Insert -> Code Block 메뉴 항목을 사용하거나 새 줄에서 다음 중 하나를 입력합니다:

  1. ``` (일반 코드 블록)
  2. ```<lang> (<lang>가 언어인 경우, 구문 강조 표시된 코드 블록)

그런 다음 Enter를 누릅니다. 인라인 코드를 표시하려면 텍스트를 백틱으로 감싸거나(`code`), Format -> Code 메뉴 항목을 사용합니다.

코드 청크

실행 가능한 코드 청크를 삽입하려면 Insert -> Code Chunk 메뉴를 사용하거나 새 줄에서 다음을 입력합니다:

```{r}

그런 다음 Enter를 누릅니다. r은 knitr가 지원하는 다른 언어(예: python 또는 sql)로 바꿀 수 있으며, 청크 레이블과 기타 옵션도 포함할 수 있습니다.

인라인 R 코드를 포함하려면 일반 인라인 코드(예: 백틱 또는 ⌘ D 단축키 사용)를 만들고 앞에 {r}(또는 r)를 붙입니다. 예를 들어 R 함수 Sys.Date()로 현재 날짜를 포함하려면 `{r} Sys.Date()`를 사용합니다.

시각 모드에서 코드를 표시할 때는 백틱이 보이지 않지만(소스 모드에서는 보임) 정상 동작합니다.

청크 실행

코드 청크 오른쪽 상단의 실행 버튼 또는 ⇧⌘ Enter 단축키로 현재 선택한 R 또는 Python 코드 청크를 실행할 수 있습니다:

R Studio 시각적 편집기에서 열린 R Markdown 문서. 일반 텍스트와 회색 배경의 코드 청크가 있고, 그 아래에 실행 결과 플롯이 있습니다. 코드 청크 오른쪽 상단에는 실행용 초록색 화살표가 있습니다.

도구 모음 버튼 또는 ⌥⌘ P 단축키로 현재 청크까지의 코드 청크를 실행할 수 있습니다.

LaTeX 및 HTML

시각 모드에서 원시 LaTeX 명령이나 HTML 태그도 포함할 수 있습니다. 원시 마크업은 자동으로 인식되어 구문 강조 표시됩니다. 예:

R Studio 시각적 편집기에서 열린 R Markdown 문서. 첫 줄은 'The implementation of the \pkg{shiny} package uses lots of 'proglang{JavaScript}.'로 시작합니다. '\pkg'와 '\proglang'이 분홍색으로 강조되어 LaTeX 명령임을 나타냅니다. 두 번째 줄에는 분홍색으로 강조된 <kbd> HTML 태그가 있습니다. 시각적 편집기가 HTML 태그로 인식해 문서에 렌더링합니다.

위 예시는 인라인 LaTeX와 HTML을 사용합니다. Format -> Raw 메뉴의 명령을 사용해 원시 블록을 포함할 수도 있습니다. 예를 들어 원시 LaTeX 블록을 포함한 문서는 다음과 같습니다:

R Studio 시각적 편집기에서 열린 R Markdown 문서. 분홍색 테두리 박스 안에 표를 설명하는 원시 LaTeX가 있습니다. 박스는 페이지 너비를 차지하며, 오른쪽 상단에 'latex' 레이블과 점 세 개 버튼이 있습니다.

Pandoc은 LaTeX 기반 출력이 아닐 때 LaTeX 명령을 무시하고, HTML 기반 출력이 아닐 때 HTML 태그를 무시합니다.

인용

시각 모드는 인용에 대해 표준 Pandoc 마크다운 표현(예: [@citation])을 사용합니다. 인용은 다양한 출처에서 삽입할 수 있습니다:

  1. 문서의 참고문헌.
  2. Zotero 개인 또는 그룹 라이브러리.
  3. DOI (Document Object Identifier) 참조.
  4. Crossref, DataCite, PubMed 검색.

Zotero, DOI 조회, 검색에서 인용을 삽입하면 문서 참고문헌에 자동으로 추가됩니다.

참고문헌

Pandoc은 BibTeX와 CSL 등 다양한 형식의 참고문헌을 지원합니다. bibliography YAML 메타데이터 필드로 참고문헌을 추가합니다. 예:

---
title: "My Document"
bibliography: references.bib
link-citations: true
---

link-citations 옵션을 지정하면 인용이 해당 참고문헌 항목으로 연결되는 하이퍼링크가 됩니다.

참고문헌 형식에 대한 자세한 내용은 Pandoc Citations 문서를 참고하세요.

인용 삽입

Insert -> Citation 명령을 사용하거나 마크다운 문법(예: [@cite] 또는 @cite)으로 인용을 삽입합니다.

인용은 대괄호 안에 있으며 세미콜론으로 구분합니다. 각 인용은 데이터베이스의 인용 식별자 앞에 ’@’가 붙는 키를 가져야 하며, 접두사, 위치, 접미사를 선택적으로 포함할 수 있습니다. 인용 키는 문자, 숫자, _로 시작해야 하고, 영숫자, _, 내부 문장부호(:.#$%&-+?<>~/)를 포함할 수 있습니다. 예:

Blah Blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
Blah Blah [@doe99, pp. 33-35, 38-39 and passim].
Blah Blah [@smith04; @doe99].
Smith says blah [-@smith04].

텍스트 본문 내 인용도 다음과 같이 작성할 수 있습니다:

@smith04 says blah.
@smith04 [p. 33] says blah.

인용 구문에 대한 자세한 내용은 Pandoc Citations 문서를 참고하세요.

도구 모음 버튼 또는 ⇧⌘ F8 단축키를 사용해 Insert Citation 대화상자를 표시합니다:

RStudio의 'Insert Citation' 창. 왼쪽에는 'My Sources', 'Bibliography', 'Zotero', 'My Library', 'From DOI', 'Crossref', 'DataCite', 'PubMed' 옵션이 세로로 배치되어 있습니다. 오른쪽 상단에는 검색 바가 있고 'Search for citation' 안내 텍스트가 보입니다. 아래에는 검색 결과 목록이 있습니다. 각 결과는 '@citation-ref' 형태의 제목, 왼쪽 아이콘, 아래의 회색 제목, 오른쪽의 회색 인용 정보를 포함합니다. 창 하단에는 'Select Citation Keys' 텍스트가 있고, 왼쪽 하단에는 'Add to bibliography' 드롭다운(현재 'references.bib'), 오른쪽에는 'Use in-text citation' 버튼과 'Insert', 'Cancel' 버튼이 있습니다.

오른쪽의 추가 버튼을 사용하면 여러 인용을 삽입할 수 있습니다.

마크다운 문법

마크다운 문법(예: [@cite])으로도 인용을 직접 삽입할 수 있습니다. 이 경우 사용 가능한 인용을 검색할 수 있는 자동 완성 인터페이스가 표시됩니다:

R Studio 시각적 편집기에서 열린 R Markdown 문서. 'htmltools' 뒤에 대괄호로 감싼 '@R-htm' 텍스트가 있으며, 아래에는 '@R-htm'으로 시작하는 검색 결과 드롭다운이 표시됩니다. 각 결과는 굵은 '@R-htm' 제목, 왼쪽 아이콘, 아래의 회색 참고문헌 제목, 오른쪽의 회색 인용 정보를 포함합니다.

인용 ID

외부 출처에서 인용을 삽입하기 전에 ID를 사용자 정의하고 싶을 수 있습니다. Insert Citation 대화상자에서 인용 오른쪽의 편집 버튼을 클릭하면 ID를 변경할 수 있습니다:

R Studio의 'Insert Citation' 메뉴 하단. 'Selected Citations' 섹션에 두 개의 인용이 선택되어 있고, 각각 둥근 모서리의 박스로 둘러싸여 있으며 왼쪽에 'x' 버튼이 있습니다. 첫 번째 인용이 선택되어 있고 인용 ID에 커서가 있어 편집할 수 있는 상태입니다.

코드 자동 완성으로 새 인용을 삽입한 경우에도 기본 인용 ID를 변경할 기회가 제공됩니다.

Zotero에서 삽입한 인용은 Better BibTeX 플러그인을 사용해 인용 ID를 생성할 수도 있습니다(Better BibTeX이 설치되어 있으면 인용 옵션에서 활성화 가능).

인용 미리보기

인용을 삽입한 뒤 커서를 올리면, 사용 가능한 경우 출처 링크와 함께 미리보기가 표시됩니다:

R Studio 시각적 편집기에서 열린 R Markdown 문서. '@fayad2020' 인용이 대괄호로 둘러싸여 있고, 마우스를 올리면 MLA 형식의 전체 인용이 표시되는 미리보기가 나타납니다.

DOI에서 인용

Insert Citation 대화상자의 From DOI 패널을 사용해 DOI 기반 인용(예: PubMed 검색에서 얻은 DOI)을 삽입할 수 있습니다:

RStudio의 'Insert Citation' 창. 왼쪽에서 'From DOI'가 선택되어 있고, 오른쪽 검색 바에는 DOI가 입력되어 있습니다. 아래 검색 결과에 해당 DOI의 문서가 표시되며, 제목(검정), 발행 연도/저널(회색), 저자(회색), DOI 하이퍼링크가 표시됩니다. 제목 왼쪽에는 저널 논문 아이콘이 있습니다.

마크다운 문법을 사용할 때는 [@ 뒤에 DOI를 붙여도 조회됩니다:

R Studio 시각적 편집기에서 열린 R Markdown 문서. 대괄호로 감싼 파란색 DOI가 있고, 그 위에 'Citation from DOI:' 팝업이 표시됩니다. 팝업에는 'Citation Id' 텍스트 박스와 인용 정보가 들어 있으며, 하단에는 'Create bibliography file: references.bib'와 'Format' 드롭다운(BibLaTeX)이 표시됩니다.

올바른 작업인지 확인하고(필요 시 제안 ID를 수정) 확인하면 인용이 문서에 삽입되고 참고문헌에 항목이 추가됩니다.

검색에서 인용

Insert Citation 대화상자의 Crossref, DataCite, PubMed 패널을 사용해 해당 서비스에서 인용을 검색할 수 있습니다:

RStudio의 'Insert Citation' 창. 'Crossref' 옵션이 선택되어 있고, 오른쪽 검색 바에 'xie knitr'가 입력되어 있으며, 아래에 검색 결과가 표시됩니다.

검색으로 삽입한 항목은 자동으로 참고문헌에 추가됩니다.

PubMed 쿼리는 지원하는 전체 쿼리 문법을 사용할 수 있습니다. 예를 들어 다음 쿼리는 저자와 제목 필드에서 검색합니다: Peterson[Author] AND Embolism[Title]. PubMed 쿼리 작성 방법은 https://pubmed.ncbi.nlm.nih.gov/advanced/에서 확인하세요.

Zotero에서 인용

Zotero는 인기 있는 무료 오픈 소스 참고문헌 관리자입니다. Zotero를 사용한다면 Zotero 라이브러리에서 직접 인용을 삽입할 수 있습니다. 로컬에 Zotero가 설치되어 있으면 위치가 자동으로 감지되고, 기본 라이브러리(My Library)의 인용을 사용할 수 있습니다:

RStudio의 'Insert Citation' 창. 'My Library' 옵션이 선택되어 있고, 오른쪽 검색 바는 비어 있으며, 검색 결과 영역에 Zotero 라이브러리의 항목이 나열되어 있습니다. 각 결과 아이콘 오른쪽 아래에는 해당 항목이 Zotero 라이브러리에서 왔음을 나타내는 작은 'Z'가 있습니다.

Zotero 참고문헌은 자동 완성에도 자동으로 표시됩니다:

Zotero 항목은 참고문헌 목록의 항목과 함께 작은 “Z” 로고가 겹쳐 표시됩니다. Zotero에서 인용을 삽입했는데 참고문헌에 없는 항목이면 자동으로 참고문헌에 추가됩니다.

데스크톱에서 RStudio와 Zotero를 함께 실행 중이라면 Zotero 라이브러리 연결에 추가 설정이 필요하지 않습니다. 하지만 RStudio Server를 사용 중이거나 웹을 통해 Zotero 라이브러리에 접근하려면 몇 가지 추가 단계가 필요합니다(Zotero Web API 섹션 참고).

그룹 라이브러리

Zotero Groups는 클래스에서 컬렉션을 공유하거나 동료와 프로젝트를 밀접하게 협업할 수 있는 강력한 방법입니다. 기본적으로 Zotero Group Libraries는 Insert Citation 대화상자나 인용 자동 완성에 포함되지 않습니다. 하지만 전역/프로젝트/문서 수준에서 그룹 라이브러리를 사용할 수 있는 옵션이 있습니다.

예를 들어 프로젝트 수준에서 Reproducible Research Series (Year 1) 그룹 라이브러리를 사용하도록 지정할 수 있습니다:

YAML에서 하나 이상의 라이브러리를 지정할 수도 있습니다. 예:

---
title: "Reproducible Research"
zotero: "Reproducible Research Series (Year 1)"
---

zotero: false를 사용하면 문서에서 Zotero를 완전히 끌 수도 있습니다:

---
title: "Reproducible Research"
zotero: false
---

Zotero Web API

RStudio Server를 사용 중이거나 로컬에 Zotero가 설치되어 있지 않더라도 Zotero Web API를 통해 Zotero 라이브러리에 접근할 수 있습니다(웹 Zotero 계정이 있고 라이브러리가 계정과 동기화되어 있어야 합니다).

RStudio Desktop을 사용한다면 보통 Zotero도 데스크톱에서 실행해 로컬 라이브러리에 접근하는 것이 더 쉽습니다. 다만 원한다면 RStudio Desktop에서 Zotero 웹 라이브러리에 접근하는 구성도 가능합니다.

API 접근 키

RStudio는 Zotero Web API로 Zotero 웹 라이브러리에 접근하므로, 먼저 Zotero 계정을 만든 다음 Zotero가 데이터를 계정에 동기화하도록 설정해야 합니다. Zotero 환경설정의 Sync 탭에서 설정할 수 있습니다:

Zotero 환경설정의 Sync 탭.

라이브러리 동기화를 설정한 후에는 RStudio에서 사용할 Zotero API Key를 만들어야 합니다:

Zotero의 'New Private Key' 섹션. 'Allow library access' 옵션이 선택되어 있습니다.

안내에 따라 새 접근 키를 만드세요. RStudio에서 그룹 라이브러리를 사용하려면 기본값을 변경해 그룹에 대한 읽기 전용 접근을 제공해야 합니다(위 그림 참고).

키를 생성한 뒤에는 반드시 키를 기록해 두세요(예: 클립보드에 복사하거나 영구적으로 저장). 다른 페이지로 이동하면 다시 볼 수 없습니다.

마지막으로 R Markdown -> Citations 환경설정으로 이동해 키를 사용하여 Zotero를 RStudio에 연결합니다:

Zotero Library 옵션을 “Web”으로 설정한 뒤 Zotero Web API 키를 붙여넣습니다. Verify Key… 버튼으로 API 키가 정상 동작하는지 확인할 수 있습니다.

연결을 확인하면 Zotero에서 인용을 삽입할 준비가 완료됩니다.