Making glossaries and indices when installing LaTeX packages from source
Installing LaTeX packages and compiling their documentation from source has some tricks which often don’t get documented. I mean, they are documented somewhere but not when and where you need them.
So here is the process.
(1) You get your ‘source’ file, possibly a something like packagename.source.zip, containing packagename.dtx and package.ins.
(2) You LaTeX the ins file and you get the sty file (and maybe some ancillary files) — the actual LaTeX macros. You copy this file/these files to somewhere like \home\username\texmf\tex\latex\packagename\.
(3) You run mktexlsr or texhash or whatever and you can use the macros. Great.
(4) You LaTeX the dtx file to get the documentation. It produces a dvi or pdf file (depending on whether you run latex or pdflatex) plus maybe an idx and maybe a glo file. What the hell?
(5) You take a guess and run makeindex packagename and it seems to work. If you’re like me until recently, you’ve got no idea what to do with the glo file and you leave it for now.
(6) You run LaTeX on the dtx and and yes indeed it compiles but the index is all overlapped with itself and weird looking and you still don’t know what to do with the glossary.
OK. this is what I found I ought to do. Apologies if it is obvious to you, it is not obvious to me.
After step (4) above, you type this:
makeindex -s gind.ist packagename.idx
makeindex -s gglo.ist -o packagename.gls packagename.glo
THEN latex it again a few times.
What the -s flag does is tell makeindex what index style (ist) file to use. In the second call, since it defaults to looking for index files, you have to tell it (a) to use the gglo.ist style since it is formatting a glossary and (b) pull in the glo file and output a gls file.
Any dtx file that has a glossary and/or an index should be processed in this way, but most of them don’t actually tell you.