> 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/bai-viet-chuyen-sau/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md).

# Giới thiệu về Kpathsea và cách các bộ máy TeX tìm kiếm tệp

## Giới thiệu

Bài viết này cung cấp phần giới thiệu về cách các bộ máy TeX định vị các tệp cần thiết để dàn trang tài liệu của bạn—dùng LaTeX hoặc bất kỳ gói macro nào khác. Mặc dù Overleaf giúp người dùng tránh khỏi những khó khăn khi quản lý một cài đặt TeX ([TeX Live](https://www.tug.org/texlive/)), những điều cơ bản về cách các bộ máy TeX tìm kiếm tệp sẽ hữu ích/đáng quan tâm nếu bạn muốn tạo cấu trúc thư mục để giúp quản lý dự án Overleaf của mình.

Tại sao điều đó có thể đúng? Nếu bạn lưu một số tệp của dự án Overleaf vào trong các thư mục thì LaTeX có thể không tìm thấy các tệp đó vì, theo mặc định, bộ máy TeX (trình biên dịch) có thể không *biết* rằng nó cần tìm kiếm trong các thư mục đó—vì vậy sẽ không tìm thấy các tệp mà chúng chứa. Để tránh điều này, bạn có thể tạo và thêm vào dự án của mình một tệp cấu hình có tên là một [tệp latexmkrc](https://mg.readthedocs.io/latexmk.html#configuration-files) tệp này có thể được dùng để cho một bộ máy TeX biết rằng các thư mục của bạn tồn tại và nó nên tìm kiếm trong đó.

Nếu bạn muốn xem ngay một ví dụ có tệp latexmkrc, bạn có thể đọc bài trợ giúp này: [Cách dùng latexmkrc với Overleaf: ví dụ và kỹ thuật](/latex/vi/bai-viet-chuyen-sau/28-how-to-use-latexmkrc-with-overleaf.md). Có thể ban đầu không rõ bằng cách nào, hoặc tại sao, tệp latexmkrc đó thực sự hoạt động. Nếu bạn muốn biết vì sao và, có lẽ, hiểu rõ hơn để sử dụng với các khả năng cấu hình tiếp theo cho dự án của mình, thì hãy đọc tiếp... Ở cuối bài viết này chúng ta sẽ thực hiện một [ví dụ thực tế](#kpathsea-and-texinputs-latexmkrc-file-to-the-rescue)—dùng kiến thức của chúng ta về cách TeX tìm tệp—để tạo một tệp latexmkrc nhằm quản lý các thư mục lồng nhau chứa các tệp đồ họa của bạn.

## TeX và tính độc lập nền tảng

Khi Knuth tạo ra TeX, tính độc lập nền tảng là một nguyên tắc trung tâm định hướng cho thiết kế và triển khai của nó, và triết lý đó được phản chiếu trong toàn bộ các hoạt động nội bộ của TeX (ví dụ: dùng số học số nguyên, xử lý chuỗi “tự chế”, quản lý bộ nhớ, v.v.). Ngay cả ngày nay, tính độc lập nền tảng của các bộ máy hiện đại dựa trên TeX vẫn còn gây ra các câu hỏi và tranh luận trên các diễn đàn công khai; chẳng hạn, xem thảo luận này trên tex.stackexchange: [XeTeX và LuaTeX có phụ thuộc nền tảng không?](https://tex.stackexchange.com/questions/94297/are-xetex-and-luatex-platform-dependent) trong đó có các bình luận và nhận xét của nhiều chuyên gia TeX nổi tiếng.

Tuy nhiên, hiện giờ hãy tạm gác sang một bên các chi tiết tinh vi hơn và lưu ý rằng các bộ máy TeX vẫn cần có tính di động rất cao—có khả năng hoạt động trên nhiều hệ điều hành và cho ra kết quả “giống hệt” nhau. Một khía cạnh then chốt của tính di động là tìm tệp theo cách độc lập với nền tảng.

## Các bộ máy TeX không tự tìm tệp… thật vậy sao!?

Không, các bộ máy TeX không *trực tiếp* tìm tệp *một cách độc lập*. Khi xử lý một `.tex` tệp, một bộ máy TeX có thể xác định nhu cầu mở một tệp cụ thể nhưng nó *ủy thác* nhiệm vụ tìm ra nó cho một phần mềm khác có tên là [*Kpathsea*](https://tug.org/kpathsea/): một thư viện phần mềm bên ngoài không thuộc *phần lõi* mã nguồn của các bộ máy TeX. Những gì Kpathsea cung cấp, về thực chất, là một API ([Giao diện lập trình ứng dụng](https://en.wikipedia.org/wiki/Application_programming_interface)) mà các bộ máy TeX (cùng với BibTeX, MetaPost và các ứng dụng khác) có thể gọi bất cứ khi nào chúng cần mở một tệp cụ thể: Kpathsea thực hiện công việc thực sự là định vị tệp đó.

Khi Knuth viết bộ máy TeX nguyên gốc—từ đó, rốt cuộc, mọi bộ máy TeX khác đều được kế thừa—vấn đề tìm/mở tệp là một thách thức đáng kể, một phần do hệ sinh thái công nghệ rất khác biệt vào thời đó. Thực tế, trong mã nguồn TeX, Knuth gọi việc nhập/xuất tệp là “tai họa của tính di động” (xem trang 12, mục 25 của [TeX: Chương trình](https://www.amazon.co.uk/Computers-Typesetting-TeX-Program-TEX/dp/0201134373)).

Cộng đồng TeX đã nhận ra nhu cầu hài hòa hóa (chuẩn hóa) việc tìm kiếm tệp cho TeX—*và phần mềm liên quan đến TeX*—và quyết định cung cấp cho TeX các công cụ để làm điều đó. Để giải quyết vấn đề rất hóc búa về một phương pháp tìm tệp độc lập với nền tảng, Karl Berry, một thành viên hàng đầu của cộng đồng TeX, đã viết phần mềm giải quyết vấn đề *tìm kiếm theo đường dẫn*: một giải pháp ông đặt tên là [**Kpathsea**](http://tug.org/texinfohtml/kpathsea.html)—được suy ra từ **K**arl’s **Path** **Sea**rching (xem [cuộc phỏng vấn này với Karl Berry](http://www.tug.org/interviews/berry.html)).

Ta có thể lưu ý rằng nó được gọi là K**tìm kiếm theo đường dẫn**sea chứ không phải K**tệp có thể chỉnh sửa**sea vì, như [tài liệu](http://tug.org/texinfohtml/kpathsea.html) ghi chú, đó là một thư viện \*tìm kiếm theo đường dẫn\*. Điều quan trọng cần nhận ra là Kpathsea không chỉ được các bộ máy TeX dùng; nhiều chương trình liên quan đến TeX, bao gồm cả BibTeX và MetaPost, cũng dùng Kpathsea để tìm các tệp đầu vào.

Tóm lược, bất cứ khi nào các macro TeX/LaTeX cần mở một tệp cụ thể, các lệnh từ đó các macro ấy được xây dựng cuối cùng sẽ được chuyển thành các chỉ thị TeX mức thấp (các nguyên thủ TeX) mà các bộ máy TeX thực sự thực thi. Nếu các chỉ thị đó bao gồm nhu cầu mở một tệp, bộ máy TeX sẽ gọi Kpathsea và về cơ bản nói rằng, “hãy tìm tệp này”; nếu việc tìm kiếm đó thành công, tệp sẽ được mở. Tuy nhiên, nếu Kpathsea không thể định vị tệp thì bộ máy TeX sẽ được báo điều đó và sẽ dừng thực thi để đưa ra lỗi khét tiếng ``! Tôi không thể tìm thấy tệp `...'`` Sự thật là Kpathsea không thể tìm thấy nó.

### Lưu ý về LuaTeX

Nói một cách chặt chẽ, chúng ta nên kèm theo một lưu ý ở phần này rằng LuaTeX có cung cấp một cơ chế để người dùng tự cung cấp mã tìm tệp của riêng mình thông qua việc dùng *callbacks*. LuaTeX cho phép người dùng viết các hàm bằng ngôn ngữ kịch bản Lua và đăng ký chúng với LuaTeX để nó sẽ gọi hàm do người dùng định nghĩa đó ở những giai đoạn nhất định trong quá trình thực thi của LuaTeX—do đó có thuật ngữ *callbacks*callbacks [Sổ tay tham chiếu LuaTeX](http://www.pragma-ade.com/general/manuals/luatex.pdf) (tại thời điểm viết bài này, liên kết đó dành cho LuaTeX 1.09).

### Tệp cấu hình của Kpathsea: texmf.cnf

Mọi cài đặt TeX đều chứa một tệp văn bản có tên là `texmf.cnf` đây là một tệp cấu hình được Kpathsea sử dụng: nó chứa nhiều “biến cấu hình” xác định các đường dẫn mà Kpathsea sẽ dùng để tìm kiếm nhiều loại tệp khác nhau mà các bộ máy TeX (hoặc BibTeX, MetaPost, v.v.) có thể cần. Như chúng ta sẽ thấy bên dưới, những “biến cấu hình” đó xác định các đường dẫn tìm kiếm được tạo từ các thành phần đường dẫn gọi là *các phần tử đường dẫn*: sử dụng nhiều cấu trúc, biến và tham số để định nghĩa mỗi phần tử đường dẫn như một “mẫu” mà Kpathsea xử lý để tạo ra các thư mục thực tế cần tìm.

Để đưa ra một ví dụ cụ thể, đây là một biến cấu hình như vậy xác định các đường dẫn tìm kiếm cho phông OpenType—hiện tại, đừng lo về ý nghĩa của cách xây dựng đường dẫn này:

```
OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR//
```

Điều quan trọng ở đây là tệp `texmf.cnf` (được Kpathsea đọc) xác định một biến cấu hình có tên là `OPENTYPEFONTS` được dùng để xác định các đường dẫn mà Kpathsea sẽ dùng để tìm kiếm phông OpenType. Vế phải của dấu “=” trông không giống bất kỳ đường dẫn nào bạn thấy trên một thiết bị thông thường vì nó được tạo dựng bằng nhiều biến và tham số để định nghĩa mỗi đường dẫn như một “mẫu” hoặc “bản thiết kế” mà Kpathsea sẽ dùng để tạo ra các thư mục thực tế cần tìm.

### Khái niệm “đường dẫn” của Kpathsea

Có lẽ khái niệm cốt lõi cần nắm là quan niệm về một “đường dẫn” của Kpathsea: cấu trúc cơ bản mà Kpathsea dùng để xác định vị trí của một tệp cụ thể. Như ta đã thấy trong `OPENTYPEFONTS` ví dụ ở trên, quan niệm về đường dẫn của Kpathsea trông rất khác so với các đường dẫn mà chúng ta quen dùng trên máy tính để bàn hay thiết bị di động.

Trích dẫn từ [tài liệu](http://tug.org/texinfohtml/kpathsea.html#Searching-overview):

> ... một *đường dẫn tìm kiếm* là một danh sách các *phần tử đường dẫn*, là các tên thư mục với một vài “chi tiết bổ sung”.

—nhưng lưu ý rằng dấu chấm phẩy (`;`) cũng được dùng để phân tách *phần tử đường dẫn*. Sau đây, chúng ta sẽ nêu ngắn gọn bản chất của một vài “chi tiết bổ sung” đó.

Trong `OPENTYPEFONTS` ví dụ của chúng ta có ba phần tử đường dẫn, mỗi phần tử được phân tách bằng dấu chấm phẩy (`;`):

![Hình minh họa các phần tử đường dẫn có trong một định nghĩa đường dẫn Kpathsea](/files/1de6b601fbca17757ed240eb04e333fde07332d5)

1. `.` (có nghĩa là thư mục hiện tại)
2. `$TEXMF/fonts/{opentype,truetype}//`
3. `$OSFONTDIR//`

Lưu ý rằng một dấu gạch chéo kép (`//`) trong một phần tử đường dẫn có nghĩa là tìm kiếm các thư mục con (đệ quy).

Một `texmf.cnf` tệp sẽ chứa nhiều “biến cấu hình” để xác định các đường dẫn tìm kiếm cho những kiểu tệp mà Kpathsea có thể tìm.

## Kpathsea: Tổng quan rất ngắn gọn

Kpathsea là một thư viện tinh vi—với nhiều chi tiết và sắc thái—và ngay cả một cái nhìn lướt qua [tài liệu](http://tug.org/texinfohtml/kpathsea.html) của nó cũng cho thấy rõ rằng chúng ta không thể đi sâu vào tất cả các chi tiết. Tuy nhiên, chúng ta có thể cố gắng cung cấp một cái nhìn tổng quan về những gì nó làm—để giúp định hướng suy nghĩ của bạn và đưa ra điểm khởi đầu cho việc đọc tiếp.

### Mục đích cốt lõi của Kpathsea

Như tài liệu đã nêu, mục đích cơ bản của Kpathsea là “trả về tên tệp từ một danh sách các thư mục do người dùng chỉ định” và rằng các thư mục đó (các đường dẫn tìm kiếm) được chỉ định bằng “một vài chi tiết bổ sung”.

### Những “chi tiết bổ sung” đó

Những “chi tiết bổ sung” được nhắc đến ở trên bao gồm nhiều tham số và biến mà Kpathsea dùng để xây dựng các đường dẫn tìm kiếm của nó (hay “các mẫu đường dẫn”) để nó có thể định nghĩa đường dẫn theo cách tổng quát hơn. Khi một bộ máy TeX thực sự đang chạy (thực thi), Kpathsea có thể dùng giá trị hiện tại của những tham số/biến đó để xác định các đường dẫn thực tế bằng cách thay các biến ấy bằng các giá trị thực (lúc chạy). Bạn có thể dễ dàng nhận ra những biến đó (trong các phần tử đường dẫn) vì chúng bắt đầu bằng một `$` ký hiệu.

Vì vậy, ta nói rằng Kpathsea *mở rộng* một phần tử đường dẫn, nghĩa là nó biến đổi các tham số và biến đó: chuyển một “mẫu” đường dẫn thành tên thực tế của một hay nhiều thư mục vật lý mà trong đó cần tìm một tệp. Điều này mang lại rất nhiều tính linh hoạt và có nghĩa là Kpathsea có thể xây dựng một danh sách các thư mục tương ứng với một phần tử đường dẫn riêng lẻ—ví dụ, nếu nó được yêu cầu tìm kiếm các thư mục con.

### Xem lại ví dụ OpenType của chúng ta

Chúng ta sẽ ghép nối các mạch ý khác nhau và khám phá `OPENTYPEFONTS` chi tiết hơn một chút:

```
OPENTYPEFONTS = .;$TEXMF/fonts/{opentype,truetype}//;$OSFONTDIR//
```

Hãy xét hai phần tử đường dẫn `$TEXMF/fonts/{opentype,truetype}//` và `$OSFONTDIR//`. Ở đây, Kpathsea nhận thấy việc dùng ngoặc nhọn `{...}` và xem `$TEXMF/fonts/{opentype,truetype}` như đại diện cho *hai* phần tử đường dẫn:

1. `$TEXMF/fonts/opentype//`
2. `$TEXMF/fonts/truetype//`

và rằng các *thư mục con* của cả hai phần tử đường dẫn đó cũng nên được tìm kiếm (được chỉ ra bởi dấu `//`).

**Lưu ý**: Xem tài liệu Kpathsea về [mở rộng thư mục con](http://tug.org/texinfohtml/kpathsea.html#Subdirectory-expansion) để biết một lưu ý quan trọng về thứ tự mà các thư mục con, ở mọi cấp, được tìm kiếm (điều này là không được chỉ định).

Chúng ta sẽ nêu một vài nhận xét về `$TEXMF` ở dưới đây.

#### $OSFONTDIR//

`$OSFONTDIR` là một biến mà giá trị của nó nên được định nghĩa như một biến môi trường chứa vị trí lưu trữ phông chữ: giá trị chính xác đương nhiên sẽ phụ thuộc vào hệ điều hành đang được dùng để chạy TeX. Lưu ý rằng ở đây, dấu `//` ra lệnh cho Kpathsea tìm kiếm các thư mục con khi tìm phông OpenType.

Định nghĩa mặc định của `OSFONTDIR` trong `texmf.cnf` là:

```
OSFONTDIR = /please/set/osfontdir/in/the/environment
```

Vì vậy, chắc chắn đây là thứ bạn cần đặt nếu muốn sử dụng nó—biến môi trường của bạn sẽ ghi đè định nghĩa “giữ chỗ” này có trong `texmf.cnf`.

Nếu bạn đặt biến môi trường `OSFONTDIR` thì, tại thời điểm chạy, bất cứ nơi nào Kpathsea nhìn thấy `$OSFONTDIR` như một phần của một phần tử đường dẫn (trong `texmf.cnf`) nó có thể thay thế biến `$OSFONTDIR` bằng giá trị thực được lưu trong biến môi trường `OSFONTDIR`. Hãy nhớ rằng, khi dùng nó trong `texmf.cnf` các phần tử đường dẫn, ta chỉ định biến `$OSFONTDIR`—với một dấu `$`ở đầu—để báo cho Kpathsea biết đây là một biến mà *giá trị* nó cần dùng giá trị của.

#### Ghi chú ngắn về $TEXMF

`TEXMF` là một biến cấu hình khác được định nghĩa trong `texmf.cnf`; ví dụ, trong bản phân phối TeX Live chính, bạn sẽ thấy:

```
TEXMF = {$TEXMFAUXTREES$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST}
```

Bạn không cần bận tâm đến chi tiết của định nghĩa `TEXMF`—chúng ta sẽ không khám phá hết mọi chi tiết, mà chỉ lưu ý rằng `$TEXMF` biến được dùng trong các phần tử đường dẫn vì nó định nghĩa một loạt thư mục cấp cao nhất (được gọi là “cây texmf”) từ đó bạn có thể bắt đầu tìm kiếm tệp.

`TEXMF` rất hữu ích nếu bạn muốn, hoặc cần, chia một cài đặt TeX thành nhiều thư mục (hoặc nhiều “cây” thư mục). Ví dụ, có một bộ sưu tập chính hay trung tâm các gói TeX/LaTeX (ví dụ: TeX Live) và một bộ sưu tập khác gồm các tệp và thư mục dùng để lưu trữ các gói LaTeX cục bộ—hoặc, có lẽ, dùng để lưu các tệp cấu hình cục bộ hoặc các phiên bản tùy biến của các gói chuẩn. Việc tách cài đặt TeX theo cách này có thể giúp việc quản lý nâng cấp bộ sưu tập chính/trung tâm (bản phân phối) của các gói TeX/LaTeX dễ hơn vì bộ sưu tập cục bộ của bạn tách biệt khỏi các tệp chính được cập nhật khi bạn nâng cấp bản phân phối/cài đặt TeX Live của mình.

Để biết thêm chi tiết về việc quản lý các cài đặt TeX phức tạp hơn, độc giả quan tâm có thể tham khảo hai bài báo này:

* [Quản lý nhiều cây TDS](http://tug.org/TUGboat/Articles/tb22-3/tb72downes.pdf) của Michael J Downes;
* [Xoay xở với các cây texmf](http://www.ntg.nl/maps/27/17.pdf) của Siep Kroonenberg.

#### Cấu trúc thư mục TeX

Bất kỳ ai đã từng quản lý một cài đặt TeX đều biết rằng các hệ thống TeX hiện đại, chẳng hạn như TeX Live, chứa hàng chục nghìn tệp thuộc rất nhiều loại. Cấu trúc Thư mục TeX (TDS) được thiết kế như một “bản thiết kế” thực hành tốt nhất để tổ chức tập hợp tệp khổng lồ trong một cài đặt TeX đang hoạt động và được khuyến nghị mạnh mẽ khi dùng với Kpathsea.

Để biết thêm thông tin, độc giả được hướng đến đặc tả TDS: [Cấu trúc thư mục cho các tệp TeX](https://www.tug.org/tds/tds.pdf).

## Các kiểu tệp Kpathsea

Bộ ứng dụng sử dụng Kpathsea cần truy cập một dải rộng các kiểu tệp, vì vậy Kpathsea dùng một “biến cấu hình” để xác định đường dẫn cho từng kiểu tệp (hoặc nhóm tệp) mà nó hỗ trợ. Tài liệu trực tuyến có một danh sách đầy đủ (xem thêm [bảng tóm tắt của chúng tôi, bên dưới](#table-listing-kpathsea-config-variables)) nhưng dưới đây là các “biến cấu hình” cho những kiểu tệp phổ biến hơn:

|                      |                                   |
| -------------------- | --------------------------------- |
| **Biến cấu hình**    | **Ví dụ kiểu tệp**                |
| TEXINPUTS            | Tệp nguồn TeX và tệp hình/đồ họa  |
| BIBINPUTS, BSTINPUTS | Tệp nguồn thư mục tài liệu BibTeX |
| TTFONTS              | Phông chữ phác thảo TrueType      |
| OPENTYPEFONTS        | Phông chữ phác thảo OpenType      |

`TEXINPUTS` là một biến cấu hình đặc biệt quan trọng vì nó chỉ định nơi một bộ máy TeX lấy các tệp nguồn đầu vào của nó. Lưu ý rằng các tệp hình ảnh được xem là tệp đầu vào và cũng có thể được tìm kiếm bằng đường dẫn do `TEXINPUTS`.

### Một vài sắc thái của Kpathsea

Như đã lưu ý, Kpathsea có nhiều sắc thái mà chúng ta không thể khám phá chi tiết ở đây. Tuy nhiên, dưới đây là các tính năng mà một số độc giả có thể muốn tìm hiểu:

* **cơ sở dữ liệu tên tệp:** Để giảm thiểu việc tìm kiếm trên đĩa, Kpathsea có thể sử dụng một “tệp cơ sở dữ liệu tên tệp được xây dựng từ bên ngoài [có tên ls-R](http://tug.org/texinfohtml/kpathsea.html#Filename-database) ánh xạ các tệp tới các thư mục”. TeX Live cung cấp một tệp như vậy và các công cụ để cập nhật nó nếu có tệp mới được thêm vào.
* **biến môi trường**: Ngoài các “biến cấu hình” (chẳng hạn như `OPENTYPEFONTS`) Kpathsea cũng khéo léo sử dụng [biến môi trường](https://en.wikipedia.org/wiki/Environment_variable); chẳng hạn, giá trị lúc chạy của các biến môi trường có thể được dùng để định nghĩa các phần tử đường dẫn trong tệp `texmf.cnf` có thể để ghi đè các biến cùng tên được định nghĩa trong `texmf.cnf`).
* **tên chương trình:** Một khía cạnh tinh tế nhưng thiết yếu trong hành vi của Kpathsea là nó có thể dùng tên của chương trình thực thi (ví dụ, bộ máy TeX) để xây dựng các cấu trúc đường dẫn tìm kiếm dành riêng cho chương trình. Điều này mang lại sự linh hoạt đáng kể vì việc tìm đường dẫn có thể được hướng tới các tệp dành cho một bộ máy TeX cụ thể. Ví dụ, đối với LuaTeX/LuaLaTeX:

  ```
  TEXINPUTS.lualatex = .;$TEXMF/tex/{lualatex,latex,luatex,generic,}//
  TEXINPUTS.luatex = .;$TEXMF/tex/{luatex,plain,generic,}//
  ```
* **tìm `texmf.cnf`**: Một câu hỏi bạn có thể đang tự hỏi là Kpathsea biết `texmf.cnf` được lưu ở đâu? Câu trả lời là một biến môi trường có tên là `TEXMFCNF`. Biến này cần được đặt (trên thiết bị/nền tảng đang chạy TeX) thành đường dẫn nơi `texmf.cnf` được lưu.

#### Gỡ lỗi các vấn đề Kpathsea

Người dùng Overleaf có lẽ không cần các tiện ích này, nhưng chúng tôi liệt kê chúng để đầy đủ:

* **kpsewhich**: Một chương trình độc lập (được bao gồm trong TeX Live) có thể dùng để kiểm tra các thiết lập của bạn: xác định giá trị của các biến và tìm tệp. Độc giả quan tâm được hướng đến [tài liệu trực tuyến](http://tug.org/texinfohtml/kpathsea.html#Invoking-kpsewhich) để biết thêm thông tin.
* **biến môi trường**: Kpathsea hỗ trợ một biến môi trường có tên là [`KPATHSEA_DEBUG`](http://www.tug.org/texinfohtml/kpathsea.html#Debugging) để hỗ trợ gỡ lỗi hành vi của nó. Bạn có thể đặt `KPATHSEA_DEBUG` thành các giá trị khác nhau tùy vào lượng thông tin gỡ lỗi bạn cần. Đặt `KPATHSEA_DEBUG=-1` sẽ tạo ra một *lượng* dữ liệu đáng kể.

## Và cuối cùng: các thư mục, tệp hình và latexmkrc

Vậy, những điều trên liên quan thế nào đến latexmkrc? Nếu bạn đọc bài viết này [Cách dùng latexmkrc với Overleaf: ví dụ và kỹ thuật](/latex/vi/bai-viet-chuyen-sau/28-how-to-use-latexmkrc-with-overleaf.md) bạn có thể thấy rằng mã (Perl) trong ví dụ latexmkrc đặt giá trị của một biến môi trường `TEXINPUTS`:

```
$ENV{'TEXINPUTS'}='./tex//:' . $ENV{'TEXINPUTS'};
```

Lưu ý rằng dấu hai chấm (:) được dùng ở đây (`./tex//**:**`) là *cực kỳ* ) là rất quan trọng. Nếu bạn bỏ qua dấu hai chấm đó thì TeX/LaTeX có thể không thể tìm thấy các tệp hệ thống quan trọng, chẳng hạn như các gói LaTeX!

Về thực chất, tệp latexmkrc này làm là thêm một đường dẫn thư mục cấp cao nhất (`./tex` trong ví dụ ở trên) vào biến môi trường do hệ thống định nghĩa để khi Kpathsea dùng biến `TEXINPUTS` môi trường `$TEXINPUTS` thì nó sẽ biết rằng thư mục `/tex//` cần được tìm kiếm để tìm các tệp đầu vào. Nếu bạn xem kỹ, bạn sẽ thấy đường dẫn thực tế được dùng là `./tex//:` trang `//` báo cho Kpathsea tìm kiếm đệ quy trong thư mục tex—tức là xem vào bất kỳ thư mục con nào nằm trong `thư mục tex` . Như đã lưu ý, chúng ta cũng đã thêm ký tự hai chấm quan trọng.

Chúng ta có thể dùng đúng kỹ thuật này cho các tệp hình.

### Một ghi chú bên lề về BibTeX

Như đã lưu ý, chương trình BibTeX cũng dùng Kpathsea để tìm các tệp đầu vào của nó; cụ thể là:

* trang `biến cấu hình BSTINPUTS` (đường dẫn tìm kiếm) được dùng để tìm `.bst` các tệp;
* và `BIBINPUTS` biến cấu hình (đường dẫn tìm kiếm) sẽ được dùng để tìm `.bib` các tệp.

Nếu bạn thêm các `.bst` hoặc `.bib` tệp mới vào dự án Overleaf của mình, bạn có thể dùng kỹ thuật dưới đây để hướng dẫn BibTeX biết tìm các tệp này ở đâu—bạn cần thay `TEXINPUTS` với `biến cấu hình BSTINPUTS` và/hoặc `BIBINPUTS`.

### TEXINPUTS và dùng các thư mục lồng nhau cho tệp đồ họa

Nếu dự án của bạn có rất nhiều tệp đồ họa, có thể tiện lợi khi tạo một bộ thư mục để lưu trữ và quản lý chúng. Ví dụ, ảnh chụp màn hình sau cho thấy một phần của dự án Overleaf dùng một thư mục cấp cao nhất có tên là **`graphics`**:

![Hình minh họa các thư mục lồng nhau trong một dự án Overleaf](/files/6f39a3b335f7249efc9a2ffa6fec825bf333dfad)

Có rất nhiều thư mục con (lồng nhau) chứa đồ họa cho các phần khác nhau của tài liệu của chúng ta.

Giả sử chúng ta có cấu trúc thư mục ở trên và muốn dùng `graphicx` gói (`\usepackage{graphicx}`) và rằng chúng ta cố làm như sau:

```latex
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\includegraphics{endlinechar}% thực hành tốt nhất là không dùng phần mở rộng tệp
\end{document}
```

Nó sẽ không hoạt động và bạn sẽ nhận được một lỗi như sau:

```
! Lỗi LaTeX: Không tìm thấy tệp `endlinechar'.
l.4 \includegraphics{endlinechar}
Tôi không thể định vị tệp với bất kỳ phần mở rộng nào sau đây:
.pdf,.PDF,.ai,.AI,.png,.PNG,.jpg,.JPG,.jpeg,.JPEG,.jp2,.JP2,.jpf,.JPF,.bmp,.BMP,
,.ps,.PS,.eps,.EPS,.mps,.MPS,.pz,.eps.Z,.ps.Z,.ps.gz,.eps.gz
```

Lỗi đó phát sinh vì tệp đồ họa của chúng ta được lưu ở một vị trí mà TeX/LaTeX (và Kpathsea) không biết tới, và vì thế không thể tìm thấy nó—đường dẫn tới tệp đồ họa là:

```
./graphics/Introduction/Chapter1/Section1/Subsection3/endlinechar.png
```

**Lưu ý**: Nhìn chung, thực hành tốt nhất được chấp nhận là ***tránh các ký tự khoảng trắng trong tên thư mục***. Mặc dù chắc chắn có thể có khoảng trắng trong tên thư mục, với các kỹ thuật được thảo luận dưới đây, chúng tôi khuyên không nên làm vậy vì lý do tính di động của tài liệu bên ngoài nền tảng Overleaf.

Như được giải thích trong [bài trợ giúp Overleaf này](/latex/vi/chu-de-khac/27-inserting-images.md) bạn tất nhiên có thể dùng thư mục để lưu trữ các tệp đồ họa của mình nhưng bạn cần cho LaTeX biết chúng được lưu ở đâu. Ở đây, chúng ta sẽ xem xét hai giải pháp:

* Dùng lệnh \graphicspath;
* Dùng kiến thức của chúng ta về Kpathsea và `TEXINPUTS`.

### Dùng \graphicspath

Tính năng `graphicx` gói cung cấp `\graphicspath` lệnh mà bạn có thể dùng để khai báo các đường dẫn nơi các tệp đồ họa của bạn nằm; vì vậy ta có thể làm như sau:

```latex
\graphicspath{{./graphics/Introduction/Chapter1/Section1/Subsection3/}}
```

và giờ đây LaTeX sẽ tìm thấy bất kỳ tệp đồ họa nào được lưu dưới đường dẫn đó.

**Lưu ý**: Nếu bạn *phải* có khoảng trắng trong tên thư mục thì bạn sẽ cần đặt các đường dẫn trong dấu ngoặc kép (`"..."`):

```latex
\graphicspath{{"./graphics/Introduction/Chapter 1/Section 1/Subsection 3/"}}
```

**Lưu ý**: Bạn có thể khai báo nhiều đường dẫn như thế này:

```latex
\graphicspath{{path1}{path2}{path3}...{pathN}}
```

trong đó `...` nghĩa là các đường dẫn bổ sung được đặt trong ngoặc nhọn.

**Lưu ý**: Chúng ta bắt đầu đường dẫn bằng `./graphics` chứ không chỉ `/graphics`. Dấu chấm (.) cho hệ điều hành biết rằng đường dẫn là tương đối với thư mục làm việc hiện tại.

Tính năng `\graphicspath` lệnh hoạt động tốt nhưng nếu bạn có nhiều thư mục thì việc thêm từng đường dẫn có thể trở nên khá tẻ nhạt; ngoài ra, các đường dẫn được định nghĩa qua `\graphicspath` sẽ không còn hoạt động nếu bạn đổi tên các thư mục hoặc tái cấu trúc chúng. Có cách nào dễ hơn không? Có, bạn có thể dùng một tệp latexmkrc!

#### \graphicspath và đệ quy (thư mục con)

Lưu ý rằng có các thảo luận/tranh luận trực tuyến về việc liệu một số hệ thống có hỗ trợ/kích hoạt `\graphicspath` để tìm kiếm đệ quy trong các thư mục con nếu bạn thêm `//` ở cuối đường dẫn: ví dụ, xem các thảo luận này trên tex.stackexchange:

* [Tìm kiếm đệ quy \graphicspath của LaTeX](https://tex.stackexchange.com/questions/25443/latex-graphicspath-recursive-search);
* [Graphicspath cho MikTeX](https://tex.stackexchange.com/questions/3131/graphicspath-for-miktex).

Để tương thích cao nhất, bạn nên giả định rằng `\graphicspath` không hỗ trợ việc tìm kiếm đệ quy trong thư mục.

### Kpathsea và TEXINPUTS (tệp latexmkrc để giải cứu)

**LƯU Ý:** Lưu ý rằng kỹ thuật sau đây hoạt động tốt trên Overleaf và các cài đặt TeX cục bộ được cấu hình phù hợp; **nhưng** nếu bạn dùng một tệp latexmkrc thì dự án của bạn có thể trở nên không tương thích với các cài đặt TeX khác, chẳng hạn như những hệ thống được dùng bởi các nhà xuất bản và hệ thống nộp bài tạp chí trực tuyến. Các cài đặt TeX của bên thứ ba có thể, hoặc có thể không, hỗ trợ hoặc cho phép dùng latexmkrc. Nếu bạn cần xuất dự án Overleaf của mình để dùng ở nơi khác, hoặc muốn nộp nó cho một tạp chí, bạn nên loại bỏ mọi ký tự khoảng trắng khỏi tên đường dẫn và, để tăng khả năng tương thích, thêm một `\graphicspath` lệnh xác định tất cả các đường dẫn:

```latex
\graphicspath{{path1}{path2}{path3}...{pathN}}
```

trong đó `...` nghĩa là các đường dẫn bổ sung được đặt trong ngoặc nhọn.

Kỹ thuật được thảo luận dưới đây (dùng `TEXINPUTS`) đã được kiểm tra thành công trên Overleaf với các bộ máy pdfTeX, XeTeX và LuaTeX (tức là các tùy chọn trình biên dịch pdfLaTeX, XeLaTeX và LuaLaTeX trong menu Overleaf):

![Hình minh họa cách chọn bộ biên dịch LaTeX trên Overleaf](/files/371b91ec4cd897e08dfcbf4d2330123123389187)

Quay lại ví dụ của chúng ta, chúng ta muốn dùng đoạn mã này (với các thư mục lồng sâu) và sẽ dùng một tệp latexmkrc để thực hiện điều đó:

```latex
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\includegraphics{endlinechar}% thực hành tốt nhất là không dùng phần mở rộng tệp
\end{document}
```

Đây là ảnh chụp màn hình cho thấy đoạn mã trên hoạt động trơn tru: LaTeX đã tìm thấy tệp đồ họa của chúng ta (`endlinechar.png`) mặc dù nó nằm trong một cấu trúc thư mục lồng sâu (không có khoảng trắng nào trong tên thư mục).

![Hình minh họa một dự án với các thư mục lồng nhau đang biên dịch trên Overleaf](/files/abf37b76a2d5759edd5956348be6333fb66ce73a)

Vậy, chúng ta đã làm điều này như thế nào? Tất cả những gì bạn cần làm là:

* tạo một tệp mới, không có phần mở rộng, và đặt tên là latexmkrc;
* thêm dòng sau vào tệp đó:

  ```
  $ENV{'TEXINPUTS'}='./graphics//:'.$ENV{'TEXINPUTS'};
  ```

Kpathsea giờ sẽ biết về các thư mục nằm dưới `**graphics**` và vì `//` nó cũng sẽ tìm trong các thư mục con.

Lưu ý một lần nữa rằng dấu hai chấm trong `./graphics//:` thực ra là *cực kỳ* ) là rất quan trọng. Nếu bạn bỏ qua dấu hai chấm đó thì TeX/LaTeX có thể không thể tìm thấy các tệp hệ thống quan trọng, chẳng hạn như các gói LaTeX!

Sử dụng ví dụ dự án đơn giản ở trên, giờ bạn có thể biên dịch nó và voilà! LaTeX tìm thấy tệp đồ họa của bạn—và bạn có thể đổi tên hoặc sắp xếp lại các thư mục dưới /graphics mà điều đó sẽ không ngăn LaTeX tìm thấy chúng.

## Bảng liệt kê các “biến cấu hình” của Kpathsea

Bảng sau là bản tóm tắt được rút ra từ [dữ liệu được liệt kê trong tài liệu Kpathsea](http://tug.org/texinfohtml/kpathsea.html#Supported-file-formats).

|                                                     |                                                                       |                                |
| --------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------ |
| **Biến cấu hình Kpathsea**                          | **Mô tả kiểu tệp**                                                    | **Phần mở rộng tệp**           |
| AFMFONTS                                            | Số liệu font Adobe                                                    | .afm                           |
| MFBASES, TEXMFINI                                   | Bản đổ bộ nhớ Metafont                                                | .base                          |
| BIBINPUTS, TEXBIB                                   | Nguồn thư mục BibTeX                                                  | .bib                           |
| BLTXMLINPUTS                                        | Các tệp thư mục BibLaTeXML cho Biber                                  | .bltxml                        |
| biến cấu hình BSTINPUTS                             | Kiểu BibTeX                                                           | .bst                           |
| CLUAINPUTS                                          | thư viện động cho Lua                                                 | .dll và .so                    |
| CMAPFONTS                                           | các tệp bảng ánh xạ ký tự                                             | .cmap                          |
| TEXMFCNF                                            | Các tệp cấu hình lúc chạy                                             | .cnf                           |
| CWEBINPUTS                                          | Các tệp đầu vào CWEB                                                  | .w, .web, .ch                  |
| TEXCONFIG                                           | Các tệp 'config.\*' của Dvips, chẳng hạn như config.ps                |                                |
| ENCFONTS                                            | các vectơ mã hóa                                                      | .enc                           |
| TEXFORMATS, TEXMFINI                                | Bản đổ bộ nhớ TeX                                                     | .fmt                           |
| FONTCIDMAPS                                         | Ánh xạ CJK                                                            | .cid                           |
| FONTFEATURES                                        | chủ yếu cho các tính năng font OpenType                               | .fea                           |
| FONTS, GFFONTS, GLYPHFONTS, TEXFONTS                | bitmap font chung                                                     | .gf                            |
| TEXPICTS, TEXINPUTS                                 | Hình PostScript bao gói                                               | .eps, .epsi                    |
| TEXINDEXSTYLE, INDEXSTYLE                           | các tệp kiểu makeindex                                                | .ist                           |
| LIGFONTS                                            | các tệp định nghĩa liên tự                                            | .lig                           |
| TEXMFDBS                                            | Cơ sở dữ liệu tên tệp                                                 |                                |
| TEXFONTMAPS                                         | Bản đồ font                                                           | .map                           |
| MPMEMS, TEXMFINI                                    | Bản đổ bộ nhớ MetaPost                                                | .mem                           |
| MPSUPPORT                                           | các tệp hỗ trợ MetaPost, được DMP sử dụng                             |                                |
| MFINPUTS                                            | Mã nguồn Metafont                                                     | .mf                            |
| MFPOOL, TEXMFINI                                    | các chuỗi chương trình Metafont                                       | .pool                          |
| MFTINPUTS                                           | tệp kiểu MFT                                                          | .mft                           |
| MISCFONTS                                           | các tệp liên quan đến font không thuộc các danh mục khác              |                                |
| MLBIBINPUTS, BIBINPUTS, TEXBIB                      | Nguồn thư mục MlBibTeX                                                | .mlbib, .mlbib                 |
| MLBSTINPUTS, BSTINPUTS                              | Kiểu MlBibTeX                                                         | .mlbst, .bst                   |
| MPINPUTS                                            | Mã nguồn MetaPost                                                     | .mp                            |
| MPPOOL, TEXMFINI                                    | các chuỗi chương trình MetaPost                                       | .pool                          |
| OCPINPUTS                                           | các tệp xử lý đã biên dịch của Omega                                  | .ocp                           |
| OFMFONTS, TEXFONTS                                  | Số liệu font Omega                                                    | .ofm, .tfm                     |
| OPENTYPEFONTS                                       | Phông chữ OpenType                                                    |                                |
| OPLFONTS, TEXFONTS                                  | Danh sách thuộc tính Omega                                            | .opl                           |
| OTPINPUTS                                           | các tệp xử lý chuyển đổi Omega                                        | .otp                           |
| OVFFONTS, TEXFONTS                                  | phông ảo Omega                                                        | .ovf                           |
| OVPFONTS, TEXFONTS                                  | Danh sách thuộc tính ảo Omega                                         | .ovp                           |
| PDFTEXCONFIG                                        | Các tệp cấu hình dành riêng cho PDFTeX                                |                                |
| PROGRAMFONTS, PKFONTS, TEXPKS, GLYPHFONTS, TEXFONTS | các font bitmap đã đóng gói                                           | .pk                            |
| TEXPSHEADERS, PSHEADERS                             | PostScript có thể tải xuống                                           | .pro                           |
| RISINPUTS                                           | các tệp thư mục RIS, chủ yếu cho Bibe                                 | .ris                           |
| SFDFONTS                                            | các tệp định nghĩa subfont                                            | .sfd                           |
| TEXINPUTS                                           | Mã nguồn TeX                                                          | .tex                           |
| TEXDOCS                                             | Các tệp tài liệu cho hệ thống TeX                                     |                                |
| TEXSOURCES                                          | Các tệp mã nguồn cho hệ thống TeX                                     |                                |
| TEXMFSCRIPTS                                        | Các tệp thực thi độc lập kiến trúc được phân phối trong các cây texmf |                                |
| TEXPOOL, TEXMFINI                                   | các chuỗi chương trình TeX                                            | .pool                          |
| TFMFONTS, TEXFONTS                                  | Số liệu font TeX                                                      | .tfm                           |
| TRFONTS                                             | phông chữ Troff                                                       |                                |
| TTFONTS                                             | Phông chữ phác thảo TrueType                                          | .ttf, ,TTF, .ttc, .TTC, .dfont |
| T1FONTS, T1INPUTS, TEXPSHEADERS, DVIPSHEADERS       | Phông viền PostScript loại 1                                          | .pfa, .pfb                     |
| T42FONTS                                            | Phông viền PostScript loại 42                                         |                                |
| VFFONTS, TEXFONTS                                   | phông chữ ảo                                                          | .vf                            |
| WEBINPUTS                                           | Các tệp đầu vào WEB                                                   | .web, .ch                      |
| WEB2C                                               | các tệp dành riêng cho triển khai web2c                               |                                |


---

# 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/bai-viet-chuyen-sau/06-an-introduction-to-kpathsea-and-how-tex-engines-search-for-files.md?ask=<question>&goal=<endgoal>
```

`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.