Subversion Repositories Scribus

Rev

Rev 13558 | Rev 16853 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
13558 mrdocs 1
<body>
2
<head><TITLE>Render Frames</TITLE></head>
3
<body>
4
<h1>Introduction</h1>
5
<p>Since version 1.3.5 Scribus contains a powerful new feature called
6
Render Frames. Originally planned as a means to insert formulas into
7
Scribus documents, the inventor, Hermann Kraus, has enabled the
8
creation of almost any kind of special typesetting, like formulas,
9
musical notation or chess notation, from within Scribus. The trick here is that Scribus uses other programs in the background. It imports their output into a special frame type called <b>Render Frames</b>.</p>
10
<p>While this feature is extremely versatile, you must not forget
11
that the use of it requires knowledge of the markup codes
12
required by a particular program. These commands are beyond the scope
13
of the Scribus documentation.</p>
14
<h1>Creating a Render Frame</h1>
15
<p>To create a Render Frame, click on the Render Frame icon in the
16
menu bar, use <i>Insert &gt; Render Frame</i>, or press D on the
17
keyboard:</p>
18
<table width="100%"><tr><td align="center"><img src="images/rf2.png"/></td></tr></table>
19
<p>The cursor will then turn into a frame symbol with an L inside:</p>
20
<table width="100%"><tr><td align="center"><img src="images/DrawLatexFrame.png"/></td></tr></table>
21
<p><br><br>
22
</p>
23
<p>The next step is to click-drag the frame and let up, just like you would do
24
with a text frame. By default, Scribus will display a welcome
25
message, which indicates that at least the configuration for LaTeX is
26
correct. What you see below is the output from LaTeX, rendered in Scribus.
27
The welcome message will be displayed in the language of the user
28
interface as set in <i>File &gt; Preferences</i>. If no translation
29
of the message is available, you will see the English version:</p>
30
<table width="100%"><tr><td align="center"><img src="images/rf3.png"/></td></tr></table>
31
<p>The
32
screenshot above has been made with the default resolution of 72 dpi,
33
which, obviously, isn't enough for printing. You can easily change
34
the resolution as you'll learn below.</p>
35
<h1>Editing Render Frames</h1>
36
<p>If
37
you right-click on a Render Frame, the context menu shows an entry
38
called "Edit Source:"</p>
39
<table width="100%"><tr><td align="center"><img src="images/rf4.png"/></td></tr></table>
40
<p>Selecting it brings up the "heart" of the Render Frame, the
41
editor:</p>
42
<table width="100%"><tr><td align="center"><img src="images/rf5.png"/></td></tr></table>
43
<p>In Scribus 1.3.5, the editor is preconfigured to use LaTeX,
44
Lilypond, gnuplot, dot/GraphViz and POV-Ray.</p>
45
<p>To the left you see a field with the caption "Enter Code."
46
Here you can insert the markup code for the output you want from the
47
external program. For preconfigured renderers Scribus is shipped with some simple code snippets that will enable you to test if the respective programs are installed and configured properly. As you can see, the editor provides syntax
48
highlighting.</p>
49
<p>The "Update" button beneath the text field will update the
50
content of the Render Frame, so that you can visually check the
51
results of changes you made to the markup text without closing the editor. "Revert" will
52
revert any change you made to the text. Please be aware that once you started editing the text, it's no longer possible to change the markup renderer, e.g., if you started editing LaTeX sourcecode, you cannot switch to Lilypond anymore.</p>
53
<p>To the right you see a row of tabs. These are not available for
54
all preconfigured markup languages, so sometimes the editor only shows the
55
"Options" tab.
56
</p>
57
<p>In the "Options" tab, the first entry is "Resolution." Its
58
default setting is "Automatic," thus, 72 dpi as explained above.
59
You can easily change the resolution of the output to something more
60
suitable for printing.</p>
61
<p>"Program" shows the list of supported programs. The editor
62
will list all programs that are configured in <I>File &gt;
63
Preferences&gt; External Tools</I>.</p>
64
<p>If you check "Use Preamble," the editor will automatically use
65
the preamble and the postamble as specified in the XML configuration
66
files. See below for more details.</p>
67
<p>"Program Messages" shows the messages that would otherwise be
68
displayed in a command-line interpreter. They are "intercepted"
69
by Scribus, just like the final output, and they are often useful to
70
find out what went wrong if the rendering failed.</p>
71
<p>If you click on "Run external editor," Scribus will start the
72
editor as specified in <i>File &gt; Preferences</i>,
73
and "Kill Program" will stop the external program. This can be
74
useful when the external program stumbles across an error you made in
75
your markup that causes the external program to fail or even crash.</p>
76
<h1>Preconfigured Programs</h1>
77
<h2>LaTeX</h2>
78
<table width="100%"><tr><td align="center"><img src="images/rf6.png"/></td></tr></table>
79
<p>The first LaTeX tab is called
80
"Fonts/Headers." In the upper drop-down list you can set the font
81
used for a Render Frame that uses LaTeX. By default, only four fonts
82
are listed, but you can easily add more by editing the LaTeX XML
83
configuration file as described in detail below: Just add another font under <code>&lt;list name=&quot;font&quot;
84
default=&quot;&quot;&gt;</code> in the file. Please note that the font list
85
for LaTeX (and many other markup programs) is completely different
86
from the fonts available to you in Scribus and other programs, as
87
LaTeX uses its own fonts and needs to be configured to use the Type&nbsp;1, TrueType and OpenType fonts available to you in programs like
88
Scribus or OpenOffice.org. For more information about LaTeX font configuration see the <a href="http://www.latex-project.org/guides/fntguide.pdf">LaTeX Font Selection Guide (PDF)</a>.</p>
89
<p>The next drop-down list allows
90
for changing the default font size. If you are used to LaTeX, you
91
will already know that this is the setting for the base font. Other
92
necessary font sizes, e.g. for superscript and subscript are
93
determined by LaTeX. You will also note that the editor lists only a
94
selection of base font sizes. Again, you can easily add other sizes
95
under <code>&lt;list name=&quot;fontsize&quot; default=&quot;11pt&quot;&gt;</code>
96
in the LaTeX XML configuration file. Since there are almost no limits
97
as to the possibilities you have for the configuration of a LaTeX
98
file, you will appreciate the option to select different XML
99
configuration files in <i>File &gt; Preferences &gt; External
100
Tools</i>.</p>
101
<p>The text field "Additional
102
Headers" allows for the insertion of additional headers to the
103
preamble of the LaTeX markup, which will be stored within the Scribus sla
104
file.</p>
105
<p>Finally, you find different tabs
106
with symbols and characters that can be created by LaTeX:</p>
107
<table width="100%"><tr><td align="center"><img src="images/rf7.png"/></td></tr></table>
108
<p>To
109
insert a single symbol into your markup code, you can either select
110
the symbol and click "Insert Symbol" or double-click on the icon
111
in the field.</p>
112
<p>For more information see the <a href="http://www.latex-project.org/">official LaTeX website</a>.</p>
113
 
