Bỏ qua để đến nội dung
Oleaflyv0.4.12

Ghim một phiên bản Typst cho từng dự án, thêm gói từ Typst Universe, kiểm soát phông chữ, biến thể bản dựng và PDF tái lập, rồi chuyển đổi một dự án LaTeX sang Typst.

Oleafly đi kèm Typst 0.15.1 và máy chủ ngôn ngữ Tinymist 0.15.8, nên một dự án Typst mới biên dịch được mà không cần cài thêm gì. Trang này nói về những gì bạn có thể thay đổi: dự án dùng Typst nào, gói và phông chữ của nó đến từ đâu, và làm thế nào một mã nguồn dựng ra nhiều hơn một PDF. Về cú pháp và thanh công cụ, hãy bắt đầu với Viết bằng Typst.

Mở Settings → Engines → Typst. Thẻ đầu tiên là Typst (built in), phiên bản đi kèm với ứng dụng. Nếu một typst đã được cài trên máy của bạn, nằm trên PATH, trong thư mục của Homebrew hoặc trong ~/.cargo/bin, một thẻ thứ hai hiển thị nó dưới tên Typst on this computer. Các dự án ghim chính xác phiên bản đó có thể biên dịch bằng nó.

Bên dưới là Versions, liệt kê Typst 0.11 đến 0.15, mới nhất trước. Mỗi dòng cho biết ngày phát hành, dung lượng tải về, bản sao đến từ đâu (Built in, Downloaded hoặc System) và, sau khi cài đặt, bản phát hành Tinymist mà nó dùng.

  • Install tải về phiên bản đó. Oleafly thử mirror riêng của mình trước rồi GitHub sau, và đối chiếu tệp nén lẫn chương trình bên trong nó với các checksum SHA-256 được dựng sẵn vào ứng dụng. Một tệp không khớp sẽ bị vứt bỏ, và một lần cài thất bại hoặc bị hủy không để lại gì. Các bản tải về nằm trong ~/.oleafly/toolchains/typst/.
  • Nút tròn ở bên trái một dòng đã cài đặt đặt phiên bản đó làm mặc định.
  • Remove xóa một phiên bản đã tải về. Phiên bản mặc định không thể bị xóa, nên hãy chọn một mặc định khác trước.

Phiên bản mặc định và việc ghim phiên bản

Phần tiêu đề “Phiên bản mặc định và việc ghim phiên bản”

Các dự án Typst mới ghim phiên bản mặc định. Các dự án tạo từ mẫu, dự án nhập vào và thư mục được liên kết cũng vậy. Việc ghim được lưu trong project.json của dự án dưới dạng một số phiên bản, chứ không phải một đường dẫn, nên nó vẫn dùng được sau khi bạn di chuyển dự án hoặc mở nó trên máy tính khác.

Thay đổi mặc định sau đó không kéo theo các dự án đã có. Điều đó là có chủ đích: một bài báo đã ghim giữ nguyên cách xuống dòng và số trang khi Oleafly phát hành một Typst mới hơn.

Để đổi phiên bản của một dự án, mở mũi tên bên cạnh Recompile và tìm dưới Typst version (this project). Default theo phiên bản được chọn trong Settings và xóa việc ghim. Các mục khác là những phiên bản đã cài trên máy này, đánh dấu [built in] hoặc [system] khi áp dụng. Để dùng một phiên bản không có trong danh sách, hãy cài nó trong Settings trước.

Nếu bạn mở một dự án ghim một phiên bản mà máy này không có, Oleafly sẽ không âm thầm dựng nó bằng một Typst khác. Việc biên dịch dừng lại với thông báo “Typst 0.13.1 is not installed”, và bản xem trước đưa ra hai nút:

  • Download Typst 0.13.1 cài phiên bản được ghim và biên dịch lại. Nút này xuất hiện khi phiên bản nằm trong số những phiên bản Oleafly cung cấp.
  • Use Typst 0.15.1, đặt tên theo phiên bản mặc định của bạn, xóa việc ghim và biên dịch lại với phiên bản mặc định.

Menu biên dịch đánh dấu việc ghim là [not installed] cho đến khi bạn chọn một trong hai nút.

Thử một phiên bản mới hơn trước khi chuyển

Phần tiêu đề “Thử một phiên bản mới hơn trước khi chuyển”

