178685 - Complete preference ref manual (for hidden prefs)

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: General, enhancement)

Description

[Bart Kelsey]

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]

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]

*** This bug has been marked as a duplicate of 158384 ***

Comment 3

[benc]

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]

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]

(sleep and caffeine shortage over here..)

Comment 6

[benc]

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]

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)]

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]

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]

See bug 198252 for anything network releated.

Comment 11

[Daniel Wang]

Attachment: Mozilla Preferences Manual (work-in-progress)

Comment 12

[Daniel Wang]

<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]

oops

Comment 14

[Ben Bucksch (:BenB)]

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)]

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]

Attachment: ~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)]

> doc structure:

Move Pref/ and customizing/ under profile/?

Comment 18

[Daniel Wang]

Attachment: ~160 prefs and counting

printing prefs done

Comment 19

[Daniel Wang]

Attachment: profile.zip (~200 prefs)

Comment 20

[Brian 'netdragon' Bober]

See also: http://preferential.mozdev.org/

Comment 21

[Daniel Wang]

online version of the draft (finally!):
http://wangrepublic.org/daniel/mozilla/prefs/

Comment 22

[Anne (:annevk)]

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]]

Reassigning Daniel's www.mozilla.org bugs to default assignee.

Comment 24

[David Boswell]

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]

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

david: feel free to veto :)

Comment 26

[Ben Bucksch (:BenB)]

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]]

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.

Comment 28

[Marc Bejarano]

chris: why the forward-dupe, in this case?

Comment 29

[Chris Ilias [:cilias]]

What is a "forward-dupe"?

Comment 30

[Marc Bejarano]

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]]

That's where the issue of where this doc goes has been discussed/decided.

Comment 32

[Marc Bejarano]

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]]

Okay, I'll switch it up.

Comment 35

[Daniel]

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]]

(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)]

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]]

[e-mail] : 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]

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]

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]]

(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]]

(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)]

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]

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/[e-mail]>) 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]]

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]]

Reopening for review by Sheppy.

Comment 47

[Ben Bucksch (:BenB)]

This should stay open.

Comment 48

[Benjamin Smedberg]

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]

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]

(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.