This is the mail archive of the
cygwin-apps
mailing list for the Cygwin project.
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.
- From: David Stacey <drstacey at tiscali dot co dot uk>
- To: cygwin-apps at cygwin dot com
- Date: Tue, 02 Oct 2012 20:10:53 +0100
- Subject: 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.
- References: <50674A3B.4060801@tiscali.co.uk> <506A430B.3000404@etr-usa.com>
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.
- Follow-Ups:
- 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.
- 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.
- From: Buchbinder, Barry (NIH/NIAID) [E]