134676 - new profiles should have a user.js file that explains how to use it

Status: RESOLVED INCOMPLETE

(Core Graveyard :: Profile: BackEnd, enhancement)

Description

[timeless]

Mozilla end users never guess that the file they should be modifying is one 
that doesn't exist.  If new profiles had a file that looked something like:

// this file is for end user customizations of preferences,
// it affects prefs.js. Please edit :-)
// @see http://www.mozilla.org/unix/customizing.html for hints

Then users who twiddle in their profile would be more likely to twiddle the 
right file and be more likely to make useful tweaks.

I'm not sure if this is installer or profile manager (it looks like it might 
be a bit of both).

Comment 1

[Gervase Markham [:gerv]]

// this file is for end user customizations of preferences,
// it affects prefs.js. Please edit :-)
// @see http://www.mozilla.org/unix/customizing.html for hints

We need a better URL, for a start. How about:

/* This file exists to allow users to change operating parameters of 
 * Mozilla which are not exposed in the user interface. It is guaranteed
 * that Mozilla will never overwrite it.
 *
 * Parameters are changed by adding lines of the following form 
 * to the end of this file:

user_pref("<parameter name>", "<parameter value>");
e.g.
user_pref("browser.foo-widget.label", "Fred");

 * Some parameters take a number or true/false as their value, in which
 * case the second pair of quotes are omitted:

user_pref("browser.foo-widget.clickable", true);

 * Details of some customisations you might wish to make can be found here:
 * http://www.mozilla.org/unix/customizing.html
 *
 * Add parameters below this line. */

(The technical details are from memory, so may need slight adjustment. We should
also probably use real examples. We could also include the most common
customisations commented out. )

Gerv

Comment 2

[Daniel Veditz [:dveditz]]

Please do *not* check in a user.js.  Most users are not technically competent
and will not touch this file, and each file we open does take extra startup time
to read and parse.

If you must, check in a user.jsx that instructs people to rename it to user.js
if they want to use it. (See userChrome.csx which was renamed from .css for
exactly these same performance reasons -- every little bit adds up).

Comment 3

[Daniel Veditz [:dveditz]]

I dispute timeless's original assertion that user.js is "the file they should be
modifying". The vast majority of users have no business editing any pref file,
and the minority that do are better off learning to edit prefs.js so that later
mods using the UI can be saved. Values in user.js will override the and mods
made via the UI and saved in prefs.js -- this can and does confuse people when
their changes take effect for the rest of the session but have to be re-changed
each time.

For prefs that have no UI or other code that will manipulate them user.js has
its place, but it's primary attraction is that it can be modified while Mozilla
is running and that's not something we want to encourage anyway.

Comment 4

[Gervase Markham [:gerv]]

Now I think about it, dveditz is right. The problem here is that:

"Users need to be able to manipulate prefs which have no UI".

The current solution is editing prefs.js/users.js. I think this is the wrong
solution. The correct solution (as proposed in some other bug that I don't have
the number of) is two textboxes in some advanced panel of the prefs UI:

[ Pref name ] [ Pref value ]

It would do sanity checking on the values, of course. This way, users could read
a message which said "Set the pref foo.bar.baz to value quux" and just enter the
values into the boxes - no file editing, no "make sure you've shut down
Mozilla", etc. etc.

Gerv

Gerv

Comment 5

[Akkana Peck]

Gerv: that would be great, since it would allow users to change hidden prefs
while the app was running, something that's not possible now.

Would it be possible to include a link from that pref panel to the customizing
document, or some other document that might give users a hint what prefs can be
set?  Perhaps after finding a different place to put it in the gila hierarchy;
it's only under unix because nobody could think of a sensible place to put it
when it was created).  If we do this, it should be rewritten to list more prefs
and be clearer about prefs; I'll sign up to do that unless someone else would
rather have the job.

BTW, the biggest attraction of user.js isn't that it can be edited on the fly;
it's that it won't be overwritten randomly, e.g. I can put my internet search
pref there so it won't keep getting reset to netscape search.  It's also
convenient to put prefs I care about in user.js so that I can copy them to all
my machines; I can't copy prefs.js between profiles because it has absolute
paths in it, but I don't want to reset all my prefs by hand every time I create
a new profile, and user.js bridges that gap.

Comment 6

[timeless]

mpt has threatened to veto any ui for adding and removing or tweaking arbitrary 
prefs. and indeed akkana is correct about why we'd want people to consider 
user.js



vendors aren't required to ship this file, so that leave' mozilla's  audience. 
i'm not quite sure what it is, but it's clear that people do try to edit 
prefs.js and they do get burnt.

Comment 7

[Akkana Peck]

Hey, I know -- let's a have a pref for whether to show the advanced pref text
boxes!  [/me runs and hides from mpt]

