跳到內容
Oleaflyv0.4.12

編譯 LaTeX、Typst 和 Markdown 專案、依引擎選擇編譯選項、讀取記錄檔,並控制離線時的套件取得。

新的 LaTeX 專案會使用 設定 → 引擎 → LaTeX 中的預設編譯引擎。預設是 Tectonic,這是隨 Oleafly 一起提供、以 XeTeX 為基礎的引擎。當專案需要傳統的 TeX 工具鏈時,也可以使用 latexmk,可以只用於單一專案,也可以設為預設。Typst 專案使用內建的 Typst 或專案鎖定的其他版本來編譯,Markdown 專案則透過 Pandoc 和 Tectonic 處理。LaTeX 編譯器和 Typst 版本屬於專案本身,所以變更其中一個專案不會影響其他專案。

在專案工具列使用「重新編譯」;旁邊的箭頭會開啟編譯選項。
在專案工具列使用「重新編譯」;旁邊的箭頭會開啟編譯選項。 開啟完整螢幕截圖
  • 在任何地方按 ⌘↵(Ctrl+Enter)。
  • 工具列右上角的 編譯 按鈕。專案有編譯結果之後,它會顯示為 重新編譯。
  • ⌘K 指令面板中的 重新編譯。
  • 以顯示 PDF 窗格的檢視開啟專案時,會自動編譯一次,讓你看到的是最新的預覽。
  • 在終端機或腳本中執行 oleafly build。請參閱命令列工具。

編譯時一律會先儲存使用中的檔案,讓 PDF 與你看到的內容相符。如果你處於僅編輯器的檢視,編譯時會顯示分割檢視,讓你看到結果。

重新編譯 旁邊的箭頭會開啟編譯選項。選單只會顯示對專案的引擎有作用的選項。

群組使用 Tectonic 的 LaTeX使用 latexmk 的 LaTeXTypstMarkdown
自動編譯是是是是
編譯模式(一般或快速)是否否否
語法檢查是是否否
編譯器(本專案)是是否否
Typst 版本、字型、建置、變體否否是否
編譯錯誤處理是是否否

停止編譯 和 從頭重新編譯 位於每個引擎選單的底部。Typst 專案有建置變體之後,就會出現 變體 群組。

在 編譯器(本專案) 下,Tectonic 是內建的。自動 會透過 latexmk 執行你的系統 TeX,並根據原始碼挑選編譯器。pdfLaTeX、XeLaTeX 和 LuaLaTeX 會鎖定該編譯器,同樣透過 latexmk 執行;upLaTeX 和 pLaTeX 用來編譯日文文件。除了 Tectonic 之外,每個選項都需要 TeX 發行版。如果這台電腦沒有,在你選擇其中一個時,Oleafly 會提議安裝 TinyTeX。請參閱沒有安裝 TeX 時。Typst 的各個群組在 Typst 專案中說明。

在編譯選項中把 自動編譯 設為 開啟,或從 ⌘K 面板執行 啟用自動編譯。它預設是關閉的,適用於每個專案,用同樣的控制項可以再把它關閉。

在 LaTeX 或 Markdown 專案中,Oleafly 會在你停止輸入約 2.5 秒後重新編譯。只有真正的編輯才會觸發。切換分頁或開啟檔案不會。

在 Typst 專案中,自動編譯就是即時預覽。Oleafly 會讓一個 Typst 程序持續執行,開啟中的檔案會在你停止輸入片刻後自行儲存,而 PDF 會在相同的捲動位置重新整理。請參閱使用自動編譯的即時預覽。

編譯不會堆積。如果你在自動編譯執行中編輯,Oleafly 會停止它,並用你最新的文字重新開始,讓 PDF 更快跟上。在以下情況,它會讓編譯完成:編譯是你或代理程式啟動的、正在下載套件、已接近完成,或它本身就是一次重新開始。在這些情況下,會恰好排入一次後續編譯,所以最終的 PDF 仍會反映你最新的編輯。

