Category talk:Preferences

This category is for articles that concentrate purely on a single preference (or preference branch, at the very least).

Structure

In general, an article belonging to this category should have the preference as its name (or at least the nearest wiki equivalent) and follow this structure:

{{wrongtitle|title=Preference Name}}

==Background==
A paragraph or two explaining what the preference effects, why it's needed,
vaguely interesting history of the preference, etc.

==Possible values and their effects==
If there are only a set number of possible values, each value should get its
own third-level heading. Otherwise, a brief description of the value and its
valid range. Indicate the default value.

==Caveats==
* A list of bugs, gotchas, or things one should know before messing with the
  preference's value.
* If there are none of note, don't include the section.

==UI==
If there's a way to change the pref via the user interface, it should be noted
here. If it's different from product to product, give directions for each
product under its own third-level heading. If there's no UI, don't include the
section.

==Recommended settings==
"Tweaker"-friendly information would go under this section. If there isn't any
such information, don't include the section.

==Previous effects==
If for some reason the preference's behavior has changed from release to
release, note it here. Otherwise, leave the section out.

==First checked in==
The date (YYYY-MM-DD) of the checkin and name of the developer who checked it
in. If possible, link to the bonsai diff of the file that actually reads the
pref.

==Has an effect in==
* A list of every product affected by the preference, with version numbers
  noted in parantheses.

==Related bugs==
* A list of interesting and notable bugs that have something directly to do
  with this pref. Ideally should include the bug associated with the initial
  checkin.

==Related preferences==
* A list of preferences that affect the same feature, do the same thing, or
  replace/were replaced by this preference.

==See also==
Standard rules apply, as per In-House style.

==External links==
Standard rules apply, as per In-House style.

[[Category:Preferences]]

The "First checked in" section

Figuring out when and what

Bugzilla, LXR, and Bonsai are your friends. In general, you can find the first checkin this way:

1. Do a LXR search for the preference name
2. View the most likely file in LXR
3. Switch to the CVS Blame view in Bonsai (link at top of page in LXR) and find the line with the pref name
4. Click on the CVS username and file version link to the left of the line number to view a diff of the checkin that last edited that line; verify that the checkin actually added the preference and didn't (e.g.) update the line to use the newer pref API
5. If a bug number is listed in the CVS blame comment, check it to see if it describes adding the preference. If so, remember to reference the bug in the article's "Related bugs" section

Side note: when searching Bugzilla, if you just plug the preference name into the search field, Bugzilla tokenizes it and returns results that are often too general. You can search for an exact phrase in Bugzilla with the syntax ("search term") (a quoted parenthesized phrase).

It's not always so straightforward. For example, the steps for finding middlemouse.openNewWindow's first checkin went more like this:

1. Do a LXR search for "middlemouse.openNewWindow"
2. Find two references to setting the default value of the preference in all.js, and a promising-looking entry in contentAreaClick.js
3. Find out that the lines in contentAreaClick.js have been there since the file's creation (2000-11-22) -- verified by switching to the file's CVS "Full Change Log" and running a Full Source Diff between the first and second versions of the file
4. Flip back to all.js to see when the preference's default values were added
5. Discover from CVS blame that both instances were modified since being added (d'oh!)
6. Switch to all.js's change log and start looking backward from 2000-11-22 (we know the preference existed since then, as that's when it first appeared in contentAreaClick.js) - searching the page for instances of "middle"
7. Discover a promising checkin description: "3.96 / akkana%netscape.com / 2000-03-13 18:56 / 6085, middle mouse should load link in new window (r=alecf,puetzk@iastate.edu); 24571, middle-mouse paste should be pref-able (r=mcafee); plus nonmodal pref window (r=pavlov)."
8. Verify from the bug report that this is the checkin in question
9. Read the patch attached to the bug and learn that the patch was made to several files, and that navigator.js was the file that actually read the new pref
10. Run a Bonsai query for all checkins made to any branch (clear the default "HEAD" value) by "akkana%netscape.com" between 2000-03-13 00:00:00 and 2000-03-13 23:59:59
11. Finally find the information that the checkin created version 1.124 of navigator.js. Link to the hard-won Bonsai diff page from the article.

This may seem like a lot of work, but it also saves work -- if you know when the preference was checked in, you can determine with a fairly high degree of certainty which versions of which Mozilla products use the pref. It doesn't entirely replace real-world testing, but fortunately it's a wiki -- someone else can do the verification.

