Closed Bug 158384 Opened 22 years ago Closed 11 years ago

Need generic preferences documentation

Categories

(Developer Documentation Graveyard :: General, defect, P1)

Tracking

(Not tracked)

RESOLVED WORKSFORME

People

(Reporter: benc, Assigned: sheppy)

References

(Blocks 1 open bug, )

Details

Attachments

(2 files, 3 obsolete files)

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...
-->cwozniak.
Assignee: rudman → cwozniak
>What is a preference?
Preferences are not JavaScript variables. Preferences are stored in a (more or
less) human readable form which is parsed by the JavaScript parser. Some day we
would like to remove this dependency because JavaScript is overkill for this
need (and opens us up to security issues.)

>Prefernce load order: That should be PreferEnce ;)
Again preferences are not JavaScript variables, but they will be resolved in
favor of the last entry read... unless locking (AutoConfig) is involved. Let's
not go there just now...

I don't really understand item 3 "Use default, hard-coded value for prefs".
Assuming that a value exists in *any* preference file, it will override any
value set in the code.

>Because prefs.js is loaded last... changes to a profile should made to the
prefs.js.
prefs.js is a generated file. Users should not be messing with it unless they
are absolutely certain of what they are doing.

"user.js" is actually the last file loaded. This file is only read in and never
written out, and is where the user should be installing their own personal
preferences (the default homepage is a common one). This way user can create a
new profile, drag their "user.js" file into it, and immediately be in a familiar
environment. The other advantage is that you can have comments or commented out
preferences in user.js and they won't be purged the next time the file is
written out.

>Modifying preference files: 
Again, users shouldn't really be mucking about in prefs.js.

>Systems administrators can modify <mozilla>/defaults/prefs/
System Administrators would generally use AutoConfig to do this sort of thing
(through CCK). Hacking individual installations is tedious.

>Care should be taken in modifying values in the "default/prefs" files...
If you (and here you means a developer) changes a value in "default/prefs", that
becomes the new default. If that value is set to the same value that is in
prefs.js, then yes, the value will be removed from prefs.js the next time it is
saved. If, however, you change the value from "0" to "3", and prefs.js has a
user value of "1", the user value will remain in effect because it is *not* the
same as the default value.
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. ***
Summary: "Brief Guide to Mozilla Preferences" needs to be moved to mozilla.org → Need preferences (prefs.js) documentation
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?
Severity: major → normal
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.
Summary: Need preferences (prefs.js) documentation → Need preferences documentation
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.
Summary: Need preferences documentation → Need generic preferences documentation
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.
Attached file briefprefs.html (obsolete) —
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?
Attached file briefprefs.html (+ pref design spec) (obsolete) —
Attachment #121869 - Attachment is obsolete: true
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.
Attached file briefprefs.html (obsolete) —
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.
Attachment #121908 - Attachment is obsolete: true
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.
Depends on: 203937
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.
no idea why I bothered it, but here we go, relieving myself of this doc
Attachment #121964 - Attachment is obsolete: true
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.
Depends on: 222973
Depends on: 178685
We have delayed this long enough -> P1
Severity: normal → major
Priority: -- → P1
QA Contact: rudman → stolenclover
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/
Assignee: cwozniak → benc
Blocks: 170662
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?



(In reply to comment #40)

> Hmmm. I think it might just be a matter of updating firefox.js instead of all.js.
> 

Sadly this doesn't seem to work either. I quite agree with your comments: the
problem is that the configuration mechanism is
(a) too complex
(b) doesn't conform with the documentation (i.e. is BUGGY!)
(c) keeps on changing from release to release.

I have been installing netscape and its successors on multi-user Unix systems
ever since Netscape first came out, and there has never been a release that
didn't force me to write a wrapper script to apply my site configurations. My
actual configuration lines have hardly changed at all, apart from when the
preference files switched to Javascript syntax, but every release I have wasted
hours fathoming out where to put them.

I've now hit a dead end trying to install it on a Windows system, because my
Windows scripting skills are pretty non-existent: if there isn't a simple
interface then I'm stuck.
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.
Status: NEW → ASSIGNED
No longer blocks: 170662
Some feedback
1) there're also [mozilla app directory]/greprefs/*.js which are common among
all gecko applications [except Minimo, there's a bug on that, iirc], and which
also used to set default values.
2) in firefox extensions can have their own default preferences set in
[extension dir]/defaults/preferences/*.js, where [extension dir] is ususally
[profile]/extensions/[extension GUID], but may also be in [app
dir]/extensions/[GUID] for global installations, I think.
3) "A preferences file is a simple JavaScript file" is quite confusing. It isn't
Javascript file anymore. It used to be, that's where .js extension and some of
syntax come from. But it's not JS, it is parsed not by js but by another
(simpler) parser.
4) A link to http://preferential.mozdev.org/ (unless something better is put on
moz.org) and a notice about about:config
<http://kb.mozillazine.org/index.phtml?title=About:config> would be nice.
5) nit: "In the profile directory are two user pref files: prefs.js and user.js.
prefs.js is automatically generated ". A new line after the first sentence would
make the reading easier, I think. (ie. "user.js\n prefs.js") The dot separating
two sentences is not visible enough  (as there are too many dots nearby :)
6) "None <a href="#filew-def-special">platform-specific</a> .js". The target
anchor does not exist in the document.
7) "Usually when the user specifically commits a preference change via user
interface such as the Preferences dialog, the application saves the change by
overwriting prefs.js". Suggesting <em>Ususually</em>. For example, changing it
from about:config doesn't seem to rewrite prefs.js on current trunk firefox
build. Clicking ok in options dialog does rewrite it though. In fact the rewrite
only happens *only* when nsIPrefService::savePrefFile(null) is called. Afaik,
many/most extensions don't do that.
8) "Note: <b>Note</b> preference names are case-sensitive."
9) "If you have Mozilla 1.4". Moz 1.4 or later or Firefox

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.
Assignee: benc → nobody
Component: Help Viewer → Documentation Requests
Product: Documentation → Mozilla Developer Network
QA Contact: danielwang → doc-request
If this bug is assigned to nobody@ then it shouldn't have ASSIGNED status.
Status: ASSIGNED → NEW
app_dir is not defined anywhere in the document and is used once.
Component: Documentation Requests → Documentation
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.
Status: NEW → RESOLVED
Closed: 12 years ago
Resolution: --- → INVALID
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.
Status: RESOLVED → REOPENED
Resolution: INVALID → ---
Reopening for review by Sheppy.
Assignee: nobody → eshepherd
This is important and should stay open and be fixed, preferably by a volunteer.
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation
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.
Status: REOPENED → RESOLVED
Closed: 12 years ago11 years ago
Resolution: --- → WORKSFORME
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.
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: