summaryrefslogtreecommitdiff
path: root/Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html
blob: df93f2dd75d218ee048c65a0bc22fbb51aac7499 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"  
  "http://www.w3.org/TR/html4/loose.dtd">  
<html > 
<head><title>6 Advanced use: Scripting</title> 
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 
<meta name="generator" content="TeX4ht (http://www.tug.org/tex4ht/)"> 
<meta name="originator" content="TeX4ht (http://www.tug.org/tex4ht/)"> 
<!-- info,2,imgdir:images/,sec-filename,next,index=2,url-enc,html --> 
<meta name="src" content="index.tex"> 
<link rel="stylesheet" type="text/css" href="index.css"> 
</head><body 
>
<!--l. 5--><p class="noindent" ><div id="container"> <!--l. 5--><div class="crosslinks"><p class="noindent">[<a 
href="Beyondthismanual.html" >next</a>] [<a 
href="GoingfurtherOthertools.html" >prev</a>] [<a 
href="GoingfurtherOthertools.html#tailGoingfurtherOthertools.html" >prev-tail</a>] [<a 
href="#tailAdvanceduseScripting.html">tail</a>] [<a 
href="index.html#AdvanceduseScripting.html" >up</a>] </p></div>
<!--l. 5--><p class="indent" >   <div class="chapternumber">6</div><h1><a 
 id="x34-380006"></a>Advanced use: Scripting</h1><a 
 id="dx34-38001"></a>
   <h3 class="sectionHead"><span class="titlemark">6.1   </span> <a 
 id="x34-390006.1"></a>Introduction to Scripting</h3>
<!--l. 9--><p class="noindent" >All the functions and utilities described so far were built into T<sub>E</sub>Xworks by default.
While some of them could be configured or customized to a certain extent,
they are intended to suit the most common needs of a general audience.
However, the T<sub>E</sub>X world is very large and diverse. In order to enable users to
address their special needs&#8212;from simply making some text bold to fulfilling
special requirements for the next book or scientific paper you want to
publish&#8212;, the core functionality of T<sub>E</sub>Xworks can be extended or modified by the use of
scripts.
<!--l. 11--><p class="indent" >   Scripts are simple text files that you can open, read, or modify in any text
editor (including T<sub>E</sub>Xworks, of course). They are written in a specific scripting language
that is essentially a programming language. At the time of writing, T<sub>E</sub>Xworks supports
QtScript<span class="footnote-mark"><a 
href="index35.html#fn1x7"><sup class="textsuperscript">1</sup></a></span><a 
 id="x34-39001f1"></a>
(built-in), Lua (with a plugin), and Python (with a plugin). To see which scripting
languages are available on your system, use the <em><b>Scripts</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>About
Scripts&#x2026;</b></em> menu item.
<!--l. 13--><p class="indent" >   Writing scripts<a 
 id="dx34-39002"></a> is beyond the scope of this manual, but is documented
elsewhere<span class="footnote-mark"><a 
href="index36.html#fn2x7"><sup class="textsuperscript">2</sup></a></span><a 
 id="x34-39003f2"></a>.
Here, only the installation and usage of scripts will be discussed.
<!--l. 15--><p class="indent" >   T<sub>E</sub>Xworks distinguishes between two types of scripts: standalone scripts and hook
scripts. The primary purpose of standalone scripts is to add new functionality to
the program. If you need a new function, such as a command to make the selected
text bold, a standalone script is the one to choose. These scripts get an
item in the <em><b>Scripts</b></em> menu, and you can run them simply by clicking on
that menu item (or by using a keyboard shortcut, if the script provides
one).
<!--l. 17--><p class="indent" >   Hook scripts, on the other hand, are meant to extend existing T<sub>E</sub>Xworks functions. They
are hooked into the code at specific places, e.g., after the typeset process
                                                                          

                                                                          
has finished or after a file was loaded, and can add or modify whatever T<sub>E</sub>Xworks
is doing. One example for this would be a script that analyses a newly
loaded file and sets the spell-checking language based on <span class="obeylines-h"><span class="verb"><span 
class="ec-lmtt-12">babel</span></span></span> commands
found in the document. Thus, hook scripts do not show up in the <em><b>Scripts</b></em>
menu but are instead run automatically when the T<sub>E</sub>Xworks function they modify is
used.
<!--l. 19--><p class="indent" >   You can easily determine which type of script you have by opening
the script file. Near the top of the file, you should find a line similar to

   <div class="fancyvrb" id="fancyvrb17"><a 
 id="x34-39005r1"></a><span 
class="ec-lmtt-10x-x-109">//</span><span 
class="ec-lmtt-10x-x-109">&#x00A0;Type:</span><span 
class="ec-lmtt-10x-x-109">&#x00A0;standalone</span></div>
<!--l. 23--><p class="noindent" >Alternatively&#8212;once the script is installed&#8212;, you can use the dialogue available from
<em><b>Scripts</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Manage Scripts</b></em> to display this information.
   <h3 class="sectionHead"><span class="titlemark">6.2   </span> <a 
 id="x34-400006.2"></a>Installing Scripts</h3>
