[gentoo-dev] Improving use.desc

[gentoo-dev] Improving use.desc

[Santiago M. Mola]

Hi,

A lot of people have complaints about the quality of USE flag
descriptions, so let's see if we can improve them a bit.

This a list of some descriptions which could be improved. Some are
just stupid things like trailing dot (not a bad thing, but most of
them doesn't have one) and some others are quite significant.

Thoughts? Suggestions? Objections?

-Xaw3d - Adds support of the 3d athena widget set
+Xaw3d - Adds support for the 3d athena widget set

-apache2 - Add Apache2 support
+apache2 - Add Apache2 HTTP Server support

-audiofile - Adds support for libaudiofile where applicable
+audiofile - Adds support for libaudiofile (processing audio data to
and from audio files in AIFF, AIFC, WAVE, and NeXT/Sun)

-avahi - Add avahi/Zeroconf support
+avahi - Add avahi/Zeroconf support (easy service discovery on local networks)

-bcmath - Adds support for libbcmath
+bcmath - Adds support for libbcmath --FIXME

-branding - Enable Gentoo specific branding
+branding - Enable Gentoo specific branding (artwork, special
functionality, and others)

-cscope - Enables cscope interface -- in vim for example
+cscope - Enables cscope (source code browsing) interface -- in vim for example

-ctype - Enables ctype functions
+ctype - Enables ctype functions --FIXME

-dbus - Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc)
+dbus - Enable DBus support (a simple way for applications to talk to
one another)

-emacs - Adds support for GNU Emacs
+emacs - Adds support for GNU Emacs text editor

-evo - Adds support for evolution
+evo - Adds support for mail-client/evolution

-examples - Install example source code
+examples - Install examples, usually source code

-expat - Enable the use of dev-libs/expat
+expat - Enable the use of dev-libs/expat for XML parsing

-ffmpeg - Enable ffmpeg support
+ffmpeg - Enable ffmpeg support --FIXME

-flac - Adds support for the flac audio codec
+flac - Adds support for FLAC: Free Lossless Audio Codec

-geoip - Add geoip support
+geoip - Add geoip support for country and city lookup based on IPs

-gnuplot - Enable gnuplot support
+gnuplot - Enable support for gnuplot (data and function plotting)

-gnutls - Adds support for net-libs/gnutls
+gnutls - Adds support for net-libs/gnutls (TLS 1.0 and SSL 3.0 support)

-jpeg2k - Support for JPEG 2000, a wavelet-based image compression format.
+jpeg2k - Support for JPEG 2000, a wavelet-based image compression format

-junit - Adds junit awareness -- useful for developers.
+junit - Adds junit awareness -- useful for developers

-kdeenablefinal - EXPERIMENTAL: KDE ebuilds will use the enable-final
flag, yielding compilation speedups at the cost of heavy mem usage and
potentially causing problems. We strongly discourage setting this.
+kdeenablefinal - EXPERIMENTAL: KDE ebuilds will use the enable-final
flag, yielding compilation speedups at the cost of heavy mem usage and
potentially causing problems. We strongly discourage setting this

-kerberos - Adds kerberos support
+kerberos - Adds support for the kerberos network authentication protocol

-libcaca - Add support for colored ASCII-art graphics
+libcaca - Add support for colored ASCII-art graphics (with media-libs/libcaca)

-libnotify - Enable notification support
+libnotify - Enable notification support --FIXME

-matroska - Adds support for the matroska container format
+matroska - Adds support for the matroska container format (extensions
.mkv, .mka and .mks)

-modplug - Adds libmodplug support
+modplug - Adds libmodplug support (for MOD-like music files)

-mpeg - Adds libmpeg3 support to various packages.
+mpeg - Adds libmpeg3 support to various packages. --FIXME: This is no
longer true

-pda - Adds support for portable devices.
+pda - Adds support for portable devices

-perl - Adds support/bindings for the Perl language.
+perl - Adds support/bindings for the Perl language