114
<h2>Lilypond</h2>
115
 
116
<table width="100%"><tr><td align="center"><img src="images/lilyp.png"/></td></tr></table>
117
 
118
There are no additional options for Lilypond available.
119
<p>For more information see the <a href="http://lilypond.org/web/">official Lilypond website</a>.</p>
120
 
121
<h2>gnuplot</h2>
122
 
123
<table width="100%"><tr><td align="center"><img src="images/plot1.png"/></td></tr></table>
124
<br></br>
125
The gnuplot options are very basic. Under <i>Ranges</i> you can enter the start and end digits for the x- and the y-axis. The default is an asterisk, which will result in gnuplot creating the digits automatically, according to the values set in the markup text.
126
<br></br>
127
<table width="100%"><tr><td align="center"><img src="images/plot2.png"/></td></tr></table>
128
<br></br>
129
The tab called <i>Labels</i> serves as an assistant to determine some visual aspects of a graph:
130
 
131
<ul>
132
<li><i>Title</i> will create a title for your graph, which will be placed at the top of the rendered image.</li>
133
<li><i>X-Label</i> and <i>Y-Label</i> will create captions for the x- and y-axis.</li>
134
<li><i>Grid</i> and <i>Grid layer</i> work similiar to the guides/page grid settings in Scribus, except that the grid in the graph will become part of the rendered image. You can choose between no grid at all, the major grid ("Major ticks only") and major plus minor grid ("Major and minor ticks"). Just like in Scribus you can also decide to have the grid rendered in the background or in the foreground.</li>
135
<li><i>Zero axis</i> will create a dotted line to indicate either the x- or the y-axis, or both. Note that using any grid will make the setting of any zero axis unnecessary, as both use the same colour. If you want to use a different line style for grid and the axes, you have to do this in the markup text. Likewise, adding a z-axis requires the editing of the graph's source code.</li>
136
</ul>
137
 