Với một dự án Typst đang mở, thẻ Typst trong Settings hiển thị Try a newer version bất cứ khi nào một Typst mới hơn đã được cài. Chọn Check with Typst 0.15.1 (hoặc phiên bản nào nó nêu tên). Oleafly dựng dự án hai lần trong các thư mục tạm, một lần với phiên bản hiện tại của dự án và một lần với phiên bản mới hơn. Không gì trong dự án của bạn thay đổi.

Báo cáo cho biết mỗi bản dựng có thành công không, số trang, cùng lỗi và cảnh báo của nó. Nó cho bạn biết nếu số trang thay đổi. New in Typst 0.15.1 liệt kê các thông báo mà chỉ phiên bản mới hơn đưa ra, còn No longer reported by Typst 0.15.1 liệt kê những thông báo biến mất. Nhấp vào một thông báo để mở tệp của nó tại dòng đó.

Nếu bạn thích những gì thấy được, Switch to Typst 0.15.1 ghim dự án vào phiên bản mới hơn. Check again chạy lại cả hai bản dựng sau khi bạn sửa gì đó.

Tinymist dẫn dắt phần gợi ý hoàn thành, trợ giúp khi rê chuột, đổi tên và định dạng trong các tệp Typst (xem Trí tuệ mã nguồn). Mỗi phiên bản phụ của Typst có bản phát hành Tinymist riêng, và một dự án nói chuyện với bản khớp với phiên bản Typst của nó.

Tinymist tích hợp sẵn bao phủ Typst 0.15. Khi bạn mở một dự án ghim vào một nhánh cũ hơn, Oleafly tải về bản Tinymist khớp ở nền sau, với cùng phép đối chiếu checksum, và trạng thái hiển thị “Downloading Tinymist 0.13.30 to match this project’s Typst version.” Nếu việc tải về thất bại, Oleafly thử lại sau. Khi Settings thấy các bản tải Tinymist mà không còn Typst nào đã cài cần đến, nó đưa ra Remove unused language server downloads.

Các phiên bản cũ tồn tại để những dự án bắt đầu trên chúng cứ dựng theo cách cũ. Một số tính năng phụ thuộc vào việc chính phiên bản Typst hỗ trợ gì:

Tính năng0.110.120.130.14 trở lên
Project fonts onlyKhôngCóCóCó
Reproducible buildKhôngCóCóCó
Khoảng trang khi xuất PNG và SVGKhôngCóCóCó
PDF/AKhôngPDF/A-2bPDF/A-2b, PDF/A-3bMọi cấp độ PDF/A Typst cung cấp
PDF/UA-1KhôngKhôngKhôngCó
Gói được giữ trong thư mục dự ánKhôngCóCóCó
Xuất HTML, và xuất Word hoặc Markdown qua HTML của TypstKhôngKhôngCóCó
Đồng bộ mã nguồn và PDFKhôngKhôngCóCó
PDF có gắn thẻ ở mỗi lần biên dịchKhôngKhôngKhôngCó

Trình chọn phông chữ có thể cho biết mỗi phông chữ đến từ đâu trên Typst 0.15 trở lên. Khi một cài đặt không thể áp dụng cho phiên bản dự án đang dùng, menu biên dịch đánh dấu nó Needs a newer Typst.

Chọn Typst packages, biểu tượng gói ở đầu bên phải của thanh công cụ Typst. Tìm trên Typst Universe theo tên, từ khóa hoặc danh mục. Mỗi gói hiển thị phiên bản mới nhất của nó, và một gói cần Typst mới hơn phiên bản dự án đang dùng sẽ nói rõ điều đó: “Needs Typst 0.14.0. This project uses Typst 0.13.1.”

Insert import ghi dòng #import vào đầu tệp Typst đang mở. Copy import đặt nó vào bảng tạm thay vào đó.

Typst tải về một gói @preview ở lần đầu một lần biên dịch nhập nó và giữ nó trong một bộ nhớ đệm mà mọi dự án dùng chung. Danh sách gói cũng được lưu vào bộ nhớ đệm. Khi ngoại tuyến, hộp thoại hiển thị danh sách gần nhất nó đã lấy, kèm ngày tháng.

