Doxygen produces ugly empty space in LaTeX and PDF output because of hypertargets

[heikki-heikkila]

Describe the bug
When doxygen produces LaTeX files, it includes hyperlinks and hypertargets in *.tex files. Occasionally a \Hypertarget command is inserted inside a TeX box, as follows:

\mbox{\Hypertarget{...

By the way, this behaviour apparently has something to do with file https://github.com/doxygen/doxygen/blob/master/src/latexgen.cpp

Occasionally this \mbox is inserted in the main vertical list of TeX typesetting between two heading macros. This is a bug. In the particular case at hand, a file named test_8h.tex (which doxygen produces as output) contains something like this:

\doxysubsubsection{Function Documentation}
\mbox{\Hypertarget{test_8h_a024e8f3ced8cfd2c34f7cfd254093e5e}\label{test_8h_a024e8f3ced8cfd2c34f7cfd254093e5e}}
\index{test.h@{test.h}!example@{example}}
\index{example@{example}!test.h@{test.h}}
\doxyparagraph{\texorpdfstring{example()}{example()}}

Note two headings, \doxysubsubsection and \doxyparagraph, and a \mbox between them. The result, in the main vertical list of TeX, contains, if penalties are excluded:

1. a box for "Function Documentation";
2. vskip to separate heading from the following item (which would often be a paragraph of text);
3. mbox, which is the next item;
4. another vskip to the separate the next heading from the previous item;
5. a box for heading "example()".

In the final output, vskips (2) and (4) are visible after one another. Then the final printable output contains double the amount of normal vertical space between the headings "Function Documentation" and "example()".

This is clearly visible in file refman.pdf, on page 2, between headings 2.1.3 and 2.1.3.1.

Expected behavior
It is expected that hypertargets are adjacent to, or contained in, the relevant TeX vbox and never produce any superfluous empty space in the final LaTeX or PDF document.

Screenshots
None (but see the PDF file)

To Reproduce
This can be reproduced exactly as another issue. See #9028. The same files, Doxyfile and test.h, and the same PDF file, refman.pdf, show also the behaviour described in this issue

Version
Doxygen 1.8.17. Linux 652723cd6b4f 3.10.0-1062.9.1.el7.x86_64

Stack trace

Additional context

[albert-github]

With the current master I see the big gap as well.
When changing the line

\mbox{\Hypertarget{test_8h_a024e8f3ced8cfd2c34f7cfd254093e5e}\label{test_8h_a024e8f3ced8cfd2c34f7cfd254093e5e}}

into

\hypertarget{test_8h_a024e8f3ced8cfd2c34f7cfd254093e5e}{}\label{test_8h_a024e8f3ced8cfd2c34f7cfd254093e5e}

the problem disappears.

We have to see why in this case the \mbox{\Hypertarget construct is used and not the \hypertarget.

Note:

• even when there is a clear test case with another issue please add to the current issue the same test case, as when for some reason the old issue is changed the test case might be less good accessible.

[heikki-heikkila]

OK, the same attachments once again
Doxyfile.txt
test.h.txt
refman.pdf
:

[albert-github]

I did some research and see that the problem is probably introduced with:

Underscores in type or member name cause unwanted hyphenation in PDF output Data Fields (Origin: bugzilla #773231)
i.e. #6093.

So simply removing the \mbox is not be a good idea.

[albert-github]

I've just pushed a proposed patch, pull request #9163

[heikki-heikkila]

I have found a workaround. Please don't take this too seriously. It's a kludge, and it hasn't been tested for any big mass of material. But perhaps it's, for someone, somewhere, better than nothing.

sed -e '
# The purpose of this sed script is to find the following pattern in a LaTeX
# file:

# \doxysubsubsection{ . . .
# \mbox{\Hypertarget{ . . .

# This is a bug in doxygen system: the Hypertarget, in this context, should
# not be enclosed in mbox.
# See https://github.com/doxygen/doxygen/issues/9159.

# the following pattern starts an interesting line; if no match, print
# the line as usual and continue with the next input line
/\\doxysubsubsection/ !{
  p
  d
}
# but otherwise there may be something to do; first print the subsection line
# as usual, and take the next line:
n
# the following pattern means that the doxygen bug did hit; if no match,
# do nothing special
/^\\mbox{\\Hypertarget/ !{
  p # print the second line without significant changes
  d # continue with the next input line
}
# the special case, where we have to fix the LaTeX file: remove mbox
s/\\mbox{\(.*\)}[[:blank:]]*$/\1/
# add some LaTeX comments, for record:
i % FYI: because of the previous heading line, Hypertarget has been fixed
i % by removing a mbox (to undo bug #9159 in doxygen):
# now print the modified text, then to next line
' *.tex

[albert-github]

I think you would be better of trying my patch, so we would also get feedback whether or not there are drawbacks to the patch.
(it looks a big patch but most is just needed for having correct prototypes.)

[kuangchu0]

@albert-github thanks for providing the fix! Is the commit pushed to the master branch? if so, which version of the doxygen is it in ? d054aed

[albert-github]

The proposed patch in #9163 is still open and not merged into master, so also not available in any release.

[kuangchu0]

@albert-github

Thanks for the prompt reply. I am currently facing the following error and wonder if this patch is the right solution for it.

(Just to provide more background. I am currently maintaining a doxgen set up that is working for 1.8.2 but failed with 1.9.0. I have also updated the configuration file with doxygen -u. )

Any suggestion is welcome.

Error Now:

[164]
! Undefined control sequence.
<argument> \Hypertarget 
                        {group__Fields_gab57a385aae42ec900b113a506370193b}\l...
l.406 ...elds_gab57a385aae42ec900b113a506370193b}}
                                                  
? 

error will go away with the following Change :

\mbox{\Hypertarget{group__Fields_gab57a385aae42ec900b113a506370193b}\label{group__Fields_gab57a385aae42ec900b113a506370193b}
------------->                                       
\hypertarget{group__Fields_gab57a385aae42ec900b113a506370193b{}\label{group__Fields_gab57a385aae42ec900b113a506370193b} 

[albert-github]

It is hard to tell whether or not this will go away with the patch. The patch might remove the \mbox but won't change the \Hypertarget into \hypertarget. Seen the nature of the patch it is not likely.

Are you using any other user modifiable files like stylesheets e.g. doxygen.sty?

Note you are going from 1.8.2 to 1.9.0, why 1.9.0 and not to the current version 1.9.4?

[kuangchu0]

@albert-github :
2. yes! I am using a local doxygen.sty. Given I am on 1.9.0, can you recommend a working doxygen.sty that will work without any error? Also, I am using teTeX/2019/. for example, if I directly download the following, I will receive error :

! LaTeX Error: File `longtable_doxygen.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

doxygen.sty

3. i don't maintain the server and 1.9.4 is not yet installed. And I am not sure how hard is it to build my own local 1.9.4. So I am kind of stuck with 1.9.0 along with teTeX/2019/. But I will ask around if that's a possibility.

[albert-github]

2. the shown doxygen.sty is identical to the official doxygen.sty for the 1.9.0 version. Looks a bit like the file longtable_doxygen.sty has been removed after the doxygen run from the latex directory. Best is:
   • to attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.
3. building doxygen, this is not that difficult, see for instructions e.g. https://www.doxygen.nl/manual/install.html

[albert-github]

An alternative code update has been made in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.9.7.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).