138
<p>For more information see the <a href="http://www.gnuplot.info/">official gnuplot website</a>.</p>
139
 
140
<h2>dot/Graphviz</h2>
141
 
142
There are no additional options for dot/Graphviz available.
143
 
144
<p>For more information see the <a href="http://www.graphviz.org/">official Graphviz website</a>.</p>
145
 
146
<h2>POV-Ray</h2>
147
 
148
<table width="100%"><tr><td align="center"><img src="images/povray.png"/></td></tr></table>
149
<br></br>
150
<p>The editor offers only one tab for the rendering of POV-Ray files, namley "Rendering Options:" </p>
151
<ul>
152
<li><i>Quality</i> provides the same seven quality levels as the POV-Ray command-line interface, and the editor uses the same default level ("Compute media and radiosity"). Otherwise, the quality levels are listed in an ascending order, "Just show quick colors" providing the lowest quality.</li>
153
<li><i>Antialiasing</i> is a technique to "smoothen" edges in a rendered image. It can dramatically improve the quality of an image, but using it may result in much longer rendering times. The options <i>Antialiasing Threshold</i> and <i>Antialiasing Depth</i> are explained in detail in the POV-Ray documentation, but the default values should suffice in most cases.</li></ul>
154
 
155
<p>For more information see the <a href="http://www.povray.org/">official POV-Ray website</a>.</p>
156
 
157
<h1>Rendering</h1>
158
<p>Once you have created the markup
159
to your satisfaction, you can click the "OK" button.</p>
160
<p>If you made a mistake, and the
161
external program cannot render your markup, Scribus displays an error
162
message:</p>
163
<table width="100%"><tr><td align="center"><img src="images/rf8.png"/></td></tr></table>
164
<p><br><br>
165
</p>
166
<p>A blue X in the Render Frame along with an error message will
167
then indicate that no content could be rendered:</p>
168
<table width="100%"><tr><td align="center"><img src="images/rf-error2.png"/></td></tr></table>
169
<h2>Additional Notes</h2>
170
<p>If you look at the context menu
171
for Render Frames, you will get the impression that they are image
172
frames. In a sense, that's correct, as you can change the preview
173
settings for Render Frames or update the content. There is, however,
174
a major difference: As said above, the markup text ist stored within
175
a Scribus file, and the rendered content is always created "on the
176
fly." Each time you open a Scribus file that contains a Render
177
Frame, Scribus will run the respective program that's necessary to
178
render the content and create a temporary image file which will then
179
be loaded into the frame. This is why Render Frames aren't listed in
180
<i>Extras &gt; Manage Images</i>.</p>
181
<p>This behaviour has some
182
consequences. While you can use a Scribus file with images on another
183
computer by using <i>File &gt; Collect for Output</i>
184
and copying the resulting archive to another machine, Render Frames
185
require the presence of the used <i>software</i>
186
on this machine. Moreover, the feature might not work between
187
different operating systems, because the command-line options can be
188
different.</p>
189
<p>Another limitation is that you can't apply any image effects to Render Frames.</p>
190
 
191
<h1>Configuration</h1>
192
<p>To make Render Frames work, you need to have the required programs
193
installed on your computer. By default, Scribus supports five
194
programs, namely LaTeX, Lilypond, gnuplot, dot/Graphviz and Lilypond. On Linux,
195
your package manager will take care about the installation and the
196
dependencies of the software. On other platforms you might need to
197
install the programs separately and edit some configuration files.</p>
198
<p>If you open the tab "External Tools" in <i>File &gt;
199
Preferences</i>, you see the configuration options for Render Frames
200
at the bottom of the dialog:</p>
201
<table width="100%"><tr><td align="center"><img src="images/rf1.png"/></td></tr></table>
202
 
203
<p>Under "Configurations," Scribus shows the default configuration files. Each program you want to use from within Scribus needs a separate configuration file. To add a new program to your Render Frames, you have to create an XML file with some required settings. Below you see an abridged and commented gnuplot configuration file, which will serve as an example:</p>
204
 
