Last Comment Bug 178685 - Complete preference ref manual (for hidden prefs)
: Complete preference ref manual (for hidden prefs)
Status: RESOLVED WONTFIX
read discussion on bug 330858 about w...
:
Product: Developer Documentation
Classification: Other
Component: General (show other bugs)
: unspecified
: All All
: -- enhancement with 2 votes (vote)
: ---
Assigned To: Eric Shepherd [:sheppy]
:
Mentors:
http://www.mozilla.org/projects/embed...
: 330858 (view as bug list)
Depends on: 195845 198252 222973 222974
Blocks: 103361 158384 170662
  Show dependency treegraph
 
Reported: 2002-11-06 10:18 PST by Bart Kelsey
Modified: 2016-03-17 08:40 PDT (History)
26 users (show)
See Also:
QA Whiteboard:
Iteration: ---
Points: ---


Attachments
Mozilla Preferences Manual (work-in-progress) (41.37 KB, text/html)
2003-06-09 00:05 PDT, Daniel Wang
no flags Details
~70 prefs and counting (84.00 KB, text/html)
2003-06-12 04:42 PDT, Daniel Wang
no flags Details
~160 prefs and counting (118.75 KB, text/html)
2003-08-12 14:20 PDT, Daniel Wang
no flags Details
profile.zip (~200 prefs) (28.76 KB, application/octet-stream)
2003-11-05 11:27 PST, Daniel Wang
no flags Details

Description Bart Kelsey 2002-11-06 10:18:15 PST
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 benc 2002-12-18 22:12:15 PST
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 Daniel Wang 2003-01-01 16:49:45 PST

*** This bug has been marked as a duplicate of 158384 ***
Comment 3 benc 2003-02-07 09:05:46 PST
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.
Comment 4 rudman 2003-02-07 09:17:50 PST
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.
Comment 5 benc 2003-02-07 10:13:03 PST
(sleep and caffeine shortage over here..)
Comment 6 benc 2003-02-07 10:17:50 PST
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 Vaclav Dvorak 2003-03-15 14:34:52 PST
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.
Comment 8 Ben Bucksch (:BenB) 2003-03-15 15:25:32 PST
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 benc 2003-03-19 09:33:33 PST
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 benc 2003-05-09 10:43:59 PDT
See bug 198252 for anything network releated.
Comment 11 Daniel Wang 2003-06-09 00:05:25 PDT
Created attachment 125210 [details]
Mozilla Preferences Manual (work-in-progress)
Comment 12 Daniel Wang 2003-06-09 00:12:03 PDT
<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 )
Comment 13 Daniel Wang 2003-06-09 00:20:34 PDT
oops
Comment 14 Ben Bucksch (:BenB) 2003-06-09 00:24:39 PDT
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 Ben Bucksch (:BenB) 2003-06-09 00:26:35 PDT
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 Daniel Wang 2003-06-12 04:42:20 PDT
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/
Comment 17 Ben Bucksch (:BenB) 2003-06-12 06:58:22 PDT
> doc structure:

Move Pref/ and customizing/ under profile/?
Comment 18 Daniel Wang 2003-08-12 14:20:14 PDT
Created attachment 129685 [details]
~160 prefs and counting

printing prefs done
Comment 19 Daniel Wang 2003-11-05 11:27:56 PST
Created attachment 134853 [details]
profile.zip (~200 prefs)
Comment 20 Brian 'netdragon' Bober 2004-06-08 01:32:59 PDT
See also: http://preferential.mozdev.org/
Comment 21 Daniel Wang 2004-07-30 19:22:40 PDT
online version of the draft (finally!):
http://wangrepublic.org/daniel/mozilla/prefs/
Comment 22 Anne (:annevk) 2004-09-20 12:00:36 PDT
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.
Comment 23 Reed Loden [:reed] (use needinfo?) 2006-01-21 13:08:32 PST
Reassigning Daniel's www.mozilla.org bugs to default assignee.
Comment 24 David Boswell 2008-08-28 12:50:10 PDT
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.
Comment 25 Marc Bejarano 2008-10-01 14:49:39 PDT
why MDC?  isn't the proposed documentation for  users?  -> SUMO

david: feel free to veto :)
Comment 26 Ben Bucksch (:BenB) 2008-10-01 14:55:57 PDT
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.
Comment 27 Chris Ilias [:cilias] 2008-10-01 18:28:30 PDT
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.

*** This bug has been marked as a duplicate of bug 330858 ***
Comment 28 Marc Bejarano 2008-10-02 08:36:23 PDT
chris: why the forward-dupe, in this case?
Comment 29 Chris Ilias [:cilias] 2008-10-02 15:42:56 PDT
What is a "forward-dupe"?
Comment 30 Marc Bejarano 2008-10-06 10:49:47 PDT
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".
Comment 31 Chris Ilias [:cilias] 2008-10-06 20:58:51 PDT
That's where the issue of where this doc goes has been discussed/decided.
Comment 32 Marc Bejarano 2008-10-07 15:17:47 PDT
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?
Comment 33 Chris Ilias [:cilias] 2008-10-07 22:18:59 PDT
Okay, I'll switch it up.
Comment 34 Chris Ilias [:cilias] 2008-10-07 22:19:33 PDT
*** Bug 330858 has been marked as a duplicate of this bug. ***
Comment 35 Daniel 2010-02-08 05:04:53 PST
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??
Comment 36 Tony Mechelynck [:tonymec] 2010-02-08 06:21:32 PST
(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 Ben Bucksch (:BenB) 2010-02-08 06:32:56 PST
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.
Comment 38 Tony Mechelynck [:tonymec] 2010-02-11 13:10:43 PST
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 Nickolay_Ponomarev 2010-02-11 13:32:20 PST
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 David E. Ross 2012-09-12 10:07:13 PDT
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.
Comment 41 Tony Mechelynck [:tonymec] 2012-09-12 10:31:09 PDT
(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.
Comment 42 Chris Ilias [:cilias] 2012-09-15 00:50:08 PDT
(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 Ben Bucksch (:BenB) 2012-09-15 02:14:03 PDT
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 David E. Ross 2012-09-15 10:23:25 PDT
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.
Comment 45 John Karahalis [:openjck] 2012-12-04 07:41:02 PST
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!).
Comment 46 John Karahalis [:openjck] 2012-12-04 08:10:24 PST
Reopening for review by Sheppy.
Comment 47 Ben Bucksch (:BenB) 2012-12-04 12:15:20 PST
This should stay open.
Comment 48 Benjamin Smedberg AWAY UNTIL 2-AUG-2016 [:bsmedberg] 2013-02-15 15:16:09 PST
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.
Comment 49 Daniel 2013-02-16 01:02:27 PST
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 Charles 2016-03-17 08:40:03 PDT
(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.

Note You need to log in before you can comment on or make changes to this bug.