Rearrange settings in documentation

This commit adjust settings documentation to reflect reorganization
made during v4 dev-cycle.

Author: deathaxe

docs/settings.md

@@ -12,32 +12,29 @@ If at any time you wish to erase your customizations and start afresh, you can s
 
 ## General Settings
 
-* `cite_auto_trigger` (`true`): if `true`, typing e.g. `\cite{` brings up the citation completion quick panel, without the need to type `C-l,x`. If `false`, you must explicitly type `C-l,x`.
-* `ref_auto_trigger` (`true`): ditto, but for `\ref{` and similar reference commands
-* `fill_auto_trigger` (`true`): ditto, but for package and file inclusion commands (see Fill Helper feature above)
-* `env_auto_trigger` (`true`): ditto, but for environment completions
-* `glossary_auto_trigger` (`true`): ditto, but for glossary completions
-* `tex_directive_auto_trigger` (`true`): ditto, but for tex directive completions
-* `cwl_autoload` (`true`): whether to load cwl completions based on packages (see the CWL feature)
-* `cwl_completion` (`prefixed`): when to activate the cwl completion poput (see CWL feature above)
-* `cwl_list` (`["latex-document.cwl", "tex.cwl", "latex-dev", "latex-209.cwl", "latex-l2tabu.cwl", "latex-mathsymbols.cwl"]`): list of cwl files to load
-* `keep_focus` (`true`): if `true`, after compiling a tex file, ST retains the focus; if `false`, the PDF viewer gets the focus. Also note that you can *temporarily* toggle this behavior with `C-l,t,f`.This can also be overridden via a key-binding by passing a `keep_focus` argument to `latextools_jumpto_pdf`.
- **Note**: In general, `keep_focus` set to `true` tries to mean "do not *change* the focus". This isn't always possible, since several of the viewers will steal focus by default. In those circumstances, LaTeXTools tries to actively return the focus to Sublime. To disable this, set the `disable_focus_hack` setting to `true`.
- **Note**: If you are on either Windows or Linux you may need to adjust the `sublime_executable` setting for this to work properly. See the [Platform settings](#platform-specific-settings) below.
-* `forward_sync` (`true`): if `true`, after compiling a tex file, the PDF viewer is asked to sync to the position corresponding to the current cursor location in ST. You can also *temporarily* toggle this behavior with `C-l,t,s`. This can also be overridden via a key-binding by passing a `forward_sync` argument to `latextools_jumpto_pdf`.
-* `tex_file_exts` (`['.tex']`): a list of extensions that should be considered TeX documents. Any extensions in this list will be treated exactly the same as `.tex` files. See the section on [Support for non-`.tex` files](#support-for-non-tex-files).
-* `latextools_set_syntax` (`true`): if `true` LaTeXTools will automatically set the syntax to `LaTeX` when opening or saving any file with an extension in the `tex_file_exts` list.
 * `overwrite_goto_overlay` (`true`): Set this to `false` to disable the overwriting of the goto overlay for the hotkey `C-r` and `C-shift-r` You can still access the "table of content quickpanel" via `C-l, C-r` and `C-shift-l, C-r
 * `enable_smart_paste` (`true`) if smart paste is enabled LaTeXTools will overwrite the C-v command and analyze the clipboard content to check whether it should execute an action. So you can just paste image urls or paths into Sublime Text and it will automatically download the image and create a figure environment.
-* `use_biblatex`: (`false`): if `true` LaTeXTools will use BibLaTeX defaults for editing `.bib` files. If `false`, LaTeXTools will use BibTeX defaults. See the section on [Support for Editing Bibliographies](#support-for-editing-bibliographies) for details.
+* `latextools_set_syntax` (`true`): if `true` LaTeXTools will automatically set the syntax to `LaTeX` when opening or saving any file with an extension in the `tex_file_exts` list.
+* `tex_file_exts` (`['.tex']`): a list of extensions that should be considered TeX documents. Any extensions in this list will be treated exactly the same as `.tex` files. See the section on [Support for non-`.tex` files](#support-for-non-tex-files).
 * `tex_spellcheck_paths` (`{}`): A mapping from the locales to the paths of the dictionaries. See the section [Spell-checking](#spell-checking).
 * `word_count_sub_level` (`"none"`): controls the level at which subcounts of words can be generated. Valid values are: `"none"`, `"part"`, `"chapter"`, and `"section"`.
-* `temp_files_exts`: list of file extensions to be considered temporary, and hence deleted using the `C-l, backspace` command.
-* `temp_files_ignored_folders`: subdirectories to skip when deleting temp files.
 * `auto_match_escaped_brackets`: auto-pair escaped brackets when typing (e.g. `\[` expands to `\[\]`)
 * `auto_match_math_brackets`: auto-pair special math related brackets when typing (e.g. `\left[` expands to `\left[\right]`)
 * `auto_match_spaces`: auto-pair leading and trailing spaces between brackets e.g. `(|)` expands to `( | )` by pressing <kbd>space</kbd> and `( | )` to `(|)` by pressing <kbd>backspace</kbd>
 
+## Completion Settings
+
+* `command_completion` (`prefixed`): when to activate the cwl completion poput (see CWL feature above)
+* `cwl_autoload` (`true`): whether to load cwl completions based on packages (see the CWL feature)
+* `cwl_list` (`["latex-document.cwl", "tex.cwl", "latex-dev", "latex-209.cwl", "latex-l2tabu.cwl", "latex-mathsymbols.cwl"]`): list of cwl files to load
+* `cite_auto_trigger` (`true`): if `true`, typing e.g. `\cite{` brings up the citation completion quick panel, without the need to type `C-l,x`. If `false`, you must explicitly type `C-l,x`.
+* `ref_auto_trigger` (`true`): ditto, but for `\ref{` and similar reference commands
+* `env_auto_trigger` (`true`): ditto, but for environment completions
+* `fill_auto_trigger` (`true`): ditto, but for package and file inclusion commands (see Fill Helper feature above)
+* `glossary_auto_trigger` (`true`): ditto, but for glossary completions
+* `tex_directive_auto_trigger` (`true`): ditto, but for tex directive completions
+* `smart_bracket_auto_trigger` (`true`): Controls whether the various fill-helpers should try to insert a completing `}`, `]`, or `)` when inserted and either the <kbd>C-l,C-f</kbd> or <kbd>C-l,x</kbd> keybindings were used to trigger the completion. This attempts to be smart about where to place the bracket, but may not work for all cases, particularly when a command is spread across mutliple lines. You can also use the toggle <kbd>C-l,t,a,b</kbd>.
+
 ## Preview Settings
 
 ### Math-Live Preview Settings
@@ -66,6 +63,12 @@ or a color name (e.g. `"yellow"`) If it is the empty string `""` it will be gues
 * `preview_popup_image_size` (`200`) and `preview_phantom_image_size` (`150`): The image size in the preview image popup and phantoms. These are the outer dimensions of the maximal size. The image will be scaled down to fit into these dimensions. It can either be an number or an array, which consist of two numbers (x and y), e.g. [200, 150].
 * `preview_image_scale_quotient` (`1`): Increase this number to get a better resolution on high dpi displays. Control the thumbnail image size, which will be generated to preview images, that are not natively supported (like pdf files). E.g. a image size of 300 with a scale quotient of 2 will create a thumbnail with the size 600, which is scaled down in the popup.
 
+## Temporary file settings
+
+* `temp_files_exts`: list of file extensions to be considered temporary, and hence deleted using the `C-l, backspace` command.
+* `temp_files_ignored_folders`: subdirectories to skip when deleting temp files.
+* `temp_files_prompt_on_delete` (`false`): If true, deleting temporary files will display an "Are you sure" prompt.
+
 ## Platform-Specific Settings
 
 This section refers to setting that can be found in a platform-specific block for each platform, i.e., `"osx"`, `"windows"`, or `"linux"`.
@@ -145,21 +148,36 @@ Any other value will be interpreted as the default.
 
 ## Viewer Settings
 
- * `viewer` (`""`): the viewer you want to use. Leave blank (`""`) or set to `"default"`for the platform-specific viewer. Can also be set to `"preview"` if you want to use Preview on OS X, `"okular"` if you want to use Okular on Linux, `"zathura"` is you want to use Zathura on Linux, or `"command"` to run arbitrary commands. For details on the `"command"` option, see the section on the [Command Viewer](available-viewers.md#command-viewer).
- * `viewer_settings`: these are viewer-specific settings. Please see the section on [Viewers](available-viewers.md#viewers) or the documentation on [Alternate Viewers](available-viewers.md#alternate-viewers) for details of what should be set here.
- * `open_pdf_on_build` (`true`): Controls whether LaTeXTools will automatically open the configured PDF viewer on a successful build. If set to `false`, the PDF viewer will only be launched if explicitly requested using `C-l,v` or `C-l,j`.
-  * `disable_focus_hack` (`false`): if `true`, the focus hack that LaTeXTools uses to return focus to Sublime in some circumstances will not be run. **Note**: This does not mean that the *viewer* won't steal the focus, only that LaTeXTools won't try to steal the focus back.
+* `forward_sync` (`true`): if `true`, after compiling a tex file, the PDF viewer is asked to sync to the position corresponding to the current cursor location in ST. You can also *temporarily* toggle this behavior with `C-l,t,s`. This can also be overridden via a key-binding by passing a `forward_sync` argument to `latextools_jumpto_pdf`.
+
+* `keep_focus` (`true`): if `true`, after compiling a tex file, ST retains the focus; if `false`, the PDF viewer gets the focus. Also note that you can *temporarily* toggle this behavior with `C-l,t,f`.This can also be overridden via a key-binding by passing a `keep_focus` argument to `latextools_jumpto_pdf`.
+  
+  **Note**: In general, `keep_focus` set to `true` tries to mean "do not *change* the focus". This isn't always possible, since several of the viewers will steal focus by default. In those circumstances, LaTeXTools tries to actively return the focus to Sublime. To disable this, set the `disable_focus_hack` setting to `true`.
+  
+  **Note**: If you are on either Windows or Linux you may need to adjust the `sublime_executable` setting for this to work properly. See the [Platform settings](#platform-specific-settings) below.
+
+* `viewer` (`""`): the viewer you want to use. Leave blank (`""`) or set to `"default"`for the platform-specific viewer. Can also be set to `"preview"` if you want to use Preview on OS X, `"okular"` if you want to use Okular on Linux, `"zathura"` is you want to use Zathura on Linux, or `"command"` to run arbitrary commands. For details on the `"command"` option, see the section on the [Command Viewer](available-viewers.md#command-viewer).
+
+* `viewer_settings`: these are viewer-specific settings. Please see the section on [Viewers](available-viewers.md#viewers) or the documentation on [Alternate Viewers](available-viewers.md#alternate-viewers) for details of what should be set here.
+
+* `open_pdf_on_build` (`true`): Controls whether LaTeXTools will automatically open the configured PDF viewer on a successful build. If set to `false`, the PDF viewer will only be launched if explicitly requested using `C-l,v` or `C-l,j`.
+
+* `disable_focus_hack` (`false`): if `true`, the focus hack that LaTeXTools uses to return focus to Sublime in some circumstances will not be run. **Note**: This does not mean that the *viewer* won't steal the focus, only that LaTeXTools won't try to steal the focus back.
 
 ## Included File Settings
 
  * `"image_types"` (`["png", "jpg", "jpeg", "pdf" "eps"]`): image types that you use in LaTeX. These are used for autocompletions and to open included images where no extension is provided. Broadly speaking, this should correspond to any `\DeclareGraphicsExtensions{}` commands used in your document, but the default value corresponds to the types of images supported by `pdflatex` (they are also supported by `xelatex` and `lualatex`).
 
 ## Bibliographic References Settings
 
-* `bibliography` (`"traditional"`): specifies the bibliography plugin to use to handle extracting entries from a bibliography. May be specified either as a single plugin or a list of plugins to be executed in order. Possible values:
+* `use_biblatex`: (`false`): if `true` LaTeXTools will use BibLaTeX defaults for editing `.bib` files. If `false`, LaTeXTools will use BibTeX defaults. See the section on [Support for Editing Bibliographies](#support-for-editing-bibliographies) for details.
+
+* `bibliography` (`"new"`): specifies the bibliography plugin to use to handle extracting entries from a bibliography. May be specified either as a single plugin or a list of plugins to be executed in order. Possible values:
 	* `"traditional"`: the default bibliography which is quite fast and works for most situations.
 	* `"new"`: a newer bibliography engine which uses a full Bib(La)TeX parser that supports more complex formatting (multiline entries, values enclosed in double quotes `""`, literals and `@string` macros) and allows you to access more fields, but can be slower and may not be necessary for most bibliographies.
+
 * `cite_panel_format` (`["{author_short} {year} - {title_short} ({keyword})","{title}"]`): specifies the format for bibliography entries displayed in the quickpanel when typing `\cite{` or using one of the keybindings. It may either be a string or a list of two strings. In the latter case, the first string becomes the first line of the text displayed in the quick panel and the second the second.
+
 * `cite_autocomplete_format`(`"{keyword}: {title}"`): specifies the format for bibliography displayed when using Sublime's autocomplete functionality (`ctrl+space` or `alt+/`). Must be only a simple string.
 
 ### Bibliography Format Strings