feat: start work on better TOC

[DockterTeagle]

I am making this very rough draft pull request as I have questions about what I am able to do and want to keep it out of discussions, as I see this being a long chain of replies.

[clason]

This adds a (hard?) requirement on a (Neovim-only) external plugin, which I don't think is acceptable...

[lervag]

This shows how to call a vimscript function in lua directly:

vimtex/lua/vimtex/fzf-lua/init.lua

Line 60 in 7d16d56

local entries = vim.fn["vimtex#parser#toc"]()

[lervag]

I am making this very rough draft pull request as I have questions about what I am able to do and want to keep it out of discussions, as I see this being a long chain of replies.

No problem, feel free to work on the draft and ask for help while doing so.

This adds a (hard?) requirement on a (Neovim-only) external plugin, which I don't think is acceptable...

Does this become a hard requirement immediately? Wouldn't it only become a hard requirement if you actually loaded the module?

There is already an fzf-lua source for the TOC, which can be used as explained in vimtex-fzf-lua.

I think we could add another TOC implementation that requires NUI, as long as it is only optionally loaded and it is properly explained with references in the docs. Similar to how I've added fzf-lua.

However, I do see that we might want to add more structure on the Lua side here. Currently, the fzf-lua feature is activated with require("vimtex.fzf-lua").run(). I guess it would be better to change it into e.g. this, so that we can have more options:

require("vimtex.toc.fzf-lua").run()

-- and then perhaps, with this PR
require("vimtex.toc.nui").run()

[lervag]

I would use lower case letters in the file names, i.e. lua/vimtex/toc/.... Also, I think we should call this script nui.lua, as this seems to aim for a TOC UI based on Nui.

[DockterTeagle]

ok doing that now, a few things:

1. I use NixOS so I added a seperate nix branch that allows me to use direnv-nix with flakes, if you are willing to approve that(I have it a seperate branch for a reason and will open a seperate pr if approved). I understand not wanting to add something that you personally(I assume) dont use. Another problem is that the existence of a flake.nix in a vim plugin usually implies a way to use the flake in the nixos config for config; therefore, there is a possibility of a confusion for other nix users out there. I would try and implement this though as it seems to not be extraordinarily difficult, probably just make an overlay. Although this could make me the de facto nix maintainer which is not something a responsibility I feel ready for. If you are willing to allow nix in this repo then there should be a discussion about which inputs, etc.
2. One problem with this code currently that jumps to mind is that it assumes that vimtex#parser#toc outputs NuiTree.node which is almost certainly not the case. so that will be probably the bulk of this issue if Nui is used.
3. my main use would be to pipe this to trouble.nvim(I am thinking probably either the location list or one of the other modes) so that will be my first target if it works, will then make it more general. What does vimtex#parser#toc ouput exactly it seems to me to be a table of strings of some sort
4. I also looked through trouble.nvim and saw no dependency on nui. so it is possible that I could write it to not require nui. As much as I respect folke, he seems to not do enough docs on what his code does, and why it is implemented that way for those who want to extend it. That is, his actual code is hard to parse for me. Then again it is possible that his code is self explanatory and I lack the experience for it to be so. Furthermore there seems to be radio silence from folke(I think he is on vacation so no shade) so I do not expect any commits from him in his repos anytime soon, let alone documentation commits.
5. is vimtex#parser#toc# a command available to users somehow? if not how could we make it so. I am seeing a scenario where all I need to do is just use that parser and then pipe it to anything.

[lervag]

First, you should keep the main questions and thread as general comments to the PR. For comments on the code you should only discuss the specific code part and/or comment.

1. I use NixOS so I added a seperate nix branch that allows me to use direnv-nix with flakes, if you are willing to approve that(I have it a seperate branch for a reason and will open a seperate pr if approved).

Perhaps, but that would probably be better as a separate PR?

NB! You should have a space before the opening paranthesis: text (remarked), not text(remark).

I understand not wanting to add something that you personally(I assume) dont use. Another problem is that the existence of a flake.nix in a vim plugin usually implies a way to use the flake in the nixos config for config; therefore, there is a possibility of a confusion for other nix users out there. I would try and implement this though as it seems to not be extraordinarily difficult, probably just make an overlay. Although this could make me the de facto nix maintainer which is not something a responsibility I feel ready for. If you are willing to allow nix in this repo then there should be a discussion about which inputs, etc.

I don't mind adding useful things even if I don't use it, but it should be a rationally good choice. If you open a PR with the suggestion and explain what it is and what it does, then it will be easier to discuss it.

Personally, I don't use nix, but I use mise - it is awesome and satisfies most of my "reproducible environment" needs.

