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.
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?
*** This bug has been marked as a duplicate of 158384 ***
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.
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.
(sleep and caffeine shortage over here..)
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.
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.
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).
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.
<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 )
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 :).
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/>
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/
> doc structure: Move Pref/ and customizing/ under profile/?
Created attachment 129685 [details] ~160 prefs and counting printing prefs done
Created attachment 134853 [details] profile.zip (~200 prefs)
See also: http://preferential.mozdev.org/
online version of the draft (finally!): http://wangrepublic.org/daniel/mozilla/prefs/
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.
Reassigning Daniel's www.mozilla.org bugs to default assignee.
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.
why MDC? isn't the proposed documentation for users? -> SUMO david: feel free to veto :)
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.
chris: why the forward-dupe, in this case?
What is a "forward-dupe"?
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.
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.
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??
(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.
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.
firstname.lastname@example.org : 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.
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 :)
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.
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.
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:email@example.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.
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!).
Reopening for review by Sheppy.
This should stay open.
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.
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.
(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.