RFC: MacPorts policy should be that docs should not be built or installed by default

[Joshua Root]

On 2019-9-20 14:40 , Ken Cunningham wrote:
> the documentation that comes along with many ports often seems like a heavy and arguably needless burden:
> 
> - huge bloat
> - lots of often onerous, massive, fussy build deps
> - often takes as much time to sort out doc building as building the port
> 
> and, the big one :
> 
> I bet almost nobody ever looks at them, much less uses them. 
> 
> Google can find what you are looking for in a tiny fraction of the time.
> 
> We just witnessed days spent trying to build some html files and a PDF for a certain few ports that was a moderate PITA, added tons of time to the port which could have been better spent elsewhere, added confusion and bloat in the portfile, and required an entire texlive infrastructure to support building it, but default, on every system that wants to build it.
> 
> I'm sure this has been bandied about for decades on MacPorts. 
> 
> Was it never decided to leave all the docs out, except for perhaps a few (not few hundred, like openssl, but a few like less than five) man pages?
> 
> An enabling +doc variant is noted in a few ports -- feel free if you're motivated, or no docs, but an expectation that docs should be included, if  there is that expectation, is wasting time, space, bandwidth, etc, etc...
> 
> I vote we expect ports to not include anything but a few man pages. Everything else should be either left out, or an optional variant. A note where the website is for documentation in the port notes would be more than sufficient.

I would say if the docs need large dependencies to build or are
themselves especially large, a variant or (preferably) a subport is
appropriate. A policy of not including docs seems a bit extreme though.
(Also don't forget that including certain documentation may be necessary
to comply with licenses like BSD.)

If you know of ports that would benefit from such changes and know how
to implement them, by all means open a PR. In some cases it may be the
maintainer just hasn't been able to figure out how to build the docs
separately.

- Josh