2. One problem with this code currently that jumps to mind is that it assumes that vimtex#parser#toc outputs NuiTree.node which is almost certainly not the case. so that will be probably the bulk of this issue if Nui is used.

Yes, you will need to convert the output to whatever is needed for NuiTree.

3. my main use would be to pipe this to trouble.nvim(I am thinking probably either the location list or one of the other modes) so that will be my first target if it works, will then make it more general.

Ok!

What does vimtex#parser#toc ouput exactly it seems to me to be a table of strings of some sort

It returns a list of dictionaries/tables. There's a spec for it here:

vimtex/autoload/vimtex/parser/toc.vim

Lines 7 to 20 in 9d9f74c

	" Parses tex project for ToC-like entries. Each entry is a dictionary
	" similar to the following:
	"
	" entry = {
	" title : "Some title",
	" number : "3.1.2",
	" file : /path/to/file.tex,
	" line : 142,
	" rank : cumulative line number,
	" level : 2,
	" type : [content | label | todo | include],
	" link : [0 | 1],
	" }
	"

4. I also looked through trouble.nvim and saw no dependency on nui. so it is possible that I could write it to not require nui. As much as I respect folke, he seems to not do enough docs on what his code does, and why it is implemented that way for those who want to extend it. That is, his actual code is hard to parse for me. Then again it is possible that his code is self explanatory and I lack the experience for it to be so. Furthermore there seems to be radio silence from folke(I think he is on vacation so no shade) so I do not expect any commits from him in his repos anytime soon, let alone documentation commits.

Ok! I'm sorry I can't be much of a help here.

5. is vimtex#parser#toc# a command available to users somehow? if not how could we make it so. I am seeing a scenario where all I need to do is just use that parser and then pipe it to anything.

I'm not sure I quite understand what you are asking. vimtex#parser#toc is a function that is available for anyone to use. I'm not sure why we would want it to be a command? You can already just call the function and use the results for anything?

[lervag]

Are you still working on this/interested in following it up?

[DockterTeagle]

oh yeah sorry i was digging through trouble's code but found it hard to read, was waiting for folke to become active again so I could ask him how it was done. Then got distracted by other things. I think I might be able to ,for my own purposes, pipe the output of TOC to trouble but I havent used LaTeX in awhile.

[DockterTeagle]

also I was on a cruise so I didn't have internet for like 10 days

[lervag]

No problem; I'll leave this open for some more time, in case you should want to continue the work.

[DockterTeagle]

so my goal is to get it like trouble, where it should jump on cursor over. this might be an old question but why isnt loclist used for TOC? I have a few days to work on this before uni starts, and would like to try and make some progress on this.

[lervag]

so my goal is to get it like trouble, where it should jump on cursor over.

I'm not sure what that means, sorry.

this might be an old question but why isnt loclist used for TOC?

I don't think it ever came up, to be honest. Feel free to open a feature request. I don't think it would be too hard to use the loclist (or quickfix list, for that matter) for the TOC.

I have a few days to work on this before uni starts, and would like to try and make some progress on this.

Cool! I'll try (but can't guarantee) to be fast at replying to your questions.

[DockterTeagle]

by "get it like trouble" I am referring to the trouble.nvim plugin. my inital goal(before even opening the discussion post) was to have better integration with it. If loclist is used this goal of trouble integration/likeness would be trivial to implement to the point of where it could just be an autocmd on the user side. That is, when LocList is opened, use Trouble. I will look into implementing this as part of this PR.
Additionally I came to the realization that nui.nvim is a tad overkill for this purpose. As that plugin to me seems to be for drawing new things.

[lervag]

by "get it like trouble" I am referring to the trouble.nvim plugin.

Ah, ok!

my inital goal(before even opening the discussion post) was to have better integration with it. If loclist is used this goal of trouble integration/likeness would be trivial to implement to the point of where it could just be an autocmd on the user side.

I see. Well, then I think this seems like a good approach.

Now, the main difference between the loclist and the quickfix list is that the loclist is local to each window, whereas there is just a single (active) quickfix list. I think you are right that it makes sense to use the loclist in this case.

That is, when LocList is opened, use Trouble. I will look into implementing this as part of this PR.

Ok, cool! I think a first step would be to create a function that fills the loclist based on toc entries. Something like this placed in autoload/vimtex/toc.vim:

function! vimtex#toc#loclist() abort
  if !has_key(b:vimtex, 'toc') | return | endif

  let l:entries = vimtex#toc#get_entries()

  " prepare for setloclist here
  let l:prepared = ...

  call setloclist(0, l:prepared, ...)
endfunction

Additionally I came to the realization that nui.nvim is a tad overkill for this purpose. As that plugin to me seems to be for drawing new things.

Yes, I think you are right here.