GNOME Bugzilla – Bug 670973
1.8.0 generates non-compilable latex output
Last modified: 2012-05-19 12:26:23 UTC
Created attachment 208581 [details] generated latex with doxygen 1.8.0 Hello, The documentation of the hwloc project doesn't compile anymore when upgrading from doxygen 1.7.6.1 to 1.8.0. It generates this latex code: \end{DoxyItemize}\/}\/} [...] {\itshape {\itshape \/}\/} Both of these cause the following latex error: ! You can't use `\/' in vertical mode. l.39 \end{DoxyItemize}\/ }\/} Just removing '\/' fixes the compile failure. But the output isn't perfect (we'll discuss that later once the failure is fixed). It looks like this is related to some of our doxygen code above: <dt>HWLOC_<type>_DISTANCES=index,...:X*Y</dt> <dt>HWLOC_<type>_DISTANCES=begin-end:X*Y*Z</dt> <dt>HWLOC_<type>_DISTANCES=index,...:distance,...</dt> <dd>... It looks like doxygen 1.8.0 doesn't like having those < > there. But if only one of these <dt> lines contains such XML entities, things seem to build fine (and output is ok). More strange: * if I remove all < and keep all > (or the contrary), build/output OK * if I keep one < and one > on different lines, build breaks. Our doxy file is https://svn.open-mpi.org/trac/hwloc/browser/trunk/doc/hwloc.doxy (the code that causes the error is soon above "\page cpu_mem_bind") Doxygen config https://svn.open-mpi.org/trac/hwloc/browser/trunk/doc/doxygen.cfg I am attaching the doxygen-generated latex for this part of the documentation. The error occurs at lines 39 and 43. Brice
Hi Brice, I haven't been able to reproduce the problem given the info above. Can you please attach a self-contained example (source+config file in a tar or zip) that allows me to reproduce the problem?
Created attachment 208921 [details] tarball to reproduce the problem I reduced the hwloc doxy file to make it more easy to debug. I could likely reduce it even more if needed. There's a README in this tarball to explain how to reproduce.
Ok, I'm able to reproduce the problem now. It is related to the special treatment of * and _ with Markdown formatting i.e. setting MARKDOWN_SUPPORT to NO will solve the issue. Also escaping the *'s and _'s or wrapping them in `..` will fix it, i.e.: --------------------------------- <dl> <dt>HWLOC_\<type\>\_DISTANCES=index,...:`X*Y`</dt> <dt>HWLOC_\<type\>\_DISTANCES=begin-end:`X*Y*Z`</dt> <dt>HWLOC_\<type\>\_DISTANCES=index,...:distance,...</dt> <dd>sets a distance matrix for objects of the given type and physical indexes. The type should be given as its case-sensitive stringified value (e.g. `NUMANode`, `Socket`, `Cache`, `Core`, `PU`). If another distance matrix already exists for the given type, either because the user specified it or because the OS offers it, it will be replaced by the given one. If the variable value is <tt>none</tt>, the existing distance matrix for the given type is removed. Otherwise, the variable value first consists in a list of physical indexes that may be specified as a comma-separated list (e.g. `0,2,4,1,3,5`) or as a range of consecutive indexes (`0-5`). It is followed by a colon and the corresponding distances: <ul> <li>If `X*Y` is given, X groups of Y close objects are specified.</li> <li>If `X*Y*Z` is given, X groups of Y groups of Z close objects are specified <li>Otherwise, the comma-separated list of distances should be given. If N objects are considered, the `i*N+j`-th value gives the distance from the i-th object to the j-th object. These distance values must use a dot as a decimal separator.</li> </ul> Note that distances are ignored in multi-node topologies. </dd> </dl> --------------------------------- I'll see if I can make Markdown processing more robust against such (ab)use.
Thanks for all the details. I am disabling MARKDOWN_SUPPORT for now, indeed that works well. Escaping doesn't look OK because it breaks the output with 1.7.x.
This bug was previously marked ASSIGNED, which means it should be fixed in doxygen version 1.8.1. Please verify if this is indeed the case. Reopen the bug if you think it is not fixed and please include any additional information that you think can be relevant.