Complete preference ref manual (for hidden prefs)

RESOLVED WONTFIX

Status

Developer Documentation
General
--
enhancement
RESOLVED WONTFIX
15 years ago
a year ago

People

(Reporter: Bart Kelsey, Assigned: sheppy)

Tracking

Details

(Whiteboard: read discussion on bug 330858 about where this belongs, URL)

Attachments

(1 attachment, 3 obsolete attachments)

(Reporter)

Description

15 years ago
So far, the only real way I've been able to find any documentation on Mozilla's
hidden preferences are by doing searches on Google or wading through the
(incompletely documented) js files themselves.  As a power user, many of the
undocumented options that I have managed to dig up information on have been of
interest to me.  It would be nice if I could find these all documented in one
place, either on the web or in Mozilla's help system.

Comment 1

15 years ago
I'd be willing to make a long-term commitment to document network-related prefs.

Is there a master document that lists prefs one by one?

Comment 2

15 years ago

*** This bug has been marked as a duplicate of 158384 ***
Status: NEW → RESOLVED
Last Resolved: 15 years ago
Resolution: --- → DUPLICATE

Comment 3

14 years ago
REOPEN: this bug wanted more specific info on each pref.

I don't know about the rest of the browser, but I'm going to be doing this for
neworking prefs.
Status: RESOLVED → REOPENED
Resolution: DUPLICATE → ---
Summary: Preferences (in prefs.js and defaults/pref/*.js) should be fully documented → File and prefinfo about <PROFILE>/*.js and <browser>/defaults/pref/*)

Comment 4

14 years ago
Ben, I don't see how http://bugzilla.mozilla.org/show_bug.cgi?id=158384 differs.
Seems that 158384 should cover all prefs, so this bug is still a dupe of that.

Updated

14 years ago
Summary: File and prefinfo about <PROFILE>/*.js and <browser>/defaults/pref/*) → File and pref finfo about <PROFILE>/*.js and <browser>/defaults/pref/*)

Comment 5

14 years ago
(sleep and caffeine shortage over here..)
Summary: File and pref finfo about <PROFILE>/*.js and <browser>/defaults/pref/*) → File and pref info about <PROFILE>/*.js and <browser>/defaults/pref/*)

Comment 6

14 years ago
Writing about how the prefs mechanism works is significantly different than
writing about how each pref affects the browser behavior. That is actually how
engineering and QA divide the pref bugs.

I think that we've got the prefs back-end material documented well in that bug,
so I'd like to separate the per file, per pref issues here.

Putting them all in one bug/document is just too messy. If you look at my
current draft document, you can see some (soon to be removed) comments about
specific prefs and pref files.

Comment 7

14 years ago
Perhaps the documentation should be generated from whatever comes out of bug
195845, so that there aren't two independent places documenting the same thing.
Depends on: 195845

Comment 8

14 years ago
If anything, then the other way around. Bug 17199 would also need very detailed
information about each pref, including documentation about possible values (for
enums).

Comment 9

14 years ago
Both of those bugs sound like features to the prefs system, but separately, I
think the behavior needs to be well documented. Some of these prefs are very
complicated, and a full write-up should be put somewhere.

I've decided to create a guide to networking preferences, for my own sanity, if
not for anyone else' benefit, I'm going to make a list of networking preferences
w/ links to any useful information I can readily find. see bug 

Eventually, I'll have time to write coherently about each pref. This might occur
i n one doc, although my thinking is that the prefs are best explained in
individual write-ups of the modules they affect.

I think we need a similar document for all prefs, that lives some place central.

Comment 10

14 years ago
See bug 198252 for anything network releated.
Depends on: 198252

Updated

14 years ago

Comment 11

14 years ago
Created attachment 125210 [details]
Mozilla Preferences Manual (work-in-progress)

Comment 12

14 years ago
<PROFILE>/*.js & <browser>/defaults/pref/* have been taken care of by bug 158384
(just need to find an appropriate place for the doc).
-> me , and making Brant my editor :-)

(oh, btw, red is for hidden pref and blue for non-hidden prefs. black's for
update-later ;-p )
Assignee: rudman → stolenclover
Status: REOPENED → NEW
Component: User → webmaster@mozilla.org
Product: Documentation → mozilla.org
QA Contact: rudman → brantgurganus2001
Summary: File and pref info about <PROFILE>/*.js and <browser>/defaults/pref/*) → Complete preference ref manual (for hidden prefs)
Version: unspecified → other

Updated

14 years ago
Status: NEW → ASSIGNED
Component: webmaster@mozilla.org → Bugzilla: Keywords & Components

Comment 13

14 years ago
oops
Component: Bugzilla: Keywords & Components → webmaster@mozilla.org

Comment 14

14 years ago
Daniel Wang, that's great, thanks, esp. that you have text for each possible
value (where it makes sense), e.g. editor.encode_entity. The more structure the
better :).

Comment 15

14 years ago
In case it's of any use for you, I tried to invent an XML data format for the
prefs documentation. It's a draft and probably wrong or lacking at places, but
maybe you can use it or some of its ideas.
<http://www.bucksch.com/1/projects/mozilla/17199/>

Comment 16

14 years ago
Created attachment 125500 [details]
~70 prefs and counting

I think I've config & AutoConfig figured out, so now I can fix bug 158384 for
end users easy.

what do you guys think about the following doc structure:

moz-org/docs/end-user/	 [sigh, should be moz-org/end-user/]
  customizing/
    theme?
    command-line-args.html  [move from moz-org/docs]
  pref/ 	 [or config/? or just customizing/?]
    index.html
    pref.html	 [current briefprefs.html file]
    config.html  [info on .cfg and .jsc config files]
    seamonkey/	[for Mozilla app suite]
      index.html   [index to complete pref manual]
      hidden.html  [reduced version, contains only useful prefs]
    browser/  [for future standalone browser]
    mail/     [for future standalone mail]
  profile/

Updated

14 years ago
Attachment #125210 - Attachment is obsolete: true

Comment 17

14 years ago
> doc structure:

Move Pref/ and customizing/ under profile/?

Comment 18

14 years ago
Created attachment 129685 [details]
~160 prefs and counting

printing prefs done
Attachment #125500 - Attachment is obsolete: true

Updated

14 years ago
Blocks: 203937

Updated

14 years ago
Blocks: 158384
No longer blocks: 203937

Updated

14 years ago
Depends on: 222973, 222974

Comment 19

14 years ago
Created attachment 134853 [details]
profile.zip (~200 prefs)
Attachment #129685 - Attachment is obsolete: true

Updated

14 years ago
QA Contact: brantgurganus2001 → stolenclover

Updated

13 years ago
Blocks: 103361
See also: http://preferential.mozdev.org/

Comment 21

13 years ago
online version of the draft (finally!):
http://wangrepublic.org/daniel/mozilla/prefs/
QA Contact: whiteclover79-bug → benc

Comment 22

13 years ago
If this is going to be moved to mozilla.org it should match the style and markup
guide, which it currently does not. If desired I can point out the problems in
more detail.

Updated

13 years ago
Blocks: 170662
Reassigning Daniel's www.mozilla.org bugs to default assignee.
Assignee: danielwang → nobody
Status: ASSIGNED → NEW
Product: mozilla.org → Websites

Comment 24

9 years ago
The www.mozilla.org site should no longer host documentation.  If there is still a need for this it should be added to MDC.  Moving to Mozilla Developer Center product for discussion.
Component: www.mozilla.org → Documentation Requests
Product: Websites → Mozilla Developer Center
QA Contact: benc → doc-request
Version: other → unspecified

Comment 25

9 years ago
why MDC?  isn't the proposed documentation for  users?  -> SUMO

david: feel free to veto :)
Component: Documentation Requests → Knowledge Base Articles
Product: Mozilla Developer Center → support.mozilla.com
QA Contact: doc-request → kb-articles

Comment 26

9 years ago
Hidden prefs are not for end-users. The docs is for developers and power users. Given that web developer docs are on MDC, I think it belongs there.
Marking as dupe of bug 330858.
Quick note about bug 330858: That bug has been ping ponged quite a bit from product to product; so please read the bug history and comments before moving it or resolving it.
Status: NEW → RESOLVED
Last Resolved: 15 years ago9 years ago
Resolution: --- → DUPLICATE
Duplicate of bug: 330858

Comment 28

9 years ago
chris: why the forward-dupe, in this case?
What is a "forward-dupe"?

Comment 30

9 years ago
you made this bug a duplicate of a bug that was opened later than this (the original) bug report.  forward as in "forward in time".
That's where the issue of where this doc goes has been discussed/decided.

Comment 32

9 years ago
but this bug already had lots of blocks, depends ons, history, and even attachments.  would you mind if i duped the other one here and we copied over any relevant info you find missing?
Okay, I'll switch it up.
Severity: major → enhancement
Status: RESOLVED → REOPENED
Component: Knowledge Base Articles → Documentation Requests
Product: support.mozilla.com → Mozilla Developer Center
QA Contact: kb-articles → doc-request
Resolution: DUPLICATE → ---
Whiteboard: read discussion on bug 330858 about where this belongs

Updated

9 years ago
Duplicate of this bug: 330858

Comment 35

7 years ago
At Comment 26, Ben Bucksch wrote:-
Hidden prefs are not for end-users. The docs is for developers and power users.
Given that web developer docs are on MDC, I think it belongs there.

and at Comment 24 here and at comment 5 of Bug 330858, David Boswell wrote:-
The www.mozilla.org site should no longer host documentation.  If there is
still a need for this it should be added to MDC.  Moving to Mozilla Developer
Center product for discussion.

One has to ask "When does one move from beibg an end-users to a power user?" When one wants to make the program do something different to other users??

Somebody, somewhere (Mozilla Suite time frame I think) thought that an end-user (or maybe a "baby power user") might want to make particular changes to program operation, so allowed users to write preference alterations into a user.js file which was then incorporated into prefs.js when the program, Mozilla Suite, was run.

But NO WE CANNOT HAVE USERS MAKING CHANGES

Additionally, as we were/are told in the mozilla.support.seamonkey newsgroup, SeaMonkey Suite has been officially dropped by Mozilla, as far as development is concerned, and the code-base "given" to a volunteer group of programmers.

How are these volunteers, and others, to be able to do what they're supposed to do, development-wise, if they don't have access to the "complete" listing of the preferences??

Updated

7 years ago

Updated

7 years ago
(In reply to comment #35)
[...]
> How are these volunteers, and others, to be able to do what they're supposed to
> do, development-wise, if they don't have access to the "complete" listing of
> the preferences??

By trying to make sense out of the source, I suppose, which I don't think is very efficient performance-wise, or else by bugging "former Mozilla Suite devs" (gone over to Firefox now, maybe) with questions, which is even more annoying.

Comment 37

7 years ago
MDC is accessible by everyone. Target group is Mozilla devs, web developers and advanced users. If somebody edits users.js, he's an advanced user.
If you complain that there is no complete doc on MDC either, that's what this bug is about.
Status: REOPENED → NEW

Updated

7 years ago
feedback@lauchpad.net : you have already added that "see also" URL https://launchpad.net/bugs/233901 before, and it was removed. If you want it to stay, please say why.

Comment 39

7 years ago
I have a strong suspicion it's a bot that works off references to our bugzilla in launchpad issues. So I doubt you'll be able to convince it :)

Comment 40

5 years ago
Today, MozillaZine is unavailable.  This means user-oriented information about preference variables at <http://kb.mozillazine.org/About:config_entries> and <http://kb.mozillazine.org/Category:Preferences> cannot be accessed.  

Since users are still being advised in the news.mozilla.org newsgroups to go to about:config to change preference variables, this information is vital for end-users.  It should not be restricted to developers or worded such that only developers can understand it.
(In reply to David E. Ross from comment #40)
> Today, MozillaZine is unavailable.  This means user-oriented information
> about preference variables at
> <http://kb.mozillazine.org/About:config_entries> and
> <http://kb.mozillazine.org/Category:Preferences> cannot be accessed.  
> 
> Since users are still being advised in the news.mozilla.org newsgroups to go
> to about:config to change preference variables, this information is vital
> for end-users.  It should not be restricted to developers or worded such
> that only developers can understand it.

The Mozillazine KB is usually up; and when it isn't, its admins can be reached via the Mozillazine forum, like with the message I just posted at http://forums.mozillazine.org/viewtopic.php?f=11&t=556178&p=12281885#p12281885 — it may take some time (a few hours, in the worst of cases) for the site to come up again, but it always does.
(In reply to David E. Ross from comment #40)
> Today, MozillaZine is unavailable.  This means user-oriented information
> about preference variables at
> <http://kb.mozillazine.org/About:config_entries> and
> <http://kb.mozillazine.org/Category:Preferences> cannot be accessed.  
> 
> Since users are still being advised in the news.mozilla.org newsgroups to go
> to about:config to change preference variables, this information is vital
> for end-users. 

I don't understand that logic. If a user is instructed to edit a hidden pref in about:config, why is it vital to know what *every* preference does?

> It should not be restricted to developers or worded such
> that only developers can understand it.

Info on MDN is not restricted to anyone. 

If you're concerned about kb.mozillazine.org downtime, remember that MDN is a wiki and you can copy the info there. And since both MDN and the Mozillazine KB are both wikis, you can fix any wording you think users won't understand.

Comment 43

5 years ago
The *nature* of the documentation on MDN is not suitable to end-users, because it's too brief. Often, it's useless text "font.size = Sets the font size" which not even I can understand.

Comment 44

5 years ago
Re comment #42:  
>  I don't understand that logic. If a user is instructed to edit 
>  a hidden pref in about:config, why is it vital to know what 
>  *every* preference does?  

It's not that I want to know what every preference variable does.  It's that, when any preference variable is cited in a support message, I want some details about it before I set it.  

For example, in the mozilla.support.seamonkey newsgroup, a thread with the subject "YOUTUBE SLUGGISH in SEA MONKEY!" (see <news://news.mozilla.org:119/5b2d124a-6317-4d60-a8f5-0bb74ba31d22@googlegroups.com>) suggested changing the setting for the preference variable browser.sessionstore.interval without explaining in sufficient (for me) detail what that preference variable really controls.  When the MozillaZine site again became available, I found that this preference variable is not listed in either of the two Web pages I cited in comment #40.  Without a good description for a preference variable, I cannot tell what risk I am taking by changing it.
Component: Documentation Requests → Documentation
Product: Mozilla Developer Network → Mozilla Developer Network
We try to only use the "Documentation" component for large documentation jobs. For other work, please edit the MDN directly (and jump in #devmo if you need help!).
Status: NEW → RESOLVED
Last Resolved: 9 years ago4 years ago
Resolution: --- → FIXED
Reopening for review by Sheppy.
Assignee: nobody → eshepherd
Status: RESOLVED → REOPENED
Resolution: FIXED → ---

Comment 47

4 years ago
This should stay open.
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation
We should *not* try to document every possible preference. Most of them are internal to specific code, and neither MDN or end-user docs should mention them at all.
Status: REOPENED → RESOLVED
Last Resolved: 4 years ago4 years ago
Resolution: --- → WONTFIX

Comment 49

4 years ago
Benjamin, perhaps thought should then be given to changing the name, as your *preference* seems to differ from my *preference*

Sure, there are some settings that cannot/must not be left to the user, but preferences, surely, should be up to the user.

Comment 50

a year ago
(In reply to Daniel from comment #49)
> Sure, there are some settings that cannot/must not be left to the user, but
> preferences, surely, should be up to the user.

Preferences that should not be 'left to the user' should not be available to the user.

Everything that is available/visible to - and most importantly, changeable by - the user - ie, in about:config - should be fully documented, no exceptions.
You need to log in before you can comment on or make changes to this bug.