[pkg-wpa-devel] Suggestions for the documentation

[Felix Homann]

Hi,

as I've told in another thread I think the documentation could need some 
enhancements. Especially since the upgrade broke many installations. Since 
Reinhard Tartler asked for it I will make some suggestions (with respect to 
the 0.4.8-2 package):

First, merge README.Debian and README.modes. The modes are a Debian/Ubuntu 
specific way of using wpa_supplicant so this information belongs in 
README.Debian.

Second, I don't think README.Debian should start with a section "Action 
scripts" but rather a first steps instruction to get wpa_supplicant working 
or working again.

README.Debian
=======

"/etc/network/interface now supports actions scripts. With action scripts,
you can develop your own advanced roaming configuration. Please look 
at our example action script in 
/usr/share/doc/wpasupplicant/examples/wpacli-action-dhclient."

What is an action script? What does it do? What parameters are passed? When 
are they called? The example has only one line of comment which is not 
comprehensible. Maybe the documentation should rather point 
to /usr/share/doc/wpasupplicant/examples/wpacli-action-skeleton. 

"If you require
static ip configuration at some locations, you can easily add commands
to configure your network here."

If it is easy why not tell how? I can't see how the script should be altered 
for a static IP.

"Another possibility would be to start
roaming solutions like whereami at this point."

How?

"We suggest that you copy that file to /etc/wpa_supplicant/roaming.script"

Please, add a note on making the script executable.

"and use like this in /etc/network/interfaces:

iface eth1 inet manual
        wpa-conf managed
        wpa-action /etc/wpa_supplicant/roaming.script"

This is a bit confusing. The essential parts for enabling roaming are 
the "manual" flag and the wpa-action line (am I right?). The wpa-conf has 
nothing to do with roaming and it is not comprehensible without the 
information from README.modes.

Furthermore, I think there is a need for a real upgrade guide. At this time 
there isn't even a mention of where the backup of /etc/wpa_supplicant.conf 
is. 

The term "roaming" is misleading since not every usage of e.g. the old 
wpa_supplicant+ifplugd has to do with actual roaming (see my other postings).

That's it for the moment.

Kind regards,

Felix