proper DOXYGEN option default value

[Don Lewis]

On 10 Mar, Steve Wills wrote:
> On Wed, Mar 04, 2015 at 02:41:48PM -0800, Don Lewis wrote:
>> I maintain a number of ports that use doxygen to generate their
>> documentation.  They all list DOXYGEN in OPTIONS_DEFAULT so that
>> the packages will include documentation.
>> 
>> I recently received a PR for one of those ports that mentioned that most
>> users don't require the documentation and pointed out that anyone
>> building the port will find it is very painful because of the amount of
>> time it takes to build doxygen and all of its dependencies (primarily
>> all the TeX stuff).
>> 
>> It's been my experience that there is enough churn in the dependencies
>> that the whole mess needs to get rebuilt fairly frequently.
>> 
>> As I see it, the pros and cons of listing DOXYGEN in OPTIONS_DEFAULT
>> are:
>>   Pros:
>>     * Users who need the documentation can use the binary packages if
>>       they desire
>>     * This option gets regular exercise on the build cluster
>>   Cons:
>>       * A bit of extra load on the ports build cluster to install
>>         doxygen and its dependencies as a BUILD_DEPENDS for each
>>         supported OS version and architecture
>>       * The packages are a bit larger
>>       * A bit more space is consumed on the user's machine because
>>         documentation is installed, even if they don't need it
>>       * Users building from ports have to build and install doxygen
>>         and it's dependencies unless they take measures to avoid it,
>>         either by disabling the option for each port or adding
>>         OPTIONS_UNSET=DOXYGEN to their /etc/make.conf to do this
>>         globally
>> 
>> The pros and cons of removing DOXYGEN from OPTIONS_DEFAULT:
>>   Pros:
>>      * Less load on the ports build cluster
>>      * Smaller packages
>>      * Less space consumed on most user machines
>>      * Users building from ports who do not need the documentation don't
>>        pay the doxygen penalty without taking any special measures
>>   Cons:
>>      * Anyone who does need the documentation has to build from the
>>        port and pay the cost of building and installing doxygen and its
>>        dependencies.
>>      * The DOXYGEN option would not get regular testing and could be
>>        subject to bit rot.
>> 
>> Ideally, the documentation could be built and packaged separately.  It
>> could even be NO_ARCH.   Unfortunately, at this time this would require
>> adding a bunch of new ports just for the documentation.
>> 
>> Since these ports only generate HTML documentation, it might be helpful
>> to have a doxygen-lite port that has GRAPHVIZ and LATEX disabled, and
>> use that as a BUILD_DEPENDS.  That introduces the problem of conflicts
>> between doxygen and doxygen-lite if someone who builds from ports needs
>> the full featured doxygen for other purposes.
>> 
>> Since we have neither of the above, should I leave my ports as-is, or
>> should I disable DOXYGEN by default?
> 
> Personally I would tend to lean towards leaving DOXYGEN off by default,
> especially if there is other accompanying documentation. This is the case for
> lang/ruby* for example.

There's no other documentation in this case.  Excluding the DOXYGEN
stuff, this is the entire pkg-plist:

bin/protoc-c
include/google/protobuf-c/protobuf-c.h
include/protobuf-c/protobuf-c.h
lib/libprotobuf-c.a
lib/libprotobuf-c.so
lib/libprotobuf-c.so.1
lib/libprotobuf-c.so.1.0.0
libdata/pkgconfig/libprotobuf-c.pc

That does sound like a good general guideline, though.

> But beward that this may mean it is more likely that the DOXYGEN parts of the
> plist may become outdated when the doxygen port is updated. So keep testing
> that option.

I've run into that problem when listing the DOXYGEN output explicitly in
pkg-plist.  I've since switched to PORTDOCS=* to avoid this source of
breakage.