Add possibility to explicitly signal root directory

[leon-richardt]

An attempt to tackle #826.

Scenario

I ran into #826 with a project structure like this:

Project Structure

meeting-notes
├── .git
├── .gitignore
├── 2022-07-13
│   └── notes.md
├── 2022-07-27
│   └── notes.md
├── 2022-08-10
│   ├── notes.md
│   ├── graphs.pdf
│   ├── multi-graph.pdf
│   └── simple-graph.pdf
├── 2022-08-24
│   ├── graphs.pdf
│   ├── document.pdf -> ../tex-doc/document.pdf
│   └── notes.md
├── 2022-09-07
│   ├── document.pdf -> ../tex-doc/document.pdf
│   └── notes.md
├── 2022-09-21
│   ├── document.pdf -> ../tex-doc/document.pdf
│   ├── notes.md
├── 2022-10-05
│   └── notes.md
├── 2022-10-19
│   └── notes.md
├── 2022-11-02
│   └── notes.md
├── 2022-11-16
│   └── notes.md
├── 2022-11-30
│   ├── document.pdf -> ../tex-doc/document.pdf
│   └── notes.md
├── 2022-12-14
│   └── notes.md
├── 2023-01-11
│   ├── document.pdf -> ../tex-doc/document.pdf
│   └── notes.md
└── tex-doc
    ├── document.aux
    ├── document.fdb_latexmk
    ├── document.fls
    ├── document.log
    ├── document.out
    ├── document.pdf
    ├── document.synctex.gz
    └── document.tex

I keep notes on biweekly meetings as Markdown files in a Git directory (see tree output above). Each meeting gets its own subdirectory so that I can also include other files that were relevant for the meeting. Additionally, some of these meeting directories have symlinks to a document located in the tex-doc/ directory.

When editing tex-doc/document.tex and compiling using TexLab, TexLab tries to determine the root directory from file path. Since meeting-notes/ is the first directory that includes one of the "special files" (the .git/ directory in this case), it is set as the root for the project. Thus, the build artifacts are placed into meeting-notes/ directly instead of tex-doc/, where I would like them to be.

Proposed Change & Justification

Prior to this commit, TexLab searches for the following paths to determine "rootness" of a directory:

• .git/
• Tectonic.toml
• .latexmkrc
• latexmkrc
• .chktexrc
• chktexrc

The Change

My proposed solution is a simple one: in addition to the files above, TexLab also looks for the files .texlabroot and texlabroot. These serve no purpose other than signaling to TexLab that this directory should be considered the project root. With this change, the project structure from above would look like this:

meeting-notes
├── .git
├── .gitignore
├── [omitted for brevity]
└── tex-doc
    ├── .texlabroot
    ├── document.aux
    ├── document.fdb_latexmk
    ├── document.fls
    ├── document.log
    ├── document.out
    ├── document.pdf
    ├── document.synctex.gz
    └── document.tex

Compilations of tex-doc/document.tex will then place the build artifacts into tex-doc/ as desired.

Commit Message

When a root directory is not directly specified in the config, TexLab traverses upwards in the file system hierarchy upwards until a .git directory or a latexmk/chktex/Tectonic configuration file is found. The first directory where one of the search items is found is then considered the root directory. This is a reasonable default but may not work for all project structures.

To provide more flexibility, this commit adds the possibility to explicitly signal when TexLab should stop searching for the root directory via empty ".texlabroot" or "texlabroot" files. These serve no purpose other than signaling to TexLab that it should stop traversing upwards at this point.

The Justification

This solution is ...

• flexible: Users have complete control over when TexLab should stop looking for a root directory.
• backwards-compatible: For existing project structures, TexLab will still behave the same as it did before this change (i.e., nothing will break).
• easy to maintain: Since this solution leverages the existing root discovery algorithm, little additional code maintenance is required.

I think this solution would also help with the scenarios described in @har7an and @xlucn in #826, maybe they can chime in with some additional opinions. 😄

Open Questions & Closing Words

If this PR ends up being merged, I feel like this behavior should definitely be documented somewhere. However, I don't know where this documentation should live. If you point me towards your preferred location, I would be happy to write some docs regarding the behavior of the project root discovery. (In fact, I think the current behavior of the project root algorithm should be documented somewhere as well — maybe it already is and I just haven't found it.)

Overall, if you don't feel comfortable with this change or if it doesn't fit the philosophy of the project, please feel free to deny this PR. No hard feelings in that case.

Thank you for your work on TexLab, it has been a joy to use so far!

[xlucn]

Thanks for pinging me here. Here's my two cents. I think an empty file with any name of .latexmkrc, latexmkrc, .chktexrc or chktexrc also does the same job as this PR.

What I had in mind is more automatic solution. For example, if current file has \begin{document} and \end{document}, then use the folder of current file as root directory. In other words, I hope texlab can find the main document and use its parent folder as root directory. This behavior is intuitive IMHO. (Maybe I should continue the discussion in #826 or in a new issue?)

Here is the reason of the proposal. Texlab is, I guess, executing latexmk from the root directory. So, if the root directory is different from the folder where the main document is, not only the output files are in the wrong place, but texlab also cannot find some included files such as included graphics or tex files. Therefore, I think it's better to determine root directory by the main document, not .git folder or some configuration files.

[leon-richardt]

I think an empty file with any name of .latexmkrc, latexmkrc, .chktexrc or chktexrc also does the same job as this PR.

You are correct, that would result in the same behavior. However, I still think the .texlabroot approach would be a better solution for two reasons:

1. Explicitness: The semantic meaning of an empty .latexmkrc/.chktexrc is unclear whereas .texlabroot only ever serves one purpose. (Although one could argue that a explanatory comment could be added in the .latexmkrc.)
2. Sovereignty: If we depend on configuration files of other tools to signal rootness of a directory, we might get undesired behavior if these tools decide to change their conventions at any point in the future. With a dedicated .texlabroot file, we would have full control over how to interpret it.

(Maybe I should continue the discussion in #826 or in a new issue?)

I agree, I think it's better to stay on topic here — I have replied to you in #826.

[leon-richardt]

Superseded by #839.