建置期間,預覽頂端會有一條細細的進度列,在第一份 PDF 出現之前,窗格會顯示百分比估計值。建置完成時,工具列會顯示一個 狀態標籤,內有編譯時間和嚴重程度圖示:

  • 綠色勾號:編譯成功。
  • 琥珀色三角形:編譯完成但有警告。你仍然會得到 PDF。
  • 紅色叉號:編譯時有錯誤。

成功時,預覽會自動切換到 PDF。只有真正的失敗(沒有產生 PDF)才會把你切換到記錄檔檢視。

編譯失敗後,錯誤在編輯器與記錄中被標示,修正後重新編譯成功。
編譯失敗後,錯誤在編輯器與記錄中被標示,修正後重新編譯成功。 開啟完整螢幕截圖
記錄檔和上一次建置所需的時間位於預覽工具列的左側。
記錄檔和上一次建置所需的時間位於預覽工具列的左側。 開啟完整螢幕截圖

預覽工具列左側的 記錄檔 按鈕可以在 PDF 和編譯記錄檔之間切換,並附有計算錯誤(紅色)或警告(琥珀色)數量的徽章:

  • 最上方是解析過的診斷清單:每個錯誤或警告都附有種類,以及在已知時的 l.42 行參照。字型無法顯示的字元會歸在 缺少的字元 之下。
  • 下方是完整的原始編譯器記錄檔,並加上顏色:錯誤為粗紅字、行參照會醒目提示、檔案的巢狀層級會縮排。
  • 複製記錄檔 按鈕會取得全部內容,可用於錯誤回報或論壇貼文。在記錄檔中按 ⌘A 再按 ⌘C 也會複製全部內容。
  • 複製記錄檔 旁邊的 清除 會隱藏記錄檔和其中的錯誤,直到下一次編譯為止。你的建置檔案會保留,下一次編譯會寫出新的記錄檔。

很長的記錄檔也會立刻開啟,即使有 100,000 行也一樣,而且捲動時不會出現空白區域。

編譯錯誤也會透過檢查器管線在編輯器中變成波浪底線,當你要求AI 助理修正錯誤時,它可以用 get_log 工具讀取同一份記錄檔。

Typst 錯誤會標示在編輯器中 Typst 回報的確切範圍,並附上原始碼行和 Typst 自己的提示。常見的錯誤也會附上簡單的說明,解釋哪裡出了問題。

Tectonic 會在文件第一次需要某個 LaTeX 套件時下載它,然後在本機快取。這台電腦的第一次編譯也會一次取得一批常用的套件。第一次編譯可能比較慢,而且需要網路連線。之後的編譯會使用快取。如果 Oleafly 的套件鏡像站失敗,編譯會改用上游來源,記錄檔也會說明這一點。

「設定」的「一般」頁面或指令面板中的 離線模式,讓 Tectonic 的這件事成為保證。編譯器會以 --only-cached 執行,絕不取得套件。需要未快取套件的文件會失敗,並顯示訊息,可能時會指出檔案名稱,而 關閉並編譯 會關閉離線模式並重新編譯。

離線模式也涵蓋 Typst。Typst 在離線模式開啟時無法下載套件,所以每個 @preview 套件都必須已在快取中,或已隨附在專案的 typst-packages 資料夾中。請參閱來自 Typst Universe 的套件。Markdown 專案會忽略離線模式,記錄檔也會說明這一點。

Tectonic 與 Typst 到哪裡找套件Tectonic 會先在這台電腦的套件快取中尋找 LaTeX 套件,缺少的套件只會下載一次。Typst 在你已隨附套件時,會先看專案的 typst-packages 資料夾,再看 Oleafly 的套件快取,缺少的套件只會從 Typst Universe 下載一次。離線模式會關閉這兩種下載。線上TectonicTypsttypst-packages在專案中套件快取在這台電腦上套件快取在這台電腦上TeX 套件只下載一次Typst Universe只下載一次離線模式下不會下載Tectonic 與 Typst 到哪裡找套件Tectonic 會先在這台電腦的套件快取中尋找 LaTeX 套件,缺少的套件只會下載一次。Typst 在你已隨附套件時,會先看專案的 typst-packages 資料夾,再看 Oleafly 的套件快取,缺少的套件只會從 Typst Universe 下載一次。離線模式會關閉這兩種下載。線上TectonicTypsttypst-packages在專案中套件快取在這台電腦上套件快取在這台電腦上TeX 套件只下載一次Typst Universe只下載一次離線模式下不會下載
編譯時會先在這台電腦上尋找。缺少的套件只會下載一次,除非已開啟離線模式。

