lots-o-ports: decide on common variant/sub-port name to build documentation: +docs or +doc

[blair (Blair Zajac)]

Blair writes, specifically regarding "cmake":

It appears that +doc is more common than +doc (at least in my list of installed packages), as I have +doc in my ${prefix}/etc/macports/variants.conf, so suggest cmake switches over.

Michaelld writes:

I'm retitling this request, since IMHO it is valid to request a common variant name to build documentation. Rather than requesting I change the variant for one specific port, lets look at the overall ports and make a group decision on how to proceed.

[michaelld (Michael Dickens)]

As quick search from the top-level ports directory results as such:

$ find . -name Portfile -print0 | xargs -0 grep "variant doc" | wc -l
128

$ find . -name Portfile -print0 | xargs -0 grep "variant doc" | grep docs | wc -l
75

So there are approximately 128 ports that use a variant "doc" or "docs" to build documentation, and those approximately 75 use "+docs" and thus approximately 53 use "+doc". As there are more ports that use "+docs" than "+doc", one could argue that those using "+doc" should move to using "+docs" instead of the other way around. I don't really care which variant is used, but I do care that my port is not singled out for any or no obvious reason.

[N.B.: One can argue whether this search returns all ports with the desired variants, or whether I really needed to use "-print0" and "xargs -0". I say that this method works & I remember it & it is nice and generic, so moving to an "-exec ..." while it could also work is beyond the point here; also, that these are meant to give approximation of the number of ports, and if those approximation are "close" in integer value, then maybe it's worth delving further into this rabbit hole, but I don't think they are really even close.]

[michaelld (Michael Dickens)]

I will add on the ports here as best I can, and which uses which variant.

[michaelld (Michael Dickens)]

Using "+docs" (does not include "-devel" ports, just the primary subport):

cmake
qtscriptgenerator
udis86
geoclue2
libdbi
libdbi-drivers
py-simpy
py-colour
py-spyder-devel
py-spyder
policykit
volk
gr-limesdr
gnss-sdr
gnuradio
opencascade
gr-iqbalance
uhd
gmsh
gr-osmosdr
avrdude
libgdamm5
libspectre
fityk
dolfin
octave
blitz-devel
itpp
sml-mode.el
cc65
kde-extra-cmake-modules
rpm54
rpm
dpkg
libvpx
libwpd-0.10
xmlstarlet
libwps-0.3
libodfgen
libetonyek
lilypond
librevenge
libwps
doxygen
xfs
xorg-xorgproto
xorg-libxcb
xorg-server
xorg-libXtst
xorg-libXfont2
xorg-libXdmcp
xorg-server-devel
xorg-xtrans
xorg-libice
pcb
xorg-libXfont
xorg-libXext
xorg-libsm
xorg-libXaw
xorg-libXmu
xorg-libXcomposite
xorg-libXi
xorg-libX11
libwpg-0.3
libcdr-0.1
libvisio-0.1
libcdr
libfreehand
glfw
libpagemaker
vigra
gl2ps
pgplot
jasper
libmspub

[michaelld (Michael Dickens)]

Using "+doc":

swig
dbus-python
redo
libfilezilla
activewire
liboil
git-ftp
dbus-glib
git
gnutls
geoclue2
xindy
blahtexml
texlive
py-openssl
py-pydicom
py-pynetdicom
openpgpsdk
libaes_siv
p11-kit
weechat
eigen3
reduce
sundials
pspp
pari
sundials2
pike
ruby24
ruby23
ruby22
ruby25
ruby20
ruby26
ruby19
ruby21
ispc
coq
ntpsec
moreutils
dirac
libxslt
awesome
lib2geom
lensfun
ftgl
libexif
giflib
dcmtk
pgrouting

[michaelld (Michael Dickens)]

NOTE: These lists do not include "-devel" ports [etc] nor the same portfile for different ports for version of Python or Perl or whatever -> just the primary subport.

[mojca (Mojca Miklavec)]

I would lean towards +doc myself, but I don't have a super strong opinion, except that I agree that it would be nice to unify these variants.

Smooth transition in not a technical problem (we did the transition from no_x11 to x11 in the past, for example, see #39383), you just need the work(force) to address every single port. For x11 it probably took a few years :) You keep an empty variant with the legacy name, and if that variant is active, activate the new name. After a year remove the legacy variant This will at least work for users who explicitly enabled the variant. It won't work for users who disabled the variant.

[mf2k (Frank Schima)]

I wrote a python script to analyze the ports to get more accurate counts. There are a few python sub-ports that slightly increase the counts. Also some portgroups add doc(s) variants and so only need to be changed once. I also overcounted -devel sub-ports. Anyway, here are the results:

variant	port count
doc	104
docs	363
with_docs	31
other	16

Plus there are sub-ports for documentation:

port name	port count
*-doc	22
*-docs	239

I can also list the actual ports. Does anyone want me to add them in the description?

[mf2k (Frank Schima)]

While I think that "doc" is more logically correct since it is short for documentation, I think we should take the easier route and use "docs" so that we have fewer ports to change.

[michaelld (Michael Dickens)]

I don't see a point in having this ticket open, since we couldn't come to an agreement. Hence, I'm closing.

[mf2k (Frank Schima)]

We still need to come to a consensus on this.

[mf2k (Frank Schima)]

@mojca: Any other thoughts on this? I prefer "+docs" because it is the easier way to go.

[MarcusCalhoun-Lopez (Marcus Calhoun-Lopez)]

I have no strong preference either, but I agree that +docs seems easier.
Is there someone who objects, or is there just indifference to the issue?

[mf2k (Frank Schima)]

I think it is indifference. I will plan to start switching nomaintainer ports to +docs in a few days if we get no objections to that.