Khi một lệnh nhập nêu một bản phát hành cũ hơn bản trên Typst Universe, số phiên bản của nó được gạch chân kèm một gợi ý như “cetz 0.4.2 is available. This import uses 0.3.4.” Thẻ gợi ý đưa ra Update to 0.4.2, thay đổi số phiên bản trong lệnh nhập. Hãy đọc nhật ký thay đổi của gói trước khi chấp nhận, vì một bản phát hành mới có thể thay đổi cách gói được gọi. Rê chuột lên một lệnh nhập cũng đưa ra Open on Typst Universe.

Dưới Project packages trong cùng hộp thoại, Vendor packages into project sao chép mọi gói mà dự án nhập vào một thư mục typst-packages ở thư mục gốc của dự án. Nó cũng sao chép các gói mà chính những gói đó nhập, và bật Use packages from the project folder.

Từ đó trở đi Typst tìm trong typst-packages trước. Một dự án đã vendored biên dịch được khi ngoại tuyến và trên bất kỳ máy tính nào, và thư mục đó có thể đi vào Git cùng mã nguồn của bạn. Một gói bạn chưa vendored vẫn đến từ bộ nhớ đệm dùng chung. Việc này cần Typst 0.12 trở lên, và trên một dự án ghim 0.11, hộp thoại yêu cầu bạn chuyển phiên bản trước.

Nếu một gói chưa có trong bộ nhớ đệm, hộp thoại nêu tên nó: “These packages aren’t in the package cache: …”. Hãy biên dịch một lần khi trực tuyến, rồi mới vendored lại.

Khi Offline mode được bật trong Settings → General, Typst không thể tải bất cứ gì. Mọi gói phải đã có trong bộ nhớ đệm dùng chung hoặc trong typst-packages. Nếu thiếu một gói, việc biên dịch thất bại và thông điệp nêu tên gói, nhờ vậy bạn biết cần tải gì ở lần trực tuyến tiếp theo.

Typst tìm phông chữ ở bốn nơi: các phông chữ dựng sẵn trong Typst, các phông chữ cài trên máy của bạn, các gói phông chữ bạn tải trong Oleafly, và các thư mục phông chữ bên trong dự án. Đặt các tệp phông chữ vào một thư mục tên fonts ở thư mục gốc của dự án, thì cả trình biên dịch lẫn máy chủ ngôn ngữ đều nhận ra chúng. Các thư mục thêm có thể được liệt kê dưới typst.font_paths trong project.json. Thư mục nằm ngoài dự án bị bỏ qua.

Dưới Fonts (this project) trong menu biên dịch, Use system fonts là mặc định. Project fonts only khiến Typst không đọc các phông chữ cài trên máy này. PDF khi đó cho ra kết quả giống nhau trên mọi máy, và nếu tài liệu yêu cầu một phông chữ dự án không có, bạn phát hiện điều đó trên chính máy của mình thay vì trên máy của một đồng tác giả.

Để chọn phông chữ phần thân, mở Document settings, biểu tượng thanh trượt trên thanh công cụ Typst, rồi nhấp Body font. Danh sách hiển thị mọi họ phông chữ Typst tìm được với cài đặt phông chữ hiện tại của dự án. Trên Typst 0.15 trở lên, mỗi họ mang một nhãn Project, System, Font pack hoặc Built in. Chọn một họ rồi chọn Apply, Oleafly ghi nó vào các quy tắc #set của tài liệu.

Settings → Downloads → Fonts có năm gói phông chữ miễn phí cho Typst: Chinese, Japanese and Korean, Classic text, Modern sans and serif, Code, và Icons and emoji. Sau khi một gói đã tải xong, mọi dự án Typst đều dùng được phông chữ của nó theo tên, và điều tương tự áp dụng cho các bản tải Lato, PT Sans và PT Serif trên tab đó. Một gói chỉ tham gia các lần biên dịch sau khi toàn bộ lượt tải đã hoàn tất, nên một lượt tải dở dang không bao giờ ảnh hưởng đến bản dựng.

Các dự án đặt Project fonts only hoặc Reproducible build không đọc gói phông chữ. Với những dự án đó, hãy sao chép tệp phông chữ vào thư mục fonts của dự án.