latexmk 使用你機器上已安裝的 TeX 發行版。Oleafly 會先檢查系統發行版,包括 MacTeX、TeX Live、MiKTeX 和 TinyTeX,而 設定 → 引擎 → LaTeX 會把它用來編譯的那一個標示為 使用中。如果都沒有,應用程式可以安裝並管理自己的 TinyTeX 副本。MiKTeX 也需要 Perl 才能執行 latexmk;請參閱 MiKTeX 與 Perl。由於系統的 TeX 程序可以讀取你的使用者帳號可存取的檔案,請只對你信任的專案使用 latexmk。

當 latexmk 建置找不到 .sty、.cls、參考文獻樣式、字型檔、babel 語言檔、TikZ 程式庫或其他 TeX 檔案時,Oleafly 可以在錯誤訊息中提供 尋找並安裝。檔案名稱和套件名稱通常不同:例如 tikz.sty 屬於 TeX Live 套件 pgf。Oleafly 會找出擁有者,用 tlmgr 安裝它,重新整理套件清單,然後重新編譯。在 Debian、Ubuntu 和 Fedora 上,TeX Live 由系統的套件管理員管理,所以 Oleafly 會改為提供 apt 或 dnf 指令。如果你想先搜尋或手動管理套件,請使用 設定 → 引擎 → LaTeX 中的 套件 清單。

  • 每個專案同一時間只會執行一次編譯,並採用只保留最新要求的佇列:較新的要求會取代過時的要求,所以在建置途中切換專案,絕不會畫出錯誤的 PDF,你輸入時也不會形成大量編譯。
  • 被取代或逾時的建置會被確實取消:Oleafly 會在每個平台上終止編譯器的整個程序樹,而不是讓它留在背景執行。
  • 執行超過 5 分鐘的編譯會被停止,而不是讓它永遠空轉。Tectonic 還在下載套件時,每次下載都會把時限往後延,最多總共 30 分鐘。Markdown 轉 PDF 有 15 分鐘,Quarto 和 Calepin 有一小時。
  • 結果帶有與要求綁定的識別,所以順序錯亂的完成所產生的過時 PDF 會被拒絕,而不是顯示出來。
  • 離線模式下的「Missing package」:在訊息中選擇 關閉並編譯,或暫時為一次編譯關閉離線模式以取得並快取它,然後再把它開啟。
  • 「這個編譯器需要可用的 TeX 發行版」:pdfLaTeX 和其他 latexmk 編譯器需要這台電腦上有 TeX,所以在沒有 TeX 的情況下選擇其中一個,就會開啟這個對話方塊。選擇 下載並使用 TinyTeX,或選擇 切換回 Tectonic 回到內建引擎。如果編譯已經因為這個原因失敗,預覽會提供 下載並使用 TinyTeX 和 使用 Tectonic。請參閱沒有安裝 TeX 時。
  • MiKTeX 上的「latexmk 需要 Perl」:安裝 Strawberry Perl,或安裝自帶 Perl 的 TinyTeX。請參閱 MiKTeX 與 Perl。
  • latexmk 建置中缺少檔案:使用 尋找並安裝。如果查詢失敗,請在 設定 → 引擎 → LaTeX 的 套件 清單中搜尋檔案或套件名稱。在 Debian、Ubuntu 或 Fedora 上,請用 apt 或 dnf 安裝。MiKTeX 套件由 MiKTeX Console 管理。
  • 沒有安裝 upLaTeX 或 pLaTeX:在提供時選擇 安裝日文支援(約 450 MB),或執行訊息中指出的指令。請參閱日文文件。
  • PDF 中缺少文字,通常是韓文、中文或日文:字型沒有這些字元的字形,TeX 會直接略過而不會失敗。Oleafly 會警告你,記錄檔也會提供可以貼上的設定。請參閱PDF 中缺少的字元,Typst 則請參閱顯示為方框的字元。
  • PDF 中缺少索引、詞彙表或符號表:Tectonic 無法執行 makeindex。請把專案切換到 latexmk,或用 \makenoidxglossaries 建置詞彙表,它不需要外部工具。在 latexmk 上,用 xindy 或 \newglossary 產生的清單不會被建置。
  • 編譯逾時:再編譯一次。如果套件還在下載,下載會從停下來的地方繼續。在 Tectonic 上編譯很長的草稿時,請把 編譯模式 設為 快速。
  • Tectonic 中的 EPS 圖片、強制指定的 pdftex 驅動程式,或缺少的內建檔案:會開啟引擎對話方塊。如果沒有開啟,或你把它關掉了,請選擇 選擇引擎。Tectonic 不夠用時說明了它在每種檢視中的位置。請選擇標示為 推薦 的選項:當 Oleafly 找到可用的 TeX 發行版時是你的系統 LaTeX,找不到時則是 下載並使用 TinyTeX。對於缺少的套件,Oleafly 可以在切換後繼續進行安裝程式。
  • minted、PythonTeX 或 \write18 被封鎖:如果你信任專案中的每個檔案,請在編輯器上方的橫幅中選擇 允許外部命令。請參閱允許外部命令。
  • Tectonic 中的套件下載失敗:請檢查網路連線,並在訊息中選擇 重新編譯。Oleafly 在鏡像站之後已經試過上游來源,下載會從停下來的地方繼續,如果電腦當時離線,連線恢復後編譯會自動再執行一次。
  • 「未安裝 Typst 0.13.1」:專案鎖定了這台電腦上沒有的 Typst 版本。在預覽中選擇 下載 Typst 0.13.1,或選擇 使用 Typst 後接你的預設版本以解除鎖定。請參閱鎖定的版本遺失時。
  • 未定義的引用或參照警告:預檢會指出每一個,並附上檔案和行號。
  • 你看不懂的錯誤:問 AI。「修正 LaTeX 錯誤」會觸發編譯、讀取記錄檔、有針對性的編輯和重新編譯的循環,並採用你所選的核准政策。