I really like Gerv's suggestion.  I wish mpt weren't so against it.  It seems a
lot easier to describe to users than telling them to quit, edit a js file, and
restart.

Comment 8

[Gervase Markham [:gerv]]

> akkana is correct about why we'd want people to consider user.js

People don't like user.js because "it won't be overwritten arbitrarily" -
hopefully the same is true of prefs.js, otherwise your preferences would
disappear on a regular basis.

The advantage of user.js is that it can be edited while Mozilla is running -
that is, you don't need to make sure people have quit Mozilla before they edit
it, which is a pain to explain (and people get it wrong.) With the two-text-box
scheme, this isn't a problem, because people can edit prefs that way while
Mozilla is running - and explaining how to do is is _so_ much easier.

"Go to Preferences | Advanced | FooPanel. Put "network.foo.enable" in box A and
"true" in box B. Click "Set Pref"."

Gerv

Gerv

Comment 9

[Gervase Markham [:gerv]]

> People don't like user.js because "it won't be overwritten arbitrarily" -

That is to say:
"It won't be overwritten arbitrarily" is not the reason people like user.js -

Gerv

Comment 10

[Daniel Veditz [:dveditz]]

From the POV of the people trying to edit prefs.js while Mozilla is running,
their edits *do* get overwritten arbitrarily and that's why they like user.js

Anyway, your example directions showing off the superiority of the proposed two
box UI is missing
 "and click the non-existant 'boolean' radio button"

Otherwise you'd be making all prefs into strings, or requiring that users quote
all real strings in the box so we can tell the difference -- neither is all that
reasonable.

Comment 11

[Jamie Zawinski]

Why not have some sooper-sekrit UI panel that actually
shows you a scrolling list of *all* possible preferences?

Yes, that's a crappy, ugly, awful UI -- but still better
than editing a text file, no?  And it prevents typos,
and you could tag prefs with type/range.

Comment 12

[Daniel Veditz [:dveditz]]

That's what bug 110090 is about -- even has a patch.  

Doesn't help the case where there's a secret (or perhaps 3rd party) pref without
a default value and is thus not in the about:config list. Let the "all prefs
must have a default" vs. "defaults for rarely used prefs are bloat" flamewar
recommence

Comment 13

[Gervase Markham [:gerv]]

> From the POV of the people trying to edit prefs.js while Mozilla is running,
> their edits *do* get overwritten arbitrarily and that's why they like user.js

My point is that:
- there is a problem that edits to prefs.js get overwritten by Moz
One solution to that is
- have a users.js which doesn't get overwritten
Another solution is
- have an "any pref" UI in Mozilla, so you don't have to edit any files.

Users want a solution to the problem. They don't necessarily want users.js - the
other solution would also do.

Gerv

Comment 14

[Dan Howard]

A user in n.m.u.win32 recently suggested a seperate program with a GUI and
toggle switches for many of the "hidden" prefs. This would have the advantage of
being able to run while Mozilla is shut down, thereby being able to work on
prefs.js rather than user.js, avoiding the start-up slowing. Of course, neither
I nor the poster has any idea how to implement this, but it may provide an
alternative solution :)

Dan Howard

Comment 15

[Andrew Hagen]

The file should not be as welcoming to users as much as it inspires caution. 


/* This file exists to allow a user to manually change the settings  
 * Mozilla uses in the profile.
 *
 * To activate this file, rename it to user.js and restart Mozilla.
 *
 * Mozilla will not overwrite user.js. If there are corresponding entries 
 * in both user.js and prefs.js, the settings in user.js will override 
 * and take precedence.
 * 
 * Caution: Edit this file carefully, or you may burn your toes off. 
 *
 * Add manual settings below this line. */

Comment 16

[Steve Grecni]

How about changing the warning at the top of prefs.js to mention that you can
create a user.js and a short blurb on the ramifications of adding it and
settings the prefs in it.  No need to create yet another blank template.

I consider myself yet another fairly advanced user that wants to set some prefs
that don't get overwritten and it took me a bit to find out about user.js after
being frustrated that my antialias font settings were getting stomped on.

Something to this extent maybe?

/* prefs.js - Warning this file WILL get overwritten by mozilla.  You can 
 * create a user.js file in this same directory with preferences that will
 * override prefs.js. 
 * For more information visit http://www.mozilla.org/unix/customizing.html */

Comment 17

[Andrew Hagen]

That's bug 142590. 

Comment 18

[Michael Lefevre]

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

Comment 19

[Garth Wallace]

Meanwhile, the mozilla newsgroups are still being inundated with "You said to
add this line to rse.js, but I can't find a user.js! Help!"

Having an empty user.js created on installation if one does not already exist,
with a *short* description of what it is, should *not* be a problem. It's not
like regular users are going to stumble on it accidentally (aside from the
occasional power user exploring his profile directory for kicks,
potentially)--the only way people find out about it is through looking at "tips
& tricks"-type webpages, or getting told about it on newsgroups.