Sau mỗi lần biên dịch, Oleafly kiểm tra những ký tự mà không phông chữ nào có sẵn vẽ được. Typst vẽ chúng thành ô vuông. Khi tìm thấy, lần biên dịch nhận một cảnh báo và một thông báo hiện phía trên trình soạn thảo:

  • Ô vuông trống nghĩa là không phông chữ nào Typst dùng được có các ký tự đó, và cảnh báo nêu tên vài ký tự. Khi một gói phông chữ bao phủ chúng, như gói Chinese, Japanese and Korean làm với văn bản CJK và gói Icons and emoji làm với emoji, thông báo đề xuất Download fonts kèm dung lượng tải, và nhật ký đề xuất Download and compile. Nếu không, hãy thêm một phông chữ có chúng vào thư mục fonts của dự án.
  • Ô vuông có dấu hỏi nghĩa là Typst đã vẽ các ký tự bằng một phông chữ giữ chỗ. Nêu tên một phông chữ có chúng dưới Body font trong Document settings, hoặc trong một danh sách phông chữ như #set text(font: ("Libertinus Serif", "Apple SD Gothic Neo")).
  • Trong một dự án đặt Project fonts only, gói phông chữ và phông chữ hệ thống không áp dụng. Thêm một phông chữ vào thư mục fonts, hoặc chuyển dự án sang Use system fonts và Standard build.

Document settings trong thông báo mở bảng nơi bạn chọn phông chữ phần thân. Đóng thông báo để ẩn nó cho cảnh báo đó.

Một biến thể bản dựng là một bộ giá trị có tên mà tài liệu của bạn đọc qua sys.inputs. Dùng biến thể khi một mã nguồn cần tạo ra các PDF khác nhau, chẳng hạn một bản gửi đánh giá ẩn danh và một bản camera-ready, hoặc một bản nháp có hình mờ.

Tài liệu quyết định mỗi giá trị làm gì. Các giá trị luôn đến dưới dạng văn bản:

#let draft = sys.inputs.at("draft", default: "false") == "true"
#if draft [*Draft. Do not circulate.*]

Để thiết lập một biến thể:

  1. Mở Document settings và cuộn đến Build variants.
  2. Chọn Add variant và đặt tên, ví dụ review.
  3. Chọn Add value, rồi nhập draft dưới Name và true dưới Value.
  4. Chọn Apply.
  5. Mở menu biên dịch. Variant (this project) giờ liệt kê review. Chọn nó và biên dịch.

No variant dựng mà không có giá trị biến thể nào. Biến thể bạn chọn chỉ được ghi nhớ trên máy này, nên một đồng tác giả có thể dựng một biến thể khác từ cùng dự án. Bản thân các biến thể được lưu trong project.json. Việc xuất cũng dùng biến thể đang được chọn.

Các giá trị mà mọi bản dựng đều nên nhận nằm dưới typst.inputs trong project.json. Khi một biến thể đặt một giá trị trùng tên, biến thể thắng.

Dưới Build (this project) trong menu biên dịch, Reproducible build làm cho cùng một mã nguồn cho ra cùng một PDF trên bất kỳ máy tính nào. Nó chỉ dùng các phông chữ của dự án và phông chữ dựng sẵn của Typst, và ghi ngày cho PDF theo commit Git cuối cùng. Một dự án không phải kho Git nhận một ngày cố định là 1 tháng 1 năm 1970.

Điều này quan trọng khi một PDF phải khớp một checksum, cho một lần nộp lưu trữ hoặc một phép so sánh trong CI. Nó cần Typst 0.12 trở lên. Khi nó đang bật, Use system fonts không dùng được. Standard build là mặc định.

Typst biên dịch ngay khi bạn gõ: mỗi dòng mới xuất hiện trong PDF.
Typst biên dịch ngay khi bạn gõ: mỗi dòng mới xuất hiện trong PDF. Mở ảnh chụp màn hình đầy đủ

Bản xem trước trực tiếp với Auto compile

Phần tiêu đề “Bản xem trước trực tiếp với Auto compile”

Đặt Auto compile thành On trong menu biên dịch. Trong một dự án Typst, Oleafly khi đó giữ một tiến trình Typst chạy liên tục. Tệp đang mở tự lưu một lúc sau khi bạn ngừng gõ, Typst biên dịch nó, và bản xem trước tải lại tại cùng vị trí cuộn. Không có một cài đặt bản xem trước trực tiếp riêng biệt: Auto compile chính là bản xem trước trực tiếp.