-php - Include support for php
+php - Include support for the PHP language

-pic - Build Position Independent Code.  Do not utilize this flag
unless you know what you're doing.
+pic - Build Position Independent Code.  Do not utilize this flag
unless you know what you're doing

-pulseaudio - Adds support for PulseAudio sound server
+pulseaudio - Adds support for PulseAudio sound server (ex-PolypAudio)

-sharedext - Adds support for building shared extensions in php
+sharedext - Adds support for building shared extensions in PHP

-simplexml - support for simplexml
+simplexml - support for SimpleXML

-sndfile - Adds support for libsndfile
+sndfile - Adds support for libsndfile reading and writing files
containing sampled sound (supporting lots of formats)

-speex - Adds support for the speex audio codec
+speex - Adds support for the speex audio codec (used for speech)

-svg - Adds support for SVG (Scalable Vector Graphics).
+svg - Adds support for SVG (Scalable Vector Graphics)

-tiff - Adds support for the tiff image format
+tiff - Adds support for the TIFF image format

-vim-syntax - Pulls in related vim syntax scripts.
+vim-syntax - Pulls in related vim syntax scripts

Regards,
Santiago

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Improving use.desc

[Ulrich Mueller]

>>>>> On Wed, 2 Jan 2008, Santiago M Mola wrote:

> A lot of people have complaints about the quality of USE flag
> descriptions, so let's see if we can improve them a bit.

> [...]

> -emacs - Adds support for GNU Emacs
> +emacs - Adds support for GNU Emacs text editor

Please leave this one as it is. For some packages the flag addresses
also the "non-editor" aspects of Emacs.

Besides, it is consistent with the xemacs flag ("Add support for XEmacs").

Ulrich
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: Improving use.desc

[Markus Ullmann]

