Category talk:Preferences: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
Line 162: Line 162:
I have only just noticed this, but when integer preferences have their values listed as third-level headings, things become rather confusing. (See for example [[privacy.popups.disable from plugins]]; at first glance, the values look like they are part of the third-level headings. Or worse, the third-level headings look like they are part of the value!) Does anyone have an opinion on using a list for values instead? (Of course, it would take time to convert all exisiting articles to this format.) --[[User:Mozcerize|Mozcerize]] 09:04, 14 June 2006 (UTC)
I have only just noticed this, but when integer preferences have their values listed as third-level headings, things become rather confusing. (See for example [[privacy.popups.disable from plugins]]; at first glance, the values look like they are part of the third-level headings. Or worse, the third-level headings look like they are part of the value!) Does anyone have an opinion on using a list for values instead? (Of course, it would take time to convert all exisiting articles to this format.) --[[User:Mozcerize|Mozcerize]] 09:04, 14 June 2006 (UTC)
: I think it's fine as is. People normally wouldn't look at the TOC without looking below. Sure, it looks a little weird, but this format works perfectly fine for all other values.--[[User:Np|Np]] 15:11, 14 June 2006 (UTC)
: I think it's fine as is. People normally wouldn't look at the TOC without looking below. Sure, it looks a little weird, but this format works perfectly fine for all other values.--[[User:Np|Np]] 15:11, 14 June 2006 (UTC)
::Agreed, there's no problem with the non-integer prefs. --[[User:Mozcerize|Mozcerize]] 13:38, 15 June 2006 (UTC)

Revision as of 13:38, 15 June 2006

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:

{{preference|pref=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 valid 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 parentheses.

==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. List bugs in ascending order.

==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

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)

I would like to create a seperate category for Thunderbird preferences and modify "Configuration (Thunderbird)" to point to it instead of "Preferences". Most of those articles have a "Has an effect in" section that explicitly lists what applications and what versions it effects. It appears that out of the 101 articles only browser.cache.*, config.trim on minimize, Network.http.use-cache and javascript.* effect Thunderbird despite the preference being listed in Thunderbirds equivalent of about:config. I did a quick sanity check and looked for some of the non-Thunderbird preferences such as Advanced.mailftp in Thunderbird\defaults\pref\mailnews.js (which defines most default preferences) and couldn't find them.

Doesn't TB read from all.js?--Np 02:29, 3 February 2006 (UTC)
Yes. mailnews.js is the most relevant because all Mozilla preferences appear to be defined even if they're useless. all.js for example defines advanced.mailftp despite Thunderbird not supporting ftp. I'm sure I'll make some mistakes but I want to identify which preferences actually effect Thunderbird and make that information easy to find. Tanstaafl 03:07, 3 February 2006 (UTC)

Note that both the existing category and http://kb.mozillazine.org/About:config_entries has no entries for Mail.* or MailNews.* and http://kb.mozillazine.org/About:config_entries never mentions whether a preference applies to Thunderbird. I can think of about a dozen mail specific preferences I'd like to write a reference article for. It looks like we have already added Thunderbird specific categories for everything but "Profiles" and "Migration (mail)". Any preference articles I'd write for Thunderbird would have Wintogreens tag mentioning it could also apply to Mozilla Suite/SeaMonkey. Comments? Tanstaafl 02:12, 3 February 2006 (UTC)

Any new preference articles you write, regardless of what they apply to, should be put into Category:Preferences. You should use the same format as the existing articles. Beyond that, I don't have any problem. You could do like what we did with security prefs - that category is a subcategory of prefs and articles are in both of them.--Np 02:29, 3 February 2006 (UTC)
No problem. I had planned on following the same format and putting it in both the generic and the thunderbird specific category. I should have been more explicit. Tanstaafl 03:07, 3 February 2006 (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)

Preferences template

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)
I like the idea of this template, but wouldn't it be better to link to the Editing configuration page rather than specify about:config or "user.js"? IMO too many articles in the KB link directly to about:config (or some other specific method) when suggesting a pref change, rather than letting Editing configuration introduce the concept of preference-setting for them. (That article is a bit rough at the moment, but I will happily tidy it up if we intend to use it more. In particular, I will make the point that changing user.js, although more advanced, facilitates easy migration of settings between profiles.) --Mozcerize 11:01, 29 December 2005 (UTC)
I'd be willing to change the link in the template to that article once it's cleaned up. Now it's too short and curt to be terribly useful. I'm going to go ahead and put this template as-is in the "Structure" layout above.--Unarmed 17:19, 3 January 2006 (UTC)

Unused and obsolete preferences (resolved)

I don't see much use in listing preferences that are not used. How about we make a subcategory for unused preferences and put them all in there? When I say "unused" I mean "doesn't do anything in the latest release".--Np 04:11, 3 January 2006 (UTC)

That works for me. Something like Category:Preferences (obsolete) ?--Unarmed 17:19, 3 January 2006 (UTC)
That reads to me like "the obsolete category Preferences". Also, obsolete implies that the preference was used at one point, and I want this to apply also to preferences that were never used. I'd prefer Category:Unused preferences--Np 17:23, 3 January 2006 (UTC)
Okay. Just to clarify, though, is the last version of the Suite before it became SeaMonkey included in the term "latest release"? My vote would be no. --Unarmed 19:44, 3 January 2006 (UTC)
Indeed, we need to decide where the cut-off point for "new" releases is. It causes no problems to move prefs which were never used to another home, but would it be a pain for users of older versions to have to look in two places for their prefs. Also, would you intend to remove older prefs from the about:config entries article? --Mozcerize 11:30, 4 January 2006 (UTC)
About the about:config article... What we're doing with that is as soon as we get a whole branch of it done, we're taking out the branch in that article and pointing users to this category. I do believe we should also migrate the unused prefs. So to answer your question, "the older prefs will be removed from that article under the same criteria as the existing prefs".--Np 18:42, 5 January 2006 (UTC)
For the cut-off point, how about listing all preferences that do something in the latest released version, any current development version, and any version that was obsoleted less than 3 months ago. So this would mean that Firefox 1.0.7, Firefox 1.5, and trunk/branch nightlies should have their prefs listed, while 1.0.6 should not.--Np 17:49, 16 January 2006 (UTC)
That sounds reasonable to me. --Unarmed 19:14, 16 January 2006 (UTC)

Moving some of this to a separate page

It's been suggested that the style/rules content on this page be moved to a separate article, to be placed in Category:MozillaZine Knowledge Base organization. Ideas on how this should fit, and/or what the article should be named? --Unarmed 03:20, 6 January 2006 (UTC)

I made the suggestion, however, I think that this discussion belongs on the Knowledge_Base_changes page where more people can see it. I added my comments under the Article-writing guidelines heading.Alice Wyman 10:49, 17 January 2006 (UTC)

Third-level headings for pref values

If there are only a set number of valid 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.

I have only just noticed this, but when integer preferences have their values listed as third-level headings, things become rather confusing. (See for example privacy.popups.disable from plugins; at first glance, the values look like they are part of the third-level headings. Or worse, the third-level headings look like they are part of the value!) Does anyone have an opinion on using a list for values instead? (Of course, it would take time to convert all exisiting articles to this format.) --Mozcerize 09:04, 14 June 2006 (UTC)

I think it's fine as is. People normally wouldn't look at the TOC without looking below. Sure, it looks a little weird, but this format works perfectly fine for all other values.--Np 15:11, 14 June 2006 (UTC)
Agreed, there's no problem with the non-integer prefs. --Mozcerize 13:38, 15 June 2006 (UTC)