Bad escriptions in Kconfig

Bad escriptions in Kconfig

[Bodo Eggert]

In some of the Kconfig files, the options are not adequately decribed. I 
collected a few of the bad descriptions I found:


---
Lowlevel video output switch controls (VIDEO_OUTPUT_CONTROL) [M/n/y/?] (NEW) ?

This framework adds support for low-level control of the video
output switch.
---

- What is THE video output switch and why would I need low level control?

- Frameworks should be auto-selected like libraries, shouldn't they?

- WTF is this a module?


-------------
---
Auxiliary Display support (AUXDISPLAY) [N/y/?] (NEW) ?

Say Y here to get to see options for auxiliary display drivers.
This option alone does not add any kernel code.
---

- If I knw what an axilary display was, I would not read this help text!

- After digging some time, I discovered that all Auxdisplays are parallel 
  port devices.
  Rename to "Parallel port display device support"?


-------------
---
Transformation user configuration interface (XFRM_USER) [N/m/y/?] (NEW)
  
Support for Transformation(XFRM) user configuration interface
like IPsec used by native Linux tools.

If unsure, say Y.
---

- I'm not sure if these words combine to a sentence.
- I can't tell if IPSEC is the only user or if I'd break other parts by not 
  saying 'Y'. OTOH, I don't want to bloat my kernel ...
- What's a native linux tool?

  
-------------
---
SCSI target support (SCSI_TGT) [N/m/y/?] (NEW) ?

If you want to use SCSI target mode drivers enable this option.
If you choose M, the module will be called scsi_tgt.
---

What TF is a SCSI target mode, what is a target mode driver?

-- 
I'm a member of DNA (National Assocciation of Dyslexics).
	-- Storm in <5Z4Z7.52353$4x4.6445347@news2-win.server.ntlworld.com>

Re: Bad escriptions in Kconfig

[Douglas Gilbert]

Bodo Eggert wrote:
> In some of the Kconfig files, the options are not adequately decribed. I 
> collected a few of the bad descriptions I found:
> 
> 
> ---
> Lowlevel video output switch controls (VIDEO_OUTPUT_CONTROL) [M/n/y/?] (NEW) ?
> 
> This framework adds support for low-level control of the video
> output switch.
> ---
> 
> - What is THE video output switch and why would I need low level control?
> 
> - Frameworks should be auto-selected like libraries, shouldn't they?
> 
> - WTF is this a module?
> 
> 
> -------------
> ---
> Auxiliary Display support (AUXDISPLAY) [N/y/?] (NEW) ?
> 
> Say Y here to get to see options for auxiliary display drivers.
> This option alone does not add any kernel code.
> ---
> 
> - If I knw what an axilary display was, I would not read this help text!
> 
> - After digging some time, I discovered that all Auxdisplays are parallel 
>   port devices.
>   Rename to "Parallel port display device support"?
> 
> 
> -------------
> ---
> Transformation user configuration interface (XFRM_USER) [N/m/y/?] (NEW)
>   
> Support for Transformation(XFRM) user configuration interface
> like IPsec used by native Linux tools.
> 
> If unsure, say Y.
> ---
> 
> - I'm not sure if these words combine to a sentence.
> - I can't tell if IPSEC is the only user or if I'd break other parts by not 
>   saying 'Y'. OTOH, I don't want to bloat my kernel ...
> - What's a native linux tool?
> 
>   
> -------------
> ---
> SCSI target support (SCSI_TGT) [N/m/y/?] (NEW) ?
> 
> If you want to use SCSI target mode drivers enable this option.
> If you choose M, the module will be called scsi_tgt.
> ---
> 
> What TF is a SCSI target mode, what is a target mode driver?

Heard of google :-)

For explanations of SCSI (and other storage) terminology
reference could be made to SAM-3 or SAM-4 drafts (because
the real standards cost money) at www.t10.org .

Perhaps many other subsections in the kernel could have
similar references.

Doug Gilbert

Re: Bad escriptions in Kconfig

[Matthew Wilcox]

On Mon, Dec 31, 2007 at 10:16:43AM -0500, Douglas Gilbert wrote:
> Bodo Eggert wrote:
> > ---
> > SCSI target support (SCSI_TGT) [N/m/y/?] (NEW) ?
> > 
> > If you want to use SCSI target mode drivers enable this option.
> > If you choose M, the module will be called scsi_tgt.
> > ---
> > 
> > What TF is a SCSI target mode, what is a target mode driver?
> 
> Heard of google :-)
> 
> For explanations of SCSI (and other storage) terminology
> reference could be made to SAM-3 or SAM-4 drafts (because
> the real standards cost money) at www.t10.org .
> 
> Perhaps many other subsections in the kernel could have
> similar references.

I think that's an appalling idea.  Someone's trying to configure their
kernel, not research hundreds of new ideas on the internet.  Here's a
better description:

	help
	  The SCSI target code allows your computer to appear as a SCSI
	  device.  This is useful in a SAN or NAS environment where you
	  want other computers to be able to treat this computer as a disc.

	  To compile this driver as a module, choose M here: the module
	  will be called scsi_tgt.

-- 
Intel are signing my paycheques ... these opinions are still mine
"Bill, look, we understand that you're interested in selling us this
operating system, but compare it to ours.  We can't possibly take such
a retrograde step."

Re: Bad escriptions in Kconfig

[Douglas Gilbert]

Matthew Wilcox wrote:
> On Mon, Dec 31, 2007 at 10:16:43AM -0500, Douglas Gilbert wrote:
>> Bodo Eggert wrote:
>>> ---
>>> SCSI target support (SCSI_TGT) [N/m/y/?] (NEW) ?
>>>
>>> If you want to use SCSI target mode drivers enable this option.
>>> If you choose M, the module will be called scsi_tgt.
>>> ---
>>>
>>> What TF is a SCSI target mode, what is a target mode driver?
>> Heard of google :-)
>>
>> For explanations of SCSI (and other storage) terminology
>> reference could be made to SAM-3 or SAM-4 drafts (because
>> the real standards cost money) at www.t10.org .
>>
>> Perhaps many other subsections in the kernel could have
>> similar references.
> 
> I think that's an appalling idea.  Someone's trying to configure their
> kernel, not research hundreds of new ideas on the internet.  Here's a
> better description:
> 
> 	help
> 	  The SCSI target code allows your computer to appear as a SCSI
> 	  device.  This is useful in a SAN or NAS environment where you
> 	  want other computers to be able to treat this computer as a disc.
> 
> 	  To compile this driver as a module, choose M here: the module
> 	  will be called scsi_tgt.

Appalling or not, it is more accurate to define a SCSI target
properly than equate it to a direct access logical unit (i.e.
a disk). IMO the designers of that driver and associated
applications made exactly the same mistake which they are now
fixing. That driver is also transport specific with support
for iSCSI and iSER. Try writing a SPI, FC or SAS target driver
for scsi_tgt (I failed with SAS).

It could also be noted that if the reader doesn't understand
the description they can most likely say 'N'.

Doug Gilbert