Trong lúc Typst khởi động, menu hiển thị “Starting Typst”. Nếu nó dừng sau nhiều lỗi lặp lại, menu nói rõ điều đó, và lần chỉnh sửa tiếp theo của bạn khởi động lại nó. Stop compilation kết thúc tiến trình, và lần chỉnh sửa tiếp theo cũng khởi động lại nó. Các dự án LaTeX và Markdown xử lý Auto compile khác đi; xem Biên dịch.

Lệnh oleafly dựng các dự án mà không cần mở ứng dụng. Nó đi kèm Oleafly, và Công cụ dòng lệnh cho biết cách đặt nó lên PATH của bạn.

Với một dự án Typst, oleafly build và oleafly watch đọc project.json và dùng cùng cài đặt như ứng dụng: phiên bản được ghim, các gói đã vendored, các thư mục phông chữ, công tắc phông chữ hệ thống, inputs và bản dựng tái lập.

  • --variant review dựng một biến thể. Một tên dự án không định nghĩa làm việc dựng dừng lại, và thông điệp liệt kê các biến thể mà dự án có.
  • --offline chặn việc tải gói, giống Offline mode trong ứng dụng.
  • Một dự án đã ghim chỉ dựng với chính xác Typst đó. CLI nhìn vào OLEAFLY_TYPST, rồi các phiên bản ứng dụng đã tải về, rồi typst nằm cạnh CLI, rồi PATH của bạn. Nếu không cái nào báo phiên bản được ghim, việc dựng dừng trước khi Typst chạy và cho bạn biết cách cài nó.
  • Một dự án không ghim dùng OLEAFLY_TYPST khi biến này được đặt. Nếu không, nó dùng phiên bản mặc định bạn chọn trong Settings → Downloads hoặc bằng oleafly typst default, và khi chưa chọn mặc định nào, dùng Typst đi kèm hoặc Typst trên PATH của bạn.
  • oleafly doctor liệt kê mọi Typst nó tìm thấy và các cài đặt mà một bản dựng sẽ dùng. Nó thất bại khi phiên bản được ghim bị thiếu.

Nếu một cài đặt không thể áp dụng cho Typst đang dùng, bản dựng in ra một ghi chú, ví dụ rằng Typst 0.11.1 không thể bỏ qua phông chữ hệ thống. Các lỗi trong terminal bao gồm cả gợi ý riêng của Typst.

Mở dự án LaTeX, nhấn ⌘K (Ctrl+K) và chạy Convert to a Typst project. Đặt tên cho dự án mới và chọn Convert. Dự án LaTeX giữ nguyên như cũ. Oleafly dựng từ nó một dự án Typst riêng biệt:

  • Pandoc chuyển đổi văn bản, công thức, hình vẽ và bảng. Nếu Pandoc chưa được thiết lập, Oleafly thiết lập nó trước.
  • Mỗi tệp được đưa vào bằng \input, \include hoặc \subfile trở thành một tệp .typ riêng.
  • Các tệp BibTeX được sao chép nguyên trạng.
  • Typst biên dịch dự án mới để kiểm tra nó.

Báo cáo khi đó cho biết dự án có biên dịch được không và đếm những gì đã được chuyển đổi: các tệp nguồn, hình vẽ, bảng, công thức trình bày, tham chiếu chéo, các công thức bộ chuyển đổi toán đã sửa, và các tệp được sao chép, cùng kiểu tài liệu tham khảo nó chọn. Needs attention liệt kê những gì phải sửa tay, chẳng hạn một lệnh include hay hình bị thiếu, một định dạng hình Typst không hiển thị được, công thức bộ chuyển đổi không xử lý nổi, một kiểu BibTeX không có bản Typst tương ứng, hoặc một nhãn nằm trên một dòng của một công thức nhiều dòng, mà giờ trỏ vào cả công thức. Các lỗi và cảnh báo biên dịch liên kết đến tệp và dòng của chúng.

Chọn Open the Typst project để chuyển sang nó. Dự án mới ghim phiên bản Typst mặc định của bạn. Trong khi Oleafly còn mở, Show the Typst conversion report trong bảng lệnh đưa báo cáo trở lại.

Để chuyển đổi một tệp đơn lẻ thay vì cả một dự án, hãy dùng LaTeX to Typst trên trang Tools.

Xem trước hình ảnh

Không tải được câu trả lời AI

Hãy thử lại, hoặc tìm trong tài liệu.