Support Enhanced gf for \documentclass, \RequirePackage, \usepackage, \PassOptionsToClass, \LoadClass and \PassOptionsToPackage

[krishnakumarg1984]

Enhanced gf command is currently only available for \input and \include

VimTeX's enhanced gf command is quite nice. With the cursor anywhere on a line containing \input{filename}, \include{filename}, one can open filename.tex.

Currently, the gf command is 'semi-smart' in that, it works for packages and class files by opening the relevant .sty or .cls files respectively, but only when the cursor is located on the class/package, and not from anywhere else within the line.

This behaviour is slightly inconsistent, and can be mildly annoying because of the following. When attempting to navigate with gf when the cursor is somewhere else in the line, vim issues a error message such as E447: Cannot find file in "usepackage" in path. The user is forced to navigate manually within the line to move the cursor on top of the package/class name located in the correct braces (there can be more than one set of parenthesis, brackets, braces on the line), and then try the gf option again.

Enhancement request

The enhancement request is that the enhanced gf command should work seamlessly and consistently, opening the intended file from anywhere within the line. The following example illustrates some test cases.

Here's a typical scenario

% \LoadClass{article}
% \PassOptionsToClass{...}{cls_name}   % -------------> Is commented out here, but is a valid use case to be tested
% \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}  % --------> Allow deep-nesting. Accepted starred versions.
%                        \documentclass{article}     % ---------> Be insensitive to any (leading) spaces
\documentclass[letterpaper]{article}
\PassOptionsToPackage{utf8}{inputenc}
\RequirePackage{nag}
\usepackage[margin=1in]{geometry}
\usepackage{babel}
\input{my_awesome_preamble}   % rest of the packages loaded with this file

\begin{document}

\input{demo}

Hello world!

\end{document}

Note that I don't have an example for \PassOptionsToClass in the above example. This command is usually employed by class authors (who import a base class, tweak its settings a bit to derive a class for a university thesis template or whatever).
Also note that I have two variants of the \documentclass listed above (with and without options), but the first one is commented out (since a document can have only one valid line specifying documentclass).

In general, most of these example commands take an option either in [ ] or within { }. It is perhaps safe to assume that the gf command is intended to open the .cls/.sty/.tex/.tikz file named within the last pair of braces.

Important Caveat

Quite a few times, when editing .cls, or .sty files through gf one does not typically intend to edit the system-wide installed file under a tex tree (especially in a shared environment, where anyway the texmf tree is typically write-protected for regular users).

Instead, one typically works by putting a copy of the relevant .sty files in the local folder. This is typical when customising Beamer templates to specific requirements of a conference or institutional branding (or when a class or package author personally helps you with a bugfix version before the next release is available on CTAN and updating requires admin access etc).

Therefore when using gf, it is important to look for the relevant file under the current project root where the main file is detected by VimTeX. Otherwise, when gf opens up the package file, one might end up inadvertently editing the non-project version on a global texmf tree.

When a copy of the .cls/.sty file is present somewhere in the current project, gf should open the file as usual, otherwise gf should set the RO attribute to prevent accidental modifications of system-wide shared tex files. (it is likely that a class/package writer only wants a quick/convenient peak at the base class when importing it).

It is up for debate regarding setting RO attributes for the files opened by gf under the current user's $TEXMFHOME.

Other Considerations

Note that the line \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} in the above example does not begin with one of the 'standard' options, but the enhanced gf shall be even more useful here for class-writers using VimTeX, if it works from the cursor located anywhere in the line. i.e. the regex should not just be looking for these commands only at the start of a line. They can be embedded anywhere within the line. This example is from a real-life use-case from the publisher Wiley's official class file.

[lervag]

I believe this is more or less properly implemented now. Please test and provide feedback. And sorry about taking so long!