htlatex leaves undefined reference (“??” link) but pdflatex produces correct output

Question

We have a large document that runs through pdflatex and through htlatex. The pdflatex output is fully ok. The htlatex output is also ok (it contains all images etc.) except that for some cross-references it will not create a link, but just a "??" as if the reference were undefined (but it cannot be undefined in the tex source, because the link/crossref is correctly inserted in the PDF).

It only happens for this one document, so I assume there is some minor problem somewhere in it's 300 pages, but I really don't know where to start looking. (Even it's english translation works, and that's supposed to contain exactly the same references named exactly the same!)

So, is there a known pattern when htlatex would not resolve a crossreference but pdflatex would?

System: MikTeX 2.6 on Windows XP

pdfLaTex command(s) used:

pdflatex -output-format=pdf -interaction=nonstopmode myfile.tex
pdflatex -output-format=pdf -interaction=nonstopmode myfile.tex
// Note that the references already work after two pdflatex runs
pdflatex -output-format=pdf -interaction=nonstopmode myfile.tex

htlatex command used: (Note that \" is to make htlatex.exe of MikTeX happy)

htlatex.exe \"myfile.tex\" \"html,5\" \"\" \"\" \"-interaction=nonstopmode\"

---

Edit: While the command below still appears in the document, further experiments have shown that directly using \namref or \autoref also just yields ??.

The links are all created the same. They use a custom macro named \KShortLink that inserts a formatted link. The macro definition looks like this:

\newcommand{\KShortLink}[1]{\emph{``\nameref{#1}''} (\KLngChapName\ref{#1}\KLngOnPage\pageref{#1})}

where the other part involved build up like this:

\newcommand{\KTranslateTable}[3]{
    \iflanguage{ngerman}{
        \newcommand{#1}{#2}
    }{}
    \iflanguage{english}{
        \newcommand{#1}{#3}
    }{}
}

\KTranslateTable{\KLngChapName}{Kapitel\ }{Chapter\ }
\KTranslateTable{\KLngOnPage}{\ auf Seite\ }{\ on page\ }

Interestingly the english version appears to work while the german version just creates ??.

Answer 1

The key to finding the problem was to systematically reduce the problematic document (which took me about 3 1/2 hours after already spending 2 hours trying to find out what part of the document to start at - hence why I asked the question before continuing to dissect my problem.)

It turns out that htlatex (or tex4ht or latex itself, whatever) completely falls over if you specify any \hypertarget with a label that contains non-ASCII characters! (Someone used an Umlaut - ü - in the label.) pdfLaTeX, however, is just fine with labels containing Umlauts!

What's interesting is that not only the link with the invalid character is messed up, but also arbitrary other links. (That why I never found the label in the first place - because it destroyed 80% of all links in the generated HTML files.)

A small example that will produce a correct PDF with pdfLaTeX but will mess up the links with htlatex:

\documentclass[fontsize=12pt,paper=a4]{scrbook}
\usepackage[T1]{fontenc}
\usepackage[latin10]{inputenc}
\usepackage[ngerman]{babel}
\usepackage{longtable}
\usepackage{hyperref}

\begin{document}
\chapter{One}
\hypertarget{labelOne}{Link Text for One}

Some Text ...

\section{Sec X}
\hypertarget{labelTwö}{Link Text Two}

Lorem Ipsum etc.

\section{The Links}

First \hyperlink{labelTwö}{this links to link number Two} and then 
second \hyperlink{labelOne}{this link to One}.
Done.

\end{document}

The logging output of this does contain two ! LaTeX Error: Missing \begin{document} in '. messages. There's also a ! Missing \endcsname inserted. just before the wrong label.