How to use Xindy with MiKTeX?

Question

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?

Answer 1

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 based on this work.}

Prerequisite: You need a Perl interpreter, it’s by the way useful also for other scripts already included in MiKTeX distribution. If you have no idea, I suggest you to install ActivePerl by ActiveState. There’s a “Free Community Edition” installer. It installs the Perl interpreter, adds itself to the system PATH environment variable and links the file extension .pl to the interpreter binary perl.exe. For advanced users there’s also Strawberry Perl for Windows, which enhances upon installation the PATH variable, but doesn’t add the link between extension and interpreter (it could be done manually, see How do I make my Perl scripts act like normal programs on Windows?) – this is not necessary for functioning, but is more comfortable for most users.

Now, 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:

   • Use the package provided by W32TeX: http://mirror.ctan.org/systems/win32/w32tex/xindy-w32.tar.xz – this file contains all you need.

     ^{Back in the past the W32TeX mirrors on CTAN often were terribly outdated. If you suspect, it is so again, you can get a mirror with recent file versions directly on W32TeX website.}

   • Use the TeX Live version (in fact, all the windows binaries, not just for Xindy, come from W32TeX) – you need to download three files:
     http://mirror.ctan.org/systems/texlive/tlnet/archive/xindy.doc.tar.xz
     http://mirror.ctan.org/systems/texlive/tlnet/archive/xindy.tar.xz
     http://mirror.ctan.org/systems/texlive/tlnet/archive/xindy.win32.tar.xz

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.

   • 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.

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.

5. Coming from TeX Live or W32TeX Xindy needs a configuration file texmf.cnf directly under <localtexmf> (MiKTeX stores its configuration in INI files and in the registry). Copy the following lines into a new text file and adjust the directory paths to your settings (as you can see, use slashes instead of backslashes). Here <localtexmf> is C:/LaTeX/LocalTeXMF.

   TEXMFCONFIG=C:/Users/Speravir/AppData/Roaming/MiKTeX/2.9
   % i.e. %APPDATA%\MiKTeX\2.9
   TEXMFVAR=C:/Users/Speravir/AppData/Local/MiKTeX/2.9
   % i.e. %LOCALAPPDATA%\MiKTeX\2.9
   TEXMFSYSCONFIG=C:/ProgramData/MiKTeX/2.9
   % i.e. %ALLUSERSPROFILE%\MiKTeX\2.9
   TEXMFSYSVAR=C:/ProgramData/MiKTeX/2.9
   % i.e. %ALLUSERSPROFILE%\MiKTeX\2.9
   TEXMFMAIN=C:/LaTeX/MiKTeX
   TEXMFLOCAL=C:/LaTeX/LocalTeXMF
   TEXMF={$TEXMFCONFIG,$TEXMFVAR,$TEXMFLOCAL,$TEXMFSYSCONFIG,$TEXMFSYSVAR,$TEXMFMAIN}
   TEXMFSCRIPTS=$TEXMF/scripts/{$engine,$progname,}//
   TEXFONTMAPS=.;$TEXMF/fonts/map/{$progname,pdftex,dvipdfm,dvips,}//
   

   ^{For the environment variables cf. for instance Windows Environment Variables on SS64.com.}

   In the save dialogue make sure, that you do not save to a file with TXT extension: Save with double quotes "texmf.cnf".

   Note: For Xindy it would probably enough to use a file with these lines:

   TEXMF=C:/LaTeX/LocalTeXMF
   TEXMFSCRIPTS=$TEXMF/scripts/xindy
   

   but I thought, it is better to provide a file with all TeX related variables for possible future uses.

   ^{See a full texmf.cnf with a lot of explaining comments under http://mirror.ctan.org/systems/luatex/base/source/texk/kpathsea/texmf.cnf (for TeX Live).}

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 it’s different for every editor, I cannot write anything about this here.

Happy Indexing!

Here a test case; for convenience I used the package imakeidx, where with the option xindy you get an automatic call to Xindy without any configuration, but then you must first add the switch --enable-write18 to the call of pdflatex (or the alias --shell-escape).
_{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}

In your favorite task manager you will see the execution of texindy.exe (that’s, what actually is called by imakeidx) and perl.exe.

Answer 2

There has been made a very easy xindy installer for windows.

Look at the wiki entry here:

http://en.wikibooks.org/w/index.php?title=LaTeX/Glossary&stable=0#Compile_glossary_-_In_windows_with_texmaker