[-- Attachment #1: Type: text/plain, Size: 538 bytes --]

Santiago M. Mola schrieb:
> -ffmpeg - Enable ffmpeg support
> +ffmpeg - Enable ffmpeg support --FIXME

ffmpeg - Enable ffmpeg-based audio/video codec support

> -junit - Adds junit awareness -- useful for developers.
> +junit - Adds junit testframework awareness -- useful for developers

junit - Adds junit test framework awareness -- useful for developers

> -libnotify - Enable notification support
> +libnotify - Enable notification support -- FIXME

libnotify - Enable desktop notification support

Greetz
-Jokey


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

Re: [gentoo-dev] Re: Improving use.desc

[Vlastimil Babka]

Markus Ullmann wrote:
>> -junit - Adds junit awareness -- useful for developers.
>> +junit - Adds junit testframework awareness -- useful for developers
> 
> junit - Adds junit test framework awareness -- useful for developers

Actually, this flag should probably go away with gen-1 java ebuilds
(gen-2 uses standard FEATURES=test for junit tests). Quick grep shows
that it's already not used anywhere.

VB
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: Improving use.desc

[Mike Kelly]

While you're at it, I think almost everything in desc/video_cards.desc,
desc/input_devices.desc, and a few more, could use some attention.

In particular, things like nv vs. nvidia are quite confusing. I usually
end up reading the xorg-server ebuild when I want to makes sense of it,
which defeats the point of video_cards.desc altogether.

Also, things like desc/userland.desc have all their variables starting
with "USERLAND setting for" which is about as useful as having every
use.desc line start with "USE setting for".

That said, the various alsa*desc files, and some others, are well
documented, and would serve as a good example for the others.

-- 
Mike Kelly
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Improving use.desc

[Santiago M. Mola]

On Jan 2, 2008 8:59 PM, Mike Kelly <pioto@pioto.org> wrote:
> While you're at it, I think almost everything in desc/video_cards.desc,
> desc/input_devices.desc, and a few more, could use some attention.

Here we go. I based it mostly on
http://xorg.freedesktop.org/archive/X11R7.0/doc/html/manindex4.html

I'm specially lost with the following:
sis / xgi
tdfx / voodoo
s3 / s3virge
nv / nouveau
radeonhd

Here's the new video_card.desc:

amd - VIDEO_CARDS setting to build driver for AMD Geode GX and LX video cards
apm - Alliance ProMotion video cards (ProMotion 6420 and 6422, AT24,
AT3D and AT25)
ark - VIDEO_CARDS setting to build driver for ark video cards
chips - VIDEO_CARDS setting to build driver for chips video cards
cirrus - Cirrus Logic video cards
cyrix - VIDEO_CARDS setting to build driver for cyrix video cards
dummy - VIDEO_CARDS setting to build driver for dummy video cards
epson - VIDEO_CARDS setting to build driver for epson video cards
fbdev - framebuffer devices
fglrx - VIDEO_CARDS setting to build driver for fglrx video cards
glint - VIDEO_CARDS setting to build driver for glint video cards
i128 - VIDEO_CARDS setting to build driver for i128 video cards
i740 - Intel i740 video cards
i810 - Intel video cards with i810, i810-DC100, i810e, i815, i830M,
845G, 852GM, 855GM, 865G, 915G, 915GM, 945G, 945GM, 965G, 965Q or
946GZ chipsets
impact - VIDEO_CARDS setting to build driver for impact video cards
imstt - Integrated Micro Solutions Twin Turbo 128 video cards
mach64 - ATI Mach64
mga - VIDEO_CARDS setting to build driver for mga video cards
neomagic - Neomagic video cards (MagicGraph chipsets)
newport - SGI Indy's and Indigo2's newport video cards
none - VIDEO_CARDS setting to build no drivers (useful when using
binary drivers)
nsc - FIXME: http://xorg.freedesktop.org/archive/X11R7.0/doc/html/nsc.4.html
nv - VIDEO_CARDS setting to build driver for nv video cards
nvidia - VIDEO_CARDS setting to build driver for nvidia video cards
r128 - ATI Rage 128
radeon - ATI Radeon up to X1050-series (i.e. Radeon SDR/DDR, Radeon
7000-9800, and Radeon X300-X1050 are supported)
rendition - Rendition / Micron Verite cards with V1000, V2100 and V2200 chipsets
s3 - VIDEO_CARDS setting to build driver for s3 video cards
s3virge - S3 ViRGE cards with ViRGE DX, GX, GX2, MX, MX+, VX, Trio 3D
and Trio 3D/2X chipsets
savage - S3 Savage family, supporting Savage (3D, 4, 2000, MX and IX),
SuperSavage (MX and IX), ProSavage (PM133, KM133, DDR, DDR-K), Twister
(ProSavage PN133) and TwisterK (ProSavage KN133)
siliconmotion - Silicon Motion based video cards with Lynx, LynxE,
Lynx3D, LynxEM, LynxEM+, Lynx3DM and Cougar3DR chipsets
sis - VIDEO_CARDS setting to build driver for sis video cards
sisusb - SiS (Silicon Integrated Systems) video chips that are
connected via a Net2280-based USB dongle (SiS315E/PRO)
sunbw2 - VIDEO_CARDS setting to build driver for sunbw2 video cards
suncg14 - VIDEO_CARDS setting to build driver for suncg14 video cards
suncg3 - VIDEO_CARDS setting to build driver for suncg3 video cards
suncg6 - VIDEO_CARDS setting to build driver for suncg6 video cards
sunffb - VIDEO_CARDS setting to build driver for sunffb video cards
sunleo - VIDEO_CARDS setting to build driver for sunleo video cards
suntcx - VIDEO_CARDS setting to build driver for suntcx video cards
tdfx - VIDEO_CARDS setting to build driver for tdfx video cards
tga - VIDEO_CARDS setting to build driver for tga video cards
trident - Trident video cards
tseng - Tseng Labs video cards
v4l - video4linux cards like bt848/bt878-based TV cards
vermilion - VIDEO_CARDS setting to build driver for Intel Vermilion video cards
vesa - generic VESA video cards
vga - generic VGA video cards
via - VIA chipsets with onboard unichrome graphics
vmware - VMware virtual video cards (for use in VMware guest systems)
voodoo - VIDEO_CARDS setting to build driver for voodoo video cards
xgi - VIDEO_CARDS setting to build driver for xgi video cards

Suggestions? Corrections?

Things like
"S3 Savage family, supporting Savage (3D, 4, 2000, MX and IX),
SuperSavage (MX and IX), ProSavage (PM133, KM133, DDR, DDR-K), Twister
(ProSavage PN133) and TwisterK (ProSavage KN133)"
are too verbose or are ok?

Regards,
Santiago

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Improving use.desc

[Bernd Steinhauser]

Hi,

What about sth. like this:

> fglrx - VIDEO_CARDS setting to build driver for fglrx video cards
fglrx - Build AMD's proprietary video driver for r300-r600 video cards
> nv - VIDEO_CARDS setting to build driver for nv video cards
nv - Open source driver for Nvidia cards, only supports 2D
(I don't know what cards it supports.)
nouveau - Open source driver for Nvidia cards, with 3D support
(When it will make it to portage, at some time in the future. ;-))
> nvidia - VIDEO_CARDS setting to build driver for nvidia video cards
nvidia - Nvidia's proprietary video driver (some cards need a special
version)
> radeon - ATI Radeon up to X1050-series (i.e. Radeon SDR/DDR, Radeon
> 7000-9800, and Radeon X300-X1050 are supported)
radeon - Open source driver with 3D support, that supports ATI cards up
to r500 chips (r600 Chips without 3D acceleration)
radeonhd - New open source driver based on AMD's released documentation,
with support for r500/r600 chips

