This is the mail archive of the cygwin-apps mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [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.


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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]