I wrote this prefs document because I could not find effective prefs documentation for the variety of technical problems I encountered. It needs to be moved from www.packetgram.com (which is getting out of the mozilla-related content business). It also needs to be reviewed by an actual prefs engineer for accuracy. Can someone declare an ideal resting place in the mozilla-org tree, so if I get some time and do the cleanup my self, it will have a home?
iirc, chris has been working on documenting the preferences. she might be good reference here. a gazillion developers touch the prefs --i'm cc'ing a couple here (brian and seth) who might have some comments...
Hi I'm pulling together the Preference Reference that will help NCADM users do customizations that they cannot do using the NCADM tool (rtm around 8/30). The NCADM tool is a wizard that includes an Advanced Preferences page. Most of the customizations that a majority of our customers would want to do can be accomplished either via the wizard or the Advanced Preference Editor. CCK is a scaled back version of NCADM (or NCADM is an enhanced version of CCK). CCK is available for download; NCADM will be available for sale. Also, there are appendixes in the NCADM guide (still in process, almost ready for review) that deal with the preference architecture and remote administration. That said, it would be good at some point to sync up the commercial doc with the open source doc so that we are sending a uniform message. Let's put our heads together. Chris
I am not sure this document doesnt have anything we already have in our current preferences documentation. However if you guys/gals could get together with Christine and put out an overall document that would be great. If you disagree please let me know.
keyser: Where's the current documentation? I would have never written this if someone had given me the info I wanted, I had to figure all this out myself and use it to help answer a variety of networking questions I was being asked. Believe me, I got a day job, and plenty of bugs to go with it.
*** Bug 178685 has been marked as a duplicate of this bug. ***
Is this bug still valid? We already have http://mozilla.org/start/1.0/faq/general.html#1.5 btw, the packetgram.com url does not work; reporter, can you post the doc as an attachment? and is this bug a request for Help file content, or a request for mozilla.org content?
The packetgram URL does work for me. I did not understand the relationship of user.js and prefs.js until now. I'll make a draft that has the updated changes, and attach it here, then delete the file from the packetgram system.
I think this bug is still valid. The prefs documentation mentioned (http://mozilla.org/start/1.0/faq/general.html#1.5) was nigh impossible for me to find. I searched the help system for prefs.js and nothing came up. Searching mozilla brought me here, which brought me to it. Plus, it's quite *nix-specific. (e.g. Customizing Mozilla) (And I still can't find the pref for having MozillaMail check all IMAP folders for new messages. Scanning about:config for it now..)
Matthew: take a look at the document in the URL field, and tell me if it is missing anything you wanted to know.
brian: I know you are probably gone, but I finally sat down today and made a lot of the helpful corrections you provided. The URL is still the same. I need to re-read your comments again, do a final re-write+spellcheck, then I'll be punting this document into mozilla.
I'm going to remove the file and pref specific info from this file, and post it here. I've reopened the dupe for the per-file, per pref info.
Done. cvs -z9 commit -m "added "A Brief Gude to Preferences"" index.html briefprefs.html (in directory C:\HOME\mozilla-org\html\catalog\end-user\customizing\) Checking in index.html; /cvsroot/mozilla-org/html/catalog/end-user/customizing/index.html,v <-- index.html new revision: 1.6; previous revision: 1.5 done RCS file: /cvsroot/mozilla-org/html/catalog/end-user/customizing/briefprefs.html,v done Checking in briefprefs.html; /cvsroot/mozilla-org/html/catalog/end-user/customizing/briefprefs.html,v <-- briefprefs.html initial revision: 1.1
This is only about the preferences system, not the actual prefs themselves, right? Adding "generic" to the summary, assuming I am right. I thought this bug was about documenting the meaning of the individual prefs.
Not really. That's the funny thing, I wrote the doc, I wrote the bug, I put the URL in the bug. Nobody reads the doc. There used to be some pref-specific comments, but that was because the document lived on packetgram, which was a network-troubleshooting web site that I run. Whatever. Ben, if you can review this doc, esp checking to see if I got bnesse's feedback correct, I'll take ownership of this bug, and then mark it fixed. If this document just does not do what it should, comment away.
Created attachment 121869 [details] briefprefs.html clarify things a little bit and add some details on the preference system. to-do: - example of how to change preferences by code at run-time - naming conventions (bug 58816) - pref-by-pref reference Ben, are you the module owner of pref lib?
Created attachment 121908 [details] briefprefs.html (+ pref design spec)
Nope. I wrote that document because I couldn't live without it, and needed it as the basis of: http://www.mozilla.org/quality/networking/docs/netprefs.html If you sensed the focused "get in, say some stuff, and get out" style of this document, now you know why. My current job is to test just networking features. You've done a great job of improving the documentation. I have not reviewed the changes in detail, but I liked what I saw. Unfortunately, I won't be able to do a through reading anytime soon. I also am not the ideal person to review a document like this. If you think this is ready to go, check it in, and we'll take changes from people interactively. I've found that it is very hard to get people to review changes before you make them.
A comment about the section "Naming conventions" in attachement 121908. It uses several "capability.policy.default.foo" as example on how to name preferences. In fact, those preferences are named as required by the object names in class info and the method names in IDL. Of course, those have a naming convention, but this is not a preference naming convention. This suggests that caps prefs really have a option on how to name the preference, which doesn't exist.
Created attachment 121964 [details] briefprefs.html Axel, those preferences exist before any naming rule exist What I am trying to do is to look at how existing preferences are named, and then infer from them a naming scheme that is compatible with current ones. The scheme needs to be useful but not accurate as far as the history of naming is concerned. in this version I have added many more detail on how preferences are handled and many contextual links to LXR. I've also added some code examples.
Created attachment 122086 [details] 600+ preference names, descriptions and valid options This may prove helpful in creating comprehensive documentation for Mozilla preferences.
As a further explanation to comment #22: I currently run a project over at preferential.mozdev.org which aims to: (1) provide a consistent GUI interface to all Mozilla prefs (this is now subwhat superceded by about:config) and, more importantly, (2) document all Mozilla preferences I don't want to duplicate effort here, so if there's any way I can contribute to the Preferences documentation effort, I'd love to help. I have attached my project's source preferences file (which I later convert into two RDF files using a Perl script). It doesn't document all preferences, but has so far recorded about 600 preferences and their options. I'm happy to massage this into a suitable format for someone if there is interest.
Daniel: this document is great! Lots of things I've wanted to know, but never would have been able to cover myself. a couple comments: "arises" could be "arising" "In Netscape product" should be "In Netscape products" "On application exit, all user-set value" should be "values" (See more information) has the HREF extending over the last ")" The paragraph that is struck out about developers changing prefs is good info, but I think it should be moved into the same area you had your sample code, "Accessing preferences programmatically" I've read up to the namespace section, I'll try to digest the rest when I can.
some changes checked in I've rewritten the doc for users & administrators. reference to developers removed (will be moved to a separate doc). The doc will be temporary (should have been in /docs instead of catalog); I'll find a more appropriate place once I finished my other docs on user profile.
Created attachment 125156 [details] preference reference for developers no idea why I bothered it, but here we go, relieving myself of this doc
Ben - in 'What is a preference?' I believe you have a type in spelling of prefs.js as perfs.js - only a small thing but a potential trap for a newbie.
We have delayed this long enough -> P1
I just realised that an arbitariliy named file put on /usr/lib/mozilla-1.2.1/defaults/pref will be read, too. That's for mozilla-1.2.1, Red Hat release. If this is standard behaviour, it ought to be documented. Also, I'm trying to include default mail account settings in my site config, but can't figure out how. The problem is setting mail.server.<server name>.userName This is of course user specific, but the value is always identical to the Unix/Linux login name, so it ought to be possible to set up the value in all.js or similar. Oh, and mail.identity.<id>.useremail is needed as well, but that can be derived directly from the above info. maybe I could use the autoConfig method or .cfg file along with getenv(), but I haven't been able to get those methods to work yet (and getenv() is not available in from .js files.)
Richard: I made a quick scan and fixed one "perf" mispelling. Thanks for the feedback!
-> ownership to me. I've updated the document also to remove Netscape references. I think this document (mostly due to Daniel), is really in good shape now, so we should start talking to other people that have less updated prefs docs, and have them link to us. Here's a quick list I found: http://www.mozilla.org/start/1.4/faq/general.html#hidden-pref (no link to us). http://www.mozilla.org/unix/customizing.html#prefs http://www.mozilla.org/support/
FYI, there's a new preference being added in bug 86193.
Some comments: Firstly the guide doesn't explain how to set the default homepage. I've tried setting: pref("browser.startup.homepage", "http://www-xray.ast.cam.ac.uk/"); but firefox just dies if I put this in unix.js Also, the guide suggests that sysadmins set things in all.js. This doesn't work for most settings (at least on Linux). To set fonts, network proxies and paper sizes, I had to use unix.js.
> Firstly the guide doesn't explain how to set the default homepage. that's bug 178685 > Also, the guide suggests that sysadmins set things in all.js. This doesn't > work for most settings (at least on Linux). To set fonts, network proxies and > paper sizes, I had to use unix.js. The doc says the platform-specific file (e.g unix.js) is loaded after all.js . As Mozilla code changes constantly, we don't want to document what prefs are loaded in platform-specific file.
I'm not spending a lot of time w/ firefox, so if people can figure out more of what goes on there, lets start a new document or make changes to this one.
The document in the URL is outdated. First, the directory structure for prefs has changed. Also, There's no information about how to lock a preference in the UI, which can be critical for admins, and I haven't found a right way to do this, just ignore the changes but the preference is reachable, and unknown value. Please work a little more on this, even with basic examples (I've tried changing the cache disk size, if you want to take it as example), together with an additional file, in order to separate from original .js files.
The proper way to change preferences in a profile is via about:config these days. As for the other items you mentioned, I'm not reading every single prefs bugs. Is there a bug number you can provide, or can you be more specific? For example, I don't know what you mean about the directory structure...
(In reply to comment #37) > The proper way to change preferences in a profile is via about:config these days. This contrasts with what's told in the url, since they're supposed to be guidelines for corporation admins to provide specific default settings for their corporations, avoiding spending a lot of time doing repeatedly and by hand the same setting once and again. > As for the other items you mentioned, I'm not reading every single prefs bugs. > Is there a bug number you can provide, or can you be more specific? For example, > I don't know what you mean about the directory structure... Take a look at Mozilla 1.7.x directory structure, which is different from previous versions, and the .js preferences files aren't in the same paths as before.
Way back when the very first version of Netscape was released it was very messy for an administrator to set site defaults, and it has got harder and harder as the years have gone by. The document http://www.mozilla.org/catalog/end-user/customizing/briefprefs.html is good and describes a nice simple scheme, but I'm not convinced it works any more (a previous comment hinted about new directory structures). I have created a file defaults/pref/all.js on a Windows installation of Firefox 1.0, but it seems to be ignored both for new and existing users. Have I done something silly or is this other people's experience? This stuff is important! If you want people to get a good impression of Mozilla you need to help the guy who administers a large site make life as easy as possible for the thousands of users under his or her control.
> The document > http://www.mozilla.org/catalog/end-user/customizing/briefprefs.html > is good and describes a nice simple scheme, but I'm not convinced it works any > more (a previous comment hinted about new directory structures). I have created > a file defaults/pref/all.js on a Windows installation of Firefox 1.0 Hmmm. I think it might just be a matter of updating firefox.js instead of all.js. I fully agree with your comments, though. Actually, this may not be a documentation issue at all; perhaps the problem is not that the mechanisms are undocumented, but that they are unnecessarily complex. I mean, why do we have to mess around with byteshift etc.? And why do you have to set the config file name in the first place? Why doesn't "general.config.filename" default to a file that is normally not there, and may thus be added by a system admin without having to update file from the distribution? Or even better, how about a site config *directory* where all files are read as part of the init sequence?
I'm still here, and can do some updating, although I don't use firefox much (I use a lot of camino and mozilla). The best way to keep this document updated is to reference bugs that describe prefs system changes. I rarely get updates from the developers, so I depend on contributors to point me in the right direction.
http://www.mozilla.org/catalog/end-user/customizing/briefprefs.html says "feedback and comments here", so here is mine I can't find out what fcc_folder_picker_mode means. I've come across it in my thunderbird installation, while trying to debug something else. But I don't know what it means, and there does not seem to be a cannonical reference to all these preferences anywhere in the documenation. I'd like to see a full, maintained, list of what they all are and mean. Does anyone know where it is?
I've recently had time to re-read this document, in the context of a new-found curiosity about Camino... I've made some gramatical and link cleanup changes, and also moved about:config to the top, in refrence to how to make changes. I think this servers the most common audience. Here's my personal todo list: users.js - should emphasis the advantage of being able to use comments (per #3) I've reviewed all the comments up to #36, about the directory info being out of date. I'll look into that now.
Since the original document, I've learned enough c++ to read some of the pref loading code. Changes: 1- added updated discussion about greprefs, application prefs. TODO: extensions? 2- added updated list of application pref files, based on examining released versions on my Mac. 3- added further emphasis on about:config, by explaining localization features. 4- re-writing file changing sections to simply say how changing files affects the behavior. If you are a sys admin, a hacker, doing a distro, coding, etc, you get to figure out what files to hack yourself. This increases the learning curve for people who are just trying to hack *a* preference, and people hacking pref files. (Also opens door for people interested in a specific app to write app-specific prefs docs....) 5- add discussion of hidden, default-less prefs. I should update the file in the next few days... editing offline right now.
Please add a link to this document to the config file documentation, which seems to be at http://developer.mozilla.org/en/docs/Automatic_Mozilla_Configurator:Locked_config_settings Also, it would be nice if the documentation spoke about what config files are automatically overwritten during an automatic upgrade. I have had problems with customizing the all.js file, and then having all those changes lost the next time there was an upgrade. Using a file like AAALocal_prefs.js might work better.
If this bug is assigned to nobody@ then it shouldn't have ASSIGNED status.
app_dir is not defined anywhere in the document and is used once.
See also http://kb.mozillazine.org/About:config_entries http://kb.mozillazine.org/Category:Preferences http://kb.mozillazine.org/Mail_and_news_settings http://preferential.mozdev.org/preferences.html http://www-archive.mozilla.org/projects/embedding/prefs.html (probably outdated) https://developer.mozilla.org/en/Mozilla/Preferences (and what it resends to) https://developer.mozilla.org/en/Mozilla/Preferences/Preference_reference ("this page is not complete") https://developer.mozilla.org/en/Mozilla/Preferences/Mozilla_networking_preferences (In reply to email@example.com from comment #49) > app_dir is not defined anywhere in the document and is used once. IIUC that value is not a preference. See also http://kb.mozillazine.org/Installation_directory
Automatically closing all bugs that have not been updated in a while. Please reopen if this is still important to you and has not yet been corrected.
I believe that this request is not INVALID: the problem is well defined, and still exists today. OTOH fixing it might be a lot of low-priority trouble, so WONTFIX might perhaps be an acceptable resolution — one which should, however, be set (or not) by an owner or peer of the module in question, i.e. not by lowly triager me.
Reopening for review by Sheppy.
This is important and should stay open and be fixed, preferably by a volunteer.
FWIW, there exists now a "Config Descriptions" extension for Firefox and SeaMonkey (but not Thunderbird, I don't know why) which fishes the comments in the pref source files and adds those comments as an additional column in about:config. Of course it can't say anything for prefs which are undocumented in the source, but otherwise IMHO it is a must-have for the power user or developer. It might be of some help to whoever (if anyone) decides to work on this bug.
As filed, this bug is about "the pref system" not individual prefs. That is already documented, both in nsIPrefBranch.idl and on MDN. For docs on specific prefs, we should have another bug (and in many cases we shouldn't document the prefs at all).
Why I am here: * https://developer.mozilla.org/en-US/docs/Mozilla/Preferences/A_brief_guide_to_Mozilla_preferences * "Feedback and comments to bug 158384" Areas affected: * "The administrator may edit the all.js† default pref file (install_directory/defaults/prefs/all.js)." * "The administrator may add an all-companyname.js preference file (install_directory/defaults/prefs/all-companyname.js)." Issues: * The "install_directory/defaults/prefs/" directory mentioned does not exist by default. "install_directory/defaults/pref/" does. Is the documentation correct? * If you copy a prefs.js from a user profile to install_directory/defaults/prefs/all-company.js or install_directory/defaults/pref/all-company.js then delete the user profile and start Thunderbird, you would expect the user preferences to be restored, but they are not. Workaround: * The only way I could get the preferences to be set by default is by putting prefs.js in "app_dir/defaults/profile/". This is not covered in this article.
I've updated the docs as appropriate. Despite the instruction, it's considered bad form to comment in really old bugs such as this one.
I already covered that in the "Why I am here" section in my previous comment, so perhaps that needs updating in the article too.