Generally I think, that the text "VIDEO_CARDS setting to build driver
for X cards" really doesn't help anyone, then you could also just leave
it blank, which might actually be a good idea, because that encourages
people to place something good in there.

Bernd
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Improving use.desc

[Donnie Berkholz]

On 14:59 Wed 02 Jan     , Mike Kelly wrote:
> While you're at it, I think almost everything in desc/video_cards.desc,
> desc/input_devices.desc, and a few more, could use some attention.
> 
> In particular, things like nv vs. nvidia are quite confusing. I usually
> end up reading the xorg-server ebuild when I want to makes sense of it,
> which defeats the point of video_cards.desc altogether.

Are there any programs (make.conf / USE editors) that manage to read and 
set that stuff?

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Improving use.desc

[Santiago M. Mola]

On Jan 4, 2008 6:31 AM, Donnie Berkholz <dberkholz@gentoo.org> wrote:
>
> Are there any programs (make.conf / USE editors) that manage to read and
> set that stuff?
>

Paludis read and show them.

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: Improving use.desc

[Robert Buchholz]

[-- Attachment #1: Type: text/plain, Size: 983 bytes --]

On Friday, 4. January 2008, Donnie Berkholz wrote:
> On 14:59 Wed 02 Jan     , Mike Kelly wrote:
> > While you're at it, I think almost everything in
> > desc/video_cards.desc, desc/input_devices.desc, and a few more, could
> > use some attention.
> >
> > In particular, things like nv vs. nvidia are quite confusing. I
> > usually end up reading the xorg-server ebuild when I want to makes
> > sense of it, which defeats the point of video_cards.desc altogether.
>
> Are there any programs (make.conf / USE editors) that manage to read and
> set that stuff?

By read, do you mean read the setting from make.conf or read the 
description? If the latter, quse reads it.

$ quse -D nvidia
 local:nvidia:gnome-extra/sensors-applet: Enable support for nvidia sensors
 local:nvidia:sys-power/cpufreqd: Enable nvidia overclocking (nvclock)
           plug-in
 video_cards.desc:nvidia: VIDEO_CARDS setting to build driver for nvidia
           video cards


Robert

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 189 bytes --]