Documentation could be more thorough as regards how to make glossaries

Description

Disclaimer: I've been away from LaTeX since late 2018, which a long long loooong time for LaTeX, in my experience, so I'm a bit rustly and might be missing something obvious. So here I'm playing the role of the beginner, maybe, but I rember that VimTeX was, and I know still is, a great (the greatest imho) plugin for LaTeX that can even make novices start using it. So I hope the feedback I'm giving can help give an improvement in this respect.

In :h vimtex, makeindex is mentioned twice, fundamentally in identical texts:

latexmk: http://users.phys.psu.edu/~collins/software/latexmk-jcc "a perl script for running LaTeX the correct number of times to resolve cross references, etc; it also runs auxiliary programs (bibtex, makeindex if necessary, and dvips and/or a previewer as requested).

From this I'd deduce that that makeindex runs out of the box, but apparently, if I don't manually run makeindex -s main.ist -o main.gls main.glo , I get has been referenced but does not exist, replaced by a fixed one for entries I've added via newglossaryentry.

Since the bibliography handling was automatic (so, in practice, I didn't need to look up for VimTeX documentation at all), I'd have expected that also glossay handling was automatic. If it is not, then maybe the doc could tell something more.

Steps to reproduce

In short, I've put an example from Overleaf in a main.tex file and started VimTeX on it.

As far as the vimrc is concerned, I'm pretty confident making it minimal with respect to non-VimTeX stuff is overkill, so I've just make sure to not define g:vimtex_compiler_latexmk. The rest is just a few options which are unrelated to the issue:

let g:vimtex_delim_stopline = 1000
let g:vimtex_view_general_viewer = 'zathura'
let g:vimtex_view_method = "zathura"
let g:vimtex_fold_enabled = 1
let g:vimtex_fold_manual = 1
let g:vimtex_quickfix_method = 'pplatex'
let g:vimtex_quickfix_autoclose_after_keystrokes = 5
let g:tex_flavor = 'latex' " avoid some skinny *.tex file to be interpreted as plaintex files

Expected behavior

From the doc, I'd have expected that executing makeindex ... was automatic.

Actual behavior

The compilation results in main.tex|| No file main.gls.. Manually executing makeindex -s main.ist -o main.gls main.glo makes all work.

Do you use a latexmkrc file?

No (I use it, but I've deleted it while doing repro steps from Overleaf example.)

VimtexInfo

System info:
  OS: Arch Linux
  Vim version: VIM 9.0 (1-1046)
  Has clientserver: true
  Servername: VIM1

VimTeX project: main
  base: main.tex
  root: /home/enrico/deleteme
  tex: /home/enrico/deleteme/main.tex
  main parser: current file verified
  document class: article
  packages: amsbsy amsgen amsmath amsopn amstext datatool-base datatool-fp defpattern etoolbox fp fp-addons fp-basic fp-eqn fp-eval fp-exp fp-pas fp-random fp-snap fp-trigo fp-upn glossaries glossaries-compatible-307 glossary-hypernav glossary-list glossary-long glossary-super glossary-tree ifthen inputenc longtable mfirstuc substr supertabular textcase xfor xkeyval
  compiler: latexmk
    engine: -pdf
    options:
      -shell-escape
      -verbose
      -synctex=1
      -interaction=nonstopmode
    callback: 1
    continuous: 1
    executable: latexmk
    job: 
      jobid: process 207040 run
      output: /tmp/vlk67Xt/1
      cmd: max_print_line=2000 latexmk -shell-escape -verbose -synctex=1 -interaction=nonstopmode -pdf -pvc -view=none -e '$compiling_cmd = ($compiling_cmd ? $compiling_cmd . " ; " : "") . "echo vimtex_compiler_callback_compiling"' -e '$success_cmd = ($success_cmd ? $success_cmd . " ; " : "") . "echo vimtex_compiler_callback_success"' -e '$failure_cmd = ($failure_cmd ? $failure_cmd . " ; " : "") . "echo vimtex_compiler_callback_failure"' 'main.tex'
      pid: 207040
  viewer: Zathura
    xwin id: 33554435
    cmd_start: zathura  -x "/usr/bin/vim -T dumb --not-a-term -n -c \"VimtexInverseSearch %{line} '%{input}'\"" --synctex-forward 41:1:'/home/enrico/deleteme/main.tex' 'main.pdf'&
  qf method: LaTeX logfile using pplatex

So I hope the feedback I'm giving can help give an improvement in this respect.

Thanks; I appreciate this kind of feedback, and I think the worst case consequence is that you learn something. Often I learn something as well, and sometimes we end up improving VimTeX either functionally or e.g. in documentation. :)

In :h vimtex, makeindex is mentioned twice, fundamentally in identical texts:

latexmk: http://users.phys.psu.edu/~collins/software/latexmk-jcc "a perl script for running LaTeX the correct number of times to resolve cross references, etc; it also runs auxiliary programs (bibtex, makeindex if necessary, and dvips and/or a previewer as requested).

Ah, yes; notice that makeindex is mentioned in a text directly quoted from latexmks own home page.

From this I'd deduce that that makeindex runs out of the box, but apparently, if I don't manually run makeindex -s main.ist -o main.gls main.glo , I get has been referenced but does not exist, replaced by a fixed one for entries I've added via newglossaryentry.

I can see where you are coming from and I agree that latexmk may have misleading documentation here. I find that I use the following in my own .latexmkrc file (see all of it here:

push @generated_exts, "nlo";
push @generated_exts, "nls";
# ....

add_cus_dep('nlo', 'nls', 0, 'nlo2nls');
sub nlo2nls {
  system("makeindex $_[0].nlo -s nomencl.ist -o $_[0].nls -t $_[0].nlg" );
}

This is for nomenclatures, but as you see, it is clearly related to your issue.

Since the bibliography handling was automatic (so, in practice, I didn't need to look up for VimTeX documentation at all), I'd have expected that also glossay handling was automatic. If it is not, then maybe the doc could tell something more.

Ok, so: latexmk is responsible for compilation here (or, through user configuration, other engines). And I believe it is important that users actually know at least something about how compilation of LaTeX documents work and in turn how latexmk (or their chosen engine) works. I'm not sure exactly how to properly handle this within the VimTeX documentation. We can't explain everything there either.

let g:vimtex_delim_stopline = 1000
let g:vimtex_view_general_viewer = 'zathura'
let g:vimtex_view_method = "zathura"
let g:vimtex_fold_enabled = 1
let g:vimtex_fold_manual = 1
let g:vimtex_quickfix_method = 'pplatex'
let g:vimtex_quickfix_autoclose_after_keystrokes = 5
let g:tex_flavor = 'latex' " avoid some skinny *.tex file to be interpreted as plaintex files

Two comments:

You don't need g:vimtex_view_general_viewer, since you are using let g:vimtex_view_method = 'zathura'.
You don't need g:tex_flavor, see :help vimtex-tex-flavor.

Expected behavior

From the doc, I'd have expected that executing makeindex ... was automatic.

Perhaps a solution would be to remove the parantheses where makeindex is mentioned?

I see that in your .latexmkrc snippet some of the extensions obviously refer to nomenclature, so changing the to those referring to glossary was kind of obvious. However, one of them, nomencl.ist suggests that we don't want it to clash with other *.ist files, so I would have thought that I would name it something along the lines of glossary.ist, but the point is that the file is generated upon running pdflatex on my main.tex files, and it is named main.ist, so I changed your snippet to this

push @generated_exts, "glo";
push @generated_exts, "gls";
push @generated_exts, "glg";

add_cus_dep('glo', 'gls', 0, 'glo2gls');
sub glo2gls {
  system("makeindex $_[0].glo -s $_[0].ist -o $_[0].gls -t $_[0].glg" );
}

And it works. But... am I doing something that will bite me when I'll add stuff like nomenclature, index, and others? Or will pdflatex generate main.ist with all that the several runs of makeindex will all need?

Perhaps a solution would be to remove the parantheses where makeindex is mentioned?

Yep, maybe it's a good idea.

Two comments:

Thanks! :)

I see that in your .latexmkrc snippet some of the extensions obviously refer to nomenclature, so changing the to those referring to glossary was kind of obvious. However, one of them, nomencl.ist suggests that we don't want it to clash with other *.ist files, so I would have thought that I would name it something along the lines of glossary.ist, but the point is that the file is generated upon running pdflatex on my main.tex files, and it is named main.ist, so I changed your snippet to this …

Yes, that seems safe - and I'm glad to hear it works. I have to admit I don't understand these things as well as I should, but I believe you will find a lot of information on these topics if you search for e.g. latexmk and makeindex and similar on the web.

And it works. But... am I doing something that will bite me when I'll add stuff like nomenclature, index, and others? Or will pdflatex generate main.ist with all that the several runs of makeindex will all need?

I think this is safe. But again, I believe you will also find a lot of relevant information online for these things if you search specifically for latexmk and glossaries/nomenclatures, etc.

Perhaps a solution would be to remove the parantheses where makeindex is mentioned?

Yep, maybe it's a good idea.

I'll do that, then.

lervag / vimtex