LaTeX 編譯器的選擇與專案的文件引擎是分開的:

  • Typst 專案使用內建的 Typst 0.15.1 或專案鎖定的版本來編譯。請參閱 Typst 專案。
  • Markdown 專案透過受管理的 Pandoc,並以 Tectonic 作為 PDF 引擎,建置成 PDF。
  • Quarto 專案使用 Quarto 把 .qmd 和 .Rmd 檔案算繪成 PDF 或網頁。請參閱 Quarto。
  • Calepin 專案使用 Calepin 執行 Typst 文件中的程式碼,再用內建的 Typst 建置 PDF。請參閱 Calepin。在你允許之前,這兩種引擎都不會執行專案的程式碼。
  • 帶標籤的無障礙 PDF 透過系統 TeX 安裝或 Oleafly 管理的 TinyTeX 使用 LuaLaTeX。請參閱 LaTeX 引擎與套件。Typst 0.14 及更新版本不需要額外步驟就會為每個 PDF 加上標籤。

引擎是建立專案時為每個專案所做的選擇,介面會配合它調整:引擎無法支援的動作會被隱藏,而不是留著讓它失敗。若要把 LaTeX 專案移到 Typst,請把它轉換成新的 Typst 專案。

啟用檢查點,可以保存成功編譯所用的原始碼。你可以比較並還原較早的建置,而不必改變你手動使用 Git 的工作流程。

若要把編譯出的 PDF 本身保留在專案資料夾中,請在預覽的儲存選單中開啟編譯時同步 PDF。

圖片預覽

無法載入 AI 回答

請再試一次,或搜尋文件。