205
<p><code>&lt;editorsettings description="Gnuplot" icon="gnuplot.png"&gt;</code> This line sets the description of the program, as well as the icon for the drop-down list in the Render Frame Editor. It must be stored in the same directory as the XML file. You can use  PNG, XPM and SVG icons.</p>
206
<p><code>&lt;executable command="gnuplot"&gt;</code> This is the command-line call of the program. You can only use software that can work on the command-line. Also, the program needs to be able to create output in either PNG, PDF or EPS format. By default, Scribus uses the command-line options for Linux/UNIX systems.</p>
207
<p><code>&lt;imagefile extension=".png"/&gt;</code> Here you tell the editor which file format it has to expect from the external program.</p>
208
<p><code>&lt;highlighter&gt; &lt;/highlighter&gt;</code> This part is mainly interesting for programmers, as it allows for the creation of indvidual syntax highlighting schemes by using Regular Expressions. For further information see: <a href="http://docs.kde.org/kde3/en/kdeutils/KRegExpEditor/index.html">http://docs.kde.org/kde3/en/kdeutils/KRegExpEditor/index.html</a> and <a href="http://doc.trolltech.com/4.4/qregexp.html">http://doc.trolltech.com/4.4/qregexp.html</a>.</p>
209
<p><code>&lt;empty-frame-text&gt;</code> Here you can enter sample text in the
210
markup language of the program you want to use, for instance:</p>
211
<p><code>plot sin(x), (cos(x))**2</code></p>
212
</p><code>&lt;preamble&gt;</code> If the markup language you
213
want to use requires a preamble, you can enter it here. It will not
214
be displayed in the editor.</p>
215
<p><code>&lt;postamble&gt;</code> If the markup language you
216
want to use requires a postamble, you can enter it here. It will not
217
be displayed in the editor.</p>
218
<p><code>&lt;tab type="settings"&gt;</code> Here's where translations to existing GUI strings as well as new tabs or other UI elements can be added via simple XML entries, for example:</p>
219
<p><code>&lt;title&gt;&lt;i18n&gt;</code>
220
<p6><code>
221
<ul>
222
<li>&lt;en&gt;Ranges&lt;/en&gt;
223
<li>&lt;de&gt;Bereiche&lt;/de&gt;
224
<li>&lt;fr&gt;Rangées&lt;/fr&gt;
225
<li>&lt;pl&gt;Zakresy&lt;/pl&gt;
226
<li>&lt;ru&gt;&#1044;&#1080;&#1072;&#1087;&#1072;&#1079;&#1086;&#1085;&#1099;&lt;/ru&gt;
227
</ul></code></p6>
228
 
229
<p>To add a new configuration file, click on the "Add..."
230
button, which will bring up a file dialog. Select your file and click
231
"Open." The file will then be added to your Render Frame
232
configuration.</p>
233
<p>By moving entries of XML configuration files in the list up or
234
down, you can change the order of entries in the editor's drop down
235
list. If you want to use a different XML configuration file for a
236
particular markup language (for example, if you need another default
237
preamble for LaTeX frames in a project), you can change the path to
238
the alternative file by clicking on "Change ..." or simply add a new configuration file with an appropriate name, like "MyLateX".</p>
239
<br>If you prefer another editor for your markup, for example if you can't live without Emacs or vi, or if the editor window is simply too small for you, you can override the built-in Scribus Render Frame Editor by using
240
another editor like vi or Kate. Just insert the path to the
241
executable file in the text field "External Editor." The external editor won't override the Render Frame editor: As soon as
242
you save your markup from the external editor, Scribus "intercepts"
243
the data and renders the output into the frame or will display error messages in the "Program Messages" field. The interception also
244
means that any change to the markup text won't be saved anywhere but
245
in your Scribus file. If you haven't specified an external editor in <i>Preferences &lt; Tools</i>, Scribus will display an error message:</p>
246
<br></br>
247
<table width="100%"><tr><td align="center"><img src="images/rf-error3.png"/></td></tr></table>
248
<br></br>
249
<p>In addition, you have the option to start with an empty frame. By checking
250
"Force DPI," Scribus will render the output of every Render Frame with the resolution
251
set in the spinbox to the right. It's set to 72 dpi by default for
252
performance reasons. If you want to produce a document for
253
professional printing, you will want to choose a higher resolution.</p>
254
</body>
255
</html>