# How to use Xindy with MiKTeX?

As probably widely is known, the indexing tool Xindy is not included in the TeX distribution MiKTeX. Because MakeIndex does not work well with Unicode, but Xindy does, I therefore have a question:

Could Xindy installed by hand, and, if yes, how could this be done?

-
As I remember was there a version of xindy for windows. Do you know what has happend with this version? –  Kurt Mar 1 '13 at 3:11
I never heard of another one than this/these version/s in my answer. –  Speravir Mar 1 '13 at 3:41

Yes, it is possible:

First a remark: There’s already a series of postings to LaTeX-Community.org – see Installing Xindy in MikteX and finally Xindy for MiKTeX, but you will see there some issues: First, the user “lartkma” provided some files, which were uploaded to Megaupload.com, but this service is down for known reasons (see Megaupload legal case on Wikipedia). Second, I strongly discourage his advice to install Xindy into the main MiKTeX installation path. I wrote about this in my answer to Purpose of local texmf trees.
But in the end all following instructions are still derived from lartkma’s work.

Prerequisite: You need a Perl interpreter – you need it anyway for the Perl scripts in MiKTeX, cf. my answer to MiKTeX and Perl scripts for advices.

If Perl is properly installed, follow the directions!

1. If you didn’t already have created a local texmf path, do it now. See Create a local texmf tree in MiKTeX.

For Xindy you will need this structure:

<localtexmf>
|
|--bin
|
|--doc
|   |
|   +--xindy
|
|--scripts
|     |
|     +--xindy
|
+--xindy
|
+--modules


Don’t forget to add the bin subfolder to the PATH environment variable, that’s important!

2. Download the Xindy binary and all other essential or related stuff. You have two choices, in both cases the directory structure is different from our needs:

3. Extract all files into a temporary folder. You need a program, which can unpack XZ files (and also TAR, but that’s common). My suggestion is 7-Zip or PeaZip. Then move all files in this manner:

• If you took the W32TeX version: All contents of the bin folder go into <localtexmf>\bin, all contents of share\texmf\doc go into <localtexmf>\doc and so on for the others.

• If you took the TeX Live version: You don’t need at all the tlpkg subfolders. All contents of the bin\win32 folder go into <localtexmf>\bin, all contents of texmf\doc\xindy go into <localtexmf>\doc\xindy – you don’t need the man subfolder – and so on for the others.

• You do not need to move xindy.exe and texindy.exe (confer item 5 below).

4. The file xindy.pl under <localtexmf>\scripts\xindy must be changed. Open it with a text-editor, one with syntax highlighting is highly recommended, and search for

in the W32TeX version:

