#35 Document texindy behavior for macros and TeX special chars

[Joachim Schrod]

Add to the documentation how texindy handles TeX macros
and special chars, and why it does that.

As an example, take the attached LaTeX idx file (by
courtesy of Lars Madsen). My email explanation of
texindy's behavior might be a start for that documentation:

-----

\&, \$, and \# are mapped to &, $, and #, when the TeX
macros are thrown out from the key. Mapped here really
means `made identical', they get to be the same sort
key. That's supposed to be the `right thing' because
these characters are non-sensical in an index key with
(La)TeX markup.

$ in an index key is ignored, to support math material
in an index key. That means that \index{$@\$}
effectively has an empty index key. That is the reason
why $ and \$ are merged in two different entries; these
are the entries with the empty key and with the key
`$'. If you would have an additional entry
\index{\Prog}, it would be merged to the $ entry,
because it also effectively has an empty key. (The
problem with \Prog is described in the LaTeX Companion.)

This behavior is in so far intentional, as it trys to
cater for typical markup in LaTeX index keys. In fact,
one has to think if ignoring # and & in a LaTeX index
key would not be the right thing to do as well.

If one doesn't want this behavior, one has to use xindy
instead of texindy and construct the document's xindy
style oneself. Or, without having it tried, one should
be able to copy tex.xdy to the document's directory and
change it to get a different markup handling. The
module search algorithm should pick up a local version
first, before it looks in the system directory -- but I
have to admit that I didn't try that out myself. But
don't tell anybody that I recommended that hack. ;-)

-----

Of course, this also is influenced by the problem that
it's not easy to specify one's own merge-rules when one
uses texindy, see the respective ticket.

[Joachim Schrod]

index files with TeX special chars and TeX macros