(bad docs) man page is inconsistent with wiki, & also inconsistent with system defaults

[Bill Yikes]

Linux systems are typically configured with either a "wheel" group or a "sudo" group to specify users that get sudo privs. In the case of Debian's default config, a "sudo" group exists in /etc/group and also the /etc/sudoers file assumes a "sudo" group. Yet the latest wpa_supplicant.conf man page gives all examples using the non-existent "wheel" group:

https://manpages.debian.org/testing/wpasupplicant/wpa_supplicant.conf.5.en.html

The wiki:

https://wiki.debian.org/WiFi/HowToUse#wpa_supplicant

is incomplete, because it neglects the setting that enables users to configure the wifi APs. The wiki assumes:

ctrl_interface=/run/wpa_supplicant

while the man page not only shows a different directory, it shows a different syntax:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel

Debian-independant docs out in the wild are all over map on this which exacerbates confusion. In attempt to get a grasp on sanity, you would think users could simply check which directory was created by the wpasupplicant installer. The answer: it created both /var/run/wpa_supplicant and /run/wpa_supplicant -- which obviously perpetuates confusion.

Considering /var is short for "variable", and a wifi config is naturally quite variable, it's tempting to go with /var/run/wpa_supplicant/. Normally the man page would also be the first port of call, but because it uses "wheel", it's hard to trust the man page. At the same time this apparently well-written distro-agnostic guide demonstrates using /run/wpa_supplicant/:

https://shapeshed.com/linux-wifi

There's another reason to distrust the man page: these config params worked on Debian Lenny-baed distros:

     ctrl_interface=/var/run/wpa_supplicant
     ctrl_interface_group=netdev

Notice that ctrl_interface_group is a separate parameter. Was that parameter made obsolete, or is it simply undocumented? It should be documented in the man page, and if it's obsolete then the manpage should still document it and mark it obsolete so users know to adapt their configs.

And woah, where does netdev come from? A: /usr/share/doc/wpasupplicant/README.Debian.gz, which shows:

ctrl_interface=DIR=/run/wpa_supplicant GROUP=netdev

and yes, that's also /run/ without the leading /var/, thus contradicting the man page. Wait, it gets better-- README.gz (not README.Debian.gz) shows:

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel

Does that mean upstream uses /var/run/ & Debian intends to use /run/?

What does "update_config=1" mean? We see it here: https://shapeshed.com/linux-wifi but no mention in any of the man pages, or in any of the /usr/share/doc/wpasupplicant/* files. Very brief mention in the wiki, but who's to say the user's network is up to visit the wiki? We should expect to find it here: https://manpages.debian.org/testing/wpasupplicant/wpa_supplicant.conf.5.en.html but that's just a few examples-- no proper documentation. "update_config" is covered by arch linux: https://wiki.archlinux.org/title/wpa_supplicant/. It turns out to be a minimal config option to support wpa_cli, yet the wpa_cli man page makes no mention of this option that's critical for wpa_cli to operate.

Please make the docs a bit less painful; less schitzophrenic.