Comment 20

[Jonathan Watt [:jwatt]]

Is this valid anymore given about:config

Comment 21

[Samir Gehani]

adt: nsbeta1-

Comment 22

[Richard Trout]

I think this bug has been forgotten about, but there is now
userChrome-example.css and userContent-example.css, so why not name this file
user-example.js and include the instructions already discussed above? 99% of
users won't know it exists, but an example file doesn't hurt.

Comment 23

[Hanspeter Niederstrasser]

Attachment: adds user-example.jsx

Adds user-example.jsx to the default profile.  Takes into account comment #1 &
comment #15 (basic instructions slightly modified), plus comment #2 (no inital
user.js).

Given that "about:config" now exists, I'm submitting this patch to either 1)
have user-example.jsx added into the profile to fix this bug, or 2) draw
attention back to this bug so that it can be closed.

Comment 24

[Conrad Carlen (not reading bugmail)]

Comment on attachment 144543 [details] [diff] [review]
adds user-example.jsx

Even though we have about:config, this is still useful for overriding a pref
that's defined in all.js. r=ccarlen

Comment 25

[Hanspeter Niederstrasser]

Comment on attachment 144543 [details] [diff] [review]
adds user-example.jsx

Thoughts on this:

The new file was called "user-example.jsx" to be similar to
userContent-example.css.  The file extension was changed to .jsx because
comment #2 suggested user.jsx to avoid loading an empty file.

Would "user-example.js" be loaded on startup (because of the js extension), or
would it be a safe name?  If it's safe and doesn't get loaded on startup, I'll
change the patch to use "user-example.js" so that we're more consistent across
user files.

Comment 26

[Simon Paquet [:sipaq]]

Comment on attachment 144543 [details] [diff] [review]
adds user-example.jsx

Roc, this is a fairly simple patch. Could you give rs?

Comment 27

[Robert O'Callahan (:roc) (email my personal email if necessary)]

Comment on attachment 144543 [details] [diff] [review]
adds user-example.jsx

dveditz should sign off on this, I don't know much about the issues.

Comment 28

[Daniel Veditz [:dveditz]]

Comment on attachment 144543 [details] [diff] [review]
adds user-example.jsx

My opinion hasn't changed much in two years. Especially since
about:config was implemented I think even fewer people will
find this useful or necessary. But, OK, this isn't going to hurt much.

>Index: user-example.jsx
>===================================================================

Please use the name "user-example.js" for some consistency
with userChrome-example.css.  It won't be loaded; unlike
the default pref location where all *.js are loaded, in
the profile only specific files are loaded.

>+ * Caution: Edit this file carefully, or you may damage your settings.

The "damage your settings" bit needs rewording. Of course you can
damage settings by editing a settings file, what this needs to make
clear is that bad settings can prevent the browser from working at all,
or lower security defenses.


>+user_pref("<parameter name>", "<parameter value>");
>+e.g.
>+user_pref("extensions.irc.nickname" "MyNickName");

Example missing a comma.

>+user_pref("dom.event.contextmenu.enabled", true);

In the particular examples given, why would you put them in user.js
instead of editing using about:config or prefs.js with the browser not
running? Using user.js for any pref that has a UI is a bad idea
(see comment 3).

>+ * Details of some customizations you might wish to make can be found here:
>+ * http://www.mozilla.org/unix/customizing.html

Add #prefs to the end of that link, sending someone to the top of that
very long page from here would confuse them greatly.

sr rejected, but close. Please submit another patch. If it just
changes the things I mention you can carry over the r=.

Comment 29

[Hanspeter Niederstrasser]

Attachment: adds user-example.js v2

new patch for adding user-example.js into default profile.  Adding the actual
'user-example.js' file as a 2nd attachment.

Comment 30

[Hanspeter Niederstrasser]

Attachment: user-example.js

user-example.js with changes from comment #28.	

Also, I suggest adding the URL of Daniel Wang's Preference Manual
<http://wangrepublic.org/daniel/mozilla/prefs/>, but holding off since it is a
non-mozilla.org site.

Comment 31

[Daniel Veditz [:dveditz]]

Comment on attachment 157516 [details] [diff] [review]
adds user-example.js v2

sr=dveditz

Comment 32

[Daniel Veditz [:dveditz]]

Comment on attachment 157521 [details]
user-example.js

sr=dveditz

I'm OK with adding the wangrepublic.org link IFF it's OK with Daniel Wang, but
as an additional link, not the first link (in case the site goes away, but also
because it's too indepth for a first look).

Comment 33

[Hanspeter Niederstrasser]

(In reply to comment #32)

I emaild him 4 days ago and got no response.  The extra link is not necessary
for explaining user-example.js, so the file in attachment 157521 [details] can be checked
in as is.