diff options
Diffstat (limited to 'Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html')
-rw-r--r-- | Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html | 400 |
1 files changed, 166 insertions, 234 deletions
diff --git a/Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html b/Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html index 2870efbaef7..df93f2dd75d 100644 --- a/Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html +++ b/Master/tlpkg/texworks/texworks-help/TeXworks-manual/en/AdvanceduseScripting.html @@ -1,234 +1,166 @@ -<?xml version="1.0"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> -<meta name="generator" content= -"HTML Tidy for Linux (vers 25 March 2009), see www.w3.org" /> - -<title>6 Advanced use: Scripting</title> -<meta http-equiv="Content-Type" content= -"text/html; charset=utf-8" /> -<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" /> -<meta name="date" content="2015-05-06 23:03:00" /> -<link rel="stylesheet" type="text/css" href="index.css" /> -<style type="text/css" xml:space="preserve"> -/*<![CDATA[*/ - em.c1 {font-weight: bold} -/*]]>*/ -</style> -</head> - -<body> -<!--l. 5--> - -<p class="noindent"></p> - -<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"></p> - -<div class="chapternumber"> -6 -</div> - -<h1><a id="x35-380006" name="x35-380006"></a>Advanced use: -Scripting</h1><a id="dx35-38001" name="dx35-38001"></a> - -<h3 class="sectionHead"><span class="titlemark">6.1</span> <a id= -"x35-390006.1" name="x35-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—from simply -making some text bold to fulfilling special requirements for the -next book or scientific paper you want to publish—, the core -functionality of T<sub>E</sub>Xworks can be extended or modified by -the use of scripts. <!--l. 11--></p> - -<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="index36.html#fn1x7"><sup class= -"textsuperscript">1</sup></a></span><a id="x35-39001f1" name= -"x35-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 class="c1">Scripts</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">Scripting -T<sub>E</sub>Xworks</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">About Scripts…</em> menu -item. <!--l. 13--></p> - -<p class="indent">Writing scripts<a id="dx35-39002" name= -"dx35-39002"></a> is beyond the scope of this manual, but is -documented elsewhere<span class="footnote-mark"><a href= -"index37.html#fn2x7"><sup class= -"textsuperscript">2</sup></a></span><a id="x35-39003f2" name= -"x35-39003f2"></a>. Here, only the installation and usage of -scripts will be discussed. <!--l. 15--></p> - -<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 class="c1">Scripts</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> - -<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 verb ec-lmtt-12">babel</span> commands found in the -document. Thus, hook scripts do not show up in the <em class= -"c1">Scripts</em> menu but are instead run automatically when the -T<sub>E</sub>Xworks function they modify is used. <!--l. 19--></p> - -<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</p> - -<div class="fancyvrb" id="fancyvrb17"> -<a id="x35-39005r1" name="x35-39005r1"></a><span class= -"ec-lmtt-10x-x-109"> </span><span class= -"ec-lmtt-10x-x-109"> //</span><span class= -"ec-lmtt-10x-x-109"> Type:</span><span class= -"ec-lmtt-10x-x-109"> standalone</span> -</div><!--l. 23--> - -<p class="noindent">Alternatively—once the script is installed—, -you can use the dialogue available from <em class= -"c1">Scripts</em><span class="lmsy-10x-x-120">→</span><em class= -"c1">Scripting T<sub>E</sub>Xworks</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">Manage Scripts</em> to -display this information.</p> - -<h3 class="sectionHead"><span class="titlemark">6.2</span> <a id= -"x35-400006.2" name="x35-400006.2"></a>Installing -Scripts</h3><a id="dx35-40001" name="dx35-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—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> - -<p class="indent">That said, installing scripts is very simple. -Script files are generally installed in <span class= -"path"><resources>/scripts</span> or subdirectories of it. -These subdirectories are shown as submenus of the <em class= -"c1">Scripts</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 class="c1">Scripts</em> -menu very confusing. One easy way to open the <span class= -"path">scripts</span> folder is the <em class= -"c1">Scripts</em><span class="lmsy-10x-x-120">→</span><em class= -"c1">Scripting T<sub>E</sub>Xworks</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">Show Scripts Folder</em> -menu item. <!--l. 32--></p> - -<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—and any other required files that you may have -received—into <span class="path"><resources>/scripts</span> -or a subdirectory of it. <!--l. 34--></p> - -<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 class= -"c1">Scripts</em><span class="lmsy-10x-x-120">→</span><em class= -"c1">Scripting T<sub>E</sub>Xworks</em> <span class= -"lmsy-10x-x-120">→</span><em class="c1">Reload Script List</em> -menu item which rescans all scripts without otherwise interfering -with the program. <!--l. 36--></p> - -<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 class="c1">Scripts</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 “Manage Scripts” -dialogue with the <em class="c1">Scripts</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">Scripting -T<sub>E</sub>Xworks</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">Manage Scripts</em><a id= -"dx35-40002" name="dx35-40002"></a> menu item. Simply uncheck the -script you want to disable and it won’t bother you again. -<!--l. 38--></p> - -<p class="noindent"></p> - -<h3 class="sectionHead"><span class="titlemark">6.3</span> <a id= -"x35-410006.3" name="x35-410006.3"></a>Using Scripts</h3><a id= -"dx35-41001" name="dx35-41001"></a> <!--l. 40--> - -<p class="noindent">Using scripts is simple. Hook scripts are used -automatically—you don’t need to do anything. Standalone scripts -show up in the <em class="c1">Scripts</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 -“Manage Scripts” dialogue to get additional information (like the -author, a brief description, etc.) about it. <!--l. 42--></p> - -<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’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 class="c1">Edit</em><span class= -"lmsy-10x-x-120">→</span><em class="c1">Preferences…</em> menu -item. There, go to the “Scripts” tab and check the “Allow scripts -to run system commands” option. If you want to disable this -function again later just uncheck the option. Note that this option -applies equally to all scripts—there is currently no way to allow -command execution only for some scripts. <!--l. 5--></p> - -<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" name= -"tailAdvanceduseScripting.html"></a></p> -</div> -</body> -</html> +<!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—from simply making some text bold to fulfilling +special requirements for the next book or scientific paper you want to +publish—, 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">→</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span +class="lmsy-10x-x-120">→</span><em><b>About +Scripts…</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"> Type:</span><span +class="ec-lmtt-10x-x-109"> standalone</span></div> +<!--l. 23--><p class="noindent" >Alternatively—once the script is installed—, you can use the dialogue available from +<em><b>Scripts</b></em><span +class="lmsy-10x-x-120">→</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span +class="lmsy-10x-x-120">→</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—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"><resources>/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">→</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span +class="lmsy-10x-x-120">→</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—and any other required files that you may have received—into +<span class="path"><resources>/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">→</span><em><b>Scripting T<sub>E</sub>Xworks</b></em> +<span +class="lmsy-10x-x-120">→</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 “Manage Scripts” dialogue with the <em><b>Scripts</b></em><span +class="lmsy-10x-x-120">→</span><em><b>Scripting T<sub>E</sub>Xworks</b></em><span +class="lmsy-10x-x-120">→</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’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—you don’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 “Manage Scripts” 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’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">→</span><em><b>Preferences…</b></em> menu +item. There, go to the “Scripts” tab and check the “Allow scripts to run +system commands” option. If you want to disable this function again +later just uncheck the option. Note that this option applies equally to all +scripts—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> |