if ( $is_TL ) { # TeX Live$modules_dir = Cwd::realpath("$cmd_dir/../../xindy/modules"); die "$cmd: Cannot locate xindy modules directory"  unless -d $modules_dir; if ($is_w32 ) {
$cmd_dir = "$cmd_dir/../../../../bin";


The last line is different in TeX Live:

        $cmd_dir = "$cmd_dir/../../../bin/win32";


No matter which version you chose, this line must be changed to

        $cmd_dir = "$cmd_dir/../../bin";


(only two times ../) and this must be controlled and most likely changed on every update. If you decided for a different folder structure, you have to adapt this to your situation!

5. If you’ve transferred xindy.exe and texindy.exe into <localtexmf>\bin, delete them or rename them by adding a second file extension like .bin or .bak to make them inactive.
In an older version of this tutorial I described here a different approach, which does not work for me anymore. I cannot tell, if this is due to changes or a bug in the executables. The new approach should be much more independent from the exe wrappers.

(xindy.mem, xindy-lisp.exe and the DLL files are needed. I cannot tell anything about tex2xindy.exe – if it still works as executable, and if not how to change it to a batch call. What it should do read in Xindy FAQ: What is tex2xindy ?)

Still in the binaries folder create two empty text files with the names xindy.bat and texindy.bat. If you like this more, you can also choose .cmd as file extension, but the filenames must not be changed!

Copy the following lines into xindy.bat and adjust the script path to your settings:

@echo off
set ScriptPath=<localtexmf>\scripts\xindy
perl %ScriptPath%\xindy.pl %*


For texindy.bat the content must be slightly different, of course:

@echo off
set ScriptPath=<localtexmf>\scripts\xindy
perl %ScriptPath%\texindy.pl %*


BTW The second and third line could be merged in both cases, but in my opinion the above version is far more readable.

If you use the default text editor Notepad, in the save dialogue make sure, that you do not save to a file with TXT extension: Save with double quotes "xindy.bat".

6. Refresh your filename data base (FNDB). How to do, is (for instance) also described in Create a local texmf tree in MiKTeX.

7. In your favorite TeX editor you perhaps need to add a call to Xindy. Because this is different for every editor, I cannot write anything about this here.

Happy Indexing!

Here two test cases, in your favorite task manager you will see the execution of perl.exe and xindy-lisp.exe:

• Creating an index:

For convenience I used the package imakeidx, because with the option xindy you get there an automatic call to Xindy (actually it’s texindy!) without any configuration, but for this you must first add the switch --enable-write18 to the call of pdflatex (or the alias --shell-escape).
Note, with texifyit’s a bit different: --tex-option="--enable-write18".

\documentclass{article}
\usepackage[latin,english]{babel} % needed for "blindtext",
% "english" is the active language
\usepackage{blindtext,lipsum,kantlipsum}

\usepackage[xindy]{imakeidx}
\makeindex[columns=1]

\begin{document}

\section*{Package \texttt{blindtext}}

\subsection*{English blindtext}\index{blindtext (package)!english}
%%% see below before section "kantlipsum" for
%%% \index{blindtext (package)!english|seealso{kantlipsum}}
\blindtext[1]

\subsection*{Latin blindtext}\index{blindtext (package)!latin}
%%% see below before section "kantlipsum" for
%%% \index{blindtext (package)!latin|seealso{lipsum}}
{\selectlanguage{latin}% note the grouping
\blindtext[1]}

\newpage

\index{blindtext (package)!english|seealso{kantlipsum}}
\index{blindtext (package)!latin|seealso{lipsum}}

\section*{Package \texttt{kantlipsum}}\index{kantlipsum}
%%% see below before "\printindex" for
%%% \index{kantlipsum|seealso{blindtext (package) with english option}}
\kant[123]

\section*{Package \texttt{lipsum}}\index{lipsum}
%%% see below before "\printindex" for
%%% \index{lipsum|seealso{blindtext (package) with latin option}}
{\selectlanguage{latin}% actually not needed here
\lipsum[123]}% note the grouping again

\newpage

\index{kantlipsum|seealso{blindtext (package) with english option}}
\index{lipsum|seealso{blindtext (package) with latin option}}

\printindex

\end{document}

• Creating a glossary with package glossaries:

testfile.tex:

\documentclass{article}

\usepackage[xindy]{glossaries}
\makeglossaries

\newglossaryentry{gloss}{
name=glossaries,
description=A package for generating glossaries in many styles
}

\begin{document}

\texttt{\gls{gloss}} is a great package!

\printglossaries
\end{document}


After one latex compilation, run makeglossaries testfile on command line. With options and filename above this will in background make a call of

xindy -L english -I xindy -M "testfile" -t "testfile.glg" -o "testfile.gls" "testfile.glo"

After a second latex run you should see the result. For other settings you must read the documentation of glossaries.

-
@Qrrbrbirlbel: Adding the bin subfolder to the system path is mentioned above. For the other issue I can only assume, that you have a different directory structure and hence have to edit xindy.plin another way. Or you've forgotten to add %userprofile%\localtexmf to the MiKTeX roots. Or it’s a user right issue, where I can’t help at all. Or … no , no more ideas. –  Speravir Oct 15 '12 at 15:00
I guess, this is a “space in path” problem. But still, when I call perl "C:\Users\<username in 8.3>\localtexmf\scripts\xindy\xindy.pl" xindy.idx, I get: XINDY:STARTUP: keyword arguments in (:IDXSTYLE :RAWINDEX "A0OuxZfRbA" :OUTPUT "xindy.ind" :LOGFILE "nul") should occur pairwise. (Moving localtexmf to a no-space path didn't help either.) Update: texindy.pl works! texindy.exe still doesn't fails to find script. I will invest further research in all those pahts. –  Qrrbrbirlbel Oct 15 '12 at 15:57
With the example I’ve given? But this seems to be beyond my horizon. Perhaps an own question? –  Speravir Oct 15 '12 at 16:08
Yes. Doesn't texindy start xindy on its own? Anyway, first job is getting the .exe to work … I probably won't invest any time now because I currently do not work on a document that requires a comprehensive index. –  Qrrbrbirlbel Oct 15 '12 at 16:17
@Speravir: Works like a charm for me. I followed the instructions literally, and used C:\localtexmf for a local texmf tree in MiKTeX. Thank you! –  nnunes Oct 29 '12 at 8:57
I cannot recommend this installation: It installs deprecated versions of xindy and Perl. When you want to perform a xindy update, you must very probably install a full Perl distribution anyway.
@Bernard Misplaced comment, I guess. It works fine with the binary folder directly below LocalTeXMF, but I think you can put it in an additional miktex as well, as long as the system path points to this. Putting it straight in first sublevel is simpler in my eyes. To texmf.cnf: In TeX Live this file is found directly in first level, and I did so. For makeindex4 read dokumentation, I could not tell anything more. –  Speravir Jul 16 '13 at 21:29