<a 
 id="dx34-40001"></a>
<!--l. 28--><p class="noindent" >A word of caution first: do not install scripts from a source you do not trust!
Before installing scripts, you should make sure that the file you are about to
install indeed does what you expect. Scripts are very powerful&#8212;they can do
almost everything a normal program can do. So while there are some security
precautions built into T<sub>E</sub>Xworks, you should still be aware that scripts could potentially
harm your computer and cause (among other things) crashes and data loss. In
particular, scripts can read, create, and modify arbitrary files on your hard
drive.
<!--l. 30--><p class="indent" >   That said, installing scripts is very simple. Script files are generally installed in
<span class="path">&#x003C;resources&#x003E;/scripts</span> or subdirectories of it. These subdirectories are shown as
submenus of the <em><b>Scripts</b></em> menu, so they can be used to group and categorize
scripts. This is especially useful if you use many different scripts that would
otherwise make the <em><b>Scripts</b></em> menu very confusing. One easy way to open
the <span class="path">scripts</span> folder is the <em><b>Scripts</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Show Scripts Folder</b></em> menu
item.
<!--l. 32--><p class="indent" >   Since scripts are usually simple plain-text files, they do not come with fancy
installers. To install them, simply copy or decompress (if archived, e.g., in a .zip
file) the script file&#8212;and any other required files that you may have received&#8212;into
<span class="path">&#x003C;resources&#x003E;/scripts</span> or a subdirectory of it.
<!--l. 34--><p class="indent" >   After having installed a new script file, T<sub>E</sub>Xworks needs to become aware of it. It
automatically scans for all scripts during start-up, so you could close all T<sub>E</sub>Xworks windows
and restart the application. An alternative is provided by the <em><b>Scripts</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Scripting T<sub>E</sub>Xworks</b></em>
<span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Reload Script List</b></em> menu item which rescans all scripts without otherwise
                                                                          

                                                                          
interfering with the program.
<!--l. 36--><p class="indent" >   You can also disable scripts (or whole directories of scripts) if you want to.
This can be useful if you do not need some scripts for some time and do not want
them to clutter the <em><b>Scripts</b></em> menu, but do not want to uninstall them entirely. Or if
you want to prevent hook scripts from being run automatically. To do this, open
the &#8220;Manage Scripts&#8221; dialogue with the <em><b>Scripts</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Manage Scripts</b></em><a 
 id="dx34-40002"></a>
menu item. Simply uncheck the script you want to disable and it won&#8217;t bother you
again.
<!--l. 38--><p class="noindent" >
   <h3 class="sectionHead"><span class="titlemark">6.3   </span> <a 
 id="x34-410006.3"></a>Using Scripts</h3>
<a 
 id="dx34-41001"></a>
<!--l. 40--><p class="noindent" >Using scripts is simple. Hook scripts are used automatically&#8212;you don&#8217;t need to do
anything. Standalone scripts show up in the <em><b>Scripts</b></em> menu or one of its submenus.
If you cannot find a script you are looking for, or if you find a script you do not
know the purpose of, you can use the &#8220;Manage Scripts&#8221; dialogue to get
additional information (like the author, a brief description, etc.) about
it.
<!--l. 42--><p class="indent" >   Some scripts need to run other programs on your system. One example would
be a script that opens the pdf in the system&#8217;s default previewer, e.g., for printing.
Since running arbitrary commands can in some situations be particularly
dangerous, this functionality is disabled by default. You will notice this when a
dialogue pops up informing you of an error in the script, or a similar
message is displayed in the status bar. To enable scripts to execute system
commands, open the preferences dialogue via the <em><b>Edit</b></em><span 
class="lmsy-10x-x-120">&#x2192;</span><em><b>Preferences&#x2026;</b></em> menu
item. There, go to the &#8220;Scripts&#8221; tab and check the &#8220;Allow scripts to run
system commands&#8221; option. If you want to disable this function again
later just uncheck the option. Note that this option applies equally to all
scripts&#8212;there is currently no way to allow command execution only for some
scripts.
                                                                          

                                                                          
                                                                          

                                                                          
                                                                          

                                                                          
   <!--l. 5--><div class="crosslinks"><p class="noindent">[<a 
href="Beyondthismanual.html" >next</a>] [<a 
href="GoingfurtherOthertools.html" >prev</a>] [<a 
href="GoingfurtherOthertools.html#tailGoingfurtherOthertools.html" >prev-tail</a>] [<a 
href="AdvanceduseScripting.html" >front</a>] [<a 
href="index.html#AdvanceduseScripting.html" >up</a>] </p></div>
<!--l. 5--><p class="indent" >   <a 
 id="tailAdvanceduseScripting.html"></a>  </div> 
</body></html>