Bad LaTeX output - Githubissues

tonycpsu commented 13 years ago

Breathe+Sphinx seems to be creating bad LaTeX output for me.

I'm using Breathe 0.7.0 and Sphinx 1.0.8 on a Mac with MacTeX 2010. I've run Doxygen to generate the XML, and I can generate HTML output fine, but when I try to go Sphinx -> LaTeX -> PDF, I get the following error:

  ! Missing \endgroup inserted.
  <inserted text> 
                  \endgroup 
  l.283 }]
           \leavevmode\phantomsection\label{index:}
  ? 
  ! Emergency stop.
  <inserted text> 
                  \endgroup 
  l.283 }]
           \leavevmode\phantomsection\label{index:}
  !  ==> Fatal error occurred, no output PDF file produced!
  Transcript written on snarf.log.

This is with a very simple .rst file with nothing other than a main header and a doxygenindex:: directive.

The bad section of LaTeX is:

\end{description}                                                                                                                                               
\end{quote}                                                                                                                                                     
\emph{Functions}\begin{quote}                                                                                                                                   
\begin{description}                                                                                                                                             
\item[{\phantomsection\label{index:project0alert_8h_1a2908a90fcf870534b032701b20b78aea}\phantomsection\label{index:project0alert_8h_1a2908a90fcf870534b032701b20b78aea}
\begin{DUlineblock}{0em}
\item[] snarf\_alert\_t * \textbf{snarf\_alert\_new}(alert\_severity\_t severity, uint64\_t timestamp)
\end{DUlineblock}                                                                                                                                               
}] \leavevmode\phantomsection\label{index:}

It doesn't like the last line.

There are also a bunch of errors about various labels being multiply defined.

Any idea what's going on? I tried it on my Linux box running the same versions of everything other than Python (2.6 on my Mac, 2.7 on my Linux box) and got the same result.

michaeljones commented 13 years ago

Hi,

Sorry about this and thank you for taking the time to report it.

I can reproduce the issue in the "testsuite". I'm afraid I've not been in the habit of checking the latex output, despite another issue like this not so long ago. I'll endeavour to make sure I'm more careful in the future and hopefully get a fix out for this soon.

I'll let you know how I get on, Michael

tonycpsu commented 13 years ago

No problem! Thanks for getting back to me on the bug report so quickly. In the mean time, is there a prior version of Breathe you can recommend me downgrading to so I can at least get usable LaTeX output?

michaeljones commented 13 years ago

Unfortunately I've just gone back through a few passed commits and can't find anything that is behaving itself. I guess latex support has been sketchy at best. It is possible that something in that works but it is not clear.

I'll try to get this resolved as soon as possible, which probably means tomorrow with a bit of luck (it's now Friday morning over here.)

I'm looking at it now but I'm not too experienced with latex and have to go to work in a few mins! Michael

michaeljones commented 13 years ago

Actually, if you have the git repos and you checkout:

45924eeddaf5f6f2738f611b23f7576e284d22b7

which is before I added support for template declarations above functions then it might be better. It seems latex isn't happy with my choice of how to do that. Not sure what the best approach would be to get around it but I'll take a closer look tomorrow.

michaeljones commented 13 years ago

It being git and all that SHA1 should be sufficient but in case there is any confusion it is the commit with the message:

Merge pull request #39 from sschaetz/master

tonycpsu commented 13 years ago

Yes, that one seems to work just fine for my purposes. I'll be happy to help test out a fix to the current version whenever it's ready.

tonycpsu commented 13 years ago

Well, I did say rolling back to the older version fixed things, but the LaTeX output is a bit screwy, in that functions with more than a few arguments scroll off the right margin of the page with no wrapping of long lines. Is this aesthetic issue something that was fixed in later versions, perhaps in a change I could apply to the version that's at least partially working for me?

michaeljones commented 13 years ago

Hi,

I'm sorry to say I don't think that has been fixed. I'm afraid you seem to be experiencing the troubles of being the first person to really use latex output with Breathe. I can only guess anyone else who has tried has experienced similar things but not reported them unfortunately.

I'm happy to try to work through these with you and generally pay more attention to the latex output but I'm afraid it might be a bumpy road initially.

Cheers for trying it and reporting what you've seen so far, Michael

michaeljones commented 13 years ago

Hi,

I've pushed some changes which might help a little. They allow the successful build of the testsuite to a pdf, something which I'm not sure has been done before embarrassingly.

Looking through the result is seems some of the long function parameter lines do wrap so maybe that will help with your problem, though I don't feel that standard paragraph word wrapping is ideal for parameter lists.

Please let me know if you get a chance to look at it, Michael

tonycpsu commented 13 years ago

Thanks, Michael. The current head builds for me, and the output is much improved, though as you say, paragraph wrapping isn't ideal for code listings. In terms of improving it, it appears to me that the Doxygen XML output isn't retaining any of the original formatting/indentation of the function definitions in the C headers, so you'd probably have to roll your own -- for most folks, simply doing one parameter per line (splitting the definition on commas), indenting each a bit, and putting the whole thing into a LaTeX {verbatim} envrionment would probably suffice. The holy grail would be to get it processed via Sphinx's Pygments support for syntax coloring and so forth, but that's certainly in the "bells and whistles" category.

In any event, I'm happy I can at least use the current release, even if the output isn't perfect.

Out of curiosity, have you ever considered using pygccxml or something along those lines to parse headers directly, bypassing Doxygen? This could potentially have the advantages of removing the dependency on Doxygen (and any backwards-incompatible changes it makes in the future) and also potentially giving Breathe better access to the raw code formatting.

michaeljones commented 13 years ago

Hi,

Thanks for the recommendations, I've made a note to work on the parameter formatting.

I'm not sure what would be gained exactly from the Pygments support as we're not really showing much code just the function declarations and the types of interest should be links anyway (though I forget if this is the case for latex) else putting the types in bold or something similar shouldn't be too hard.

As for pygccxml, a few points (sorry they're so long!):

It is definitely something people ask about and I actually started the project with that in mind to use for the parsing, but it didn't expose any information about the comments (because it reflects the internal state of gcc and gcc ignores the comments on parsing) so we'd have to have put in a huge amount of extra work in to even reach the stage that Doxygen gives us for free. I haven't checked back with the gccxml project for a while so that may have changed but it seems unlikely.
Doxygen is a very stable tool which does an excellent job of providing the required information. I'm not sure that a dependency on gcc is more preferable to that.
I used doxygen initially to get up and going quicker but now I use it because the truth is I'm proud to have built a project that helps bring together two successful established tools.
Finally, I'm very keen that Breathe stays modular enough to accept other back ends, so if someone wants to demonstrate that another source of information is better they're welcome to implement it and I'll make the relevant changes to the overall framework to make it easier for them.

Thanks again for the feedback, Michael

tonycpsu commented 13 years ago

Re: Pygments, I just figured since you get it "for free" in Sphinx, it'd be worth using it to get consistent formatting with code samples from other languages. Your points about Doxygen vs. pygccxml are all valid, and if you can't get at the formatted comments using it, there's no advantage at all over Doxygen.

Thanks again for getting the LaTeX output fixed, and for all the great work you've put into Breathe.

michaeljones commented 13 years ago

Thanks, though I was under the impression the Pygments only did highlighting not reformatting. If it does formatting I'll definitely look into it!

breathe-doc / breathe

Bad LaTeX output #47