> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/vi/ngon-ngu/01-multilingual-typesetting-on-overleaf-using-polyglossia-and-fontspec.md). # Dàn trang đa ngôn ngữ trên Overleaf bằng polyglossia và fontspec ## Giới thiệu Bài viết này cung cấp tổng quan về việc dàn trang các tài liệu đa ngôn ngữ trên Overleaf bằng bộ biên dịch XeLaTeX (hoặc LuaLaTeX) kết hợp với các `fontspec` và `polyglossia` gói LaTeX. Đối với nhiều người dùng, nếu không muốn nói là hầu hết, lựa chọn mặc định cho bộ máy TeX của họ là `pdfTeX`, vốn, khác với XeTeX và LuaTeX, không có khả năng tích hợp để đọc [UTF-8](https://en.wikipedia.org/wiki/UTF-8) các tệp văn bản được mã hóa. Việc dùng pdfTeX khiến việc dàn trang một số ngôn ngữ trong LaTeX rất phức tạp, đặc biệt là những ngôn ngữ không dùng hệ chữ dựa trên Latin. Một số gói—chẳng hạn như [`inputenc`, `fontenc` và](/latex/vi/ngon-ngu/05-arabic.md) [`arabtex`](/latex/vi/ngon-ngu/05-arabic.md)—cung cấp hỗ trợ cho pdfTeX để dàn trang các ngôn ngữ và hệ chữ không phải Latin, nhưng không phải mọi hình tự và ký tự đều được hỗ trợ hoặc hiển thị đúng trong tệp PDF đầu ra, ngay cả khi bạn đã dùng tùy chọn `utf8` hoặc `utf8x` với `inputenc`. Để thảo luận chuyên sâu về UTF-8, mã hóa Unicode và các bộ máy XeTeX/LuaTeX, bài viết trên Overleaf [Unicode, UTF-8 and multilingual text: An introduction](/latex/vi/bai-viet-chuyen-sau/51-unicode-utf-8-and-multilingual-text-an-introduction.md) là một bài đọc rất thú vị. ## Giới thiệu XeTeX và LuaTeX Các bộ máy XeTeX và LuaTeX có thể trực tiếp đọc/xử lý văn bản mã hóa UTF-8; do đó, chúng cung cấp hỗ trợ gốc cho Unicode—chúng cũng có thể [làm việc trực tiếp với phông TrueType và OpenType](/latex/vi/phong-chu/03-xelatex.md) trực tiếp. Những đặc tính này khiến chúng trở thành lựa chọn tự nhiên để dàn trang các tài liệu đa ngôn ngữ hoặc không phải Latin trong LaTeX, tạo ra các đầu ra như sau: ![](/files/8a4f8b6095eb6b738cd05887cf3f0073ae9c8d6e) ![](/files/d712cbbf52cddc01c2cac86f5cb210ce325138fe) ![](/files/89af55b66ff23ad7fc644909b519b314aa229cc6) Các ví dụ này có thể tìm thấy trong Thư viện Overleaf: [Cách viết văn bản đa ngôn ngữ với các hệ chữ khác nhau trong LaTeX trên Overleaf](https://www.overleaf.com/latex/examples/how-to-write-multilingual-text-with-different-scripts-in-latex/wfdxqhcyyjxz) và ["Cảm ơn" đa ngôn ngữ](https://www.overleaf.com/latex/templates/multilingual-thank-you/wjmrnnqkstyf). Nếu bạn muốn dàn trang tiếng Trung, tiếng Nhật và tiếng Hàn, hãy xem các bài viết này: * [Tiếng Trung](/latex/vi/ngon-ngu/06-chinese.md) * [Tiếng Nhật](/latex/vi/ngon-ngu/11-japanese.md) * [Tiếng Hàn](/latex/vi/ngon-ngu/12-korean.md) Xe(La)TeX vẫn hữu ích cho các ngôn ngữ này, nhưng cũng có những bộ máy TeX chuyên dụng hơn, cụ thể là [được thiết kế để dàn trang các ngôn ngữ CJK](/latex/vi/chu-de-khac/45-tex-primitives-listed-by-cjk-tex-engine.md)—chẳng hạn như [pTeX](https://ctan.org/pkg/ptex?lang=en) để dàn trang tiếng Nhật. Lưu ý rằng nếu con trỏ của bạn dường như hoạt động không đúng khi chỉnh sửa văn bản bằng một số ngôn ngữ nhất định trên Overleaf, bạn có thể nhấp vào nút Overleaf **Menu** (nằm phía trên danh sách tệp dự án) và thay đổi tùy chọn “Font Family”. Bạn cũng có thể thử [thay đổi tùy chọn phông chữ đơn cách của trình duyệt](https://www.howtogeek.com/208552/how-to-change-the-default-fonts-in-your-web-browser/) hoặc thay vào đó dùng chế độ Rich Text của Overleaf. Tuy nhiên, tại thời điểm viết bài, chế độ Source và Rich Text có thể chưa (hoặc chưa) hỗ trợ đầy đủ việc chỉnh sửa văn bản từ phải sang trái ở mức chức năng mà chúng tôi hướng tới. ## Thay đổi bộ biên dịch của dự án Tính năng `fontspec` và `polyglossia` gói cần bộ biên dịch XeLaTeX hoặc LuaLaTeX, vì vậy bạn sẽ cần thiết lập dự án Overleaf của mình để dùng một trong hai bộ biên dịch đó. Hướng dẫn chi tiết có thể tìm thấy trong bài viết của chúng tôi [Chọn một bộ biên dịch LaTeX](/latex/vi/chu-de-khac/08-choosing-a-latex-compiler.md) nhưng đây là một đoạn video ngắn cho thấy cách đặt bộ biên dịch cho dự án của bạn: {% embed url="" %} Khi bạn biên dịch bằng XeLaTeX hoặc LuaLaTeX, bạn có thể (nên) xóa `inputenc` và `fontenc` các gói khỏi phần lời dẫn của tệp .tex vì các bộ máy có hỗ trợ Unicode này sẽ mặc định các tệp đầu vào (văn bản) được mã hóa UTF-8. Nhân tiện, mọi tệp văn bản tải lên Overleaf đều được chuyển sang UTF-8 nên thông thường bạn nên dùng `utf8` với `inputenc` khi làm việc với các bộ biên dịch pdfLaTeX và LaTeX trên Overleaf. ## Nếu toàn bộ tài liệu của bạn chỉ bao gồm một ngôn ngữ Khi sử dụng gói `fontspec` này, bạn có thể chỉ cần thiết lập một phông chính (serif), một phông sans-serif và có lẽ một phông đơn cách được thiết kế để hỗ trợ ngôn ngữ bạn đang dàn trang—nhưng có một điểm cần lưu ý, chúng ta sẽ quay lại sau trong bài viết. Ví dụ, nếu toàn bộ tài liệu của bạn bằng tiếng Hy Lạp, với một vài từ tiếng Anh, bạn chỉ cần viết ```latex \usepackage{fontspec} \setmainfont[Script=Greek]{GFS Artemisia} \setsansfont[Script=Greek]{GFS Neohellenic} \setmonofont[Script=Greek]{Noto Mono} . . . Το Lorem Ipsum είναι \textsf{απλά} ένα κείμενο χωρίς νόημα για τους επαγγελματίες της \texttt{τυπογραφίας} και στοιχειοθεσίας. ``` Bạn có thể chọn phông chữ từ một [danh sách các phông TrueType và OpenType có sẵn](https://www.overleaf.com/help/193). Gói `Ligatures=TeX` được thêm tự động cho `\setmainfont` và `\setsansfont`, vì vậy bạn không cần tự thêm nó. (`\setromanfont` là bí danh của `\setmainfont`.) Mã LaTeX ở trên tạo ra kết quả đầu ra sau: ![](/files/f9a46f6b91c7b13c66d7c13e997aa495fb06df4b) ## Nhiều ngôn ngữ/hệ chữ trong cùng một tài liệu: Giới thiệu polyglossia Nếu tài liệu của bạn chứa lượng văn bản đáng kể bằng nhiều ngôn ngữ, thì `polyglossia` gói này hữu ích trong việc xử lý các quy ước dàn trang và ngắt từ đặc thù của từng ngôn ngữ. ```latex \usepackage{fontspec} \setmainfont{FreeSerif} \setsansfont{FreeSans} \setmonofont{FreeMono} \usepackage{polyglossia} \setdefaultlanguage{french} \setotherlanguages{english,russian,thai} \begin{document} \begin{abstract} Le Lorem Ipsum est simplement du faux texte employé dans la composition et la mise en page avant impression. \end{abstract} Merci. \textenglish{Thank you.} \textrussian{Спасибо.} Et plus de texte en français! Le Lorem Ipsum est le faux texte standard ... \begin{english} Lorem Ipsum is simply dummy text ... \end{english} \begin{russian} Lorem Ipsum - это текст-`\textsf{рыба}', часто используемый в \texttt{печати} и вэб-дизайне. ... \end{russian} \begin{thai} \XeTeXlinebreaklocale "th_TH" \textenglish{Lorem Ipsum} คือ เนื้อหาจำลองแบบเรียบๆ ที่ใช้กันในธุรกิจงานพิมพ์หรืองานเรียงพิมพ์ \end{thai} ``` ![](/files/7c3e6726638180ac72a69e9a592c9a8400a84a50) `polyglossia` cho phép bạn đặt ngôn ngữ chính của tài liệu bằng `\setdefaultlanguage` (mặc định là tiếng Anh) và (có thể nhiều) ngôn ngữ ‘khác’ bằng `\setotherlanguages`. (`\setmainlanguage` là bí danh của `\setdefaultlanguage`.) Nếu bạn chỉ định sẽ dùng một ngôn ngữ nước ngoài khác, bạn có thể dùng dạng số ít `\setotherlanguage`. Tên ngôn ngữ giống như những tên được dùng bởi `babel`. Chúng tôi đã chuẩn bị một ví dụ nhỏ về một tài liệu (chủ yếu) bằng tiếng Pháp, cũng chứa một ít văn bản tiếng Anh, tiếng Nga và tiếng Thái. Chúng tôi quyết định dùng các phông FreeSerif, FreeSans và FreeMono. Vì ngôn ngữ chính của tài liệu là `french`, còn `abstract` môi trường tự động tạo tiêu đề ‘Résumé’. Hãy chú ý rằng, ở cuối đoạn đầu tiên, dấu chấm than được dàn trang theo quy ước khoảng cách kiểu Pháp: nó được tách ra khỏi ‘français’ mặc dù ngay sau từ `français` trong mã nguồn. Trong phần văn bản chính, các đoạn ngắn tiếng Anh, chữ Kirin và tiếng Thái có thể được chèn vào một đoạn văn bản tiếng Pháp bằng `\textenglish{Thank you}`, `\textrussian{Спасибо}` và `\textthai{ขอบคุณ}`. Nói chung, bạn có thể dùng `\textLANGUAGE{...}` để dàn trang văn bản bằng bất kỳ `LANGUAGE` ngôn ngữ nào đã được khai báo bởi `\setdefaultlanguage` và `\setotherlanguages`. Vì phông chính (serif) của tài liệu là FreeSerif, và FreeSerif chứa các hình tự cho bảng chữ cái Latin, Kirin và Thái (và nhiều hơn nữa!), `fontspec` và `polyglossia` nên có thể dùng nó để hiển thị tất cả các văn bản này vào tệp PDF đầu ra. Đối với các đoạn văn dài bằng ngôn ngữ nước ngoài/ngôn ngữ khác, khuyến nghị dùng `\begin{LANGUAGE}`...`\end{LANGUAGE}`, ví dụ. `\begin{russian}`...`\end{russian}`, `\begin{thai}`...`\end{thai}`. Trong trường hợp tiếng Ả Rập, bạn không thể dùng `\begin{arabic}`...`\end{arabic}`; bạn sẽ phải viết `\begin{Arabic}`...`\end{Arabic}` thay vào đó, trong khi `\textarabic{...}` vẫn hợp lệ. Một số ngôn ngữ có thể cần lưu ý thêm: chẳng hạn, trong môi trường `thai` môi trường, các từ `Lorem Ipsum` cần được bao trong một `\textenglish{...}` (hoặc `\textfrench{...}`lệnh) để bảo đảm chúng được hiển thị bằng các hình tự của hệ chữ Latin. Đến đây bạn có thể hỏi: Nếu FreeSerif đã rất linh hoạt và vốn chứa các hình tự cho tiếng Nga và tiếng Thái, tại sao chúng ta vẫn cần dùng `\textrussian`, `\begin{english}`...`\end{english}` v.v.? Chẳng phải như thế là thừa sao? Hãy xem điều gì xảy ra khi chúng ta bỏ các `\begin{english}`...`\end{english}` và `\begin{russian}`...`\end{russian}` môi trường: ![](/files/bc127b78f0c5615c23aff5548753eb453039eee0) Dĩ nhiên, các hình tự Latin và Kirin đều được hiển thị trong tệp PDF đầu ra, nhưng lưu ý rằng một số từ giờ đây bị ngắt từ sai: ‘unk-nown’ và ‘unchan-ged’—và стандартной thì không bị ngắt từ chút nào. Nếu không có các môi trường chuyển đổi ngôn ngữ, bộ biên dịch nghĩ rằng các mục văn bản này vẫn là tiếng Pháp và cố gắng dàn trang chúng theo các quy ước tiếng Pháp. Bộ biên dịch cố áp dụng các quy tắc ngắt từ tiếng Pháp, và dĩ nhiên cho ra kết quả sai. Đó là lý do vì sao kiểu chữ và dàn trang còn nhiều hơn chỉ là thiết kế và lựa chọn phông: chúng là những ngành phụ thuộc rất nhiều vào ngôn ngữ và văn hóa. Xem lại ví dụ tiếng Hy Lạp đầu tiên, giờ chúng ta thấy vì sao nên tải `polyglossia` và dùng `\setdefaultlanguage{greek}`: để bảo đảm tài liệu được dàn trang theo các quy ước Hy Lạp. ## Trộn lẫn các ngôn ngữ viết từ phải sang trái (RTL) và từ trái sang phải (LTR) Bạn cần cẩn thận khi dàn trang một hỗn hợp các hệ chữ viết từ phải sang trái (RTL), như tiếng Ả Rập hoặc tiếng Hebrew, và các hệ chữ viết từ trái sang phải (LTR) trong cùng một tài liệu. Hãy xem tài liệu Ả Rập ngắn sau có một từ tiếng Anh, dùng Amiri làm phông chính: ```latex \usepackage{polyglossia} \setdefaultlanguage{arabic} \setmainfont{Amiri} \begin{document} ما هو differentiation \end{document} ``` kết quả là: ![](/files/404300f09fa2f52394bcc81cded47e2b218ee04e) Văn bản được tự động dàn theo hướng phải sang trái, bắt đầu từ mép phải của trang. Bản thân từ “differentiation” được dàn đúng như văn bản trái sang phải—nhưng khoan, *không, không phải vậy*! Nó được hiển thị thành “dffirentiation” trong kết quả đầu ra! Chuyện gì đang xảy ra vậy? Phông Amiri quả thực có các hình tự cho chữ cái Latin nhưng ở đây văn bản `differentiation` không được đánh dấu là tiếng Anh: bộ biên dịch xem `differentiation` như văn bản phải sang trái, như thể đó là một chuỗi ký tự Ả Rập. Trong quá trình dàn trang, chuỗi gốc `iff` được xử lý thành `ffi` (tức là như văn bản RTL) và hình tự [liên tự](https://en.wikipedia.org/wiki/Typographic_ligature) cho “ffi” được dàn trang. Việc đánh dấu từ đó bằng `\textenglish{...}` đảm bảo nó được diễn giải đúng là văn bản từ trái sang phải. ```latex \setmainfont{Amiri} \setotherlanguage{english} \newfontfamily\englishfont{TeX Gyre Termes} \begin{document} ما هو \textenglish{differentiation} ``` ![](/files/7d1f9dd4d4b239b747e630bdeb5c389b54d08a33) **Lưu ý:** Nếu bạn đã quen với các lệnh của `babel` gói commands bạn sẽ vui khi biết rằng các lệnh `\selectlanguage`, `\foreignlanguage` và môi trường `otherlanguage` cũng được hỗ trợ bởi `polyglossia`. ## Các tùy chọn riêng theo ngôn ngữ Một số ngôn ngữ hỗ trợ thêm các tùy chọn tùy biến; ví dụ, `greek` chấp nhận một `variant=ancient`, `mono` hoặc `poly` cho tiếng Hy Lạp cổ, đơn thanh hoặc đa thanh; `hindi` có thể được cấu hình với `numerals=western` hoặc `devanagari`. Xem [tài liệu gói polyglossia](http://texdoc.net/pkg/polyglossia) để biết chi tiết. Những tùy chọn này có thể được chỉ định khi tải ngôn ngữ: ```latex \setdefaultlanguage[variant=poly]{greek} \setotherlanguage[numerals=western]{hindi} ``` hoặc sau đó bất cứ lúc nào: ```latex \setkeys{greek}{variant=ancient} ``` hoặc thậm chí cục bộ cho một môi trường cụ thể: ```latex \begin{greek}[variant=ancient] ... \end{greek} ``` ## Chỉ định phông cho từng ngôn ngữ cụ thể Bạn có thể chỉ định phông dùng cho các ngôn ngữ khác nhau. Giả sử bạn muốn dàn trang toàn bộ văn bản tiếng Anh (có trong ví dụ trước) bằng chữ nghiêng; bạn có thể viết: ```latex \newfontfamily\englishfont{FreeSerif Italic} ``` ![](/files/b72ecb54b37dfb10aa3febf544397d7aabde3379) Tất nhiên bạn còn có thể dùng thứ gì đó cầu kỳ hơn nữa: ```latex \newfontfamily\englishfont{Chancery Uralic} ``` ![](/files/bbf40b969e6318f74ef1847568217a24d4ffbccb) Cơ chế đặt phông cho các ngôn ngữ hoặc hệ chữ khác nhau này đặc biệt quan trọng khi bạn dùng một phông chính mà *không* có các hình tự cho mọi hệ chữ hoặc ngôn ngữ trong tài liệu của bạn. Giả sử giờ chúng ta quyết định dùng Caladea làm phông chính của tài liệu: ```latex \setmainfont{Caladea} ``` Khi biên dịch, chúng ta sẽ thấy lỗi sau: ``` Lỗi gói polyglossia: Phông roman hiện tại không chứa hệ chữ Kirin! (polyglossia) Vui lòng định nghĩa \cyrillicfont với \newfontfamily. Xem tài liệu gói polyglossia để biết giải thích. Nhập H để được trợ giúp ngay. ... l.15 \select@language {russian} Lỗi gói polyglossia: Phông roman hiện tại không chứa hệ chữ Thái! (polyglossia) Vui lòng định nghĩa \thaifont với \newfontfamily. Xem tài liệu gói polyglossia để biết giải thích. Nhập H để được trợ giúp ngay. ... l.23 \select@language {thai} ... ``` Bây giờ chúng ta buộc phải chỉ định phông nào sẽ dùng cho các hệ chữ Kirin và Thái. Một lần nữa, bạn có thể tham khảo [danh sách các phông TrueType và OpenType có sẵn](https://www.overleaf.com/help/193) trên Overleaf. ```latex \newfontfamily\cyrillicfont[Script=Cyrillic]{Charis SIL} \newfontfamily\thaifont[Script=Thai]{Garuda} ``` ![](/files/30bc838254a7eb5449b476520bbfb5e27bfdfbd3) **Lưu ý**: việc giải quyết các vấn đề liên quan đến lựa chọn các tổ hợp phông vừa đẹp mắt vừa tương thích về mặt dàn trang nằm ngoài phạm vi của bài viết này. Lưu ý rằng chúng ta đã định nghĩa `\cyrillicfont` thay vì `\russianfont`, tức là chúng ta đã định nghĩa một phông cho *hệ chữ* thay vì cho ngôn ngữ Nga *ngôn ngữ*. Ưu điểm của việc định nghĩa `\cyrillicfont` là nếu, chẳng hạn, `serbian` cũng là một ngôn ngữ đã được định nghĩa trong dự án của bạn, thì `\textserbian` sẽ tự động dùng phông đã định nghĩa cho `\cyrillicfont`. Nếu bạn chỉ định nghĩa `\russianfont`, thì khi dùng `\textserbian` nó sẽ lại phàn nàn rằng “phông roman hiện tại không chứa hệ chữ Kirin” và bạn sẽ cần định nghĩa `\cyrillicfont` dù sao cũng vậy — *trừ khi* bạn *thực sự* muốn dùng một phông khác cho văn bản tiếng Serbia! Một trường hợp tương tự khác là Devanagari *hệ chữ*, hệ chữ được dùng cho các *ngôn ngữ*; hoặc hệ chữ Ả Rập được dùng cho tiếng Ả Rập và Farsi (Ba Tư). ```latex \setdefaultlanguage{english} \setotherlanguages{hindi,sanskrit} \newfontfamily\devanagarifont[Script=Devanagari]{Lohit Devanagari} ... Tiếng Hindi: \texthindi{हिन्दी} Tiếng Phạn: \textsanskrit{संस्कृतम्} ``` ![](/files/5afcf2c54ab678cf106115ea0833c3e79e8cb968) Khi dùng `\newfontfamily` cần phải chỉ định `Script`, nếu không một số hình tự có thể hiển thị không đúng; ví dụ, nếu chúng ta chỉ viết `\newfontfamily\thaifont{Garuda}` kết quả dàn trang có thể bị sai (hình bên trái dưới đây)—kết quả đúng được tạo ra bằng cách thêm `[Script=Thai]`. Sai: ![](/files/d40f5360924f67c0f7b66949cf0b68c46d4546a5) Đúng: ![](/files/ea8386d4b9aa923a46b633f51e51d895deb64928) ## Định nghĩa các họ phông khác Hãy xem một ví dụ khác, lần này với tiếng Hebrew: ```latex \documentclass{article} \usepackage{polyglossia} \setdefaultlanguage[numerals=hebrew]{hebrew} \setotherlanguage{english} \newfontfamily\hebrewfont[Script=Hebrew]{Hadasim CLM} \begin{document} \section{מבוא} זוהי עובדה מבוססת שדעתו של הקורא תהיה מוסחת עלידי טקטס קריא כאשר הוא יביט בפריסתו. - \end{document} ``` ![](/files/0cb388049c924428043b4fed105d133b66770c5d) Từ đầu đến giờ vẫn ổn. Giờ giả sử chúng ta đang dùng một mẫu vốn được tạo cho tài liệu tiếng Anh, trong đó tiêu đề mục được đặt bằng phông sans serif sử dụng `titlesec` gói: ```latex \RequirePackage{titlesec} \titleformat{\section}{\Large\sffamily\bfseries}{\thesection}{1em}{} \usepackage{polyglossia} \setdefaultlanguage[numerals=hebrew]{hebrew} ... ``` Chúng ta gặp thông báo lỗi: ``` Lỗi gói polyglossia: Phông roman hiện tại không chứa hệ chữ Hebrew! (polyglossia) Vui lòng định nghĩa \hebrewfont với \newfontfamily. Xem tài liệu gói polyglossia để biết giải thích. Nhập H để được trợ giúp ngay. ... l.27 \section{מבוא} ``` Điều này hơi khó hiểu: chẳng phải chúng ta đã định nghĩa `\hebrewfont` là Hadasim CLM rồi sao? Thực ra là vì chúng ta *chưa chỉ định phông sans serif cho tiếng Hebrew*. Hãy khắc phục bằng cách thêm định nghĩa cho `\hebrewfontsf`: ```latex \newfontfamily\hebrewfontsf[Script=Hebrew]{Miriam CLM} ``` Và bây giờ chúng ta có kết quả: ![](/files/6abd389f3073b052c5a648dc6035a9b52eac6ea5) Nếu cần, chúng ta cũng có thể định nghĩa một phông đơn cách để dùng với `\hebrewfonttt`. ## Lời cảm ơn Tất cả các đoạn Lorem Ipsum, bằng nhiều ngôn ngữ khác nhau, đều lấy từ [`https://lipsum.com`](https://lipsum.com). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/vi/ngon-ngu/01-multilingual-typesetting-on-overleaf-using-polyglossia-and-fontspec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.