195845 - Descriptions for hidden preferences accessable by about:config and other parts of Mozilla

Status: RESOLVED DUPLICATE of bug 269423

(Core :: Preferences: Backend, enhancement)

Description

[Brian 'netdragon' Bober]

I'm putting this bug in Preferences because it would require a modification of
the preferences service. We should add a field to all prefs that stores a
description for the preferences (maybe in all.js). That way, the prefs service
could grab the descriptions and generate an HTML file describing all the
preferences -- such as about:prefs or some other means.

This would go well with trying to make manual editing of prefs more visible for
the average user and release the need for too much UI in the prefs window.

That way, we can focus on fixing bugs, and not the preferences UI.

Comment 1

[Jason Bassford]

Doesn't about:config already list all of the preferences?  Since that's where
you would dynamically change their values, why not just add this description to
that screen somewhere (such as an "About" button at the right), rather than
introducing another screen?

Comment 2

[Boris Zbarsky [:bzbarsky]]

My comments on this are:

1) BLOAT!
2) This is what "Help" is for
3) There is no way some prefs should be documented anywhere outside the code

Comment 3

[Alec Flett]

no no no and absolutely no. The backend pref service will NEVER support this.
write docs.
or better yet come up with a mechanism in the build system to document these
prefs...

Here's a suggestion: write a .properties file with each pref as the key
browser.homepage.description=The first page loaded in a new browser window
browser.homepage.type=string

and then come up with some XUL which enumerates the prefs and looks up the value
in the .properties file. You could add that as a column in the about:config
page. Thus you'd only bloat when the about:config page is loaded, and you'd see
the pref descriptions in the UI. You could even use the .type aspect to do error
checking on the current state of the prefs. 

The nice thing with that is that there would only be bloat if you included the
.properties file in your distribution.. 

Comment 4

[sairuh (rarely reading bugmail)]

see bug 158384 for providing [more detailed] documentation for prefs.

Comment 5

[[e-mail]]

We could just tack all the descriptions on to the existing config.properties
file, as and when they are documented. I just wonder what the perf hit for a
missed stringbundle entry is.

Comment 6

[Alec Flett]

put it in a seperate .properties file - that way embeddors who want about:config
don't have to include a potentially giant file.

The "perf hit" for a missing entry is just a hashtable miss, and is very minor..
less than a hashtable hit, actually. (because if you hit, you have to allocate
space for the string, and so forth)

Comment 7

[[e-mail]]

My current idea for this is for config.js to be able to use different
.properties files based on the pref domain - perhaps <domain>.properties would
be a pref containing the actual properties file to use. This means that
extensions could create a pref telling config.js where to find the descriptions.

Comment 8

[Brian 'netdragon' Bober]

neil: See also: Bug 17199, bug 107418

Comment 9

[Ben Bucksch (:BenB)]

IMO, this is a dup of bug 17199. That bug was intended to give users a nice UI
to all prefs, including restricting to defined values and embedded documentation.

Comment 10

[Brian 'netdragon' Bober]

I don't agree. This is a form for manual entry of preferences, which would be
faster for the advanced user than a tree.

Both these bugs make it so that manual editing of prefs is transparent to the
average user. Both these bugs make it so we don't have to concentrate on
preferences UI until our preferences are more or less set rock solid (if that
ever happens). Both bugs are different issues.

Comment 11

[Brian 'netdragon' Bober]

It would also be nice if you could just select the pref from the list and it
would paste it into the pref box. For instance:

select:

browser.automatic_image_resizing and its pasted into the textbox in about:config as

"browser.automati_image_resizing=" then someone only has to type in the value of
the preference.

Comment 12

[Stephen Bounds]

The Preferential extension (http://preferential.mozdev.org) is already trying to
document all Mozilla, Firebird and extension preferences.  The extension itself
delivers the preferences in RDF format, but the original source for the
preference descriptions is similar to that suggested by Alec Flett (in comment 3).

I'm happy to make the original source available to anyone if you feel it would
be useful (e-mail me) -- you can view an out-of-date version of the document
attached to bug 158384 to get an idea of what I'm talking about.

Comment 13

[Jason Barnabe (np)]

*** Bug 233703 has been marked as a duplicate of this bug. ***

Comment 14

[Ben Goodger (use ben at mozilla dot org for email)]

Mass reassign of my non-Firefox bugs to [e-mail]

Comment 15

[Boris Zbarsky [:bzbarsky]]

*** Bug 254845 has been marked as a duplicate of this bug. ***

Comment 16

[benc]

-> core/prefs-BE

Comment 17

[Kevin B]

Many preferences are already documented at http://kb.mozillazine.org/.  Maybe the context menu for an item in about:config can have an entry opens the corresponding page.  This is easy to implement and doesn't add bloat.