[ITP] doxygen-1.8.0-2 -- A documentation system for C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.

[David Stacey]

On 02/10/12 02:27, Warren Young wrote:
> You should keep using -1 for subsequent build attempts until one gets 
> RFU'd.  Use new package versions only to disambiguate published 
> package versions.  The package version number is there to help 
> setup.exe out, not to help us poor humans out. :)

Apologies for that. I was following the advice here: 
http://cygwin.com/setup.html#submitting

"Do increase the version number no matter what... even if has only been 
discussed in mailing list and never uploaded: it costs nothing and 
avoids confusion in both setup.exe and people mind."

Maybe someone would be kind enough to clarify when the version number 
should be bumped up and when it shouldn't.

> Nits:
>
> 1. Another build requirement change: the doxygen.README file still 
> refers to TeTeX, which was replaced recently with TeX Live.  But, 
> installing a basic TeX setup alone isn't enough.  To build the PDF 
> manual, you need the optional texlive-collection-fontutils package for 
> epstopdf, and texlive-collection-latexextra for float.sty. There's no 
> need to mention any other packages.  Installing those two into a stock 
> Cygwin install will drag in enough of the remaining TeX stuff to build 
> the manual.

Good spot. I'll correct the reference to TeTeX and submit another 
version. For my own sanity I'll call it 1.8.0-3, unless someone 
clarifies the version-bumping quote first.

> 2. /usr/share/doc/doxygen/latex should be removed, in favor of a 
> .../pdf subdirectory.  I don't see a reason to ship source and 
> intermediate build files here, expecting the user to build the docs.  
> What's wanted here is a PDF of the LaTeX *output*.

I agree completely, but I kept the 'latex' directory for a couple of 
reasons. Firstly, this was consistent with the previous build of doxygen 
(1.7.4-1), which included the latex directory [1]. Secondly, I rather 
thought that if 'make install' wanted to install the latex directory 
then it wasn't really my place to delete of it.

However, I've had a little look at a couple of popular Linux 
distributions, and neither Fedora [2] nor Ubuntu [3] include the latex 
directory in their doxygen packages. Fedora includes the HTML manual and 
some examples in the main 'doxygen' package; Ubuntu has the HTML manual, 
the examples and the PDF manual in a separate 'doxygen-doc' package [4].

The upshot of this little investigation is that I'm happy to generate 
the PDF and remove the latex intermediary files. But I see this as an 
enhancement (rather than a mistake that needs correcting), so I'll do 
this in the next release of doxygen that I package.

[1] http://cygwin.com/packages/doxygen/doxygen-1.7.4-1
[2] 
https://admin.fedoraproject.org/pkgdb/builds/show/F-17-i386/doxygen/1/1.8.0/1.fc17/i686#files
[3] http://packages.ubuntu.com/quantal/i386/doxygen/filelist
[4] http://packages.ubuntu.com/quantal/all/doxygen-doc/filelist

> 3. I'd rather see your first version be 1.8.2-1 instead.  Why start 
> with a version two bug fix releases back?

The reason for this is simply down to the amount of testing that I've 
given the packages. I've given 1.8.0 a rather thorough testing in a 
Cygwin environment. I'm happy that it works reliably, has no major bugs 
and improves upon the 1.7.4 build we have at the moment.

Sometimes these "bug fix releases" introduce more bugs than they fix, 
which is why I'm not going for 1.8.1!

I have a build of 1.8.2 for Cygwin, but I have done *much* less testing 
of it. This version also builds the doxywizard GUI as a separate 
package, but this has had next to no testing. I'd sooner release 
something that I have confidence in. When I've got that same level of 
confidence in 1.8.2 (maybe in a couple of months) then I'll upload that 
version.

> There's a bogus test in Doxygen's configure script, where it goes 
> looking for dot(1) from GraphViz.  It does a weak check for it in a 
> few common locations, and yells if it isn't there.  dot(1) being a 
> filter, there isn't a huge penalty for using the native Windows 
> version, which of course doesn't get installed in any of those 
> locations.  It would be nice to either 1) send upstream a test using 
> the PATH instead of a hardcoded list; or 2) adopt Yaakov's GraphViz 
> package:

If the configure script doesn't detect dot(1) then it isn't the end of 
the world - you can specify the location of the dot executable by 
specifying DOT_PATH in the project configuration file:

http://www.stack.nl/~dimitri/doxygen/config.html#cfg_dot_path

But even that shouldn't be necessary: Cygwin adds the Windows path to 
its own PATH, so provided that the Windows 'dot.exe' is in your Windows 
path and you've set HAVE_DOT=YES in your project configuration file, you 
/should/ get GraphViz graphs in your doxygen output.

When I'm more proficient at making Cygwin packages then I may consider 
adopting GraphViz. GraphViz is a useful tool on its own, and the doxygen 
output is so much better if it can use dot(1), so there would be benefit 
to Cygwin having the GraphViz package.

Apologies for the long ramble, and many thanks for taking the time to 
look at my package.

Dave.