Scripter and scripts
This chapter concerns information not needed by a new user, since it is what we would consider advanced usage. Nonetheless, it is worth reading through this chapter just so that you are aware of the capabilities of Scripter.
A script in our sense here is a small program which allows you to perform a series of operations in Scribus. The script is a text file which consists of a series of instructions, either in some highly automated way, or perhaps dependent on user input as the script runs. Scripts are especially useful for complex, repetitive tasks, especially when a number of objects need to be created and manipulated in a predictable pattern. You might create a basic layout and even add content. Scripts might also take existing content and perform a series of tedious actions on that content.
While you might simply use a script that someone else has written, you can also adapt an existing script to your specific needs. In fact, this can be a good way to introduce yourself to scripting, by modifying an existing script bit by bit. On the Scribus wiki you can find a number of Scripts for performing a variety of tasks you might have some interest in. All you need to do is create a file and copy the script into that file and save on your computer. Run the script by choosing from the menu Scripts > Execute Script..., then selecting your script file.
In Scribus, scripts are written in the Python programming language, and the script files should end in the extension .py, so your script file might be myscript.py. You will not damage Scribus even with a poorly written script, even though the script may fail to work or not work properly.
Like any programming language, Python has a vocabulary and syntax, and this takes some time to learn. Below you will see some resources to help you about Python.
Run a script
You should have a number of scripts included with your Scribus program, and you will see these listed under Scripts > Scribus Scripts.
- Autoquote – converts typewriter quotation marks to typographical quotation marks, and adapts to your chosen language.
- CalendarWizard – creates a calendar.
- color2csv – save to a csv file a list of the colors used in your document.
- ColorChart – creates a swatch from the colors in your document.
- csv2color – imports a list of colors saved in a csv file.
- DirectImageImport – creates an image frame and loads an image.
- FontSample – creates a document listing the fonts on your system with sample text.
- importcsv2table – imports the colors from a csv file to a created table.
- InfoBox – creates a text or image frame filling the width of one or more columns in a text frame. Loads an image if you wish.
You can modify these scripts according to your needs, the best method being to make a copy which you then edit. You can find the above scripts in:
Linux: /usr/share/scribus/scripts
Mac OSX: /Users/username/scribus/trunk/Scribus/scribus/plugins/scriptplugin/scripts/
Windows 7: C:\Program Files\Scribus1.4\share\scripts\
Create a folder, perhaps named Scripts, then when you click Scripts > Execute Script... you will know where to find them.
Add scripts
As stated above, the quickest and best way to find a variety of scripts in on the Scribus wiki (http://wiki.scribus.net), under the category Scripts. Not only should you find the scripts themselves, but typically instructions on using the script, such as whether you should have a document open and perhaps some object selected, or whether the script creates a document. There often are hints to the particular commands in a script and especially valuable is seeing the correct sequence of commands to make some object with particular properties.
For example, if you wanted to use the script from the wiki article Adding 'DRAFT' to a Document,
- First, open a plain text editor. An example is Gedit (which you can get and install from http://www.gedit.org).
- Go to the wiki article mentioned above.
- Highlight the actual script from that article, copy, then paste to Gedit.
- Save the file with the name draft.py
The script is now ready to use in Scribus.
- Make sure you have a document open.
- Scripts > Execute Script..., find the script on your system.
- Once you click OK the word DRAFT appears on the page.
Make your own scripts
If you can't find a script that meets your needs, you can write your own, or perhaps get someone who knows some Python programming to make it for you.
On the other hand, you might be able to simply modify an existing script, or combine features from two or more scripts already on the wiki, once you understand which commands produce which results.
For example, let's say that instead of the word 'DRAFT' you want the French 'BROUILLON'.
- At line 25 of your draft.py script is the command draft = "DRAFT".
- In front of the word draft type a #, which causes that line to be ignored by Python.
- Now at the beginning of line 27, remove the # so that now draft = 'BROUILLON' will be executed when the script runs.
- Save file and run it again.
Getting help and more information
All we have shown in this section is a brief overview of scripting. Here are some links which can get you started, and help when you get stuck on some issue.
Introduction to Python syntax
Check the manual included with Scribus: under Help > Scribus Manual > For Developers > Scripter, and also Scripter FAQ.
Some beginning Scribus Python scripts
Python commands specific to Scribus
This is in the manual included with Scribus, under Help > Scribus Manual > For Developers > Scripter API
Getting human help!
Send a note to the Scribus mail list, where you might find your question answered by the community of developers and users: http://lists.scribus.net/mailman/listinfo/scribus . To send a message to the list, use this address: scribus@lists.scribus.net .
You can even discuss issues live on IRC, at chat.freenode.net, on the #scribus channel. If you've never used an IRC client, you might try out a link on the wiki site: http://wiki.scribus.net/canvas/Special:WebChat
Both the mail list and #scribus have the appearance that they might be English-only, but in case you struggle with English, there is typically someone able to answer most European languages.
The Scribus file format: .sla
This has nothing to do with Scripter, but we wanted to include in this chapter some information on the Scribus file format. the SLA format, like Scribus itself, is completely open, and in plain-text. It is similar to XML, and for that matter HTML, which you may be familiar with if you've ever looked at the HTML source with your browser. Because it is plain text, you can easily edit the file directly in a plain text editor.
SLA: an editable format
You should have no trouble finding your Scribus files, especially if you have followed our recommendations on organizing your projects, since they end with the extension .sla. You might be concerned about doing so, but feel free to open a file in a plain text editor. Take some time to notice the overall structure, which is quite complex even in small project, but there are tags which identify the various parts of your project, as well as the fonts used, styles, colors and so on.
In the example below we see a small section of a file where the color palette is listed. We can see that there are two spot colors listed, a PANTONE 541C and PANTONE 541C PALE. This would result in adding another color to the printing process, and of course an extra color means extra time and expense. What we really wanted was to use PANTONE 541C each time but with 50% saturation in the second instance. We can solve this quite easily by editing the file.
Below you can see how we have edited the file where the colors were used. In the second line, we delete PALE from the color name, then edit SHADE and SHADE2 values to 50 for our 50% saturation.
It is always good practice to make a copy of a file (save it under a slightly different name), so that if you make some mistake you still have the original. A badly edited file might not be able to be loaded by Scribus, and you would get a message that the file is corrupt. Even so, if necessary, you should be able to get help in fixing your file, if you cannot fix it yourself.