1Common NetSurf user options
2---------------------------
3
4This document outlines the common configuration options supported by
5  the NetSurf core.
6
7Overview
8========
9
10The users configurations are generally stored in a "Choices" file and
11  are loaded at browser startup. Most user interfaces provide a way
12  to configure these parameters in a manner consistant with the
13  toolkit in use.
14
15The user choices are stored as a simple key:value list.
16
17Each entry has a type, one of: boolean, integer, unsigned integer,
18  hexadecimal colour value or string.
19
20General Options
21===============
22
23 Option Key           | Type   | Default   | Description
24 -------------------- | ------ | --------- | --------------------------------
25 http_proxy           | bool   | false     | An HTTP proxy should be used.
26 http_proxy           | bool   | false     | An HTTP proxy should be used.
27 http_proxy_host      | string | NULL      | Hostname of proxy.
28 http_proxy_port      | int    | 8080      | Proxy port.
29 http_proxy_auth      | int    | 0         | Proxy authentication method.
30 http_proxy_auth_user | string | NULL      | Proxy authentication user name
31 http_proxy_auth_pass | string | NULL      | Proxy authentication password
32 http_proxy_noproxy   | string | localhost | Proxy omission list
33 font_size            | int    | 128       | Default font size / 0.1pt.
34 font_min_size        | int    | 85        | Minimum font size.
35 font_sans            | string | NULL      | Default sans serif font
36 font_serif           | string | NULL      | Default serif font
37 font_mono            | string |  NULL     | Default monospace font
38 font_cursive         | string |  NULL     | Default cursive font
39 font_fantasy         | string |  NULL     | Default fantasy font
40 accept_language      | string |  NULL     | Accept-Language header.
41 accept_charset       | string |  NULL     | Accept-Charset header.
42 memory_cache_size    | int    | 12MiB     | Preferred maximum size of memory cache in bytes.
43 disc_cache_size      | uint   | 1GiB      | Preferred expiry size of disc cache in bytes.
44 disc_cache_age       | int    | 28        | Preferred expiry age of disc cache in days.
45 disc_cache_path      | string |  NULL     | Path to disc cache, NULL means to use system path |
46 block_advertisements | bool   | false     | Whether to block advertisements
47 do_not_track         | bool   | false     | Disable website tracking [1]
48 send_referer         | bool   | true      | Whether to send the referer HTTP header.
49 foreground_images    | bool   | true      | Whether to fetch foreground images
50 background_images    | bool   | true      | Whether to fetch background images
51 animate_images       | bool   | true      | Whether to animate images
52 enable_javascript    | bool   | false     | Whether to execute javascript
53 script_timeout       | int    | 10        | Maximum time to wait for a script to run in seconds
54 expire_url           | int    | 28        | How many days to retain URL data for.
55 font_default         | int    | 0         | Default font family
56 ca_bundle            | string | NULL      | ca-bundle location
57 ca_path              | string | NULL      | ca-path location
58 cookie_file          | string | NULL      | Cookie file location
59 cookie_jar           | string | NULL      | Cookie jar location
60 homepage_url         | string | NULL      | Home page location
61 search_url_bar       | bool   | false     | search web from url bar
62 search_provider      | int    | 0         | default web search provider
63 url_suggestion       | bool   | true      | URL completion in url bar
64 window_x             | int    | 0         | default x position of new windows
65 window_y             | int    | 0         | default y position of new windows
66 window_width         | int    | 0         | default width of new windows
67 window_height        | int    | 0         | default height of new windows
68 window_screen_width  | int    | 0         | width of screen when above options were saved
69 window_screen_height | int    | 0         | height of screen when above options were saved
70 toolbar_status_size  | int    | 6667      | default size of status bar vs. h scroll bar
71 scale                | int    | 100       | default window scale
72 incremental_reflow   | bool   | true      | Whether to reflow web pages while objects are fetching
73 min_reflow_period    | uint   | 25        | Minimum time (in cs) between HTML reflows while objects are fetching
74 core_select_menu     | bool   | false     | Use core selection menu
75
76[1] http://www.w3.org/Submission/2011/SUBM-web-tracking-protection-20110224/#dnt-uas
77
78Fetcher options
79===============
80
81 Option Key               | Type | Default | Description
82 ------------------------ | -----| ------- | -----------------------------------
83 max_fetchers             | int  | 24      | Maximum simultaneous active fetchers
84 max_fetchers_per_host    | int  | 5       | Maximum simultaneous active fetchers per host. (<=option_max_fetchers else it makes no sense) [2]
85 max_cached_fetch_handles | int  |  6      | Maximum number of inactive fetchers cached. The total number of handles netsurf will therefore have open is this plus option_max_fetchers.
86 suppress_curl_debug      | bool | true    | Suppress debug output from cURL.
87 target_blank             | bool | true    | Whether to allow target="_blank"
88 button_2_tab             | bool | true    | Whether second mouse button opens in new tab.
89
90[2] Note that rfc2616 section 8.1.4 says that there should be no more
91     than two keepalive connections per host. None of the main browsers
92     follow this as it slows page fetches down considerably.
93     See https://bugzilla.mozilla.org/show_bug.cgi?id=423377#c4
94
95
96PDF / Print options
97===================
98
99 Option Key             | Type | Deflt | Description
100 ---------------------- | ---- | ----- | ------------------------------------
101 margin_top             | int  | 10    | top margin of exported page
102 margin_bottom          | int  | 10    | bottom margin of exported page
103 margin_left            | int  | 10    | left margin of exported page
104 margin_right           | int  | 10    | right margin of exported page
105 export_scale           | int  | 70    | scale of exported content
106 suppress_images        | bool | false | suppressing images in printed content
107 remove_backgrounds     | bool | false | turning off all backgrounds for printed content
108 enable_loosening       | bool | true  | turning on content loosening for printed content
109 enable_PDF_compression | bool | true  | compression of PDF documents
110 enable_PDF_password    | bool | false | setting a password and encoding PDF documents
111
112System colours
113==============
114
115These are the css system colours which the browser also uses to style
116generated output.
117
118 Option Key                     | Type   | Default
119 ------------------------------ | ------ | ----------
120 sys_colour_ActiveBorder        | colour | 0x00d3d3d3
121 sys_colour_ActiveCaption       | colour | 0x00f1f1f1
122 sys_colour_AppWorkspace        | colour | 0x00f1f1f1
123 sys_colour_Background          | colour | 0x006e6e6e
124 sys_colour_ButtonFace          | colour | 0x00f9f9f9
125 sys_colour_ButtonHighlight     | colour | 0x00ffffff
126 sys_colour_ButtonShadow        | colour | 0x00aeaeae
127 sys_colour_ButtonText          | colour | 0x004c4c4c
128 sys_colour_CaptionText         | colour | 0x004c4c4c
129 sys_colour_GrayText            | colour | 0x00505050
130 sys_colour_Highlight           | colour | 0x00c00800
131 sys_colour_HighlightText       | colour | 0x00ffffff
132 sys_colour_InactiveBorder      | colour | 0x00f1f1f1
133 sys_colour_InactiveCaption     | colour | 0x00e6e6e6
134 sys_colour_InactiveCaptionText | colour | 0x00a6a6a6
135 sys_colour_InfoBackground      | colour | 0x008fdfef
136 sys_colour_InfoText            | colour | 0x00000000
137 sys_colour_Menu                | colour | 0x00f1f1f1
138 sys_colour_MenuText            | colour | 0x004e4e4e
139 sys_colour_Scrollbar           | colour | 0x00cccccc
140 sys_colour_ThreeDDarkShadow    | colour | 0x00aeaeae
141 sys_colour_ThreeDFace          | colour | 0x00f9f9f9
142 sys_colour_ThreeDHighlight     | colour | 0x00ffffff
143 sys_colour_ThreeDLightShadow   | colour | 0x00ffffff
144 sys_colour_ThreeDShadow        | colour | 0x00d5d5d5
145 sys_colour_Window              | colour | 0x00f1f1f1
146 sys_colour_WindowFrame         | colour | 0x004e4e4e
147 sys_colour_WindowText          | colour | 0x00000000
148