[Doxygen-users] RTF generation problems and more

[Hood, E. <eh...@ti...>]

I checked the list archive (which by the way has no searching capabilities
due to a config error) and noticed the someone else posted problems
with loading the RTF output into Word 2000.

I am trying out v1.2.11.1 on Red Hat Linux 6.1 (or maybe 6.2).

I am not an RTF expert, but I discovered that there are extra '}'s
within the document.  These appear to cause Word 2000 to stop
processing since the first extra '}' matches the initial '{' at
the start of the document.  Therefore, there is something in the
RTF generation code output an extra '}' on a frequent basis.

I did a quick Vim macro (I'm a big Vi/Vim user) to remove the extra
'}'s.  Unfortunately, if I let it run to completion, Word 2000
gives status about converting the document, but at the end of
the document, it gives a stupid error about bad file or path (when
it should state that some formatting error occured and information
about the specific error).

If I interupt the macro before removing all unbalanced '}'s, I can
get Word 2000 to load the portion with the extra '}'s removed.
There is something at the end of the RTF document where my simple
macro cannot apply.  I do have a class with an inner public
interface, so I do not know if that puts some extra problems in
the mix.  Doing a Ctrl-A, F9 in Word does resolve all the cross
references in the RTF.  Note, errors occur because of unknown
bookmarks if this is done to the raw RTF generated by doxygen due to
the extra '}'s problem.

I've been trying doxygen on project library done in Java, and
noticed some of the following problems (which may not be specific
to Java):

. I at least noticed that the <big> tag is not supported, which
  would probably assume that <small> tag is not either.  For HTML
  output generation, these tags should be passed as-is instead
  of escaped.  It would seem straight-forward to map them to
  to appropriate styles for LaTeX and RTF output.

. Docs in <pre> tags are not formatted correctly in RTF output.
  Line breaks are messed up.

. Conversion of HTML tables in javadoc not supported in RTF.

. Numeric entity references not supported.  For example,
  &#xF9; &8218;.

. <dl> formatting in RTF output does not indent <dd> elements.

. <cite> HTML element not supported.  This could be handled like
  <i> for typsetting purposes.

. <address> HTML element not supported.  This could be handled
  as an italicized paragraph block.

. I have some javadoc with non-functional HTML form markup
  (for a servlet class).  Probably not worth supporting, but
  I figure I would mention it since the markup is not supported
  by doxygen.

. I try to generate Postscript documentation from the LaTeX output,
  but get numerous TeX errors when running make in the latex
  output directory.  If the PS or PDF output can be done, I could
  care less about the RTF stuff.  I'm not a LaTeX/TeX person,
  so I can do little to help debug.

Overall, I think doxygen is pretty slick since it does help
one achieve the goal of consistent code level documentation
on multi-language projects and its ability to generate printable
documentation.

--ewh
  
--
Earl W. Hood
Texas Instruments
eh...@ti...
972-917-1695