The information you gain while researching the first checkin is often invaluable to the rest of the article. I often do this section first, as I find related bugs, applicable products, and verification that the preference does something along the way.

Formatting

Bonsai lists the developer's CVS username, but it's nicer to use their real name in the link. Oftentimes their real name is listed in the Bugzilla bug for the checkin. If it isn't, Google can almost always find a page with their username and real name on it.

There are a couple of special cases regarding checkins. Some preferences are so old (e.g., advanced.mailftp) that they were used in Netscape Communicator, and we don't have access to Communicator's CVS logs. For these cases, try to find the earliest instance you can of the preference and cite it thusly:

Present since at least YYYY-MM-DD. Exact checkin date unknown.

The other special case is when the same preference is checked in to two separate projects (e.g., browser.backspace_action). This may become more common as much of SeaMonkey and Firefox's UI is implemented in entirely different files. For this case, a definition list pairing the product name and a link to the checkin suffices:

==First checked in==
;Mozilla Suite/SeaMonkey
:[http://bonsai.mozilla.org/... YYYY-MM-DD by So-And-So]
;Mozilla Firefox
:[http://bonsai.mozilla.org/... YYYY-MM-DD by What's-His-Name]

Versions affected

• Release dates for the Mozilla Suite with comments on related Netscape releases.
• Release dates for Phoenix/Firebird/Firefox.

Help Wanted

What would really be nice is help verifying that the "Has an effect in" information is accurate, and adding other products (I haven't been testing Thunderbird, Minimo, or Camino, for example). Eventually it'd be neat to have subcategories of this category for separate products (e.g., "Firefox 1.0.x Preferences"), but that's in the distant future for now.

Just for Firefox, or other MozApps too?

Is this category just for Firefox preferences, or will it contain corresponding articles for TB and Seamonkey preferences? --Mozcerize 08:59, 1 December 2005 (UTC)

All preferences, at least for now. --Np 15:27, 1 December 2005 (UTC)

Subcategories

Is there any use to creating categories under this one for people who want faster page loading/lower memory consumption, etc.? --Np 16:35, 7 December 2005 (UTC)

Perhaps. Here we have a situation where the feature to which an article corresponds may not be immediate from the title, and so any assistance we can give could be useful. The downside would be—as concluded when discussing the other categories—that it would be harder to locate a specific pref because you'd have to work through the categories (and hence would need to know in advance what the pref related to).

It really depends on how people use these pref articles. If they want this part of the KB to be an index of the available prefs then I don't think having subcategories is helpful. However, if you think people tend to browse the prefs, then categories make sense. An alternative would be to have separate articles which discuss specific groups of prefs in relation to a particular idea, and then promote these articles in the editable part of the category page. That way we get the best of both worlds, but of course it's a little more work. --Mozcerize 09:01, 8 December 2005 (UTC)

I'm thinking the preference would be in both the main index and a more specific category.--Np 05:27, 28 December 2005 (UTC)

It looks like MediaWiki will automatically divide up a large category into chunks (200 categorized page links per view) [1]. So if you're thinking to manually create subcategories just for faster page loading, there's probably not much point. --wintogreen 14:21, 28 December 2005 (UTC)

When I said "faster page loading", I meant "preferences that will affect page loading speed", not "faster page loading of the list of preferences". --Np 16:02, 28 December 2005 (UTC)

lol, I was imagining some poor sap with win95 on a dialup... uh, never mind. --wintogreen 16:20, 28 December 2005 (UTC)

Don't edit these pages to change your settings, dumbasses

Looks like we're still going to need a template telling people that this isn't the right place to change their settings. --Np 21:55, 13 December 2005 (UTC)

I threw together a template — suggestions and comments welcome before I go through and apply it to all the articles. (Example article with template applied) --Unarmed 04:41, 27 December 2005 (UTC)

• I don't see any reason to include the data type in the template.
• about:config should be before user.js because it's more user-friendly. Also, is there a need to say both about:config/user.js and link to an article that says the same thing?
• I'd prefer it there were only one box. --Np 04:53, 27 December 2005 (UTC)

Those sound like valid points to me. My rationale behind the data type was to eventually add some other useful information to the template to be put at the top of the article, but that's not really the main purpose of the template. I agree about the links; I'll fix that. As for "only one box", I was unsure how to approach this. Should the same text & link from the wrongtitle template be copied into the preferences template, to be shown in the same box? That might be the easiest way. There's no real reason to treat the wrongtitle template like a category, I guess; duplication in that regard would be fine. --Unarmed 05:41, 27 December 2005 (UTC)