Skip to content

Commit cebc41d

Browse files
jcwinklerjcwinkler
committed
Doc: Added configuration section
1 parent d13ac35 commit cebc41d

File tree

3 files changed

+221
-1
lines changed

3 files changed

+221
-1
lines changed

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ Key features
6767
usage/faq
6868
usage/troubleshooting
6969
usage/command_line_usage
70+
usage/configuration
7071

7172

7273
.. toctree::

‎docs/source/usage/configuration.rst‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
.. |TexText| replace:: **TexText**
2+
.. |Inkscape| replace:: **Inkscape 1.x**
3+
4+
.. role:: bash(code)
5+
:language: bash
6+
:class: highlight
7+
8+
.. role:: dos(code)
9+
:language: dos
10+
:class: highlight
11+
12+
13+
.. _configuration:
14+
15+
=====================
16+
TexText Configuration
17+
=====================
18+
19+
Usually, |TexText| is configured automatically during setup or via selecting
20+
certian options in the GUI. In case of any problems or to address certain
21+
issues one may directly edit the |TexText| configuration file.
22+
23+
.. contents:: :local:
24+
:depth: 2
25+
26+
27+
The TexText configuration file
28+
==============================
29+
30+
The configuration file ``config.json`` can be found at the following locations:
31+
32+
- Linux: ``~/.config/textext/config.json``
33+
- Winbdows: ``C:\Users\AppData\Roaming\TexText\config.json``
34+
- MacOS: ``~/Library/Preferences/textext``
35+
36+
The top level structure is:
37+
38+
.. code-block:: json
39+
40+
{
41+
"preamble": "...",
42+
"scale": 1.0,
43+
"previous_tex_command": "...",
44+
"gui": {
45+
"toolkit": "...",
46+
"use_gtk_source": true,
47+
"confirm_close": true,
48+
"line_numbers": true,
49+
"auto_indent": true,
50+
"insert_spaces": true,
51+
"tab_width": 2,
52+
"new_node_content": "...",
53+
"close_shortcut": "..."
54+
}
55+
}
56+
57+
Fields and Allowed Values (toplevel)
58+
------------------------------------
59+
60+
preamble (string, optional)
61+
Path to a LaTeX preamble file (.tex) or typst preamble file (.typst)
62+
is included in the document. If this is not set the default files
63+
(``default_packages.tex`` or ``default_preamble_typst.typ``) from the
64+
|TexText| installation directory is used.
65+
66+
Example:
67+
68+
.. code-block:: json
69+
70+
"preamble": "C:\\Users\\...\\default_packages.tex"
71+
72+
scale (number, optional)
73+
Scaling factor for the rendered LaTeX object.
74+
75+
Default: 1.0
76+
77+
Example:
78+
79+
.. code-block:: json
80+
81+
"scale": 0.8
82+
83+
previous_tex_command (string, optional)
84+
Last used LaTeX engine. Determines which engine is preselected in the next
85+
session.
86+
87+
Allowed values: ``"pdflatex"`` (default), ``"lualatex"``, ``"xelatex"``,
88+
``"typst"``
89+
90+
91+
Fields and Allowed Values (``gui`` object)
92+
------------------------------------------
93+
94+
toolkit (string, optional)
95+
Specifies the GUI toolkit to be used.
96+
97+
Allowed values: ``"gtk"`` (recommended), ``"tk"``
98+
99+
use_gtk_source (boolean, optional)
100+
Enable GtkSourceView for syntax highlighting (only valid, if
101+
``toolkit="gtk"``.
102+
103+
Values: ``true`` or ``false``
104+
105+
confirm_close (boolean, optional)
106+
Whether to show a confirmation prompt when closing the editor.
107+
108+
Values: ``true`` or ``false``
109+
110+
line_numbers (boolean, optional)
111+
Display line numbers in the editor.
112+
113+
Values: ``true`` or ``false``
114+
115+
auto_indent (boolean, optional)
116+
Enable automatic indentation of LaTeX code.
117+
118+
Values: ``true`` or ``false``
119+
120+
insert_spaces (boolean, optional)
121+
Insert spaces instead of tab characters when pressing Tab.
122+
123+
Values: ``true`` or ``false``
124+
125+
tab_width (integer, optional)
126+
Number of spaces per tab.
127+
128+
Example:
129+
130+
.. code-block:: json
131+
132+
"tab_width": 2
133+
134+
new_node_content (string, optional)
135+
Initial content used for new LaTeX nodes.
136+
137+
Allowed values: ``"Empty"`` (no content), ``"InlineMath"`` (e.g. $$) -
138+
default, ``"DisplayMath"`` (e.g. \\[\\])
139+
140+
close_shortcut (string, optional)
141+
Keyboard shortcut to close the editor.
142+
143+
Allowed values: ``"Escape"``, ``"CtrlQ"``, ``"None"`` (no shortcut)
144+
145+
JSON schema for the configuration file
146+
======================================
147+
148+
.. code-block:: json
149+
150+
{
151+
"$schema": "http://json-schema.org/draft-07/schema#",
152+
"title": "TeXText Configuration Schema",
153+
"type": "object",
154+
"properties": {
155+
"preamble": {
156+
"type": "string",
157+
"description": "Path to a LaTeX preamble file (.tex)"
158+
},
159+
"scale": {
160+
"type": "number",
161+
"description": "Scale factor for the rendered LaTeX content",
162+
"minimum": 0
163+
},
164+
"previous_tex_command": {
165+
"type": "string",
166+
"description": "Previously used LaTeX engine",
167+
"enum": ["pdflatex", "lualatex", "xelatex", "typst"]
168+
},
169+
"gui": {
170+
"type": "object",
171+
"description": "Graphical user interface configuration",
172+
"properties": {
173+
"toolkit": {
174+
"type": "string",
175+
"enum": ["gtk", "tk"],
176+
"description": "GUI toolkit to be used"
177+
},
178+
"use_gtk_source": {
179+
"type": "boolean",
180+
"description": "Enable GtkSourceView (for syntax highlighting)"
181+
},
182+
"confirm_close": {
183+
"type": "boolean",
184+
"description": "Ask for confirmation when closing the editor"
185+
},
186+
"line_numbers": {
187+
"type": "boolean",
188+
"description": "Display line numbers in the code editor"
189+
},
190+
"auto_indent": {
191+
"type": "boolean",
192+
"description": "Enable automatic indentation"
193+
},
194+
"insert_spaces": {
195+
"type": "boolean",
196+
"description": "Insert spaces instead of tab characters"
197+
},
198+
"tab_width": {
199+
"type": "integer",
200+
"minimum": 1,
201+
"description": "Number of spaces per tab"
202+
},
203+
"new_node_content": {
204+
"type": "string",
205+
"enum": ["Empty", "InlineMath", "DisplayMath"],
206+
"description": "Default content for new LaTeX nodes"
207+
},
208+
"close_shortcut": {
209+
"type": "string",
210+
"enum": ["Escape", "CtrlQ", "None"],
211+
"description": "Keyboard shortcut for closing the editor"
212+
}
213+
},
214+
"additionalProperties": false
215+
}
216+
},
217+
"additionalProperties": false
218+
}

‎docs/source/usage/gui.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -433,4 +433,5 @@ to configure the code editor:
433433
Further reading
434434
---------------
435435

436-
See :ref:`faq`, :ref:`troubleshooting`, and :ref:`commandlineusage`
436+
See :ref:`faq`, :ref:`troubleshooting`, :ref:`commandlineusage`,
437+
and :ref:`configuration` for more information.

0 commit comments

Comments
 (0)