wifi-radar.conf manual page mostly useless

[era]

Binary package hint: wifi-radar

The manual page for wifi-radar.conf looks like basically a copy/paste of the wifi-radar manual page. The NAME, SYNOPSIS, FILES, BUGS, and AUTHOR sections look like duplicates; they are mostly redundant here, to the extent that they are not erroneous.

The EXAMPLES section is not completely useless (sorry for the attention-grabbing title for this bug report). Getting an example of the general syntax and the available directives is useful, but the manual page fails to document even briefly what those examples actually mean.

Most of the directives are fairly self-explanatory, but e.g. "speak_up" is definitely not.

/usr/bin/wifi-radar contains the following comments, which could be copied to the manual page (modulo typo fixes):

# The interface you use
INTERFACE = "eth1"

# How long should the scan last?
SCAN_TIMEOUT = "5"

# Should I speak up when connecting to a network? (If you have a speach command)
SPEAK_UP = False

# You may set this to true for cards that require a "commit" command with iwconfig
COMMIT_REQUIRED = False

# You may set this to true for cards that require the interface to be brought up first
IFUP_REQUIRED = False

# ...

IWLIST_COMMAND = "LC_MESSAGES=C iwlist"
IWCONFIG_COMMAND = "LC_MESSAGES=C iwconfig"
IFCONFIG_COMMAND = "LC_MESSAGES=C ifconfig"
ROUTE_COMMAND = "LC_MESSAGES=C route"

# X1000 Linux has a say command (text to speach) to accounce connecting to networks.
# Set the SPEAK_UP to false if you do not have or want this.
SAY_COMMAND = "say"

The scan_timeout could benefit from some elaboration, and the interface option is apparently optional, in which case all interfaces will be scanned. The speak_up option looks like it may be better off remaining undocumented (in which case it should perhaps not be in the EXAMPLES either).

[Ante Karamatić (ivoks)]

IMHO, content of man pages should be fixed upstream, except typos, etc.

[era (era)]

Attached please find an overhauled manual page. Diff available on request but it didn't make much sense to diff, because it's basically rewritten.

[era (era)]

... So, could you bring this upstream, or shall I?

[era (era)]

Oh, and for the record, see also bug #97413

[era (era)]

Also notice that there are a couple of FIXME comments and a couple of commented-out parts.

I suppose the FIXME comments could be fixed by redirecting to one of the wireless-tools pages for more information.

The "channel" setting could be uncommented. I meant to check but forgot.

The "signal" setting is visible in the code but I guess it is only used to keep track of the current signal, and not a user-configurable field.

[Ante Karamatić (ivoks)]

This will not get fixed for feisty, but will be sent upstream (both debian and debian's upstream).

Thank you for your effort.

[era (era)]

I'm not in a place where I can easily check this, but "[GLOBAL]" in the patch looks wrong, and should probably read "[DEFAULT]". There isn't a [GLOBAL] section, is there?

[era (era)]

Just for the record, is there an upstream bug for this?

[era (era)]

Looks like this was finally independently fixed by upstream, and can be closed once 2.0x lands (LP bug #409932).

I must say I am somewhat peeved that the hours I put into producing a manual page were wasted.

[Sean Robinson (seankrobinson)]

  Your time wasn't wasted. It was your bug report that prompted me to
re-write the man page. In fact, I tried to use your version as a starting
point. Unfortunately, the wifi-radar.conf format changed so much in v2.0, I
abandoned that version and restarted with something else I had prepared for
the user manual.

On Tue, Aug 11, 2009 at 11:34 AM, era <email address hidden> wrote:

> Looks like this was finally independently fixed by upstream, and can be
> closed once 2.0x lands (LP bug #409932).
>
> I must say I am somewhat peeved that the hours I put into producing a
> manual page were wasted.
>
> --
> wifi-radar.conf manual page mostly useless
> https://bugs.launchpad.net/bugs/97390
> You received this bug notification because you are subscribed to wifi-
> radar in ubuntu.
>
> Status in “wifi-radar” package in Ubuntu: Confirmed
>
> Bug description:
> Binary package hint: wifi-radar
>
> The manual page for wifi-radar.conf looks like basically a copy/paste of
> the wifi-radar manual page. The NAME, SYNOPSIS, FILES, BUGS, and AUTHOR
> sections look like duplicates; they are mostly redundant here, to the extent
> that they are not erroneous.
>
> The EXAMPLES section is not completely useless (sorry for the
> attention-grabbing title for this bug report). Getting an example of the
> general syntax and the available directives is useful, but the manual page
> fails to document even briefly what those examples actually mean.
>
> Most of the directives are fairly self-explanatory, but e.g. "speak_up" is
> definitely not.
>
> /usr/bin/wifi-radar contains the following comments, which could be copied
> to the manual page (modulo typo fixes):
>
> # The interface you use
> INTERFACE = "eth1"
>
> # How long should the scan last?
> SCAN_TIMEOUT = "5"
>
> # Should I speak up when connecting to a network? (If you have a speach
> command)
> SPEAK_UP = False
>
> # You may set this to true for cards that require a "commit" command with
> iwconfig
> COMMIT_REQUIRED = False
>
> # You may set this to true for cards that require the interface to be
> brought up first
> IFUP_REQUIRED = False
>
> # ...
>
> IWLIST_COMMAND = "LC_MESSAGES=C iwlist"
> IWCONFIG_COMMAND = "LC_MESSAGES=C iwconfig"
> IFCONFIG_COMMAND = "LC_MESSAGES=C ifconfig"
> ROUTE_COMMAND = "LC_MESSAGES=C route"
>
> # X1000 Linux has a say command (text to speach) to accounce connecting to
> networks.
> # Set the SPEAK_UP to false if you do not have or want this.
> SAY_COMMAND = "say"
>
> The scan_timeout could benefit from some elaboration, and the interface
> option is apparently optional, in which case all interfaces will be scanned.
> The speak_up option looks like it may be better off remaining undocumented
> (in which case it should perhaps not be in the EXAMPLES either).
>

--
Sean Robinson
WiFi Radar - http://wifi-radar.berlios.de
Python WiFi - http://pythonwifi.wikispot.org

[era (era)]

> Your time wasn't wasted.

Good to hear, thanks! (-: